About This Reference

For an overview of the changes to the software and docs, see "What's new in Photon 1.14 (as of June 01, 2000)."

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.

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

This reference doesn't include contributed widgets. You'll find the documentation for them (if any) in the source files in /qnx4/phtk/src/contrib.

What's new in Photon 1.14 (as of June 01, 2000)

General changes:

• A summary of common flags used by all or most widgets has been added.
• Missing resources have been added to the tables of inherited resources. These tables now indicate which resources are inherited by not used by the class.

The following data structures are now described in this reference:

• PtGenListItem_t
• PtGenTreeItem_t
• PtTreeItem_t

Specific changes:

PtArc

The start and end angles are specified by Pt_ARC_START and Pt_ARC_END.

Pt_ARG_LINE_STYLE has been removed from the list of inherited resources.

PtBasic

The following resources can't be edited in PhAB:

• Pt_ARG_FILL_PATTERN
• Pt_ARG_TRANS_PATTERN

If you multi-click on a widget, its Pt_CB_ACTIVATE callbacks are invoked once for each click. The callback data includes the click count (1 for the first click, 2 for the second, and so on).

The Pt_CB_LOST_FOCUS callbacks should return Pt_CONTINUE to relinquish focus, or Pt_END to keep it (for example, if the user has to type something in a text widget).

PtBezier

Pt_ARG_LINE_STYLE has been removed from the list of inherited resources.

PtBitmap

The default value of Pt_ARG_BITMAP_BALLOON_FILL_COLOR is Pg_BALLOONCOLOR. The default value of Pt_ARG_BITMAP_BALLOON_POSITION is Pt_BITMAP_BALLOON_RIGHT.

PtButton

Pt_ARG_LABEL_DATA has been added to the list of inherited resources.

PtCalendar

The PtCalenderSelectCallback_t structure included in the data for the Pt_CB_CALENDAR_SELECT callback is of type PtCalendarDate_t.

PtClock

The default value of Pt_ARG_CLOCK_HOUR, Pt_ARG_CLOCK_MINUTE, and Pt_ARG_CLOCK_SECOND is Pt_CLOCK_CURRENT.

The default value of Pt_ARG_CLOCK_SECOND_COLOR is Pg_RED.

PtComboBox

The default value of Pt_ARG_FILL_COLOR is Pg_TRANSPARENT.

The description now includes a summary of the callbacks associated with the text and list parts of the combo box.

PtContainer

Pt_CONSUME_EVENTS is set in Pt_ARG_EFLAGS for this class and its descendants.

The Pt_CB_FILTER callbacks are invoked before the event is passed to the child. Contrast this resource with the Pt_CB_RAW resource defined for PtWidget.

The Pt_CB_RESIZE callbacks are invoked when the container's size changes.

PtDBContainer

The default value of Pt_ARG_DB_IMAGE_TYPE is Pg_IMAGE_PALETTE_BYTE.

Pt_ARG_MEMORY_CONTEXT_TYPE should be Pt_ARG_DB_MEMORY_CONTEXT_TYPE

PtDivider

The PtDividerSizes_t structure is described with the Pt_ARG_DIVIDER_SIZES resource.

PtFileSel

The reason_subtype for a Pt_CB_FS_STATE callback is either Pt_TREE_COLLAPSING or Pt_TREE_EXPANDING.

You can show hidden files or directories by combining the Pt_FS_SHOW_HIDDEN flag with Pt_FS_SHOW_DIRS or Pt_FS_SHOW_FILES.

Set the Pt_CB_FS_BKGD_HANDLER callback resource before the Pt_ARG_FS_ROOT_DIR resource in order to translate all the filenames.

PtFSAddFirst() automatically sets the Pt_TREE_ITEM_EXPANDABLE flag in the parent item.

PtFSRemoveItem() never clears the Pt_TREE_ITEM_EXPANDABLE flag in the item's parent.

For Pt_CB_FS_BKGD_HANDLER callbacks, cbdata points to a structure of type PtFileSelBkgdCallback_t, and reason_subtype is one of:

• Pt_FS_NEW_ITEM - a new item is being added to the widget.
• Pt_FS_OLD_ITEM - the PtFileSel widget is doing intensive work and you may want to process events.

Prototypes have changed for:

• PtFSAllocItem()
• PtFSFreeAllItems()

PtGauge

Pt_ARG_GAUGE_MAXIMUM, Pt_ARG_GAUGE_MINIMUM, and Pt_ARG_GAUGE_VALUE are of type long.

PtGenList

The default value of Pt_ARG_BALLOON_COLOR is Pg_BLACK.

Pt_ARG_LIST_ITEM_COUNT and Pt_ARG_LIST_SEL_COUNT are of type unsigned short, not short.

PtGraphic

The example in the "Scaling based on original coordinates" section of the description has been corrected.

PtHtml

The description now includes a table of additional supported entities.

For more information on supporting images, see PxLoadImage() in the Photon Library Reference.

Pt_ARG_HTML_PAGE_N, Pt_ARG_HTML_PAGES, and the Pt_HTML_PAGE_MODE flag (see Pt_ARG_HTML_FLAGS) have been added to support printing.

PtIcon

The Pt_DELAY_ACTIVATION bit in the inherited resource Pt_ARG_FLAGS is now called Pt_DELAY_REALIZE.

PtLabel

The default value of Pt_ARG_UNDERLINE1 is Pg_BLACK. The default value of Pt_ARG_UNDERLINE2 is Pg_TRANSPARENT.

Pt_BACKFILL_TEXT has been added to the flags for Pt_ARG_LABEL_FLAGS

PtLine

Pt_ARG_LINE_STYLE has been removed from the list of inherited resources.

PtList

Prototypes have changed for:

• PtListAddItems()
• PtListItemExists()
• PtListItemPos()
• PtListRemovePositions()
• PtListReplaceItemPos()
• PtListReplaceItems()

PtListDeletePositions() is deprecated; use PtListRemovePositions() instead.

PtMenu

If Pt_MENU_TRANSIENT is set in the menu's Pt_ARG_MENU_FLAGS resource, the menu might be destroyed before the selected item's callback is invoked. To find out how to avoid this, see the "Lifetime" section of the description of PtMenu.

You can use the Pt_ARG_MENU_TEXT_FONT resource to control what font is used for displaying menu items. This resource overrides the normal default font for text items placed in the menu.

The Pt_DELAY_ACTIVATION bit in the inherited resource Pt_ARG_FLAGS is now called Pt_DELAY_REALIZE.

PtMenuBar

Pt_ARG_GROUP_HORZ_ALIGN and Pt_ARG_GROUP_VERT_ALIGN are inherited from PtGroup.

PtMenuButton

This widget inherits the following resources from PtLabel:

• Pt_ARG_HORIZONTAL_ALIGNMENT
• Pt_ARG_VERTICAL_ALIGNMENT
• Pt_ARG_ACCEL_KEY
• Pt_ARG_BALLOON_COLOR
• Pt_ARG_BALLOON_FILL_COLOR
• Pt_ARG_BALLOON_POSITION
• Pt_ARG_LABEL_BALLOON
• Pt_ARG_LABEL_FLAGS
• Pt_ARG_LABEL_DATA
• Pt_ARG_LABEL_TYPE
• Pt_ARG_LINE_SPACING
• Pt_ARG_UNDERLINE1
• Pt_ARG_UNDERLINE2
• Pt_ARG_UNDERLINE_TYPE

PtMessage

The prototype for PtMessageGetWindow() has been corrected.

PtMultiText

The example in "Setting text using ranges" has been corrected; the initialization for hello was incomplete.

The resource names have been corrected in the "Changing the attributes of a range of text" section of the Description.

The default value of Pt_ARG_MULTITEXT_FLAGS is Pt_EMT_SCROLL_TO_CURSOR.

The default value of Pt_ARG_MULTITEXT_TABS is { 20 }.

Pt_ARG_HORIZONTAL_ALIGNMENT and Pt_ARG_VERTICAL_ALIGNMENT are inherited from PtLabel.

Pt_CB_MODIFY_VERIFY and Pt_CB_MOTION_VERIFY are inherited from PtText. PtMultiTextControl_t, PtMultiTextCallback_t, and PtMultiTextInfo_t are the same structure.

Instructions for calculating the "virtual dimensions" of a multitext widget have been added.

To display a horizontal scrollbar in a PtMultiText widget:

• Set the Pt_ARG_SCROLLBAR_X_DISPLAY to Pt_AS_REQUIRED or Pt_ALWAYS.
• Clear Pt_EMT_WORD and Pt_EMT_CHAR in the widget's Pt_ARG_MULTITEXT_WRAP_FLAGS resource.

The example in "Hyperlinks using cursor-motion callbacks" has been corrected; the attr argument has been added to the call to PtMultiTextModifyText().

A list of the bits in the attributes_mask has been added to the descriptions of PtMultiTextModifyAttributes() and PtMultiTextModifyText().

Prototypes have changed for:

• PtMultiTextModifyAttributes()
• PtMultiTextModifyText()

If both Pt_EMT_WORD and Pt_EMT_CHAR are set in the widget's Pt_ARG_MULTITEXT_WRAP_FLAGS, word wrapping is applied.

PtNumericFloat

Pt_ARG_NUMERIC_ORIENTATION has been removed from the list of inherited resources.

The Pt_CB_ACTIVATE callback is invoked only when the user presses Enter when the text field has focus and the value has been changed.

The Pt type for Pt_ARG_NUMERIC_INCREMENT, Pt_ARG_NUMERIC_MAX, Pt_ARG_NUMERIC_MIN, and Pt_ARG_NUMERIC_VALUE is Struct.

PtNumericInteger

Pt_ARG_NUMERIC_ORIENTATION has been removed from the list of inherited resources.

The Pt_CB_ACTIVATE callback is invoked only when the user presses Enter when the text field has focus and the value has been changed.

PtOnOffButton

The Pt_CB_ONOFF_NEW_VALUE callbacks are now invoked whenever a call to PtSetResources() changes the state of the button, provided the Pt_CALLBACKS_ACTIVE flag is set.

PtPolygon

The bits defined for Pt_ARG_POLYGON_FLAGS can be ORed to specify the type of polygon.

Pt_ARG_LINE_STYLE has been removed from the list of inherited resources.

PtRaw

Don't call the drawing function directly from your program. Instead, damage the widget by calling PtDamageWidget(), and let the library call the drawing function.

PtRect

Pt_ARG_LINE_STYLE has been removed from the list of inherited resources.

PtScrollbar

The width of a stepper arrow in a horizontal scrollbar is automatically set to be 3/4 of the height of the scrollbar. Similarily, the height of a stepper arrow in a vertical scrollbar is set to 3/4 of the scrollbar's width.

PtSlider

Pt_ARG_SLIDER_INCREMENT and Pt_ARG_SLIDER_MULTIPLE are of type ushort_t.

If the widget has the Pt_CALLBACKS_ACTIVE bit set in its Pt_ARG_FLAGS resource, the Pt_CB_SLIDER_MOVE callbacks are invoked when the handle position is changed by a call to PtSetResources().

PtTerminal

The resource names have been corrected in the "Fonts" section of the Description.

The C type for Pt_ARG_TERM_CONSOLE is PtTerminalConsoleWrite_t The C type for Pt_ARG_TERM_PROTOCOL is int.

PtTerminal now includes internal and ANSI character sets. See:

• "Character sets" in the description
• Pt_ARG_TERM_CHARSETS
• PtTerminalCharset_t, PtTerminalCharsets_t
• PtTerminalCreateCsXlat().
• PtTerminalDefaultCharsets():

as well as the following functions described in the Photon Library Reference:

• PxTerminalBuildCharsets()
• PxTerminalSaveCharsets()
• PxTerminalLoadCharsets()

A section on PtTerminal and PtTty has been added to the description.

PtTerminal works only with fixed-width fonts. It ignores any attempts to change Pt_ARG_TERM_FONT to a proportional font.

PtText

The Pt_DELAY_ACTIVATION bit in the Pt_ARG_FLAGS resource is now called Pt_DELAY_REALIZE. This flag is mentioned in "String changes" in the description of this widget.

The description and callback structure for Pt_CB_ACTIVATE have been corrected.

PtTextControl_t and PtTextCallback_t are the same structure.

The default setting for Pt_ARG_RESIZE_FLAGS is Pt_RESIZE_Y_AS_REQUIRED | Pt_RESIZE_Y_INITIAL.

The prototype has changed for PtTextModifyText().

The descriptions of Pt_ARG_SELECTION_RANGE and Pt_ARG_TEXT_SUBSTRING have been expanded.

The example in "Handling deletions" has been improved.

The C type for Pt_ARG_CURSOR_POSITION is int, not short.

PtTimer

PtTimer is easy to use, but doesn't give accurate timer events. In particular, it doesn't guarantee a constant repeat rate; since the repetition is handled by rearming the timer for each event, any delays in handling the events accumulate. Kernel timers guarantee an accurate repeat rate even if your application can't keep up with them.

PtTree

An example of building a tree has been added to the description.

If you multi-click on an item, the tree's Pt_CB_TREE_SELECTION callbacks are invoked once for each click. The callback data includes the click count (1 for the first click, 2 for the second, and so on).

Prototypes have changed for:

• PtTreeGetCurrent()
• PtTreeItemIndex()

PtTty

Although PtTty is a descendant of PtContainer, you can't put any widgets in it.

Sections on PtTerminal and PtTty, setting PtTty resources and colors have been added to the description.

PtWidget

The default value of Pt_ARG_CURSOR_COLOR is Ph_CURSOR_DEFAULT_COLOR.

The Pt_ARG_DATA resource is used internally by the Photon libraries as well as by compound widgets.

The following resources can't be edited in PhAB:

• Pt_ARG_AREA (set automatically)
• Pt_ARG_BITMAP_CURSOR
• Pt_ARG_DATA
• Pt_ARG_DIM (set automatically)
• Pt_ARG_POS (set automatically)

The Pt_OBSCURED bit in Pt_ARG_FLAGS is set only if the widget is completely covered by one other widget, or it's completely beyond its parent container's canvas.

The Pt_CB_RAW callbacks are invoked after the widget has processed the event, and then only for events that the widget doesn't consume. Contrast this with the Pt_CB_FILTER resource defined by PtContainer.

PtWindow

If any of Pt_ARG_MAX_HEIGHT, Pt_ARG_MAX_WIDTH, Pt_ARG_MIN_HEIGHT, and Pt_ARG_MIN_WIDTH are set to 0, default values specified by the window manager are used.

The Pt type for Pt_ARG_WINDOW_CURSOR_OVERRIDE is Boolean, not Scalar.

PtWindowToBack() and PtWindowToFront() move the given window and all its child windows to the back or front of the workspace. There's no way to move a parent window in front of its children.

The Pt_CB_WINDOW callbacks are invoked for only those events specified in the Pt_ARG_WINDOW_NOTIFY_FLAGS.

The window hasn't been completely realized when the Pt_CB_WINDOW_OPENING callbacks are invoked; don't change the window's widget family hierarchy in these callbacks. If you need to adjust the widgets' stacking order, do it in the Pt_CB_REALIZED callbacks.

RtProgress

Pt_ARG_GAUGE_VALUE_PREFIX and Pt_ARG_GAUGE_VALUE_SUFFIX are inherited from PtGauge.

RtTrend

The default value of Rt_ARG_TREND_FLAGS is Rt_TREND_HORIZONTAL|Rt_GRID| Rt_TREND_RIGHT_TO_LEFT|Rt_GRID_IS_TRANSLUCENT.

The C type for the number of entries in the Rt_ARG_TREND_COLOR_LIST array is short.