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.
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 text_parameter, where 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 command egg-texture-cards, based on a texture that you painted by hand. 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 geom_parameter.
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_pos and image_scale.
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 geom keyword).
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.
The 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:
| Keyword | Definition | Value |
| text | Text to be displayed on the object | String |
| text_bg | Background color of the text on the object | (R,G,B,A) |
| text_fg | Color of the text | (R,G,B,A) |
| text_pos | Position of the displayed text | (x,z) |
| text_roll | Rotation of the displayed text | Number |
| text_scale | Scale of the displayed text | (sx,sz) |
| text_* | Parameters to control the appearance of the text | Any keyword parameter appropriate to OnscreenText. |
| frameSize | Size of the object | (Left,Right,Bottom,Top) |
| frameColor | Color of the object's frame | (R,G,B,A) |
| relief | Relief appearance of the frame | SUNKEN, RAISED, GROOVE, RIDGE, FLAT, or None |
| invertedFrames | If true, switches the meaning of SUNKEN and RAISED | 0 or 1 |
| borderWidth | If relief is SUNKEN, RAISED, GROOVE, or RIDGE, changes the size of the bevel | (Width,Height) |
| image | An image to be displayed on the object | image filename or Texture object |
| image_pos | Position of the displayed image | (x,y,z) |
| image_hpr | Rotation of the displayed image | (h,p,r) |
| image_scale | Scale of the displayed image | (sx,sy,sz) |
| geom | A geom to represent the object's appearance | NodePath |
| geom_pos | Position of the displayed geom | (x,y,z) |
| geom_hpr | Rotation of the displayed geom | (h,p,r) |
| geom_scale | Scale of the displayed geom | (sx,sy,sz) |
| pos | Position of the object | (X,Y,Z) |
| hpr | Orientation of the object | (H,P,R) |
| scale | Scale of the object | Number |
| pad | When frameSize is omitted, this determines the extra space around the geom or text's bounding box by which to expand the default frame | (Width,Height) |
| state | The initial state of the object | NORMAL or DISABLED |
| frameTexture | Texture applied directly to the frame generated when relief is FLAT | image filename or Texture object |
| enableEdit | Affects direct-gui-edit functionality | 0 or 1 |
| suppressKeys | If 1, suppresses triggers of global keyboard-related Panda events (not part of the GUI system) | 0 or 1 |
| suppressMouse | If 1, suppresses triggers of global mouse-related Panda events (e.g. camera controls) | 0 or 1 |
| sortOrder | Specifies render order for overlapping objects. Higher numbers are drawn in front of lower numbers. | Number |
| textMayChange | 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:
|
myDirectObject.resetFrameSize()
|
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.
|
