Widget Ref

® ®
QNX Neutrino Realtime Operating System

®
Photon microGUI
Widget Reference
For QNX ® Neutrino® 6.5.0
© 2010, QNX Software Systems GmbH & Co. KG.

© 1995 – 2010, QNX Software Systems GmbH & Co. KG. All rights reserved.
Published under license by:
QNX Software Systems Co.
175 Terence Matthews Crescent
Kanata, Ontario
K2M 1W8
Canada
Voice: +1 613 591-0931
Fax: +1 613 591-3579
Email: info@qnx.com
Web: http://www.qnx.com/
Electronic edition published 2010.
QNX, Neutrino, Photon, Photon microGUI, Momentics, Aviage, and related marks, names, and logos are trademarks, registered in certain jurisdictions, of QNX Software
Systems GmbH & Co. KG. and are used under license by QNX Software Systems Co. All other trademarks belong to their respective owners.
Contents
About This Reference xv

What you’ll find in this guide xvii
Typographical conventions xvii
Note to Windows users xviii
Technical support xviii
1 Global Data Structures 1

PtBalloonCallback_t 5
PtCallback_t 6
PtCallbackInfo_t 8
PtHotkeyCallback_t 9
PtRawCallback_t 11
2 Widgets 13
Widget hierarchy 15
Widget icons in PhAB 16
What’s in a widget description? 19
PtArc 22
PtBarGraph 27
PtBasic 33
PtBezier 52
PtBkgd 56
PtButton 62
PtCalendar 68
PtClient 79
PtClock 87
PtColorPanel 96
PtColorPatch 100
PtColorSel 105
PtColorSelGroup 111
PtColorWell 115
PtComboBox 120
PtComboBoxListClose() 131
May 13, 2010 Contents iii

PtComboBoxListOpen() 132
PtCompound 133
PtContainer 137
PtDisjoint 152
PtDivider 156
PtEllipse 164
PtFileSel 168
PtFSAddAfter() 189
PtFSAddFirst() 191
PtFSAllItems() 193
PtFSAllocItem() 194
PtFSClearSelection() 196
PtFSDamageItem() 197
PtFSExpandParents() 198
PtFSFolderCollapse() 199
PtFSFolderExpand() 200
PtFSFreeAllItems() 201
PtFSFreeItems() 202
PtFSGetCurrent() 203
PtFSGetSelIndexes() 204
PtFSGoto() 205
PtFSItemIndex() 206
PtFSRemoveChildren() 207
PtFSRemoveItem() 208
PtFSRemoveList() 209
PtFSRootItem() 210
PtFSSelect() 211
PtFSSelectedItems() 212
PtFSSetSelIndexes() 213
PtFSShow() 214
PtFSUnselect() 215
PtFSUnselectNonBrothers() 216
PtFontSel 217
PtGauge 225
PtGenList 233
PtGenListAddItems() 250
PtGenListAllItems() 252
PtGenListClearSelection() 253
PtGenListCreateTextBalloon() 254
PtGenListDamageItem() 256
PtGenListDrawBackground() 257
iv Contents May 13, 2010

PtGenListDrawString() 259
PtGenListFirstItem() 261
PtGenListGetCurrent() 262
PtGenListGetSelIndexes() 263
PtGenListGoto() 264
PtGenListHold() 265
PtGenListItem_t 266
PtGenListItemIndex() 268
PtGenListItemRealloc() 269
PtGenListLastItem() 270
PtGenListLockItem() 271
PtGenListRelease() 272
PtGenListRemoveItems() 273
PtGenListResize() 274
PtGenListSelect() 275
PtGenListSelectedItems() 276
PtGenListSetColumnBalloon() 277
PtGenListSetGflags() 278
PtGenListSetSelIndexes() 279
PtGenListShow() 280
PtGenListUnlockItem() 281
PtGenListUnselect() 282
PtGenTree 283
PtGenTreeAddAfter() 292
PtGenTreeAddFirst() 293
PtGenTreeAllItems() 294
PtGenTreeClearSelection() 295
PtGenTreeCollapse() 296
PtGenTreeDamageItem() 297
PtGenTreeExpand() 298
PtGenTreeExpandParents() 299
PtGenTreeFreeAllItems() 300
PtGenTreeFreeItems() 301
PtGenTreeGetCurrent() 302
PtGenTreeGetSelIndexes() 303
PtGenTreeGoto() 304
PtGenTreeItem_t 305
PtGenTreeItemIndex() 307
PtGenTreeItemRealloc() 308
PtGenTreeItemResize() 309
PtGenTreeRemoveChildren() 310
May 13, 2010 Contents v

PtGenTreeRemoveItem() 311
PtGenTreeRemoveList() 312
PtGenTreeResize() 313
PtGenTreeRootItem() 314
PtGenTreeSelect() 315
PtGenTreeSelectedItems() 316
PtGenTreeSetSelIndexes() 317
PtGenTreeShow() 318
PtGenTreeUnselect() 319
PtGenTreeUnselectNonBrothers() 320
PtGraphic 321
PtGrid 332
PtGroup 336
PtImageArea 344
PtLabel 352
PtLine 367
PtList 371
PtListAddItems() 383
PtListDeleteAllItems() 384
PtListDeleteItemPos() 385
PtListDeleteItems() 386
PtListGotoPos() 387
PtListItemExists() 388
PtListItemPos() 389
PtListRemovePositions() 390
PtListReplaceItemPos() 391
PtListReplaceItems() 392
PtListSelectPos() 393
PtListShowPos() 394
PtListUnselectPos() 395
PtMenu 396
PtMenuBar 411
PtMenuButton 415
PtMeter 421
PtMTrend 434
PtMTrendAddData(), PtMTrendChangeData() 445
PtMultiText 447
PtMultiLines_t 472
PtMultiTextAttributes_t 474
PtMultiTextCallback_t 476
PtMultiTextCreateAttributes() 477
vi Contents May 13, 2010

PtMultiTextGetAttributes() 478
PtMultiTextInfo() 481
PtMultiTextLine_t 484
PtMultiTextModifyAttributes() 485
PtMultiTextModifyText() 487
PtMultiTextQuery_t 489
PtMultiTextSegment_t 490
PtNumeric 491
PtNumericFloat 496
PtNumericInteger 503
PtOnOffButton 509
PtOSContainer 514
PtPane 518
PtPanelGroup 522
PtPGCreatePopup() 534
PtPGFindIndexByPanel() 537
PtPGFindIndexByTitle() 538
PtPGFindPanelByIndex() 539
PtPGFindPanelByTitle() 540
PtPGFindTitleByIndex() 541
PtPixel 542
PtPolygon 545
PtPrintSel 549
PtProgress 559
PtProgressEntireSegment() 564
PtProgressFirstSegment() 565
PtProgressNextSegment() 566
PtProgressTextRect() 567
PtRaw 568
PtRawList 576
PtRawTree 586
PtRect 595
PtRegion 599
PtScrollArea 606
PtScrollAreaCanvas() 615
PtScrollbar 616
PtScrollContainer 624
PtSeparator 630
PtServer 638
PtSlider 646
PtTab 654
May 13, 2010 Contents vii

PtTerminal 660
PtTerminalCharset_t, PtTerminalCharsets_t 690
PtTerminalCopy() 693
PtTerminalCreateCsXlat() 694
PtTerminalDefaultCharsets() 695
PtTerminalFontInfo() 696
PtTerminalGetKeys() 697
PtTerminalGetSelection() 698
PtTerminalName() 699
PtTerminalPasteClipboard() 700
PtTerminalPasteSelection() 701
PtTerminalPut(), PtTerminalPutc(), PtTerminalPuts() 702
PtTerminalSelectWord() 703
PtText 704
PtTextCallback_t, PtTextControl_t, PtTextControlInfo_t 729
PtTextGetSelection() 730
PtTextModifyText() 731
PtTextSetSelection() 733
PtTimer 735
PtToggleButton 738
PtToolbar 744
PtToolbarGroup 749
PtTree 753
PtTreeAddAfter() 772
PtTreeAddFirst() 774
PtTreeAddImages() 776
PtTreeAllItems() 777
PtTreeAllocItem() 778
PtTreeChangeItem() 779
PtTreeClearSelection() 781
PtTreeCollapse() 782
PtTreeCreateItem() 783
PtTreeExpand() 785
PtTreeFreeAllItems() 786
PtTreeFreeItems() 787
PtTreeGetCurrent() 788
PtTreeGetSelIndexes() 789
PtTreeGoto() 790
PtTreeItem_t 791
PtTreeItemAttributes_t 793
PtTreeItemIndex() 795
viii Contents May 13, 2010

PtTreeModifyItem() 796
PtTreeModifyItemString() 797
PtTreeRemoveChildren() 798
PtTreeRemoveItem() 800
PtTreeRemoveList() 801
PtTreeRootItem() 802
PtTreeSelect() 803
PtTreeSelectedItems() 804
PtTreeSetSelIndexes() 805
PtTreeShow() 806
PtTreeUnselect() 807
PtTreeUnselectNonBrothers() 808
PtTrend 809
PtTrendChangeData(), PtTrendChangeTrendData() 819
PtTty 822
PtTtyShell() 838
PtUpDown 839
PtWebClient 845
PtWidget 917
PtWindow 941
PtWindowFocus() 958
PtWindowGetState() 959
PtWindowToBack() 960
PtWindowToFront() 961
A What’s New 963

What’s new in Photon for QNX Neutrino 6.5.0 965
Changes 965
Errata 965
What’s new in Photon for QNX Neutrino 6.4 966
Changes 966
What’s new in Photon for QNX Neutrino 6.3 Service Pack 1 966
New widgets 966
Changes 966
New widgets 967
Changes 967
Changes 970
Errata 970
May 13, 2010 Contents ix


New widgets 972
Deprecated widgets 973
Other changes 973
Glossary 985
Index 1001
x Contents May 13, 2010

List of Figures
The Photon widget hierarchy. 15
Instances of PtArc: arcs, circles, ellipses, wedges, and chords. 22
A PtBarGraph widget. 27
A widget displaying all the border components. 35
A widget displaying a half-round bevel. 35
A Bézier curve created by PtBezier. 52
Several different styles of background widgets. 56
A PtButton widget. 62
A PtCalendar widget. 68
Analog, digital, and LED clocks created by PtClock. 87
A PtColorPanel widget. 96
A PtColorPatch widget. 100
A PtColorSelGroup widget. 111
A PtColorWell widget. 115
A PtComboBox widget provides a text-entry area and a list of choices. 120
Two PtDivider widgets: one contains two lists, the other contains some buttons.
156
A PtEllipse widget. 164
A PtFileSel widget. 168
A single-level file selector. 170
The results of using PtFSAddAfter(). 189
The results of using PtFSAddFirst(). 191
The results of using PtFSRemoveChildren(). 207
The results of using PtFSRemoveItem(). 208
The results of using PtFSRemoveList(). 209
A PtFontSel widget. 217
A five-pointed star before clipping. 324
The star after clipping. 324
A PtGrid widget. 332
A group of buttons. 336
A text string in a PtLabel widget. 352
A PtLine widget. 367
A PtList containing text items. 371
A PtMenu widget that contains various menu items. 396
May 13, 2010 List of Figures xi

A PtMenuBar that contains several menu buttons. 411

A PtMenuButton widget. 415
A PtMeter widget. 421
A one-arc PtMeter widget. 422
A PtMTrend widget. 434
A PtMultiText widget. 447
A PtNumericFloat widget. 496
A PtNumericInteger widget. 503
A PtOnOffButton widget. 509
A dialog box featuring several PtPane widgets. 518
A PtPanelGroup widget as used in PhAB. 522
Open or closed PtPolygon widgets. 545
A PtPrintSel widget. 549
Two styles of PtProgress bar. 559
Additional Pt_ARG_TREE_FLAGS for a PtRawTree widget. 593
A PtRect widget. 595
A PtScrollbar widget. 616
A PtScrollContainer widget acts as a viewport. 624
PtSeparator widgets, as used to organize the items in a menu. 630
A PtSlider widget. 646
A PtSlider widget with a custom handle and trough. 646
A group of PtTab widgets positioned at the top of a PtPane. 654
A PtTerminal widget. 660
A PtText widget. 704
Various button styles supported by PtToggleButton. 738
A PtToolbar as used in PhAB. 744
A PtToolbarGroup. 749
A PtTree widget, as used in the Helpviewer. 753
A PtTree without images. 754
A PtTree with images. 756
Additional Pt_ARG_TREE_FLAGS for a PtTree widget. 769
The results of using PtTreeAddAfter(). 772
The results of using PtTreeAddFirst(). 774
The results of using PtTreeRemoveChildren(). 798
The results of using PtTreeRemoveItem(). 800
The results of using PtTreeRemoveList(). 801
A PtTrend widget. 809
Replacing trend samples with PtTrendChangeData() or
PtTrendChangeTrendData(). 820
Output from a terminal device. 822
A PtUpDown widget. 839
xii List of Figures May 13, 2010

A PtWindow widget that contains an editor application. 941
May 13, 2010 List of Figures xiii

About This Reference
May 13, 2010 About This Reference xv

© 2010, QNX Software Systems GmbH & Co. KG. Typographical conventions
What you’ll find in this guide

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 the What’s New
appendix to find out how the widgets have changed in this release.
For information about: See:

Data structures Global Data Structures
Widget classes Widgets
What is new or changed in this release What’s New
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.
Typographical conventions
Throughout this manual, we use certain typographical conventions to distinguish
technical terms. In general, the conventions we use conform to those found in IEEE
POSIX publications. The following table summarizes our conventions:
Reference Example
Code examples if( stream == NULL )
Command options -lR
Commands make
Environment variables PATH
File and pathnames /dev/null
Function names exit()
Keyboard chords Ctrl-Alt-Delete
Keyboard input something you type
Keyboard keys Enter
Program output login:
continued. . .
May 13, 2010 About This Reference xvii

Technical support © 2010, QNX Software Systems GmbH & Co. KG.
Reference Example
Programming constants NULL
Programming data types unsigned short
Programming literals 0xFF, "message string"
Variable names stdin
User-interface components Cancel
We use an arrow (→) in directions for accessing menu items, like this:
You’ll find the Other... menu item under Perspective→Show View.
We use notes, cautions, and warnings to highlight important messages:
Notes point out something important or useful.
CAUTION: Cautions tell you about commands or procedures that may have
! unwanted or undesirable side effects.
WARNING: Warnings tell you about commands or procedures that could be

dangerous to your files, your hardware, or even yourself.
Note to Windows users

In our documentation, we use a forward slash (/) as a delimiter in all pathnames,
including those pointing to Windows files.
We also generally follow POSIX/UNIX filesystem conventions.
Technical support
To obtain technical support for any QNX product, visit the Support area on our
website (www.qnx.com). You’ll find a wide range of support options, including
community forums.
xviii About This Reference May 13, 2010

Chapter 1
Global Data Structures
May 13, 2010 Chapter 1 • Global Data Structures 1

The Photon API defines various data types and structures:
• If you’re using the Photon Application Builder (PhAB), the appropriate header files
are automatically included in your application.
• If you’re not using PhAB, include <Pt.h>.
This chapter describes the data structures listed below:
PtBalloonCallback_t
Balloon callback structure
PtCallback_t Regular callback structure
PtCallbackInfo_t
Specific callback information
PtHotkeyCallback_t
Hotkey handler structure
PtRawCallback_t
Event handler structure
The following datatypes are described in the Photon Library Reference:
ApInfo_t PhAB information structure
PgColor_t Composite color value
PgColorHSV_t Hue-Saturation-Value color value
PhArea_t Position and dimensions of a rectangular area
PhClipboardHdr Clipboard header structure
PhDim_t Dimensions of an area
PhEvent_t An event
PhEventRegion_t
Emitter and collector of an event
PhImage_t Data and characteristics of an image
PhPoint_t Coordinates of a single point
PhRect_t Coordinates of a rectangle
PhRegion_t A region

PhRegionDataHdr_t
Data that’s attached to a region
PhTile_t A list of rectangles
PhWindowEvent_t
A window action
PtArg_t Argument structure used for getting and setting widget resources
PtDndFetch_t Structure that defines data types a widget accepts from a

drag-and-drop event
PtFDProc_t Type for defining a file-descriptor function
PtInputCallbackProc_t
Type for defining a input callback function
PtSignalProc_t Type for defining a signal-handling function
PtWorkProc_t Type for defining a work procedure function
4 Chapter 1 • Global Data Structures May 13, 2010

© 2010, QNX Software Systems GmbH & Co. KG. PtBalloonCallback_t
Balloon callback structure
Synopsis:
typedef struct Pt_balloon_callback {
PtWidget_t *widget;
void (*event_f )( PtWidget_t *wgt,
void *data,
PtCallbackInfo_t *cbinfo);
} PtBalloonCallback_t;
Description:
The PtBalloonCallback_t structure lets you attach a balloon callback to a
widget’s container. The container invokes the specified function whenever a balloon
action is warranted. This structure contains at least:
widget A pointer to the widget the callback is being attached to.
event_f A pointer to an inflate/deflate function that’s called whenever a balloon

action is required for widget. The arguments passed to this function are:
wgt A pointer to the widget whose balloon is being affected.

data NULL.
cbinfo In the cbinfo structure, the reason member is Pt_CB_BALLOONS,
and the reason_subtype member is one of the following:
• Pt_INFLATE_BALLOON— make the balloon visible.
• Pt_POP_BALLOON— remove the balloon.
Classification:
Photon
See also:
PtCallbackInfo_t, PtContainer

PtCallback_t © 2010, QNX Software Systems GmbH & Co. KG.
Regular callback structure
Synopsis:
typedef struct Pt_callback {
int (*event_f )( PtWidget_t *, void *,
PtCallbackInfo_t * );
void *data;
} PtCallback_t;
Description:
The PtCallback_t structure lets you specify a widget’s callbacks when you call
PtCreateWidget() or PtAddCallbacks().
This structure contains at least:
event_f A pointer to the callback function.
data A pointer to data that you want to pass as the second parameter to the
callback function when it’s invoked.
Callback functions
A callback function takes the following arguments:
PtWidget_t *widget
A pointer to the widget instance that invoked the callback.
void *client_data
The data from the PtCallback_t structure.
A PhAB callback takes as its second argument a pointer to an ApInfo_t structure.

For more information, see the Photon Library Reference.
PtCallbackInfo_t *cbinfo
A pointer to a common Photon callback structure. The structure provides
information related to the widget callback being invoked, the Photon event, and
some widget-specific callback data. The format of the data varies with the
widget class and callback type. For more information, see PtCallbackInfo_t.
Callback functions should return Pt_CONTINUE unless the description of the widget’s
callback resource tells you to return something else.
Classification:
Photon

© 2010, QNX Software Systems GmbH & Co. KG. PtCallback_t
See also:
PtBalloonCallback_t, PtCallbackInfo_t, PtHotkeyCallback_t,
PtRawCallback_t
ApInfo_t, PtAddCallbacks(), PtCreateWidget() in the Photon Library Reference
“Callbacks” in the Managing Widgets in Application Code chapter of the Photon
Programmer’s Guide.

PtCallbackInfo_t © 2010, QNX Software Systems GmbH & Co. KG.
Specific callback information
Synopsis:
typedef struct Pt_callback_info {
unsigned long reason;
unsigned long reason_subtype;
PhEvent_t *event;
void *cbdata;
} PtCallbackInfo_t;
Description:
The PtCallbackInfo_t structure is the third argument passed to all callback
functions. You can use this structure to determine why callbacks occurred and to get
the specific callback information.
The structure contains at least the following members:
reason The reason why this callback was invoked. For example, if you
cause the widget to invoke its Pt_CB_ACTIVATE callback,
reason is Pt_CB_ACTIVATE.
reason_subtype If there are different ways to invoke the callback, this member
indicates which one.
event A pointer to a PhEvent_t structure that describes the event that

caused this callback to be invoked.
cbdata A pointer to callback-specific data.
For more information about these fields, see the descriptions of callbacks for each
widget.
Classification:
Photon
See also:
PtBalloonCallback_t, PtCallback_t, PtHotkeyCallback_t,
PtRawCallback_t
PhEvent_t in the Photon Library Reference

© 2010, QNX Software Systems GmbH & Co. KG. PtHotkeyCallback_t
Hotkey handler structure
Synopsis:
typedef struct Pt_hotkey_callback {
unsigned short key_sym_cap;
short flags;
unsigned long key_mods;
PtWidget_t *widget;
void *data;
int (*event_f )(
PtWidget_t *, void *,
} PtHotkeyCallback_t;
Description:
The PtHotkeyCallback_t structure lets you specify hotkeys or hotkey handlers, or
both, for various widgets. It contains at least the following members:
key_sym_cap Depending on the specified flags, this member contains either the
symbol or cap of the key to be interpreted as a hotkey. For valid
key_sym_cap values, see <photon/PkKeyDef.h>.
flags Determines how key_sym_cap is interpreted and whether or not

key_mods is used. Valid bits include:
Pt_HOTKEY_SYM Interpret key_sym_cap as a key symbol; the

default is to interpret it as a key cap.
Pt_HOTKEY_IGNORE_MODS
Ignore the key_mods argument. This flag is
typically used in menus, where you want both
upper- and lowercase letters to be accepted as
hotkeys.
key_mods Key modifiers that must be active for the key to be considered a
hotkey. If the Pt_HOTKEY_IGNORE_MODS flag is set, this
member is ignored.
For valid key modifiers, see <photon/PkKeyDef.h>. All
key-modifier manifests begin with Pk_KM_.
widget If event_f is NULL, the widget member’s activate callback is

invoked with a reason_subtype of Pt_CB_HOTKEY. If the widget
member is NULL when the hotkey is attached, it’s set to the widget
that the hotkey is attached to.
data A pointer to any data that you want to pass as the second argument
to the callback function.
event_f A pointer to the hotkey function. If event_f is NULL when the

hotkey is activated, the widget that the hotkey is attached to has its

PtHotkeyCallback_t © 2010, QNX Software Systems GmbH & Co. KG.
Pt_CB_ACTIVATE callback (see PtBasic) invoked with a

reason_subtype of Pt_CB_HOTKEY.
Classification:
Photon
See also:
PtBalloonCallback_t, PtCallback_t, PtCallbackInfo_t,
Pt_CB_ACTIVATE (PtBasic), Pt_CB_HOTKEY (PtWidget), PtRawCallback_t

© 2010, QNX Software Systems GmbH & Co. KG. PtRawCallback_t
Event handler structure
Synopsis:
typedef struct Pt_raw_callback {
unsigned long event_mask;
int (*event_f )(
PtWidget_t *,
void *,
void *data;
} PtRawCallback_t;
Description:
The PtRawCallback_t structure lets you specify event handlers (raw and filter
callbacks) for your application’s widgets. You use this structure when setting the
Pt_CB_RAW or Pt_CB_FILTER resource of any widget (see PtWidget) or calling
PtAddEventHandler(), PtAddEventHandlers(), PtAddFilterCallback(), or
PtAddFilterCallbacks().
This structure contains at least the following members:
event_mask A bitmap that specifies which events trigger the function specified in
event_f . See PhEvent_t in the Photon Library Reference.
event_f A pointer to the callback function.
data A pointer to data that you want to be passed as the second argument
to the callback function.
Classification:
Photon
See also:
PtBalloonCallback_t, PtCallback_t, PtCallbackInfo_t, Pt_CB_RAW
(PtWidget), PtHotkeyCallback_t
PtAddEventHandler(), PtAddEventHandlers() PtAddFilterCallback(),
PtAddFilterCallbacks() in the Photon Library Reference
“Event handlers” in the Managing Widgets in Application Code chapter of the Photon
Programmer’s Guide

Chapter 2
Widgets
May 13, 2010 Chapter 2 • Widgets 13

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

Widget icons in PhAB © 2010, QNX Software Systems GmbH & Co. KG.
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 Bé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
continued. . .
16 Chapter 2 • Widgets May 13, 2010

© 2010, QNX Software Systems GmbH & Co. KG. Widget icons in PhAB

N/A PtCompound Superclass for compound widgets—not
PtContainer Superclass for container widgets

N/A PtDisjoint Superclass for disjoint widgets—not
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
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
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
continued. . .

Widget icons in PhAB © 2010, QNX Software Systems GmbH & Co. KG.
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
PtScrollBar Scrollbar
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. What’s in a widget description?
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.

What’s in a widget description? © 2010, QNX Software Systems GmbH & Co. KG.
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.

© 2010, QNX Software Systems GmbH & Co. KG. What’s in a widget description?
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.

PtArc © 2010, QNX Software Systems GmbH & Co. KG.
An elliptical arc
Class hierarchy:
PtWidget → PtBasic → PtGraphic → PtArc
PhAB icon:
Public header:
<photon/PtArc.h>
Description:
You can use PtArc to create an elliptical arc that’s defined by:
• the origin
• an ellipse
• a start angle
• an end angle.
Instances of PtArc: arcs, circles, ellipses, wedges, and chords.
The ellipse is specified using two control points stored in Pt_ARG_POINTS. These
points are relative to the widget’s origin, Pt_ARG_ORIGIN (see PtGraphic). If the
points aren’t set, the ellipse is specified by the widget’s dimensions, Pt_ARG_DIM.
An arc is drawn along the ellipse in a counter-clockwise direction, starting at the start
angle and finishing at the end angle. The start and end angles are specified by two
resources: Pt_ARG_ARC_START and Pt_ARG_ARC_END.
The arc may be scaled directly by scaling its defining points. Scaling a circular arc by
unequal amounts in the x and y directions results in an elliptical arc.
The arc may also be drawn as a closed curve by specifying the arc type with the
Pt_ARG_ARC_TYPE resource:
• Pt_ARC_CURVE — draws the arc inscribed by the points

• Pt_ARC_PIE — draws the arc inscribed by the points with lines drawn from the two
end points to the centroid of the arc, creating a pie-slice

© 2010, QNX Software Systems GmbH & Co. KG. PtArc
• Pt_ARC_CHORD — draws the arc inscribed by the points with the chord
connecting the two end points closing the curve.
New resources:
Resource C type Pt type Default

Pt_ARG_ARC_END unsigned short Scalar 0
Pt_ARG_ARC_START unsigned short Scalar 0
Pt_ARG_ARC_TYPE unsigned short Scalar Pt_ARC_CURVE
Pt_ARG_ARC_END
C type Pt type Default
unsigned short Scalar 0
The end angle, in tenths of a degree.
Pt_ARG_ARC_START
The start angle, in tenths of a degree. If this angle is 0, the arc starts on the horizon, to
the right of the center. Angles increase in a counter-clockwise direction.
Pt_ARG_ARC_TYPE
unsigned short Scalar Pt_ARC_CURVE
The type of arc; one of:
Pt_ARC_CHORD Curve with ends connected by a straight line.
Pt_ARC_CURVE Curve only.
Pt_ARC_PIE Curve with ends connected to the center.
Inherited resources:
If the widget modifies an inherited resource, the “Default override” column indicates
the new value. This modification affects any subclasses of the widget.

Resource Inherited from Default override

Pt_ARG_ANCHOR_FLAGS PtWidget
Pt_ARG_ANCHOR_OFFSETS PtWidget
Pt_ARG_AREA PtWidget
Pt_ARG_BASIC_FLAGS PtBasic
Pt_ARG_BEVEL_WIDTH PtWidget
Pt_ARG_BITMAP_CURSOR PtWidget
Pt_ARG_BEVEL_COLOR PtBasic
Pt_ARG_BEVEL_CONTRAST PtBasic
Pt_ARG_COLOR PtBasic
Pt_ARG_CONTRAST PtBasic
Pt_ARG_CURSOR_COLOR PtWidget
Pt_ARG_CURSOR_TYPE PtWidget
Pt_ARG_DARK_BEVEL_COLOR PtBasic
Pt_ARG_DARK_FILL_COLOR PtBasic
Pt_ARG_DASH_LIST PtGraphic
Pt_ARG_DASH_SCALE PtGraphic
Pt_ARG_DATA PtWidget
Pt_ARG_DIM PtWidget
Pt_ARG_EFLAGS PtWidget
Pt_ARG_EXTENT PtWidget
Pt_ARG_FILL_COLOR PtBasic Pg_TRANSPARENT
Pt_ARG_FILL_PATTERN PtBasic
Pt_ARG_FLAGS PtWidget
Pt_ARG_GRAPHIC_FLAGS PtGraphic
Pt_ARG_HEIGHT PtWidget
Pt_ARG_HELP_TOPIC PtWidget
Pt_ARG_HIGHLIGHT_ROUNDNESS PtBasic
Pt_ARG_INLINE_COLOR PtBasic
Pt_ARG_INSIDE_COLOR PtGraphic
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtArc

Pt_ARG_LIGHT_BEVEL_COLOR PtBasic
Pt_ARG_LIGHT_FILL_COLOR PtBasic
Pt_ARG_LINE_CAP PtGraphic
Pt_ARG_LINE_JOIN PtGraphic
Pt_ARG_LINE_WIDTH PtGraphic
Pt_ARG_MARGIN_HEIGHT PtBasic
Pt_ARG_MARGIN_WIDTH PtBasic
Pt_ARG_MAXIMUM_DIM PtWidget
Pt_ARG_MINIMUM_DIM PtWidget
Pt_ARG_ORIGIN PtGraphic
Pt_ARG_OUTLINE_COLOR PtBasic
Pt_ARG_POINTER PtWidget
Pt_ARG_POINTS PtGraphic
Pt_ARG_POS PtWidget
Pt_ARG_RESIZE_FLAGS PtWidget Pt_RESIZE_XY_AS_REQUIRED
Pt_ARG_STYLE PtBasic
Pt_ARG_TRANS_PATTERN PtBasic
Pt_ARG_USER_DATA PtWidget
Pt_ARG_WIDTH PtWidget
Pt_CB_ACTIVATE PtBasic
Pt_CB_ARM PtBasic
Pt_CB_BLOCKED PtWidget
Pt_CB_DESTROYED PtWidget
Pt_CB_DISARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_FILTER PtWidget
Pt_CB_GOT_FOCUS PtBasic
Pt_CB_HOTKEY PtWidget
Pt_CB_IS_DESTROYED PtWidget
continued. . .


Pt_CB_LOST_FOCUS PtBasic
Pt_CB_MENU PtBasic
Pt_CB_OUTBOUND PtWidget
Pt_CB_RAW PtWidget
Pt_CB_REALIZED PtWidget
Pt_CB_REPEAT PtBasic
Pt_CB_RESCALE PtGraphic
Pt_CB_UNREALIZED PtWidget

© 2010, QNX Software Systems GmbH & Co. KG. PtBarGraph
A bar graph
Class hierarchy:
PtWidget → PtBasic → PtBarGraph
PhAB icon:
Public header:
<photon/PtBarGraph.h>
Description:
PtBarGraph draws a horizontal or vertical bar graph, with or without a grid.
A PtBarGraph widget.
You specify the bars by setting Pt_ARG_BARGRAPH_DATA to an array of values.

The colors of the bars depends on how you set the widget’s resources:
• To specify the color for each bar, set Pt_ARG_BARGRAPH_COLOR to be an array

of PgColor_t values.
• If you set Pt_ARG_BARGRAPH_COLOR to NULL, the widget uses the value of

Pt_ARG_COLOR for all the bars.
The Pt_ARG_BARGRAPH_FLAGS resource controls the direction of the graph and

whether or not the grid is displayed.
If you set Pt_ARG_BARGRAPH_DEPTH to a positive value, the bars are drawn with
a bevel.

PtBarGraph © 2010, QNX Software Systems GmbH & Co. KG.
New resources:

Pt_ARG_BARGRAPH_BASE short Scalar 0
Pt_ARG_BARGRAPH_COLOR PgColor_t, short Array NULL
Pt_ARG_BARGRAPH_DATA short, short Array NULL
Pt_ARG_BARGRAPH_DEPTH short Scalar 0
Pt_ARG_BARGRAPH_FLAGS long Flag Pt_BARGRAPH_VERTICAL
Pt_ARG_BARGRAPH_GRID_COLOR PgColor_t Scalar Pg_DGREY

Pt_ARG_BARGRAPH_GRID_HORIZ short Scalar 6
Pt_ARG_BARGRAPH_GRID_VERT short Scalar 6
Pt_ARG_BARGRAPH_MAX short Scalar SHRT_MAX
Pt_ARG_BARGRAPH_MIN short Scalar SHRT_MIN
Pt_ARG_BARGRAPH_BASE
short Scalar 0
The value that’s used as the base line for the bars. If the data for a bar is greater than
this value, the bar is displayed above the base line (for a vertical bar graph) or to the
right (for a horizontal graph).
Pt_ARG_BARGRAPH_COLOR
PgColor_t, short Array NULL
An array of colors to use for the bars. If this resource is NULL, the widget uses the
value of Pt_ARG_COLOR (inherited from PtBasic) as the color for all the bars.
You should have at least as many bar colors as entries in the
Pt_ARG_BARGRAPH_DATA array.
You can’t edit this resource in PhAB.
Here’s an example of setting this resource:

PgColor_t bar_colours[7] = {Pg_RED, Pg_BLUE, Pg_CELIDON,
Pg_GREEN, Pg_YELLOW, Pg_MAGENTA,

Pg_DGREEN };
PtSetResource (widget, Pt_ARG_BARGRAPH_COLOR, bar_colours, 7);
Pt_ARG_BARGRAPH_DATA
short, short Array NULL
The data to be displayed in the bar graph. When you set this resource, the value is the
array of data, and arg is the number of bars.
Here’s an example of setting this resource:
short bar_values[7] = {0, 450, 399, 22, 500, 50, 555 };
PtSetResource (widget, Pt_ARG_BARGRAPH_DATA, bar_values, 7);
Pt_ARG_BARGRAPH_DEPTH
short Scalar 0
The depth of the bars in the graph, in pixels.
Pt_ARG_BARGRAPH_FLAGS
long Flag Pt_BARGRAPH_VERTICAL
Flags that affect the appearance and behavior of the bar graph; a combination of:
Pt_BARGRAPH_GRID
Display a grid.
Pt_BARGRAPH_VERTICAL
Make the bars vertical.
Pt_BARGRAPH_HORIZONTAL
Make the bars horizontal.

Pt_ARG_BARGRAPH_GRID_COLOR

PgColor_t Scalar Pg_DGREY
The color of the grid, if displayed.
Pt_ARG_BARGRAPH_GRID_HORIZ
short Scalar 6
The number of horizontal lines in the grid.
Pt_ARG_BARGRAPH_GRID_VERT
short Scalar 6
The number of vertical lines in the grid.
Pt_ARG_BARGRAPH_MAX
short Scalar SHRT_MAX
The maximum value in the bar graph.
Pt_ARG_BARGRAPH_MIN
short Scalar SHRT_MIN
The minimum value in the bar graph.


Pt_ARG_COLOR PtBasic Pg_RED
Pt_ARG_DIM PtWidget
Pt_ARG_FILL_COLOR PtBasic Pg_BLACK
continued. . .


Pt_ARG_POS PtWidget
Pt_ARG_RESIZE_FLAGS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

© 2010, QNX Software Systems GmbH & Co. KG. PtBasic
A superclass of basic resources for most widgets
Class hierarchy:
PtWidget → PtBasic
Immediate subclasses:
• PtBarGraph –>
• PtCalendar
• PtClock
• PtContainer
• PtGauge
• PtGraphic
• PtLabel
• PtRaw
• PtSeparator
• PtTrend
PhAB icon:
Public header:
<photon/PtBasic.h>
Description:
The PtBasic superclass provides basic resources for all widgets. It provides the
fundamental callbacks for:
• getting/losing focus
• activating
• button press, release, and repeat
Also, PtBasic supports:
• toggle buttons
• autohighlighting
and provides resources for:
• margins

PtBasic © 2010, QNX Software Systems GmbH & Co. KG.
• bevel colors
• outline and inline colors
• draw color
• fill color
• fill pattern.
Selecting widgets
PtBasic defines some callback resources for actions involving the left pointer button.
These callbacks are invoked only if the widget has Pt_SELECTABLE set in its
Pt_ARG_FLAGS (see PtWidget).
When you: The widget becomes: Callback invoked:

Press the left pointer button while Armed Pt_CB_ARM
pointing at the widget
Release the left pointer button Activated Pt_CB_ACTIVATE
while pointing at an armed widget
Release the left pointer button Disarmed Pt_CB_DISARM
when the pointer is outside an
armed widget
• Not all widgets change their appearance when armed.
• The callback information for Pt_CB_ACTIVATE includes the number of clicks.

The activate callbacks are invoked once for each click.
If you hold down the left pointer button, the widget’s Pt_CB_REPEAT callbacks are
invoked.
PtBasic also defines an action involving the right pointer button: when you press the
right pointer button while pointing at a widget, the widget’s Pt_CB_MENU callback
list is invoked.
In order for this action to occur, the widget must have must have Pt_MENUABLE set
and Pt_ALL_BUTTONS cleared in its Pt_ARG_FLAGS resource; the widget doesn’t
have to have Pt_SELECTABLE set. Pt_CB_MENU is invoked only when the pointer
button is pressed, not when the button is released or held down.
If the widget has Pt_ALL_BUTTONS set in its Pt_ARG_FLAGS resource, the actions
for all pointer buttons are those for the left button.

Borders and colors

PtBasic defines resources that give you full control over the widget’s colors,
shadings, and borders.
A widget’s border is made up of various components, all of which are optional; set the
bits in Pt_ARG_BASIC_FLAGS to indicate which components to display. These
components, going from outside to inside, are:
• A one-pixel etch line
• A one-pixel outline, of the color specified by Pt_ARG_OUTLINE_COLOR
• A shaded bevel, the width of which is set by Pt_ARG_BEVEL_WIDTH (defined

by PtWidget)
• A one-pixel inline, of the color specified by Pt_ARG_INLINE_COLOR
A widget displaying all the border components.
The color of the bevel is the same as the widget’s fill color unless overridden by
Pt_ARG_BEVEL_COLOR. The bevel is shaded according to
Pt_ARG_BEVEL_CONTRAST, which is used to calculate the default values of
Pt_ARG_DARK_BEVEL_COLOR and Pt_ARG_LIGHT_BEVEL_COLOR. You can
override the contrast by setting the light and dark bevel colors explicitly. By default,
the upper left corner of the bevel is a gradient that goes from the light bevel color to
the light fill color. The lower right bevel goes from the dark fill color to the dark bevel
color.
If you set Pt_STATIC_BEVEL_COLORS in Pt_ARG_BASIC_FLAGS, the bevel color
doesn’t change when you set Pt_ARG_FILL_COLOR.
You can display a full (i.e. half-round) bevel by setting Pt_FULL_BEVELS in
Pt_ARG_BASIC_FLAGS:
A widget displaying a half-round bevel.
You can use Pt_ARG_FILL_COLOR to specify the widget’s fill color. These bits in
Pt_ARG_BASIC_FLAGS affect the fill:

Pt_FLAT_FILL By default, the widget’s fill is a flat color; to use a gradient for the
fill, clear this bit.
Pt_REVERSE_GRADIENT
The default gradient goes from the light fill color at the top to the
dark fill color at the bottom. To reverse the gradient, set this bit.
Pt_HORIZONTAL_GRADIENT
Make the gradient change color on the horizontal axis instead of
the vertical axis.
You can specify the amount of contrast between the light and dark fill colors by setting
Pt_ARG_CONTRAST. If this resource doesn’t give you the look you want, you can
override it by setting Pt_ARG_DARK_FILL_COLOR and
Pt_ARG_LIGHT_FILL_COLOR explicitly.
Pt_ARG_COLOR specifies the foreground or drawing color.
Setting Pt_ARG_FILL_COLOR overrides any previous setting of

Pt_ARG_DARK_FILL_COLOR, and Pt_ARG_LIGHT_FILL_COLOR. If
Pt_STATIC_BEVEL_COLORS isn’t set in Pt_ARG_BASIC_FLAGS, the new fill color
also overrides Pt_ARG_BEVEL_COLOR, Pt_ARG_DARK_BEVEL_COLOR, and
Pt_ARG_LIGHT_BEVEL_COLOR.
New resources:

Pt_ARG_BANDWIDTH_THRESHOLD unsigned long Scalar 0
Pt_ARG_BASIC_FLAGS unsigned long Flag Pt_ALL_ETCHES | Pt_ALL_BEVELS |
Pt_ALL_OUTLINES | Pt_FLAT_FILL
Pt_ARG_BEVEL_COLOR PgColor_t Scalar Pg_LGREY

Pt_ARG_BEVEL_CONTRAST char Scalar 75
Pt_ARG_COLOR PgColor_t Scalar Pg_BLACK
Pt_ARG_CONTRAST char Scalar 20
Pt_ARG_DARK_BEVEL_COLOR PgColor_t Scalar Set internally
Pt_ARG_DARK_FILL_COLOR PgColor_t Scalar Set internally
Pt_ARG_FILL_COLOR PgColor_t Scalar Pg_LGREY
continued. . .


Pt_ARG_FILL_PATTERN PgPattern_t Struct Pg_PAT_FULL
Pt_ARG_HIGHLIGHT_ROUNDNESS unsigned char Scalar 0
Pt_ARG_INLINE_COLOR PgColor_t Scalar Pg_DGRAY
Pt_ARG_LIGHT_BEVEL_COLOR PgColor_t Scalar Set internally
Pt_ARG_LIGHT_FILL_COLOR PgColor_t Scalar Set internally
Pt_ARG_MARGIN_HEIGHT unsigned short Scalar 0
Pt_ARG_MARGIN_WIDTH unsigned short Scalar 0
Pt_ARG_OUTLINE_COLOR PgColor_t Scalar Pg_WHITE
Pt_ARG_STYLE See below Complex
Pt_ARG_TRANS_PATTERN PgPattern_t Struct Pg_PAT_NONE
Pt_CB_ACTIVATE PtCallback_t * Link NULL
Pt_CB_ARM PtCallback_t * Link NULL
Pt_CB_DISARM PtCallback_t * Link NULL
Pt_CB_GOT_FOCUS PtCallback_t * Link NULL
Pt_CB_LOST_FOCUS PtCallback_t * Link NULL
Pt_CB_MENU PtCallback_t * Link NULL
Pt_CB_REPEAT PtCallback_t * Link NULL
Pt_ARG_BANDWIDTH_THRESHOLD
unsigned long Scalar 0
PtBasic defines this resource but ignores any attempts to set it. It is overridden and
used by some of PtBasic’s descendents. In general, it defines a threshold below
which a widget optimizes drawing on a system with a slow connection.
Pt_ARG_BASIC_FLAGS
unsigned long Flag Pt_ALL_ETCHES | Pt_ALL_BEVELS |
Pt_ALL_OUTLINES | Pt_FLAT_FILL
This flag resource controls which “edge decorations” are rendered for a widget when
it’s highlighted (see Pt_ARG_FLAGS, defined by PtWidget). It gives you individual
control over the rendering of the top, bottom, left, and right edges of a widget. It also

gives you control over the fill type (flat or gradient) and several behavior elements
with regards to the rendering of a widget’s border.
Valid Pt_ARG_BASIC_FLAGS bits (applied only if the widget is also highlighted)
control:
• the appearance of the edges
• the fill
• the behavior when the widget’s state changes.
Edge-control bits
Pt_TOP_ETCH
Pt_BOTTOM_ETCH
Pt_LEFT_ETCH
Pt_RIGHT_ETCH Render a single alpha line on an edge of the widget. The top
and left lines are dark, and the bottom and right lines are light.
This can make a widget look like it’s slightly inset.
Pt_BLANK_ETCHES Don’t draw the etched lines.
Pt_OPAQUE_ETCHES
Use a solid line, instead of an alpha line, for the etching. The
color is calculated based on the widget’s color and widget’s
parent color.
Pt_TOP_OUTLINE
Pt_BOTTOM_OUTLINE
Pt_LEFT_OUTLINE
Pt_RIGHT_OUTLINE
Render a single-pixel outline on an edge of the widget.
Pt_TOP_BEVEL
Pt_BOTTOM_BEVEL
Pt_LEFT_BEVEL
Pt_RIGHT_BEVEL
Render a bevel Pt_ARG_BEVEL_WIDTH pixels wide on an
edge of the widget.
Pt_FULL_BEVELS Render a full bevel (i.e. half-round) instead of a half bevel

(quarter-round).
Pt_TOP_INLINE
Pt_BOTTOM_INLINE
Pt_LEFT_INLINE
Pt_RIGHT_INLINE
Render a single-pixel inline on an edge of the widget.

These convenience manifests make working with these bits easier:
Pt_TOP_LEFT_ETCH
Pt_BOTTOM_RIGHT_ETCH
Pt_ALL_ETCHED
Pt_ALL_ETCHES
Adjust the etching on the top/left, bottom/right, or all edges.
Pt_TOP_LEFT_OUTLINE
Pt_BOTTOM_RIGHT_OUTLINE
Pt_ALL_OUTLINES
Adjust the outline on the top/left, bottom/right, or all edges.
Pt_TOP_LEFT_BEVEL
Pt_BOTTOM_RIGHT_BEVEL
Pt_ALL_BEVELS
Adjust the bevel on the top/left, bottom/right, or all edges.
Pt_TOP_LEFT_INLINE
Pt_BOTTOM_RIGHT_INLINE
Pt_ALL_INLINES
Adjust the inline on the top/left, bottom/right, or all edges.
Pt_ALL_TOP
Pt_ALL_BOTTOM
Pt_ALL_LEFT
Pt_ALL_RIGHT
Pt_ALL Adjust all edge decorations (etch, outline, bevel, and inline) on
the top, left, bottom, right, or all edges.
Fill-control bits
Pt_FLAT_FILL If set, the widget is filled with a solid color as given by

Pt_ARG_FILL_COLOR. If clear, the widget is filled with a
gradient.
Pt_HORIZONTAL_GRADIENT
If set, and Pt_FLAT_FILL is clear, the fill gradient changes colors
on the horizontal axis. If clear and Pt_FLAT_FILL is clear, the fill
gradient changes colors on the vertical axis.
Pt_REVERSE_GRADIENT
If set and Pt_FLAT_FILL is clear, the gradient rendered is reversed
(i.e. begin with the dark fill color on the top or left when the
widget isn’t pressed).
Pt_STATIC_BEVEL_COLORS
If set, the bevel color doesn’t change when you set
Pt_ARG_FILL_COLOR.

Pt_BASIC_PREVENT_FILL
If set, the widget isn’t filled. This is useful when you want to set
the base color for borders and etches without actually rendering a
fill.
Behavior on state change
These bits affect how the widget behaves when set (depressed) or unset (raised):
Pt_STATIC_GRADIENT
If set, the gradient doesn’t reverse when the widget is set or unset.
Pt_STATIC_BEVELS
If set, the rendered bevels don’t change when the widget is set or unset.
Pt_ARG_BEVEL_COLOR
PgColor_t Scalar Pg_LGREY
The main color of the bevel. See PgColor_t in the Photon Library Reference.
This value is automatically generated when you set Pt_ARG_FILL_COLOR. Setting

Pt_ARG_FILL_COLOR overrides any values set previously via this resource.
Pt_ARG_BEVEL_CONTRAST
char Scalar 75
This value determines how much the dark and light bevel colors differ from the base
bevel color (Pt_ARG_BEVEL_COLOR). The higher the value, the greater the
difference:
0 No change.
255 Maximum contrast.
The effect of this resource is visible only if the widget has bevels displayed (see
Pt_ARG_BASIC_FLAGS).
Pt_ARG_COLOR

The widget’s foreground or drawing color. See PgColor_t in the Photon Library
Reference.
Pt_ARG_CONTRAST
char Scalar 20
This value determines how much the dark and light fill colors differ from the base fill
color (Pt_ARG_FILL_COLOR). The higher the value, the greater the difference:
0 No change.
255 Maximum contrast.
The effect of this resource is visible only if the widget is filled with a gradient (see
Pt_ARG_BASIC_FLAGS).
Pt_ARG_DARK_BEVEL_COLOR
PgColor_t Scalar Set internally
This resource, with Pt_ARG_LIGHT_BEVEL_COLOR, specifies the outermost colors

used when applying a bevel to a widget. See Pt_ARG_BASIC_FLAGS to find out
when gradients and borders are rendered for a given widget.
These values are automatically generated when you set Pt_ARG_FILL_COLOR.

Setting Pt_ARG_FILL_COLOR overrides any values set previously via these
resources.
Pt_ARG_DARK_FILL_COLOR
This resource, with Pt_ARG_LIGHT_FILL_COLOR, specifies the colors with which

a gradient (if applied) starts and ends. These values are also used as the inner color for
the bevels (i.e. the bottom bevel normally goes through a transition from
Pt_ARG_DARK_BEVEL_COLOR to Pt_ARG_DARK_FILL_COLOR when a bevel
is applied to the widget). See Pt_ARG_BASIC_FLAGS to find out when gradients and
bevels are rendered for a given widget.


resources.
Pt_ARG_FILL_COLOR
The base fill color for the widget. See PgColor_t in the Photon Library Reference.
This color is used as the base color when generating the Pt_ARG_BEVEL_COLOR,
Pt_ARG_LIGHT_BEVEL_COLOR, Pt_ARG_DARK_BEVEL_COLOR,
Pt_ARG_LIGHT_FILL_COLOR, and Pt_ARG_DARK_FILL_COLOR.
Setting this resource effectively overrides all values previously set for the LIGHT and
DARK resources. This is like setting the chroma for a widget.
If the widget uses a flat fill, that fill is Pt_ARG_FILL_COLOR. If the widget uses a
gradient fill, the gradient runs from Pt_ARG_LIGHT_FILL_COLOR to
Pt_ARG_DARK_FILL_COLOR. If the widget uses a bevel, it’s rendered with color
ranges as defined by Pt_ARG_LIGHT_BEVEL_COLOR to
Pt_ARG_LIGHT_FILL_COLOR and Pt_ARG_DARK_BEVEL_COLOR to
Pt_ARG_DARK_FILL_COLOR.
See Pt_ARG_BASIC_FLAGS to find out when gradients and borders are rendered for
a given widget.
Pt_ARG_FILL_PATTERN
PgPattern_t Struct Pg_PAT_FULL
The widget’s background pattern. You can’t edit this resource in PhAB.
Pt_ARG_HIGHLIGHT_ROUNDNESS
unsigned char Scalar 0
The radius, in pixels, of the widget’s borders. The default value of 0 results in square
corners. If Pt_ARG_HIGHLIGHT_ROUNDNESS is > 0, gradient fill is bypassed.

If you set this resource to a nonzero value, the widget library has to work with a
nonrectangular widget. It might take longer to draw the widget, and you might notice
some flickering. You can reduce the flickering by placing the widget inside a
PtOSContainer.
Pt_ARG_INLINE_COLOR
PgColor_t Scalar Pg_DGRAY
The color of the inline of the border. See PgColor_t in the Photon Library Reference.
The inline is drawn if any of Pt_TOP_INLINE, Pt_BOTTOM_INLINE,
Pt_LEFT_INLINE, and Pt_RIGHT_INLINE are set in Pt_ARG_BASIC_FLAGS.
Pt_ARG_LIGHT_BEVEL_COLOR
This resource, with Pt_ARG_DARK_BEVEL_COLOR, specifies the outermost colors

used when applying a bevel to a widget. See Pt_ARG_BASIC_FLAGS to find out
when gradients and borders are rendered for a given widget.

resources.
Pt_ARG_LIGHT_FILL_COLOR
This resource, with Pt_ARG_DARK_FILL_COLOR, specifies the colors with which a

gradient (if applied) starts and ends. These values are also used as the inner color for
the bevels (i.e. the bottom bevel normally goes through a transition from
Pt_ARG_DARK_BEVEL_COLOR to Pt_ARG_DARK_FILL_COLOR when a bevel
is applied to the widget). See Pt_ARG_BASIC_FLAGS to find out when gradients and
borders are rendered for a given widget.


resources.
Pt_ARG_MARGIN_HEIGHT
The amount of vertical space between the widget’s canvas and the widget’s border.
The canvas is the valid drawing area of the widget and is inside all borders and
margins.
Pt_ARG_MARGIN_WIDTH
The amount of horizontal space between the widget’s canvas and the widget’s border.
The canvas is the valid drawing area of the widget and is inside all borders and
margins.
Pt_ARG_OUTLINE_COLOR
PgColor_t Scalar Pg_WHITE
The color of the outline of the border. See PgColor_t in the Photon Library
Reference.
The outline is drawn if any of Pt_TOP_OUTLINE, Pt_BOTTOM_OUTLINE,
Pt_LEFT_OUTLINE, and Pt_RIGHT_OUTLINE are set in Pt_ARG_BASIC_FLAGS.
Pt_ARG_STYLE
See below Complex
The style to use for this widget instance. This resource is a complex one, so it requires
special handling, as described below.

A style is a collection of override methods that can change how a widget looks and
behaves. Styles can also add widget resources. For more information, see “Widget
Styles” in the Managing Widgets in Application Code chapter of the Photon
When setting this resource, the value is a character string that’s the name of the style.
For example:
PtSetResource( widget, Pt_ARG_STYLE, "MyStyle", 0);
Setting this resource has the same effect as calling PtSetWidgetStyle(). For more
information, see the Photon Library Reference.
When you get the value of this resource, you get a pointer to a
PtWidgetClassStyle_t structure. For example:
PtWidgetClassStyle_t *style = NULL;

.
.
.
PtGetResource( widget, Pt_ARG_STYLE, &style, 0);
Don’t access the members of the PtWidgetClassStyle_t structure directly; call

PtGetStyleMember() instead.
Pt_ARG_TRANS_PATTERN
PgPattern_t Struct Pg_PAT_NONE
The widget’s transparency pattern. You’ll find this handy for “ghosting” widgets. You
can’t edit this resource in PhAB.
Pt_CB_ACTIVATE
PtCallback_t * Link NULL
A list of PtCallback_t structures that define the callbacks that the widget calls
when it becomes activated. To activate a widget, you typically release the left pointer
button while pointing at an armed widget.
Pt_ARG_FLAGS.
PtText, PtMultiText, and PtComboBox have special versions of
Pt_CB_ACTIVATE.
Each callback is passed a PtCallbackInfo_t structure that contains at least the

following members:

reason Pt_CB_ACTIVATE
reason_subtype Pt_CB_HOTKEY if the callbacks were invoked because a hotkey
was pressed; otherwise 0.

caused the callback to be invoked, or NULL if there isn’t an event.
cbdata A pointer to a PtBasicCallback_t structure that contains at

least the following members:
• long int value —
if the Pt_TOGGLE flag in Pt_ARG_FLAGS is set, value
contains either 1 (the widget is pushed in) or 0 (the widget is
pushed out). If Pt_TOGGLE isn’t set, value contains the click
count.
These callbacks should return Pt_CONTINUE.

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).
If you want to process only the last of a series of clicks, use a Pt_CB_RAW callback to
look for a Ph_EV_BUT_RELEASE event with a subtype of
Ph_EV_RELEASE_ENDCLICK. For more information, see PhEvent_t in the Photon
Library Reference.
The Ph_EV_BUT_RELEASE event with a subtype of Ph_EV_RELEASE_ENDCLICK

occurs approximately half a second after the click, which could be annoying to the
user. Most Photon applications don’t use multiple clicks because of this.
Pt_CB_ARM
when it becomes armed. To arm a widget, you typically press the left pointer button
while pointing at the widget.
Pt_ARG_FLAGS.

following members:
reason Pt_CB_ARM

reason_subtype 0 (not used).

cbdata NULL.
Pt_CB_DISARM
when it becomes disarmed. To disarm a widget, you typically release the left pointer
button when not pointing at an armed widget.
Pt_ARG_FLAGS.

following members:
reason Pt_CB_DISARM

cbdata NULL.
Pt_CB_GOT_FOCUS
A list of PtCallback_t structures that define the callbacks invoked when a widget
gets focus or its focus status changes (e.g. a child widget gets focus from its parent or
the focus switches from a child to its parent). You can call PtIsFocused() to find the
current focus state of any widget.
following members:

reason Pt_CB_GOT_FOCUS

caused the callback to be invoked.
cbdata NULL, or a pointer to a PtFocusInfo_t. PtFocusInfo_t

contains at least:
PtWidget_t *src A pointer to the widget which is losing

focus. This pointer could be NULL.
PtWidget_t *dst A pointer to the widget which is intended to
get the focus. This pointer could be NULL,
for example if PtContainerNullFocus() was
invoked.
Returning Pt_END doesn’t make your widget refuse focus; if the widget doesn’t want
focus, it has to give focus to another widget by calling one of the focus functions
described in the Photon Library Reference.
Pt_CB_LOST_FOCUS
when it loses focus.
following members:
reason Pt_CB_LOST_FOCUS


contains at least:

PtWidget_t *dst A pointer to the widget which is intended to
get the focus. This pointer could be NULL,

for example if PtContainerNullFocus() was

invoked.
These 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).
Pt_CB_MENU
when you press the right button while the pointer is on top of the widget.
The widget must have Pt_MENUABLE set and Pt_ALL_BUTTONS cleared in its
Pt_ARG_FLAGS resource. The widget doesn’t need to have Pt_SELECTABLE set in
its Pt_ARG_FLAGS for these callbacks to be invoked.
Pt_CB_MENU is invoked only when the pointer button is pressed, not when the
button is released or held down.

following members:
reason Pt_CB_MENU

cbdata NULL.
Pt_CB_REPEAT
when it receives Ph_EV_BUT_REPEAT events. These events occur when you hold
down the left pointer button (or the right pointer button if the widget has
Pt_ALL_BUTTONS set in its Pt_ARG_FLAGS resource).

Pt_ARG_FLAGS.

following members:
reason Pt_CB_REPEAT

cbdata NULL.

Pt_ARG_BEVEL_WIDTH PtWidget 0
Pt_ARG_DIM PtWidget
Pt_ARG_GRID_LAYOUT_DATA PtWidget
continued. . .


Pt_ARG_LAYOUT_DATA PtWidget
Pt_ARG_POS PtWidget
Pt_ARG_ROW_LAYOUT_DATA PtWidget
Pt_CB_DND PtWidget
Pt_CB_RAW PtWidget

PtBezier © 2010, QNX Software Systems GmbH & Co. KG.
A Bézier curve
Class hierarchy:
PtWidget → PtBasic → PtGraphic → PtBezier
PhAB icon:
Public header:
<photon/PtBezier.h>
Description:
The PtBezier class draws a Bézier curve via PgDrawBezier().
A Bézier curve created by PtBezier.
The Pt_ARG_POINTS resource specifies the points in the Bézier curve. These points
are relative to the widget’s Pt_ARG_ORIGIN. For more information, see PtGraphic.
New resources:

Pt_ARG_BEZIER_FLAGS unsigned short Flag 0
Pt_ARG_BEZIER_FLAGS
unsigned short Flag 0
Flags that affect the appearance of the curve; any combination of:
Pg_CLOSED Connect the last point to the first.

© 2010, QNX Software Systems GmbH & Co. KG. PtBezier
Pg_RELATIVE Use relative coordinates to draw the curve. Each point is relative to
the previous point.

Pt_ARG_BANDWIDTH_THRESHOLD PtBasic Not used by this class.
Pt_ARG_DIM PtWidget
continued. . .

PtBezier © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtBezier

Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

PtBkgd © 2010, QNX Software Systems GmbH & Co. KG.
A color-gradient and image background
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtBkgd
PhAB icon:
Public header:
<photon/PtBkgd.h>
Description:
The PtBkgd widget provides a background of a color gradient with an optional image
on top of it. The image can be tiled across the gradient.
Several different styles of background widgets.
A PtBkgd widget is filled with a color gradient that’s based on the widget’s
Pt_ARG_FILL_COLOR and Pt_ARG_CONTRAST (defined by PtBasic). For
example, the background could start from dark blue at the top and gradually fade to
light blue at the bottom.
On top of this gradient, you can display an image, defined by the
Pt_ARG_BKGD_IMAGE resource. If the image is smaller than the PtBkgd widget,
you can tile the image in various ways by setting Pt_ARG_BKGD_SPACING_X,
Pt_ARG_BKGD_SPACING_Y, and Pt_ARG_BKGD_TILE.

© 2010, QNX Software Systems GmbH & Co. KG. PtBkgd
New resources:

Pt_ARG_BKGD_IMAGE PhImage_t * Image NULL
Pt_ARG_BKGD_SPACING_X short Scalar 0
Pt_ARG_BKGD_SPACING_Y short Scalar 0
Pt_ARG_BKGD_TILE uint8_t Scalar Pt_BKGD_GRID
Pt_ARG_BKGD_IMAGE
PhImage_t * Image NULL
A pointer to a PhImage_t structure that defines the image to be displayed. If it’s

NULL, no image is displayed. For more information, see PhImage_t and
PxLoadImage() in the Photon Library Reference.
Set the flags member of the PhImage_t structure to:
Ph_RELEASE_IMAGE | Ph_RELEASE_PALETTE |
Ph_RELEASE_TRANSPARENCY_MASK | Ph_RELEASE_GHOST_BITMAP
before providing the image to the widget. If you do this, the memory used for the
image is released when the widget is unrealized or destroyed.
When you set this resource, the widget copies the PhImage_t structure but not the
data pointed to by the members of the structure. After setting this resource, you can
free() the PhImage_t if you don’t need it, but don’t free() the members of it.
Pt_ARG_BKGD_SPACING_X
short Scalar 0
The horizontal spacing between tiles, in pixels.
Pt_ARG_BKGD_SPACING_Y
continued. . .

The vertical spacing between tiles, in pixels.
Pt_ARG_BKGD_TILE
uint8_t Scalar Pt_BKGD_GRID
This resource determines the type of tiling used to display the image. Possible values:
Pt_BKGD_CENTER Draw the image once and center it within the container.
Pt_BKGD_CENTER_GRID
Center the image within the container and then, if the image is
smaller than the container, tile the image around the outside.
Pt_BKGD_GRID Repeat the image in grid fashion.
Pt_BKGD_NONE Don’t tile the image; just display it once in the upper left corner.

Pt_ARG_ANCHOR_FLAGS PtWidget Pt_LEFT_ANCHORED_LEFT|
Pt_RIGHT_ANCHORED_LEFT|
Pt_TOP_ANCHORED_TOP|
Pt_BOTTOM_ANCHORED_TOP
continued. . .


Pt_ARG_CONTAINER_FLAGS PtContainer
Pt_ARG_CURSOR_OVERRIDE PtContainer
Pt_ARG_DIM PtWidget
Pt_ARG_FILL_COLOR PtBasic
Pt_ARG_FILL_LAYOUT_INFO PtContainer
Pt_ARG_GRID_LAYOUT_INFO PtContainer
Pt_ARG_LAYOUT_INFO PtContainer
continued. . .


Pt_ARG_POS PtWidget
Pt_ARG_ROW_LAYOUT_INFO PtContainer
Pt_ARG_TITLE PtContainer
Pt_ARG_TITLE_FONT PtContainer
Pt_CB_ARM PtBasic
Pt_CB_BALLOONS PtContainer
Pt_CB_CHILD_ADDED_REMOVED PtContainer
Pt_CB_CHILD_GETTING_FOCUS PtContainer
Pt_CB_CHILD_LOSING_FOCUS PtContainer
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
continued. . .


Pt_CB_RAW PtWidget
Pt_CB_RESIZE PtContainer

PtButton © 2010, QNX Software Systems GmbH & Co. KG.
A button for initiating an action
Class hierarchy:
PtWidget → PtBasic → PtLabel → PtButton
• PtOnOffButton
• PtToggleButton
PhAB icon:
Public header:
<photon/PtButton.h>
Description:
The PtButton class draws a button. Buttons let you initiate an action within your
application; clicking a button invokes an application callback.
A PtButton widget.
Creating pushbuttons
A pushbutton is like a button you might find on a calculator or a control panel. The
label is displayed within the button. The widget itself is shaded to appear like a raised
button. When you click on the button, it becomes “pressed in.”
The label inside the button is usually a text string and/or icon representing the action
that’s performed when the button is pressed. You specify a label for the button in the
same way as for PtLabel widgets.
Pushbutton behavior
A pushbutton is usually associated with a command to be performed — when you
click on the pushbutton, the command is executed. For more information, see
PtBasic.
Visual feedback
A visual cue is displayed when a pushbutton is armed. Usually the pushbutton appears
to be pressed in. The original appearance is restored once the pushbutton has been
disarmed or activated.
You can also configure a pushbutton so that the background of the widget is filled with
a different color to provide more noticeable feedback when the button is armed. Use

© 2010, QNX Software Systems GmbH & Co. KG. PtButton
the Pt_ARG_ARM_COLOR resource to set the fill color for armed pushbuttons. This
resource is ignored if the Pt_ARG_ARM_FILL resource hasn’t been set to Pt_TRUE.
When the pushbutton is displaying an image, you may want the image to change when
the pushbutton is armed. This is useful if you want to change the color of the icon
displayed or change the actual image, such as changing a mail box icon from one with
the flag up to one with the flag down. If you wish to change only the color, you can
use Pt_ARG_ARM_COLOR if the image is a bitmap with backfill turned on. The arm
color is used in place of the widget’s fill color.
To display a different image entirely when the button is armed, use the
Pt_ARG_ARM_IMAGE resource. When the Pt_ARG_LABEL_TYPE resource (see
PtLabel) is set to an image type, this resource is consulted to see if an alternate
image is available for displaying when the pushbutton is armed. If the data points to an
image, that image is displayed when the button is armed.
New resources:

Pt_ARG_ARM_COLOR PgColor_t Scalar PgGray(170)
Pt_ARG_ARM_FILL unsigned char Scalar Pt_FALSE
Pt_ARG_ARM_IMAGE PhImage_t * Image NULL
Pt_ARG_ARM_COLOR
PgColor_t Scalar PgGray(170)
The background color used when the button is armed (pressed in). See PgColor_t in
the Photon Library Reference.
This resource is used only if Pt_ARG_ARM_FILL is set to Pt_TRUE.
Pt_ARG_ARM_FILL
unsigned char Scalar Pt_FALSE
Determines whether or not to use Pt_ARG_ARM_COLOR as the background color

used when the button is armed (pressed in). Possible values:
Pt_TRUE Use the value of Pt_ARG_ARM_COLOR.

Pt_FALSE Ignore the value of Pt_ARG_ARM_COLOR.

Pt_ARG_ARM_IMAGE

A pointer to a PhImage_t structure (see the Photon Library Reference) that defines
the image to use when the button is armed. It’s used only if the label type
(Pt_ARG_LABEL_TYPE — see PtLabel) is Pt_IMAGE or Pt_TEXT_IMAGE.
image is released when the widget is unrealized or destroyed.

Pt_ARG_ACCEL_KEY PtLabel
Pt_ARG_BALLOON_COLOR PtLabel
Pt_ARG_BALLOON_FILL_COLOR PtLabel
Pt_ARG_BALLOON_POSITION PtLabel
Pt_ARG_BALLOON_TEXT PtLabel
Pt_ARG_BASIC_FLAGS PtBasic Pt_ALL_ETCHES | Pt_ALL_BEVELS |
Pt_ALL_OUTLINES | Pt_STATIC_GRADIENT
continued. . .


Pt_ARG_DIM PtWidget
Pt_ARG_FILL_COLOR PtBasic Pg_LGREY
Pt_ARG_FLAGS PtWidget |=Pt_SELECTABLE|
Pt_HIGHLIGHTED
Pt_ARG_HORIZONTAL_ALIGNMENT PtLabel Pt_CENTER
Pt_ARG_LABEL_BALLOON PtLabel
Pt_ARG_LABEL_FLAGS PtLabel
Pt_ARG_LABEL_IMAGE PtLabel
Pt_ARG_LABEL_TYPE PtLabel
continued. . .


Pt_ARG_LINE_SPACING PtLabel
Pt_ARG_MARGIN_BOTTOM PtLabel
Pt_ARG_MARGIN_LEFT PtLabel
Pt_ARG_MARGIN_RIGHT PtLabel
Pt_ARG_MARGIN_TOP PtLabel
Pt_ARG_POS PtWidget
Pt_ARG_SECONDARY_H_ALIGN PtLabel
Pt_ARG_SECONDARY_V_ALIGN PtLabel
Pt_ARG_TEXT_FONT PtLabel
Pt_ARG_TEXT_IMAGE_SPACING PtLabel
Pt_ARG_TEXT_STRING PtLabel
Pt_ARG_UNDERLINE_TYPE PtLabel
Pt_ARG_UNDERLINE1 PtLabel
Pt_ARG_VERTICAL_ALIGNMENT PtLabel Pt_CENTER
continued. . .


Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

PtCalendar © 2010, QNX Software Systems GmbH & Co. KG.
A calendar
Class hierarchy:
PtWidget → PtBasic → PtCalendar
PhAB icon:
Public header:
<photon/PtCalendar.h>
Description:
PtCalendar draws a calendar showing the day of the week, month and year. You can
interactively change the date and browse other months and years. The calendar is
drawn on a per-month basis and can be drawn with or without a grid.
A PtCalendar widget.
New resources:

Pt_ARG_CALENDAR_COLOR1 PgColor_t Scalar Pg_BLACK
Pt_ARG_CALENDAR_COLOR2 PgColor_t Scalar Pg_DGREY
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtCalendar

Pt_ARG_CALENDAR_COLOR5 PgColor_t Scalar Pg_BLUE
Pt_ARG_CALENDAR_DATE PtCalendarDate_t Struct Current date
Pt_ARG_CALENDAR_FLAGS unsigned long Flag See below.
Pt_ARG_CALENDAR_FONT1 char * String "TextFont09"
Pt_ARG_CALENDAR_FONT2 char * String "TextFont09i"
Pt_ARG_CALENDAR_FONT3 char * String "TextFont09"
Pt_ARG_CALENDAR_FONT4 char * String "TextFont09b"
Pt_ARG_CALENDAR_FONT5 char * String "TextFont09b"
Pt_ARG_CALENDAR_HIGHLIGHT unsigned long Flag 0
Pt_ARG_CALENDAR_MONTH_BTN_COLOR PgColor_t Scalar Pg_GREY
Pt_ARG_CALENDAR_MONTH_NAMES char *, short Array See below.
Pt_ARG_CALENDAR_SEL_COLOR PgColor_t Scalar Pg_YELLOW
Pt_ARG_CALENDAR_TIME_T time_t Scalar Current date
Pt_ARG_CALENDAR_WDAY_NAMES char *, short Array See below.
Pt_ARG_CALENDAR_YEAR_BTN_COLOR PgColor_t Scalar Pg_GREY
Pt_CB_CALENDAR_SELECT PtCallback_t * Link NULL
Pt_ARG_CALENDAR_COLOR1
PgColor_t Scalar Pg_BLACK
The color used to display the current month’s days. See PgColor_t in the Photon
Library Reference.
PgColor_t Scalar Pg_DGREY
The color used to display the next and previous month’s days. See PgColor_t in the
Photon Library Reference.


The color used for the year and month name. See PgColor_t in the Photon Library
Reference.
The color used for any highlighted days in the calendar (see
Pt_ARG_CALENDAR_HIGHLIGHT).
PgColor_t Scalar Pg_BLUE
The color used for the names of the days of the week (see
Pt_ARG_CALENDAR_WDAY_NAMES). See PgColor_t in the Photon Library
Reference.
Pt_ARG_CALENDAR_DATE
PtCalendarDate_t Struct Current date
The current date shown on the calendar.
You might find it easier to use Pt_ARG_CALENDAR_TIME_T instead of

Pt_ARG_CALENDAR_DATE. They both specify the date, but
Pt_ARG_CALENDAR_DATE uses a custom data structure.
You can’t set either of these resources in PhAB.
This date is stored in a PtCalendarDate_t structure that contains:
• year — the current year starting from 0000.
• month — the current month [0-11]; 0 is January.
• day — the current day of the month [0-30].

Pt_ARG_CALENDAR_FLAGS

unsigned long Flag Pt_CALENDAR_YEAR_BTNS |
Pt_CALENDAR_MONTH_BTNS |
Pt_CALENDAR_SHOW_PREV |
Pt_CALENDAR_SHOW_NEXT |
Pt_CALENDAR_SHOW_GRID
Calendar-specific flags. This can be a combination of:
Pt_CALENDAR_YEAR_BTNS
Show the next/previous year buttons.
Pt_CALENDAR_MONTH_BTNS
Show the next/previous month buttons.
Pt_CALENDAR_SHOW_PREV
Show the last few days of the previous month.
Pt_CALENDAR_SHOW_NEXT
Show the first few days of the following month.
Pt_CALENDAR_SHOW_GRID
Show the calendar in a grid format with lines separating the days.
Pt_ARG_CALENDAR_FONT1
char * String "TextFont09"
The font used for the current month’s days.
char * String "TextFont09i"
The font used for the next and previous month’s days.


The font used for the year and month name.
char * String "TextFont09b"
The font used for any highlighted days in the calendar (see
Pt_ARG_CALENDAR_HIGHLIGHT).
The font used for the names of the days of the week (see
Pt_ARG_CALENDAR_WDAY_NAMES).
Pt_ARG_CALENDAR_HIGHLIGHT
unsigned long Flag 0
A set of up to 32 bits that specify the days of the current month to highlight. For
example, 0x1 means that day 1 is highlighted and 0x3 means that days 1 and 2 are
highlighted.
The highlighted days are displayed using the values of
Pt_ARG_CALENDAR_COLOR4 and Pt_ARG_CALENDAR_FONT4.
You can’t edit Pt_ARG_CALENDAR_HIGHLIGHT in PhAB.
Pt_ARG_CALENDAR_MONTH_BTN_COLOR
PgColor_t Scalar Pg_GREY

The color used for the buttons for moving to the next and previous months. See
PgColor_t in the Photon Library Reference.
Pt_ARG_CALENDAR_MONTH_NAMES
char *, short Array See below
An array of names to be used for the months of the year. By default these values are:
Element Value
0 January
1 February
2 March
3 April
4 May
5 June
6 July
7 August
8 September
9 October
10 November
11 December
The array should contain 12 elements. If you set more, the extras are discarded. If you
set fewer, the above elements are used for the missing ones.
You can’t edit Pt_ARG_CALENDAR_MONTH_NAMES in PhAB.
Pt_ARG_CALENDAR_SEL_COLOR
PgColor_t Scalar Pg_YELLOW
The color of the currently selected day of the month. See PgColor_t in the Photon
Library Reference.

Pt_ARG_CALENDAR_TIME_T

time_t Scalar Current date
The current date shown on the calendar. This date is stored in a time_t structure.
You can’t edit Pt_ARG_CALENDAR_TIME_T in PhAB.
Pt_ARG_CALENDAR_WDAY_NAMES
char *, short Array See below.
An array of names to be used for the days of the week. By default these values are:
Element Value
0 Su
1 Mo
2 Tu
3 We
4 Th
5 Fr
6 Sa
The array should contain 7 elements. If you set more, the extras are discarded. If you
set fewer, the above elements are used for the missing ones.
You can’t edit Pt_ARG_CALENDAR_WDAY_NAMES in PhAB.
Pt_ARG_CALENDAR_YEAR_BTN_COLOR
PgColor_t Scalar Pg_GREY
The color used for the buttons for moving to next and previous years. See PgColor_t
in the Photon Library Reference.

Pt_CB_CALENDAR_SELECT

A list of PtCallback_t structures that define the callbacks invoked when a date is
selected. Each callback is passed a PtCallbackInfo_t structure that contains at
reason Pt_CB_CALENDAR_SELECT

cbdata A pointer to a PtCalendarSelectCallback_t structure.
The PtCalendarSelectCallback_t structure contains at least:
int type The type of selection made:

• Pt_CALENDAR_DATE_SELECTED
• Pt_CALENDAR_WDAY_SELECTED
• Pt_CALENDAR_MONTH_SELECTED
• Pt_CALENDAR_YEAR_SELECTED
PtCalendarDate_t date
The selected date. This structure contains at least:
• signed char day — values in the range 0 through 30.
• signed char month — values in the range 0 through 11.
• signed short year — values in the range -32767 through
+32767.
time_t time The selected date, represented as a time_t.


Pt_ARG_DIM PtWidget
continued. . .


Pt_ARG_MARGIN_HEIGHT PtBasic 2
Pt_ARG_MARGIN_WIDTH PtBasic 2
Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
continued. . .



© 2010, QNX Software Systems GmbH & Co. KG. PtClient
Client widget
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtClient
• PtWebClient
PhAB icon:
None — not normally instantiated.
Public header:
<photon/PtClient.h>
Description:
PtClient and PtServer let one process (the “server”) display widgets in a window
that belongs to another process (the “client”).
PtClient and PtServer use a Photon connection to communicate (see
“Connections” in the Interprocess Communications chapter of the Photon
Programmer’s Guide), but they have a few resources that in most cases let applications
avoid dealing with connection objects directly.
A PtClient widget creates a parent region for a PtServer widget and handles the
process of connecting to a PtServer. Then, the client controls the server’s size and
notifies it of certain events in order to make the server look and feel as if it were just
another container in the client’s window. Additionally, PtClient lets your
application send arbitrary messages to the server process.
New resources:

Pt_ARG_CLIENT_FLAGS unsigned Flags 0
Pt_ARG_CLIENT_NAME char * String NULL
Pt_ARG_CLIENT_REPLY_LEN unsigned Scalar 0
Pt_ARG_CLIENT_SEND char, unsigned Array NULL, 0
Pt_ARG_CLIENT_SERVER PtConnectionClient_t * Pointer NULL
Pt_CB_CLIENT_CONNECTED PtCallback_t * Link NULL
Pt_CB_CLIENT_ERROR PtCallback_t * Link NULL
continued. . .

PtClient © 2010, QNX Software Systems GmbH & Co. KG.

Pt_CB_CLIENT_EVENT PtCallback_t * Link NULL
Pt_CB_CLIENT_NOT_FOUND PtCallback_t * Link NULL
Pt_ARG_CLIENT_FLAGS
unsigned Flags 0
Flags that control the behavior of the widget:
Pt_CLIENT_NOEVENTS
Setting this flag tells the widget that the server doesn’t use the
Pt_ARG_SERVER_SEND resource.
Pt_CLIENT_NONBLOCK
If this flag is clear, the call to PtSetResources() that sets
Pt_ARG_CLIENT_NAME doesn’t return until the connecting has either
succeeded or been aborted.
If the flag is set, setting the Pt_ARG_CLIENT_NAME is nonblocking, and the
connecting is performed in background, after PtSetResources() has returned.
Pt_ARG_CLIENT_NAME
char * String NULL
The connector name to which to connect. Setting this resource initiates the process of
connecting to a server.
If the connection isn’t successful, the widget’s Pt_CB_CLIENT_NOT_FOUND
callbacks are invoked.
Pt_ARG_CLIENT_REPLY_LEN
unsigned Scalar 0
The maximum length of a reply from the server, in bytes. See

Pt_ARG_CLIENT_SEND.

Pt_ARG_CLIENT_SEND

char, unsigned Array NULL, 0
When you set this resource, the widget sends a message to its PtServer. The
message invokes a Pt_CB_SERVER_RECEIVE callback in the server that lets the
server specify a reply. The reply is then available in the client by getting the
Pt_ARG_CLIENT_SEND resource (the length gives you the actual length of the reply,
not the size of the buffer).
Pt_ARG_CLIENT_SERVER (read only)

PtConnectionClient_t * Pointer NULL
A pointer to the connection object used for communicating to the PtServer. Don’t
use this pointer for anything other than checking to see if it’s NULL.
Pt_CB_CLIENT_CONNECTED
A list of PtCallback_t structures that define the callbacks that are invoked when the
client connects to the server. Each callback is passed a PtCallbackInfo_t structure
that contains at least the following members:
reason Pt_CB_CLIENT_CONNECTED
event NULL.
cbdata NULL.
Pt_CB_CLIENT_ERROR

A list of PtCallback_t structures that define the callbacks that are invoked when an
error occurs.
following members:
reason Pt_CB_CLIENT_ERROR

cbdata A pointer to a PtClientErrorCallback_t structure that

contains at least:
• int action — the value that the connection client’s error
handler will return. It’s initialized to Pt_END. Set it to
Pt_CONTINUE to retry the failed operation.
Not all operations are retried if an error handler returns Pt_CONTINUE. For example, a
MsgReply() is never retried.
• int errnum — the errno value from the error handler.

• int where — the value (of type enum
PtConnectionClientError) that describes what operation
failed.
If this value is Pt_CONNECTION_CLIENT_BROKEN, the widget disconnected from

the server and its Pt_ARG_CLIENT_NAME resource has been reset to NULL.
Pt_CB_CLIENT_EVENT
A list of PtCallback_t structures that define the callbacks that are invoked for each
message sent by the server’s Pt_ARG_SERVER_SEND resource.
following members:
reason Pt_CB_CLIENT_EVENT


cbdata A pointer to a PtClientCallback_t structure that contains at

least:
• void const *message — a pointer to the message.
• unsigned nbytes — its length.
Pt_CB_CLIENT_NOT_FOUND
A list of PtCallback_t structures that define the callbacks that are invoked if the
widget fails to find the server specified when you set Pt_ARG_CLIENT_NAME.
following members:
reason Pt_CB_CLIENT_NOT_FOUND
event NULL.
cbdata A pointer to an int initialized to Pt_END. Set it to Pt_CONTINUE

if you want the widget to retry after a little while. Typically, the
first Pt_CB_CLIENT_NOT_FOUND callback spawns the server,
and any subsequent Pt_CB_CLIENT_NOT_FOUND callback
checks whether or not the server is still running, and abort the
connecting if the server has terminated.

continued. . .


Pt_ARG_DIM PtWidget
continued. . .


Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
continued. . .


Pt_CB_RAW PtWidget

© 2010, QNX Software Systems GmbH & Co. KG. PtClock
An analog, digital, or LED clock
Class hierarchy:
PtWidget → PtBasic → PtClock
PhAB icon:
Public header:
<photon/PtClock.h>
Description:
A PtClock draws a clock and can optionally update its display periodically (about
once a second) to reflect the current time.
Analog, digital, and LED clocks created by PtClock.
PtClock follows the system time, but don’t rely on it to be accurate all the time.
The widget may flicker excessively, particularly if you use a transparent fill color. To
reduce flicker, use a nontransparent fill color or disable the display of seconds.
Alternatively, you can place the clock in a PtOSContainer, but you must use a
transparent fill for the clock, or it won’t be refreshed properly.
New resources:

Pt_ARG_CLOCK_FACE_COLOR PgColor_t Scalar Pg_WHITE
Pt_ARG_CLOCK_FACE_OUTLINE_COLOR PgColor_t Scalar Pg_BLACK
Pt_ARG_CLOCK_FLAGS long Flag See below.
Pt_ARG_CLOCK_FONT char * String "TextFont09"
continued. . .

PtClock © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_CLOCK_HOUR short Scalar Pt_CLOCK_CURRENT
Pt_ARG_CLOCK_HOUR_COLOR PgColor_t Scalar Pg_BLACK

Pt_ARG_CLOCK_HOUR_OFFSET short Scalar 0
Pt_ARG_CLOCK_MINUTE short Scalar Pt_CLOCK_CURRENT
Pt_ARG_CLOCK_MINUTE_COLOR PgColor_t Scalar Pg_BLACK

Pt_ARG_CLOCK_MINUTE_OFFSET short Scalar 0
Pt_ARG_CLOCK_SECOND short Scalar Pt_CLOCK_CURRENT
Pt_ARG_CLOCK_SECOND_COLOR PgColor_t Scalar Pg_RED

Pt_ARG_CLOCK_SECOND_OFFSET short Scalar 0
Pt_ARG_CLOCK_SEP1 char * String ":"
Pt_ARG_CLOCK_SEP1_COLOR PgColor_t Scalar Pg_BLACK
Pt_ARG_CLOCK_SEP2 char * String ":"
Pt_ARG_CLOCK_SEP2_COLOR PgColor_t Scalar Pg_BLACK
Pt_ARG_CLOCK_TYPE short Scalar Pt_CLOCK_ANALOG
Pt_CB_CLOCK_TIME_CHANGED PtCallback_t * Link NULL
Pt_ARG_CLOCK_FACE_COLOR
The fill color of the clock’s face (applicable only for analog clocks). See PgColor_t
in the Photon Library Reference.
Pt_ARG_CLOCK_FACE_OUTLINE_COLOR
The color of the line drawn around the clock face (applicable only for analog clocks).
See PgColor_t in the Photon Library Reference.
Pt_ARG_CLOCK_FLAGS

Defines the clock’s behavior. Possible values are:
Pt_CLOCK_24_HOUR
Use a 24-hour display rather than conventional 12-hour format. This flag
overrides Pt_CLOCK_SHOW_AMPM.
Pt_CLOCK_PAD_HOURS
Pad the hour field with a leading zero such that there are always 2 digits in the
hours field (applicable only for digital or LED clocks).
Pt_CLOCK_SHOW_AMPM
Display an AM/PM indicator. For digital clocks, this is rendered as an AM or PM
suffix. For LED clocks, this is rendered as a dot in the upper right corner (AM)
or lower right corner (PM) of the display. This flag has no effect on analog
clocks, and is overridden by the Pt_CLOCK_24_HOUR flag.
Pt_CLOCK_SHOW_NUMBERS
Display numbers on the face (applicable only for analog clocks).
Pt_CLOCK_SHOW_SECONDS
Display the seconds component of the time.
Pt_CLOCK_TRACK_TIME
Update the clock every second to reflect the current time. If this flag isn’t set, the
clock holds its current setting until it’s changed programmatically or the flag is
reenabled.
Pt_ARG_CLOCK_FONT
The font to use. For analog clocks, this applies to the numbers on the face (if
displayed). For digital clocks, this applies to the entire display.
Pt_ARG_CLOCK_HOUR
short Scalar Pt_CLOCK_CURRENT
The current hour setting for the clock (reflecting the current system clock setting if
Pt_CLOCK_TRACK_TIME is set). This value is in 24-hour format.
If you set this resource to Pt_CLOCK_CURRENT, the clock is set to the current system
time.

Pt_ARG_CLOCK_HOUR_COLOR

The color to use when drawing the hours component. See PgColor_t in the Photon
Library Reference.
Pt_ARG_CLOCK_HOUR_OFFSET
short Scalar 0
Offset the clock setting by this amount when displaying the hours field.
Pt_ARG_CLOCK_MINUTE
short Scalar Pt_CLOCK_CURRENT
The current minute setting for the clock (reflecting the current system clock setting if
Pt_CLOCK_TRACK_TIME is set). If you set this resource to Pt_CLOCK_CURRENT,
the clock is set to the current system time.
Pt_ARG_CLOCK_MINUTE_COLOR
The color to use when drawing the minutes component. See PgColor_t in the Photon
Library Reference.
Pt_ARG_CLOCK_MINUTE_OFFSET
short Scalar 0
Offset the clock setting by this amount when displaying the minutes field.
Pt_ARG_CLOCK_SECOND

The current second setting for the clock (reflecting the current system clock setting if
Pt_CLOCK_TRACK_TIME is set). If you set this resource to Pt_CLOCK_CURRENT,
the clock is set to the current system time.
Pt_ARG_CLOCK_SECOND_COLOR
PgColor_t Scalar Pg_RED
The color to use when drawing the seconds component. See PgColor_t in the Photon
Library Reference.
Pt_ARG_CLOCK_SECOND_OFFSET
short Scalar 0
Offset the clock setting by this amount when displaying the seconds field.
Pt_ARG_CLOCK_SEP1
char * String ":"
The separator to use between the hours and minutes field (applicable only for digital
clocks; LED clocks always use a colon). Only the first character of the string is used.
Pt_ARG_CLOCK_SEP1_COLOR
The color to use when drawing the separator character between hours and minutes.
Pt_ARG_CLOCK_SEP2
char * String ":"
The separator to use between the minutes and seconds field (applicable only for digital
clocks with Pt_CLOCK_SHOW_SECONDS set; LED clocks always use a colon). Only
the first character of the string is used.

Pt_ARG_CLOCK_SEP2_COLOR

The color to use when drawing the separator character between minutes and seconds.
Pt_ARG_CLOCK_TYPE
short Scalar Pt_CLOCK_ANALOG
The clock type:
Pt_CLOCK_DIGITAL
A numeric display (using system fonts).
Pt_CLOCK_LED A scalable display that resembles conventional LED/LCD

digital clocks.
Pt_CLOCK_ANALOG
An analog clock with hands.
Pt_CB_CLOCK_TIME_CHANGED
A list of PtCallback_t structures that define the callbacks invoked when the time on
the clock changes. This occurs once a second if Pt_CLOCK_SHOW_SECONDS is set,
otherwise once every minute when the minute changes.
If the widget has the Pt_CALLBACKS_ACTIVE bit set in its Pt_ARG_FLAGS
resource, these callbacks are also invoked when your application changes the time by
calling PtSetResource() or PtSetResources().
following members:
reason Pt_CB_CLOCK_TIME_CHANGED
reason_subtype Why this callback was invoked. This value is a flag that may
contain any of the following (ORed together):
• Pt_CLOCK_HOUR_CHANGED

• Pt_CLOCK_MINUTE_CHANGED
• Pt_CLOCK_SECOND_CHANGED

caused the callback to be invoked. If event is NULL, the callback
was invoked because your application changed the time setting
by calling PtSetResources().
cbdata A pointer to a PtClockTimeCallback_t structure that

contains at least:
• short hour — The new hour displayed on the clock (in
24-hour format). Note that this includes the hour offset, if any.
• short minute — The new minute displayed on the clock.
• short second — The new second displayed on the clock.
• short old_hour — The previous hour displayed on the clock
before the change was made (in 24-hour format). Note that
this includes the hour offset, if any.
• short old_minute — The previous minute displayed on the
clock before the change was made.
• short old_second — The previous second displayed on the
clock before the change was made.

continued. . .


Pt_ARG_DIM PtWidget
Pt_ARG_POS PtWidget
continued. . .


Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

PtColorPanel © 2010, QNX Software Systems GmbH & Co. KG.
A color panel
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtCompound → PtColorSel →
PtColorPanel
PhAB icon:
Public header:
<photon/PtColorPanel.h>
Description:
A composite color selector that provides color selection via a combination of the
following optional mechanisms:
• A PtColorWell widget
• textual entry fields that let you type values for the individual channels.
• A “dropper” button that lets you pick a color from anywhere on the screen by
clicking on it (press Esc to abort the operation).
A PtColorPanel widget.
New resources:

Pt_ARG_CPANEL_FLAGS uint16_t Flag Pt_CPANEL_SHOW_FIELDS |
Pt_CPANEL_SHOW_WELL |
Pt_CPANEL_SHOW_DROPPER
Pt_ARG_CPANEL_FLAGS

© 2010, QNX Software Systems GmbH & Co. KG. PtColorPanel
Flags that affect the appearance and behavior of the color panel. Bits include:
Pt_CPANEL_SHOW_DROPPER
Display the dropper button.
Pt_CPANEL_SHOW_FIELDS
Display the textual entry fields.
Pt_CPANEL_SHOW_WELL
Display the color well.

Pt_ARG_CS_COLOR PtColorSel
Pt_ARG_CS_COLOR_MODELS PtColorSel
Pt_ARG_CS_CURRENT_MODEL PtColorSel
Pt_ARG_CS_FLAGS PtColorSel
continued. . .

PtColorPanel © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_CS_PALETTE PtColorSel
Pt_ARG_DIM PtWidget
Pt_ARG_POS PtWidget
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtColorPanel

Pt_CB_ARM PtBasic
Pt_CB_CS_COLOR_CHANGED PtColorSel
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

PtColorPatch © 2010, QNX Software Systems GmbH & Co. KG.
A widget for selecting a hue and shading or tint
Class hierarchy:
PtColorPatch
PhAB icon:
Public header:
<photon/PtColorPatch.h>
Description:
A PtColorPatch is a widget that you can use to select a color from a three
dimensional color space by means of a 2-dimensional color spectrum and a slider.
A PtColorPatch widget.
The widget includes:
• An optional combo box used to select the color space (HSB, and so on). It’s
displayed if Pt_CPATCH_SHOW_SELECTOR is set in Pt_ARG_CPATCH_FLAGS.
• An optional slider on the left controls one of the variables of the three-dimensional
color space. It’s displayed if Pt_CPATCH_SHOW_SLIDER is set in
Pt_ARG_CPATCH_FLAGS.
• An area displaying a “plane of color” defined by the remaining two variables in the
three-dimensional color space. You can use the pointer to select a color from this
plane.
New resources:

© 2010, QNX Software Systems GmbH & Co. KG. PtColorPatch
Pt_ARG_CPATCH_FLAGS
unsigned short Flag Pt_CPATCH_SHOW_SELECTOR |
Pt_CPATCH_SHOW_SLIDER |
Pt_CPATCH_ENABLE_MENU
Flags that affect the appearance and behavior of the color patch. Bits include:
Pt_CPATCH_SHOW_SELECTOR
Show a PtComboBox selector that lets you select the color models that are
supported by the color patch (see the Pt_ARG_CS_COLOR_MODELS resource
defined by PtColorSel).
Pt_CPATCH_SHOW_SLIDER
Show a slider on the left that lets you change the channel not shown in the
spectrum. Clear this bit if you want that channel to remain fixed (your
application will need to set it programmatically).
Pt_CPATCH_ENABLE_MENU
Enable a popup menu that lets you change the patch’s configuration. orientation
of the palette, and so on.

continued. . .


Pt_ARG_DIM PtWidget
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtColorPatch

Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
continued. . .


Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

© 2010, QNX Software Systems GmbH & Co. KG. PtColorSel
Superclass for color-selector widgets
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtCompound → PtColorSel
• PtColorPanel
• PtColorPatch
• PtColorSelGroup
• PtColorWell
PhAB icon:
Public header:
<photon/PtColorSel.h>
Description:
PtColorSel is a superclass for all color-selection widgets. It defines a common
interface to widgets that let you select colors. To maintain consistency, any widget that
implements color selection should be a descendant of PtColorSel.
New resources:

Pt_ARG_CS_COLOR PgColor_t Scalar Pg_BLACK
Pt_ARG_CS_COLOR_MODELS PgColorModel_t *, short Array {Pg_CM_RGB}
Pt_ARG_CS_CURRENT_MODEL uint8_t Scalar 0
Pt_ARG_CS_FLAGS uint16_t Flags 0
Pt_ARG_CS_PALETTE PgPalette_t * Alloc NULL
Pt_CB_CS_COLOR_CHANGED PtCallback_t * Link NULL
Pt_ARG_CS_COLOR
The currently selected color. See PgColor_t in the Photon Library Reference.

PtColorSel © 2010, QNX Software Systems GmbH & Co. KG.
Pt_ARG_CS_COLOR_MODELS

PgColorModel_t *, short Array {Pg_CM_RGB}
A list of color models that this color selector supports. When you set a color using a
color model that the selector doesn’t support, the actual color can still be calculated;
ensuring that the color model is supported can reduce roundoff errors if the color
doesn’t cleanly map between RGB and the color model in question.
In addition, this resource is useful for widgets that let you choose from the different
color models that the widget supports.
The following color models are defined:
Pg_CM_RGB Red-green-blue.
Pg_CM_HSB Hue-saturation-brightness.
Pg_CM_HLS Hue-lightness-saturation. A modified HSB model that’s more

intuitive for selecting colors in a GUI.
Pg_CM_CMYK Cyan-magenta-yellow-black.
Here’s an example of how to set this resource:
PgColorModel_t const *models[]={Pg_CM_RGB, Pg_CM_CMYK,

Pg_CM_HSB};
PtSetResource( my_widget, Pt_ARG_CS_COLOR_MODELS,

models, 3 );
Pt_ARG_CS_CURRENT_MODEL
uint8_t Scalar 0
An index to the currently active model into the array of color models that this widget
supports. Indexes start at 0.
Pt_ARG_CS_FLAGS
uint16_t Flags 0
Flags that control the widget’s behavior:

Pt_CS_FAST_UPDATE
If the selector is undergoing a high-bandwidth change, do any rendering (if
applicable) in a “fast” manner. This is a meta-flag that doesn’t actually affect the
behavior of PtColorSel itself, but may be observed by subclasses
(PtColorPatch uses it to render the two-dimensional patch).
Pt_CS_QUANTIZE_COLOR
Ensure Pt_ARG_CS_COLOR is always mapped (quantized) to the nearest
match in the palette if a palette is set. The PtColorSel widget always does this
matching, so subclasses don’t need to implement it.
Pt_ARG_CS_PALETTE
PgPalette_t * Alloc NULL
The color palette supported by this PtColorSel. A palette serves these main
purposes:
• It supplies the needed palette information for a palette-oriented color selector.
• It imposes a discrete set of colors within a continuous range that this selector must
conform to.
Pt_CB_CS_COLOR_CHANGED
selected color changes.
following members:
reason Pt_CB_CS_COLOR_CHANGED
reason_subtype A combination of the following:

• Pt_CS_COLOR_CHANGED — a low-bandwidth change (e.g.
click, set). If this bit isn’t set, assume that a high-bandwidth
change is in progress, and there might be many subsequent
callbacks in a very short time.
• Pt_CS_COLOR_CHANGE_COMPLETE — a widget-specific
inference that the selection is “complete.” For example, this bit
is useful if the color selector appears in a popup pane that you
wish to dismiss automatically when the change is complete.


cbdata A pointer to a PtColorSelCallback_t structure that contains

at least these members:
• PgColor_t rgb — the selected color, in RGB format. See
• PgColorChannel_t const *channels — the constituent
channel values for the selected color. You should interpret
these values based on the color_model.
• PgColorModel_t const *color_model — the color model,
which you should to interpret the values stored in the channels.
If this is NULL, the channels should be disregarded.

continued. . .


Pt_ARG_DIM PtWidget
Pt_ARG_POS PtWidget
continued. . .


Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

© 2010, QNX Software Systems GmbH & Co. KG. PtColorSelGroup
A group of color selectors
Class hierarchy:
PtColorSelGroup
PhAB icon:
Public header:
<photon/PtColorSelGroup.h>
Description:
A PtColorSelGroup is a composite color selector that, by default, provides a
PtColorPanel for selecting colors and lets you add other color selectors to it to
augment its functionality.
A PtColorSelGroup widget.
PtColorSelGroup ensures that all its children are synchronized whenever one of
their values is changed.
New resources:

Pt_ARG_CSGROUP_FLAGS uint16_t Flag 0
Pt_ARG_CSGROUP_FLAGS
uint16_t Flag 0
Flags that affect the appearance and behavior of the color-selector group. Bits include:
Pt_CSGROUP_ALL_AT_ONCE
Display all of the children color selectors at once, rather than showing one at a
time.

PtColorSelGroup © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_DIM PtWidget
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtColorSelGroup

Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
continued. . .

PtColorSelGroup © 2010, QNX Software Systems GmbH & Co. KG.

Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

© 2010, QNX Software Systems GmbH & Co. KG. PtColorWell
A rectangle that displays a color and lets you change it
Class hierarchy:
PtColorWell
PhAB icon:
Public header:
<photon/PtColorWell.h>
Description:
A PtColorWell is a rectangular area that displays a color. When you click on it, a
PtColorPatch pops up to let you select a color to be displayed in the color well.
A PtColorWell widget.
New resources:

Pt_ARG_CWELL_FLAGS uint16_t Flag Pt_CWELL_POPUP_ON_SELECT |
Pt_CWELL_POPUP_ON_MENU
Pt_ARG_CWELL_SWATCH_DIM PhDim_t Struct {220, 120}
Pt_ARG_CWELL_FLAGS

PtColorWell © 2010, QNX Software Systems GmbH & Co. KG.
Flags that affect the appearance and behavior of the color well. You can set this
resource to any combination of these bits:
Pt_CWELL_POPUP_ON_SELECT
Pop up the color patch when you click on the well using the select (usually left)
button.
Pt_CWELL_POPUP_ON_MENU
Pop up the color patch when you click on the well using the menu (usually right)
button.
Pt_ARG_CWELL_SWATCH_DIM
PhDim_t Struct {220, 120}
A PhDim_t structure (see the Photon Library Reference) that defines the dimensions
of the popup color patch, in pixels.

continued. . .


Pt_ARG_DIM PtWidget
continued. . .

PtColorWell © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
continued. . .



PtComboBox © 2010, QNX Software Systems GmbH & Co. KG.
A text field with a list of choices
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtCompound → PtComboBox
PhAB icon:
Public header:
<photon/PtComboBox.h>
Description:
The PtComboBox class provides a widget that’s built from two exported subordinate
widgets: PtList and PtText.
A PtComboBox widget provides a text-entry area and a list of choices.
You can type in the text field or choose a predefined entry from the list. The list can be
either:
Static Always present above or below the text field.
Dropping You must click a button to see the list.
The widget behaves like a PtList or PtText widget, depending on which part has
focus.
You can’t specify the selection mode for the list; Pt_ARG_SELECTION_MODE is
blocked. The list always uses Pt_BROWSE_MODE.
To select an item using the pointer, either click on an item or drag the pointer down the
list and release the button when the correct item is highlighted. You can select only
one item. If you drag the pointer, the list can scroll.

© 2010, QNX Software Systems GmbH & Co. KG. PtComboBox
A blocking mechanism lets PtComboBox block the inheritance of certain resources

from its subordinate widgets. This prevents any actions that would negatively affect
the look and behavior of a PtComboBox widget. For more information, see the
“Exported subordinate children” section.
Keyboard actions
The keyboard actions depend on which part of the PtComboBox has focus. If the text
widget has focus, the keyboard actions are:
Key Action
↑ Set the text to the previous item in the list
↓ Set the text to the next item in the list
Alt-↓ Display the list, highlighting the item corresponding to the current text
The Alt-↓ action occurs only if Pt_COMBOBOX_ALT_DOWN is set in the widget’s

Pt_ARG_CBOX_FLAGS.
If the list has focus, the keyboard actions are:
Key Action
Enter Select the current item (see “Current item” in the description of
PtGenList)
↑ Move to the previous item
↓ Move to the next item
Pg Up Move to the previous page
Pg Dn Move to the next page
Home Move to the first item
End Move to the last item
Callbacks
The following callbacks are associated with the text part of the PtComboBox and are
invoked as described for PtText:
• Pt_CB_ACTIVATE
• Pt_CB_MODIFY_NOTIFY or Pt_CB_TEXT_CHANGED
• Pt_CB_MODIFY_VERIFY
• Pt_CB_MOTION_NOTIFY

• Pt_CB_MOTION_VERIFY
The following callbacks are associated with the list part of the PtComboBox and are
invoked as described for PtList:
• Pt_CB_LIST_INPUT
• Pt_CB_SELECTION
PtComboBox also defines the following callbacks for the list:
• Pt_CB_CBOX_ACTIVATE
• Pt_CB_CBOX_CLOSE
New resources:

Pt_ARG_CBOX_BUTTON_WIDTH unsigned short Scalar 13
Pt_ARG_CBOX_FLAGS unsigned long Flag 0
Pt_ARG_CBOX_MAX_VISIBLE_COUNT unsigned short Scalar 0
Pt_ARG_CBOX_SEL_ITEM unsigned short Scalar 0
Pt_ARG_CBOX_TEXT_FILL_COLOR unsigned long Scalar Pg_LGRAY
Pt_CB_CBOX_ACTIVATE PtCallback_t * Link NULL
Pt_CB_CBOX_CLOSE PtCallback_t * Link NULL
Pt_ARG_CBOX_BUTTON_WIDTH
The width of the drop button, in pixels.
Pt_ARG_CBOX_FLAGS
Possible values:
Pt_COMBOBOX_ALT_DOWN
Enable the Alt-↓ keychord, which displays the list and highlights the item
corresponding to the current text.

Pt_COMBOBOX_MAX_WIDTH
Make the combo box size itself to fit the longest list item.
Pt_COMBOBOX_OPEN (read-only)
If this bit is set, the list is currently open.
Pt_COMBOBOX_STATIC
Make the list field static and remove the drop button. If this bit is off, the list
field is visible only when the drop button is pressed.
Pt_COMBOBOX_TOP
Place the list field above the text field. If this bit is off, the list field is placed
below the text field. If there isn’t enough space between the text field and the
edge of the screen, the list may appear on the opposite side of the text field.
Pt_ARG_CBOX_MAX_VISIBLE_COUNT
The maximum number of list items that may be visible before scrollbars appear. If this
is 0, the entire list is displayed without scrollbars.
You can use either this resource or Pt_ARG_VISIBLE_COUNT to control the size of
the list, but you shouldn’t use them both.
Pt_ARG_CBOX_SEL_ITEM
An index into Pt_ARG_ITEMS that indicates which list item is currently selected.
Pt_ARG_CBOX_TEXT_FILL_COLOR
unsigned long Scalar Pg_LGRAY
The fill color of the text area.
Pt_CB_CBOX_ACTIVATE
continued. . .

A list of PtCallback_t structures that define the callbacks that the widget invokes
when the list is activated (i.e opened).
following members:
reason Pt_CB_CBOX_ACTIVATE
event A pointer to a PhEvent_t structure that describes the event that caused
the callback to be invoked, or NULL if there isn’t an event.
cbdata NULL
Pt_CB_CBOX_CLOSE
A list of PtCallback_t structures that define the callbacks that are invoked when
you close the combobox’s list.
following members:
reason Pt_CB_CBOX_CLOSE.
the callback to be invoked, or NULL if there isn’t an event.
cbdata NULL.
Exported subordinate children:

Unless the resources are already defined in PtComboBox, the PtComboBox class uses
the resources of its exported subordinate children, PtList and PtText.
The PtComboBox class “inherits” all the resources of its exported subordinate
children, with the exception of the following, which are blocked:
• Pt_ARG_SELECTION_MODE (defined in PtGenList and inherited by PtList)
— browse mode is always used.
• Pt_ARG_SELECTION_INDEXES (defined in PtList) — PtComboBox replaces
this with Pt_ARG_CBOX_SEL_ITEM because you can select only one item from
the list.

Where PtComboBox and one of its exported subordinate children both define
resources having the same name, the resource defined in PtComboBox takes
precedence.
If PtComboBox modifies an inherited resource, the “Default override” column
indicates the new value. If PtComboBox inherits a resource from one of its exported
subordinate children, the default value assigned by the subordinate widget is inherited
too; the “Default override” column shows this default value.

Pt_ARG_ACCEL_KEY PtLabel Blocked by this class.
Pt_ARG_COLUMNS PtText
Pt_ARG_CURSOR_POSITION PtText
continued. . .


Pt_ARG_DIM PtWidget
Pt_ARG_EDIT_MASK PtText
Pt_ARG_FLAGS PtWidget |=Pt_HIGHLIGHTED | Pt_SET
&=˜Pt_GETS_FOCUS
Pt_ARG_HORIZONTAL_ALIGNMENT PtLabel
Pt_ARG_ITEMS PtList
Pt_ARG_LABEL_FLAGS PtLabel &=˜Pt_LABEL_SELECT_SHIFT
Pt_ARG_LABEL_TYPE PtLabel Blocked by this class.
Pt_ARG_LINE_SPACING PtLabel Blocked by this class.
Pt_ARG_LIST_BALLOON PtList
Pt_ARG_LIST_COLUMN_ATTR PtGenList
Pt_ARG_LIST_COLUMN_POS PtGenList
Pt_ARG_LIST_FLAGS PtGenList
Pt_ARG_LIST_FONT PtGenList
continued. . .


Pt_ARG_LIST_ITEM_COUNT PtGenList
Pt_ARG_LIST_SB_RES PtGenList
Pt_ARG_LIST_SCROLL_RATE PtGenList
Pt_ARG_LIST_SEL_COUNT PtGenList
Pt_ARG_LIST_SPACING PtList
Pt_ARG_LIST_TOTAL_HEIGHT PtGenList
Pt_ARG_MAX_LENGTH PtText
Pt_ARG_MODIFY_ITEMS PtList
Pt_ARG_POS PtWidget
Pt_ARG_RESIZE_FLAGS PtWidget Pt_RESIZE_XY_ALWAYS
Pt_ARG_SCROLLBAR_WIDTH PtGenList 17
Pt_ARG_SELECTION_FILL_COLOR PtGenList
Pt_ARG_SELECTION_INDEXES PtList Blocked by this class; see
Pt_ARG_CBOX_SEL_ITEM
Pt_ARG_SELECTION_MODE PtGenList Blocked by this class; browse mode is always
used.
Pt_ARG_SELECTION_RANGE PtText
Pt_ARG_SELECTION_TEXT_COLOR PtGenList
continued. . .


Pt_ARG_TEXT_CURSOR_WIDTH PtText
Pt_ARG_TEXT_FLAGS PtText
Pt_ARG_TEXT_HIGHLIGHT_BACKGROUND_COLOR PtText
Pt_ARG_TEXT_HIGHLIGHT_TEXT_COLOR PtText
Pt_ARG_TEXT_SUBSTRING PtText
Pt_ARG_TOP_ITEM_POS PtGenList
Pt_ARG_UNDERLINE_TYPE PtLabel Blocked by this class.
Pt_ARG_UNDERLINE1 PtLabel Blocked by this class.
Pt_ARG_UNDERLINE2 PtLabel Blocked by this class.
Pt_ARG_VERTICAL_ALIGNMENT PtLabel
Pt_ARG_VISIBLE_COUNT PtGenList See below.
Pt_CB_ACTIVATE PtBasic Behaves as for PtText.
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
continued. . .


Pt_CB_LIST_INPUT PtList
Pt_CB_MENU PtBasic
Pt_CB_MODIFY_NOTIFY PtText
Pt_CB_MODIFY_VERIFY PtText
Pt_CB_MOTION_NOTIFY PtText
Pt_CB_MOTION_VERIFY PtText
Pt_CB_RAW PtWidget
Pt_CB_SCROLL_MOVE PtGenList
Pt_CB_SELECTION PtList
Pt_CB_TEXT_CHANGED PtText
Pt_ARG_VISIBLE_COUNT
Set this resource to a nonzero value to resize the list to a multiple of the item height. If
the number of items is less than this resource, blank items are displayed at the end of
the list; if the number of items is greater than this resource, a scrollbar is displayed.
You can use either this resource or Pt_ARG_CBOX_MAX_VISIBLE_COUNT to
control the size of the list, but you shouldn’t use them both.
Convenience functions:
The PtComboBox widget and its exported subordinate PtList and PtText children
define various convenience functions that make it easier to use the combo box once it’s
been created. Here’s a brief overview:
PtComboBoxListOpen()
Open a combobox list.
PtComboBoxListClose()
Close an open combobox list.

PtListAddItems() Adds one or more items to the list at a specified position.
PtListDeleteAllItems()
Removes all the items from the list.
PtListDeleteItems() Deletes items in the list by name.
PtListDeleteItemPos()
Deletes a range of items by position.
PtListItemExists() Determines whether or not an item exists within the list.
PtListItemPos() Determines the position of an item within the list.
PtListRemovePositions()
Deletes items at specified positions.
PtListReplaceItemPos()
Replaces items by position number.
PtListReplaceItems()
Replaces items by item text.
PtTextGetSelection() Gets the selected range from a PtText widget.
PtTextModifyText() Modifies the contents of a PtText widget.
PtTextSetSelection() Sets the selected range for a PtText widget.

© 2010, QNX Software Systems GmbH & Co. KG. PtComboBoxListClose()
Close an open combobox list
Synopsis:
int PtComboBoxListClose( PtWidget_t *widget );
Description:
This function closes the list in a PtComboBox widget.
Returns:
0 Success.
-1 The specified widget isn’t a PtComboBox widget.
Classification:
Photon
Safety
Interrupt handler No
Signal handler No
Thread No
See also:
PtComboBoxListOpen()

PtComboBoxListOpen() © 2010, QNX Software Systems GmbH & Co. KG.
Open a combobox list
Synopsis:
int PtComboBoxListOpen( PtWidget_t *widget );
Description:
This function opens/drops down the list in a PtComboBox widget.
Returns:
0 Success.
-1 The specified widget isn’t a PtComboBox widget.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtComboBoxListClose()

© 2010, QNX Software Systems GmbH & Co. KG. PtCompound
Superclass for all compound widgets
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtCompound
• PtColorSel
• PtComboBox
• PtDivider
• PtGenList
• PtMenuButton
• PtMultitext
• PtNumeric
PhAB icon:
Public header:
<photon/PtCompound.h>
Description:
The PtCompound superclass provides the ability to combine widgets into a
compound. A compound widget can export its subordinate children to let you get and
set their resources, or it can block access to them to provide a “canned” appearance.

continued. . .

PtCompound © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_DIM PtWidget
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtCompound

Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
continued. . .

PtCompound © 2010, QNX Software Systems GmbH & Co. KG.


© 2010, QNX Software Systems GmbH & Co. KG. PtContainer
Layout and geometry management for all container widgets
Class hierarchy:
PtWidget → PtBasic → PtContainer
• PtBkgd
• PtClient
• PtCompound
• PtDisjoint
• PtFontSel
• PtGroup
• PtImageArea
• PtOSContainer
• PtPane
• PtPanelGroup
• PtPrintSel
• PtScrollArea
• PtTerminal
• PtToolbar
• PtToolbarGroup
PhAB icon:
Public header:
<photon/PtContainer.h>
Description:
The PtContainer superclass provides layout and geometry management for all
container widgets. It also redirects certain events—such as button presses, releases,
repeats, and keys—to the child that has focus.

PtContainer © 2010, QNX Software Systems GmbH & Co. KG.
New resources:

Pt_ARG_CONTAINER_FLAGS long Flag Pt_ENABLE_CUA | Pt_ENABLE_CUA_ARROWS
Pt_ARG_CURSOR_OVERRIDE int Boolean Pt_FALSE

Pt_ARG_FILL_LAYOUT_INFO PtFillLayoutInfo_t * Struct NULL
Pt_ARG_GRID_LAYOUT_INFO PtGridLayoutInfo_t * Struct NULL
Pt_ARG_LAYOUT PtLayoutDefinition_t * Struct NULL
Pt_ARG_LAYOUT_INFO void * Struct NULL
Pt_ARG_LAYOUT_TYPE int Scalar NULL
Pt_ARG_ROW_LAYOUT_INFO PtRowLayoutInfo_t * Struct NULL
Pt_ARG_TITLE char * String NULL
Pt_ARG_TITLE_FONT char * String "TextFont09"
Pt_CB_BALLOONS PtBalloonCallback_t * Link NULL

Pt_CB_CHILD_ADDED_REMOVED PtCallback_t * Link NULL
Pt_CB_CHILD_GETTING_FOCUS PtCallback_t * Link NULL
Pt_CB_CHILD_LOSING_FOCUS PtCallback_t * Link NULL
Pt_CB_LAYOUT PtCallback_t * Link NULL
Pt_CB_RESIZE PtCallback_t * Link NULL
Pt_ARG_CONTAINER_FLAGS
long Flag Pt_ENABLE_CUA | Pt_ENABLE_CUA_ARROWS
Flags that control the look and behavior of the container:
Pt_AUTO_EXTENT Cause the container to recalculate its preferred size when any
of its children are realized, unrealized, moved, or resized.
Pt_BLOCK_CUA_FOCUS
Prevent Common User Access from moving focus into this
container.
Pt_DISABLE_BALLOONS
Prevent balloons from being inflated in this or any child
container.

Pt_ENABLE_CUA Let CUA keys function in this container (and its children).
Pt_ENABLE_CUA_ARROWS
Permit arrow-key navigation in this container (and its
children).
Pt_ETCH_TITLE_AREA
Display an etched line below the title given by
Pt_ARG_TITLE, provided that Pt_SHOW_TITLE is also set.
Pt_GRADIENT_TITLE_AREA
Display a gradient behind the title given by Pt_ARG_TITLE,
provided that Pt_SHOW_TITLE is also set.
Pt_HOTKEYS_FIRST Process key events that reach this container as hotkeys before
passing them to any children. If the key is a hotkey, the event is
consumed and isn’t passed to any children. Normally the key
is passed to the children and, if not consumed, is processed as
a hotkey.
Pt_HOTKEY_TERMINATOR
Prevent hotkey searches from going to parents of this
container. Note that this flag works only if it’s set in a disjoint
container-class widget.
Pt_SHOW_TITLE Display the title given by Pt_ARG_TITLE, using the font

specified by Pt_ARG_TITLE_FONT.
Pt_ARG_CURSOR_OVERRIDE
int Boolean Pt_FALSE
Let the container’s cursor override its children’s cursors.
Pt_ARG_LAYOUT
PtLayoutDefinition_t * Struct NULL
A generic resource that lets you set the active layout for the container, and the layout
info structure at the same time. This is an alternative to setting
Pt_ARG_LAYOUT_TYPE and Pt_ARG_*_LAYOUT_INFO separately.
This resource can be one of:
• PtFillLayout

• PtRowLayout
• PtGridLayout
• NULL (equivalent to PtAnchorLayout, the default layout type)
When you set this resource using PtSetResource() or PtSetArg(), you can optionally
also set the Pt_ARG_*_LAYOUT_INFO resource for the appropriate layout type
using the len argument. To do this, pass a pointer to layout information structure
appropriate to the layout type as len. It can be one of:
• PtFillLayoutInfo_t
• PtRowLayoutInfo_t
• PtGridLayoutInfo_t
For more information about using layouts and layout resources, see Using Layouts in
Geometry Management in the Photon Programmer’s Guide.
Pt_ARG_LAYOUT_INFO
void * Struct NULL
A generic resource that lets you set the information structure for layouts. When you
set this resource, you must set the len argument of PtSetResource() or PtSetArg() to
the layout type, which is one of:
• PtFillLayout
• PtRowLayout
• PtGridLayout
Pt_ARG_LAYOUT_TYPE
int Scalar NULL
An alternative way of setting or getting the active layout and layout information.
When you set this resource, the value argument of PtSetResource() or PtSetArg() can
be one of:
• Pt_FILL_LAYOUT
• Pt_ROW_LAYOUT

• PT_GRID_LAYOUT
• Pt_ANCHOR_LAYOUT
You can optionally also set the information structure with this resource. To do this, set
the len argument of PtSetResource() or PtSetArg() to the layout information structure,
Pt*LayoutInfo_t. If you set len to NULL, the information structure for the current
layout is set. In this case, make sure that the layout information structure you set
matches the current layout type, or your application may crash.
Pt_ARG_FILL_LAYOUT_INFO
PtFillLayoutInfo_t Struct NULL
The information structure for the PtFillLayout layout type. You can set this
resource directly, or via Pt_ARG_LAYOUT_INFO.
The PtFillLayoutInfo_t contains at least these members:
short type Direction of layout:

• Pt_LAYOUT_HORIZONTAL — layout children in a row
• Pt_LAYOUT_VERTICAL — layout children in a column
short spacing Distance between children, in pixels
There is no layout data for children for this layout type.

Pt_ARG_ROW_LAYOUT_INFO
PtRowLayoutInfo_t Struct NULL
The information structure for the PtRowLayout layout type. You can set this resource
directly, or via Pt_ARG_LAYOUT_INFO.
PtRowLayoutInfo_t contains at least these members:
short type Direction of layout:

• Pt_LAYOUT_HORIZONTAL — layout children in rows
• Pt_LAYOUT_VERTICAL — layout children in columns

short flags A combination of the following flags:

• Pt_ROW_JUSTIFY — distribute extra space between
children when the container grows
• Pt_ROW_PACK — leave children widgets their preferred
size. If this flag is not set, child widgets are all the same size.
• Pt_ROW_WRAP — enable wrapping
PhRect_t margins Container margins in pixels, where:

• ul.x is the left
• ul.y is the top
• lr.x is the right
• lr.y is the bottom
short h_spacing Horizontal spacing distance between children, in pixels
short v_spacing Vertical spacing between children, in pixels
You can use PtRowLayoutInfoDflts to initialize your copy of

PtRowLayoutInfo_t. It has the following values:
type = Pt_LAYOUT_HORIZONTAL
flags = Pt_ROW_PACK | Pt_ROW_WRAP
margin.ul.x = margin.ul.y = margin.lr.x = margin.lr.y = 3
h_spacing = v_spacing = 3
Pt_ARG_GRID_LAYOUT_INFO
PtGridLayoutInfo_t Struct NULL
The information structure for the PtGridLayout layout type. You can set this
resource directly, or via Pt_ARG_LAYOUT_INFO.
PtGridLayoutInfo_t contains at least these members:
unsigned n_cols The number of columns in the grid.
unsigned flags Combination of the following flags:

• Pt_EQUAL_COLS — Force all columns to be the same
width.

• Pt_EQUAL_ROWS — Force all rows to be the same height.

PhRect_t margins Container margins in pixels, where:
• ul.y is the top
short h_spacing Horizontal spacing between columns, in pixels.
short v_spacing Vertical spacing between rows, in pixels.
You can use PtGridLayoutInfoDflts to initialize your copy of

PtGridLayoutInfo_t. It has the following values:
• n_cols = 1
• flags = 0
• margin.ul.x = margin.ul.y = margin.lr.x = margin.lr.y = 2
• h_spacing = v_spacing = 2
Pt_ARG_TITLE
char * String NULL
The title to be displayed if Pt_SHOW_TITLE is set in Pt_ARG_CONTAINER_FLAGS.
Pt_ARG_TITLE_FONT
The font to use for the label’s text string; see PgSetFont() in the Photon Library
Reference.

Pt_CB_BALLOONS
PtBalloonCallback_t * Link NULL
A list of PtBalloonCallback_t structures that define balloon callbacks that the

container invokes if the pointer remains motionless for 1.25 seconds over the widget
specified in the callback structure.
following members:
reason Pt_CB_BALLOONS
reason_subtype Pt_INFLATE_BALLOON when the balloon should be displayed, or

Pt_POP_BALLOON when it should be removed.

cbdata NULL
These callbacks (unlike other callbacks) return nothing.
By default, this callback list invokes the indicated widget’s inflate function, which is
specified by the following resources:
• Pt_ARG_LABEL_BALLOON (PtLabel and its subclasses)
• Pt_ARG_LIST_BALLOON (PtList)
• Pt_ARG_TREE_BALLOON (PtTree)
When a container has balloons registered, it becomes sensitive to Ph_EV_BOUNDARY

events. When the container sees an enter event, it enables the balloon mechanism for
that container. When a boundary event with a subtype of Ph_EV_PTR_STEADY is
received and it’s over a widget that has registered a balloon, the balloons are flagged as
active and the widget’s inflate function is called.
While the balloons are active, Ph_EV_PTR_MOTION_NOBUTTON events are used to
determine when the cursor leaves a widget with an inflated balloon (its inflate function
is called with a Pt_POP_BALLOON subtype). While the balloons are active, any
widget that has a balloon that intersects with a Ph_EV_PTR_MOTION_NOBUTTON
event has its balloon inflated.
Key events and pointer button events deactivate the balloons. Another
Ph_EV_PTR_STEADY event over a widget with a balloon is required to reactivate the
balloons.

If your application has a widget that obscures the container, the widget must have a
region that consumes Ph_EV_BOUNDARY events to prevent the balloon mechanism
for the container from becoming enabled and activated.
This can be done by giving the overlapping widget a Pt_CB_RAW callback (see
PtWidget) that’s sensitive to Ph_EV_BOUNDARY events, or by giving the
overlapping widget a cursor (which automatically sets Ph_FORCE_BOUNDARY in the
flags for the widget’s region, which means it’s opaque to boundary events).
Pt_CB_CHILD_ADDED_REMOVED
A list of PtCallback_t structures that define the callbacks that are invoked when a
widget is added or removed from a container:
• When a child is being added to the container, these callbacks are invoked after the
child has been completely added to the widget family hierarchy and has been
realized (if applicable).
• When a child is being removed from the container, these callbacks are invoked after
the child has been unrealized. If the child is being destroyed, these callbacks are
invoked before the child is freed (i.e. the pointer to the child is still valid, but the
child has Pt_DESTROYED set in its Pt_ARG_FLAGS.
These callbacks are invoked only if:
• Pt_CALLBACKS_ACTIVE is set in the container’s Pt_ARG_FLAGS.
• Pt_PROCREATED isn’t set in the Pt_ARG_FLAGS of the child being added or

removed.

following:
reason Pt_CB_CHILD_ADDED_REMOVED
reason_subtype Pt_CHILD_ADDED or Pt_CHILD_REMOVED.
event Not used (NULL).
cbdata A pointer to the widget being added or removed (i.e. the new or
former child widget).

Pt_CB_CHILD_GETTING_FOCUS

A list of PtCallback_t structures that define the callbacks invoked when a child
widget (or child of a child and so on) is getting focus. You can call PtIsFocused() to
find the current focus state of any widget.
following members:
reason Pt_CB_CHILD_GETTING_FOCUS


contains at least:

PtWidget_t *dst A pointer to the widget which is intended
to get the focus. This pointer could be
NULL, for example if
PtContainerNullFocus() was invoked.
PtWidget_t *child A pointer to the immediate child of the
called container callback.

Or:
Pt_CB_CHILD_LOSING_FOCUS

A list of PtCallback_t structures that define the callbacks invoked when a child
widget (or child of a child and so on) is losing focus. You can call PtIsFocused() to
find the current focus state of any widget.
following members:
reason Pt_CB_CHILD_LOSING_FOCUS


contains at least:

PtWidget_t *dst A pointer to the widget which is intended
to get the focus. This pointer could be
NULL, for example if
PtContainerNullFocus() was invoked.
PtWidget_t *child A pointer to the immediate child of the
called container callback.

Or:
Pt_CB_LAYOUT
A list of PtCallback_t structures that define the callbacks invoked when the widget
is about to start laying out children, and when the widget is finished laying out
children.
following members:
reason Pt_CB_LAYOUT
reason_subtype • Pt_LAYOUT_INIT — starting to lay out children.

• Pt_LAYOUT_DONE — finished laying out children.

event A pointer to a PhEvent_t structure filled with NULLs
cbdata NULL
Pt_CB_RESIZE
A list of PtCallback_t structures that define the callbacks that the container invokes
when its size changes. Each callback is passed a PtCallbackInfo_t structure that
contains at least the following members:
reason Pt_CB_RESIZE
event Not used (NULL).
cbdata A pointer to a PtContainerCallback_t structure that

PhRect_t old_size;
A PhRect_t structure (see the Photon
Library Reference that contains the extent
of the container before the size changed.
PhRect_t new_size;
A PhRect_t structure that contains the
new extent of the container after the size
changed.
PhDim_t old_dim A PhDim_t structure that contains the
dimensions of the container before the size
changed.
PhDim_t new_dim A PhDim_t structure that contains the
dimensions of the container after the size
changed.


Pt_ARG_DIM PtWidget
Pt_ARG_EFLAGS PtWidget Pt_CONSUME_EVENTS
continued. . .


Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
continued. . .


Pt_CB_RAW PtWidget

PtDisjoint © 2010, QNX Software Systems GmbH & Co. KG.
Superclass for disjoint widgets
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtDisjoint
• PtMenu
• PtRegion
• PtWindow
PhAB icon:
Public header:
<photon/PtDisjoint.h>
Description:
PtDisjoint is the superclass for the widget classes that are disjoint (i.e. are
instantiated without a parent).
New resources:

Pt_ARG_SYSINFO PhSysInfo_t * Struct See below.
Pt_CB_SYSINFO PtCallback_t * Link NULL
Pt_ARG_SYSINFO (read only)

PhSysInfo_t * Struct See below.
If you get the value of this resource, you get a pointer to a PhSysInfo_t structure
(see the Photon Library Reference) that indicates the conditions above this widget.
Pt_CB_SYSINFO
receives a Ph_EV_INFO event.

© 2010, QNX Software Systems GmbH & Co. KG. PtDisjoint

following members:
reason Pt_CB_SYSINFO
reason_subtype One of:

• Ph_FEP — the information is from a “front-end input
processor.” You can get the data with this code:
PhFEPInfo_t *fep_info = PhGetData( event );
• Ph_INVALIDATE_SYSINFO — the rendering environment has

changed. No data is included in the event; if you need it, call
PhQuerySystemInfo() or PtQuerySystemInfo(), both of which
are described in the Photon Library Reference.

cbdata NULL.

Pt_ARG_BANDWIDTH_THRESHOLD PtBasic
continued. . .

PtDisjoint © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_DIM PtWidget
Pt_ARG_POS PtWidget
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtDisjoint

Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

PtDivider © 2010, QNX Software Systems GmbH & Co. KG.
A container that divides space among its children
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtCompound → PtDivider
PhAB icon:
Public header:
<photon/PtDivider.h>
Description:
The PtDivider widget is a container that lays out its children like a one-row or
one-column PtGroup widget, but lets you resize the children by dragging “handles”
placed between the children.
Two PtDivider widgets: one contains two lists, the other contains some buttons.
The PtDivider class inherits resources from the PtGroup class. Access to these
resources is controlled through PtDivider’s exporting mechanism.
A blocking mechanism lets PtDivider block the inheritance of certain resources
from its subordinate PtGroup widget. This prevents any actions that would negatively
affect the look and behavior of a PtDivider widget. For more information, see the
“Exported subordinate children” section.
Examples
In this example, we use the Pt_CB_DIVIDER_HANDLE_CALLBACK callback to set
the default widget sizes:
static int default_sizes[] = { 100, 50, 60, 200, ... };
int drag_handle_cb( PtWidget_t *dvdr, ApInfo_t *data,

PtCallbackInfo_t *cbinfo ) ) {
PtDividerHandleCallback_t *cbdata = cbinfo->cbdata;

PhEvent_t *ev = cbinfo->event;
PhPointerEvent_t *pe = PhGetData( ev );
if( ev->type == Ph_EV_BUT_RELEASE

&& ev->subtype == Ph_EV_RELEASE_REAL

© 2010, QNX Software Systems GmbH & Co. KG. PtDivider
&& pe->click_count == 2
) {
// Set the default size on a double click
PtSetResource( cbdata->left, Pt_ARG_WIDTH,

default_sizes[cbdata->index], 0 );
New resources:

Pt_ARG_DIVIDER_FLAGS unsigned short Flag Pt_DIVIDER_RESIZE_BOTH
Pt_ARG_DIVIDER_OFFSET short Scalar 0

Pt_ARG_DIVIDER_SIZES PtDividerSizes_t *, short Array NULL, 0 (read-only)
Pt_CB_DIVIDER_DRAG PtCallback_t * Link NULL
Pt_CB_DIVIDER_HANDLE_CALLBACK PtCallback_t * Link NULL
Pt_ARG_DIVIDER_FLAGS
unsigned short Flag Pt_DIVIDER_RESIZE_BOTH
Possible values:
Pt_DIVIDER_NORESIZE
Don’t resize the children, just invoke the callback.
Pt_DIVIDER_RESIZE_BOTH
Resize both widgets: the one to the left and to the right (or above and below) the
dragged handle. If this flag isn’t set, only the left child is resized and the right
child is moved.
Pt_DIVIDER_INVISIBLE
Never display the drag outline. This flag is useful mainly when
Pt_DIVIDER_NORESIZE is also set.

Pt_DIVIDER_CASCADE
The re-sizing of a widget is “cascaded” to adjacent widgets when the widget has
reached it’s minimum size. At that point the adjacent widget starts to shrink
until it reaches its minimum size, and then its neighbor is resized, and so on.
Pt_DIVIDER_LAST_IS_SPACER
Useful when the divider is in a PtList widget with a horizontal scrollbar. The
last widget is a spacer. When the Pt_CB_DIVIDER_DRAG callback is invoked,
this widget’s size is always reported as 1, regardless of its actual size.
Pt_DIVIDER_NODRAG
The divider handles can’t be dragged. They don’t display a drag cursor when the
pointer is hovering over them.
Pt_ARG_DIVIDER_OFFSET
short Scalar 0
This number is added to positions of child widgets (relative to the position of the
PtDivider widget) when the values for the Pt_ARG_DIVIDER_SIZES resource are
calculated. By setting Pt_ARG_DIVIDER_OFFSET, you can make the
Pt_ARG_DIVIDER_SIZES relative to any arbitrary point.
Pt_ARG_DIVIDER_SIZES (read-only)
PtDividerSizes_t *, short Array NULL, 0
The array of positions and sizes of realized children of the divider. Each
PtDividerSizes_t structure contains:
short from The left side or top of the child, depending on the divider’s
orientation.
short to The right or bottom of the child, depending on the divider’s

orientation.
Pt_CB_DIVIDER_DRAG
widget receives a drag event.


resource, these callbacks are also invoked when your application changes the size of a
child by calling PtSetResource() or PtSetResources().
following members:
reason Pt_CB_DIVIDER_DRAG
reason_subtype The subtype of the drag event (see Ph_EV_DRAG in the

description of the PhEvent_t structure in the Photon Library
Reference), or Pt_CB_DIVIDER_SETRESOURCES if a child is
being resized through PtSetResources() and the widget has the
Pt_CALLBACKS_ACTIVE bit set in its Pt_ARG_FLAGS resource.
event A pointer to a PhEvent_t structure that describes the received

drag event, or NULL if a child is being resized through a call to
PtSetResources().
cbdata A pointer to a PtDividerCallback_t structure that contains at

PtWidget_t *left, *right;

The two widgets in the group separated by the
divider.
int moved; How far the widget on the right has been moved.
int resized;
The amount by which the widget on the left has
been resized.
PtDividerSizes_t const *sizes;
The new value of the Pt_ARG_DIVIDER_SIZES
resource.
int nsizes; The number of items in the sizes array.
Pt_CB_DIVIDER_HANDLE_CALLBACK
you press the pointer button when pointing at widget’s resize handles, and also when
the button is released.
following members:

reason Pt_CB_DIVIDER_HANDLE_CALLBACK
event A pointer to a PhEvent_t structure that describes the received

pointer event.
cbdata A pointer to a PtDividerHandleCallback_t structure that

int start_drag Set to 1 when a drag operation is requested on a

click; you can set to 0 to decline the drag
operation.
int index The drag handle index.
PtWidget_t *handle
The drag handle.
PtWidget_t *left, *right;
The two widgets in the group separated by the
divider.

Unless the resources are already defined in PtDivider, the PtDivider class uses
the resources of its exported subordinate child, PtGroup.
Where PtDivider and PtGroup both define resources having the same name, the
resource defined in PtDivider takes precedence.
If PtDivider modifies an inherited resource, the “Default override” column indicates
the new value. If PtDivider inherits a resource from PtGroup, the default value
assigned by PtGroup is inherited too; the “Default override” column shows this
default value.

Pt_ARG_ANCHOR_FLAGS PtWidget 0 (no anchors)
Pt_ARG_BANDWIDTH_THRESHOLD PtBasic Ph_BAUD_CONSOLE (see below)
continued. . .


Pt_ARG_CONTAINER_FLAGS PtContainer Sets Pt_AUTO_EXTENT and
Pt_CHILD_MOVED_RESIZED
Pt_ARG_DIM PtWidget
Pt_ARG_EFLAGS PtWidget Clears Pt_DAMAGE_ON_FOCUS, sets
Pt_CONSUME_EVENTS
Pt_ARG_GROUP_FLAGS PtGroup Sets Pt_GROUP_STRETCH flag
Pt_ARG_GROUP_HORZ_ALIGN PtGroup
Pt_ARG_GROUP_ORIENTATION PtGroup Pt_GROUP_HORIZONTAL (see below)
Pt_ARG_GROUP_ROWS_COLS PtGroup Blocked by this class.
Pt_ARG_GROUP_SPACING PtGroup 0
Pt_ARG_GROUP_SPACING_X PtGroup Blocked by this class.
Pt_ARG_GROUP_SPACING_Y PtGroup Blocked by this class.
continued. . .


Pt_ARG_GROUP_VERT_ALIGN PtGroup 0
Pt_ARG_POS PtWidget
Pt_ARG_RESIZE_FLAGS PtWidget 0
Pt_ARG_SEP_IMAGE PtSeparator
Pt_ARG_SEP_IMAGE_H_ALIGN PtSeparator
Pt_ARG_SEP_IMAGE_V_ALIGN PtSeparator
Pt_ARG_SEP_TYPE PtSeparator
Pt_CB_ARM PtBasic
continued. . .


Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
Defines the “graphics bandwidth” threshold that determines whether the widget
resizes the children after each received drag event or only once, when the drag is
completed — see PtQuerySystemInfo().
Pt_ARG_GROUP_ORIENTATION
The value of this resource can be only Pt_GROUP_HORIZONTAL or
Pt_GROUP_VERTICAL.

PtEllipse © 2010, QNX Software Systems GmbH & Co. KG.
An ellipse
Class hierarchy:
PtWidget → PtBasic → PtGraphic → PtEllipse
PhAB icon:
Public header:
<photon/PtEllipse.h>
Description:
The PtEllipse class draws an ellipse.
A PtEllipse widget.
The bounding box of the ellipse, which determines its height and width, is defined by
two points that you can specify in the Pt_ARG_POINTS resource. These points are
relative to the widget’s Pt_ARG_ORIGIN. For more information, see PtGraphic.
If you don’t set these points, Pt_ARG_DIM determines the height and width (see
PtWidget).

continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtEllipse

Pt_ARG_DIM PtWidget
continued. . .

PtEllipse © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtEllipse


PtFileSel © 2010, QNX Software Systems GmbH & Co. KG.
A tree widget for selecting files and directories
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtCompound → PtGenList →
PtGenTree → PtFileSel
PhAB icon:
Public header:
<photon/PtFileSel.h>
Description:
The PtFileSel widget is a tree where items can be files, directories, links to files or
directories, or custom entries.
A PtFileSel widget.
This widget is useful when a program lets you open or save files or directories. It reads
a directory and displays the contents. You can also use the widget to navigate a
filesystem and choose your own file and directory.
The items in the PtFileSel widget are displayed with images to show what type of
file they are. Directory items are expandable and can show the files, directories and
links under them. To expand and collapse items, you can use the pointer or these keys:
To: Press one of:

Expand a directory Enter, →, or + on the keypad
Collapse a directory Backspace, ←, or - on the keypad
Each item is stored in a PtFileSelItem_t structure that contains at least:
PtGenTreeItem_t gen
Used internally.

© 2010, QNX Software Systems GmbH & Co. KG. PtFileSel
short opened A value that indicates whether the given directories’ children
have already been allocated or not:
• Pt_FS_NEW_DIR—an unallocated directory
• Pt_FS_OLD_DIR—an allocated directory
short type The type of file the item is:

• Pt_FS_DIR_OP—an open directory, one that has visible items
• Pt_FS_DIR_CL—a closed directory, one that doesn’t have
visible items
• Pt_FS_DLINK_OP—a link to an open directory
• Pt_FS_DLINK_CL—a link to a closed directory
• Pt_FS_FILE—a file
• Pt_FS_FLINK—a link to a file
• Pt_FS_ERROR—a file that had a read error
short root A value that indicates if this is the root item:

• 1—this is the root directory
• 0—this isn’t the root directory
char *fullpath The full pathname of the item
int tag Used internally
The widget has two main modes of operation:
Tree mode (default) Items are displayed in a tree structure; opening a directory
causes a new branch to be created.
Single-level mode Items are displayed in a single level or list; the list contains all
the files in the current directory. When a directory is chosen,
the existing items are freed and new ones are created for the
new directory. You can traverse up the filesystem by using the
.. item. To use this mode, set the Pt_FS_SINGLE_LEVEL bit
in Pt_ARG_FS_FLAGS.

A single-level file selector.
In this mode, you can also turn on the “key seek” flag,
Pt_FS_SEEK_KEY, which lets you use the keyboard to search
for a file. In this mode, the widget selects the next file or
directory whose name starts with a character that you type.
The search is case-sensitive and wraps to the top of the list if
the character isn’t found. Whenever you press a key, the
Pt_CB_FS_SELECTION callback is invoked with a
reason_subtype of Pt_LIST_SELECTION_BROWSE.
The widget can also display file information including name, size, date, permissions,
owner and group. You can use the Pt_ARG_FS_FORMAT resource to set the amount
and order of information displayed. A PtDivider widget is automatically included in
the file selector, along with a label for each column you request.
If you want to override the default headers, create a PtDivider of your own, add
appropriate PtLabel widgets to it, and make the divider a child of the file selector.
The information you requested is displayed in the proper columns.
For example, if you create a PtDivider with the headings “Filename”, “File size”,
and “Modification time” as a child of a PtFileSel widget and set the
Pt_ARG_FS_FORMAT to nsd, the PtFileSel items contain the name, size, and
date information in the proper columns, but your divider is displayed.
By default, when you expand an item (directory) for the first time, the directory is read
and items are allocated. After this, when you collapse and expand the item, the
information is stored in memory to remove the delay of reading a directory. You can
refresh an item at any time by using the Pt_ARG_FS_REFRESH resource. You can
also set the Pt_FS_FREE_ON_COLLAPSE flag to cause a directory to be reread every
time it’s expanded. Every time a new root directory is set, all the previous items are
freed.
If you plan to add items to the PtFileSel widget yourself by using the
PtFSAllocItem(), PtFSAddFirst(), and PtFSAddAfter() convenience functions, you

should have a state callback (Pt_CB_FS_STATE, subtype = Pt_FS_STATE_START)

that returns Pt_END.
If you’re in tree mode and you get a state callback for one of your items (i.e. not from
a filesystem), you should deal with the expansion/collapse and return Pt_END from the
callback to prevent PtFileSel from trying to find the item in the filesystem.
If you’re in single-level mode and you get a state callback for one of your items, you
should deal with the expansion; it’s your responsibility to free all the previous items.
Return Pt_END from the callback as mentioned above.
Examples
In the examples below, Pt_FS_ALL_FLAGS is a value containing all the flag bits. It’s
used for a mask.
To display only directories, in tree mode:
...
PtSetArg(&args[0], Pt_ARG_FS_FLAGS, Pt_FS_SHOW_DIRS,
Pt_FS_ALL_FLAGS);
PtSetArg(&args[1], Pt_ARG_FS_ROOT_DIR, "/", 0);
PtSetArg(&args[2], Pt_ARG_AREA, area, 0);
PtCreateWidget(PtFileSel, Pt_DEFAULT_PARENT, 3, args);
...
To display only files in single-level mode, with keyboard seek on:
...
PtSetArg(&args[0], Pt_ARG_FS_FLAGS,
Pt_FS_SINGLE_LEVEL|Pt_FS_SHOW_FILES| \
Pt_FS_KEY_SEEK, Pt_FS_ALL_FLAGS);
...
To display a single level of directories with a “..” item to move up levels:
...
Pt_FS_SHOW_DIRS|Pt_FS_SINGLE_LEVEL,
Pt_FS_ALL_FLAGS);
...
To display a combination of directories and files in tree mode:
...
Pt_FS_SHOW_DIRS|Pt_FS_SHOW_FILES,
Pt_FS_ALL_FLAGS);
...

To show only hidden files (that is, those whose name begins with a “.” and aren’t
normally displayed):
...
Pt_FS_SHOW_FILES|Pt_FS_SHOW_HIDDEN,
Pt_FS_ALL_FLAGS);
...
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.
The PtFileSel widget reads a filesystem, so there could be some delays on large
directories. To help you cope with these delays, the widget does the following:
• The Pt_CB_FS_STATE callback is invoked when an item is expanded or

collapsed. The expansion may take a long time if the directory is large, so the
Pt_CB_FS_STATE callback is actually invoked twice, once at the start of the
expansion/collapse (reason = Pt_FS_STATE_START) and once at the end (reason =
Pt_FS_STATE_END). This lets you block the widget until the expansion/collapse is
done. The code below gives an example of this.
• The Pt_CB_FS_BKGD_HANDLER callback is invoked each time a directory

entry is read. You can use this callback to call something like
PtBkgdHandlerProcess(). By doing this, any pending Photon events are handled
and all the screen damage is fixed. This function should be small; if not, it will
slow down the directory reading even further.
Here’s a full PtFileSel example:
#include <stdio.h>
#include <stdlib.h>
#include <Pt.h>
#include <photon/PtFileSel.h>
PtWidget_t *window, *button, *fs;
/* Quit button callback */

int
quit( PtWidget_t *widget, void *data,
PtCallbackInfo_t *info)
{
PtExit(EXIT_SUCCESS);
return (Pt_CONTINUE);
}
/* Open button callback */

int
file_open( PtWidget_t *widget, void *data,
{
PtFileSelItem_t *item;
char buffer[PATH_MAX+NAME_MAX + 40];
char const *btns[] = { "&OK" };

item = PtFSGetCurrent(fs);
if (item == NULL)
return(Pt_CONTINUE);
strcpy(buffer, "The selected file is\n");

strcat(buffer, item->fullpath);
PtAlert( window, NULL, "Selected File", NULL,

buffer, NULL, 1, btns, NULL, 1, 1, Pt_MODAL );
}
/* State callback, will use the reason to block the

widget for large directory opens. */
int
state_cb( PtWidget_t *widget,
void * data,
{
PtArg_t args[3];
PtFileSelCallback_t *it;
it = (PtFileSelCallback_t *)(info->cbdata);
if (it->reason == Pt_FS_STATE_START)
{
PtSetArg(&args[0], Pt_ARG_FLAGS, Pt_BLOCKED,
Pt_BLOCKED);
PtSetArg(&args[1], Pt_ARG_CURSOR_TYPE,
Ph_CURSOR_CLOCK, 0);
}
else
{
PtSetArg(&args[0], Pt_ARG_FLAGS, ˜Pt_BLOCKED,
Pt_BLOCKED);
Ph_CURSOR_INHERIT, 0);
}
PtSetResources(widget, 2, args);
}
/* Function to handle photon draw events and fix

screen damage */
int
handler_cb(PtWidget_t *widget,
void * data,
{
PtBkgdHandlerProcess();
}
int main(void)
{
PtArg_t args[10];
PtCallback_t cb, cb2;
PhDim_t win_dim = { 300, 300 };
PhArea_t area;

if (PtInit(NULL) == -1)
exit(EXIT_FAILURE);
/* Make the main window. */

PtSetArg( &args[0], Pt_ARG_WINDOW_TITLE,
"PtFileSel Demo", 0 );
PtSetArg( &args[1], Pt_ARG_DIM, &win_dim, 0 );
if ((window = PtCreateWidget(PtWindow, Pt_NO_PARENT,

2, args)) == NULL)
PtExit(EXIT_FAILURE);
/* Make a file selector. */

area.size.w = 200;
area.size.h = 200;
area.pos.x = 10;
area.pos.y = 10;
cb.event_f = state_cb;
cb2.event_f = handler_cb;
PtSetArg(&args[0], Pt_ARG_AREA, &area, 0 );
Pt_FS_SHOW_DIRS|Pt_FS_SHOW_FILES,
Pt_FS_ALL_FLAGS );
PtSetArg(&args[3], Pt_CB_FS_STATE, &cb, 0);
PtSetArg(&args[4], Pt_CB_FS_BKGD_HANDLER, &cb2, 0);
fs = PtCreateWidget( PtFileSel, window, 5, args );
/* Make a button for quitting. */

area.size.w = 60;
area.size.h = 20;
area.pos.x = 230;
area.pos.y = 250;
cb.event_f = quit;
PtSetArg( &args[0], Pt_ARG_AREA, &area, 0 );
PtSetArg( &args[1], Pt_ARG_TEXT_STRING, "Quit", 0);
PtSetArg( &args[2], Pt_CB_ACTIVATE, &cb, 0);
button = PtCreateWidget( PtButton, window, 3, args );
/* Make a open button. */

area.size.w = 60;
area.size.h = 20;
area.pos.x = 160;
area.pos.y = 250;
cb.event_f = file_open;
PtSetArg( &args[0], Pt_ARG_AREA, &area, 0 );
PtSetArg( &args[1], Pt_ARG_TEXT_STRING, "Open", 0);
PtSetArg( &args[2], Pt_CB_ACTIVATE, &cb, 0);
PtCreateWidget( PtButton, window, 3, args );
PtRealizeWidget( window );
PtMainLoop();
return (EXIT_SUCCESS);
}

New resources:

Pt_ARG_FS_FILE_SPEC char * String "*"
Pt_ARG_FS_FLAGS unsigned long Flags Pt_FS_SHOW_DIRS |
Pt_FS_SHOW_FILES
Pt_ARG_FS_FORMAT char * String n
Pt_ARG_FS_IMAGES PhImage_t *, short Array PFM-style images (write-only)
Pt_ARG_FS_LBL_DATE char * String "Date"
Pt_ARG_FS_LBL_GROUP char * String "Group"
Pt_ARG_FS_LBL_NAME char * String "Name"
Pt_ARG_FS_LBL_OWNER char * String "Owner"
Pt_ARG_FS_LBL_PERMISSIONS char * String "Permissions"
Pt_ARG_FS_LBL_SIZE char * String "Size"
Pt_ARG_FS_REFRESH PtFileSelItem_t * Pointer NULL
Pt_ARG_FS_ROOT_DIR char * String NULL
Pt_CB_FS_BKGD_HANDLER PtCallback_t * Link NULL
Pt_CB_FS_SELECTION PtCallback_t * Link NULL
Pt_CB_FS_STATE PtCallback_t * Link NULL
Pt_ARG_FS_FILE_SPEC
char * String "*"
A string that you can use to limit the files listed, by specifying a pattern that the
filenames must match. The default is *, but you can use values such as *.c, *.[ch]
and so on. You can specify multiple patterns by separating them with a space or a
comma (for example, *.gif, *.jpg).
Pt_ARG_FS_FLAGS
unsigned long Flags Pt_FS_SHOW_DIRS | Pt_FS_SHOW_FILES
Flags that control the appearance and behavior of the file selector:

Pt_FS_CASE_INSENSITIVE
The file name’s filtering (according to the file_spec ) is
case-insensitive.
Pt_FS_ERROR_POPUP
Display an error dialog when the desired root directory is
invalid.
Pt_FS_FREE_ON_COLLAPSE
Free items on every collapse. This means that every time an
item expands, all its child items are reread from the disk.
Pt_FS_NO_ROOT_DISPLAY
Don’t show the root item.
Pt_FS_SEEK_KEY Keyboard seek mode, valid only for single-level mode. Type
characters to seek an item.
Pt_FS_SHOW_DIRS Show directories.
Pt_FS_SHOW_ERRORS
Show files that had a read error.
Pt_FS_SHOW_FILES
Show files.
Pt_FS_SHOW_HIDDEN
Show hidden files or directories. This flag must be combined
with Pt_FS_SHOW_FILES and/or Pt_FS_SHOW_DIRS. A
hidden file or directory is one whose name begins with a
period (.).
Pt_FS_SINGLE_LEVEL
Single-level mode, instead of tree mode. Directories and
possibly files are shown in one level with a .. item for moving
up directory levels.
If the Pt_FS_NO_ROOT_DISPLAY and Pt_FS_SINGLE_LEVEL flags are both set, the

Pt_FS_NO_ROOT_DISPLAY flag is ignored.
Pt_ARG_FS_FORMAT
char * String n
A string that’s used to set the order and amount of file information displayed and
optionally the initial size (in pixels) of each column shown. The following information

can be displayed for each item in the widget by including the corresponding letter in
the Pt_ARG_FS_FORMAT string:
To display: Specify:
Name n
Size (in bytes) s
Size (in kbytes) k
Date d
Permissions p
Owner o
Group g
These letters must be in lower case.
The s and k options are mutually exclusive. If you try to set both, the first one found
in the string is used and the other is ignored. The maximum number of characters is 6;
any extra ones are ignored.
If you wish to display only the filename and no divider at the top, set this resource to
NULL. To set the size of the column, specify a number of pixels before the
corresponding letter. For example, if you want to have the name (100 pixels wide) and
the date (200 pixels wide) displayed, set the Pt_ARG_FS_FORMAT resource as
follows:
PtSetArg(&args[0], Pt_ARG_FS_FORMAT, "100n200d", 0);
Pt_ARG_FS_IMAGES (write-only)
PhImage_t * Array PFM-style images
A pointer to an array of image pointers (of type PhImage_t — see the Photon Library
Reference) to be used for displaying items. The following constants are used to index
into this array (the order shown is the order the images appear in the array):
• Pt_FS_DIR_OP—open directories
• Pt_FS_DIR_CL—closed directories
• Pt_FS_DLINK_OP—open directory links
• Pt_FS_DLINK_CL—closed directory links

• Pt_FS_FILE—files
• Pt_FS_FLINK—file links
• Pt_FS_ERROR—errors
If you don’t want to change an image, specify NULL for that array element. For
example, to change the file image, set the Pt_FS_FILE entry of the array to the image
pointer and set all others to NULL.
For example, to change the Pt_FS_DIR_OP and Pt_FS_FILE images:
PhImage_t *images[7];
/* Fill the below image structures */
.
.
.
PhImage_t new_open_image, new_file_image;
...
images[Pt_FS_DIR_OP] = &new_open_image;
images[Pt_FS_DIR_CL] = NULL;
images[Pt_FS_DLINK_OP] = NULL;
images[Pt_FS_DLINK_CL] = NULL;
images[Pt_FS_FILE] = &new_file_image;
images[Pt_FS_FLINK] = NULL;
images[Pt_FS_ERROR] = NULL;
PtSetArg(&args[0], Pt_ARG_FS_IMAGES, images, 7);

...
If you want to save processing time, set the length parameter to PtSetArg() to the index
of the last image you changed + 1.
Set the flags member of the PhImage_t structures to:
before providing the images to the widget. If you do this, the memory used for the
images is released when the widget is unrealized or destroyed.
Pt_ARG_FS_LBL_DATE
char * String "Date"
The label used for the column that displays the files’ modification dates.
Pt_ARG_FS_LBL_GROUP

The label used for the column that displays the group for the owner of the files.
Pt_ARG_FS_LBL_NAME
char * String "Name"
The label used for the column that displays the names of the files.
Pt_ARG_FS_LBL_OWNER
char * String "Owner"
The label used for the column that displays the owners of the files.
Pt_ARG_FS_LBL_PERMISSIONS
char * String "Permissions"
The label used for the column that displays the permissions for the files.
Pt_ARG_FS_LBL_SIZE
char * String "Size"
The label used for the column that displays the sizes of the files.
Pt_ARG_FS_REFRESH
PtFileSelItem_t * Pointer NULL
A pointer to the PtFileSelItem_t structure for an expandable item that’s to be

refreshed (i.e. reread from the disk). For example, if you have a large directory
displayed and someone adds a file, you may wish to refresh the directory item. To do
this, set the Pt_ARG_FS_REFRESH resource to point to the root item for that subtree.

Pt_ARG_FS_ROOT_DIR

char * String NULL
The root directory for the file selector. The default value is NULL or none.
The widget stores the actual path obtained via the realpath() function (see the QNX
Neutrino Library Reference). For example, if you set this resource to
///home//fred/.././fred/src, the widget actually sets it to /home/fred/src
or /fs/hd0-qnx4/home/fred/src (if home is a link to /fs/hd0-qnx4/home).
Setting Pt_ARG_FS_ROOT_DIR to NULL clears the PtFileSel directory tree, and
setting it to "." loads the current working directory.
Pt_CB_FS_BKGD_HANDLER
A list of PtCallback_t structures that define the callbacks invoked each time a
directory item is read. For example, if you have 5 files in a directory and expand that
directory, this callback is invoked 5 times. This gives you a chance to translate any
non-UTF-8 filenames into UTF-8 strings. It’s also useful for handling pending Photon
events.
following members:
reason Pt_CB_FS_BKGD_HANDLER

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

cbdata Used only for the Pt_FS_NEW_ITEM subtype of this callback
For the Pt_FS_NEW_ITEM reason subtype, cbdata points to a structure of type

PtFileSelBkgdCallback_t, which contains at least:

char* name A pointer to a buffer that contains the filename that the widget will
add to the list. You can use this callback to ensure that the buffer
contains a valid UTF-8 string.
If this callback returns Pt_END, the item isn’t added. If you want to make sure that the
widget correctly displays filenames that aren’t encoded in UTF-8, you can use
PxTranslate... functions to translate them, copy the new string into name, and return
Pt_CONTINUE. You may also wish to process events.
Set the Pt_CB_FS_BKGD_HANDLER callback resource before the

Pt_ARG_FS_ROOT_DIR resource in order to translate all the filenames.
Here’s an example of this callback:
int
handler_cb( PtWidget_t *widget, void *data,
{
PtFileSelBkgdCallback_t *it = (void *) info->cbdata;
if (info->reason_subtype == Pt_FS_NEW_ITEM)
{
int srctaken = 0, dstmade = 0;
char dst[NAME_MAX * 3];
/* ctrl is a PxTransCtrl structure that was set with a

call to PxTranslateSet(). The following will convert
the string and copy it back to the original: */
if (PxTranslateToUTF( ctrl, it->name, strlen( it->name),

&srctaken, dst, sizeof(dst)-1, &dstmade) == 0)
{
dst[ dstmade ] = ’\0’;
strcpy(it->name, dst);
}
else
/* Can’t translate to UTF-8 -- let’s just ignore this file... */
return Pt_END;
}
PtBkgdHandlerProcess();
return(Pt_CONTINUE);
}
Pt_CB_FS_SELECTION
A list of PtCallback_t structures that define the callbacks invoked when you select
an item. Each callback is passed a PtCallbackInfo_t structure that contains at least
the following members:
reason Pt_CB_FS_SELECTION

reason_subtype Depending on the selection mode, this is one of:

• Pt_LIST_SELECTION_FINAL
• Pt_LIST_SELECTION_BROWSE
• Pt_LIST_SELECTION_CANCEL

cbdata A pointer to a PtFileSelCallback_t structure that contains:

• unsigned sel_mode—the current selection mode:
- Pt_BROWSE_MODE
- Pt_MULTIPLE_MODE
- Pt_EXTENDED_MODE
- Pt_SINGLE_MODE
- Pt_RANGE_MODE
• PtFileSelItem_t *item—a pointer to the item that has
been selected
• unsigned nitems—the number of selected items, which
depends on the selection mode
• short reason—not valid for this callback
Pt_CB_FS_STATE
A list of PtCallback_t structures that define the callbacks invoked when an item is
expanded or collapsed. Each callback is passed a PtCallbackInfo_t structure that
reason Pt_CB_FS_STATE
reason_subtype Pt_TREE_COLLAPSING or Pt_TREE_EXPANDING.

cbdata A pointer to a PtFileSelCallback_t structure that contains:

• unsigned sel_mode—the current selection mode:
- Pt_BROWSE_MODE
- Pt_MULTIPLE_MODE

- Pt_EXTENDED_MODE
- Pt_SINGLE_MODE
- Pt_RANGE_MODE
• PtFileSelItem_t *item—if the reason member is
Pt_FS_STATE_START, this is a pointer to the item being
collapsed or expanded; if the reason member is
Pt_FS_STATE_END, this is NULL.
If the Pt_FS_SINGLE_LEVEL flag is set in the Pt_ARG_FS_FLAGS resource, item is

always NULL because all the previous items are destroyed when you select a new
directory in single-level mode.
• unsigned nitems—not valid for this callback

• short reason—
Pt_FS_STATE_START
The callback is being called before the
directory is read (useful for blocking the
widget when reading a large directory).
Pt_FS_STATE_END The callback is being called after the
directory is read (useful for unblocking
the widget).

continued. . .


Pt_ARG_DIM PtWidget
Pt_ARG_LIST_DNDSEL_COLOR PtGenList
continued. . .


Pt_ARG_POS PtWidget
Pt_ARG_SCROLLBAR_WIDTH PtGenList
Pt_ARG_SELECTION_MODE PtGenList
Pt_ARG_TREE_FLAGS PtGenTree
Pt_ARG_TREE_LINE_COLOR PtGenTree
Pt_ARG_TREE_LINE_SPACING PtGenTree
Pt_ARG_TREE_MARGIN_COLOR PtGenTree
Pt_ARG_VISIBLE_COUNT PtGenList
Pt_CB_ARM PtBasic
continued. . .


Pt_CB_BALLOONS PtContainer Not used by this class.
Pt_CB_DND PtWidget See below.
Pt_CB_GEN_TREE_INPUT PtGenTree
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
Pt_CB_DND
For Pt_CB_DND callbacks for a PtList, the cbinfo->cbdata is a pointer to a
PtTreeDndCallback_t structure, containing at least the following members:
PtDndCallbackInfo_t dnd_info
See the description of Pt_CB_DND for PtWidget.
PtGenTreeItem_t *item
A pointer to the PtGenTreeItem_t structure for the target item
involved in the drag-and-drop operation. You can cast this to be a
pointer to a PtFileSelItem_t.
int item_pos The index of that item.

unsigned long flags

Possible values:
• Pt_LIST_ITEM_DNDSELECTED_UP — the drop occurred above
the item.
• Pt_LIST_ITEM_DNDSELECTED_DOWN — the drop occurred
below the item.
• Pt_LIST_ITEM_DNDSELECTED_IN — the drop occurred inside
the item.
int action This member is initially set to Pt_LIST_ITEM_DNDSELECTED_UP

| Pt_LIST_ITEM_DNDSELECTED_DOWN |
Pt_LIST_ITEM_DNDSELECTED_IN. You can unset some of these
values to indicate that the drag-and-drop isn’t accepted in that case.
For example, if you unset Pt_LIST_ITEM_DNDSELECTED_IN, the
drag-and-drop can’t occur inside the item, only above or below.
The PtFileSel widget defines the following convenience functions that make it
easier to use the file selector once it’s been created:
PtFileSelection() Create a file-selector dialog — see the Photon Library

Reference
PtFSAddAfter() Insert an item after the specified item
PtFSAddFirst() Add a root item to the widget
PtFSAllItems() Fill a buffer with pointers to all items
PtFSAllocItem() Create an item for a file-selector widget
PtFSClearSelection()
Clear the selection
PtFSDamageItem() Redraw an item
PtFSExpandParents()
Expand an item’s collapsed ancestors
PtFSFolderCollapse()
Collapse an expandable item (directory)
PtFSFolderExpand() Expand an expandable item (directory)
PtFSFreeAllItems() Unlink and frees all items
PtFSFreeItems() Free an unlinked item

PtFSGetCurrent() Get the current item (see “Current item” in the description of
PtGenList)
PtFSGetSelIndexes() Fill a buffer with indexes
PtFSGoto() Set the current item
PtFSItemIndex() Calculate the index of the specified item
PtFSRemoveChildren()
Unlink all the children of a given item
PtFSRemoveItem() Unlink an item
PtFSRemoveList() Unlink the root item
PtFSRootItem() Return the first root item of the file selector
PtFSSelect() Select the specified item
PtFSSelectedItems() Fill a buffer with item pointers
PtFSSetSelIndexes() Set the selection indexes
PtFSShow() Set the position so that the specified item is visible
PtFSUnselect() Unselect the specified item
PtFSUnselectNonBrothers()
Unselect all items that aren’t siblings of the specified item

© 2010, QNX Software Systems GmbH & Co. KG. PtFSAddAfter()
Insert an item after the specified item
Synopsis:
void PtFSAddAfter( PtWidget_t *fs,
PtFileSelItem_t *item,
PtFileSelItem_t *brother );
Description:
This function inserts a list of items linked with the brother field. PtFSAddAfter()
assumes that item points to a list of items. The fs variable points to a PtFileSel
widget. The new items are added to the specified file selector below the specified
brother.
item tree tree
B 1 1
2 brother 2 brother
3 A item
C
The results of using PtFSAddAfter().
You can call this function with a NULL fs argument, as long as brother points to an
item that isn’t attached to any file selector widget.
Classification:
Photon
Safety
Signal handler No
Thread No

PtFSAddAfter() © 2010, QNX Software Systems GmbH & Co. KG.
See also:
PtFSAddFirst()

© 2010, QNX Software Systems GmbH & Co. KG. PtFSAddFirst()
Add a root item to a file selector tree
Synopsis:
void PtFSAddFirst( PtWidget_t *fs,
PtFileSelItem_t *parent );
Description:
This function adds a list of items linked with the brother field. The parent argument
identifies the parent item for the added items. The new items are added in front of any
existing children of the parent item.
The parent argument may also be NULL, in which case the item is added at the root
level of the file selector before any existing items at the root level. This is what
happens when the Pt_ARG_FS_ROOT_DIR resource is set.
item tree tree
B 1 parent 1 parent
2 A item
3
2
3
The results of using PtFSAddFirst().
You can call this function with a NULL fs argument, as long as parent points to an item
that isn’t attached to any file selector widget.
PtFSAddFirst() automatically sets the Pt_TREE_ITEM_EXPANDABLE flag in the
parent item.
Classification:
Photon
Safety
Signal handler No
continued. . .

PtFSAddFirst() © 2010, QNX Software Systems GmbH & Co. KG.
Safety
Thread No
See also:
PtFSAddAfter(), PtFSRootItem()

© 2010, QNX Software Systems GmbH & Co. KG. PtFSAllItems()
Fill a buffer with pointers to all items
Synopsis:
PtFileSelItem_t **PtFSAllItems(
PtWidget_t *widget,
PtFileSelItem_t **buffer );
Description:
This function fills a buffer with pointers to all items in the widget.
If buffer is NULL, the function allocates a buffer using malloc(), and terminates it with
a NULL entry. It’s your application’s responsibility to free the buffer when it’s no
longer needed.
If buffer isn’t NULL, the function doesn’t add a NULL to the end of it.
Returns:
A pointer to the buffer.
Classification:
Photon
Safety
Signal handler No
Thread No

PtFSAllocItem() © 2010, QNX Software Systems GmbH & Co. KG.
Create an item for a PtFileSel widget
Synopsis:
PtFileSelItem_t * PtFSAllocItem(
PtFileSelWidget_t *fs,
int type,
char const *info );
Description:
You can use this function to create a PtFileSelItem_t for the PtFileSel widget.
It’s useful if your application can display items that aren’t physically part of the
filesystem. The parameters are as follows:
type The type of item you’re creating:

• Pt_FS_DIR_OP — open directory
• Pt_FS_DIR_CL — closed directory
• Pt_FS_DLINK_OP — open directory link
• Pt_FS_DLINK_CL — closed directory link
• Pt_FS_FILE — file
• Pt_FS_FLINK — file link
• Pt_FS_ERROR — file with an error
This must contain a valid file type and is used to display the item’s image.
info The string that’s displayed in the tree for the item. It should contain all the
information required, such as name, size, and date. The information should
be separated by tabs and in the same order as the format string. For example,
if your format is "nso" (name, size, owner), you should pass something like
"bob\t100\towner" as info.
An item pointer is returned. If you wish to store any information in the item, use the
item->fullpath character pointer. It’s used in most items to store the full path of the
item, but this function initializes it to NULL.
Returns:
The allocated item pointer if successful, or NULL if an error occurred.
Examples:
Suppose you wish to add your own item. In the state callback, you can check the
item’s fullpath to see if it’s the one you want to deal with and if so, add your own
items afterwards. Just return Pt_END from the Pt_FS_STATE_START callback to
prevent the widget from doing the expansion.

© 2010, QNX Software Systems GmbH & Co. KG. PtFSAllocItem()
/* State callback. Use the reason to block the widget for

large directory opens. */
int state_cb( PtWidget_t *widget,
struct fs_dialog_modal *user,
{
PtArg_t args[3];
PtFileSelCallback_t *it;
PtFileSelItem_t *new_item;
it = (PtFileSelCallback_t *)(info->cbdata);
if (it->reason == Pt_FS_STATE_START) {
PtSetArg(&args[0], Pt_ARG_FLAGS, Pt_BLOCKED,
Pt_BLOCKED);
Ph_CURSOR_CLOCK, 0);
if ((strcmp(it->item->fullpath, "/Gamma") == 0) &&

(info->reason_subtype == Pt_TREE_EXPANDING)) {
it->item->type = Pt_FS_DIR_OP;
PtFSDamageItem(fs, it->item);
new_item = PtFSAllocItem(fs, Pt_FS_FILE,
"Fred Flintstone");
PtFSAddFirst(fs, new_item, it->item);
return (Pt_END);
}
} else {
PtSetArg(&args[0], Pt_ARG_FLAGS, ˜Pt_BLOCKED,
Pt_BLOCKED);
Ph_CURSOR_INHERIT, 0);
}
PtSetResources(widget, 2, args);
}
Classification:
Photon
Safety
Signal handler No
Thread No

PtFSClearSelection() © 2010, QNX Software Systems GmbH & Co. KG.
Clear the selection
Synopsis:
void PtFSClearSelection( PtWidget_t *widget );
Description:
This function clears the selection.
Classification:
Photon
Safety
Signal handler No
Thread No

© 2010, QNX Software Systems GmbH & Co. KG. PtFSDamageItem()
Redraw an item in the file selector
Synopsis:
void PtFSDamageItem( PtWidget_t *fs,
PtFileSelItem_t *item );
Description:
Call this function to redraw an item when its data has changed.
Classification:
Photon
Safety
Signal handler No
Thread No

PtFSExpandParents() © 2010, QNX Software Systems GmbH & Co. KG.
Expand an item’s collapsed ancestors
Synopsis:
void PtFSExpandParents( PtWidget_t *fs,
PhEvent_t *event );
Description:
This function tries to expand any collapsed ancestors of the given item. The event is
passed to PtFSFolderExpand().
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtFSFolderCollapse()
Collapse an expandable item (directory)
Synopsis:
void PtFSFolderCollapse( PtWidget_t *fs,
PhEvent_t *event );
Description:
This function collapses the given item. The item must be expandable, i.e. a directory
item. The fs argument must point to the file selector that contains the item or be NULL
if the item doesn’t belong to any file selector.
If fs isn’t NULL, its Pt_CB_FS_STATE callback is invoked. The event argument is
passed to the callback.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

PtFSFolderExpand() © 2010, QNX Software Systems GmbH & Co. KG.
Expand an expandable item (directory)
Synopsis:
int PtFSFolderExpand( PtWidget_t *fs,
PhEvent_t *event );
Description:
This function expands the given item. The fs argument must point to the file selector
that contains the item or be NULL if the item doesn’t belong to any file selector.
If fs isn’t NULL, its Pt_CB_FS_STATE callback is invoked. The event argument is to
the callback. If the item isn’t expanded, the return value reflects that.
Returns:
0 Success.
Pt_END The item couldn’t be expanded.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtFSFreeAllItems()
Unlink and free all items
Synopsis:
void PtFSFreeAllItems( PtWidget_t const *fs );
Description:
This function unlinks and frees all items in the PtFileSel widget. Note that this
function is called automatically when a PtFileSel widget is destroyed.
Classification:
Photon
Safety
Signal handler No
Thread No

PtFSFreeItems() © 2010, QNX Software Systems GmbH & Co. KG.
Free an unlinked item
Synopsis:
void PtFSFreeItems( PtFileSelItem_t *item );
Description:
This function frees the subtree item (the item together with its brothers and their
children). The function assumes that the items don’t belong to any file selector—use
PtFSRemoveChildren(), PtFSRemoveItem(), or PtFSRemoveList() to remove the
subtree items from a file selector widget before freeing the subtree.
Classification:
Photon
Safety
Signal handler No
Thread No

© 2010, QNX Software Systems GmbH & Co. KG. PtFSGetCurrent()
Get the current item
Synopsis:
PtFileSelItem_t *PtFSGetCurrent(
PtWidget_t const *widget );
Description:
This function returns a pointer to the current item (see “Current item” in the
description of PtGenList).
Classification:
Photon
Safety
Signal handler No
Thread No

PtFSGetSelIndexes() © 2010, QNX Software Systems GmbH & Co. KG.
Fill a buffer with indexes
Synopsis:
unsigned short *PtFSGetSelIndexes(
PtWidget_t *widget,
unsigned short *buffer );
Description:
This function fills a buffer with indexes of all the selected items in the PtFileSel
widget. The first item in the widget has an index of 1, not 0.
If buffer is NULL, the function allocates a buffer using malloc(), and the buffer is
zero-terminated.
If buffer is non-NULL, the function adds zero to the end only if there are no selected
items in the widget.
Returns:
Classification:
Photon
Safety
Signal handler No
Thread No

© 2010, QNX Software Systems GmbH & Co. KG. PtFSGoto()
Set the current item
Synopsis:
void PtFSGoto( PtWidget_t *fs,
Description:
This function sets the current item and (if necessary) the current position so that the
new current item is visible (see “Current item” in the description of PtGenList).
If item is NULL, there will be no current item.
Classification:
Photon
Safety
Signal handler No
Thread No

PtFSItemIndex() © 2010, QNX Software Systems GmbH & Co. KG.
Calculate the index of the given item within the file selector
Synopsis:
int PtFSItemIndex( PtFileSelWidget_t const *fs,
PtFileSelItem_t const *item );
Description:
This function calculates the index of the given item within the fs. The index of the first
item is 1.
Returns:
The index of the given item.
Classification:
Photon
Safety
Signal handler No
Thread No

© 2010, QNX Software Systems GmbH & Co. KG. PtFSRemoveChildren()
Unlink the children of the specified item
Synopsis:
PtFileSelItem_t *PtFSRemoveChildren(
Description:
This function unlinks all the children of the specified item and returns the pointer to
the first of them. You can then give the pointer to the PtFSFreeItems() function.
tree tree returned pointer
A item A C
B D
The results of using PtFSRemoveChildren().
This function doesn’t collapse the item. If the children are visible, NULL is returned.
Call PtFSFolderCollapse() before PtFSRemoveItem() to make sure that the item is
collapsed.
Returns:
A pointer to the first child removed.
Classification:
Photon
Safety
Signal handler No
Thread No

PtFSRemoveItem() © 2010, QNX Software Systems GmbH & Co. KG.
Unlink an item
Synopsis:
void PtFSRemoveItem( PtWidget_t *fs,
Description:
This function unlinks the given item together with its children from its parent and
brothers (if any) and sets the item->parent and item->brother fields to NULL.
tree tree item
A A B
B item C
The results of using PtFSRemoveItem().
The fs argument must point to the PtFileSel widget containing the item, or be NULL
if the item doesn’t belong to any file selector.
If fs is NULL and the item has no parent but has a previous brother, the function won’t
be able to find the previous brother and therefore can’t unlink the item from its brother.
The function does nothing if item->parent and fs are both NULL.
PtFSRemoveItem() never clears the Pt_TREE_ITEM_EXPANDABLE flag in the item’s
parent.
Classification:
Photon
Safety
Signal handler No
Thread No

© 2010, QNX Software Systems GmbH & Co. KG. PtFSRemoveList()
Unlink the root item
Synopsis:
void PtFSRemoveList( PtWidget_t *fs,
PtFileSelItem_t *first );
Description:
This function unlinks the item first and its brothers (together with their children) from
their parent (and previous brother) and sets their parent fields to NULL.
tree tree first
A A B
B first C
The results of using PtFSRemoveList().
The fs argument must point to the PtFileSel widget that contains the items, or be
NULL if the items don’t belong to any file selector.
If fs is NULL and first has no parent but has a previous brother, the function won’t be
able to find the previous brother and therefore can’t unlink first from its previous
brother.
Classification:
Photon
Safety
Signal handler No
Thread No

PtFSRootItem() © 2010, QNX Software Systems GmbH & Co. KG.
Return the first root item of the file selector
Synopsis:
PtFileSelItem_t *PtFSRootItem(
PtFileSelWidget_t const *fs );
Description:
This function returns a pointer to the first root item.
Returns:
A pointer to the first root item.
Classification:
Photon
Safety
Signal handler No
Thread No

© 2010, QNX Software Systems GmbH & Co. KG. PtFSSelect()
Select the specified item
Synopsis:
void PtFSSelect( PtWidget_t *widget,
Description:
This function selects the given item.
Classification:
Photon
Safety
Signal handler No
Thread No

PtFSSelectedItems() © 2010, QNX Software Systems GmbH & Co. KG.
Fill a buffer with pointers to the selected items
Synopsis:
PtFileSelItem_t **PtFSSelectedItems(
PtWidget_t *widget,
PtFileSelItem_t **buffer );
Description:
This function fills a buffer with pointers to the currently selected items:
• If buffer is NULL, the function allocates a buffer using malloc(), and the buffer is
NULL-terminated.
• If buffer is non-NULL, the function adds a NULL at the end only if there are no
selected items in the widget.
Returns:
Classification:
Photon
Safety
Signal handler No
Thread No

© 2010, QNX Software Systems GmbH & Co. KG. PtFSSetSelIndexes()
Set the selection indexes
Synopsis:
int PtFSSetSelIndexes( PtWidget_t *widget,
const unsigned short *buffer,
int count );
Description:
This function sets the selection indexes. The function assumes that buffer points to a
sorted array of indexes. The first item in the widget has an index of 1, not 0.
The function returns the number of items that have been actually selected, which may
be smaller than count if the array isn’t sorted or contains duplicate indexes or indexes
that are out of range.
If the selection mode is Pt_RANGE_MODE, only the first index and the count are used.
Returns:
The number of items selected.
Classification:
Photon
Safety
Signal handler No
Thread No

PtFSShow() © 2010, QNX Software Systems GmbH & Co. KG.
Set the position so that the specified item is visible
Synopsis:
void PtFSShow( PtWidget_t *widget,
Description:
This function sets the current position so that the given item is visible. If item is NULL,
the function does nothing. This lets you do something like this:
PtFSShow( widget, PtFSGetCurrent(widget) );
without checking to see if PtFSGetCurrent() returned NULL.
Classification:
Photon
Safety
Signal handler No
Thread No

© 2010, QNX Software Systems GmbH & Co. KG. PtFSUnselect()
Unselect the given item
Synopsis:
void PtFSUnselect( PtWidget_t *widget,
Description:
This function unselects the given item.
PtFSUnselect() doesn’t support the Pt_RANGE_MODE selection mode.
Classification:
Photon
Safety
Signal handler No
Thread No

PtFSUnselectNonBrothers() © 2010, QNX Software Systems GmbH & Co. KG.
Synopsis:
void PtFSUnselectNonBrothers(
PtWidget_t *widget,
Description:
This function unselects all the items that aren’t siblings of the given item. If item is
NULL, the current item (see “Current item” in the description of PtGenList) is used.
Classification:
Photon
Safety
Signal handler No
Thread No

© 2010, QNX Software Systems GmbH & Co. KG. PtFontSel
A widget for selecting font attributes
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtFontSel
PhAB icon:
Public header:
<photon/PtFontSel.h>
Description:
The PtFontSel widget lets you select font attributes.
A PtFontSel widget.
A PtFontSel widget lets you select the:
• font family
• style (italic, bold, underline, double underline, and case)
• font size
• text and background color
The PtFontSel shows sample text that reflects the current font format choices.
New resources:

PtFontSel © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_FONT_DISPLAY unsigned short Flag Pt_FONTSEL_ALL_FONTS
Pt_ARG_FONT_FLAGS unsigned short Flag Pt_FONTSEL_SAMPLE |

Pt_FONTSEL_AA_CHECK
Pt_ARG_FONT_LBL_BKGDCOLOR char * String "Bkgd:"

Pt_ARG_FONT_LBL_FONT char * String "Font:"
Pt_ARG_FONT_LBL_SIZE char * String "Size:"
Pt_ARG_FONT_LBL_STYLE char * String "Style:"
Pt_ARG_FONT_LBL_TEXTCOLOR char * String "Text:"
Pt_ARG_FONT_NAME char * String "TextFont09"
Pt_ARG_FONT_POINT_SIZE_MAX long Scalar 9999
Pt_ARG_FONT_SAMPLE char * String "AaBbCcXxYyZz"
Pt_ARG_FONT_SYMBOL long Scalar ’A’
Pt_ARG_FONT_TEXT_COLOR PgColor_t Scalar Pg_BLACK
Pt_ARG_FONT_TEXT_BKGD_COLOR PgColor_t Scalar Pg_WHITE
Pt_CB_FONT_MODIFY PtCallback_t * Link NULL
Pt_ARG_FONT_DISPLAY
unsigned short Flag Pt_FONTSEL_ALL_FONTS
Flags to filter the inclusion of font families in the selection dialog (see
PtFontSelection() in the Photon Library Reference). You can OR these flags together:
• Pt_FONTSEL_SCALABLE — Include scalable fonts.
• Pt_FONTSEL_BITMAP — Include bitmap fonts.
• Pt_FONTSEL_FIXED — Include fixed-width fonts.
• Pt_FONTSEL_PROP — Include proportional-width fonts.
You can use Pt_FONTSEL_ALL_FONTS to override this filtering.
Pt_ARG_FONT_FLAGS

Flags to modify the appearance of the widget:
• Pt_FONTSEL_SAMPLE — show a sample text string in the current font.
• Pt_FONTSEL_AA_CHECK — allow the use of the anti-aliasing (A/A) button only

for scalable fonts. For normal bitmap fonts, this button is dimmed. However,
external font mapping rules may supplement bitmap fonts with scalable fonts at
certain point sizes, allowing this attribute to be applied.
• Pt_FONTSEL_COLORSEL_BKGD — display a sample of the background color to

be used for the text. If you click on the sample, you can change the color.
• Pt_FONTSEL_COLORSEL_TEXT — display a sample of the color to be used for

the text. If you click on the sample, you can change the color.
Pt_ARG_FONT_LBL_BKGDCOLOR
char * String "Bkgd:"
The label for the background color.
Pt_ARG_FONT_LBL_FONT
char * String "Font:"
The label beside the combo box for choosing the font.
Pt_ARG_FONT_LBL_SIZE
char * String "Size:"
The label used beside the font-size field.
Pt_ARG_FONT_LBL_STYLE
char * String "Style:"
The label used beside the Style combo box.

Pt_ARG_FONT_LBL_TEXTCOLOR

char * String "Text:"
The label for the text color.
Pt_ARG_FONT_NAME
The name of the initial font. This resource also reflects the currently selected font,
style, quality, and size.
Pt_ARG_FONT_POINT_SIZE_MAX
long Scalar 9999
The maximum point size the font selector allows, with a maximum of 9999. If this
resource is set to a size that is smaller than the current font size, the current size is set
to the new maximum.
Pt_ARG_FONT_SAMPLE
char * String "AaBbCcXxYyZz"
The string to be used as a sample display of the font (if the Pt_FONTSEL_SAMPLE
flag is set).
Pt_ARG_FONT_SYMBOL
long Scalar ’A’
A character used to filter the inclusion of font families in the selection dialog. Only
those fonts that define this character are included.
You can use this resource to display only Latin fonts (set it to ’A’) or Cyrillic fonts
(set it to Pk_Cyrillic_IO). You can use the value Pt_FONTSEL_ALL_SYMBOLS to
override this filtering.

Pt_ARG_FONT_TEXT_COLOR

The color of the text. See PgColor_t in the Photon Library Reference.
Pt_ARG_FONT_TEXT_BKGD_COLOR
The background color of the text. See PgColor_t in the Photon Library Reference.
Pt_CB_FONT_MODIFY
A list of PtCallback_t structures that define the callbacks invoked when the
selected font is modified.
resource, these callbacks are also invoked when your application changes the selected
font by calling PtSetResource() or PtSetResources().
following members:
reason Pt_CB_FONT_MODIFY
the callback to be invoked.
cbdata A pointer to the name of the new font selection.


Pt_ARG_CONTAINER_FLAGS PtContainer &=˜Pt_GETS_FOCUS
Pt_ARG_DIM PtWidget
Pt_ARG_FLAGS PtWidget 0
continued. . .


Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
continued. . .


Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
The PtFontSel class defines the following convenience function:
PtFontSelection() Display a modal dialog for selecting a font. See the Photon
Library Reference.

© 2010, QNX Software Systems GmbH & Co. KG. PtGauge
Common resources for gauge-type widgets
Class hierarchy:
PtWidget → PtBasic → PtGauge
• PtMeter
• PtProgress
• PtScrollBar
• PtSlider
PhAB icon:
Public header:
<photon/PtGauge.h>
Description:
The PtGauge superclass provides common resources for gauge-like widgets, which
are capable of displaying a range of values.
New resources:

Pt_ARG_GAUGE_FLAGS short int Flag 0
Pt_ARG_GAUGE_FONT char * String "TextFont09"
Pt_ARG_GAUGE_H_ALIGN unsigned char Scalar Pt_CENTER
Pt_ARG_GAUGE_V_ALIGN unsigned char Scalar Pt_CENTER
Pt_ARG_GAUGE_VALUE long Scalar 0
Pt_ARG_GAUGE_VALUE_PREFIX char * String NULL
Pt_ARG_GAUGE_VALUE_SUFFIX char * String NULL
Pt_ARG_MAXIMUM long Scalar 100
Pt_ARG_MINIMUM long Scalar 0
Pt_ARG_ORIENTATION char Boolean Pt_HORIZONTAL
Pt_CB_GAUGE_VALUE_CHANGED PtCallback_t * Link NULL

PtGauge © 2010, QNX Software Systems GmbH & Co. KG.
Pt_ARG_GAUGE_FLAGS

short int Flag 0
Flags that affect the appearance and behavior of the gauge. Possible values:
Pt_GAUGE_INDETERMINATE
The current value is “unknown.”
Any subclass of PtGauge may observe this bit, but the only
widget that currently does is PtProgress.
Pt_GAUGE_INTERACTIVE
Let the user change the value of the gauge interactively at
runtime (e.g. by dragging). When the value is changed in this
manner, the widget’s Pt_CB_GAUGE_VALUE_CHANGED
Pt_GAUGE_LIVE Alter the widget’s appearance as time passes to indicate that

although the value may not be changing, the application is still
working.
Pt_GAUGE_MAX_ON_TOP
Pt_GAUGE_MAX_ON_LEFT
The position of the maximum value.
Pt_GAUGE_SHOW_VALUE
Display the value of the gauge.
Pt_GAUGE_VALUE_XOR
XOR the value display with the background (i.e. invert the fill
of the typeface).
The default setting for this resource is 0; that is, no flags have been set.
Pt_ARG_GAUGE_FONT

The font used for displaying the value, title, and any other text.
Pt_ARG_GAUGE_H_ALIGN
unsigned char Scalar Pt_CENTER
Controls horizontal alignment. Possible values are:
Pt_LEFT Draw the value aligned to the left edge.
Pt_RIGHT Draw the value aligned to the right edge.
Pt_CENTER Draw the value centered.
Pt_ARG_GAUGE_V_ALIGN
Controls vertical alignment. Possible values are:
Pt_TOP Draw the value aligned with the top edge.
Pt_BOTTOM Draw the value aligned with the bottom edge.
Pt_CENTER Draw the value centered.
Pt_ARG_GAUGE_VALUE
long Scalar 0
The gauge’s current value.
Pt_ARG_GAUGE_VALUE_PREFIX
char * String NULL
Text prefixed to the value displayed. For example, a value of Red: results in Red:35.

Pt_ARG_GAUGE_VALUE_SUFFIX

char * String NULL
Text appended to the value displayed. For example, a value of % results in 35%.
Pt_ARG_MAXIMUM
long Scalar 100
The maximum value of the gauge.
Pt_ARG_MINIMUM
long Scalar 0
The minimum value of the gauge.
Pt_ARG_ORIENTATION
char Boolean Pt_HORIZONTAL
The orientation of the gauge; one of:
• Pt_HORIZONTAL
• Pt_VERTICAL
Pt_CB_GAUGE_VALUE_CHANGED
user changes the value of an interactive gauge (i.e. one that has the
Pt_GAUGE_INTERACTIVE bit set in its Pt_ARG_GAUGE_FLAGS).
resource, these callbacks are also invoked when your application changes the value by
calling PtSetResource() or PtSetResources().


following members:
reason Pt_CB_GAUGE_VALUE_CHANGED
reason_subtype One of the following:

• Pt_GAUGE_DECREMENT, Pt_GAUGE_INCREMENT — the
value decreased or increased by a single unit. The meaning of
a “unit” may be specific to the widget (for example,
Pt_ARG_INCREMENT) but in the absence of such a binding
should be understood to mean 1.
• Pt_GAUGE_MULTIPLE_INCREMENT,
Pt_GAUGE_MULTIPLE_DECREMENT — the value decreased
or increased by a multiple unit. A multiple unit definition is
optional (for example, Pt_ARG_PAGE_INCREMENT) and if
the widget doesn’t define it, callbacks with this subtype don’t
occur.
• Pt_GAUGE_TO_MAX, Pt_GAUGE_TO_MIN — the value has
gone to the maximum or minimum value of the gauge.
• Pt_GAUGE_DRAGGED — the valued changed because of a
drag operation. (In the case of low-bandwidth restrictions, you
can disregard callbacks of this subtype)
• Pt_GAUGE_RELEASED — signals the end of a drag (good for
low-bandwidth restrictions). Since the value is the same as the
last callback of subtype Pt_GAUGE_DRAGGED, you don’t
need to handle this subtype if you’re paying attention to the
Pt_GAUGE_DRAGGED subtypes.
• Pt_GAUGE_JUMP — the gauge has jumped to a new value
(i.e. none of the criteria for the other subtypes has been met).

caused the callback to be invoked, or NULL if the callback was
invoked because your application changed the value and
Pt_CALLBACKS_ACTIVE is set.
cbdata A pointer to a PtGaugeCallback_t structure, which contains at

least:
• long value — the new value for the gauge.


Pt_ARG_DIM PtWidget
continued. . .


Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
continued. . .



© 2010, QNX Software Systems GmbH & Co. KG. PtGenList
Generic superclass for list and tree widgets
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtCompound → PtGenList
• PtGenTree
• PtList
• PtRawList
PhAB icon:
Public header:
<photon/PtGenList.h>
Description:
The PtGenList class is a superclass for creating list widgets. It’s discussed in more
detail in Building Custom Widgets.
PtGenList handles a vertical, left-aligned list of rectangular items that may have
different sizes. You can select one or more items, depending on the selection policy
(see Pt_ARG_SELECTION_MODE).
PtGenListItem_t is the data structure used for the items.
A PtGenList widget can have one child, provided it’s a PtDivider widget. In this
case, PtGenList attaches a callback to the child so that the columns are set
automatically to match the children of PtDivider; the items are drawn below the
divider. Some child classes of PtGenList, such as PtList and PtTree, use Tab
characters as column separators.
Using scrollbars
PtGenList creates a scrollbar if the list’s area isn’t large enough to display all the
items in the list. By default, the vertical scrollbar is displayed only when necessary,
and the horizontal scrollbar is never displayed. You can control this behavior by
setting the scrollbar bits in Pt_ARG_LIST_FLAGS to display a horizontal or vertical
scrollbar always, never, or as required.
You can set or get a limited number of resources (mainly the colors) for the child
PtScrollbar widget by using the list’s Pt_ARG_LIST_SB_RES resource.
Current item
Most of the time, one of the items in a list widget is the current item. (On rare
occasions, a list can have no current item but it can’t have more than one.)
The concept of the current item is similar to the concept of widget focus; typically, the
current item is drawn with a blue dotted line around it when its widget has focus.

PtGenList © 2010, QNX Software Systems GmbH & Co. KG.
When you press Enter or Space, it’s the current item that gets selected; depending on
the widget’s selection mode, this may also unselect any previously selected items
and/or unselect the current item if it was already selected. For more information, see
the description of Pt_ARG_SELECTION_MODE.
Cursor keys change the current item, scroll the list if necessary to make the new
current item visible, and, depending on the widget’s selection mode, may also select
and unselect items. For instance, pressing the ↓ key makes the next item the current
item, and may select the new current item and unselect any previously selected items.
Clicking on an item also makes it the current item and also may select or unselect
items.
Holding down the Ctrl key when you click or press cursor keys will prevent any
changes to the selection if you just want to walk the list without changing the selection.
Mouse actions
Mouse actions depend on the current selection mode.
Button action Result

Press Result depends on the value of Pt_ARG_SELECTION_MODE
Release Invokes callbacks.
Keyboard actions
Keyboard actions depend on the current selection mode.
Key Action
Enter Result depends on value of Pt_ARG_SELECTION_MODE
↑ Previous item
↓ Next item
Pg Up Previous page
Pg Dn Next page
Home First item
End Last item
New resources:


Pt_ARG_LIST_COLUMN_ATTR See below Array NULL
Pt_ARG_LIST_COLUMN_POS PtListColumn_t *, short Array NULL
Pt_ARG_LIST_DNDSEL_COLOR PgColor_t Scalar PgRGB(216, 216, 216)
Pt_ARG_LIST_FLAGS unsigned short Flag See below
Pt_ARG_LIST_FONT char * String "TextFont09"
Pt_ARG_LIST_ITEM_COUNT unsigned short Scalar 0 (read-only)
Pt_ARG_LIST_SB_RES PtArg_t *, int Array None
Pt_ARG_LIST_SCROLL_RATE unsigned char Scalar 2
Pt_ARG_LIST_SEL_COUNT unsigned short Scalar 0 (read-only)
Pt_ARG_LIST_TOTAL_HEIGHT unsigned Scalar 0 (read-only)
Pt_ARG_SCROLLBAR_WIDTH unsigned short Scalar 0 (see below)
Pt_ARG_SELECTION_FILL_COLOR PgColor_t Scalar PgRGB(142, 162, 155)
Pt_ARG_SELECTION_MODE unsigned short Scalar See below
Pt_ARG_SELECTION_TEXT_COLOR PgColor_t Scalar Pg_WHITE
Pt_ARG_TOP_ITEM_POS unsigned short Scalar 1
Pt_ARG_VISIBLE_COUNT unsigned short Scalar 0 (read-only)
Pt_CB_SCROLL_MOVE PtCallback_t * Link NULL
Pt_ARG_LIST_COLUMN_ATTR
PtListColumnAttributes_t *, short Array NULL
An array of PtListColumnAttributes_t structures, each containing at least the

following:
short flags; Flags that define the alignment of the text and other behavior:
• Pt_LIST_COLUMN_ELLIPSIS — If the text doesn’t fit into the
column, draw an ellipsis (...) instead of part of the text, in
accordance with the column’s alignment. For example, if the
column is left-aligned, draw the ellipsis instead of the end of the
text; if the column is right-aligned, draw the ellipsis instead of the
beginning.
• Pt_LIST_COLUMN_ELLIPSIS_MIDDLE — Draw the ellipsis in
the middle of the string. You must also set
Pt_LIST_COLUMN_ELLIPSIS.

• Pt_LIST_COLUMN_ELLIPSIS_INVERT Invert the ellipsis

position. You must also set Pt_LIST_COLUMN_ELLIPSIS.
• Pt_LIST_COLUMN_LEFT
• Pt_LIST_COLUMN_RIGHT
• Pt_LIST_COLUMN_CENTER
• Pt_LIST_COLUMN_DAMAGE_ALWAYS — redraw the column
when the column’s position or size changes, even if it doesn’t
seem necessary.
For example, if a right-aligned column is made narrower but its
right edge doesn’t move, there’s no need to redraw the column.
You can set the flag to force a redraw, which needs to be done if
the column contains some elements that aren’t right-aligned. This
flag is usually set by the child class of PtGenList that knows
what’s drawn in the columns.
• Pt_LIST_COLUMN_NO_STRING — if set,
PtGenListDrawString() skips over this column.
Pt_ARG_LIST_COLUMN_POS
PtListColumn_t *, short Array NULL
An array of PtListColumn_t column structures. The structure contains at least the

following:
short from, to; They define the positions of the left and right edges of the
column (relative to the left edge of widget’s canvas).
Pt_ARG_LIST_DNDSEL_COLOR
PgColor_t Scalar PgRGB(216, 216, 216)
The selection color in a drag-and-drop operation. See PgColor_t in the Photon

Library Reference.
Pt_ARG_LIST_FLAGS

Flags that control the appearance and behavior of the list. The possible values are:
Pt_LIST_BALLOON_AS_REQUIRED
Show a balloon if the contents of the list are clipped.
Pt_LIST_BALLOONS_IN_COLUMNS (on by default)

Display balloons for individual columns, not the entire row.
Pt_LIST_BOUNDARY_KEY_EVENTS
If this flag is clear (the default), cursor key events (↑, ↓, Pg Up,
Pg Down, Home, and End) are always consumed by the widget.
If this flag is set, a cursor key event is consumed only if it actually
changes the current item. For example, an ↑ or Home event isn’t
consumed if the first item in the list is already the current item.
Pt_LIST_HEADER_AUTORESIZE
Adjust the width of the PtDivider widget (if there is one) when
the scrollbar is realized or unrealized.
Pt_LIST_NO_COLUMN_LINES
Don’t display the lines that separate the columns in the list.
Pt_LIST_NON_SELECT
Make the list read-only.
Pt_LIST_HSCROLLBAR_ALWAYS
Always display a horizontal scrollbar.
Pt_LIST_HSCROLLBAR_NEVER (on by default)

Never display a horizontal scrollbar.
Pt_LIST_HSCROLLBAR_AS_REQUIRED (on by default)

Display a horizontal scrollbar only if required.
Pt_LIST_VSCROLLBAR_ALWAYS
Always display a vertical scrollbar.
Pt_LIST_VSCROLLBAR_NEVER (on by default)

Never display a vertical scrollbar.
Pt_LIST_VSCROLLBAR_AS_REQUIRED (on by default)
Display a vertical scrollbar only if required.

Pt_LIST_SCROLLBAR_AUTORESIZE
If the list contains a PtDivider header, resize the vertical
scrollbar so as to align the top of the scrollbar with the bottom of
the divider. If this flag isn’t set, the top of the scrollbar aligns with
the top of the list, regardless of header size.
Pt_LIST_SCROLLBAR_ALWAYS, Pt_LIST_SCROLLBAR_NEVER,
Pt_LIST_SCROLLBAR_AS_REQUIRED
Deprecated — use the corresponding Pt_LIST_VSCROLLBAR*
flags.
Pt_LIST_SCROLLBAR_GETS_FOCUS
Let the vertical scrollbar get focus.
Pt_LIST_SHOW_BALLOON
Show list balloons.
Pt_LIST_SNAP Make the list snap to fit the number of items. Note that the
Pt_LIST_SNAP flag is cleared automatically if the items in the list
don’t have equal heights.
Pt_LIST_STRETCH_HEADER
Make the PtDivider list header at least as wide as the list
canvas. For example, if Pt_LIST_VSCROLLBAR_AS_REQUIRED
is set, and a visible vertical scrollbar disappears because the list
changes, the header is stretched to fit the list, if required.
Pt_ARG_LIST_FONT
The font used for the items in the list.
Pt_ARG_LIST_ITEM_COUNT (read-only)
The number of items.
Pt_ARG_LIST_SB_RES

An array of PtArg_t structures (see the Photon Library Reference) that are passed to
the list’s child PtScrollbar. Note that you can modify only a selected set of the
scrollbar’s resources:
Scrollbar resource Inherited from

Pt_ARG_MIN_SLIDER_SIZE PtScrollbar
The PtGenList widget doesn’t let you modify resources that might affect the
position or size of the scrollbar. The main purpose of this resource is to change the
colors of the scrollbar.
To get the Pt_ARG_LIST_SB_RES resource, your application must supply a buffer
and pass its address and length to the PtSetArg() macro. For example, this code for a
PtScrollbar widget:
PtGetResources( scrollbar, N, args );
is equivalent to this when the scrollbar is part of a PtGenList:
PtArg_t tmp;
PtSetArg( &tmp, Pt_ARG_LIST_SB_RES, args, N );
PtGetResources( list, 1, &tmp );
Pt_ARG_LIST_SCROLL_RATE
If you drag in a list and move outside the widget, the list scrolls at a rate determined by
the number of “button repeats”. This resource specifies the number of button repeats
that must be received before scrolling occurs. The default value is 2. To make the

scrolling faster, set this resource to 1; to make scrolling slower, set this resource to a
larger number.
Pt_ARG_LIST_SEL_COUNT (read-only)
The number of selected items.
Pt_ARG_LIST_TOTAL_HEIGHT (read-only)
unsigned Scalar 0
The total height (in pixels) of all items.
Pt_ARG_SCROLLBAR_WIDTH
unsigned short Scalar 0 (see below)
The width of the accompanying scrollbar, if displayed. The minimum width is 6

pixels. If you set this resource to 0, the default width of 15 is used.
Pt_ARG_SELECTION_FILL_COLOR
PgColor_t Scalar PgRGB(142, 162, 155)
The fill color for selected items. See PgColor_t in the Photon Library Reference.
Pt_ARG_SELECTION_MODE
unsigned short Scalar See below
The selection mode. PtGenList lets you select items using the mouse or the
keyboard. The descriptions below assume you’re using a mouse. If a mouse isn’t
available, you can use the ↑ and ↓ keys on the numeric keypad to highlight items in a
list. The widget accepts the current selection when you press Enter.
Pt_BROWSE_MODE (default)
To select an item using the mouse, either click on an item or drag the pointer
down the list and release the mouse button when the correct item is highlighted.
You can select only one item. If you drag the mouse, the list can scroll.

Pt_MULTIPLE_MODE
To select multiple items using the mouse, click on more than one item. When
you click on a selected item, the item becomes unselected.
Pt_EXTENDED_MODE
Support click-Shift-click/drag and Ctrl-click combinations to select multiple
items. To select all items between and including two items in a list, click on the
first item, press the Shift key, then click on or drag to any other item in the list.
To select multiple disjoint items, hold down the Ctrl while clicking on selected
items.
Pt_SINGLE_MODE
To select an item, point to the item, then click the mouse button. You can select
only one item; if you select a second one, the first becomes unselected.
Pt_RANGE_MODE
To select a range of items, point to the first item, drag to the last item in the
range, then release the mouse button. When you’re dragging the mouse, the list
can scroll.
The PtGenList widget supports several “predefined” selection modes, but you can
also set “compose selection modes” using special flag values. To define a compose
mode, start with one of the following values, which describe what kind of sets of items
can be selected:
Pt_SELECTION_MODE_SINGLE
Select up to one item.
Pt_SELECTION_MODE_NONE
Callback functions take care of selecting items.
Pt_SELECTION_MODE_MULTIPLE
Each item can be selected independently.
Pt_SELECTION_MODE_RANGE
A range of items can be selected.
You can OR one of these values with zero or more of the following flags, which
describe how the mouse and keyboard should work:
Pt_SELECTION_MODE_NOMOVE
Don’t move the current item when you drag the mouse.
Pt_SELECTION_MODE_NOSCROLL
Don’t scroll the widget if you drag the mouse above or below the widget.

Pt_SELECTION_MODE_NOREST
Don’t restore the previous state if you release the mouse outside the widget.
Pt_SELECTION_MODE_NOCLEAR
If you click on an item, don’t clear the previous selection (use with
Pt_SELECTION_MODE_MULTIPLE mode only).
Pt_SELECTION_MODE_AUTO
The keyboard automatically selects the current item (unless you’re pressing Ctrl).
Pt_SELECTION_MODE_NOFOCUS
If the Pt_SELECTION_MODE_AUTO flag is set, don’t select the current item
automatically when the widget gets focus.
Pt_SELECTION_MODE_TOGGLE
You can unselect an item by clicking on it (Pt_SELECTION_MODE_SINGLE and
Pt_SELECTION_MODE_MULTIPLE modes only).
Note that zero isn’t a valid value for the selection mode; neither is a mixture of
predefined and compose values.
The “predefined” selection modes are equivalent to the following compose modes:
For Pt_BROWSE_MODE:
Pt_SELECTION_MODE_SINGLE | Pt_SELECTION_MODE_AUTO
For Pt_MULTIPLE_MODE:
Pt_SELECTION_MODE_MULTIPLE | Pt_SELECTION_MODE_NOMOVE |
Pt_SELECTION_MODE_NOCLEAR | Pt_SELECTION_MODE_TOGGLE |
Pt_SELECTION_MODE_NOSCROLL
For Pt_EXTENDED_MODE:
Pt_SELECTION_MODE_MULTIPLE | Pt_SELECTION_MODE_AUTO |
Pt_SELECTION_MODE_NOMOVE | Pt_SELECTION_MODE_NOFOCUS
For Pt_SINGLE_MODE:
Pt_SELECTION_MODE_SINGLE | Pt_SELECTION_MODE_NOCLEAR
For Pt_RANGE_MODE:
Pt_SELECTION_MODE_RANGE | Pt_SELECTION_MODE_AUTO |
Pt_SELECTION_MODE_NOFOCUS
Pt_ARG_SELECTION_TEXT_COLOR

The text color for selected items. See PgColor_t in the Photon Library Reference.
Pt_ARG_TOP_ITEM_POS
The item index that appears at the top of the list. (The first item is 1.)
Pt_ARG_VISIBLE_COUNT (read-only)
The number of items currently visible.
Pt_CB_SCROLL_MOVE
when the top item position changes.
resource, these callbacks are also invoked when your application changes the top item
position (Pt_ARG_TOP_ITEM_POS) by calling PtSetResource() or
PtSetResources().
following members:
reason Pt_CB_SCROLL_MOVE
reason_subtype Defines the source of the position change:
Pt_LIST_SCROLL_SCROLLBAR
The scrollbar was used.
Pt_LIST_SCROLL_LIST
The list was used directly.

cbdata A pointer to a PtScrollbarCallback_t structure that

unsigned action; A value indicating what happened — see

below.
int position; A value corresponding to the handle’s
location.
The action field can be one of the following:
Pt_SCROLL_DECREMENT
The scrollbar handle position has been decreased by one
increment.
Pt_SCROLL_INCREMENT
The handle position has been increased by one increment.
Pt_SCROLL_PAGE_INCREMENT
The handle position has been increased by one page.
Pt_SCROLL_PAGE_DECREMENT
The handle position has been decreased by one page.
Pt_SCROLL_TO_MAX
The handle has been moved to the maximum value.
Pt_SCROLL_TO_MIN
The handle has been moved to the minimum value.
Pt_SCROLL_DRAGGED
The handle is being dragged.
Pt_SCROLL_RELEASED
The handle has been released after having been dragged.
Pt_SCROLL_SET The change of position is the result of a call to PtSetResources()

and the widget has the Pt_CALLBACKS_ACTIVE bit set in its
Pt_ARG_FLAGS resource.
Pt_SCROLL_JUMP You jumped to a specific location by Ctrl-clicking on the

scrollbar.


Pt_ARG_DIM PtWidget
Pt_ARG_FLAGS PtWidget |= Pt_HIGHLIGHTED |
Pt_ETCH_HIGHLIGHT | Pt_SET |
Pt_GETS_FOCUS | Pt_FOCUS_RENDER
continued. . .


Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
continued. . .


Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
Pt_CB_DND
For Pt_CB_DND callbacks for a PtGenList, the cbinfo->cbdata is a pointer to a
PtListDndCallback_t structure, containing at least the following members:
PtGenListItem_t *item
The target item involved in the drag-and-drop operation.
unsigned long flags

Possible values:
the item.
below the item.
If neither of these is set, the drop occurred inside the item.

The following convenience functions and data structure are useful when working with
descendants of PtGenList:

In general, the subclass specifies which of the convenience functions you can use. For
example, PtList and PtTree don’t let you call any of the PtGenList convenience
functions except the ones that are redefined as their own convenience functions.
PtGenListAddItems()
Add items to a list.
PtGenListAllItems() Get pointers to all the items in a list.
PtGenListClearSelection()
Clear the selection.
PtGenListCreateTextBalloon()
Create a popup balloon for an item in the list.
PtGenListDamageItem()
Redraw an item when its data has been changed.
PtGenListDrawBackground()
Draw the background of a list.
PtGenListDrawString()
Draw a string.
PtGenListFirstItem()
Return a pointer to the first item in a list.
PtGenListGetCurrent()
Return a pointer to the current item in a list.
PtGenListGetSelIndexes()
Get the indexes of the selected items.
PtGenListGoto() Set the current item so that the new current item is visible.
PtGenListHold() Prevent visible repair of a list widget.
PtGenListItem_t PtGenList item structure
PtGenListItemIndex()
Find the index of an item.
PtGenListItemRealloc()
Reallocate memory for an item.
PtGenListLastItem() Return a pointer to the last item in a list.

PtGenListLockItem()
Lock an item so it can be resized.
PtGenListRelease() Release a hold on visible repairs of a list widget.
PtGenListRemoveItems()
Remove items from a list.
PtGenListResize() Resize a list widget.
PtGenListSelect() Select an item in a list.
PtGenListSelectedItems()
Get pointers to the selected items.
PtGenListSetColumnBalloon()
Adjust the balloon text to correspond to a given column.
PtGenListSetGflags()
Modify the gflags field of the widget.
PtGenListSetSelIndexes()
Set the selection indexes.
PtGenListShow() Set the current position so a given item is visible.
PtGenListUnlockItem()
Unlock an item so it can be updated.
PtGenListUnselect() Unselect an item in a list.
The following convenience functions are useful only if you’re creating a custom list
widget; they’re described in the Creating a List Widget chapter of Building Custom
Widget:
PtSuperClassGenListDraw()
Invoke the Draw List method in a superclass.
PtSuperClassGenListInflate()
Invoke the List Inflate method in a superclass.
PtSuperClassGenListKey()
Invoke the List Key method in a superclass.
PtSuperClassGenListMouse()
Invoke the List Mouse method in a superclass.
PtSuperClassGenListSelect()
Invoke the List Select method in a superclass.

PtGenListAddItems() © 2010, QNX Software Systems GmbH & Co. KG.
Add items to a list
Synopsis:
void PtGenListAddItems( PtWidget_t *list,
PtGenListItem_t *items,
PtGenListItem_t *after );
Description:
This function adds items to the PtGenList widget pointed to by list. The arguments
are:
items A pointer to a list of PtGenListItem_t structures linked with the next

field (the prev field is ignored).
after If after is NULL, add the items at the beginning of the list. If after isn’t
NULL, it must point to an item in the widget and items is added after that
item.
In all selection modes except Pt_SELECTION_MODE_RANGE, if there’s no current

item in the widget and some of the added items have the Pt_LIST_ITEM_CURRENT
flag set, the first of them becomes the current item (see “Current item” in the
description of PtGenList). In all other items, the flag is cleared.
If no item is currently selected and the mode is set to Pt_SELECTION_MODE_SINGLE,
the first of the added items having the Pt_LIST_ITEM_SELECTED flag set becomes the
selected item. This flag on all other items is cleared.
In Pt_SELECTION_MODE_MULTIPLE mode and Pt_SELECTION_MODE_NONE
mode, all items with the Pt_LIST_ITEM_SELECTED flag are selected.
In Pt_SELECTION_MODE_RANGE mode, the behavior depends on whether there’s a
selected range in the widget and how the after item is located relative to the selected
range. In particular, if you remove a range of items and then reinsert them in the same
place, the selected range is restored. However, the “direction” of the range may be
reversed.
If no items are selected in Pt_SELECTION_MODE_RANGE mode but a range of added
items has the Pt_LIST_ITEM_SELECTED flag set, these items become the selected
range. The first or last item in this range becomes the current item, depending on the
setting of the Pt_LIST_ITEM_CURRENT flag of the first selected item.
Classification:
Photon
Safety
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtGenListAddItems()
Safety
Signal handler No
Thread No
See also:
PtGenList, PtGenListItem_t

PtGenListAllItems() © 2010, QNX Software Systems GmbH & Co. KG.
Get pointers to all the items in a list
Synopsis:
PtGenListItem_t **PtGenListAllItems(
PtWidget_t *widget,
PtGenListItem_t **buffer );
Description:
This function fills the given buffer with pointers to all the list items.
If buffer is NULL, the function allocates a buffer by calling malloc(), and the buffer is
NULL-terminated (or zero-terminated). It’s your application’s responsibility to free the
buffer when it’s no longer needed.
If buffer isn’t NULL, the function doesn’t add a NULL or zero to the end.
Returns:
A pointer to a buffer containing pointers to all the items in the list, or NULL.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtGenListClearSelection()
Clear the selection
Synopsis:
void PtGenListClearSelection( PtWidget_t *widget );
Description:
This function clears the selection of the given PtGenList widget.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtGenList

PtGenListCreateTextBalloon() © 2010, QNX Software Systems GmbH & Co. KG.
Create a popup balloon for a list item
Synopsis:
PtWidget_t *PtGenListCreateTextBalloon(
PtWidget_t *widget,
PtWidget_t *parent,
const PhArea_t *area,
const char *string,
int column,
const char *font);
Description:
This function creates a PtLabel widget to be used as a popup balloon for a list item.
The arguments are as follows:
widget A pointer to the PtGenList widget.
parent A pointer to the widget’s parent window.
area A pointer to a PhArea_t structure to use as the Pt_ARG_AREA resource

for the balloon.
string The string to display in the balloon.
column The number of the column to extract from the string (see below).
font The font to use for the label. If this is NULL, use the same font as the
PtGenList widget.
The string consists of columns separated by tab characters. The column argument
selects a column, with 0 or a negative number indicating the column at the beginning
of the string, 1 indicating the characters after the first tab, and so on. For example, if
column is 1 and string is "One\tTwo\tThree", the label contains the string "Two".
Returns:
A pointer to the PtLabel widget.
Classification:
Photon
Safety
Signal handler No
Thread No

© 2010, QNX Software Systems GmbH & Co. KG. PtGenListCreateTextBalloon()
See also:
PhArea_t in the Photon Library Reference

PtGenListDamageItem() © 2010, QNX Software Systems GmbH & Co. KG.
Redraw an item when its data has been changed
Synopsis:
void PtGenListDamageItem( PtWidget_t *list,
PtGenListItem_t *item );
Description:
Call this function to redraw the item when its data has been changed. If the size
changes too, use PtGenListLockItem() and PtGenListUnlockItem() instead.
If you’re modifying more than one item, you should use PtGenListHold() and
PtGenListRelease() to avoid multiple calls to the Draw method.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtGenListDrawBackground()
Draw the background of a list
Synopsis:
void PtGenListDrawBackground(
PtWidget_t *list,
PtGenListItem_t const *items,
unsigned nitems,
PhRect_t const *where,
int lmarg,
int rmarg,
int tmarg,
int bmarg );
Arguments:
list The widget pointer.
items A pointer to the PtGenListItem_t structure for the first item that needs
to be redrawn.
nitems The number of items the function should look at.
where A pointer to a PhRect_t structure (see the Photon Library Reference) that
defines the extent of the items.
lmarg, rmarg, tmarg, bmarg
These arguments define additional “margins” on the left, right, top, and
bottom — by setting them to a positive value, you can shorten the
selection bar.
Description:
This function can be used by a child class of PtGenList for drawing the background.
If the Pt_GEN_LIST_SHOW_DAMAGED bit is set in list->gflags, the function draws
only the background for damaged items.
To determine the color it uses to draw the background, PtGenListDrawBackground()
calls the List Attributes method for the list widget.
Classification:
Photon
Safety
Signal handler No
Thread No

PtGenListDrawBackground() © 2010, QNX Software Systems GmbH & Co. KG.
See also:
PhRect_t in the Photon Library Reference

© 2010, QNX Software Systems GmbH & Co. KG. PtGenListDrawString()
Draw a string
Synopsis:
void PtGenListDrawString( PtWidget_t *list,
PtGenListItem_t const *item,
const char *string,
int lmarg,
int rmarg );
Arguments:
list A pointer to the list widget. This should be the same as that used in
the list argument of the List Draw method.
item A pointer to a PtGenListItem_t structure, which describes the

item in the list widget you want to draw the string for.
string The string to display. Any Tab characters in the string are
interpreted as column separators.
where A pointer to a PhRect_t structure (see the Photon Library

Reference) that defines the rectangle in which the text is positioned.
The x values for the rectangle should be the same as those used in
the where argument of the List Draw method. The y values define
the vertical position of the string to be drawn between the given
values.
lmarg, rmarg Define additional margins. The value of lmarg is added to the from
value of the first column, and rmarg is subtracted from the to value
of the last column. If the widget doesn’t have columns, the width of
the widget’s canvas is used as a column.
Description:
This function can be used by a child class of PtGenList for drawing strings.
To determine the font and colors it uses to draw a string, PtGenListDrawString() calls
the List Attributes method for the list widget.
Examples:
Here’s an excerpt showing the List Draw method of a widget (taken from PtList):
static PtGenListDrawF_t list_draw;
static void list_draw(

PtWidget_t *const widget, PtGenListItem_t *items,
unsigned index, unsigned nitems, PhRect_t *where
) {
const int item_height = items->size.h;
PtGenListDrawBackground( widget, items, nitems, where, 0, 0, 0, 0 );

PtGenListDrawString() © 2010, QNX Software Systems GmbH & Co. KG.
do {
short bot;
bot = where->ul.y + item_height;
if ( items->flags & Pt_LIST_ITEM_DAMAGED ) {
where->lr.y = bot - 1;
PtGenListDrawString( widget, items, STRING(items),
where, 0, 0 );
}
where->ul.y = bot;
items = items->next;
} while ( --nitems );
}
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtGenListFirstItem()
Return a pointer to the first item in a list
Synopsis:
PtGenListItem_t *PtGenListFirstItem(
PtWidget_t const *list );
Description:
This function returns a pointer to the first item in the given list.
Returns:
A pointer to the first item.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

PtGenListGetCurrent() © 2010, QNX Software Systems GmbH & Co. KG.
Return a pointer to the current item in a list
Synopsis:
PtGenListItem_t *PtGenListGetCurrent(
PtWidget_t const *widget );
Description:
This function returns a pointer to the current item in the given list (see “Current item”
in the description of PtGenList).
Returns:
A pointer to the current item.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtGenListGetSelIndexes()
Get the indexes of the selected items
Synopsis:
unsigned short *PtGenListGetSelIndexes(
PtWidget_t *widget,
Description:
This function fills the given buffer with the indexes of the currently selected items.
The first item in the list has an index of 1, not 0.
If buffer is NULL, the function allocates a buffer using malloc(), and terminates the
buffer with a zero. It’s your application’s responsibility to free the buffer when it’s no
longer needed.
If buffer isn’t NULL, the function adds a 0 to the end only if there are no selected items.
Returns:
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtGenList

PtGenListGoto() © 2010, QNX Software Systems GmbH & Co. KG.
Set the current item so that the new current item is visible
Synopsis:
void PtGenListGoto( PtWidget_t *list,
Description:
If you pass item as NULL, there isn’t a current item.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtGenListHold()
Prevent visible repair of a list widget
Synopsis:
void PtGenListHold( PtWidget_t *widget );
Description:
This function is a list-aware version of the PtHold() function. After a call to
PtGenListHold(), the PtGenListDamageItem() function simply sets the
Pt_LIST_ITEM_DAMAGED flag in the item instead of calling PtDamageExtent().
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtGenListRelease()
PtDamageExtent(), PtHold() in the Photon Library Reference

PtGenListItem_t © 2010, QNX Software Systems GmbH & Co. KG.
PtGenList item structure
Synopsis:
typedef struct Pt_genlist_item {
unsigned flags;
PhDim_t size;
PtGenListItem_t *next, *prev;
} PtGenListItem_t;
Description:
This data structure describes an item in a PtGenList widget.
Applications should view this as a read-only structure; subclasses usually define ways
to modify PtGenListItem_t members.
The members include at least:
flags The state of the item:
Pt_LIST_ITEM_SELECTED
This item is selected.
Pt_LIST_ITEM_CURRENT
This item is the current item (see “Current item” in the
Pt_LIST_ITEM_DAMAGED
This item should be redrawn.
Pt_LIST_ITEM_ABOVE
This item is above the visible range of items. Use the
Pt_ARG_TOP_ITEM_POS resource to scroll the list.
Pt_LIST_ITEM_BELOW
This item is below the visible range of items. Use the
Pt_ARG_TOP_ITEM_POS resource to scroll the list.
Pt_LIST_ITEM_INWIDGET
The item has been added to a widget.
Pt_LIST_ITEM_FLAG_USER1
Flags that you can use for any purpose in your application. The
widgets don’t use these flags.
The Pt_LIST_ITEM_USED_FLAGS macro defines the flags used by the

PtGenList widget. The remaining bits are available for the child
class.

© 2010, QNX Software Systems GmbH & Co. KG. PtGenListItem_t
It’s safe to set only the following item flags before adding the item to a
widget — they’re preserved if they don’t conflict with the current state
of the widget:
Preserved unless the selection mode is Pt_SINGLE_MODE and
another item is already selected.
Preserved unless there’s already a current item in the widget.
Don’t modify these flags directly after the item is in a list; they’re set
and cleared by the convenience functions.
size A PhDim_t structure (see the Photon Library Reference) that defines
the width and height of the item. If the widget has columns, the widths
of the items are ignored.
next, prev The widget uses these links to find the next and previous items in the
list.
Classification:
Photon
See also:
PtGenList, PtGenTree, PtGenTreeItem_t, PtList, PtTreeItem_t
PhDim_t in the Photon Library Reference
Building Custom Widgets

PtGenListItemIndex() © 2010, QNX Software Systems GmbH & Co. KG.
Find the index of an item
Synopsis:
int PtGenListItemIndex(
PtWidget_t const *list,
PtGenListItem_t const *item );
Description:
This function calculates the index of the given item within the list. The index of the
first item is 1.
Returns:
The index of the given item.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtGenListItemRealloc()
Reallocate memory for an item
Synopsis:
PtGenListItem_t *PtGenListItemRealloc(
PtGenListItem_t *item,
PtWidget_t *list,
size_t size );
Description:
This function isn’t used by the PtGenList widget itself. It may be used to reallocate
memory if the item was allocated using malloc().
The given size should include the size of the PtGenListItem_t structure. If the item
is moved to a different address by the realloc() function, PtGenListItemRealloc()
repairs the list links.
Returns:
A pointer to the reallocated item.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

PtGenListLastItem() © 2010, QNX Software Systems GmbH & Co. KG.
Return a pointer to the last item in a list
Synopsis:
PtGenListItem_t *PtGenListLastItem(
PtWidget_t const *list );
Description:
This function returns a pointer to the last item in the list.
Returns:
A pointer to the last item.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtGenListLockItem()
Lock an item so it can be resized
Synopsis:
void PtGenListLockItem( PtWidget_t *list,
Description:
Use this function if the size field of a list item must be changed. Call
PtGenListLockItem() first to save the old size of the item, then modify the item. Then,
call PtGenListUnlockItem() last to update and resize or redisplay the widget if
necessary.
You can lock only one item per widget at a time. If you resize a large number of items,
set all the sizes and then call PtGenListResize().
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

PtGenListRelease() © 2010, QNX Software Systems GmbH & Co. KG.
Release a hold on visible repairs of a list widget
Synopsis:
void PtGenListRelease( PtWidget_t *widget );
Description:
This function is a list-aware version of PtRelease().
After a call to PtGenListHold(), PtGenListDamageItem() simply sets the
Pt_LIST_ITEM_DAMAGED flag in the item instead of calling PtDamageExtent().
PtGenListRelease() looks for items that have the flag set and calls PtDamageExtent().
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtGenListHold()
PtDamageExtent(), PtRelease() in the Photon Library Reference

© 2010, QNX Software Systems GmbH & Co. KG. PtGenListRemoveItems()
Remove items from a list
Synopsis:
PtGenListItem_t *PtGenListRemoveItems(
PtWidget_t *list,
PtGenListItem_t *first,
PtGenListItem_t *last );
Description:
This function removes the given sublist list from the PtGenList widget. If first or
last is NULL, the first or last item of the entire list is used. Both arguments may point
to the same item, but last must not precede first in the list.
The function returns the first removed item (or NULL if the list was empty). The
function inserts NULL in the next field of the last removed item and the prev field of
the first removed item. This ensures the returned value (if not NULL) always points to
the first item of a NULL-terminated, double-linked list. No other fields in any of the
removed items are modified.
If the current item is removed, there won’t be a current item in the list unless the
selection mode is Pt_SELECTION_MODE_RANGE and only part of the selected range
is removed. In this case, the current item is set to the first or last of the remaining
selected items (see “Current item” in the description of PtGenList).
Returns:
The first removed item, or NULL if the list was empty.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

PtGenListResize() © 2010, QNX Software Systems GmbH & Co. KG.
Resize a list widget
Synopsis:
void PtGenListResize( PtWidget_t *widget );
Description:
This function causes the given widget to:
• recalculate the total size of all its items
• recalculate the height of the currently displayed items
• apply the widget’s resize policy, if any.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtGenListLockItem(), PtGenListUnlockItem()

© 2010, QNX Software Systems GmbH & Co. KG. PtGenListSelect()
Select an item in a list
Synopsis:
void PtGenListSelect( PtWidget_t *widget,
Description:
This function selects the given item in the list. If the selection mode is set to
Pt_SELECTION_MODE_SINGLE or Pt_SELECTION_MODE_RANGE, this may
involve selecting or unselecting other items.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

PtGenListSelectedItems() © 2010, QNX Software Systems GmbH & Co. KG.
Get pointers to the selected items
Synopsis:
PtGenListItem_t **PtGenListSelectedItems(
PtWidget_t *widget,
PtGenListItem_t **buffer );
Description:
This function fills the given buffer with pointers to the currently selected items.
buffer with a NULL. It’s your application’s responsibility to free the buffer when it’s
no longer needed.
If buffer isn’t NULL, the function adds a NULL to the end only if there are no selected
items.
Returns:
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtGenListSetColumnBalloon()
Adjust the balloon text for a list item to correspond to a column
Synopsis:
PhArea_t *PtGenListSetColumnBalloon(
PhArea_t *area,
PtListColumn_t const *column );
Description:
This function adjusts the PhArea_t structure pointed to by area so that it corresponds
to the given column rather than the entire item. If column is NULL, area isn’t modified.
Returns:
A pointer to the adjusted area.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PhArea_t in the Photon Library Reference

PtGenListSetGflags() © 2010, QNX Software Systems GmbH & Co. KG.
Modify the gflags field of the widget
Synopsis:
unsigned PtGenListSetGflags( PtWidget_t *widget,
unsigned value,
unsigned mask );
Description:
This function modifies the gflags field of the widget. The bits defined by mask are set
to the value defined by value.
Returns:
The old value of gflags.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtGenList

© 2010, QNX Software Systems GmbH & Co. KG. PtGenListSetSelIndexes()
Synopsis:
int PtGenListSetSelIndexes(
PtWidget_t *widget,
const unsigned short *buffer
int count );
Description:
This function lets you set the selection indexes for the given PtGenList. It assumes
that buffer points to a sorted array of indexes. The first item in the list widget has an
index of 1, not 0.
be smaller than count if the array isn’t sorted or contains duplicate or out-of-range
indexes.
In Pt_SELECTION_MODE_RANGE mode, only the first index and count are used. In
Pt_SELECTION_MODE_SINGLE mode, only the first index is used; if count is greater
than 1, it’s treated as 1.
Returns:
The number of items actually selected.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtGenList

PtGenListShow() © 2010, QNX Software Systems GmbH & Co. KG.
Set the current position so a given item is visible
Synopsis:
void PtGenListShow( PtWidget_t *list,
Description:
PtGenListShow( list, item->next );
without having to make sure item->next isn’t NULL.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtGenListUnlockItem()
Unlock an item so it can be updated
Synopsis:
void PtGenListUnlockItem( PtWidget_t *list,
Description:
Use this function if the size field of a list item must be changed. First, call
PtGenListLockItem() to save the old size of the item, and then modify the item. Then,
call PtGenListUnlockItem() to update and resize or redisplay the widget if necessary.
Only one item per widget can be locked at a time. If you resize a large number of
items, set all sizes and then call PtGenListResize().
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

PtGenListUnselect() © 2010, QNX Software Systems GmbH & Co. KG.
Unselect an item in a list
Synopsis:
void PtGenListUnselect( PtWidget_t *widget,
Description:
This function unselects the given item. PtGenListUnselect() has no effect in the
Pt_SELECTION_MODE_RANGE selection mode.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtGenTree
A generic superclass for tree widgets
Class hierarchy:
PtGenTree
• PtFileSel
• PtRawTree
• PtTree
PhAB icon:
Public header:
<photon/PtGenTree.h>
Description:
The PtGenTree widget displays a tree of items. When you expand an item, another
list of items drops down from it. Additional items can be added to an expandable item
when it’s about to be expanded. Expanded items can be collapsed, which results in the
exclusion of items from the displayed list.
The tree can actually be a “forest” — the widget can contain multiple items at the root
level. The root items are always visible (included on the displayed list) because they
don’t have a parent that could be collapsed.
You can build a tree (or a forest) that isn’t linked to any widget and then add the whole
tree to a widget as a root or subtree. Alternatively, you can add each item to the widget
tree separately, but once the widget is realized, you’ll have to use PtHold() and
PtUpdate() to avoid multiple redraws.
PtGenTreeItem_t is the data structure used for the items.
For more information about this class, see Building Custom Widgets.
New resources:

Pt_ARG_TREE_FLAGS unsigned int Flag Pt_TREE_HAS_BUTTONS | Pt_TREE_TO_LEFT |
Pt_TREE_TO_RIGHT | Pt_TREE_INDENT_BUTTONS |
Pt_TREE_SHOW_CONNECTORS
continued. . .

PtGenTree © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_TREE_LINE_COLOR PgColor_t Scalar PgRGB(239, 239, 239)
Pt_ARG_TREE_LINE_SPACING unsigned short Scalar 3
Pt_ARG_TREE_MARGIN_COLOR PgColor_t Scalar PgRGB(225, 225, 225)
Pt_CB_GEN_TREE_INPUT PtCallback_t * Link NULL
Pt_ARG_TREE_FLAGS
unsigned int Flag Pt_TREE_HAS_BUTTONS |
Pt_TREE_TO_LEFT |
Pt_TREE_TO_RIGHT |
Pt_TREE_INDENT_BUTTONS |
Possible values are:
Pt_TREE_HAS_BUTTONS
Display the buttons for expanding and collapsing items.
Pt_TREE_INDENT_BUTTONS
Indent the buttons.
Pt_TREE_INDENT_LINES
If Pt_TREE_SHOW_LINES is set, indent the lines to match the tree item
indentation.
Display the connectors.
Pt_TREE_SHOW_LINES
Display horizontal lines between each item in the tree.
Pt_TREE_SHOW_MARGIN
Display the margins.
Pt_TREE_TO_RIGHT
Extend the items to the right edge of the widget.
Pt_TREE_TO_LEFT
Extend the item background to the left edge.

The PtTree subclass defines some additional flags.
Pt_ARG_TREE_LINE_COLOR
PgColor_t Scalar PgRGB( 239, 239, 239 )
The color of the lines. See PgColor_t in the Photon Library Reference.
Pt_ARG_TREE_LINE_SPACING
The spacing between lines, in pixels.
Pt_ARG_TREE_MARGIN_COLOR
PgColor_t Scalar PgRGB( 225, 225, 225 )
The color of the margins. See PgColor_t in the Photon Library Reference.
Pt_CB_GEN_TREE_INPUT
A list of PtCallback_t structures that define the callbacks invoked on mouse and
key events. Each callback is passed a PtCallbackInfo_t structure that contains at
reason Pt_CB_GEN_TREE_INPUT
reason_subtype The event type (same as event->type). For more info, see the
types described for PhEvent_t in the Photon Library Reference.

cbdata A pointer to a PtGenTreeInput_t structure that contains at


PtGenTreeItem_t *item;
For mouse events, the item pointed to by the
mouse or NULL if the mouse doesn’t point to
an item. For key events, the item that is going
to be the current item (see “Current item” in
the description of PtGenList) after the event
is normally processed by the widget.
unsigned index; The index of the item.
PhPoint_t pos; The pointer position relative to the item. See
PhPoint_t in the Photon Library Reference.
int consumed; Initially set to Pt_CONTINUE. Your callback
function can suppress normal handling of the
event by setting this field to another value. In
the case of key events, set it to Pt_END to
consume the event, or to Pt_HALT to pass the
event to the parent widget. Mouse events are
always consumed.

continued. . .


Pt_ARG_DIM PtWidget
continued. . .


Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
continued. . .


Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
Pt_CB_DND
For Pt_CB_DND callbacks for a PtGenTree, the cbinfo->cbdata is a pointer to a
A pointer to the target item involved in the drag-and-drop operation.
unsigned long flags

Possible values:
the item.
below the item.

PtGenTree defines the following convenience functions and data structure:
PtGenTreeAddAfter() Add items after a given item.
PtGenTreeAddFirst() Add items in front of any existing items.
PtGenTreeAllItems() Get pointers to all the items in the tree.
PtGenTreeClearSelection()
Clear the selection.
PtGenTreeCollapse() Collapse a subtree.
PtGenTreeDamageItem()
Redraw an item when its data has changed.
PtGenTreeExpand() Expand a given subtree.
PtGenTreeExpandParents()
Expand any collapsed ancestors of a given item.
PtGenTreeFreeAllItems()
Free all the items in a tree.
PtGenTreeFreeItems()
Free the items in a subtree.
PtGenTreeGetCurrent()
Get a pointer to the current item.
PtGenTreeGetSelIndexes()
Get the indexes of the selected items.
PtGenTreeGoto() Set the current item and position so that a given item is visible.
PtGenTreeItem_t PtGenTree item structure
PtGenTreeItemIndex()
Calculate the index of a given item.
PtGenTreeItemRealloc()
Reallocate an item.
PtGenTreeItemResize()
Resize an item.
PtGenTreeRemoveChildren()
Unlink all the children of a given item.

PtGenTreeRemoveItem()
Remove a given item and its children from its parents and
siblings.
PtGenTreeRemoveList()
Remove a given items and its siblings from their parent.
PtGenTreeResize() Resize many items.
PtGenTreeRootItem()
Get a pointer to the first root item.
PtGenTreeSelect() Select a given item.
PtGenTreeSelectedItems()
Get pointers to the selected items.
PtGenTreeSetSelIndexes()
Set the selection indexes.
PtGenTreeShow() Set the current position so that a given item is visible.
PtGenTreeUnselect() Unselect a given item.
PtGenTreeUnselectNonBrothers()
Unselect all items that aren’t siblings of a given item.
The following convenience functions are useful only if you’re creating a custom tree
widget; they’re described in the Creating a Tree Widget chapter of Building Custom
Widget:
PtSuperClassGenTreeDrawItem()
Invoke the Tree Draw Item method of a given superclass.
PtSuperClassGenTreeItemState()
Invoke the Tree Item State method of a superclass.

PtGenTreeAddAfter() © 2010, QNX Software Systems GmbH & Co. KG.
Add items after a given item
Synopsis:
int PtGenTreeAddAfter( PtWidget_t *tree,
PtGenTreeItem_t *items,
PtGenTreeItem_t *brother );
Description:
This function inserts a list of trees linked with the brother field. PtGenTreeAddAfter()
assumes that items points to a list of trees. The tree variable points to a PtGenTree
widget. The new items are added to the specified tree below the specified brother.
This function may be called with a NULL tree argument, as long as brother points to
an item that isn’t attached to any tree widget.
Returns:
0 Success.
-1 The item is already in a widget.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtGenTree, PtGenTreeItem_t

© 2010, QNX Software Systems GmbH & Co. KG. PtGenTreeAddFirst()
Add items in front of any existing items
Synopsis:
int PtGenTreeAddFirst( PtWidget_t *tree,
PtGenTreeItem_t *item,
PtGenTreeItem_t *parent );
Description:
This function adds the list of PtGenTreeItem_t structures pointed to by item to the
given PtGenTree widget. The list of items are linked with their brother fields. The
item argument can be NULL.
The parent argument identifies the parent item for the added items (if any). The new
items are added in front of any existing children of the parent item. If parent is NULL,
the items are added at the root level of the tree, before any existing items there.
The tree argument can be NULL, provided that parent points to an item that isn’t
attached to any tree widget.
PtGenTreeAddFirst() sets the Pt_TREE_ITEM_EXPANDABLE flag in the parent item,
whether or not the item argument is NULL.
Returns:
0 Success.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

PtGenTreeAllItems() © 2010, QNX Software Systems GmbH & Co. KG.
Get pointers to all the items in the tree
Synopsis:
PtGenTreeItem_t **PtGenTreeAllItems(
PtWidget_t *widget,
PtGenTreeItem_t **buffer );
Description:
This function fills a buffer with pointers to all items in the widget. If buffer is NULL,
the function allocates a buffer using malloc() and the buffer is NULL-terminated. If
buffer isn’t NULL, the function doesn’t add a NULL at the end.
Returns:
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtGenTreeClearSelection()
Clear the selection
Synopsis:
void PtGenTreeClearSelection( PtWidget_t *widget );
Description:
This function clears the selection in the given PtGenTree widget.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtGenTree

PtGenTreeCollapse() © 2010, QNX Software Systems GmbH & Co. KG.
Collapse a subtree
Synopsis:
int PtGenTreeCollapse( PtWidget_t *tree,
PhEvent_t *event );
Description:
This function collapses the given subtree item. The tree argument must point to the
tree that contains the item or can be NULL if the item doesn’t belong to any tree.
If the item belongs to the tree widget, the widget’s Tree Item State method is called.
Returns:
The value returned by the Tree Item State method.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtGenTreeDamageItem()
Redraw an item when its data has changed
Synopsis:
void PtGenTreeDamageItem( PtWidget_t *tree,
PtGenTreeItem_t *item );
Description:
Call this function to redraw the given item when its data has changed.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtGenTree

PtGenTreeExpand() © 2010, QNX Software Systems GmbH & Co. KG.
Expand a given subtree
Synopsis:
int PtGenTreeExpand( PtWidget_t *tree,
PhEvent_t *event );
Description:
This function expands the given subtree item. The tree argument must point to the tree
that contains the item or can be NULL if the item doesn’t belong to any tree.
If tree isn’t NULL, the Tree Item State method of that widget is called. If it returns a
nonzero value, the item isn’t expanded; if it returns zero, the expansion proceeds.
PtGenTreeExpand() returns the same value.
If the Tree Item State method destroys the item, make sure that it doesn’t return zero.
Returns:
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtGenTreeExpandParents()
Expand any collapsed ancestors of a given item
Synopsis:
int PtGenTreeExpandParents( PtWidget_t *tree,
PhEvent_t *event );
Description:
If any ancestors of the given item are collapsed, this function attempts to expand them.
Returns:
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

PtGenTreeFreeAllItems() © 2010, QNX Software Systems GmbH & Co. KG.
Free all the items in a tree
Synopsis:
void PtGenTreeFreeAllItems( PtWidget_t *tree );
Description:
This function unlinks and frees all items in the tree widget.
This function isn’t called automatically when the PtGenTree widget is being deleted,
because the widget doesn’t assume that its items have been allocated.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtGenTree

© 2010, QNX Software Systems GmbH & Co. KG. PtGenTreeFreeItems()
Free the items in a subtree
Synopsis:
int PtGenTreeFreeItems( PtGenTreeItem_t *item );
Description:
This function frees the subtree item, together with its siblings and their children. The
items must not belong to any tree. (Use PtGenTreeRemoveItem(),
PtGenTreeRemoveList(), or PtGenTreeRemoveChildren() to remove the subtree before
freeing it.)
Returns:
0 Success.
-1 The item is still in a widget.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

PtGenTreeGetCurrent() © 2010, QNX Software Systems GmbH & Co. KG.
Get a pointer to the current item
Synopsis:
PtGenTreeItem_t *PtGenTreeGetCurrent(
const PtWidget_t *widget );
Description:
This function returns a pointer to the current item (see “Current item” in the
Returns:
A pointer to the current item.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtGenTreeGetSelIndexes()
Get the indexes of the selected items
Synopsis:
unsigned short *PtGenTreeGetSelIndexes(
PtWidget_t *widget,
Description:
This function fills a buffer with indexes of all the selected items in the widget. The
first item in the widget has an index of 1, not 0.
buffer with a zero.
If buffer isn’t NULL, the function adds a 0 to the end only if there are no selected items.
Returns:
A pointer to the buffer containing the indexes.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtGenTree

PtGenTreeGoto() © 2010, QNX Software Systems GmbH & Co. KG.
Set the current item and position so that a given item is visible
Synopsis:
int PtGenTreeGoto( PtWidget_t *tree,
Description:
If item is NULL, there’s no current item.
You can call PtGenTreeGoto() with an item whose ancestor is collapsed, in which case
the ancestor is expanded.
Returns:
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtGenTreeItem_t
PtGenTree item structure
Synopsis:
typedef struct Pt_gentree_item {
PtGenListItem_t list;
struct Pt_gentree_item *father,
*son,
*brother;
PhDim_t dim;
} PtGenTreeItem_t;
Description:
This data structure describes an item in a PtGenTree widget.
Applications should view this as a read-only structure; subclasses usually define ways
to modify PtGenTreeItem_t members.
The members include at least:
list A structure that describes a generic-list item. This structure includes state
information for the item (whether or not it’s selected, the current item,
damaged, out of view, and so on), its size, and links to other generic-list items.
For more information, see PtGenListItem_t.
The PtGenTree class defines some new flags that can be set in
item->list.flags:
Pt_TREE_ITEM_EXPANDABLE
The item can be expanded:
• It has a button for expanding or collapsing the item (unless the
widget disables the buttons by clearing Pt_TREE_HAS_BUTTONS in
its Pt_ARG_TREE_FLAGS resource).
• It reacts to the Right and Left arrow keys by attempting to expand or
collapse itself (which, again, can be disabled by a subclass).
The setting of this flag is preserved when the item is added to a widget.
This flag is usually set in the parent item automatically when you add a
branch to an item.
This flag isn’t cleared when all the child items are deleted. You can
clear or set this flag in your code, but:
• Make sure the item is collapsed before clearing the flag.
• Call PtGenTreeDamageItem() afterward to cause the item to be
redrawn.
Pt_TREE_ITEM_EXPANDED
The branches of this item are currently on display.
If the Pt_TREE_ITEM_EXPANDABLE flag is set when the item is added
to a widget, the setting of Pt_TREE_ITEM_EXPANDED flag is

PtGenTreeItem_t © 2010, QNX Software Systems GmbH & Co. KG.
preserved; if Pt_TREE_ITEM_EXPANDABLE isn’t set, this flag is

cleared.
Once the item is in a widget, don’t set or clear this flag; use the
convenience functions instead.
Pt_TREE_ITEM_INWIDGET
The item has been added to a widget.
father, son, brother

Tree links. You can use them to traverse the tree structure, but don’t modify
them directly — use the convenience functions to modify the tree structure.
dim A PhDim_t structure (see the Photon Library Reference) that defines the size
of the item, excluding the tree ornaments (lines and button).
When an item is added to the widget, the widget calculates item->list.size
based on the size specified in item->dim, the minimum height of the item, and
the item’s position in the tree. The height of an item in a tree widget is always
an even number of pixels — if you specify an odd number for the height in the
dim field, a gap of at least one pixel is displayed between the current item (see
“Current item” in the description of PtGenList) and any other item directly
below.
Classification:
Photon
See also:
PtGenList, PtGenListItem_t, PtGenTree, PtTreeItem_t
PhDim_t in the Photon Library Reference
Building Custom Widgets

© 2010, QNX Software Systems GmbH & Co. KG. PtGenTreeItemIndex()
Calculate the index of a given item
Synopsis:
int PtGenTreeItemIndex(
const PtWidget_t *tree,
const PtGenTreeTtem_t *item );
Description:
This function calculates the index of the given item within the tree. The index of the
first item is 1.
Returns:
The index of the item.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtGenTree

PtGenTreeItemRealloc() © 2010, QNX Software Systems GmbH & Co. KG.
Reallocate an item
Synopsis:
PtGenTreeItem_t *PtGenTreeItemRealloc(
PtWidget_t *tree,
size_t newsize );
Description:
Use this function to reallocate an item. It repairs any links damaged if the realloc()
function moves the item to a different address. The tree argument must point to the
tree that contains the item or be NULL if the item doesn’t belong to any tree.
Returns:
A pointer to the reallocated item.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtGenTreeItemResize()
Resize an item
Synopsis:
void PtGenTreeItemResize( PtGenTreeItem_t *item,
PtWidget_t *tree );
Description:
This function resizes one item. You should call it after changing the dimensions of an
item (item->dim). You don’t need to call this function if item doesn’t belong to any
tree or if a subtree containing the item is collapsed.
If you’re resizing many items, use PtGenTreeResize() instead.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

PtGenTreeRemoveChildren() © 2010, QNX Software Systems GmbH & Co. KG.
Unlink all the children of a given item
Synopsis:
PtGenTreeItem_t *PtGenTreeRemoveChildren(
Description:
This function unlinks all the children of the given item and returns the pointer to the
first of them. You can then give the pointer to PtGenTreeFreeItems().
This function doesn’t collapse the item. If the children are visible, NULL is returned.
Call PtGenTreeCollapse() before PtGenTreeRemoveItem() to make sure the item is
collapsed.
Returns:
A pointer to the first unlinked child.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtGenTreeRemoveItem()
Remove a given item and its children from its parents and siblings
Synopsis:
void PtGenTreeRemoveItem( PtWidget_t *tree,
Description:
This function unlinks the given item (together with its children) from its parent and
brothers (if any) and sets item->parent and item->brother to NULL. The tree argument
must point to the PtGenTree widget containing item or can be NULL if item doesn’t
belong to any tree.
If tree is NULL and item has no parent but has a previous sibling, then
PtGenTreeRemoveItem() can’t find the previous sibling and can’t unlink item from its
sibling. The function does nothing if item->parent and tree are NULL.
PtGenTreeRemoveItem() never clears the Pt_TREE_ITEM_EXPANDABLE flag in the
item’s parent.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

PtGenTreeRemoveList() © 2010, QNX Software Systems GmbH & Co. KG.
Remove a given items and its siblings from their parent
Synopsis:
void PtGenTreeRemoveList( PtWidget_t *tree,
PtGenTreeItem_t *first );
Description:
This function unlinks the item first and its siblings (together with their children) from
their parent (and previous sibling) and sets their parent fields to NULL. The tree
argument must point to the widget that contains the items or can be NULL if the items
don’t belong to any tree.
If tree is NULL and first has no parent but has a previous sibling,
PtGenTreeRemoveList() can’t find the previous sibling and can’t unlink first from its
previous sibling.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtGenTreeResize()
Resize many items
Synopsis:
void PtGenTreeResize( PtWidget_t *widget );
Description:
Use this function to resize many items. You should call it after changing the size field
of a number of tree items; modify item->dim directly in all items, then call
PtGenTreeResize() once.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtGenTree

PtGenTreeRootItem() © 2010, QNX Software Systems GmbH & Co. KG.
Get a pointer to the first root item
Synopsis:
PtGenTreeItem_t *PtGenTreeRootItem(
PtWidget_t const *tree );
Description:
This function returns a pointer to the first root item of the tree.
Returns:
A pointer to the first root item.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtGenTreeSelect()
Select a given item
Synopsis:
void PtGenTreeSelect( PtWidget_t *widget,
Description:
This function selects the given item. As with other PtGenTree*() functions, the tree
argument can be set to NULL if item doesn’t belong to a widget.
If tree isn’t NULL and none of item’s ancestors is collapsed, PtGenListSelect() is
called. If tree is NULL or some of the ancestors of the item are collapsed,
PtGenTreeSelect() simply sets the Pt_LIST_ITEM_SELECTED flag in the item.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

PtGenTreeSelectedItems() © 2010, QNX Software Systems GmbH & Co. KG.
Get pointers to the selected items
Synopsis:
PtGenTreeItem_t **PtGenTreeSelectedItems(
PtWidget_t *widget,
PtGenTreeItem_t **buffer );
Description:
This function fills a buffer with pointers to the currently selected items. If buffer is
NULL, the function allocates a buffer using malloc(), and the buffer is
NULL-terminated.
If buffer isn’t NULL, the function adds a NULL to the end only if there are no selected
items.
Returns:
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtGenTreeSetSelIndexes()
Synopsis:
int PtGenTreeSetSelIndexes(
PtWidget_t *widget,
unsigned short const *buffer,
int count );
Description:
This function sets the selection indexes. It assumes that buffer points to a sorted array
of indexes. The first item in the widget has an index of 1, not 0.
be smaller than count if the array isn’t sorted or contains duplicate or out-of-range
indexes.
When the selection mode is Pt_SELECTION_MODE_RANGE, only the first index and
the count are used.
Returns:
The number of items actually selected.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtGenTree

PtGenTreeShow() © 2010, QNX Software Systems GmbH & Co. KG.
Set the current position so that a given item is visible
Synopsis:
int PtGenTreeShow( PtWidget_t *widget,
Description:
PtGenTreeShow( widget, PtGenTreeGetCurrent(widget) );
without checking whether PtGenTreeGetCurrent() returned a NULL value.

PtGenTreeShow() can be called with an item whose ancestor is collapsed, in which
case the ancestor will be expanded.
Returns:
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtGenTreeUnselect()
Unselect a given item
Synopsis:
void PtGenTreeUnselect( PtWidget_t *widget,
Description:
This function unselects the given item.
PtGenTreeUnselect() doesn’t support Pt_SELECTION_MODE_RANGE selection

mode.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

PtGenTreeUnselectNonBrothers() © 2010, QNX Software Systems GmbH & Co. KG.
Deselect all items that aren’t siblings of a given item
Synopsis:
void PtGenTreeUnselectNonBrothers(
PtWidget_t *wgt,
Description:
This function deselects all the items that aren’t siblings of the given item. If item is
NULL, the function uses the current item (see “Current item” in the description of
PtGenList).
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtGraphic
Common resources for graphical widgets
Class hierarchy:
PtWidget → PtBasic → PtGraphic
• PtArc
• PtBezier
• PtEllipse
• PtGrid
• PtLine
• PtPixel
• PtPolygon
• PtRect
PhAB icon:
Public header:
<photon/PtGraphic.h>
Description:
The PtGraphic superclass provides the common resources used by all graphic
widgets. Graphical widgets provide attributes for color, fills, patterns, line thickness,
joins, and much more.
When you want to incorporate simple, static drawings in your interface, use the
subclasses of PtGraphic.
Don’t call the Pg... drawing primitives directly, as they aren’t redrawn when widgets
are damaged and repaired. If you need to draw something that can’t be done with these
widgets, do your drawing inside a PtRaw widget. For more information, see the Raw
Drawing and Animation chapter of the Photon Programmer’s Guide.
Each graphical widget draws a single graphical primitive. The provided primitives are:
• lines
• rectangles
• ellipses
• arcs

PtGraphic © 2010, QNX Software Systems GmbH & Co. KG.
• polylines
• points
You can build up a drawing by creating one widget for each of the graphical primitives
you need. You should create the widgets from back to front, so that their stacking
order is correct and they consequently appear correct when drawn to the screen. You
should also place the widgets in a container widget (i.e a subclass of PtContainer).
Origin and coordinates

All the vector graphics widgets are defined by an origin and a set of coordinates.
The origin is an offset from the graphic widget’s origin, which is used as the origin of
the coordinate space for the graphics primitive.
The set of coordinates is implemented as an array of PhPoint_t structures (see the
Photon Library Reference). Each coordinate specifies a vertex or control point of the
primitive. Here’s a code fragment to illustrate:
PhPoint_t points[]=
{ { 0, 0},
{40,40},
{40, 5},
{ 0, 0}};
PtSetArg(&argt[0], Pt_ARG_POINTS, points, 4 ) ;
PtCreateWidget( PtPolygon, parent, 1, argt ) ;
Each of the coordinates defining the primitive is relative to the graphics widget’s
origin.
You can specify the graphics widget’s origin by setting Pt_ARG_ORIGIN. This
resource takes a PhPoint_t as a value. This point is the origin of the primitive’s
coordinate space, in pixels, relative to the widget’s origin.
The set of points is specified using the array resource Pt_ARG_POINTS. The number
of points required in the array — and the interpretation of those points — depends on
the type of graphics primitive being defined.
Line attributes
When drawing the points for the primitive, the widget uses its associated line drawing
attributes to determine the color and drawing style to use. These line drawing attributes
are specified using the following resources defined by the PtGraphic widget class:
Pt_ARG_LINE_WIDTH
The curve’s width, in pixels.
Pt_ARG_LINE_CAP
The cap style for capping off the curve’s start and end points.
Pt_ARG_LINE_JOIN
The join style for connecting any intermediate vertices in the curve.

Colors
The graphics primitives use the following resources (defined by PtBasic) to
determine their colors and patterns:
Pt_ARG_COLOR The widget’s line color.
Pt_ARG_FILL_COLOR
The color of the rectangular area occupied by the widget (i.e.
its extent).
Pt_ARG_FILL_PATTERN
The stipple pattern to use to fill the extent.
The graphics primitives that can draw a closed curve may also use these resources
(defined by PtGraphic) for the inside of the curve:
• Pt_ARG_INSIDE_COLOR
• Pt_ARG_INSIDE_FILL_PATTERN
• Pt_ARG_INSIDE_TRANS_PATTERN
Creating a drawing
To create a drawing composed of several graphical widgets, you should first create a
container-class widget to place the widgets in. If you wish, set the border width and
margins of the container to zero.
At this point, you may create the graphics primitives and position them within the
container widget. You may choose to position and size the graphics widgets in one of
several ways, but the simplest is to place them all at position (0,0), which is adequate
for most purposes.
The origin resource, Pt_ARG_ORIGIN, provides a reference point or datum for all the
primitives added to the container-class widget. This resource defines a coordinate
space for each graphic, allowing maximum flexibility for positioning and sizing
primitives.
For example, the origin lets you create a library of symbols defined in their own
coordinate space. You can then use the origin to place the symbol anywhere in the
drawing, and the widget itself doesn’t need to be positioned. The only thing you have
to do then is scale the symbol itself.
Sizing the primitives
If you know the overall dimensions of the drawing, you may want to explicitly set the
dimensions of the graphics widgets as you create them. You might also want to set the
dimensions if you want to have a standard symbol clipped to obtain a new shape. The
figure below illustrates how a five-pointed star is drawn when Pt_ARG_ORIGIN is set
to (50,50) and the dimensions of the widget are fixed at 101 x 101 pixels. The star is
constructed from this set of points:

{(95, -31), (-58, 81), (0, -100), (58, 81), (-95, -31)}
A five-pointed star before clipping.
Note the resulting bounding box of the widget as well as the origin of the polygon’s
coordinate space, which is fixed at position (50,50) of the widget’s canvas.
The star after clipping.
If you don’t need special clipping, however, you should use the graphics widget’s
resize policy or another geometry management mechanism to determine the widget’s
size. The default resize policy for graphics is Pt_RESIZE_...AS_REQUIRED for both
the width and height. To fix the dimensions of the widget as shown in the case above,
you have to override the default resize policy. For more information, see the
Pt_ARG_RESIZE_FLAGS resource in the description of PtWidget.

Grouping elements of the drawing
Occasionally you’ll want to group together a number of graphical primitives and

define them as a group or unit. All the primitives within the group are defined in terms
of their common origin, and the unit may be repositioned or resized without affecting
the group’s components. You can do this simply by creating a container-class widget
and placing the widgets for the graphical primitives within it.
Using this technique, you can create a complex drawing composed of a number of
subdrawings. There’s no limit to the number of drawings that can be nested in this
way. The only limiting factor here is the number of resources consumed. In a system
with constrained memory, many deeply nested drawings may consume too much
memory.
New resources:

Pt_ARG_DASH_LIST char, short Array NULL
Pt_ARG_DASH_SCALE long Scalar 0
Pt_ARG_GRAPHIC_FLAGS char Flag 0
Pt_ARG_INSIDE_COLOR PgColor_t Scalar Pg_TRANSPARENT
Pt_ARG_INSIDE_FILL_PATTERN PgPattern_t Struct Pg_PAT_FULL
Pt_ARG_INSIDE_TRANS_PATTERN PgPattern_t Struct Pg_PAT_NONE
Pt_ARG_LINE_CAP unsigned short Scalar Pg_BUTT_CAP
Pt_ARG_LINE_JOIN unsigned short Scalar Pg_MITER_JOIN
Pt_ARG_LINE_WIDTH long Scalar 0
Pt_ARG_ORIGIN PhPoint_t Struct 0,0
Pt_ARG_POINTS PhPoint_t *, short Array NULL
Pt_CB_RESCALE PtCallback_t * Link NULL
Pt_ARG_DASH_LIST
char, short Array NULL
An array of bytes that describes the on and off bits for stroke operations.

Pt_ARG_DASH_SCALE

long Scalar 0
A scaling factor that’s applied to each of the bits in the dash list to determine the
number of pixels for each dash. For information on setting this factor, see
PgSetStrokeDash() in the Photon Library Reference.
Pt_ARG_GRAPHIC_FLAGS
char Flag 0
Possible values:
Pt_FLOAT_POS Adjust the position and origin of the widget, but leave the graphic
in place relative to the widget’s parent. The upper left corner of
the widget’s canvas is at the upper left corner of the bounding
box described by the point array. Depending on its resize policy,
the widget may resize to fit the rendering.
Pt_FLOAT_ORIGIN
Adjust the origin of the graphic, but leave the widget in place
relative to its parent. The upper left corner of the bounding box
described by the point array is at the upper left corner of the
widget’s canvas.
The default setting of this resource is 0; that is, no flags have been set.
Pt_ARG_INSIDE_COLOR
PgColor_t Scalar Pg_TRANSPARENT
The color of the inside of the graphic. See PgColor_t in the Photon Library
Reference.
Pt_ARG_FILL_COLOR (inherited from PtBasic) is the color of the widget’s extent
(i.e. the rectangular area that the widget occupies).

Pt_ARG_INSIDE_FILL_PATTERN

PgPattern_t Struct Pg_PAT_FULL
The background pattern of the inside of the graphic. You can’t edit this resource in
PhAB.
Pt_ARG_FILL_PATTERN (inherited from PtBasic) is the fill pattern of the widget’s
extent (i.e. the rectangular area that the widget occupies).
Pt_ARG_INSIDE_TRANS_PATTERN
PgPattern_t Struct Pg_PAT_NONE
The transparency pattern for the inside of the graphic. You can use this resource for
“ghosting” widgets. You can’t edit this resource in PhAB.
Pt_ARG_TRANS_PATTERN (inherited from PtBasic) is the transparency pattern of
the widget’s extent (i.e. the rectangular area that the widget occupies).
Pt_ARG_LINE_CAP
unsigned short Scalar Pg_BUTT_CAP
Defines how the ends of thick lines are drawn; see PgSetStrokeCap(). Possible values:
• Pg_BUTT_CAP
• Pg_ROUND_CAP
• Pg_SQUARE_CAP
Pt_ARG_LINE_JOIN
unsigned short Scalar Pg_MITER_JOIN
Defines how thick lines are connected; see PgSetStrokeJoin(). Possible values:
• Pg_BEVEL_JOIN
• Pg_BUTT_JOIN
• Pg_MITER_JOIN

• Pg_ROUND_JOIN
• Pg_QROUND_JOIN (quick rounded join)
Pt_ARG_LINE_WIDTH
long Scalar 0
The line width for any graphically based widget.
Pt_ARG_ORIGIN
PhPoint_t Struct 0,0
A PhPoint_t structure that specifies the offset from the upper left corner of the
widget’s canvas. The graphic is rendered with its origin at:
(widget position) + (Pt_ARG_ORIGIN)
Pt_ARG_POINTS
PhPoint_t *, short Array NULL
An array of points (PhPoint_t structures) describing the graphic. The number of

points required in the array and the interpretation of those points depend on the type of
graphics primitive being defined.
Pt_CB_RESCALE
A list of PtCallback_t structures that define the callbacks that the widget invokes if
its Pt_ARG_DIM or Pt_ARG_AREA resource is modified. You can use this callback
to rescale the widget.
following members:
reason Pt_CB_RESCALE
event NULL (not used).

cbdata A pointer to a PhArea_t structure (see the Photon Library

Reference) that indicates the old area of the widget (prior to the
area/dimension change). You can retrieve the current area by
calling PtGetResources().

Pt_ARG_DIM PtWidget
continued. . .


Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
continued. . .


Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

PtGrid © 2010, QNX Software Systems GmbH & Co. KG.
A grid pattern
Class hierarchy:
PtWidget → PtBasic → PtGraphic → PtGrid
PhAB icon:
Public header:
<photon/PtGrid.h>
Description:
PtGrid draws a grid pattern via PgDrawGrid() (see the Photon Library Reference).
A PtGrid widget.
New resources:

Pt_ARG_GRID_VERTICAL short Scalar 4
Pt_ARG_GRID_HORIZONTAL short Scalar 4
Pt_ARG_GRID_HORIZONTAL
short Scalar 4
The number of horizontal lines in the grid.
Pt_ARG_GRID_VERTICAL
short Scalar 4
The number of vertical lines in the grid.

© 2010, QNX Software Systems GmbH & Co. KG. PtGrid

Pt_ARG_DIM PtWidget
continued. . .

PtGrid © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_INSIDE_COLOR PtGraphic Not used by this class.
Pt_ARG_INSIDE_FILL_PATTERN PtGraphic Not used by this class.
Pt_ARG_INSIDE_TRANS_PATTERN PtGraphic Not used by this class.
Pt_ARG_POS PtWidget
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtGrid

Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

PtGroup © 2010, QNX Software Systems GmbH & Co. KG.
A container that can arrange its children in rows and columns
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtGroup
PhAB icon:
None — use the Group button in PhAB’s toolbar:
Public header:
<photon/PtGroup.h>
Description:
The PtGroup class inherits the functionality of a container and actively manages the
geometry of its children: the children are arranged in rows, columns, or a matrix. You
can use PtGroup to make the children mutually exclusive, so that the user can set only
one child at a time.
A group of buttons.
PhAB has a Group command that creates a PtGroup widget. See “Aligning widgets
using groups” in the Geometry Management chapter of the Programmer’s Guide.
New resources:

Pt_ARG_CELL_HORZ_ALIGN unsigned short Scalar Pt_GROUP_HORZ_LEFT
Pt_ARG_CELL_VERT_ALIGN unsigned short Scalar Pt_GROUP_VERT_TOP
Pt_ARG_GROUP_FLAGS unsigned long Flag 0

Pt_ARG_GROUP_HORZ_ALIGN unsigned short Scalar Pt_GROUP_HORZ_CENTER
Pt_ARG_GROUP_ORIENTATION unsigned short Scalar Pt_GROUP_HORIZONTAL
Pt_ARG_GROUP_ROWS_COLS unsigned short Scalar 0

Pt_ARG_GROUP_SPACING unsigned short Scalar 0
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtGroup

Pt_ARG_GROUP_SPACING_X unsigned short Scalar 0
Pt_ARG_GROUP_SPACING_Y unsigned short Scalar 0
Pt_ARG_GROUP_VERT_ALIGN unsigned short Scalar Pt_GROUP_VERT_CENTER
Pt_ARG_CELL_HORZ_ALIGN
unsigned short Scalar Pt_GROUP_HORZ_LEFT
Determines how the children are aligned horizontally within the cells. Possible values:
• Pt_GROUP_HORZ_LEFT
• Pt_GROUP_HORZ_CENTER
• Pt_GROUP_HORZ_RIGHT
Pt_ARG_CELL_VERT_ALIGN
unsigned short Scalar Pt_GROUP_VERT_TOP
Determines how the children are aligned vertically within the cells. Possible values:
• Pt_GROUP_VERT_TOP
• Pt_GROUP_VERT_CENTER
• Pt_GROUP_VERT_BOTTOM
Pt_ARG_GROUP_FLAGS
Possible values:
Pt_GROUP_EQUAL_SIZE
Force all children to be the same height and width.
Pt_GROUP_EXCLUSIVE
Allow only one child to be set at a time.

Pt_GROUP_NO_SELECT_ALLOWED
Allow any exclusive group to have no selected item. If this flag is set, you can
deselect the currently selected child without having to select another child. To
do this, click on the currently selected child.
Pt_GROUP_NO_KEYS
Prevent the group from using any keys (e.g. arrows).
Pt_GROUP_NO_KEY_WRAP_HORIZONTAL
Don’t use keys that would cause horizontal wrap.
Pt_GROUP_NO_KEY_WRAP_VERTICAL
Don’t use keys that would cause vertical wrap.
Pt_GROUP_NO_KEY_WRAP
Don’t use keys that would cause horizontal or vertical wrap.
Pt_GROUP_EQUAL_SIZE_HORIZONTAL
Make the children in the group the same width.
Pt_GROUP_EQUAL_SIZE_VERTICAL
Make the children in the group the same height.
Pt_GROUP_STRETCH_HORIZONTAL
Stretch the rightmost children in the group horizontally to fill its canvas.
Pt_GROUP_STRETCH_VERTICAL
Stretch the bottommost children in the group vertically to fill its canvas.
Pt_GROUP_STRETCH_FILL
Stretch the last widget(s) to fill the available space in the direction indicated by
the orientation.
Don’t set the Pt_GROUP_EQUAL_SIZE_... and Pt_GROUP_STRETCH_... flags for the

same direction — the group will expand every time its extent is calculated.
Pt_ARG_GROUP_HORZ_ALIGN
unsigned short Scalar Pt_GROUP_HORZ_CENTER
How the children are aligned horizontally within the group. The children retain their
relative positions to each other. Possible values:
• Pt_GROUP_HORZ_LEFT

• Pt_GROUP_HORZ_CENTER
• Pt_GROUP_HORZ_RIGHT
Pt_ARG_GROUP_ORIENTATION
unsigned short Scalar Pt_GROUP_HORIZONTAL
The orientation of the group; one of:
Pt_GROUP_ASIS Don’t align children.
Pt_GROUP_HORIZONTAL
Align children in a row.
Pt_GROUP_VERTICAL
Align children in a column.
Pt_ARG_GROUP_ROWS_COLS
For a horizontally aligned group, this resource indicates the number of columns to
distribute children into. For a vertically aligned group, this resource indicates the
number of rows to distribute children into. Not used for an “as is” group; see
Pt_ARG_GROUP_ORIENTATION, above.
Pt_ARG_GROUP_SPACING
If alignment is in effect, this resource defines how many pixels separate each child of
the group.
If you set this resource, you automatically set Pt_ARG_GROUP_SPACING_X and

Pt_ARG_GROUP_SPACING_Y to the same value.
Pt_ARG_GROUP_SPACING_X

the group horizontally. Setting Pt_ARG_GROUP_SPACING automatically sets this
resource.
Pt_ARG_GROUP_SPACING_Y
the group vertically. Setting Pt_ARG_GROUP_SPACING automatically sets this
resource.
Pt_ARG_GROUP_VERT_ALIGN
unsigned short Scalar Pt_GROUP_VERT_CENTER
Determines how the children are aligned within the group. The children retain their
relative positions to each other. Possible values:
• Pt_GROUP_VERT_TOP
• Pt_GROUP_VERT_CENTER
• Pt_GROUP_VERT_BOTTOM

continued. . .


Pt_ARG_DIM PtWidget
continued. . .


Pt_ARG_POS PtWidget
Pt_ARG_RESIZE_FLAGS PtWidget Pt_RESIZE_XY_ALWAYS
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
continued. . .


Pt_CB_RAW PtWidget

PtImageArea © 2010, QNX Software Systems GmbH & Co. KG.
An area for viewing an image
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtImageArea
PhAB icon:
Public header:
<photon/PtImageArea.h>
Description:
PtImageArea is an area in which you can display an image. You can select an area,
zoom in and out, and scroll if the image is too large to fit in the area. You can
optionally display a grid when you’ve zoomed in past a specified amount.
PtImageArea() can not handle alpha images.
New resources:

Pt_ARG_IMAGEAREA_FLAGS short Flag 0
Pt_ARG_IMAGEAREA_GRID_COLOR PgColor_t Scalar Pg_BLACK
Pt_ARG_IMAGEAREA_GRID_THRESHOLD long Scalar 0
Pt_ARG_IMAGEAREA_IMAGE PhImage_t * Image NULL
Pt_ARG_IMAGEAREA_LEFT short Scalar 0
Pt_ARG_IMAGEAREA_SELECTION PhRect_t Struct 0, 0, 0, 0
Pt_ARG_IMAGEAREA_TOP short Scalar 0
Pt_ARG_IMAGEAREA_ZOOM long Scalar 0
Pt_CB_IMAGEAREA_DRAG PtCallback_t * Link NULL
Pt_CB_IMAGEAREA_MOVEMENT PtCallback_t * Link NULL
Pt_CB_IMAGEAREA_SCROLLED PtCallback_t * Link NULL
Pt_CB_IMAGEAREA_SELECTION PtCallback_t * Link NULL

© 2010, QNX Software Systems GmbH & Co. KG. PtImageArea
Pt_ARG_IMAGEAREA_FLAGS

short Flag 0
Flags that control the behavior of the image area:
Pt_IMAGEAREA_AUTOSCALE
Automatically scale the image to fit the size of the widget.
Pt_IMAGEAREA_ENABLE_SELECTION
Allow the user to select part of the image.
Pt_IMAGEAREA_EDITABLE_SELECTION
Allow the user to modify a selection.
Pt_ARG_IMAGEAREA_GRID_COLOR
The color of the grid, if displayed. See PgColor_t in the Photon Library Reference.
Pt_ARG_IMAGEAREA_GRID_THRESHOLD
long Scalar 0
The grid threshold, expressed as a fixed-point 16.16 number. If the zooming factor
(Pt_ARG_IMAGEAREA_ZOOM) is greater than this threshold, the grid is displayed.
Pt_ARG_IMAGEAREA_IMAGE
the image to be displayed in the image area.
Pt_ARG_IMAGEAREA_LEFT

The coordinate, in image pixels, of the left side of the image viewport. This only
applies when the image is larger than the widget.
Pt_ARG_IMAGEAREA_SELECTION
PhRect_t Struct 0, 0, 0, 0
A PhRect_t structure (see the Photon Library Reference) that contains the selected
area of the image, in image coordinates (pixels).
Pt_ARG_IMAGEAREA_TOP
short Scalar 0
The coordinate, in image pixels, of the top side of the image viewport. This only
applies when the image is larger than the widget.
Pt_ARG_IMAGEAREA_ZOOM
long Scalar 0
The zooming factor, expressed as a fixed-point 16.16 number.
Pt_CB_IMAGEAREA_DRAG
A list of PtCallback_t structures that define the callbacks invoked when the image
area is dragged.
following members:
reason Pt_CB_IMAGEAREA_DRAG

• Pt_IMAGEAREA_INIT
• Pt_IMAGEAREA_DRAG
• Pt_IMAGEAREA_COMPLETE


cbdata A pointer to a PtImageAreaCallback_t structure that contains
at least the following members:
• PhRect_t rect — a PhRect_t structure (see the Photon
Library Reference) that defines the area dragged in image
coordinates (pixels).
Pt_CB_IMAGEAREA_MOVEMENT
mouse cursor is moved over the image area.
following members:
reason Pt_CB_IMAGEAREA_MOVEMENT


Library Reference) that defines the area the mouse moved over
in image coordinates (pixels).
Pt_CB_IMAGEAREA_SCROLLED
image area is scrolled.
following members:

reason Pt_CB_IMAGEAREA_SCROLLED
reason_subtype The direction in which the image area scrolled:
• Pt_IMAGEAREA_SCROLLED_X
• Pt_IMAGEAREA_SCROLLED_Y


Library Reference) that defines the new viewport area of the
image.
Pt_CB_IMAGEAREA_SELECTION
A list of PtCallback_t structures that define the callbacks invoked when the image
area is selected.
following members:
reason Pt_CB_IMAGEAREA_SELECTION

• Pt_IMAGEAREA_INIT
• Pt_IMAGEAREA_DRAG
• Pt_IMAGEAREA_COMPLETE


Library Reference) that defines the area selected.


Pt_ARG_DIM PtWidget
continued. . .


Pt_ARG_LAYOUT_TYPE PtContainer
Pt_ARG_POS PtWidget
Pt_ARG_SCROLLBAR_X_DISPLAY PtScrollArea
Pt_ARG_SCROLLBAR_X_HEIGHT PtScrollArea
Pt_ARG_SCROLLBAR_Y_DISPLAY PtScrollArea
Pt_ARG_SCROLLBAR_Y_WIDTH PtScrollArea
Pt_ARG_TEXT_STRING PtLabel Insufficient Memory
continued. . .


Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_LAYOUT PtContainer
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

PtLabel © 2010, QNX Software Systems GmbH & Co. KG.
A text, bitmap, or image label
Class hierarchy:
PtWidget → PtBasic → PtLabel
• PtButton
• PtMenuLabel — see PtMenuButton
• PtTab
• PtText
PhAB icon:
Public header:
<photon/PtLabel.h>
Description:
The PtLabel class provides a text string, bitmap, or image for labeling other widgets.
You can have text pop up in a balloon to provide further meaning to the label.
A text string in a PtLabel widget.
As their name implies, labels are tags attached to objects to identify their name or
nature. Label widgets are usually positioned beside the other widget they’re
describing, although in some cases (e.g. lists), the label appears above the object.
The most frequent use of a label is to identify the name of an input field. For example,
a mail program must provide input fields for indicating the recipient and the subject of
a mail message being composed. The label widget lets you attach “To:” and
“Subject:” tags to those input fields.
Creating labels
The default label type is a null-terminated text string. To specify the type of label, use
the Pt_ARG_LABEL_TYPE resource. The possible values for this resource are:
Pt_Z_STRING The label is a null-terminated ASCII string. This is the default.
Pt_IMAGE The label is an image, typically a small icon.
Pt_TEXT_IMAGE The label displays an image and text. To specify the positioning
of these two elements relative to each other, set
Pt_ARG_BALLOON_POSITION. Use

© 2010, QNX Software Systems GmbH & Co. KG. PtLabel
Pt_ARG_TEXT_IMAGE_SPACING to specify the number of

pixels between the image and text.
Different resources are used for the label data for different label types. This is
particularly useful when you wish to switch quickly between image labels and text
labels, so you can give the user a choice between using icons and textual descriptions
of operations.
At the push of a button, the user can switch your interface from an iconic
representation of commands to a textual representation of the same labels. You can
switch the label from an icon to text simply by changing the label type resource.
Text labels
When the label type is textual, the label widget gets the text to be displayed from the
Pt_ARG_TEXT_STRING resource.
To specify the font for the text, set Pt_ARG_TEXT_FONT.
The label widget defines its own margins in addition to the margin width defined by
the PtBasic widget class. There are separate left, right, top, and bottom margins,
which you can specify using:
• Pt_ARG_MARGIN_LEFT
• Pt_ARG_MARGIN_RIGHT
• Pt_ARG_MARGIN_TOP
• Pt_ARG_MARGIN_BOTTOM
These margins are cumulative, so that the actual margin of one edge of the widget is
the corresponding resource value added to the margin width.
The text label may be aligned independently to the left or right margin, or centered
horizontally within the margins of the widget. The
Pt_ARG_HORIZONTAL_ALIGNMENT resource controls this behavior.
Pt_ARG_SECONDARY_H_ALIGN controls how the text is aligned when the label is
smaller than the text (that is, when the text is clipped). If this resource is not set, the
value from Pt_ARG_HORIZONTAL_ALIGNMENT is used. The values to specify for
these horizontal alignment resources are:
• Pt_LEFT
• Pt_RIGHT
• Pt_CENTER
For example, you may want to set Pt_ARG_HORIZONTAL_ALIGNMENT to

Pt_CENTER, but ensure that the beginning of the text is readable if the label becomes
smaller than the text (for example, if the window is resized, and the label’s resize
policies allow clipping) by setting Pt_ARG_SECONDARY_V_ALIGN to Pt_LEFT.

You can also control the vertical alignment, i.e. whether the text is aligned to the
widget’s top or bottom margin, or centered vertically between the two margins. The
Pt_ARG_VERTICAL_ALIGNMENT resource controls this behavior.
Pt_ARG_SECONDARY_V_ALIGN controls the alignment of clipped text. The values
to specify for the vertical alignment are:
• Pt_TOP
• Pt_BOTTOM
• Pt_CENTER
By default, the text displayed in the label widget is left-aligned horizontally, and
centered vertically. The baseline is calculated by adding the ascender of the label font
to the top margin. When text is aligned to the bottom of the widget, the baseline is
calculated by subtracting the descender of the label font from the widget’s bottom
margin.
You can align the baselines of labels drawn with different fonts by selecting bottom
alignment for each of the widgets and choosing appropriate margins for them. In this
case, make sure you specify a widget height large enough to accommodate the height
of the largest font used.
The desired baseline for your aligned widgets is adjusted by the size of the maximum
descender of all the fonts used. For each label, add the difference between this
descender and the descender of that label’s font, then add this difference to the
widget’s bottom margin. Keep track of this value so that you can recalculate the
correct margin setting if you want to change the base margin or the font later on.
Image and bitmap labels

When the label is an image, the label widget gets the image from the
Pt_ARG_LABEL_IMAGE resource, which contains a pointer to an image structure, of
type PhImage_t, which is described in the Photon Library Reference.
The members of the image structure used by the label and button widgets are:
type Specifies the type of image. This determines which other members of the
image structure are significant and defines the format of the raw image
data.
Images can be palette-based or raw. Palette-based images, including
bitmaps, have a color palette that serves as a lookup table for determining
what color should be displayed for each pixel. Each pixel in the image is
encoded as an index into the lookup table, and the pixel is displayed using
the color contained in the corresponding table entry.
Raw images have actual RGB color values encoded in the image data.
More than one pixel may be encoded in each byte of the image data, so
image-scan lines are padded out to a byte boundary.
Bitmaps are encoded with 1 bit-per-pixel, with the most significant bit first.
The types are:

• Pg_BITMAP_BACKFILL — a bitonal image; the two colors are

specified in the color palette.
• Pg_BITMAP_TRANSPARENT — a monochrome image. The bits in the
image data that are set to 1 are drawn using color palette entry 1; zeros
are treated as transparent, so they’re not drawn.
The other types of palette-based images are:
• Pg_IMAGE_PALETTE_BYTE — palette-based image encoded as 8
bits-per-pixel.
• Pg_IMAGE_PALETTE_NIBBLE — palette-based image encoded as 4
bits-per-pixel. The most significant nibble in a byte specifies the
leftmost pixel.
Raw images are all encoded using 16, 24, or 32 bits-per-pixel. The types of
raw images are:
• Pg_IMAGE_DIRECT_8888 — raw image with 8 bits each for blue,
green, and red (with an additional 8 bits reserved).
• Pg_IMAGE_DIRECT_888 — raw image with 8 bits each for blue, green,
and red.
• Pg_IMAGE_DIRECT_664 — raw image with 6 bits each for green and
red, and 4 bits for blue.
• Pg_IMAGE_DIRECT_1555 — raw image with 5 bits each for blue,
green, and red.
bpl The number of bytes used to encode each scan line. This depends on the
image type and size.
size The width and height of the image in pixels.
colors The number of colors used in the image for palette-based images. It’s used
for determining how many color palette entries are significant.
palette The color lookup table for determining the color of each pixel in the image.
image The raw image data.
For more information about manipulating images and image data formats, see the Raw
Drawing and Animation chapter of the Photon Programmer’s Guide.
Balloons
Balloons are a very handy feature of the PtLabel widget class. You can use a balloon
to display a line of text when the pointer pauses on top of a widget for more than a
second.
This can be very useful in an application with a lot of icons. Whenever you pause on
an icon, a little text box pops up beside it to display the name or action the icon
represents.
To use balloons with label class widgets:

1 Set the Pt_SHOW_BALLOON bit in the Pt_ARG_LABEL_FLAGS resource.
2 Set the Pt_ARG_BALLOON_POSITION resource to define the location.
The Pt_ARG_BALLOON_TEXT resource defines the text displayed in the balloon. If

this resource is not set, the Pt_ARG_TEXT_STRING is displayed instead. This allows
you to choose one of the two main uses of balloons, either to give further information
to the user, or to display the label text in cases where the label has been truncated.
New resources:

Pt_ARG_ACCEL_KEY char * String NULL
Pt_ARG_BALLOON_COLOR PgColor_t Scalar Pg_BLACK
Pt_ARG_BALLOON_FILL_COLOR PgColor_t Scalar Pt_BALLOONCOLOR
Pt_ARG_BALLOON_POSITION short Scalar Pt_BALLOON_RIGHT
Pt_ARG_BALLOON_TEXT char * String NULL
Pt_ARG_HORIZONTAL_ALIGNMENT unsigned char Scalar Pt_LEFT
Pt_ARG_LABEL_BALLOON PtWidget_t * (*)() Pointer PtInflateBalloon
Pt_ARG_LABEL_FLAGS char Flag Pt_LABEL_SELECT_SHIFT
Pt_ARG_LABEL_IMAGE PhImage_t * Image NULL

Pt_ARG_LABEL_TYPE char Scalar Pt_Z_STRING
Pt_ARG_LINE_SPACING unsigned short Scalar 0
Pt_ARG_MARGIN_BOTTOM unsigned short Scalar 0
Pt_ARG_MARGIN_LEFT unsigned short Scalar 0
Pt_ARG_MARGIN_RIGHT unsigned short Scalar 0
Pt_ARG_MARGIN_TOP unsigned short Scalar 0
Pt_ARG_SECONDARY_H_ALIGN signed short Scalar -1 (Not used)
Pt_ARG_SECONDARY_V_ALIGN signed short Scalar -1 (Not used)
Pt_ARG_TEXT_FONT char * String "TextFont09"
Pt_ARG_TEXT_IMAGE_SPACING int Scalar 2
Pt_ARG_TEXT_STRING char * String NULL
Pt_ARG_UNDERLINE1 PgColor_t Scalar Pg_BLACK
continued. . .


Pt_ARG_UNDERLINE2 PgColor_t Scalar Pg_TRANSPARENT
Pt_ARG_UNDERLINE_TYPE unsigned short Scalar Pt_NO_ULINE
Pt_ARG_VERTICAL_ALIGNMENT unsigned char Scalar Pt_CENTER
Pt_ARG_ACCEL_KEY
char * String NULL
The accelerator key to underline within the widget’s text string. You typically use this
resource for hotkeys.
Pt_ARG_BALLOON_COLOR
The balloon’s text color. See PgColor_t in the Photon Library Reference.
Pt_ARG_BALLOON_FILL_COLOR
PgColor_t Scalar Pt_BALLOONCOLOR
The balloon’s fill color. See PgColor_t in the Photon Library Reference.
Pt_ARG_BALLOON_POSITION
short Scalar Pt_BALLOON_RIGHT
Indicates where the balloon with the label’s text pops up. If Pt_ARG_LABEL_TYPE
is Pt_TEXT_IMAGE, this resource also controls the positioning of the text and image
elements relative to each other. Possible values:
• Pt_BALLOON_INPLACE
• Pt_BALLOON_TOP
• Pt_BALLOON_LEFT
• Pt_BALLOON_RIGHT
• Pt_BALLOON_BOTTOM

Pt_ARG_BALLOON_TEXT

char * String NULL
The text string to display in the balloon. If left blank, the Pt_ARG_TEXT_STRING is
used for balloons.
Pt_ARG_HORIZONTAL_ALIGNMENT
unsigned char Scalar Pt_LEFT
The horizontal alignment for the text string. Possible values:
• Pt_LEFT
• Pt_CENTER
• Pt_RIGHT
Pt_ARG_LABEL_BALLOON
PtWidget_t * (*)() Pointer PtInflateBalloon
By default, when you pause the pointer over this widget, the widget displays a small
balloon. If you want to change the look of the balloon, you can use this resource to
override the default inflate function.
Here’s the prototype of the inflate function:
PtWidget_t * InflateBalloon( PtWidget_t *window,
PtWidget_t *widget,
int position,
char *text,
char *font,
PgColor_t fill_color,
PgColor_t text_color );
The arguments are:
window The window widget of the widget that requires the balloon.
widget The widget that requires the balloon.
position Where the balloon is to pop up:

• Pt_BITMAP_BALLOON_BOTTOM

• Pt_BITMAP_BALLOON_INPLACE
• Pt_BITMAP_BALLOON_LEFT
• Pt_BITMAP_BALLOON_RIGHT
• Pt_BITMAP_BALLOON_TOP
text The text to display in the balloon.
font The font for the text.
fill_color The balloon’s fill color.
text_color The color of text in the balloon.
You can use the supplied values in your inflate function or ignore them and use your
own values.
Pt_ARG_LABEL_FLAGS
char Flag Pt_LABEL_SELECT_SHIFT
Possible values:
Pt_BACKFILL_TEXT
If this is set, the widget fills the text background with the
widget’s fill color before rendering the text.
Pt_LABEL_SELECT_SHIFT
If this is set, the text shifts down and to the right by one pixel
when the widget is armed. Otherwise, the text doesn’t shift.
Pt_SHOW_BALLOON
If the pointer remains motionless for 1.25 seconds over the
label, a balloon pops up with the label’s text.
Pt_BALLOON_AS_REQUIRED
Same as Pt_SHOW_BALLOON, except the balloon is inflated
only if the label is clipped by its parent container.
Pt_USE_ELLIPSIS Replace part of the text with an ellipsis (...) if there isn’t
enough space to display all of it.
Pt_ELLIPSIS_MIDDLE
Put the ellipsis into the middle of the text string, instead of at
its end(s). This flag is used only when you’ve set
Pt_USE_ELLIPSIS.

Pt_ARG_LABEL_IMAGE

the image to be used if the label type (see Pt_ARG_LABEL_TYPE, below) is
Pt_IMAGE or Pt_TEXT_IMAGE.
image is released when image is replaced or the widget is unrealized or destroyed.
Pt_ARG_LABEL_TYPE
char Scalar Pt_Z_STRING
The type of information displayed by the label. Possible values:
Pt_Z_STRING Use Pt_ARG_TEXT_STRING to display the text.
Pt_IMAGE Use Pt_ARG_LABEL_IMAGE to display an image.
Pt_TEXT_IMAGE Display the image and text of the label. You can specify the
positioning of these two elements relative to each other by
setting Pt_ARG_BALLOON_POSITION.
Pt_ARG_LINE_SPACING
The space, in pixels, between the lines of text in the label.

Pt_ARG_MARGIN_BOTTOM

The amount of space between the bottom of the label’s canvas and the canvas defined
by the basic widget.
Pt_ARG_MARGIN_LEFT
The amount of space between the left side of the label’s canvas and the canvas defined
by the basic widget.
Pt_ARG_MARGIN_RIGHT
The amount of space between the right side of the label’s canvas and the canvas
defined by the basic widget.
Pt_ARG_MARGIN_TOP
The amount of space between the top of the label’s canvas and the canvas defined by
the basic widget.
Pt_ARG_SECONDARY_H_ALIGN
signed short Scalar -1
The horizontal alignment for the text string, if the text string is clipped. Possible
values:
• Pt_LEFT
• Pt_CENTER
• Pt_RIGHT

Pt_ARG_SECONDARY_V_ALIGN

signed short Scalar -1
The vertical alignment for the text string, if the text string is clipped. Possible values:
• Pt_TOP
• Pt_CENTER
• Pt_BOTTOM
Pt_ARG_TEXT_FONT
The font used for the label’s text string; see PgSetFont().
Pt_ARG_TEXT_IMAGE_SPACING
int Scalar 2
The space, in pixels, between the text and the image in the label.
Pt_ARG_TEXT_STRING
char * String NULL
The text string to be displayed if Pt_ARG_LABEL_TYPE is Pt_Z_STRING or

Pt_TEXT_IMAGE, as well as the text to display in the balloon if
Pt_ARG_BALLOON_TEXT is blank.
Pt_ARG_UNDERLINE1
The underline color for the first line.

Pt_ARG_UNDERLINE2

PgColor_t Scalar Pg_TRANSPARENT
The underline color for the second line (used to create thick or beveled underlines).
Pt_ARG_UNDERLINE_TYPE
unsigned short Scalar Pt_NO_ULINE
The type of underline. Possible values:
• Pt_NO_ULINE
• Pt_DOUBLE_ULINE (use with underline color)
• Pt_SINGLE_ULINE (use with underline color)
• Pt_ULINE_ETCHED_IN (use with border color)
• Pt_ULINE_ETCHED_OUT (use with border color)
Pt_ARG_VERTICAL_ALIGNMENT
The vertical alignment for the text string. Possible values:
• Pt_TOP
• Pt_CENTER
• Pt_BOTTOM

continued. . .


Pt_ARG_DIM PtWidget
continued. . .


Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
continued. . .



© 2010, QNX Software Systems GmbH & Co. KG. PtLine
A line
Class hierarchy:
PtWidget → PtBasic → PtGraphic → PtLine
PhAB icon:
Public header:
<photon/PtLine.h>
Description:
You can use PtLine to create line primitives.
A PtLine widget.
A line is defined by the origin and two points:
Pt_ARG_ORIGIN
Origin for the line’s coordinate space.
Pt_ARG_POINTS
The line’s start and end points. If you don’t set these points, no line is rendered.
For more information, see PtGraphic.

continued. . .

PtLine © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_DIM PtWidget
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtLine

Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
continued. . .

PtLine © 2010, QNX Software Systems GmbH & Co. KG.

Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

© 2010, QNX Software Systems GmbH & Co. KG. PtList
A scrolling list of text items
Class hierarchy:
PtList
PhAB icon:
Public header:
<photon/PtList.h>
Description:
The PtList class displays a scrolling list of text items. You can select one or more
items, depending on the selection policy.
A PtList containing text items.
Lists are particularly useful for presenting a large or unknown number of textual items
(e.g. a set of items changing over time). Lists have the added advantage of displaying
the set of items currently selected, and allowing more than one item to be selected at
once (see the Pt_ARG_SELECTION_MODE resource defined by PtGenList).
If the number of items is too large to display in the area allocated to the list, the widget
can display a vertical scrollbar. You can use the inherited Pt_ARG_LIST_FLAGS
resource to control when the scrollbar appears: always, never, or as required.
Limitations
PtList widgets have a few limitations:
• They display only text. If you want to display an image for each item, use a
PtRawList or PtTree instead.
• All items are in the same font.
• All unselected items are the same color
• All selected items are the same color.

PtList © 2010, QNX Software Systems GmbH & Co. KG.
Displaying items in columns

To display items in columns, you can:
• Create a PtDivider widget as a child of the PtList. Put it at the top of the list,
and create (for example) PtButton widgets as children of the divider, one for each
column. The width of each button is the width of the column.
Or
• Use the inherited Pt_ARG_LIST_COLUMN_POS resource.
With both methods, use Tab characters in the item strings to separate the text for each
column.
Even if you use columns, each line in the list remains a single item. When you click
on any part of the line, the entire line is selected — having columns doesn’t make the
list into a spreadsheet.
Creating lists
If you know the list of available choices when you create the list, you can specify it
using the Pt_ARG_ITEMS resource. This resource takes an array of null-terminated
strings.
You should establish the selection policy for the list when it’s created. The resource
that controls the selection policy is Pt_ARG_SEL_MODE.
The default selection policy is browse selection mode, which is the more user-friendly
of the two selection modes that allow a single selection.
If the number of items in a widget is variable, or is known to be large, you should
control the size of the widget by explicitly setting dimensions or limiting the number
of items displayed.
If you ever need to get the items in a list, you can use some code like this:
PtArg_t args[1];
short *num, i;
char **items = NULL;
PtSetArg(&args[0], Pt_ARG_ITEMS, &items, &num);

PtGetResources(list_wgt, 1, args);
for (i = 0; i < *num; i++)

printf("Item %d: %s\n", i, items[i]);
Controlling the number of items displayed

To control the number of visible items in the list widget, use the
Pt_ARG_VISIBLE_COUNT resource. The number of visible items is the number of
list items displayed in the list at any given time. If this number is less than the total
number of items in the list, the list widget can add a vertical scrollbar so that you can
scroll through the whole list.

If you specify it, the number of visible items is used to calculate the dimensions of the
list (overriding any explicit dimensions specified in Pt_ARG_DIM).
Selection notification
The list widget uses the Pt_CB_SELECTION callback to notify your application
whenever you make a new selection. The cbdata passed to the callback always
contains a pointer to a PtListCallback_t structure. The selection policy in effect
for the widget at the time of the callback determines which members of the structure
are valid.
The mode member of the callback data structure indicates the selection mode that
Handling single selections
Single selection and browse selection modes let you select only a single item. In
browse mode, the selection isn’t made until you release the pointer button after
dragging the pointer over the list items.
In either case, the selection callback is invoked when you make the selection. The
following members of the callback data structure identify the item that you selected:
• item — the textual label for the selected item
• item_len — the size of the item’s label, in bytes
• item_pos — the index of the selected item in the array of items maintained by the
Pt_ARG_ITEMS resource.
Handling multiple selections
Multiple selection modes, including extended selection, let you select several items at
once. When the selection callback is invoked, more than one item may have been
added to the set of selected items.
The data passed to the callback function uses these members to identify the complete
set of selected items:
• sel_item_count — the number of currently selected items
• sel_array — an array of indexes for each currently selected item.
Each index in the array refers to the original array of items maintained by the
Pt_ARG_ITEMS resource.
New resources:


Pt_ARG_ITEMS char *, short Array NULL
Pt_ARG_LIST_BALLOON PtListBalloonF_t * Pointer See below
Pt_ARG_LIST_SPACING short Scalar 0
Pt_ARG_MODIFY_ITEMS PtListModifyItems_t Struct Write-only
Pt_ARG_SELECTION_INDEXES unsigned short, short Array NULL
Pt_CB_LIST_INPUT PtCallback_t * Link NULL
Pt_CB_SELECTION PtCallback_t * Link NULL
Pt_ARG_ITEMS
char *, short Array NULL
An array of pointers to text items to be displayed in the list.
Pt_ARG_LIST_BALLOON
PtListBalloonF_t * Pointer See below
A function that inflates a balloon for the item the pointer is on. PtListBalloonF_t
is a function type:
typedef PtWidget_t *PtListBalloonF_t(

PtWidget_t *widget, PtWidget_t *parent,
PhArea_t *area, PtListColumn_t const *col,
int coln, const char *item,
unsigned index, const char *font);
The arguments are as follows:
widget A pointer to the PtList widget.
parent A pointer to its parent window.
area A pointer to a PhArea_t structure (see the Photon Library Reference) that
defines the area that covers the item. The area->pos member is relative to
the parent window.
col The position of the column the pointer is on.
coln The index of the column the pointer is on.

item The item the pointer is on.

index The index of item.
font The widget’s Pt_ARG_LIST_FONT resource.
The default function does this:
return
PtGenListCreateTextBalloon(
widget, parent,
PtGenListSetColumnBalloon ( area, col ),
item, coln, font);
Pt_ARG_LIST_SPACING
short Scalar 0
The spacing, in pixels, between the items in the list.
Pt_ARG_MODIFY_ITEMS (write only)

PtListModifyItems_t Struct
Used internally by the convenience functions.
Pt_ARG_SELECTION_INDEXES
unsigned short, short Array NULL
An array of indexes indicating which list items given by the Pt_ARG_ITEMS array are
currently selected.
Pt_CB_LIST_INPUT
on each mouse and key event. Each callback is passed a PtCallbackInfo_t
structure that contains at least the following members:
reason Pt_CB_LIST_INPUT

reason_subtype The event type (same as event->type). For more info, see the
event types described for the PhEvent_t structure in the Photon
Library Reference.
cbdata A pointer to a PtListInput_t structure that contains at least the

following members:
PhPoint_t pos; The mouse position relative to the item (valid

only for mouse events). See PhPoint_t in
char * item; For mouse events, the item under the cursor.
For key events, the item that will be the
current item (see “Current item” in the
description of PtGenList) after the event is
processed normally.
unsigned index; The index of that item (the first item on the
list has an index of 1).
int consumed; Initially set to Pt_CONTINUE. Your callback
function can suppress normal handling of the
event by setting this field to another value. In
the case of key events, set it to Pt_END to
consume the event, or to Pt_HALT to pass the
event to the parent widget. Mouse events are
always consumed.
Pt_CB_SELECTION
whenever you select an item from the list. Each callback is passed a
PtCallbackInfo_t structure that contains at least the following members:
reason Pt_CB_SELECTION
reason_subtype This value depends on the value of

Pt_ARG_SELECTION_MODE. In general, the value of
reason_subtype is:
• Pt_LIST_SELECTION_FINAL when the mouse button is
released inside the widget or the Enter is pressed (selection is
accepted).

• Pt_LIST_SELECTION_CANCEL when the mouse button is

released outside the widget (previous state restored).
• Pt_LIST_SELECTION_BROWSE when the mouse button is
held down, the space bar is used to select an item, or arrow
keys are being used to scroll through the list (a selection is in
the process of being made).

cbdata A pointer to a PtListCallback_t structure that contains at

unsigned mode The selection mode.

char *item The item just selected; see below.
int item_len The length of the item, in bytes.
int item_pos The position of the item in the array of
items in the list.
char **sel_items The list of selected items.
unsigned short *sel_array
An array of the selected positions within
the list.
int sel_item_count The number of items in the sel_items list
and the sel_array list.
The item member of the PtListCallback_t structure identifies the item that you
just selected (or unselected in modes that let you unselect items by clicking on them).
Depending on the selection mode used by the list, any previously selected items might
or might not remain selected — check sel_items or sel_array.

continued. . .


Pt_ARG_DIM PtWidget
continued. . .


Pt_ARG_POS PtWidget
continued. . .


Pt_ARG_VISIBLE_COUNT PtGenList See below.
Pt_CB_ARM PtBasic
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
Pt_ARG_VISIBLE_COUNT
Although this resource is inherited from PtGenList, it’s used in a different way. For
PtGenList, Pt_ARG_VISIBLE_COUNT is a read-only resource that tells you the
number of visible items. For PtList, it can be set to number of items you want to
display in the list. If it isn’t specified, or is set to 0, the widget displays as many items
as its specified dimensions allow.

Pt_CB_DND
For Pt_CB_DND callbacks for a PtList, the cbinfo->cbdata is a pointer to a
PtListDndCallback_t structure, containing at least the following members:
char *item The target item involved in the drag-and-drop operation.
unsigned long flags

Possible values:
the item.
below the item.

The PtList widget defines the following convenience functions that make it easier to
use the list once it’s been created:
PtListAddItems() Add one or more items to the list at a specified position.
PtListDeleteAllItems()
Remove all the items from the list.
PtListDeleteItemPos()
Delete a range of items by position.
PtListDeleteItems() Delete items in the list by name.
PtListGotoPos() Make the item at the specified position the current item and
display it.
PtListItemExists() Determine whether or not an item exists within the list.
PtListItemPos() Determine the position of an item within the list.

PtListRemovePositions()
Remove the items at the specified positions.
PtListReplaceItemPos()
Replace items by position number.
PtListReplaceItems()
Replace items by item text.
PtListSelectPos() Select the item at the specified position.
PtListShowPos() Display the item at the specified position.
PtListUnselectPos() Unselect the item at the specified position.

© 2010, QNX Software Systems GmbH & Co. KG. PtListAddItems()
Add items to a list
Synopsis:
int PtListAddItems( PtWidget_t *widget,
const char **items,
int item_count,
unsigned int position );
Description:
This function lets you add one or more items to a list widget at a specified position.
The items argument points to an array of items and item_count indicates the number
of strings in the array.
List positions start at 1, not 0. If you specify a position of 0, the items are added to the
end of the list.
If you add new items in between existing items, the rest of the items are moved down
the list.
Returns:
0 Success.
-1 A memory allocation error occurred, or the specified widget isn’t a PtList

widget.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtList

PtListDeleteAllItems() © 2010, QNX Software Systems GmbH & Co. KG.
Delete all items from a list
Synopsis:
int PtListDeleteAllItems( PtWidget_t *widget );
Description:
This function deletes all the items from a list.
Returns:
0 Success.
-1 The specified widget isn’t a PtList widget.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtList, PtListDeleteItems(), PtListDeleteItemPos(), PtListRemovePositions()

© 2010, QNX Software Systems GmbH & Co. KG. PtListDeleteItemPos()
Delete a range of items from a list
Synopsis:
int PtListDeleteItemPos( PtWidget_t *widget,
int item_count,
int position );
Description:
This function deletes item_count items from the list, starting from position. The first
item in the widget has a position of 1, not 0.
Returns:
0 Success.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtList, PtListDeleteAllItems(), PtListDeleteItems(), PtListRemovePositions()

PtListDeleteItems() © 2010, QNX Software Systems GmbH & Co. KG.
Delete specific items from a list
Synopsis:
int PtListDeleteItems( PtWidget_t *widget,
const char **items,
int item_count );
Description:
This function deletes each item in the items array from the list. The item_count
argument indicates the number of strings in the array.
Returns:
0 Success.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtList, PtListDeleteAllItems(), PtListDeleteItemPos(), PtListRemovePositions()

© 2010, QNX Software Systems GmbH & Co. KG. PtListGotoPos()
Make an item the current item and display it
Synopsis:
void PtListGotoPos( PtWidget_t *widget,
int pos );
Description:
The first item in the widget has an index of 1. If pos is 0, there will be no current item.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtList, PtListShowPos()

PtListItemExists() © 2010, QNX Software Systems GmbH & Co. KG.
Determine whether a list contains a particular item
Synopsis:
int PtListItemExists( PtWidget_t *widget,
const char *item );
Description:
This function performs a linear search on the list for the specified item.
Returns:
1 The item exists in the list.
0 The item wasn’t found.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtList, PtListItemPos()

© 2010, QNX Software Systems GmbH & Co. KG. PtListItemPos()
Determine the position of an item in a list
Synopsis:
int PtListItemPos( PtWidget_t *widget,
const char *item );
Description:
This function performs a linear search on the list for the specified item.
Returns:
The position of the item, or 0 if it wasn’t found.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtList, PtListItemExists()

PtListRemovePositions() © 2010, QNX Software Systems GmbH & Co. KG.
Remove items in a list at specific positions
Synopsis:
int PtListRemovePositions(
PtWidget_t *widget,
const unsigned short *pos_list,
int pos_count );
Description:
This function deletes the item at each position specified in the array pos_list. The first
item in the widget has a position of 1, not 0. The pos_count argument specifies the
number of entries in the pos_list array.
Returns:
0 Success.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtList, PtListDeleteAllItems(), PtListDeleteItemPos(), PtListDeleteItems()

© 2010, QNX Software Systems GmbH & Co. KG. PtListReplaceItemPos()
Replace items in a list at a specific position
Synopsis:
int PtListReplaceItemPos( PtWidget_t *widget,
const char **new_items,
int item_count,
int position );
Description:
This function replaces item_count items in the list with new_items. The position
argument tells the function where to start. The first item in the widget has a position of
1, not 0.
Returns:
0 Success.
-1 A memory allocation error occurred, or the specified widget is not a PtList

widget.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtList, PtListReplaceItems()

PtListReplaceItems() © 2010, QNX Software Systems GmbH & Co. KG.
Replace specific items in a list
Synopsis:
int PtListReplaceItems( PtWidget_t *widget,
const char **old_items,
const char **new_items,
int item_count );
Description:
This function searches the entire list for each item in old_items. Every occurrence of
each item found is replaced with the corresponding new_item. This operation
continues until item_count is reached.
Returns:
0 Success.
-1 A memory allocation error occurred, or the specified widget is not a PtList

widget.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtList, PtListReplaceItemPos()

© 2010, QNX Software Systems GmbH & Co. KG. PtListSelectPos()
Select the item at a given position
Synopsis:
void PtListSelectPos( PtWidget_t *widget,
int pos );
Description:
This function selects the item at the given position. The first item in the widget has a
position of 1, not 0.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtList, PtListUnselectPos()

PtListShowPos() © 2010, QNX Software Systems GmbH & Co. KG.
Show the item at the given position
Synopsis:
void PtListShowPos( PtWidget_t *widget,
int pos );
Description:
This function scrolls the list pointed to by widget to make the item with the position
given by pos visible. The first item in the widget has a position of 1, not 0. If the item
is already visible, this function does nothing.
This function doesn’t affect which items are currently selected.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtList, PtListGotoPos()

© 2010, QNX Software Systems GmbH & Co. KG. PtListUnselectPos()
Unselect the item at the given position
Synopsis:
void PtListUnselectPos( PtWidget_t *widget,
int pos );
Description:
This function unselects the item at the given position. The first item in the widget has
a position of 1, not 0.
PtListUnselectPos() has no effect if the Pt_ARG_SELECTION_MODE resource is set
to Pt_SELECTION_MODE_RANGE.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtList, PtListSelectPos()

PtMenu © 2010, QNX Software Systems GmbH & Co. KG.
A popdown or pullup menu
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtGroup → PtMenu
PhAB icon:
None — use PhAB’s Menu module.
Public header:
<photon/PtMenu.h>
Description:
Menus display a list of possible selections (called items) and let you choose one of
them. The PtMenu class provides popup and pulldown menus that work in either
press-drag-release or click-move-click mode.
A PtMenu widget that contains various menu items.
You can use PhAB’s Menu module instead of this widget, which makes it easier to add
menus to your project. See “Menu modules” in the Working with Modules chapter of
the Photon Programmer’s Guide.
The selections displayed in a menu are usually pushbuttons that activate application
functions, but they may also be toggle buttons, cascaded menu buttons that invoke
submenus, or any other selectable widget. Although menus usually consist of
PtMenuButton widgets, you can use any type of widget as a menu item by making it
the child of a PtMenu widget.
If PtMenu has any PtLabel-class children that have the Pt_ARG_ACCEL_KEY
resource defined, the menu attaches hotkey callbacks on behalf of those children.

© 2010, QNX Software Systems GmbH & Co. KG. PtMenu
A PtMenu widget blocks any nonmenu hotkeys while it’s displayed.
If you use a nonselectable widget as a menu item, you can make it selectable by
setting the Pt_SELECTABLE bit in its Pt_ARG_FLAGS (see PtWidget). PtMenu then
sets up callbacks on its children to alter their behavior where necessary, thus ensuring
that the children operate as you expect. For example, the children automatically
highlight in press-drag-release mode.
If a menu item has a PtMenu widget as a child, and that child has the
Pt_MENU_CHILD bit set in its Pt_ARG_MENU_FLAGS resource, the child behaves
as a submenu and is realized when necessary.
Most applications have a menu bar, a horizontal bar (usually a PtMenuBar widget)
across the top of the application window. The menu bar contains a number of menu
buttons; when you click on one, the associated pulldown menu appears.
A menu may also be activated or popped up in response to an event such as a button
press inside another type of widget. Known as a popup menu, this type of menu
normally appears at the current pointer position.
A menu is displayed when it’s activated; it may be in one of these modes:
Press-drag-release Press the pointer button and hold it down to keep the menu
displayed. Drag the pointer to the desired selection and release
the button over the selection to choose it. While dragging, the
selection underneath the pointer is displayed in a different
color.
Click-stay Click the pointer button — that is, press and then release the
button without moving the pointer. The menu is displayed until
you click on an item. The item you choose is displayed in a
different color.
When a selectable widget (such as a button or toggle) is chosen from the menu:
• the widget is activated
• the associated action is performed
• any menus displayed disappear.
If the selected item is a cascaded menu button, its menu is activated and it’s displayed
to the right of or below the selection.
Creating menus
You can use PtMenu to create either a pulldown or a popup menu.
The Pt_ARG_MENU_FLAGS resource controls the menu’s behavior and appearance,
including:

• the size
• the lifetime of the menu
• the behavior of a submenu or cascaded menu.
You can set Pt_ARG_MENU_TITLE to specify a title to be displayed at the top of the
menu. You can also set Pt_ARG_MENU_TITLE_FONT to specify the title’s font.
You can use Pt_ARG_MENU_TEXT_FONT to specify the font to use for displaying
menu items. This resource overrides the normal default font for text items placed in
the menu.
Populating the menu
As with other containers, items are placed in a menu by creating them as children of
the menu itself. The widgets that you place in the menu behave according to their
type. You can use any widgets that have the Pt_SELECTABLE flag set in their
Pt_ARG_FLAGS. This includes buttons, toggle buttons, and menu buttons.
Menu buttons within the menu provide cascaded submenus. For more information on
how to create cascaded submenus, see “Cascaded Menus.”
Widgets that have the Pt_AUTOHIGHLIGHT flag set automatically have the visual
cuing provided for you. All the widgets in the Photon widget library that set the
Pt_SELECTABLE flag by default set this flag as well. If you explicitly set either of
these flags for other widget types, be sure to use them appropriately in combination so
they’ll behave correctly in a menu.
The menu may also contain other widgets that aren’t menu selections. For example,
you can add separators and labels to the menu to make a visual distinction between
different sections of the menu and to enhance its appearance.
Sizing
Normally, the menu is wide enough to hold the widest menu item; all the menu items
are made this size as well. The Pt_MENU_AUTO bit in the Pt_ARG_MENU_FLAGS
resource controls menu sizing.
If you want to explicitly control the sizes of the menu items, you can clear this flag —
it’s then your responsibility to set the dimensions of each menu item.
Lifetime
A menu may be created either in advance or dynamically in response to the action that
activated it.
If you create the menu in advance, you have to create a callback function to position
the menu and realize it in response to the action that activates it. When you make a
selection, the menu unrealizes itself.
To create the menu dynamically, your callback function must create the menu first,
then position it and realize it. You may also want the menu to be re-created from

scratch the next time the callback is invoked. In this case, you can create the menu as a
transient menu by setting the Pt_MENU_TRANSIENT bit in Pt_ARG_MENU_FLAGS.
This menu destroys itself after you select a menu item.
The menu might be destroyed before the selected menu item’s callback is invoked. To
make sure that the menu item’s callback is called first, attach the menu item callback
as follows:
PtCallback_t callbacks[] = { { menu_item_callback, NULL } };
PtSetArg( &arg[0], Pt_ARG_TEXT_STRING, "Open", 0 );

PtSetArg( &arg[1], Pt_CB_ACTIVATE, callbacks, Pt_LINK_INSERT );
item = PtCreateWidget( PtMenuButton, menu, 2, arg );
Pulldown menus
To create a pulldown menu, you must create the menu as a child of the menu button.
You must also attach a callback to the menu button that pulls down the menu in
response to a button press.
Attach the callback to the Pt_CB_ARM or Pt_CB_MENU callback list (see
PtBasic) so that both press-drag-release and click-stay modes work, then provide the
pointer to the menu widget as the client_data for the callback.
Your callback must position the menu beneath the menu button and make it appear. To
do this, call PtPositionMenu() with the menu widget as the first parameter, and a
NULL pointer as the second parameter. This function determines the correct position
for the menu, knowing that its parent is a menu button. After this, you can make the
menu appear by calling PtRealizeWidget(). For more information about these
functions, see the Photon Library Reference.
For example, to display a pulldown menu:
int
postMenu( PtWidget_t *w, void *client_data,
{
if (client_data)
{
PtWidget_t *menu = (PtWidget_t *)client_data;
PtPositionMenu(menu, NULL);
PtRealizeWidget(menu);
}
}
To create a pulldown menu invoked by a “File” menu button with this routine as the
callback function, use the following code:
fileMenu = PtCreateWidget(PtMenu, fileButton, 0, NULL);
create_file_items(fileMenu);
PtAddCallback(fileButton, Pt_CB_ARM, postMenu, fileMenu);

In this example, the create_file_items() function creates the menu items in the file
menu.

Popup menus
Popup menus are frequently used in an application’s work area. Often this area is not a
container widget. In this case, you don’t create the menu as a child of the work area
itself; instead, create the menu as a child of the work area’s parent.
As with pulldown menus, you have to provide a callback function or event handler to
activate your popup menu. This callback has to position the menu and make it appear.
If the widget that you wish to associate with the popup menu doesn’t have a
Pt_CB_ARM or Pt_CB_MENU callback list, the simplest way to activate the menu is
to associate an event handler with button-press events. Provide the menu pointer to the
event handler as client_data. The event handler should make sure that the appropriate
menu button was actually pressed before it activates the menu.
The event handler should position the menu by calling PtPositionMenu(). In this case,
pass the Photon event from the PtCallbackInfo_t structure as the second parameter
to the function. This identifies the pointer position where the menu should be placed.
The following function illustrates how you can activate a popup menu:
int
postMenu( PtWidget_t *w, void *client_data,
{
PhEvent_t *event = info ? info->event : NULL;
PhPointerEvent_t *ptr = event ? (PhPointerEvent_t *)
PhGetData(event) : NULL;
/* post the popup if the right button was pressed */

if (event && client_data &&
(event->type & Ph_EV_BUT_PRESS) &&
(ptr->buttons == 1))
{
PtPositionMenu(menu, event);
}
}
The following code illustrates how you can create a popup menu and activate it using
the above function:
PtSetArg(&arg[0], Pt_ARG_POS, &offsets.ul, 0);
PtSetArg(&arg[1], Pt_ARG_DIM, &workarea, 0);
PtSetArg(&arg[2], Pt_ARG_ANCHOR_FLAGS,
Pt_LEFT_ANCHORED_LEFT|Pt_RIGHT_ANCHORED_RIGHT|
Pt_TOP_ANCHORED_TOP|Pt_BOTTOM_ANCHORED_BOTTOM,
Pt_IS_ANCHORED);
PtSetArg(&arg[3], Pt_ARG_ANCHOR_OFFSETS, &offsets, 0);
raw = PtCreateWidget(PtRaw, window, 4, arg);
popupMenu = PtCreateWidget(PtMenu, window, 0, NULL );

create_file_items(popupMenu);
PtAddEventHandler(raw, Ph_EV_BUT_PRESS, popup_menu_cb,
popupMenu);

Cascaded menus
If you place a menu button in a menu and create another menu as its child, you’ll get a
cascaded submenu. Unlike pulldown menus or popup menus, you don’t have to attach
any callbacks to activate submenus — they’re handled automatically.
You must, however, set the Pt_MENU_CHILD bit in the Pt_ARG_MENU_FLAGS to
indicate that the menu is a submenu. If you want the submenu to appear to the right of
its parent — the conventional way that submenus cascade — you’ll also have to set the
Pt_MENU_RIGHT flag in the PtMenuButton widget’s Pt_ARG_BUTTON_TYPE
resource.
Here’s the create_file_items() function from the previous example; notice how it
creates a cascaded submenu:
void create_file_items(PtWidget_t *parent)

{
PtArg_t arg[3];
PtWidget_t *importButton, *importMenu;
PtCallback_t quit_callbacks[] = { {quit_cb, NULL} };
PtCallback_t noop[] = { {nop_cb, NULL} };
PtSetArg(&arg[0], Pt_ARG_TEXT_STRING, "Open", 0);

PtSetArg(&arg[1], Pt_ARG_TEXT_FONT, Helvetica_14B, 0);
PtSetArg(&arg[2], Pt_CB_ACTIVATE, noop, 1);
PtCreateWidget(PtButton, parent, 3, arg);
PtSetArg(&arg[0], Pt_ARG_TEXT_STRING, "New", 0);

PtSetArg(&arg[0], Pt_ARG_TEXT_STRING, "Import", 0);

PtSetArg(&arg[2], Pt_ARG_BUTTON_TYPE, Pt_MENU_RIGHT,
Pt_MENU_RIGHT);
importButton = PtCreateWidget(PtMenuButton, parent, 3, arg);
PtSetArg(&arg[0], Pt_ARG_MENU_FLAGS,
Pt_MENU_AUTO|Pt_MENU_CHILD,
Pt_MENU_AUTO|Pt_MENU_CHILD);
importMenu = PtCreateWidget(PtMenu, importButton, 1, arg );
create_import_items(importMenu);
PtCreateWidget(PtSeparator, parent, 0, NULL);
PtSetArg(&arg[0], Pt_ARG_TEXT_STRING, "Quit", 0);

PtSetArg(&arg[2], Pt_CB_ACTIVATE, quit_callbacks, 1);
}
Complete menu example

Here’s a complete example that uses all the techniques described above. It includes an
application window with a menu bar along the top, and a work area. The menu bar
consists of a File menu and a Help menu. The work area is a PtRaw widget that has a

popup menu associated with the right pointer button. The popup menu contains the
same selections as the file menu.
#include <Pt.h>
#include <stdlib.h>
/* The name of the font to use in the menus: */

char Helvetica_14B[MAX_FONT_TAG];
int
post_menu_cb(PtWidget_t *w, void *client_data, PtCallbackInfo_t *info)
{
client_data = client_data; info = info;
if (client_data)
{
PtPositionMenu(menu, NULL);
}
}
int
popup_menu_cb(PtWidget_t *w, void *client_data, PtCallbackInfo_t *info)
{
PhEvent_t *event = info ? info->event : NULL;
PhPointerEvent_t *ptr = event ? (PhPointerEvent_t *)
PhGetData
(event) : NULL;
w = w;
/* post the popup if the right button was pressed */

if (event && client_data &&
(event->type & Ph_EV_BUT_PRESS) &&
(ptr->buttons == 1))
{
PtPositionMenu(menu, event);
}
}
int
nop_cb(PtWidget_t *w, void *client_data,
{
PtArg_t arg[1];
char *text;
w = w; client_data = client_data; info = info;
PtSetArg(&arg[0], Pt_ARG_TEXT_STRING, &text, 0);

PtGetResources(w, 1, arg);
if (text)
printf("Pushed the %s button\n", text);
}
int
quit_cb(PtWidget_t *w, void *client_data, PtCallbackInfo_t *info)
{
w = w; client_data = client_data; info = info;
PtExit( EXIT_SUCCESS );
}

void create_import_items(PtWidget_t *parent)

{
PtArg_t arg[3];
PtSetArg(&arg[0], Pt_ARG_TEXT_STRING, "Image", 0);

PtSetArg(&arg[0], Pt_ARG_TEXT_STRING, "Bitmap", 0);

}
void create_file_items(PtWidget_t *parent)

{
PtArg_t arg[3];
PtWidget_t *importButton, *importMenu;
PtCallback_t quit_callbacks[] = { {quit_cb, NULL} };
PtSetArg(&arg[0], Pt_ARG_TEXT_STRING, "Open", 0);

PtSetArg(&arg[0], Pt_ARG_TEXT_STRING, "New", 0);

PtSetArg(&arg[0], Pt_ARG_TEXT_STRING, "Import", 0);

PtSetArg(&arg[2], Pt_ARG_BUTTON_TYPE, Pt_MENU_RIGHT,
Pt_MENU_RIGHT);
importButton = PtCreateWidget(PtMenuButton, parent, 3, arg);
PtSetArg(&arg[0], Pt_ARG_MENU_FLAGS,
Pt_MENU_AUTO|Pt_MENU_CHILD,
Pt_MENU_AUTO|Pt_MENU_CHILD);
importMenu = PtCreateWidget(PtMenu, importButton, 1, arg );
create_import_items(importMenu);
PtCreateWidget(PtSeparator, parent, 0, NULL);
PtSetArg(&arg[0], Pt_ARG_TEXT_STRING, "Quit", 0);

PtSetArg(&arg[2], Pt_CB_ACTIVATE, quit_callbacks, 1);
}
void create_help_items(PtWidget_t *parent)

{
PtArg_t arg[3];
PtSetArg(&arg[0], Pt_ARG_TEXT_STRING, "About", 0);

PtCreateWidget(PtMenuButton, parent, 3, arg);
}
int
main(int argc, char *argv[])
{
PtAppContext_t app;
PhDim_t dim, workarea, *group_size;
PhPoint_t pos;
PtArg_t arg[5];
PtWidget_t *window, *group, *raw;
PtWidget_t *fileButton, *helpButton;
PtWidget_t *fileMenu, *helpMenu, *popupMenu;


0, NULL)) == NULL)
/* Generate the name of the font for the menus. */

if(PfGenerateFontName("Helvetica", PF_STYLE_BOLD, 14,
Helvetica_14B) == NULL) {
perror("Unable to generate font name");
}
PtSetArg(&arg[0], Pt_ARG_ANCHOR_FLAGS,
Pt_LEFT_ANCHORED_LEFT|Pt_RIGHT_ANCHORED_RIGHT,
Pt_IS_ANCHORED);
PtSetArg(&arg[1], Pt_ARG_BEVEL_WIDTH, 2, 0);
PtSetArg(&arg[2], Pt_ARG_FLAGS, Pt_HIGHLIGHTED, Pt_HIGHLIGHTED);
group = PtCreateWidget(PtGroup, window, 3, arg);
PtSetArg(&arg[0], Pt_ARG_TEXT_STRING, "File", 0);

fileButton = PtCreateWidget(PtMenuButton, group, 2, arg);
PtSetArg(&arg[0], Pt_ARG_TEXT_STRING, "Help", 0);

helpButton = PtCreateWidget(PtMenuButton, group, 2, arg);
fileMenu = PtCreateWidget(PtMenu, fileButton, 0, NULL);

create_file_items(fileMenu);
helpMenu = PtCreateWidget(PtMenu, helpButton, 0, NULL);

create_help_items(helpMenu);
PtAddCallback(fileButton, Pt_CB_ARM, post_menu_cb, fileMenu);

PtAddCallback(helpButton, Pt_CB_ARM, post_menu_cb, helpMenu);
PtRealizeWidget(window);
PtSetArg(&arg[0], Pt_ARG_DIM, &group_size, 0);

PtGetResources(group, 1, arg);
workarea.w = 300;
workarea.h = 200;
pos.x = 0;
pos.y = group_size->h + 2 * 2;
PtSetArg(&arg[0], Pt_ARG_POS, &pos, 0);

PtSetArg(&arg[1], Pt_ARG_DIM, &workarea, 0);
raw = PtCreateWidget(PtRaw, window, 2, arg);
popupMenu = PtCreateWidget(PtMenu, window, 0, NULL );

create_file_items(popupMenu);
PtAddEventHandler(raw, Ph_EV_BUT_PRESS, popup_menu_cb, popupMenu);
PtRealizeWidget(raw);
dim.w = workarea.w;
dim.h = workarea.h + group_size->h + 2 * 2;
PtSetArg(&arg[0], Pt_ARG_DIM, &dim, 0);
PtSetResources(window, 1, arg);
PtMainLoop();
}

New resources:

Pt_ARG_MENU_FLAGS unsigned long Flag Pt_MENU_AUTO | Pt_MENU_TEXT_ALIGN
Pt_ARG_MENU_INPUT_GROUP short Scalar 0

Pt_ARG_MENU_ITEM_FILL_COLOR PgColor_t Scalar 0xCCCCCC
Pt_ARG_MENU_ITEM_HIGHLIGHT_COLOR PgColor_t Scalar 0xA6B1CE
Pt_ARG_MENU_SPACING short Scalar Value of Pt_ARG_BEVEL_WIDTH
Pt_ARG_MENU_TEXT_FONT char * String NULL
Pt_ARG_MENU_TITLE char * String NULL
Pt_ARG_MENU_TITLE_FONT char * String "MenuFont09"
Pt_ARG_SUBMENU_PARENT_HIGHLIGHT_COLOR PgColor_t Scalar 0xB0B0B0
Pt_ARG_MENU_FLAGS
unsigned long Flag Pt_MENU_AUTO | Pt_MENU_TEXT_ALIGN
Flags that control the menu’s appearance and behavior. You can set this resource to
any combination of the following bits:
Pt_MENU_AUTO Make all items the same width.
Pt_MENU_CHILD Let this menu override its parent menu.
Pt_MENU_GRADIENT
Fill the highlighted item with a gradient.
Pt_MENU_TEAR_OFF
Let the user “tear off” the menu from where it originally
appears and keep it somewhere else.
Pt_MENU_TEXT_ALIGN
Align text horizontally.
Pt_MENU_TRANSIENT
Destroy the menu on closing. The menu might be destroyed
before the callback for the selected menu item is invoked.

Pt_ARG_MENU_INPUT_GROUP

short Scalar 0
The input group for the menu. When this resource is set to a non-zero value, the menu
uses that input group’s rectangle to position itself on the screen. A mouse-click
outside of the menu in any other input group does not dismiss the menu.
If this resource is 0, and you have more than one input group, the menu picks a random
group to position itself. Mouse-clicks from any input group will dismiss the menu.
Pt_ARG_MENU_ITEM_FILL_COLOR
PgColor_t Scalar 0xCCCCCC
Menu items normally inherit their fill color from the menu, which inherits its color
from the parent widget. If you set this resource, this color is used as the fill color for
all menu items, except the items which have a non-transparent fill color.
Pt_ARG_MENU_ITEM_HIGHLIGHT_COLOR
PgColor_t Scalar 0xA6B1CE
The highlight fill color for menu items.
Pt_ARG_MENU_SPACING
short Scalar Value of Pt_ARG_BEVEL_WIDTH
The amount of space, in pixels, between each menu item. The default is the value of
the Pt_ARG_BEVEL_WIDTH resource defined by PtWidget.
Pt_ARG_MENU_TEXT_FONT
char * String NULL

The font used for PtLabel-based menu items; see PgSetFont() in the Photon Library
Reference. This resource overrides the normal default font for text items placed in the
menu.
Pt_ARG_MENU_TITLE
char * String NULL
The menu’s title. If you don’t want a title, set this resource to NULL.
Pt_ARG_MENU_TITLE_FONT
char * String "MenuFont09"
The font used for displaying the title.
Pt_ARG_SUBMENU_PARENT_HIGHLIGHT_COLOR
PgColor_t Scalar 0xB0B0B0
The highlight fill color for a menu item when an item in its submenu is selected.

Pt_ARG_ANCHOR_FLAGS PtWidget Not used by this class.
Pt_ARG_ANCHOR_OFFSETS PtWidget Not used by this class.
continued. . .


Pt_ARG_BASIC_FLAGS PtBasic Sets Pt_TOP_OUTLINE | Pt_BOTTOM_OUTLINE |
Pt_LEFT_OUTLINE | Pt_RIGHT_OUTLINE |
Pt_TOP_BEVEL | Pt_BOTTOM_BEVEL |
Pt_LEFT_BEVEL | Pt_RIGHT_BEVEL |
Pt_FLAT_FILL | Pt_TOP_LEFT_OUTLINE |
Pt_BOTTOM_RIGHT_OUTLINE |
Pt_ALL_OUTLINES | Pt_TOP_LEFT_BEVEL |
Pt_BOTTOM_RIGHT_BEVEL | Pt_ALL_BEVELS
Pt_ARG_BEVEL_CONTRAST PtBasic 25
Pt_ARG_CELL_HORZ_ALIGN PtGroup
Pt_ARG_CELL_VERT_ALIGN PtGroup
Pt_ARG_CONTAINER_FLAGS PtContainer Not used by this class.
Pt_ARG_DIM PtWidget
Pt_ARG_FLAGS PtWidget Sets Pt_DELAY_ACTIVATION |
Pt_DELAY_REALIZE|
Pt_HIGHLIGHTED
Pt_ARG_GROUP_FLAGS PtGroup
continued. . .


Pt_ARG_GROUP_HORZ_ALIGN PtGroup
Pt_ARG_GROUP_ORIENTATION PtGroup 1
Pt_ARG_GROUP_ROWS_COLS PtGroup
Pt_ARG_GROUP_SPACING PtGroup
Pt_ARG_GROUP_SPACING_X PtGroup
Pt_ARG_GROUP_SPACING_Y PtGroup
Pt_ARG_GROUP_VERT_ALIGN PtGroup
Pt_ARG_HEIGHT PtWidget 8
Pt_ARG_LAYOUT PtContainer
Pt_ARG_POS PtWidget
continued. . .


Pt_ARG_WIDTH PtWidget 9
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

© 2010, QNX Software Systems GmbH & Co. KG. PtMenuBar
A container for managing menu buttons
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtToolbar → PtMenuBar
PhAB icon:
Public header:
<photon/PtMenuBar.h>
Description:
The PtMenuBar class provides alignment of menu buttons, and cursor-key navigation
through menus.
A PtMenuBar that contains several menu buttons.
This widget is a container that aligns its children and automatically anchors itself to
the top and sides of its parent.
A PtMenuBar can have only PtMenuButton widgets as children.

Pt_ARG_ANCHOR_FLAGS PtWidget Pt_LEFT_ANCHORED_LEFT |
Pt_RIGHT_ANCHORED_RIGHT |
Pt_TOP_ANCHORED_TOP
Pt_ARG_AREA PtWidget height = 29
continued. . .

PtMenuBar © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_DIM PtWidget
Pt_ARG_FLAGS PtWidget |= Pt_HIGHLIGHTED
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtMenuBar

Pt_ARG_ORIENTATION PtToolbar
Pt_ARG_POS PtWidget
Pt_ARG_TOOLBAR_FLAGS PtToolbar &= ˜Pt_TOOLBAR_END_SEPARATOR
Pt_ARG_TOOLBAR_LAYOUT_FLAGS PtToolbar Pt_TOOLBAR_FROM_LINE_START |
Pt_TOOLBAR_TO_LINE_END
Pt_ARG_TOOLBAR_SPACING PtToolbar 10
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
continued. . .

PtMenuBar © 2010, QNX Software Systems GmbH & Co. KG.

Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

© 2010, QNX Software Systems GmbH & Co. KG. PtMenuButton
A button used to display a menu
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtCompound → PtMenuButton
PhAB icon:
Public header:
<photon/PtMenuButton.h>
Description:
The PtMenuButton class displays text or images with optional accelerator key text.
Menu buttons are used to present menus from within menu bars or other menus.
A PtMenuButton widget.
If you want an accelerator key, set the Pt_ARG_ACCEL_KEY resource that’s

inherited from PtLabel. For example:
narg = 0;
PtSetArg (&args [narg++], Pt_ARG_TEXT_STRING, "File", 0);
PtSetArg (&args [narg++], Pt_ARG_ACCEL_KEY, "F", 0);
PtCreateWidget (PtMenuButton, database.menu, narg, args);
New resources:

Pt_ARG_ACCEL_FONT char * String "TextFont09b"
Pt_ARG_ACCEL_TEXT char * String ""
Pt_ARG_BUTTON_TYPE unsigned short Scalar Pt_MENU_TEXT
Pt_ARG_MODIFIER_KEYS unsigned long Flag 0
These resources are actually defined in <photon/PtMenuLabel.h> for the

PtMenuLabel widget, which you’ll never instantiate on its own.

PtMenuButton © 2010, QNX Software Systems GmbH & Co. KG.
Pt_ARG_ACCEL_FONT

The font used to render the hotkey accelerator text.
Pt_ARG_ACCEL_TEXT
char * String ""
The text that identifies the hotkey that’s bound to this widget.
Pt_ARG_BUTTON_TYPE
unsigned short Scalar Pt_MENU_TEXT
The type of menu button; one of the following:
Pt_MENU_TEXT Display the accelerator text, if it’s defined.
Pt_MENU_RIGHT Display the submenu to the right of the button.
Pt_MENU_DOWN Display the submenu below the button.
Pt_MENU_UP Display the submenu above the button.
Pt_ARG_MODIFIER_KEYS
The modifier key(s) to be displayed in the menu button, expressed as a bitwise OR of

one or more of the Pk_KM_* flags defined in <photon/PkKeyDef.h>.


Pt_ARG_BASIC_FLAGS PtBasic Pt_FLAT_FILL
Pt_ARG_DIM PtWidget
Pt_ARG_EFLAGS PtWidget &= ˜Pt_CONSUME_EVENTS
continued. . .


Pt_ARG_FLAGS PtWidget Pt_SELECTABLE|
Pt_MENU_BUTTON|
Pt_GETS_FOCUS|
Pt_MENUABLE|
Pt_ALL_BUTTONS
Pt_ARG_POS PtWidget
continued. . .


Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
continued. . .


Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

© 2010, QNX Software Systems GmbH & Co. KG. PtMeter
A meter
Class hierarchy:
PtWidget → PtBasic → PtMeter
PhAB icon:
Public header:
<photon/PtMeter.h>
Description:
The PtMeter widget is drawn as a half circle with divisional ticks at 1/4, 1/2, and 3/4
of the arc.
100
A PtMeter widget.
You can move the needle in several ways:
• With the mouse — click once to move the meter to the current mouse position;
drag the mouse with a button held down to make the needle follow the mouse,
through meter values.
• With the keyboard — you can use these resources to set up keys to move the needle
to the left or right:
- Pt_ARG_METER_KEY_LEFT
- Pt_ARG_METER_KEY_RIGHT
• Programatically — set the Pt_ARG_METER_NEEDLE_POSITION resource.
Your meter can include up to 3 severity arcs, drawn in colors to indicate different
levels of the meter:
• Arc 1 — Pt_ARG_METER_MIN_NEEDLE_POSITION to
Pt_ARG_METER_LEVEL1_POS.
• Arc 2 — Pt_ARG_METER_LEVEL1_POS to Pt_ARG_METER_LEVEL2_POS.
• Arc 3 — Pt_ARG_METER_LEVEL2_POS to
Pt_ARG_METER_MAX_NEEDLE_POSITION.
The widget bases its size on the text size and the specified dimensions. If the given
dimensions are too small, it sizes itself appropriately based on the resize policy. The

PtMeter © 2010, QNX Software Systems GmbH & Co. KG.
height of the widget depends on the radius of the meter, which in turn depends on the
X dimension and text sizes.
Creating a 3-arc meter

To create a 3-arc meter with the default arc colors and positions (as shown above):
...
PhArea_t area = { { 10, 10 }, { 200, 200 } };
...
PtSetArg(&args[0], Pt_ARG_AREA, &area, 0);
PtCreateWidget(PtMeter, parent, 1, args)
...
Creating a 1-arc meter

This example creates a 1-arc meter that has a minimum value of 0, and a maximum of
1000. You can move its needle by clicking the mouse buttons; a callback notifies your
application when you move the needle:
1000
A one-arc PtMeter widget.
...
PhArea_t area = { { 10, 10 }, { 200, 200 } };
PtCallback_t cb[1] = { {moved_cb, NULL} };

PtSetArg(&args[1], Pt_ARG_METER_MAX_NEEDLE_POSITION,
1000, 0);
PtSetArg(&args[2], Pt_CB_METER_MOVED, &cb[0], 0);
PtCreateWidget(PtMeter, parent, 3, args)
...
int moved_cb(PtWidget_t *widget, void *data,

{
PtMeterCallback_t *mydata;
mydata = info->cbdata;
printf("Got the callback. Position was: %d severity: %d\n ",

mydata->position, mydata->severity);
}
...

Creating a 3-arc meter movable by keys and mouse

This example creates a 3-arc meter whose needle can be moved:
• with the mouse
• to the right with ↑ (Pk_Up)
• to the left with ↓ (Pk_Down)
with an increment of 10 for each keystroke (for example, the meter moves 0, 10, 20, ...
when you press the up-arrow key).
...
PhArea_t area = { { 10, 10 }, { 200, 200 } };
PtCallback_t cb[1] = { {moved_cb, NULL} };

PtSetArg(&args[1], Pt_ARG_METER_KEY_LEFT, Pk_Down, 0);
PtSetArg(&args[2], Pt_ARG_METER_KEY_RIGHT, Pk_Up, 0);
PtSetArg(&args[3], Pt_ARG_METER_INCREMENT, 10, 0);
PtSetArg(&args[4], Pt_CB_METER_MOVED, &cb[0], 0);
PtCreateWidget( PtMeter, parent, 5, args );
...
int moved_cb( PtWidget_t *widget, void *data,

{
printf("Got the callback. Position was: %d severity: %d\n",

mydata->position, mydata->severity);
}
You’ll notice that as you move the needle on the widget, there’s very little flickering.
This is because when the needle moves it’s merely erased and then drawn at the new
position. However, if you create a meter with Pg_TRANSPARENT as a fill color, you’ll
notice more flickering because the needle can’t merely be erased — the background
must be drawn as well. In this case, flickering is reduced by calculating a bounding
rectangle for the needle and redrawing only that rectangle. The most flickering
(redraw) occurs when the needle is at 45° or 135°.
For flicker-free performance when using Pg_TRANSPARENT as a fill color, put the
PtMeter inside a PtOSContainer widget.
Full meter example

#include <stdio.h>
#include <Pt.h>
#include <photon/PtMeter.h>
PtWidget_t *window, *meter, *quit, *sev_lbl, *pos_lbl;
/* Callback for when the meter moves */

int meter_cb( PtWidget_t *widget, void *data,
{

char pos[10], sev[5];
PtArg_t args[2];
itoa(mydata->position, pos, 10);
itoa(mydata->severity, sev, 10);
/* Set the position label to the current position. */

PtSetArg(&args[0], Pt_ARG_TEXT_STRING, pos, 0);
PtSetResources(pos_lbl, 1, args);
/* Set the severity label to the current severity. */

PtSetArg(&args[0], Pt_ARG_TEXT_STRING, sev, 0);
PtSetResources(sev_lbl, 1, args);
}
/* Callback for the quit button */

int quit_cb( PtWidget_t *widget, void *data,
{
PtExit (EXIT_SUCCESS);
}
int main(int argc, char *argv[])

{
PtArg_t args[10];
PhDim_t win_dim = { 300, 300 };
PhArea_t meter_area = { { 10, 20 }, { 280, 280 } };
PhArea_t sev_area = { { 125, 200 }, { 50, 20 } };
PhArea_t pos_area = { { 125, 230 }, { 50, 20} };
PhArea_t quit_area = { { 230, 270 }, { 60, 20 } };
PtCallback_t callbacks[2] = { {meter_cb, NULL},
{quit_cb, NULL} };
int n = 0;
char Helvetica_12[MAX_FONT_TAG];
PtSetArg( &args[n++], Pt_ARG_WINDOW_TITLE,

"PtMeter Demo", 0 );
PtSetArg( &args[n++], Pt_ARG_DIM, &win_dim, 0 );

n, args)) == NULL)
/* Draw the meter with 3 arcs and a callback for when

the meter is moved. */
n = 0;
PtSetArg( &args[n++], Pt_ARG_AREA, &meter_area, 0 );
PtSetArg( &args[n++], Pt_ARG_METER_MAX_NEEDLE_POSITION,
1000, 0 );
/* Generate the name of the font to use for the meter. */

if(PfGenerateFontName("Helvetica", 0, 12,
Helvetica_12) == NULL) {
} else {

PtSetArg( &args[n++], Pt_ARG_METER_TEXT_FONT,

Helvetica_12, 0 );
}
PtSetArg( &args[n++], Pt_CB_METER_MOVED, &callbacks[0], 0 );
/* If you don’t want your meter to be selectable, add

* the following:
*
* PtSetArg( &args[n++], Pt_ARG_METER_FLAGS,
* PtM_NON_SELECTABLE, PtM_NON_SELECTABLE );
*/
meter = PtCreateWidget( PtMeter, window, n, args );
/* Draw a label to show the severity changes.

The first label is the label to be changed,
and the second is the name of the parameter. */
n = 0;
PtSetArg( &args[n++], Pt_ARG_AREA, &sev_area, 0 );
PtSetArg( &args[n++], Pt_ARG_FLAGS,
Pt_HIGHLIGHTED | Pt_ETCH_HIGHLIGHT, \
Pt_HIGHLIGHTED | Pt_ETCH_HIGHLIGHT);
PtSetArg( &args[n++], Pt_ARG_BEVEL_WIDTH, 1, 0);
PtSetArg( &args[n++], Pt_ARG_TEXT_STRING, "1", 0);
sev_lbl = PtCreateWidget( PtLabel, window, n, args );
n = 0;
sev_area.pos.x -= 60;
PtSetArg( &args[n++], Pt_ARG_AREA, &sev_area, 0 );
PtSetArg( &args[n++], Pt_ARG_TEXT_STRING, "Severity:", 0);
PtCreateWidget( PtLabel, window, n, args );
/* Draw a label to show the position changes.

The first label is the label to be changed,
and the second is the name of the parameter. */
n = 0;
PtSetArg( &args[n++], Pt_ARG_AREA, &pos_area, 0 );
PtSetArg( &args[n++], Pt_ARG_FLAGS,
Pt_HIGHLIGHTED | Pt_ETCH_HIGHLIGHT, \
Pt_HIGHLIGHTED | Pt_ETCH_HIGHLIGHT);
PtSetArg( &args[n++], Pt_ARG_BEVEL_WIDTH, 1, 0);
PtSetArg( &args[n++], Pt_ARG_TEXT_STRING, "0", 0);
pos_lbl = PtCreateWidget( PtLabel, window, n, args );
n = 0;
pos_area.pos.x -= 60;
PtSetArg( &args[n++], Pt_ARG_AREA, &pos_area, 0 );
PtSetArg( &args[n++], Pt_ARG_TEXT_STRING, "Position:", 0);
PtCreateWidget( PtLabel, window, n, args );
/* Draw a quit button. */

n = 0;
PtSetArg( &args[n++], Pt_ARG_AREA, &quit_area, 0 );
PtSetArg( &args[n++], Pt_ARG_TEXT_STRING, "Quit", 0);
PtSetArg( &args[n++], Pt_CB_ACTIVATE, &callbacks[1], 0);
quit = PtCreateWidget( PtButton, window, n, args );
PtMainLoop();

New resources:

Pt_ARG_METER_COLOR PgColor_t Scalar Pg_BLACK
Pt_ARG_METER_FLAGS signed long Flag PtM_SELECTABLE
Pt_ARG_METER_FONT_COLOR PgColor_t Scalar Pg_BLACK
Pt_ARG_METER_INCREMENT signed short Scalar 5
Pt_ARG_METER_KEY_LEFT int Scalar Pk_Left
Pt_ARG_METER_KEY_RIGHT int Scalar Pk_Right
Pt_ARG_METER_LEVEL1_COLOR PgColor_t Scalar Pg_GREEN
Pt_ARG_METER_LEVEL1_POS short Scalar 50
Pt_ARG_METER_LEVEL2_COLOR PgColor_t Scalar Pg_YELLOW
Pt_ARG_METER_LEVEL2_POS short Scalar 75
Pt_ARG_METER_LEVEL3_COLOR PgColor_t Scalar Pg_RED
Pt_ARG_METER_MAX_NEEDLE_POSITION short Scalar 100
Pt_ARG_METER_MIN_NEEDLE_POSITION short Scalar 0
Pt_ARG_METER_NEEDLE_COLOR PgColor_t Scalar Pg_WHITE
Pt_ARG_METER_NEEDLE_POSITION short Scalar 0
Pt_ARG_METER_NUM_SEVERITY_LEVELS short Scalar 3
Pt_ARG_METER_TEXT_FONT char * String "TextFont09"
Pt_CB_METER_MOVED PtCallback_t * Link NULL
Pt_ARG_METER_COLOR
The color for the center circle, outline of the meter, and divisional ticks. See

Pt_ARG_METER_FLAGS

signed long Flag PtM_SELECTABLE
The valid bits are:
PtM_NO_TEXT Don’t display the minimum and maximum text strings.
PtM_NON_SELECTABLE
Make the meter noninteractive.
PtM_SELECTABLE
Make the meter interactive.
Pt_ARG_METER_FONT_COLOR
The font color for the minimum and maximum strings. See PgColor_t in the Photon
Library Reference.
Pt_ARG_METER_INCREMENT
signed short Scalar 5
The increment used when the keyboard is used to move the meter’s needle. Every
press of the assigned keys moves the meter this distance.
Pt_ARG_METER_KEY_LEFT
int Scalar Pk_Left
The key, as defined in <photon/PkKeyDef.h>, that you can use to move the meter’s
needle to the left. The default value is the left arrow, Pk_Left.
For this key to be useful, you must set Pt_GETS_FOCUS in the meter’s
Pt_ARG_FLAGS.

Pt_ARG_METER_KEY_RIGHT

int Scalar Pk_Right
The key, as defined in <photon/PkKeyDef.h>, that you can use to move the meter’s
needle to the right. The default value is the right arrow, Pk_Right.
For this key to be useful, you must set Pt_GETS_FOCUS in the meter’s
Pt_ARG_FLAGS.
Pt_ARG_METER_LEVEL1_COLOR
PgColor_t Scalar Pg_GREEN
The color of the first severity arc. See PgColor_t in the Photon Library Reference.
Pt_ARG_METER_LEVEL1_POS
short Scalar 50
The position of the end of the first severity arc, expressed as a percentage of the whole.
If the minimum and/or maximum value(s) change, the location of the arc is updated to
remain at this percentage.
PgColor_t Scalar Pg_YELLOW
The color of the second severity arc. See PgColor_t in the Photon Library Reference.
Pt_ARG_METER_LEVEL2_POS
short Scalar 75
The position of the end of the second severity arc, expressed as a percentage of the
whole. If the minimum and/or maximum value(s) change, the location of the arc is
updated to remain at this percentage.


The color of the third severity arc. See PgColor_t in the Photon Library Reference.
Pt_ARG_METER_MAX_NEEDLE_POSITION
short Scalar 100
The maximum needle position; also the value drawn as the maximum.
Pt_ARG_METER_MIN_NEEDLE_POSITION
short Scalar 0
The minimum needle position; also the value drawn as the minimum.
Pt_ARG_METER_NEEDLE_COLOR
The color of the meter’s needle. See PgColor_t in the Photon Library Reference.
Pt_ARG_METER_NEEDLE_POSITION
short Scalar 0
The current needle position, somewhere between the minimum and maximum needle
position. If the position is above the maximum, the maximum is used; if the position is
below the minimum, the minimum is used.
Pt_ARG_METER_NUM_SEVERITY_LEVELS
short Scalar 3

The number of severity arcs (levels) that the meter displays. This must be 1, 2, or 3. If
this resource is set higher than 3, only 3 arcs are displayed.
Pt_ARG_METER_TEXT_FONT
The font for the minimum and maximum strings.
Pt_CB_METER_MOVED
A list of PtCallback_t structures that define the callbacks invoked when the needle
is moved. Each callback is passed a PtCallbackInfo_t structure that contains at
reason Pt_CB_METER_MOVED
reason_subtype Why the callback was invoked:

• Pt_ARG_MOVED—the needle moved because
Pt_ARG_METER_NEEDLE_POSITION was set; event is
NULL
• Pt_KEY_MOVED—the needle moved due to a key event;
event is a Ph_EV_KEY event
• Pt_MOUSE_MOVED—the needle moved due to a mouse
event; event is a Ph_EV_PTR_MOTION_BUTTON or
Ph_EV_BUT_PRESS event
For more information, see PhEvent_t in the Photon Library
Reference.
caused the callback to be invoked. If event is NULL, then the
callback was invoked because the
Pt_ARG_METER_NEEDLE_POSITION resource was set.
cbdata A pointer to a PtMeterCallback_t structure that contains at
least:
int position The current position of the needle between the

minimum and maximum positions.
int severity The severity arc number that the needle current
lies in, between 1 and the number of arcs.


Pt_ARG_COLOR PtBasic Not used by this class.
Pt_ARG_DIM PtWidget
Pt_ARG_FILL_PATTERN PtBasic Not used by this class.
Pt_ARG_FLAGS PtWidget Pt_GETS_FOCUS
continued. . .


Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
continued. . .


Pt_CB_RAW PtWidget

PtMTrend © 2010, QNX Software Systems GmbH & Co. KG.
A medical trend widget
Class hierarchy:
PtWidget → PtBasic → PtMTrend
PhAB icon:
Public header:
<photon/PtMTrend.h>
Description:
A PtMTrend widget displays trend graphs intended for medical applications. The data
is displayed as a set of connected points that shift in a specified direction and at the
rate at which data is fed in, or at a rate specified by the application.
PtMTrend is similar to PtTrend, but with some added capabilities:
• A trace mode that displays a trace line, indicating where new data is being drawn.
• Each graph has its own minimum and maximum values.
• Customizable line thickness and join type for each graph.
• You can provide your own customized functions for drawing graphs, the grid, and
the trace line.
A PtMTrend widget.

© 2010, QNX Software Systems GmbH & Co. KG. PtMTrend
Example
This simple example illustrates how you can display data in a PtMTrend widget (in
this case, random data generated by a timer callback):
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <Pt.h>
/****************************************************************** STATICS ***/

static PtWidget_t *feed_toggle_wgt, *mtrend_wgt;
/*************************************************************** TIMER_CB() ***/

// This is the function which is changing (feeding) the trend widget data.
int
timer_cb( PtWidget_t *widget, void *data, PtCallbackInfo_t *cbinfo )
{
if( Pt_SET & PtWidgetFlags( feed_toggle_wgt ) ) {
int val1 = rand() % 100,
val2 = rand() % 200;
PtMTrendAddData( mtrend_wgt, 0, &val1, 1 );
PtMTrendAddData( mtrend_wgt, 1, &val2, 1 );
}
return Pt_CONTINUE;
}
/******************************************************************* MAIN() ***/

int
main( int argc, char *argv[] )
{
PtWidget_t *window, *wgt;
PtArg_t args[20];
int i;
// application window
i = 0;
PtSetArg( &args[i++], Pt_ARG_WINDOW_TITLE, "MTrend Sample Application", 0 );
PtSetArg( &args[i++], Pt_ARG_HEIGHT, 200, 0 );
PtSetArg( &args[i++], Pt_ARG_WIDTH, 400, 0 );
if( NULL == ( window = PtAppInit( NULL, &argc, argv, i, args ) ) ) {

perror( "PtAppInit()" );
return 1;
}
// feed toggle
i = 0;
PtSetArg( &args[i++], Pt_ARG_TEXT_STRING, "Feed data", 0 );
feed_toggle_wgt = PtCreateWidget( PtToggleButton, NULL, i, args );
// mtrend
{
PhArea_t area = { {20, 30}, {360,140} };
PtMTrendAttr_t graph1_attr[] = { Pt_MTREND_STATE_SHOWN, Pg_RED, 1,
Pg_MITER_JOIN, 0, 100 };
PtMTrendAttr_t graph2_attr[] = { Pt_MTREND_STATE_SHOWN, Pg_BLUE, 1,
Pg_MITER_JOIN, 0, 200 };
i = 0;
PtSetArg( &args[i++], Pt_ARG_MTREND_N_GRAPHS, 2, 0 );
PtSetArg( &args[i++], Pt_ARG_MTREND_N_SAMPLES, 100, 0 );

PtSetArg( &args[i++], Pt_ARG_MTREND_FLAGS, Pt_TRUE, Pt_MTREND_BLIT );

PtSetArg( &args[i++], Pt_ARG_MTREND_GRAPH_ATTR, &graph1_attr, 0 );
PtSetArg( &args[i++], Pt_ARG_MTREND_GRAPH_ATTR, &graph2_attr, 1 );
PtSetArg( &args[i++], Pt_ARG_AREA, &area, 0 );
mtrend_wgt = PtCreateWidget( PtMTrend, NULL, i, args );

}
// timer
{
PtCallback_t callback = { timer_cb, NULL };
i = 0;
PtSetArg( &args[i++], Pt_ARG_TIMER_INITIAL, 100, 0 );
PtSetArg( &args[i++], Pt_ARG_TIMER_REPEAT, 100, 0 );
PtSetArg( &args[i++], Pt_CB_TIMER_ACTIVATE, &callback, 0 );
PtCreateWidget( PtTimer, NULL, i, args );

}
PtMainLoop();
return 0;
}
To run this example, save it as a file named mtrend_sample.c, and compile it with
cc -o mtrend_sample -lph mtrend_sample.c. You can then run the
application ./mtrend_sample.
New resources:

Pt_ARG_MTREND_FLAGS int Flag Pt_MTREND_ALWAYS_SCROLL
Pt_ARG_MTREND_N_SAMPLES unsigned Scalar 0

Pt_ARG_MTREND_N_GRAPHS unsigned Scalar 0
Pt_ARG_MTREND_GRAPH_ATTR PtMTrendAttr_t Struct N/A
Pt_ARG_MTREND_GRAPH_STATE int Scalar N/A
Pt_ARG_MTREND_GRAPH_DATA PtMTrendData_t Struct N/A
Pt_ARG_MTREND_TRACE_WIDTH int Scalar 5
Pt_ARG_MTREND_TRACE_COLOR PgColor_t Scalar 0xC0C0C0
Pt_ARG_MTREND_TRACE_DRAW_F See below pointer N/A

Pt_ARG_MTREND_GRID_X unsigned Scalar 5
continued. . .


Pt_ARG_MTREND_GRID_Y unsigned Scalar 5
Pt_ARG_MTREND_GRID_COLOR PgColor_t Scalar 0xC0C0C0
Pt_ARG_MTREND_GRID_DRAW_F See below pointer N/A

Pt_ARG_MTREND_ADVANCE_BY_N_SAMPLES unsigned Scalar 1
Pt_ARG_MTREND_FLAGS
int Flag 0
Flags that control the way the widget draws data.

Direction flags; one of:
Pt_MTREND_HORZ_L2R
Draw the trend left to right.
Pt_MTREND_HORZ_R2L
Draw the trend right to left.
Pt_MTREND_VERT_T2B
Draw the trend top to bottom.
Pt_MTREND_VERT_B2T
Draw the trend bottom to top.
When setting the direction flag, use Pt_MTREND_DIRECTION_MASK as the len

argument for the PtSetArg() or PtSetResource() function.
Grid flags; one of:
Pt_MTREND_GRID_NONE
Do not show a grid.
Pt_MTREND_GRID_ABOVE
Draw the grid over the graphs.
Pt_MTREND_GRID_BELOW
Draw the grid under the graphs.
To set the grid, use Pt_MTREND_GRID_MASK as the len argument for the PtSetArg()
or PtSetResource() function.
Graphs drawing mode; one of:

Pt_MTREND_TRACE
Draw a trace line indicating where new graph data is being drawn on the trend.
Pt_MTREND_BLIT
Use blit mode — blit the data to reduce CPU use. Blit mode is available only if
Pt_MTREND_TRACE isn’t set and no grid is shown.
Pt_MTREND_ALWAYS_SCROLL
When data is first drawn on an empty graph, start drawing from the side of the
graph that represents the newest data. The side that represents new data is
dependent on the direction flag. For example, if the direction is
Pt_MTREND_HORZ_L2R, new data is drawn on the right hand side of the graph,
and older data is scrolled to the left.
If this flag is not set, when data is first drawn in the graph, it is drawn on the side
that represents old data. Once the graph fills with data, it begins to scroll in the
direction indicated by the direction flag.
Pt_ARG_MTREND_N_SAMPLES
unsigned Scalar 0
The maximum number of samples shown in the trend. If you reduce this number when
there is sample data in the trend, the oldest samples are trimmed.
Pt_ARG_MTREND_N_GRAPHS
unsigned Scalar 0
The number of graphs drawn in the trend. Note that graphs are numbered starting at 0,
but this resource indicates the actual number of graphs.
If you add new graphs to a trend widget, they appear with minimum values until you
set the graph data. If you reduce the number of graphs, existing graphs are removed
from the trend. For example, if you have 5 graphs numbered 0 to 4 in your trend, and
you change Pt_ARG_MTREND_N_GRAPHS from 5 to 3, graphs 3 and 4 are
removed from the trend.
Pt_ARG_MTREND_GRAPH_ATTR
PtMTrendAttr_t Struct N/A
Set attributes of a graph. PtMTrendAttr_t contains the following members, which

your application must fill in:

int state The trend state; one of Pt_MTREND_STATE_SHOWN (visible)

or Pt_MTREND_STATE_HIDDEN (not visible).
PgColor_t color The line color.
int line_thickness The line thickness, in pixels.
int join_type The line join type; see PgSetStrokeJoin() in the Photon Library
Reference for more information about join types.
int min and max The minimum and maximum values for sample data.
void *draw_f A pointer to a customized draw function for the graph. You
can set the pointer to your own function (see below).
To set your graph draw function, draw_f should be a pointer of type:
void (*draw_f)( PtWidget_t *widget,

PhTile_t *damage,
struct pt_mtrend_graph_info *attr );
The widget argument is a pointer to the trend widget of type PtMTrend. The damage
argument is the damage list for the widget. The attr argument is type
pt_mtrend_graph_info, which has at least the following attributes:
PtMTrendAttr_t attr
A structure containing the attribute information for the graph.
int n_samples The total number of samples in the data buffer.
int *data A pointer to an array of data for the graph, with the oldest data at
position 0.
When setting this resource with PtSetArg() or PtSetResource(), pass the graph number
as the len argument.
Pt_ARG_MTREND_GRAPH_STATE
int Scalar N/A
Enables or disables graph drawing. Values:
Pt_MTREND_STATE_SHOWN
Draw the graph.
Pt_MTREND_STATE_HIDDEN
Don’t draw the graph.

When setting this resource with PtSetArg() or PtSetResource(), pass the graph number
as the len argument.
Pt_ARG_MTREND_GRAPH_DATA
PtMTrendData_t Struct N/A
Use to add or change data for a specified graph. When setting this resource with
PtSetArg() or PtSetResource(), pass the graph number as the len argument. The
PtMTrendData_t contains at least these members:
int mode Can be one of Pt_MTREND_ADD or Pt_MTREND_PUT
unsigned n_samples
The number of data samples in the data array.
unsigned last_sample
The sample number where to put new data into the buffer, if mode is
Pt_MTREND_PUT.
const int *data

The data samples array.
For convenience, the library provides PtMTrendAddData() and

PtMTrendChangeData() for working with data in the graphs.
Pt_ARG_MTREND_TRACE_WIDTH
int Scalar 5
The width of the trace strip. If positive, this is the number of pixels. If negative, the
width is calculated as the absolute value of this resource multiplied by the width of
one data sample.
Pt_ARG_MTREND_TRACE_COLOR
PgColor_t Scalar 0xC0C0C0
The trace strip color.

Pt_ARG_MTREND_TRACE_DRAW_F

See below Pointer N/A
By default, a pointer to the default trace drawing function. You can provide your own
drawing function for the trace line by setting this resource to a pointer with the
following type:
void (*draw_f)( PtWidget_t *widget, PhTile_t *damage );
The arguments are:
widget A pointer to a PtMTrendWidget_t structure. The function should use

the trace.pos and trace.dim members of this structure for drawing.
damage The damage list for the draw function.
Pt_ARG_MTREND_GRID_X
unsigned Scalar 5
The number of vertical grid lines, if the grid is turned on.
Pt_ARG_MTREND_GRID_Y
unsigned Scalar 5
The number of horizontal grid lines, if the grid is turned on.
Pt_ARG_MTREND_GRID_COLOR
PgColor_t Scalar 0xC0C0C0
The grid line color, if the grid is turned on.
Pt_ARG_MTREND_GRID_DRAW_F

A pointer to the default grid drawing function. You can provide your own customized
grid drawing function by setting this resource to a pointer to a function of the
following type:
void (*draw_f)( PtWidget_t *widget, PhTile_t *damage );
The arguments are:
widget A pointer to a PtMTrendWidget_t structure. The function should use

the grid.* members for drawing.
damage The damage list for the widget.
Pt_ARG_MTREND_ADVANCE_BY_N_SAMPLES
unsigned Scalar 1
This resource specifies the number of data samples to be shifted when the limit (the
edge of the trend widget) is reached. If set to 1 (default), the trend appears to be
continuously scrolling. That is, for each draw cycle, the trend is scrolled by one
sample, then the new sample is drawn.
If you set this resource to a larger value, the trend scroll behavior is different. For
example, if you set the value to 10, each time the trend reaches the end of the widget,
the trend is scrolled back by ten samples. Ten more samples are drawn before the
trend is scrolled again.
You can set this resource to a value larger than 1 only for trends that aren’t in trace
mode.

continued. . .


Pt_ARG_DIM PtWidget
continued. . .


Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
The PtMTrend defines the following convenience functions that make it easier to use
the widget once it’s been created:
PtMTrendAddData()
Add data to a trend.
PtMTrendChangeData()
Change existing data in a trend.

© 2010, QNX Software Systems GmbH & Co. KG. PtMTrendAddData(),
PtMTrendChangeData()
Add or change data for a PtMTrend widget
Synopsis:
void PtMTrendAddData( PtWidget_t *widget,

unsigned graph_no,
const int *newdata,
unsigned nsamples );
void PtMTrendChangeData( PtWidget_t *widget,

unsigned graph_no,
int const *newdata,
unsigned last_sample,
unsigned nsamples );
Arguments:
widget A pointer to a widget of type PtMTrend.
graph_no The number of the graph to be added to or changed, in the range 0 to

trend count - 1, inclusive.
newdata A pointer to an array of the new data (see below).
nsamples The number of samples in the array.
last_sample (PtMTrendChangeData() only)

The index of the newest sample to replace, where 0 is considered to be
the index of the most recently added sample.
Description:
PtMTrendAddData() lets you add data for a PtMtrend, while
PtMTrendChangeData() lets you change existing data.
The newdata array is ordered with the oldest sample at newdata[0], and the newest at
newdata[nsamples - 1]. The oldest sample to be replaced has an index of last_sample
+ nsamples - 1;
The samples in the trend are replaced as follows:
• trend sample[last_sample] = newdata[nsamples - 1].
• trend sample[last_sample + 1] = newdata[nsamples - 2].
• ...
• trend sample[last_sample + nsamples - 1] = newdata[0].
If last_sample + nsamples - 1 is outside the range of samples for the widget, some
initial portion of the new data is discarded.

PtMTrendAddData(), PtMTrendChangeData() © 2010, QNX Software Systems GmbH & Co.
KG.
Classification:
Photon
Safety
Signal handler No
Thread No

© 2010, QNX Software Systems GmbH & Co. KG. PtMultiText
Multiline stylized text
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtCompound → PtMultiText
PhAB icon:
Public header:
<photon/PtMultiText.h>
Description:
The PtMultiText widget class lets you display and edit multilined stylized text.
A PtMultiText widget.
Lines can be automatically wrapped on character or word boundaries. Optional

scrollbars are provided to make it easy to view wide or long documents. Multiple
colors and fonts are supported on any line.
The text buffer of the PtMultiText widget is a zero-terminated string consisting of
multibyte (UTF-8) characters. You can set attributes (such as font, color, or style) for
any segment of text, but this information isn’t embedded in the text buffer.
Features
The MultiText widget provides many features that make it ideal for multilined data
entry fields or as the basis for an editor:
• optional line- and word- or character-wrapping
• support for multiple text fonts and colors
• support for “tagging” segments of text
• optional automatic scrollbars, both horizontal and vertical
• range selection
• cut, copy, and paste
• multiple tab stops
• tab expansion

PtMultiText © 2010, QNX Software Systems GmbH & Co. KG.
• optional automatic indentation
• anchoring
• many useful callbacks
• cursor visibility, editable or read-only options
• overstrike and insert editing modes
You can control all these features via the widget’s resources and convenience
functions. For example, to force the widget to wrap long lines at word boundaries, set
the Pt_EMT_WORD bit of the Pt_ARG_MULTITEXT_WRAP_FLAGS resource:
PtSetArg( &argt, Pt_ARG_MULTITEXT_WRAP_FLAGS, Pt_EMT_WORD,

Pt_EMT_WORD );
PtSetResources( mtwidget, 1, &argt );
If you set both the word- and character-wrap flags, word wrapping is applied.
You can also control the amount of space left between lines of text using
Pt_ARG_LINE_SPACING. The value of this resource is the number of pixels to leave
between the descenders of one line of text and the ascenders of the next.
To display a horizontal scrollbar:
• 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.
Setting text
You can set the contents of the text buffer using the Pt_ARG_TEXT_STRING,
Pt_ARG_TEXT_SUBSTRING, or Pt_ARG_MULTITEXT_SEGMENTS resources, or
the PtTextModifyText() or PtMultiTextModifyText() convenience functions. The
PtMultiText widget automatically wraps the text according to the wrap flags, and
displays scrollbars if the Pt_ARG_SCROLLBAR_X_DISPLAY and/or
Pt_ARG_SCROLLBAR_Y_DISPLAY resources allow for them.
If you set the text using the Pt_ARG_TEXT_STRING resource, the new text replaces
the entire text buffer of the widget, and all the lines of text are drawn using the same
attributes. The font is the one specified by the Pt_ARG_TEXT_FONT resource
inherited from PtLabel. The text foreground and background colors are taken from
the values of the Pt_ARG_COLOR and Pt_ARG_FILL_COLOR resources.
If you set the text using Pt_ARG_TEXT_SUBSTRING, only the specified portion of
the text buffer is affected. Text can be deleted and/or inserted. The text inserted is
drawn with the same attributes as the text at the insertion point.

Text attributes
You can control the following attributes of a range of text:
• font
• text color
• background color
• tag ( void * for your own use )
There are several methods for setting the attributes that affect a given range of text:
• Delete and/or insert ranges of text with attributes via the PtMultiTextModifyText()
convenience function. Specify the attributes in the PtMultiTextAttributes_t
structure that you pass to this function.
• Change the attributes of a range of text that’s already there by filling in a

PtMultiTextAttributes_t structure and using it to set the
Pt_ARG_MULTITEXT_RANGE_ATTRIBUTES resource or, by calling the
PtTextModifyText() convenience function.
• Define the ranges of text in advance (along with the associated set of attributes) and
place them in the text buffer by setting the Pt_ARG_MULTITEXT_SEGMENTS
resource. This is an easy way to initialize the PtMultiText widget with a catchy
message.
When setting the text and attributes via the Pt_ARG_MULTITEXT_SEGMENTS
resource, you provide the resource with an array of PtMultiLines_t structures.
Each element of the array has a text string and an associated set of attributes that
are used when displaying the text.
Setting text using ranges

The following example shows how to create a multiline text widget with two ranges of
text with different attributes:
#include <stdio.h>
#include <stdlib.h>
#include <Pt.h>
#include <Ph.h>
char Verdana24[MAX_FONT_TAG];
PtMultiLines_t hello[] = {
{ "Hello\n", Pt_DEFAULT_FONT, Pt_DEFAULT_COLOR,
Pt_INHERIT_COLOR },
{ "World!", Pt_DEFAULT_FONT, Pg_BLUE, Pt_INHERIT_COLOR }
};
main() {
PtWidget_t *window;
PtArg_t args[2];
int nargs = 0;
PhDim_t dim = { 300, 150 };


0, NULL)) == NULL)
PtExit( EXIT_FAILURE );
if(PfGenerateFontName("Verdana", 0, 24,
Verdana24) == NULL) {
} else {
hello[1].font = Verdana24;
}
PtSetArg( &args[nargs++], Pt_ARG_DIM, &dim, 0 );
PtSetArg( &args[nargs++], Pt_ARG_MULTITEXT_SEGMENTS,
&hello, sizeof( hello )/sizeof(hello[0]) );
PtCreateWidget( PtMultiText, Pt_DEFAULT_PARENT,
nargs, args );
PtMainLoop();
}
Inserting text with assigned attributes

You can insert a new range of text into the text buffer and specify its attributes using
the PtMultiTextModifyText() function. To delete and/or insert text such that it takes on
the attributes in effect at the insertion point, use PtTextModifyText().
The following shows how our “Hello, world” example could be rewritten to insert text
into the widget:
#include <stdio.h>
#include <stdlib.h>
#include <Pt.h>
#include <Ph.h>
main()
{
PtWidget_t *window, *mtext;
PtArg_t args[2];
int nargs = 0;
PhDim_t dim = { 300, 150 };
PtMultiTextAttributes_t attr;
char Verdana24[MAX_FONT_TAG];

0, NULL)) == NULL)
PtExit( EXIT_FAILURE );
if(PfGenerateFontName("Verdana", 0, 24,
Verdana24) == NULL) {
attr.font = Pt_DEFAULT_FONT;
} else {

attr.font = Verdana24;
}
PtSetArg( &args[nargs++], Pt_ARG_DIM, &dim, 0 );

mtext = PtCreateWidget( PtMultiText, Pt_DEFAULT_PARENT,
nargs, args );
PtTextModifyText( mtext, NULL, NULL, 0, "Hello, \n", 8 );
PtMultiTextModifyText( mtext, NULL, NULL, -1,
"World! \n", 8, attr, Pt_MT_FONT );
PtMainLoop();
}
Changing the attributes of a range of text

With a WYSIWYG editor, you can select a range of text in the text widget and change
the text attributes of that range. This requires the ability to modify the attributes of a
range programmatically. Modifying the attributes of a range is also useful for marking
blocks of text, as may be done to indicate the results of a search. You can modify the
attributes of a range of text by using the PtMultiTextModifyAttributes() function or by
setting the Pt_ARG_MULTITEXT_RANGE_ATTRIBUTES resource.
The following example shows how to change the font of the text selection to 14-point
Helvetica, by using PtMultiTextModifyAttributes():
int start, end;
if( PtTextGetSelection( text, &start, &end ) )

{
} else {
attr.font = Helvetica_14;
PtMultiTextModifyAttributes( text, &start, &end,
&attr, Pt_MT_FONT );
}
}
This code segment first determines the start and end of the text selection by calling
PtTextGetSelection(). This gives the start and end positions to use in a subsequent call
to PtMultiTextModifyAttributes().
The following example shows how to change the font of the text selection to 14-point
Helvetica, by setting the Pt_ARG_MULTITEXT_RANGE_ATTRIBUTES resource:
PtMultiTextControl_t mtc;
if( PtTextGetSelection( text, &mtc.tc.start, &mtc.tc.end ) )

{


} else {
PtArg_t argt;
attr.font = Helvetica_14;
mtc.attributes = &attr;
PtSetArg( &argt, Pt_ARG_MULTITEXT_RANGE_ATTRIBUTES,
&mtc, Pt_MT_FONT );
PtSetResources( text, 1, &argt );
}
}
The members of the PtMultiTextControl_t structure (also known as

PtMultiTextCallback_t) used in the example are:
PtTextCallback_t tc
Text control structure used to control the modification of text. This is always
present in the modification callbacks of PtText or PtMultiText widgets. The
members of PtTextCallback_t (also known as PtTextControl_t) are:
int start_pos
int end_pos The characters from start_pos up to but not including
end_pos will be deleted.
int cur_insert The position to insert characters if no deletion has occurred;
otherwise, the new characters will be inserted at start_pos.
int new_insert Useful only in modify callbacks, this member indicates the
position the cursor will be in after the modification has
occurred.
int length The number of multibyte (UTF-8) characters to insert.
char *text The multibyte string to insert.
int doit Must be set to nonzero before changes to the content of the
body of text will be permitted.
PtMultiTextAttributes_t *attributes
This structure describes a set of attributes. See PtMultiTextAttributes_t.
PtMultiTextSegment_t *seg
Valid only in callbacks from the PtMultiText widget. It points to the segment
of text that’s involved in the modification that caused the callback. See
PtMultiTextSegment_t.
If you implement editing functions that allow operations that alter the attributes of
fonts in text ranges, you should always obtain the current attributes in effect at the start
of each range and make changes based on those.

Hyperlinks using cursor-motion callbacks

Since the cursor-motion callback notifies your application whenever the cursor is
moved, the callback can also notify the application when the user presses the pointer
button over a “hot-spot” used for a hypertext link.
You can store the data for a hypertext link itself on the pointer maintained in the tag
for the text segment. The cursor-motion callback can then simply:
1 Check the tag’s contents to determine if the cursor has been positioned on a
hypertext link.
2 Check the event to see if the appropriate event type caused the callback to be
invoked (i.e. a pointer-button press).
3 Take the action associated with the hypertext link.
You can refine this technique further by changing the callback so that it registers only
an event handler that invokes the action associated with the hypertext link, then
deregisters itself. This lets you define more complex behavior (e.g. proper “activate”
behavior for the link). In this case, the link is followed only if the user releases the
pointer button when the pointer is over the link.
When dealing with structured text such as hypertext, it’s a good idea to break the text
down into nodes. Define a data structure for these nodes, defining the type of node and
any data associated with the node. Create a range of text for each node, attaching a
pointer to the node as the Pt_MT_TAG attribute for the range, and add the range to the
widget. The text’s original structure can be obtained in callbacks by looking at the tag
in the attributes member of the callback data structure.
The following illustrates a simple node structure, allowing either plain text or a
hypertext link:
typedef enum text_node_enum { tnText, tnHyperlink }

TextNodeType_t;
typedef text_node_str {
TextNodeType_t type;
void *data;
} TextNode_t;
The following code illustrates how a hypertext link can be activated within a multiline
text widget:
struct line_str {
TextNode_t node;
char *text;
} lines[] = {
{ {tnText, NULL}, "Click " },
{ {tnHyper, (void *)"file.html#id"}, "here" },
{ {tnText, NULL}, " to follow a hypertext link"}
};
int
follow_link(PtWidget_t *widget, void *client_data,
{

PtMultiTextCallback_t *cbs =
(PtTextCallback_t *)info->cbdata;
if (info->reason == Pt_CB_MOTION_VERIFY &&

info->event != NULL &&
(info->event->type & Ph_EV_BUT_PRESS))
{
TextNode_t *node =
(TextNode_t *)cbs->attributes->tag;
printf("URL referenced: %s\n", node->data);
}
}
void
init_text(PtWidget_t *text)
{
PtMultiTextAttributes_t reg, hyper;
int nlines;
PtMultiTextCreateAttributes(&reg);
PtMultiTextCreateAttributes(&hyper);
hyper.text_color = Pg_DGREEN;
for (nlines = 0; nlines < sizeof(lines)/
sizeof(lines[0]); nlines++)
{
PtMultiTextAttributes_t *attr =
lines[nlines].node.type == tnHyper ? &hyper
: ®
PtMultiTextModifyText (text, 0, 0, -1,

lines[nlines].text,
&lines[nlines].node,
attr,
Pt_MT_TAG|Pt_MT_FOREGROUND);
}
PtAddCallback(text, Pt_CB_MOTION_VERIFY, follow_link,
NULL);
}
The data member of a hyperlink node is assumed to be a string indicating what action
to take. In this case, it refers to another document to load by a URL of the form used
by the Photon Helpviewer.
Widget dimensions
As for all widgets, Pt_ARG_DIM holds the dimensions of a PtMultiText widget.
For example, suppose you have a multitext widget that can show four lines of text. If
you type more than four lines, say six lines, the widget displays a scrollbar to let you
know there are more lines. Querying Pt_ARG_DIM gives the dimensions of the four
lines of text.
If you need to determine the dimensions of the entire text — the six lines in our
example — you’ll need to calculate it as described below:
Use the Pt_ARG_MULTITEXT_QUERY_LINE resource to query the first line (line 1).
This gives you information in the form of a PtMultiTextQuery_t structure, which
contains a pointer to a PtMultiTextLine_t structure. The PtMultiTextLine_t

structure contains a PhRect_t structure (see the Photon Library Reference) that
specifies the extent for that line. Calculate the dimensions of the line as:
height = extent.lr.y - extent.ul.y + 1;

width = extent.lr.x - extent.ul.x + 1;
The lines are organized as a linked list, using the next and previous pointers in the
PtMultiTextLine_t structure. Traverse all the lines until the next pointer is NULL,
calculating:
• the sum of the heights
• the maximum width
When you’ve examined all the lines, you’ll have the “virtual dimensions” of the text
input area (i.e. the area that the text would occupy if it had enough room to do so)
If you have only one font in the PtMultiText widget, the method of finding the
dimensions can be simplified. For example, to find the virtual height, calculate the
height of the first line and multiply it by the number of lines.
Drag and Drop

If you select some text and hold down the Ctrl key, you can drag the selected text to a
PtText, PtMultiText, PtTerminal, or PtTty widget.
New resources:

Pt_ARG_MULTITEXT_BOTTOM_LINE long Scalar None (write-only)
Pt_ARG_MULTITEXT_FLAGS long Flag See below
Pt_ARG_MULTITEXT_NUM_LINES long Scalar 1 (read-only)
Pt_ARG_MULTITEXT_NUM_LINES_VISIBLE short Scalar None (read-only)
Pt_ARG_MULTITEXT_QUERY_CHARACTER PtMultiTextQuery_t * Complex None (read-only)
Pt_ARG_MULTITEXT_QUERY_LINE PtMultiTextQuery_t * Complex None (read-only)
Pt_ARG_MULTITEXT_RANGE_ATTRIBUTES PtMultiTextControl_t * Complex None
Pt_ARG_MULTITEXT_ROWS long Scalar None (write-only — see
below)
Pt_ARG_MULTITEXT_SEGMENTS PtMultiLines_t, short Array None (write-only)
Pt_ARG_MULTITEXT_TABS int, int Array {20}
Pt_ARG_MULTITEXT_TOP_LINE long Scalar 1
continued. . .


Pt_ARG_MULTITEXT_WRAP_FLAGS short Flag See below
Pt_ARG_MULTITEXT_X_SCROLL_POS short Scalar 0
Pt_ARG_MULTITEXT_Y_SCROLL_POS long Scalar 1
Pt_ARG_SCROLLBAR_X_DISPLAY unsigned short Scalar Pt_NEVER
Pt_ARG_SCROLLBAR_X_HEIGHT unsigned short Scalar 0 (use scrollbar default of 15)
Pt_ARG_SCROLLBAR_Y_DISPLAY unsigned short Scalar Pt_NEVER
Pt_ARG_SCROLLBAR_Y_WIDTH unsigned short Scalar 0 (use scrollbar default of 15)
The convenience functions can make it easier for you to use the complex resources.
For more information, see “Convenience functions,” below.
Pt_ARG_MULTITEXT_BOTTOM_LINE (write-only)
long Scalar None
Set the bottom line (top line + number of visible lines -1).
Pt_ARG_MULTITEXT_FLAGS
long Flag Pt_EMT_SCROLL_TO_CURSOR
Flags that affect the appearance and behavior of the widget. The valid bits are:
Pt_EMT_AUTOINDENT
Automatically indent a new line (when you press Enter) to match the previous
line, by duplicating any leading whitespace characters.
Pt_EMT_FULL_LINES
Draw a line of text only if there’s enough room for its ascenders and descenders.
Pt_EMT_FORCED_SCROLL
Scroll down automatically if there’s a blank space at the bottom of the widget
and lines of text above the top of it.
Pt_EMT_SCROLL_TO_CURSOR
Enable cursor tracking.

Pt_ARG_MULTITEXT_NUM_LINES (read-only)

long Scalar 1
The line number of the last line in the buffer. The first line is line 1, not 0.
Pt_ARG_MULTITEXT_NUM_LINES_VISIBLE (read-only)
short Scalar None
The number of lines that are currently visible.
Pt_ARG_MULTITEXT_QUERY_CHARACTER (read-only)
PtMultiTextQuery_t * Complex None
Use this resource to get information about a certain character. This resource is a
complex one, so it needs special handling. When getting, set the arguments to
PtSetArg() as follows:
value A pointer to an instance of a PtMultiTextQuery_t structure.
len The index of the character you want to be query. The index of the first
character is 0.
Pt_ARG_MULTITEXT_QUERY_LINE (read-only)
PtMultiTextQuery_t * Complex None
Use this resource to get information about a certain line. This resource is a complex
one, so it needs special handling. When getting, set the arguments to PtSetArg() as
follows:
value A pointer to an instance of a PtMultiTextQuery_t structure.
len The index of the line to be queried. The index of the first line is 1.

Pt_ARG_MULTITEXT_RANGE_ATTRIBUTES

PtMultiTextControl_t * Complex None
This resource modifies/queries the attributes of a specified range. This resource is a

complex one, so it needs special handling.
When setting this resource, set the arguments to PtSetArg() as follows:
value A pointer to an instance of a PtMultiTextControl_t structure.
len A bitmask indicating which attributes to affect in the range. The valid bits
for this mask are:
• Pt_MT_FONT
• Pt_MT_FOREGROUND
• Pt_MT_TEXT_COLOR
• Pt_MT_BACKGROUND
• Pt_MT_BACKGROUND_COLOR
• Pt_MT_TAG
• Pt_MT_FLAGS
When getting the value of this resource, set the arguments to PtSetArg() as follows:
value The address of a pointer to a PtMultiTextInfo_t structure, which is the

same as PtMultiTextControl_t.
len A pointer to an instance of a PtTextCallback_t structure that defines the

range you want to query.
Pt_ARG_MULTITEXT_ROWS (write-only)
long Scalar None (see below)
Specifies the number of rows. Setting this resource sets the widget’s height dimension
based on the height of the current font and number of rows specified. There’s no
default value for this resource because the widget initially uses its dimension to
determine the number of rows.

This is a “one-shot” resource; it changes the size of the widget when you set it, based
on the widget’s current settings. If you later change the font, the value of
Pt_ARG_MULTITEXT_ROWS isn’t used to recalculate the height of the widget.
Pt_ARG_MULTITEXT_SEGMENTS (write-only)
PtMultiLines_t, short Array None
This resource provides an easy way for you to define a multisegment message. (A
segment is a set of contiguous characters that share common attributes, such as font,
color, and so on.)
All the text provided in the PtMultiLines_t array is concatenated and used to
replace the text in the Pt_ARG_TEXT_STRING resource. The rest of the information
in the array is used to build up an index of segments into the text. The array itself isn’t
preserved within the widget. Consequently, you should treat
Pt_ARG_MULTITEXT_SEGMENTS as a write-only resource. To retrieve the text, use
the Pt_ARG_TEXT_STRING resource.
Pt_ARG_MULTITEXT_TABS
int, int Array {20}
Provides a means of specifying tab stops to the multitext widget. The array provided is
an array of integers, each of which is a tab spacing, in pixels, relative to the last tab
position. The last tab spacing is repeated; for example, a tab array of {10,20,10}
produces tab stops at 10, 30, 40, 50, 60, ... pixels.
Pt_ARG_MULTITEXT_TOP_LINE
long Scalar 1
Set or get the top line or vertical scroll position, in lines (where the first line is line 1).
Pt_ARG_MULTITEXT_WRAP_FLAGS

This resource controls how the multitext widget wraps. The possible values are:
Pt_EMT_WORD Wrap on word breaks.
Pt_EMT_CHAR Wrap at the end of the line.
Pt_EMT_NEWLINE
Wrap on carriage returns.
If both the word and character wrap flags are on, word wrapping is applied.
Pt_ARG_MULTITEXT_X_SCROLL_POS
short Scalar 0
The horizontal scroll position (in pixels).
Pt_ARG_MULTITEXT_Y_SCROLL_POS
long Scalar 1
Set or get the top line or vertical scroll position in lines, where the first line is line 1.
This resource is the same as Pt_ARG_MULTITEXT_TOP_LINE.
Pt_ARG_SCROLLBAR_X_DISPLAY
unsigned short Scalar Pt_NEVER
This resource indicates when to display the horizontal scrollbar. The possible values
are:
• Pt_NEVER (default)
• Pt_AS_REQUIRED
• Pt_ALWAYS
In order to display a horizontal scrollbar, you need to clear Pt_EMT_WORD and

Pt_EMT_CHAR in the widget’s Pt_ARG_MULTITEXT_WRAP_FLAGS resource.

Pt_ARG_SCROLLBAR_X_HEIGHT

unsigned short Scalar 0 (use scrollbar default of 15)
The height of the horizontal scrollbar. If you set this resource to 0, widget uses the
default size of 15.
Pt_ARG_SCROLLBAR_Y_DISPLAY
unsigned short Scalar Pt_NEVER
This resource indicates when to display the vertical scrollbar. The possible values are:
• Pt_NEVER (default)
• Pt_AS_REQUIRED
• Pt_ALWAYS
Pt_ARG_SCROLLBAR_Y_WIDTH
unsigned short Scalar 0 (use scrollbar default of 15)
The width of the vertical scrollbar. If you set this resource to 0, widget uses the default
size of 15.

Pt_ARG_ANCHOR_FLAGS PtWidget 0 (no anchors)
continued. . .


Pt_ARG_COLUMNS PtText
Pt_ARG_CURSOR_POSITION PtText 0
Pt_ARG_CURSOR_TYPE PtWidget Ph_CURSOR_INSERT
Pt_ARG_DIM PtWidget
Pt_ARG_EFLAGS PtWidget &= ˜Pt_CONSUME_EVENTS
Pt_ARG_FLAGS PtWidget |=Pt_SET|
Pt_HIGHLIGHTED|
Pt_GETS_FOCUS
continued. . .


Pt_ARG_MAX_LENGTH PtText
Pt_ARG_POS PtWidget
Pt_ARG_SELECTION_RANGE PtText
Pt_ARG_TEXT_CURSOR_WIDTH PtText
Pt_ARG_TEXT_HIGHLIGHT_BACKGROUND_COLOR PtText
Pt_ARG_TEXT_HIGHLIGHT_TEXT_COLOR PtText
Pt_ARG_TEXT_SUBSTRING PtText
continued. . .


Pt_CB_ACTIVATE PtBasic See below
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_GOT_FOCUS PtBasic See below
Pt_CB_LOST_FOCUS PtBasic See below
Pt_CB_MENU PtBasic
Pt_CB_MODIFY_NOTIFY PtText See below
Pt_CB_MODIFY_VERIFY PtText See below
Pt_CB_MOTION_NOTIFY PtText See below
Pt_CB_MOTION_VERIFY PtText See below
Pt_CB_RAW PtWidget
Pt_CB_TEXT_CHANGED PtText See below

By default, this widget has the bit Pt_TEXT_BLINKING_CURSOR in

Pt_ARG_TEXT_FLAGS set to on.
Pt_CB_ACTIVATE
Pt_CB_ACTIVATE is inherited from PtBasic, but its behavior is different for a
PtMultiText widget. Each callback is passed a PtCallbackInfo_t structure that
reason_subtype Indicates why the callback was invoked:

• 0 — you clicked on the widget and it has Pt_SELECTABLE set
in its Pt_ARG_FLAGS.
• Pt_EDIT_ACTIVATE — you pressed Enter in the text field.
• Pt_CHANGE_ACTIVATE — you modified the text, gave focus
to another widget, and Pt_CHANGE_ACTIVATE is set in the
text widget’s Pt_ARG_TEXT_FLAGS (inherited from
PtText).

cbdata If reason_subtype is 0, the callback data is as described for the
Pt_CB_ACTIVATE resource for PtBasic.
If reason_subtype is Pt_EDIT_ACTIVATE or
Pt_CHANGE_ACTIVATE, cbdata points to a
PtMultiTextCallback_t structure that contains at least the
following members:
PtTextCallback_t tc;
PtMultiTextAttributes_t const *attributes;
PtMultiTextSegment_t *seg;
void *extended_data;
• The PtTextCallback_t tc structure has the following

members:
int start_pos;
int end_pos; All characters starting at start_pos up to
but not including end_pos are to be
deleted. If start_pos and end_pos are
equal, no characters are to be deleted.
int cur_insert; The position at which text will be inserted.
A value of 0 indicates that the text will be
inserted to the left of the first character, 1 to
the right of the first character, and so on.

int new_insert; Where the cursor will be after the changes

are applied.
int length; The number of characters to be inserted. If
length is zero, no text is being inserted, so
the text field is invalid.
char *text; The text to be inserted at cur_insert.
Before using text, check the length field to
make sure text contains valid data. In
addition, note that text might not be
zero-terminated.
int doit; Indicates whether or not this modification
will be applied to the widget. If doit is zero,
the widget discards the modification. If doit
is nonzero, the widget uses the contents of
the callback structure to modify itself.
For more information, see
PtTextModifyText() or
PtMultiTextModifyText().
• PtMultiTextSegment_t *seg is the text segment that
contains the character indicated by cur_insert. See
PtMultiTextSegment_t.
• PtMultiTextAttributes_t *attributes are the attributes
associated with seg. See PtMultiTextAttributes_t.
Pt_CB_GOT_FOCUS, Pt_CB_LOST_FOCUS
Pt_CB_GOT_FOCUS and Pt_CB_LOST_FOCUS are inherited from PtBasic, but
the cbdata member of the callback information is different for a PtMultiText
widget.
following members:
reason The name of the callback resource that caused this callback to be
invoked.

cbdata A pointer to a PtMultiTextCallback_t structure.
The members of the PtMultiTextCallback_t structure are used as follows:
• The PtTextCallback_t tc structure has the following members:

int cur_insert; The position of the cursor along the string. A value of 0
indicates that the cursor is to the left of the first character, 1 to
char *text; The beginning of the text string.
int length; The length of the text string (not including the NULL).
• PtMultiTextSegment_t *seg is the text segment that contains the character

indicated by cur_insert. See PtMultiTextSegment_t.
• PtMultiTextAttributes_t *attributes are the attributes associated with seg.

See PtMultiTextAttributes_t.
The Pt_CB_GOT_FOCUS callbacks should return Pt_CONTINUE.

The Pt_CB_LOST_FOCUS callbacks should return:

Or:
• Pt_END to keep it (for example, if you have to type something in the text widget).
Pt_CB_TEXT_CHANGED, Pt_CB_MODIFY_NOTIFY, Pt_CB_MOTION_NOTIFY

Pt_CB_TEXT_CHANGED (Pt_CB_MODIFY_NOTIFY), and
Pt_CB_MOTION_NOTIFY are inherited from PtText but the cbdata member of the
callback information is different for a PtMultiText widget.
following members:
invoked.

int cur_insert; The position of the cursor along the string. A value of 0
indicates that the cursor is to the left of the first character, 1 to
char *text; The beginning of the text string.
int length; The length of the text string (not including the NULL).


Pt_CB_MODIFY_VERIFY
Pt_CB_MODIFY_VERIFY is inherited from PtText, but the cbdata member of the
callback information is different for a PtMultiText widget.
following members:
invoked.

int start_pos;
int end_pos; All characters starting at start_pos up to but not including
end_pos are to be deleted. If start_pos and end_pos are
equal, no characters are to be deleted.
int cur_insert; The position at which text will be inserted. A value of 0
indicates that the text will be inserted to the left of the first
character, 1 to the right of the first character, and so on.
int new_insert; Where the cursor will be after the changes are applied.
int length; The number of characters to be inserted. If length is zero, no
text is being inserted, so the text field is invalid.
Before using text, check the length field to make sure text
contains valid data. In addition, note that text might not be
zero-terminated.
int doit; Indicates whether or not this modification will be applied to
the widget. If doit is zero, the widget discards the
modification. If doit is nonzero, the widget uses the contents
of the callback structure to modify itself.
For more information, see PtTextModifyText() or
PtMultiTextModifyText().


Pt_CB_MOTION_VERIFY
Pt_CB_MOTION_VERIFY (Pt_CB_MODIFY_NOTIFY), is inherited from PtText,
but the cbdata member of the callback information is different for a PtMultiText
widget.
following members:
invoked.

int cur_insert; The current position of the cursor. A value of 0 indicates that
the cursor is to the left of the first character, 1 to the right of
the first character, and so on.
int start_pos;
int end_pos;
int new_insert; These all indicate the destination of the cursor at the time the
callback is invoked. A value of 0 indicates that the cursor will
be to the left of the first character, 1 to the right of the first
character, and so on.
char *text; The string beginning at cur_insert.
int length; The number of characters from the selected character to the
end of the segment.
int doit; Indicates whether or not this modification will be applied to
the widget. If doit is zero, the cursor remains at cur_insert. If
doit is nonzero, the cursor will be repositioned at new_insert.


If cbinfo->event is NULL, the cursor motion occurred because:
• Your application set a resource on this widget that affects the cursor position.
Or:
• The application called a function that repositioned the cursor.
The PtMultiText widget defines several convenience functions and data structures
that make it easier to use the widget once it’s been created. Here’s a brief overview:
PtMultiLines_t Structure for setting multiline text and attributes
PtMultiTextAttributes_t
Attributes for multiline text
PtMultiTextCallback_t, PtMultiTextControl_t
Information passed to PtMultiText callbacks
PtMultiTextCreateAttributes()
Initialize a multitext attribute structure.
PtMultiTextGetAttributes()
Get the attributes of a PtMultiText widget.
PtMultiTextInfo() Get character/line information from a PtMultiText widget.
PtMultiTextInfo_t
PtMultiTextLine_t
Information about a line of text in a PtMultiText
PtMultiTextModifyAttributes()
Modify the attributes of a PtMultiText widget.
PtMultiTextModifyText()
Modify the contents of a PtMultiText widget.
PtMultiTextQuery_t
Structure for getting information about a line or character
PtMultiTextSegment_t
Information about a segment of text in a PtMultiText
PtTextGetSelection()
Get the selected range from a PtText widget.

PtTextModifyText() Modify the contents of a PtText widget.
PtTextSetSelection()
Set the selected range for a PtText widget.

PtMultiLines_t © 2010, QNX Software Systems GmbH & Co. KG.
Structure for setting multiline text and attributes
Synopsis:
typedef struct
{
char * string;
char * font;
PgColor_t text_color;
PgColor_t background_color;
} PtMultiLines_t;
Description:
This structure is used to specify multiline text and its attributes. You can pass an array
of these structures to the PtMultiText widget’s
Pt_ARG_MULTITEXT_SEGMENTS resource.
The members include:
string The UTF-8 text string to display.

font The font used to render text. This must be specified as the name
of an existing font or as one of the following special values:
Pt_INHERIT_FONT Use the same font as the previous range.
Pt_DEFAULT_FONT Use the value of the

Pt_ARG_TEXT_FONT resource.
To make text bold/italic, change the font to a bold/italic typeface.
text_color The color used for the text.

This must be set to a valid color (i.e. a variable of type
PgColor_t — see the Photon Library Reference) or one of the
following special values:
Pt_INHERIT_COLOR
Use the same color as the previous range.
Pt_DEFAULT_COLOR
Use the value of the Pt_ARG_COLOR resource.
background_color The color used as a background for the text. This must be set to
a valid color (i.e. a variable of type PgColor_t) or one of the
Pt_INHERIT_COLOR
Pt_DEFAULT_COLOR
Use the value of the Pt_ARG_FILL_COLOR resource.

© 2010, QNX Software Systems GmbH & Co. KG. PtMultiLines_t
Classification:
Photon
See also:
PtMultiText, PtMultiTextAttributes_t
PgColor_t in the Photon Library Reference

PtMultiTextAttributes_t © 2010, QNX Software Systems GmbH & Co. KG.
Attributes for multiline text
Synopsis:
typedef struct
{
char * font;
PgColor_t text_color;
PgColor_t background_color;
int flags;
void * tag;
} PtMultiTextAttributes_t;
Description:
This structure describes a set of attributes for multiline text:
font The font used to render text. This must be specified as the name
of an existing font or as one of the following special values:
Pt_INHERIT_FONT Use the same font as the previous range.
Pt_DEFAULT_FONT Use the value of the

Pt_ARG_TEXT_FONT resource.
To make text bold/italic, change the font to a bold/italic typeface.
text_color The color used for the text.

This must be set to a valid color (i.e. a variable of type
PgColor_t — see the Photon Library Reference) or one of the
Pt_INHERIT_COLOR
Pt_DEFAULT_COLOR
Use the value of the Pt_ARG_COLOR resource.
background_color The color used as a background for the text. This must be set to
a valid color (i.e. a variable of type PgColor_t) or one of the
Pt_INHERIT_COLOR
Pt_DEFAULT_COLOR
Use the value of the Pt_ARG_FILL_COLOR resource.
flags For internal use.

tag To be used at your application’s discretion.

© 2010, QNX Software Systems GmbH & Co. KG. PtMultiTextAttributes_t
Classification:
Photon
See also:
PtMultiText, PtMultiTextInfo()
PgColor_t in the Photon Library Reference

PtMultiTextCallback_t © 2010, QNX Software Systems GmbH & Co. KG.
Synopsis:
typedef struct
{
PtTextCallback_t tc;
PtMultiTextAttributes_t const *attributes;
PtMultiTextSegment_t *seg;
void *extended_data;
} PtMultiTextCallback_t;
typedef PtMultiTextCallback_t PtMultiTextControl_t;

typedef PtMultiTextControl_t PtMultiTextInfo_t;
Description:
PtMultiTextCallback_t, PtMultiTextControl_t, and PtMultiTextInfo_t
are different names for the same structure. They’re used in callbacks for the
PtMultiText widgets as well as to specify actions or request data. The members of
these structures are:
tc A pointer to a PtTextCallback_t structure that describes the

affected text.
attributes A pointer to a PtMultiTextAttributes_t structure that

describes the attributes of the affected text.
seg A pointer to a PtMultiTextSegment_t structure that describes

the segment of text that’s involved in the modification that invoked
the callback.
extended_data A pointer to user data.
Classification:
Photon
See also:
PtMultiText, PtMultiTextAttributes_t, PtMultiTextSegment_t,
PtTextCallback_t

© 2010, QNX Software Systems GmbH & Co. KG. PtMultiTextCreateAttributes()
Initialize a multitext attribute structure
Synopsis:
PtMultiTextAttributes_t *
PtMultiTextCreateAttributes(
PtMultiTextAttributes_t *attrs);
Description:
This function initializes the specified PtMultiTextAttributes_t structure to
default values. If you don’t specify a PtMultiTextAttributes_t structure, one is
allocated and initialized.
Returns:
A pointer to the initialized attributes structure, or NULL if no memory was available.
Examples:
See PtMultiTextGetAttributes().
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTextGetSelection(), PtTextModifyText(), PtTextSetSelection(),

PtMultiTextGetAttributes() © 2010, QNX Software Systems GmbH & Co. KG.
Get the attributes of a PtMultiText widget
Synopsis:
PtMultiTextAttributes_t *
PtMultiTextGetAttributes(
PtWidget_t *widget,
int char_offset,
PtMultiTextAttributes_t *attributes,
int *start,
int *end );
Description:
This function sets the provided PtMultiTextAttributes_t structure to the
attributes found at char_offset.
If you provide the integers for start and end, the function sets these parameters to the
character offsets that mark the beginning and end of the segment that contains
char_offset. Both start and end are 0-based. So, for example, if *start is set to 0, it
indicates the first character in the widget’s text buffer.
Returns:
A pointer to the provided PtMultiTextAttributes_t structure, or NULL if the
specified widget is NULL or isn’t a PtMultiText widget.
Examples:
/* Standard headers */
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <string.h>
/* Toolkit headers */
#include <Ph.h>
#include <Pt.h>
#include <Ap.h>
/* Local headers */
#include "editor.h"
#include "abimport.h"
#include "proto.h"
int
save( PtWidget_t *widget, ApInfo_t *apinfo,
PtCallbackInfo_t *cbinfo )
{
PtArg_t argt;
FILE *fp;
char *text;
PtMultiTextAttributes_t attrs;
int start = 0, end = 0, len;
if( !(fp = fopen( "notepad", "w" ) ) )

return Pt_CONTINUE;
PtSetArg( &argt, Pt_ARG_TEXT_STRING, &text, 0 );

PtGetResources( ABW_text, 1, &argt );

© 2010, QNX Software Systems GmbH & Co. KG. PtMultiTextGetAttributes()
len = strlen( text ) + 1;

fwrite( &len, sizeof( len ), 1, fp );
fwrite( text, len, 1, fp );
PtMultiTextGetAttributes( ABW_text, start,
&attrs, NULL, &end );
while( end > start )
{
fwrite( &start, sizeof( start ), 1, fp);
fwrite( &end, sizeof( end ), 1, fp);
fwrite( &attrs, sizeof( attrs ), 1, fp );
if( attrs.font )
{ len = strlen( attrs.font ) +1;
fwrite( &len, sizeof( len ), 1, fp );
fwrite( attrs.font, len, 1, fp );
}
start = end;
PtMultiTextGetAttributes( ABW_text, start,
&attrs, NULL, &end );
}
fclose( fp );
widget = widget, apinfo = apinfo, cbinfo = cbinfo;
return Pt_CONTINUE;
}
int load( PtWidget_t *widget, ApInfo_t *apinfo,

{
PtArg_t argt;
FILE *fp;
char *text;
int start = -1, end = 0, len;
if( !(fp = fopen( "notepad", "r" ) ) )

return Pt_CONTINUE;
fread( &len, sizeof( len ), 1, fp );

if( !( text = (char *) malloc( len ) ) )
return Pt_CONTINUE;
fread( text, len, 1, fp );
PtSetArg( &argt, Pt_ARG_TEXT_STRING, text, 0 );

PtSetResources( ABW_text, 1, &argt );
free( text );
while( fread( &start, sizeof( start ), 1, fp ) )

{
fread( &end, sizeof( end ), 1, fp );
fread( &attrs, sizeof( attrs ), 1, fp );
if( attrs.font )
{ fread( &len, sizeof( len ), 1, fp );
attrs.font = (char *) malloc( len );
fread( attrs.font, len, 1, fp );
}
PtMultiTextModifyAttributes( ABW_text, start,
end, &attrs, -1 );
if( attrs.font )
free( attrs.font );
}
fclose( fp );
widget = widget, apinfo = apinfo, cbinfo = cbinfo;
return Pt_CONTINUE;

PtMultiTextGetAttributes() © 2010, QNX Software Systems GmbH & Co. KG.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtMultiTextCreateAttributes(), PtTextGetSelection(), PtTextModifyText(),
PtTextSetSelection(), PtMultiTextAttributes_t

© 2010, QNX Software Systems GmbH & Co. KG. PtMultiTextInfo()
Get character or line information from a PtMultiText widget
Synopsis:
int PtMultiTextInfo( PtWidget_t *widget,
int query_type,
int *char_offset,
int *line_num,
PtMultiTextLine_t *line,
int *start,
int *end,
int *length,
PtMultiTextSegment_t *seg,
PtMultiTextAttributes_t *attrs);
Description:
This function gets information about a character or line within a PtMultiText
widget.
Using the information returned in the provided integers and in the
PtMultiTextLine_t, PtMultiTextSegment_t, and
PtMultiTextAttributes_t structures, you can determine:
• which line a character is on
• the start and end offsets of a given line
• the segment and attributes that exist at the beginning of a line
• the segment and attributes that exist at a given character offset.
Any argument representing information that you don’t require can be set to NULL.
Any argument representing information you do require must point to an instance of the
integers or structures of the appropriate type. The data returned is copied from the
widget’s internal structures into the structures provided.
The returned data may not remain valid for very long, so you should use it
immediately!
If you set query_type to Pt_MT_QUERY_LINE, then:
• line_num must point to an instance of an int that specifies the line number on
which information will be collected (the widget’s first line is line 1, its second is
line 2, and so on)
• line_num will be set to the last line if the widget has fewer than line_num lines
• char_offset, if provided, will be set to the offset of the first character of the line
• attrs, if provided, will be filled in with the attributes in effect at the beginning of the
line
If you set query_type to Pt_MT_QUERY_CHAR, then:

PtMultiTextInfo() © 2010, QNX Software Systems GmbH & Co. KG.
• char_offset must point to an instance of an int that contains a character offset (the
widget’s first character is 0, its second is 1, and so on)
• char_offset will be set to the last character if the widget has fewer than char_offset
characters
• attrs, if provided, will be filled in with the attributes in effect at the given
char_offset
Here’s what the function fills in when you provide a pointer to any of the following
parameters:
line_num The number of the line found by the query.
line The line structure for that line.
start The character offset of the first character in the line.
end The character offset of the last character in the line.

Both start and end are 0-based. So, for example, if *start is set to 0, it
indicates the first character in the widget’s text buffer.
length The number of characters in the line.
seg The segment that contains char_offset.
You could use this function to scroll to a specific line. For example, if you set
Pt_ARG_CURSOR_POSITION to the offset of a character on line 35, the widget will
scroll to line 35. (The PtMultiText widget will scroll as necessary, horizontally and
vertically, to make the cursor visible).
Returns:
0 Success.
1 The provided widget is NULL or isn’t a PtMultiText widget.
Classification:
Photon
Safety
Signal handler No
Thread No

© 2010, QNX Software Systems GmbH & Co. KG. PtMultiTextInfo()
See also:
PtMultiTextAttributes_t, PtMultiTextLine_t, PtMultiTextSegment_t

PtMultiTextLine_t © 2010, QNX Software Systems GmbH & Co. KG.
Information about a line of text in a PtMultiText
Synopsis:
typedef struct Pt_emt_text_line
{
unsigned int first_char;
unsigned int byte_offset;
unsigned short num_chars;
PhRect_t extent;
PtMultiTextSegment_t *segment;
struct Pt_emt_text_line *prev;
struct Pt_emt_text_line *next;
} PtMultiTextLine_t;
Description:
The PtMultiTextLine_t structure describes a line of text as displayed in a
PtMultiText widget.
first_char The index into the entire string of the first character on the line.
byte_offset The offset into the entire string of the first character on the line, in
bytes.
num_chars The number of characters on the line.
extent The PhRect_t that specifies the extent of the line.
segment A pointer to the PtMultiTextSegment_t structure that describes

the segment in effect at the start of the line.
prev A pointer to the PtMultiTextLine_t structure for the previous line.
next A pointer to the PtMultiTextLine_t structure for the next line.
Classification:
Photon
See also:
PtMultiText, PtMultiTextInfo(), PtMultiTextSegment_t

© 2010, QNX Software Systems GmbH & Co. KG. PtMultiTextModifyAttributes()
Modify the attributes of a PtMultiText widget
Synopsis:
void PtMultiTextModifyAttributes(
PtWidget_t *widget,
int start,
int end,
PtMultiTextAttributes_t const *attrs,
int attributes_mask );
Description:
This function applies attributes to a range of characters within the specified
PtMultiText widget. All characters from start up to, but not including, end are
affected.
The attributes that this function applies are taken from the provided
PtMultiTextAttributes_t structure. Only the attributes specified in
attributes_mask are applied. The valid bits for this mask are:
• Pt_MT_FONT
• Pt_MT_FOREGROUND
• Pt_MT_TEXT_COLOR
• Pt_MT_BACKGROUND
• Pt_MT_BACKGROUND_COLOR
• Pt_MT_TAG
• Pt_MT_FLAGS
This function causes a nondestructive deselect before attempting the changes.
Examples:
See PtMultiTextGetAttributes().
Classification:
Photon
Safety
Signal handler No
Thread No

PtMultiTextModifyAttributes() © 2010, QNX Software Systems GmbH & Co. KG.
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtMultiTextModifyText()
Modify the contents of a PtMultiText widget
Synopsis:
void PtMultiTextModifyText(
PtWidget_t *widget,
int start,
int end,
int insert_pos,
char *text,
int length,
PtMultiTextAttributes_t const *attrs,
int attributes_mask );
Description:
This function modifies the contents and attributes of a PtMultiText widget.
If start doesn’t equal end, then:
• all characters from start up to but not including end are deleted
• the widget’s current insert position is set to the lesser of start and end
• insert_pos is ignored.
If start does equal end, then:
• no text is deleted
• the widget’s current insert position is set to insert_pos; if insert_pos equals -1, the
current insert position is set to the end of the widget’s text buffer.
Once the current insert position is set, the function inserts length characters from text.
It does this regardless of the widget’s insertion mode. If length is 0, no text is inserted.
Here’s what happens after the function inserts the text into the segment that contains
the current insert position:
• The text inherits the segment’s attributes.
• The text is separated into its own segment, but keeps its inherited values.
• The attributes specified by attributes_mask are applied to the new segment from
the attrs structure provided. The valid bits for this mask are:
- Pt_MT_FONT
- Pt_MT_FOREGROUND
- Pt_MT_TEXT_COLOR
- Pt_MT_BACKGROUND
- Pt_MT_BACKGROUND_COLOR
- Pt_MT_TAG
- Pt_MT_FLAGS

PtMultiTextModifyText() © 2010, QNX Software Systems GmbH & Co. KG.
This function causes a nondestructive deselect before attempting the changes.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtMultiTextQuery_t
Structure for getting information about a line or character
Synopsis:
typedef struct
{
int character_number;
int line_number;
PtMultiTextLine_t *line;
PtMultiTextSegment_t *segment;
char *character;
} PtMultiTextQuery_t;
Description:
This structure is used to get information about a specified line or character in a
PtMultiText widget. You’ll use it when getting the value of
Pt_ARG_MULTITEXT_QUERY_CHARACTER or
Pt_ARG_MULTITEXT_QUERY_LINE. When getting these resources, use the len
member of the PtArg_t structure (see the Photon Library Reference) to indicate the
character or line to be queried. When you get call PtGetResources(), the members of
the PtMultiTextQuery_t structure are filled in:
character_number The index into the string of the character queried. Characters
are numbered from 0.
line_number The index of the line queried. Lines are numbered from 1.
line A pointer to the PtMultiTextLine_t structure that describes

the line queried or the line that contains the character queried.
segment A pointer to the PtMultiTextSegment_t structure in effect

for the character queried or at the beginning of the line queried.
character The character queried or the first character of the line queried.
Classification:
Photon
See also:
PtMultiText, PtMultiTextSegment_t, PtMultiTextLine_t

PtMultiTextSegment_t © 2010, QNX Software Systems GmbH & Co. KG.
Information about a segment of text in a PtMultiText
Synopsis:
typedef struct Pt_emt_text_segment
{
int first_char;
int num_chars;
struct Pt_emt_text_segment *prev;
struct Pt_emt_text_segment *next;
} PtMultiTextSegment_t;
Description:
This structure that describes a segment of text in a PtMultiText widget. A segment
is a block of text for which some attributes (such as color and font) are set. The
members of the PtMultiTextSegment_t structure are:
attrs The PtMultiTextAttributes_t structure that describes the

attributes in effect for this segment of text.
first_char The multibyte (UTF-8) offset to the first character in the segment.
This isn’t the byte offset to the first character in the segment.
num_chars The number of multibyte (UTF-8) characters in the segment.
prev, next Pointers to the previous and next segments in the PtMultiText
widget.
Classification:
Photon
See also:
PtMultiText, PtMultiTextAttributes_t

© 2010, QNX Software Systems GmbH & Co. KG. PtNumeric
A superclass for numeric widgets
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtCompound → PtNumeric
• PtNumericFloat
• PtNumericInteger
PhAB icon:
Public header:
<photon/PtNumeric.h>
Description:
PtNumeric is a parent class for all numeric widgets. It creates a PtText widget and
arrows to let you interact with the widget. It also creates some of the base
functionality of numeric widgets.
New resources:

Pt_ARG_NUMERIC_FLAGS unsigned short Flag See below
Pt_ARG_NUMERIC_PREFIX char * String NULL
Pt_ARG_NUMERIC_SPACING unsigned short Scalar 1
Pt_ARG_NUMERIC_SUFFIX char * String NULL
Pt_ARG_NUMERIC_UPDOWN_WIDTH unsigned short Scalar 17
Pt_ARG_NUMERIC_FLAGS
unsigned short Flag Pt_NUMERIC_ENABLE_UPDOWN |
Pt_NUMERIC_WRAP |
Pt_NUMERIC_AUTO_HIGHLIGHT
Flags that control the widget’s appearance and behavior; any combination of:
Pt_NUMERIC_AUTO_HIGHLIGHT
Autohighlight text when selected.

PtNumeric © 2010, QNX Software Systems GmbH & Co. KG.
Pt_NUMERIC_ENABLE_UPDOWN
Display the up/down buttons.
Pt_NUMERIC_HEXADECIMAL
Display the value as a hexadecimal number (applies only to
PtNumericInteger).
Pt_NUMERIC_USE_SEPARATORS
Insert comma separators in values (e.g. 1,000).
Pt_NUMERIC_WRAP
Wrap numbers from minimum to maximum and from maximum to minimum.
Pt_ARG_NUMERIC_PREFIX
char * String NULL
A prefix string to be added to all entered values.
Pt_ARG_NUMERIC_SPACING
The spacing, in pixels, between the text field and the up/down buttons.
Pt_ARG_NUMERIC_SUFFIX
char * String NULL
A suffix string to be added to all entered values.
Pt_ARG_NUMERIC_UPDOWN_WIDTH
The width, in pixels, of the PtScrollbar widget.

Unless the resources are already defined in PtNumeric, the PtNumeric class uses
the resources of its exported subordinate child, PtScrollbar.

The PtNumeric class “inherits” all the resources of its exported subordinate child.
Where PtNumeric and its exported subordinate child both define resources having
the same name, the resource defined in PtNumeric takes precedence.

Pt_ARG_ARM_COLOR PtButton
Pt_ARG_ARM_FILL PtButton Pg_GRAY
Pt_ARG_ARM_IMAGE PtButton
Pt_ARG_DIM PtWidget
continued. . .

PtNumeric © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_POS PtWidget
Pt_ARG_RESIZE_FLAGS PtWidget Pt_RESIZE_Y_ALWAYS |
Pt_RESIZE_X_AS_REQUIRED
Pt_CB_ARM PtBasic
continued. . .


Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

PtNumericFloat © 2010, QNX Software Systems GmbH & Co. KG.
Floating-point numeric widget
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtCompound → PtNumeric →
PtNumericFloat
PhAB icon:
Public header:
<photon/PtNumericFloat.h>
Description:
The PtNumericFloat class is a numeric widget that lets you enter floating-point
values between given minimum and maximum values. You can also use an
incorporated PtScrollbar to increase or decrease the value by a set amount.
A PtNumericFloat widget.
In addition, you can use the resources defined by PtNumeric to add prefix and suffix
strings, and use comma separators. You can use Pt_ARG_NUMERIC_PRECISION to
specify the precision of the number (i.e. the number of decimal places, for example,
1,000.00).
PtNumericFloat defines several resources with a C type of double * and a Pt type
of Struct. Remember that you can’t set and get them as if they were scalar values.
Here’s how to set the widget’s value:
double number = 5.55;
PtSetResource (ABW_base_float, Pt_ARG_NUMERIC_VALUE,

&number, 0);
Here’s how to get the value:
double *number;
PtGetResource (ABW_base_float, Pt_ARG_NUMERIC_VALUE,

&number, 0);
printf ("Value is %f\n", *number);

© 2010, QNX Software Systems GmbH & Co. KG. PtNumericFloat
PtNumericFloat isn’t included in the shared ph library because it uses

floating-point operations. If you use it in a non-PhAB application, link with the static
library. For more information, see Compiling and linking a non-PhAB application in
the Programming Photon without PhAB chapter of the Photon Programmer’s Guide.
New resources:

Pt_ARG_NUMERIC_INCREMENT double * Struct 1.0
Pt_ARG_NUMERIC_MAX double * Struct 1000000.00
Pt_ARG_NUMERIC_MIN double * Struct -1000000.00
Pt_ARG_NUMERIC_PRECISION int Scalar 2
Pt_ARG_NUMERIC_VALUE double * Struct 0.0
Pt_CB_NUMERIC_CHANGED PtCallback_t * Link NULL
Pt_ARG_NUMERIC_INCREMENT
double * Struct 1.0
The value by which to increase or decrease the value when the up/down buttons are
pressed.
Pt_ARG_NUMERIC_MAX
double * Struct 1000000.00
The maximum value for the widget.
Pt_ARG_NUMERIC_MIN
double * Struct -1000000.00
The minimum value for the widget.

Pt_ARG_NUMERIC_PRECISION

int Scalar 2
The precision or number of displayed decimal places of the widget’s current value.
Pt_ARG_NUMERIC_VALUE
double * Struct 0.0
The current value of the widget.
Pt_CB_NUMERIC_CHANGED
widget’s value changes.
resource, these callbacks are also invoked when your application changes the
Pt_ARG_NUMERIC_VALUE with a call to PtSetResource() or PtSetResources(), or if
the Pt_ARG_NUMERIC_VALUE is changed indirectly by a change to
Pt_ARG_NUMERIC_MIN or Pt_ARG_NUMERIC_MAX.
following members:
reason Pt_CB_NUMERIC_CHANGED
reason_subtype A subtype that indicates why the callback was invoked:

• Pt_NUMERIC_CHANGED — the text in the numeric’s text
field has been changed.
• Pt_NUMERIC_SET — PtSetResource() or PtSetResources()
was called to change the current value.
• Pt_NUMERIC_UPDOWN_ACTIVATE — a button was pressed
to change the current value.
• Pt_NUMERIC_UPDOWN_REPEAT — a button was held down


cbdata A pointer to a PtNumericFloatCallback_t structure that

contains at least:
• double numeric_value — the current value of the widget

Unless the resources are already defined in PtNumericFloat, the PtNumericFloat
class uses the resources of its exported subordinate child, PtScrollbar.
The PtNumericFloat class “inherits” all the resources of its exported subordinate
child. Where PtNumericFloat and its exported subordinate child both define
resources having the same name, the resource defined in PtNumericFloat takes
precedence.

continued. . .


Pt_ARG_DIM PtWidget
Pt_ARG_NUMERIC_FLAGS PtNumeric
Pt_ARG_NUMERIC_PREFIX PtNumeric
Pt_ARG_NUMERIC_SPACING PtNumeric
Pt_ARG_NUMERIC_SUFFIX PtNumeric
Pt_ARG_NUMERIC_UPDOWN_WIDTH PtNumeric
continued. . .


Pt_ARG_POS PtWidget
Pt_CB_ACTIVATE PtBasic See below.
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
continued. . .


Pt_CB_ACTIVATE
If cbinfo->reason_subtype is Pt_NUMERIC_ACTIVATE, the callback was invoked
because you changed the value and pressed Enter while in PtNumericFloat’s text
field.

© 2010, QNX Software Systems GmbH & Co. KG. PtNumericInteger
Integer numeric widget
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtCompound → PtNumeric →
PtNumericInteger
PhAB icon:
Public header:
<photon/PtNumericInteger.h>
Description:
The PtNumericInteger class lets you specify integer values between given
minimum and maximum values.
A PtNumericInteger widget.
A PtScrollbar widget is included to let you increase or decrease the value by a set
amount. You can use the resources defined by PtNumeric to add prefix and suffix
strings, and use comma separators (e.g. 1,000).
If you want the value to be displayed as a hexadecimal value, set
Pt_NUMERIC_HEXADECIMAL in Pt_ARG_NUMERIC_FLAGS.
New resources:

Pt_ARG_NUMERIC_INCREMENT int Scalar 1
Pt_ARG_NUMERIC_MAX int Scalar INT_MAX
Pt_ARG_NUMERIC_MIN int Scalar INT_MIN
Pt_ARG_NUMERIC_VALUE int Scalar 0
Pt_CB_NUMERIC_CHANGED PtCallback_t * Link NULL
Pt_ARG_NUMERIC_INCREMENT

PtNumericInteger © 2010, QNX Software Systems GmbH & Co. KG.
The amount by which to increase or decrease the value when the up/down buttons are
pressed.
Pt_ARG_NUMERIC_MAX
int Scalar INT_MAX
The maximum value for the widget.
Pt_ARG_NUMERIC_MIN
int Scalar INT_MIN
The minimum value for the widget.
Pt_ARG_NUMERIC_VALUE
int Scalar 0
The current value of the widget.
Pt_CB_NUMERIC_CHANGED
widget’s value changes.
resource, these callbacks are also invoked when your application changes the
Pt_ARG_NUMERIC_VALUE with a call to PtSetResource() or PtSetResources(), or if
the Pt_ARG_NUMERIC_VALUE is changed indirectly by a change to
Pt_ARG_NUMERIC_MIN or Pt_ARG_NUMERIC_MAX.
following members:
reason Pt_CB_NUMERIC_CHANGED
reason_subtype A subtype that indicates why the callback was invoked:

• Pt_NUMERIC_CHANGED — the text in the numeric’s text

field has been changed.
• Pt_NUMERIC_SET — PtSetResource() or PtSetResources()
was called to change the current value.
• Pt_NUMERIC_UPDOWN_ACTIVATE — a button was pressed
• Pt_NUMERIC_UPDOWN_REPEAT — a button was held down

cbdata A pointer to a PtNumericIntegerCallback_t structure that

contains at least:
• int numeric_value — the current value of the widget.

Unless the resources are already defined in PtNumericInteger, the
PtNumericInteger class uses the resources of its exported subordinate child,
PtScrollbar.
The PtNumericInteger class “inherits” all the resources of its exported subordinate
child. Where PtNumericInteger and its exported subordinate child both define
resources having the same name, the resource defined in PtNumericInteger takes
precedence.

continued. . .


Pt_ARG_DIM PtWidget
continued. . .


Pt_ARG_NUMERIC_FLAGS PtNumeric
Pt_ARG_NUMERIC_PREFIX PtNumeric
Pt_ARG_NUMERIC_SPACING PtNumeric
Pt_ARG_NUMERIC_SUFFIX PtNumeric
Pt_ARG_NUMERIC_UPDOWN_WIDTH PtNumeric
Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
continued. . .


Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
Pt_CB_ACTIVATE
If cbinfo->reason_subtype is Pt_NUMERIC_ACTIVATE, the callback was invoked
because you changed the value and pressed Enter while in PtNumericInteger’s text
field.

© 2010, QNX Software Systems GmbH & Co. KG. PtOnOffButton
An on/off button that can be set or unset
Class hierarchy:
PtWidget -> PtBasic -> PtLabel -> PtButton -> PtOnOffButton
PhAB icon:
Public header:
<photon/PtOnOffButton.h>
Description:
A PtOnOffButton widget displays an on/off button that can be set or unset.
Instances of this class of widget are typically used in exclusive or nonexclusive groups.
A PtOnOffButton widget.
You can set the position of the text relative to the button with the
Pt_ARG_BALLOON_POSITION resource.
New resources:

Pt_ARG_ONOFF_STATE unsigned char Scalar 0 (off)
Pt_CB_ONOFF_NEW_VALUE PtCallback_t * Link NULL
Pt_ARG_ONOFF_STATE
unsigned char Scalar 0 (off)
The current state of the on/off button. If the button is off, this resource is 0; if the
button is on, it’s nonzero.

PtOnOffButton © 2010, QNX Software Systems GmbH & Co. KG.
Pt_CB_ONOFF_NEW_VALUE

when the state of the on/off button changes.
If you’ve set the Pt_CALLBACKS_ACTIVE bit set in the widget’s Pt_ARG_FLAGS
resource, these callbacks are also invoked when your application changes the state of
the button by calling PtSetResource() or PtSetResources().
following members:
reason Pt_CB_ONOFF_NEW_VALUE

cbdata A pointer to a PtOnOffButtonCallback_t structure that

contains at least the following member:
int state; The current state of the on/off button.

continued. . .


Pt_ARG_ARM_FILL PtButton
Pt_ARG_DIM PtWidget
Pt_ARG_FLAGS PtWidget |=Pt_SELECTABLE &=˜Pt_TOGGLE
continued. . .

PtOnOffButton © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_POS PtWidget
continued. . .


Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

PtOSContainer © 2010, QNX Software Systems GmbH & Co. KG.
Offscreen-context container for flicker-free drawing
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtOSContainer
PhAB icon:
Public header:
<photon/PtOSContainer.h>
Description:
PtOSContainer creates an offscreen context and forces all its children’s draws to be
directed to that context. The draw stream is rendered into offscreen video memory,
taking advantage of any hardware-acceleration features supported by the graphics
driver. The graphics hardware can then blit the image directly onto the screen,
resulting in flicker-free widgets and/or animation.
When you unrealize a PtOSContainer widget, its offscreen memory is automatically

released. When you rerealize the widget, the offscreen memory is reallocated.

continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtOSContainer

Pt_ARG_DIM PtWidget
Pt_ARG_FILL_COLOR PtBasic See below.
continued. . .

PtOSContainer © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtOSContainer

Pt_ARG_FILL_COLOR
You can’t set this resource to Pg_TRANSPARENT. The widget ignores any attempt to
do so.

PtPane © 2010, QNX Software Systems GmbH & Co. KG.
A container for organizing widgets
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtPane
PhAB icon:
Public header:
<photon/PtPane.h>
Description:
PtPane is a container widget that’s useful for logically or visually grouping widgets
in an application. Any child widgets that extend beyond the canvas of the PtPane
widget are clipped.
A dialog box featuring several PtPane widgets.

Pt_ARG_ANCHOR_FLAGS PtWidget Pt_LEFT_ANCHORED_LEFT|
Pt_RIGHT_ANCHORED_LEFT|
Pt_TOP_ANCHORED_TOP|
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtPane

Pt_ARG_BASIC_FLAGS PtBasic Pt_ALL_OUTLINES |
Pt_ALL_BEVELS |
Pt_FLAT_FILL
Pt_ARG_DIM PtWidget
Pt_ARG_FLAGS PtWidget Pt_HIGHLIGHTED
continued. . .

PtPane © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtPane

Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

PtPanelGroup © 2010, QNX Software Systems GmbH & Co. KG.
A container that manages panels
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtPanelGroup
PhAB icon:
Public header:
<photon/PtPanelGroup.h>
Description:
A PtPanelGroup is a container that manages panels and optionally provides a
method for you to switch between them.
A PtPanelGroup widget as used in PhAB.
PtPanelGroup provides two modes to switch between panels:
Multiple tabs As shown above, there’s one tab per panel — click on a tab to select
a panel.
Single tab When you click on the tab, a popup menu lets you select a panel:
You can make the PtPanelGroup switch automatically between these two selection
modes as necessary, depending on the available space — single-tab mode is useful
when there isn’t much horizontal space. For more information, see
Pt_ARG_PG_SELECTION_MODE.

© 2010, QNX Software Systems GmbH & Co. KG. PtPanelGroup
Populating a panel group

You can populate a PtPanelGroup in the following ways, depending on your
requirements:
• Multiple panels, created at design time
• Single panel, repopulated at runtime.
• A PtPanelGroup can use only one population method; you can’t add some panels
at design time and others at runtime. However, you can add an empty container and
populate it at runtime when you switch panels.
• If you use the single-panel method to populate the PtPanelGroup at runtime, you
can’t drag and drop the panels, to avoid the complexity of having different (and
possibly conflicting) population methods coexisting in the same panel group.
Multiple panels
When you design the UI for your application, you can put container widgets (i.e.
descendants of PtContainer) into a PtPanelGroup. PtPanelGroup manages
these containers and incorporates them into the selection mechanism (i.e. it assigns
tabs to them).
The panel group uses the Pt_ARG_TITLE resource for each container widget for that
widget’s tab title.
This method gives you complete control over the layout in an application-building
environment (for example, PhAB). The drawback to this method is that it requires
more memory at runtime, since all of the widgets in all of the panels exist for the
lifetime of the PtPanelGroup.
To add panels to a PtPanelGroup in PhAB, select a container widget from the palette
and click on the PtPanelGroup. The container is automatically sized to fit the panel
group. When you add other panels, click on the top part of the panel group (i.e. above
the existing panels and tabs). Use the Module Tree control panel to verify that the
panels are where you want them (for more information, see the chapter on PhAB’s
environment in the Photon Programmer’s Guide).
To flip between existing panels in PhAB, select the PtPanelGroup and change
Pt_ARG_PG_CURRENT_INDEX to the number of the panel you wish to edit.
Single panel
At runtime, your application’s code can clear and repopulate the PtPanelGroup
when a new panel is selected. This method might save a significant amount of memory
at runtime, but it’s less convenient than the first method, since it requires some code to
intercept the panel switching and to repopulate the panel group’s display.

This method yields slower switches, since your application must clear the panel
group’s display and then reconstruct it each time you select a different panel.
However, you can design the individual panels in PhAB (as picture modules) and then
use PtClearWidget() and ApCreateModule() whenever you switch panels.
If you choose this method to populate a PtPanelGroup, use the
Pt_ARG_PG_PANEL_TITLES resource to specify number of panels and their titles.
For an example of using this method, see Pt_CB_PG_PANEL_SWITCHING.
Panel margins
PtPanelGroup defines its own margins in addition to the margin width defined by
the PtBasic widget class. There are separate left, right, top, and bottom margins,
which are specified using these resources:
These margins are cumulative, so that the actual margin of one edge of the widget is
the corresponding resource value added to the margin width.
Panel indexes
Panels are indexed from 0 through n - 1, where n is the number of panels managed by
the PtPanelGroup. An index value of Pt_PG_INVALID may be interpreted as a
“NULL” value.
The panel indexes indicate the order of panels in the PtPanelGroup; they change
when panels are added, removed, or reordered.
New resources:

Pt_ARG_MARGIN_BOTTOM unsigned short Scalar 5
Pt_ARG_MARGIN_LEFT unsigned short Scalar 5
Pt_ARG_MARGIN_RIGHT unsigned short Scalar 5
Pt_ARG_MARGIN_TOP unsigned short Scalar 3
continued. . .


Pt_ARG_PG_CURRENT char * String NULL
Pt_ARG_PG_CURRENT_INDEX uint16_t Scalar Pt_PG_INVALID
Pt_ARG_PG_FLAGS unsigned short Flag 0x0
Pt_ARG_PG_OVERLAP_THRESHOLD unsigned char Scalar 128

Pt_ARG_PG_PANEL_TITLES char *, unsigned short Array NULL
Pt_ARG_PG_SELECTION_MODE unsigned char Scalar Pt_PG_AUTO
Pt_CB_PG_PANEL_SWITCHING PtCallback_t * Link NULL
Pt_ARG_MARGIN_BOTTOM
The amount of space between the bottom of the panel group’s canvas and the canvas
Pt_ARG_MARGIN_LEFT
The amount of space between the left side of the panel group’s canvas and the canvas
Pt_ARG_MARGIN_RIGHT
The amount of space between the right side of the panel group’s canvas and the canvas
Pt_ARG_MARGIN_TOP
The amount of space between the top of the panel group’s canvas and the canvas

Pt_ARG_PG_CURRENT

char * String NULL
The name of the currently selected panel.

You can set this resource to switch to another panel. If more than one panel has the
same title, the widget switches to the first one it finds with the specified title.
Pt_ARG_PG_CURRENT_INDEX
uint16_t Scalar Pt_PG_INVALID
The index of the currently selected panel, where 0 indicates the first panel. You can set
this resource to switch to another panel.
Pt_ARG_PG_FLAGS
unsigned short Flag 0x0
This resource controls the behavior of the PtPanelGroup. Possible values are:
Pt_PG_DND Support drag-and-drop operations of container-type widgets.

Panels that are dragged away from the PtPanelGroup are
reparented to another container if one is present at the drop site and it
also supports drag-and-drop operations. Otherwise a popup window
is created at the drop site with a new PtPanelGroup to display the
panel.
If the panel group is populated at runtime, drag-and-drop isn’t
supported and this flag is ignored.
Pt_PG_MULTI_CONTAINER_MODE (read-only)
The PtPanelGroup was populated with more than one container.
You can’t set or clear this bit; the widget sets or clears this bit to
reflect its state.
Pt_PG_SELECTOR_ALIGN_RIGHT
Align the tab or tabs to the right of the PtPanelGroup instead of the
left. Pt_ARG_MARGIN_WIDTH controls the amount that the
selector is inset from the edge.

Pt_PG_SELECTOR_ON_BOTTOM
Place the tab or tabs at the bottom of the PtPanelGroup instead of
at the top.
Pt_PG_TABS_EQUAL_SIZE
Force all tabs to be the same size. If this bit isn’t set, tabs occupy as
little space as possible to accommodate their displayable data, and
changing the size of one tab doesn’t affect the sizes of the others.
Pt_PG_USE_PANEL_COLORS
Let each tab specify its own color. This flag works only when the
panelgroup has multiple containers; the text and fill color for the tab
are retrieved from the Pt_ARG_COLOR and
Pt_ARG_FILL_COLOR resources of the corresponding panel.
Pt_ARG_PG_OVERLAP_THRESHOLD
The amount by which tabs can overlap before switching to/from single-tab selection
mode (providing the selection type is set to Pt_PG_AUTO).
This quantity is specified as an integer between 0 and 255 and represents a fraction of
tab width. For example, a value of 0 doesn’t let tabs overlap at all, while a value of
128 lets tabs overlap by up to half their width.
If you set this to too large a value, it might be difficult to use the tabs.
Pt_ARG_PG_PANEL_TITLES
char *, unsigned short Array NULL
An array of strings that represent the titles for the panels managed by this
PtPanelGroup.
If the PtPanelGroup is populated with multiple containers,

Pt_ARG_PG_PANEL_TITLES is a read-only resource.
When you get the value of this resource, it gives the titles of the panels and the number
of panels, regardless of how the panel group was populated.

Pt_ARG_PG_SELECTION_MODE

unsigned char Scalar Pt_PG_AUTO
This resource indicates the method you’ll use to select panels. One of:
Pt_PG_NONE Don’t use an internal selector. When this mode is in use, panels
must be selected programmatically (by setting the
Pt_ARG_PG_CURRENT or Pt_ARG_PG_CURRENT_INDEX
resource).
Pt_PG_AUTO Display one tab per panel as long as there’s enough space,
depending on the sizes of the tabs and the
Pt_ARG_PG_OVERLAP_THRESHOLD resource. If there isn’t
enough space, display a single tab that, when selected, provides a
popup list of panels.
Pt_PG_SINGLE_TAB
Use single-tab selection mode, regardless of the space available.
Pt_CB_PG_PANEL_SWITCHING
A list of PtCallback_t structures that define the callbacks that are invoked when a
new panel is selected. This resource lets you clear and repopulate the display container
(if necessary), set up resources of existing panels (if applicable), or prevent the switch
by returning a value other than Pt_CONTINUE.
resource, these callbacks are also invoked when your application changes
Pt_ARG_PG_CURRENT or Pt_ARG_PG_CURRENT_INDEX by calling
PtSetResource() or PtSetResources().
following members:
reason Pt_CB_PG_PANEL_SWITCHING
reason_subtype Not used.

caused the callback to be invoked. If event is NULL, then the

callback was invoked because the selection was changed

programmatically.
cbdata A pointer to a PtPanelGroupCallback_t structure that

contains at least:
• char *old_panel — the title of the panel that was previously
selected, or NULL if no panel was previously selected.
• char *new_panel — the title of the newly selected panel, or
NULL if no panel is being selected.
• uint16_t old_panel_index — the index of the panel that was
previously selected, or Pt_PG_INVALID if no panel was
previously selected
• uint16_t new_panel_index — the index of the newly
selected panel, or Pt_PG_INVALID if no panel is being
selected.
The panel indexes indicate the order of panels in the PtPanelGroup; they change
when panels are added, removed, or reordered.
These callbacks should return Pt_CONTINUE to permit the switch to occur. Returning
a value other than Pt_CONTINUE prevents the switch from taking place. This is useful
if you want to “lock” the PtPanelGroup to the currently selected panel.
For example, to clear and repopulate a PtPanelGroup at runtime in a
Pt_CB_PG_PANEL_SWITCHING callback:
int panelswitch_cb( PtWidget_t *widget,

ApInfo_t *apinfo,
PtCallbackInfo_t *cbinfo)
{
PtPanelGroupCallback_t *pgcb =
(PtPanelGroupCallback_t*)(cbinfo->cbdata);
/* We use some arbitrary user function that returns

nonzero if switch is ok */
if(!switch_ok(widget))
/* Prevent the switch from happening */
return(Pt_END);
/* Clear the PtPanelGroup display */
PtClearWidget(widget);
/* Here we use the panel indexes rather than titles

to figure out current panel. This is deterministic,
provided the Pt_ARG_PG_PANEL_TITLES resource
isn’t changed. */
switch(pgcb->new_panel_index)
{
case 0:

/* Populate the display. Note that we provide

widget (the PtPanelGroup pointer) as the
parent. In this case, PtPanelGroup accepts
the widgets as children. */
ApCreateModule(ABM_pic_module_0,widget,NULL);
PtReRealizeWidget( widget );
break;
case 1:
ApCreateModule(ABM_pic_module_1,widget,NULL);
PtReRealizeWidget( widget );
break;
...
}
return(Pt_CONTINUE); /* Let the switch proceed */

}

Pt_ARG_BASIC_FLAGS PtBasic Pt_ALL_OUTLINES
continued. . .


Pt_ARG_DIM PtWidget
Pt_ARG_POS PtWidget
continued. . .


Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
The PtPanelGroup widget defines the following convenience functions:
PtPGCreatePopup()
Create an empty copy of a panel group as a popup window

PtPGFindIndexByPanel()
Get the index for a panel, given a pointer to the panel
PtPGFindIndexByTitle()
Get the index of a panel, given its title
PtPGFindPanelByIndex()
Get a pointer to the panel widget with a given index
PtPGFindPanelByTitle()
Get a pointer to the panel widget with a given title
PtPGFindTitleByIndex()
Get the title of the panel with a given index

PtPGCreatePopup() © 2010, QNX Software Systems GmbH & Co. KG.
Create an empty copy of a panel group as a popup window
Synopsis:
PtWidget_t *PtPGCreatePopup( PtWidget_t *widget,
PhPoint_t const *pos );
Description:
This function creates an empty copy of the PtPanelGroup specified by widget, in the
form of a popup window. The popup window is positioned at pos, or at (0,0) if pos is
NULL.
PtPGCreatePopup() copies the following resources into the new panel group:
• Pt_ARG_ANCHOR_FLAGS
• Pt_ARG_BASIC_FLAGS
• Pt_ARG_BEVEL_WIDTH
• Pt_ARG_BITMAP_CURSOR
• Pt_ARG_COLOR
• Pt_ARG_CONTAINER_FLAGS
• Pt_ARG_CURSOR_COLOR
• Pt_ARG_CURSOR_TYPE
• Pt_ARG_DIM
• Pt_ARG_EFLAGS
• Pt_ARG_FILL_COLOR
• Pt_ARG_FILL_PATTERN
• Pt_ARG_FLAGS
• Pt_ARG_HELP_TOPIC
• Pt_ARG_MARGIN_HEIGHT
• Pt_ARG_MARGIN_WIDTH
• Pt_ARG_PG_FLAGS
• Pt_ARG_PG_SELECTION_MODE

© 2010, QNX Software Systems GmbH & Co. KG. PtPGCreatePopup()
• Pt_ARG_RESIZE_FLAGS
• Pt_ARG_TRANS_PATTERN
• Pt_CB_BALLOONS
• Pt_CB_BLOCKED
• Pt_CB_CHILD_ADDED_REMOVED
• Pt_CB_DESTROYED
• Pt_CB_FILTER
• Pt_CB_GOT_FOCUS
• Pt_CB_HOTKEY
• Pt_CB_LOST_FOCUS
• Pt_CB_MENU
• Pt_CB_PG_PANEL_SWITCHING
• Pt_CB_REALIZED
• Pt_CB_RESIZE
• Pt_CB_UNREALIZED
Returns:
A pointer the to new PtPanelGroup widget, or NULL if there wasn’t enough
memory.
To realize or otherwise manipulate the popup window, do it to the panel group’s parent
(using the PtWidgetParent() macro).
Classification:
Photon
Safety
Signal handler No
Thread No

PtPGCreatePopup() © 2010, QNX Software Systems GmbH & Co. KG.
See also:
PtPanelGroup
PhPoint_t, PtWidgetParent() in the Photon Library Reference

© 2010, QNX Software Systems GmbH & Co. KG. PtPGFindIndexByPanel()
Get the index of a panel, given a pointer to the panel
Synopsis:
int PtPGFindIndexByPanel( PtWidget_t *widget,
PtWidget_t const *panel );
Description:
This function retrieves the index for a specified panel within the PtPanelGroup
specified by the widget argument.
Returns:
The panel index, or Pt_PG_INVALID if the panel couldn’t be found, or if the
PtPanelGroup isn’t in multiple-container mode.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtPanelGroup, PtPGFindIndexByTitle(), PtPGFindPanelByIndex(),
PtPGFindPanelByTitle(), PtPGFindTitleByIndex()

PtPGFindIndexByTitle() © 2010, QNX Software Systems GmbH & Co. KG.
Get the index of a panel, given its title
Synopsis:
int PtPGFindIndexByTitle( PtWidget_t *widget,
char const *title );
Description:
This function retrieves the index of the panel with the specified title within the
PtPanelGroup specified by the widget argument.
Returns:
The panel index, or Pt_PG_INVALID if the panel couldn’t be found.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtPanelGroup, PtPGFindIndexByPanel(), PtPGFindPanelByIndex(),

© 2010, QNX Software Systems GmbH & Co. KG. PtPGFindPanelByIndex()
Get a pointer to the panel widget with a given index
Synopsis:
PtWidget_t *PtPGFindPanelByIndex( PtWidget_t *widget,
int panel );
Description:
This function retrieves the panel associated with the specified panel index within the
Returns:
A pointer to the panel widget, or NULL if the specified panel doesn’t exist or the
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtPanelGroup, PtPGFindIndexByPanel(), PtPGFindIndexByTitle(),

PtPGFindPanelByTitle() © 2010, QNX Software Systems GmbH & Co. KG.
Get a pointer to the panel widget with a given title
Synopsis:
PtWidget_t *PtPGFindPanelByTitle( PtWidget_t *widget,
char const *title );
Description:
This function retrieves the panel with the specified title within the PtPanelGroup
specified by the widget argument.
Returns:
A pointer to the panel widget, or NULL if the panel couldn’t be found or the
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtPGFindPanelByIndex(), PtPGFindTitleByIndex()

© 2010, QNX Software Systems GmbH & Co. KG. PtPGFindTitleByIndex()
Get the title of the panel with a given index
Synopsis:
char *PtPGFindTitleByIndex( PtWidget_t *widget,
int index );
Description:
This function retrieves the title of the panel with the specified index within the
Returns:
A pointer to the title of the specified panel, or NULL if the specified panel doesn’t
exist.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtPGFindPanelByIndex(), PtPGFindPanelByTitle()

PtPixel © 2010, QNX Software Systems GmbH & Co. KG.
A set of points
Class hierarchy:
PtWidget → PtBasic → PtGraphic → PtPixel
PhAB icon:
Public header:
<photon/PtPixel.h>
Description:
You can use the PtPixel widget to draw a set of points. The array of points,
Pt_ARG_POINTS specifies a number of points to be drawn using the widget’s
drawing attributes. These points are relative to the widget’s Pt_ARG_ORIGIN. For
more information, see PtGraphic.
Each point in the Pt_ARG_POINTS array is a position at which a point is to be drawn.
The points are drawn independently of each other (i.e. they’re not connected).

Pt_ARG_COLOR PtBasic Pg_BLACK
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtPixel

Pt_ARG_DASH_LIST PtGraphic Not used by this class.
Pt_ARG_DASH_SCALE PtGraphic Not used by this class.
Pt_ARG_DIM PtWidget
Pt_ARG_LINE_CAP PtGraphic Not used by this class.
Pt_ARG_LINE_JOIN PtGraphic Not used by this class.
continued. . .

PtPixel © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

© 2010, QNX Software Systems GmbH & Co. KG. PtPolygon
A set of connected line segments
Class hierarchy:
PtWidget → PtBasic → PtGraphic → PtPolygon
PhAB icon:
Public header:
<photon/PtPolygon.h>
Description:
You can use the PtPolygon widget to draw a set of connected line segments, called a
polyline, from the vertices of the line segments.
Open or closed PtPolygon widgets.
The points that you specify in the Pt_ARG_POINTS resource are the vertices of the
polyline or polygon. These points are relative to the widget’s Pt_ARG_ORIGIN. For
more information, see PtGraphic.
For a polygon, the last vertex doesn’t have to be the same as the first; the widget can
close the polygon for you.
You can use Pt_ARG_POLYGON_FLAGS to specify:
• whether points in the polygon definition are relative to the previous point or in
absolute coordinates
• whether a polyline (open curve) or polygon (closed curve) is to be drawn.
New resources:

PtPolygon © 2010, QNX Software Systems GmbH & Co. KG.
Pt_ARG_POLYGON_FLAGS
This resource defines the type of polygon to be drawn. You can OR the following flag
bits (defined in <photon/Pg.h>):
Pg_CLOSED Connect the last point to the first.
Pg_POLY_RELATIVE
Use relative coordinates to draw the polygon. Each point is relative
to the previous point.

continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtPolygon

Pt_ARG_DIM PtWidget
Pt_ARG_INSIDE_FILL_PATTERN PtGraphic
Pt_ARG_INSIDE_TRANS_PATTERN PtGraphic
continued. . .

PtPolygon © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

© 2010, QNX Software Systems GmbH & Co. KG. PtPrintSel
A widget for selecting printing properties
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtPrintSel
PhAB icon:
Public header:
<photon/PtPrintSel.h>
Description:
The PtPrintSel widget lets you select a printer, change its properties, and optionally
select a range of pages and the number of copies to print.
A PtPrintSel widget.
The widget has a resource for a print context, Pt_ARG_PRINT_CONTEXT, that you
must set to one you’ve created with PpCreatePC():

PtPrintSel © 2010, QNX Software Systems GmbH & Co. KG.
PtSetArg(&args[0], Pt_ARG_PRINT_CONTEXT, pc, 0);

/* Set some other resources... */
printsel = PtCreateWidget(PtPrintSel, window, nargs, args);
The widget automatically handles all aspects of selecting a printer and also runs the
properties application to modify elements in the print context. When you’re finished
selecting the printer, you can get the modified print context by using PtGetResource()
or PtGetResources() to get the widget’s print-context resource:
/* The user has finished configuring the print session. */
PtGetResource( printsel, Pt_ARG_PRINT_CONTEXT, &pc, 0);
New resources:

Pt_ARG_PRINT_CONTEXT PpPrintContext_t Struct NULL
Pt_ARG_PRINT_FLAGS unsigned short Flag Pt_PRINTSEL_FILE_PANE | Pt_PRINTSEL_SETTINGS_PANE
| Pt_PRINTSEL_PREFERENCES
Pt_ARG_PRINT_FILE char * String NULL

Pt_ARG_PS_LBL_ALL char * String Print All Pages
Pt_ARG_PS_LBL_COLLATED char * String Print Collated
Pt_ARG_PS_LBL_COPIES char * String Copies:
Pt_ARG_PS_LBL_DOUBLE_SIDED char * String Print Double Sided
Pt_ARG_PS_LBL_FILE char * String File:
Pt_ARG_PS_LBL_FROM char * String From:
Pt_ARG_PS_LBL_NAME char * String Name:
Pt_ARG_PS_LBL_NOT_COLLATED char * String Print Not Collated
Pt_ARG_PS_LBL_PREFERENCES char * String Preferences
Pt_ARG_PS_LBL_PRINT_ORDER char * String Print Order
Pt_ARG_PS_LBL_PRINT_PAGES char * String Print Pages
Pt_ARG_PS_LBL_RANGE char * String Print Range
Pt_ARG_PS_LBL_REVERSED char * String Print Reversed Order
Pt_ARG_PS_LBL_SELECTION char * String Print Selection
Pt_ARG_PS_LBL_SEND_TO_FILE char * String Send to file
continued. . .


Pt_ARG_PS_LBL_SEND_TO_PRINTER char * String Send to printer
Pt_ARG_PS_LBL_TO char * String To:
Pt_CB_PRINT_PROPS PtCallback_t * Link NULL
If you click on the Preferences button, the widget displays the Printer Properties dialog
by PtPrintPropSelect(). You can customize this dialog by setting some
pseudo-resources. They aren’t really widget resources, but you can set them for
PtPrintSel as if they were, and the widget passes the settings to
PtPrintPropSelect(). For details about these resources, see the Photon Library
Reference.
Pt_ARG_PRINT_CONTEXT
PpPrintContext_t Struct NULL
The current Print Context settings. This resource isn’t available through PhAB, but
you’ll need a Print Context in order to do any printing. Use PpCreatePC() to create a
Print Context, and PpSetPC() to change its settings.
When you use PtGetResources() to get this resource, you must provide a
PpPrintContext_t structure, which is filled in directly with the values of the
context. Unlike most calls to PtGetResources(), you aren’t given a pointer into the
widget’s internal memory.
Pt_ARG_PRINT_FILE
char * String NULL
The name of the destination file when a document is printed to a file.
Pt_ARG_PRINT_FLAGS
unsigned short Flag Pt_PRINTSEL_FILE_PANE |
Pt_PRINTSEL_SETTINGS_PANE |
Pt_PRINTSEL_PREFERENCES
Flags that modify the appearance of the widget:

Pt_PRINTSEL_FILE_PANE
Enable the Send to file pane.
Pt_PRINTSEL_NO_COPIES
Disable the Copies widget.
Pt_PRINTSEL_NO_PAGE_RANGE
Disable the Print Range toggle button and the From and To fields.
Pt_PRINTSEL_NO_PRINTSELECT
Disable the printer-name combobox. Physical output goes to the default physical
printer whose name is shown.
Pt_PRINTSEL_NO_SELECT_RANGE
Disable the Print Selection toggle button.
Enable the Preferences button.
Pt_PRINTSEL_SETTINGS_PANE
Enable the Print Pages, Print Order and Copies panes.
The following flag macros are defined in <PtPrintSel.h>:
Pt_PRINTSEL_ALL_PANES
Pt_PRINTSEL_FILE_PANE | Pt_PRINTSEL_SETTINGS_PANE
Pt_PRINTSEL_DFLT_LOOK
Pt_PRINTSEL_FILE_PANE | Pt_PRINTSEL_SETTINGS_PANE |
Pt_ARG_PS_LBL_ALL
char * String Print All Pages
The label used for the button used to print all the pages.
Pt_ARG_PS_LBL_COLLATED
char * String Print Collated
The label used for the toggle button used to collate the pages.

Pt_ARG_PS_LBL_COPIES

char * String Copies:
The label for the field for specifying the number of copies.
Pt_ARG_PS_LBL_DOUBLE_SIDED
char * String Print Double Sided
The label for the toggle button used to choose between single- and double-sided
printing.
Pt_ARG_PS_LBL_FILE
char * String File:
The label of the field used to specify the name of the file to print to.
Pt_ARG_PS_LBL_FROM
char * String From:
The label used for the lower end of a range of pages to print.
Pt_ARG_PS_LBL_NAME
char * String Name:
The label for the field that holds the printer’s name.
Pt_ARG_PS_LBL_NOT_COLLATED
char * String Print Not Collated
The label for the button that requests noncollated printing.

Pt_ARG_PS_LBL_PREFERENCES

char * String Preferences
The label for the button for choosing print preferences.
Pt_ARG_PS_LBL_PRINT_ORDER
char * String Print Order
The title for the pane for selecting the order in which pages are printed.
Pt_ARG_PS_LBL_PRINT_PAGES
char * String Print Pages
The title of the pane for choosing which pages to print.
Pt_ARG_PS_LBL_RANGE
char * String Print Range
The label of the button and fields used to select a range of pages for printing.
Pt_ARG_PS_LBL_REVERSED
char * String Print Reversed Order
The label for the button to select printing in reverse order.
Pt_ARG_PS_LBL_SELECTION
char * String Print Selection
The label for the button for printing just the selected pages.

Pt_ARG_PS_LBL_SEND_TO_FILE

char * String Send to file
The title of the pane used to send the output to a file.
Pt_ARG_PS_LBL_SEND_TO_PRINTER
char * String Send to printer
The title of the pane used to send the output to a printer.
Pt_ARG_PS_LBL_TO
char * String To:
The label used for the upper end of a range of pages to print.
Pt_CB_PRINT_PROPS
you click on the Preferences button. If this resource isn’t set or is set to NULL,
clicking the Preferences button displays the Print Properties dialog by invoking the
PtPrintPropSelect() convenience function; for more information, see the Photon
Library Reference.
following members:
reason Pt_CB_PRINT_PROPS

• Pt_CB_PRINT_PROPS_END
• Pt_CB_PRINT_PROPS_START


cbdata A pointer to a PpPrintContext_t structure. For more

information, see the Printing chapter of the Photon Programmer’s
Guide.

Pt_ARG_CONTAINER_FLAGS PtContainer &=˜Pt_GETS_FOCUS
Pt_ARG_DIM PtWidget Read only
continued. . .


Pt_ARG_MARGIN_HEIGHT PtBasic Read only
Pt_ARG_MARGIN_WIDTH PtBasic Read only
Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
continued. . .


Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
The PtPrintSel class defines the following convenience function:
PtPrintSelect() Display a custom modal dialog for selecting print options
PtPrintSelection() Display a modal dialog for initiating printing
For more information, see the Photon Library Reference.

© 2010, QNX Software Systems GmbH & Co. KG. PtProgress
A progress bar
Class hierarchy:
PtWidget → PtBasic → PtGauge → PtProgress
PhAB icon:
Public header:
<photon/PtProgress.h>
Description:
The PtProgress widget draws a progress bar and (optionally) the corresponding
value.
Two styles of PtProgress bar.
The bar can be either a single bar, growing continuously as the value is changed, or it
can consist of a number of divisions of equal size.
The following bits of the Pt_ARG_GAUGE_FLAGS resource defined by PtGauge are
of particular interest to PtProgress:
Pt_GAUGE_INDETERMINATE
The current value is “unknown.”
Pt_GAUGE_LIVE Alter the widget’s appearance as time passes to indicate that

although the value may not be changing, the application is still
working.
Pt_GAUGE_INTERACTIVE
Let the user change the value of the gauge interactively at
runtime (e.g. by dragging). When the value is changed in this
manner, the widget’s Pt_CB_GAUGE_VALUE_CHANGED
New resources:

PtProgress © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_PROGRESS_BAR_COLOR PgColor_t Scalar Pg_RED
Pt_ARG_PROGRESS_DIVISIONS unsigned short Scalar 1
Pt_ARG_PROGRESS_GAP unsigned short Scalar 4
Pt_ARG_PROGRESS_SPACING unsigned short Scalar 0
Pt_ARG_PROGRESS_BAR_COLOR
The color of the progress bar. See PgColor_t in the Photon Library Reference.
Pt_ARG_PROGRESS_DIVISIONS
The number of divisions (1 means continuous).

PtProgress doesn’t use this resource, but any subclasses can.
Pt_ARG_PROGRESS_GAP
The gap (in pixels) between the progress bar and the text (if the text isn’t on top of the
bar).
PtProgress doesn’t use this resource, but any subclasses can.
Pt_ARG_PROGRESS_SPACING
The spacing (in pixels) between divisions (see Pt_ARG_PROGRESS_DIVISIONS).


Pt_ARG_COLOR PtBasic Pg_BLACK
Pt_ARG_DIM PtWidget
Pt_ARG_FILL_COLOR PtBasic Pg_GRAY
Pt_ARG_GAUGE_FLAGS PtGauge
Pt_ARG_GAUGE_FONT PtGauge
Pt_ARG_GAUGE_H_ALIGN PtGauge
Pt_ARG_GAUGE_V_ALIGN PtGauge
Pt_ARG_GAUGE_VALUE PtGauge
Pt_ARG_GAUGE_VALUE_PREFIX PtGauge
Pt_ARG_GAUGE_VALUE_SUFFIX PtGauge
continued. . .

PtProgress © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_MAXIMUM PtGauge
Pt_ARG_MINIMUM PtGauge
Pt_ARG_ORIENTATION PtGauge
Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
continued. . .


Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
PtProgress defines the following convenience functions:
These functions are useful only if you create subclasses of PtProgress.
PtProgressEntireSegment()
Get the entire segment of a progress bar
PtProgressFirstSegment()
Get the first segment of a progress bar
PtProgressNextSegment()
Get the next segment of a progress bar
PtProgressTextRect()
Get the text area of a progress bar

PtProgressEntireSegment() © 2010, QNX Software Systems GmbH & Co. KG.
Get the entire segment of a progress bar
Synopsis:
int PtProgressEntireSegment( PtWidget_t *widget,
short *start,
short *end);
Description:
This function gets the coordinates (x for a horizontal bar, y for a vertical one) of the
entire segment of the PtProgress pointed to by widget.
The coordinates are stored in the space pointed to by start and end, taking into account
whether or not the progress bar is inverted (i.e. the starting coordinate is always less
than or equal to the end coordinate).
Returns:
0 Success.
Pt_PROGRESS_NO_MORE_SEGMENTS
No segment was found.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtProgress, PtProgressEntireSegment(), PtProgressFirstSegment(),
PtProgressNextSegment(), PtProgressTextRect(),

© 2010, QNX Software Systems GmbH & Co. KG. PtProgressFirstSegment()
Get the first segment of a progress bar
Synopsis:
int PtProgressFirstSegment(PtWidget_t *widget,
short *start,
short *end );
Description:
first segment of the PtProgress pointed to by widget.
After calling this function, you can call PtProgressNextSegment() to get the
coordinates of succeeding segments.
Returns:
0 Success.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtProgress, PtProgressEntireSegment(), PtProgressNextSegment(),

PtProgressNextSegment() © 2010, QNX Software Systems GmbH & Co. KG.
Get the next segment of a progress bar
Synopsis:
int PtProgressNextSegment( PtWidget_t *widget,
short *start,
short *end);
Description:
next segment of the PtProgress pointed to by widget.
You must have called PtProgressFirstSegment() before calling this function.
Returns:
0 Success.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

© 2010, QNX Software Systems GmbH & Co. KG. PtProgressTextRect()
Get the text area of a progress bar
Synopsis:
void PtProgressTextRect( PtWidget_t const *widget,
PhRect_t *rect );
Description:
This function gets the rectangle in which text is drawn on the PtProgress pointed to
by widget. The rectangle’s coordinates are stored in the PhRect_t structure pointed
to by rect.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtProgressNextSegment()

PtRaw © 2010, QNX Software Systems GmbH & Co. KG.
A widget for use with Photon drawing primitives
Class hierarchy:
PtWidget → PtBasic → PtRaw
PhAB icon:
Public header:
<photon/PtRaw.h>
Description:
The PtRaw widget lets you use the Photon graphics drawing functions in applications
that use widgets.
The PtRaw class provides a good starting point for creating custom widgets. However,
custom widgets require their own Initialization, Extent, and Connect methods in
addition to a Draw method. Since the PtRaw widget is typically used for drawing, the
Draw function PtRaw supports is described in detail in this chapter. If you’d like more
information about when to use an Initialization, Extent, or Connect function, see
Building Custom Widgets.
With a PtRaw widget, you can draw using raw Photon graphics primitives without
completely losing what you’ve drawn when the widget is damaged. If the widget is
damaged, your application is notified so that it may redraw whatever it had previously
drawn.
You must refresh the contents of the canvas whenever they become damaged. This is
necessary because Photon doesn’t keep track of the widget’s raw contents for you. It’s
more efficient to have you, as application programmer, maintain the original data
structure and redraw the contents of the canvas. If it takes a long time to render the
contents of the canvas, consider rendering them into an image and copying the image
into the canvas when it’s damaged.
The canvas is considered damaged whenever one of the following situations occurs:
• A Photon expose event arrives at the canvas’s region.
• The widget is realized — the empty region has been drawn and the contents of the
canvas must be drawn.
• The region becomes unobscured — a region that was covering part of the canvas’
region has moved or been destroyed. The contents of the obscured area were lost,
so that area must be redrawn.

© 2010, QNX Software Systems GmbH & Co. KG. PtRaw
Draw function
The PtRaw widget defines a drawing function, Pt_ARG_RAW_DRAW_F, which is
invoked any time the contents of the canvas have to be refreshed due to damage.
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.
The drawing function you provide for the canvas gets two arguments when it’s
invoked:
• a pointer to the canvas widget
• a list of tiles indicating which parts of the canvas have been damaged.
For simple situations where the widget’s contents don’t change, you could put the
drawing primitives in the draw function directly. But it’s more likely that the contents
change dynamically. In this case, you should create a data structure, or model, that
defines the contents of the canvas.
Place a pointer to this data structure in the Pt_ARG_POINTER or
Pt_ARG_USER_DATA resource of the PtRaw widget, so that your draw function can
get it easily. This function should be able to walk the data structure you’ve provided
and to render the contents of the canvas, based on that information. The draw function
must handle its own clipping and highlighting.
Before your function begins drawing, it should establish its coordinate space correctly.
First, get the coordinates of the clip rectangle or the widget canvas, by calling
PtCalcCanvas() with the raw widget and the address of a rectangle to be filled with the
boundaries of the raw widget’s clip region.
Once you’ve determined the clip region, you should determine a scale factor, based on:
• the portion of the model you wish to display
• the overall extents of the model
• the current dimensions of the canvas.
The coordinates for the Pg* calls made within the draw function are relative to the
canvas of PtRaw’s parent. You need to translate the coordinates to compensate for the
raw widget’s margins. The edge of the margins is given as the rectangle’s upper-left
corner given by the PtCalcCanvas() function. Add the rectangle’s upper-left corner to
any translation you wish to perform on the model and pass this value to
PgSetTranslation().
This function takes two parameters. The second parameter should be set to the
constant Pg_RELATIVE. When rendering your model, scale the values by your scale
factor. The coordinates are automatically translated by the amount you specified in the
call to PgSetTranslation().

If your draw function changes the current clipping (PtClipAdd()) or translation

(PgSetTranslation()), be sure to restore them before returning from the draw function.
The simple example below shows a drawing function that fills the entire canvas with
blue:
void raw_draw(PtWidget_t *widget, PhTile_t *damage)

{
PhRect_t rect;
PtSuperClassDraw(PtBasic, widget, damage);
PtCalcCanvas(widget, &rect);
PgSetFillColor(Pg_BLUE);
PgDrawRect(&rect, Pg_DRAW_FILL);
}
If your model doesn’t explicitly represent color information, make sure you set the
stroke color to the value contained in the Pt_ARG_COLOR resource and the fill color
to the value specified in the Pt_ARG_FILL_COLOR resource.
Here’s a more detailed example of setting up and using a PtRaw widget:
pos.x = 220;
dim.w = 200, dim.h = 200;
n=0;
PtSetArg( &args[n], Pt_ARG_DIM, &dim, 0 );n++;
PtSetArg( &args[n], Pt_ARG_POS, &pos, 0 );n++;
PtSetArg( &args[n], Pt_ARG_RAW_DRAW_F, &draw, 1 );n++;
PtSetArg( &args[n], Pt_ARG_BEVEL_WIDTH, 2, 0 );n++;
PtSetArg( &args[n], Pt_ARG_FLAGS, Pt_TRUE,
Pt_SELECTABLE | Pt_HIGHLIGHTED );n++;
PtSetArg( &args[n], Pt_CB_ARM, &aback, 1 );n++;
PtCreateWidget(PtRaw, Pt_DEFAULT_PARENT, n, &args[0] );
.
.
.
void draw( PtWidget_t *widget, PhTile_t *damage )

{
PhRect_t rect;
damage = damage;
PtSuperClassDraw( PtBasic, widget, damage );
/* Find our canvas. */

PtCalcCanvas( widget, &rect );
/* Clip to our basic canvas (it’s only polite). */

PtClipAdd( widget, &rect );
/* Do our drawing... */
PgSetStrokeColor( Pg_RED );
PgDrawRect( &rect , Pg_DRAW_STROKE );
rect.ul.x++;
rect.ul.y++;
rect.lr.y--;
rect.lr.x--;

PgSetStrokeColor( Pg_WHITE );
PgDrawRect( &rect , Pg_DRAW_STROKE );
/* Remove our clipping */

PtClipRemove();
For more information, see the Raw Drawing and Animation chapter of the Photon
New resources:

Pt_ARG_RAW_CALC_OPAQUE_F See below Pointer NULL
Pt_ARG_RAW_CONNECT_F See below Pointer NULL
Pt_ARG_RAW_DRAW_F See below Pointer NULL
Pt_ARG_RAW_EXTENT_F See below Pointer NULL
Pt_ARG_RAW_INIT_F See below Pointer NULL
Pt_ARG_RAW_CALC_OPAQUE_F
See below Pointer NULL
A function that calculates the raw widget’s opacity tile list:
int (*calc_opaque_f) (PtWidget_t *widget)
If this resource isn’t set, the raw widget uses the function defined by PtBasic.
Pt_ARG_RAW_CONNECT_F
A function that creates any regions needed by the widget (normally PtWidget does
this for you):
int (*connect_f) (PtWidget_t *widget)

Pt_ARG_RAW_DRAW_F

A function that renders the widget on the screen:
void (*draw_f) (PtWidget_t *widget, PhTile_t *damage)
The damage argument points to a linked list of PhTile_t structures (see the Photon
Library Reference) that identify which areas of the widget have been damaged.
For more information, see the Raw Drawing and Animation chapter of the Photon
Pt_ARG_RAW_EXTENT_F
A function that determines the exact size of the widget based on default values and/or
the widget’s position, size, margins, borders, and highlighting information:
void (*extent_f) (PtWidget_t *widget)
Pt_ARG_RAW_INIT_F
This function is typically used by widgets that create children. It checks to ensure that
all members used in a subsequent call to the extent function are correctly assigned.
int (*init_f) (PtWidget_t *widget)


Pt_ARG_DIM PtWidget
continued. . .


Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
continued. . .



PtRawList © 2010, QNX Software Systems GmbH & Co. KG.
A raw list
Class hierarchy:
PtRawList
PhAB icon:
Public header:
<photon/PtRawList.h>
Description:
PtRawList is a list that gives you more control than PtList over the appearance and
behavior of its items. You can supply various functions to draw items, react to events,
and so on. If these functions aren’t given, the widget uses the default functions defined
for PtGenList.
Use PtGenListAddItems() to add items to the raw list.
New resources:

Pt_ARG_RAWLIST_BACKGROUND_F See below Pointer NULL
Pt_ARG_RAWLIST_DRAW_F See below Pointer NULL
Pt_ARG_RAWLIST_GFLAGS unsigned short Flag 0
Pt_ARG_RAWLIST_INFLATE_F See below Pointer NULL
Pt_ARG_RAWLIST_KEY_F See below Pointer NULL
Pt_ARG_RAWLIST_MOUSE_F See below Pointer NULL
Pt_ARG_RAWLIST_SELECT_F See below Pointer NULL
Pt_ARG_RAWLIST_BACKGROUND_F
A function that draws the background of the list. If this resource is NULL, the widget
uses the default function defined for PtGenList.
This function is of type PtRawListDrawBackgroundF_t; the prototype is:
void drawbackground( PtWidget_t *widget,

© 2010, QNX Software Systems GmbH & Co. KG. PtRawList
PhRect_t const *canvas,

PhRect_t const *empty );
The arguments are:
widget A pointer to the raw-list widget.
canvas A pointer to a PhRect_t structure (see the Photon Library Reference) that
defines the widget’s canvas.
empty A pointer to a PhRect_t structure that defines the empty area between the
last item and the bottom margin, if any.
Pt_ARG_RAWLIST_DRAW_F
A function that draws the widget. If this resource is NULL, the widget uses the default
function defined for PtGenList.
This function is of type PtRawListDrawF_t; the prototype is:
void drawf( PtWidget_t *widget,

unsigned index,
unsigned nitems,
PhRect_t *where );
The arguments are:
item A pointer to the PtGenListItem_t structure for the first item that needs
to be redrawn.
index The index of the item to be redrawn. The first item in the list has an index
of 1.
nitems The number of items the function should look at.
where A pointer to a PhRect_t structure (see the Photon Library Reference) that
defines the extent of the items. The function can modify the structure
pointed to by where, if needed.
Pt_ARG_RAWLIST_GFLAGS

Flags that affect the behavior of the widget. The bits include:
Pt_GEN_LIST_NO_BACKGROUND
If set, the Draw function doesn’t draw the background (under the items) or
margins.
Pt_GEN_LIST_ITEM_BACKGROUND
If this bit is set but the Pt_GEN_LIST_NO_BACKGROUND bit is clear, the Draw
function draws the background beneath each item and calls the List Draw
method once for each item that needs to be drawn.
Pt_GEN_LIST_NO_CLIPPING
If this bit is clear, the Draw method sets clipping to the widget’s canvas before
calling the List Draw method. The clipping isn’t set if no items are wider than
the canvas.
Pt_GEN_LIST_SHOW_DAMAGED
If this flag is set, the Draw method scans the damage list and sets the
Pt_LIST_ITEM_DAMAGE flag in the items that need to be drawn. The List Draw
method isn’t called at all if no items are damaged.
Pt_GEN_LIST_FULL_WIDTH
If this flag is set, the space to the right of an item is considered part of the item
— the width stored in the item is treated as a suggested minimum. If that space
is damaged, the item is marked as damaged. If this flag isn’t set, the space to the
right of an item is treated like the margin. Mouse clicks on that space are
ignored.
Pt_GEN_LIST_NO_AUTOFOCUS
If this flag is clear, giving focus to the widget when there’s no current item (see
“Current item” in the description of PtGenList) in that widget automatically
sets the current item to the first displayed item.
Pt_LIST_BALLOONS_IN_COLUMNS
If this flag is set and the widget has columns, the widget destroys and recreates
the balloon when the mouse pointer crosses column boundaries.
Pt_ARG_RAWLIST_INFLATE_F
A function that’s called when a balloon widget needs to be created. It should create a
balloon and returns its widget pointer. If this resource is NULL, the widget uses the
default function defined for PtGenList.

This function is of type PtRawListInflateF_t The prototype is:

PtWidget_t *inflatef( PtWidget_t *widget,
PtWidget_t *parent,
unsigned index,
int column,
PhArea_t *area );
The arguments are:
parent A pointer to the balloon’s parent.
item A pointer to the PtGenListItem_t structure for the item under the
mouse pointer.
index The index of the list item. The first item in the list has an index of 1.
column The index of the column under the mouse pointer, or -1 if the pointer isn’t
on a column or the list has no columns.
contains the area, relative to the parent widget, corresponding to the entire
item, Use PtGenListSetColumnBalloon() to adjust the area to the specified
column if you’re not using PtGenListCreateTextBalloon().
Pt_ARG_RAWLIST_KEY_F
A function that’s called for key events. If this resource is NULL, the widget uses the
default function defined for PtGenList.
This function is of type PtRawListKeyF_t; the prototype is:
int keyf( PtWidget_t *widget,

PhEvent_t *ev,
PhKeyEvent_t *kev,
PtGenListItem_t *newcur,
unsigned newpos );
The arguments are:
ev A pointer to the PhEvent_t structure (see the Photon Library Reference)

that describes the event.
kev A pointer a PhKeyEvent_t structure that describes the event data, which
the function can modify.

newcur A pointer to the PtGenListItem_t structure for the new current item
(see “Current item” in the description of PtGenList) in the list, if the
event is processed normally.
newpos The index of the new current item. The first item in the list has an index of
1.
This function must return one of the following values:
Pt_CONTINUE The PtGenList class processes the data contained in the

PhKeyEvent_t structure (see the Photon Library Reference).
Note that the class’s raw callbacks can modify the contents of this
structure.
Pt_END The widget ignores the event and the class’s raw callbacks return
Pt_CONTINUE immediately.
Pt_HALT The event is consumed by the widget, but PtGenList itself

doesn’t take any further action. The class’s raw callbacks return
Pt_END immediately.
Pt_ARG_RAWLIST_MOUSE_F
A function that’s called to handle mouse events if the mouse points to an item. If this
resource is NULL, the widget uses the default function defined for PtGenList.
This function is of type PtRawListMouseF_t, and the prototype is:
int mousef( PtWidget_t *widget,
unsigned index,
PhPoint_t *where,
int column,
PhEvent_t *event );
The arguments are:
item A pointer to the PtGenListItem_t structure for the item under the
mouse cursor.
index The index of that item. The first item in the list has an index of 1.
where A pointer to a PhPoint_t structure that gives the mouse position relative
to the item. The function can modify the structure pointed to by where.
column The column number.

event A pointer to the PhEvent_t structure (see the Photon Library Reference)
This function must return one of the following values:
Pt_CONTINUE The PtGenList class processes the data contained in the

PhKeyEvent_t structure (see the Photon Library Reference).
Note that the class’s raw callbacks can modify the contents of this
structure.
Pt_END The widget ignores the event and the class’s raw callbacks return
Pt_CONTINUE immediately.
Pt_HALT The event is consumed by the widget, but PtGenList itself

doesn’t take any further action. The class’s raw callbacks return
Pt_END immediately.
Pt_ARG_RAWLIST_SELECT_F
A function that’s called when an item is selected or unselected. If this resource is

NULL, the widget uses the default function defined for PtGenList.
This function is of type PtRawListSelectF_t, with a prototype of:
void selectf( PtWidget_t *widget,
int pos,
int column,
int nitems,
int subtype,
PhEvent_t *ev );
The arguments are:

item A pointer to a PtGenListItem_t structure. In
Pt_SELECTION_MODE_RANGE selection mode, it’s a pointer to the first
selected item. In other modes, it’s a pointer to the item that’s been
selected or unselected.
pos The index of that item. The first item on the list has an index of 1.
nitems The current number of selected items (the same as list->sel_count).
subtype The selection subtype.
event A pointer to the PhEvent_t structure (see the Photon Library Reference)


Pt_ARG_DIM PtWidget
continued. . .


Pt_ARG_POS PtWidget
continued. . .


Pt_CB_ARM PtBasic
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

Pt_CB_DND
For Pt_CB_DND callbacks for a PtRawList, the cbinfo->cbdata is a pointer to a
PtGenListDndCallback_t structure, containing at least the following members:
PtGenListItem_t *item
The target item involved in the drag-and-drop operation.
unsigned long flags

Possible values:
the item.
below the item.
the item.

You can use any of the convenience functions defined for PtGenList when working
with a PtRawList.

PtRawTree © 2010, QNX Software Systems GmbH & Co. KG.
A raw tree
Class hierarchy:
PtGenTree → PtRawTree
PhAB icon:
Public header:
<photon/PtRawTree.h>
Description:
PtRawTree is a tree that gives you more control than PtTree over the appearance
and behavior of its items. You can supply various functions to draw items, react to
events, and so on. If these functions aren’t given, the widget uses the default functions
defined for PtGenTree or PtGenList.
New resources:

Pt_ARG_RAWTREE_DRAW_F See below Pointer NULL
Pt_ARG_RAWTREE_INFLATE_F See below Pointer NULL
Pt_ARG_RAWTREE_SELECT_F See below Pointer NULL
Pt_ARG_RAWTREE_STATE_F See below Pointer NULL
Pt_ARG_RAWTREE_DRAW_F
A function that’s called to draw the widget. If this resource is NULL, the default
function for PtGenTree is called.
This function is of type PtRawTreeDrawItemF_t, and has this prototype:
void drawitemf( PtWidget_t *widget,

int lmargin,
int rmargin );
The arguments are:

© 2010, QNX Software Systems GmbH & Co. KG. PtRawTree
widget A pointer to the widget.

item A pointer to the PtGenTreeItem_t structure for the item that needs to
be redrawn.
where A pointer to a PhRect_t structure (see the Photon Library Reference)

that defines the extent of the item.
lmargin If positive, an additional left margin to add to the first column.
rmargin If positive, an additional right margin to add to the last column.
The PtGenTree List Draw method is responsible for drawing the lines and boxes
representing the tree structure. This function should draw only the item.
Pt_ARG_RAWTREE_INFLATE_F
A function that’s called when a balloon widget needs to be created. It should create a
balloon and return its widget pointer. If this resource is NULL, the default function for
PtGenTree is called.
This function is of type PtRawTreeInflateF_t, and has this prototype:
PtWidget_t *inflatef( PtWidget_t *widget,

PtWidget_t *parent,
unsigned index,
int column,
PhArea_t *area );
The arguments are:
parent A pointer to the balloon’s parent.
item A pointer to the PtGenTreeItem_t structure for the item under the
mouse pointer.
index The index of the list item. The first item in the list has an index of 1.
column The index of the column under the mouse pointer, or -1 if the pointer isn’t
on a column or the list has no columns.
contains the area, relative to the parent widget, corresponding to the entire
item, Use PtGenListSetColumnBalloon() to adjust the area to the specified
column if you’re not using PtGenListCreateTextBalloon().

Pt_ARG_RAWTREE_SELECT_F

A function that’s called when an item is selected or unselected. If this resource is

NULL, the default function for PtGenTree is called.
This function is of type PtRawTreeSelectF_t, and has this prototype:
void selectf( PtWidget_t *widget,

int pos,
int column,
int nitems,
int subtype,
PhEvent_t *ev );
The arguments are:
widget A pointer to the raw-tree widget.
item A pointer to a PtGenTreeItem_t structure. In

Pt_SELECTION_MODE_RANGE selection mode, it’s a pointer to the first
selected item. In other modes, it’s a pointer to the item that’s been
selected or unselected.
pos The index of that item. The first item on the list has an index of 1.
nitems The current number of selected items (the same as list->sel_count).
subtype The selection subtype.
event A pointer to a PhEvent_t structure (see the Photon Library Reference)

Pt_ARG_RAWTREE_STATE_F
A function that’s called when an item is expanded or collapsed. If this resource is

NULL, the default function for PtGenTree is called.
This function is of type PtRawTreeItemStateF_t, and has this prototype:
int statef( PtWidget_t *widget,


PhEvent_t *event,
int reason );
The arguments are:
PtWidget_t *widget
A pointer to the widget.
A pointer to the PtGenTreeItem_t structure for the item that’s being
collapsed or expanded.
PhEvent_t *event
A pointer to a PhEvent_t structure (see the Photon Library
Reference) that describes the event.
int reason Either Pt_TREE_EXPANDING or Pt_TREE_COLLAPSING.
If reason is Pt_TREE_EXPANDING, the item is about to be expanded. This function

can update the item’s branches before the actual expansion. After the function returns,
the widget displays a list of items in the expanded branch.
If an item in the list has its Pt_TREE_ITEM_EXPANDED flag set, the items below are
displayed too. To permit the expansion, return zero; to prevent it, return a nonzero
value.
If reason is Pt_TREE_COLLAPSING, the item has been collapsed. Its branches are
concealed and this function can free the associated items.

continued. . .


Pt_ARG_DIM PtWidget
continued. . .


Pt_ARG_POS PtWidget
Pt_ARG_TREE_FLAGS PtGenTree See below.
continued. . .


Pt_CB_ARM PtBasic
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
Pt_ARG_TREE_FLAGS
In addition to the flags defined by PtGenTree, the following flags are defined:
• Pt_TREE_BALLOON_ON_IMAGE — the balloon is permitted to cover the image

and the text
• Pt_TREE_BALLOON_ON_TREE — the balloon is permitted to cover the tree, the

image, and the text
By default, neither is set. The width and location of the balloon depend on these flags:

Neither Pt_TREE_BALLOON_ Pt_TREE_BALLOON_

ON_IMAGE ON_TREE
Additional Pt_ARG_TREE_FLAGS for a PtRawTree widget.
Pt_CB_DND
For Pt_CB_DND callbacks for a PtRawTree, the cbinfo->cbdata is a pointer to a
involved in the drag-and-drop operation.
unsigned long flags

Possible values:
the item.
below the item.
the item.


You can use any of the convenience functions defined for PtGenTree when working
with a PtRawTree.

© 2010, QNX Software Systems GmbH & Co. KG. PtRect
A rectangle
Class hierarchy:
PtWidget → PtBasic → PtGraphic → PtRect
PhAB icon:
Public header:
<photon/PtRect.h>
Description:
A PtRect widget draws a single rectangle whose bounding box is defined by two
points. To set these points, use the Pt_ARG_POINTS resource. These points are
relative to the widget’s Pt_ARG_ORIGIN. For more information, see PtGraphic.
If you don’t set Pt_ARG_POINTS, the rectangle defaults to the size defined by
Pt_ARG_POS and Pt_ARG_DIM (see PtWidget).
A PtRect widget.
The rectangle can have square or rounded corners. For rounded corners, specify a
radius in pixels for the curve at the corners by using the
Pt_ARG_RECT_ROUNDNESS resource.
New resources:
Resource C Type Pt Type Default

Pt_ARG_RECT_ROUNDNESS unsigned short Scalar 0
Pt_ARG_RECT_ROUNDNESS
Defines the number of pixels used for rounding the corners of the rectangle.

PtRect © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_DIM PtWidget
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtRect

Pt_ARG_INSIDE_FILL_PATTERN PtGraphic
Pt_ARG_INSIDE_TRANS_PATTERN PtGraphic
Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
continued. . .

PtRect © 2010, QNX Software Systems GmbH & Co. KG.

Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

© 2010, QNX Software Systems GmbH & Co. KG. PtRegion
A Photon region
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtRegion
• PtServer
PhAB icon:
None — instantiate it by calling PtCreateWidget().
Public header:
<photon/PtRegion.h>
Description:
PtRegion is ideal for controlling a region without foregoing the convenience of the
Photon widget library interface. With PtRegion, you can control a region without
having to modify the standard main loop function.
For more information about regions, see PhRegion_t in the Photon Library
Reference, and the Regions chapter of the Photon Programmer’s Guide.
New resources:

Pt_ARG_REGION_FIELDS long Flag 0
Pt_ARG_REGION_FLAGS long Flag 0
Pt_ARG_REGION_INFRONT long Scalar 0
Pt_ARG_REGION_INPUT_GROUP short Scalar 0
Pt_ARG_REGION_OPAQUE long Flag 0
Pt_ARG_REGION_PARENT long Scalar 0
Pt_ARG_REGION_RECTANGLES PhRect_t *, unsigned short Array NULL
Pt_ARG_REGION_SENSE long Flag 0
Pt_ARG_REGION_FIELDS

PtRegion © 2010, QNX Software Systems GmbH & Co. KG.
This resource indicates which portions of the region were changed the last time that
you set any resources, including the flags, sensitivity, opacity, origin, and position.
The following bits can be used to define a field in a region change
(PhRegionChange()) or open (PhRegionOpen()). For more information, see <PhT.h>.
The Ph_REGION_HANDLE, Ph_REGION_ORIGIN, and Ph_REGION_RECT bits are set

up automatically when the widget is initialized.
Bit Corresponding resource

Ph_REGION_FLAGS Pt_ARG_REGION_FLAGS
Ph_REGION_EV_OPAQUE Pt_ARG_REGION_OPAQUE
Ph_REGION_EV_SENSE Pt_ARG_REGION_SENSE
Ph_REGION_STATE Read-only. Don’t modify.
Ph_REGION_ORIGIN See below.
Ph_REGION_PARENT Pt_ARG_REGION_PARENT
Ph_REGION_IN_FRONT Pt_ARG_REGION_INFRONT
Ph_REGION_BEHIND See below.
Ph_REGION_RECT See below.
Ph_REGION_INPUT_GROUP Pt_ARG_REGION_INPUT_GROUP
Any time you change PtRegion’s Pt_ARG_POS or Pt_ARG_AREA resource, the

Ph_REGION_ORIGIN bit is changed automatically.
The Ph_REGION_BEHIND bit defines which region this region will be opened in front
of. The specified region becomes the brother in behind. A value of 0 makes the region
the rearmost child of its parent when created.
Any time you change PtRegion’s Pt_ARG_AREA or Pt_ARG_DIM resource, the
Ph_REGION_RECT bit is changed automatically.
Pt_ARG_REGION_FLAGS
long Flag 0
Defines the region type and behavior:
• Ph_WINDOW_REGION
• Ph_WND_MGR_REGION

• Ph_GRAFX_REGION
• Ph_PTR_REGION
• Ph_KBD_REGION
• Ph_PRINT_REGION
• Ph_INPUTGROUP_REGION
• Ph_AUXPTR_REGION
• Ph_FORCE_FRONT
• Ph_FOLLOW_IG_SIZE
• Ph_FORCE_BOUNDARY
• Ph_NO_COMPRESSION
• Ph_CURSOR_SET
Pt_ARG_REGION_INFRONT
long Scalar 0
Defines which region (rid) this region will be opened behind. The specified region
becomes the brother in front. A value of 0 makes the region the frontmost child of its
parent when created.
Pt_ARG_REGION_INPUT_GROUP
short Scalar 0
Associates the region with the specified input group.
Pt_ARG_REGION_OPAQUE
long Flag 0
A bitmask that defines which events this region is opaque to. For a list of event types,
see PhEvent_t in the Photon Library Reference.

Pt_ARG_REGION_PARENT

long Scalar 0
Specifies the ID (rid) of the region that will be this region’s parent.
Pt_ARG_REGION_RECTANGLES
PhRect_t *, unsigned short Array NULL
This resource allows you to create a region with more than one rectangle. When this
array has at least one element, the widget uses the rectangle(s) in the array rather than
its own extent for the rectangle set of its region.
Pt_ARG_REGION_SENSE
long Flag 0
A bitmask that defines which events this region is sensitive to. For a list of event types,
see PhEvent_t in the Photon Library Reference.

continued. . .


Pt_ARG_DIM PtWidget
continued. . .


Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
continued. . .


Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

PtScrollArea © 2010, QNX Software Systems GmbH & Co. KG.
A viewport for viewing a large virtual area
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtScrollArea
• PtScrollContainer
PhAB icon:
Public header:
<photon/PtScrollArea.h>
Description:
PtScrollArea is a metaclass that supports scrolling and panning for its subclasses.
It combines scrollbar widgets and an area that provides a viewport onto a virtual
display area. Typically, the virtual area is larger than the viewing area; the scrollbar
widgets let you bring any part of the virtual area into view.
As for other widgets, you can set the physical size of a PtScrollArea with its
Pt_ARG_AREA resource (inherited from PtWidget). The virtual size depends on its
Pt_ARG_SCROLLAREA_MAX_X and Pt_ARG_SCROLLAREA_MAX_Y resources.
Any anchorable children of a PtScrollArea widget anchor to the virtual size, not
the physical size.
If the virtual area’s size is greater than the viewport’s size, you’ll need horizontal
and/or vertical scrollbars to control the viewport’s position. The dimensions are
checked when the widget is realized to determine if scrollbars are necessary.
Pt_ARG_SCROLLBAR_X_DISPLAY and Pt_ARG_SCROLLBAR_Y_DISPLAY
indicate when the scrollbars should be displayed:
• Pt_NEVER — never display the scrollbars.
• Pt_ALWAYS — display the scrollbars even if they’re not needed.
• Pt_AS_REQUIRED — display the scrollbars only if they’re needed.
Scrolling notification
When you move either the vertical or horizontal scrollbar to change the viewport’s
position, the Pt_CB_SCROLLAREA_SCROLLED callbacks are invoked to notify your
application that the viewport has been moved. You may use these callbacks to keep
two related viewports synchronized with each other by monitoring both viewports and
updating the position of the alternate viewport when one of them scrolls. See
“Scrolling control” below.

© 2010, QNX Software Systems GmbH & Co. KG. PtScrollArea
Scrolling control
The scrollbars provided by the scrollable area let you vary the position of the viewport
between (0,0) and (xmax, ymax), where xmax and ymax are the maximum positions in
x and y. These are equal to the virtual area’s size in the specified dimension minus the
viewport’s size in that dimension.
The size of the handle used by the scrollbar to represent the viewport’s position within
the virtual area is the viewport’s size relative to the virtual area’s size.
The handle may be moved by incremental amounts by clicking on either of the arrow
buttons in the scrollbar. You can control the increment by setting the increment
resource corresponding to the scrollbar:
• Pt_ARG_SCROLLAREA_INCREMENT_X
• Pt_ARG_SCROLLAREA_INCREMENT_Y
These specify the number of pixels to increment the viewport’s position by when one
of the stepper buttons in the scrollbar is pressed.
You can pan the viewport by holding down the Alt key, pointing inside the viewport,
and dragging.
You can also update the viewport’s position under program control. To move the
viewport, you simply set a new position using the Pt_ARG_SCROLLAREA_POS_X
and Pt_ARG_SCROLLAREA_POS_Y resources.
New resources:

Pt_ARG_SCROLLAREA_FLAGS unsigned short Flag See below
Pt_ARG_SCROLLAREA_INCREMENT_X int Scalar 10
Pt_ARG_SCROLLAREA_INCREMENT_Y int Scalar 10
Pt_ARG_SCROLLAREA_MAX_X uint32_t Scalar 0
Pt_ARG_SCROLLAREA_MAX_Y uint32_t Scalar 0
Pt_ARG_SCROLLAREA_POS_X uint32_t Scalar 0
Pt_ARG_SCROLLAREA_POS_Y uint32_t Scalar 0
Pt_ARG_SCROLLAREA_SCROLLBAR_COLOR PgColor_t Scalar Pg_LGREY
Pt_ARG_SCROLLBAR_X_DISPLAY uint8_t Scalar Pt_AS_REQUIRED
Pt_ARG_SCROLLBAR_X_HEIGHT uint8_t Scalar 15
continued. . .


Pt_ARG_SCROLLBAR_Y_DISPLAY uint8_t Scalar Pt_AS_REQUIRED
Pt_ARG_SCROLLBAR_Y_WIDTH uint8_t Scalar 15
Pt_CB_SCROLLAREA_SCROLLED PtCallback_t * Link NULL
Pt_ARG_SCROLLAREA_FLAGS
unsigned short Flag Pt_SCROLLAREA_ENABLE_PAN
These flags control the behavior of the scroll area. Valid bits include:
Pt_SCROLLAREA_IGNORE_KEYS
Prevent the scroll area from handling and consuming the arrow keys, Pg Up, Pg
Dn, Home, or End.
Pt_SCROLLAREA_ENABLE_PAN
Allow you to pan the scroll area by Alt-clicking and dragging anywhere in the
client (viewport) area.
Pt_ARG_SCROLLAREA_INCREMENT_X
int Scalar 10
The number of pixels that the widget scrolls by when you click the horizontal arrow
buttons.
Pt_ARG_SCROLLAREA_INCREMENT_Y
int Scalar 10
The number of pixels that the widget scrolls by when you click the vertical arrow
buttons.
Pt_ARG_SCROLLAREA_MAX_X
uint32_t Scalar 0

The width (in pixels) of the total scrollable area. This is the widget’s virtual width. To
specify the displayed portion of this scrollable area, use Pt_ARG_AREA.
Pt_ARG_SCROLLAREA_MAX_Y
uint32_t Scalar 0
The height (in pixels) of the total scrollable area. This is the widget’s virtual height.
To specify the displayed portion of this scrollable area, use Pt_ARG_AREA.
Pt_ARG_SCROLLAREA_POS_X
uint32_t Scalar 0
The horizontal position of the displayed portion of the scrollable area.
Pt_ARG_SCROLLAREA_POS_Y
uint32_t Scalar 0
The vertical position of the displayed portion of the scrollable area.
Pt_ARG_SCROLLAREA_SCROLLBAR_COLOR
Sets the color of the widget’s scrollbars.
Pt_ARG_SCROLLBAR_X_DISPLAY
uint8_t Scalar Pt_AS_REQUIRED
Controls the visibility of the horizontal scrollbar. Possible values:
Pt_NEVER Don’t display.
Pt_ALWAYS Always display.
Pt_AS_REQUIRED
Display if the visible dimension is less than the virtual dimension.

Pt_ARG_SCROLLBAR_X_HEIGHT

uint8_t Scalar 15
The height, in pixels, of the horizontal scrollbar. The minimum height is 6 pixels.
Pt_ARG_SCROLLBAR_Y_DISPLAY
uint8_t Scalar Pt_AS_REQUIRED
Controls the visibility of the scrollbar. Possible values:
Pt_NEVER Don’t display.
Pt_ALWAYS Always display.
Pt_AS_REQUIRED
Display if the visible dimension is less than the virtual dimension.
Pt_ARG_SCROLLBAR_Y_WIDTH
uint8_t Scalar 15
The width, in pixels, of the vertical scrollbar. The minimum width is 6 pixels.
Pt_CB_SCROLLAREA_SCROLLED
A list of PtCallback_t structures that define the callbacks that the PtScrollArea
widget invokes when its scrollbars are moved.
resource, these callbacks are also invoked when your application changes the positions
of the scrollbars by calling PtSetResource() or PtSetResources().
following members:
reason Pt_CB_SCROLLAREA_SCROLLED


• Pt_SCROLLAREA_X_CHANGED — change in x (horizontal)
position.
• Pt_SCROLLAREA_Y_CHANGED — change in y (vertical)
position.
• Pt_SCROLLAREA_XY_CHANGED — simultaneous change in
both axes.

caused the callback to be invoked, or NULL if there’s no event.
cbdata A pointer to a PtScrollAreaCallback_t structure that

contains at least:
int32_t old_x, old_y

The x and y positions before this change.
int32_t new_x, new_y
The current x and y positions (after the change).

Pt_ARG_ANCHOR_FLAGS PtWidget Pt_RIGHT_ANCHORED_LEFT|
Pt_ARG_BASIC_FLAGS PtBasic Pt_ALL_ETCHES | Pt_ALL_OUTLINES |
Pt_FLAT_FILL
continued. . .


Pt_ARG_DIM PtWidget
Pt_ARG_FLAGS PtWidget |= Pt_GETS_FOCUS | Pt_HIGHLIGHTED | Pt_SET
| Pt_REGION
continued. . .


Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
continued. . .


Pt_CB_RAW PtWidget
The PtScrollArea widget defines the following convenience function:
PtScrollAreaCanvas()
Get the viewport canvas, as opposed to the widget canvas

© 2010, QNX Software Systems GmbH & Co. KG. PtScrollAreaCanvas()
Get the viewport canvas of a PtScrollArea
Synopsis:
PhRect_t *PtScrollAreaCanvas( PtWidget_t *widget,
PhRect_t *rect );
Library:
ph
Description:
This function determines the canvas rectangle for the specified widget’s viewport. The
PtScrollArea canvas rectangle describes the area inside the widget’s border; the
viewport’s canvas is the area inside the scrollbars. The rect argument must point to a
PhRect_t structure; if you pass rect as NULL, the function returns NULL.
Returns:
A pointer to the viewport’s canvas, or NULL if an error occurs.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:

PtScrollbar © 2010, QNX Software Systems GmbH & Co. KG.
A scrollbar
Class hierarchy:
PtWidget → PtBasic → PtGauge → PtScrollbar
PhAB icon:
Public header:
<photon/PtScrollbar.h>
Description:
A PtScrollbar widget provides a scrollbar. It returns values (via callbacks) that
indicate a value within the provided range.
A PtScrollbar widget.
A scrollbar consists of the following parts:
Trough A shaded box, oriented horizontally or vertically, that represents

the total range.
Handle A shaded button-like object that moves through the trough. Its
range of motion is limited by the trough.
Stepper arrows Arrow buttons drawn at either end of the trough that let the handle
slide forward or back by incremental amounts. The width of a
stepper arrow in a horizontal scrollbar is automatically set to be
3/4 of the height of the scrollbar. Similarly, the height of a stepper
arrow in a vertical scrollbar is set to 3/4 of the scrollbar’s width.
A scrollbar can return values from minimum to (maximum - size-of-handle + 1).

You’ll find the returned values useful for implementing scrolling areas, text
viewers/editors, and so on.
The handle size is determined by the Pt_ARG_SLIDER_SIZE resource. If you don’t
set this resource, the handle size is one-tenth of the specified range.
The handle’s value is represented by its relative position within the trough. The size of
the trough represents the allowable range of values.
Your application can also control the handle’s size. You can change it to indicate an
object’s size and the portion viewed when the scrollbar is used for scrolling.
Scrolling is the action of controlling which part of an object is displayed when the
object is too large to view all at once. By default, the trough’s size visually represents

© 2010, QNX Software Systems GmbH & Co. KG. PtScrollbar
the scroll region — the total length of the object being viewed; you can use the
Pt_SCROLLBAR_FIXED_SLIDER_SIZE bit in the Pt_ARG_SCROLLBAR_FLAGS to
override this.
The edge of the handle represents your current relative position within the object. The
handle’s size represents the proportion of the entire object that is currently in view.
Sliding the handle within the trough controls which portion of the object is displayed.
Your application is responsible for changing the display of the object in response to
any change in the handle’s position.
Mouse actions
When the mouse button is pressed, the result depends on the location of the pointer.
If the pointer is: the handle:

On either arrow Moves up or down one increment (holding down the mouse
button repeats the action)
In the trough Moves up or down one page increment (holding down the
mouse button repeats the action)
On the handle Starts a drag action
If you hold down the Ctrl and click the button while pointing at the trough, the slider
jumps to the pointer’s position.
Keyboard actions
If you press: The handle moves:

↑ Up one increment
↓ Down one increment
→ Right one increment
← Left one increment
Ctrl-↑ Up one page increment
Ctrl-↓ Down one page increment
Ctrl-→ Right one page increment
Ctrl-← Left one page increment
Home To the top or left (depending on the orientation)
End To the bottom or right (depending on the orientation)

New resources:

Pt_ARG_INCREMENT long Scalar 1
Pt_ARG_MIN_SLIDER_SIZE unsigned short Scalar 10
Pt_ARG_PAGE_INCREMENT int Scalar -1
Pt_ARG_SCROLLBAR_FLAGS unsigned short Flag 0
Pt_ARG_SLIDER_SIZE int Scalar 1/10th of range
Pt_CB_SCROLL_MOVE PtCallback_t * Link NULL
Pt_ARG_INCREMENT
long Scalar 1
The value the widget scrolls by when you click the arrow buttons.
Pt_ARG_MIN_SLIDER_SIZE
The minimum length of the handle, in pixels.
Pt_ARG_PAGE_INCREMENT
int Scalar -1
The handle increment to be used when the scrollbar is moved by a page. If this value
is -1, the value for Pt_ARG_SLIDER_SIZE is used.
Pt_ARG_SCROLLBAR_FLAGS
Flags that control the appearance and behavior of the scrollbar. The valid bits are:

Pt_SCROLLBAR_FIXED_SLIDER_SIZE
Make the scrollbar slider a fixed size, as specified by
Pt_ARG_MIN_SLIDER_SIZE.
Pt_SCROLLBAR_FOCUSED
Cause the scrollbar to be rendered as if it has focus even if it doesn’t. This is
useful in applications where one widget collects keystrokes and directs specific
keys to other widgets.
Pt_SCROLLBAR_SHOW_ARROWS
Display arrow buttons at the ends of the trough.
Pt_ARG_SLIDER_SIZE
int Scalar 1/10th of range
The length of the handle, in the range of 1 to (Pt_ARG_MAXIMUM -

Pt_ARG_MINIMUM).
Pt_CB_SCROLL_MOVE
A list of PtCallback_t structures that define the callbacks that the scrollbar invokes
when the scroll position changes.
resource, these callbacks are also invoked when your application changes the position
of the scrollbar by calling PtSetResource() or PtSetResources().
following members:
reason Pt_CB_SCROLL_MOVE

cbdata A pointer to a PtScrollbarCallback_t structure that
• unsigned action — one of the following:
Pt_SCROLL_DECREMENT
The scrollbar has been decreased by one
increment.

Pt_SCROLL_INCREMENT
The scrollbar has been increased by one
increment.
Pt_SCROLL_PAGE_INCREMENT
The scrollbar has been increased by one
page.
Pt_SCROLL_PAGE_DECREMENT
The scrollbar has been decreased by one
page.
Pt_SCROLL_TO_MAX
The handle part of the scrollbar has been
moved to the maximum value.
Pt_SCROLL_TO_MIN
The handle has been moved to the
minimum value.
Pt_SCROLL_DRAGGED
The handle is being dragged.
Pt_SCROLL_RELEASED
The handle part has been released after
having been dragged.
Pt_SCROLL_SET The position of the handle was changed
by a call to PtSetResources(), and the
widget has the Pt_CALLBACKS_ACTIVE
bit set in its Pt_ARG_FLAGS resource.
Pt_SCROLL_JUMP You jumped to a specific location by
Ctrl-clicking on the scrollbar.
• int position — a value corresponding to the handle’s
location.

continued. . .


Pt_ARG_BANDWIDTH_THRESHOLD PtBasic Ph_BAUD_SLOW (see below)
Pt_ARG_BASIC_FLAGS PtBasic Pt_ALL_ETCHES | Pt_ALL_INLINES
Pt_ARG_COLOR PtBasic Pg_GRAY
Pt_ARG_DIM PtWidget
Pt_ARG_FILL_COLOR PtBasic Pg_MGRAY
Pt_ARG_FILL_PATTERN PtBasic Pg_PAT_DIAGF8
Pt_ARG_FLAGS PtWidget |=Pt_GETS_FOCUS|
Pt_HIGHLIGHTED|
Pt_SET|
Pt_SELECTABLE|
Pt_SELECT_NOREDRAW
Pt_ARG_GAUGE_FLAGS PtGauge ˜Pt_GAUGE_HORIZONTAL
Pt_ARG_GAUGE_FONT PtGauge Not used by this class.
Pt_ARG_GAUGE_H_ALIGN PtGauge Not used by this class.
Pt_ARG_GAUGE_V_ALIGN PtGauge Not used by this class.
Pt_ARG_GAUGE_VALUE_PREFIX PtGauge Not used by this class.
Pt_ARG_GAUGE_VALUE_SUFFIX PtGauge Not used by this class.
continued. . .


Pt_ARG_MAXIMUM PtGauge 19
Pt_ARG_MINIMUM PtGauge 0
Pt_ARG_ORIENTATION PtGauge Pt_VERTICAL
Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
continued. . .


Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
The threshold value for graphics bandwidth (as reported by PtQuerySystemInfo()) that
defines a slow connection.

PtScrollContainer © 2010, QNX Software Systems GmbH & Co. KG.
A viewport for viewing a large virtual container
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtScrollArea →
PtScrollContainer
PhAB icon:
Public header:
<photon/PtScrollContainer.h>
Description:
A PtScrollContainer widget combines one or more scrollbar widgets and an area
that provides a viewport onto a virtual display area. The virtual display area is a
container for other widgets. Typically, the virtual area is larger than the viewing area;
the scrollbar widgets let you bring any part of the virtual area into view.
A PtScrollContainer widget acts as a viewport.
If the virtual area’s size is significantly greater than that of the viewport (such as when
a large textual document is being viewed), it’s usually impractical in terms of
performance and memory to use a scrolling area. This is because the widget for the
virtual area keeps the entire contents of the object in memory and always renders the
entire object, most of which gets clipped. In these cases, you should consider creating
your own subclass of PtScrollArea to manage only the portion of the virtual area
that’s displayed.
Anchors and resize policy

Anchors between a scrollable area and its parent affect the scrollable area’s visible
area.
Children of the scrollable area are anchored to its virtual area.
The scrollable area’s Pt_ARG_SCROLLCONT_RESIZE_FLAGS specify the resize
policy that’s applied to its virtual area. You can set the virtual area’s size directly by

© 2010, QNX Software Systems GmbH & Co. KG. PtScrollContainer
modifying the resources associated with it. Otherwise, the area changes only under the
following conditions:
• The Pt_AUTO_EXTENT flag is set.
OR
• The scrollable area’s resize policy is set to allow it to resize in response to a change
in its contents (i.e. any of its children change)
AND
• one of its children changes size, as a result of its resize policy or a programmatic
change
AND
• you call PtExtentWidget() on the scrollable area after the change.
Other layouts are possible by making another container, such as a group widget, a
child of the scrollable area.
New resources:

Pt_ARG_SCROLLCONT_FLAGS uint16_t Flag Pt_SCROLLCONT_TRACK_FOCUS
Pt_ARG_SCROLLCONT_RESIZE_FLAGS long Flag Pt_RESIZE_XY_AS_REQUIRED
Pt_ARG_SCROLLCONT_FLAGS
uint16_t Flag Pt_SCROLLCONT_TRACK_FOCUS
Flags that control the appearance and behavior of the widget. The defined bits include:
Pt_SCROLLCONT_TRACK_FOCUS
Pan to accommodate the focused child as focus changes.
Pt_ARG_SCROLLCONT_RESIZE_FLAGS
long Flag Pt_RESIZE_XY_AS_REQUIRED
Flags that control the resizing of the virtual area. The defined bits are the same as
those defined for Pt_ARG_RESIZE_FLAGS:

• Pt_RESIZE_X_AS_REQUIRED
• Pt_RESIZE_X_ALWAYS
• Pt_RESIZE_X_INITIAL
• Pt_RESIZE_X_BITS
• Pt_RESIZE_Y_AS_REQUIRED
• Pt_RESIZE_Y_ALWAYS
• Pt_RESIZE_Y_INITIAL
• Pt_RESIZE_Y_BITS
• Pt_RESIZE_XY_ALWAYS
• Pt_RESIZE_XY_AS_REQUIRED
• Pt_RESIZE_XY_INITIAL
• Pt_RESIZE_XY_BITS

Pt_ARG_ANCHOR_FLAGS PtWidget Pt_RIGHT_ANCHORED_LEFT|
continued. . .


Pt_ARG_DIM PtWidget
Pt_ARG_FLAGS PtWidget |=Pt_GETS_FOCUS|
Pt_HIGHLIGHTED|
Pt_SET
continued. . .


Pt_ARG_POS PtWidget
Pt_ARG_SCROLLAREA_FLAGS PtScrollArea
Pt_ARG_SCROLLAREA_INCREMENT_X PtScrollArea
Pt_ARG_SCROLLAREA_INCREMENT_Y PtScrollArea
Pt_ARG_SCROLLAREA_MAX_X PtScrollArea
Pt_ARG_SCROLLAREA_MAX_Y PtScrollArea
Pt_ARG_SCROLLAREA_POS_X PtScrollArea
Pt_ARG_SCROLLAREA_POS_Y PtScrollArea
Pt_ARG_SCROLLAREA_SCROLLBAR_COLOR PtScrollArea
Pt_ARG_SCROLLBAR_X_DISPLAY PtScrollArea
Pt_ARG_SCROLLBAR_X_HEIGHT PtScrollArea
Pt_ARG_SCROLLBAR_Y_DISPLAY PtScrollArea
Pt_ARG_SCROLLBAR_Y_WIDTH PtScrollArea
Pt_CB_ARM PtBasic
continued. . .


Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
Pt_CB_SCROLLAREA_SCROLLED PtScrollArea

PtSeparator © 2010, QNX Software Systems GmbH & Co. KG.
Separator for organizing widgets
Class hierarchy:
PtWidget → PtBasic → PtSeparator
PhAB icon:
Public header:
<photon/PtSeparator.h>
Description:
PtSeparator provides a separator line with various styles. You should find it handy
when creating menus, or for organizing areas that hold a lot of widgets.
PtSeparator widgets, as used to organize the items in a menu.
New resources:

Pt_ARG_SEP_ARM_BITMAP_CURSOR PhBitmapCursorDescription_t * Alloc NULL
Pt_ARG_SEP_ARM_CURSOR_COLOR PgColor_t Scalar Ph_CURSOR_ DEFAULT_COLOR
Pt_ARG_SEP_ARM_CURSOR_TYPE unsigned short Scalar Ph_CURSOR_ INHERIT
Pt_ARG_SEP_DRAG_BOUNDS PhRect_t Struct NULL
Pt_ARG_SEP_FLAGS short Flag Pt_SEP_ HORIZONTAL
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtSeparator

Pt_ARG_SEP_IMAGE PhImage_t * Image NULL
Pt_ARG_SEP_IMAGE_H_ALIGN unsigned char Scalar Pt_LEFT
Pt_ARG_SEP_IMAGE_V_ALIGN unsigned char Scalar Pt_TOP
Pt_ARG_SEP_TYPE unsigned short Scalar Pt_SINGLE_ LINE
Pt_CB_SEP_DRAG PtCallback_t * Link NULL
Pt_ARG_SEP_ARM_BITMAP_CURSOR
PhBitmapCursorDescription_t * Alloc NULL
A pointer to a PhBitmapCursorDescription_t, which represents the cursor which

is used when the separator is armed and being dragged.
The widget automatically sets the hdr member of the
PhBitmapCursorDescription_t and PhBitmapCursorData_t structures.
The PhBitmapCursorDescription_t contains at least these members:
hdr A PhCursorDescription_t structure that is automatically filled in by the

widget.
bmp A PhBitmapCursorData_t structure that describes the bitmap.
The PhCharacterCursorDescription_t contains at least these members:
hdr A PhCursorDescription_t structure.
color A PgColor_t structure that describes the background colour of the bitmap.
The PhBitmapCursorData_t contains at least these members:
hdr A pointer to a PhRegionDataHdr_t structure that defines the

region data header.
size1 The dimensions of the first bitmap plane, in pixels.
offset1 The position of the upper-left corner of the first plane of the bitmap,
relative to the hot spot.
color1 The color of the first bitmap plane.

bytesperline1 The number of bytes per line for the first bitmap plane.
size2 The dimensions of the second bitmap plane, in pixels.
offset2 The position of the upper-left corner of the second plane of the
bitmap, relative to the hot spot.
color2 The color of the second bitplane. You can have more than two
bitplanes.
bytesperline2 The number of bytes per line for the second bitmap plane.
images The bitmap image data, as a series of 1-bit-per-pixel planes.
Pt_ARG_SEP_ARM_CURSOR_COLOR
PgColor_t Scalar Ph_CURSOR_DEFAULT_COLOR
A PgColor_t structure that defines the color for the cursor specified by the
Pt_ARG_SEP_ARM_CURSOR_TYPE, which is used when the separator is armed
and being dragged. For more information, see PgColor_t in the Photon Library
Reference.
Pt_ARG_SEP_ARM_CURSOR_TYPE
unsigned short Scalar Ph_CURSOR_INHERIT
The cursor type which is used when the separator is armed and being dragged. It can
be:
Ph_CURSOR_INHERIT
Inherit the cursor, not from the class hierarchy, but from the family hierarchy;
that is, from the way your application nests the widgets. The cursor might even
be inherited from the Photon server itself.
Ph_CURSOR_BITMAP
Use the bitmap stored in Pt_ARG_SETP_ARM_BITMAP_CURSOR for the
cursor.
Pt_ARG_SEP_DRAG_BOUNDS
PhRect_t Struct NULL

The dragging boundary for the separator. This resource is used when dragging is
initiated (see the Pt_SEP_DRAGGABLE flag). The default of this resource is the
widget’s parent’s canvas. Set the resource to NULL to use the defaults.
Pt_ARG_SEP_FLAGS
short Flag Pt_SEP_HORIZONTAL
Flags that control the separator’s appearance. Possible values:
Pt_SEP_ORIENTATION
If this bit is Pt_SEP_VERTICAL, the separator is vertical. If this bit is
Pt_SEP_HORIZONTAL, the separator is horizontal.
Pt_SEP_DRAGGABLE
The separator can be dragged within its parent’s canvas, or by the bounding
rectangle specified by via tthe Pt_SEP_DRAG_BOUNDS resource.
Pt_SEP_DRAW_DRAG_BAND
Enable rubber band drawing while dragging the widget.
Pt_ARG_SEP_IMAGE
PhImage_t Image NULL
You can use this resource to create your own style of separator. It specifies an image to
be used as the separator. Set to NULL to disable image drawing. For more information
about PhImage_t, see the Photon Library Reference.
Pt_ARG_SEP_IMAGE_H_ALIGN
unsigned char scalar Pt_LEFT
The separator’s horizontal image alignment. Can be one of:
• Pt_LEFT
• Pt_CENTER
• Pt_RIGHT

Pt_ARG_SEP_IMAGE_V_ALIGN

unsigned char scalar Pt_TOP
The separator’s vertical image alignment. Can be one of:
• Pt_TOP
• Pt_CENTER
• Pt_BOTTOM
Pt_ARG_SEP_TYPE
unsigned short Scalar Pt_SINGLE_LINE
The type of separator. Possible values:
• Pt_SINGLE_LINE
• Pt_DOUBLE_LINE
• Pt_SINGLE_DASH_LINE
• Pt_DOUBLE_DASH_LINE
• Pt_ETCHED_IN
• Pt_ETCHED_OUT
• Pt_NOLINE
Pt_CB_SEP_DRAG
A list of PtCallback_t structures that define the callbacks involved when you drag the
separator widget.
following members:
reason Pt_CB_SEP_DRAG

• Pt_INIT — the separator was armed

• Pt_MOVED — the separator was dragged
• Pt_DONE — the separator was disarmed; look the
PhDragEvent_t structure of the event member to find out
more details.

cbdata A pointer to a PtSeparatorCallback_t structure which

contains at least contains PhRect_t, a separator rectangle
relative to its parent.

Pt_ARG_BANDWIDTH_THRESHOLD PtBasic See below.
Pt_ARG_DIM PtWidget
continued. . .


Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
continued. . .


Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
Pt_ARG_BANDWIDTH_THRESHOLD defines the "graphics bandwidth" threshold
over which the separator drag mode is switched to drag outline mode, as if the
Pt_SEP_DRAW_DRAG_BAND flag was set. This optimizes the number of events in
low bandwidth situations, such as when you are using phrelay. Note that this
resource only applies when the separator is draggable.
By default this resource is set to Ph_BAUD_NETWORK.
For more information about the system bandwidth, see PtQuerySystemInfo() and
PhSysInfo_t in the Photon Library Reference.

PtServer © 2010, QNX Software Systems GmbH & Co. KG.
Server widget
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtRegion → PtServer
PhAB icon:
None — instantiate it by calling PtCreateWidget().
Public header:
<photon/PtServer.h>
Description:
PtClient and PtServer allow one process (the “server”) to display widgets in a
window that belongs to another process (the “client”).
PtClient and PtServer use a Photon connection to communicate (see
“Connections” in the Interprocess Communications chapter of the Photon
Programmer’s Guide), but they have a few resources that in most cases let applications
avoid dealing with connection objects directly.
A PtServer widget displays its contents inside the PtClient it’s attached to. The
contents can be any widgets you choose to put in your PtServer widget.
Additionally, PtServer lets your application send arbitrary messages to the client
process.
When a PtServer is attached to a PtClient, it’s the client that decides what size
your server should be and when it should be realized, unrealized, and destroyed.
Don’t try to resize, realize, unrealize, or destroy a PtServer widget that’s connected
to a client. Don’t exit from an application that has active PtServer widgets. If you
need to do any of those things, you should do it by sending a message to ask the client
to do the appropriate action on its PtClient widget instead.
New resources:

Pt_ARG_SERVER_CONNECTION PtConnectionServer_t * Pointer NULL
Pt_ARG_SERVER_NAME char * String NULL
Pt_ARG_SERVER_SEND char, int Array (write only)
Pt_CB_SERVER_CONNECTED PtCallback_t * Link NULL
Pt_CB_SERVER_ERROR PtCallback_t * Link NULL
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtServer

Pt_CB_SERVER_RECEIVE PtCallback_t * Link NULL
Pt_CB_SERVER_TRANSPORT PtCallback_t * Link NULL
Pt_ARG_SERVER_CONNECTION
PtConnectionServer_t * Pointer NULL
A pointer to the connection object used for communicating to the PtClient. If you
get the value of this resource, don’t use this pointer for anything other than checking to
see if it’s NULL.
You can set this resource, provided that the widget isn’t connected to a client yet. This
is useful in a server application that has a connector that multiple clients can connect
to. This kind of server has a connector callback that creates a PtServer widget and
gives the new connection object to its Pt_ARG_SERVER_CONNECTION resource
(see PtConnectorCreate() in the Photon Library Reference for more details about
connectors).
In a server that just creates one PtServer widget, the Pt_ARG_SERVER_NAME
resource is a simpler way of connecting to a client.
Pt_ARG_SERVER_NAME
char * String NULL
When you set this resource, the widget creates a connector and lets a client connect to
it. After the client has connected, the connector is automatically destroyed.
Pt_ARG_SERVER_SEND (write only)

char, int Array
When you set this resource, the widget sends the given message to the client
PtClient that invokes the Pt_CB_CLIENT_EVENT callback.
Pt_CB_SERVER_CONNECTED

A list of PtCallback_t structures that define the callbacks invoked when a client
connects to the widget.
following members:
reason Pt_CB_SERVER_CONNECTED
event NULL (not used).
cbdata NULL.
Pt_CB_SERVER_ERROR
A list of PtCallback_t structures that define the callbacks that are invoked when an
error occurs.
following members:
reason Pt_CB_SERVER_ERROR

cbdata A pointer to a PtServerErrorCallback_t structure that
contains at least:
• int action — the value that the PtConnectionServer error
handler will return. It’s initialized to Pt_END. Set it to
Pt_CONTINUE to retry the failed operation.
Not all operations are retried if an error handler returns Pt_CONTINUE. For example, a
MsgReply() is never retried.
• int errnum — the errno value from the error handler.

• int where — the value (of type enum
PtConnectionServerError) that describes what operation
failed.

If this value is Pt_CONNECTION_SERVER_BROKEN, the widget is destroyed after the

callback returns.
Pt_CB_SERVER_RECEIVE
server receives a message sent by the client’s Pt_ARG_CLIENT_SEND resource.
following members:
reason Pt_CB_SERVER_RECEIVE

cbdata A pointer to a PtServerCallback_t structure that contains at

least:
• void const *message — the message from the client.
• unsigned msg_len — its length, in bytes.
• void *reply — set this to point to your reply buffer.
• unsigned reply_len — put its length here.
Pt_CB_SERVER_TRANSPORT
PtClient that the PtServer is attached to is realized in a Photon session different
from the one that the server is connected to. This can happen when the client is being
transported to a different Photon.
following members:

reason Pt_CB_SERVER_TRANSPORT

cbdata A pointer to the pathname of the new Photon device.

Pt_ARG_DIM PtWidget
continued. . .


Pt_ARG_POS PtWidget
Pt_ARG_REGION_FIELDS PtRegion 0x00000018
Pt_ARG_REGION_FLAGS PtRegion
Pt_ARG_REGION_INFRONT PtRegion
Pt_ARG_REGION_INPUT_GROUP PtRegion
continued. . .


Pt_ARG_REGION_OPAQUE PtRegion 0x00210EF8
Pt_ARG_REGION_PARENT PtRegion
Pt_ARG_REGION_SENSE PtRegion 0x00290240
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
continued. . .


Pt_CB_RAW PtWidget

PtSlider © 2010, QNX Software Systems GmbH & Co. KG.
A widget for choosing a value from a range
Class hierarchy:
PtWidget → PtBasic → PtGauge → PtSlider
PhAB icon:
Public header:
<photon/PtSlider.h>
Description:
A PtSlider widget lets you choose numerical values within a specified range from
minimum to maximum.
A PtSlider widget.
A slider consists of a narrow trough (representing the total range), a movable handle,
and optional tick marks. The handle — which appears on top of the trough —
represents the current position within the range. You can specify the size of the handle
by setting Pt_ARG_SLIDER_HANDLE_WIDTH.
If you want to create your own style of slider, you can specify:
• Pt_ARG_SLIDER_IMAGE to replace the default handle
• Pt_ARG_SLIDER_TROUGH_IMAGE1 and
Pt_ARG_SLIDER_TROUGH_IMAGE2 to replace the default trough.
A PtSlider widget with a custom handle and trough.
You need to set Pt_ARG_SLIDER_FLAGS appropriately to use these images.
Mouse actions
When you press the mouse button, the result depends on the location of the pointer.

© 2010, QNX Software Systems GmbH & Co. KG. PtSlider
If the pointer is: Then:

In the trough The handle moves up or down one slider multiple
On the handle A drag is started
If you hold down the Ctrl key and click in the trough, the handle jumps to the position
of the pointer.
Keyboard actions
If you press: The handle moves:

↑ Up one increment
↓ Down one increment
→ Right one increment
← Left one increment
Pg Up Up/right one “page”
Pg Down Down/left one “page”
Home To the minimum value
End To the maximum value
where:
• The size of a “page” is determined by the Pt_ARG_SLIDER_MULTIPLE resource.
• The locations of the minimum and maximum value depend on the

Pt_ARG_ORIENTATION and Pt_ARG_GAUGE_FLAGS resources inherited from
PtGauge.
New resources:

Pt_ARG_SLIDER_FLAGS short int Flag 0
Pt_ARG_SLIDER_HANDLE_COLOR PgColor_t Scalar PgGrey(217)
Pt_ARG_SLIDER_HANDLE_WIDTH short int Scalar 15
Pt_ARG_SLIDER_IMAGE PhImage_t * Image NULL
continued. . .


Pt_ARG_SLIDER_INCREMENT unsigned short Scalar 1
Pt_ARG_SLIDER_MULTIPLE unsigned short Scalar 10
Pt_ARG_SLIDER_TICK_MAJOR_DIV unsigned long Scalar 10
Pt_ARG_SLIDER_TROUGH_IMAGE1 PhImage_t * Image NULL
Pt_ARG_SLIDER_TROUGH_IMAGE2 PhImage_t * Image NULL
Pt_CB_SLIDER_MOVE PtCallback_t * Link NULL
Pt_ARG_SLIDER_FLAGS
short int Flag 0
Valid flags:
Pt_SLIDER_IMAGE
Use the image specified by Pt_ARG_SLIDER_IMAGE as the slider handle.
Pt_SLIDER_TROUGH_IMAGE
Use the images specified by Pt_ARG_SLIDER_TROUGH_IMAGE1 and
Pt_ARG_SLIDER_TROUGH_IMAGE2 as the trough.
Pt_ARG_SLIDER_HANDLE_COLOR
PgColor_t Scalar PgGrey(217)
The color of the slider handle. See PgColor_t in the Photon Library Reference.
Pt_ARG_SLIDER_HANDLE_WIDTH
short int Scalar 15
The width of the slider handle.
Pt_ARG_SLIDER_IMAGE

You can use this resource to create your own style of slider. It specifies an image to be
used as the slider’s handle. For more information about the PhImage_t structure, see
The widget ignores this resource unless you set Pt_SLIDER_IMAGE in

Pt_ARG_SLIDER_FLAGS.
Pt_ARG_SLIDER_INCREMENT
The slider increment when you press the cursor keys.
Pt_ARG_SLIDER_MULTIPLE
The slider increment when you click the pointer button in the trough, or you press Pg
Up or Pg Down.
Pt_ARG_SLIDER_TICK_MAJOR_DIV
The number of major divisions.
Pt_ARG_SLIDER_TROUGH_IMAGE1, Pt_ARG_SLIDER_TROUGH_IMAGE2
You can use these resources to create your own style of slider. Use them to specify the
images to be displayed as the trough. The slider becomes the same size as
Pt_ARG_SLIDER_TROUGH_IMAGE1.
The widget ignores these resources unless you set Pt_SLIDER_TROUGH_IMAGE in

Pt_ARG_SLIDER_FLAGS.
If you specify just Pt_ARG_SLIDER_TROUGH_IMAGE1, it’s used as the

background for the entire slider.

If you specify both images:

• Pt_ARG_SLIDER_TROUGH_IMAGE1 is displayed from the minimum value of
the slider to the current handle position.
• Pt_ARG_SLIDER_TROUGH_IMAGE2 is displayed from the current handle

position to the maximum value.
If the image specified by Pt_ARG_SLIDER_TROUGH_IMAGE2 is a different size

than the one specified by Pt_ARG_SLIDER_TROUGH_IMAGE1, you should use a
non-transparent color to avoid drawing artifacts when the handle position changes.
By default, the maximum value is on the right side of a horizontal slider. The widget
displays the first image to the left of the handle, and the second image to the right. If
you set Pt_GAUGE_MAX_ON_LEFT in the Pt_ARG_GAUGE_FLAGS resource
(inherited from PtGauge), the widget displays the first image to the right of the
handle, and the second image to the left.
You get similar results with a vertical slider if you set Pt_GAUGE_MAX_ON_TOP.
The images aren’t rotated if you change the slider’s Pt_ARG_ORIENTATION

resource (inherited from PtGauge). You should create horizontal images for a
horizontal slider, and vertical images for a vertical slider.
For more information about the PhImage_t structure, see the Photon Library
Reference.
Pt_CB_SLIDER_MOVE
A list of PtCallback_t structures that define the callbacks that the slider invokes
when the handle position changes.
resource, these callbacks are also invoked when your application changes the handle
position by calling PtSetResource() or PtSetResources().
following members:
reason Pt_CB_SLIDER_MOVE

• 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

cbdata A pointer to a PtSliderCallback_t structure that contains at

least the following member:
int position; A value corresponding to the slider handle’s

location.

Pt_ARG_COLOR PtBasic Pg_GRAY
continued. . .


Pt_ARG_DIM PtWidget
Pt_ARG_FLAGS PtWidget |=Pt_GETS_FOCUS
Pt_ARG_GAUGE_FLAGS PtGauge |= Pt_GAUGE_MAX_ON_TOP
Pt_ARG_GAUGE_FONT PtGauge
Pt_ARG_GAUGE_H_ALIGN PtGauge Not used by this class.
Pt_ARG_GAUGE_V_ALIGN PtGauge Not used by this class.
Pt_ARG_GAUGE_VALUE_PREFIX PtGauge Not used by this class.
Pt_ARG_GAUGE_VALUE_SUFFIX PtGauge Not used by this class.
Pt_ARG_MAXIMUM PtGauge
continued. . .


Pt_ARG_MINIMUM PtGauge
Pt_ARG_ORIENTATION PtGauge Pt_HORIZONTAL
Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

PtTab © 2010, QNX Software Systems GmbH & Co. KG.
A tab button for initiating an action
Class hierarchy:
PtWidget → PtBasic → PtLabel → PtTab
PhAB icon:
Public header:
<photon/PtTab.h>
Description:
The PtTab class draws a tab such as is found on a file folder. Clicking the tab invokes
an application callback.
A group of PtTab widgets positioned at the top of a PtPane.
Instead of using a PtTab, you should use a PtPanelGroup. This is the preferred
method, since PtPanelGroup manages all aspects of a tabbed panel for you.
If you insist on using PtTab widgets, you typically:
• Group the tabs together and set the Pt_GROUP_EXCLUSIVE bit in the PtGroup
widget’s Pt_ARG_GROUP_FLAGS resource. This flag allows only one of the tabs
to be set at a time.
• Use other PtGroup flags and resources to make the tabs the same size, aligned
horizontally, and so on. For more information, see “Aligning widgets using groups”
in the Geometry Management chapter of the Photon Programmer’s Guide.
• Place the tabs at the top of a PtPane or some other container. Use the same border
width for the tabs and the container, and line up the top of the container’s border
with the top of the bevel on the tab.
• Use PhAB’s Picture module and internal links to change the contents of the
container widget for the tabs. For more information, see the Photon Programmer’s
Guide.
New resources:

© 2010, QNX Software Systems GmbH & Co. KG. PtTab

Pt_ARG_TAB_FLAGS unsigned int Flag 0
Pt_ARG_TAB_UNSELECTED_COLOR PgColor_t Scalar PgGray(0xc0)
Pt_ARG_TAB_FLAGS
unsigned int Flag 0
Flags that affect how the widget appears. The defined bits are:
Pt_TAB_UPSIDE_DOWN
Vertically invert the tab; display the rounded corners on the
bottom of the widget instead of the top.
Pt_TAB_RIGHTSIDE_LEFT
Horizontally invert the tab.
Pt_TAB_DRAG_HANDLE
Show a textured drag handle within the tab, visually indicating
that the associated panel can be pulled away. You need to write
some code to support the dragging (PtPanelGroup supports it
already).
Pt_TAB_MULTI Indicate that this tab produces a popup panel of some sort when
pressed (the term “multi” is used since, in this case, the tab
generally represents multiple choices). You need to write some
code to this (PtPanelGroup supports it already).
Pt_ARG_TAB_UNSELECTED_COLOR
PgColor_t Scalar PgGray(0xc0)
The color of the tab when it isn’t selected (i.e. not set). See PgColor_t in the Photon
Library Reference.
When the tab is set, it gets its color from Pt_ARG_FILL_COLOR (see PtBasic).


Pt_ARG_DIM PtWidget
Pt_ARG_FILL_COLOR PtBasic PgGray(170)
Pt_ARG_FLAGS PtWidget |=Pt_CLIP_HIGHLIGHT| Pt_TOGGLE
Pt_ARG_HIGHLIGHT_ROUNDNESS PtBasic 3
continued. . .


Pt_ARG_LABEL_FLAGS PtLabel &= ˜Pt_LABEL_SELECT_SHIFT
Pt_ARG_POS PtWidget
continued. . .


Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
The PtTab widget defines the following macros that make it easier to use the tab once
it’s been created:
PtTabIsUpsideDown()
Return a nonzero value if the tab is upside down, 0 otherwise
PtTabIsRightsideUp()
Return a nonzero value if the tab is rightside up, 0 otherwise

PtTabIsRightsideLeft()
Return a nonzero value if the tab is flipped left-to-right, 0 otherwise
PtTabIsRightsideRight()
Return a nonzero value if the tab isn’t flipped left-to-right, 0
otherwise
PtTabIsDraggable()
Return a nonzero value if the panel can be dragged away, 0
otherwise
PtTabIsMulti() Return a nonzero value if the tab produces a popup panel of some
sort when pressed, 0 otherwise
PtTabDragHandleRect()
Retrieve the rectangle that encompasses the drag area of the tab

PtTerminal © 2010, QNX Software Systems GmbH & Co. KG.
A window that emulates a character-mode terminal
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtTerminal
• PtTty
PhAB icon:
Public header:
<photon/PtTerm.h>
Description:
The PtTerminal class provides a text window emulating a character terminal.
A PtTerminal widget.
You can send characters to the terminal by calling PtTerminalPutc(), PtTerminalPut()

and PtTerminalPuts(). If you type in the terminal, the keyboard input is passed to the
widget via the Pt_CB_TERM_INPUT callback.
Other convenience functions and callbacks support the following kinds of user
interaction:
• resizing the terminal window
• changing the displayed font
• scrolling
• other activities permitted through escape sequences. For information about specific
escape sequences, see devc-con in the QNX Neutrino Utilities Reference.

© 2010, QNX Software Systems GmbH & Co. KG. PtTerminal
PtTerminal uses some Ctrl-Alt combinations for cutting and pasting, changing font
sizes, and so on, but all Alt-key combinations that are defined for text mode are passed
to your text-mode application, provided that the window manager lets PtTerminal
see them.
The window manager intercepts certain Alt-key combinations unless you set
Ph_WM_STATE_ISALTKEY in the Pt_ARG_WINDOW_STATE resource of the
PtWindow that contains the PtTerminal.
PtTerminal and PtTty

The main difference between PtTerminal and PtTty is that PtTerminal doesn’t
do any I/O for you. The only way to display characters in a PtTerminal is by giving
them to one of the PtTerminalPut*() functions. Similarly, the only thing PtTerminal
does with Photon input is translate function keys into text-mode compatible escape
sequences and give the result to your Pt_CB_TERM_INPUT callback.
PtTty adds device I/O to that. The code that opens a pty, reads characters from it, and
gives those characters to PtTerminalPut() is part of PtTty. Similarly, PtTty attaches
a Pt_CB_TERM_INPUT callback that writes Photon keyboard input (translated by
PtTerminal to text-mode compatible format) to the pty.
Another responsibility of PtTty is spawning a command for you and invoking the
Pt_CB_TTY_TERMINATED callbacks when the command terminates.
Fonts
Your application program can use Pt_ARG_TERM_FONT to set an explicit font
name, or Pt_ARG_TERM_FONT_INDEX to choose a font from the list of supported
fonts, Pt_ARG_TERM_FONT_LIST.
If you set the Pt_TERM_KBFONT bit in Pt_ARG_TERM_RESIZE_FL, you can select
a font using the keyboard:
• Press Ctrl-Alt-< or Ctrl-Alt-[ to decrement the value of

Pt_ARG_TERM_FONT_INDEX by one (unless it’s already at 0) or set it to the
maximum value (if the current value is -1).
• Press Ctrl-Alt-> or Ctrl-Alt-] to increment the value of

Pt_ARG_TERM_FONT_INDEX by one (unless it’s already at the maximum
value).
The Pt_TERM_KBFORCE flag affects any resizing that occurs when the above
keychords are used:
• If this flag isn’t set, the above keystrokes simply set the
Pt_ARG_TERM_FONT_INDEX resource.
• If the flag is set, the [ and ] keys adjust the window size to keep the terminal size
(rows/columns) while the < and > keys attempt to adjust the terminal size within
the current window size.

If you’ve set the Pt_TERM_OPFONT flag, you can use escape sequences to set the font:
• If you use Pt_ARG_TERM_FONT to set the font, and the new font name is equal
to one of the names on the current font list, Pt_ARG_TERM_FONT_INDEX is set
to the index of that list item. When the Pt_ARG_TERM_FONT_LIST resource is
set, the widget also attempts to find the current font name on the list and set the
index.
• If the font list contains an invalid font name, you can set
Pt_ARG_TERM_FONT_INDEX to its index, but the current font isn’t changed.
Character sets
PtTerminal uses two 8-bit character sets:
Internal character set

What the widget uses to store characters internally. This character set is also
used in QNX mode as the “text-mode character set” (i.e. anything that you pass
to PtTerminalPut() is assumed to use this character set, and Photon key events
get translated to this character set before being passed to the
Pt_CB_TERM_INPUT callback).
In ANSI mode, the internal character set can be used for the display by setting
one of the G0...G3 character sets to “the PC character set.” The escape
sequences that do it are:
ESC ( U
ESC ) U
ESC * U
ESC + U
See the documentation for devc-con in the QNX Neutrino Utilities Reference.
ANSI character set
What’s used in ANSI mode. It’s the default setting for the G2 character set
(which is used by default for characters above 0x9F). It’s also the character set
to which Photon key events get translated in the ANSI mode.
By default, the internal character set is the PC character set (“IBM code page 437”)
and the ANSI character set is ISO 8859-1. PtTerminal lets you choose any 8-bit
character sets — the only requirement is that they must be supersets of ASCII:
PtTerminal translates only codes above 0x7F.
By default, PtTerminal assumes that the Photon font used for the display is encoded
using the internal character set (in particular, all the terminal fonts shipped with
Photon use the PC character set rather than Unicode). Your application can define an
additional mapping; for example, you can use a Unicode font to display any character
sets in PtTerminal.
The Pt_ARG_TERM_CHARSETS resource stores the current character sets.

Resource changes and function reentrancy

When the PtTerminalPut*() functions parse the output stream, certain escape
sequences contained in the stream may cause resource changes that invoke callback
functions. The callback functions shouldn’t call any of the PtTerminalPut*() functions
to output text to the same terminal widget that invoked the callback because the
protocol engine function isn’t reentrant. Recursion is allowed, but only when each of
the nested calls outputs data to a different terminal widget. Otherwise, the
PtTerminalPut*() functions return -1 to indicate an illegal call.
Geometry
The groups of resources that affect a terminal widget’s geometry are:
Dimensions Pt_ARG_DIM and Pt_ARG_AREA (see PtWidget)
Margins Pt_ARG_MARGIN_HEIGHT, Pt_ARG_MARGIN_WIDTH (see

PtBasic), and Pt_ARG_TERM_MARGINS
Terminal size Pt_ARG_TERM_SIZE, Pt_ARG_TERM_ROWS, and

Pt_ARG_TERM_COLS
Font Pt_ARG_TERM_FONT and Pt_ARG_TERM_FONT_INDEX
Resizing
A widget’s dimensions can be calculated as long as terminal size, font size, and
margins are known. Thus, whenever one of these resources is changed, another
resource — or sometimes even two resources — must be adjusted too.
The return value of the function attached to the Pt_ARG_TERM_RESIZE_FUN
resource (known as the resize function) determines how the widget is resized. The
function is called with two output arguments: the first is a pointer to a string that
describes which resource is changing and how, and the second is the value of widget’s
Pt_ARG_TERM_RESIZE_STR resource.
Each character in the string has a specific meaning. The first character is a resource
identifier that describes which resource is changing:
D (dimension) Change Pt_ARG_DIM and Pt_ARG_AREA.
M (margin) Change Pt_ARG_MARGIN_WIDTH and

Pt_ARG_MARGIN_HEIGHT.
S (size) Change Pt_ARG_TERM_SIZE, Pt_ARG_TERM_ROWS, and

Pt_ARG_TERM_COLS.
F (font) Change Pt_ARG_TERM_FONT.

The next series of characters provide the details, starting with the character x or y to
specify direction (horizontal or vertical). The next character can be one of the
following:
Character Meaning
- The value is decreasing.
+ The value is increasing.
= The value didn’t change (used only when the size or margin is
changing).
Additional characters can be given to indicate resources that aren’t sufficient alone to
adjust the widget because these resources have limited values. An m means that the
adjustment must involve a resource other than the margins, and an s means that the
adjustment must involve a resource other than the terminal size.
Adjusting after a resize
The result of the “resize function” is a string specifying the order of the resources used
in the adjustment process. The adjustment can be performed in both directions, but if
the original resource change doesn’t affect horizontal or vertical dimensions, only the
affected direction is adjusted.
The resize function may either return a static string or use the buffer passed in the first
argument. The buffer size is at least 10 bytes. A NULL pointer is equivalent to an
empty string.
Each character in the adjustment string has a specific meaning:
x Perform a horizontal adjustment on the following characters.
y Perform a vertical adjustment on the following characters.
d Adjust the Pt_ARG_DIM resource.
s Adjust the Pt_ARG_TERM_SIZE resource.
m Adjust the Pt_ARG_MARGIN_WIDTH and/or Pt_ARG_MARGIN_HEIGHT

resource and copy the new value to the Pt_ARG_TERM_MARGINS resource.
M Adjust the Pt_ARG_TERM_MARGINS resource.
For example, xsym adjusts the number of columns (xs) and the margin height (ym).
Before any adjustments specified by the string are done, Pt_ARG_TERM_MARGINS
is reset to the values of Pt_ARG_MARGIN_HEIGHT and/or
Pt_ARG_MARGIN_WIDTH.

Adjusting the dimension is always successful, while adjusting the size or margin isn’t
always sufficient — size is limited and must be a multiple of the font size, and margin
must be nonnegative.
After the adjustments specified by the string are done, the dimension is adjusted to
make sure that the new values are coherent. Thus, specifying a d is always superfluous
and specifying anything after a d has no effect unless it specifies a different direction.
The default resize function
The default function uses only the resource identifier (i.e. D, M, S or F) given in the
first argument. The function assumes that the Pt_ARG_TERM_RESIZE_STR resource
string given in the second argument consists of segments delimited by colons.
Each of the segments consists of a list of letters that define resources, an equality
symbol (=), and the string that’s returned if the resource identifier matches one of the
letters in the list.
The default value of the Pt_ARG_TERM_RESIZE_STR resource is D=sM:M=s, which
means:
• If the dimension has changed (D), sM is returned. The size and margin of the widget
are adjusted. If the sizes couldn’t be matched (that is, the new dimensions are
smaller than the minimum size), the dimension is readjusted.
• If a margin is changed (M), s is returned, and the widget attempts to adjust the
appropriate size component (rows or columns), after which the dimension is
adjusted to fit the exact margin width or height.
• If font (F) or size (S) is changed, the corresponding resource identifier isn’t found
on the default list and an empty string is returned. The terminal’s margin is set
according to the margin width and height resources, and then the dimension is
recalculated.
Size limits
Other resources that may affect geometry are the size limits:
• Pt_ARG_TERM_MINSIZE
• Pt_ARG_TERM_MINROWS
• Pt_ARG_TERM_MINCOLS
• Pt_ARG_TERM_MAXSIZE
• Pt_ARG_TERM_MAXROWS
• Pt_ARG_TERM_MAXCOLS
When a limit is being set to a value that makes the current size invalid, the current size
is adjusted. If a minimum is set to a value larger than the corresponding maximum,
then both the maximum and the current size are also set to this value.

The opposite is also true: if a maximum is changed, the corresponding minimum may
be adjusted. This means that if you want to set the limits and size to arbitrary values
regardless of their current values, you should set the limits before the size.
The minimum size (together with font and margins) determines also minimal values
for the Pt_ARG_DIM resource. There’s no upper limit for the dimensions because
there’s no upper limit for Pt_ARG_TERM_MARGINS.
Console emulation
A PtSetResources() call for the Pt_ARG_TERM_CONSOLE writes data directly to
the widget’s screen buffer.
First, your application should fill a PtTerminalConsoleWrite_t structure:
void const *buffer

A pointer to the data to be written.
unsigned short offset
The offset into the widget’s screen buffer at which to write the data.
unsigned short nbytes
The number of bytes to write.
Pass a pointer to the structure as the second argument to PtSetArg(). When you call
PtSetResources(), the widget transfers the actual screen data from the buffer given by
the application to the widget’s screen buffer. Then the corresponding area of the
widget is damaged in order to display the new data. PtSetResources() doesn’t check to
see if the offset and length given by your application exceed the size of the buffer.
If you call PtGetResources() to get Pt_ARG_TERM_CONSOLE, you’re given a
pointer to the buffer. If your application wishes to get the contents of a specific
fragment of the screen, it must calculate the offset to the desired position in the buffer
and copy the data.
Color coding
The Pt_ARG_TERM_COLOR_TABLE resource is an array used by the widget for
mapping color numbers into Photon PgColor_t color values (see the Photon Library
Reference). Color numbers are indexes into this array. The default array has 16
elements corresponding to 16 standard CGA colors.
Pt_ARG_FILL_COLOR (see PtBasic) defines the color of the margins.
The background color of the terminal defaults to black — or whatever the
Pt_ARG_TERM_COLOR_TABLE resource defines as entry 0. If you want a different
background color, you can either change the color table or set the background color by
sending appropriate escape sequences to the terminal using PtTerminalPut(). The
latter is probably safer if the widget is a PtTty that will be running arbitrary programs
in it; programs that use color might look odd if the colors in the color table differ too
much from the default values.

Drawing and scrolling

The Pt_ARG_TERM_DRAW_MODES resource defines the widget’s scrolling
capability.
Scrolling optimization
If your application gives characters to PtTerminalPut() in a large portion that consists

of many lines that scroll through the terminal, the widget may attempt to optimize
drawing speed.
Instead of blitting h-1 lines (where h is the height of the terminal in lines) and drawing
the bottom line on each scroll, the widget blits h-n lines (if h-n is positive) and draws
min(h,n) lines every n scrolls.
The limit for the actual value of n is determined by
Pt_ARG_BANDWIDTH_THRESHOLD (see PtBasic), Pt_ARG_TERM_SCROLL,
and Pt_ARG_TERM_DRAW_MODES, and by the current graphics bandwidth (see
PhQuerySystemInfo() in the Photon Library Reference). If the connection is slow and
the Pt_TERM_SCROLL_NOSPEEDCHK bit in Pt_ARG_TERM_CURSOR_FLAGS is
clear, there’s no limit for n. Otherwise, the maximal value of n is the value of the
Pt_ARG_TERM_SCROLL resource.
Drag and Drop

New resources:

Pt_ARG_TERM_ANSI_PROTOCOL int Boolean 1
Pt_ARG_TERM_APP PtTerminalAppState_t Struct See below
Pt_ARG_TERM_CHARSETS PtTerminalCsXlatData_t * Pointer See below
Pt_ARG_TERM_COLOR_MODE PtTerminalColorMode_t Struct Pt_TERM_COLOR_MODE
Pt_ARG_TERM_COLOR_TABLE PgColor_t, short Array CGA colors, 16

Pt_ARG_TERM_COLS short Scalar 80
Pt_ARG_TERM_CONSOLE PtTerminalConsoleWrite_t Complex N/A
Pt_ARG_TERM_CUR_COL short Scalar 0
Pt_ARG_TERM_CUR_POS PtTerminalRowCol_t Struct 0, 0
continued. . .


Pt_ARG_TERM_CUR_ROW short Scalar 0
Pt_ARG_TERM_CURSOR_FLAGS short Flag Pt_TERM_CURSOR_ON_FOCUS
Pt_ARG_TERM_DRAW_MODES unsigned char Flag Pt_TERM_SCROLL_RFSH
Pt_ARG_TERM_FONT char * String "pcterm14"

Pt_ARG_TERM_FONT_INDEX short Scalar -1
Pt_ARG_TERM_FONT_LIST char *, short Array NULL, 0
Pt_ARG_TERM_FONT_SIZE PhDim_t Struct Size of default font (read-only)
Pt_ARG_TERM_MARGINS PhRect_t Struct 0, 0, 0, 0 (read-only)
Pt_ARG_TERM_MAXCOLS short Scalar 1000
Pt_ARG_TERM_MAXROWS short Scalar 1000
Pt_ARG_TERM_MAXSIZE PtTerminalRowCol_t Struct 1000, 1000
Pt_ARG_TERM_MINCOLS short Scalar 1
Pt_ARG_TERM_MINROWS short Scalar 1
Pt_ARG_TERM_MINSIZE PtTerminalRowCol_t Struct 1, 1
Pt_ARG_TERM_OPTIONS unsigned long Flag 0x84380
Pt_ARG_TERM_OPTMASK unsigned long Flag ˜0uL
Pt_ARG_TERM_RESIZE_FL unsigned short Flag All defined flags
Pt_ARG_TERM_RESIZE_FUN See below Pointer Pointer to static function
Pt_ARG_TERM_RESIZE_STR char * String "DF=sM:M=s"
Pt_ARG_TERM_ROWS short Scalar 25
Pt_ARG_TERM_SCRLBK_COUNT short Scalar 0
Pt_ARG_TERM_SCRLBK_LIMIT short Scalar 0
Pt_ARG_TERM_SCRLBK_POS short Scalar 0
Pt_ARG_TERM_SCROLL short Scalar Pt_TERM_MAX_ROWS
Pt_ARG_TERM_SELECTION PtTerminalSelection_t Struct 0

Pt_ARG_TERM_SIZE PtTerminalRowCol_t Struct 25, 80
Pt_ARG_TERM_VISUAL_BELL short Scalar 20
Pt_CB_TERM_APP PtCallback_t * Link NULL
Pt_CB_TERM_FONT PtCallback_t * Link NULL
continued. . .


Pt_CB_TERM_INPUT PtCallback_t * Link NULL
Pt_CB_TERM_OPTIONS PtCallback_t * Link NULL
Pt_CB_TERM_RESIZE PtCallback_t * Link NULL
Pt_CB_TERM_RESIZED PtCallback_t * Link NULL
Pt_CB_TERM_SCRLBK PtCallback_t * Link NULL
Pt_ARG_TERM_ANSI_PROTOCOL
short Boolean 1
The protocol to use for the terminal:
0 QNX4
1 ANSI
Pt_ARG_TERM_APP
PtTerminalAppState_t Struct See below
A structure containing the application window’s state, which the protocol engine needs
(see the Pt_CB_TERM_APP callback). This structure also contains some other
information that a terminal emulator can use, such as the window title, size, and
position.
The PtTerminalAppState_t structure is defined as:
typedef struct Pt_terminal_app_state {
struct PtTerminal_app_state_bins {
/* Binary part - memcmp can be used for comparing */
unsigned version;
PhArea_t area;
PtTerminalRowCol_t size;
unsigned iconic: 1, infront: 1;
}
b;
/* Strings - guaranteed to never contain garbage after ’\0’ */
char title[ Pt_TERM_WSTRING_MAX + 1 ];
char l_msg[ Pt_TERM_WSTRING_MAX + 1 ];
char icon[ Pt_TERM_WSTRING_MAX + 1 ];
char reserved;
}
PtTerminalAppState_t;

Most of the members of this structure are present mainly for compatibility with
terminal emulators other than pterm, A text-mode program might use certain special
escape sequences to set those values, and other special escape sequences to query
those values. In pterm, the values are preserved (so your text-mode program sees the
expected responses to escape sequences), but are otherwise ignored. The only
exception is title — pterm uses it to set its window title.
If you have a text-mode program that needs a terminal emulator other than pterm,
you’ll need to use the Pt_ARG_TERM_APP resource and the Pt_CB_TERM_APP
callback.
The members are:
b.version The version number, which is initialized to 100, can be queried by an

escape sequence. It’s useful if you want to write a terminal emulator that
recognizes additional escape sequences and you want your text-mode
programs to be able to detect whether they’re running in a pterm
(version=100) or in your emulator (version=something else).
b.area The area of the PtTerminal widget.
b.size The terminal’s size, in rows and columns.
b.iconic A bit that indicates whether or not the application is iconified

(minimized).
b.infront A bit that indicates whether or not the application is in front of all other
windows.
title The first part of the window’s title.
l_msg The second part of the window’s title.
icon The string to display on the icon instead of the window title.
Pt_ARG_TERM_CHARSETS
PtTerminalCsXlatData_t * Pointer See below
This resource handles the character set translation. It’s a pointer to translation tables
stored in a PtTerminalCsXlatData_t structure. The contents of the structure aren’t
defined in a public header — the only way to create a PtTerminalCsXlatData_t
structure is by calling PtTerminalCreateCsXlat().
If you set Pt_ARG_TERM_CHARSETS to NULL, the widget calls
PtTerminalCreateCsXlat() to create its own copy of the default translation tables. This
copy is freed when you destroy the widget or set its Pt_ARG_TERM_CHARSETS
resource to a non-NULL value.

PtTerminalCreateCsXlat() doesn’t make a copy of the PtTerminalCharsets_t

structure passed to it, and PtTerminal doesn’t make a copy of the
PtTerminalCsXlatData_t structure when you set Pt_ARG_TERM_CHARSETS.
Don’t free or modify these structures until they’re no longer needed by any widget.
The PtTerminalCsXlatData_t structure created by PtTerminalCreateCsXlat() is
placed in a single allocated block of memory. When it’s no longer needed, you can
simply free() it.
Pt_ARG_TERM_COLOR_MODE
PtTerminalColorMode_t Struct Pt_TERM_COLOR_MODE
A set of pointers to conversion functions, used internally by the widget.
Pt_ARG_TERM_COLOR_TABLE
PgColor_t, short Array CGA colors, 16
The color table used for the display. See PgColor_t in the Photon Library Reference.
This resource is used to convert color numbers used internally to actual Photon color
values. Color numbers are indexes into this array. The default array has 16 elements
corresponding to 16 standard CGA colors:
Index Color
0 BLACK
1 BLUE
2 GREEN
3 CYAN
4 RED
5 MAGENTA
6 BROWN
7 WHITE (light grey)
8 BRIGHT BLACK (dark grey)
continued. . .

Index Color
9 BRIGHT BLUE
10 BRIGHT GREEN
11 BRIGHT CYAN
12 BRIGHT RED
13 BRIGHT MAGENTA
14 BRIGHT BROWN (yellow)
15 BRIGHT WHITE
Pt_ARG_TERM_COLS
short Scalar 80
The number of character columns.
Pt_ARG_TERM_CONSOLE
PtTerminalConsoleWrite_t Complex N/A
You can use this resource to access the widget’s “video memory” For more
information, see “Console emulation,” above.
Pt_ARG_TERM_CUR_COL
short Scalar 0
The column number of the cursor’s position.
Pt_ARG_TERM_CUR_POS
PtTerminalRowCol_t Struct 0, 0
The cursor position. The PtTerminalRowCol_t structure contains the following

members:
• short r
• short c

Pt_ARG_TERM_CUR_ROW

short Scalar 0
The line number of the cursor’s position.
Pt_ARG_TERM_CURSOR_FLAGS
short Flag Pt_TERM_CURSOR_ON_FOCUS
Flags affecting the cursor timer. Possible values are:
• Pt_TERM_CURSOR_ON_FOCUS — the cursor blinks when the widget has focus.
• Pt_TERM_CURSOR_ALWAYS — the cursor always blinks.
• Pt_TERM_CURSOR_NEVER (zero) — the cursor never blinks.
• Pt_TERM_CURSOR_TIMER — the timer is activated even if not needed. This may

be useful for getting a raw callback periodically. Note that this timer runs only
when the widget is realized.
• Pt_TERM_CURSOR_NOSPEEDCHK — if this flag isn’t set, the cursor won’t blink

if the connection to Photon is slow. See also
Pt_ARG_BANDWIDTH_THRESHOLD.
Pt_ARG_TERM_DRAW_MODES
unsigned char Flag Pt_TERM_SCROLL_RFSH
Flags that determine scrolling optimization:
• Pt_TERM_SCROLL_NOBLIT — always redraw instead of blitting.
• Pt_TERM_SCROLL_NOHWCHK — attempt to blit even if blitting isn’t supported

by hardware.
• Pt_TERM_SCROLL_RFSH — redraw the screen on the first scroll even if PhBlit()

won’t be used.
• Pt_TERM_SCROLL_NOVISCHK — always assume that the widget isn’t clipped or

obscured by other widgets. (Normally, the widget checks to see if it it’s obscured or
clipped by other widgets in such a way that using PhBlit() would move parts of
another widget.)

• Pt_TERM_SCROLL_NOSPEEDCHK — don’t check the bandwidth. If this flag isn’t

set and the bandwidth isn’t greater than the value of the
Pt_ARG_BANDWIDTH_THRESHOLD resource, the widget behaves as if the
Pt_TERM_SCROLL_NOBLIT, Pt_TERM_SCROLL_NOHWCHK, and
Pt_TERM_SCROLL_RFSH flags are clear and the Pt_ARG_TERM_SCROLL
resource has a huge value.
For more information, see the “Drawing and scrolling” part of the “Description”
section above.
Pt_ARG_TERM_FONT
char * String "pcterm14"
The name of the font used for the display. For more information, see “Fonts,” above.
PtTerminal works only with fixed-width fonts. It ignores any attempts to change to
a proportional font.
Pt_ARG_TERM_FONT_INDEX
short Scalar -1
The position of the current font in the font list, or -1 if the current font isn’t in the list.
You can use this resource to choose a font from the list, but you can’t explicitly set it
to -1.
Pt_ARG_TERM_FONT_LIST
char *, short Array NULL, 0
The list of fonts (an array of pointers to strings).

When you set this resource, the meaning of the value argument of the PtSetArg()
macro depends on whether the len argument is zero or nonzero:
• If len is nonzero, value should be a pointer to an array of pointers to font names,

and len should be the number of pointers in the array. The widget replaces the
current font list with a copy of the given list.
• If len is zero, value should be either NULL or a pointer to string. If value is NULL,
the font list is removed. Otherwise, the given string is appended to the current list.
For more information, see “Fonts,” above.

Pt_ARG_TERM_FONT_SIZE (read-only)

PhDim_t Struct Size of default font
A PhDim_t structure (see the Photon Library Reference) that defines the dimensions
of the font used for the display.
Pt_ARG_TERM_MARGINS (read-only)
A PhRect_t structure (see the Photon Library Reference) that contains the actual
width and height of the widget’s margins. These values are equal to or greater than
values of Pt_ARG_MARGIN_WIDTH and Pt_ARG_MARGIN_HEIGHT resources.
For more information, see “Geometry,” above.
Pt_ARG_TERM_MAXCOLS
short Scalar 1000
The maximum number of character columns.
Pt_ARG_TERM_MAXROWS
short Scalar 1000
The maximum number of character rows.
Pt_ARG_TERM_MAXSIZE
The maximum screen size, in character rows and columns. The

PtTerminalRowCol_t structure contains the following members:
• short r
• short c

Pt_ARG_TERM_MINCOLS

short Scalar 1
The minimum number of character columns.
Pt_ARG_TERM_MINROWS
short Scalar 1
The minimum number of character rows.
Pt_ARG_TERM_MINSIZE
The minimum screen size, in character rows and columns. The

PtTerminalRowCol_t structure contains the following members:
• short r
• short c
Pt_ARG_TERM_OPTIONS
unsigned long Flag 0x84380
A set of flags that can be set or cleared by escape sequences. The flags are numbered
from 1 to 32 (see <photon/PtTerm.h>). The widget handles some of them, and
your application can handle some others.
Pt_ARG_TERM_OPTMASK
unsigned long Flag ˜0uL
A set of bits that correspond to those in Pt_ARG_TERM_OPTIONS. Clearing a bit in

Pt_ARG_TERM_OPTMASK disables the escape sequence for the corresponding bit
in Pt_ARG_TERM_OPTIONS

Pt_ARG_TERM_RESIZE_FL

unsigned short Flag All defined flags
Flags that affect the resizing of the terminal widget. Any combination of:
• Pt_TERM_OPFONT — FONT can be set with escape sequences.
• Pt_TERM_KBFONT — FONT can be set with keyboard.
• Pt_TERM_KBFORCE — when FONT is set with keyboard, keep the widget’s SIZE
or DIM (depending on the key sequence).
• Pt_TERM_ANCHOR_PARENT_WIDTH — resize the parent widget’s width if the

terminal’s right edge is anchored to the parent’s right edge.
• Pt_TERM_ANCHOR_PARENT_HEIGHT — resize the parent widget’s height if the

terminal’s bottom edge is anchored to the parent’s bottom edge.
• Pt_TERM_ANCHOR_WINDOWS_ONLY — don’t resize the parent unless it’s a

window.
Pt_ARG_TERM_RESIZE_FUN
See below Pointer Pointer to static function
A pointer to a function to be used in geometry adjustments. The prototype is:
const char*(*)(char*, const char*)
For more information, see “Geometry,” above.
Pt_ARG_TERM_RESIZE_STR
char * String "DF=sM:M=s"
A hint for the function used in geometry adjustments. For more information, see
“Geometry,” above.
Pt_ARG_TERM_ROWS

The number of character rows.
Pt_ARG_TERM_SCRLBK_COUNT
short Scalar 0
The current number of lines saved in the scrollback buffer.
Pt_ARG_TERM_SCRLBK_LIMIT
short Scalar 0
The maximum of number of lines saved in the scrollback buffer.
Pt_ARG_TERM_SCRLBK_POS
short Scalar 0
The current position in the scrollback buffer (reset to zero on any output, including the
Pt_ARG_TERM_CONSOLE resource).
Pt_ARG_TERM_SCROLL
short Scalar Pt_TERM_MAX_ROWS
The maximum number of scrolls that will be delayed. For more information, see
“Scrolling optimization,” above.
Pt_ARG_TERM_SELECTION
PtTerminalSelection_t Struct 0
The PtTerminalSelection_t structure contains at least the following members:
unsigned char type;

unsigned char old_type;
unsigned short flags;
PtTerminalRowCol_t first, last;
where:

type Can be one of:

• Pt_TERM_SELECTION_NONE — no selection.
• Pt_TERM_SELECTION_BLOCK — a block is selected.
• Pt_TERM_SELECTION_STREAM — a stream is selected.
old_type The last value of type that differed from Pt_TERM_SELECTION_NONE.
flags Valid flags are:

• Pt_TERM_SELECTION_ALWAYS — the pointer always selects text.
• Pt_TERM_SELECTION_NEVER — the pointer never selects text.
• Pt_TERM_SELECTING (read_only) — something is being selected.
The following flags aren’t stored in the widget but they tell the widget
that the corresponding member of the structure shouldn’t be modified:
• Pt_TERM_SELECTION_TYPE_KEEP — don’t modify type.
• Pt_TERM_SELECTION_FIRST_KEEP — don’t modify first.
• Pt_TERM_SELECTION_LAST_KEEP — don’t modify last.
• Pt_TERM_SELECTION_FLAGS_KEEP — don’t modify flags.
first, last Two positions that define the selected area. If selected by the mouse,
first is the position of the press and last is the position of the release.
The PtTerminalRowCol_t structure contains the following members:
• short r
• short c
Pt_ARG_TERM_SIZE
The screen size, in characters. The PtTerminalRowCol_t structure contains the

following members:
• short r
• short c
Pt_ARG_TERM_VISUAL_BELL
short Scalar 20
The time, in milliseconds, of the screen flash when the ASCII BEL character (Ctrl-G)
is received.

Pt_CB_TERM_APP

A list of PtCallback_t structures that define the callbacks invoked whenever the
Pt_ARG_TERM_APP resource changes, or a private escape sequence is received.
following members:
reason Pt_CB_TERM_APP
reason_subtype The character or number defining the type of escape sequence.

event NULL
cbdata Either a NULL pointer, or the string contained in the escape

sequence.
There are four general sources of the Pt_CB_TERM_APP callback. They can be
recognized by the values of the reason_subtype and cbdata fields:
reason_subtype=0, cbdata=NULL
A change of terminal’s size or font. Before issuing this callback, the widget sets
the area and size fields of the Pt_ARG_TERM_APP resource to the values of
the widget’s Pt_ARG_AREA and Pt_ARG_TERM_SIZE resources so that even
if a terminal emulator program doesn’t modify the Pt_ARG_TERM_APP
resource, the terminal responds properly to escape sequences that query terminal
parameters.
reason_subtype=0, cbdata=""
An explicit change of the Pt_ARG_TERM_APP resource.
reason_subtype=nonzero, cbdata=NULL
An escape sequence that set some of the data stored in the “binary” part of the
Pt_ARG_TERM_APP resource. The reason_subtype field indicates the first
parameter of the escape sequence.
reason_subtype=nonzero, cbdata=string
An escape sequence that changed one of the strings stored in the
Pt_ARG_TERM_APP resource.
The value of the reason_subtype field is the ASCII code of the character that indicates
the escape sequence type, and the cbdata field points to the <string>.

Pt_CB_TERM_FONT

A list of PtCallback_t structures that define the callbacks invoked after the font is
changed. Each callback is passed a PtCallbackInfo_t structure that contains at
reason Pt_CB_TERM_FONT
event NULL
cbdata A pointer to a PtTerminalFontChange_t structure that contains at

const char * old_font;

Defines the previous font.
const char * new_font;
Defines the new font.
Pt_CB_TERM_INPUT
A list of PtCallback_t structures that define the callbacks invoked when keyboard
or mouse input is delivered to the widget. Each callback is passed a
reason Pt_CB_TERM_INPUT
reason_subtype Can be one of:

• Pt_TERM_KEYBOARD_INPUT — for key events other than
the Break key.
• Pt_TERM_MOUSE_INPUT — for mouse events.
• Pt_TERM_CTRLBRK_INPUT — for the Break key.
• Pt_TERM_PROTOCOL_INPUT — for responses to an escape
sequence.
• Pt_TERM_PASTE_INPUT — for pasting from the clipboard.

• Pt_TERM_PASTE_NF_INPUT — for pasting from the

clipboard.
caused the callback to be invoked, or NULL if the characters are a
reply to an escape sequence rather than reaction to a keyboard or
mouse event.
cbdata A pointer to a PtTerminalInput_t structure that contains at

unsigned length; The number of characters the key generates

(may be zero if a key was pressed that
doesn’t generate characters).
const char * string;
A pointer to the buffer containing the
characters.
PtTerminalRowCol_t position;
In the case of a pointer event, the current
mouse position. In all other cases, the
current cursor position. The
PtTerminalRowCol_t structure contains
the following members:
• short r
• short c
The widget issues this callback on every keystroke unless both Ctrl and Alt modifiers
are pressed.
When text is being pasted from the clipboard, the callback subtype is set to
Pt_TERM_PASTE_INPUT if the buffer has been allocated with the malloc() function.
A callback function can take over the responsibility for freeing the buffer by changing
the subtype to Pt_TERM_PASTE_NF_INPUT.
Pt_CB_TERM_OPTIONS
Pt_ARG_TERM_OPTIONS resource changes. Each callback is passed a
reason Pt_CB_TERM_OPTIONS

reason_subtype 0 if options have been changed via widget resources, or 1 if

options have been changed by an escape sequence.
event NULL
cbdata A pointer to a PtTerminalOptionChange_t structure that

unsigned long old_opts;

The previous value of the options.
unsigned long new_opts;
The new value of the options.
Pt_CB_TERM_RESIZE
terminal is about to change its size (i.e the number of rows and/or columns).
following members:
reason Pt_CB_TERM_RESIZE
event NULL
cbdata A pointer to a PtTerminalSizeChange_t structure that contains at

PtTerminalRowCol_t old_size;
The current size of the terminal.
PtTerminalRowCol_t new_size;
The new size.

• short r
• short c
This callback is issued whenever one of the Pt_ARG_TERM_SIZE,

Pt_ARG_TERM_ROWS, or Pt_ARG_TERM_COLS resources is set, even if the new
value is equal to the old value.

However, if your application calls PtSetResources() with invalid size values (outside
of limits defined by Pt_ARG_TERM_MINSIZE and Pt_ARG_TERM_MAXSIZE
resources), the new size is validated before issuing the callback.
Pt_CB_TERM_RESIZED
A list of PtCallback_t structures that define the callbacks invoked after the size is
changed.
following members:
reason Pt_CB_TERM_RESIZED
event NULL
cbdata A pointer to a PtTerminalSizeChange_t structure that contains at

The previous size of the terminal.
The current size.

• short r
• short c
This callback is issued whenever one of the Pt_ARG_TERM_SIZE,

Pt_ARG_TERM_ROWS, or Pt_ARG_TERM_COLS resources is set, even if the new
value is equal to the old value.
After an unsuccessful attempt to resize the terminal, the callback is issued with cbdata
set to NULL.
Pt_CB_TERM_SCRLBK

Pt_ARG_TERM_SCRLBK_POS resource or the number of saved lines in the widget’s
buffer changes. Each callback is passed a PtCallbackInfo_t structure that contains
reason Pt_CB_TERM_SCRLBK
reason_subtype 0
event NULL
cbdata A pointer to a PtTerminalScrlbkCb_t structure that contains

short old_count; The previous value of the line count

short old_pos; The previous value of the line position.
short new_count; The new line count.
short new_pos; The new line position.
Functions invoked by this callback shouldn’t set any of the widget’s resources.

Pt_ARG_BANDWIDTH_THRESHOLD PtBasic Ph_BAUD_SLOW (see below)
continued. . .


Pt_ARG_DIM PtWidget
Pt_ARG_FILL_COLOR PtBasic Pt_INHERIT_COLOR (see below)
continued. . .


Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
continued. . .


The threshold value for graphics bandwidth (as reported by PhQuerySystemInfo()) that
defines a slow connection. For more information, see
Pt_ARG_TERM_CURSOR_FLAGS and “Scrolling optimization,” above.
Pt_ARG_FILL_COLOR
The color of widget’s margins. When set to Pt_INHERIT_COLOR, the widget draws
margins using the “saved” fill color, which can be set to the current fill color using an
escape sequence:
In QNX mode: ESC S
In ANSI mode: ESC [ 8 ]
The PtTerminal widget defines the following convenience functions and data
structures that make it easier to use the terminal once it’s been created:
PtTerminalCharset_t, PtTerminalCharsets_t
Character sets used by PtTerminal
PtTerminalCopy() Copy the current selection to the clipboard.
PtTerminalCreateCsXlat().
Create a translation table for PtTerminal’s character sets.
PtTerminalDefaultCharsets():
Get the default character sets used by PtTerminal.
PtTerminalFontInfo()
Examine a font.
PtTerminalGetKeys()
Get the terminal line-editing keys.
PtTerminalGetSelection()
Get a copy of the current selection.
PtTerminalName() Get the terminal’s termcap/terminfo name.

PtTerminalPasteClipboard()
Paste the contents of the clipboard into the terminal.
PtTerminalPasteSelection()
Paste the current selection into the terminal.
PtTerminalPut(), PtTerminalPutc(), PtTerminalPuts()
Output text to the terminal.
PtTerminalSelectWord()
Select a word.

PtTerminalCharset_t, PtTerminalCharsets_t © 2010, QNX Software
Systems GmbH & Co. KG.
Character sets used by PtTerminal
Synopsis:
typedef struct {
const unsigned short *table;
unsigned char first, last;
...
} PtTerminalCharset_t;
typedef struct {
unsigned short from, to;
} PtTerminalCharSubst_t;
typedef struct {
PtTerminalCharset_t const *AnsiCharset;
PtTerminalCharset_t const *InternalCharset;
PtTerminalCharset_t const *FontTranslation;
PtTerminalCharSubst_t const *Subst;
unsigned short NumSubst;
...
} PtTerminalCharsets_t;
Description:
The PtTerminalCharset_t and PtTerminalCharsets_t structures define
character sets used internally and externally by PtTerminal.
Both structures have some undocumented members at the end, reserved for future
extensions. To be safe, make sure that they’re filled with zeros. The order of the
documented members will stay the same — it’s safe to initialize these structures
statically.
A PtTerminalCharset_t structure defines an 8-bit character set by defining its

mapping to Unicode. This is how this mapping can be expressed in C:
wchar_t unicode_value( unsigned char ch,

PtTerminalCharset_t const *cs ) {
wchar_t result;
if ( ch < 0x80 )
return ch; /* ch is an ASCII character */
else {
if ( ch >= cs->first && ch <= cs->last
&& ( result = cs->table[ cs - cs->first ] ) != L’\0’ )
/* ch is mapped to a Unicode value */
return result;
else
/* ch is an illegal value */
return NO_MAPPING_DEFINED;
}
}
If a character set contains “illegal values”, they’re displayed as blanks and are never
generated from a key event. But in general, it’s a good idea to avoid having illegal
values in a character set — preferably, the internal character set should define all

© 2010, QNX Software Systems GmbH & Co. KG. PtTerminalCharset_t,
PtTerminalCharsets_t
values from 0x80 to 0xFF and the ANSI character set should define all values from
0xA0 to 0xFF.
You can set AnsiCharset or InternalCharset (or both) to NULL; the function then uses
the defaults (8859-1 for AnsiCharset and PC character set for InternalCharset). It’s
also possible to get to the actual tables that define the defaults by calling
PtTerminalDefaultCharsets():
const PtTerminalCharsets_t *PtTerminalDefaultCharsets( void );
The FontTranslation defines the mapping from the internal character set to whatever
character set your Photon font is using. In other words, if FontTranslation isn’t NULL,
PtTerminal uses the 16-bit code returned by:
unicode_value( internal_char, FontTranslation )
to display the 8-bit internal code internal_char. Note that if you want the widget to use
Unicode, FontTranslation should point to the same character set as InternalCharset.
If FontTranslation is NULL, the font is assumed to be compatible with the internal
character set, and no mapping is used.
The Subst field points to an array that lists character substitutions that the widget uses
when a character is missing from the character set that it needs to be translated to. The
array must be sorted with the respect to the from field. NumSubst defines the length of
the array.
The situations where the substitutions are performed are:
• When the widget receives a key event containing a Unicode symbol that doesn’t
exist in the current text-mode character set (i.e. either the ANSI character set or the
internal character set, depending on the current terminal emulation), the widget
searches the Subst array for an entry where from is the character in the event and to
is a character that exists in the text-mode character set. If such an entry exists, the
to character is used instead of the symbol in the event. If multiple matching entries
exist in the table, the first one is used. If none exists, the event doesn’t generate any
terminal input.
• In the ANSI mode, characters written to the terminal must be converted from the
ANSI character set to the internal character set before they can be displayed. If the
ANSI character set contains characters that the internal character set doesn’t
contain, the Subst array is searched for a replacement character. If none is found,
the character is displayed as a space.
Classification:
Photon

PtTerminalCharset_t, PtTerminalCharsets_t © 2010, QNX Software
See also:
PtTerminal, PtTerminalDefaultCharsets()

© 2010, QNX Software Systems GmbH & Co. KG. PtTerminalCopy()
Copy the current selection to the clipboard
Synopsis:
void PtTerminalCopy( PtWidget_t *widget,
PhEvent_t *event );
Description:
This function copies the current selection in the given PtTerminal widget to the
clipboard. The event parameter is used to select the input group; see
PhClipboardCopyString() in the Photon Library Reference.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTerminal

PtTerminalCreateCsXlat() © 2010, QNX Software Systems GmbH & Co. KG.
Create a translation table for PtTerminal’s character sets
Synopsis:
PtTerminalCsXlatData_t *PtTerminalCreateCsXlat(
PtTerminalCharsets_t const *csets );
Description:
This function creates a translation table for the character sets used by PtTerminal.
The PtTerminalCsXlatData_t structure is for internal use only; you must use this
function to create it.
The csets argument is a pointer to a PtTerminalCharsets_t structure that defines
the character sets and their translation.
Returns:
A pointer to a PtTerminalCsXlatData_t structure that you can use to set the
Pt_ARG_TERM_CHARSETS resource of a PtTerminal widget.
PtTerminalCreateCsXlat() doesn’t make a copy of the PtTerminalCharsets_t

structure pointed to by csets, and PtTerminal doesn’t make a copy of the
PtTerminalCsXlatData_t structure when you set Pt_ARG_TERM_CHARSETS.
Don’t free these structures until they’re no longer needed by any widget.
The PtTerminalCsXlatData_t structure created by PtTerminalCreateCsXlat() is
placed in a single allocated block of memory. When it’s no longer needed, you can
simply free() it.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTerminal, Pt_ARG_TERM_CHARSETS, PtTerminalCharsets_t

© 2010, QNX Software Systems GmbH & Co. KG. PtTerminalDefaultCharsets()
Get the default character sets used by PtTerminal
Synopsis:
const PtTerminalCharsets_t *
PtTerminalDefaultCharsets( void );
Description:
This function returns a pointer to the tables that define the default character sets used
by PtTerminal.
Returns:
A pointer to the tables.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTerminal, PtTerminalCharsets_t

PtTerminalFontInfo() © 2010, QNX Software Systems GmbH & Co. KG.
Convert the font name to a fixed-width font name
Synopsis:
int PtTerminalFontInfo( const char *font,
PhDim_t *size,
PhPoint_t *offs );
Description:
This function makes sure that the given font exists and is a fixed-width font. It returns
an allocated copy of the name. If the appropriate font doesn’t exist,
PtTerminalFontInfo() returns NULL.
This function stores information about the font’s geometry at locations pointed to by
size and offs:
• If size isn’t NULL, the width and height of the character cell are stored in the
PhDim_t structure (see the Photon Library Reference) it points to.
• If offs isn’t NULL, the function stores, in the PhPoint_t structure that it points to,
the position that should be given to a drawing function in order to draw the
character cell starting at position (0, 0).
Returns:
0 if the font name exists and is a fixed-width font, and -1 if not.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTerminal

© 2010, QNX Software Systems GmbH & Co. KG. PtTerminalGetKeys()
Get the terminal line-editing keys
Synopsis:
void PtTerminalGetKeys( int protocol,
struct termios *buf );
Description:
This function fills the following items of the buf ->c_cc array with values appropriate
for the given protocol:
• VPREFIX
• VSUFFIX
• VLEFT
• VRIGHT
• VUP
• VDOWN
• VINS
• VDEL
• VHOME
• VEND
The other fields of the structure aren’t modified. For more information, see the
Pt_ARG_TERM_ANSI_PROTOCOL resource associated with the PtTerminal
widget.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTerminal

PtTerminalGetSelection() © 2010, QNX Software Systems GmbH & Co. KG.
Get a copy of the current selection
Synopsis:
char *PtTerminalGetSelection( PtWidget_t *widget );
Description:
This function returns a copy of the current selection (or NULL if there’s no selection).
It’s your application’s responsibility to free() the buffer when it’s no longer needed.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTerminal

© 2010, QNX Software Systems GmbH & Co. KG. PtTerminalName()
Get the terminal termcap or terminfo name
Synopsis:
const char *PtTerminalName( int protocol );
Description:
This function returns a terminal name (one of qnxm or qansi-m), based on the given
protocol.
For more information, see the Pt_ARG_TERM_ANSI_PROTOCOL resource
associated with the PtTerminal widget.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTerminal

PtTerminalPasteClipboard() © 2010, QNX Software Systems GmbH & Co. KG.
Paste the contents of the clipboard into the terminal
Synopsis:
void PtTerminalPasteClipboard( PtWidget_t *widget,
PhEvent_t *event );
Description:
This function pastes the contents of the clipboard into the terminal’s “keyboard” by
invoking the widget’s Pt_CB_TERM_INPUT callback. The given event is passed to
the callback functions. If event isn’t NULL, event->input_group also selects the
clipboard; see PhClipboardPasteString() in the Photon Library Reference.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTerminal

© 2010, QNX Software Systems GmbH & Co. KG. PtTerminalPasteSelection()
Paste the current selection into the terminal
Synopsis:
void PtTerminalPasteSelection( PtWidget_t *widget,
PhEvent_t *event );
Description:
This function pastes the current selection into the terminal’s “keyboard” by invoking
the widget’s Pt_CB_TERM_INPUT callback. The given event is passed to the
callback functions.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTerminal

PtTerminalPut(), PtTerminalPutc(), PtTerminalPuts() © 2010, QNX Software
Output text to the terminal
Synopsis:
int PtTerminalPut( PtWidget_t *widget,
const char *buffer,
size_t nchars );
int PtTerminalPutc( PtWidget_t *widget,

char character );
int PtTerminalPuts( PtWidget_t *widget,

const char *string );
Description:
These functions output characters to the terminal widget.
Returns:
0 Success.
-1 An error occurred (errno is set).
Errors:
EINVAL The widget isn’t a terminal widget.
EBUSY Invalid recursion.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTerminal

© 2010, QNX Software Systems GmbH & Co. KG. PtTerminalSelectWord()
Select a word
Synopsis:
int PtTerminalSelectWord(
PtWidget_t *widget,
PtTerminalRowCol_t const *pos );
Description:
This function selects a word containing the character at the specified position (or at the
cursor position if pos is NULL).
• short r
• short c
Returns:
1 Done.
0 There’s no word at the specified position (neither the character at the specified
position nor the character to the left is a letter, digit or underscore).
-1 The pos argument is invalid (i.e. beyond the screen size).
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTerminal

PtText © 2010, QNX Software Systems GmbH & Co. KG.
Single-line text
Class hierarchy:
PtWidget → PtBasic → PtLabel → PtText
PhAB icon:
Public header:
<photon/PtText.h>
Description:
The Photon text widgets let you type textual information into a text-entry box. The
widgets provide basic editing features, so you can alter text that’s entered. They also
support a point-and-click model of editing, so that you can operate on blocks of text as
a unit.
A PtText widget.
Photon provides two different text widgets:
• PtText — a small, simple widget that provides a single-line data-entry field. You
can’t change the attributes of the text in the field — the same font and color are
used throughout the text string.
• PtMultiText — a full-featured text editor that handles multiple lines of text. You
can select blocks of text and assign to them different text attributes (e.g. you can
display the text in several different fonts and colors).
Interaction model
The text that you enter in the text widget is either inserted into or overwrites the
existing text, depending on the insertion mode. The location where text is inserted or
replaced is visually represented by a cursor.
In insert mode, the cursor appears as a vertical bar or pipe (|) between two characters.
When you enter a character, it appears at the cursor location, and the cursor is moved
to the right of that character.
In replace mode, the cursor appears as an underline (_) beneath a character. When you
enter a new character, it replaces the character at the cursor location, and the cursor is
moved to the next character in the text.

© 2010, QNX Software Systems GmbH & Co. KG. PtText
Selecting text
Clicking the mouse button once changes the cursor location to the character position
nearest the pointer location. Double-clicking selects the text under the pointer, using
space characters as the selection delimiter. Dragging the pointer with the button
pressed selects a range of text as the object of a subsequent operation. The selected
range of text, which begins at the cursor position and ends at the pointer location, is
highlighted by inverting the foreground and background colors used to display the
text. Releasing the button completes the range selection.
You can extend the range of text selected by dragging with the Shift key pressed. The
selected range of text is changed to the text between the current cursor position and the
pointer location. The extension of the range of text is completed when the button is
released. Alternately, you can extend the range by Shift-clicking at a new position.
Any character you type after selecting a range of text replaces the selected range. Your
application can also specify a string to replace the selected range.
You can delete selected text by pressing Delete or Backspace. Pressing
Ctrl-Backspace deletes all the text to the left of the cursor up to the first space
character. Ctrl-Delete deletes the text to the right of the cursor up to the first space
character.
The widget’s text

To modify the text widget’s contents within a program, you must be able to access the
text widget’s internal storage. The primary means of access to this text is through the
Pt_ARG_TEXT_STRING resource (inherited from PtLabel).
Setting text
When you set the widget’s text using Pt_ARG_TEXT_STRING, you must give a
null-terminated C string as a value.
The following short program creates a text widget whose initial contents are the string
“hello, world...”:
#include <Pt.h>
PhArea_t area = { {0, 0}, {200,40} };

{
PtAppContext_t app;
int nargs = 0;
PtArg_t args[4];
PtWidget_t *window;
PtSetArg(&args[nargs++], Pt_ARG_POS, &area.pos, 0);

PtSetArg(&args[nargs++], Pt_ARG_DIM, &area.size, 0);
PtSetArg(&args[nargs++], Pt_ARG_WINDOW_TITLE, "hello", 0);
nargs, args)) == NULL)

nargs = 0;
area.pos.y = 15;
PtSetArg(&args[nargs++], Pt_ARG_POS, &area.pos, 0);
PtSetArg(&args[nargs++], Pt_ARG_DIM, &area.size, 0);
PtSetArg(&args[nargs++], Pt_ARG_TEXT_STRING,
"hello, world...", 0);
PtCreateWidget(PtText, window, nargs, args);
PtMainLoop();
}
Getting text
You can retrieve the widget’s text as a null-terminated C string by getting the value of
the Pt_ARG_TEXT_STRING resource with the PtGetResources() function.
For more information, see “Getting resources” in the Manipulating Resources in
Application Code chapter of the Photon Programmer’s Guide.
Getting the current selection
You can obtain the range of characters in the current selection by using the
PtTextGetSelection() function. This function takes the widget as the first parameter
and returns the start and end position in the remaining two parameters. You can pass
the range to other convenience functions to modify the selected text.
Replacing text
Your application can change any block of text in the widget by calling
PtTextModifyText(). The arguments are:
widget A pointer to the text widget.

start_pos The start position of the range of text to be replaced.
end_pos The end position of the range of text to be replaced.
cur_insert The position to place the cursor before the change.
text The UTF-8 string to replace the block of text.
length The number of multibyte characters in the string.
Text-modification callbacks
Your application can monitor and control changes made to the widget’s text using the
text-modification callbacks. These callbacks are invoked when you type new text. If
the widget has the Pt_CALLBACKS_ACTIVE bit set in its Pt_ARG_FLAGS resource,
these callbacks are also invoked when your application changes the text is changed by
calling PtSetResource(), PtSetResources(), or a convenience function such as
PtTextModifyText(). The text-modification callbacks are:

Pt_CB_MODIFY_VERIFY
Called before any changes are made to the text.
Pt_CB_MODIFY_NOTIFY (also known as Pt_CB_TEXT_CHANGED)

Called after a change.
Validation
The Pt_CB_MODIFY_VERIFY callback is useful for validating changes before

they’re made to the widget. You can use this callback to alter the text modification or
prevent it entirely.
This callback can manipulate the text modification via the cbdata member of the
PtCallbackInfo_t structure passed to it. The cbdata member is a pointer to a
text-callback structure. This is a PtTextCallback_t structure if the widget is a
PtText, and a PtMultiTextCallback_t structure if the widget is a PtMultiText
widget.
The following example shows how the text member of the above structure can be
modified to alter the text inserted into the widget. The example uses the allcaps()
callback function to convert any lowercase characters to uppercase before they’re
inserted into the widget.
#include <Pt.h>
#include <stdlib.h>
#include <ctype.h>
int allcaps(PtWidget_t *, void *, PtCallbackInfo_t *);

{
PtAppContext_t app;
PhRect_t extent;
PhPoint_t pos;
PhPoint_t dim;
PtArg_t args[6];
int nargs;
PtWidget_t *window, *text, *label;
/* Labels work with UTF-8 (multibyte character) strings.

International characters can be entered only from an
editor that supports UTF-8 */
nargs = 0;
PtSetArg(&args[nargs], Pt_ARG_MARGIN_HEIGHT, 4, 0);
nargs++;

nargs = 0;
PtSetArg(&args[nargs], Pt_ARG_TEXT_STRING, "Enter Text:", 0);
nargs++;

label = PtCreateWidget(PtLabel, window, nargs, args);
PtExtentWidget(label);
PtWidgetExtent(label, &extent);
pos.x = extent.lr.x + 4;
pos.y = 0;
nargs = 0;
PtSetArg(&args[nargs], Pt_ARG_COLUMNS, 20, 0); nargs++;
PtSetArg(&args[nargs], Pt_ARG_POS, &pos, 0); nargs++;
text = PtCreateWidget(PtText, window, nargs, args);
PtAddCallback(text, Pt_CB_MODIFY_VERIFY, allcaps, NULL);
PtMainLoop();
}
int allcaps( PtWidget_t *w, void *client_data,

{
int len;
PtTextCallback_t *cbs = (PtTextCallback_t
*)info->cbdata;
if (cbs->text == NULL)
return Pt_CONTINUE;
for ( len = 0; len < cbs->length; len++ )

if (islower(cbs->text[len]))
cbs->text[len] = toupper(cbs->text[len]);
return Pt_CONTINUE;
}
Preventing the modification
You can prevent the text from being added to the widget by setting the doit member of
the PtTextCallback_t structure to zero or by setting the length member to zero.
Setting the length to 0 stops the widget from inserting the text; it doesn’t prevent any
deletion included in the modification.
Handling deletions
You can determine if a modification is replacing or deleting a block of text by

checking start_pos and end_pos. If these values differ, then a block of text is being
removed from the widget and may potentially be replaced by new text contained in the
text member.
Be sure to handle backspaces correctly. As well as checking for a different start and
end position, an application can determine which of Backspace or Delete was pressed
by checking the length, cur_insert, and new_insert:
• If length is zero, then no text replaces the deleted range—you most likely pressed
the Delete key or the destructive backspace key.

• If new_insert is less than cur_insert, you pressed the destructive backspace key.
• If new_insert equals cur_insert, you pressed the Delete key.
Example: entering a password
The following simple example of accepting a password as input illustrates how to

handle all editing operations (including pasting) correctly:
/* This program creates two text widgets for entering
a password:
- one offscreen to collect the password
- one onscreen in which to type.
All characters are displayed as stars in the onscreen

widget but are saved in the offscreen widget. This is
done by making the displayed widget’s callbacks
manipulate the offscreen widget’s text.
*/
#include <Pt.h>
#include <stdio.h>
#include <stdlib.h>
int check_passwd(PtWidget_t *, void *, PtCallbackInfo_t *);

int update_passwd(PtWidget_t *, void *, PtCallbackInfo_t *);
PtWidget_t *displayed_text, *offscreen_text;

{
PhRect_t extent;
PhPoint_t pos;
PtArg_t args[2];
int nargs;
PtWidget_t *window, *label;
nargs = 0;
PtSetArg(&args[nargs++], Pt_ARG_MARGIN_HEIGHT, 4, 0);

nargs = 0;
PtSetArg( &args[nargs++], Pt_ARG_TEXT_STRING,
"Enter Text:", 0);
label = PtCreateWidget( PtLabel, Pt_DEFAULT_PARENT,
nargs, args);
PtExtentWidget(label);
PtWidgetExtent(label, &extent);
pos = extent.lr;
pos.x += 4;
pos.y = 0;
/* Create the displayed text widget: */
nargs = 0;

PtSetArg(&args[nargs++], Pt_ARG_POS, &pos, 0);

PtSetArg(&args[nargs++], Pt_ARG_COLUMNS, 20, 0);
displayed_text = PtCreateWidget( PtText, Pt_DEFAULT_PARENT,
nargs, args);
PtAddCallback(displayed_text, Pt_CB_MODIFY_VERIFY,
update_passwd, NULL);
PtAddCallback(displayed_text, Pt_CB_ACTIVATE,
check_passwd, NULL);
/* Create an offscreen text widget: */
pos.x = -1000;
nargs = 0;
PtSetArg(&args[nargs++], Pt_ARG_POS, &pos, 0);
offscreen_text = PtCreateWidget( PtText, Pt_DEFAULT_PARENT,
nargs, args);
PtMainLoop();
}
int check_passwd( PtWidget_t *widget, void *client_data,

PtCallbackInfo_t *info )
{
/* This callback gets the password out of the offscreen

widget. It’s invoked when you activate the displayed
widget (e.g. by pressing Enter). */
PtTextCallback_t *cbs = (PtTextCallback_t

*)info->cbdata;
char *passwd;
PtGetResource( offscreen_text, Pt_ARG_TEXT_STRING,
&passwd, 0 );
if (info->reason_subtype == Pt_EDIT_ACTIVATE)
printf("Password: %s\n", passwd);
return Pt_CONTINUE;
}
int update_passwd( PtWidget_t *widget, void *client_data,

PtCallbackInfo_t *info )
{
/* This callback is invoked when you type in the displayed

widget, but it passes the typing to the offscreen widget.
The characters are replaced by the same number of stars
in the displayed widget.
You need as many stars in the string below as characters

that you allow in the password. */
PtTextCallback_t *tcb = (PtTextCallback_t *)info->cbdata;

static const char stars[] = "********************";
PtSetResource( offscreen_text, Pt_ARG_TEXT_SUBSTRING, tcb, 0 );

tcb->text = stars;
return Pt_CONTINUE;
}

String changes
After you’ve entered the new text into the widget, the Pt_CB_TEXT_CHANGED or
Pt_CB_MODIFY_NOTIFY callback list is invoked. You can use this callback to keep
track of changes after they’ve been made. This is useful in form-filling applications
and text editors to determine if the contents of the text buffer are “dirty” (i.e. the user
modified them).
This callback uses the same text-modification callback structure as the
Pt_CB_MODIFY_VERIFY callback. The text member of this structure contains a
UTF-8 string indicating the current contents of the text widget (i.e. the entire text
buffer).
As an example, you can use this callback in form-filling applications to provide a
visual cue to indicate that one or more fields within the form have changed. The user
then knows that the pending changes won’t take effect until they’re applied, usually by
pressing an Apply or OK button.
To use this callback in this way:
1 Create the form, including the Apply and Cancel buttons. The Apply button
should have the Pt_GHOST and Pt_BLOCKED bits set in its Pt_ARG_FLAGS
resource (see PtWidget) to give it an inactive or disabled appearance.
2 Attach a callback function to the Pt_CB_TEXT_CHANGED callback list. Make

sure this callback turns off the Pt_GHOST and Pt_BLOCKED bits for the Apply
button.
Another possibility is to create a check button beside each field in the form when the
user alters the field’s contents. Activating the check button causes the new value to
take effect.
Focus callbacks
The text widget inherits callbacks from PtBasic that tell your application either that
the text widget has gained or lost focus.
The text widget gains focus when the user either clicks on the text widget or presses
the Tab key to move from another widget into this one.
When the text widget obtains the focus by either of these two means, any callbacks
defined in its Pt_CB_GOT_FOCUS callback list are called. This is useful if your
application wishes to alter the appearance of a text widget that the user is entering text
into, or to trigger the update of a status field providing hints to a user using a “novice”
mode of the interface.
The Pt_CB_LOST_FOCUS callback is invoked any time the user switches focus
away from the text widget, either by tabbing to or clicking within another widget. You
can use this callback to undo any change in the text widget’s appearance that the
application made to indicate that the widget had focus. The callback can also be useful
in checking any syntax in the fields within a form.

Cursor-movement callbacks
You can track changes to the text cursor position representing the current insertion
point by adding a cursor movement callback to the Pt_CB_MOTION_VERIFY
callback list. The callback is invoked every time:
• You move the cursor by using the arrow keys.

Or:
• You click the SELECT pointer button.

Or:
• Your application calls a widget convenience function that modifies the text buffer,
causing the cursor to be moved.
The reason member given in the callback info for this callback is
Pt_CB_MOTION_VERIFY. The event member indicates the type of action that caused
You can determine the type of action that caused the callback to be invoked by making
a comparison on the event member. If it’s set to NULL, the callback was invoked as a
result of an application function call. Otherwise, the callback was invoked as a result
of a user action (such as a pointer button press or keypress event).
The event member is a pointer to a PhEvent_t structure (see the Photon Library
Reference) that describes the user’s action. To differentiate between a pointer event
and a keypress event, look at the type of that event.
The cbdata member of info is a pointer to the same type of text-modification callback
structure used by the other text widget callbacks. This callback uses the cur_insert,
new_insert, and doit members of the structure. Your application can set the doit
member to zero to prevent the cursor movement from taking place.
Activate callback
The PtText widget inherits an activate callback from PtBasic, Pt_CB_ACTIVATE,
that’s invoked when one of the following occurs:
• You press the Enter key within the widget. This signals that any changes to the field
are complete and your application can use the new value.
The reason_subtype in the callback information is Pt_EDIT_ACTIVATE. The
callback data is a pointer to the same text-modification callback structure as used
by the text-modification callbacks. The text member of that structure contains a
UTF-8 string indicating the contents of the buffer.
• You click on the widget and Pt_SELECTABLE is set in its Pt_ARG_FLAGS. In this
case, the reason_subtype in the callback information is 0, and the callback is as
described for PtBasic.
• You modified the text, moved focus to another widget, and

Pt_CHANGE_ACTIVATE is set in the text widget’s Pt_ARG_TEXT_FLAGS.

The reason_subtype in the callback information is Pt_CHANGE_ACTIVATE. The

callback data is a pointer to the same text-modification callback structure as used
by the text-modification callbacks. The text member of that structure contains a
UTF-8 string indicating the contents of the buffer.
The reason code in the callback information is always Pt_CB_ACTIVATE.

When only one text field is contained within a container widget (e.g. a dialog), the
activate callback is often chained to the activate action on the dialog. In other words,
for a prompt dialog, typing a new value in the text field and pressing the Enter key has
the same effect as pressing the dialog’s OK button after entering the new value.
Edit masks
The PtText widget provides an edit mask that lets you specify a pattern for the text
entered into the text field. Any characters that you type must conform to this pattern or
they’re rejected.
Edit masks can be difficult to use and aren’t very flexible; use a
Pt_CB_MODIFY_VERIFY callback instead.
The string entered into a data-entry field often conforms to some format. The text
widget can use an edit mask to ensure that the information is in the correct format.
You can provide a single edit mask for the text widget by setting the
Pt_ARG_EDIT_MASK resource. This resource is a null-terminated text string that
acts as a template for text entered in the text field. Each character that you type must
match the corresponding character in the edit mask.
Here are the characters that you can specify in the edit mask, along with the characters
they match:
This character: Matches:

# Any single numeric digit
X Any character (don’t care)
A Any alphabetic character (the letters A-Z)
n Any alphanumeric character (the letters A-Z or any numeric
digit). All alphabetic characters are converted to lowercase.
N Any alphanumeric character (the letters A-Z or any numeric
digit). All alphabetic characters are converted to uppercase.
c Any alphabetic character (the letters A-Z). All characters are
converted to lowercase.
continued. . .

This character: Matches:

C Any alphabetic character (the letters A-Z). All characters are
converted to uppercase.
d Any alphanumeric character (the letters A-Z or any numeric
digit), but without case conversion.
Any other character that appears in the edit mask is assumed to be a constant character
that must appear at that position in the text field. When you’ve typed enough
characters to reach that position, the character is automatically inserted. After that,
you can’t delete or alter it.
As an example, Canadian postal codes must consist of uppercase alphabetic characters
and numbers in the following order: character, digit, character, space, digit, character,
digit. For example, QNX Software System’s postal code is K2M 1W8. So, a text field
for entering a postal code might specify C#C #C# as the edit mask. The text field
widget enforces the constraints on the characters you type and automatically adds the
space character.
Mouse actions
If you: The widget:

Press the mouse button Gets input focus
Press the mouse button and drag the mouse Extends the text selection
Release the mouse button Ends the text selection
Keyboard actions
If you press: The widget:

Any character Inserts the typed character
→ Moves the cursor to the right
← Moves the cursor to the left
Home Moves the cursor to the beginning of the line
End Moves the cursor to the end of the line
Shift-→ Extends the text selection to the right
Shift-← Extends the text selection to the left
Shift-Home Extends the text selection to the beginning of the line
continued. . .

If you press: The widget:

Shift-End Extends the text selection to the end of the line
Backspace Deletes the previous character
Delete Deletes the current character
Enter Processes the text
Tab Moves the cursor to the next text field
Shift-Tab Moves the cursor to the previous text field
Ctrl-→ Moves the cursor to the next word
Ctrl-← Moves the cursor to the previous word
Ins Toggles between insert and replace modes
Drag and Drop

New resources:

Pt_ARG_COLUMNS short Scalar 0
Pt_ARG_CURSOR_POSITION int Scalar -1
Pt_ARG_EDIT_MASK char * String NULL
Pt_ARG_MAX_LENGTH signed int Scalar SHRT_MAX
Pt_ARG_SELECTION_RANGE See below Complex See below
Pt_ARG_TEXT_CURSOR_WIDTH char Scalar 1
Pt_ARG_TEXT_FLAGS unsigned long Flag Pt_CURSOR_VISIBLE | Pt_EDITABLE |
Pt_INSERT_MODE |
Pt_TEXT_BLINKING_CURSOR
Pt_ARG_TEXT_HIGHLIGHT_BACKGROUND_COLOR PgColor_t Scalar Pt_DEFAULT_COLOR
Pt_ARG_TEXT_HIGHLIGHT_TEXT_COLOR PgColor_t Scalar Pt_DEFAULT_COLOR
Pt_ARG_TEXT_SUBSTRING See below Complex See below

Pt_CB_MODIFY_NOTIFY PtCallback_t * Link NULL
continued. . .


Pt_CB_MODIFY_VERIFY PtCallback_t * Link NULL
Pt_CB_MOTION_NOTIFY PtCallback_t * Link NULL
Pt_CB_MOTION_VERIFY PtCallback_t * Link NULL
Pt_CB_TEXT_CHANGED PtCallback_t * Link NULL
Pt_ARG_COLUMNS
short Scalar 0
The number of “M” characters that fit in the field horizontally. The widget uses this
resource only if the width component of the Pt_ARG_DIM resource is 0.
Pt_ARG_CURSOR_POSITION
int Scalar -1
The cursor position. A value of 0 indicates that the cursor is placed before the first
character, 1 before the second character, and so on.
Pt_ARG_EDIT_MASK
char * String NULL
A string that serves as an input filter for the text field. Each character in the string
determines the acceptable input for the corresponding character position in the text
field. The edit mask can contain the following:
X Any character.
A Alphabetic characters only.
# Numeric characters only.
d Alphanumeric characters.
N Alphanumeric characters. All alphabetic characters are converted

to uppercase.
n Alphanumeric characters. All alphabetic characters are converted

to lowercase.

C Alphabetic characters only. All alphabetic characters are converted

to uppercase.
c Alphabetic characters only. All alphabetic characters are converted
to lowercase.
Anything else Treated as a place holder, and appears as is, without alteration, in
the text field. The cursor “steps over” place holders.
See “Edit masks,” above.
Edit masks can be difficult to use and aren’t very flexible; use a
Pt_CB_MODIFY_VERIFY callback instead.
Pt_ARG_MAX_LENGTH
signed int Scalar SHRT_MAX
The maximum text length that the widget accepts.
Pt_ARG_SELECTION_RANGE
See below Complex See below
You can use this resource to select a range of text or determine what text is currently
selected. This resource is complex, and requires special handling:
• When setting, set the value argument to PtSetArg() to the address of a

PtTextControl_t structure. Use the start_pos and end_pos members of the
structure to indicate the range of text to be highlighted (selected). If end_pos is -1
or beyond the end of the string, the widget sets the end of the range to the last
character position of its text. Always set the doit member to 1.
• When getting, set the value to the address of a pointer to a PtTextControl_t

structure. The widget sets the start_pos and end_pos members to hold the
currently highlighted selected range. If no range is currently selected, start_pos is
-1. Don’t free() this structure.
The len isn’t used when setting or getting this resource.

You can call PtTextGetSelection() or PtTextSetSelection() instead of using this
resource.

Pt_ARG_TEXT_CURSOR_WIDTH

char Scalar 1
The width, in pixels, of the cursor.
Pt_ARG_TEXT_FLAGS
unsigned long Flag Pt_CURSOR_VISIBLE | Pt_EDITABLE |
Pt_INSERT_MODE |
Valid flags:
Pt_CHANGE_ACTIVATE
If the text is changed and the widget loses focus, invoke the
Pt_CB_ACTIVATE callback with the Pt_CHANGE_ACTIVATE
subtype.
For more information, see the description of Pt_CB_ACTIVATE in
“Inherited resources,” below.
Pt_CURSOR_VISIBLE
Display the cursor. Default is on.
Pt_EDITABLE Make the text editable. Default is on.
Pt_INSERT_MODE
Toggle insert/replace mode. Default is insert (on).
Pt_NO_DRAG_SELECTION
Disable text selection by dragging. Text selection using the
keyboard is still enabled. This option is useful for optimizing
applications running on touchscreen devices. Default is off.
Pt_TEXT_AUTO_HIGHLIGHT
Highlight the text when the widget is given focus. Default is off.
Set the cursor to blink when the widget has focus. Default is on.

Pt_ARG_TEXT_HIGHLIGHT_BACKGROUND_COLOR

PgColor_t Scalar Pt_DEFAULT_COLOR
The background color for highlighting. See PgColor_t in the Photon Library
Reference.
If you set this resource to Pt_DEFAULT_COLOR, the widget uses the default
background color.
Pt_ARG_TEXT_HIGHLIGHT_TEXT_COLOR
PgColor_t Scalar Pt_DEFAULT_COLOR
The text color for highlighting. See PgColor_t in the Photon Library Reference.
If you set this resource to Pt_DEFAULT_COLOR, the widget uses the default text color.
Pt_ARG_TEXT_SUBSTRING
See below Complex See below
You can use this resource to get or set a substring of the widget’s text. It’s a complex
resource, so it needs special handling:
• When setting, set the value argument to PtSetArg() to the address of an instance of
a PtTextControl_t structure that defines which characters are to be deleted and
which are to be inserted. Set the members as follows:
- start_pos — the beginning of the range to delete, or -1 if you don’t want delete
any text.
- end_pos — the end of the range to delete, or -1 if you don’t want delete any text.
- cur_insert — the position at which to insert the new text.
- length — the number of multibyte characters to add.
- text — a pointer to the text to add.
Instead of setting this resource, you can call PtTextModifyText().
• When getting, set the value to the address of a PtTextControl_t structure. Set
the start_pos and end_pos to the beginning and end of the substring you want.
When you get the resource, the length member is the number of multibyte
characters in the substring, and text points to the range in the widget’s internal
memory. The cur_insert is set to the current insert position of the widget.

You don’t use the len argument to PtSetArg() when setting or getting this resource.
Pt_CB_MODIFY_NOTIFY or Pt_CB_TEXT_CHANGED
after the value of the text string changes.
It doesn’t matter which name you use for this resource.
If you’ve set the Pt_CALLBACKS_ACTIVE bit in the widget’s Pt_ARG_FLAGS

resource, these callbacks are also invoked when your application changes the text is
changed by calling PtSetResource(), PtSetResources(), or a convenience function such
as PtTextModifyText().
following members:
reason Pt_CB_MODIFY_NOTIFY

cbdata A pointer to a PtTextCallback_t structure that contains at

int cur_insert; The position of the cursor along the string. A

value of 0 indicates that the cursor is to the left
of the first character, 1 to the right of the first
char *text; The text string.
int length; The length of the text string (not including the
NULL).
For more information, see “Text-modification callbacks,” above.

Pt_CB_MODIFY_VERIFY

before the value of the text string changes. To alter the input to the widget, you can
modify the members of the callback structure.
resource, these callbacks are also invoked when your application changes the text is
changed by calling PtSetResource(), PtSetResources(), or a convenience function such
as PtTextModifyText().
following members:
reason Pt_CB_MODIFY_VERIFY

unsigned int start_pos;

unsigned int end_pos;
All characters starting at start_pos up to but
not including end_pos are being deleted. If
start_pos and end_pos are equal, no
characters are being deleted.
int cur_insert; The position at which text is being inserted. A
value of 0 indicates that the text is being
inserted to the left of the first character, 1 to
int new_insert; Where the cursor will be after the changes are
applied.
int length; The number of characters to be inserted. If
length is zero, no text is being inserted.
int doit; Indicates whether or not this modification will
be applied to the widget. If doit is zero, the
widget discards the modification. If doit is
nonzero, the widget uses the contents of the
callback structure to modify itself.
For more information, see PtTextModifyText().

Pt_CB_MOTION_NOTIFY

after it repositions the cursor.
resource, these callbacks are also invoked when your application repositions the cursor
by calling PtSetResource() or PtSetResources().
following members:
reason Pt_CB_MOTION_NOTIFY

cbdata A pointer to a PtTextCallback_t structure.
Pt_CB_MOTION_VERIFY
before it repositions the cursor. You can use this callback resource to modify or even
disallow cursor repositioning.
resource, these callbacks are also invoked when your application repositions the cursor
by calling PtSetResource() or PtSetResources().
following members:
reason Pt_CB_MOTION_VERIFY



int cur_insert; The current position of the cursor. A value of

0 indicates that the cursor is to the left of the
first character, 1 to the right of the first
int start_pos;
int end_pos;
int new_insert; All these indicate the destination of the
cursor. A value of 0 indicates that the cursor
will be to the left of the first character, 1 to the
right of the first character, and so on.
char *text; The string beginning at cur_insert.
int length; The number of characters from the selected
character to the end of the segment.
int doit; Indicates whether or not this modification will
be applied to the widget. If doit is zero, the
cursor remains at cur_insert. If doit is
nonzero, the cursor will be repositioned at
new_insert.

Pt_ARG_ACCEL_KEY PtLabel Not used by this class.
continued. . .


Pt_ARG_CURSOR_TYPE PtWidget Ph_CURSOR_INSERT
Pt_ARG_DIM PtWidget
Pt_ARG_EFLAGS PtWidget |= Pt_CONSUME_EVENTS
Pt_ARG_FILL_COLOR PtBasic Pg_GRAY
Pt_ARG_FLAGS PtWidget |=Pt_SET|
Pt_HIGHLIGHTED|
Pt_GETS_FOCUS
Pt_ARG_LABEL_FLAGS PtLabel &=˜Pt_LABEL_SELECT_SHIFT
Pt_ARG_LABEL_IMAGE PtLabel Not used by this class.
Pt_ARG_LABEL_TYPE PtLabel Not used by this class.
continued. . .


Pt_ARG_LINE_SPACING PtLabel Not used by this class.
Pt_ARG_POS PtWidget
Pt_ARG_RESIZE_FLAGS PtWidget Pt_RESIZE_Y_AS_REQUIRED|
Pt_RESIZE_Y_INITIAL
Pt_ARG_UNDERLINE_TYPE PtLabel Not used by this class.
Pt_ARG_UNDERLINE1 PtLabel Not used by this class.
Pt_ARG_UNDERLINE2 PtLabel Not used by this class.
Pt_ARG_VERTICAL_ALIGNMENT PtLabel Pt_CENTER
continued. . .


Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_GOT_FOCUS PtBasic See below.
Pt_CB_LOST_FOCUS PtBasic See below.
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
Pt_CB_ACTIVATE
Pt_CB_ACTIVATE is inherited from PtBasic, but its behavior is different for a
PtText widget. Each callback is passed a PtCallbackInfo_t structure that
reason_subtype Indicates why the callback was invoked:

• 0 — you clicked on the widget and it has Pt_SELECTABLE set
in its Pt_ARG_FLAGS.
• Pt_EDIT_ACTIVATE — you pressed Enter in the text field.
• Pt_CHANGE_ACTIVATE — you modified the text, gave focus
to another widget, and Pt_CHANGE_ACTIVATE is set in the
widget’s Pt_ARG_TEXT_FLAGS.


cbdata If reason_subtype is 0, the callback data is as described for the

Pt_CB_ACTIVATE resource for PtBasic.
If reason_subtype is Pt_EDIT_ACTIVATE or
Pt_CHANGE_ACTIVATE, cbdata points to a
PtTextCallback_t structure that contains at least the
following members:
• int cur_insert — the position of the cursor along the string
at the time the user pressed Enter. A value of 0 indicates that
• char *text — the text string.
• int length — the length of the text string (not including the
\0).
Pt_CB_GOT_FOCUS, Pt_CB_LOST_FOCUS
Pt_CB_GOT_FOCUS and Pt_CB_LOST_FOCUS are inherited from PtBasic, but
the callback data is different for a PtText widget. Each callback is passed a
reason Pt_CB_GOT_FOCUS or Pt_CB_LOST_FOCUS

• int cur_insert — the position of the cursor along the string
at the time the user pressed Enter. A value of 0 indicates that
• char *text — the text string.
• int length — the length of the text string (not including the
\0).
The Pt_CB_GOT_FOCUS callbacks should return Pt_CONTINUE.

The Pt_CB_LOST_FOCUS callbacks should return:

Or:

The PtText widget defines the following convenience functions and data structures
that make it easier to use the widget once it’s been created:
PtTextCallback_t, PtTextControl_t, PtTextControlInfo_t

Information passed to PtText callbacks
PtTextGetSelection()
Get the selected range from a PtText widget.
PtTextModifyText()
Modify the contents of a PtText widget.
PtTextSetSelection()
Set the selected range for a PtText widget.

© 2010, QNX Software Systems GmbH & Co. KG. PtTextCallback_t,
PtTextControl_t, PtTextControlInfo_t
Information passed to PtText callbacks
Synopsis:
typedef struct Pt_text_callback {
int start_pos;
int end_pos;
int cur_insert;
int new_insert;
int length;
short reserved;
char *text;
int doit;
} PtTextCallback_t;
typedef PtTextCallback_t PtTextControl_t;
typedef PtTextControl_t PtTextControlInfo_t;
Description:
PtTextCallback_t, PtTextControl_t, and PtTextControlInfo_t are
different names for the same structure. They’re used in callbacks for PtText widgets
as well as to specify actions or request data. The members of these structures are:
start_pos The start position of the affected range of text.
end_pos The end position of the affected range of text.
cur_insert The character position where the cursor was located at the time of the
change.
new_insert The character position where the cursor will be located after the
change.
length The number of multibyte characters in the text string that’s about to be
added to the widget.
text A pointer to length characters to be added to the widget.
doit Indicates whether or not the change should be made to the widget’s
text. In a Pt_CB_MODIFY_VERIFY callback, you can prevent the
text from being added to the widget by setting doit or length to zero.
Classification:
Photon
See also:
PtMultiTextCallback_t

PtTextGetSelection() © 2010, QNX Software Systems GmbH & Co. KG.
Get the selected range from a PtText widget
Synopsis:
int PtTextGetSelection( PtWidget_t *widget,
int *start,
int *end );
Description:
This function gets the currently selected range from a PtText widget. It returns the
number of characters currently selected and sets the provided integers to the actual
range. All characters from start up to but not including end are currently selected.
Both start and end are 0-based. So, for example, if start returns as 0, it indicates the
first character in the widget’s text buffer.
Returns:
The number of characters currently selected, or -1 if the specified widget isn’t a
PtText widget.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtText, PtTextSetSelection()

© 2010, QNX Software Systems GmbH & Co. KG. PtTextModifyText()
Modify the contents of a PtText widget
Synopsis:
int PtTextModifyText( PtWidget_t *widget,
int start,
int end,
int insert_pos,
char const *text,
int length );
Description:
This function modifies the contents of a PtText widget.
If start doesn’t equal end, then:
• All characters from start up to, but not including, end are deleted.
• The widget’s current insert position is set to the lesser of start and end.
• The insert_pos argument is ignored.
If start does equal end, then:
• No text is deleted.
• The widget’s current insert position is set to insert_pos; if insert_pos equals -1, the
current insert position is set to the end of the widget’s text buffer.
Both start and end are 0-based. So, for example, if start is 0, it indicates the first
character in the widget’s text buffer.
Once the current insert position is set, the function inserts length characters from text.
It does this regardless of the widget’s insert mode. If length is zero, no text is inserted.
This function causes a nondestructive deselect before attempting the changes. If the
widget has the Pt_CALLBACKS_ACTIVE bit set in its Pt_ARG_FLAGS resource, it
then invokes its Pt_CB_MODIFY_VERIFY callbacks, if any. These callbacks might
do one of the following:
• Cause the changes to be discarded.

Or:
• Modify the text to be inserted and/or deleted before this function applies the
changes.
If this call results in a change to the widget’s text (and Pt_CALLBACKS_ACTIVE is

set), the widget invokes its Pt_CB_MODIFY_NOTIFY or Pt_CB_TEXT_CHANGED
callbacks, if any.

PtTextModifyText() © 2010, QNX Software Systems GmbH & Co. KG.
Returns:
1 The widget’s text was changed.
0 No change occurred.
-1 The widget is NULL or isn’t a PtText widget.
Classification:
Photon
Safety
Signal handler No
Thread No

© 2010, QNX Software Systems GmbH & Co. KG. PtTextSetSelection()
Set the selected range for a PtText widget
Synopsis:
int PtTextSetSelection( PtWidget_t *widget,
int *start,
int *end );
Description:
This function sets the selected range for a PtText. When the function completes
successfully, start and end contain the range actually selected (start < end). These
values may differ from the original values you specified if:
• The start value you specified was greater than end.

Or:
• The range you specified exceeded the bounds of the widget’s text.
Both start and end are 0-based. So, for example, if start is 0, it indicates the first
character in the widget’s text buffer.
This function causes a nondestructive deselect of the currently selected range, if there
is one.
Here’s how a selected range behaves:
• If you move the text cursor (via arrow keys or a mouse click), the range is
deselected nondestructively.
• If you perform an action that would modify the widget’s text in any way, the range
is deleted and replaced by your input. If that input is Del or a delete backspace
(DBS on many keyboards), the range is simply deleted.
Returns:
The number of characters successfully selected (which may be 0 if *start equals *end
or if *start and *end are both greater than the number of characters in the widget), or
-1 if the specified widget isn’t a PtText widget.
Classification:
Photon
Safety
Signal handler No
Thread No

PtTextSetSelection() © 2010, QNX Software Systems GmbH & Co. KG.
See also:
PtText, PtTextGetSelection()

© 2010, QNX Software Systems GmbH & Co. KG. PtTimer
A widget that invokes a callback after a given length of time
Class hierarchy:
PtWidget → PtTimer
PhAB icon:
Public header:
<photon/PtTimer.h>
Description:
A PtTimer widget invokes a callback after an initial and repeated time period, given
in milliseconds. This widget is intended to provide a non-accurate, resourceless time
base for your application. To disable the timer, set Pt_ARG_TIMER_INITIAL to 0 or
unrealize the widget.
When you create a PtTimer widget in PhAB, it appears as a black box. The box
doesn’t appear when you run the application; it’s just a placeholder.
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. For more
information, see “Timers” in the Working with Code chapter of the Photon
New resources:

Pt_ARG_TIMER_INITIAL unsigned long Scalar 0
Pt_ARG_TIMER_REPEAT unsigned long Scalar 0
Pt_CB_TIMER_ACTIVATE PtCallback_t * Link NULL
Pt_ARG_TIMER_INITIAL
The time, in milliseconds, before the first timer callback is activated.

PtTimer © 2010, QNX Software Systems GmbH & Co. KG.
Pt_ARG_TIMER_REPEAT

The time, in milliseconds, for the repeat rate of the timer once the initial time period
has expired.
Pt_CB_TIMER_ACTIVATE
when the timer has expired.
following members:
reason Pt_CB_TIMER_ACTIVATE

• Pt_TIMER_INITIAL
• Pt_TIMER_REPEAT

cbdata NULL.

continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtTimer

Pt_ARG_AREA PtWidget Not used by this class.
Pt_ARG_BITMAP_CURSOR PtWidget Not used by this class.
Pt_ARG_BEVEL_WIDTH PtWidget Not used by this class.
Pt_ARG_CURSOR_COLOR PtWidget Not used by this class.
Pt_ARG_CURSOR_TYPE PtWidget Not used by this class.
Pt_ARG_DIM PtWidget Not used by this class.
Pt_ARG_EFLAGS PtWidget Not used by this class.
Pt_ARG_EXTENT PtWidget Not used by this class.
Pt_ARG_HEIGHT PtWidget Not used by this class.
Pt_ARG_HELP_TOPIC PtWidget Not used by this class.
Pt_ARG_MAXIMUM_DIM PtWidget Not used by this class.
Pt_ARG_MINIMUM_DIM PtWidget Not used by this class.
Pt_ARG_POS PtWidget Not used by this class.
Pt_ARG_RESIZE_FLAGS PtWidget Not used by this class.
Pt_ARG_WIDTH PtWidget Not used by this class.
Pt_CB_BLOCKED PtWidget Not used by this class.
Pt_CB_DND PtWidget
Pt_CB_FILTER PtWidget Not used by this class.
Pt_CB_HOTKEY PtWidget Not used by this class.
Pt_CB_OUTBOUND PtWidget Not used by this class.
Pt_CB_RAW PtWidget Not used by this class.

PtToggleButton © 2010, QNX Software Systems GmbH & Co. KG.
A toggle switch that’s either off or on
Class hierarchy:
PtWidget → PtBasic → PtLabel → PtButton → PtToggleButton
PhAB icon:
Public header:
<photon/PtToggleButton.h>
Description:
A PtToggleButton widget is like a toggle switch, although it behaves like a button.
It has on and off states, and pressing the button inverts the current state of the button.
Various button styles supported by PtToggleButton.
Creating toggle buttons

Toggle buttons inherit resources from PtLabel and PtButton; specify the label for
toggle buttons the way you do for these classes.
A toggle button is displayed as a button with a label beside it. The button is either set
or unset, and you can control its appearance with the Pt_ARG_INDICATOR_COLOR
and Pt_ARG_INDICATOR_TYPE resources. You can set the position of the text
relative to the button with the Pt_ARG_BALLOON_POSITION resource.
You can also set Pt_ARG_ARM_COLOR, which specifies the fill color for the
button’s interior when the button is set. This resource is used only if the value of
Pt_ARG_ARM_FILL is Pt_TRUE. These resources are inherited from PtButton.
To determine whether or not the button is set, check the:
• Pt_SET bit in the Pt_ARG_FLAGS resource — see PtWidget
• Callback data passed to the Pt_CB_ACTIVATE callbacks — see PtBasic.

© 2010, QNX Software Systems GmbH & Co. KG. PtToggleButton
Grouping toggle buttons

A group can control how several toggle buttons behave together. If you place the
toggle buttons in a group and make them mutually exclusive, they behave like the
channel-selector buttons on a car radio: only one of the buttons can be set at any given
time, and setting any button automatically unsets the button that’s currently set.
To make a group of toggle buttons mutually exclusive, set the Pt_GROUP_EXCLUSIVE
bit in the group’s Pt_ARG_GROUP_FLAGS resource. For example:
PtSetArg (&argt[n], Pt_ARG_GROUP_FLAGS, Pt_TRUE,

Pt_GROUP_EXCLUSIVE );
n++;
PtSetArg (&argt[n], Pt_ARG_GROUP_ORIENTATION,
Pt_GROUP_VERTICAL, 0 ) ;
n++;
group = PtCreateWidget (PtGroup, parent, n, argt );
PtSetArg (&argt[0], Pt_ARG_TEXT_STRING,

"Button 1", 0 ) ;
button1 = PtCreateWidget (PtToggleButton, group,
1, argt ) ;

"Button 2", 0 ) ;
1, argt ) ;

"Button 3", 0 ) ;
1, argt ) ;
PtRealizeWidget ( group ) ;
You can use the same callback for all the buttons, but how do you determine which
one is selected? There are several ways:
• Specify a Pt_CB_ACTIVATE callback (see PtBasic) for the group. The PtGroup
adds its callback to each of its children; when the callback is invoked, the widget
argument is a pointer to the selected button, not the group. You can compare the
pointer to previously saved pointers to the buttons.
Or:
• Store a unique value in each button’s Pt_ARG_USER_DATA resource (see

PtWidget). In the callback, get this resource and use its value to determine which
button was pressed.
Or:
• If you create the buttons in code (instead of in PhAB), you can pass a unique value
in the client_data argument to the callback routine.

New resources:

Pt_ARG_INDICATOR_COLOR PgColor_t Scalar Pg_WHITE
Pt_ARG_INDICATOR_TYPE unsigned char Scalar Pt_TOGGLE_CHECK
Pt_ARG_INDICATOR_COLOR
The fill color for the toggle button’s indicator. See PgColor_t in the Photon Library
Reference.
Pt_ARG_INDICATOR_TYPE
unsigned char Scalar Pt_TOGGLE_CHECK
Determines how the indicator is drawn. Possible values:
• Pt_TOGGLE_RADIO
• Pt_TOGGLE_CHECK
• Pt_TOGGLE_OUTLINE
Here’s how these types look, both set and unset:


Pt_ARG_ARM_FILL PtButton
Pt_ARG_DIM PtWidget
continued. . .


Pt_ARG_FLAGS PtWidget |=Pt_SELECTABLE| Pt_TOGGLE
Pt_ARG_LABEL_IMAGE PtLabel Not used by this class.
Pt_ARG_LABEL_TYPE PtLabel Not used by this class.
Pt_ARG_POS PtWidget
continued. . .


Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

PtToolbar © 2010, QNX Software Systems GmbH & Co. KG.
Superclass for toolbar widgets
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtToolbar
• PtMenuBar
PhAB icon:
Public header:
<photon/PtToolbar.h>
Description:
A PtToolbar is a container that organizes its children as a horizontal (by default) or
vertical toolbar.
A PtToolbar as used in PhAB.
The children of a PtToolbar can be any type of widget. They’re center-aligned

within the toolbar, and can optionally be separated from each other with etched lines:
New resources:

Pt_ARG_ORIENTATION char Boolean Pt_HORIZONTAL
Pt_ARG_TOOLBAR_FLAGS uint16_t Flag Pt_TOOLBAR_DRAGGABLE |
Pt_TOOLBAR_END_SEPARATOR |
Pt_TOOLBAR_FOLLOW_FOCUS
Pt_ARG_TOOLBAR_LAYOUT_FLAGS uint8_t Flag 0

Pt_ARG_TOOLBAR_SPACING uint8_t Scalar 2

© 2010, QNX Software Systems GmbH & Co. KG. PtToolbar
Pt_ARG_ORIENTATION

char Boolean Pt_HORIZONTAL
Indicates whether the toolbar is to be drawn vertically or horizontally. Possible values:
• Pt_HORIZONTAL
• Pt_VERTICAL
Pt_ARG_TOOLBAR_FLAGS
uint16_t Flag Pt_TOOLBAR_DRAGGABLE |
Pt_TOOLBAR_END_SEPARATOR |
Flags that control the behavior of the widget. Any combination of:
Pt_TOOLBAR_DRAGGABLE
Enable dragging operations.
Pt_TOOLBAR_REVERSE_LAST_ITEM
Right- or bottom-align the frontmost (i.e. last) item.
Pan the toolbar as focus changes within it.
Pt_TOOLBAR_LOCK_ORIENTATION
Don’t let the orientation change.
Pt_TOOLBAR_ITEM_SEPARATORS
Render separators between all items.
Pt_TOOLBAR_END_SEPARATOR
Render a separator after the last item.
Pt_ARG_TOOLBAR_LAYOUT_FLAGS
uint8_t Flag 0
Flags that PtToolbarGroup uses to record the toolbar’s layout:

Pt_TOOLBAR_FROM_LINE_START
Start the toolbar on a new line.
Pt_TOOLBAR_TO_LINE_END
Run the toolbar to the end of the line.
Pt_ARG_TOOLBAR_SPACING
uint8_t Scalar 2
The spacing, in pixels, between items in the toolbar.

Pt_ARG_BASIC_FLAGS PtBasic (& ˜Pt_FLAT_FILL) | Pt_REVERSE_GRADIENT
Pt_ARG_BEVEL_CONTRAST PtBasic 65
Pt_ARG_CONTAINER_FLAGS PtContainer |= Pt_AUTO_EXTENT
Pt_ARG_CONTRAST PtBasic 10
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtToolbar

Pt_ARG_DIM PtWidget
Pt_ARG_POS PtWidget
continued. . .


Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

© 2010, QNX Software Systems GmbH & Co. KG. PtToolbarGroup
A group of toolbars
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtToolbarGroup
PhAB icon:
Public header:
<photon/PtToolbarGroup.h>
Description:
A PtToolbarGroup is a container that manages its children, which must be of the
PtToolbar class or one of its subclasses.
A PtToolbarGroup.
You can drag the toolbars in the group to expand or shrink them.
New resources:

Pt_ARG_ORIENTATION char Scalar Pt_HORIZONTAL
Pt_ARG_TG_FLAGS uint16_t Flag 0
Pt_ARG_ORIENTATION
char Scalar Pt_HORIZONTAL
Indicates whether the toolbar group is to be drawn vertically or horizontally. Possible

values:
• Pt_HORIZONTAL
• Pt_VERTICAL

PtToolbarGroup © 2010, QNX Software Systems GmbH & Co. KG.
This resource overrides the orientation specified for the toolbar group’s children.
Pt_ARG_TG_FLAGS
uint16_t Flag 0
Flags that control the behavior of the widget:
Pt_TG_COLLAPSIBLE
Toolbars are collapsible. If this bit is set, you can click on a toolbar’s drag
handle to minimize the toolbar to a thin bar.

Pt_ARG_BASIC_FLAGS PtBasic &= ˜Pt_ALL_BEVELS, |=
Pt_ALL_OUTLINES
Pt_ARG_CONTAINER_FLAGS PtContainer |= Pt_AUTO_EXTENT
continued. . .

© 2010, QNX Software Systems GmbH & Co. KG. PtToolbarGroup

Pt_ARG_DIM PtWidget
Pt_ARG_POS PtWidget
continued. . .

PtToolbarGroup © 2010, QNX Software Systems GmbH & Co. KG.

Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget

© 2010, QNX Software Systems GmbH & Co. KG. PtTree
A tree of items that collapse and expand as requested
Class hierarchy:
PtGenTree → PtTree
PhAB icon:
Public header:
<photon/PtTree.h>
Description:
The PtTree widget displays a tree of items that collapse or expand according to your
selections. PtTree assumes that each tree item contains two images and a string.
A PtTree widget, as used in the Helpviewer.
Allocating items and building a tree

The items in a PtTree are stored in structures of type PtTreeItem_t, which you
should allocate by calling PtTreeAllocItem() or PtTreeCreateItem(). The PtTree
widget frees all its items automatically when it’s destroyed.
The item structure contains a “user data” pointer that you can use to store any data you
want to associate with the item; the widget ignores this pointer. There are some
functions that free items, but none of them attempts to free the user data.
PtTreeAllocItem() takes as arguments:

PtTree © 2010, QNX Software Systems GmbH & Co. KG.
• a pointer to the tree widget — this must be the same widget that the item will be
added to
• the text to display for the item
• indexes of images to use when the item is “set” and “unset” — we’ll look at these
later.
This function uses the font and image list stored in the tree widget to determine the
item’s dimensions. This means that between creating an item and adding it to the
widget, you mustn’t change the widget’s font or images.
PtTreeCreateItem() is similar to PtTreeAllocItem(), except instead of the set and unset
image indexes, it takes a pointer to a PtTreeItemAttributes_t structure which
defines the set and unset images, as well as font and color attributes for the item’s text.
Use PtTreeAddFirst() and PtTreeAddAfter() to build a tree. For example, suppose you
wanted to build the following tree:
A PtTree without images.
Assuming your tree widget is referenced by tree_wgt, use the following code:
PtTreeItem_t *item, *brother;

char *text;
/* Add "Item 1" as first root item */
text = "Item 1";

item = PtTreeCreateItem(tree_wgt, text, NULL);
PtTreeAddFirst(tree_wgt, item, NULL);
brother = item;
/* Add "Item 2" as root item after "Item 1" */
text = "Item 2";

PtTreeAddAfter(tree_wgt, item, brother);
brother = item;
/* Add "Item 2a" as first child of "Item 2" */
text = "Item 2a";

PtTreeAddFirst(tree_wgt, item, brother);
/* Add "Item 3" as root item after "Item 2" */

text = "Item 3";

Using images in tree items

The array of all available images is stored in the widget’s Pt_ARG_TREE_IMAGES
resource; the items contain indexes into this array.
Before allocating the tree items, set up the array of images; PtTreeAddImages()
provides a convenient way to do this.
When you call PtTreeAllocItem() to allocate the tree items, specify the index of the
icons to use when the item is set or unset. To specify the meaning of “set” and “unset”,
use the Pt_ARG_TREE_IMGMASK resource.
Alternatively, you can use PtTreeCreateItem() or PtTreeChangeItem() to assign
images not in the Pt_ARG_TREE_IMAGES resource to a tree item.
Here’s some code that sets up a tree with images:
PtTreeItem_t *item, *brother;
char *text;
int closed_dir, closed_file, open_dir, open_file;
/* Extract the images from a widget database and add them

to the tree’s array of images: */
closed_dir = PtTreeAddImages (tree_wgt,

ApGetImageRes (database, "dir_closed"), 1);
closed_file = PtTreeAddImages (tree_wgt,
ApGetImageRes (database, "file_closed"), 1);
open_dir = PtTreeAddImages (tree_wgt,
ApGetImageRes (database, "dir_open"), 1);
open_file = PtTreeAddImages (tree_wgt,
ApGetImageRes (database, "file_open"), 1);
/* Add "Directory 1" as first root item */
text = "Directory 1";

item = PtTreeAllocItem(tree_wgt, text, open_dir, closed_dir);
PtTreeAddFirst(tree_wgt, item, NULL);
brother = item;
/* Add "Directory 2" as root item after "Directory 1" */

brother = item;
/* Add "My File" as first child of "Directory 2" */
text = "My File";

item = PtTreeAllocItem(tree_wgt, text, open_file, closed_file);
PtTreeAddFirst(tree_wgt, item, brother);
/* Add "Directory 3" as root item after "Directory 2" */


The tree’s Pt_ARG_TREE_IMGMASK is set to Pt_TREE_ITEM_EXPANDED so that

the “open” icon is displayed when the tree item is expanded. The tree looks like this:
A PtTree with images.
Displaying text in columns

To display items in columns, you can:
• Create a PtDivider widget as a child of the PtTree. Put it at the top of the tree,
and create (for example) PtButton widgets as children of the divider, one for each
column. The width of each button is the width of the column.
Or
• Use the Pt_ARG_LIST_COLUMN_POS resource inherited from PtGenList.
With both methods, use the Tab character in the item strings as a column separator.
Even if you use columns, each line in the tree remains a single item. When you select
any part of the line, the entire line is selected — having columns doesn’t make the tree
into a spreadsheet.
Displaying images in columns

You can make your PtTree display clickable images instead of text in selected
columns. Here’s how:
Set the Pt_LIST_COLUMN_NO_STRING flag in the PtGenList column attributes
(Pt_ARG_LIST_COLUMN_ATTR) for each column that you want to display images.
This prevents text from being drawn on top of images. For example:
static const PtListColumnAttributes_t latrs[] = {

{ Pt_LIST_COLUMN_LEFT },
{ Pt_LIST_COLUMN_CENTER | Pt_LIST_COLUMN_NO_STRING }
};
PtSetResource( ABW_tree, Pt_ARG_LIST_COLUMN_ATTR, latrs,

sizeof(latrs) / sizeof(latrs[0]) );
A tab character in an item’s string skips over a column flagged as

Pt_LIST_COLUMN_NO_STRING. For example, if the second column has the flag set,
you need only one tab character between the strings for the first and the third column.
Set up an array of image pointers for each column and an array of tree column
attributes (Pt_ARG_TREE_COLUMN_ATTR):
static const PhImage_t *images[3] = { &image1, &image2,
&image3 };
static const PtTreeColumnAttributes_t tatrs[] = {

/* The first column has no images: */
{ NULL, 0, Pt_TREE_COLUMN_NOCB },
{ images, sizeof(images) / sizeof(images[0]),
Pt_TREE_COLUMN_NOSELECT,
Pt_LIST_ITEM_FLAG_USER1 | Pt_LIST_ITEM_FLAG_USER2
}
};
PtSetResource( ABW_tree, Pt_ARG_TREE_COLUMN_ATTR, tatrs,

sizeof(tatrs) / sizeof(tatrs[0]) );
Optionally, write an image-selector function and attach it to the

Pt_ARG_TREE_COLUMN_IMGFUN resource.
This function takes as arguments a tree item, a column index, and a column attributes
structure, and returns an index into the column’s image array (or -1 for no image). You
need this function only if:
• You need more than two states per column (i.e. either two images to choose from
or one image that can be either present or absent)
Or:
• You want to use something other than an item flag to distinguish between these two
states.
For example:
static int image_selector(
PtWidget_t *widget,
PtTreeItem_t *item,
PtTreeColumnAttributes_t const *cattr,
unsigned cindex )
{
unsigned const flags = item->gen.list.flags;
int result = -1;
/* We don’t really need to check if cindex is one

because we only have one column that displays images.
But for the sake of example... */
if ( cindex == 1 ) {
/* This column has three images and four possible

states (no image is the fourth state).

The function should return -1 for no image and
0...3 to pick an image. */
if ( flags & Pt_LIST_ITEM_FLAG_USER2 )

result += 2;
if ( flags & Pt_LIST_ITEM_FLAG_USER1 )
result += 1;
}
return result;
}
.
.
.
PtSetResource( ABW_tree, Pt_ARG_TREE_COLUMN_IMGFUN,
image_selector, 0 );
Optionally, attach a Pt_CB_TREE_COLUMN_SEL callback that both notifies your

application when you click on a column, and lets you control how the item’s state
changes.
For instance, the following callback makes your items cycle through the four possible
states:
static int column_cb( PtWidget_t *widget, void *data,

PtCallbackInfo_t *cbinfo ) {
PtTreeCallback_t *tcb = cbinfo->cbdata;
if ( tcb->column == 1 ) {
if ( tcb->new_flags & Pt_LIST_ITEM_FLAG_USER1 )
tcb->new_flags ˆ= Pt_LIST_ITEM_FLAG_USER2;
}
return Pt_CONTINUE;
}
New resources:

Pt_ARG_TREE_BALLOON PtTreeBalloonF_t * Pointer See below
Pt_ARG_TREE_COLUMN_ATTR See below Array NULL
Pt_ARG_TREE_COLUMN_IMGFUN See below Pointer See below
Pt_ARG_TREE_IMAGES PhImage_t *, short Array NULL
Pt_ARG_TREE_IMGMASK unsigned Scalar Pt_LIST_ITEM_SELECTED
Pt_CB_TREE_COLUMN_SEL PtCallback_t * Link NULL

Pt_CB_TREE_SELECTION PtCallback_t * Link NULL
Pt_CB_TREE_STATE PtCallback_t * Link NULL

Pt_ARG_TREE_BALLOON

PtTreeBalloonF_t * Pointer See below
A function that inflates a balloon for the item the pointer is on. PtTreeBalloonF_t
is a function type:
typedef PtWidget_t *PtTreeBalloonF_t( PtWidget_t *widget,

PtWidget_t *parent,
PhArea_t *area,
PtListColumn_t *column,
PtTreeItem_t *item,
int coln,
const char *font );
The parameters are as follows:
widget A pointer to the PtTree widget.
parent A pointer to its parent window.
covers the item. The area->pos member is relative to the parent window.
column A pointer to a PtListColumn_t structure that indicates the position of

the column the pointer is on. For information about this structure, see the
Pt_ARG_LIST_COLUMN_POS resource inherited from PtGenList.
item A pointer to the item the pointer is on.
coln The index of the column the pointer is on.
font The value of the widget’s Pt_ARG_LIST_FONT resource.
The default function does this:
return
PtGenListCreateTextBalloon(
widget, parent,
PtGenListSetColumnBalloon ( area, column ),
item->string, coln, font);
Pt_ARG_TREE_COLUMN_ATTR

Attributes for the tree’s columns. This resource is an array of

PtTreeColumnAttributes_t structures. The structure contains at least the
following members (in the following order — static initialization is OK):
PhImage_t const **images

An array of image pointers. When you set the resource, this array
is copied, but the PhImage_t structures pointed to by it aren’t.
unsigned short nimages

The number of entries in the images array.
unsigned short cflags
Column flags; any combination of:
• Pt_TREE_COLUMN_NOSELECT — when set, clicking on
this column doesn’t cause selection.
• Pt_TREE_COLUMN_NOCURRENT — when set, clicking on
this column doesn’t even set the current item (see “Current
item” in the description of PtGenList).
• Pt_TREE_COLUMN_NOCB — when set, clicking on this
column doesn’t change the item’s flags or invoke the
Pt_CB_TREE_COLUMN_SEL callback.
unsigned iflags Item flags that are used to select this column’s image. See
Pt_ARG_TREE_COLUMN_IMGFUN and
Pt_CB_TREE_COLUMN_SEL
Pt_ARG_TREE_COLUMN_IMGFUN
PtTreeColumnImageF_t * Pointer See below
This function is called by the draw function for each item and each column that has the
Pt_LIST_COLUMN_NO_STRING flag in the Pt_ARG_LIST_COLUMN_ATTR
resource (see PtGenList) and a nonempty image array defined in the
Pt_ARG_TREE_COLUMN_ATTR resource.
The function must be of the following type:
typedef int PtTreeColumnImageF_t(

PtWidget_t *widget,
PtTreeItem_t *item,
PtTreeColumnAttributes_t const *cattr,
unsigned cindex );
The arguments are:

widget A pointer to the PtTree widget.

item A pointer to the item being drawn.
cattr A pointer to a PtTreeColumnAttributes_t structure that describes the

column attributes. For information about this structure, see
Pt_ARG_TREE_COLUMN_ATTR.
cindex The column index.
The function should return an index into the image array, or -1 if no image should be
drawn. If you return a value that’s equal to or greater than the column’s nimages, no
image is drawn.
The default function returns 0 or 1, depending on whether the column’s iflags ANDed
with the item’s flags gives a nonzero result.
The function attached to this resource isn’t allowed to modify anything and should be
quick, since it’s called a lot.
For an example, see “Displaying images in columns,” above.
Pt_ARG_TREE_IMAGES
PhImage_t *, short Array NULL
A list of images that can be displayed with tree items. For more information about the
image structure, see PhImage_t in the Photon Library Reference.
Set the flags member of the PhImage_t structures to:
before providing the images to the widget. If you do this, the memory used for the
images is released when the widget is destroyed or Pt_ARG_TREE_IMAGES is set.
For a convenient way to add images, see PtTreeAddImages(); for an example, see
“Using images in tree items,” above.
Pt_ARG_TREE_IMGMASK
unsigned Scalar Pt_LIST_ITEM_SELECTED
Defines the mask for selecting an item’s image.

When you create an item by calling PtTreeAllocItem(), you specify the images to be
used when the item is set or unset. An item is considered set if its flags masked with
the tree’s Pt_ARG_TREE_IMGMASK resource give a nonzero value. The flags
include:
The item is selected.
The item is the current item (see “Current item” in the description of
PtGenList).
Pt_TREE_ITEM_EXPANDABLE
The item can be expanded.
Pt_TREE_ITEM_EXPANDED
The branches of this item are currently displayed.
Pt_CB_TREE_COLUMN_SEL
you click on a column that has an entry in the Pt_ARG_TREE_COLUMN_ATTR
array but the Pt_TREE_COLUMN_NOCB flag in that entry isn’t set.
following members:
reason Pt_CB_TREE_COLUMN_SEL

cbdata A pointer to a PtTreeCallback_t structure that includes:
unsigned sel_mode;
The current selection mode
(Pt_ARG_SELECTION_MODE).
PtTreeItem_t *item;
If the selection mode isn’t set to
Pt_RANGE_MODE, item is a pointer to the
item you clicked on. If the selection mode is

set to Pt_RANGE_MODE, item is a pointer to

the first of the selected items.
unsigned nitems; This contains the number of selected items,
excluding collapsed subtrees.
int click_count; The number of mouse clicks (0 for keyboard
events or if event is NULL).
unsigned old_iflags
The current value of the item’s flags.
unsigned new_iflags
The value of the item’s flags, to be set after
the callback functions return.
Only the “user flags”
(Pt_LIST_ITEM_FLAG_USER[1234] defined
in PtGenList.h) and
Pt_LIST_ITEM_DAMAGED are looked at.
The initial value of new_flags is calculated
as follows:
• Set new_iflags to old_iflags;
• If the column attributes entry has any of
the user flags set in iflags, flip those flags
in new_iflags and set
Pt_LIST_ITEM_DAMAGED.
After the callback functions return, the user
flags are copied back from new_iflags and if
the Pt_LIST_ITEM_DAMAGED flag is set in
new_iflags, the item is damaged. Make sure
that you set the Pt_LIST_ITEM_DAMAGED
flag if you modify new_iflags in a way that
requires the item to be redrawn, particularly
if you have your own function attached to
the Pt_ARG_TREE_COLUMN_IMGFUN
resource.
int column The column number, or -1 if none.
PtTreeColumnAttributes_t const *cattr
A pointer to the attributes of that column, if
any. For information about this structure, see
Pt_ARG_TREE_COLUMN_ATTR.

For an example, see “Displaying images in columns,” above.

Pt_CB_TREE_SELECTION

A list of PtCallback_t structures that define the callbacks invoked when you select
an item from the tree.
following members:
reason Pt_CB_TREE_SELECTION
reason_subtype This value depends on the selection mode. One of:

• Pt_LIST_SELECTION_FINAL
• Pt_LIST_SELECTION_BROWSE
• Pt_LIST_SELECTION_CANCEL

cbdata A pointer to a PtTreeCallback_t structure that contains at

unsigned sel_mode;
PtTreeItem_t *item;
If the selection mode isn’t set to
Pt_RANGE_MODE, item is a pointer to the
item you clicked on. If the selection mode
is set to Pt_RANGE_MODE, item is a
pointer to the first of the selected items.
unsigned nitems; This contains the number of selected items,
excluding collapsed subtrees.
int click_count; The number of mouse clicks (0 for
keyboard events).

If you multi-click on a tree, its 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).

If you want to process only the last of a series of clicks, use a Pt_CB_RAW callback to
look for a Ph_EV_BUT_RELEASE event with a subtype of
Ph_EV_RELEASE_ENDCLICK. For more information, see PhEvent_t in the Photon
Library Reference.
The Ph_EV_BUT_RELEASE event with a subtype of Ph_EV_RELEASE_ENDCLICK

occurs approximately half a second after the click, which could be annoying to the
user. Most Photon applications don’t use multiple clicks because of this.
Pt_CB_TREE_STATE
A list of PtCallback_t structures that define the callbacks that are called before an
item is expanded and after an item is collapsed. Each callback is passed a
reason Pt_CB_TREE_STATE
reason_subtype Pt_TREE_COLLAPSING or Pt_TREE_EXPANDING.

cbdata A pointer to a PtTreeCallback_t structure that contains at

unsigned sel_mode;
PtTreeItem_t *item;
A pointer to the item that’s being collapsed or
expanded.
int expand; This field is initially set to 0. If the
reason_subtype is Pt_TREE_EXPANDING, set
expand to a nonzero value to suppress expansion.


Pt_ARG_DIM PtWidget
continued. . .


Pt_ARG_POS PtWidget
continued. . .


Pt_ARG_TREE_FLAGS PtGenTree See below.
Pt_CB_ARM PtBasic
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
continued. . .


Pt_ARG_TREE_FLAGS
In addition to the flags defined by PtGenTree, the following flags are defined:
• Pt_TREE_BALLOON_ON_IMAGE — the balloon is permitted to cover the image

and the text
• Pt_TREE_BALLOON_ON_TREE — the balloon is permitted to cover the tree, the

image, and the text
By default, neither is set. The width and location of the balloon depend on these flags:
Neither Pt_TREE_BALLOON_ Pt_TREE_BALLOON_

ON_IMAGE ON_TREE
Additional Pt_ARG_TREE_FLAGS for a PtTree widget.
To make the balloons appear, set one of the balloon bits (e.g.
Pt_LIST_BALLOON_AS_REQUIRED) in the Pt_ARG_LIST_FLAGS resource inherited
from PtGenList.
Pt_CB_DND
For Pt_CB_DND callbacks for a PtTree, the cbinfo->cbdata is a pointer to a

involved in the drag-and-drop operation. You can cast this to be a
pointer to a PtTreeItem_t.
unsigned long flags

Possible values:
the item.
below the item.
the item.

The PtTree widget defines the following structures and convenience functions that
make it easier to use the tree once it’s been created:
PtTreeAddAfter() Insert an item after the specified item
PtTreeAddFirst() Add a root item to the widget, or add an item as the first child
of a specified item
PtTreeAddImages() Add images to the PtTree widget’s image list
PtTreeAllItems() Fill a buffer with pointers to all items
PtTreeAllocItem() Allocate a new item
PtTreeClearSelection()
Clear the selection
PtTreeCollapse() Collapse an expandable item
PtTreeChangeItem() Change the text string and attributes of the specified item
PtTreeCreateItem() Allocate a new item with attributes
PtTreeExpand() Expand an expandable item

PtTreeFreeAllItems()
PtTreeFreeItems() Free an unlinked item
PtTreeGetCurrent() Get the current item
PtTreeGetSelIndexes()
Fill a buffer with indexes of selected items
PtTreeGoto() Set the current item
PtTreeItem_t PtTree item structure
PtTreeItemAttributes_t
PtTree item attributes structure, used by PtTreeCreateItem()
and PtTreeChangeItem().
PtTreeItemIndex() Calculate the index of the specified item
PtTreeModifyItem() Change item resources
PtTreeModifyItemString()
Change the string for a PtTree item
PtTreeRemoveChildren()
PtTreeRemoveItem() Unlink an item
PtTreeRemoveList() Unlink the given item and any siblings that follow
PtTreeRootItem() Return the first root item of the tree
PtTreeSelect() Select the specified item
PtTreeSelectedItems()
Fill a buffer with pointers to the selected items
PtTreeSetSelIndexes()
PtTreeShow() Set the position so that the specified item is visible
PtTreeUnselect() Unselect the specified item
PtTreeUnselectNonBrothers()

PtTreeAddAfter() © 2010, QNX Software Systems GmbH & Co. KG.
Insert an item after the specified item
Synopsis:
int PtTreeAddAfter( PtWidget_t *tree,
PtTreeItem_t *item,
PtTreeItem_t *brother );
Description:
This function inserts a list of trees linked with the brother member of the
PtTreeItem_t structure.
PtTreeAddAfter() assumes that item points to a list of trees. The tree variable points to
a PtTree widget. The new items are added to the specified tree below the specified
brother:
item tree tree
B 1 1
2 brother 2 brother
3 A item
C
The results of using PtTreeAddAfter().
You can call this function with a NULL tree argument, as long as brother points to an
item that isn’t attached to any tree widget.
Returns:
0 Success.
Examples:
See “Allocating items and building a tree” in the description of PtTree.

© 2010, QNX Software Systems GmbH & Co. KG. PtTreeAddAfter()
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTree, PtTreeAddFirst(), PtTreeAllocItem(), PtTreeFreeAllItems(),
PtTreeFreeItems(), PtTreeItem_t

PtTreeAddFirst() © 2010, QNX Software Systems GmbH & Co. KG.
Add a root item to a tree list
Synopsis:
int PtTreeAddFirst( PtWidget_t *tree,
PtTreeItem_t *item,
PtTreeItem_t *parent );
Description:
This function adds the list of PtTreeItem_t structures pointed to by item to the
given PtTree widget. The list of items are linked with their brother fields. The item
argument can be NULL.
The parent argument identifies the parent item for the added items. The new items are
added in front of any existing children of the parent item:
item tree tree
B 1 parent 1 parent
2 A item
3
2
3
The results of using PtTreeAddFirst().
If parent is NULL, the items are added at the root level of the tree, before any existing
items there.
The tree argument can be NULL, provided that parent points to an item that isn’t
attached to any tree widget.
PtTreeAddFirst() automatically sets the Pt_TREE_ITEM_EXPANDABLE flag in the
parent item, whether or not the item argument is NULL.
Returns:
0 Success.

© 2010, QNX Software Systems GmbH & Co. KG. PtTreeAddFirst()
Examples:
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTree, PtTreeAddAfter(), PtTreeAllocItem(), PtTreeFreeAllItems(),
PtTreeFreeItems(), PtTreeItem_t, PtTreeRootItem()

PtTreeAddImages() © 2010, QNX Software Systems GmbH & Co. KG.
Add images to the PtTree widget’s image list
Synopsis:
int PtTreeAddImages( PtWidget_t *widget,
PhImage_t const *images,
int n );
Description:
This function adds n images to the widget’s image list. The function returns the index
of the first of the added items, which is the same as the number of images on the list
(before the new ones were added). The widget makes its own copy of the PhImage_t
structures, but it doesn’t copy the palettes or image data pointed to by members of the
structures.
Returns:
The index of the first of the added items.
Examples:
See “Using images in tree items” in the description of PtTree.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTree
PhImage_t in the Photon Library Reference

© 2010, QNX Software Systems GmbH & Co. KG. PtTreeAllItems()
Fill a buffer with pointers to all items
Synopsis:
PtTreeItem_t **PtTreeAllItems(
PtWidget_t *widget,
PtTreeItem_t **buffer );
Description:
This function fills a buffer with pointers to all items in the widget. If buffer is NULL,
the function allocates a buffer using malloc(), and the buffer is NULL-terminated. If
buffer isn’t NULL, the function doesn’t add a NULL at the end.
Items that belong to collapsed subtrees aren’t included in the buffer. If you need a list
of all the items, traverse the father, son, and brother pointers in the
PtGenTreeItem_t structure that’s part of PtTreeItem_t.
Returns:
Examples:
PtTreeItem_t *item, **buf;
buf = PtTreeAllItems( widget, NULL );

for ( i=0; ( item = buf[i] ) != NULL; ++i ) {
printf( "%s\n", item->string );
}
free( buf );
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTree, PtTreeGetCurrent(), PtTreeGetSelIndexes(), PtTreeItem_t,
PtTreeSelectedItems(), PtTreeSetSelIndexes()

PtTreeAllocItem() © 2010, QNX Software Systems GmbH & Co. KG.
Allocate a new item
Synopsis:
PtTreeItem_t *PtTreeAllocItem(
PtWidget_t const *tree,
const char *string,
short set_img,
short unset_img );
Description:
This function allocates a new item. The item’s string is copied from string.
The set_img argument is the index of the image to be displayed when the item is set,
and unset_img is the image to be displayed when it isn’t set. An item is considered set
if its flags masked with the Pt_ARG_TREE_IMGMASK resource of the widget give a
nonzero value.
The image must be already present in the widget: if you specify an index that’s larger
than the current image count, it’s changed to -1. A value of -1 means “no image.”
Use PtTreeAddFirst() and PtTreeAddAfter() to add the new item to a tree structure.
Examples:
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTree, PtTreeAddAfter(), PtTreeAddFirst(), PtTreeAddImages(),
PtTreeFreeAllItems(), PtTreeFreeItems(), PtTreeItem_t, PtTreeModifyItem(),

© 2010, QNX Software Systems GmbH & Co. KG. PtTreeChangeItem()
Create a tree item with attributes
Synopsis:
PtTreeItem_t *PtTreeChangeItem(
PtWidget_t *tree,
PtTreeItem_t *item,
const char *string,
PtTreeItemAttributes_t const *attr
);
Arguments:
tree A pointer to the PtTree widget which contains the item you want to
change.
item A pointer to the PtTreeItem_t you wish to change.
string The tree item text string. Set to NULL to leave the item’s text string
unchanged.
attr A pointer to the new PtTreeItemAttributes_t structure you want to set

for this item. Set to NULL to display no images, and use the widget-defined
font and colors. The Pt_TREE_ITEM_HAS_ATTRS flag bit is still set for the
item.
Description:
This function changes an existing tree item, created with PtTreeCreateItem() or
PtTreeAllocItem(). The string and attr parameters will override the existing item text
string and attributes.
Returns:
A pointer to a PtTreeItem_t
Success.
NULL Error
PtTreeChangeItem() can return a pointer to a new item that your application must
maintain. Your code should look like this:
new_item = PtTreeChangeItem(tree, item, newname, NULL);

if( new_item != null ) {
item = new_item;
} else {
// Handle this error!
...
}

PtTreeChangeItem() © 2010, QNX Software Systems GmbH & Co. KG.
Examples:
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTree, PtTreeAddAfter(), PtTreeAllocItem(), PtTreeCreateItem(),
PtTreeFreeAllItems(), PtTreeFreeItems(), PtTreeItem_t,
PtTreeItemAttributes_t, PtTreeRootItem()

© 2010, QNX Software Systems GmbH & Co. KG. PtTreeClearSelection()
Clear the selection
Synopsis:
void PtTreeClearSelection( PtWidget_t *widget );
Description:
This function clears the selection.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTree, PtTreeGetCurrent(), PtTreeGetSelIndexes(), PtTreeGoto(), PtTreeSelect(),
PtTreeSelectedItems(), PtTreeSetSelIndexes(), PtTreeUnselect(),
PtTreeUnselectNonBrothers()

PtTreeCollapse() © 2010, QNX Software Systems GmbH & Co. KG.
Collapse an expandable item
Synopsis:
int PtTreeCollapse( PtWidget_t *tree,
PtTreeItem_t *item,
PhEvent_t *event );
Description:
This function collapses the given subtree item. The tree argument must point to the
tree that contains the item, or it can be NULL if the item doesn’t belong to any tree.
If the item is in the tree, the tree’s Pt_CB_TREE_STATE callback is invoked after the
item has been collapsed. The event argument to this function is the event that’s passed
to the callback.
Returns:
The value assigned to the expand field in the callback structure, or zero if the item isn’t
in a tree or there’s no Pt_CB_TREE_STATE callback that modifies the expand field.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTree, PtTreeExpand(), PtTreeGetCurrent(), PtTreeGoto(), PtTreeItem_t,
PtTreeShow()

© 2010, QNX Software Systems GmbH & Co. KG. PtTreeCreateItem()
Create a tree item with attributes
Synopsis:
PtTreeItem_t *PtTreeCreateItem(
PtWidget_t const *tree,
const char *string,
PtTreeItemAttributes_t const *attr
);
Arguments:
tree A pointer to the PtTree widget that this item will be added to.
string The text to display for the item.
attr A pointer to a PtTreeItemAttributes_t structure which defines the

attributes for the item. Set to NULL to set no images for the item, and to use
the widget-defined font and colors.
Description:
This function creates a new tree item. The item’s string is copied from string.
Attributes are set with a PtTreeItemAttributes_t structure, passed as attr. The
item’s Pt_TREE_ITEM_HAS_ATTRS is set whether attr is passed as a pointer or NULL.
Both PtTreeAllocItem() and PtTreeCreateItem() create a tree item. PtTreeCreateItem()
lets you specify set and unset images that are not already present in the widget’s
Pt_ARG_TREE_IMAGES array. In general, if you want to use images in this array,
you should use PtTreeAllocItem().
An item created with PtTreeCreateItem(widget,string,NULL) behaves identically to an

item created with PtTreeAllocItem(widgetmstring,-1,-1), except it has the
Pt_TREE_ITEM_HAS_ATTRS flag set, whereas the latter does not.
Using PtTreeCreateItem() you can also specify text and fill color attributes for selected
and unselected items.
Use PtTreeAddFirst() and PtTreeAddAfter() to add the new item to a tree structure.
Returns:
A pointer to a PtTreeItem_t
Success.
NULL Error

PtTreeCreateItem() © 2010, QNX Software Systems GmbH & Co. KG.
Examples:
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTree, PtTreeAddAfter(), PtTreeAllocItem(), PtTreeChangeItem(),
PtTreeFreeAllItems(), PtTreeFreeItems(), PtTreeItem_t,
PtTreeItemAttributes_t, PtTreeRootItem()

© 2010, QNX Software Systems GmbH & Co. KG. PtTreeExpand()
Expand an expandable item
Synopsis:
int PtTreeExpand( PtWidget_t *tree,
PtTreeItem_t *item,
PhEvent_t *event );
Description:
This function expands the given subtree item. The tree argument must point to the tree
that contains the item or can be NULL if the item doesn’t belong to any tree.
If the item is in the tree, the tree’s Pt_CB_TREE_STATE callback is invoked before
the item is expanded. The event argument to this function is the event that’s passed to
the callback. Your callback function can prevent the expansion by setting the expand
field in the callback structure to a nonzero value; zero means successful expansion.
Returns:
The value assigned to the expand field in the callback structure, or zero if the item isn’t
in a tree or there’s no Pt_CB_TREE_STATE callback that modifies the expand field.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTree, PtTreeCollapse(), PtTreeGetCurrent(), PtTreeGoto(), PtTreeItem_t,
PtTreeShow()

PtTreeFreeAllItems() © 2010, QNX Software Systems GmbH & Co. KG.
Synopsis:
void PtTreeFreeAllItems( PtWidget_t *tree );
Description:
This function unlinks and frees all items in the tree widget. Note that this function is
called automatically when the PtTree widget is being destroyed.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTree, PtTreeAllocItem(), PtTreeFreeItems(), PtTreeRemoveChildren(),
PtTreeRemoveItem(), PtTreeRemoveList()

© 2010, QNX Software Systems GmbH & Co. KG. PtTreeFreeItems()
Free an unlinked item
Synopsis:
int PtTreeFreeItems( PtTreeItem_t *item );
Description:
This function frees the given subtrees (the item together with its brothers and their
children). The items must not belong to any tree — use PtTreeRemoveChildren(),
PtTreeRemoveItem(), or PtTreeRemoveList() to remove the subtree from a tree widget
before freeing the subtrees.
Returns:
0 Success.
-1 The item is still in a widget.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTree, PtTreeAllocItem(), PtTreeFreeAllItems(), PtTreeItem_t,
PtTreeRemoveChildren(), PtTreeRemoveItem(), PtTreeRemoveList()

PtTreeGetCurrent() © 2010, QNX Software Systems GmbH & Co. KG.
Get the current item
Synopsis:
PtTreeItem_t *PtTreeGetCurrent(
const PtWidget_t *widget );
Description:
This function returns a pointer to the current item in the given PtTree widget (see
“Current item” in the description of PtGenList).
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTree, PtTreeClearSelection(), PtTreeGetSelIndexes(), PtTreeGoto(),
PtTreeItem_t, PtTreeRootItem(), PtTreeSelect(), PtTreeSelectedItems(),
PtTreeSetSelIndexes(), PtTreeShow(), PtTreeUnselect(), PtTreeUnselectNonBrothers()

© 2010, QNX Software Systems GmbH & Co. KG. PtTreeGetSelIndexes()
Fill a buffer with indexes
Synopsis:
unsigned short *PtTreeGetSelIndexes(
PtWidget_t *widget,
Description:
This function fills a buffer with indexes of all the selected items in the PtTree widget.
The first item in the widget has an index of 1, not 0.
zero-terminated.
• If buffer is non-NULL, the function adds zero to the end only if there are no
Items that belong to collapsed subtrees aren’t included in the buffer.
Returns:
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTree, PtTreeClearSelection(), PtTreeGetCurrent(), PtTreeGoto(), PtTreeItem_t,
PtTreeRootItem(), PtTreeSelect(), PtTreeSelectedItems(), PtTreeSetSelIndexes(),
PtTreeShow(), PtTreeUnselect(), PtTreeUnselectNonBrothers()

PtTreeGoto() © 2010, QNX Software Systems GmbH & Co. KG.
Set the current item
Synopsis:
int PtTreeGoto( PtWidget_t *list,
PtTreeItem_t *item );
Description:
If you pass item as NULL, there will be no current item.
Returns:
0 Success.
Nonzero item belongs to a collapsed subtree, and a callback function prevented

the subtree from being expanded.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTree, PtTreeClearSelection(), PtTreeGetCurrent(), PtTreeGoto(), PtTreeItem_t,
PtTreeRootItem(), PtTreeSelect(), PtTreeSelectedItems(), PtTreeSetSelIndexes(),
PtTreeShow(), PtTreeUnselect(), PtTreeUnselectNonBrothers()

© 2010, QNX Software Systems GmbH & Co. KG. PtTreeItem_t
PtTree item structure
Synopsis:
typedef struct Pt_tree_item {
PtGenTreeItem_t gen;
union {
struct { short set, unset; } img;
PtTreeItemAttributes_t const *ptr;
} attr;
void *data;
char string[1];
} PtTreeItem_t;
Description:
This data structure describes an item in a PtTree. The members include at least:
gen A structure that describes a generic-tree item. This structure

includes state information for the item (whether or not it’s selected,
the current item, damaged, out of view, expandable, expanded, and
so on), its size, and links to other generic-tree items. For more
information, see PtGenTreeItem_t.
attr.img.set The index into the tree’s Pt_ARG_TREE_IMAGES resource of the

image that’s displayed when the item is set. An item is considered
set if its flags masked with the tree’s Pt_ARG_TREE_IMGMASK
resource give a nonzero value.
attr.img.unset The index of the image displayed when the item isn’t set.
attr.ptr A pointer to the item’s PtTreeItemAttributes_t attribute

structure.
data A pointer to arbitrary user data. The widget doesn’t use this
member.
string The string to be displayed for the item. This field is allocated the
appropriate amount of space when it’s set.
Use PtTreeAllocItem() or PtTreeCreateItem() to allocate and fill in this structure.

Once the tree item has been created or changed, item->gen.list.flags indicates which
half of the PtTreeItem_t’s attr union is valid. When this flag is
Pt_TREE_ITEM_HAS_ATTRS, attr.ptr is a pointer to an attributes structure (or NULL).
When this flag is clear, attr.img.set and attr.img.unset are indexes into the
Pt_ARG_TREE_IMAGES array (or -1).
Classification:
Photon

PtTreeItem_t © 2010, QNX Software Systems GmbH & Co. KG.
See also:
PtGenList, PtGenTree, PtGenTreeItem_t, PtTree, PtTreeAddAfter(),
PtTreeAddFirst(), PtTreeAllItems(), PtTreeAllocItem(), PtTreeChangeItem(),
PtTreeCreateItem(), PtTreeFreeItems(), PtTreeGetCurrent(),
PtTreeItemAttributes_t, PtTreeItemIndex(), PtTreeModifyItem(),
PtTreeModifyItemString(), PtTreeRemoveItem(), PtTreeRootItem(),
PtTreeSelectedItems()

© 2010, QNX Software Systems GmbH & Co. KG. PtTreeItemAttributes_t
PtTree item attributes structure
Synopsis:
typedef struct Pt_tree_item_attributes {
PtGenListItemAttrs_t list;
PhImage_t const *set_image, *unset_image;
}
PtTreeItemAttributes_t;
Description:
This data structure describes the attributes for a PtTreeItem_t. The members
include at least:
list A PtGenListItemsAttrs_t structure that represents a list of

generic item attributes. See the description below.
set_image A pointer to the set image for the item.
unset_image A pointer for the unset image for the item.
It’s your responsibility to allocate and deallocate the members of this structure, and to
ensure that their contents don’t change while the structure is in use.
Use this structure as a parameter to PtTreeCreateItem() to create a tree item with
attributes (as opposed to PtTreeAllocItem()), and to PtTreeChangeItem() to change an
existing tree item.
The list member is a PtGenListItemAttrs_t with this structure:
typedef struct Pt_genlist_item_attrs {
const char *font;
PtGenListColorSet_t unselected_colors;
PtGenListColorSet_t selected_colors;
unsigned flags;
} PtGenListItemAttrs_t;
The members are:
font The font name for the item text. If this item is set to NULL, the
widget-defined font it used.
unselected_colors, selected_colors
The text and fill color for the list item. Set to Pg_TRANSPARENT to use the
widget-defined color.
This member is a PtGenListColorSet_t, with this structure:
typedef struct Pt_gen_list_color_set {
PgColor_t text, fill;
} PtGenListColorSet_t;
flags Used internally. Must be set to zero.

PtTreeItemAttributes_t © 2010, QNX Software Systems GmbH & Co. KG.
Classification:
Photon
See also:
PtTree, PtTreeChangeItem(), PtTreeCreateItem(), PtTreeItem_t

© 2010, QNX Software Systems GmbH & Co. KG. PtTreeItemIndex()
Calculate the index of the given item within the tree
Synopsis:
int PtTreeItemIndex( const PtTreeWidget_t *tree,
const PtTreeItem_t *item );
Description:
This function calculates the index of the given item within the tree. The index of the
first item is 1.
Returns:
The index of the item, or 0 if it belongs to a collapsed subtree.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTree, PtTreeAllItems(), PtTreeGetSelIndexes(), PtTreeItem_t

PtTreeModifyItem() © 2010, QNX Software Systems GmbH & Co. KG.
Change item resources
Synopsis:
PtTreeItem_t *PtTreeModifyItem( PtWidget_t *tree,
PtTreeItem_t *item,
const char *string,
short set_img,
short unset_img );
Description:
This function changes item resources:
• The item’s string is changed to be a copy of string. If string is NULL, the item’s
string isn’t changed.
• The set_img argument is the index of the image that’s displayed when the item is
set, and unset_img is the image displayed when it isn’t set. An item is considered
set if its flags masked with the Pt_ARG_TREE_IMGMASK resource of the widget
give a nonzero value.
The tree is a pointer to the PtTree that the item belongs to, or NULL. If the item is in
a tree, it must be in the one pointed to by tree.
Returns:
The new address of the item.
This address may differ from the old one if the new string is longer.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTree, PtTreeAllocItem(), PtTreeItem_t, PtTreeItemIndex(),

© 2010, QNX Software Systems GmbH & Co. KG. PtTreeModifyItemString()
Change the string for a PtTree item
Synopsis:
PtTreeItem_t *PtTreeModifyItemString(
PtWidget_t *tree,
PtTreeItem_t *item,
const char *string );
Description:
This function changes the string for the given item, making a copy of string. The tree
is a pointer to the PtTree that the item is in, or NULL. If the item is in a tree, it must
be in the one pointed to by tree.
Returns:
The new address of the item.
This address may differ from the old one if the new string is longer.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTree, PtTreeAllocItem(), PtTreeItem_t, PtTreeItemIndex(), PtTreeModifyItem()

PtTreeRemoveChildren() © 2010, QNX Software Systems GmbH & Co. KG.
Synopsis:
PtTreeItem_t *PtTreeRemoveChildren(
Description:
This function unlinks all the children of the specified item and returns the pointer to
the first of them:
tree tree returned pointer
A item A C
B D
The results of using PtTreeRemoveChildren().
You can then give the pointer to the PtTreeFreeItems() function.

This function doesn’t collapse the item. If the children are visible,
PtTreeRemoveChildren() returns NULL. Call PtTreeCollapse() before
PtTreeRemoveItem() to make sure that the item is collapsed.
Returns:
A pointer to the first of the removed children, or NULL if the children are visible.
Classification:
Photon
Safety
Signal handler No
Thread No

© 2010, QNX Software Systems GmbH & Co. KG. PtTreeRemoveChildren()
See also:
PtTree, PtTreeAddAfter(), PtTreeAddFirst(), PtTreeAllocItem(),
PtTreeFreeAllItems(), PtTreeFreeItems(), PtTreeItem_t, PtTreeRemoveItem(),
PtTreeRemoveList()

PtTreeRemoveItem() © 2010, QNX Software Systems GmbH & Co. KG.
Unlink an item
Synopsis:
void PtTreeRemoveItem( PtWidget_t *tree,
Description:
This function unlinks the given item together with its children from its parent and
brothers (if any) and sets the item->gen.father and item->gen.brother fields to NULL:
tree tree item
A A B
B item C
The results of using PtTreeRemoveItem().
The tree argument must point to the PtTree widget containing the item, or can be
NULL if the item doesn’t belong to any tree.
Note that if tree is NULL and the item has no parent but has a previous brother, then
the function can’t find the previous brother, and therefore can’t unlink the item from its
brother. The function does nothing if item->gen.father and tree are NULL.
PtTreeRemoveItem() never clears the Pt_TREE_ITEM_EXPANDABLE flag in the item’s
parent.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTreeFreeAllItems(), PtTreeFreeItems(), PtTreeItem_t, PtTreeRemoveChildren(),
PtTreeRemoveList()

© 2010, QNX Software Systems GmbH & Co. KG. PtTreeRemoveList()
Unlink the root item
Synopsis:
void PtTreeRemoveList( PtWidget_t *tree,
PtTreeItem_t *first );
Description:
This function unlinks the item first and its brothers (together with their children) from
their parent (and previous brother) and sets their gen.father fields to NULL:
tree tree first
A A B
B first C
The results of using PtTreeRemoveList().
The tree argument must point to the PtTree widget that contains the items, or can be
NULL if the items don’t belong to any tree.
Note that if tree is NULL and first has no parent but has a previous brother, then the
function won’t be able to find the previous brother and therefore can’t unlink first from
its previous brother.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTreeFreeAllItems(), PtTreeFreeItems(), PtTreeItem_t, PtTreeRemoveChildren(),
PtTreeRemoveItem()

PtTreeRootItem() © 2010, QNX Software Systems GmbH & Co. KG.
Return the first root item of the tree
Synopsis:
PtTreeItem_t *PtTreeRootItem(
PtTreeWidget_t const *tree );
Description:
This function returns a pointer to the first root item in the given PtTree widget.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTree, PtTreeAddAfter(), PtTreeAddFirst(), PtTreeAllItems(), PtTreeFreeAllItems(),
PtTreeFreeItems(), PtTreeGetCurrent(), PtTreeGoto(), PtTreeItem_t,
PtTreeSelect(), PtTreeShow()

© 2010, QNX Software Systems GmbH & Co. KG. PtTreeSelect()
Select the specified item
Synopsis:
void PtTreeSelect( PtWidget_t *widget,
Description:
This function selects the given item belonging to the given PtTree widget. You can
pass NULL for widget if the item doesn’t belong to a widget.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTree, PtTreeClearSelection(), PtTreeGetCurrent(), PtTreeGetSelIndexes(),
PtTreeGoto(), PtTreeItem_t, PtTreeSelectedItems(), PtTreeSetSelIndexes(),
PtTreeUnselect(), PtTreeUnselectNonBrothers()

PtTreeSelectedItems() © 2010, QNX Software Systems GmbH & Co. KG.
Fill a buffer with item pointers
Synopsis:
PtTreeItem_t **PtTreeSelectedItems(
PtWidget_t *widget,
PtTreeItem_t **buffer );
Description:
This function fills a buffer with pointers to the tree’s selected items:
NULL-terminated.
• If buffer is non-NULL, the function adds a NULL at the end only if there are no
Items that belong to collapsed subtrees aren’t included in the buffer.
Returns:
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTreeGoto(), PtTreeItem_t, PtTreeSelect(), PtTreeSetSelIndexes(),

© 2010, QNX Software Systems GmbH & Co. KG. PtTreeSetSelIndexes()
Synopsis:
int PtTreeSetSelIndexes(
PtWidget_t *widget,
const unsigned short *buffer,
int count );
Description:
This function sets the selection indexes. The function assumes that buffer points to a
sorted array of indexes. The first item in the widget has an index of 1, not 0.
be smaller than count if the array isn’t sorted or contains duplicate indexes or indexes
out of range.
Note that if the selection mode is Pt_RANGE_MODE, only the first index and the count
are used.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTreeGoto(), PtTreeItem_t, PtTreeSelect(), PtTreeSelectedItems(),

PtTreeShow() © 2010, QNX Software Systems GmbH & Co. KG.
Set the position so that the specified item is visible
Synopsis:
int PtTreeShow( PtWidget_t *widget,
Description:
This function sets the current position so that the given item is visible. If you pass item
as NULL, the function does nothing. This lets you do something like this:
PtTreeShow( widget, PtTreeGetCurrent(widget) );
without checking to see if PtTreeGetCurrent() returned NULL.
Returns:
0 Success.
Nonzero item belongs to a collapsed subtree, and a callback function prevented

the subtree from being expanded
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTree, PtTreeClearSelection(), PtTreeCollapse(), PtTreeExpand(),
PtTreeGetCurrent(), PtTreeGetSelIndexes(), PtTreeGoto(), PtTreeItem_t,
PtTreeRootItem(), PtTreeSelect()

© 2010, QNX Software Systems GmbH & Co. KG. PtTreeUnselect()
Unselect the given item
Synopsis:
void PtTreeUnselect( PtWidget_t *widget,
Description:
This function unselects the given item belonging to the given PtTree widget.
Note that PtTreeUnselect() doesn’t support the Pt_RANGE_MODE selection mode.
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTreeSetSelIndexes(), PtTreeUnselectNonBrothers()

PtTreeUnselectNonBrothers() © 2010, QNX Software Systems GmbH & Co. KG.
Synopsis:
void PtTreeUnselectNonBrothers(
PtWidget_t *widget,
Description:
This function unselects all the items that aren’t siblings of the given item. If you pass
item as NULL, the current item is used (see “Current item” in the description of
PtGenList).
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtTreeSetSelIndexes(), PtTreeUnselect()

© 2010, QNX Software Systems GmbH & Co. KG. PtTrend
A trend graph
Class hierarchy:
PtWidget → PtBasic → PtTrend
PhAB icon:
Public header:
<photon/PtTrend.h>
Description:
A PtTrend widget displays a trend graph. The data is displayed as a set of connected
points that shift in a specified direction and at the rate at which data is fed in.
A PtTrend widget.
New resources:

Pt_ARG_TREND_ATTRIBUTES PtTrendAttr_t, short Array 1 or (1,1,1,1..)
Pt_ARG_TREND_COLOR_LIST PgColor_t, short Array NULL
continued. . .

PtTrend © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_TREND_COUNT int Scalar 1
Pt_ARG_TREND_DATA short, int Array None (write-only)
Pt_ARG_TREND_FLAGS long Flag See below
Pt_ARG_TREND_GRID_COLOR PgColor_t Scalar Pg_GRAY
Pt_ARG_TREND_GRID_X short int Scalar 5
Pt_ARG_TREND_GRID_Y short int Scalar 5
Pt_ARG_TREND_INC short int Scalar 1
Pt_ARG_TREND_MAX short int Scalar SHRT_MAX
Pt_ARG_TREND_MIN short int Scalar SHRT_MIN
Pt_ARG_TREND_PALETTE_END unsigned short Scalar 256
Pt_ARG_TREND_ATTRIBUTES
PtTrendAttr_t, short Array 1 or (1,1,1,1..)
The attributes that the trend may have. This resource is an array of structures of type
PtTrendAttr_t, which contains at least the following member:
int map An index into Pt_ARG_TREND_COLOR_LIST to indicate the color

that the trend uses. This index is used as follows:
Index Color used

0 Pt_ARG_FILL_COLOR (that is, the background color for the widget)
1 the first color in Pt_ARG_TREND_COLOR_LIST (which is the same as
Pt_ARG_COLOR)
2 the second color in Pt_ARG_TREND_COLOR_LIST
3 etc.
In order to set this resource, you must use the arguments to PtSetArg() in an unusual
way; the value argument points to the value of the resource, as usual, but len is used
for the trend number, not the size of value.
To set the colors for all the trends at once, specify a list of mappings of trends onto
colors, and use 0 for the trend number. That is, the len argument to 0 and have the
value argument point to an array of PtTrendAttr_t structures.

For example, the following code fragment sets up the color list, and sets the colors to
be used for three trends.
int trend_color_array[4] = {Pg_GREEN, Pg_RED,
Pg_YELLOW, Pg_BLUE};
PtTrendAttr_t one_attr, several_attr[3];
PtArg_t args[2];
PtWidget_t trend_widget;
.
.
.
/* Set up the color list. */

PtSetArg (&args[0], Pt_ARG_TREND_COLOR_LIST,
trend_color_array, 4);
PtSetResources (trend_widget, 1, args);
/* Map the trends to colors. */

several_attr[0].map = 3; /* Trend 0 is Pg_YELLOW */
several_attr[1].map = 2; /* Trend 1 is Pg_RED */
several_attr[2].map = 4; /* trend 2 is Pg_BLUE */
PtSetArg (&args[0], Pt_ARG_TREND_ATTRIBUTES,

several_attr, 0);
To set an attribute for a given trend, set PtSetArg’s len argument to the number of that
trend, and have the value argument point to a single structure of type
PtTrendAttr_t. For example, the following changes the color of trend 2 to
Pg_GREEN:
one_attr.map = 1;
PtSetArg (&args[0], Pt_ARG_TREND_ATTRIBUTES,
&one_attr, 2);
It isn’t possible to set the color of trend 0 alone, as setting the len argument of
PtSetArg() to 0 specifies that you want to set the color index for all the trends.
Pt_ARG_TREND_COLOR_LIST
PgColor_t, short Array NULL
The list of colors that the trend may use. See PgColor_t in the Photon Library
Reference.
To assign one of these colors to a trend, use the Pt_ARG_TREND_ATTRIBUTES
resource.
The first color in this list is always the same as Pt_ARG_COLOR.

Pt_ARG_TREND_COUNT

int Scalar 1
The number of trends that the widget displays.
Pt_ARG_TREND_DATA (write-only)
short, int Array None
The data displayed by the trends. You can use this resource to set the data; you can’t
use it to extract the data from the trends.
When you want to add data to a trend, your application should set the value argument
to PtSetArg() with a pointer to a data buffer that contains the new data points. The
application must also set the len parameter to the number of new data points being
added to the trend.
If the widget is displaying multiple trends, the data buffer must contain the new data
for each trend: data for the first trend is followed by data for the second trend, and so
on. The application must set len to be the total number of points being added, not the
number of points per trend.
If you set the value parameter to NULL, the trend’s display is cleared.
If you wish to replace some of the data for one trend, call PtTrendChangeData(). To
replace data in all trends, call PtTrendChangeTrendData().
Pt_ARG_TREND_FLAGS
long Flag Pt_TREND_HORIZONTAL | Pt_GRID |
Pt_TREND_RIGHT_TO_LEFT |
Pt_GRID_IS_TRANSLUCENT
Flags that control the appearance of the widget. The bits include:
Pt_GRID Draw a grid.

If this flag is set, you must also set
Pt_GRID_IS_TRANSLUCENT, Pt_GRID_ABOVE_TRENDS, or
Pt_TRENDS_ABOVE_GRID.
Pt_GRID_ABOVE_TRENDS
Make the grid opaque, appearing over the trends.

The grid is displayed only if Pt_GRID is set.
Pt_GRID_FORCE Draw a grid even if the graphics device doesn’t support planar
hardware blitting. Some flickering may occur.
Pt_GRID_IS_TRANSLUCENT
Make the grid translucent, appearing over the trends.
Pt_PIXEL Draw the trend with PgDrawPixelArray() instead of

PgDrawPolygon().
Pt_TREND_HORIZONTAL
Make the trends horizontal.
If this is set, you must also set Pt_TREND_LEFT_TO_RIGHT or
Pt_TREND_RIGHT_TO_LEFT.
Pt_TREND_BOTTOM_TO_TOP
Make the trends move from the bottom to the top of the widget.
You can use this only with Pt_TREND_VERTICAL.
Pt_TREND_LEFT_TO_RIGHT
Make the trends move from left to right. You can use this only
with Pt_TREND_HORIZONTAL.
Pt_TREND_RIGHT_TO_LEFT
Make the trends move from right to left. You can use this only
with Pt_TREND_HORIZONTAL.
Pt_TREND_TOP_TO_BOTTOM
Make the trends move from the top to the bottom of the widget.
You can use this only with Pt_TREND_VERTICAL.
Pt_TREND_VERTICAL
Make the trends vertical.
If this is set, you must also set Pt_TREND_TOP_TO_BOTTOM
or Pt_TREND_BOTTOM_TO_TOP.
Pt_TRENDS_ABOVE_GRID
Make the grid opaque, appearing under the trends.

If you set Pt_ARG_TREND_FLAGS to an invalid value, the widget draws only the
background.
Pt_ARG_TREND_GRID_COLOR
PgColor_t Scalar Pg_GRAY
The color of the grid, specified as an RGB value. See PgColor_t in the Photon
Library Reference.
The grid is displayed only if Pt_GRID is set in Pt_ARG_TREND_FLAGS.
Pt_ARG_TREND_GRID_X
short int Scalar 5
The number of grid lines along the x axis; in other words, the number of vertical lines.
The grid is displayed only if Pt_GRID is set in Pt_ARG_TREND_FLAGS.
Pt_ARG_TREND_GRID_Y
short int Scalar 5
The number of grid lines along the y axis; in other words, the number of horizontal
lines. The grid is displayed only if Pt_GRID is set in Pt_ARG_TREND_FLAGS.
Pt_ARG_TREND_INC
short int Scalar 1
The distance between data points displayed on the screen. The default is 1. Note that
if the increment is too large, the data won’t be plotted correctly. Generally, you should
use this resource only if you need a coarse-grained display.
Pt_ARG_TREND_MAX

The maximum data value for all the trends.
Pt_ARG_TREND_MIN
short int Scalar SHRT_MIN
The minimum data value for all the trends.
Pt_ARG_TREND_PALETTE_END
Defines the range of palette entries the widget uses for drawing if the grid is displayed.
This is useful if you have more than one PtTrend widget and you want to make sure
their palette entries don’t overlap.
Each PtTrend widget uses:
• two palette entries for each entry in the Pt_ARG_TREND_COLOR_LIST— one

for the trend, and one for where the trend overlaps the grid
• one palette entry for the background
• one palette entry for the grid.
If E is the value of the Pt_ARG_TREND_PALETTE_END resource and N is the

number of palette entries used for the widget (rounded up to the next power of 2), the
widget uses palette entries from E - N to E - 1.
The value of Pt_ARG_TREND_PALETTE_END should be a multiple of N. If it isn’t,
it’s rounded down to a multiple of N.

continued. . .


Pt_ARG_DIM PtWidget
continued. . .


Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
The PtTrend widget defines the following convenience functions that make it easier
to use the widget once it’s been created:

PtTrendChangeData()
Replace some samples for all trends
PtTrendChangeTrendData()
Replace some samples for one trend

© 2010, QNX Software Systems GmbH & Co. KG. PtTrendChangeData(),
Replace some samples for one or all trends
Synopsis:
void PtTrendChangeData( PtWidget_t *widget,
short const *newdata,
unsigned nsamples);
void PtTrendChangeTrendData( PtWidget_t *widget,

unsigned tn,
short const *newdata,
unsigned nsamples);
Description:
These functions let you replace some samples in one or more trends, without touching
other data or other trends in the widget.
These functions are used to replace data that’s already in a trend, not to add data to the
end of the trends.
PtTrendChangeTrendData() lets you change data for a single trend. The widget
argument must be a widget of type PtTrend. The tn argument is the number of the
trend to be changed, in the range 0 to trend count - 1, inclusive.
The newdata argument is a pointer to an array of the new data. last_sample is the
index of the newest sample to replace, where 0 is considered to be the index of the
most recently added sample. nsamples is the number of samples to be replaced. The
diagram below shows how the samples are replaced.

PtTrendChangeData(), PtTrendChangeTrendData() © 2010, QNX Software Systems
GmbH & Co. KG.
Old samples Movement New samples
last_sample + nsamples -1 last_sample
newdata[0] newdata[nsamples-1]
Replacing trend samples with PtTrendChangeData() or PtTrendChangeTrendData().
The newdata array is ordered with the oldest sample at newdata[0], and the newest at
newdata[nsamples - 1]. The oldest sample to be replaced will have an index of
last_sample + nsamples - 1;
The samples in the trend are replaced as follows:
• trend sample[last_sample] = newdata[nsamples - 1].
• trend sample[last_sample + 1] = newdata[nsamples - 2].
• ...
• trend sample[last_sample + nsamples - 1] = newdata[0].
If last_sample + nsamples - 1 is outside the range of samples for the widget, some
initial portion of the new data is discarded.
PtTrendChangeData() lets you change the data for all the trends. Its arguments are
similar to those of PtTrendChangeTrendData() with the following exceptions:
• The tn argument isn’t passed to PtTrendChangeData().
• The data for the first trend is put into the first nsamples places of newdata, followed
by those for trend 2, 3 and so on.

© 2010, QNX Software Systems GmbH & Co. KG. PtTrendChangeData(),
Calling PtTrendChangeData() is similar to calling PtTrendChangeTrendData() in the
following loop:
for (i=0; i<TREND_COUNT; ++i) {
PtTrendChangeTrendData (widget, i, newdata, last_sample,
nsamples);
newdata += nsamples;
}
The only difference is that PtTrendChangeData() redraws the widget once; the loop
redraws it once per iteration.
Classification:
Photon
Safety
Signal handler No
Thread No

PtTty © 2010, QNX Software Systems GmbH & Co. KG.
A PtTerminal widget attached to a device
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtTerminal → PtTty
PhAB icon:
Public header:
<photon/PtTty.h>
Description:
A PtTty widget is a PtTerminal attached to a device. The device output is passed to
the terminal, but also can be caught with the Pt_CB_TTY_OUTPUT callback.
Output from a terminal device.
If the widget has the Pt_GETS_FOCUS flag set in its Pt_ARG_FLAGS resource,
keyboard input to the widget (as well as mouse events) are redirected to the device.
You can also use the Pt_ARG_TTY_INPUT resource to simulate keyboard input.
PtTerminal and PtTty

The main difference between PtTerminal and PtTty is that PtTerminal doesn’t
do any I/O for you. The only way to display characters in a PtTerminal is by giving
them to one of the PtTerminalPut*() functions. Similarly, the only thing PtTerminal
does with Photon input is translate function keys into text-mode compatible escape
sequences and give the result to your Pt_CB_TERM_INPUT callback.
PtTty adds device I/O to that. The code that opens a pty, reads characters from it, and
gives those characters to PtTerminalPut() is part of PtTty. Similarly, PtTty attaches
a Pt_CB_TERM_INPUT callback that writes Photon keyboard input (translated by
PtTerminal to text-mode compatible format) to the pty.
Another responsibility of PtTty is spawning a command for you and invoking the
Pt_CB_TTY_TERMINATED callbacks when the command terminates.

© 2010, QNX Software Systems GmbH & Co. KG. PtTty
Setting PtTty resources

Some of the resources for PtTty aren’t just data stored in the widget, they’re “action
resources” that define an action to be performed when you set the resource. This
includes all the resources flagged as write-only.
Some of those actions are order-dependent. For example, you can’t spawn a program
on a device (by setting Pt_ARG_TTY_CMD or Pt_ARG_TTY_ARGV) before defining
which device it’s to be spawned on (by setting Pt_ARG_TTY_SFD,
Pt_ARG_TTY_PATH, or Pt_ARG_TTY_PSEUDO).
The widget opens its pty and starts its command as soon as you set
Pt_ARG_TTY_CMD or Pt_ARG_TTY_ARGV, even if the widget hasn’t yet been
realized. By default, the command continues to run if you unrealize the widget.
Additionally, the following resources are order-dependent even though they’re not
action resources:
• Pt_ARG_TERM_ANSI_PROTOCOL
• Pt_ARG_TTY_FDSET
• Pt_ARG_TTY_FLAGS (Pt_TTY_SETENV and Pt_TTY_ARGV0)
• Pt_ARG_TTY_SPAWN_OPTIONS
Since the widget looks at the current value of these resources when spawning the
command, changing their values after a command has been spawned doesn’t affect the
command that’s already running. Make sure that those resources have correct values
before you set Pt_ARG_TTY_CMD or Pt_ARG_TTY_ARGV.
Here’s an example:
/* Open a pseudo tty -- NULL is a shortcut for "/dev";
* the widget will add something like "ttyp3" to it
*/
PtSetArg( &arg, Pt_ARG_TTY_PSEUDO, NULL, 0 );
PtSetResources( ABW_tty, 1, &arg );
/* Have we succeeded? */
PtSetArg( &arg, Pt_ARG_TTY_SFD, 0, 0 );
PtGetResources( ABW_tty, 1, &arg );
if ( arg.value == -1 )
PtTerminalPuts( ABW_tty, "Unable to find a pty\r\n" );
else {
/* Run a program on the pseudo tty.
* NULL is more or less a shortcut for
* "char *argv[] = { "/bin/sh", NULL };",
* except it runs *your* shell rather than always /bin/sh.
*/
PtSetArg( &arg, Pt_ARG_TTY_ARGV, NULL, 0 );
PtSetResources( ABW_tty, 1, &arg );
/* Have we succeeded? */
PtSetArg( &arg, Pt_ARG_TTY_PID, NULL, 0 );
PtGetResources( ABW_tty, 1, &arg );

if ( arg.value == 0 )
PtTerminalPuts( ABW_tty, "Unable to spawn the shell\r\n" );
}
PhAB doesn’t know that these resources are order-dependent. Set the resources in the
correct order. If you suspect that the order isn’t correct, set all the order-dependent
resources to their default values, and then set them again in the correct order.
File descriptors
PtTty uses three file descriptors, but they don’t have to be different. The following
resources are involved:
Pt_ARG_TTY_RFD
The file descriptor that the widget uses for reading. Any input from this fd is
displayed in the widget.
Pt_ARG_TTY_WFD
The fd to which the widget writes keyboard input.
Pt_ARG_TTY_SFD
The fd that the widget maps stdin, stdout, and stderr to when you set
Pt_ARG_TTY_CMD or Pt_ARG_TTY_ARGV.
Pt_ARG_TTY_SFD overrides the entries in the iov array of the

Pt_ARG_TTY_SPAWN_OPTIONS resource that correspond to the set bits in
Pt_ARG_TTY_FDSET.
Pt_ARG_TTY_FDS
A shortcut for setting Pt_ARG_TTY_RFD, Pt_ARG_TTY_WFD, and
Pt_ARG_TTY_SFD to the same value. Setting Pt_ARG_TTY_FDS to -1 closes
any previously open file descriptors and sets Pt_ARG_TTY_PATH to NULL.
When you set Pt_ARG_TTY_RFD or Pt_ARG_TTY_WFD to a file descriptor, the

widget sets the O_NONBLOCK flag on that fd if it isn’t already set.
When the widget is later destroyed, or its resources are changed in such a way that
neither Pt_ARG_TTY_RFD nor Pt_ARG_TTY_WFD references that fd any more, the
widget unsets the O_NONBLOCK flag. If the Pt_ARG_TTY_SFD resource doesn’t
reference that fd either, the fd is then closed.
In short, if you give an fd to a PtTty widget, it’s the widget’s responsibility to close it
when it’s no longer used. If you want to keep the fd, make a copy using dup() (see the
QNX Neutrino Library Reference) and give that copy to the widget. Either way, don’t
use either the copy or the original fd for any I/O while the widget is using it.

Drag and Drop

New resources:

Pt_ARG_TTY_ARGV char ** Pointer (write-only)
Pt_ARG_TTY_BUFFER char, unsigned short Array allocated
Pt_ARG_TTY_BUFLEN unsigned short Scalar 1024
Pt_ARG_TTY_CMD char * String (write-only)
Pt_ARG_TTY_DEVSIZE PtTerminalRowCol_t Struct 0, 0
Pt_ARG_TTY_EXIT_STATUS int Scalar 0 (read-only)
Pt_ARG_TTY_FDS int Scalar -1
Pt_ARG_TTY_FDSET unsigned short Scalar 7
Pt_ARG_TTY_FLAGS unsigned short Flag See below
Pt_ARG_TTY_INPUT char, unsigned short Array (write-only)
Pt_ARG_TTY_INPUT_WRITTEN unsigned short Scalar 0 (read-only)
Pt_ARG_TTY_PATH char * String NULL
Pt_ARG_TTY_PID pid_t Scalar 0
Pt_ARG_TTY_PRI int Scalar -1
Pt_ARG_TTY_PSEUDO char * String NULL
Pt_ARG_TTY_RFD int Scalar -1
Pt_ARG_TTY_SFD int Scalar -1
Pt_ARG_TTY_SPAWN_OPTIONS PtSpawnOptions_t const * Pointer NULL
Pt_ARG_TTY_WFD int Scalar -1
Pt_CB_TTY_DEVSIZE PtCallback_t * Link NULL
Pt_CB_TTY_OUTPUT PtCallback_t * Link NULL
Pt_CB_TTY_TERMINATED PtCallback_t * Link NULL
Pt_ARG_TTY_ARGV (write-only)

When you set this resource, the widget spawns a process on the device. The resource
value must be the pointer to a NULL-terminated array of pointers to strings. These
strings are used for the program name and arguments.
The first string in the array specifies the program to execute. If it doesn’t contain a
slash character, the PATH environment variable is used to search for the program.
If the Pt_TTY_ARGV0 flag is set (which is the default), the first string is also used as
the first argument to the new process (argv[0]). If the flag is clear, the argument list is
assumed to start from the second item of the array passed as the resource value. This
lets you run a program whose argv[0] entry is different from the actual name of the
program.
If the list is NULL or contains too few non-NULL elements (the minimum is one when
the Pt_TTY_ARGV0 flag is set and two when it’s clear), the user’s shell is spawned. If
the Pt_TTY_ARGV0 flag is clear and the list is NULL or empty, this is a login shell.
All the flags and resources described under Pt_ARG_TTY_CMD, except the
Pt_TTY_ARGV0 flag, have the same effect when this resource is set.
Pt_ARG_TTY_BUFFER
char, unsigned short Array allocated
The buffer that’s used by the widget for reading data from the device and passing them
to the PtTerminalPut() function. If you set this resource, you must give both the
address and the length of a buffer for the widget to use. Several widgets may share a
common buffer, provided that none of them attaches a callback that could cause a
recursive invocation of PtTerminalPut().
Pt_ARG_TTY_BUFLEN
The length of the buffer used by the widget for reading data from the device. If you set
this resource, the widget allocates a buffer.
Pt_ARG_TTY_CMD (write-only)
char * String
When you set this resource, the widget spawns a process on the device.

If the resource value is a NULL or points to an empty string, the user’s shell is
spawned. If the resource is a nonempty string, the widget spawns the user’s shell with
two arguments: -c and the resource string. In either case, if the Pt_TTY_ARGV0 flag
is clear, the shell is started as a login shell.
If another process has been spawned previously and is still running, and the
Pt_ARG_TTY_PID resource hasn’t been set to zero, a SIGTERM signal is sent to the
process group of that process before starting the new program.
If the Pt_TTY_SETENV flag is set (which is the default), the TERM environment
variable of the new process is set to a value corresponding to the current terminal
protocol (using the PtTerminalName() function). The environment variables LINES
and COLUMNS are also removed if they exist.
Pt_ARG_TTY_DEVSIZE
The current device size. It can differ from the terminal widget’s size, depending on the
Pt_ARG_TTY_FLAGS resource. The PtTerminalRowCol_t structure contains the
following members:
• short r
• short c
Pt_ARG_TTY_EXIT_STATUS (read-only)
int Scalar 0
The exit status of the process spawned on the device. You can examine the value using
the POSIX macros described for waitpid() in the QNX Neutrino Library Reference.
The value is valid only after the child process has terminated.
Pt_ARG_TTY_FDS
int Scalar -1
A shortcut for setting Pt_ARG_TTY_RFD, Pt_ARG_TTY_WFD, and

Pt_ARG_TTY_SFD to the same value. Setting Pt_ARG_TTY_FDS to -1 closes any
previously open file descriptors and sets the Pt_ARG_TTY_PATH to NULL.
For more details, see “File descriptors,” above.

Pt_ARG_TTY_FDSET

This number defines (as a bitmask) the set of file descriptors that the widget sets for a
new process started when the Pt_ARG_TTY_CMD or Pt_ARG_TTY_ARGV resource
is set. The default value of 7 means that the PtTty widget’s device is available as
descriptors 0, 1 and 2. Only the ten low-order bits are used because the redirection is
done using the iov[] member of the PtSpawnOptions_t structure, which has ten
elements.
Pt_ARG_TTY_FLAGS
unsigned short Flag See below
Flags that affect the widget’s behavior. Any combination of:
• Pt_TTY_DEVRESIZE — when the terminal’s size changes, the device is resized.
• Pt_TTY_TERMRESIZE — when the device size changes, the terminal widget’s size
is set (but the operation may fail if the device size is beyond terminal’s size limit).
• Pt_TTY_DEVLIMIT — when the device size changes beyond the terminal’s size
limit, the device is resized.
• Pt_TTY_DEVFORCE — when the device size changes, it’s resized back to the
terminal’s size.
• Pt_TTY_SETENV — modify environment variables (see Pt_ARG_TTY_CMD).
• Pt_TTY_ARGV0 — use the program name as argv[0] (see Pt_ARG_TTY_CMD).
• Pt_TTY_BUF_PRIVATE (read-only) — the widget is using an allocated buffer.
By default, all bits are set except Pt_TTY_DEVFORCE.

If both Pt_TTY_TERMRESIZE and Pt_TTY_DEVRESIZE flags are set, changes of sizes
are propagated in both directions. However, if the sizes differ at the moment when the
flags are set or when the device is being opened, the device size is adjusted.
If the Pt_TTY_DEVFORCE flag is set, the Pt_TTY_DEVLIMIT flag is ignored.
Pt_ARG_TTY_INPUT

Characters to be written to the device.

Since the device is opened with the O_NONBLOCK flag, the number of bytes that are
actually written may be less than the specified length. You can use the
Pt_ARG_TTY_INPUT_WRITTEN resource to find out how many bytes the widget
managed to write.
Pt_ARG_TTY_INPUT_WRITTEN (read-only)
The number of characters successfully written by the Pt_ARG_TTY_INPUT resource.
Pt_ARG_TTY_PATH
char * String NULL
When you set this resource, the widget closes all its file descriptors, then attempts to
open the given pathname and stores the new fd (or -1 on error) in Pt_ARG_TTY_RFD,
Pt_ARG_TTY_WFD, and Pt_ARG_TTY_SFD.
The descriptor is guaranteed to be greater than 2 and have the FD_CLOEXEC flag set.
Pt_ARG_TTY_PID
pid_t Scalar 0
Zero or the process ID of the process that has been spawned on the device. The only
value to which you can explicitly set this resource is zero, meaning “Forget about that
process.” If this resource is nonzero when the device is closed (e.g. when the widget is
being destroyed), a SIGHUP signal is sent to the process group of the child process.
Pt_ARG_TTY_PRI
int Scalar -1
The priority of Photon pulses attached to the device — see PtAppAddFdPri() in the
Photon Library Reference.

Pt_ARG_TTY_PSEUDO

char * String NULL
When you set this resource, the widget closes all its file descriptors, then attempts to
find and open a pseudo-tty.
The “master” fd is stored in both Pt_ARG_TTY_RFD and Pt_ARG_TTY_WFD, and
the “slave” fd in Pt_ARG_TTY_SFD.
Also, the pathname of the slave device is stored in Pt_ARG_TTY_PATH.
You should set this resource to NULL or to the name of a directory that contains some
ptys.
After opening the pseudo tty, the stty entry of the “slave” device is set to default
modes. The editing keys are set according to the current value of the
Pt_ARG_TERM_ANSI_PROTOCOL resource (see PtTerminal). If the protocol is
changed with the same call to PtSetResources() that opens the pseudo tty, the order of
the argument list is significant.
Both descriptors opened in this mode are guaranteed to be greater than 2 and have the
FD_CLOEXEC flag set.
Pt_ARG_TTY_RFD
int Scalar -1
The file descriptor that the widget uses for reading. Any input from this FD is
displayed in the widget.
Pt_ARG_TTY_SFD
int Scalar -1
The file descriptor to which the widget maps stdin, stdout, and stderr when you set
Pt_ARG_TTY_CMD or Pt_ARG_TTY_ARGV.


Pt_ARG_TTY_FDSET.
Pt_ARG_TTY_SPAWN_OPTIONS
PtSpawnOptions_t const * Pointer NULL
A pointer to a PtSpawnOptions_t structure that’s used for spawning the child

process.
If you leave this resource set to NULL, the widget uses the default values in:
extern const PtSpawnOptions_t PtTtyDefaultSpawnOptions
For more information about this structure, see PtSpawn() in the Photon Library
Reference.

Pt_ARG_TTY_FDSET.
Pt_ARG_TTY_WFD
int Scalar -1
The file descriptor to which the widget writes keyboard input.

When you set this resource, the widget attaches itself to the given file descriptor. The
descriptor must be open in a mode that allows writing. To force the widget to detach
from any file descriptor it’s attached to, set this resource to -1.
Pt_CB_TTY_DEVSIZE

A list of PtCallback_t structures that define the callbacks invoked when a resize
event is received from the device (and before the terminal widget is resized according
to the new size).
following members:
reason Pt_CB_TTY_DEVSIZE
event NULL
cbdata A pointer to a PtTerminalSizeChange_t structure that has at least

following members:
Previous size of the device.
Current size.

• short r
• short c
Pt_CB_TTY_OUTPUT
A list of PtCallback_t structures that define the callbacks invoked when any output
from the device is received (and before the output is passed to the terminal widget)
following members:
reason Pt_CB_TTY_OUTPUT
event NULL
cbdata A pointer to a PtTtyOutput_t structure that has at least following

members defined:
int length; The number of characters received.

const char * buffer;
A pointer to buffer containing the characters.

Pt_CB_TTY_TERMINATED

A list of PtCallback_t structures that define the callbacks invoked after the child
process has terminated. Each callback is passed a PtCallbackInfo_t structure that
reason Pt_CB_TTY_TERMINATED
event NULL
cbdata A pointer to an int containing the Pt_ARG_TTY_EXIT_STATUS

resource.

Pt_ARG_BANDWIDTH_THRESHOLD PtBasic Ph_BAUD_SLOW (see PtTerminal)
continued. . .


Pt_ARG_DIM PtWidget
Pt_ARG_POS PtWidget
continued. . .


Pt_ARG_TERM_APP PtTerminal
Pt_ARG_TERM_COLOR_MODE PtTerminal
Pt_ARG_TERM_COLOR_TABLE PtTerminal
Pt_ARG_TERM_COLS PtTerminal
Pt_ARG_TERM_CONSOLE PtTerminal
Pt_ARG_TERM_CUR_COL PtTerminal
Pt_ARG_TERM_CUR_POS PtTerminal
Pt_ARG_TERM_CUR_ROW PtTerminal
Pt_ARG_TERM_CURSOR_FLAGS PtTerminal
Pt_ARG_TERM_DRAW_MODES PtTerminal
Pt_ARG_TERM_FONT PtTerminal
Pt_ARG_TERM_FONT_LIST PtTerminal
Pt_ARG_TERM_FONT_INDEX PtTerminal
Pt_ARG_TERM_FONT_SIZE PtTerminal
Pt_ARG_TERM_MARGINS PtTerminal
Pt_ARG_TERM_MAXCOLS PtTerminal
Pt_ARG_TERM_MAXROWS PtTerminal
Pt_ARG_TERM_MAXSIZE PtTerminal
Pt_ARG_TERM_MINCOLS PtTerminal
Pt_ARG_TERM_MINROWS PtTerminal
Pt_ARG_TERM_MINSIZE PtTerminal
Pt_ARG_TERM_OPTIONS PtTerminal
Pt_ARG_TERM_OPTMASK PtTerminal
Pt_ARG_TERM_ANSI_PROTOCOL PtTerminal
Pt_ARG_TERM_RESIZE_FL PtTerminal
Pt_ARG_TERM_RESIZE_FUN PtTerminal
Pt_ARG_TERM_RESIZE_STR PtTerminal
Pt_ARG_TERM_ROWS PtTerminal
continued. . .


Pt_ARG_TERM_SCRLBK_COUNT PtTerminal
Pt_ARG_TERM_SCRLBK_LIMIT PtTerminal
Pt_ARG_TERM_SCRLBK_POS PtTerminal
Pt_ARG_TERM_SCROLL PtTerminal
Pt_ARG_TERM_SELECTION PtTerminal
Pt_ARG_TERM_SIZE PtTerminal
Pt_ARG_TERM_VISUAL_BELL PtTerminal
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
continued. . .


Pt_CB_TERM_APP PtTerminal
Pt_CB_TERM_FONT PtTerminal
Pt_CB_TERM_INPUT PtTerminal
Pt_CB_TERM_OPTIONS PtTerminal
Pt_CB_TERM_RESIZE PtTerminal
Pt_CB_TERM_RESIZED PtTerminal
Pt_CB_TERM_SCRLBK PtTerminal
The PtTty widget defines the following convenience function:
PtTtyShell() Return the user’s default shell.

PtTtyShell() © 2010, QNX Software Systems GmbH & Co. KG.
Return the user’s default shell
Synopsis:
const char PtTtyShell( void );
Description:
The PtTtyShell() function returns either the value of the SHELL environment variable
or, if SHELL is undefined, the user’s default shell defined in the passwd file.
This string is used by the PtTty widget to start the user’s shell (see
Pt_ARG_TTY_CMD and Pt_ARG_TTY_ARGV resources to PtTty).
Classification:
Photon
Safety
Signal handler No
Thread No

© 2010, QNX Software Systems GmbH & Co. KG. PtUpDown
Vertical or horizontal increment/decrement buttons
Class hierarchy:
PtWidget → PtBasic → PtUpDown
PhAB icon:
Public header:
<photon/PtUpDown.h>
Description:
The PtUpDown widget creates vertical or horizontal increment/decrement buttons. It
lets you increase or decrease a value.
A PtUpDown widget.
By default, the buttons display images of arrows, but you can use other images if
necessary. You can also specify the armed data, the image displayed when the user
presses one of the buttons.
The Pt_CB_ACTIVATE,Pt_CB_ARM, Pt_CB_DISARM, and Pt_CB_REPEAT
callbacks for the buttons have a subtype that indicates which button was pressed.
New resources:

Pt_ARG_ARM_COLOR PgColor_t Scalar PgGray(170)
Pt_ARG_ORIENTATION int Boolean Pt_VERTICAL
Pt_ARG_SPACING unsigned short Scalar 0
Pt_ARG_UPDOWN_ARM_DATA_DECREMENT PhImage_t * Image NULL
Pt_ARG_UPDOWN_ARM_DATA_INCREMENT PhImage_t * Image NULL
Pt_ARG_UPDOWN_BORDER_WIDTH unsigned short Scalar 1
Pt_ARG_UPDOWN_DATA_DECREMENT PhImage_t * Image NULL
Pt_ARG_UPDOWN_DATA_INCREMENT PhImage_t * Image NULL
Pt_ARG_UPDOWN_FLAGS signed short Flag See below
continued. . .

PtUpDown © 2010, QNX Software Systems GmbH & Co. KG.

Pt_ARG_UPDOWN_INDICATOR_MARGIN unsigned short Scalar 0
Pt_ARG_ARM_COLOR
PgColor_t Scalar Pg_GRAY
The background color used when the button is armed (pressed in). See PgColor_t in
This resource is used only if Pt_ARG_UPDOWN_FLAGS has
Pt_UPDOWN_FILL_ON_ARM set.
Pt_ARG_ORIENTATION
int Boolean Pt_VERTICAL
The direction the arrows are pointing:
• Pt_VERTICAL
• Pt_HORIZONTAL
Pt_ARG_SPACING
The spacing between the increment and decrement buttons, in pixels.
Pt_ARG_UPDOWN_ARM_DATA_DECREMENT
The image for the armed decrement button. This resource is used only if
Pt_UPDOWN_ARM_DECREMENT is set in Pt_ARG_UPDOWN_FLAGS.
Pt_ARG_UPDOWN_ARM_DATA_INCREMENT

The image for the armed increment button. This resource is used only if
Pt_UPDOWN_ARM_INCREMENT is set in Pt_ARG_UPDOWN_FLAGS.
Pt_ARG_UPDOWN_BORDER_WIDTH
The width of the widget’s border, in pixels.
Pt_ARG_UPDOWN_DATA_DECREMENT
The image for the unarmed decrement button. This resource is used only if
Pt_UPDOWN_DECREMENT is set in Pt_ARG_UPDOWN_FLAGS.
Pt_ARG_UPDOWN_DATA_INCREMENT
The image for the unarmed increment button. This resource is used only if
Pt_UPDOWN_INCREMENT is set in Pt_ARG_UPDOWN_FLAGS.
Pt_ARG_UPDOWN_FLAGS
signed short Flag Pt_FILL_ON_ARM
Pt_UPDOWN_INCREMENT_IMAGE
Use the Pt_ARG_UPDOWN_DATA_INCREMENT resource as the image for
the unarmed increment button.
Pt_UPDOWN_DECREMENT_IMAGE
Use the Pt_ARG_UPDOWN_DATA_DECREMENT resource as the image for
the unarmed decrement button.
Pt_UPDOWN_INCREMENT_ARM_IMAGE
Use the Pt_ARG_UPDOWN_ARM_DATA_INCREMENT resource as the
image for the armed increment button.

Pt_UPDOWN_DECREMENT_ARM_IMAGE
Use the Pt_ARG_UPDOWN_ARM_DATA_DECREMENT resource as the
image for the armed decrement button.
Pt_UPDOWN_ROTATE_INDICATORS
Rotate the arrow indicators on the increment and decrement buttons by ninety
degrees. This flag only applies to arrow indicators; it doesn’t rotate images when
images are used.
Pt_UPDOWN_FILL_ON_ARM
Not currently used.
Pt_ARG_UPDOWN_INDICATOR_MARGIN
unsigned Scalar 0
The distance, in pixels, around the button image.

Pt_ARG_COLOR PtBasic Not used by this class.
continued. . .


Pt_ARG_DIM PtWidget
Pt_ARG_FILL_COLOR PtBasic Not used by this class.
Pt_ARG_FILL_PATTERN PtBasic Not used by this class.
Pt_ARG_MARGIN_HEIGHT PtBasic Not used by this class.
Pt_ARG_MARGIN_WIDTH PtBasic Not used by this class.
Pt_ARG_POS PtWidget
Pt_ARG_WIDTH PtWidget 5
Pt_CB_ACTIVATE PtBasic See below
continued. . .


Pt_CB_ARM PtBasic See below
Pt_CB_DISARM PtBasic See below
Pt_CB_DND PtWidget
Pt_CB_FILTER PtWidget Not used by this class.
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
Pt_CB_REPEAT PtBasic See below
Pt_CB_ACTIVATE, Pt_CB_ARM, Pt_CB_DISARM, Pt_CB_REPEAT

These callbacks are passed a PtCallbackInfo_t structure that contains at least the
following members:
unsigned long reason;

unsigned long reason_subtype;
PhEvent_t *event;
void *cbdata;
The callbacks are similar to those for PtButton, except the reason_subtype indicates
which button was pressed:
• UPDOWN_TOP
• UPDOWN_BOTTOM
• UPDOWN_LEFT
• UPDOWN_RIGHT

© 2010, QNX Software Systems GmbH & Co. KG. PtWebClient
Widget for displaying web pages
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtClient → PtWebClient
PhAB icon:
Public header:
<photon/PtWebClient.h>
Description:
You can use the PtWebClient widget to start, interact, and control a web server, such
as Voyager or NetFront. PtWebClient also provides a user-defined area within your
application for the server to format and display web pages. Your application controls
the server by setting widget resources. The server communicates status information
and user interaction back to the application using the widget callbacks.
PtWebClient transparently supports the version of HTML that the server supports.
For more information about the Voyager and NetFront web servers, see the vserver
and netfront documentation in the QNX® Momentics® 6.3.0 Web Browser
Technology Development Kit Release Notes.
The PtWebClient widget can interact with a web server only on self-hosted systems.
On Windows hosts you can use the widget in a PhAB project, but it won’t display
content until run on a target.
Starting the server

Start the server initially by setting the Pt_ARG_WEB_SERVER resource.
Typically, the PtWebClient widget is in a PhAB application, and its
Pt_ARG_WEB_SERVER resource is NULL.
You can set the Pt_ARG_WEB_SERVER resource to either:
• the name of a web server profile
Or:
• a web server command and any command-line options
If you set this resource to a profile name (for example, online), the widget searches
the web server profile files for a match. If a match is found, the widget starts the web
server and client name found in the profile; the Pt_ARG_CLIENT_NAME is ignored
(since it is already in the profile). If the profile is not found, the widget assumes the
resource is the command, including path if required, for the web server’s executable.
If you start the profile name with the @ character, there is no profile lookup. Instead,
the web client widget discards the @, and uses the remaining string as the command
line (including path and options) for starting the server.

PtWebClient © 2010, QNX Software Systems GmbH & Co. KG.
To start the current online web server, do the following in the prerealize setup function
for the module containing the widget:
PtSetArg( &args[0], Pt_ARG_WEB_SERVER, "online", 0 );
PtSetResources( ABW_web_pane, 1, args );
To use the default off-line web server profile, do the following in the prerealize setup
function for the module containing the widget:
PtSetArg( &args[0], Pt_ARG_WEB_SERVER, "offline", 0 );
Once the server is started, you can check that it was successful by getting the value of
Pt_ARG_WEB_STARTUP_ERRNO. For example:
int *error;
PtSetArg( &args[0], Pt_ARG_WEB_STARTUP_ERRNO, &error, 0 );

PtGetResources( ABW_web_pane, 1, args );
if ( *error != EOK ) {
/* error occurred - use errno to display message */
}
After successfully starting the server, you can access URLs by setting the
Pt_ARG_WEB_GET_URL resources.
Migrating from libPtWeb.so.2 to libPtWeb.so.3

If your browser application has been designed to work with the PtWebClient widget
from libPtWeb.so.2, and you want to migrate to the new PtWebClient API in
libPtWeb.so.3, you should be aware of some changes that are required in your
code:
1 All the macros starting with WWW_ are renamed to start with Pt_WEB_ now.
You should change your code accordingly. For example:
WWW_RESPONSE_OK is now Pt_WEB_RESPONSE_OK. The compiler will
probably make you aware of this if you try to compile code that uses the old
macro names.
2 In all the structures that are passed either from the server to PtWebClient or
from PtWebClient to the server, members that were char member[] are now
pointers to char, char *member.
This change is particularly important in the structures that are filled in by the
user. Therefore the following structures have been renamed to make the
compiler aware:
• PtWebClientAuthenticationData_t — renamed
PtWebClient2AuthenticationData_t
• PtWebClientHelperData_t — renamed
PtWebClient2HelperData_t
• PtWebClientUnknownData_t — renamed
PtWebClient2UnknownData_t

• PtWebClientData_t — renamed PtWebClient2Data_t

• PtWebCommand_t — renamed PtWebClient2Command_t
• PtWebClientSSLResponse_t — renamed
PtWebClient2SSLResponse_t
For example, PtWebClientAuthenticationData_t used to be defined as:

typedef struct {
short response;
short type;
char userid[255];
char password[255];
char url[MAX_URL_LENGTH];
} PtWebClientAuthenticationData_t;
It’s now defined as:

typedef struct {
short response;
short type;
char *userid;
char *password;
char *url;
} PtWebClient2AuthenticationData_t;
You should allocate the userid, password and url members , and it’s your
responsibility to free them.
New resources:

Pt_ARG_WEB_ACTIVATE_LINK int Scalar 0 (write-only)
Pt_ARG_WEB_AUTHENTICATE See below Pointer NULL (write-only)
Pt_ARG_WEB_BUILD_DATE char * String NULL (read-only)
Pt_ARG_WEB_COMMAND PtWebClient2Command_t * Pointer NULL (write-only)
Pt_ARG_WEB_DATA PtWebClient2Data_t * Pointer NULL (write-only)
Pt_ARG_WEB_DOWNLOAD char *, char * String N/A (write-only)
Pt_ARG_WEB_ENCODING char * String NULL
Pt_ARG_WEB_GET_CERTIFICATES See below Pointer NULL (read-only)

Pt_ARG_WEB_GET_CONTEXT char * String NULL (read-only)
continued. . .


Pt_ARG_WEB_GET_HISTORY See below Pointer None (read-only)
Pt_ARG_WEB_GET_URL char * String N/A (write-only)
Pt_ARG_WEB_HELPER See below Pointer NULL (write-only)

Pt_ARG_WEB_H_ERRNO int Scalar 0
Pt_ARG_WEB_IMPORT_CERTIFICATE See below Pointer N/A (write-only)
Pt_ARG_WEB_NAVIGATE_FRAME int Scalar 0
Pt_ARG_WEB_NAVIGATE_LINK int Scalar 0
Pt_ARG_WEB_NAVIGATE_PAGE int Scalar 0
Pt_ARG_WEB_OPTION char *, char* String NULL
Pt_ARG_WEB_PRINT PpPrintContext_t *, int Pointer NULL (write-only)

Pt_ARG_WEB_RELOAD N/A N/A N/A (write-only)
Pt_ARG_WEB_SERVER char * String NULL
Pt_ARG_WEB_SERVER_PID pid_t Scalar read-only

Pt_ARG_WEB_SSL_RESPONSE See below Pointer NULL
Pt_ARG_WEB_STARTUP_ERRNO int Scalar 0
Pt_ARG_WEB_STOP N/A N/A N/A (write-only)
Pt_ARG_WEB_UNKNOWN_RESP See below Pointer NULL (write-only)

Pt_ARG_WEB_VERSION char * String NULL (read-only)
Pt_CB_WEB_AUTHENTICATE PtCallback_t * Link NULL
Pt_CB_WEB_CLOSE_WINDOW PtCallback_t * Link NULL
Pt_CB_WEB_COMPLETE PtCallback_t * Link NULL
Pt_CB_WEB_CONTEXT PtCallback_t * Link NULL
Pt_CB_WEB_DATA_REQ PtCallback_t * Link NULL
Pt_CB_WEB_DOWNLOAD PtCallback_t * Link NULL
Pt_CB_WEB_ERROR PtCallback_t * Link NULL
Pt_CB_WEB_IMPORT_CERTIFICATE PtCallback_t * Link NULL
Pt_CB_WEB_METADATA PtCallback_t * Link NULL
Pt_CB_WEB_NEED_SCROLL PtCallback_t * Link NULL
Pt_CB_WEB_NEW_WINDOW PtCallback_t * Link NULL
continued. . .


Pt_CB_WEB_PAGE_INFO PtCallback_t * Link NULL
Pt_CB_WEB_SSL_CERTINFO PtCallback_t * Link NULL
Pt_CB_WEB_SSL_CERTNONTRUSTED PtCallback_t * Link NULL
Pt_CB_WEB_SSL_CLIENT_CERT_SELECT PtCallback_t * Link NULL
Pt_CB_WEB_SSL_ERROR PtCallback_t * Link NULL
Pt_CB_WEB_START PtCallback_t * Link NULL
Pt_CB_WEB_STATUS PtCallback_t * Link NULL
Pt_CB_WEB_UNKNOWN PtCallback_t * Link NULL
Pt_CB_WEB_URL PtCallback_t * Link NULL
Pt_ARG_WEB_ACTIVATE_LINK (key mode only)

int Scalar 0 (write-only)
This resource activates and deactivates the current link.
• If the current link is an image map and it’s activated, a cursor appears at the top-left
corner of the image and the Pt_ARG_WEB_NAVIGATE_LINK resource moves the
cursor in the appropriate direction. If you then set
Pt_ARG_WEB_ACTIVATE_LINK to 0, the link in the imagemap is activated; if
you set this resource to 1, the image map selection is canceled.
• If a form type of TEXTAREA or TEXT is active, setting this resource to 0 gives

focus, and a value of 1 removes focus.
Pt_ARG_WEB_AUTHENTICATE
PtWebClient2AuthenticationData_t * Pointer NULL (write-only)
Set this resource to give authentication information to the server when the
Pt_CB_WEB_AUTHENTICATE callbacks have been invoked. The data structure used
is as follows:
typedef struct {
short response;
short type;
char *userid;
char *password;
char *url;
} PtWebClient2AuthenticationData_t;


response The type of response:
• Pt_WEB_RESPONSE_OK — the information is valid.
• Pt_WEB_RESPONSE_CANCEL — cancel the authentication request.
type The type of authentication:

• Pt_WEB_BASIC_AUTHENTICATION
• Pt_WEB_DIGEST_AUTHENTICATION
• Pt_WEB_PROXY_AUTHENTICATION.
userid A pointer to the user’s login string.
password A pointer to the user’s password string.
url A pointer to the URL of the request that invoked the callback.
Pt_ARG_WEB_BUILD_DATE (read only)

char * String NULL (read-only)
The build date of the connected web server.
Pt_ARG_WEB_COMMAND (write only)

PtWebClient2Command_t * Pointer NULL
Tell the server to perform a specific command. The command is specified in the len
argument to PtSetArg(). If a pointer to the PtWebClient2Command_t data structure
is required with the command, pass it as the value argument to PtSetArg().
The PtWebClient2Command_t data structure is as follows:
typedef struct {
union {
struct {
char *filename;
} SaveasInfo;
struct {
char *String;
unsigned long flags;
} FindInfo;
struct {
char *string;
int number;
} SetWidgetInfo;
struct {
int input_group;
} ClipboardInfo;

char *scroll_to;
int reset_type;
int num_purge;
};
} PtWebClient2Command_t;
The commands are:
Pt_WEB_COMMAND_FIND
Find and highlight a word in the current document. The part of the
PtWebClient2Command_t data structure used is:
struct {
char *string;
unsigned long flags;
} FindInfo;
where:
• string — a pointer to the word to find in the document.
• flags — a combination of:
- Pt_WEB_FIND_START_AT_TOP — start the search at the top of the
document.
- Pt_WEB_FIND_MATCH_CASE — match the character case in the word.
- Pt_WEB_FIND_GO_BACKWARDS — search backward.
- Pt_WEB_FIND_MATCH_WHOLE_WORDS — match whole words.
Pt_WEB_COMMAND_LOADMISSING
Load any missing images.
Pt_WEB_COMMAND_SAVEAS
Save the current document to disk. The part of the PtWebClient2Command_t
data structure used is:
struct {
char *filename;
} SaveasInfo;
where filename is a pointer to the name of the file in which to save the document.
Pt_WEB_COMMAND_RESET_OPT
Cause any changed options that may change the current visible page to take
effect.
Pt_WEB_COMMAND_PURGE_CACHE
Purge the in-memory image and page cache.
Pt_WEB_COMMAND_LOADMISSING_CONTEXT
Load a missing image whose context is valid (the context is valid after a
Pt_CB_WEB_CONTEXT callback).

Pt_WEB_COMMAND_SET_WIDGET
Set the value of a text control. The part of the PtWebClient2Command_t data
structure used is:
struct {
char *string;
int number;
} SetWidgetInfo;
where:
• string — a pointer to the string that you want to set the contents of the
control to.
• number — the numeric ordinal of the control you want to change (as returned
in the Pt_CB_WEB_STATUS callbacks of type
Pt_WEB_STATUS_CONTENTS).
Pt_ARG_WEB_DATA (write only)

PtWebClient2Data_t * Pointer NULL
Voyager server only.

This resource is set in response to a Pt_CB_WEB_DATA_REQ callback. It provides
the header and data of the client protocol data stream to the browser.
The data structure used is as follows:
typedef struct {
int type;
char *url;
int length;
char *data;
} PtWebClient2Data_t;
The members are:
type Possible values:

• Pt_WEB_DATA_HEADER — the data is the header of the request.
• Pt_WEB_DATA_BODY — the data is the body of the request.
• Pt_WEB_DATA_CLOSE — this flag closes (aborts) the request.
url A pointer to the URL of this client data stream.
length The number of bytes of data (no more than what was asked for in the
Pt_CB_WEB_DATA_REQ callback).
data A pointer to the data.
Here’s an example of using the client protocol:

int web_data( PtWidget_t *widget, ApInfo_t *apinfo,

{
PtArg_t args[1];
PtWebClient2Data_t webdata;
PtWebDataReqCallback_t *web_data_req = cbinfo->cbdata;
const char *html =
"<html><body bgcolor=\"#ffffff\"><p>\
<center><table border=1 bgcolor=\"#f8f7d9\"><tr>\
<td>This is a simple test of the client protocol</td>\
<td><font size=4>Voyager Client: Version 2.01\
<br>Built on: %s<br><hr>\
<font size=4>Voyager Server: %s<br>Built on: %s\
</font></center></td></tr></table></center>
<p>\
</body></html>\n";
char about[512];
static int about_sent;
/* eliminate ’unreferenced’ warnings */

apinfo = apinfo;
if ( !strcmp( web_data_req->url, "client:about" ) ) {

if( cbinfo->reason_subtype == Pt_WEB_DATA_HEADER ) {
const char *data = "Content-Type: text/html\n";
webdata.type = Pt_WEB_DATA_HEADER;
webdata.length = strlen(data);
strcpy( webdata.url, web_data_req->url );
PtSetArg( &args[0], Pt_ARG_WEB_DATA, data,
&webdata );
PtSetResources( widget, 1, args );
} else if( cbinfo->reason_subtype == Pt_WEB_DATA_BODY ) {
/*
* Since no content length was given, you need
* to signal EOF with a zero length data packet
*/
if ( about_sent ) {
webdata.type = Pt_WEB_DATA_BODY;
webdata.length = 0;
PtSetArg( &args[0], Pt_ARG_WEB_DATA, "",
&webdata );
about_sent = 0;
} else {
char *version, *build_date;
PtSetArg( &args[0], Pt_ARG_WEB_VERSION,

&version, 0 );
PtSetArg( &args[1], Pt_ARG_WEB_BUILD_DATE,
&build_date, 0 );
PtGetResources(widget, 2, args );
sprintf( about, html, __DATE__, version,
build_date );
webdata.length = strlen(about);
PtSetArg( &args[0], Pt_ARG_WEB_DATA, about,
&webdata );
about_sent = 1;
}
}

} else {
if( cbinfo->reason_subtype == Pt_WEB_DATA_HEADER ) {
/*
* If I give a content length then I don’t need
* provide a zero byte data packet
*/
const char *data =
"Content-Type: text/plain\nContent-Length: 20\n";
webdata.type = Pt_WEB_DATA_HEADER;
webdata.length = strlen(data);
&webdata );
} else if( cbinfo->reason_subtype == Pt_WEB_DATA_BODY ) {
const char *data = "Unknown client type\n";
webdata.length = strlen( data );
&webdata );
}
}
return( Pt_CONTINUE );
}
Pt_ARG_WEB_DOWNLOAD (write only)

char *, char * String N/A
This resource lets you download a file without having to wait for the
Pt_CB_WEB_UNKNOWN callback to provide a file. The value argument of
PtSetArg() should contain the URL of the file to download and the len argument
should contain the filename to save it as.
Pt_ARG_WEB_DOWNLOAD does GET requests only.
Pt_ARG_WEB_ENCODING
char * String NULL
The current document encoding. See PxTranslateSet() in the Photon Library

Reference.
For the netfront server, you can set this resource to Autodetect Encoding (the
default setting). When this value is set, the netfront server will try to auto detect the
encoding.

Pt_ARG_WEB_GET_CERTIFICATES (read only)

PtWebSSLClientCertificates_t * Pointer NULL
This resource gets information about current client certificates.

typedef struct {
int ncert;
char *url;
int reserved1;
int reserved2;
PtWebSSLCertInfo_t info[1];
} PtWebSSLClientCertificates_t;
The members are:
ncert The number of certificates.
url Not used.
info A PtWebSSLCertInfo_t structure that contains information about the

certificate. See the Pt_CB_WEB_SSL_CERTNONTRUSTED resource for
a description of the PtWebSSLCertInfo_t structure.
Pt_ARG_WEB_GET_CONTEXT (read only)

char * String NULL
This resource gets the context information, which is valid after a

Pt_CB_WEB_CONTEXT callback. To get context information, specify the type in the
len argument of PtSetArg().
The possible context types are:
Pt_WEB_CONTEXT_ANCHOR
The URL of a link.
Pt_WEB_CONTEXT_OBJECT
The URL of a image or embedded object.
Pt_WEB_CONTEXT_BKGD
The URL of a background image.

Pt_ARG_WEB_GET_HISTORY (read only)

PtWebClientHistory_t * Pointer None
Use this resource to get the site history list from the browser. This is a list of titles and
URLs of all the sites visited in the timeframe specified in the History_Expire
option (default 4 days).
The data structures used with this resource are:
typedef struct {
short num;
short offset;
} PtWebClientHistory_t;
where:
• num — the number of history entries to return
• offset — the offset into the history site list at which to begin.
and:
typedef struct {
char *title;
char *url;
time_t lastvisited;
} PtWebClientHistoryData_t;
When you use these structures, you pass PtWebClientHistory_t as the value
argument to PtSetArg(), and PtWebClientHistory_t as the len argument.
Here’s an example of how to get the history:
PtArg_t args[1];
PtWebClientHistoryData_t list[HISTORY_REQUEST_SIZE];
PtWebClientHistory_t list_info;
char *description[HI_MAX_LIST_SIZE];
int i, item_count = 0, loop = TRUE;
list_info.num = HISTORY_REQUEST_SIZE;
list_info.offset = 0;
/* retrieve history list from voyager server */

while (loop) {
/* get the next 10 history entries */
PtSetArg(&args[0], Pt_ARG_WEB_GET_HISTORY,
&list, &list_info);
PtGetResources( w, 1, args);
for (i=0; i < 10; i++, item_count++) {

if (list[i].url[0] == NULL ||
list[i].url[0] == 0 ||

item_count >= HI_MAX_LIST_SIZE) {

loop = FALSE;
break;
}
if ( description[item_count] =
malloc(strlen(list[i].url) +
strlen(list[i].title) + 4) )
sprintf(description[item_count], "%s\t%s\t",
list[i].title, list[i].url);
}
list_info.offset += HISTORY_REQUEST_SIZE;
}
Pt_ARG_WEB_GET_URL (write only)

char * String N/A
The URL that you want the browser to display or save. Set the len argument of
PtSetArg() to one of:
Pt_WEB_ACTION_DISPLAY
Display the URL in the browser.
Pt_WEB_ACTION_SAVEAS
Download and save the URL.
You can OR the following flags into the action to control the caching of the page and
the recording of history (these flags are supported by vserver only):
Pt_WEB_NO_MEMORY_CACHE
Don’t cache the page in memory.
Pt_WEB_NO_DISK_CACHE
Don’t cache the page on disk.
Pt_WEB_NO_SITE_HISTORY
Don’t record the site in the site history.
Pt_WEB_NO_PAGE_HISTORY
Don’t record the site in the page history.

• When saving a URL, the browser responds with a Pt_CB_WEB_UNKNOWN to

obtain a filename to save the file once it has determined that it can get the URL or
see Pt_ARG_WEB_DOWNLOAD .
• The maximum length of a URL string is 1024 bytes or MAX_URL_LENGTH.
Pt_ARG_WEB_HELPER (write only)

PtWebClient2HelperData_t * Pointer NULL
Setting this resource tells the server which external helper applications are available.
typedef struct {
short action;
char *mimetype;
char *suffixes;
char *encoding;
char *helperapp;
} PtWebClient2HelperData_t;
The members of this structure are:
action The action to take:

• Pt_WEB_ACTION_ADD — add the external helper.
• Pt_WEB_ACTION_DELETE — delete the external helper (if added
previously).
mimetype A pointer to the mimetype of the data that the helper application can
handle.
suffixes A pointer to the file suffixes of the helper application data files (e.g.
"mpeg mpg").
encoding Currently not used.
helperapp A pointer to the complete filename to the helper application; use %s to

indicate where the data file should appear on the command line.

If you wish to control the running of the helper application yourself, add the helper
with no help application (i.e. helperapp=""). A Pt_CB_WEB_UNKNOWN
callback is called if an HTML page contains an <embed> tag to a file with the
mimetype or suffix provided. (Normally these files are ignored.)
Pt_ARG_WEB_H_ERRNO
int Scalar 0
The value of h_errno after a DNS failure. The possible values are:
HOST_NOT_FOUND
No such host is known.
NO_DATA The name is known to the name server, but has no IP address
associated with it—this isn’t a temporary error. Another type of
request to the name server using this domain name results in an
answer (e.g. a mail-forwarder may be registered for this domain).
NO_RECOVERY Some unexpected server failure was encountered. This is a

nonrecoverable error.
TRY_AGAIN This is usually a temporary error and means that the local server
didn’t receive a response from an authoritative server. A retry at
some later time may succeed.
Pt_ARG_WEB_IMPORT_CERTIFICATE
PtWebImportCertificate_t Pointer 0
NetFront server only.

Set this resource when you want a client certificate to be imported.
typedef struct {
int type;
char *path;
} PtWebImportCertificate_t;

type The type of certificate to be imported. It can be one of:

• Pt_WEB_CERT_TYPE_DER — x509 certificate
• Pt_WEB_CERT_TYPE_PKCS7
• Pt_WEB_CERT_TYPE_PKCS12
path The full path to the file that contains the certificate data.
After you set this resource, the netfront server starts importing the certificate. If the
certificate is password-protected, netfront issues a Pt_CB_WEB_AUTHENTICATE
with type=Pt_WEB_IMPORT_CERT_AUTHENTICATION. (In this case action, realm,
and url aren’t used.) The client responds by setting the password member of the
Pt_ARG_WEB_AUTHENTICATE resource. The netfront server then continues
importing the certificate. If an error or a warning needs to be displayed, the
Pt_CB_WEB_SSL_ERROR and Pt_CB_WEB_SSL_CERTNONTRUSTED are
invoked with reason set to Pt_WEB_SSL_IMPORT_CERT.
At the end of the import process, a Pt_CB_WEB_IMPORT_CERTIFICATE is
invoked indicating whether the process was successful or not.
Pt_ARG_WEB_NAVIGATE_FRAME
int Scalar 0
Controls focus navigation of FRAMES pages when the browser is in key mode. Set
the value argument of PtSetArg() to one of:
Pt_WEB_DIRECTION_UP
Focus the frame above the current one.
Pt_WEB_DIRECTION_DOWN
Focus the frame below the current one.
Pt_WEB_DIRECTION_LEFT
Focus the frame to the left of the current one.
Pt_WEB_DIRECTION_RIGHT
Focus the frame to the right of the current one.
Pt_WEB_DIRECTION_FWD
Focus the next frame.
Pt_WEB_DIRECTION_BACK
Focus the previous frame.

The next and previous directions are defined by the order of the <FRAME> tags in each
<FRAMESET> tag.
Pt_ARG_WEB_NAVIGATE_LINK
int Scalar 0
This resource controls focus navigation of links on the current page when the browser
is in key mode. Set the value argument to PtSetArg() to one of the following:
Pt_WEB_DIRECTION_UP
Focus the link above the current one.
Focus the link below the current one.
Focus the link to the left of the current one.
Focus the link to the right of the current one.
Focus the next link.
Focus the previous link.
Pt_WEB_DIRECTION_FIRST
Focus the first link on the current page.
Pt_WEB_DIRECTION_LAST
Focus the last link on the current page.
When an IMAGE-MAP type link has been activated, this resource is used to navigate
the “ImageMap_Cursor” over the image map in the specified direction. The len
argument is then used to specify the number of pixels to move the cursor.
When a FORM type object has been activated (given focus), these commands are
turned into cursor-key directions and given to the form object.

The next and previous directions are defined by the order of the links in the HTML
page.
Pt_ARG_WEB_NAVIGATE_PAGE
int Scalar 0
This resource controls the scrolling of the displayed page and the ability to navigate
back and forward through pages in the page history. Set the value argument to a
direction and the len argument to the amount to scroll, in percentage of the visible
page (e.g. 100 to scroll one full page). The direction must be one of:
Pt_WEB_DIRECTION_UP
Scroll the page up.
Scroll the page down.
Scroll the page to the left.
Scroll the page to the right.
Go to the previous page in the page history.
Go to the next page in the page history.
The len argument has no effect when using Pt_WEB_DIRECTION_FWD or

Pt_WEB_DIRECTION_BACK.
Getting the value of this resource indicates whether or not you can perform a given
operation. Currently, only Pt_WEB_DIRECTION_FWD and
Pt_WEB_DIRECTION_BACK are supported.
The format of the data returned is 1 << Pt_WEB_DIRECTION_xx. For example:
int *nav_dir;
PtSetArg( &arg, Pt_ARG_WEB_NAVIGATE_PAGE, &nav_dir, 0 );

PtGetResources( webclient, 1, args );
if ( *nav_dir & (1 << Pt_WEB_DIRECTION_FWD ) ) {
/* I can go forward in the page history */
} else if ( *nav_dir & (1 << Pt_WEB_DIRECTION_BACK ) ) {
/* I can go backward in the page history */
Pt_ARG_WEB_OPTION
char *, char* String NULL
Set this resource to set options on the web server. This resource takes two parameters:
• value — the setting of the options.
• len — the string that describes the option.
For example, to change the scrollbar size:
PtArg_t args[1];
PtSetArg( &args[0], Pt_ARG_WEB_OPTION, "10",

"iScrollbarSize" );
PtSetResources( webclient_wgt, 1, args );
You can read the options from the server by getting the value of this resource. The
following piece of code increases the font size by one level:
char *size;
PtSetArg( &args[0], Pt_ARG_WEB_OPTION, &size,

"iUserTextSize" );
PtGetResources( ABW_web_pane, 1, args );
if ( size ) {
fontsize = atoi( size );
if ( fontsize < 3 ) {
sprintf( buf, "%d", fontsize + 1 );
PtSetArg( &args[0], Pt_ARG_WEB_OPTION,
buf, "iUserTextSize" );
}
}

If you’re changing options that have visual effects after the PtWebClient widget is
realized, then you must issue a reset command in order for the changes to be seen. The
command is as follows:
PtSetArg( &args[0], Pt_ARG_WEB_COMMAND, 0,

Pt_WEB_COMMAND_RESET_OPT );
The following sections list the options and their defaults:
• HTML Options
• HTTP cookie options
• Authentication options
• FTP options
• Gopher options
• HTTP options
• File options
• Image options
• Print options
• SOCKS options
• TCP/IP options
• Disk Cache options
• Miscellaneous options
• NetFront-specific options
HTML Options
The HTML options are:
A:active color The color of a link when you click on it with the mouse.
Default: "#ff0000"
A:link color The normal color of a link.

Default: "#0000ff"
A:visited color The color of a link after it’s been visited.

Default: "#008080"

bAutoLoadImages Voyager server only.

If "TRUE", images are loaded as they’re encountered in the
page. If "FALSE", images are loaded only if the
Pt_WEB_COMMAND_LOADMISSING command is issued.
Default: "TRUE"
bDisableHighlight
Don’t highlight text while dragging over it.
Default: "FALSE"
bDisableImagePlaceHolders
Disable drawing image placeholders for missing or invalid
images.
Default: "FALSE"
bIgnoreDocumentAttributes
If "TRUE", color attributes override what’s specified in the page.
Default: "FALSE"
bkey_mode Voyager server only.

If set to "TRUE", key navigation is enabled.
Default: "FALSE"
BODY background The color of the page background.

Default: "#ffffff"
BODY color The color of text inside the body on the HTML page.
Default: "#000000"
BODY font-family
The font family name of the text in the body portion of the page.
BODY margin-right
The margin, in pixels, between right side of display area and the
first visible element in the page (Note: page tags may override
this).
Default: "10"
BODY margin-top The margin, in pixels, between top of display area and the first
visible element in the page (Note: page tags may override this).
Default: "20"

bot_border_color
The bottom color of borders in frame pages.
Default: "#606060"
bot_focus_color Voyager server only.

The bottom color of the focus box in key mode.
Default: "#7f7f00"
bUnderlineLinks If "TRUE", the link on a page is underlined.

Default: "TRUE"
bview_source Voyager server only.

Allow page source to be viewed. Setting this option to
"FALSE" saves memory.
Default: "TRUE"
disable_exception_dlg
Don’t allow the Javascript exception dialog to be displayed.
Default: "FALSE"
disable_new_windows
Don’t allow Javascript windows to open.
Default: "FALSE"
enable_link_arm Voyager server only.

Activate links on arming (useful for touch screens).
Default: "FALSE"
enable_print_bgcolor
Print background colors.
Default: "FALSE"
Focus_Outline_Color
NetFront only
The colour of the focus outline, in RGB format.
Default: "#9098F8"
form_font Voyager server only.

The font used for lists, comboboxes, submit buttons and reset
buttons.

frame_spacing Voyager server only.

The spacing between frames, in pixels.
Default: "2"
H* font-family Voyager server only.

The font family name of the text used in headings on the page.
iReformatHandling
Reformat handling
Default: "2"
Possible values:
• "0" — no progressive formatting or display. Subviews can
be progressively requested, but nothing formats or displays
until the document reaches a totally stable state. This mode
is commonly used for kiosk browsers and is also useful for
devices.
• "1" — reformat once after all subviews are loaded. Text is
displayed immediately as it comes in, and subviews that
have size hints are displayed as they arrive without
reformatting. Reformatting isn’t done until the entire
document is complete. However, any other reformatting,
such as resizing the window, brings those subviews with size
hints onto the screen.
• "2" — reformat the GUI after each subview is loaded. Any
subviews with size hints are displayed without reformatting.
However, subviews without hints trigger a partial reformat as
soon as their size is known, so they can be displayed
immediately.
iScrollbarSize The scrollbar width, in pixels.

Default: "16"
iUserTextSize The base logical font size of text size used in the page.
Defaults:
Voyager — "2"
NetFront — "100"
Possible values:
Voyager uses values between "0" and "4" for small to large
text, with "2" being average size.
NetFront uses values larger than "5", which represent the
percent of original size of the text, with "100" being the
original size.

java_disable Voyager server only.

Disable Java applet tag parsing (forced "TRUE" if
vgr_javanpl.so isn’t found).
Default: "FALSE"
mono_form_font Voyager server only.
The font used for editable form fields.
PRE font-family Voyager server only.
The font family name used for preformatted text ( this should be
a fixed-width font).
top_border_color
The top color of borders in frame pages.
Default: "#ffffff"
top_focus_color Voyager server only.
The top color of the focus box in key mode.
Default: "#ffff00"
underline_width Voyager server only.
The line thickness, in pixels, of the underline used on links.
Default: "1"
HTTP cookie options
The HTTP cookie options are:
cookiejar_name
The name of file to store cookie information in.
Default: "cookie.jar"
cookiejar_path
The directory used to write the cookie file in.
Default: "$(HOME)"
cookiejar_save_always
Always keep the cookie-jar file on disk up-to-date.
Default: "FALSE"
cookiejar_size
The maximum size, in bytes, that the cookie-jar file is allowed to grow. A value
of "-1" means no limit.
Default: "-1"

Authentication options
The authentication options are:
max_password_guesses
The maximum number of guesses allowed when performing authentication.
Default: "3"
FTP options
The FTP options are:
email_address Voyager server only.

The email address used for the password on anonymous logins
on the FTP server.
Default: "80"
ftp_proxy_host Voyager server only.

The host name or IP address of proxy server for FTP requests.
Default: none
ftp_proxy_port Voyager server only.

The port number on the FTP proxy server to use.
Default: "80"
proxy_overrides A comma-separated list of host names or IP addresses to

bypass the FTP proxy server when accessed.
Default: "80"
Gopher options
The Gopher options are:
gopher_proxy_host
The host name or IP address of the proxy server for gopher requests.
Default: none
gopher_proxy_port
The port number on the gopher proxy server to use.
Default: "80"

proxy_overrides
A comma-separated list of host names or IP addresses to bypass the gopher
proxy server when accessed.
Default: none
HTTP options
The HTTP options are:
http_proxy_host
The host name or IP address of the proxy server for HTTP requests.
Default: none
http_proxy_port
The port number on the HTTP proxy server to use.
Default: "80"
proxy_overrides
A comma-separated list of host names or IP addresses to bypass the HTTP
proxy server when accessed.
Default: none
File options
The file options are:
file_display_dir
Display directory listings as HTML pages. For example, file:/ produces an
HTML page with the content of the root directory.
Default: "TRUE"
file_strict_access
Enable strict file access (file: URLs must have the
Pt_WEB_STRICT_FILE_ACCESS flag set when requested via
Pt_ARG_WEB_GET_URL or Pt_ARG_WEB_DOWNLOAD).
Default: "FALSE"
Image options
The image options are:

bProgressiveImageDisplay
Display images progressively as they’re being loaded.
Default: "TRUE"
concurrent_decodes
The number of concurrent JPEG decodings that should be done. This option is
write-only. This option can save significant memory when decoding JPEGS to
256 colors.
Default: "4"
quantize_jpegs
Always convert JPEGs to a 256-color palette. (The default is based on the
current graphics mode; if running on a high-color or direct-color graphics driver,
JPEGs are converted to the default color mode, usually 24-bit. If a palette-based
graphics driver is running, the JPEGs are always converted to 256 colors using
the current hardware palette, and setting this option has no effect.)
Default: "FALSE"
Print options
The print options are:
Print_Left_Footer_String
The left footer used when printing.
Default: "Page &"
Print_Left_Header_String
The left header string used when printing.
Default: "&w"
Print_Header_Font
The font used in the header and footer.
Default: "helv"
Print_Header_Font_Size
The font size used in the header and footer.
Default: "8"
Print_Right_Footer_String
The right footer used when printing.
Default: "&d &t"
Print_Right_Header_String
The right header string used when printing.
Default: "&u"

You can use these special characters in the header and footer strings:
"&w" Page title.

"&u" URL.
"&p" Page number.
"&d" Date — American style (“mmm dd yyyy”).
"&D" Date — European style (“dd mmm yyyy”).
"&t" Time — 12-hour format (“HH:MM am”).
"&T" Time — 24-hour format (“HH:MM”).
"&&" The ampersand ("&") character.
SOCKS options
These options are for the Voyager server only. The SOCKS options are:
socks_app The application name to pass to the SOCKS server.

Default: none
socks_port The port number on the SOCKS server to use.
Default: none
socks_server The host name or IP address of the SOCKS server for any
requests.
Default: none
socks_user The user ID to pass to the SOCKS server.
Default: none
TCP/IP options
The TCP/IP options are:
file_buckets Voyager server only.

Fill network buffers before processing them.
Default: "TRUE"
max_connections
Default: "4"
socket_timeout
Default: "2400"

Disk-cache options
The disk-cache options are:
clear_main_cache_on_exit
Clear the on-disk cache when the browser exits.
Default: "FALSE"
dcache_verify_policy
0 means never verify if the document has changed;
1 means verify if the document has changed once per session;
2 means always verify if the document has changed.
Default: "0"
Note: Verifying is done by using the “If-Modified-Since” request-header.
enable_disk_cache
Enable on-disk caching.
Default: "TRUE"
keep_index_file_updated
Keep the disk-cache index file updated on disk when it changes, instead of
updating it once on exiting.
Default: "FALSE"
main_cache_dir
The directory used to store cache files.
Default: "/tmp"
main_cache_kb_size
The maximum size of the on-disk cache.
Default: "5000"
main_index_file
The name of the cache index file.
Default: "main.ndx"
Miscellaneous options
The miscellaneous options are:
IBeam_Cursor See /usr/include/photon/PhCursor.h

Default: "e90e" (the insert cursor)

Link_Cursor See /usr/include/photon/PhCursor.h

Default: "e90c" (the finger cursor)
Normal_Cursor See /usr/include/photon/PhCursor.h

Default: "e900" (the pointer cursor)
Page_History_Length
The maximum number of pages allowed in the page history
(back/forward history).
Default: "50"
Use_Anti_Alias Use anti-aliased fonts.

Default: "TRUE"
Use_Double_Buffer
Enable double-buffered rendering.
Default: "TRUE"
Visitation_Horizon
The number of days after which to expire the visited links
display (i.e. VLINK -> LINK).
Default: "4"
Voyager-server-only miscellaneous options:
Accept_Charset_Header
The value string to pass with the Accept-Charset header (see
the HTTP specification).
Default: "TRUE"
Accept_Language_Header
The value string to pass with the Accept-Language header (see
the HTTP specification).
Default: "TRUE"
Global_History_File
The full pathname of the file to store the site history list in. (Note:
this page is an HTML-formatted page.)
Default: none
History_Expire
The number of days used to expire entries in the site history list.
(Note: set to "0" to remove the history when the client is shut
down and restarted.)
Default: "4"

Image_Cache_Size_KB
The size of image cache, in kilobytes.
Default: "1024"
ImageMap_Cursor
See /usr/include/photon/PhCursor.h
Default: "e90c" (the finger cursor)
ImageMap_Cursor_NoLink
Default: "e900" (the pointer cursor)
LinkWait_Cursor
Default: "e918" (the point-wait cursor)
NormalWait_Cursor
Default: "e918" (the point-wait cursor)
Page_Cache_Size
The number of pages kept in memory.
Default: "4"
Safe_Memory_Free
The minimum amount of memory, in kilobytes, to leave for the
system. If the system has less than this amount available,
Voyager’s requests to allocate memory fail.
Default: "0"
Show_Server_Errors
Display the HTML-formatted error pages received from the
remote HTTP servers. Otherwise, generate a
Pt_CB_WEB_ERROR callback.
Default: "FALSE"
Site_History_Length
The maximum number of sites allowed in the site history (the list
is obtained from server).
Default: "500"
Use_Explicit_Accept_Headers
Send an explicit Accept: content-type header request field
in the HTTP header; otherwise send Accept: */*.
Default: "TRUE"

Wait_Cursor See /usr/include/photon/PhCursor.h

Default: "e908" (the wait cursor)
NetFront-specific options
These options are specific to the netfront server.
ServerId (Read only) The string identifier for the server. You can use this
string if your client can be used with both the vserver and
netfront servers, and you want to do specific things when
connected to a certain server. The strings returned are vserver
and Netfront, respectively.
iUserZoom A numeric value for the global (text and image) zoom factor, in
percent. A value of "100" means original size.
fNavigatorUserAgent
The user agent string.
memory_cache_kb_size
The amount of in-cache memory. The default is 0.
fEnableWML Enable Wireless Markup Language (WML/WAP) support. The

default is "FALSE".
fDisableSelection
Disable text slection. When "TRUE", a user can’t select HTML text
in the netfront canvas. The default is "FALSE".
fDisableJavascriptAlert
Disable Javascript alert() dialogs. When "TRUE", JavaScript alert()
dialogs aren’t displayed. The default is "FALSE".
fDisableJavascriptConfirm
Disable Javascript confirm() dialogs. When "TRUE", JavaScript
confirm() dialogs aren’t displayed. The default is "FALSE".
fDisableJavascriptPrompt
Disable Javascript prompt() dialogs. When "TRUE", JavaScript
prompt() dialogs aren’t displayed. The default is "FALSE".
These options are write-only:
fRunJavaScript If "TRUE", JavaScript is enabled.

Default: "TRUE"
fScriptDisables Validates/invalidates external script files. Possible values are:

• "DISABLE_SCRIPT_SRC" — invalidates the src attribute of

the <script> element. The external script isn’t read.
• "DISABLE_SCRIPT_EXECUTE" — invalidates scripts in
newly generated Windows.
• "DISABLES_NONE" — no disabling.
Default: "DISABLES_NONE"
fCSSDisables Options used to configure CSS. Possible values are:

• "DISABLE_CSS_DEFAULT" — default style sheet is invalid.
• "DISABLE_CSS_LINK" — external file definition (LINK
REL) style sheet is invalid.
• "DISABLE_CSS_IMPORT" — import (@import) style sheet
is invalid.
• "DISABLE_CSS_STYLETAG" — <style> tag is invalid.
• "DISABLE_CSS_STYLEATTR" — style attribute is invalid.
Set to "FLAG_NONE" to clear all flags.
Default: all flags enabled.
fSSLVersion The version of SSL to use. Can be a combination of values:

• "V2" — use SSL version 2.
• "V3" — use SSL version 3.
• "TLS" — use TLS version 1.
Set to "FLAG_NONE" for none.
Default: all flags enabled.
fDisplayTable Sets whether the browser displays <table> elements

described in content by table style or not.
Default: "TRUE"
fDisplayImage Sets whether the browser displays images.

Default: "TRUE"
fAnimateImage Sets whether the browser animates images.

Default: "TRUE"
fWaitDecodeImage
Sets whether the browser waits until an image is displayed to
decode it.
Default: "FALSE"

fAnimationImageMaxLoops
The maximum number of animation loops for images. No limit
if set to "-1".
Default: "-1"
fMaxImageDelayTime
The maximum delay time for animations, in milliseconds. No
limit if less than "0".
Default: "-1"
fMinImageDelayTime
The minimum delay time for animations, in milliseconds. No
limit if less than "0".
Default: "-1"
fMaxImageWidth The maximum display width size of images, in pixels. Possible

values are:
• greater than "0" — if the width of the image is larger than
this, the image is scaled so its width equals
fMaxImageWidth.
• equal to "0" — the image is displayed at its real size.
• less than "0" — specifies the negative of the maximum size
of a viewport. If the width of an image is larger than that of
the viewport, it is resized to the width of the viewport. If the
image size to be displayed is larger than the specified value,
the reduction decode is attempted. If the reduction decode is
impossible, the image is resized again when it is displayed.
Default: "0"
fMaxImageHeight similar
The maximum display height size of image (in pixels).
• greater than "0" — if the height of the image is larger than
this, the image is scaled so its height equals
fMaxImageHeight.
• equal to "0" — the image is displayed at its real size.
• less than "0" — specifies the negative of the maximum size
of a viewport. If the height of an image is larger than that of
the viewport, it is resized to the height of the viewport. If the
image size to be displayed is larger than the specified value,
the reduction decode is attempted. If the reduction decode is
impossible, the image is resized again when it is displayed.
Default: "0"

fMaxPixelsPerImage
The maximum image size, which is the width × height, in
pixels. No limit if set to "-1".
This sets the maximum image file size that can be displayed.
The size is determined by the width and height recorded in the
image file before the browser engine converts the size. It isn’t
related to the attribute values specified by the image’s HTML
tag. If the image size is larger than the specified value or the
image header is damaged, the browser cancels decoding and it
displays the image-data-damaged icon. This prevents a
memory shortage when the browser attempts to reserve
memory for an abnormally large image.
Default: "-1"
fKeepResizedImage
Sets whether the browser retains a temporary image or not
when it scales an image up or down.
Default: "FALSE"
fMaxPixelsPerDecodedPixelMap
Sets the maximum pixel map size. Possible values are:
• > "0" — the maximum pixel map size when decoding an
image, in pixels.
• "-1" — no limitation on the pixel map size.
Default: "-1"
If a large image causes a lack of memory when it’s decoded,
nothing can be displayed. Setting the appropriate value for
fMaxPixelsPerDecodedPixelMap enlarges the reduced
image again, and enables the browser to display the rough
image with a resolution lower than its original.
If the pixel map size is larger than the specified maximum size,
a reduction decode is attempted so that the image is the
specified size or smaller. If the decoder is unable to reduce the
image to the specified size, the image-data-damaged icon is
displayed.
fDeleteImageBound
• "INT_MIN" — release all the pixelmaps that have been
already decoded.
• "-1" — keep all the pixelmaps that have been already
decoded.

• ≥ "0" — the margin outside the visible display area where

pixelmaps are not released. The pixelmaps in the range of
the visible display area plus the specified margin (in pixels)
are not released, and the browser decodes images that
haven’t been decoded yet. Pixelmaps outside the visible
display area are released.
• "INT_MAX" — decode all the images that haven’t been
decoded yet. Pixelmaps aren’t released.
Default: "-1"
fImageResizeAlgorithm
The algorithm to use to reduce images. Possible values are:
• "IMAGERESIZE_SIMPLE"
• "IMAGERESIZE_BILINEAR"
Default: "IMAGERESIZE_SIMPLE"
fPixelMapProtectInMemoryCrisis
Sets whether to protect (by releasing) the pixelmap or not when
a memory error occurs, except when processing images.
Default: "TRUE"
fMaxActiveDecoders
The maximum number of image decoders that can operate at
the same time (except the image decoder operating on
animation). No limit when set to -1.
Default: "-1"
fIncrementalReflow
• "TRUE" — Execute incremental reflow. The browser
displays elements one by one, even if the layout information
isn’t calculated. It lays out again if the element is changed
when the layout information is decided.
• "FALSE" — Don’t execute incremental reflow.
Default: "FALSE"
fTextareaRows Default value for the rows attribute of the <textarea>

element.
Default: "4"
fTextareaCols Default value for the cols attribute of the <textarea> element.
Default: "20"

fBlinkOnPeriod The “on” time for the <blink> element, in milliseconds.

Default: "1500"
fBlinkOffPeriod The “off” time for the <blink> element, in milliseconds.

Default: "800"
fBlinkLimitTime The time limit for blinking of the <blink> element, in

milliseconds. Set to "-1" for no limit.
Default: "-1"
fWapMarqueeSpeedFast
The fast speed of a <marquee> element, in milliseconds.
Default: "60"
fWapMarqueeSpeedNormal
The normal speed of a <marquee> element, in milliseconds.
Default: "82"
fWapMarqueeSpeedSlow
The slow speed of a <marquee> element, in milliseconds.
Default: "100"
fWaitStartMarquee
Specifies whether to delay scrolling a <marquee> element
until the marquee is displayed.
Default: "FALSE"
fMaxTotalContentsSize
The maximum size, in bytes, of the content displayed in one
page. This setting requires a restart to take effect. Set it to
"-1" for no limit.
Default: "-1"
Fit_Into_Pane Turns Smart-Fit mode on or off. Smart-Fit fits a display to the

window width.
Default: "FALSE"
fProgressiveOnlyDisplayed
Sets how progressive display works:
• "TRUE" — The browser formats the visible content
progressively, and then formats the rest of the content. This
shortens the time required to display a page.
• "FALSE" — Formats all content progressively.
Default: "TRUE"

fDisplayCompact Sets the behavior if content protrudes off the screen:

• "TRUE" — Ignore all margin and padding settings.
• "FALSE" — Don’t ignore margin and padding.
Default: "FALSE"
fTabWidth Sets the width of the tab character in the <pre> element.
Default: "8"
fEnableFrameSet Enables the <frameset> tag.

Default: "TRUE"
fEnableIFrame Enables the <iframe> tag.

Default: "TRUE"
fInhibitLineOverlap
Prevents lines of text from overlapping in the situation where a
small value is set for line-height in a style sheet, but there’s no
small font.
Default: "FALSE"
fCanvasMarginWidth
The margin width of the drawing content area. This is the
default value of the <body> tag.
Default: "2"
fCanvasMarginHeight
The margin height of the drawing content area. This is the
default value of the <body> tag.
Default: "2"
fRememberFormValue
Sets whether the browser saves the content entered in a form to
its history (excluding <input> where "type" is password).
Default: "TRUE"
fEnableClientPull
Allows the browser to attempt a connection due to a client pull
when it is browsing off-line.
Default: "TRUE"
fNotifyInclError
Indicates whether the browser notifies you if an error occurs
when loading embedded content, such as images.
Default: "FALSE"

fPDConfig Specifies when mouse events are generated. Can be one of

these values:
• "NO_MOUSE_MOVE" — generate mouse over at the time of
mouse down, and generate mouse out at the time of mouse
up.
• "NO_POINTING_DEVICE" — generate mouse over at the
time of on focus, and generate mouse out at the time of on
blur.
Or: "FLAG_NONE" — none of the above.
Default: "FLAG_NONE"
fAutoSetFocus Specifies whether focus is set if there is a focus target on

screen:
• "TRUE" — set a focus automatically.
• "FALSE" — don’t set focus automatically.
Default: "FALSE"
fAccesskeyFocusOnlySubmitReset
Specifies the behavior of pressing the access key specified by
the accesskey attribute of form <input> elements:
• "TRUE" — don’t execute a send/reset when the access key
is pressed, but only move the focus.
• "FALSE" — execute a send/reset when the access key is
pressed.
Default: "FALSE"
fEnableTabIndex Specifies whether a tab index is enabled:

• "TRUE" — tab index is valid.
• "FALSE" — tab index is invalid.
Default: "TRUE"
fTabOrder Specifies the tab order:

• "TABORDER_DOCTREE" — tab order is determined by the
description in the document, set by the tabindex attribute.
• "TABORDER_DISPLAY" — tab order starts from the y
coordinate of the upper edge of the focusable elements in
the focus area.
• "TABORDER_BASELINE" — tab order starts from the y
coordinate of the lower edge of the focusable elements in
the focus area.
Default: "TABORDER_DISPLAY"

fFocusOutlineWidth
Specifies the border for image maps or buttons with focus, in
pixels. Must be ≥1.
Default: "1"
fFocusOutlineWidthForControl
Specifies the border for controls with focus, in pixels:
• ≥"0" — the border width of the focus frame.
• "-1" — don’t draw the focus frame, even though the focus
was retrieved.
Default: "1"
fFocusOutlineWidthForIFrame
The border width of the focus frame, in pixels, for the inline
frame.
Default: "1"
fContentParserMaxStayTime
The maximum time for the “content parser progress”, before it
can be interrupted, in milliseconds. This process analyzes the
text data and builds the internal DOM tree. Set to "0" or more.
Default: "100"
Higher values for “progress stay” times can result in faster page-rendering times.
Lower values means the process is interrupted more often, possibly resulting in slower
rendering times, but also allowing processes other than the browser engine more
processor time.
fPageMakerMaxStayTime
The maximum time for the “page maker progress”, before it
can be interrupted, in milliseconds. Set to "0" or more.
Default: "100"
Higher values for “progress stay” times can result in faster page rendering times.
processor time.
fEditorMaxStayTimeFG
The maximum time for the “editor progress” for the visible
display area, in milliseconds. In this process, the rendering
engine calculates the layout information and draws the content
to the currently displayed area. Set to "0" or more.
Default: "100"

processor time.
fEditorMaxStayTimeBG
The maximum time for the “editor progress” for the
undisplayed area, in milliseconds. In this process, the rendering
engine calculates the layout information for the area that isn’t
currently displayed. Set to "0" or more.
Default: "100"
processor time.
fUseHTTP11PipeLine
Sets whether the browser uses pipelining in HTTP/1.1.
Default: "FALSE"
fCookieMode Cookie processing mode:
• "COOKIE_NOTIFY_BEFORE_SET" — notify before setting
a cookie.
• "COOKIE_ALWAYS_SET" — always set.
• "COOKIE_NEVER_SET" — never set.
Default: "COOKIE_NOTIFY_BEFORE_SET"
fMaxStreams Maximum number of simultaneous TCP connections.
Default: "4"
fMaxRequestHeader
The maximum HTTP request line size, in bytes.
Default: "-1" (no limit)
fMaxRequestBody The maximum HTTP request body size, in bytes.
fMaxTotalCookies
The maximum number of cookies.
Default: "300"
fMaxCookiesPerDomain
The maximum number of cookies for each domain.
Default: "20"

fMaxLenPerCookie
The maximum size per cookie, in bytes.
Default: "4096"
fMaxRedirect The maximum number of redirects.

Default: "30"
fMaxPageAuth The maximum number of authentications per page.

fMaxProxyAuth The maximum time for authentication per proxy.

fSendProxyKeepAlive
Transmit Proxy-Connection: KeepAlive header at HTTP.
Default: "TRUE"
fSendReferer Transmit Referer header at HTTP.

Default: "TRUE"
fSendCookie Transmit cookies.

Default: "TRUE"
fDisableFilep Disable file protocol.

Default: "FALSE"
fAllowHTTPandHTTPS
Display HTTPS content in HTTP content, or display HTTP
content in HTTPS content.
Default: "TRUE"
fBlockquoteMargin_left
The left margin when drawing a <blockquote> element, in
pixels.
Default: "30"
fBlockquoteMargin_right
The right margin when drawing a <blockquote> element, in
pixels.
Default: "30"
fBlockquoteMargin_top
The top margin when drawing a <blockquote> element, in
pixels.
Default: "19"

fBlockquoteMargin_bottom
The bottom margin when drawing a <blockquote> element,
in pixels.
Default: "19"
Pt_ARG_WEB_PRINT (write-only)
PpPrintContext_t *, int Pointer
Set this resource to print the page. You can use the len argument of PtSetArg() to
specify a combination of the following flags:
Pt_WEB_PRINT_FROM_CACHE
When printing, let the print filters read images from the image cache, to reduce
the size of intermediate file.
Use this option only if the filter is run locally. It’s up to the client application to
prevent any activation in the server while printing.
Pt_WEB_PRINT_ALL_FRAMES
Print all frames as shown on the current page.
Pt_ARG_WEB_RELOAD (write only)

N/A N/A N/A
This is a write-only resource without any specified type. Set it to any value to reload
the current page:
PtSetArg (&args[0], Pt_ARG_WEB_RELOAD, 0, 0);

PtSetResources (widget, 1, args);
Pt_ARG_WEB_SERVER
char * String NULL
The name of a web-server profile to use, or the path and any options to the web server
to start. Setting this resource starts the server; if there’s a server already attached to the
client, it’s shut down and the new one is started.

Web-server profiles are stored in $HOME/.ph/webservers (the user profile) and

/etc/photon/webservers (the global profile). The user profile is searched first.
The format of this file is:
profile= server,name
In this format, server is the server executable, including path and command-line
options if required, and name is the named connection that the client must use to
establish a connection to the server. Profile names aren’t rigidly defined, so you can
use any name that suits your application if you create a custom profile. The file can
contain whitespace, and lines that start with # are comments. If you need to use a
comma in a command-line option, use quotation marks around the command line.
Here’s an example:
# default server for "online" browsing (i.e. www)

online = vserver,VoyagerServer-2
#default server for "offline" browsing (i.e. files on disk)

offline = vserver.file -l -nVoyagerOffline,VoyagerOffline
# server profile for using Mozilla engine

mozilla = mozilla -sshared,MozillaServer
# my own webserver - an example of using ’,’

myserver = "/foo/bar/mywebserver -oOpt1,Opt2",MyServer
If no matching profile is found, then the string is taken literally as the server to spawn,
and the setting for Pt_ARG_CLIENT_NAME is used to connect to the spawned server.
You can bypass the profile lookup by beginning the Pt_ARG_WEB_SERVER string
with the @ character. PtWebClient discards the @ and uses the remainder as the
command to start the web server. In this scenario, the setting for
Pt_ARG_CLIENT_NAME is used to connect to the server.
You can use web-server profiles to override the web server used by existing
applications. For example, if an application tries to start the vserver server, you can
cause it to use mozilla instead with the following profile:
# default server for old Voyager client

vserver = mozilla -sshared,MozillaServer
Any options set prior to setting the resource are set back to their defaults.
For an example of using this resource, see “Starting the server,” above.
Pt_ARG_WEB_SERVER_PID (read only)

A read-only resource that returns the PID of the web server. The value is 0 if the
widget has connected to an existing server, or -1 if spawn() has failed.
Pt_ARG_WEB_SSL_RESPONSE
PtWebClient2SSLResponse_t * Pointer NULL
A resource that’s used only if you’re using the SSL (Secure Sockets Layer) version on
the web server. This resource is used in response to the
Pt_CB_WEB_SSL_CERTNONTRUSTED and Pt_CB_WEB_SSL_ERROR callbacks.
typedef struct {
char *url;
int response;
} PtWebClient2SSLResponse_t;
url A pointer to the URL obtained from the Pt_CB_WEB_SSL_ERROR

callback.

• Pt_WEB_RESPONSE_OK — override the error and continue.
• Pt_WEB_RESPONSE_CANCEL — abort the transaction.
Pt_ARG_WEB_STARTUP_ERRNO (read only)

int Scalar 0
A read-only resource that you can use to determine if the server started successfully. If
the value isn’t EOK, use errno to determine what went wrong. For more information,
see “Starting the server,” above.
Pt_ARG_WEB_STOP (write only)

N/A N/A N/A
This is a write-only resource without any specified type. Set it to any value to stop the
loading of the current page:
PtSetArg (&args[0], Pt_ARG_WEB_STOP, 0, 0);

PtSetResources (widget, 1, args);
Pt_ARG_WEB_UNKNOWN_RESP (write-only)
PtWebClient2UnknownData_t * Pointer
Set this resource to give a response to the server after a Pt_CB_WEB_UNKNOWN

callback. When the downloading begins, the browser engine calls your
Pt_CB_WEB_DOWNLOAD callback.
typedef struct {
short response;
short zero;
int download_ticket;
char *filename;
char *url;
} PtWebClient2UnknownData_t;

• Pt_WEB_RESPONSE_OK — the filename file is valid;
continue with the disk download.
Pt_CB_WEB_DOWNLOAD is called.
• Pt_WEB_RESPONSE_CANCEL — cancel the downloading of
the unknown file.
download_ticket Arbitrary data. You can set this to unique data to help you keep
track of downloads, for example if several downloads happen
concurrently.
filename A pointer to the name of the file in which to save unknown data.
url A pointer to the URL obtained from the

Pt_CB_WEB_UNKNOWN callback.
Pt_ARG_WEB_VERSION (read only)

char * String
Get the value of this resource to obtain the version of the connected web server.

Pt_CB_WEB_AUTHENTICATE

A list of PtCallback_t structures that define the callbacks invoked when the server
requires authentication information or when canceling a previous authentication
request. To return the information, set the Pt_ARG_WEB_AUTHENTICATE resource.
following members:
reason Pt_CB_WEB_AUTHENTICATE
event NULL
cbdata A pointer to a PtWebAuthenticateCallback_t structure:
typedef struct {
short type;
short action;
char *realm;
char *url;
} PtWebAuthenticateCallback_t;
The members of the PtWebAuthenticateCallback_t structure are:
type The type of authentication used:

• Pt_WEB_BASIC_AUTHENTICATION
• Pt_WEB_DIGEST_AUTHENTICATION
• Pt_WEB_PROXY_AUTHENTICATION
• Pt_WEB_IMPORT_CERT_AUTHENTICATION
action The action to take:

• Pt_WEB_ACTION_OK — the server is requesting basic authentication
information.
• Pt_WEB_ACTION_ABORT — the server is canceling a previous request
for basic authentication information.
realm A pointer to the realm name.
url A pointer to the URL that requires the authentication.

Pt_CB_WEB_CLOSE_WINDOW

A list of PtCallback_t structures that define the callbacks invoked when a web page
with Javascript requests that its window be closed.
following members:
reason Pt_CB_WEB_CLOSE_WINDOW
event NULL
cbdata NULL
Pt_CB_WEB_COMPLETE
A list of PtCallback_t structures that define the callbacks invoked when the page
has completed loading. Each callback is passed a PtCallbackInfo_t structure that
reason Pt_CB_WEB_COMPLETE
event NULL
cbdata A pointer to a PtWebCompleteCallback_t structure:
typedef struct {
char *url;
} PtWebCompleteCallback_t;
The url member points to the URL of the page that has just
completed.
Pt_CB_WEB_CONTEXT

A list of PtCallback_t structures that define the callbacks invoked when the user
right-clicks on the current page with the mouse.
following members:
reason Pt_CB_WEB_CONTEXT
event NULL
cbdata A pointer to a PtWebContextCallback_t structure:
typedef struct {
long context;
PhPoint_t pos;
} PtWebContextCallback_t;
The members of the PtWebContextCallback_t structure are:
context The context, which is one of:

• Pt_WEB_CONTEXT_ANCHOR — the URL of a link is available.
• Pt_WEB_CONTEXT_OBJECT — the URL of an image or embedded
object is available.
• Pt_WEB_CONTEXT_BKGD — the URL of a background image is
available.
pos A PhPoint_t structure (see the Photon Library Reference) that contains
the (x, y) coordinates of the location where the right mouse button was
pressed.
Pt_CB_WEB_DATA_REQ

A list of PtCallback_t structures that define the callbacks invoked when a file has
been requested using the client protocol in the URL (e.g. client:about). The
callback notifies the client that the server is waiting for data; to return the data, set the
Pt_ARG_WEB_DATA resource.


following members:
reason Pt_CB_WEB_DATA_REQ
reason_subtype The same as the type member in the callback data.
event NULL
cbdata A pointer to a PtWebDataReqCallback_t structure:
typedef struct {
int type;
int length;
char *url;
} PtWebDataReqCallback_t;
The members of the PtWebDataReqCallback_t structure are:
type The type of request:

• Pt_WEB_DATA_HEADER — the server is requesting the header portion
of the data. The header is of the same form present in an HTTP request
header.
• Pt_WEB_DATA_BODY — the server is requesting the body portion of
the data.
• Pt_WEB_DATA_CLOSE — the server has closed the data stream, and no
more data should be given to the server.
length The maximum amount of data the server can accept, in bytes.
url A pointer to the URL of the request.
For an example of using the client protocol, see Pt_ARG_WEB_DATA.
Pt_CB_WEB_DOWNLOAD
browser begins a file download.
following members:
reason Pt_CB_WEB_DOWNLOAD

event NULL
cbdata A pointer to a PtWebDownloadCallback_t structure:
typedef struct {
int download_ticket;
int type;
int current;
int total;
char *url;
char *message;
} PtWebDownloadCallback_t;
The members of the PtWebDownloadCallback_t structure are:
download_ticket This is the download_ticket assigned to the download when you

set the PtWebClient2UnknownData_t structure for the
Pt_ARG_WEB_UNKNOWN_RESP resource. This ticket allows
you to keep track of multiple downloads.
type Can be one of:

• Pt_WEB_DOWNLOAD_ERROR — an error occurred; display
a dialog with some error text (see message).
• Pt_WEB_DOWNLOAD_DONE — the download is complete.
• Pt_WEB_DOWNLOAD_PROGRESS — the download is in
progress.
current The current number of bytes that have been downloaded.
total The total expected number of bytes.
url The URL of the downloaded file.
message A descriptive message of the error that has occurred. The

message is used only when type is
Pt_WEB_DOWNLOAD_ERROR.
Pt_CB_WEB_ERROR
A list of PtCallback_t structures that define the callbacks invoked if an error occurs
while loading a page. This includes unknown URL protocols such as mailto:,
allowing the client to handle them.

The mailto links are handled by the client. This is done by watching for the mailto
URL in the Pt_CB_WEB_ERROR callback.

following members:
reason Pt_CB_WEB_ERROR
event NULL
cbdata A pointer to a PtWebErrorCallback_t structure:

typedef struct {
short type;
short reason;
char *url;
char *description;
} PtWebErrorCallback_t;
The members of the PtWebErrorCallback_t structure are:
type The type of error:

• Pt_WEB_ERROR_SERVER_EXIT — the server has terminated.
• Pt_WEB_ERROR_TOPVIEW — an error occurred when loading the
requested page.
• Pt_WEB_ERROR_SUBVIEW — an error occurred when loading a
subdocument of the requested page (e.g. images in an HTML
page).
• Pt_WEB_ERROR_FILE — an error occurred when saving a
document to disk.
• Pt_WEB_ERROR_WML — an error occurred when loading the
requested WML page.
reason If type is Pt_WEB_ERROR_SERVER_EXIT, the reason member

contains the terminating status of the server (use waitpid () to
determine why the server terminated).
If type is Pt_WEB_ERROR_WML, an error occurred in WML content,
and the reason member contains one of:
Pt_WEB_ERROR_WML_AccessDenied
Access rejection error caused by specifying an access element.
Pt_WEB_ERROR_WML_InvalidVariableReference
Incorrect variable name error.

Pt_WEB_ERROR_WML_InfiniteLoop
The WML parser has detected an infinite loop.
Pt_WEB_ERROR_WML_Unknown
An unknown WML error has occurred.
Pt_WEB_ERROR_WML_SAX
The WML parser has detected a syntax error.
For other values of type, the possible values of reason are:
-1 Unspecified or unknown error.

-2 Parameter check / consistency check failed.
-3 Low memory.
-4 Low image-cache memory.
-5 The operation was aborted.
-6 Bad header.
-8 The document contains no data.
-9 Missing service API.
-10 Missing request API.
-11 Multiple initialization.
-12 DNS failure.
-13 Connection failure.
-14 Network failure.
-15 Bad input stream.
-16 Request for data sink failed.
-17 New data sink failed.
-18 Invalid redirect.
-19 Unknown server error.
-21 Unknown document character-set encoding.
-31 Corrupt data.
-39 Helper failed.
-40 SSL not supported.
-41 Unknown URL (No URL handler could be found to process the
given URL).
-400 HTTP — Bad request.

-401 HTTP — Unauthorized.
-402 HTTP — Payment required.
-403 HTTP — Forbidden.
-404 HTTP — Not found.

-405 HTTP — Method not allowed.

-406 HTTP — Not acceptable.
-407 HTTP — Proxy authentication required.
-408 HTTP — Request time-out.
-409 HTTP — Conflict.
-410 HTTP — Gone.
-411 HTTP — Length required.
-412 HTTP — Precondition required.
-413 HTTP — Request entity is too large.
-414 HTTP — Request URL too is large.
-415 HTTP — Unsupported media type.
-500 HTTP — Internal server error.

-501 HTTP — Not implemented.
-502 HTTP — Bad gateway.
-503 HTTP — Service unavailable.
-504 HTTP — Gateway time-out.
-505 HTTP — HTTP version not supported.
-1200 FTP — Server error.

-1202 FTP — Error 332.
-1203 FTP — Error 530.
description The netfront server sets this member to a string containing a

description of the error.
Voyager server does not use this member, and sets it to NULL.
Pt_CB_WEB_IMPORT_CERTIFICATE
A list of PtCallback_t structures that define the callbacks invoked to inform the
client whether a client certificate import operation is successful. The client initiates the
import by setting Pt_ARG_WEB_IMPORT_CERTIFICATE
following members:
reason Pt_CB_WEB_IMPORT_CERTIFICATE.

event NULL
cbdata A pointer to a PtWebImportCertificateCallback_t
structure:
typedef struct {
int reason;
char *description;
} PtWebImportCertificateCallback_t;
The reason is one of:

• Pt_WEB_IMPORT_CERTIFICATE_OK
• Pt_WEB_IMPORT_CERTIFICATE_ERROR
If reason is Pt_WEB_IMPORT_CERTIFICATE_ERROR,
description is a textual explanation for the error.
Pt_CB_WEB_METADATA
A list of PtCallback_t structures that define the callbacks invoked to inform the
client of metadata that was read from the page. The only metadata currently returned
is the web page title.
following members:
reason Pt_CB_WEB_METADATA
event NULL
cbdata A pointer to a PtWebMetaDataCallback_t structure:

typedef struct {
char *url;
char *name;
char *value;
} PtWebMetaDataCallback_t;
The members include the following:
url The page URL.

name The metadata name; currently only title is supported.
value The metadata value.
Here’s an example of using Pt_CB_WEB_METADATA to set a window widget’s title

to the HTML page title (web_curr_title is a global variable):

int web_title( PtWidget_t *widget, ApInfo_t *apinfo,

{
PtWebMetaDataCallback_t *cb = cbinfo->cbdata;
PtArg_t args[1];
if ( !strcmp( cb->name, "title" ) ) {

if ( web_curr_title )
free( web_curr_title );
web_curr_title = strdup( cb->value );
PtSetArg( &args[0], Pt_ARG_WINDOW_TITLE, cb->value, 0 );
PtSetResources( ABW_base, 1, args );
}
return( Pt_CONTINUE );
}
Pt_CB_WEB_NEED_SCROLL (key mode only)


requires the client to scroll the page.
following members:
reason Pt_CB_WEB_NEED_SCROLL
event NULL
cbdata A pointer to a PtWebNeedScrollCallback_t structure:
typedef struct {
short dir;
} PtWebNeedScrollCallback_t;
where dir indicates the direction to scroll:

• Pt_WEB_DIRECTION_UP
• Pt_WEB_DIRECTION_DOWN
• Pt_WEB_DIRECTION_LEFT
• Pt_WEB_DIRECTION_RIGHT

Pt_CB_WEB_NEW_WINDOW

browser requests that a new PtWebClient widget be connected to the server so that it
can display a page.
If no callback is attached, then the requested page appears in the window that the
request was made (i.e. the one the user clicked in). This doesn’t apply to Javascript
open windows.
following members:
reason Pt_CB_WEB_NEW_WINDOW
event NULL
cbdata A pointer to a PtWebWindowCallback_t structure:
typedef struct {
PhDim_t size;
long flags;
} PtWebWindowCallback_t;
The members of the PtWebWindowCallback_t structure are:
size A PhDim_t structure (see the Photon Library Reference) that defines the
dimensions of the new window.
flags A combination of the following bits:

• Pt_WEB_SHOW_TOOLBAR — if the client contains a toolbar, it should
be visible.
• Pt_WEB_SHOW_MENUBAR — if the client contains a menubar, it should
be visible.
• Pt_WEB_RESIZEABLE — the new window should be resizable.
• Pt_WEB_SHOW_STATUS — the status field should be visible.
• Pt_WEB_SHOW_LOCATION — the URL location text field should be
visible.

Pt_CB_WEB_PAGE_INFO

A list of PtCallback_t structures that define the callbacks invoked when the page
size or position has changed. Each callback is passed a PtCallbackInfo_t structure
that contains at least:
reason Pt_CB_WEB_PAGE_INFO
event NULL
cbdata A pointer to a PtWebPageInfoCallback_t structure:
typedef struct {
long vheight;
long vwidth;
long height;
long width;
long ypos;
long xpos;
} PtWebPageInfoCallback_t;
The members of the PtWebPageInfoCallback_t structure are:
vheight The height of the visible portion, in pixels.
vwidth The width of the visible portion, in pixels.
height The height of the page, in pixels.
width The width of the page, in pixels.
ypos The position of the right side of the page, in pixels.
xpos The position of the top of the page, in pixels.
Pt_CB_WEB_SSL_CERTINFO

web server has discovered an SSL connection; invoked after the handshake phase has
determined the other party’s identity.
This callback list is invoked only if you’re using the SSL version of the Voyager server
(Spyrus Terisa version).

following members:
reason Pt_CB_WEB_SSL_CERTINFO
event NULL
cbdata A pointer to a PtWebSSLCertInfoCallback_t structure:
typedef struct PtWebSSLCertInfoCallback_t {

char *url;
char *cipher_kind;
int is_sgc;
int version;
unsigned int flags;
struct {
char *serial;
char *subject;
char *issuer;
} certinfo;
time_t valid_begin, valid_end;
char *status;
char *extensions;
} PtWebSSLCertInfoCallback_t;
The members of the PtWebSSLCertInfoCallback_t structure are:
url A pointer to the URL associated with the error.
cipher_kind A pointer to the cipher suite used for the connection

(SSL_3_RSA_WITH_RC4-128_MD5,
SSL_3_RSA_WITH_RC4_40_MD5, etc.)
is_sgc Nonzero if the connection is using the “Server Gated

Cryptography” (also called “Step-Up Encryption”).
version The version number: 2 for SSL 2.0, 0x0300 (768) for SSL 3.0,
0x0301 for TLS 1.0.
flags Flags for future extensions (always zero in the current

implementation).

certinfo.serial A pointer to the serial number for the certificate (a hexadecimal

number).
certinfo.subject, certinfo.issuer
A pointer to distinguished names of the public key being certified.
valid_begin, valid_end
The time (in seconds since 01/01/1970 0h UTC) at which the
certificates became valid and invalid.
status A pointer to the status of the certificate, represented as a string

(Valid, Pending, Expired, Trusted root, Unverified, and
so on).
extensions A pointer to some additional information about the SSL

connections (string).
When this callback is invoked, typically the client saves this information relative to the
current SSL connection, in order to be able to display it on a subsequent user’s request
(usually when the user clicks on the lock).
these callbacks should return only Pt_CONTINUE; there’s no need to fill up a special
structure as response.
Pt_CB_WEB_SSL_CERTNONTRUSTED
web server has discovered that the current SSL connection is made with a nontrusted
certificate. Note that Voyager supports only server certificates, and not Client
certificates.

following members:
reason Pt_CB_WEB_SSL_CERTNONTRUSTED
event NULL
cbdata A pointer to a PtWebSSLCertNonTrustedCallback_t

structure:

typedef struct {
short action;
short ncert;
char *url;
char *status;
int reason;
PtWebSSLCertInfo_t info[1];
} PtWebSSLCertNonTrustedCallback_t;
The members of the PtWebSSLCertNonTrustedCallback_t structure are:
action One of the following:

• Pt_WEB_ACTION_OK—the callback was invoked as a warning; The
nontrusted certificate didn’t make the connection to be aborted.
• Pt_WEB_ACTION_ABORT—the connection was aborted.
ncert The number of items in the info array.
url A pointer to the URL associated with the error.
status A pointer to the status of the certificate, represented as a string (Valid,

Pending, Expired, Trusted root, Unverified, and so on).
info An array of PtWebSSLCertInfo_t structures (see below).
reason The reason the callback was invoked. Can be one of:
• Pt_WEB_SSL_AUTHENTICATE — the callback was invoked during an
authentication.
• Pt_WEB_SSL_IMPORT_CERT — the callback was invoked during an
import-certificate operation.
typedef struct {
char *name;
char *subject;
char *issuer;
char *cert_serial;
char *version;
char *signature_algorithm;
char *basic_constraints;
char *extended_key_usage;
int rsa_public_key_bits;
time_t valid_begin, valid_end;
} PtWebSSLCertInfo_t;
PtWebSSLCertInfo_t has these members:
name A pointer to the certificate’s name.

subject, issuer A pointer to distinguished names of the public key being

certified.
cert_serial A pointer to the serial number for the certificate (hexadecimal
number).
version The version of X.509 applied to the certificate (1, 2, or 3).
signature_algorithm
The signature algorithm, which can be one of:
• CRL_SIGN_ALGO_RSA — RSA Encryption
• CRL_SIGN_ALGO_MD2_WITH_RSA — MD2 with RSA
Encryption
• CRL_SIGN_ALGO_MD5_WITH_RSA — MD5 with RSA
Encryption
• CRL_SIGN_ALGO_SHA1_WITH_RSA — SHA-1 with RSA
Encryption
• CRL_SIGN_ALGO_SHA1_WITH_RSA_SIGN — SHA-1
with RSA Signature
basic_constraints Basic constraints for the certificate.
extended_key_usage
The extended key usage, which specifies the uses for which a
certificate is valid.
rsa_public_key_bits
The number of bits in the public RSA key.
valid_begin, valid_end
The times (in seconds since 01/01/1970 0h UTC) at which the
certificates became valid and invalid.
When this callback is invoked, typically the client displays a dialog giving three
choices to the user:
• Abort
• Continue
• Accept.
The transaction is halted until you set the Pt_ARG_WEB_SSL_RESPONSE resource.

You need to fill in a PtWebClient2SSLResponse_t structure with the URL found
in the callback structure and one of these response codes:
Pt_WEB_RESPONSE_CANCEL
Abort the connection to the site.

Pt_WEB_RESPONSE_CONTINUE
Connect to the site, but don’t save the certificate.
Pt_WEB_RESPONSE_OK
Connect to the site, and save the certificate.
Pt_CB_WEB_SSL_CLIENT_CERT_SELECT
netfront server wants the browser client to display a client- certificate-selection
dialog. The dialog should list the available client certificates and the user should select
one certificate to be used for the current URL that requested it.
You need to fill in a PtWebClient2SSLResponse_t structure with the url found in
the callback structure and you have to set the response field to the index (starting at 0)
of the selected certificate.
following members:
reason Pt_CB_WEB_SSL_CLIENT_CERT_SELECT

event NULL
cbdata A pointer to a PtWebSSLClientCertCallback_t structure:

typedef struct {
int ncert;
char *url;
int reserved1;
int reserved2;
PtWebSSLCertInfo_t *info;
} PtWebSSLClientCertCallback_t;
The members of the PtWebSSLClientCertCallback_t structure include:
ncert The number of certificates to be displayed (the number of items in the info
array).
url The current URL that have requested the client certificates selection dialog
to be displayed.
info An array of information about the certificates. See the
Pt_CB_WEB_SSL_CERTNONTRUSTED resource for a description of the
PtWebSSLCertInfo_t structure.

Pt_CB_WEB_SSL_ERROR

Voyager server has discovered an error or inconsistency with the current SSL
transaction.

following members:
reason Pt_CB_WEB_SSL_ERROR
event NULL
cbdata A pointer to a PtWebSSLErrorCallback_t structure:
typedef struct {
short certerr;
short trusted;
char *url;
int reason;
} PtWebSSLErrorCallback_t;
The members of the PtWebSSLErrorCallback_t structure are:
• trusted — indicates whether the current certificate is trusted.
• url — a pointer to the URL associated with the error.
• reason — one of:

- Pt_WEB_SSL_AUTHENTICATE — the callback is invoked during an
authentication.
- Pt_WEB_SSL_IMPORT_CERT — the callback is invoked during an import
certificate operation.
• certerr — one of the following:
Pt_WEB_ERROR_CertNoError
You don’t have a trusted certification on your end.

Pt_WEB_ERROR_CertChainInvalid
No correct server should provide a certificate chain that causes this error. Any
chain that creates this error is entirely insecure. Therefore, this error can’t be
overridden.
Pt_WEB_ERROR_CertExpired
The certificate provided by the remote server has expired.
Pt_WEB_ERROR_CertNamesNotEqual
The name in the certificate isn’t the same as its DNS name.
Pt_WEB_ERROR_CertChainIncomplete
This error can be overridden and is equivalent to receiving a certificate with an
unknown and untrusted root certificate. If you choose to override this error,
you abandon any protection from active attacks, but, because this error can be
caused by a server with a valid certificate (albeit one issued by an unknown
party), letting users override this error may let them connect to a valid site they
would otherwise be unable to access.
Pt_WEB_ERROR_InvalidSignature
Like Pt_WEB_ERROR_CertChainInvalid, this error can’t be overridden.
Pt_WEB_ERROR_BasicConstraints
Violates basic constraints.
Pt_WEB_ERROR_FailedVerify
Cannot verify the signature.
Pt_WEB_ERROR_IncorrectKeyUsage
Key use and extension key use are invalid.
Pt_WEB_ERROR_RootCertificateNotValid
The browser’s root CA certificate is expired.

You need to fill in a PtWebClient2SSLResponse_t structure with the URL found
in the callback structure and one of the following response codes:
• Pt_WEB_RESPONSE_OK — override the error and continue.
• Pt_WEB_RESPONSE_CANCEL — abort the transaction.
Pt_CB_WEB_START
A list of PtCallback_t structures that define the callbacks invoked when a page
starts loading. Each callback is passed a PtCallbackInfo_t structure that contains

reason Pt_CB_WEB_START
event NULL
cbdata NULL
Pt_CB_WEB_STATUS
browser’s status changes. These callbacks give you many different types of
information.
following members:
reason Pt_CB_WEB_STATUS
event NULL
cbdata A pointer to a PtWebStatusCallback_t structure:

typedef struct {
short type;
short zero;
char *desc;
char *url;
} PtWebStatusCallback_t;
This callback gives you many different types of information. Before performing any
actions, you should first check the type and then act accordingly.
The types are:
Pt_WEB_STATUS_MOUSE
Reports when the mouse moved over links, images, etc.
Pt_WEB_STATUS_CONNECT
Reports connection-related messages.
Pt_WEB_STATUS_DEFAULT
Reported when Javascript requests the default status bar text be changed (i.e.
window.defaultStatus="..."). The defaultStatus message appears when
nothing else is in the status bar.

Pt_WEB_STATUS_PROGRESS
A progress message (e.g. the number of bytes downloaded).
Pt_WEB_STATUS_INFO
Reports various information. Valid INFO types are:
FORM-EDIT Single-line text field has focus.

FORM-PASS The password field has focus.
FORM-LIST Single-select list has focus.
FORM-MULTILIST Multi-select list has focus.
FORM-COMBO Combo box has focus.
FORM-TEXTAREA Multi-line text field has focus.
FORM-CHECKBOX Check box has focus.
FORM-RADIO Radio button has focus.
FORM-SUBMIT Submit button has focus.
FORM-RESET Reset button has focus.
LINK-IMAGE-MAP Image map has focus.
LINK-IMAGE Image link has focus.
LINK-TEXT Text link has focus.
FRAMESET-DOC Frames document has been loaded.
FORM-CURSOR-LEFT
The cursor inside a FORM control or image map has
reached the leftmost position.
FORM-CURSOR-RIGHT
reached the rightmost cursor position.
FORM-CURSOR-TOP
reached the topmost position.
FORM-CURSOR-BOTTOM
reached the bottommost cursor position.
PAGE-TOP The page has scrolled to its topmost position.
PAGE-BOTTOM The page has scrolled to its bottommost position.
PAGE-LEFT The page has scrolled to its leftmost position.
PAGE-RIGHT The page has scrolled to its rightmost position.
Pt_WEB_STATUS_PRINT
Reports print-related status (pages printed):

• "Print Error %d" — an error occurred. The %d parameter can be:

-600 No printer was set.
-601 The page wasn’t printable.
-602 A general printing error occurred.
• "Print Done"
• "Print Done - More" — more pages can be printed.
Pt_WEB_STATUS_CONTENTS
Reports when a single-line text field, password, or text area control receives
focus on the page. The information passed in the description field is a string
containing an ordinal number identifying the control on the web page, followed
by a colon, followed by the contents of the text field that just got focus.
Pt_CB_WEB_UNKNOWN
has received a file that it can’t display or has no external helpers that match its
mimetype or file suffix. Set Pt_ARG_WEB_UNKNOWN_RESP to provide a filename
or cancel the download anytime after this callback.
following members:
reason Pt_CB_WEB_UNKNOWN
event NULL
cbdata A pointer to a PtWebUnknownCallback_t structure:

typedef struct {
short action;
short flags;
char *content_type;
int content_length;
char *url;
} PtWebUnknownCallback_t;
The members of the PtWebUnknownCallback_t structure are:
action The action taking place:

• Pt_WEB_ACTION_OK — the server is requesting a the name of
a file in which to save the data.

• Pt_WEB_ACTION_ABORT — the server is canceling a

previous request for a filename.
flags Not currently used.
content_type A pointer to the mime content type of the file (if available).
content_length The length of the file (-1 if unknown).
url A pointer to the URL of the file.
Pt_CB_WEB_URL
browser has a complete URL to be loaded. This is useful for saving internal history
lists or saving URLs in hotlists.
following members:
reason Pt_CB_WEB_URL
event NULL
cbdata A pointer to a PtWebUrlCallback_t structure:
typedef struct {
char *url;
} PtWebUrlCallback_t;

continued. . .


Pt_ARG_CLIENT_FLAGS PtClient
Pt_ARG_CLIENT_NAME PtClient "VoyagerServer-2"
Pt_ARG_CLIENT_REPLY_LEN PtClient
Pt_ARG_CLIENT_SEND PtClient
Pt_ARG_CLIENT_SERVER PtClient
Pt_ARG_DIM PtWidget
continued. . .


Pt_ARG_POS PtWidget
Pt_CB_ARM PtBasic
Pt_CB_CLIENT_CONNECTED PtClient
Pt_CB_CLIENT_EVENT PtClient
Pt_CB_CLIENT_NOT_FOUND PtClient
Pt_CB_DND PtWidget
continued. . .


Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
Caveats:
Calling PtWidgetToFront() or PtWidgetToBack() on a PtWebClient widget has no
effect. This is because the PtWebServer widget is in a different application. Moving
a widget in one application cannot cause draw events that are emitted from a different
application’s region to be clipped. If you do not wish to display the PtWebClient,
you should unrealize it using the PtUnrealizeWidget API call.

© 2010, QNX Software Systems GmbH & Co. KG. PtWidget
Superclass for all widgets
Class hierarchy:
PtWidget
• PtBasic
• PtTimer
PhAB icon:
Public header:
<photon/PtWidget.h>
Description:
PtWidget is the fundamental superclass. All widgets belong to a subclass of
PtWidget.
Geometry
Geometry refers to the size and location of the widget. The following resources let you
set and get the widget’s geometry in various ways:
Pt_ARG_AREA The (x, y) coordinates of the widget’s upper left corner, and the
widget’s height and width.
Pt_ARG_DIM The widget’s width and height.
Pt_ARG_EXTENT A rectangle giving the coordinates of the upper-left and

lower-right corners of the widget.
Pt_ARG_GRID_LAYOUT_DATA
The grid layout data structure, which contains layout hints and
settings for the widget when its container has a layout type of
PtGridLayout.
Pt_ARG_HEIGHT The overall height.
Pt_ARG_LAYOUT_DATA
A generic resource to set the layout data structure, which
contains layout hints and settings for the widget.
Pt_ARG_MAXIMUM_DIM
The maximum size of the widget.
Pt_ARG_MINIMUM_DIM
The minimum size of the widget.

PtWidget © 2010, QNX Software Systems GmbH & Co. KG.
Pt_ARG_POS The coordinates of the upper left corner of the widget.
Pt_ARG_ROW_LAYOUT_DATA
The row layout data structure, which contains layout hints and
settings for the widget when its container has a layout type of
PtRowLayout.
Pt_ARG_WIDTH The overall width of the widget.
These resources aren’t displayed in PhAB’s control panel; you can use the pointer to
change a widget’s size and location, or you can edit the values in PhAB’s toolbar.
Setting one of these resources causes the others to be updated automatically.
Storing arbitrary user data

You can store arbitrary data in a widget by using these resources:
Pt_ARG_POINTER
When you set this resource, the widget copies the value of the pointer into its
internal memory.
If you use Pt_ARG_POINTER, you can have several widgets pointing at the
same data. If you free the data, you’ll need to make sure that no widgets still
refer to it.
Pt_ARG_USER_DATA
When you set this resource, the widget copies a block of data of a given size into
its internal memory.
There’s another resource, Pt_ARG_DATA, that sounds like it can be used for storing
user data, but it can’t. It’s used internally by PhAB applications and compound
widgets.
New resources:

Pt_ARG_ANCHOR_FLAGS unsigned Flag 0
Pt_ARG_ANCHOR_OFFSETS PhRect_t Struct 0, 0, 0, 0
Pt_ARG_AREA PhArea_t Struct 0,0,0,0
Pt_ARG_BEVEL_WIDTH unsigned short Scalar 2
continued. . .


Pt_ARG_BITMAP_CURSOR PhCursorDef_t * Alloc NULL
Pt_ARG_CURSOR_COLOR PgColor_t Scalar Ph_CURSOR_DEFAULT_COLOR
Pt_ARG_CURSOR_TYPE unsigned short Scalar Ph_CURSOR_INHERIT
Pt_ARG_DATA void * Alloc NULL

Pt_ARG_DIM PhDim_t Struct 0,0
Pt_ARG_EFLAGS unsigned long Flag 0
Pt_ARG_EXTENT PhRect_t Struct 0,0,0,0
Pt_ARG_FLAGS long Flag 0
Pt_ARG_GRID_LAYOUT_DATA PtGridLayoutData_t * Struct NULL
Pt_ARG_HEIGHT unsigned short Scalar 0
Pt_ARG_HELP_TOPIC char * String NULL
Pt_ARG_LAYOUT_DATA void * Struct NULL
Pt_ARG_MAXIMUM_DIM PhDim_t Struct 0,0
Pt_ARG_MINIMUM_DIM PhDim_t Struct 0,0
Pt_ARG_POINTER void * Pointer NULL
Pt_ARG_POS PhPoint_t Struct 0,0
Pt_ARG_RESIZE_FLAGS long Flag 0
Pt_ARG_ROW_LAYOUT_DATA PtRowLayoutData_t * Struct NULL
Pt_ARG_USER_DATA void * Alloc NULL
Pt_ARG_WIDTH unsigned short Scalar 0
Pt_CB_BLOCKED PtCallback_t * Link NULL
Pt_CB_DESTROYED PtCallback_t * Link NULL
Pt_CB_DND PtCallback_t * Link NULL
Pt_CB_FILTER PtRawCallback_t * Link NULL
Pt_CB_HOTKEY PtHotkeyCallback_t * Link NULL
Pt_CB_IS_DESTROYED PtCallback_t * Link NULL
Pt_CB_OUTBOUND PtCallback_t * Link NULL
Pt_CB_RAW PtRawCallback_t * Link NULL
Pt_CB_REALIZED PtCallback_t * Link NULL
continued. . .


Pt_CB_UNREALIZED PtCallback_t * Link NULL
Pt_ARG_ANCHOR_FLAGS
unsigned Flag 0
This resource specifies how the widget is anchored to its parent. The possible values
are:
Pt_LEFT_ANCHORED_RIGHT
Anchor the widget’s left extent to the right edge of its parent’s canvas.
Pt_RIGHT_ANCHORED_RIGHT
Anchor the widget’s right extent to the right edge of its parent’s canvas.
Pt_TOP_ANCHORED_BOTTOM
Anchor the widget’s top extent to the bottom edge of its parent’s canvas.
Pt_BOTTOM_ANCHORED_BOTTOM
Anchor the widget’s bottom extent to the bottom edge of its parent’s canvas.
Pt_LEFT_ANCHORED_LEFT
Anchor the widget’s left extent to the left edge of its parent’s canvas.
Pt_RIGHT_ANCHORED_LEFT
Anchor the widget’s right extent to the left edge of its parent’s canvas.
Pt_TOP_ANCHORED_TOP
Anchor the widget’s top extent to the top edge of its parent’s canvas.
Anchor the widget’s bottom extent to the top edge of its parent’s canvas.
Pt_BALLOONS_ON
If a child widget has been assigned a balloon, pop up the balloon as soon as the
pointer passes over the child widget; otherwise delay the pop up for 1.25
seconds.

If the resize policy conflicts with the anchors, the Pt_ARG_RESIZE_FLAGS override
Pt_ARG_ANCHOR_OFFSETS and Pt_ARG_ANCHOR_FLAGS.
For more information about anchors, see the Geometry Management chapter of the
Photon Programmer’s Guide.
Pt_ARG_ANCHOR_OFFSETS
The four values in this PhRect_t structure (see the Photon Library Reference)
determine the anchor offsets of each of the widget’s sides. (An anchor offset is the
distance between the anchoring side of the parent and corresponding side of the child.)
The Pt_ARG_ANCHOR_OFFSETS resource isn’t displayed in PhAB because PhAB

sets it automatically.
If a side is anchored, its anchor offsets, if explicitly specified, override

Pt_ARG_AREA and Pt_ARG_DIM.
Only offsets that have a corresponding bit set in the Pt_ARG_ANCHOR_FLAGS
resource are applied. For example, let’s say you have a
Pt_ARG_ANCHOR_OFFSETS resource of (5,10,20,25) with absolute anchoring and
a Pt_ARG_ANCHOR_FLAGS resource of Pt_LEFT_ANCHORED_LEFT |
Pt_RIGHT_ANCHORED_RIGHT | Pt_TOP_ANCHORED_TOP |
Pt_BOTTOM_ANCHORED_BOTTOM. In that case, the pane’s extent will be:
• 5 pixels from its parent’s left canvas edge
• 10 pixels from its parent’s top canvas edge
• 20 pixels from its parent’s right canvas edge
• and 25 pixels from its parent’s bottom canvas edge
This remains true even as the parent is resized.

Pt_ARG_AREA

PhArea_t Struct 0,0,0,0
A PhArea_t structure (see the Photon Library Reference) that contains the x, y,
height, and width values for the widget. For related resources, see the “Geometry”
section, above.
You can edit this resource in PhAB’s toolbar, not the control panel; PhAB also sets it
automatically when you move or size the widget.
Pt_ARG_BEVEL_WIDTH
The width of the widget’s bevel if the widget is highlighted and is to draw a bevel (see
Pt_ARG_FLAGS, below, and the Pt_ARG_BASIC_FLAGS resource defined for
PtBasic).
Pt_ARG_BITMAP_CURSOR
PhCursorDef_t * Alloc NULL
Defines bitmaps for the cursor when the cursor type (Pt_ARG_CURSOR_TYPE) is set
to Ph_CURSOR_BITMAP. You can’t edit this resource in PhAB.
The widget automatically sets the hdr member of the PhCursorDef_t structure. For
information, see the Photon Library Reference.
Pt_ARG_CURSOR_COLOR
PgColor_t Scalar Ph_CURSOR_DEFAULT_COLOR
The color of the pointer when it’s inside the widget. See PgColor_t in the Photon
Library Reference.
Pt_ARG_CURSOR_TYPE

The type of cursor:
Ph_CURSOR_INHERIT
Inherit the cursor, not from the class hierarchy, but from the family hierarchy;
that is, from the way your application nests the widgets. The cursor might even
be inherited from the Photon server itself.
Ph_CURSOR_BITMAP
Use the bitmap stored in Pt_ARG_BITMAP_CURSOR for the cursor.
By default, bitmap cursors aren’t inherited by a widget’s child regions. To change this,
set Pt_ARG_CURSOR_TYPE to:
Ph_CURSOR_BITMAP & ˜Ph_CURSOR_NO_INHERIT
For other cursor definitions, see the cursor type table in

PhCharacterCursorDescription_t.
Pt_ARG_DATA
void * Alloc NULL
This resource is used internally by PhAB applications as well as by compound

widgets. It isn’t displayed in PhAB. For more information, see Building Custom
Widgets.
If you want to store arbitrary data in a widget, use its Pt_ARG_POINTER or

Pt_ARG_USER_DATA resource. See “Storing arbitrary user data,” above.
Pt_ARG_DIM
PhDim_t Struct 0,0
A PhDim_t structure (see the Photon Library Reference) that defines the height and
width values for the widget. For related resources, see the “Geometry” section, above.
automatically when you size the widget.

Pt_ARG_EFLAGS

Extended flags inherited by all widgets:
Pt_CONSUME_EVENTS
Consume any event encountered, whether or not an action was performed as a
result of that event. (When a widget has processed an event and prevents another
widget from interacting with the event, the first widget is said to have consumed
the event.)
Pt_INTERNAL_HELP
Display help information for the widget in a balloon, not in the Helpviewer. See
the chapter on Context-Sensitive Help in the Photon Programmer’s Guide.
Pt_DAMAGE_PARENT (read-only)
If the widget is damaged for any reason, damage its parent instead (internal use
only).
Pt_SKIP_LAYOUT
Skip this widget when performing a layout. See Using layouts in the Geometry
Management chapter of the Photon Programmer’s Guide.
Pt_ARG_EXTENT
PhRect_t Struct 0,0,0,0
A PhRect_t structure (see the Photon Library Reference) that contains the extent of
the widget, a rectangle that specifies the upper-left and lower-right corners of the
widget. For related resources, see the “Geometry” section, above.
A widget’s extent isn’t normally calculated until the widget is realized. You can force
a widget to calculate its extent by calling PtExtentWidget() — see the Photon Library
Reference.
Pt_ARG_FLAGS

Common flags used by all widgets. Except for those indicated as read-only, these flags
are all read/write.
PtWidgetFlags() is a convenience function that retrieves the value of this resource.
The flags include:
Pt_ALL_BUTTONS Any pointer button can activate the widget. Default is the left
button only.
Pt_AUTOHIGHLIGHT
Highlight and give focus to the widget when the cursor enters
its extent, and unhighlight and remove focus when the cursor
leaves.
Pt_BLOCKED Prevent the widget and all its non-window-class children from
interacting with Photon events.
Pt_CALLBACKS_ACTIVE
If certain widgets have this bit set, and your application sets
their resources, the relevant callbacks are invoked. Otherwise
callbacks aren’t invoked when your application sets resources.
If a callback refers to this flag, its description says so explicitly.
For example, if this bit is set for a PtDivider and you use
PtSetResources() to change the size of one of its children, the
Pt_CB_DIVIDER_DRAG callback is invoked.
Pt_CLEAR (read-only)
The widget’s brothers-in-front don’t intersect with its extent.
Pt_CLIP_HIGHLIGHT
Clip the corners of the highlighting rectangle.
Pt_DAMAGED (read-only)
The widget requires repair.
Pt_DAMAGE_FAMILY (read-only)
The widget and all its children need to be repaired.
Pt_DELAY_REALIZE
Prevent the widget from becoming realized unless it’s explicitly
realized with PtRealizeWidget().
Pt_DESTROYED (read-only)
The widget has been marked for destruction.

Pt_FOCUS_RENDER
Render a focus indicator when the widget when it gets focus.
Pt_GETS_FOCUS Allow the widget to be granted focus. The widget needs to have
this bit set if it’s to receive key events.
Pt_GHOST Dim the widget. Setting this flag doesn’t affect the widget’s
behavior, just its appearance. The simplest way to disable the
widget is to set the Pt_BLOCKED flag in this resource.
Pt_HIGHLIGHTED Allow the widget to be highlighted as defined by the

Pt_ARG_BEVEL_WIDTH, and the Pt_ARG_BASIC_FLAGS
resource defined by PtBasic.
Pt_IN_FLUX (read-only)
A call to PtContainerHold() has been made on the widget.
Pt_MENUABLE Respond to clicks on the pointer’s right button (i.e. enable the
Pt_CB_MENU callback defined by PtBasic).
Pt_MENU_BUTTON
The widget is a menu item.
Pt_OBSCURED (read-only)
The widget is completely covered by one other widget, or it’s
completely outside its parent container’s canvas.
Pt_OPAQUE (read-only)
This widget obscures everything directly behind it (i.e. it isn’t
transparent).
Pt_PROCREATED (read-only)
The widget was created by another widget (as opposed to an
application), such as the PtList and PtText created by a
PtComboBox.
Pt_REALIZED (read-only)
The widget is realized.
Pt_REALIZING (read-only)
The widget is in the process of being realized.
Pt_REGION Force the widget to have a region.
Pt_SELECTABLE You can select (repeat, arm, disarm, and activate) the widget.
Widgets usually provide visual feedback when selected.
Pt_SELECT_NOREDRAW
The widget doesn’t change its appearance when set or unset.
This is meaningful only when the widget is selectable.

Pt_SET The widget is in a “set” state. Generally, this indicates that the
widget has been selected.
Pt_TOGGLE Pressing the pointer button on this widget causes it to toggle

between being set and unset. Normally, selectable widgets act
as push buttons — they become set when you press the pointer
button, and unset when you release the button.
Pt_WIDGET_REBUILD (read-only)
The widget will be rebuilt (rerealized) when the widget engine
is finished applying resource changes.
Pt_WIDGET_RESIZE (read-only)
The widget will be resized when the widget engine is finished
applying resource changes.
Pt_ARG_GRID_LAYOUT_DATA
PtGridLayoutData_t * Struct NULL
A PtGridLayoutData_t structure that defines additional layout data for the widget
when its container widget uses a PtGridLayout type layout.
PtGridLayoutData_t has at least these members:
short flags Combination of the following flags:

• Pt_H_GRAB — If the parent grows horizontally, this child’s
cell gets some or all of the extra space, depending on the
setting of the h_weight member, and whether or not other
cells are also grabbing extra space.
• Pt_V_GRAB — If the parent grows vertically, this child’s
cell gets some or all of the extra space, depending on the
setting of the v_weight member, and whether or not other
cells are also grabbing extra space .
• Pt_GRAB_BOTH — Pt_V_GRAB | Pt_V_GRAB
• Pt_H_ALIGN_BEGINNING — Left align the widget in its
cell
• Pt_H_ALIGN_CENTER — Center the widget horizontally
in its cell
• Pt_H_ALIGN_END — Right align the widget in its cell
• Pt_H_ALIGN_FILL — Horizontally stretch (or “fill”) the
widget in its cell

• Pt_V_ALIGN_BEGINNING — Top align the widget in its

cell
• Pt_V_ALIGN_CENTER — Center the widget vertically in
its cell
• Pt_V_ALIGN_END — Bottom align the widget in its cell
• Pt_V_ALIGN_FILL — Vertically stretch (or “fill”) the
widget in its cell
• Pt_ALIGN_BEGINNING_BOTH —
Pt_H_ALIGN_BEGINNING | Pt_V_ALIGN_BEGINNING
• Pt_ALIGN_CENTER_BOTH — Pt_H_ALIGN_CENTER |
Pt_V_ALIGN_CENTER
• Pt_ALIGN_END_BOTH — Pt_H_ALIGN_END |
Pt_V_ALIGN_END
• Pt_ALIGN_FILL_BOTH — Pt_H_ALIGN_FILL |
Pt_V_ALIGN_FILL
short h_span Horizontal span of this child in a number of columns.
short v_span Vertical span of this child in a number of rows.
PhDim_t hint The w (width) and h (height) hints for this child widget. Think
of these hints as a user defined minimum size, even if the
widget could be smaller. Set w and h to 0 if you just want to
apply flags to this child.
short h_weight The portion of the extra space the widget’s cell gets if its parent
grows, and the widget has the Pt_H_GRAB flag set.
short v_weight The portion of the extra space the widget’s cell gets if its parent
grows, and the widget has the Pt_V_GRAB flag set.
PhRect_t margin cell margins in pixels, where:

• ul.y is the top

You can use PtGridLayoutDataDflts to initialize your copy of PtGridLayoutData_t.

It has the following values:
• flags = Pt_H_ALIGN_BEGINNING | Pt_V_ALIGN_BEGINNING
• h_span = v_span = 1
• hint.w = hint.h = 0
• h_weigth = v_weight = 0
• margin.ul.x = margin.ul.y = margin.lr.x = margin.lr.y = 0
Pt_ARG_HEIGHT
The height of the widget. For related resources, see the “Geometry” section, above.
Pt_ARG_HELP_TOPIC
char * String NULL
The meaning of this resource depends on the bits set in Pt_ARG_EFLAGS:
• If Pt_INTERNAL_HELP isn’t set, Pt_ARG_HELP_TOPIC is used to set the topic

position within the HTML help file.
• If Pt_INTERNAL_HELP is set, Pt_ARG_HELP_TOPIC is the help information to

be displayed.
For more information, see the PtHelp*() functions and the chapter on
Context-Sensitive Help in the Photon Programmer’s Guide.

Pt_ARG_LAYOUT_DATA

void * Struct NULL
This resource provides a convenient method to get or set either of the

Pt_ARG_*_LAYOUT_DATA resources.
When you set this resource using PtSetResource() or PtSetArg(), set the value
argument to a pointer to the layout data structure you want to use. This can be one of:
• PtRowLayoutData_t
• PtGridLayoutData_t
You can optionally set the len argument to a pointer to the layout type that corresponds
to the data structure (that is, PtRowLayout or PtGridLayout). If you set len to
NULL, the layout data structure for the current layout is set. In this case, make sure
that the data structure corresponds to the correct layout type, or your application might
crash.
Pt_ARG_MAXIMUM_DIM
PhDim_t Struct 0,0
A PhDim_t structure (see the Photon Library Reference) that defines the maximum
size that a widget can be. For related resources, see the “Geometry” section, above.
Pt_ARG_MINIMUM_DIM
PhDim_t Struct 0,0
A PhDim_t structure (see the Photon Library Reference) that defines the minimum
size that a widget can be. For related resources, see the “Geometry” section, above.
Pt_ARG_POINTER
void * Pointer NULL
A pointer to any data that you want to associate with the widget.

For a comparison between this resource and Pt_ARG_USER_DATA, see “Storing

arbitrary user data,” above.
Pt_ARG_POS
PhPoint_t Struct 0,0
A PhPoint_t structure that stores the x and y coordinates for the widget. For related
resources, see the “Geometry” section, above.
automatically when you move the widget.
Pt_ARG_RESIZE_FLAGS
long Flag 0
Controls a widget’s resize policy in both the x and y directions. Possible values:
• Pt_RESIZE_X_AS_REQUIRED
• Pt_RESIZE_X_ALWAYS
• Pt_RESIZE_X_INITIAL
• Pt_RESIZE_X_BITS
• Pt_RESIZE_Y_AS_REQUIRED
• Pt_RESIZE_Y_ALWAYS
• Pt_RESIZE_Y_INITIAL
• Pt_RESIZE_Y_BITS
• Pt_RESIZE_XY_ALWAYS
• Pt_RESIZE_XY_AS_REQUIRED
• Pt_RESIZE_XY_INITIAL
• Pt_RESIZE_XY_BITS
Note that each ...BITS flag is a mask that represents all the bits of that type.
The default setting of this resource is 0; that is, no resize policy is in effect.
A widget’s resize policy deals solely with the widget’s renderable data. For a button,
the data is its text; for a container, the data is its children. Any rendered data that
doesn’t fit within the widget’s canvas is clipped.

If no resize policy is in effect, the widget’s size is unbounded; it may be made as large
or small as specified via Pt_ARG_DIM or Pt_ARG_AREA.
If a resize policy is in effect, the widget grows or shrinks to honor that policy. If the
policy is ...ALWAYS, the widget resizes itself to fit its data—the dimensions specified
via Pt_ARG_DIM or Pt_ARG_AREA don’t apply. If the policy is ...AS_REQUIRED,
the widget resizes itself to fit its data only if its current canvas size is inadequate to
contain that data. In other words, it grows, but doesn’t shrink, to fit its data.
If the widget has the ...INITIAL bit set, the resize policy is applied only once each time
the widget is realized. This bit is meaningful only in concert with ...ALWAYS or
...AS_REQUIRED.
For more information about resize policies, see the Geometry Management chapter of
Pt_ARG_ROW_LAYOUT_DATA
PtRowLayoutData_t * Struct NULL
A PtRowLayoutData_t structure that defines additional layout data for the widget
when its container widget uses a PtRowLayout type layout.
PtRowLayoutData_t has at least these members:
PhDim_t hint Contains w (width) and h (height) hints for this child widget. Think
of these hints as a user defined minimum size, even if the widget
could be smaller. Set w and h to 0 if you just want to apply flags to
this child.
short flags Combination of the following flags:

• Pt_ROW_WRAP_AFTER — Unconditionally wrap after this
child. Pt_ROW_WRAP should be set in the flags member of the
PtRowLayoutInfo_t of the parent.
• Pt_ROW_WRAP_BEFORE — Unconditionally wrap this child.
Pt_ROW_WRAP should be set in the flags member of the
PtRowLayoutInfo_t of the parent.
• Pt_ROW_FILL — If this child is the last one in its row or
column, stretch or shrink it to occupy all the available space.

You can use PtRowLayoutDataDflts to initialize your copy of PtRowLayoutData_t. It

has the following values:
• flags = NULL
• hint.w = hint.h = 0
Pt_ARG_USER_DATA
void * Alloc NULL
Data that you want to store in the widget’s internal memory.

For a comparison between this resource and Pt_ARG_POINTER, see “Storing
arbitrary user data,” above.
Pt_ARG_WIDTH
The width of the widget. For related resources, see the “Geometry” section, above.
Pt_CB_BLOCKED
whenever it must ignore an event due to being blocked.
following members:
reason Pt_CB_BLOCKED
event A pointer to a PhEvent_t structure that describes the event that was
blocked for this widget.

cbdata NULL
Pt_CB_DESTROYED
is marked for destruction and is no longer visible. You can use these callbacks, for
example, to adjust the appearance of the widgets around the one being destroyed.
In contrast, the Pt_CB_IS_DESTROYED callbacks are invoked when the widget’s

resources are actually being released.

following members:
reason Pt_CB_DESTROYED
event A pointer to a PhEvent_t structure filled with NULLs.
cbdata NULL
Pt_CB_DND
A list of PtCallback_t structures that define the callbacks called when a

drag-and-drop (Ph_EV_DNDROP) event is received. For more information, see the
Drag and Drop chapter of the Photon Programmer’s Guide.
A widget doesn’t have to have Pt_SELECTABLE set in its Pt_ARG_FLAGS for its
Pt_CB_DND callbacks to be invoked.

following members:
reason Pt_CB_DND

• Ph_EV_DND_ENTER — the pointer has moved into the
widget during a drag-and-drop operation.

• Ph_EV_DND_LEAVE — the pointer has left the widget.

• Ph_EV_DND_CANCEL — the drag-and-drop operation has
been canceled.
• Ph_EV_DND_COMPLETE — the drag-and-drop operation has
been completed.
• Ph_EV_DND_MOTION — the pointer is moving.
• Ph_EV_DND_DROP — the user is dropping the dragged item
on this widget.

cbdata A pointer to a PtDndCallbackInfo_t structure that contains at

• PtTransportCtrl_t *trans_ctrl — a pointer to the
PtTransportCtrl_t structure (see the Photon Library
Reference) controlling the drag-and-drop operation if this
application is the originator of it. NULL otherwise.
The following members are valid only when the
reason_subtype is Ph_EV_DND_DROP:
int unsigned fetch_index
This contains the index of the element defined in
the “fetch array” that describes the data
contained in the data member of this structure.
PhTransportHdr_t *trans_hdr
A pointer to the transport header for the
unpacked data. See <PhTransport.h>.
void *data A pointer to the data extracted from the
drag-and-drop event. The type of data is given
by examining the fetch_index member.
The following member is meaningful only when the
reason_subtype is Ph_EV_DND_ENTER:
int unsigned flags
If set to Ph_DND_DELAY_ACK in the callback, the
library doesn’t automatically acknowledge the ENTER
event. This results in a clock cursor over this drop zone
until the drag-and-drop operation is canceled.
Otherwise the library automatically acknowledges the
ENTER event based on the number of data items selected
from the drag-and-drop event via PtDndSelect().
The PtTransportCtrl_t structure also includes:

int unsigned handle

A variable for the your convenience. The value placed
here will be found in handle in subsequent callbacks
related to the ENTER event where the handle was set.
Additional data is passed to Pt_CB_DND callbacks for these widget classes:
• PtFileSel
• PtGenList
• PtGenTree
• PtList
• PtRawList
• PtRawTree
• PtTree
A drag-and-drop recipient typically calls PtDndSelect() when the reason_subtype is

Ph_EV_DND_ENTER, and handles the data when the reason_subtype is
Ph_EV_DND_DROP. The other subtypes can be generally ignored.
For more information, see the Drag and Drop chapter of the Photon Programmer’s
Guide.
Pt_CB_FILTER
PtRawCallback_t * Link NULL
A list of raw callbacks invoked when an event that matches the provided event mask is
to be passed to the widget.
These callbacks are invoked before the event is processed by the widget. Contrast this
resource with Pt_CB_RAW.
Because the Pt_CB_FILTER callback is called before the widget processes the event,
it gives you the opportunity to decide if the event should be ignored, discarded, or
processed by the widget. The return code from the callback indicates what is to
happen to the event.
You can add a Pt_CB_FILTER callback to a widget in your application’s code by
calling PtAddFilterCallback() or PtAddFilterCallbacks(). For more information about
this callback, see “Event handlers” in the Events chapter of the Photon Programmer’s
Guide.


following members:
reason Pt_CB_FILTER

cbdata NULL
These callbacks should return one of:
Pt_CONSUME Consume the event and prevent further propagation of it.
Pt_IGNORE Ignore the event. The event is still consumed if the widget has
Pt_CONSUME_EVENTS set in its Pt_ARG_EFLAGS. If
Pt_CONSUME_EVENTS isn’t set, the event continues through the
widget hierarchy as if the current widget didn’t exist.
Pt_PROCESS Allow the event to be processed by the widget as usual.
Pt_CB_HOTKEY
PtHotkeyCallback_t * Link NULL
A list of PtHotkeyCallback_t structures. If the widget receives a key event that

matches a structure’s key cap and key modifiers, the widget calls the function specified
in that structure. If a function isn’t specified, the widget invokes its
Pt_CB_ACTIVATE callback list with a reason_subtype of Pt_CB_HOTKEY.
A hotkey isn’t invoked if any ancestor of the widget that owns it is blocked.
You can add a Pt_CB_HOTKEY callback to a widget in your application’s code by

calling PtAddHotkeyHandler(). For more information about this callback, see “Hotkey
callbacks” in the Editing Resources and Callbacks in PhAB chapter of the Photon
following members:
reason Pt_CB_HOTKEY
cbdata A pointer to a PtHotkeyCallback_t structure.


Pt_CB_IS_DESTROYED
widget’s resources are being released. You’ll find this resource useful for cleaning up
variables or memory associated with the widget.
In contrast, the Pt_CB_DESTROYED callbacks are invoked when the widget is

marked for destruction and is no longer visible.

following members:
reason Pt_CB_IS_DESTROYED
cbdata NULL
Pt_CB_OUTBOUND
A list of PtCallback_t structures that define the callbacks invoked when you press
the pointer button on the widget and then move out of the “hot spot” with the button
still depressed.
This callback is particularly useful for initiating drag or drag-and-drop operations. For
more information, see the Drag and Drop chapter of the Photon Programmer’s Guide.
following members:
reason Pt_CB_OUTBOUND
reason_subtype The button state (the same as ptr->button_state if the code given
below is included in your callback).
caused the callback to be invoked. The event data is a
PhPointerEvent_t structure (see the Photon Library
Reference) that can be fetched in the following manner:

PhPointerEvent_t *ptr =
(PhPointerEvent_t *)PhGetData( cbinfo->event );
cbdata NULL
Pt_CB_RAW
PtRawCallback_t * Link NULL
A list of PtRawCallback_t structures that defines the raw callbacks that the widget
invokes if the event it receives matches the event mask provided in the
PtRawCallback_t structure.
These callbacks are invoked after the widget has processed the event, even if the
widget’s class methods consume it. Contrast this with the Pt_CB_FILTER resource,
which is invoked before the widget processes the event.
You can add a Pt_CB_RAW callback to a widget in your application’s code by calling
PtAddEventHandler() or PtAddEventHandlers(). For more information about this
callback, see “Event handlers” in the Events chapter of the Photon Programmer’s
Guide.
following members:
reason Pt_CB_RAW
the callback to be invoked. If the widget’s class methods consumed the
event, Ph_CONSUMED is set in the event’s processing_flags member.
cbdata NULL
These callbacks should return one of:
Pt_CONSUME Consume the event and prevent further propagation of it.
Pt_CONTINUE Allow the event to be passed up to the widget’s parent.

Pt_CB_REALIZED

whenever it is realized.
following members:
reason Pt_CB_REALIZED
cbdata NULL
Pt_CB_UNREALIZED
whenever it’s unrealized.
following members:
reason Pt_CB_UNREALIZED
cbdata NULL

© 2010, QNX Software Systems GmbH & Co. KG. PtWindow
An application window that’s managed by the Photon Window Manager
Class hierarchy:
PtWidget → PtBasic → PtContainer → PtDisjoint → PtWindow
PhAB icon:
None — use PhAB’s Window or Dialog module.
Public header:
<photon/PtWindow.h>
Description:
The PtWindow class provides a top-level container for your applications’ widgets. It
also provides a standard appearance for all windows. Windows are managed by the
Photon Window Manager if it’s present (PtForwardWindowEvent() sends window
events to the Window Manager — see the Photon Library Reference).
A PtWindow widget that contains an editor application.
The frame and title bar aren’t part of the PtWindow widget; the window manager adds
them. The value of the widget’s Pt_ARG_DIM resource doesn’t include the frame, but
you can call PtWindowGetFrameSize() to determine the size of the frame.

PtWindow © 2010, QNX Software Systems GmbH & Co. KG.
• Use PhAB’s Window module instead of using this widget directly. See “Window
modules” in the Working with Modules chapter of the Photon Programmer’s
Guide.
• A PtWindow is the top-level widget of the application. If you try to use another
class for the top-level widget (aside from a PtRegion), the behavior is undefined
— you’ll likely get a fatal error.
• In addition to the sections below, see the Window Management chapter of the
The PtWindow class handles the details of opening a Photon window and displaying
the widget hierarchy in it. It also tells the Window Manager what controls to place in
the frame around the application window. This gives a standard appearance to the
windows of all applications using the Photon widget library.
Interacting with the Window Manager

Using resources, you can choose which elements of the window frame will be
displayed. You can control which window management functions the Window
Manager will perform, and whether they’re invoked from the window menu or from
one of the window controls. You can also have your application notified when the user
has requested a window management function, regardless of whether or not the
Window Manager will perform that function.
Setting the window’s title
You can specify the string displayed in the window’s title bar by setting the
Pt_ARG_WINDOW_TITLE resource.
Controlling the decorations
You control the elements displayed in the window frame using the
Pt_ARG_WINDOW_RENDER_FLAGS resource. Enable or disable a window-frame
element by setting or clearing the appropriate bit.
The Pt_ARG_WINDOW_RENDER_FLAGS resource also has one of the following
bits set to specify how the window and its frame are displayed and behave:
• Ph_WM_RENDER_ASAPP
• Ph_WM_RENDER_ASDIALOG
• Ph_WM_RENDER_ASICON
• Ph_WM_RENDER_ASPALETTE

Controlling window resizing
If you need to control the maximum and minimum possible sizes for the window, use
the Pt_ARG_MAXIMUM_DIM and Pt_ARG_MINIMUM_DIM resources defined by
PtWidget.
The following resources also control the window’s size:
• Pt_ARG_MAX_HEIGHT
• Pt_ARG_MAX_WIDTH
• Pt_ARG_MIN_HEIGHT
• Pt_ARG_MIN_WIDTH
Enabling Window Manager functions
You can control how the Window Manager operates on your window by setting
Pt_ARG_WINDOW_MANAGED_FLAGS.
Every flag in the resource corresponds to an operation the Window Manager can
perform on the window. If the flag is set, the Window Manager lets you perform that
operation. If a flag isn’t set, the Window Manager disables the operation.
Each operation is identified by the name of the flag that enables/disables it. Here are
the operations the Window Manager lets you perform on a window:
Ph_WM_BACKDROP
Use the window as the backdrop for the workspace.
Ph_WM_CLOSE Close the window. If the window is the main window for the
application, the application itself is terminated.
Ph_WM_COLLAPSE You can collapse the window to just the title bar.
Ph_WM_CONSWITCH
Move the window within the Photon coordinate space so that it
remains in the same position on the screen when the workspace
is moved in response to a console-switch request.
Ph_WM_FOCUS Give focus to the window.

Ph_WM_HIDE Minimize/hide the window. You can restore the window by
clicking on its button in the running-tasks part of the shelf.
Ph_WM_MAX Maximize the window (i.e. make it fill the entire screen).
Ph_WM_MOVE Move the window to a new location.
Ph_WM_NO_FOCUS_LIST
Prevent you from cycling focus to the window by pressing
Alt-Esc, Alt-Shift-Esc, or Alt-Tab.

Ph_WM_RESIZE Change the size of the window.
Ph_WM_RESTORE Restore the window to its state prior to an iconify or maximize

operation.
Ph_WM_TASKBAR Taskbar applications should include this window.
Ph_WM_TERMINATE
Terminate the application. This operation is used for graceful
shutdown of the windowing system.
Ph_WM_TOBACK Move the window to the back of the window stacking order.
Ph_WM_TOFRONT Move the window to the front of the window stacking order.
Notifying the application
You may also tell the Window Manager to notify the application after it has done a
Window Manager operation. This behavior is controlled by the
Pt_ARG_WINDOW_NOTIFY_FLAGS resource. This resource consists of the same
set of flags as the Pt_ARG_WINDOW_MANAGED_FLAGS resource.
Setting a flag in this resource tells the Window Manager that it should send an event to
the application whenever the corresponding operation is performed on the window
widget. The event sent to the application is handled by the window’s
Pt_CB_WINDOW callbacks.
The callback data for these callbacks consists of a pointer to a window event structure,
PhWindowEvent_t (described in the Photon Library Reference).
Creating subwindows
Some parts of the UI, such as toolbars, palettes, or dialogs, may reside outside the
main application window in windows of their own. These windows are usually
subwindows of the main application window.
A subwindow is obtained by creating a window widget as the child of another window
widget. A subwindow can’t be placed behind its parent. The subwindows associated
with a window are also iconified as a group whenever the window itself is iconified.
New resources:

Pt_ARG_MAX_HEIGHT short Scalar 0 (See below)
Pt_ARG_MAX_WIDTH short Scalar 0 (See below)
continued. . .


Pt_ARG_MIN_HEIGHT short Scalar 0 (See below)
Pt_ARG_MIN_WIDTH short Scalar 0 (See below)
Pt_ARG_WINDOW_ACTIVE_COLOR PgColor_t Scalar See below
Pt_ARG_WINDOW_FLAGS unsigned short Flag See below
Pt_ARG_WINDOW_FRONT_WINDOW PhRid_t Scalar 0
Pt_ARG_WINDOW_HELP_ROOT char * String NULL
Pt_ARG_WINDOW_INACTIVE_COLOR PgColor_t Scalar See below
Pt_ARG_WINDOW_MANAGED_FLAGS unsigned long Flag See below
Pt_ARG_WINDOW_NOTIFY_FLAGS unsigned long Flag See below
Pt_ARG_WINDOW_RENDER_FLAGS unsigned long Flag See below
Pt_ARG_WINDOW_STATE unsigned long Flag See below
Pt_ARG_WINDOW_TITLE char * String "Untitled"
Pt_ARG_WINDOW_TITLE_COLOR PgColor_t Scalar See below
Pt_CB_WINDOW PtCallback_t * Link NULL
Pt_CB_WINDOW_CLOSING PtCallback_t * Link NULL
Pt_CB_WINDOW_OPENING PtCallback_t * Link NULL
Pt_CB_WINDOW_TRANSPORT PtCallback_t * Link NULL
Pt_ARG_MAX_HEIGHT
short Scalar 0 (See below)
The maximum height of the window. If you set this resource to 0, the default value
specified by the window manager is used.
You should use Pt_ARG_MAXIMUM_DIM instead of this resource.
Pt_ARG_MAX_WIDTH
short Scalar 0 (see below)
The maximum width of the widget. If you set this resource to 0, the default value

You should use Pt_ARG_MAXIMUM_DIM instead of this resource.
Pt_ARG_MIN_HEIGHT
The minimum height of the widget. If you set this resource to 0, the default value
You should use Pt_ARG_MINIMUM_DIM instead of this resource.
Pt_ARG_MIN_WIDTH
The minimum width of the widget. If you set this resource to 0, the default value
You should use Pt_ARG_MINIMUM_DIM instead of this resource.
Pt_ARG_WINDOW_ACTIVE_COLOR
PgColor_t Scalar Pg_DEFAULT_WM_COLOR
The color of the window’s frame when the window has focus. This overrides the color
specified by the window manager.
Pt_ARG_WINDOW_FLAGS
unsigned short Flag Pt_WINDOW_FRAME_BLOCKABLE
This resource has a single bit, Pt_WINDOW_FRAME_BLOCKABLE. It controls

whether the Window Manager knows that the window widget is blocked with the
Pt_BLOCKED flag in Pt_ARG_FLAGS. If this bit is not set, a user can give the
window focus and resize it, even if it’s blocked.

Pt_ARG_WINDOW_FRONT_WINDOW

PhRid_t Scalar 0
Specifies the region ID of the window that this window is to be positioned behind.
Pt_ARG_WINDOW_HELP_ROOT
char * String NULL
Defines the root topic path for the window. For more information, see the PtHelp*()
functions in the Photon Library Reference and the Context-Sensitive Help chapter of
Pt_ARG_WINDOW_INACTIVE_COLOR
The color of the window’s frame when the window doesn’t have focus. This overrides
the color specified by the window manager.
Pt_ARG_WINDOW_MANAGED_FLAGS
unsigned long Flag Ph_WM_APP_DEF_MANAGED
Controls which actions the Window Manager performs for the application, but doesn’t
affect whether or not the Window Manager notifies the application of those actions
(for that, use Pt_ARG_WINDOW_NOTIFY_FLAGS). You can set the following bits:
If you set this bit: the Window Manager:

Ph_WM_BACKDROP Allows the window to be the workspace backdrop
Ph_WM_CLOSE Closes the application
Ph_WM_COLLAPSE Collapses the window to just the title bar
Ph_WM_CONSWITCH Moves the window to keep it on the visible display
whenever the virtual Photon console is switched
continued. . .

If you set this bit: the Window Manager:

Ph_WM_FFRONT Allows the window to become force front. To make
the base window force front, set
Ph_WM_STATE_ISFRONT in the
Pt_ARG_WINDOW_STATE resource.
Ph_WM_FOCUS Handles gaining and losing focus for this window
Ph_WM_HELP Provides context-sensitive help
Ph_WM_MAX Maximizes the window
Ph_WM_MENU Pops up the window menu
Ph_WM_MOVE Moves the window
Ph_WM_NO_FOCUS_LIST Doesn’t let you cycle focus to the window when you
press Alt-Esc, Alt-Shift-Esc, or Alt-Tab
Ph_WM_RESIZE Resizes the application
Ph_WM_RESTORE Restores the window after it has been iconified,
maximized, or hidden
Ph_WM_TASKBAR Includes the window in its taskbar
Ph_WM_TOBACK Sends the window to the back
Ph_WM_TOFRONT Sends the window to the front
Ph_WM_HIDE Hides the window
The default is Ph_WM_APP_DEF_MANAGED, a convenience manifest that’s defined

in <PhWm.h> as:
#define Ph_WM_APP_DEF_MANAGED ( Ph_WM_CLOSE | \

Ph_WM_FOCUS | \
Ph_WM_MENU | \
Ph_WM_TOFRONT | \
Ph_WM_TOBACK | \
Ph_WM_RESIZE | \
Ph_WM_MOVE | \
Ph_WM_HIDE | \
Ph_WM_MAX | \
Ph_WM_RESTORE | \
Ph_WM_TASKBAR | \
Ph_WM_COLLAPSE)
Pt_ARG_WINDOW_NOTIFY_FLAGS
unsigned long Flag Ph_WM_RESIZE|Ph_WM_CLOSE| Ph_WM_HELP

This resource controls which events the Pt_CB_WINDOW callbacks are invoked for.
This resource doesn’t cause the window manager to perform actions (for that, use
Pt_ARG_WINDOW_MANAGED_FLAGS). Pt_ARG_WINDOW_NOTIFY_FLAGS
uses the same set of bits as Pt_ARG_WINDOW_MANAGED_FLAGS, but the
following bits have no notification associated with them:
• Ph_WM_FFRONT
• Ph_WM_NO_FOCUS_LIST
• Ph_WM_TASKBAR
Pt_ARG_WINDOW_RENDER_FLAGS
unsigned long Flag Ph_WM_APP_DEF_RENDER
Controls how the Window Manager renders components of the window. The value of
this resource is one of the following bits, which determine how the window and its
frame look and feel:
Ph_WM_RENDER_ASAPP
Render the window as an application.
Ph_WM_RENDER_ASDIALOG
Render it as a dialog.
Ph_WM_RENDER_ASICON
Render it as an icon.
Ph_WM_RENDER_ASPALETTE
Render it as a palette.
as well as any combination of the following bits:
Ph_WM_RENDER_BORDER
Put a border around the window.
Ph_WM_RENDER_CLOSE
If the window has a title bar, include a close button.
Ph_WM_RENDER_COLLAPSE
If the window has a title bar, add a collapse button.
Ph_WM_RENDER_HELP
If the window has a title bar, include a help button.

Ph_WM_RENDER_INLINE
Add a black line just inside the standard borders.
Ph_WM_RENDER_MAX
If the window has a title bar, include a maximize button.
Ph_WM_RENDER_MENU
If the window has a title bar, include a menu button.
Ph_WM_RENDER_MIN
If the window has a title bar, include a minimize button.
Ph_WM_RENDER_RESIZE
If the window has a border, add resize handles.
Ph_WM_RENDER_TITLE
If the window has a border, add a title bar.
The default value is Ph_WM_APP_DEF_RENDER, a convenience manifest that’s

defined in <PhWm.h> as:
#define Ph_WM_APP_DEF_RENDER ( Ph_WM_RENDER_ASAPP | \

Ph_WM_RENDER_BORDER | \
Ph_WM_RENDER_RESIZE | \
Ph_WM_RENDER_MOVE | \
Ph_WM_RENDER_CLOSE | \
Ph_WM_RENDER_TITLE | \
Ph_WM_RENDER_MENU | \
Ph_WM_RENDER_MIN | \
Ph_WM_RENDER_MAX | \
Ph_WM_RENDER_COLLAPSE)
Pt_ARG_WINDOW_STATE
unsigned long Flag Ph_WM_STATE_ISFOCUS
This resource controls the window’s state. You can set one of the following:
Ph_WM_STATE_ISALTKEY
Pass Alt function-key combinations to the application.
Ph_WM_STATE_ISBACKDROP
Open as the workspace backdrop. See
Ph_WM_STATE_ISBLOCKED
Block input to the window.

Ph_WM_STATE_ISCOLLAPSE
Display just the window’s title bar.
Ph_WM_STATE_ISFOCUS
Grant focus to the window when it’s opened if the cursor focus option to the
Window Manager is disabled (default is enabled).
Ph_WM_STATE_ISFRONT
Open the base window in front of the windows of all applications. Child
windows will open behind the last forced front window in the family. See
Ph_WM_STATE_ISHIDDEN
Open as a normal window but don’t display it.
Ph_WM_STATE_ISICONIFIED
Open the window and iconify it.
Ph_WM_STATE_ISMAX
Open as a maximized window.
You can get and set the state of the window at any time by using this resource, but you
might get unexpected results if the user is changing the window state at the same time.
The safest time to use this resource to set the window state is before the window is
realized. For example, you could set it when creating the PtWindow widget or in the
window’s Pt_CB_WINDOW_OPENING callback. The setting will be in effect when
the window is realized.
You can set Pt_ARG_WINDOW_STATE after the window has been realized, basing
your changes on what you think the current window state is, but it’s safer to tell the
window manager how you want to change the state, by calling:
PtForwardWindowEvent()
Change the state for the window associated with a given region ID
PtForwardWindowTaskEvent()
Change the state for a window associated with a given Photon connection ID
Pt_ARG_WINDOW_TITLE
char * String "Untitled"
The string that the Window Manager displays in the title bar.

Pt_ARG_WINDOW_TITLE_COLOR
The color of the window’s title (i.e. the text). This overrides the color specified by the
window manager.
Pt_CB_WINDOW
when it receives an event from the Window Manager. See
Pt_ARG_WINDOW_NOTIFY_FLAGS.
following members:
reason Pt_CB_WINDOW

cbdata A pointer to a PhWindowEvent_t (described in the Photon

Library Reference).

For an example of using this callback to verify that the user really wants to exit the
application, see “Notification callback” in the Window Management chapter of the
Pt_CB_WINDOW_CLOSING
when the window is being closed. It’s invoked before the window’s region is removed.
These callbacks are invoked when the window is about to unrealize for any reason.
This includes transporting to another Photon and explicit calls to PtDestroyWidget() or
PtUnrealizeWidget(). If you want to make sure in a Window Closing callback that the
window is actually being destroyed, check the Pt_DESTROYED flag in

Pt_ARG_FLAGS. You can also use the Pt_CB_DESTROYED callback to know when
a window is marked for destruction, or Pt_CB_IS_DESTROYED to know when it is
being destroyed.
The Pt_CB_WINDOW_CLOSING callbacks are invoked when the window is already

closing. To be notified before the window is closed, use the Ph_WM_CLOSE bit in
Pt_ARG_WINDOW_NOTIFY_FLAGS and the Pt_CB_WINDOW callback.

following members:
reason Pt_CB_WINDOW_CLOSING
event NULL (not supplied).
cbdata NULL (not supplied).
Pt_CB_WINDOW_OPENING
when the window is being opened. If you want to resize the window and want
anchoring to be in effect, do it in this type of callback.
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.

following members:
reason Pt_CB_WINDOW_OPENING
reason_subtype 0 (not used)

cbdata NULL

Pt_CB_WINDOW_TRANSPORT

when the window is being transported through a Jump Gate.
following members:
reason Pt_CB_WINDOW_TRANSPORT
reason_subtype 0 (not used)
event A pointer to a PhEvent_t structure that describes the

Ph_EV_WM event that caused the callback to be invoked.
cbdata Internal use only

Pt_ARG_BEVEL_WIDTH PtWidget Not used by this class.
continued. . .


Pt_ARG_DIM PtWidget
Pt_ARG_MARGIN_HEIGHT PtBasic Not used by this class.
Pt_ARG_MARGIN_WIDTH PtBasic Not used by this class.
continued. . .


Pt_ARG_POS PtWidget
Pt_ARG_RESIZE_FLAGS PtWidget |=Pt_RESIZE_XY_AS_REQUIRED
Pt_ARG_SYSINFO PtDisjoint
Pt_CB_ARM PtBasic
Pt_CB_DND PtWidget
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
continued. . .


Pt_CB_SYSINFO PtDisjoint
The PtWindow widget defines the following convenience functions:
PtWindowFocus() Give a window focus.
PtWindowGetState()
Return the current state of a window.
PtWindowToBack() Move a window to the back of the workspace.
PtWindowToFront() Bring a window to the front and give it focus.

PtWindowFocus() © 2010, QNX Software Systems GmbH & Co. KG.
Give a window focus
Synopsis:
int PtWindowFocus( PtWidget_t *widget );
Description:
This function lets your application give focus to the specified window widget. To do
this, the function sends a message to the Window Manager, telling it to give the
window focus. The Window Manager may change consoles if the specified window
isn’t in the current console.
Returns:
0 Successful completion.
-1 The window wasn’t found or an error occurred.
Examples:
PtWidget_t *my_window;
/* give my window focus */

if ( 0 == PtWindowFocus( my_window ) ) {
/* focus related processing */
}
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtWindowToBack(), PtWindowToFront()
PtForwardWindowEvent() in the Photon Library Reference

© 2010, QNX Software Systems GmbH & Co. KG. PtWindowGetState()
Return the current state of a window
Synopsis:
long PtWindowGetState( PtWidget_t *widget );
Description:
This function returns the current state of the window pointed to by the widget variable:
State Description
Ph_WM_STATE_ISHIDDEN The window is hidden.
Ph_WM_STATE_ISMAX The window is maximized.
Ph_WM_STATE_ISBACKDROP The window is a backdrop.
Ph_WM_STATE_ISTASKBAR The window is a taskbar.
Ph_WM_STATE_ISICONIFIED The window is iconified.
Ph_WM_STATE_ISFRONT The window is the frontmost in the family.
Ph_WM_STATE_ISFOCUS The window has focus.
Returns:
The current state of the window, or -1 if the widget isn’t a PtWindow or wasn’t
realized.
Classification:
Photon
Safety
Signal handler No
Thread No

PtWindowToBack() © 2010, QNX Software Systems GmbH & Co. KG.
Move a window to the back of the workspace
Synopsis:
void PtWindowToBack( PtWidget_t *widget );
Description:
This function moves the specified window widget and all its child windows to the back
of the workspace. To do this, the function sends a message to the Window Manager.
There’s no way to move a window behind its parent window. If you want to be able to
move one window behind another in your application, they must be siblings. For
example, to make a window a sibling rather than a child of the base window, set the
window’s parent to NULL.
Examples:
/* move my window to the back */

PtWindowToBack( my_window );
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtWindowFocus(), PtWindowToFront()
PtForwardWindowEvent(), PtWidgetToBack(), PtWidgetToFront() in the Photon
Library Reference

© 2010, QNX Software Systems GmbH & Co. KG. PtWindowToFront()
Bring a window to the front and give it focus
Synopsis:
void PtWindowToFront( PtWidget_t *widget );
Description:
This function brings the specified window widget and all its child windows to the front
of the workspace and gives the front window focus. To do this, the function sends a
message to the Window Manager. The Window Manager may switch consoles if the
specified window isn’t within the current workspace.
There’s no way to move a parent window in front of its child. If you want to be able to
move one window in front of another in your application, they must be siblings. For
example, to make a window a sibling rather than a child of the base window, set the
window’s parent to NULL.
Examples:
/* bring my window to the front */

PtWindowToFront( my_window );
Classification:
Photon
Safety
Signal handler No
Thread No
See also:
PtWindowToBack(), PtWindowFocus()
PtForwardWindowEvent(), PtWidgetToBack(), PtWidgetToFront() in the Photon
Library Reference

Appendix A
What’s New
In this appendix. . .
What’s new in Photon for QNX Neutrino 6.3 Service Pack 1 966
May 13, 2010 Appendix: A • What’s New 963

© 2010, QNX Software Systems GmbH & Co. KG. What’s new in Photon for QNX Neutrino 6.5.0
This appendix lists the changes and additions to the Photon Widget Reference.
• “What’s new in Photon for QNX Neutrino 6.5.0”
• “What’s new in Photon for QNX Neutrino 6.4”
• “What’s new in Photon for QNX Neutrino 6.3.0 Service Pack 1”
What’s new in Photon for QNX Neutrino 6.5.0

Changes
PtGenList We’ve documented the following bits for Pt_ARG_LIST_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
The following bits are deprecated:
• Pt_LIST_SCROLLBAR_ALWAYS
• Pt_LIST_SCROLLBAR_NEVER
• Pt_LIST_NOBLIT
PtTreeChangeItem()
Note that this function can return a pointer to a new item that your
application must maintain.
Errata
PtComboBox The default value of Pt_ARG_CBOX_BUTTON_WIDTH is 13, not
17.
PtFlash This widget was discontinued in QNX Neutrino 6.4.0, but its
documentation wasn’t completely removed.

What’s new in Photon for QNX Neutrino 6.4 © 2010, QNX Software Systems GmbH & Co. KG.
What’s new in Photon for QNX Neutrino 6.4

Changes
PtPrintSel
New resources:
• Pt_ARG_PRINT_FILE
PtFileSel
• PtFileSel - contains an updated code sample.
What’s new in Photon for QNX Neutrino 6.3 Service Pack

1
New widgets
• PtImageArea
Changes
PtGenList
Changes to Pt_ARG_LIST_FLAGS:
New flags:
• Pt_LIST_VSCROLLBAR_ALWAYS
• 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
Removed flags:
• Pt_LIST_NOBLIT
966 Appendix: A • What’s New May 13, 2010

© 2010, QNX Software Systems GmbH & Co. KG. What’s new in Photon for QNX Neutrino 6.3
PtBasic
Changed resources:
• Pt_ARG_BASIC_FLAGS — new flag: Pt_BASIC_PREVENT_FILL.
PtWindow
New resources:
• Pt_ARG_WINDOW_FLAGS.

New widgets
• PtMTrend
Changes
PtBasic
Changed resources:
• Pt_CB_GOT_FOCUS
• Pt_CB_LOST_FOCUS
PtContainer
PtContainer can now be instantiated in PhAB, and has a PhAB icon.
New resources:
• Pt_CB_CHILD_GETTING_FOCUS
• Pt_CB_CHILD_LOSING_FOCUS
• Pt_ARG_LAYOUT
• Pt_ARG_LAYOUT_INFO
• Pt_ARG_LAYOUT_TYPE
• Pt_ARG_FILL_LAYOUT_INFO
• Pt_ARG_GRID_LAYOUT_INFO
• Pt_ARG_ROW_LAYOUT_INFO
• Pt_CB_LAYOUT

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:
• Pt_ARG_FONT_LBL_TEXTCOLOR
• Pt_ARG_FONT_LBL_BKGDCOLOR
• Pt_ARG_FONT_POINT_SIZE_MAX
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:
• Pt_ARG_SECONDARY_H_ALIGN
• Pt_ARG_SECONDARY_V_ALIGN
• Pt_ARG_BALLOON_TEXT
PtSeparator
New resources:
• Pt_ARG_SEP_ARM_BITMAP_CURSOR
• Pt_ARG_SEP_ARM_CURSOR_COLOR
• Pt_ARG_SEP_ARM_CURSOR_TYPE
• Pt_ARG_SEP_DRAG_BOUNDS
• Pt_ARG_SEP_FLAGS
• Pt_ARG_SEP_IMAGE

• Pt_ARG_SEP_IMAGE_H_ALIGN
• Pt_ARG_SEP_IMAGE_V_ALIGN
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:
• PtTreeCreateItem()
• PtTreeChangeItem()
• PtTreeItemAttributes_t
PtWebClient
New resources:
• Pt_CB_WEB_DOWNLOAD
• Pt_CB_WEB_SSL_CLIENT_CERT_SELECT
Changed resources:
• Pt_ARG_WEB_ENCODING
• Pt_ARG_WEB_COMMAND
• Pt_ARG_WEB_OPTION
• Pt_ARG_WEB_SERVER
• Pt_CB_WEB_ERROR
• Pt_CB_WEB_SSL_CERTNONTRUSTED
• Pt_CB_WEB_SSL_ERROR
Flags are renamed from WWW_* to Pt_WEB_* in these resources:
• Pt_ARG_WEB_AUTHENTICATE
• Pt_ARG_WEB_COMMAND
• Pt_ARG_WEB_DATA
• Pt_ARG_WEB_GET_URL
• Pt_ARG_WEB_HELPER

What’s new in Photon for QNX Neutrino 6.2.1 © 2010, QNX Software Systems GmbH & Co. KG.
• Pt_ARG_WEB_NAVIGATE_FRAME
• Pt_ARG_WEB_NAVIGATE_LINK
• Pt_ARG_WEB_NAVIGATE_PAGE
• Pt_ARG_WEB_PRINT
• Pt_CB_WEB_AUTHENTICATE
• Pt_CB_WEB_DATA_REQ
• Pt_CB_WEB_ERROR
• Pt_CB_WEB_NEED_SCROLL
• Pt_CB_WEB_SSL_CERTNONTRUSTED
• Pt_CB_WEB_SSL_ERROR
• Pt_CB_WEB_STATUS
• Pt_CB_WEB_UNKNOWN
PtWidget
New resources:
• Pt_ARG_GRID_LAYOUT_DATA
• Pt_ARG_LAYOUT_DATA
• Pt_ARG_ROW_LAYOUT_DATA

Changes
PtGraphics
New resources:
• Pt_ARG_INSIDE_FILL_PATTERN
• Pt_ARG_INSIDE_TRANS_PATTERN
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.

© 2010, QNX Software Systems GmbH & Co. KG. What’s new in Photon for QNX Neutrino 6.2.0
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.

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:
• Pt_ARG_FONT_TEXT_COLOR
• Pt_ARG_FONT_TEXT_BKGD_COLOR
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

What’s new in Photon for QNX Neutrino 6.1.0 © 2010, QNX Software Systems GmbH & Co. KG.
PtTerminal
PtText
PtTty

PtGroup
New resources:
• Pt_ARG_CELL_HORZ_ALIGN
• Pt_ARG_CELL_VERT_ALIGN
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.

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
PtBasic
New resources:
• Pt_ARG_BASIC_FLAGS
• Pt_ARG_BEVEL_COLOR
• Pt_ARG_BEVEL_CONTRAST
• Pt_ARG_CONTRAST

• Pt_ARG_DARK_BEVEL_COLOR
• Pt_ARG_DARK_FILL_COLOR
• Pt_ARG_INLINE_COLOR
• Pt_ARG_LIGHT_BEVEL_COLOR
• Pt_ARG_LIGHT_FILL_COLOR
• Pt_ARG_OUTLINE_COLOR
• Pt_ARG_STYLE
• 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:
• Pt_ARG_ANCHOR_FLAGS

• Pt_ARG_ANCHOR_OFFSETS
• Pt_CB_FILTER
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_ARG_FS_LBL_NAME
• Pt_ARG_FS_LBL_SIZE
• Pt_ARG_FS_LBL_DATE
• Pt_ARG_FS_LBL_PERMISSIONS
• Pt_ARG_FS_LBL_OWNER
• Pt_ARG_FS_LBL_GROUP
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:
• Pt_ARG_TREE_LINE_COLOR
• Pt_ARG_TREE_LINE_SPACING
• Pt_ARG_TREE_MARGIN_COLOR
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
• 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:
• Pt_ARG_PS_LBL_ALL
• Pt_ARG_PS_LBL_COLLATED
• Pt_ARG_PS_LBL_COPIES
• Pt_ARG_PS_LBL_DOUBLE_SIDED
• Pt_ARG_PS_LBL_FILE
• Pt_ARG_PS_LBL_FROM
• Pt_ARG_PS_LBL_NAME
• Pt_ARG_PS_LBL_NOT_COLLATED
• Pt_ARG_PS_LBL_PREFERENCES

• Pt_ARG_PS_LBL_PRINT_ORDER
• Pt_ARG_PS_LBL_PRINT_PAGES
• Pt_ARG_PS_LBL_RANGE
• Pt_ARG_PS_LBL_REVERSED
• Pt_ARG_PS_LBL_SELECTION
• Pt_ARG_PS_LBL_SEND_TO_FILE
• Pt_ARG_PS_LBL_SEND_TO_PRINTER
• Pt_ARG_PS_LBL_TO
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:
• Pt_ARG_MAXIMUM
• Pt_ARG_MINIMUM
• Pt_ARG_ORIENTATION
• 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
• 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
• 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:
• Pt_ARG_TREE_COLUMN_ATTR
• Pt_ARG_TREE_COLUMN_IMGFUN
• Pt_CB_TREE_COLUMN_SEL
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:
• Pt_ARG_TTY_FDS
• Pt_ARG_TTY_RFD
• Pt_ARG_TTY_SFD
• Pt_ARG_TTY_WFD
• 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
• 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.

Glossary
May 13, 2010 Glossary 985

accelerator
See hotkey.
activate
A widget is usually activated when you release a mouse button while pointing at an
armed widget.
active window
The window that currently has focus.
anchor offset
The distance between the edges of a widget and the parent widget it’s anchored to.
anchor
A constraint mechanism used to manage what happens to a widget when its parent is
expanded or contracted. For example, a pane that’s anchored to the sides of a window
expands or contracts as the window’s size is changed.
application region
A region that belongs to a Photon application (as opposed to a Photon system process,
such as the window manager, graphics drivers, etc.). An application region is usually
placed behind the device region. Also called a window region.
argument list
An array of type PtArg_t used when setting and getting widget resources.
arm
A widget is usually armed when you press a mouse button while pointing at it.
backdrop
An image that’s displayed as a background on your screen.
backdrop region
A region placed behind all windows to display a background image.
balloon
A small box that pops up to define or explain part of the user interface. A balloon is
displayed when the pointer pauses over a widget.
bitmap
A color picture consisting of one or more bitplanes.

bitplane
An array of bits representing pixels of a single color in a bitmap.
blit
An operation that moves an area of a graphics context (e.g. the screen) to another area
on the same or a different context.
callback
A callback function or a callback resource.
callback function
Code connecting an application’s user interface to its code. For example, a callback is
invoked when you press a button.
callback resource
A resource that specifies a list of functions and their client data to be called when a
certain action occurs.
canvas
The part of a widget that’s used for drawing. For PtWidget, this is the area inside the
widget’s borders. For PtBasic and its descendants, the canvas is the area inside the
widget’s border and margins. Other widgets, such as PtLabel, may define additional
margins.
class
See widget class.
class hierarchy
The relationships between all of the widget classes.
client data
Any arbitrary data the application may need to provide to a callback function.
clipping list
An array of rectangles used to restrict output to a particular area.
clipping rectangle
A rectangle used to restrict output to a particular area.
CMY value
A color expressed as levels of cyan, magenta, and yellow.
988 Glossary May 13, 2010

CMYK value
A color expressed as levels of cyan, magenta, yellow, and black.
code-type link callback

In a PhAB application, an application function that’s called when a widget’s callback
list is invoked.
color depth
The number of bits per pixel for a screen or pixmap.
Common User Access

See CUA.
compose sequence
A sequence of key presses that can be used to type a character that might not appear
on the keyboard.
console
One of nine virtual screens on the desktop. Also called a workspace.
consume
When a widget has processed an event and prevents another widget from interacting
with the event, the first widget is said to have consumed the event.
container
A widget that can have other widgets as children. For example, PtWindow, PtGroup,
and PtOSContainer.
cooked event
A key or pointer event that has been assigned a location in the Photon event space.
Also called a focused event.
CUA
Common User Access — a standard that defines how you can change focus by using
the keyboard.
current item
The item in a list or tree widget that will be selected (or perhaps unselected) when you
press Enter or Space. It’s typically drawn with a blue dotted line around it when its
widget has focus.

cursor
An indicator of a position on a screen, such as a pointer or an insertion point in a text
field.
damaged
Whenever a widget needs to be redisplayed due to a change in the window (e.g. the
widget is changed, moved, or realized), it’s said to be damaged.
dead key
A key that, when pressed, doesn’t produce a symbol, but initiates a compose
sequence.
default placement
The placement of a region when no siblings are specified. The opposite of specific
placement.
desktop
The virtual screen, consisting of nine consoles or workspaces.
device region
The region located in the middle of the event space, with application regions behind
it and driver regions in front of it (from the user’s point of view).
dialog module
A PhAB module similar to a window module, except that a dialog module can have
only one instance per process.
direct-color
A color scheme in which each pixel is represented by an RGB value. Contrast
palette-based.
disjoint parent
A disjoint widget that’s the ancestor of another widget.
disjoint widget
A widget that can exist without a parent. If a disjoint widget has a parent, it can exist
outside its parent’s canvas. For example, PtWindow, PtMenu, and PtRegion are
disjoint widgets, but PtButton, PtBkgd, and PtRect aren’t.
A disjoint widget owns regions that aren’t children of its parent’s regions. Any
clipping set by the parent of a disjoint widget isn’t applied to the disjoint widget. The
regions of disjoint widgets are sensitive and opaque to expose events.

dithering
A process whereby pixels of two colors are combined to create a texture or a blended
color.
draw context
A structure that defines the flow of the draw stream. The default draw context emits
draw events to graphics drivers. Print contexts and memory contexts are types of
draw contexts.
draw stream
A series of tokens that are dispatched via draw events and can be collected by a
rendering engine such as a graphics driver.
driver region
A region created by a driver, usually placed in front of the device region.
encapsulation driver
A program that displays Photon graphical output inside another windowing system
such as the X Window System.
event
A data structure that represents an interaction between you and an application or
between applications. Events travel through the event space either toward you or away
(i.e. toward the root region).
event compression
The merging of events such that the application sees only their latest values. The
application doesn’t have to process many unnecessary events.
event handler
A callback function that lets an application respond directly to Photon events, such as
dragging events.
event mask
A set of event types that are of interest to an event handler. When one of these events
occurs, the event handler is invoked.
event space
An abstract, three-dimensional space that contains regions — from the root region at
the back to the graphics region at the front. You sit outside the event space, looking in
from the front. Events travel through the event space either toward the root region or
toward you.

exported subordinate child

A widget created by a container widget (as opposed to an application) whose
resources you can access only through the parent.
exposure
Typically occurs when a region is destroyed, resized, or moved. Expose events are
sent to applications to inform them when the contents of their regions need to be
redisplayed.
extent
A rectangle that describes the outermost edges of a widget.
File Manager
The Photon File Manager (PFM), an application used to maintain and organize files
and directories.
focus
A widget that has focus will receive any key events collected by its window.
focus region
A region placed just behind the device region by the Photon Window Manager that
lets it intercept key events and direct them to the active window.
focused event
A key or pointer event that has been assigned a location in the Photon event space.
Also called a cooked event.
folder
In the Photon File Manager, a metaphor for a directory.
GC
See graphics context.
geometry negotiation
The process of determining the layout for a widget and its descendants, which depends
on the widget’s layout policy, any size set for the widget, and the dimensions and
desired positions of each of the widget’s children.
global header file

A header file that’s included in all code generated by PhAB for an application. The
global header file is specified in PhAB’s Application Startup Information dialog.

graphics driver
A program that places a region that’s sensitive to draw events on the user’s side of the
device region, collects draw events, and renders the graphical information on the
screen.
graphics context (GC)

A data structure that defines the characteristics of primitives, including foreground
color, background color, line width, clipping, etc.
Helpviewer
A Photon application for viewing online documentation.
hotkey
A special key or keychord that invokes an action (such as a menu item) without
actually selecting a widget. Also called an accelerator. Contrast keyboard shortcut.
hotspot
The part of the pointer that corresponds to the coordinates reported for the pointer (e.g.
the intersection of crosshairs, or the tip of the arrow of the basic pointer).
HSB
Hue-Saturation-Brightness color model.
HSV
Hue-Saturation-Value color model.
icon module
A PhAB module that associates icons with an application.
image
A rectangular array of color values, where each element represents a single pixel. See
also direct-color and palette-based.
initialization function
In a PhAB application, a function that’s called before any widgets are created.
input driver
A program that emits, and is the source of, key and/or pointer events.
input group
A set of input and output devices. There’s typically one input group per user.

input handler (or input-handling function)

A function that’s hooked into Photon’s main event-processing loop to handle messages
and pulses sent to the application by other processes.
instance
A concrete example of an abstract class; for example, “Lassie” is an instance of the
class “dog.” In Photon, an instance is usually a widget instance; for example, a
pushbutton is an instance of the PtButton widget class. When an instance of a
widget is created, the initial values of its resources are assigned.
instance name
In PhAB, a string that identifies a particular instance of a widget so that you can access
the instance in your application’s code.
instantiation
The action of creating an instance of a widget class in an application.
internal link
A PhAB mechanism that lets a developer access a PhAB module directly from an
application’s code.
Image Viewer
A Photon application (pv) that displays images.
key modifier
A flag in a key event that indicates the state of the corresponding modifier key when
another key was pressed.
keyboard driver
A program that gets information from the keyboard hardware, builds Photon key
events, and emits them towards the root region.
keyboard shortcut
A key that selects a menu item. The shortcut works only if the menu is displayed.
Contrast hotkey.
language database
A file that contains the text strings used in a PhAB application; a language database
makes it easier to create multilingual applications with PhAB’s language editor.
link callback
A mechanism that connects different parts of a PhAB application. For example, a link
callback can be invoked to display a dialog when a button is pressed.

margin
The area between a widget’s border and canvas.
memory context
A draw context in which Photon draw events are directed to memory for future
displaying on the screen, as opposed to a printer (print context) or to the screen
directly (the default draw context).
menu module
A PhAB module used to create a menu.
method
A function that’s internal to a widget class and invoked under specific conditions (e.g.
to draw the widget). Methods are provided as pointers to functions in widget class
records.
modifier key
A key (such as Shift, Alt, or Ctrl) used to change the meaning of another key.
module
An object in PhAB that holds an application’s widgets. PhAB modules include
windows, menus, icons, pictures, and dialogs.
module-type link callback

A link callback that displays a PhAB module.
mouse driver
A program that gets information from the pointer hardware, builds Photon raw pointer
events, and emits them towards the root region.
opaque
The state of a region with regard to events. If a region is opaque to an event type, any
event of that type that intersects with the region has its rectangle set adjusted to clip
out the intersecting area. The region prevents the event from passing through.
palette
An array of colors. A hard palette is in hardware; a soft palette is in software.
palette-based
A color scheme in which each pixel is represented by an index into a palette. Contrast
direct-color.

PDR
See Press-drag-release.
PFM
See Photon File Manager.
PhAB
Photon Application Builder. Visual design tool that generates the code required to
implement a user interface.
phditto
A utility that accesses the Photon workspace on a remote node. See also ditto.
Phindows
Photon in Windows. An application that accesses a Photon session from a Microsoft
Windows environment.
Photon File Manager (PFM)

An application used to maintain and organize files and directories.
Photon Manager or server

The program that maintains the Photon event space by managing regions and events.
Photon Terminal
An application (pterm) that emulates a character-mode terminal in a Photon window.
Photon Window Manager (PWM)

An application that manages the appearance of window frames and other objects on
the screen. For example, the window manager adds the resize bars, title bar, and
various buttons to an application’s window. The window manager also provides a
method of focusing keyboard events.
picture module
A PhAB module that contains an arrangement of widgets that can be displayed in
another widget or used as a widget database.
pixmap
A bitmap or image.
plane mask
A mask used to restrict graphics operations to affect only a subset of color bits.

point source
A single-point rectangle set used as the source of an event.
pointer
An object on the screen that tracks the position of a pointing device (e.g. a mouse,
tablet, track-ball, or joystick). Photon has several pointers indicating various states:
Basic, Busy, Help, Move, Resize, I-beam, No-input.
Press-drag-release (PDR)
A method of selecting a menu item by pressing down a mouse button while pointing to
a menu button, dragging until the desired item is highlighted, and releasing the mouse
button.
print context
A draw context in which Photon draw events are directed to a file, as opposed to the
screen (the default draw context) or to memory (memory context).
printer driver
A program that converts Photon draw stream format into a format suitable for a
printer, including PostScript, Hewlett-Packard PCL, and Canon.
procreated widget
A widget created by another widget (as opposed to an application), such as the
PtList and PtText created by a PtComboBox. Also known as a subordinate child.
pterm
A Photon Terminal; an application that emulates a character-mode terminal in a
Photon window.
pulse
A small message that doesn’t require a reply; used for asynchronous communication
with a Photon application.
pv
See Image Viewer.
PWM
See Photon Window Manager.
raw event
An input event that hasn’t been assigned a location in the Photon event space. Also
called an unfocused event.

raw callback
A function that lets an application respond directly to Photon events such as dragging
events. Also called an event handler.
realize
To display a widget and its descendants, possibly making them interactive.
rectangle set
An array of nonoverlapping rectangles associated with an event.
region
A rectangular area within the Photon event space that’s used by an application for
collecting and emitting events.
resize policy
A rule that governs how a widget resizes itself when its contents change.
resource
An attribute of a widget, such as fill color, dimensions, or a callback list.
root region
The region at the very back of the Photon event space.
sensitive
The state of a region with regard to events. If a region is sensitive to a particular type
of event, the region’s owner collects a copy of any such event that intersects with the
region.
setup function
A function that’s called after a PhAB module is created.
shelf
An application that attaches areas to the outside edge of the screen. You can add
plugins to customize these areas, such as a taskbar, launcher, clock, and magnifier.
Snapshot
A Photon application for capturing images of the screen.
specific placement
The placement of a region when one or more siblings are specified. The opposite of
default placement.

subordinate child
A widget created by another widget (as opposed to an application), such as the
PtList and PtText created by a PtComboBox. Also known as a procreated widget.
table-of-contents (TOC) file

In the Photon Helpviewer, a file that describes a hierarchy of help topics.
taskbar
A shelf plugin that displays icons representing the applications that are currently
running.
tile
A data structure used to build linked lists of rectangles, such as a list of the damaged
parts of an interface.
topic path
Help information identified by a string of titles that are separated by slashes.
topic root
A topic path that’s used as a starting point for locating help topics.
topic tree
A hierarchy of help information.
translation file
A file containing translated strings for a PhAB application. There’s one translation file
per language supported by the application.
unfocused event
See raw event.
Unicode
The ISO/IEC 10646 16-bit encoding scheme for representing the characters used in
most languages.
UTF-8
The encoding for Unicode characters, where each character is represented by one,
two, or three bytes.
widget
A component (e.g. a pushbutton) in a graphical user interface.

widget class
A template for widgets that perform similar functions and provide the same public
interface. For example, PtButton is a widget class.
widget database
In PhAB, a module containing widgets that can be copied at any time into a window,
dialog, or other container.
widget family
A hierarchy of widget instances. For example, a window and the widgets it contains.
widget instance
See instance.
window frame region

A region that PWM adds to a window. It lets you move, resize, iconify, and close the
window.
Window Manager
See Photon Window Manager.
window module
A PhAB module that’s instantiated as a PtWindow widget.
window region
A region that belongs to an application window.
work procedure
A function that’s invoked when there are no Photon events pending for an application.
workspace
See console.
workspace menu
A configurable menu that’s displayed when you press or click the right mouse button
while pointing at the background of the desktop.

Index
A callback 144
customizing 358
accelerators 357 disabling 138
menu items 396 fill color 357
activation popping up immediately 920
any mouse button 925 position 356, 357
defined 34 PtBalloonCallback_t 5
Pt_CB_ACTIVATE 45, 739 text 358
anchor flags 920, 921 text color 357
anchor offsets 920, 921 bandwidth, graphics threshold 37
arc widget See PtArc bar graph widget See PtBarGraph
area 917, 922 basic widget See PtBasic
arming bevel
defined 34 color
Pt_CB_ARM 46 main 40
arrow keys full 38
disabling rendering 38
PtGroup 338 width 38, 922
PtScrollArea 608 bevel color 41, 43
enabling bevels
PtContainer 139 static 40
PtMeter 427, 428 bitmap widget
PtText 712 label See PtLabel
PtTextSetSelection() 733 blocking 925
autohighlighting 925 hotkeys 937
Pt_CB_BLOCKED 933
border
color
B inline 43
outline 44
Bézier curve widget See PtBezier
roundness 42
background
browse mode 240
color 42
browser
pattern 42, 327
see PtWebClient 845
widget See PtBkgd
button widget
balloons
May 13, 2010 Index 1001

Index © 2010, QNX Software Systems GmbH & Co. KG.
menu See PtMenuButton circle widget See PtEllipse

on/off See PtOnOffButton class hierarchy 15
pushbutton See PtButton clipped highlighting rectangle 925
toggle See PtToggleButton clock widget See PtClock
up/down See PtUpDown color
background 42
bevel 41, 43
main 40
C border
inline 43
calendar widget See PtCalendar outline 44
callbacks fill 41–43
activate 45, 739 font selector
arguments 6 text 221
arm 46 text background 221
balloon 144 foreground 41
blocked 933 models 106
child added/removed 145 color selectors See PtColorPanel, See
destroyed 934, 938 PtColorPatch, See
disarm 47 PtColorSelGroup, See PtColorSel,
drag and drop 934 See PtColorWell
filter 936 color-gradient widget See PtBkgd
getting focus 146 column widget See PtGroup
got focus 47, 711 combobox widget See PtComboBox
hotkey 937 compound widget See also PtCompound
invoking when resources are set 925 procreated child 926
losing focus 146 container widget
lost focus 48, 711 flags 138, 143
menu 34, 49 general purpose See PtContainer
outbound 938 offscreen-context See PtOSContainer
PtBalloonCallback_t 5 contrast 41
PtCallback_t 6 contrast, bevel 40
PtCallbackInfo_t 8 conventions
PtHotkeyCallback_t 9 typographical xvii
PtRawCallback_t 11 creating a drawing 323
raw 939 Ctrl-click selection 241
realized 940 CUA (Common User Access)
repeat 34, 49 enabling 139
resizing 148 enabling arrow keys 139
return value 6 preventing focusing 138
right mouse button 34, 49 cursor
unrealized 940 bitmap 922
canvas color 922
determining type 923
PtScrollArea 615
child added/removed callback 145
chord 23
1002 Index May 13, 2010

© 2010, QNX Software Systems GmbH & Co. KG. Index
D blocking 925, 933

consuming 924, 939
damage filter callbacks 936
family 925 PtRawCallback_t 11
parent 924 hotkeys
widget 925 callback 937
dashed lines 325, 326 PtHotkeyCallback_t 9
data, user-defined 739, 918, 930, 933 terminating searches for 139
PtRaw 569 key
destruction consuming 237
marking for 925 processing as hotkeys first 139
Pt_CB_DESTROYED 934 pending
Pt_CB_IS_DESTROYED 938 PtFileSel 180
device emulator widget See PtTty Ph_EV_BUT_REPEAT 49
dimensions 917, 922, 923, 929, 933 raw callbacks 939
maximum 917, 930 PtRawCallback_t 11
minimum 917, 930 repeat callback 49
dimming 45, 327, 926 window manager 944, 948, 952
disarming extended flags 924
defined 34 extended-selection mode 241
Pt_CB_DISARM 47 extent 917, 924, See also resizing
disjoint widget See PtDisjoint no intersections with 925
divider widget See PtDivider recalculating automatically 138
drag and drop
Pt_CB_DND 934
Pt_CB_OUTBOUND 938
dragging F
Pt_CB_OUTBOUND 938
drawing FD_CLOEXEC 829, 830
color 41 file folder widget See PtTab
flicker-free See PtOSContainer file selector widget See PtFileSel
using graphical widgets 321, 323 fill
using primitive graphics functions 568 color 42
flat 39
gradient 39
pattern 42, 327
E reverse gradient 39
fill color 41, 43
edges filter callback 936
alpha line 38 filter callbacks 11
bevel 38 flags
inline 38, 43 anchor 920, 921
outline 38, 44 container 138, 143
edit masks 713 extended 924
ellipse widget See PtEllipse generic list 237
elliptical arc widget See PtArc generic list column 235
events generic tree 284, 305
May 13, 2010 Index 1003

graphic 326 G
group 337
alignment in cells 337 gauge widget See PtGauge
menu 405 generic list widget See PtGenList
PtColorPanel 97 generic tree widget See PtGenTree
PtColorPatch 101 ghosting 45, 327, 926
PtColorSelGroup 111 gradient
PtColorWell 116 fill 39
PtRawList 578 static 40
region 600 graphics
resize 931 bandwidth threshold 37
widget 925 vector 322
flicker-free drawing See PtOSContainer graphics primitives functions 568
floating-point number widget See graphics primitives widget
PtNumericFloat arc See PtArc
flux 926 Bézier curve See PtBezier
focus circle, ellipse See PtEllipse
getting 925 flags 326
granting 926 line See PtLine
Pt_CB_CHILD_GETTING_FOCUS 146 pixels See PtPixel
Pt_CB_CHILD_LOSING_FOCUS 146 polygon See PtPolygon
Pt_CB_GOT_FOCUS 47, 711 rectangle See PtRect
Pt_CB_LOST_FOCUS 48, 711 superclass See PtGraphic
Pt_GEN_LIST_NO_AUTOFOCUS 578 grid widget See PtGrid
rendering 926 group widget See PtGroup
font selector widget See PtFontSel
force front 947, 951
foreground color 41
FORM-CHECKBOX 911 H
FORM-COMBO 911
height 917, 922, 923, 929
FORM-CURSOR-BOTTOM 911
maximum 917, 930
FORM-CURSOR-LEFT 911
minimum 917, 930
FORM-CURSOR-RIGHT 911
help
FORM-CURSOR-TOP 911
button 949
FORM-EDIT 911
in a balloon 924
FORM-LIST 911
information 929
FORM-MULTILIST 911
root 947
FORM-PASS 911
topic path 929
FORM-RADIO 911
highlighting
FORM-RESET 911
automatically 925
FORM-SUBMIT 911
clipping corners 925
FORM-TEXTAREA 911
requesting 926
FRAMESET-DOC 911
HOST_NOT_FOUND 859
hotkeys
accelerator key 357
blocking 937
1004 Index May 13, 2010

callback 937 list widget

menu items 396 superclass See PtGenList
PtHotkeyCallback_t 9 text items See PtList
terminating searches for 139 with text-entry field See PtComboBox
hyperlinks 453 list, raw See PtRawList
I M
image widget margins
background See PtBkgd height 44
label See PtLabel width 44
images matrix widget See PtGroup
viewing See PtImageArea MAX_URL_LENGTH 858
increment/decrement button widget See memory context 514
PtUpDown memory, freeing
insert mode 704 when destroying a widget 938
integer widget See PtNumericInteger menu
enabling mouse button 926
item, indicating 926
Pt_CB_MENU 34, 49
J menu bar widget See PtMenuBar
menu button widget See PtMenuButton
Jump Gate 954 menu widget See PtMenu
meter widget See PtMeter
methods
List Draw
K PtList 259
key events Tree Item State
consuming 237 tree widgets 296, 298
processing as hotkeys first 139 mouse
left button actions 34
click count 46
Pt_CB_ACTIVATE 45, 739
L Pt_CB_ARM 46
Pt_CB_DISARM 47
label widget See PtLabel making actions the same for all buttons 34,
layouts 925
PtWidget 924 right button action 34, 926
line widget See PtLine Pt_CB_MENU 34, 49
lines, dashed 325, 326 multiline text widget See PtMultiText
LINK-IMAGE 911 multiple choice widget See PtComboBox
LINK-IMAGE-MAP 911 multiple-select mode 241
LINK-TEXT 911
List Draw method
PtList 259
May 13, 2010 Index 1005

N Pg_CM_RGB 106
Pg_IMAGE_DIRECT_1555 355
navigation See CUA (Common User Access) Pg_IMAGE_DIRECT_664 355
NO_DATA 859 Pg_IMAGE_DIRECT_888 355
NO_RECOVERY 859 Pg_IMAGE_DIRECT_8888 355
numeric widget Pg_IMAGE_PALETTE_BYTE 355
floating-point See PtNumericFloat Pg_IMAGE_PALETTE_NIBBLE 355
integer See PtNumericInteger Pg_MITER_JOIN 327
range of values See PtSlider Pg_POLY_RELATIVE 546
superclass See PtNumeric Pg_QROUND_JOIN 328
Pg_RELATIVE 53
Pg_ROUND_CAP 327
Pg_ROUND_JOIN 328
O Pg_SQUARE_CAP 327
PgColor_t 472, 474
obscuring 926
Ph_AUXPTR_REGION 601
offscreen-context container widget See
Ph_BAUD_SLOW 620
PtOSContainer
Ph_CONSUMED 939
on/off button widget See PtOnOffButton
Ph_CURSOR_BITMAP 922, 923
opacity 926
Ph_CURSOR_INHERIT 923
Ph_CURSOR_NO_INHERIT 923
Ph_CURSOR_SET 601
P Ph_EV_BOUNDARY 144, 145
Ph_EV_DND_CANCEL 935
PAGE-BOTTOM 911 Ph_EV_DND_COMPLETE 935
PAGE-LEFT 911 Ph_EV_DND_DROP 935
PAGE-RIGHT 911 Ph_EV_DND_ENTER 934
PAGE-TOP 911 Ph_EV_DND_LEAVE 935
pane widget See PtPane Ph_EV_DND_MOTION 935
panels See PtPanelGroup Ph_EV_PTR_MOTION_NOBUTTON 144
passwords, entering into a PtText 709 Ph_EV_PTR_STEADY 144
pathname delimiter in QNX Ph_FOLLOW_IG_SIZE 601
documentation xviii Ph_FORCE_BOUNDARY 145, 601
pattern Ph_FORCE_FRONT 601
background 42, 327 Ph_GRAFX_REGION 601
fill 42, 327 Ph_INPUTGROUP_REGION 601
transparency 45, 327 Ph_KBD_REGION 601
Pg_BEVEL_JOIN 327 Ph_NO_COMPRESSION 601
Pg_BITMAP_BACKFILL 355 Ph_PRINT_REGION 601
Pg_BITMAP_TRANSPARENT 355 Ph_PTR_REGION 601
Pg_BUTT_CAP 327 Ph_WINDOW_REGION 600
Pg_BUTT_JOIN 327 Ph_WM_APP_DEF_MANAGED 948
Pg_CLOSED 52, 546 Ph_WM_BACKDROP 947
Pg_CM_CMYK 106 Ph_WM_CLOSE 947
Pg_CM_HLS 106 Ph_WM_COLLAPSE 947
Pg_CM_HSB 106 Ph_WM_CONSWITCH 947
1006 Index May 13, 2010

Ph_WM_FFRONT 947, 949 Pt_CB_DISARM 47

Ph_WM_FOCUS 947 making actions the same for all buttons 34,
Ph_WM_HELP 947 925
Ph_WM_HIDE 947 right button action 34, 926
Ph_WM_MAX 947 Pt_CB_MENU 34, 49
Ph_WM_MENU 947 points widget See PtPixel
Ph_WM_MOVE 947 polygon widget See PtPolygon
Ph_WM_NO_FOCUS_LIST 947, 949 position 917, 922, 931
Ph_WM_RENDER_ASAPP 942, 949 PpPrintContext_t 551
Ph_WM_RENDER_ASDIALOG 942, 949 primitive graphics functions 568
Ph_WM_RENDER_ASICON 942, 949 print selector widget See PtPrintSel
Ph_WM_RENDER_ASPALETTE 942, 949 procreated child 926
Ph_WM_RENDER_BORDER 949 progress widget See PtProgress
Ph_WM_RENDER_CLOSE 949 Pt_ALL 39
Ph_WM_RENDER_COLLAPSE 949 Pt_ALL_BEVELS 39
Ph_WM_RENDER_HELP 949 Pt_ALL_BOTTOM 39
Ph_WM_RENDER_INLINE 950 Pt_ALL_BUTTONS 34, 49, 925
Ph_WM_RENDER_MAX 950 Pt_ALL_ETCHED 39
Ph_WM_RENDER_MENU 950 Pt_ALL_ETCHES 39
Ph_WM_RENDER_MIN 950 Pt_ALL_INLINES 39
Ph_WM_RENDER_RESIZE 950 Pt_ALL_LEFT 39
Ph_WM_RENDER_TITLE 950 Pt_ALL_OUTLINES 39
Ph_WM_RESIZE 947 Pt_ALL_RIGHT 39
Ph_WM_RESTORE 947 Pt_ALL_TOP 39
Ph_WM_STATE_ISALTKEY 950 Pt_ARC_CHORD 23
Ph_WM_STATE_ISBACKDROP 950 Pt_ARC_CURVE 23
Ph_WM_STATE_ISBLOCKED 950 Pt_ARC_PIE 23
Ph_WM_STATE_ISCOLLAPSE 951 Pt_ARG_ACCEL_FONT 416
Ph_WM_STATE_ISFOCUS 951 Pt_ARG_ACCEL_KEY
Ph_WM_STATE_ISFRONT 951 PtLabel 357
Ph_WM_STATE_ISHIDDEN 951 PtMenuButton 415
Ph_WM_STATE_ISICONIFIED 951 Pt_ARG_ACCEL_TEXT 416
Ph_WM_STATE_ISMAX 951 Pt_ARG_ANCHOR_FLAGS 920, 921
Ph_WM_TASKBAR 947, 949 Pt_ARG_ANCHOR_OFFSETS 920, 921
Ph_WM_TOBACK 947 Pt_ARG_ARC_END 23
Ph_WM_TOFRONT 947 Pt_ARG_ARC_START 23
Ph_WND_MGR_REGION 600 Pt_ARG_ARC_TYPE 23
PhCursorDef_t 922 Pt_ARG_AREA
pie wedge 23 PtScrollArea 606, 608, 609
pixel widget See PtPixel PtTerminal 663
Pk_Cyrillic_IO 220 PtWidget 917, 921, 922
pointer Pt_ARG_ARM_COLOR 62, 63, 840
left button actions 34 Pt_ARG_ARM_FILL 62, 63
click count 46 Pt_ARG_ARM_IMAGE 63, 64
Pt_CB_ACTIVATE 45, 739 Pt_ARG_BALLOON_COLOR
Pt_CB_ARM 46 PtLabel 357
May 13, 2010 Index 1007

Pt_ARG_BALLOON_FILL_COLOR Pt_ARG_CALENDAR_COLOR3 70
PtLabel 357 Pt_ARG_CALENDAR_COLOR4 70
Pt_ARG_BALLOON_POSITION 353, 356, Pt_ARG_CALENDAR_COLOR5 70
357 Pt_ARG_CALENDAR_DATE 70
Pt_ARG_BALLOON_TEXT 358 Pt_ARG_CALENDAR_FLAGS 71
Pt_ARG_BANDWIDTH_THRESHOLD Pt_ARG_CALENDAR_FONT1 71
PtBasic 37 Pt_ARG_CALENDAR_FONT2 71
PtDivider 163 Pt_ARG_CALENDAR_FONT3 72
PtScrollbar 623 Pt_ARG_CALENDAR_FONT4 72
PtTerminal 667, 688 Pt_ARG_CALENDAR_FONT5 72
Pt_ARG_BARGRAPH_BASE Pt_ARG_CALENDAR_HIGHLIGHT 72
PtBarGraph 28 Pt_ARG_CALENDAR_MONTH_BTN_COLOR 72
Pt_ARG_BARGRAPH_COLOR Pt_ARG_CALENDAR_MONTH_NAMES 73
PtBarGraph 27, 28 Pt_ARG_CALENDAR_SEL_COLOR 73
Pt_ARG_BARGRAPH_DATA Pt_ARG_CALENDAR_TIME_T 74
PtBarGraph 27, 29 Pt_ARG_CALENDAR_WDAY_NAMES 74
Pt_ARG_BARGRAPH_DEPTH Pt_ARG_CALENDAR_YEAR_BTN_COLOR 74
PtBarGraph 29 Pt_ARG_CBOX_BUTTON_WIDTH 122
Pt_ARG_BARGRAPH_FLAGS Pt_ARG_CBOX_FLAGS 121, 122
PtBarGraph 29 Pt_ARG_CBOX_MAX_VISIBLE_COUNT
Pt_ARG_BARGRAPH_GRID_COLOR 123
PtBarGraph 30 Pt_ARG_CBOX_SEL_ITEM 123
Pt_ARG_BARGRAPH_GRID_HORIZ Pt_ARG_CBOX_TEXT_FILL_COLOR 123
PtBarGraph 30 Pt_ARG_CELL_HORZ_ALIGN 337
Pt_ARG_BARGRAPH_GRID_VERT Pt_ARG_CELL_VERT_ALIGN 337
PtBarGraph 30 Pt_ARG_CLIENT_FLAGS
Pt_ARG_BARGRAPH_MAX PtClient 80
PtBarGraph 30 Pt_ARG_CLIENT_NAME 80, 82
Pt_ARG_BARGRAPH_MIN Pt_ARG_CLIENT_REPLY_LEN
PtBarGraph 30 PtClient 80
Pt_ARG_BEVEL_COLOR 40 Pt_ARG_CLIENT_SEND
Pt_ARG_BEVEL_CONTRAST PtClient 81
PtBasic 40 Pt_ARG_CLIENT_SERVER
Pt_ARG_BEVEL_WIDTH PtClient 81
PtBasic 38 Pt_ARG_CLOCK_FACE_COLOR 88
PtMenu 406 Pt_ARG_CLOCK_FACE_OUTLINE_COLOR 88
PtWidget 922 Pt_ARG_CLOCK_FLAGS 89
Pt_ARG_BEZIER_FLAGS 52 Pt_ARG_CLOCK_FONT 89
Pt_ARG_BITMAP_CURSOR 922 Pt_ARG_CLOCK_HOUR 89
Pt_ARG_BKGD_IMAGE 57 Pt_ARG_CLOCK_HOUR_COLOR 90
Pt_ARG_BKGD_SPACING_X 57 Pt_ARG_CLOCK_HOUR_OFFSET 90
Pt_ARG_BKGD_SPACING_Y 58 Pt_ARG_CLOCK_MINUTE 90
Pt_ARG_BKGD_TILE 58 Pt_ARG_CLOCK_MINUTE_COLOR 90
Pt_ARG_BUTTON_TYPE 401, 416 Pt_ARG_CLOCK_MINUTE_OFFSET 90
Pt_ARG_CALENDAR_COLOR1 69 Pt_ARG_CLOCK_SECOND 91
Pt_ARG_CALENDAR_COLOR2 69 Pt_ARG_CLOCK_SECOND_COLOR 91
1008 Index May 13, 2010

Pt_ARG_CLOCK_SECOND_OFFSET 91 Pt_ARG_DATA 923

Pt_ARG_CLOCK_SEP1 91 Pt_ARG_DIM
Pt_ARG_CLOCK_SEP1_COLOR 91 PtArc 22
Pt_ARG_CLOCK_SEP2 91 PtEllipse 164
Pt_ARG_CLOCK_SEP2_COLOR 92 PtMultiText 454
Pt_ARG_CLOCK_TYPE 92 PtRect 595
Pt_ARG_COLOR PtTerminal 663, 664, 666
PtBarGraph 27, 28 PtText 716
PtBasic 41 PtWidget 917, 923
PtMultiText 448, 472, 474 Pt_ARG_DIVIDER_FLAGS 157
PtRaw 570 Pt_ARG_DIVIDER_OFFSET 158
PtTrend 811 Pt_ARG_DIVIDER_SIZES 158
Pt_ARG_COLUMNS 716 Pt_ARG_EDIT_MASK 713, 716
Pt_ARG_CONTAINER_FLAGS 138, 143 Pt_ARG_EFLAGS 924, 929
Pt_ARG_CONTRAST Pt_ARG_EXTENT
PtBasic 41 PtWidget 917, 924
Pt_ARG_CPANEL_FLAGS Pt_ARG_FILL_COLOR
PtColorPanel 97 PtBasic 42
Pt_ARG_CPATCH_FLAGS PtMultiText 448, 472, 474
PtColorPatch 101 PtOSContainer 517
Pt_ARG_CS_COLOR PtRaw 570
PtColorSel 105, 106 PtTerminal 688
Pt_ARG_CS_CURRENT_MODEL PtTrend 810
PtColorSel 106 Pt_ARG_FILL_LAYOUT_INFO 141
Pt_ARG_CS_FLAGS Pt_ARG_FILL_PATTERN 42
PtColorSel 106 Pt_ARG_FLAGS 934
Pt_ARG_CS_PALETTE menu items 397
PtColorSel 107 PtBasic 34, 46, 49
Pt_ARG_CSGROUP_FLAGS PtClock 92
PtColorSelGroup 111 PtContainer 145
Pt_ARG_CURSOR_COLOR 922 PtDivider 158
Pt_ARG_CURSOR_OVERRIDE 139 PtFontSel 221
Pt_ARG_CURSOR_POSITION 716 PtGauge 228
Pt_ARG_CURSOR_TYPE 923 PtGenList 243
Pt_ARG_CWELL_FLAGS PtMenu 398
PtColorWell 116 PtMeter 427, 428
Pt_ARG_CWELL_SWATCH_DIM PtMultiText 465
PtColorWell 116 PtOnOffButton 510
Pt_ARG_DARK_BEVEL_COLOR PtPanelGroup 528
PtBasic 41 PtScrollArea 610
Pt_ARG_DARK_FILL_COLOR PtScrollbar 619
PtBasic 41 PtSlider 650
Pt_ARG_DASH_LIST PtText 706, 712, 720–722, 726, 731
PtGraphic 325 PtToggleButton 738
Pt_ARG_DASH_SCALE PtTty 822
PtGraphic 326 PtWidget 925
May 13, 2010 Index 1009

Pt_ARG_FONT_DISPLAY 218 PtGroup 339

Pt_ARG_FONT_FLAGS 219 Pt_ARG_GROUP_ROWS_COLS 339
Pt_ARG_FONT_LBL_BKGDCOLOR 219 Pt_ARG_GROUP_SPACING 339
Pt_ARG_FONT_LBL_FONT 219 Pt_ARG_GROUP_SPACING_X 340
Pt_ARG_FONT_LBL_SIZE 219 Pt_ARG_GROUP_SPACING_Y 340
Pt_ARG_FONT_LBL_STYLE 219 Pt_ARG_GROUP_VERT_ALIGN 340
Pt_ARG_FONT_LBL_TEXTCOLOR 220 Pt_ARG_HEIGHT
Pt_ARG_FONT_NAME 220 PtWidget 917, 929
Pt_ARG_FONT_POINT_SIZE_MAX 220 Pt_ARG_HELP_TOPIC 929
Pt_ARG_FONT_SAMPLE 220 Pt_ARG_HIGHLIGHT_ROUNDNESS 42
Pt_ARG_FONT_SYMBOL 220 Pt_ARG_HORIZONTAL_ALIGNMENT 353,
Pt_ARG_FONT_TEXT_BKGD_COLOR 221 358
Pt_ARG_FONT_TEXT_COLOR 221 Pt_ARG_IMAGEAREA_FLAGS
Pt_ARG_FS_FILE_SPEC 175 PtImageArea 345
Pt_ARG_FS_FLAGS 169, 175 Pt_ARG_IMAGEAREA_GRID_COLOR
Pt_ARG_FS_FORMAT 176 PtImageArea 345
Pt_ARG_FS_IMAGES 177 Pt_ARG_IMAGEAREA_GRID_THRESHOLD
Pt_ARG_FS_LBL_DATE 178 PtImageArea 345
Pt_ARG_FS_LBL_GROUP 179 Pt_ARG_IMAGEAREA_IMAGE
Pt_ARG_FS_LBL_NAME 179 PtImageArea 345
Pt_ARG_FS_LBL_OWNER 179 Pt_ARG_IMAGEAREA_LEFT
Pt_ARG_FS_LBL_PERMISSIONS 179 PtImageArea 346
Pt_ARG_FS_LBL_SIZE 179 Pt_ARG_IMAGEAREA_SELECTION
Pt_ARG_FS_REFRESH 179 PtImageArea 346
Pt_ARG_FS_ROOT_DIR 180 Pt_ARG_IMAGEAREA_TOP
Pt_ARG_GAUGE_FLAGS PtImageArea 346
PtGauge 226 Pt_ARG_IMAGEAREA_ZOOM
PtProgress 559 PtImageArea 346
PtSlider 650 Pt_ARG_INCREMENT 618
Pt_ARG_GAUGE_FONT 227 Pt_ARG_INDICATOR_COLOR 740
Pt_ARG_GAUGE_H_ALIGN 227 Pt_ARG_INDICATOR_TYPE 740
Pt_ARG_GAUGE_V_ALIGN 227 Pt_ARG_INLINE_COLOR 43
Pt_ARG_GAUGE_VALUE 227 Pt_ARG_INSIDE_COLOR
Pt_ARG_GAUGE_VALUE_PREFIX 227 PtGraphic 326
Pt_ARG_GAUGE_VALUE_SUFFIX 228 Pt_ARG_INSIDE_FILL_PATTERN 327
Pt_ARG_GRAPHIC_FLAGS 326 Pt_ARG_INSIDE_TRANS_PATTERN 327
Pt_ARG_GRID_HORIZONTAL 332 Pt_ARG_ITEMS 373, 374
Pt_ARG_GRID_LAYOUT_DATA 927 Pt_ARG_LABEL_BALLOON 358
PtWidget 917 Pt_ARG_LABEL_FLAGS 356, 359
Pt_ARG_GRID_LAYOUT_INFO 142 Pt_ARG_LABEL_IMAGE 354, 360
Pt_ARG_GRID_VERTICAL 332 Pt_ARG_LABEL_TYPE
Pt_ARG_GROUP_FLAGS 337 PtButton 63
toggle buttons 739 PtLabel 352, 360
Pt_ARG_GROUP_HORZ_ALIGN 338 Pt_ARG_LAYOUT 139
Pt_ARG_GROUP_ORIENTATION Pt_ARG_LAYOUT_DATA 930
PtDivider 163 PtWidget 917
1010 Index May 13, 2010

Pt_ARG_LAYOUT_INFO 140 PtLabel 353, 361

Pt_ARG_LAYOUT_TYPE 140 PtPanelGroup 524, 525
Pt_ARG_LIGHT_BEVEL_COLOR Pt_ARG_MARGIN_WIDTH
PtBasic 43 PtBasic 44
Pt_ARG_LIGHT_FILL_COLOR PtTerminal 663, 664, 675
PtBasic 43 Pt_ARG_MAX_HEIGHT 945
Pt_ARG_LINE_CAP Pt_ARG_MAX_LENGTH 717
PtGraphic 327 Pt_ARG_MAX_WIDTH 945
Pt_ARG_LINE_JOIN Pt_ARG_MAXIMUM 228
PtGraphic 327 Pt_ARG_MAXIMUM_DIM
Pt_ARG_LINE_SPACING PtWidget 917, 930
PtLabel 353, 360 Pt_ARG_MENU_FLAGS 397, 398, 401, 405
PtMultiText 448 Pt_ARG_MENU_INPUT_GROUP 406
Pt_ARG_LINE_WIDTH Pt_ARG_MENU_ITEM_FILL_COLOR 406
PtGraphic 328 Pt_ARG_MENU_ITEM_HIGHLIGHT_COLOR
Pt_ARG_LIST_BALLOON 374 406
Pt_ARG_LIST_COLUMN_ATTR Pt_ARG_MENU_SPACING 406
PtGenList 235 Pt_ARG_MENU_TEXT_FONT 398, 406
PtTree 756 Pt_ARG_MENU_TITLE 398, 407
Pt_ARG_LIST_COLUMN_POS Pt_ARG_MENU_TITLE_FONT 398, 407
PtGenList 236 Pt_ARG_METER_COLOR 426
PtList 372 Pt_ARG_METER_FLAGS 427
PtTree 756 Pt_ARG_METER_FONT_COLOR 427
Pt_ARG_LIST_DNDSEL_COLOR 236 Pt_ARG_METER_INCREMENT 427
Pt_ARG_LIST_FLAGS Pt_ARG_METER_KEY_LEFT 421, 427
PtGenList 233, 237 Pt_ARG_METER_KEY_RIGHT 421, 428
Pt_ARG_LIST_FONT 238 Pt_ARG_METER_LEVEL1_COLOR 428
Pt_ARG_LIST_ITEM_COUNT 238 Pt_ARG_METER_LEVEL1_POS 428
Pt_ARG_LIST_SB_RES 233, 239 Pt_ARG_METER_LEVEL2_COLOR 428
Pt_ARG_LIST_SCROLL_RATE 239 Pt_ARG_METER_LEVEL2_POS 428
Pt_ARG_LIST_SEL_COUNT 240 Pt_ARG_METER_LEVEL3_COLOR 429
Pt_ARG_LIST_SPACING 375 Pt_ARG_METER_MAX_NEEDLE_POSITION 429
Pt_ARG_LIST_TOTAL_HEIGHT 240 Pt_ARG_METER_MIN_NEEDLE_POSITION 429
Pt_ARG_MARGIN_BOTTOM Pt_ARG_METER_NEEDLE_COLOR 429
PtLabel 353, 361 Pt_ARG_METER_NEEDLE_POSITION 421,
PtPanelGroup 524, 525 429, 430
Pt_ARG_MARGIN_HEIGHT Pt_ARG_METER_NUM_SEVERITY_LEVELS
PtBasic 44 429
PtTerminal 663, 664, 675 Pt_ARG_METER_TEXT_FONT 430
Pt_ARG_MARGIN_LEFT Pt_ARG_MIN_HEIGHT 946
PtLabel 353, 361 Pt_ARG_MIN_SLIDER_SIZE 618
PtPanelGroup 524, 525 Pt_ARG_MIN_WIDTH 946
Pt_ARG_MARGIN_RIGHT Pt_ARG_MINIMUM 228
PtLabel 353, 361 Pt_ARG_MINIMUM_DIM
PtPanelGroup 524, 525 PtWidget 917, 930
Pt_ARG_MARGIN_TOP Pt_ARG_MODIFIER_KEYS 416
May 13, 2010 Index 1011

Pt_ARG_MODIFY_ITEMS 375 Pt_ARG_NUMERIC_PREFIX 492

Pt_ARG_MOVED 430 Pt_ARG_NUMERIC_SPACING 492
Pt_ARG_MTREND_ADVANCE_BY_N_SAMPLES 442 Pt_ARG_NUMERIC_SUFFIX 492
Pt_ARG_MTREND_ATTRIBUTES 437 Pt_ARG_NUMERIC_UPDOWN_WIDTH 492
Pt_ARG_MTREND_GRAPH_ATTR 438 Pt_ARG_NUMERIC_VALUE
Pt_ARG_MTREND_GRAPH_DATA 440 PtNumericFloat 498
Pt_ARG_MTREND_GRAPH_STATE 439 PtNumericInteger 504
Pt_ARG_MTREND_GRID_COLOR 441 Pt_ARG_ONOFF_STATE 509
Pt_ARG_MTREND_GRID_DRAW_F 442 Pt_ARG_ORIENTATION 840
Pt_ARG_MTREND_GRID_X 441 PtGauge 228
Pt_ARG_MTREND_GRID_Y 441 PtToolbar 745
Pt_ARG_MTREND_N_GRAPHS 438 PtToolbarGroup 749
Pt_ARG_MTREND_N_SAMPLES 438 Pt_ARG_ORIGIN 322, 323, 328
Pt_ARG_MTREND_TRACE_DRAW_F 441 PtArc 22
Pt_ARG_MTREND_TRACE_WIDTH 440 PtBezier 52
Pt_ARG_MULTITEXT_BOTTOM_LINE 456 PtEllipse 164
Pt_ARG_MULTITEXT_FLAGS 456 PtLine 367
Pt_ARG_MULTITEXT_NUM_LINES 457 PtPolygon 545
Pt_ARG_MULTITEXT_NUM_LINES_VISIBLE Pt_ARG_OUTLINE_COLOR 44
457 Pt_ARG_PAGE_INCREMENT 618
Pt_ARG_MULTITEXT_QUERY_CHARACTER Pt_ARG_PG_CURRENT
457 PtPanelGroup 526
Pt_ARG_MULTITEXT_QUERY_LINE 454, Pt_ARG_PG_CURRENT_INDEX
457 PtPanelGroup 526
Pt_ARG_MULTITEXT_RANGE_ATTRIBUTES Pt_ARG_PG_FLAGS
449, 451, 458 PtPanelGroup 526
Pt_ARG_MULTITEXT_ROWS 458 Pt_ARG_PG_OVERLAP_THRESHOLD
Pt_ARG_MULTITEXT_SEGMENTS 448, 449, PtPanelGroup 527
459 Pt_ARG_PG_PANEL_TITLES
Pt_ARG_MULTITEXT_TABS 459 PtPanelGroup 527
Pt_ARG_MULTITEXT_TOP_LINE 459 Pt_ARG_PG_SELECTION_MODE
Pt_ARG_MULTITEXT_WRAP_FLAGS 448, PtPanelGroup 528
460 Pt_ARG_POINTER
Pt_ARG_MULTITEXT_X_SCROLL_POS 460 PtRaw 569
Pt_ARG_MULTITEXT_Y_SCROLL_POS 460 PtWidget 918, 930
Pt_ARG_NUMERIC_FLAGS 491 Pt_ARG_POINTS
Pt_ARG_NUMERIC_INCREMENT PtArc 22
PtNumericFloat 497 PtBezier 52
PtNumericInteger 504 PtEllipse 164
Pt_ARG_NUMERIC_MAX PtGraphic 322, 328
PtNumericFloat 497 PtLine 367
PtNumericInteger 504 PtPixel 542
Pt_ARG_NUMERIC_MIN PtPolygon 545
PtNumericFloat 497 PtRect 595
PtNumericInteger 504 Pt_ARG_POLYGON_FLAGS 545, 546
Pt_ARG_NUMERIC_PRECISION 498 Pt_ARG_POS
1012 Index May 13, 2010

PtRect 595 PtRawTree 586

PtWidget 918, 931 Pt_ARG_RAWTREE_INFLATE_F
Pt_ARG_PRINT_CONTEXT 549, 551 PtRawTree 587
Pt_ARG_PRINT_FILE 551 Pt_ARG_RAWTREE_SELECT_F
Pt_ARG_PRINT_FLAGS 551 PtRawTree 588
Pt_ARG_PROGRESS_BAR_COLOR 560 Pt_ARG_RAWTREE_STATE_F
Pt_ARG_PROGRESS_DIVISIONS 560 PtRawTree 588
Pt_ARG_PROGRESS_GAP 560 Pt_ARG_RECT_ROUNDNESS 595, 595
Pt_ARG_PROGRESS_SPACING 560 Pt_ARG_REGION_FIELDS 600
Pt_ARG_PS_LBL_ALL 552 Pt_ARG_REGION_FLAGS 600
Pt_ARG_PS_LBL_COLLATED 552 Pt_ARG_REGION_INFRONT 601
Pt_ARG_PS_LBL_COPIES 553 Pt_ARG_REGION_INPUT_GROUP 601
Pt_ARG_PS_LBL_DOUBLE_SIDED 553 Pt_ARG_REGION_OPAQUE 601
Pt_ARG_PS_LBL_FILE 553 Pt_ARG_REGION_PARENT 602
Pt_ARG_PS_LBL_FROM 553 Pt_ARG_REGION_RECTANGLES 602
Pt_ARG_PS_LBL_NAME 553 Pt_ARG_REGION_SENSE 602
Pt_ARG_PS_LBL_NOT_COLLATED 553 Pt_ARG_RESIZE_FLAGS
Pt_ARG_PS_LBL_PREFERENCES 554 PtWidget 931
Pt_ARG_PS_LBL_PRINT_ORDER 554 Pt_ARG_ROW_LAYOUT_DATA 932
Pt_ARG_PS_LBL_PRINT_PAGES 554 PtWidget 918
Pt_ARG_PS_LBL_RANGE 554 Pt_ARG_ROW_LAYOUT_INFO 141
Pt_ARG_PS_LBL_REVERSED 554 Pt_ARG_SCROLLAREA_FLAGS 608
Pt_ARG_PS_LBL_SELECTION 554 Pt_ARG_SCROLLAREA_INCREMENT_X 608
Pt_ARG_PS_LBL_SEND_TO_FILE 555 Pt_ARG_SCROLLAREA_INCREMENT_Y 608
Pt_ARG_PS_LBL_SEND_TO_PRINTER 555 Pt_ARG_SCROLLAREA_MAX_X 606, 608
Pt_ARG_PS_LBL_TO 555 Pt_ARG_SCROLLAREA_MAX_Y 606, 609
Pt_ARG_RAW_CALC_OPAQUE_F 571 Pt_ARG_SCROLLAREA_POS_X 609
Pt_ARG_RAW_CONNECT_F 571 Pt_ARG_SCROLLAREA_POS_Y 609
Pt_ARG_RAW_DRAW_F 569, 572 Pt_ARG_SCROLLAREA_SCROLLBAR_COLOR
Pt_ARG_RAW_EXTENT_F 572 PtScrollArea 609
Pt_ARG_RAW_INIT_F 572 Pt_ARG_SCROLLBAR_FLAGS 618
Pt_ARG_RAWLIST_BACKGROUND_F Pt_ARG_SCROLLBAR_WIDTH 240
PtRawList 576 Pt_ARG_SCROLLBAR_X_DISPLAY
Pt_ARG_RAWLIST_DRAW_F PtMultiText 448, 460
PtRawList 577 PtScrollArea 606, 609
Pt_ARG_RAWLIST_GFLAGS Pt_ARG_SCROLLBAR_X_HEIGHT
PtRawList 578 PtMultiText 461
Pt_ARG_RAWLIST_INFLATE_F PtScrollArea 610
PtRawList 578 Pt_ARG_SCROLLBAR_Y_DISPLAY
Pt_ARG_RAWLIST_KEY_F PtMultiText 448, 461
PtRawList 579 PtScrollArea 606, 610
Pt_ARG_RAWLIST_MOUSE_F Pt_ARG_SCROLLBAR_Y_WIDTH
PtRawList 580 PtMultiText 461
Pt_ARG_RAWLIST_SELECT_F PtScrollArea 610
PtRawList 581 Pt_ARG_SCROLLCONT_FLAGS
Pt_ARG_RAWTREE_DRAW_F PtScrollContainer 625
May 13, 2010 Index 1013

Pt_ARG_SCROLLCONT_RESIZE_FLAGS Pt_ARG_TERM_COLOR_TABLE 666, 671

PtScrollContainer 625 Pt_ARG_TERM_COLS 663, 672, 683, 684
Pt_ARG_SECONDARY_H_ALIGN 353, 361 Pt_ARG_TERM_CONSOLE 666, 672
Pt_ARG_SECONDARY_V_ALIGN 353, 362 Pt_ARG_TERM_CUR_COL 672
Pt_ARG_SELECTION_FILL_COLOR 240 Pt_ARG_TERM_CUR_POS 672
Pt_ARG_SELECTION_INDEXES 375 Pt_ARG_TERM_CUR_ROW 673
Pt_ARG_SELECTION_MODE Pt_ARG_TERM_CURSOR_FLAGS 673
PtGenList 240 Pt_ARG_TERM_DRAW_MODES 667, 673
PtTree 762, 764, 765 Pt_ARG_TERM_FONT 661, 663, 674
Pt_ARG_SELECTION_RANGE 717 Pt_ARG_TERM_FONT_INDEX 661, 663,
Pt_ARG_SELECTION_TEXT_COLOR 243 674
Pt_ARG_SEP_ARM_BITMAP_CURSOR 631 Pt_ARG_TERM_FONT_LIST 661, 674
Pt_ARG_SEP_ARM_CURSOR_COLOR 632 Pt_ARG_TERM_FONT_SIZE 675
Pt_ARG_SEP_ARM_CURSOR_TYPE 632 Pt_ARG_TERM_MARGINS 663, 664, 666,
Pt_ARG_SEP_DRAG_BOUNDS 632 675
Pt_ARG_SEP_FLAGS 633 Pt_ARG_TERM_MAXCOLS 665, 675
Pt_ARG_SEP_IMAGE 633 Pt_ARG_TERM_MAXROWS 665, 675
Pt_ARG_SEP_IMAGE_H_ALIGN 633 Pt_ARG_TERM_MAXSIZE 665, 675, 683
Pt_ARG_SEP_IMAGE_V_ALIGN 634 Pt_ARG_TERM_MINCOLS 665, 676
Pt_ARG_SEP_TYPE 634 Pt_ARG_TERM_MINROWS 665, 676
Pt_ARG_SERVER_CONNECTION Pt_ARG_TERM_MINSIZE 665, 676, 683
PtServer 639 Pt_ARG_TERM_OPTIONS 676
Pt_ARG_SERVER_NAME Pt_ARG_TERM_OPTMASK 676
PtServer 639 Pt_ARG_TERM_RESIZE_FL 677
Pt_ARG_SERVER_SEND Pt_ARG_TERM_RESIZE_FUN 663, 677
PtServer 639 Pt_ARG_TERM_RESIZE_STR 663, 665, 677
Pt_ARG_SLIDER_FLAGS 648 Pt_ARG_TERM_ROWS 663, 678, 683, 684
Pt_ARG_SLIDER_HANDLE_COLOR 648 Pt_ARG_TERM_SCRLBK_COUNT 678
Pt_ARG_SLIDER_HANDLE_WIDTH 648 Pt_ARG_TERM_SCRLBK_LIMIT 678
Pt_ARG_SLIDER_IMAGE 649 Pt_ARG_TERM_SCRLBK_POS 678
Pt_ARG_SLIDER_INCREMENT 649 Pt_ARG_TERM_SCROLL 667, 678
Pt_ARG_SLIDER_MULTIPLE 649 Pt_ARG_TERM_SELECTION 678
Pt_ARG_SLIDER_SIZE 618, 619 Pt_ARG_TERM_SIZE 663, 664, 679, 683, 684
Pt_ARG_SLIDER_TICK_MAJOR_DIV 649 Pt_ARG_TERM_VISUAL_BELL 679
Pt_ARG_SLIDER_TROUGH_IMAGE1 649 Pt_ARG_TEXT_CURSOR_WIDTH 718
Pt_ARG_SLIDER_TROUGH_IMAGE2 649 Pt_ARG_TEXT_FLAGS 465, 712, 718, 726
Pt_ARG_STYLE 44 Pt_ARG_TEXT_FONT
Pt_ARG_SUBMENU_PARENT_HIGHLIGHT_COLOR 407 PtLabel 353, 362
Pt_ARG_SYSINFO PtMultiText 448, 472, 474
PtDisjoint 152 Pt_ARG_TEXT_HIGHLIGHT_BACKGROUND_COLOR 719
Pt_ARG_TAB_FLAGS 655 Pt_ARG_TEXT_HIGHLIGHT_TEXT_COLOR
Pt_ARG_TAB_UNSELECTED_COLOR 655 719
Pt_ARG_TERM_ANSI_PROTOCOL 669 Pt_ARG_TEXT_IMAGE_SPACING
Pt_ARG_TERM_APP 669 PtLabel 362
Pt_ARG_TERM_CHARSETS 662, 670 Pt_ARG_TEXT_STRING
Pt_ARG_TERM_COLOR_MODE 671 PtLabel 353, 356, 362
1014 Index May 13, 2010

PtMultiText 448, 459 Pt_ARG_TREND_PALETTE_END 815

PtText 705 Pt_ARG_TTY_ARGV 826
Pt_ARG_TEXT_SUBSTRING Pt_ARG_TTY_BUFFER 826
PtMultiText 448 Pt_ARG_TTY_BUFLEN 826
PtText 719 Pt_ARG_TTY_CMD 826, 826
Pt_ARG_TG_FLAGS Pt_ARG_TTY_DEVSIZE 827
PtToolbarGroup 750 Pt_ARG_TTY_EXIT_STATUS 827, 833
Pt_ARG_TIMER_INITIAL 735 Pt_ARG_TTY_FDS 827
Pt_ARG_TIMER_REPEAT 736 Pt_ARG_TTY_FDSET 828
Pt_ARG_TITLE Pt_ARG_TTY_FLAGS 828
PtContainer 139, 143 Pt_ARG_TTY_INPUT 829
Pt_ARG_TITLE_FONT Pt_ARG_TTY_INPUT_WRITTEN 829
PtContainer 143 Pt_ARG_TTY_PATH 829
Pt_ARG_TOOLBAR_FLAGS Pt_ARG_TTY_PID 827, 829
PtToolbar 745 Pt_ARG_TTY_PRI 829
Pt_ARG_TOOLBAR_LAYOUT_FLAGS Pt_ARG_TTY_PSEUDO 830
PtToolbar 745 Pt_ARG_TTY_RFD 830
Pt_ARG_TOOLBAR_SPACING Pt_ARG_TTY_SFD 830
PtToolbar 746 Pt_ARG_TTY_SPAWN_OPTIONS 831
Pt_ARG_TOP_ITEM_POS 243, 266 Pt_ARG_TTY_WFD 831
Pt_ARG_TRANS_PATTERN 45 Pt_ARG_UNDERLINE_TYPE 363
Pt_ARG_TREE_BALLOON 759 Pt_ARG_UNDERLINE1 362
Pt_ARG_TREE_COLUMN_ATTR 757, 760 Pt_ARG_UNDERLINE2 363
Pt_ARG_TREE_COLUMN_IMGFUN 757, Pt_ARG_UPDOWN_ARM_DATA_DECREMENT
760 840
Pt_ARG_TREE_FLAGS Pt_ARG_UPDOWN_ARM_DATA_INCREMENT
PtGenTree 284, 305 841
PtRawTree 592 Pt_ARG_UPDOWN_BORDER_WIDTH 841
PtTree 769 Pt_ARG_UPDOWN_DATA_DECREMENT
Pt_ARG_TREE_IMAGES 755, 761 841
Pt_ARG_TREE_IMGMASK 755, 761 Pt_ARG_UPDOWN_DATA_INCREMENT
Pt_ARG_TREE_LINE_COLOR 285 841
Pt_ARG_TREE_LINE_SPACING 285 Pt_ARG_UPDOWN_FLAGS 841
Pt_ARG_TREE_MARGIN_COLOR 285 Pt_ARG_UPDOWN_INDICATOR_MARGIN
Pt_ARG_TREND_ATTRIBUTES 810, 811 842
Pt_ARG_TREND_COLOR_LIST 810, 811, Pt_ARG_USER_DATA
815 PtRaw 569
Pt_ARG_TREND_COUNT 812 PtToggleButton 739
Pt_ARG_TREND_DATA 812 PtWidget 918, 933
Pt_ARG_TREND_FLAGS 812 Pt_ARG_VERTICAL_ALIGNMENT 353, 363
Pt_ARG_TREND_GRID_COLOR 814 Pt_ARG_VISIBLE_COUNT
Pt_ARG_TREND_GRID_X 814 PtComboBox 129
Pt_ARG_TREND_GRID_Y 814 PtGenList 243
Pt_ARG_TREND_INC 814 PtList 372, 380
Pt_ARG_TREND_MAX 815 Pt_ARG_WEB_ACTIVATE_LINK 849
Pt_ARG_TREND_MIN 815 Pt_ARG_WEB_AUTHENTICATE 849
May 13, 2010 Index 1015

Pt_ARG_WEB_BUILD_DATE 850 Pt_BALLOON_INPLACE 357

Pt_ARG_WEB_COMMAND 850 Pt_BALLOON_LEFT 357
Pt_ARG_WEB_DATA 852 Pt_BALLOON_RIGHT 357
Pt_ARG_WEB_DOWNLOAD 854 Pt_BALLOON_TOP 357
Pt_ARG_WEB_ENCODING 854 Pt_BALLOONCOLOR 357
Pt_ARG_WEB_GET_CERTIFICATES 855 Pt_BALLOONS_ON 920
Pt_ARG_WEB_GET_CONTEXT 855 Pt_BARGRAPH_GRID 29
Pt_ARG_WEB_GET_HISTORY 856 Pt_BARGRAPH_HORIZONTAL 29
Pt_ARG_WEB_GET_URL 846, 857 Pt_BARGRAPH_VERTICAL 29
Pt_ARG_WEB_H_ERRNO 859 Pt_BASIC_PREVENT_FILL 40
Pt_ARG_WEB_HELPER 858 Pt_BITMAP_BALLOON_BOTTOM 358
Pt_ARG_WEB_IMPORT_CERTIFICATE 859 Pt_BITMAP_BALLOON_INPLACE 359
Pt_ARG_WEB_NAVIGATE_FRAME 860 Pt_BITMAP_BALLOON_LEFT 359
Pt_ARG_WEB_NAVIGATE_LINK 861 Pt_BITMAP_BALLOON_RIGHT 359
Pt_ARG_WEB_NAVIGATE_PAGE 862 Pt_BITMAP_BALLOON_TOP 359
Pt_ARG_WEB_OPTION 863 Pt_BKGD_CENTER 58
Pt_ARG_WEB_PRINT 887 Pt_BKGD_CENTER_GRID 58
Pt_ARG_WEB_RELOAD 887 Pt_BKGD_GRID 58
Pt_ARG_WEB_SERVER 845, 887 Pt_BKGD_NONE 58
Pt_ARG_WEB_SERVER_PID 889 Pt_BLANK_ETCHES 38
Pt_ARG_WEB_SSL_RESPONSE 889 Pt_BLOCK_CUA_FOCUS 138
Pt_ARG_WEB_STARTUP_ERRNO 846, 889 Pt_BLOCKED 925, 926
Pt_ARG_WEB_STOP 889 Pt_BOTTOM_ANCHORED_BOTTOM 920
Pt_ARG_WEB_UNKNOWN_RESP 890 Pt_BOTTOM_ANCHORED_TOP 920
Pt_ARG_WEB_VERSION 890 Pt_BOTTOM_BEVEL 38
Pt_ARG_WIDTH Pt_BOTTOM_ETCH 38
PtWidget 918, 933 Pt_BOTTOM_INLINE 38, 43
Pt_ARG_WINDOW_ACTIVE_COLOR 946 Pt_BOTTOM_OUTLINE 38, 44
Pt_ARG_WINDOW_FLAGS 946 Pt_BOTTOM_RIGHT_BEVEL 39
Pt_ARG_WINDOW_FRONT_WINDOW 947 Pt_BOTTOM_RIGHT_ETCH 39
Pt_ARG_WINDOW_HELP_ROOT 947 Pt_BOTTOM_RIGHT_INLINE 39
Pt_ARG_WINDOW_INACTIVE_COLOR 947 Pt_BOTTOM_RIGHT_OUTLINE 39
Pt_ARG_WINDOW_MANAGED_FLAGS 943, Pt_BROWSE_MODE 120, 182, 240
947 Pt_CALENDAR_DATE_SELECTED 75
Pt_ARG_WINDOW_NOTIFY_FLAGS 944, Pt_CALENDAR_MONTH_BTNS 71
948 Pt_CALENDAR_MONTH_SELECTED 75
Pt_ARG_WINDOW_RENDER_FLAGS 942, Pt_CALENDAR_SHOW_GRID 71
949 Pt_CALENDAR_SHOW_NEXT 71
Pt_ARG_WINDOW_STATE 950 Pt_CALENDAR_SHOW_PREV 71
Pt_ARG_WINDOW_TITLE 951 Pt_CALENDAR_WDAY_SELECTED 75
Pt_ARG_WINDOW_TITLE_COLOR 952 Pt_CALENDAR_YEAR_BTNS 71
Pt_AUTO_EXTENT 138 Pt_CALENDAR_YEAR_SELECTED 75
Pt_AUTOHIGHLIGHT 398, 925 Pt_CALLBACKS_ACTIVE 498, 925
Pt_BACKFILL_TEXT 359 Pt_CB_CHILD_ADDED_REMOVED
Pt_BALLOON_AS_REQUIRED 359 145
Pt_BALLOON_BOTTOM 357 Pt_CB_CLOCK_TIME_CHANGED 92
1016 Index May 13, 2010

Pt_CB_DIVIDER_DRAG 158 Pt_CB_CLOCK_TIME_CHANGED 92

Pt_CB_FONT_MODIFY 221 Pt_CB_CS_COLOR_CHANGED
Pt_CB_GAUGE_VALUE_CHANGED PtColorSel 107
228 Pt_CB_DESTROYED 934
Pt_CB_MODIFY_NOTIFY 706, 720, 731 Pt_CB_DISARM
Pt_CB_MODIFY_VERIFY 721, 731 PtBasic 34, 47
Pt_CB_MOTION_NOTIFY 722 PtUpDown 844
Pt_CB_MOTION_VERIFY 722 Pt_CB_DIVIDER_DRAG 158
Pt_CB_ONOFF_NEW_VALUE 510 Pt_CB_DIVIDER_HANDLE_CALLBACK
Pt_CB_PG_PANEL_SWITCHING 528 159
Pt_CB_SCROLL_MOVE 243, 619 Pt_CB_DND
Pt_CB_SCROLLAREA_SCROLLED 610 PtFileSel 186
Pt_CB_SLIDER_MOVE 650 PtGenList 247
Pt_CB_TEXT_CHANGED 706, 720, 731 PtGenTree 289
PtTextModifyText() 731 PtList 381
Pt_CB_ACTIVATE PtRawList 585
hotkeys 937 PtRawTree 593
PtBasic 34, 45, 46 PtTree 769
PtGroup 739 PtWidget 934
PtMultiText 465 Pt_CB_FILTER 936
PtNumericFloat 502 Pt_CB_FONT_MODIFY 221
PtNumericInteger 508 Pt_CB_FS_BKGD_HANDLER 180
PtText 712, 726 Pt_CB_FS_SELECTION 181
PtToggleButton 738 Pt_CB_FS_STATE 182
PtUpDown 844 Pt_CB_GAUGE_VALUE_CHANGED
Pt_CB_ARM PtGauge 228
PtBasic 34, 46 PtProgress 559
PtMenuButton 399 Pt_CB_GEN_TREE_INPUT 285
PtUpDown 844 Pt_CB_GOT_FOCUS
Pt_CB_BALLOONS 144 PtBasic 47
Pt_CB_BLOCKED 933 PtMultiText 466
Pt_CB_CALENDAR_SELECT 75 PtText 711, 727
Pt_CB_CBOX_ACTIVATE 124 Pt_CB_HOTKEY 937
Pt_CB_CBOX_CLOSE 124 Pt_CB_IMAGEAREA_DRAG
Pt_CB_CHILD_ADDED_REMOVED 145 PtImageArea 346
Pt_CB_CHILD_GETTING_FOCUS Pt_CB_IMAGEAREA_MOVEMENT
PtContainer 146 PtImageArea 347
Pt_CB_CHILD_LOSING_FOCUS Pt_CB_IMAGEAREA_SCROLLED
PtContainer 146 PtImageArea 347
Pt_CB_CLIENT_CONNECTED Pt_CB_IMAGEAREA_SELECTION
PtClient 81 PtImageArea 348
Pt_CB_CLIENT_ERROR 81 Pt_CB_IS_DESTROYED 938
Pt_CB_CLIENT_EVENT Pt_CB_LAYOUT 147
PtClient 82 Pt_CB_LIST_INPUT 375
Pt_CB_CLIENT_NOT_FOUND Pt_CB_LOST_FOCUS
PtClient 83 PtBasic 48
May 13, 2010 Index 1017

PtMultiText 466 Pt_CB_SYSINFO

PtText 711, 727 PtDisjoint 152
Pt_CB_MENU Pt_CB_TERM_APP 680
enabling 926 Pt_CB_TERM_FONT 681
PtBasic 34, 49 Pt_CB_TERM_INPUT 681, 700, 701
PtMenuButton 399 Pt_CB_TERM_OPTIONS 682
Pt_CB_METER_MOVED 430 Pt_CB_TERM_RESIZE 683
Pt_CB_MODIFY_NOTIFY Pt_CB_TERM_RESIZED 684
PtMultiText 467 Pt_CB_TERM_SCRLBK 685
PtText 707, 711, 720, 731 Pt_CB_TEXT_CHANGED
Pt_CB_MODIFY_VERIFY PtMultiText 467
PtMultiText 468 PtText 707, 711, 720, 731
PtText 707, 721, 731 Pt_CB_TIMER_ACTIVATE 736
Pt_CB_MOTION_NOTIFY Pt_CB_TREE_COLUMN_SEL
PtMultiText 467 PtTree 758, 762
PtText 722 Pt_CB_TREE_SELECTION 764
Pt_CB_MOTION_VERIFY Pt_CB_TREE_STATE 765, 782, 785
PtMultiText 469 Pt_CB_TTY_DEVSIZE 831
PtText 712, 722 Pt_CB_TTY_OUTPUT 832
Pt_CB_NUMERIC_CHANGED Pt_CB_TTY_TERMINATED 833
PtNumericFloat 498 Pt_CB_UNREALIZED 940
PtNumericInteger 504 Pt_CB_WEB_AUTHENTICATE 891
Pt_CB_ONOFF_NEW_VALUE 510 Pt_CB_WEB_CLOSE_WINDOW 892
Pt_CB_OUTBOUND 938 Pt_CB_WEB_COMPLETE 892
Pt_CB_PG_PANEL_SWITCHING Pt_CB_WEB_CONTEXT 893
PtPanelGroup 528 Pt_CB_WEB_DATA_REQ 893
Pt_CB_PRINT_PROPS 555 Pt_CB_WEB_DOWNLOAD 894
Pt_CB_RAW 939 Pt_CB_WEB_ERROR 895
Pt_CB_REALIZED 940 Pt_CB_WEB_IMPORT_CERTIFICATE 898
Pt_CB_REPEAT 34, 49 Pt_CB_WEB_METADATA 899
Pt_CB_RESCALE 328 example 899
Pt_CB_RESIZE 148 Pt_CB_WEB_NEED_SCROLL 900
Pt_CB_SCROLL_MOVE Pt_CB_WEB_NEW_WINDOW 901
PtGenList 243 Pt_CB_WEB_PAGE_INFO 902
PtScrollbar 619 Pt_CB_WEB_SSL_CERTINFO 902
Pt_CB_SCROLLAREA_SCROLLED 606, 610 Pt_CB_WEB_SSL_CERTNONTRUSTED 904
Pt_CB_SELECTION 373, 376 Pt_CB_WEB_SSL_CLIENT_CERT_SELECT 907
Pt_CB_SEP_DRAG 634 Pt_CB_WEB_SSL_ERROR 908
Pt_CB_SERVER_CONNECTED Pt_CB_WEB_START 909
PtServer 640 Pt_CB_WEB_STATUS 910
Pt_CB_SERVER_ERROR 640 Pt_CB_WEB_UNKNOWN 912
Pt_CB_SERVER_RECEIVE Pt_CB_WEB_URL 913
PtServer 641 Pt_CB_WINDOW 952
Pt_CB_SERVER_TRANSPORT Pt_CB_WINDOW_CLOSING 952
PtServer 641 Pt_CB_WINDOW_OPENING 953
Pt_CB_SLIDER_MOVE 650 Pt_CB_WINDOW_TRANSPORT 954
1018 Index May 13, 2010

Pt_CHANGE_ACTIVATE 465, 712, 718, 726 Pt_DEFAULT_COLOR 472, 474

Pt_CHILD_ADDED 145 Pt_DEFAULT_FONT 472, 474
Pt_CHILD_REMOVED 145 Pt_DELAY_REALIZE 925
Pt_CLEAR 925 Pt_DESTROYED 145, 925
Pt_CLIENT_NOEVENTS 80 Pt_DISABLE_BALLOONS 138
Pt_CLIENT_NONBLOCK 80 Pt_DIVIDER_CASCADE 157
Pt_CLIP_HIGHLIGHT 925 Pt_DIVIDER_INVISIBLE 157
Pt_CLOCK_24_HOUR 89 Pt_DIVIDER_LAST_IS_SPACER 158
Pt_CLOCK_ANALOG 92 Pt_DIVIDER_NODRAG 158
Pt_CLOCK_DIGITAL 92 Pt_DIVIDER_NORESIZE 157
Pt_CLOCK_HOUR_CHANGED 92 Pt_DIVIDER_RESIZE_BOTH 157
Pt_CLOCK_LED 92 Pt_DOUBLE_DASH_LINE 634
Pt_CLOCK_MINUTE_CHANGED 93 Pt_DOUBLE_LINE 634
Pt_CLOCK_PAD_HOURS 89 Pt_DOUBLE_ULINE 363
Pt_CLOCK_SECOND_CHANGED 93 Pt_EDIT_ACTIVATE 465, 726
Pt_CLOCK_SHOW_AMPM 89 Pt_EDITABLE 718
Pt_CLOCK_SHOW_NUMBERS 89 Pt_ELLIPSIS_MIDDLE 359
Pt_CLOCK_SHOW_SECONDS 89 Pt_EMT_AUTOINDENT 456
Pt_CLOCK_TRACK_TIME 89 Pt_EMT_CHAR 460
Pt_COMBOBOX_ALT_DOWN 121, 122 Pt_EMT_FORCED_SCROLL 456
Pt_COMBOBOX_MAX_WIDTH 123 Pt_EMT_FULL_LINES 456
Pt_COMBOBOX_OPEN 123 Pt_EMT_NEWLINE 460
Pt_COMBOBOX_STATIC 123 Pt_EMT_SCROLL_TO_CURSOR 456
Pt_COMBOBOX_TOP 123 Pt_EMT_WORD 448, 460
Pt_CONNECTION_CLIENT_BROKEN 82 Pt_ENABLE_CUA 139
Pt_CONNECTION_SERVER_BROKEN 641 Pt_ENABLE_CUA_ARROWS 139
Pt_CONSUME 937 Pt_ETCH_TITLE_AREA 139
Pt_CONSUME_EVENTS 924 Pt_ETCHED_IN 634
Pt_CONTINUE 6 Pt_ETCHED_OUT 634
Pt_CPANEL_SHOW_DROPPER 97 Pt_EXTENDED_MODE 182, 241
Pt_CPANEL_SHOW_FIELDS 97 Pt_FLAT_FILL 39
Pt_CPANEL_SHOW_WELL 97 Pt_FLOAT_ORIGIN 326
Pt_CPATCH_ENABLE_MENU 101 Pt_FLOAT_POS 326
Pt_CPATCH_SHOW_SELECTOR 101 Pt_FOCUS_RENDER 926
Pt_CPATCH_SHOW_SLIDER 101 Pt_FONTSEL_AA_CHECK 219
Pt_CS_COLOR_CHANGE_COMPLETE 107 Pt_FONTSEL_ALL_FONTS 218
Pt_CS_COLOR_CHANGED 107 Pt_FONTSEL_ALL_SYMBOLS 220
Pt_CS_FAST_UPDATE 107 Pt_FONTSEL_BITMAP 218
Pt_CS_QUANTIZE_COLOR 107 Pt_FONTSEL_COLORSEL_BKGD 219
Pt_CSGROUP_ALL_AT_ONCE 111 Pt_FONTSEL_COLORSEL_TEXT 219
Pt_CURSOR_VISIBLE 718 Pt_FONTSEL_FIXED 218
Pt_CWELL_POPUP_ON_MENU 116 Pt_FONTSEL_PROP 218
Pt_CWELL_POPUP_ON_SELECT 116 Pt_FONTSEL_SAMPLE 219
Pt_DAMAGE_FAMILY 925 Pt_FONTSEL_SCALABLE 218
Pt_DAMAGE_PARENT 924 Pt_FS_CASE_INSENSITIVE 176
Pt_DAMAGED 925 Pt_FS_DIR_CL 169, 177
May 13, 2010 Index 1019

Pt_FS_DIR_OP 169, 177 Pt_GRADIENT_TITLE_AREA 139

Pt_FS_DLINK_CL 169, 177 Pt_GRID 812
Pt_FS_DLINK_OP 169, 177 Pt_GRID_ABOVE_TRENDS 812
Pt_FS_ERROR 169, 178 Pt_GRID_FORCE 813
Pt_FS_ERROR_POPUP 176 Pt_GRID_IS_TRANSLUCENT 813
Pt_FS_FILE 169, 178 Pt_GROUP_ASIS 339
Pt_FS_FLINK 169, 178 Pt_GROUP_EQUAL_SIZE 337
Pt_FS_FREE_ON_COLLAPSE 176 Pt_GROUP_EQUAL_SIZE_HORIZONTAL 338
Pt_FS_NEW_DIR 169 Pt_GROUP_EQUAL_SIZE_VERTICAL 338
Pt_FS_NEW_ITEM 180 Pt_GROUP_EXCLUSIVE 337, 739
Pt_FS_NO_ROOT_DISPLAY 176 Pt_GROUP_HORIZONTAL 339
Pt_FS_OLD_DIR 169 Pt_GROUP_HORZ_CENTER 337, 339
Pt_FS_OLD_ITEM 180 Pt_GROUP_HORZ_LEFT 337, 338
Pt_FS_SEEK_KEY 170, 176 Pt_GROUP_HORZ_RIGHT 337, 339
Pt_FS_SHOW_DIRS 176 Pt_GROUP_NO_KEY_WRAP 338
Pt_FS_SHOW_ERRORS 176 Pt_GROUP_NO_KEY_WRAP_HORIZONTAL
Pt_FS_SHOW_FILES 176 338
Pt_FS_SHOW_HIDDEN 176 Pt_GROUP_NO_KEY_WRAP_VERTICAL 338
Pt_FS_SINGLE_LEVEL 169, 176, 183 Pt_GROUP_NO_KEYS 338
Pt_FS_STATE_END 183 Pt_GROUP_NO_SELECT_ALLOWED 337
Pt_FS_STATE_START 183 Pt_GROUP_STRETCH_FILL 338
Pt_FULL_BEVELS 38 Pt_GROUP_STRETCH_HORIZONTAL 338
Pt_GAUGE_DECREMENT 229 Pt_GROUP_STRETCH_VERTICAL 338
Pt_GAUGE_DRAGGED 229 Pt_GROUP_VERT_BOTTOM 337, 340
Pt_GAUGE_INCREMENT 229 Pt_GROUP_VERT_CENTER 337, 340
Pt_GAUGE_INDETERMINATE 226, 559 Pt_GROUP_VERT_TOP 337, 340
Pt_GAUGE_INTERACTIVE 226, 228, 559 Pt_GROUP_VERTICAL 339
Pt_GAUGE_JUMP 229 Pt_HIGHLIGHTED 926
Pt_GAUGE_LIVE 226, 559 Pt_HORIZONTAL_GRADIENT 39
Pt_GAUGE_MAX_ON_LEFT 226, 650 Pt_HOTKEY_IGNORE_MODS 9
Pt_GAUGE_MAX_ON_TOP 226, 650 Pt_HOTKEY_SYM 9
Pt_GAUGE_MULTIPLE_DECREMENT 229 Pt_HOTKEY_TERMINATOR 139
Pt_GAUGE_MULTIPLE_INCREMENT 229 Pt_HOTKEYS_FIRST 139
Pt_GAUGE_RELEASED 229 Pt_IGNORE 937
Pt_GAUGE_SHOW_VALUE 226 Pt_IMAGE 64, 352, 360
Pt_GAUGE_TO_MAX 229 Pt_IMAGEAREA_AUTOSCALE 345
Pt_GAUGE_TO_MIN 229 Pt_IMAGEAREA_COMPLETE 346, 348
Pt_GAUGE_VALUE_XOR 226 Pt_IMAGEAREA_DRAG 346, 348
Pt_GEN_LIST_FULL_WIDTH 578 Pt_IMAGEAREA_EDITABLE_SELECTION 345
Pt_GEN_LIST_ITEM_BACKGROUND 578 Pt_IMAGEAREA_ENABLE_SELECTION 345
Pt_GEN_LIST_NO_AUTOFOCUS 578 Pt_IMAGEAREA_INIT 346, 348
Pt_GEN_LIST_NO_BACKGROUND 578 Pt_IN_FLUX 926
Pt_GEN_LIST_NO_CLIPPING 578 Pt_INFLATE_BALLOON 5, 144, 358
Pt_GEN_LIST_SHOW_DAMAGED 257, 578 Pt_INHERIT_COLOR 472, 474
Pt_GETS_FOCUS 427, 428, 822, 926 Pt_INHERIT_FONT 472, 474
Pt_GHOST 926 Pt_INSERT_MODE 718
1020 Index May 13, 2010

Pt_INTERNAL_HELP 924, 929 Pt_LIST_SCROLLBAR_AS_REQUIRED 238

Pt_KEY_MOVED 430 Pt_LIST_SCROLLBAR_AUTORESIZE 238
Pt_LABEL_SELECT_SHIFT 359 Pt_LIST_SCROLLBAR_GETS_FOCUS 238
Pt_LEFT_ANCHORED_LEFT 920 Pt_LIST_SCROLLBAR_NEVER 238
Pt_LEFT_ANCHORED_RIGHT 920 Pt_LIST_SELECTION_BROWSE 182, 764
Pt_LEFT_BEVEL 38 Pt_LIST_SELECTION_CANCEL 182, 764
Pt_LEFT_ETCH 38 Pt_LIST_SELECTION_FINAL 182, 764
Pt_LEFT_INLINE 38, 43 Pt_LIST_SHOW_BALLOON 238
Pt_LEFT_OUTLINE 38, 44 Pt_LIST_SNAP 238
Pt_LIST_BALLOON_AS_REQUIRED 237, 769 Pt_LIST_STRETCH_HEADER 238
Pt_LIST_BALLOONS_IN_COLUMNS 237, 578 Pt_LIST_VSCROLLBAR_ALWAYS 233, 237
Pt_LIST_BOUNDARY_KEY_EVENTS 237 Pt_LIST_VSCROLLBAR_AS_REQUIRED 233,
Pt_LIST_COLUMN_CENTER 236 237
Pt_LIST_COLUMN_DAMAGE_ALWAYS 236 Pt_LIST_VSCROLLBAR_NEVER 233, 237
Pt_LIST_COLUMN_ELLIPSIS 235 Pt_MENU_AUTO 398, 405
Pt_LIST_COLUMN_ELLIPSIS_INVERT 236 Pt_MENU_BUTTON 926
Pt_LIST_COLUMN_ELLIPSIS_MIDDLE 235 Pt_MENU_CHILD 397, 401, 405
Pt_LIST_COLUMN_LEFT 236 Pt_MENU_DOWN 416
Pt_LIST_COLUMN_NO_STRING 236, 756 Pt_MENU_GRADIENT 405
Pt_LIST_COLUMN_RIGHT 236 Pt_MENU_RIGHT 401, 416
Pt_LIST_HEADER_AUTORESIZE 237 Pt_MENU_TEAR_OFF 405
Pt_LIST_HSCROLLBAR_ALWAYS 233, 237 Pt_MENU_TEXT 416
Pt_LIST_HSCROLLBAR_AS_REQUIRED 233, Pt_MENU_TEXT_ALIGN 405
237 Pt_MENU_TRANSIENT 398, 405
Pt_LIST_HSCROLLBAR_NEVER 233, 237 Pt_MENU_UP 416
Pt_LIST_ITEM_ABOVE 266 Pt_MENUABLE 34, 926
Pt_LIST_ITEM_BELOW 266 Pt_MOUSE_MOVED 430
Pt_LIST_ITEM_CURRENT 250, 266, 267, 762 Pt_MT_BACKGROUND 458, 485, 487
Pt_LIST_ITEM_DAMAGED 265, 266, 272, 763 Pt_MT_BACKGROUND_COLOR 458, 485, 487
Pt_LIST_ITEM_DNDSELECTED_DOWN 187, Pt_MT_FLAGS 458, 485, 487
247, 289, 381, 585, 593, 770 Pt_MT_FONT 458, 485, 487
Pt_LIST_ITEM_DNDSELECTED_IN 187, 247, Pt_MT_FOREGROUND 458, 485, 487
289, 381, 585, 593, 770 Pt_MT_QUERY_CHAR 481
Pt_LIST_ITEM_DNDSELECTED_UP 187, 247, Pt_MT_TAG 453, 458, 485, 487
289, 381, 585, 593, 770 Pt_MT_TEXT_COLOR 458, 485, 487
Pt_LIST_ITEM_FLAG_USER[1234] 763 Pt_MULTIPLE_MODE 182, 241
Pt_LIST_ITEM_FLAG_USER* 266 Pt_NO_DRAG_SELECTION 718
Pt_LIST_ITEM_INWIDGET 266 Pt_NO_ULINE 363
Pt_LIST_ITEM_SELECTED 250, 266, 267, Pt_NOLINE 634
315, 762 Pt_NUMERIC_AUTO_HIGHLIGHT 491
Pt_LIST_ITEM_USED_FLAGS 266 Pt_NUMERIC_CHANGED 498, 505
Pt_LIST_NO_COLUMN_LINES 237 Pt_NUMERIC_ENABLE_UPDOWN 492
Pt_LIST_NON_SELECT 237 Pt_NUMERIC_HEXADECIMAL 492
Pt_LIST_SCROLL_LIST 243 Pt_NUMERIC_SET 498, 505
Pt_LIST_SCROLL_SCROLLBAR 243 Pt_NUMERIC_UPDOWN_ACTIVATE 498, 505
Pt_LIST_SCROLLBAR_ALWAYS 238 Pt_NUMERIC_UPDOWN_REPEAT 498, 505
May 13, 2010 Index 1021

Pt_NUMERIC_USE_SEPARATORS 492 Pt_REVERSE_GRADIENT 39

Pt_NUMERIC_WRAP 492 Pt_RIGHT_ANCHORED_LEFT 920
Pt_OBSCURED 926 Pt_RIGHT_ANCHORED_RIGHT 920
Pt_OPAQUE 926 Pt_RIGHT_BEVEL 38
Pt_OPAQUE_ETCHES 38 Pt_RIGHT_ETCH 38
Pt_PG_AUTO 528 Pt_RIGHT_INLINE 38, 43
Pt_PG_DND 526 Pt_RIGHT_OUTLINE 38, 44
Pt_PG_MULTI_CONTAINER_MODE 526 Pt_SCROLL_DECREMENT 244, 619
Pt_PG_NONE 528 Pt_SCROLL_DRAGGED 244, 620
Pt_PG_SELECTOR_ALIGN_RIGHT 526 Pt_SCROLL_INCREMENT 244, 620
Pt_PG_SELECTOR_ON_BOTTOM 527 Pt_SCROLL_JUMP 244, 620
Pt_PG_SINGLE_TAB 528 Pt_SCROLL_PAGE_DECREMENT 244, 620
Pt_PG_TABS_EQUAL_SIZE 527 Pt_SCROLL_PAGE_INCREMENT 244, 620
Pt_PG_USE_PANEL_COLORS 527 Pt_SCROLL_RELEASED 244, 620
Pt_PIXEL 813 Pt_SCROLL_SET 244, 620
Pt_POP_BALLOON 5, 144 Pt_SCROLL_TO_MAX 244, 620
Pt_PRINTSEL_ALL_PANES 552 Pt_SCROLL_TO_MIN 244, 620
Pt_PRINTSEL_DFLT_LOOK 552 Pt_SCROLLAREA_ENABLE_PAN 608
Pt_PRINTSEL_FILE_PANE 552 Pt_SCROLLAREA_IGNORE_KEYS 608
Pt_PRINTSEL_NO_COPIES 552 Pt_SCROLLBAR_FIXED_SLIDER_SIZE 618
Pt_PRINTSEL_NO_PAGE_RANGE 552 Pt_SCROLLBAR_FOCUSED 619
Pt_PRINTSEL_NO_PRINTSELECT 552 Pt_SCROLLBAR_SHOW_ARROWS 619
Pt_PRINTSEL_NO_SELECT_RANGE 552 Pt_SCROLLCONT_TRACK_FOCUS 625
Pt_PRINTSEL_PREFERENCES 552 Pt_SELECT_NOREDRAW 926
Pt_PRINTSEL_SETTINGS_PANE 552 Pt_SELECTABLE 34, 397, 398, 465, 712, 726,
Pt_PROCESS 937 926, 934
Pt_PROCREATED 145, 926 Pt_SELECTION_MODE_AUTO 242
Pt_PROGRESS_NO_MORE_SEGMENTS Pt_SELECTION_MODE_MULTIPLE 241, 250
564–566 Pt_SELECTION_MODE_NOCLEAR 242
Pt_RANGE_MODE 182, 241, 762, 764 Pt_SELECTION_MODE_NOFOCUS 242
not supported byPtTreeUnselect() 807 Pt_SELECTION_MODE_NOMOVE 241
Pt_REALIZED 926 Pt_SELECTION_MODE_NONE 241, 250
Pt_REALIZING 926 Pt_SELECTION_MODE_NOREST 242
Pt_REGION 926 Pt_SELECTION_MODE_NOSCROLL 241
Pt_RESIZE_X_ALWAYS 626, 931 Pt_SELECTION_MODE_RANGE 241, 250,
Pt_RESIZE_X_AS_REQUIRED 626, 931 273, 275, 279, 319, 581, 588
Pt_RESIZE_X_BITS 626, 931 Pt_SELECTION_MODE_SINGLE 241, 250, 275
Pt_RESIZE_X_INITIAL 626, 931 Pt_SELECTION_MODE_TOGGLE 242
Pt_RESIZE_XY_ALWAYS 626, 931 Pt_SET 738, 927
Pt_RESIZE_XY_AS_REQUIRED 626, 931 Pt_SHOW_BALLOON 356, 359
Pt_RESIZE_XY_BITS 626, 931 Pt_SHOW_TITLE 139, 143
Pt_RESIZE_XY_INITIAL 626, 931 Pt_SINGLE_DASH_LINE 634
Pt_RESIZE_Y_ALWAYS 626, 931 Pt_SINGLE_LINE 634
Pt_RESIZE_Y_AS_REQUIRED 626, 931 Pt_SINGLE_MODE 182, 241
Pt_RESIZE_Y_BITS 626, 931 Pt_SINGLE_ULINE 363
Pt_RESIZE_Y_INITIAL 626, 931 Pt_SKIP_LAYOUT 924
1022 Index May 13, 2010

Pt_SLIDER_DECREMENT 650 Pt_TERM_SELECTION_LAST_KEEP 679

Pt_SLIDER_DRAGGED 651 Pt_TERM_SELECTION_NEVER 679
Pt_SLIDER_IMAGE 648 Pt_TERM_SELECTION_NONE 679
Pt_SLIDER_INCREMENT 650 Pt_TERM_SELECTION_STREAM 679
Pt_SLIDER_JUMP 651 Pt_TERM_SELECTION_TYPE_KEEP 679
Pt_SLIDER_MULTIPLE_DECREMENT 651 Pt_TEXT_AUTO_HIGHLIGHT 718
Pt_SLIDER_MULTIPLE_INCREMENT 650 Pt_TEXT_BLINKING_CURSOR 718
Pt_SLIDER_RELEASED 651 Pt_TEXT_IMAGE 353, 360
Pt_SLIDER_SET 651 Pt_TG_COLLAPSIBLE 750
Pt_SLIDER_TO_MAX 651 Pt_TIMER_INITIAL 736
Pt_SLIDER_TO_MIN 651 Pt_TIMER_REPEAT 736
Pt_SLIDER_TROUGH_IMAGE 648 Pt_TOGGLE 927
Pt_STATIC_BEVELS 40 Pt_CB_ACTIVATE 46
Pt_STATIC_GRADIENT 40 Pt_TOGGLE_CHECK 740
Pt_TAB_DRAG_HANDLE 655 Pt_TOGGLE_OUTLINE 740
Pt_TAB_MULTI 655 Pt_TOGGLE_RADIO 740
Pt_TAB_RIGHTSIDE_LEFT 655 Pt_TOOLBAR_DRAGGABLE 745
Pt_TAB_UPSIDE_DOWN 655 Pt_TOOLBAR_END_SEPARATOR 745
Pt_TERM_ANCHOR_PARENT_HEIGHT 677 Pt_TOOLBAR_FOLLOW_FOCUS 745
Pt_TERM_ANCHOR_PARENT_WIDTH 677 Pt_TOOLBAR_FROM_LINE_START 746
Pt_TERM_ANCHOR_WINDOWS_ONLY 677 Pt_TOOLBAR_ITEM_SEPARATORS 745
Pt_TERM_COLOR_MODE 671 Pt_TOOLBAR_LOCK_ORIENTATION 745
Pt_TERM_CTRLBRK_INPUT 681 Pt_TOOLBAR_REVERSE_LAST_ITEM 745
Pt_TERM_CURSOR_ALWAYS 673 Pt_TOOLBAR_TO_LINE_END 746
Pt_TERM_CURSOR_NEVER 673 Pt_TOP_ANCHORED_BOTTOM 920
Pt_TERM_CURSOR_NOSPEEDCHK 673 Pt_TOP_ANCHORED_TOP 920
Pt_TERM_CURSOR_ON_FOCUS 673 Pt_TOP_BEVEL 38
Pt_TERM_CURSOR_TIMER 673 Pt_TOP_ETCH 38
Pt_TERM_KBFONT 661, 677 Pt_TOP_INLINE 38, 43
Pt_TERM_KBFORCE 661, 677 Pt_TOP_LEFT_BEVEL 39
Pt_TERM_KEYBOARD_INPUT 681 Pt_TOP_LEFT_ETCH 39
Pt_TERM_MOUSE_INPUT 681 Pt_TOP_LEFT_INLINE 39
Pt_TERM_OPFONT 662, 677 Pt_TOP_LEFT_OUTLINE 39
Pt_TERM_PASTE_INPUT 681 Pt_TOP_OUTLINE 38, 44
Pt_TERM_PASTE_NF_INPUT 682 Pt_TREE_BALLOON_ON_IMAGE 592, 769
Pt_TERM_PROTOCOL_INPUT 681 Pt_TREE_BALLOON_ON_TREE 592, 769
Pt_TERM_SCROLL_NOBLIT 673 Pt_TREE_COLLAPSING 182, 589, 765
Pt_TERM_SCROLL_NOHWCHK 673 Pt_TREE_COLUMN_NOCB 760
Pt_TERM_SCROLL_NOSPEEDCHK 667, 674 Pt_TREE_COLUMN_NOCURRENT 760
Pt_TERM_SCROLL_NOVISCHK 673 Pt_TREE_COLUMN_NOSELECT 760
Pt_TERM_SCROLL_RFSH 673 Pt_TREE_EXPANDING 182, 589, 765
Pt_TERM_SELECTING 679 Pt_TREE_HAS_BUTTONS 284, 305
Pt_TERM_SELECTION_ALWAYS 679 Pt_TREE_INDENT_BUTTONS 284
Pt_TERM_SELECTION_BLOCK 679 Pt_TREE_INDENT_LINES 284
Pt_TERM_SELECTION_FIRST_KEEP 679 Pt_TREE_ITEM_EXPANDABLE 191, 293, 305,
Pt_TERM_SELECTION_FLAGS_KEEP 679 311, 762, 774
May 13, 2010 Index 1023

Pt_TREE_ITEM_EXPANDED 305, 589, 756, Pt_WEB_COMMAND_SAVEAS 851

762 Pt_WEB_COMMAND_SET_WIDGET 852
Pt_TREE_ITEM_INWIDGET 306 Pt_WEB_CONTEXT_ANCHOR 855, 893
Pt_TREE_SHOW_CONNECTORS 284 Pt_WEB_CONTEXT_BKGD 855, 893
Pt_TREE_SHOW_LINES 284 Pt_WEB_CONTEXT_OBJECT 855, 893
Pt_TREE_SHOW_MARGIN 284 Pt_WEB_DATA_BODY 852, 894
Pt_TREE_TO_LEFT 284 Pt_WEB_DATA_CLOSE 852, 894
Pt_TREE_TO_RIGHT 284 Pt_WEB_DATA_HEADER 852, 894
Pt_TREND_BOTTOM_TO_TOP 813 Pt_WEB_DIGEST_AUTHENTICATION 850,
Pt_TREND_HORIZONTAL 813 891
Pt_TREND_LEFT_TO_RIGHT 813 Pt_WEB_DIRECTION_BACK 860–862
Pt_TREND_RIGHT_TO_LEFT 813 Pt_WEB_DIRECTION_DOWN 860–862, 900
Pt_TREND_TOP_TO_BOTTOM 813 Pt_WEB_DIRECTION_FIRST 861
Pt_TREND_VERTICAL 813 Pt_WEB_DIRECTION_FWD 860–862
Pt_TRENDS_ABOVE_GRID 813 Pt_WEB_DIRECTION_LAST 861
Pt_TTY_ARGV0 826, 828 Pt_WEB_DIRECTION_LEFT 860–862, 900
Pt_TTY_BUF_PRIVATE 828 Pt_WEB_DIRECTION_RIGHT 860–862, 900
Pt_TTY_DEVFORCE 828 Pt_WEB_DIRECTION_UP 860–862, 900
Pt_TTY_DEVLIMIT 828 Pt_WEB_ERROR_BasicConstraints 909
Pt_TTY_DEVRESIZE 828 Pt_WEB_ERROR_CertChainIncomplete 909
Pt_TTY_SETENV 827, 828 Pt_WEB_ERROR_CertChainInvalid 909
Pt_TTY_TERMRESIZE 828 Pt_WEB_ERROR_CertExpired 909
Pt_ULINE_ETCHED_IN 363 Pt_WEB_ERROR_CertNamesNotEqual 909
Pt_ULINE_ETCHED_OUT 363 Pt_WEB_ERROR_CertNoError 908
Pt_UPDOWN_DECREMENT_ARM_IMAGE Pt_WEB_ERROR_FailedVerify 909
841 Pt_WEB_ERROR_FILE 896
Pt_UPDOWN_DECREMENT_IMAGE 841 Pt_WEB_ERROR_IncorrectKeyUsage 909
Pt_UPDOWN_FILL_ON_ARM 842 Pt_WEB_ERROR_InvalidSignature 909
Pt_UPDOWN_INCREMENT_ARM_IMAGE Pt_WEB_ERROR_RootCertificateNotValid 909
841 Pt_WEB_ERROR_SERVER_EXIT 896
Pt_UPDOWN_INCREMENT_IMAGE 841 Pt_WEB_ERROR_SUBVIEW 896
Pt_UPDOWN_ROTATE_INDICATORS 842 Pt_WEB_ERROR_TOPVIEW 896
Pt_USE_ELLIPSIS 359 Pt_WEB_ERROR_WML 896
Pt_WEB_ACTION_ABORT 891, 913 Pt_WEB_FIND_GO_BACKWARDS 851
Pt_WEB_ACTION_ADD 858 Pt_WEB_FIND_MATCH_CASE 851
Pt_WEB_ACTION_DELETE 858 Pt_WEB_FIND_MATCH_WHOLE_WORDS
Pt_WEB_ACTION_DISPLAY 857 851
Pt_WEB_ACTION_OK 891, 912 Pt_WEB_FIND_START_AT_TOP 851
Pt_WEB_ACTION_SAVEAS 857 Pt_WEB_IMPORT_CERT_AUTHENTICATION
Pt_WEB_BASIC_AUTHENTICATION 850, 891 891
Pt_WEB_COMMAND_FIND 851 Pt_WEB_NO_DISK_CACHE 857
Pt_WEB_COMMAND_LOADMISSING 851 Pt_WEB_NO_MEMORY_CACHE 857
Pt_WEB_COMMAND_LOADMISSING_CONTEXT Pt_WEB_NO_PAGE_HISTORY 857
851 Pt_WEB_NO_SITE_HISTORY 857
Pt_WEB_COMMAND_PURGE_CACHE 851 Pt_WEB_PRINT_ALL_FRAMES 887
Pt_WEB_COMMAND_RESET_OPT 851 Pt_WEB_PRINT_FROM_CACHE 887
1024 Index May 13, 2010

Pt_WEB_PROXY_AUTHENTICATION 850, vertical lines 30

891 maximum value 30
Pt_WEB_RESIZEABLE 901 minimum value 30
Pt_WEB_RESPONSE_CANCEL 850, 889, 890, Pt_ARG_BARGRAPH_BASE 28
906, 909 Pt_ARG_BARGRAPH_COLOR 27, 28
Pt_WEB_RESPONSE_CONTINUE 907 Pt_ARG_BARGRAPH_DATA 27, 29
Pt_WEB_RESPONSE_OK 850, 889, 890, 907, Pt_ARG_BARGRAPH_DEPTH 29
909 Pt_ARG_BARGRAPH_FLAGS 29
Pt_WEB_SHOW_LOCATION 901 Pt_ARG_BARGRAPH_GRID_COLOR
Pt_WEB_SHOW_MENUBAR 901 30
Pt_WEB_SHOW_STATUS 901 Pt_ARG_BARGRAPH_GRID_HORIZ 30
Pt_WEB_SHOW_TOOLBAR 901 Pt_ARG_BARGRAPH_GRID_VERT 30
Pt_WEB_STATUS_CONNECT 910 Pt_ARG_BARGRAPH_MAX 30
Pt_WEB_STATUS_CONTENTS 912 Pt_ARG_BARGRAPH_MIN 30
Pt_WEB_STATUS_DEFAULT 910 Pt_ARG_COLOR 27, 28
Pt_WEB_STATUS_INFO 911 PtBasic 33
Pt_WEB_STATUS_MOUSE 910 behavior 34
Pt_WEB_STATUS_PRINT 911 bevel color 41, 43
Pt_WEB_STATUS_PROGRESS 911 main 40
Pt_WIDGET_REBUILD 927 bevel width 38
Pt_WIDGET_RESIZE 927 border color
Pt_Z_STRING 64, 352, 360 inline 43
PtArc 22 outline 44
control points 22 border roundness 42
end angle 23 callbacks
Pt_ARG_ARC_END 23 activate 45, 46
Pt_ARG_ARC_START 23 arm 46
Pt_ARG_ARC_TYPE 23 disarm 47
Pt_ARG_DIM 22 got focus 47
Pt_ARG_ORIGIN 22 lost focus 48
Pt_ARG_POINTS 22 menu 34, 49
start angle 23 repeat 34, 49
type 23 right mouse button 34, 49
PtBalloonCallback_t 5 contrast 41
PtBarGraph 27 contrast, bevel 40
bars fill color 41–43
vertical 29 fill pattern 42, 327
base 28 foreground color 41
color 27, 28 graphics bandwidth threshold 37
data 27, 29 margins
depth 29 height 44
flags 29 width 44
grid Pt_ARG_BANDWIDTH_THRESHOLD 37
color 30 Pt_ARG_BEVEL_COLOR 40
displaying 29 Pt_ARG_BEVEL_CONTRAST 40
horizontal lines 30 Pt_ARG_BEVEL_WIDTH 38
May 13, 2010 Index 1025

Pt_ARG_COLOR 41 data 63, 64

Pt_ARG_CONTRAST 41 fill 62, 63
Pt_ARG_DARK_BEVEL_COLOR 41 behavior 62
Pt_ARG_DARK_FILL_COLOR 41 creating 62
Pt_ARG_FILL_COLOR 42 label type 63
Pt_ARG_FILL_PATTERN 42 Pt_ARG_ARM_COLOR 62, 63
Pt_ARG_FLAGS 34, 46, 49 Pt_ARG_ARM_FILL 62, 63
Pt_ARG_HIGHLIGHT_ROUNDNESS 42 Pt_ARG_ARM_IMAGE 63, 64
Pt_ARG_INLINE_COLOR 43 Pt_ARG_LABEL_TYPE 63
Pt_ARG_INSIDE_FILL_PATTERN 327 visual feedback 62
Pt_ARG_INSIDE_TRANS_PATTERN PtCalendar 68
327 callbacks
Pt_ARG_LIGHT_BEVEL_COLOR 43 date selection 75
Pt_ARG_LIGHT_FILL_COLOR 43 date
Pt_ARG_MARGIN_HEIGHT 44 current 70, 74
Pt_ARG_MARGIN_WIDTH 44 days
Pt_ARG_OUTLINE_COLOR 44 highlighted 72
Pt_ARG_STYLE 44 highlighted, color 70
Pt_ARG_TRANS_PATTERN 45 highlighted, font 72
Pt_CB_ACTIVATE 34, 45, 46 name, color 70
Pt_CB_ARM 34, 46 name, font 72
Pt_CB_DISARM 34, 47 names 74
Pt_CB_GOT_FOCUS 47 selected, color 73
Pt_CB_LOST_FOCUS 48 flags 71
Pt_CB_MENU 34, 49 grid, displaying 71
enabling 926 month
Pt_CB_REPEAT 34, 49 current, day color 69
selectable 34 current, day font 71
style 44 name, color 70
transparency pattern 45, 327 name, font 72
PtBezier 52 names 73
Pt_ARG_BEZIER_FLAGS 52 next/previous buttons, color 72
Pt_ARG_ORIGIN 52 next/previous buttons, displaying 71
Pt_ARG_POINTS 52 next/previous days, displaying 71
PtBkgd 56 next/previous, day color 69
image 57 next/previous, font 71
Pt_ARG_BKGD_IMAGE 57 Pt_ARG_CALENDAR_COLOR1 69
Pt_ARG_BKGD_SPACING_X 57 Pt_ARG_CALENDAR_COLOR2 69
Pt_ARG_BKGD_SPACING_Y 58 Pt_ARG_CALENDAR_COLOR3 70
Pt_ARG_BKGD_TILE 58 Pt_ARG_CALENDAR_COLOR4 70
tiling Pt_ARG_CALENDAR_COLOR5 70
spacing 57, 58 Pt_ARG_CALENDAR_DATE 70
type 58 Pt_ARG_CALENDAR_FLAGS 71
PtButton 62 Pt_ARG_CALENDAR_FONT1 71
armed Pt_ARG_CALENDAR_FONT2 71
color 62, 63 Pt_ARG_CALENDAR_FONT3 72
1026 Index May 13, 2010

Pt_ARG_CALENDAR_FONT4 72 face
Pt_ARG_CALENDAR_FONT5 72 color 88
Pt_ARG_CALENDAR_HIGHLIGHT 72 numbers, displaying 89
Pt_ARG_CALENDAR_MONTH_BTN_COLOR 72 outline color 88
Pt_ARG_CALENDAR_MONTH_NAMES 73 flags 89
Pt_ARG_CALENDAR_SEL_COLOR 73 flicker, reducing 87
Pt_ARG_CALENDAR_TIME_T 74 font 89
Pt_ARG_CALENDAR_WDAY_NAMES 74 hour
Pt_ARG_CALENDAR_YEAR_BTN_COLOR 74 color 90
Pt_CB_CALENDAR_SELECT 75 current setting 89
year leading zero, adding 89
color 70 offset 90
font 72 LED/LCD 92
next/previous buttons, color 74 minute
next/previous buttons, displaying 71 color 90
PtCalendarSelectCallback_t 75 current setting 90
PtCallback_t 6 offset 90
PtCallbackInfo_t 8 Pt_ARG_CLOCK_FACE_COLOR 88
PtClient 79 Pt_ARG_CLOCK_FACE_OUTLINE_COLOR
callbacks 88
connected 81 Pt_ARG_CLOCK_FLAGS 89
error 81 Pt_ARG_CLOCK_FONT 89
not connected 83 Pt_ARG_CLOCK_HOUR 89
Pt_CB_CLIENT_EVENT 82 Pt_ARG_CLOCK_HOUR_COLOR 90
connection object 81 Pt_ARG_CLOCK_HOUR_OFFSET 90
connector name 80, 82 Pt_ARG_CLOCK_MINUTE 90
flags 80 Pt_ARG_CLOCK_MINUTE_COLOR 90
messages, sending to server 81 Pt_ARG_CLOCK_MINUTE_OFFSET 90
Pt_ARG_CLIENT_FLAGS 80 Pt_ARG_CLOCK_SECOND 91
Pt_ARG_CLIENT_NAME 80, 82 Pt_ARG_CLOCK_SECOND_COLOR 91
Pt_ARG_CLIENT_REPLY_LEN 80 Pt_ARG_CLOCK_SECOND_OFFSET
Pt_ARG_CLIENT_SEND 81 91
Pt_ARG_CLIENT_SERVER 81 Pt_ARG_CLOCK_SEP1 91
Pt_CB_CLIENT_CONNECTED 81 Pt_ARG_CLOCK_SEP1_COLOR 91
Pt_CB_CLIENT_ERROR 81 Pt_ARG_CLOCK_SEP2 91
Pt_CB_CLIENT_EVENT 82 Pt_ARG_CLOCK_SEP2_COLOR 92
Pt_CB_CLIENT_NOT_FOUND 83 Pt_ARG_CLOCK_TYPE 92
reply length 80 Pt_ARG_FLAGS 92
PtClientCallback_t 83 Pt_CB_CLOCK_TIME_CHANGED 92
PtClock 87 second
24-hour display 89 color 91
AM/PM indicator 89 current setting 91
analog 92 displaying 89
callbacks offset 91
time changed 92 separator
digital 92 character 91
May 13, 2010 Index 1027

color 91, 92 determining if open 123

time item, selected 123
updating every second 89 items, maximum visible 123
type 92 items, number visible 129
PtClockTimeCallback_t 93 opening from code 132
PtColorPanel 96 opening via keyboard 121, 122
flags 97 placing above text 123
Pt_ARG_CPANEL_FLAGS 97 static 123
PtColorPatch 100 types 120
flags 101 maximizing width 123
Pt_ARG_CPATCH_FLAGS 101 Pt_ARG_CBOX_BUTTON_WIDTH 122
PtColorSel 105 Pt_ARG_CBOX_FLAGS 121, 122
callbacks Pt_ARG_CBOX_MAX_VISIBLE_COUNT
color changed 107 123
color 105 Pt_ARG_CBOX_SEL_ITEM 123
flags 106 Pt_ARG_CBOX_TEXT_FILL_COLOR
models 106 123
models, current 106 Pt_ARG_VISIBLE_COUNT 129
palette 107 Pt_CB_CBOX_ACTIVATE 124
Pt_ARG_CS_COLOR 105 Pt_CB_CBOX_CLOSE 124
Pt_ARG_CS_COLOR_MODELS 106 text area, fill color 123
Pt_ARG_CS_CURRENT_MODEL 106 PtComboBoxListClose() 131
Pt_ARG_CS_FLAGS 106 PtComboBoxListOpen() 132
Pt_ARG_CS_PALETTE 107 PtCompound 133
Pt_CB_CS_COLOR_CHANGED 107 PtContainer 137
PtColorSelGroup 111 balloons
flags 111 callback 144
Pt_ARG_CSGROUP_FLAGS 111 disabling 138
PtColorWell 115 callbacks
color-swatch dimensions 116 child added/removed 145
flags 116 child getting focus 146
Pt_ARG_CWELL_FLAGS 116 child losing focus 146
Pt_ARG_CWELL_SWATCH_DIM 116 resize 148
PtComboBox 120 CUA
behavior 120 enabling 139
callbacks enabling arrow keys 139
drop button activation 124 preventing focusing 138
list close 124 flags 138, 143
convenience functions 129 hotkeys, terminating searches for 139
drop button key events, processing as hotkeys first 139
suppressing 123 Pt_ARG_CONTAINER_FLAGS 138, 143
width 122 Pt_ARG_FILL_LAYOUT_INFO 141
flags 121, 122 Pt_ARG_FLAGS 145
keyboard actions 121 Pt_ARG_GRID_LAYOUT_INFO 142
list Pt_ARG_LAYOUT 139
closing from code 131 Pt_ARG_LAYOUT_INFO 140
1028 Index May 13, 2010

Pt_ARG_LAYOUT_TYPE 140 resizing

Pt_ARG_ROW_LAYOUT_INFO 141 both children 157
Pt_ARG_TITLE 139, 143 preventing 157
Pt_ARG_TITLE_FONT 143 sizes of realized children 158
Pt_CB_BALLOONS 144 PtDividerCallback_t 159
Pt_CB_CHILD_ADDED_REMOVED PtDividerHandleCallback_t 160
145 PtDndCallbackInfo_t 935
Pt_CB_CHILD_GETTING_FOCUS 146 PtEllipse 164
Pt_CB_CHILD_LOSING_FOCUS 146 height 164
Pt_CB_LAYOUT 147 Pt_ARG_DIM 164
Pt_CB_RESIZE 148 Pt_ARG_ORIGIN 164
reextent, forcing 138 Pt_ARG_POINTS 164
title width 164
etching 139 PtFileSel 168
font 143 background handler 180
gradient 139 callbacks
showing 139 drag and drop 186
text 143 item selection 181
PtContainerCallback_t 148 case insensitivity 176
PtContainerHold() 243, 926 convenience functions 187
PtDamageExtent() 265, 272 custom headers 170
PtDisjoint 152 directories, listing 176
callbacks, system information 152 error dialog 176
Pt_ARG_SYSINFO 152 events, processing pending 180
Pt_CB_SYSINFO 152 files
system information 152 hidden 176
PtDivider 156 information 170, 176
bandwidth threshold 163 listing 176
callbacks names, pattern for 175
dragging 158 flags 169, 175
mouse clicks 159 items
drag outline, suppressing 157 adding 189, 191
flags 157 allocating 194
group orientation 163 collapsing 168, 182, 199
in a list 237 damaging 197
offset 158 expanding 168, 182, 200
Pt_ARG_BANDWIDTH_THRESHOLD expanding parents 198
163 freeing 201, 202
Pt_ARG_DIVIDER_FLAGS 157 freeing when collapsing 176
Pt_ARG_DIVIDER_OFFSET 158 getting all 193
Pt_ARG_DIVIDER_SIZES 158 getting current 203
Pt_ARG_FLAGS 158 getting selected 204, 212
Pt_ARG_GROUP_ORIENTATION 163 images for 177
Pt_CB_DIVIDER_DRAG 158 index of 206
Pt_CB_DIVIDER_HANDLE_CALLBACK redrawing 197
159 removing 207–209
May 13, 2010 Index 1029

rereading 179 text background 221

root 210 convenience functions 224
scrolling to 214 flags 219
selecting 211, 213 font
selection, clearing 196 currently selected 220
setting current 205 families, filtering 218
unselecting 215, 216 initial 220
keyboard seek mode 176 label
labels background color 219
date 178 font name 219
group 179 size 219
name 179 style 219
owner 179 text color 220
permissions 179 maximum point size 220
size 179 Pt_ARG_FLAGS 221
Pt_ARG_FS_FILE_SPEC 175 Pt_ARG_FONT_DISPLAY 218
Pt_ARG_FS_FLAGS 169, 175 Pt_ARG_FONT_FLAGS 219
Pt_ARG_FS_FORMAT 176 Pt_ARG_FONT_LBL_BKGDCOLOR
Pt_ARG_FS_IMAGES 177 219
Pt_ARG_FS_LBL_DATE 178 Pt_ARG_FONT_LBL_FONT 219
Pt_ARG_FS_LBL_GROUP 179 Pt_ARG_FONT_LBL_SIZE 219
Pt_ARG_FS_LBL_NAME 179 Pt_ARG_FONT_LBL_STYLE 219
Pt_ARG_FS_LBL_OWNER 179 Pt_ARG_FONT_LBL_TEXTCOLOR 220
Pt_ARG_FS_LBL_PERMISSIONS 179 Pt_ARG_FONT_NAME 220
Pt_ARG_FS_LBL_SIZE 179 Pt_ARG_FONT_POINT_SIZE_MAX 220
Pt_ARG_FS_REFRESH 179 Pt_ARG_FONT_SAMPLE 220
Pt_ARG_FS_ROOT_DIR 180 Pt_ARG_FONT_SYMBOL 220
Pt_CB_DND 186 Pt_ARG_FONT_TEXT_BKGD_COLOR
Pt_CB_FS_BKGD_HANDLER 180 221
Pt_CB_FS_SELECTION 181 Pt_ARG_FONT_TEXT_COLOR 221
Pt_CB_FS_STATE 182 Pt_CB_FONT_MODIFY 221
read error 176 required symbol 220
reading directories 170 sample text 220
root directory 180 PtForwardWindowEvent() 951
sample code 171 PtForwardWindowTaskEvent() 951
seeking files 176 PtFSAddAfter() 189
single-level mode 169, 176, 183 PtFSAddFirst() 191
tree mode 169 PtFSAllItems() 193
PtFileSelBkgdCallback_t 180 PtFSAllocItem() 194
PtFileSelCallback_t 182 PtFSClearSelection() 196
PtFileSelItem_t 168 PtFSDamageItem() 197
PtFontSel 217 PtFSExpandParents() 198
callbacks PtFSFolderCollapse() 199
font modified 221 PtFSFolderExpand() 200
colors PtFSFreeAllItems() 201
text 221 PtFSFreeItems() 202
1030 Index May 13, 2010

PtFSGetCurrent() 203 vertical alignment 227

PtFSGetSelIndexes() 204 PtGaugeCallback_t 229
PtFSGoto() 205 PtGenList 233
PtFSItemIndex() 206 background, drawing 257
PtFSRemoveChildren() 207 balloon
PtFSRemoveItem() 208 adjusting for a column 277
PtFSRemoveList() 209 creating 254
PtFSRootItem() 210 for individual columns 237
PtFSSelect() 211 showing 238
PtFSSelectedItems() 212 when clipping occurs 237
PtFSSetSelIndexes() 213 browse mode 240
PtFSShow() 214 callbacks
PtFSUnselect() 215 drag and drop 247
PtFSUnselectNonBrothers() 216 scroll 243
PtGauge 225 column flags 235
callbacks column positions 236
value changed 228 compose selection modes, defining 241
flags 226 convenience functions 247
font 227 drag and drop, selection color 236
horizontal alignment 227 events, consuming 237
interactive 226, 228 extended mode 241
live 226 flags 237
orientation 228 font 238
Pt_ARG_FLAGS 228 gflags, getting 278
Pt_ARG_GAUGE_FLAGS 226 horizontal scrollbar
Pt_ARG_GAUGE_FONT 227 always 237
Pt_ARG_GAUGE_H_ALIGN 227 as required 237
Pt_ARG_GAUGE_V_ALIGN 227 never 237
Pt_ARG_GAUGE_VALUE 227 items
Pt_ARG_GAUGE_VALUE_PREFIX 227 adding 250
Pt_ARG_GAUGE_VALUE_SUFFIX 228 browsing 240
Pt_ARG_MAXIMUM 228 Ctrl-click 241
Pt_ARG_MINIMUM 228 current 233
Pt_ARG_ORIENTATION 228 damaging 256
Pt_CB_GAUGE_VALUE_CHANGED getting all 252
228 getting current 262
value getting first 261
current 227 getting last 270
displaying 226 getting selected 263, 276
indeterminate 226 index 268
inverting fill color 226 locking 271
maximum 228 number of 238
maximum, position of 226 number selected 240
minimum 228 number visible 243
prefix 227 reallocating 269
suffix 228 removing 273
May 13, 2010 Index 1031

selected, color of 240 color 233, 239

selected, text color 243 granting focus to 238
selecting 275 resources 233, 239
selecting a range 241 width 240
selecting many 241 scrollbars 233
selecting one 241 selection
setting current 264 clearing 253
setting selected 279 selection mode 240
Shift-click 241 single-select mode 241
showing 280 snapping to the number of items 238
top one displayed 243 stretching header 238
total height 240 strings, drawing 259
unlocking 281 text alignment 235
unselecting 282 vertical scrollbar
keyboard actions 234 always 237
mouse actions 234 as required 237
multiple mode 241 never 237
Pt_ARG_FLAGS 243 resizing 238
Pt_ARG_LIST_COLUMN_ATTR 235 PtGenListAddItems() 250
Pt_ARG_LIST_COLUMN_POS 236 PtGenListAllItems() 252
Pt_ARG_LIST_DNDSEL_COLOR 236 PtGenListClearSelection() 253
Pt_ARG_LIST_FLAGS 233, 237 PtGenListCreateTextBalloon() 254, 579, 587
Pt_ARG_LIST_FONT 238 PtGenListDamageItem() 256, 265, 272
Pt_ARG_LIST_ITEM_COUNT 238 PtGenListDndCallback_t 585
Pt_ARG_LIST_SB_RES 233, 239 PtGenListDrawBackground() 257
Pt_ARG_LIST_SCROLL_RATE 239 PtGenListDrawString() 259
Pt_ARG_LIST_SEL_COUNT 240 PtGenListFirstItem() 261
Pt_ARG_LIST_TOTAL_HEIGHT 240 PtGenListGetCurrent() 262
Pt_ARG_SCROLLBAR_WIDTH 240 PtGenListGetSelIndexes() 263
Pt_ARG_SELECTION_FILL_COLOR 240 PtGenListGoto() 264
Pt_ARG_SELECTION_MODE 240 PtGenListHold() 256, 265, 272
Pt_ARG_SELECTION_TEXT_COLOR 243 PtGenListItem_t 266
Pt_ARG_TOP_ITEM_POS 243 PtGenListItemIndex() 268
Pt_ARG_VISIBLE_COUNT 243 PtGenListItemRealloc() 269
Pt_CB_DND 247 PtGenListLastItem() 270
Pt_CB_SCROLL_MOVE 243 PtGenListLockItem() 256, 271, 281
PtDivider as child 233 PtGenListRelease() 256, 272
adjusting size 237 PtGenListRemoveItems() 273
range-select mode 241 PtGenListResize() 271, 274, 281
read-only 237 PtGenListSelect() 275
repairs PtGenListSelectedItems() 276
holding 265 PtGenListSetColumnBalloon() 277, 579, 587
releasing hold on 272 PtGenListSetGflags() 278
resizing 274 PtGenListSetSelIndexes() 279
scroll rate 239 PtGenListShow() 280
scrollbar PtGenListUnlockItem() 256, 271, 281
1032 Index May 13, 2010

PtGenListUnselect() 282 Pt_ARG_TREE_MARGIN_COLOR 285

PtGenTree 283 Pt_CB_DND 289
buttons Pt_CB_GEN_TREE_INPUT 285
displaying 284, 305 selection
indenting 284 clearing 295
callbacks PtGenTreeAddAfter() 292
drag and drop 289 PtGenTreeAddFirst() 293
mouse and key event 285 PtGenTreeAllItems() 294
connectors PtGenTreeClearSelection() 295
displaying 284 PtGenTreeCollapse() 296
convenience functions 290 PtGenTreeDamageItem() 297
flags 284, 305 PtGenTreeExpand() 298, 589
items PtGenTreeExpandParents() 299
adding 292, 293 PtGenTreeFreeAllItems() 300
collapsing 296 PtGenTreeFreeItems() 301
damaging 297 PtGenTreeGetCurrent() 302
expanding 298 PtGenTreeGetSelIndexes() 303
expanding parents 299 PtGenTreeGoto() 304
extending background to the left 284 PtGenTreeInput_t 285
extending to the right 284 PtGenTreeItem_t 305
freeing 301 PtGenTreeItemIndex() 307
freeing all 300 PtGenTreeItemRealloc() 308
getting all 294 PtGenTreeItemResize() 309
getting current 302 PtGenTreeRemoveChildren() 310
getting root 314 PtGenTreeRemoveItem() 311
getting selected 303, 316, 317 PtGenTreeRemoveList() 312
index 307 PtGenTreeResize() 313
reallocating 308 PtGenTreeRootItem() 314
removing 311, 312 PtGenTreeSelect() 315
removing children 310 PtGenTreeSelectedItems() 316
resizing 309, 313 PtGenTreeSetSelIndexes() 317
selecting 315 PtGenTreeShow() 318
setting current 304 PtGenTreeUnselect() 319
showing 318 PtGenTreeUnselectNonBrothers() 320
unselecting 319, 320 PtGetStyleMember() 45
lines PtGraphic 321
color 285 callbacks
displaying 284 rescale 328
indenting 284 colors
spacing 285 fill 326
margins inside 326
displaying 284 dash
margins, color 285 scaling 326
Pt_ARG_TREE_FLAGS 284, 305 style 325
Pt_ARG_TREE_LINE_COLOR 285 flags 326
Pt_ARG_TREE_LINE_SPACING 285 lines
May 13, 2010 Index 1033

cap style 327 Pt_ARG_CELL_HORZ_ALIGN 337

join style 327 Pt_ARG_CELL_VERT_ALIGN 337
width 328 Pt_ARG_GROUP_FLAGS 337, 739
origin 322, 328 Pt_ARG_GROUP_HORZ_ALIGN 338
floating 326 Pt_ARG_GROUP_ORIENTATION 339
points 322, 328 Pt_ARG_GROUP_ROWS_COLS 339
position, floating 326 Pt_ARG_GROUP_SPACING 339
Pt_ARG_DASH_LIST 325 Pt_ARG_GROUP_SPACING_X 340
Pt_ARG_DASH_SCALE 326 Pt_ARG_GROUP_SPACING_Y 340
Pt_ARG_GRAPHIC_FLAGS 326 Pt_ARG_GROUP_VERT_ALIGN 340
Pt_ARG_INSIDE_COLOR 326 Pt_CB_ACTIVATE 739
Pt_ARG_LINE_CAP 327 vertical wrapping, preventing 338
Pt_ARG_LINE_JOIN 327 PtHold() 265
Pt_ARG_LINE_WIDTH 328 PtHotkeyCallback_t 9, 937
Pt_ARG_ORIGIN 322, 323, 328 PtImageArea 344
Pt_ARG_POINTS 322, 328 callbacks
Pt_CB_RESCALE 328 dragging 346
PtGrid 332 movement 347
lines scrolled 347
horizontal, number of 332 selection 348
vertical, number of 332 flags 345
Pt_ARG_GRID_HORIZONTAL 332 grid color 345
Pt_ARG_GRID_VERTICAL 332 grid threshold 345
PtGroup 336 image 345
callbacks left 346
activate 739 Pt_ARG_IMAGEAREA_FLAGS 345
cells Pt_ARG_IMAGEAREA_GRID_COLOR
horizontal alignment 337 345
vertical alignment 337 Pt_ARG_IMAGEAREA_GRID_THRESHOLD
children 345
aligning 339 Pt_ARG_IMAGEAREA_IMAGE 345
exclusive choice 337 Pt_ARG_IMAGEAREA_LEFT 346
forcing equal height 338 Pt_ARG_IMAGEAREA_SELECTION 346
forcing equal size 337 Pt_ARG_IMAGEAREA_TOP 346
forcing equal width 338 Pt_ARG_IMAGEAREA_ZOOM 346
horizontal alignment 338 Pt_CB_IMAGEAREA_DRAG 346
no choice 337 Pt_CB_IMAGEAREA_MOVEMENT 347
spacing between 339, 340 Pt_CB_IMAGEAREA_SCROLLED 347
stretching horizontally 338 Pt_CB_IMAGEAREA_SELECTION 348
stretching vertically 338 selected area 346
vertical alignment 340 top 346
flags 337 zooming factor 346
horizontal wrapping, preventing 338 PtLabel 352
keys, preventing use of 338 accelerator key 357
number of rows and columns 339 backfilling text 359
orientation 339 balloons
1034 Index May 13, 2010

customizing 358 Pt_ARG_UNDERLINE2 363

enabling 359 Pt_ARG_VERTICAL_ALIGNMENT 353,
enabling if clipped 359 363
fill color 357 shifting when selected 359
position 356, 357 text 353, 362
text 356, 358 position 353, 357
text color 357 spacing relative to image 353, 362
creating 352 using ellipsis 359
flags 356, 359 type 352, 360
font 353, 362 underline color 362, 363
horizontal alignment 353, 358, 361 underline type 363
image vertical alignment 353, 362, 363
data 354, 360 PtLine 367
position 353, 357 Pt_ARG_ORIGIN 367
spacing relative to text 353, 362 Pt_ARG_POINTS 367
line spacing 360 PtList 371
margins balloon function 374
bottom 353, 361 callbacks
left 353, 361 drag and drop 381
right 353, 361 mouse and key event 375
top 353, 361 selection 373, 376
Pt_ARG_ACCEL_KEY 357 convenience functions 381
Pt_ARG_BALLOON_COLOR 357 creating 372
Pt_ARG_BALLOON_FILL_COLOR 357 items
Pt_ARG_BALLOON_POSITION 353, adding 383
356, 357 array of 373, 374
Pt_ARG_BALLOON_TEXT 358 checking existence of 388
Pt_ARG_HORIZONTAL_ALIGNMENT 353, deleting a range 385
358 deleting all 384
Pt_ARG_LABEL_BALLOON 358 deleting specific 386
Pt_ARG_LABEL_FLAGS 356, 359 determining position of 389
Pt_ARG_LABEL_IMAGE 354, 360 displaying in columns 372
Pt_ARG_LABEL_TYPE 352, 360 getting 372
Pt_ARG_LINE_SPACING 353, 360 number displayed 372
Pt_ARG_MARGIN_BOTTOM 353, 361 removing by position 390
Pt_ARG_MARGIN_LEFT 353, 361 replacing 392
Pt_ARG_MARGIN_RIGHT 353, 361 replacing by position 391
Pt_ARG_MARGIN_TOP 353, 361 selected 375
Pt_ARG_SECONDARY_H_ALIGN 353, selecting by position 393
361 setting the current 387
Pt_ARG_SECONDARY_V_ALIGN 362 showing by position 394
Pt_ARG_TEXT_FONT 353, 362 spacing between 375
Pt_ARG_TEXT_IMAGE_SPACING 362 unselecting 395
Pt_ARG_TEXT_STRING 353, 356, 362 methods
Pt_ARG_UNDERLINE_TYPE 363 List Draw 259
Pt_ARG_UNDERLINE1 362 Pt_ARG_ITEMS 373, 374
May 13, 2010 Index 1035

Pt_ARG_LIST_BALLOON 374 gradient fill 405

Pt_ARG_LIST_COLUMN_POS 372 input group 406
Pt_ARG_LIST_SPACING 375 items
Pt_ARG_MODIFY_ITEMS 375 accelerators 396
Pt_ARG_SELECTION_INDEXES 375 fill color 406
Pt_ARG_VISIBLE_COUNT 372, 380 font 398, 406
Pt_CB_DND 381 forcing equal widths 405
Pt_CB_LIST_INPUT 375 highlight color 406
Pt_CB_SELECTION 373, 376 hotkeys 396
PtDivider as child 372 making selectable 397
selection policy selecting 397
browse 373 spacing between 406
extended 373 widget types 396
multiple 373 labels 398
single 373 lifetime 398
PtListAddItems() 383 menu bar 397
PtListCallback_t 373, 377 overriding parent menu 405
PtListColumn_t 236 PhAB’s Menu module, using instead 396
PtListColumnAttributes_t 235 populating 398
PtListDeleteAllItems() 384 popup 397, 400
PtListDeleteItemPos() 385 positioning 399
PtListDeleteItems() 386 press-drag-release mode 397
PtListDndCallback_t 247, 381 Pt_ARG_BEVEL_WIDTH 406
PtListGotoPos() 387 Pt_ARG_FLAGS 398
PtListInput_t 376 Pt_ARG_MENU_FLAGS 397, 398, 401,
PtListItemExists() 388 405
PtListItemPos() 389 Pt_ARG_MENU_INPUT_GROUP 406
PtListRemovePositions() 390 Pt_ARG_MENU_ITEM_FILL_COLOR
PtListReplaceItemPos() 391 406
PtListReplaceItems() 392 Pt_ARG_MENU_ITEM_HIGHLIGHT_COLOR
PtListSelectPos() 393 406
PtListShowPos() 394 Pt_ARG_MENU_SPACING 406
PtListUnselectPos() 395 Pt_ARG_MENU_TEXT_FONT 398, 406
PtM_NO_TEXT 427 Pt_ARG_MENU_TITLE 398, 407
PtM_NON_SELECTABLE 427 Pt_ARG_MENU_TITLE_FONT 398, 407
PtM_SELECTABLE 427 Pt_ARG_SUBMENU_PARENT_HIGHLIGHT_COLOR
PtMenu 396 407
activating via an event handler 400 pulldown 399
appearance, controlling 397 separators 398
cascaded menus 401 sizing 398
click-stay mode 397 submenu 407
creating 397 submenus 397
destroying 399 tear off 405
destroying on closing 405 text alignment 405
example 401 title 398, 407
flags 397, 398, 401, 405 title font 398, 407
1036 Index May 13, 2010

PtMenuBar 411, See also PtMenu minimum 429

anchoring 411 mouse movement 421
children 411 no text 427
PtMenuButton 415 noninteractive 427
accelerator position
displaying 416 level 1 428
font 416 level 2 428
key 415 maximum 429
modifier keys 416 minimum 429
text 416 needle 421, 429
callbacks Pt_ARG_FLAGS 427, 428
arm 399 Pt_ARG_METER_COLOR 426
menu 399 Pt_ARG_METER_FLAGS 427
menu position 416 Pt_ARG_METER_FONT_COLOR 427
Pt_ARG_ACCEL_FONT 416 Pt_ARG_METER_INCREMENT 427
Pt_ARG_ACCEL_KEY 415 Pt_ARG_METER_KEY_LEFT 421, 427
Pt_ARG_ACCEL_TEXT 416 Pt_ARG_METER_KEY_RIGHT 421, 428
Pt_ARG_BUTTON_TYPE 401, 416 Pt_ARG_METER_LEVEL1_COLOR 428
Pt_ARG_MODIFIER_KEYS 416 Pt_ARG_METER_LEVEL1_POS 428
Pt_CB_ARM 399 Pt_ARG_METER_LEVEL2_COLOR 428
Pt_CB_MENU 399 Pt_ARG_METER_LEVEL2_POS 428
type 416 Pt_ARG_METER_LEVEL3_COLOR 429
PtMeter 421 Pt_ARG_METER_MAX_NEEDLE_POSITION
callbacks 429
needle movement 430 Pt_ARG_METER_MIN_NEEDLE_POSITION
color 429
center 426 Pt_ARG_METER_NEEDLE_COLOR
font 427 429
level 1 428 Pt_ARG_METER_NEEDLE_POSITION
level 2 428 421, 429, 430
level 3 429 Pt_ARG_METER_NUM_SEVERITY_LEVELS
needle 429 429
outline 426 Pt_ARG_METER_TEXT_FONT 430
ticks 426 Pt_CB_METER_MOVED 430
examples 422 severity arcs 421
flags 427 size 421
flickering 423 PtMTrend 434
font 430 adding or changing graph data 440
interactive 427 attributes 437
key graph attributes 438
increment 427 graph drawing state 439
left 421, 427 grid color 441
movement with 421 grid draw function 442
right 421, 428 grid lines 441
levels, number of 429 number of graphs 438
maximum 429 number of samples 438
May 13, 2010 Index 1037

Pt_ARG_MTREND_ADVANCE_BY_N_SAMPLES 442 font 451, 472, 474

Pt_ARG_MTREND_ATTRIBUTES 437 hyperlinks 453
Pt_ARG_MTREND_GRAPH_ATTR 438 indentation, automatic 456
Pt_ARG_MTREND_GRAPH_DATA 440 lines
Pt_ARG_MTREND_GRAPH_STATE 439 bottom 456
Pt_ARG_MTREND_GRID_COLOR 441 displaying if there’s room 456
Pt_ARG_MTREND_GRID_DRAW_F getting information 457, 481
442 number of 457
Pt_ARG_MTREND_GRID_X 441 number visible 457
Pt_ARG_MTREND_GRID_Y 441 spacing 448
Pt_ARG_MTREND_N_GRAPHS 438 top 459, 460
Pt_ARG_MTREND_N_SAMPLES 438 Pt_ARG_COLOR 448, 472, 474
Pt_ARG_MTREND_TRACE_DRAW_F Pt_ARG_DIM 454
441 Pt_ARG_FILL_COLOR 448, 472, 474
Pt_ARG_MTREND_TRACE_WIDTH Pt_ARG_FLAGS 465
440 Pt_ARG_LINE_SPACING 448
scrolling 442 Pt_ARG_MULTITEXT_BOTTOM_LINE 456
trace line drawing function 441 Pt_ARG_MULTITEXT_FLAGS 456
trace line width 440 Pt_ARG_MULTITEXT_NUM_LINES
trends 457
data, replacing 445 Pt_ARG_MULTITEXT_NUM_LINES_VISIBLE
PtMTrendAddData() 445 457
PtMTrendChangeData() 445 Pt_ARG_MULTITEXT_QUERY_CHARACTER
PtMultiLines_t 449, 459, 472 457
PtMultiText 447 Pt_ARG_MULTITEXT_QUERY_LINE
attributes 454, 457
creating 477 Pt_ARG_MULTITEXT_RANGE_ATTRIBUTES
getting 458, 478 449, 451, 458
modifying 451, 458, 485, 487 Pt_ARG_MULTITEXT_ROWS 458
callbacks Pt_ARG_MULTITEXT_SEGMENTS 448,
activate 465 449, 459
got focus 466 Pt_ARG_MULTITEXT_TABS 459
lost focus 466 Pt_ARG_MULTITEXT_TOP_LINE 459
modify notify 467 Pt_ARG_MULTITEXT_WRAP_FLAGS
modify verify 468 448, 460
motion notify 467 Pt_ARG_MULTITEXT_X_SCROLL_POS
motion verify 469 460
text changed 467 Pt_ARG_MULTITEXT_Y_SCROLL_POS
character information, getting 457, 481 460
color 472, 474 Pt_ARG_SCROLLBAR_X_DISPLAY 448,
convenience functions 470 460
cursor tracking, enabling 456 Pt_ARG_SCROLLBAR_X_HEIGHT 461
dimensions 454 Pt_ARG_SCROLLBAR_Y_DISPLAY 448,
features 447 461
flags 456, 465 Pt_ARG_SCROLLBAR_Y_WIDTH 461
flags, wrapping 460 Pt_ARG_TEXT_FLAGS 465
1038 Index May 13, 2010

Pt_ARG_TEXT_FONT 448, 472, 474 flags 491

Pt_ARG_TEXT_STRING 448, 459 Pt_ARG_NUMERIC_FLAGS 491
Pt_ARG_TEXT_SUBSTRING 448 Pt_ARG_NUMERIC_PREFIX 492
Pt_CB_ACTIVATE 465 Pt_ARG_NUMERIC_SPACING 492
Pt_CB_GOT_FOCUS 466 Pt_ARG_NUMERIC_SUFFIX 492
Pt_CB_LOST_FOCUS 466 Pt_ARG_NUMERIC_UPDOWN_WIDTH
Pt_CB_MODIFY_NOTIFY 467 492
Pt_CB_MODIFY_VERIFY 468 spacing 492
Pt_CB_MOTION_NOTIFY 467 text
Pt_CB_MOTION_VERIFY 469 autohighlighting 491
Pt_CB_TEXT_CHANGED 467 hexadecimal 492
rows, number of 458 inserting commas 492
scrollbars prefix 492
displaying 460, 461 suffix 492
height 461 wrapping 492
position 460 PtNumericFloat 496
width 461 callbacks
scrolling, automatic 456 activate 502
tab stops 459 value changed 498
text increment 497
inserting 450 precision 498
modifying 487 Pt_ARG_NUMERIC_INCREMENT 497
multisegment 459 Pt_ARG_NUMERIC_MAX 497
ranges of 449 Pt_ARG_NUMERIC_MIN 497
setting 448 Pt_ARG_NUMERIC_PRECISION 498
setting attributes 449 Pt_ARG_NUMERIC_VALUE 498
wrapping 448 Pt_CB_ACTIVATE 502
carriage return 460 Pt_CB_NUMERIC_CHANGED 498
end of line 460 value
word break 460 current 498
PtMultiTextAttributes_t 474 maximum 497
PtMultiTextCallback_t 452, 476, 707 minimum 497
PtMultiTextControl_t 452, 458, 476 PtNumericFloatCallback_t 499
PtMultiTextCreateAttributes() 477 PtNumericInteger 503
PtMultiTextGetAttributes() 478 callbacks
PtMultiTextInfo_t 476 activate 508
PtMultiTextInfo() 481 value changed 504
PtMultiTextLine_t 454, 484 increment 504
PtMultiTextModifyAttributes() 451, 485 Pt_ARG_NUMERIC_INCREMENT 504
PtMultiTextModifyText() 448–450, 487 Pt_ARG_NUMERIC_MAX 504
PtMultiTextQuery_t 454, 457, 489 Pt_ARG_NUMERIC_MIN 504
PtMultiTextSegment_t 490 Pt_ARG_NUMERIC_VALUE 504
PtNumeric 491 Pt_CB_ACTIVATE 508
buttons Pt_CB_NUMERIC_CHANGED 504
displaying 492 value
width 492 current 504
May 13, 2010 Index 1039

hexadecimal 503 color 527

maximum 504 displaying one per panel 528
minimum 504 displaying only one 528
PtNumericIntegerCallback_t 505 forcing equal size 527
PtOnOffButton 509 overlap 527
Pt_ARG_FLAGS 510 PtPixel 542
Pt_ARG_ONOFF_STATE 509 Pt_ARG_POINTS 542
Pt_CB_ONOFF_NEW_VALUE 510 PtPolygon 545
PtOSContainer 514 closed 546
fill color 517 flags 545, 546
Pt_ARG_FILL_COLOR 517 Pt_ARG_ORIGIN 545
PtPane 518 Pt_ARG_POINTS 545
PtPanelGroup 522 Pt_ARG_POLYGON_FLAGS 545, 546
convenience functions 532 relative coordinates 546
copying as popup window 534 PtPositionMenu() 399
drag and drop 526 PtPrintSel 549
flags 526 callbacks
margins print properties 555
bottom 524, 525 convenience functions 558
left 524, 525 file 551
right 524, 525 flags 551
top 524, 525 labels
panel index, finding 537, 538 all pages 552
panel pointer, finding 539, 540 collate pages 552
panel title, finding 541 double sided 553
panel titles 527 file name 553
panels not collated 553
current 526 number of copies 553
switching 528 pages from 553
Pt_ARG_FLAGS 528 pages to 555
Pt_ARG_MARGIN_BOTTOM 524, 525 preferences 554
Pt_ARG_MARGIN_LEFT 524, 525 print order 554
Pt_ARG_MARGIN_RIGHT 524, 525 print pages 554
Pt_ARG_MARGIN_TOP 524, 525 print range 554
Pt_ARG_PG_CURRENT 526 print selected 554
Pt_ARG_PG_CURRENT_INDEX 526 printer name 553
Pt_ARG_PG_FLAGS 526 reverse order 554
Pt_ARG_PG_OVERLAP_THRESHOLD 527 send to file 555
Pt_ARG_PG_PANEL_TITLES 527 send to printer 555
Pt_ARG_PG_SELECTION_MODE 528 print context 549, 551
Pt_CB_PG_PANEL_SWITCHING 528 Pt_ARG_PRINT_CONTEXT 549, 551
selection mechanism location 526, 527 Pt_ARG_PRINT_FILE 551
selection mode 528 Pt_ARG_PRINT_FLAGS 551
selector Pt_ARG_PS_LBL_ALL 552
none 528 Pt_ARG_PS_LBL_COLLATED 552
tabs Pt_ARG_PS_LBL_COPIES 553
1040 Index May 13, 2010

Pt_ARG_PS_LBL_DOUBLE_SIDED color 570

553 connect function 571
Pt_ARG_PS_LBL_FILE 553 custom widgets 568
Pt_ARG_PS_LBL_FROM 553 damage 568
Pt_ARG_PS_LBL_NAME 553 data model 569
Pt_ARG_PS_LBL_NOT_COLLATED data, user-defined 569
553 drawing
Pt_ARG_PS_LBL_PREFERENCES 554 function 569
Pt_ARG_PS_LBL_PRINT_ORDER 554 drawing function 572
Pt_ARG_PS_LBL_PRINT_PAGES 554 example 570
Pt_ARG_PS_LBL_RANGE 554 extent function 572
Pt_ARG_PS_LBL_REVERSED 554 fill color 570
Pt_ARG_PS_LBL_SELECTION 554 initialization function 572
Pt_ARG_PS_LBL_SEND_TO_FILE 555 opacity-calculation function 571
Pt_ARG_PS_LBL_SEND_TO_PRINTER Pt_ARG_COLOR 570
555 Pt_ARG_FILL_COLOR 570
Pt_ARG_PS_LBL_TO 555 Pt_ARG_POINTER 569
Pt_CB_PRINT_PROPS 555 Pt_ARG_RAW_CALC_OPAQUE_F 571
PtProgress 559 Pt_ARG_RAW_CONNECT_F 571
callbacks Pt_ARG_RAW_DRAW_F 569, 572
value changed 559 Pt_ARG_RAW_EXTENT_F 572
color 560 Pt_ARG_RAW_INIT_F 572
convenience functions 563 Pt_ARG_USER_DATA 569
flags 559 redrawing 568
number of divisions 560 scaling 569
Pt_ARG_GAUGE_FLAGS 559 translation
Pt_ARG_PROGRESS_BAR_COLOR 560 restoring 570
Pt_ARG_PROGRESS_DIVISIONS 560 setting 569
Pt_ARG_PROGRESS_GAP 560 PtRawCallback_t 11, 939
Pt_ARG_PROGRESS_SPACING 560 PtRawList 576
Pt_CB_GAUGE_VALUE_CHANGED callbacks
559 drag and drop 585
segments, getting 564, 565 convenience functions 585
next 566 flags 578
spacing functions
bar and text 560 background 576
divisions 560 draw 577
text area, getting 567 inflate balloon 578
PtProgressEntireSegment() 564 key event 579
PtProgressFirstSegment() 565 mouse event 580
PtProgressNextSegment() 566 selection 581
PtProgressTextRect() 567 Pt_ARG_RAWLIST_BACKGROUND_F 576
PtRaw 568 Pt_ARG_RAWLIST_DRAW_F 577
clipping Pt_ARG_RAWLIST_GFLAGS 578
restoring 570 Pt_ARG_RAWLIST_INFLATE_F 578
setting 569 Pt_ARG_RAWLIST_KEY_F 579
May 13, 2010 Index 1041

Pt_ARG_RAWLIST_MOUSE_F 580 Pt_ARG_REGION_INFRONT 601

Pt_ARG_RAWLIST_SELECT_F 581 Pt_ARG_REGION_INPUT_GROUP 601
Pt_CB_DND 585 Pt_ARG_REGION_OPAQUE 601
PtRawListDrawBackgroundF_t 576 Pt_ARG_REGION_PARENT 602
PtRawListInflateF_t 578 Pt_ARG_REGION_RECTANGLES 602
PtRawListMouseF_t 580 Pt_ARG_REGION_SENSE 602
PtRawListSelectF_t 581 region
PtRawTree 586 in front 601
balloon parent 602
location 592 resources, changing 600
callbacks sensitivity 602
drag and drop 593 PtRelease() 272
convenience functions 594 PtScrollArea 606
flags 592 arrow keys, ignoring 608
functions callbacks
draw 586 scrollbars moved 606, 610
inflate balloon 587 canvas, determining 615
selection 588 convenience functions 614
state 588 displayed portion, position 609
Pt_ARG_RAWTREE_DRAW_F 586 flags 608
Pt_ARG_RAWTREE_INFLATE_F 587 Pt_ARG_AREA 606, 608, 609
Pt_ARG_RAWTREE_SELECT_F 588 Pt_ARG_FLAGS 610
Pt_ARG_RAWTREE_STATE_F 588 Pt_ARG_SCROLLAREA_FLAGS 608
Pt_ARG_TREE_FLAGS 592 Pt_ARG_SCROLLAREA_INCREMENT_X
Pt_CB_DND 593 608
PtRawTreeDrawItemF_t 586 Pt_ARG_SCROLLAREA_INCREMENT_Y
PtRawTreeInflateF_t 587 608
PtRawTreeItemStateF_t 588 Pt_ARG_SCROLLAREA_MAX_X 606,
PtRawTreeSelectF_t 588 608
PtRect 595 Pt_ARG_SCROLLAREA_MAX_Y 606,
dimensions 595 609
points 595 Pt_ARG_SCROLLAREA_POS_X 609
position 595 Pt_ARG_SCROLLAREA_POS_Y 609
Pt_ARG_DIM 595 Pt_ARG_SCROLLAREA_SCROLLBAR_COLOR 609
Pt_ARG_POINTS 595 Pt_ARG_SCROLLBAR_X_DISPLAY 606,
Pt_ARG_POS 595 609
Pt_ARG_RECT_ROUNDNESS 595 Pt_ARG_SCROLLBAR_X_HEIGHT 610
rounding corners 595 Pt_ARG_SCROLLBAR_Y_DISPLAY 606,
PtRegion 599 610
flags 600 Pt_ARG_SCROLLBAR_Y_WIDTH 610
input group 601 Pt_CB_SCROLLAREA_SCROLLED 606,
instantiation 599 610
multiple rectangles 602 scrollbars
opacity 601 color 609
Pt_ARG_REGION_FIELDS 600 displaying 606, 609, 610
Pt_ARG_REGION_FLAGS 600 height 610
1042 Index May 13, 2010

increment 608 Pt_ARG_SEP_ARM_CURSOR_COLOR

width 610 632
scrolling Pt_ARG_SEP_ARM_CURSOR_TYPE
control 607 632
notification 606 Pt_ARG_SEP_DRAG_BOUNDS 632
size Pt_ARG_SEP_FLAGS 633
physical 606 Pt_ARG_SEP_IMAGE 633
virtual 606, 608, 609 Pt_ARG_SEP_IMAGE_H_ALIGN 633
PtScrollAreaCanvas() 615 Pt_ARG_SEP_IMAGE_V_ALIGN 634
PtScrollbar 616 Pt_ARG_SEP_TYPE 634
arrow buttons, displaying 619 Pt_CB_SEP_DRAG 634
bandwidth threshold 623 type 634
callbacks PtServer 638
scrolled 619 callbacks
flags 618 connected 640
handle length error 640
current 619 receive 641
minimum 618 transport 641
increment connection object 639
page 618 instantiation 638
step 618 messages, sending to client 639
keyboard actions 617 name 639
mouse actions 617 Pt_ARG_SERVER_CONNECTION 639
Pt_ARG_BANDWIDTH_THRESHOLD 623 Pt_ARG_SERVER_NAME 639
Pt_ARG_FLAGS 619 Pt_ARG_SERVER_SEND 639
Pt_ARG_INCREMENT 618 Pt_CB_SERVER_CONNECTED 640
Pt_ARG_MIN_SLIDER_SIZE 618 Pt_CB_SERVER_ERROR 640
Pt_ARG_PAGE_INCREMENT 618 Pt_CB_SERVER_RECEIVE 641
Pt_ARG_SCROLLBAR_FLAGS 618 Pt_CB_SERVER_TRANSPORT 641
Pt_ARG_SLIDER_SIZE 618, 619 PtServerCallback_t 641
Pt_CB_SCROLL_MOVE 619 PtSetWidgetStyle() 45
rendering as if focused 619 PtSlider
slider, fixed size 618 callbacks
PtScrollContainer 624 movement 650
anchors 624 flags 648
flags 625 gauge flags 650
Pt_ARG_SCROLLCONT_FLAGS 625 handle
Pt_ARG_SCROLLCONT_RESIZE_FLAGS color 648
625 image 648, 649
resize flags 625 width 648
resize policy 624 increment 649
PtSeparator 630 increment, multiple 649
flags 633 keyboard actions 647
orientation 633 mouse actions 646
Pt_ARG_SEP_ARM_BITMAP_CURSOR Pt_ARG_FLAGS 650
631 Pt_ARG_GAUGE_FLAGS 650
May 13, 2010 Index 1043

Pt_ARG_SLIDER_FLAGS 648 columns

Pt_ARG_SLIDER_HANDLE_COLOR 648 current 672
Pt_ARG_SLIDER_HANDLE_WIDTH 648 maximum number of 675
Pt_ARG_SLIDER_IMAGE 649 minimum number of 676
Pt_ARG_SLIDER_INCREMENT 649 number of 672
Pt_ARG_SLIDER_MULTIPLE 649 console emulation 666
Pt_ARG_SLIDER_TICK_MAJOR_DIV 649 convenience functions 688
Pt_ARG_SLIDER_TROUGH_IMAGE1 649 cursor
Pt_ARG_SLIDER_TROUGH_IMAGE2 649 blinking 673
Pt_CB_SLIDER_MOVE 650 not checking for speed 673
ticks, major position 672
number of 649 timer 673
trough escape sequences 676
image 649 flags 673
PtSliderCallback_t 651 font
PtTab 654 enabling escape sequences 677
convenience functions 658 index 661, 674
displaying upside down 655 list of 661, 674
flags 655 maintaining widget size 677
Pt_ARG_TAB_FLAGS 655 name 661, 674
Pt_ARG_TAB_UNSELECTED_COLOR 655 setting via keyboard 677
typical usage 654 size 675
unselected color 655 verifying 696
PtTerminal 660 function reentrancy 663
ANSI protocol 669 geometry 663
application window state 669 line-editing keys, getting 697
callback 680 margins 675
bandwidth, not checking 674 name, getting 699
blitting 673 options 676
callbacks disabling 676
font changed 681 protocol 669
input 681 Pt_ARG_AREA 663
options changed 682 Pt_ARG_BANDWIDTH_THRESHOLD 667,
resizing, after 684 688
resizing, before 683 Pt_ARG_DIM 663, 664, 666
character sets 662, 670 Pt_ARG_FILL_COLOR 688
creating translation tables 694 Pt_ARG_MARGIN_HEIGHT 663, 664,
characters, outputting 702 675
clipboard Pt_ARG_MARGIN_WIDTH 663, 664,
copying to 693 675
pasting from 700 Pt_ARG_TERM_ANSI_PROTOCOL 669
clipped, assuming widget isn’t 673 Pt_ARG_TERM_APP 669
color Pt_ARG_TERM_CHARSETS 662, 670
coding 666 Pt_ARG_TERM_COLOR_MODE 671
mode 671 Pt_ARG_TERM_COLOR_TABLE 666,
table 671 671
1044 Index May 13, 2010

Pt_ARG_TERM_COLS 663, 672, 683, redrawing

684 always 673
Pt_ARG_TERM_CONSOLE 666, 672 on first scroll 673
Pt_ARG_TERM_CUR_COL 672 resizing 663
Pt_ARG_TERM_CUR_POS 672 adjusting after 664
Pt_ARG_TERM_CUR_ROW 673 flags 677
Pt_ARG_TERM_CURSOR_FLAGS 673 hint 677
Pt_ARG_TERM_DRAW_MODES 667, parent widget 677
673 resize function 677
Pt_ARG_TERM_FONT 661, 663, 674 resize function, default 665
Pt_ARG_TERM_FONT_INDEX 661, rows
663, 674 current 673
Pt_ARG_TERM_FONT_LIST 661, 674 maximum number of 675
Pt_ARG_TERM_FONT_SIZE 675 minimum number of 676
Pt_ARG_TERM_MARGINS 663, 664, number of 678
666, 675 screen size 679
Pt_ARG_TERM_MAXCOLS 665, 675 maximum 675
Pt_ARG_TERM_MAXROWS 665, 675 minimum 676
Pt_ARG_TERM_MAXSIZE 665, 675, 683 scrollback buffer
Pt_ARG_TERM_MINCOLS 665, 676 callback 685
Pt_ARG_TERM_MINROWS 665, 676 maximum number of lines 678
Pt_ARG_TERM_MINSIZE 665, 676, 683 number of lines saved 678
Pt_ARG_TERM_OPTIONS 676 position in 678
Pt_ARG_TERM_OPTMASK 676 scrolling optimization 667, 673
Pt_ARG_TERM_RESIZE_FL 677 scrolls, maximum number delayed 678
Pt_ARG_TERM_RESIZE_FUN 663, 677 selection
Pt_ARG_TERM_RESIZE_STR 663, 665, current 678
677 getting current 698
Pt_ARG_TERM_ROWS 663, 678, 683, pasting current 701
684 size limits 665
Pt_ARG_TERM_SCRLBK_COUNT 678 video memory 666, 672
Pt_ARG_TERM_SCRLBK_LIMIT 678 visual bell 679
Pt_ARG_TERM_SCRLBK_POS 678 word, selecting 703
Pt_ARG_TERM_SCROLL 667, 678 PtTerminalAppState_t 669
Pt_ARG_TERM_SELECTION 678 PtTerminalCharset_t 690
Pt_ARG_TERM_SIZE 663, 664, 679, PtTerminalCharsets_t 690
683, 684 PtTerminalCopy() 693
Pt_ARG_TERM_VISUAL_BELL 679 PtTerminalCreateCsXlat() 694
Pt_CB_TERM_APP 680 PtTerminalDefaultCharsets() 695
Pt_CB_TERM_FONT 681 PtTerminalFontChange_t 681
Pt_CB_TERM_INPUT 681, 700, 701 PtTerminalFontInfo() 696
Pt_CB_TERM_OPTIONS 682 PtTerminalGetKeys() 697
Pt_CB_TERM_RESIZE 683 PtTerminalGetSelection() 698
Pt_CB_TERM_RESIZED 684 PtTerminalInput_t 682
Pt_CB_TERM_SCRLBK 685 PtTerminalName() 699
QNX 4 protocol 669 PtTerminalOptionChange_t 683
May 13, 2010 Index 1045

PtTerminalPasteClipboard() 700 Pt_ARG_EDIT_MASK 713, 716

PtTerminalPasteSelection() 701 Pt_ARG_FLAGS 706, 712, 720–722, 726,
PtTerminalPut() 702 731
PtTerminalPutc() 702 Pt_ARG_MAX_LENGTH 717
PtTerminalPuts() 702 Pt_ARG_SELECTION_RANGE 717
PtTerminalRowCol_t 672 Pt_ARG_TEXT_CURSOR_WIDTH 718
PtTerminalScrlbkCb_t 685 Pt_ARG_TEXT_FLAGS 712, 718, 726
PtTerminalSelectWord() 703 Pt_ARG_TEXT_HIGHLIGHT_BACKGROUND_COLOR
PtTerminalSizeChange_t 683, 684, 832 719
PtText 704 Pt_ARG_TEXT_HIGHLIGHT_TEXT_COLOR
arrow keys 712 719
callbacks Pt_ARG_TEXT_STRING 705
activate 726 Pt_ARG_TEXT_SUBSTRING 719
activate, invoking when losing focus 718 Pt_CB_ACTIVATE 712, 726
changed 707, 711, 720 Pt_CB_GOT_FOCUS 711, 727
got focus 711 Pt_CB_LOST_FOCUS 711, 727
lost focus 711 Pt_CB_MODIFY_NOTIFY 707, 711,
modify-notify 707, 711, 720 720, 731
modify-verify 707, 721 Pt_CB_MODIFY_VERIFY 707, 721, 731
motion-notify 722 Pt_CB_MOTION_NOTIFY 722
motion-verify 712, 722 Pt_CB_MOTION_VERIFY 712, 722
columns, number of 716 Pt_CB_TEXT_CHANGED 707, 711, 720,
convenience functions 728 731
cursor replace mode 704, 718
blinking 718 selection 705
cursor position 716 getting current 730
cursor width 718 range 717
cursor, displaying 718 setting 733
edit mask 713, 716 selection mode 718
editable 718 substring, getting or setting 719
flags 712, 718, 726 text 705
focus 711 getting 706
highlighting modifying 705, 706, 731
background color 719 PtTextCallback_t 452, 465–469, 707,
text color 719 720–723, 727, 729
when given focus 718 PtTextControl_t 452, 729
input filter 713, 716 PtTextControlInfo_t 729
insert mode 704, 718 PtTextGetSelection() 451, 730
interaction model 704 PtTextModifyText() 448–450, 706, 731
keyboard actions 714 PtTextSetSelection() 733
maximum length 717 PtTimer 735
mouse actions 714 callbacks
passwords, entering 709 expiration 736
Pt_ARG_COLUMNS 716 initial time 735
Pt_ARG_CURSOR_POSITION 716 Pt_ARG_TIMER_INITIAL 735
Pt_ARG_DIM 716 Pt_ARG_TIMER_REPEAT 736
1046 Index May 13, 2010

Pt_CB_TIMER_ACTIVATE 736 columns 756

repetition time 736 convenience functions 770
PtToggleButton 738 flags 769
“set” images 755, 761
checking to see if 738 adding 755, 776
callbacks mask 755, 761
activate 738 selecting 755, 761
creating 738 items
exclusive choice 739 adding after 772
grouping 739 adding first 774
indicator allocating 753, 778
fill color 740 collapsing 782
types 738, 740 current, getting 788
Pt_ARG_FLAGS 738 current, setting 790
Pt_ARG_INDICATOR_COLOR 740 expanding 785
Pt_ARG_INDICATOR_TYPE 740 freeing 787
Pt_ARG_USER_DATA 739 freeing all 786
Pt_CB_ACTIVATE 738 getting all 777
user-defined data 739 index, getting 795
PtToolbar 744 modifying 796, 797
flags 745 removing 800, 801
layout flags 745 removing children 798
orientation 745 root item, getting 802
Pt_ARG_ORIENTATION 745 scrolling to 790
Pt_ARG_TOOLBAR_FLAGS 745 selecting 803
Pt_ARG_TOOLBAR_LAYOUT_FLAGS 745 selection, clearing 781
Pt_ARG_TOOLBAR_SPACING 746 selection, getting 789, 804
spacing 746 selection, setting 805
PtToolbarGroup 749 showing 806
flags 750 unselecting 807
orientation 749 unselecting nonbrothers 808
Pt_ARG_ORIENTATION 749 Pt_ARG_LIST_COLUMN_ATTR 756
Pt_ARG_TG_FLAGS 750 Pt_ARG_LIST_COLUMN_POS 756
PtTree 753 Pt_ARG_SELECTION_MODE 762, 764,
balloon 765
enabling 769 Pt_ARG_TREE_BALLOON 759
function 759 Pt_ARG_TREE_COLUMN_ATTR 757,
location 769 760
callbacks Pt_ARG_TREE_COLUMN_IMGFUN
column-selection 758, 762 757, 760
drag and drop 769 Pt_ARG_TREE_FLAGS 769
selection 764 Pt_ARG_TREE_IMAGES 755, 761
state-change 765 Pt_ARG_TREE_IMGMASK 755, 761
column attributes 757, 760 Pt_CB_DND 769
column flags 756 Pt_CB_TREE_COLUMN_SEL 758, 762
column function 757, 760 Pt_CB_TREE_SELECTION 764
May 13, 2010 Index 1047

Pt_CB_TREE_STATE 765 color 814

PtDivider as child 756 drawing 812
selection mode 762, 764, 765 forcing display of 813
PtTree horizontal lines, number of 814
items opaque, over trends 812
changing 779 translucent 813
creating 783 vertical lines, number of 814
PtTreeAddAfter() 772 palette entries, range of 815
PtTreeAddFirst() 774 Pt_ARG_COLOR 811
PtTreeAddImages() 755, 776 Pt_ARG_FILL_COLOR 810
PtTreeAllItems() 777 Pt_ARG_TREND_ATTRIBUTES 810, 811
PtTreeAllocItem() 778 Pt_ARG_TREND_COLOR_LIST 810,
PtTreeCallback_t 762, 764 811, 815
PtTreeChangetem() 779 Pt_ARG_TREND_COUNT 812
PtTreeClearSelection() 781 Pt_ARG_TREND_DATA 812
PtTreeCollapse() 782 Pt_ARG_TREND_FLAGS 812
PtTreeColumnAttributes_t 760 Pt_ARG_TREND_GRID_COLOR 814
PtTreeCreateItem() 783 Pt_ARG_TREND_GRID_X 814
PtTreeDndCallback_t 186, 289, 593, 769 Pt_ARG_TREND_GRID_Y 814
PtTreeExpand() 785 Pt_ARG_TREND_INC 814
PtTreeFreeAllItems() 786 Pt_ARG_TREND_MAX 815
PtTreeFreeItems() 787 Pt_ARG_TREND_MIN 815
PtTreeGetCurrent() 788 Pt_ARG_TREND_PALETTE_END 815
PtTreeGetSelIndexes() 789 trends
PtTreeGoto() 790 data 812
PtTreeItem_t 753, 791 data, replacing 819
PtTreeItemAttributes_t 793 direction of movement 813
PtTreeItemIndex() 795 distance between points 814
PtTreeModifyItem() 796 drawing as pixels 813
PtTreeModifyItemString() 797 drawing over grid 813
PtTreeRemoveChildren() 798 horizontal 813
PtTreeRemoveItem() 800 maximum value 815
PtTreeRemoveList() 801 minimum value 815
PtTreeRootItem() 802 number of 812
PtTreeSelect() 803 vertical 813
PtTreeSelectedItems() 804 PtTrendChangeData() 819
PtTreeSetSelIndexes() 805 PtTrendChangeTrendData() 819
PtTreeShow() 806 PtTty 822
PtTreeUnselect() 807 argv[0], using program name as 828
PtTreeUnselectNonBrothers() 808 buffer 826
PtTrend 809 size 826
attributes 810 using 828
color list 811 callbacks
convenience functions 817 device resized 831
flags 812 output 832
grid process terminated 833
1048 Index May 13, 2010

characters Pt_ARG_TTY_SFD 830

number written to device 829 Pt_ARG_TTY_SPAWN_OPTIONS 831
to be written to device 829 Pt_ARG_TTY_WFD 831
COLUMNS 827 Pt_CB_TTY_DEVSIZE 831
command 826 Pt_CB_TTY_OUTPUT 832
convenience functions 837 Pt_CB_TTY_TERMINATED 833
device shell, returning name of 838
pathname 829 spawn options 831
resizing automatically 828 TERM 827
size 827 widget, resizing automatically 828
size, limiting to terminal 828 PtTtyOutput_t 832
size, same as terminal 828 PtTtyShell() 838
environment variables, modifying 827, 828 PtUpDown 839
exit status 827 arm color 840
file descriptor borders
all 827 width 841
read 830 decrement
resources 824 image 840, 841
set 828 flags 841
standard input, output, and error 830 increment
write 831 image 841
flags 828 indicator
LINES 827 spacing between 842
Photon pulses, priority 829 orientation 840
process Pt_ARG_ARM_COLOR 840
arguments 826 Pt_ARG_ORIENTATION 840
ID 829 Pt_ARG_UPDOWN_ARM_DATA_DECREMENT
program name, using asargv[0] 828 840
pseudo-tty device 830 Pt_ARG_UPDOWN_ARM_DATA_INCREMENT
Pt_ARG_FLAGS 822 841
Pt_ARG_TTY_ARGV 826 Pt_ARG_UPDOWN_BORDER_WIDTH 841
Pt_ARG_TTY_BUFFER 826 Pt_ARG_UPDOWN_DATA_DECREMENT
Pt_ARG_TTY_BUFLEN 826 841
Pt_ARG_TTY_CMD 826 Pt_ARG_UPDOWN_DATA_INCREMENT
Pt_ARG_TTY_DEVSIZE 827 841
Pt_ARG_TTY_EXIT_STATUS 827, 833 Pt_ARG_UPDOWN_FLAGS 841
Pt_ARG_TTY_FDS 827 Pt_ARG_UPDOWN_INDICATOR_MARGIN
Pt_ARG_TTY_FDSET 828 842
Pt_ARG_TTY_FLAGS 828 Pt_CB_ACTIVATE 844
Pt_ARG_TTY_INPUT 829 Pt_CB_ARM 844
Pt_ARG_TTY_INPUT_WRITTEN 829 Pt_CB_DISARM 844
Pt_ARG_TTY_PATH 829 Pt_UPDOWN_DECREMENT_ARM_IMAGE
Pt_ARG_TTY_PID 827, 829 841
Pt_ARG_TTY_PRI 829 Pt_UPDOWN_DECREMENT_IMAGE 841
Pt_ARG_TTY_PSEUDO 830 Pt_UPDOWN_FILL_ON_ARM 842
Pt_ARG_TTY_RFD 830
May 13, 2010 Index 1049

Pt_UPDOWN_INCREMENT_ARM_IMAGE HTTP 870

841 HTTP cookie 868
Pt_UPDOWN_INCREMENT_IMAGE 841 image 870
Pt_UPDOWN_ROTATE_INDICATORS 842 miscellaneous 873
PtWebAuthenticateCallback_t 891 print 871
PtWebClient 845 SOCKS 872
callbacks TCP/IP 872
authentication 891 page
certificates 898 loading, stopping 889
closing window 892 navigation 862
file requested 893 printing 887
file, unknown 912 reloading 887
loading complete 892 Pt_ARG_WEB_ACTIVATE_LINK 849
loading error 895 Pt_ARG_WEB_AUTHENTICATE 849
metadata 899 Pt_ARG_WEB_BUILD_DATE 850
new window 901 Pt_ARG_WEB_COMMAND 850
page information 902 Pt_ARG_WEB_DATA 852
right-click 893 Pt_ARG_WEB_DOWNLOAD 854
scrolling 900 Pt_ARG_WEB_ENCODING 854
SSL certification 902 Pt_ARG_WEB_GET_CERTIFICATES
SSL client error 907 855
SSL error 908 Pt_ARG_WEB_GET_CONTEXT 855
SSL nontrusted 904 Pt_ARG_WEB_GET_HISTORY 856
start loading 909 Pt_ARG_WEB_GET_URL 846, 857
status 910 Pt_ARG_WEB_H_ERRNO 859
URL being loaded 913 Pt_ARG_WEB_HELPER 858
certificate information 859 Pt_ARG_WEB_IMPORT_CERTIFICATE
certificates 855 859
client protocol data stream 852 Pt_ARG_WEB_NAVIGATE_FRAME 860
context information 855 Pt_ARG_WEB_NAVIGATE_LINK 861
DNS errors 859 Pt_ARG_WEB_NAVIGATE_PAGE 862
downloads 894 Pt_ARG_WEB_OPTION 863
encoding 854 Pt_ARG_WEB_PRINT 887
external helpers 858 Pt_ARG_WEB_RELOAD 887
file, downloading 854 Pt_ARG_WEB_SERVER 845, 887
frame navigation 860 Pt_ARG_WEB_SERVER_PID 889
link Pt_ARG_WEB_SSL_RESPONSE 889
deactivating 849 Pt_ARG_WEB_STARTUP_ERRNO 846,
navigation 861 889
options Pt_ARG_WEB_STOP 889
authentication 869 Pt_ARG_WEB_UNKNOWN_RESP 890
disk-cache 873 Pt_ARG_WEB_VERSION 890
file 870 Pt_CB_WEB_AUTHENTICATE 891
FTP 869 Pt_CB_WEB_CLOSE_WINDOW 892
Gopher 869 Pt_CB_WEB_COMPLETE 892
HTML 864 Pt_CB_WEB_CONTEXT 893
1050 Index May 13, 2010

Pt_CB_WEB_DATA_REQ 893 PtWebDownloadCallback_t 895

Pt_CB_WEB_DOWNLOAD 894 PtWebErrorCallback_t 896
Pt_CB_WEB_ERROR 895 PtWebImportCertificateCallback_t
Pt_CB_WEB_IMPORT_CERTIFICATE 898 899
Pt_CB_WEB_METADATA 899 PtWebMetaDataCallback_t 899
Pt_CB_WEB_NEED_SCROLL 900 PtWebNeedScrollCallback_t 900
Pt_CB_WEB_NEW_WINDOW 901 PtWebPageInfoCallback_t 902
Pt_CB_WEB_PAGE_INFO 902 PtWebSSLCertInfoCallback_t 903
Pt_CB_WEB_SSL_CERTINFO 902 PtWebSSLCertNonTrustedCallback_t
Pt_CB_WEB_SSL_CERTNONTRUSTED 904
904 PtWebSSLClientCertCallback_t 907
Pt_CB_WEB_SSL_CLIENT_CERT_SELECT PtWebSSLErrorCallback_t 908
907 PtWebStatusCallback_t 910
Pt_CB_WEB_SSL_ERROR 908 PtWebUnknownCallback_t 912
Pt_CB_WEB_START 909 PtWebUrlCallback_t 913
Pt_CB_WEB_STATUS 910 PtWebWindowCallback_t 901
Pt_CB_WEB_UNKNOWN 912 PtWidget 917
Pt_CB_WEB_URL 913 activation by any mouse button 925
scrolling 862 anchor flags 920, 921
server anchor offsets 920, 921
authentication information 849 area 917, 922
build date 850 autohighlighting 925
command 850 balloons
options 863 popping up immediately 920
path 845, 887 bevel width 922
process ID 889 blocking 925
unknown response 890 callbacks
version 890 blocked 933
site history list 856 destroyed 934, 938
SSL (Secure Sockets Layer) response 889 drag-and-drop 934
starting 845 filter 936
startup errors 846, 889 hotkey 937
URL 846, 857 outbound 938
PtWebClient2AuthenticationData_t raw event 939
849 unrealized 940
PtWebClient2Command_t 850 callbacks, invoking when resources are set
PtWebClient2Data_t * 852 925
PtWebClient2HelperData_t 858 cursor
PtWebClient2SSLResponse_t 906, 909 bitmap 922
PtWebClient2SSLResponse_t * 889 color 922
PtWebClient2UnknownData_t 890 type 923
PtWebClientHistory_t 856 damage
PtWebClientHistoryData_t 856 indicating for family 925
PtWebCompleteCallback_t 892 indicating for widget 925
PtWebContextCallback_t 893 propagating to parent 924
PtWebDataReqCallback_t 894 destruction, marked for 925
May 13, 2010 Index 1051

dimensions 917, 922, 923 Pt_ARG_POINTER 918, 930

maximum 930 Pt_ARG_POS 918, 931
minimum 930 Pt_ARG_RESIZE_FLAGS 931
events, consuming 924 Pt_ARG_ROW_LAYOUT_DATA 918, 932
extended flags 924 Pt_ARG_USER_DATA 918, 933
extent 917, 924 Pt_ARG_WIDTH 918, 933
extent, no intersections with 925 Pt_CB_BLOCKED 933
flags 925 Pt_CB_DESTROYED 934
flux 926 Pt_CB_DND 934
focus, granting 926 Pt_CB_FILTER 936
ghosting 926 Pt_CB_HOTKEY 937
height 917, 922, 923, 929 Pt_CB_IS_DESTROYED 938
maximum 930 Pt_CB_OUTBOUND 938
minimum 930 Pt_CB_RAW 939
help information 924, 929 Pt_CB_REALIZED 940
highlighting Pt_CB_UNREALIZED 940
automatically 925 realizing
clipping corners 925 callback 940
requesting 926 delaying 925
layouts indicating completion 926
skipping 924 indicating in progress 926
menu button 926 whenever resources are set 927
menuable 926 redrawing, preventing 926
obscured 926 region, forcing to have 926
opaque 926 render focus 926
position 917, 922, 931 resizing
procreated child 926 flags 931
Pt_ARG_ANCHOR_FLAGS 920, 921 whenever resources are set 927
Pt_ARG_ANCHOR_OFFSETS 920, 921 selectable 926
Pt_ARG_AREA 917, 921, 922 set state 927
Pt_ARG_BEVEL_WIDTH 922 toggling, enabling 927
Pt_ARG_BITMAP_CURSOR 922 user-defined data 918, 930, 933
Pt_ARG_CURSOR_COLOR 922 width 917, 922, 923, 933
Pt_ARG_CURSOR_TYPE 923 maximum 930
Pt_ARG_DATA 923 minimum 930
Pt_ARG_DIM 917, 921, 923 x, y coordinates 917, 922, 931
Pt_ARG_EFLAGS 924, 929 PtWidgetClassStyle_t 45
Pt_ARG_EXTENT 917, 924 PtWidgetFlags() 925
Pt_ARG_FLAGS 925 PtWindow 941
Pt_ARG_GRID_LAYOUT_DATA 917, active color 946
927 Alt function key combinations 950
Pt_ARG_HEIGHT 917, 929 application 949
Pt_ARG_HELP_TOPIC 929 backdrop 947, 950
Pt_ARG_LAYOUT_DATA 917, 930 block input 950
Pt_ARG_MAXIMUM_DIM 917, 930 border 949
Pt_ARG_MINIMUM_DIM 917, 930 callbacks
1052 Index May 13, 2010

opening 953 Pt_ARG_WINDOW_FLAGS 946

transport 954 Pt_ARG_WINDOW_FRONT_WINDOW 947
window event 952 Pt_ARG_WINDOW_HELP_ROOT 947
close button 949 Pt_ARG_WINDOW_INACTIVE_COLOR 947
closing 947 Pt_ARG_WINDOW_MANAGED_FLAGS
callback 952 943, 947
collapse button 949 Pt_ARG_WINDOW_NOTIFY_FLAGS
collapsing to title bar 947, 951 944, 948
convenience functions 957 Pt_ARG_WINDOW_RENDER_FLAGS
cursors, overriding children’s 139 942, 949
cycling focus 947 Pt_ARG_WINDOW_STATE 950
dialog 949 Pt_ARG_WINDOW_TITLE 951
flags 946 Pt_ARG_WINDOW_TITLE_COLOR 952
managed 943, 947 Pt_CB_WINDOW 952
notify 944, 948 Pt_CB_WINDOW_CLOSING 952
render 942, 949 Pt_CB_WINDOW_OPENING 953
focus Pt_CB_WINDOW_TRANSPORT 954
gaining and losing 947 resizing 943, 947
giving 958 handles 950
giving when opened 951 restoring 947
force front 947, 951 sending to back 947, 960
height sending to front 947, 961
maximum 945 state 950
minimum 946 getting 959
help subwindows 944
button 949 switching consoles automatically 947
context-sensitive 947 taskbar, including in 947
root 947 title
hiding 947, 951 bar 950
icon 949 color 952
iconifying 951 text 951
in front 951 width
inactive color 947 maximum 945
inline 950 minimum 946
maximize button 950 window in front 947
maximizing 947, 951 window manager 942
menu button 950 window menu 947
minimize button 950 PtWindowFocus() 958
moving 947 PtWindowGetState() 959
palette 949 PtWindowToBack() 960
Pt_ARG_CURSOR_OVERRIDE 139 PtWindowToFront() 961
Pt_ARG_MAX_HEIGHT 945 pushbutton widget See PtButton
Pt_ARG_MAX_WIDTH 945 PWM 941
Pt_ARG_MIN_HEIGHT 946
Pt_ARG_MIN_WIDTH 946
Pt_ARG_WINDOW_ACTIVE_COLOR 946
May 13, 2010 Index 1053

R servers See PtServer

set state 927
range-select mode 241 Pt_CB_ACTIVATE 46
raw callbacks 11, 939 shared memory 514
raw drawing widget See PtRaw Shift-click selection 241
raw list See PtRawList single-select mode 241
raw tree See PtRawTree slider widget See PtSlider
realizing space, sharing among widgets See PtDivider
delaying 925 style 44
done 926 superclass widget See PtWidget
in progress 926 support, technical xviii
Pt_CB_REALIZED 940
whenever resources are set 927
rebuilding 927
rectangle widget See PtRect T
redrawing, preventing 926
region Tab character, use as column separator 372, 756
forcing a widget to have 926 tab widget See PtTab
region widget See PtRegion technical support xviii
render shared library 514 terminal emulator widget See PtTerminal
replace mode 704 attached to a device See PtTty
resizing TEXT 849
callback 148 text widget
flags 931 label See PtLabel
and anchor flags 932 multiline See PtMultiText
policy 324, 931 single-line See PtText
whenever resources are set 927 with list of choices See PtComboBox
resources TEXTAREA 849
inheritance of 16 threshold, graphics bandwidth 37
types 20 time widget See PtClock
reverse gradient timer widget See PtTimer
fill 39 toggle button widget See PtToggleButton
row widget See PtGroup toggling
enabling 927
Pt_CB_ACTIVATE 46
state, checking 46
S toolbars See PtToolbarGroup, See
PtToolbar
scroll area widget See PtScrollArea transparency pattern 45, 327
scrollable container widget See Tree Item State method
PtScrollContainer tree widgets 296, 298
scrollbar widget See PtScrollbar tree widget
selecting general purpose See PtTree
enabling 926 superclass See also PtGenTree
widgets 34 tree widgets
selection mode 240 methods
separator widget See PtSeparator Tree Item State 296, 298
1054 Index May 13, 2010

tree, raw See PtRawTree X

trend widget See PtMTrend, See PtTrend
TRY_AGAIN 859 x, y coordinates 917, 922, 931
typographical conventions xvii
U
unrealizing
Pt_CB_UNREALIZED 940
up/down button widget See PtUpDown
UPDOWN_BOTTOM 844
UPDOWN_LEFT 844
UPDOWN_RIGHT 844
UPDOWN_TOP 844
user-defined data 739, 918, 930, 933
PtRaw 569
V
vector graphics 322
viewport widget See PtScrollArea, See
PtScrollContainer
Voyager Web Server 845
W
web browser
see PtWebClient 845
web server 845
wedge 23
widget See also PtWidget
description, contents of 19
hierarchy 15
widgets
icon in PhAB 16
width 917, 922, 923, 933
maximum 917, 930
minimum 917, 930
window manager 941
window widget See PtWindow
May 13, 2010 Index 1055

Widget Ref

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Widget Ref

Uploaded by

Copyright:

Available Formats

® ®

QNX Neutrino Realtime Operating System

For QNX ® Neutrino® 6.5.0

© 2010, QNX Software Systems GmbH & Co. KG.

About This Reference xv

1 Global Data Structures 1

May 13, 2010 Contents iii

iv Contents May 13, 2010

May 13, 2010 Contents v

vi Contents May 13, 2010

May 13, 2010 Contents vii

viii Contents May 13, 2010

A What’s New 963

May 13, 2010 Contents ix

What’s new in Photon for QNX Neutrino 6.1.0 972

x Contents May 13, 2010

May 13, 2010 List of Figures xi

A PtMenuBar that contains several menu buttons. 411

xii List of Figures May 13, 2010

A PtWindow widget that contains an editor application. 941

May 13, 2010 List of Figures xiii

May 13, 2010 About This Reference xv

What you’ll find in this guide

For information about: See:

May 13, 2010 About This Reference xvii

You’ll find the Other... menu item under Perspective→Show View.

We use notes, cautions, and warnings to highlight important messages:

Notes point out something important or useful.

WARNING: Warnings tell you about commands or procedures that could be

Note to Windows users

xviii About This Reference May 13, 2010

May 13, 2010 Chapter 1 • Global Data Structures 1

The Photon API defines various data types and structures:

• If you’re not using PhAB, include <Pt.h>.

This chapter describes the data structures listed below:

PtCallback_t Regular callback structure

The following datatypes are described in the Photon Library Reference:

ApInfo_t PhAB information structure

PgColor_t Composite color value

PgColorHSV_t Hue-Saturation-Value color value

PhArea_t Position and dimensions of a rectangular area

PhClipboardHdr Clipboard header structure

PhDim_t Dimensions of an area

PhImage_t Data and characteristics of an image

PhPoint_t Coordinates of a single point

PhRect_t Coordinates of a rectangle

May 13, 2010 Chapter 1 • Global Data Structures 3

PhTile_t A list of rectangles

PtDndFetch_t Structure that defines data types a widget accepts from a

PtFDProc_t Type for defining a file-descriptor function

PtSignalProc_t Type for defining a signal-handling function

PtWorkProc_t Type for defining a work procedure function

4 Chapter 1 • Global Data Structures May 13, 2010

widget A pointer to the widget the callback is being attached to.

event_f A pointer to an inflate/deflate function that’s called whenever a balloon

wgt A pointer to the widget whose balloon is being affected.

May 13, 2010 Chapter 1 • Global Data Structures 5

event_f A pointer to the callback function.

A PhAB callback takes as its second argument a pointer to an ApInfo_t structure.

6 Chapter 1 • Global Data Structures May 13, 2010

May 13, 2010 Chapter 1 • Global Data Structures 7

event A pointer to a PhEvent_t structure that describes the event that

cbdata A pointer to callback-specific data.

8 Chapter 1 • Global Data Structures May 13, 2010