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.


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

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.


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

Changes

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

This section summarizes the changes to:

PtGenList

Changes to Pt_ARG_LIST_FLAGS:

New flags:

Deprecated flags:

Removed flags:

PtBasic

Changed resources:

PtWindow

New resources:

What's new in Photon for QNX Neutrino 6.3

New widgets

Changes

This section summarizes the changes to:

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:

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 PtOSContainer 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

New flags for Pt_ARG_BASIC_FLAGS:

PtFontSel

New flags for Pt_ARG_FONT_FLAGS:

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:

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

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

New resources:

Deprecated resources:

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:

PtComboBox

Pt_COMBOBOX_ALT_DOWN is a new bit for Pt_ARG_CBOX_FLAGS.

PtContainer

New resources:

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:

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:

Deprecated bits for Pt_ARG_GAUGE_FLAGS:

PtGenTree

New resources:

New bits for Pt_ARG_TREE_FLAGS:

Deprecated bits for Pt_ARG_TREE_FLAGS:

PtGraphic

New resources:

PtGrid

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

PtLabel

New resources:

PtMenuButton

New resources:

New bits for Pt_ARG_BUTTON_TYPE:

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:

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:

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

Deleted bits for Pt_ARG_SCROLLBAR_FLAGS:

New bits for Pt_ARG_SCROLLBAR_FLAGS:

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:

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

Deleted bits for Pt_ARG_SLIDER_FLAGS:

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

PtTerminal

New resource:

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:

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:

PtWidget

New resources:

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:

The following bits have been added to Pt_ARG_WINDOW_RENDER_FLAGS:

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.

Copyright © 1995 - 2007, QNX Software Systems. All rights reserved.