Widgets

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.

Widget hierarchy

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

Widget hierarchy

The Photon widget hierarchy.

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`	Elliptical arc
	`PtBarGraph`	Bar graph
	`PtBasic`	Superclass of basic resources for most widgets
	`PtBezier`	Bézier curve
	`PtBkgd`	Background of tiled images, gradients, or bitmaps
	`PtButton`	Button for initiating an action
	`PtCalendar`	Calendar
N/A	`PtClient`	Superclass for client widgets — not normally instantiated
	`PtClock`	Analog, digital, or LED clock
	`PtColorPanel`	Color panel
	`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
	`PtEllipse`	Ellipse
	`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
	`PtGrid`	Grid pattern
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
	`PtMeter`	Meter widget
	`PtMTrend`	Medical trend widget
	`PtMultitext`	Multiple-line stylized text field
N/A	`PtNumeric`	Numeric field superclass—not normally instantiated
	`PtNumericFloat`	Floating-point numeric field
	`PtNumericInteger`	Integer 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
	`PtProgress`	Progress bar
	`PtRaw`	Widget in which you can use low-level Pg drawing functions
	`PtRawList`	Raw list
	`PtRawTree`	Raw tree
	`PtRect`	Rectangle
N/A	`PtRegion`	Photon region—must be created with PtCreateWidget()
N/A	`PtScrollArea`	Superclass for scrolling widgets—not normally instantiated
	`PtScrollBar`	Scrollbar
	`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
	`PtTab`	Terminal emulator
	`PtTerminal`	Terminal emulator
	`PtText`	Single-line text field
	`PtTimer`	Timer
	`PtToggleButton`	Toggle button
	`PtToolbar`	Superclass for toolbar widgets
	`PtToolbarGroup`	Group of toolbars
	`PtTree`	Hierarchy tree
	`PtTrend`	Display of connected points that shift in a specified direction at the rate in which data is fed
	`PtTty`	Terminal device
	`PtUpDown`	Up/Down 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.

Description

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:

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.

Default

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:

Resource: 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:

|=Pt_SELECTABLE &=~Pt_HIGHLIGHTED

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.