This chapter describes the widgets in the Photon library. It also includes:
- a diagram of the widget hierarchy
- a table of widget icons in PhAB
- an overview of what you'll find in a widget description.
If your browser supports image maps, you can select a widget from this diagram:
|The widget hierarchy is important because classes inherit resources and behavior from their ancestors. When you're working with a particular class, be sure to look at the descriptions of its ancestors, too.|
The following table lists the Photon widget classes and the icons used in PhAB's widget palette:
|PtBasic||Superclass of basic resources for most widgets|
|PtBkgd||Background of tiled images, gradients, or bitmaps|
|PtButton||Button for initiating an action|
|N/A||PtClient||Superclass for client widgets — not normally instantiated|
|PtClock||Analog, digital, or LED clock|
|PtColorPatch||Color patch for selecting a hue and shading or tint|
|N/A||PtColorSel||Superclass for color-selector widgets—not normally instantiated|
|PtColorSelGroup||Group of color selectors|
|PtColorWell||Rectangle that displays a color and lets you change it|
|PtComboBox||Text-entry field with a list of choices|
|N/A||PtCompound||Superclass for compound widgets—not normally instantiated|
|PtContainer||Superclass for container widgets|
|N/A||PtDisjoint||Superclass for disjoint widgets—not normally instantiated|
|PtDivider||Widget that divides a given space among its child widgets and allows resizing|
|PtFileSel||Tree widget for selecting files and directories|
|PtFontSel||Widget for selecting font attributes|
|N/A||PtGauge||Superclass for gauge-like widgets—not normally instantiated|
|N/A||PtGenList||Superclass for list widgets—not normally instantiated|
|N/A||PtGenTree||Superclass for tree widgets—not normally instantiated|
|N/A||PtGraphic||Superclass for graphical widgets—not normally instantiated|
|N/A||PtGroup||Group—use PhAB's Group Together button to create this|
|PtImageArea||An area for viewing an image|
|PtLabel||A text, bitmap, or image label|
|PtLine||Straight line (single segment)|
|PtList||List of text items|
|N/A||PtMenu||Menu—use a Menu module instead|
|PtMenuBar||Menubar that's placed at the top of a window|
|PtMenuButton||Button that pops up a menu, or an item in a menu|
|PtMTrend||Medical trend widget|
|PtMultitext||Multiple-line stylized text field|
|N/A||PtNumeric||Numeric field superclass—not normally instantiated|
|PtNumericFloat||Floating-point numeric field|
|PtOnOffButton||Button that's either on or off|
|PtOSContainer||Offscreen-context container, useful for drawing flicker-free images and animations|
|PtPane||Container for organizing widgets|
|PtPanelGroup||Container that manages panels|
|PtPixel||Set of points|
|PtPolygon||Set of connected line segments|
|PtPrintSel||Compound widget for choosing printing options|
|PtRaw||Widget in which you can use low-level Pg drawing functions|
|N/A||PtRegion||Photon region—must be created with PtCreateWidget()|
|N/A||PtScrollArea||Superclass for scrolling widgets—not normally instantiated|
|PtScrollContainer||Viewport for viewing a large virtual area|
|PtSeparator||Separator for organizing widgets|
|N/A||PtServer||Server widget — must be created with PtCreateWidget()|
|PtSlider||Numerical input mechanism with a range|
|PtText||Single-line text field|
|PtToolbar||Superclass for toolbar widgets|
|PtToolbarGroup||Group of toolbars|
|PtTrend||Display of connected points that shift in a specified direction at the rate in which data is fed|
|PtWebClient||Widget for displaying web pages|
|N/A||PtWidget||Widget superclass—not normally instantiated|
|N/A||PtWindow||Window—use a PhAB window module instead|
You'll find the following sections in a typical widget-class description:
The classes a widget inherits its resources and behavior from.
The icon in PhAB's widget palette for the widget.
The name of the header file containing the resource manifests, data structures, and #define directives associated with the widget class.
How to use the widget. This section may include sample code as well as an example of the widget's appearance.
The new resources introduced by this widget class. This section describes the following for each resource:
- The resource manifest.
- C type
- The C data type this resource refers to.
- Pt type
- An indication of how you should get or set the resource.
These methods are described in the
Manipulating Resources in
Application Code chapter of the Photon Programmer's Guide.
The Pt types are:
- Alloc — an arbitrarily sized memory object.
- Array — an array. For this type of resource, the C type column has two values: the first is the data type the array is expected to contain; the second is the data type of the array counter (usually short).
- Boolean — a bit that's either on or off.
- Complex — a resource that needs special handling. There's usually a convenience function defined to help you use a complex resource.
- Flag — a value in which each bit has a different meaning.
- Image — a PhImage_t structure; see the Photon Library Reference.
- Link — a linked list.
- Pointer — a pointer to arbitrary data.
- Scalar — a value that can be represented within a single long (that is, a long, a short, or a char).
- String — a NULL-terminated UTF-8 string.
- Struct — an instance of the structure listed in the C type column.
- The default value(s) of a resource.
This section lists the resources that the widget class inherits from its ancestors, or in the case of a compound widget, from its exported subordinate children. The default values that a widget class inherits can be overridden. The Inherited resources table contains the following columns of information:
- The manifest of the inherited resource.
- Inherited from
- The widget class this resource is defined in (default values are defined in the originating class).
- Default override
- The default resources a widget class inherits can be overridden. If a default value is overridden, this column contains the new default value. When a widget inherits resources from exported subordinate children, new defaults can be assigned by the widget class inheriting those resources. With the exception of resources inherited from exported subordinate children, modifications to resources affects all subclassed widgets.
The value in the Default override column may start with |=, as in the following example:
|=Pt_SELECTABLE | Pt_HIGHLIGHTED
This symbol indicates that the flags listed are added to the resource without destroying any flags already set in it (i.e. the new flags and the default value are combined in an OR operation).
A &=~ symbol means that one or more flags are cleared. In the following example, the Pt_SELECTABLE flag is added to the resource and the Pt_HIGHLIGHTED flag is cleared:
If the widget does anything special with an inherited resource, it's described after the table.
This section describes the functions you can use to control the widget once it has been created.