This chapter describes the widgets in the Photon library. It also includes:

Widget hierarchy

If your browser supports image maps, you can select a widget from this diagram:

PtImageArea PtUpDown PtMTrend PtBarGraph PtScrollContainer PtRawList PtGenTree PtList PtRawTree PtFileSel PtTree PtColorWell PtColorPatch PtColorPanel PtColorSelGroup PtColorSel PtNumeric PtNumericInteger PtNumericFloat PtMultiText PtMenuButton PtGenList PtDivider PtComboBox PtPane PtServer PtWindow PtRegion PtMenu PtToolbarGroup PtToolbar PtWebClient PtClient PtDisjoint PtPanelGroup PtOSContainer PtPrintSel PtFontSel PtTty PtTerminal PtScrollArea PtBkgd PtMenuBar PtGroup PtCompound PtText PtProgress PtSlider PtScrollbar PtMeter PtArc PtRect PtPolygon PtPixel PtLine PtGrid PtEllipse PtBezier PtOnOffButton PtToggleButton PtClock PtCalendar PtTab PtMenuLabel: see PtMenuButton PtButton PtTrend PtSeparator PtRaw PtLabel PtGraphic PtGauge PtContainer PtTimer PtBasic PtWidget

Widget hierarchy

The Photon widget hierarchy.

Note: 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.

Widget icons in PhAB

The following table lists the Photon widget classes and the icons used in PhAB's widget palette:

PhAB Icon Class Description
PtArc button PtArc Elliptical arc
PtBarGraph button PtBarGraph Bar graph
PtBasic button PtBasic Superclass of basic resources for most widgets
PtBezier button PtBezier Bézier curve
PtBkgd button PtBkgd Background of tiled images, gradients, or bitmaps
PtButton button PtButton Button for initiating an action
PtCalendar button PtCalendar Calendar
N/A PtClient Superclass for client widgets — not normally instantiated
PtClock button PtClock Analog, digital, or LED clock
PtColorPanel button PtColorPanel Color panel
PtColorPatch button PtColorPatch Color patch for selecting a hue and shading or tint
N/A PtColorSel Superclass for color-selector widgets—not normally instantiated
PtColorSelGroup button PtColorSelGroup Group of color selectors
PtColorWell button PtColorWell Rectangle that displays a color and lets you change it
PtComboBox button PtComboBox Text-entry field with a list of choices
N/A PtCompound Superclass for compound widgets—not normally instantiated
PtContainer button PtContainer Superclass for container widgets
N/A PtDisjoint Superclass for disjoint widgets—not normally instantiated
PtDivider button PtDivider Widget that divides a given space among its child widgets and allows resizing
PtEllipse button PtEllipse Ellipse
PtFileSel button PtFileSel Tree widget for selecting files and directories
PtFontSel button 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
PtGrid button PtGrid Grid pattern
N/A PtGroup Group—use PhAB's Group Together button to create this
PtImageArea button PtImageArea An area for viewing an image
PtLabel button PtLabel A text, bitmap, or image label
PtLine button PtLine Straight line (single segment)
PtList button PtList List of text items
N/A PtMenu Menu—use a Menu module instead
PtMenuBar button PtMenuBar Menubar that's placed at the top of a window
PtMenuButton button PtMenuButton Button that pops up a menu, or an item in a menu
PtMeter button PtMeter Meter widget
PtMtrend button PtMTrend Medical trend widget
PtMultitext button PtMultitext Multiple-line stylized text field
N/A PtNumeric Numeric field superclass—not normally instantiated
PtNumericFloat button PtNumericFloat Floating-point numeric field
PtNumericInteger button PtNumericInteger Integer field
PtOnOffButton button in PhAB PtOnOffButton Button that's either on or off
PtOSContainer button in PhAB PtOSContainer Offscreen-context container, useful for drawing flicker-free images and animations
PtPane button PtPane Container for organizing widgets
PtPanelGroup button PtPanelGroup Container that manages panels
PtPixel button PtPixel Set of points
PtPolygon button PtPolygon Set of connected line segments
PtPrintSel button PtPrintSel Compound widget for choosing printing options
PtProgress button PtProgress Progress bar
PtRaw button PtRaw Widget in which you can use low-level Pg drawing functions
PtRawList button PtRawList Raw list
PtRawTree button PtRawTree Raw tree
PtRect button PtRect Rectangle
N/A PtRegion Photon region—must be created with PtCreateWidget()
N/A PtScrollArea Superclass for scrolling widgets—not normally instantiated
PtScrollBar button PtScrollBar Scrollbar
PtScrollContainer button PtScrollContainer Viewport for viewing a large virtual area
PtSeparator button PtSeparator Separator for organizing widgets
N/A PtServer Server widget — must be created with PtCreateWidget()
PtSlider button PtSlider Numerical input mechanism with a range
PtTab button PtTab Terminal emulator
PtTerminal button PtTerminal Terminal emulator
PtText button PtText Single-line text field
PtTimer button PtTimer Timer
PtToggleButton button PtToggleButton Toggle button
PtToolbar button PtToolbar Superclass for toolbar widgets
PtToolbarGroup button PtToolbarGroup Group of toolbars
PtTree button PtTree Hierarchy tree
PtTrend button in PhAB PtTrend Display of connected points that shift in a specified direction at the rate in which data is fed
PtTty button PtTty Terminal device
PtUpDown button PtUpDown Up/Down button
PtWebClient button PtWebClient Widget for displaying web pages
N/A PtWidget Widget superclass—not normally instantiated
N/A PtWindow Window—use a PhAB window module instead

What's in a widget description?

You'll find the following sections in a typical widget-class description:

Class hierarchy

The classes a widget inherits its resources and behavior from.

PhAB icon

The icon in PhAB's widget palette for the widget.

Public header

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.

New resources

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:

The default value(s) of a resource.

Inherited resources

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:


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.

Convenience functions

This section describes the functions you can use to control the widget once it has been created.