About This Reference

The Photon Widget Reference describes the global data structures and the widgets defined in the Photon toolkit, along with their resources and any associated convenience functions. It's intended for developers of Photon applications.

If you're familiar with earlier versions of Photon, you should read:

"What's new in Photon for QNX Neutrino 6.3.0 Service Pack 1"
"What's new in Photon for QNX Neutrino 6.3"
"What's new in Photon for QNX Neutrino 6.2.1"
"What's new in Photon for QNX Neutrino 6.2.0"
"What's new in Photon for QNX Neutrino 6.1.0"
"What's new in Photon for QNX Neutrino 6.0"

to find out how the widgets have changed in this release.

For information about:	See:
Data structures	Global Data Structures
Widget classes	Widgets
Explanations of Photon terms	Glossary

Since widgets inherit a lot of behavior from their parent classes, you should make yourself familiar with the fundamental classes, especially PtWidget, PtBasic, and PtContainer.

This reference doesn't include contributed widgets. You'll find the documentation for them (if any) in their source files.

What's new in Photon for QNX Neutrino 6.3 Service Pack 1

New widgets

PtImageArea

Changes

The ancestry of several widgets has changed. See the Widgets chapter for details.

This section summarizes the changes to:

PtGenList
PtBasic
PtWindow

`PtGenList`

Changes to Pt_ARG_LIST_FLAGS:

New flags:

Pt_LIST_VSCROLLBAR_ALWAYS
Pt_LIST_SCROLLBAR_AS_REQUIRED
Pt_LIST_VSCROLLBAR_AS_REQUIRED
Pt_LIST_VSCROLLBAR_NEVER
Pt_LIST_HSCROLLBAR_ALWAYS
Pt_LIST_HSCROLLBAR_AS_REQUIRED
Pt_LIST_HSCROLLBAR_NEVER
Pt_LIST_STRETCH_HEADER

Deprecated flags:

Pt_LIST_SCROLLBAR_ALWAYS
Pt_LIST_SCROLLBAR_NEVER
Pt_LIST_SCROLLBAR_AS_REQUIRED

Removed flags:

Pt_LIST_NOBLIT

`PtBasic`

Changed resources:

Pt_ARG_BASIC_FLAGS -- new flag: Pt_BASIC_PREVENT_FILL.

`PtWindow`

New resources:

Pt_ARG_WINDOW_FLAGS.

What's new in Photon for QNX Neutrino 6.3

New widgets

PtMTrend

Changes

This section summarizes the changes to:

PtBasic
PtContainer
PtFontSel
PtLabel
PtSeparator
PtTerminal
PtTree
PtWebClient
PtWidget

`PtBasic`

Changed resources:

`PtContainer`

PtContainer can now be instantiated in PhAB, and has a PhAB icon.

New resources:

`PtFontSel`

The PtFontSel interface widget is changed. A user can now select text and background color, and the style selection method is changed. The changed interface has introduced new resources, and made other resources unnecessary.

New resources:

Deprecated resources:

Pt_ARG_DIM
Pt_ARG_FONT_LBL_STYLE_BOLD
Pt_ARG_FONT_LBL_STYLE_BOLDITALIC
Pt_ARG_FONT_LBL_STYLE_ITALIC
Pt_ARG_FONT_LBL_STYLE_PLAIN
Pt_ARG_FONT_LBL_QUALITY
Pt_ARG_FONT_LBL_QUALITY_PLAIN
Pt_ARG_FONT_LBL_QUALITY_ANTIALIASED

`PtLabel`

New resources:

`PtSeparator`

New resources:

`PtTerminal`

PtTerminalFont() is deprecated; use PtTerminalFontInfo() instead.

The length field in PtTerminalInput_t is changed from unsigned short to unsigned, which allows PtTerminal to paste more than 65535 bytes of data from the clipboard.

`PtTree`

New convenience functions and attributes structure:

`PtWebClient`

New resources:

Changed resources:

Flags are renamed from WWW_* to Pt_WEB_* in these resources:

`PtWidget`

New resources:

What's new in Photon for QNX Neutrino 6.2.1

Changes

`PtGraphics`

New resources:

Errata

PtClock

If the clock flickers too much, you can place it in a widget, but you must use a transparent fill for the clock, or else it won't be refreshed properly.

PtPanelGroup

The Pt_ARG_PG_CURRENT_INDEX resource is 1-based.

The default value for a panel group's Pt_ARG_RESIZE_FLAGS is 0.

Corrected the example of the Pt_CB_PG_PANEL_SWITCHING callback.

What's new in Photon for QNX Neutrino 6.2.0

This section summarizes the changes to:

PtBasic
PtFontSel
PtGenList
PtMultiText
PtOSContainer
PtSlider
PtTerminal
PtText
PtTty

`PtBasic`

New flags for Pt_ARG_BASIC_FLAGS:

Pt_BLANK_ETCHES
Pt_OPAQUE_ETCHES

`PtFontSel`

New flags for Pt_ARG_FONT_FLAGS:

Pt_FONTSEL_COLORSEL_BKGD
Pt_FONTSEL_COLORSEL_TEXT

New resources:

`PtGenList`

Pt_ARG_LIST_FLAGS includes a new flag, Pt_LIST_NO_COLUMN_LINES, that makes the list not display the lines that separate the list's columns.

`PtMultiText`

This widget now supports drag and drop; see "Drag and drop."

`PtOSContainer`

When you unrealize a PtOSContainer widget, its offscreen memory is automatically released. When you rerealize the widget, the offscreen memory is reallocated.

`PtSlider`

New resources:

Pt_ARG_SLIDER_TROUGH_IMAGE1, Pt_ARG_SLIDER_TROUGH_IMAGE2

`PtTerminal`

This widget now supports drag and drop; see "Drag and drop."

`PtText`

This widget now supports drag and drop; see "Drag and drop."

`PtTty`

This widget now supports drag and drop; see "Drag and drop."

What's new in Photon for QNX Neutrino 6.1.0

`PtGroup`

New resources:

`PtMenu`

Pt_MENU_TEXT_ALIGN is a new bit for Pt_ARG_MENU_FLAGS. It's set by default.

`PtNumericFloat`

This widget exports Pt_ARG_TEXT_FLAGS and Pt_ARG_TEXT_FONT from its subordinate PtText widget.

`PtNumericInteger`

This widget exports Pt_ARG_TEXT_FLAGS and Pt_ARG_TEXT_FONT from its subordinate PtText widget.

What's new in Photon for QNX Neutrino 6.0

This section includes:

New widgets
Deprecated widgets
Other changes

New widgets

PtClient
PtColorPanel
PtColorPatch
PtColorSel
PtColorSelGroup
PtColorWell
PtDisjoint
PtOSContainer
PtPanelGroup
PtProgress
PtRawList
PtRawTree
PtScrollContainer -- use this instead of PtScrollArea
PtServer
PtToolbar
PtToolbarGroup
PtWebClient

Deprecated widgets

Instead of:	Use:
`AwFileSelect`	`PtFileSel`
`AwMessage`	PtAlert(), PtNotice(), or PtPrompt() (see the Photon Library Reference)
`PtBitmap`	`PtLabel`
`PtDBContainer`	`PtOSContainer`
`PtHtml`	`PtWebClient`
`PtIcon`	Define in PhAB
`PtMessage`	PtAlert(), PtNotice(), or PtPrompt() -- see the Photon Library Reference
`PtTab`	`PtPanelGroup`
`RtMeter`	`PtMeter`
`RtProgress`	`PtProgress`
`RtTrend`	`PtTrend`

Other changes

This section describes the changes made to:

PtBasic
PtBezier
PtBkgd
PtButton
PtComboBox
PtContainer
PtFileSel
PtFontSel
PtGenList
PtGauge
PtGenTree
PtGraphic
PtGrid
PtLabel
PtMenuButton
PtMultiText
PtNumeric
PtNumericInteger
PtPolygon
PtPrintSel
PtRaw
PtRegion
PtScrollArea
PtScrollbar
PtSlider
PtTerminal
PtText
PtTimer
PtToggleButton
PtTree
PtTty
PtWidget
PtWindow

`PtBasic`

New resources:

Deprecated resources:

Pt_ARG_BOT_BORDER_COLOR
Pt_ARG_TOP_BORDER_COLOR

`PtBezier`

Pg_DRAW_FILL and Pg_DRAW_STROKE have been deleted from Pt_ARG_BEZIER_FLAGS. Use Pt_ARG_INSIDE_COLOR (defined by PtGraphic) and Pt_ARG_COLOR (defined by PtBasic) instead.

`PtBkgd`

The Pt type of Pt_ARG_BKGD_IMAGE is now Image.

`PtButton`

New resources:

Pt_ARG_ARM_IMAGE -- replaces Pt_ARG_ARM_DATA.

`PtComboBox`

Pt_COMBOBOX_ALT_DOWN is a new bit for Pt_ARG_CBOX_FLAGS.

`PtContainer`

New resources:

Pt_ARG_TITLE
Pt_ARG_TITLE_FONT
Pt_CB_CHILD_ADDED_REMOVED
Pt_ARG_CURSOR_OVERRIDE -- replaces Pt_ARG_WINDOW_CURSOR_OVERRIDE formerly defined by PtWindow.

Resources moved to PtWidget:

The Pt_AUTO_EXTENT bit of Pt_ARG_CONTAINER_FLAGS now causes the container to recalculate its preferred size when any of its children are realized, unrealized, moved, or resized. (This bit previously didn't apply to unrealizing.)

The PtContainerCallback_t structure that's passed to Pt_CB_RESIZE now includes the old and new dimensions of the container.

`PtFileSel`

New resources:

Pt_FS_NO_ROOT_DISPLAY is a new bit for Pt_ARG_FS_FLAGS.

`PtFontSel`

New resources:

Pt_ARG_FONT_LBL_FONT
Pt_ARG_FONT_LBL_QUALITY -- deprecated
Pt_ARG_FONT_LBL_QUALITY_ANTIALIASED -- deprecated
Pt_ARG_FONT_LBL_QUALITY_PLAIN -- deprecated
Pt_ARG_FONT_LBL_SIZE
Pt_ARG_FONT_LBL_STYLE
Pt_ARG_FONT_LBL_STYLE_BOLD -- deprecated
Pt_ARG_FONT_LBL_STYLE_BOLDITALIC -- deprecated
Pt_ARG_FONT_LBL_STYLE_ITALIC -- deprecated
Pt_ARG_FONT_LBL_STYLE_PLAIN -- deprecated

`PtGenList`

Pt_ARG_LIST_DNDSEL_COLOR is a new resource.

The actions included in the callback data for Pt_CB_SCROLL_MOVE now include Pt_SCROLL_JUMP.

Pt_ARG_LIST_SCROLL_RATE is now of type unsigned char instead of short.

Pt_LIST_COLUMN_NO_STRING is a new flag for Pt_ARG_LIST_COLUMN_ATTR

`PtGauge`

New resources:

Resource	Replaces
Pt_ARG_MAXIMUM	Pt_ARG_GAUGE_MAXIMUM
Pt_ARG_MINIMUM	Pt_ARG_GAUGE_MINIMUM
Pt_ARG_ORIENTATION	Pt_ARG_GAUGE_ORIENTATION
Pt_CB_GAUGE_VALUE_CHANGED	N/A

New bits for Pt_ARG_GAUGE_FLAGS:

Pt_GAUGE_INDETERMINATE
Pt_GAUGE_INTERACTIVE
Pt_GAUGE_LIVE
Pt_GAUGE_SHOW_VALUE -- replaces Pt_SHOW_VALUE.
Pt_GAUGE_VALUE_XOR -- replaces Pt_VALUE_XOR.

Deprecated bits for Pt_ARG_GAUGE_FLAGS:

Pt_GAUGE_MAX_ON_RIGHT
Pt_GAUGE_MAX_ON_BOTTOM

`PtGenTree`

New resources:

New bits for Pt_ARG_TREE_FLAGS:

Pt_TREE_SHOW_LINES
Pt_TREE_SHOW_MARGIN
Pt_TREE_INDENT_LINES
Pt_TREE_INDENT_BUTTONS
Pt_TREE_SHOW_CONNECTORS

Deprecated bits for Pt_ARG_TREE_FLAGS:

Pt_TREE_HAS_LINES
Pt_TREE_ROOT_LINES

`PtGraphic`

New resources:

Pt_ARG_INSIDE_COLOR

`PtGrid`

The following resources are no longer relevant, and have been deleted:

Pt_ARG_DASH_LIST
Pt_ARG_DASH_SCALE
Pt_ARG_LINE_CAP
Pt_ARG_LINE_JOIN
Pt_ARG_LINE_WIDTH

`PtLabel`

New resources:

Pt_ARG_LABEL_IMAGE -- replaces Pt_ARG_LABEL_DATA.
Pt_ARG_TEXT_IMAGE_SPACING

`PtMenuButton`

New resources:

Pt_ARG_MODIFIER_KEYS

New bits for Pt_ARG_BUTTON_TYPE:

Pt_MENU_UP
Pt_MENU_ACCL_CTRL
Pt_MENU_ACCL_ALT
Pt_MENU_ACCL_SHFT

`PtMultiText`

The attributes member of the PtMultiTextControl_t structure is now of type PtMultiTextAttributes_t const *.

`PtNumeric`

The following resources are no longer relevant, and have been deleted:

Pt_ARG_NUMERIC_TEXT_BORDER
Pt_ARG_NUMERIC_TEXT_BOT_BORDER_COLOR
Pt_ARG_NUMERIC_TEXT_COLOR
Pt_ARG_NUMERIC_TEXT_FILL_COLOR
Pt_ARG_NUMERIC_TEXT_FONT
Pt_ARG_NUMERIC_TEXT_TOP_BORDER_COLOR
Pt_ARG_NUMERIC_UPDOWN_BORDER_WIDTH

`PtNumericInteger`

The default values of Pt_ARG_NUMERIC_MAX and Pt_ARG_NUMERIC_MIN are INT_MAX and INT_MIN.

`PtPolygon`

Pg_POLY_FILL and Pg_POLY_STROKE have been deleted from Pt_ARG_POLYGON_FLAGS. Use Pt_ARG_INSIDE_COLOR (defined by PtGraphic) and Pt_ARG_COLOR (defined by PtBasic) instead.

`PtPrintSel`

New resources:

The flags for the Pt_ARG_PRINT_FLAGS resource have been replaced.

The Pt_PRINTSEL_ADDNEW and Pt_PRINTSEL_RETURN subtypes of the Pt_CB_PRINT_PROPS callbacks have been deprecated; the Pt_PRINTSEL_INSTALLER, Pt_PRINTSEL_PROPERTIES_EXITED, Pt_PRINTSEL_INSTALLER_EXITED, Pt_PRINTSEL_NOPRINTER, and Pt_PRINTSEL_PRINTER subtypes have been added.

`PtRaw`

New resource:

Pt_ARG_RAW_CALC_OPAQUE_F

`PtRegion`

You don't have to set bits in Pt_ARG_REGION_FIELDS to make changes to the region's resources take effect. This resource now indicates which portions of the region were changed the last time that you set any resources, including the flags, sensitivity, opacity, origin, and position.

`PtScrollArea`

This class has become a superclass for widgets that scroll. Use PtScrollContainer as a viewport that contains other widgets. PhAB automatically converts an existing PtScrollArea into a PtScrollContainer.

New resources:

Pt_CB_SCROLLAREA_SCROLLED -- replaces Pt_CB_SCROLLED_X and Pt_CB_SCROLLED_Y.

Pt_SCROLLAREA_ENABLE_PAN has been added to, and Pt_SCROLL_AREA_TRACK_FOCUS removed from, Pt_ARG_SCROLLAREA_FLAGS.

PtScrollAreaCanvas() is a new convenience function.

`PtScrollbar`

This widget is now a subclass of PtGauge. Hence, it inherits the following resources instead of defining them:

The following resources are no longer relevant, and have been deleted:

Pt_ARG_DIRECTION
Pt_ARG_SCROLL_POSITION -- use Pt_ARG_GAUGE_VALUE

Deleted bits for Pt_ARG_SCROLLBAR_FLAGS:

Pt_SCROLLBAR_HORIZONTAL
Pt_SCROLLBAR_INVERTED

New bits for Pt_ARG_SCROLLBAR_FLAGS:

Pt_SCROLLBAR_FIXED_SLIDER_SIZE

The actions included in the callback data for Pt_CB_SCROLL_MOVE now include Pt_SCROLL_JUMP.

`PtSlider`

The appearance of this widget has changed a lot. Labels are no longer part of the widget; place PtLabel widgets around the slider if required.

New resources:

Pt_ARG_SLIDER_HANDLE_COLOR
Pt_ARG_SLIDER_THICKNESS -- deprecated; use Pt_ARG_SLIDER_HANDLE_WIDTH

The following resources are no longer relevant, and have been deleted:

Pt_ARG_SLIDER_HANDLE_HEIGHT
Pt_ARG_SLIDER_LABEL_BR
Pt_ARG_SLIDER_LABEL_BR_COL
Pt_ARG_SLIDER_LABEL_TL
Pt_ARG_SLIDER_LABEL_TL_COL
Pt_ARG_SLIDER_ORIENTATION
Pt_ARG_SLIDER_TICK_MAJOR_COL
Pt_ARG_SLIDER_TICK_MINOR_COL
Pt_ARG_SLIDER_TROUGH_COL
Pt_ARG_SLIDER_TROUGH_SIZE

Deleted bits for Pt_ARG_SLIDER_FLAGS:

Pt_TICKS_ON_TOP
Pt_TICKS_ON_LEFT
Pt_TICKS_ON_BOTTOM
Pt_TICKS_ON_RIGHT
Pt_TICKS_TOUCH_TROUGH
Pt_TICKS_ETCHED_OUT
Pt_TICKS_ETCHED_IN
Pt_SLIDER_POINT_LEFT
Pt_SLIDER_POINT_UP
Pt_SLIDER_POINT_RIGHT
Pt_SLIDER_POINT_DOWN

The reason_subtype for Pt_CB_SLIDER_MOVE is now used and can be one of the following:

Pt_SLIDER_INCREMENT
Pt_SLIDER_DECREMENT
Pt_SLIDER_MULTIPLE_INCREMENT
Pt_SLIDER_MULTIPLE_DECREMENT
Pt_SLIDER_DRAGGED
Pt_SLIDER_RELEASED
Pt_SLIDER_TO_MIN
Pt_SLIDER_TO_MAX
Pt_SLIDER_JUMP
Pt_SLIDER_SET

`PtTerminal`

New resource:

Pt_ARG_TERM_ANSI_PROTOCOL -- replaces Pt_ARG_TERM_PROTOCOL

The Subst member has been added to PtTerminalCharset_t.

`PtText`

The C type for Pt_ARG_CURSOR_POSITION is int, not short.

`PtTimer`

Pt_ARG_TIMER_INITIAL and Pt_ARG_TIMER_REPEAT are now unsigned long instead of long.

`PtToggleButton`

Deprecated resources:

Pt_ARG_INDICATOR_DEPTH
Pt_ARG_INDICATOR_HEIGHT
Pt_ARG_INDICATOR_WIDTH
Pt_ARG_SET_COLOR -- use Pt_ARG_ARM_COLOR instead (see PtButton).
Pt_ARG_SET_FILL -- use Pt_ARG_ARM_FILL instead (see PtButton).
Pt_ARG_SPACING -- use Pt_ARG_TEXT_IMAGE_SPACING instead (see PtLabel).

The types supported by Pt_ARG_INDICATOR_TYPE have completely changed:

Old	New
Pt_ONE_OF_MANY	N/A
Pt_N_OF_MANY	N/A
Pt_ROUND	N/A
Pt_RADIO	Pt_TOGGLE_RADIO
Pt_TICK	N/A
Pt_CHECK	Pt_TOGGLE_CHECK
N/A	Pt_TOGGLE_OUTLINE

`PtTree`

New resources:

PtTreeAddAfter() and PtTreeAddFirst() now return 0 on success, or -1 if the item is already in a tree.

PtTreeFreeItems() now returns 0 on success, or -1 if the items are still in a tree.

The expand member of the PtTreeCallback_t structure passed to Pt_CB_TREE_STATE is now used whether expanding or collapsing an item. PtTreeCollapse() now returns the value of the expand member (the prototype has changed).

The PtTreeItem_t structure has changed to allow for future enhancements. This:

short set_img, unset_img;

has been replaced by:

union {
    struct { short set, unset; } img;
    } attr;

PtTreeModifyItemString() is a new convenience function that changes the string for a PtTree item.

`PtTty`

The way the PtTty uses file descriptors has changed. Instead of two FDs, it can now have three: one for reading, one for writing, and one to give to a child process. Each can be set separately. This way, it's possible to use a PtTty with a pair of pipes instead of a pseudo tty. It's also possible to close the "slave" end of the pty after giving it to a child process.

New resources:

The following resources are no longer relevant, and have been deleted:

Pt_ARG_TTY_FD -- set Pt_ARG_TTY_FDS instead.
Pt_ARG_TTY_MFD -- get Pt_ARG_TTY_RFD or Pt_ARG_TTY_WFD instead.

`PtWidget`

New resources:

Pt_ARG_ANCHOR_FLAGS -- moved from PtContainer
Pt_ARG_ANCHOR_OFFSETS -- moved from PtContainer
Pt_ARG_BEVEL_WIDTH -- replaces Pt_ARG_BORDER_WIDTH
Pt_ARG_MINIMUM_DIM
Pt_ARG_POINTER
Pt_CB_DND
Pt_CB_FILTER -- moved from PtContainer
Pt_CB_IS_DESTROYED
Pt_CB_OUTBOUND

The Pt_CB_RAW callbacks are now invoked even if the widget's class methods consume the event. In this case, Ph_CONSUMED is set in the event's processing_flags member.

The Pt_ETCH_HIGHLIGHT bit of Pt_ARG_FLAGS is deprecated; use the Pt_ARG_BASIC_FLAGS defined by PtBasic.

`PtWindow`

The following resources are no longer relevant, and have been deleted:

Pt_ARG_ICON_WINDOW
Pt_ARG_WINDOW_CURSOR_OVERRIDE -- replaced by the Pt_ARG_CURSOR_OVERRIDE resource defined by PtContainer.

The following bits have been added to Pt_ARG_WINDOW_RENDER_FLAGS:

Ph_WM_RENDER_COLLAPSE
Ph_WM_RENDER_ASDIALOG
Ph_WM_RENDER_ASPALETTE

Instead of using Pt_ARG_MAX_HEIGHT, Pt_ARG_MAX_WIDTH, Pt_ARG_MIN_HEIGHT, and Pt_ARG_MIN_WIDTH to set the window's dimensions, you can use the Pt_ARG_MAXIMUM_DIM and Pt_ARG_MINIMUM_DIM resources that are defined by PtWidget.

Museum

About This Reference