The DirectGUI Python modules
Panda3D comes with a set of tools for the creation of a graphical interface for any program. The DirectGui system is used to create buttons, labels, text entries, and frames within the program. All of these items can be decorated with text, images, and 3D graphics. Commands may be associated with these items as well. Since these objects inherit from the NodePath class, anything done to a NodePath may be done to them, such as show()/hide(), setPos(), posInterval(), and so on. Also, since DirectGui objects are by default parented to the node aspect2d, they will stay on the screen no matter how the user navigates through the world.
You can specify the parent nodepath for any DirectGUI object using the parent= argument. You can use base.aspect2d for center-oriented pacement, and a2dTopLeft or a2dBottomRight respectively. The Y coordinate should be left 0, because it's useless in the 2D space. The Z coordinate goes from -1 to 1, and X depends on the aspect ratio, by the default 4:3 it's from -1.3333 to 1.3333. The other aspect2d variants don't scale the numbers, just offset them.
The direct-gui-edit option in the Config.prc file allows the user to use the middle mouse button to move around widgets, and resize them while holding the control key; this is very useful to lay a screen out during development. If you need to turn this ability off for an individual object, set its
enableEdit keyword parameter to False.
All of the DirectGui objects are constructed in a similar way:
from direct.gui.DirectGui import *
myObject = Directxxxxxx(keyword=value, keyword=value, ...)
Each DirectGui object may contain any of four fundamental pieces that determine its appearance. There may be an optional text, an optional geom, an optional image, and an optional frame.
A DirectGui's text label may be any arbitrary text string, and whatever text string you supply is automatically created using the OnscreenText interface and centered on the object. You can specify the text string using the
text keyword. You can also specify further parameters to control the appearance or placement of the text using the form
parameter is any valid keyword to the OnscreenText constructor.
A DirectGui's geom can be any NodePath that you design, to represent the appearance of the gui object. Typically, this will be a model that you created via the program
egg-texture-cards. This little program takes a png or other picture and turns it into an egg. See Automatic_Texture_Animation, for more details. Using this interface, you can completely customize the look of the DirectGui object to suit your needs. You can specify the geom object using the
geom keyword, and like the text parameter, you can also control the geom's placement using keywords like
The image is less often used. It is the filename of a texture image (or an already-loaded Texture object). It is intended for displaying a simple texture image for which you don't already have a model created via
egg-texture-cards. A default card will be created to display this texture, with a bounding box of (-1, 0, -1) to (1, 0, 1); that is, a square with sides of length 2 units, centered on the origin. You can position and scale this card with the keywords
image_scale. See also OnscreenImage
Finally, the DirectGui may have a frame created for it. This is typically a gray rectangular background with an optional bevel. There are a handful of different frame styles; you can use the
relief keyword to select from one of the available styles; your choices are SUNKEN, RAISED, GROOVE, or RIDGE. You can also specify
relief = None to avoid creating a frame polygon altogether (this is commonly done when you have specified your own geom object with the
The overall size of the DirectGui object is controlled with the
frameSize keyword. This is a four-tuple of floating-point numbers of the form (left, right, bottom, top), which specifies the bounding box region of the DirectGui object. That is, the lower-left corner will be at position (left, 0, bottom), and the upper-right will be at (right, 0, top). Note that these values represent coordinates from the origin of the frame. Setting the frameSize to (-0.1, 0.1, -0.1, 0.1), for instance, will create a box, 0.2 units wide and 0.2 units in height, with 0,0 being the center of the frame located at
pos on the screen.
frameSize keyword is optional. If you omit it, the default frameSize is computed based on the bounding box of the text, geom, and/or image that you have specified.
The following is a list of keywords that are typically available to DirectGui objects of all kinds. Individual kinds of DirectGUI objects may add more options to this list, but these keywords are not repeated on each of the following pages, for brevity:
||Text to be displayed on the object
||Background color of the text on the object
||Color of the text
||Position of the displayed text
||Rotation of the displayed text
||Scale of the displayed text
||Parameters to control the appearance of the text
||Any keyword parameter appropriate to OnscreenText.
||Size of the object
||Relative scale of the visible frame to its clickable bounds. Useful for creating things like the paging region of a slider, which is visibly smaller than the acceptable click region (the height of the thumb).
||Color of the object’s frame
||Relief appearance of the frame
||SUNKEN, RAISED, GROOVE, RIDGE, FLAT, or None
||If true, switches the meaning of SUNKEN and RAISED
||0 or 1
||If relief is SUNKEN, RAISED, GROOVE, or RIDGE, changes the size of the bevel
||An image to be displayed on the object
||image filename or Texture object
||Position of the displayed image
||Rotation of the displayed image
||Scale of the displayed image
||A geom to represent the object’s appearance
||Position of the displayed geom
||Rotation of the displayed geom
||Scale of the displayed geom
||Parent to attach to
||Position of the object
||Orientation of the object
||Scale of the object
||When frameSize is omitted, this determines the extra space around the geom or text’s bounding box by which to expand the default frame
||The initial state of the object
||NORMAL or DISABLED
||Texture applied directly to the generated frame
||image filename or Texture object
||Affects direct-gui-edit functionality
||0 or 1
||If 1, suppresses triggers of global keyboard-related Panda events (not part of the GUI system)
||0 or 1
||If 1, suppresses triggers of global mouse-related Panda events (e.g. camera controls)
||0 or 1
||Specifies render order for overlapping objects. Higher numbers are drawn in front of lower numbers.
||Whether the text of an object can be changed after creation
||0 or 1
Remember that the axes for Panda3D use x for left and right, y for in and out of the screen, and z for up and down. An object's frame is always in the background of the object. The geom, if any, is shown in front of the frame, and text is shown in front of the geom.
It is possible to change most of these values after object creation, using:
myDirectObject['keyword'] = value
Most properties can be updated in this way, although position and other transform-related values cannot be updated via the keyword parameters--attempts to update them will silently fail. Instead, use the NodePath methods to change the object's transform.
Some types of updates, such as changing the text or the geom, may also change the size of the object. If you change any of these properties after the object has been created, it is necessary to tell the object to re-determine its size:
If you don't do this, you may find, for example, that a button isn't clickable because it believes it has a zero-width frame.
To permanently remove a DirectGUI object, you should use the method:
It is not sufficient to simply call
removeNode(), since the DirectGUI system adds a number of messenger hooks that need to be cleaned up. However, if you have a hierarchy of DirectGUI objects, for instance a number of buttons parented to a frame, it is sufficient to call destroy() only on the topmost object; it will propagate downwards.