Photon microGUI

Widget Reference

For Photon 1.14

 2005, QNX Software Systems

 1996 – 2005, QNX Software Systems. 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: [email protected]
Web: http://www.qnx.com/

Publishing history
December 1996 First edition
April 1998 Second edition

Technical support options

To obtain technical support for any QNX product, visit the Technical Support section in the Support area on our website
(www.qnx.com). You’ll find a wide range of support options, including our free web-based QNX Developer’s Network.

QNX, Photon microGUI, and Neutrino are registered trademarks, and Jump Gate Connectivity is a trademark, of QNX Software Systems in certain jurisdictions.
All other trademarks and registered trademarks belong to their respective owners.
 Contents

About This Reference xv

Typographical conventions xvii
Note to Windows users xviii
What you’ll find in this reference xix

1 Global Data Structures 1

PtBalloonCallback t 5
PtCallback t 7
PtCallbackInfo t 9
PtHotkeyCallback t 11
PtRawCallback t 13

2 Widgets 15
Widget hierarchy 17
Common widget flags 18
What’s in a widget description? 22
AwFileSelect 26
AwMessage 33
PtArc 38
PtBasic 43
PtBezier 56
PtBitmap 60
PtBkgd 69
PtButton 79
PtCalendar 86

September 20, 2005 Contents iii

  2005, QNX Software Systems

PtClock 98
PtComboBox 109
PtComboBoxListClose() 123
PtComboBoxListOpen() 124
PtCompound 125
PtContainer 128
PtDBContainer 139
PtDivider 143
PtEllipse 151
PtFileSel 154
PtFSAddAfter() 178
PtFSAddFirst() 179
PtFSAllItems() 181
PtFSAllocItem() 182
PtFSClearSelection() 185
PtFSDamageItem() 186
PtFSExpandParents() 187
PtFSFolderCollapse() 188
PtFSFolderExpand() 189
PtFSFreeAllItems() 190
PtFSFreeItems() 191
PtFSGetCurrent() 192
PtFSGetSelIndexes() 193
PtFSGoto() 194
PtFSItemIndex() 195
PtFSRemoveChildren() 196
PtFSRemoveItem() 197
PtFSRemoveList() 198
PtFSRootItem() 199
PtFSSelect() 200
PtFSSelectedItems() 201
PtFSSetSelIndexes() 202

iv Contents September 20, 2005

 2005, QNX Software Systems

PtFSShow() 203
PtFSUnselect() 204
PtFSUnselectNonBrothers() 205
PtFontSel 206
PtGauge 212
PtGenList 218
PtGenListCreateTextBalloon() 236
PtGenListItem t 238
PtGenListSetColumnBalloon() 240
PtGenTree 241
PtGenTreeItem t 248
PtGraphic 251
PtGrid 276
PtGroup 281
PtHtml 289
PtHtmlLink() 309
PtHtmlTitle() 310
PtIcon 311
PtLabel 316
PtLine 333
PtList 337
PtListAddItems() 351
PtListDeleteAllItems() 352
PtListDeleteItemPos() 353
PtListDeleteItems() 354
PtListGotoPos() 355
PtListItemExists() 356
PtListItemPos() 357
PtListRemovePositions() 358
PtListReplaceItemPos() 359
PtListReplaceItems() 360
PtListSelectPos() 361

September 20, 2005 Contents v

  2005, QNX Software Systems

PtListShowPos() 362
PtListUnselectPos() 363
PtMenu 364
PtMenuBar 382
PtMenuButton 386
PtMessage 392
PtMessageGetWindow() 397
PtMultiText 398
PtMultiLines t 429
PtMultiTextAttributes t 431
PtMultiTextCallback t, PtMultiTextControl t,
PtMultiTextInfo t 433
PtMultiTextCreateAttributes() 435
PtMultiTextGetAttributes() 436
PtMultiTextInfo() 440
PtMultiTextLine t 443
PtMultiTextModifyAttributes() 445
PtMultiTextModifyText() 447
PtMultiTextQuery t 449
PtMultiTextSegment t 451
PtNumeric 453
PtNumericFloat 462
PtNumericInteger 470
PtOnOffButton 477
PtPane 482
PtPixel 486
PtPolygon 489
PtPrintSel 494
PtRaw 501
PtRect 509
PtRegion 513
PtScrollArea 521
PtScrollbar 534

vi Contents September 20, 2005

 2005, QNX Software Systems

PtSeparator 545
PtSlider 549
PtTab 561
PtTerminal 566
PtTerminalCharset t, PtTerminalCharsets t 605
PtTerminalCopy() 608
PtTerminalCreateCsXlat() 609
PtTerminalDefaultCharsets() 611
PtTerminalFont() 612
PtTerminalGetKeys() 614
PtTerminalGetSelection() 616
PtTerminalName() 617
PtTerminalPasteClipboard() 618
PtTerminalPasteSelection() 619
PtTerminalPut(), PtTerminalPutc(), PtTerminalPuts() 620
PtTerminalSelectWord() 622
PtText 623
PtTextCallback t, PtTextControl t,
PtTextControlInfo t 653
PtTextGetSelection() 655
PtTextModifyText() 656
PtTextSetSelection() 658
PtTimer 660
PtToggleButton 663
PtTree 671
PtTreeAddAfter() 686
PtTreeAddFirst() 688
PtTreeAddImages() 690
PtTreeAllItems() 691
PtTreeAllocItem() 693
PtTreeClearSelection() 695
PtTreeCollapse() 696
PtTreeExpand() 697

September 20, 2005 Contents vii

  2005, QNX Software Systems

PtTreeFreeAllItems() 699
PtTreeFreeItems() 700
PtTreeGetCurrent() 701
PtTreeGetSelIndexes() 702
PtTreeGoto() 704
PtTreeItem t 705
PtTreeItemIndex() 707
PtTreeModifyItem() 708
PtTreeRemoveChildren() 710
PtTreeRemoveItem() 712
PtTreeRemoveList() 714
PtTreeRootItem() 716
PtTreeSelect() 717
PtTreeSelectedItems() 718
PtTreeSetSelIndexes() 720
PtTreeShow() 721
PtTreeUnselect() 723
PtTreeUnselectNonBrothers() 724
PtTty 725
PtTtyShell() 743
PtUpDown 744
PtWidget 753
PtWindow 770
PtWindowFocus() 793
PtWindowGetState() 795
PtWindowToBack() 797
PtWindowToFront() 799
RtMeter 801
RtProgress 816
RtTrend 820
RtTrendChangeData(), RtTrendChangeTrendData() 832

viii Contents September 20, 2005

 2005, QNX Software Systems

Glossary 835

Index 857

September 20, 2005 Contents ix

 List of Figures
The Photon widget hierarchy. 17
An AwFileSelect widget. 26
An AwMessage widget. 33
A typical AwMessage widget with three buttons. 35
Arcs, circles, ellipses, wedges, and chords created by PtArc.
38
A Bézier curve created by PtBezier. 56
Bitmapped images. 60
A background image. 69
A PtButton widget. 79
A PtCalendar widget. 86
Analog, digital, and LED clocks created by PtClock. 98
A PtComboBox widget provides a text-entry area and a list of
choices. 109
Two PtDivider widgets: one contains a scroll area and two lists,
the other contains some buttons. 143
A PtEllipse widget. 151
A PtFileSel widget. 154
A single-level file selector. 157
A PtFontSel widget. 206
A five-pointed star before clipping. 254
The star after clipping. 255
A PtGrid widget. 276
A group of buttons. 281
A PtHtml widget. 289
An icon. 311

September 20, 2005 List of Figures xi

  2005, QNX Software Systems

A text string in a PtLabel widget. 316

A PtLine widget. 333
A PtList containing text items. 337
A PtMenu widget that contains various menu items. 364
A PtMenuBar that contains several menu buttons. 382
A PtMenuButton widget. 386
A PtMessage widget. 392
A PtMultiText widget. 398
A PtNumericFloat widget. 462
A PtNumericInteger widget. 470
A PtOnOffButton widget. 477
A dialog box featuring several PtPane widgets. 482
PtPolygon can display open or closed polygons. 489
A PtPrintSel widget. 494
A PtRect widget. 509
A PtScrollArea widget acts as a viewport. 522
A PtScrollbar widget. 534
PtSeparator widgets are frequently used to organize the items
in a menu. 545
A PtSlider widget. 549
A group of PtTab widgets positioned at the top of a PtPane.
561
A PtTerminal widget. 566
A PtText widget. 623
Various button styles supported by PtToggleButton. 663
The Photon Helpviewer uses a PtTree widget to give you quick
access to documentation. 672
The Pt ARG TREE FLAGS for a PtTree widget. 683
The results of using PtTreeAddAfter(). 686
The results of using PtTreeAddFirst(). 688
The results of using PtTreeRemoveChildren(). 710
The results of using PtTreeRemoveItem(). 712
The results of using PtTreeRemoveList(). 714

xii List of Figures September 20, 2005

 2005, QNX Software Systems

Output from a terminal device. 725

A PtUpDown widget. 744
A PtWindow widget. 770
An RtMeter widget. 801
A one-arc RtMeter widget. 803
An RtProgress bar. 816
An RtTrend widget. 820
Replacing trend samples with RtTrendChangeData() or
RtTrendChangeTrendData(). 833

September 20, 2005 List of Figures xiii

 About This Reference

September 20, 2005 About This Reference xv

 2005, QNX Software Systems Typographical conventions

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:
Programming constants NULL
Programming data types unsigned short
Programming literals 0xFF, "message string"
Variable names stdin
User-interface components Cancel

We format single-step instructions like this:

➤ To reload the current page, press Ctrl – R.

We use an arrow (→) in directions for accessing menu items, like this:

September 20, 2005 About This Reference xvii

Typographical conventions  2005, QNX Software Systems

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.

xviii About This Reference September 20, 2005

 2005, QNX Software Systems What you’ll find in this reference

What you’ll find in this reference

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

For: See:
Information about data structures Global Data Structures
A diagram of the widget class hierarchy Widgets
Descriptions of common flags Widgets
An alphabetical list of all flags Widgets
An overview of what’s in a widget Widgets
description
Descriptions of widget classes Widgets
Explanations of Photon terms Glossary

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

☞ This reference doesn’t include contributed widgets. You’ll find the

documentation for them (if any) in the source files in
/qnx4/phtk/src/contrib.

September 20, 2005 About This Reference xix

 Chapter 1
Global Data Structures

September 20, 2005 Chapter 1 ¯ Global Data Structures 1

 2005, QNX Software Systems

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:

ApBitmap t PhAB bitmap structure

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

PhDim t Dimensions of an area

September 20, 2005 Chapter 1 ¯ Global Data Structures 3

  2005, QNX Software Systems

PhClipHeader Clipboard header structure

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 Which resource is affected when you get or set

resources

PtFDProc t Pointer to a file-descriptor function

PtInputCallbackProc t
Pointer to a input callback function

PtSignalProc t
Pointer to a signal-handling function

PtWorkProc t Pointer to a work procedure function

4 Chapter 1 ¯ Global Data Structures September 20, 2005

 2005, QNX Software Systems 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 the following members:

widget Pointer to the widget the callback is being attached to.

event f 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 Pointer to the widget whose balloon is being

affected.
data A value of 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 — the balloon should
be made visible
¯ Pt POP BALLOON — the balloon should be
removed.

September 20, 2005 Chapter 1 ¯ Global Data Structures 5

PtBalloonCallback t  2005, QNX Software Systems

Classification:
Photon

See also:
PtCallbackInfo t, PtContainer

6 Chapter 1 ¯ Global Data Structures September 20, 2005

 2005, QNX Software Systems PtCallback t
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 Data that’s passed 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.
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.

September 20, 2005 Chapter 1 ¯ Global Data Structures 7

PtCallback t  2005, QNX Software Systems

☞ A PhAB callback takes as its second argument a pointer to an

ApInfo t structure. For more information, see the Photon Library
Reference.

Callback functions should return Pt CONTINUE unless the description

of the widget’s callback resource gives you a reason to return
something else.

Classification:
Photon

See also:
PtBalloonCallback t, PtCallbackInfo t,
PtHotkeyCallback t, PtRawCallback t
ApInfo t, PtAddCallbacks(), PtCreateWidget() in the Photon
Library Reference
“Manipulating callbacks in your code” in the Creating Widgets in
Application Code chapter of the Photon Programmer’s Guide.

8 Chapter 1 ¯ Global Data Structures September 20, 2005

 2005, QNX Software Systems PtCallbackInfo t
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 the user caused the widget to invoke its
Pt CB ACTIVATE callback, then reason would be
Pt CB ACTIVATE.
reason subtype
If there are different ways to invoke the callback, this
member indicates which one.

event A pointer to the 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

September 20, 2005 Chapter 1 ¯ Global Data Structures 9

PtCallbackInfo t  2005, QNX Software Systems

See also:
PtBalloonCallback t, PtCallback t, PtHotkeyCallback t,
PtRawCallback t
PhEvent t in the Photon Library Reference

10 Chapter 1 ¯ Global Data Structures September 20, 2005

 2005, QNX Software Systems 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 *,
PtCallbackInfo t * );
} 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 sym; 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
hot keys.

key mods Key modifiers that must be active for the key to be
considered a hotkey. If the

September 20, 2005 Chapter 1 ¯ Global Data Structures 11

PtHotkeyCallback t  2005, QNX Software Systems

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 widget is NULL when the hotkey
is attached, it’s set to the widget to which the hotkey
is attached.

data Passed as the second parameter to the callback

function when that function is invoked.

event f Pointer to the hotkey function. If event f is NULL

when the hotkey is activated, the widget to which
the hotkey is attached has its Pt CB ACTIVATE
callback invoked with a reason subtype of
Pt CB HOTKEY.

Classification:
Photon

See also:
PtBalloonCallback t, PtCallback t, PtCallbackInfo t,
Pt CB HOTKEY (PtWidget), PtRawCallback t

12 Chapter 1 ¯ Global Data Structures September 20, 2005

 2005, QNX Software Systems PtRawCallback t
Event handler structure

Synopsis:
typedef struct Pt raw callback {
unsigned long event mask;
int (*event f )( PtWidget t *, void *,
PtCallbackInfo t * );
void *data;
} PtRawCallback t;

Description:
The PtRawCallback t structure lets you specify event handlers for
various widgets. You use this structure when setting the Pt CB RAW
resource of any widget (see PtWidget) or calling
PtAddEventHandler().
This structure contains at least the following members:

event mask Which events will trigger the function specified in

event f . See PhEvent t in the Photon Library
Reference.

event f Pointer to the callback function.

data Data that’s passed as the second parameter to the

callback function when that function is invoked.

Classification:
Photon

See also:
PtBalloonCallback t, PtCallback t, PtCallbackInfo t,
Pt CB RAW (PtWidget), PtHotkeyCallback t

September 20, 2005 Chapter 1 ¯ Global Data Structures 13

 Chapter 2
Widgets

September 20, 2005 Chapter 2 ¯ Widgets 15

 2005, QNX Software Systems Widget hierarchy

Widget hierarchy
PtWidget AwFileSelect
AwMessage
PtBasic PtBitmap
PtCalendar
PtClock
PtContainer PtCompound PtComboBox
PtDivider
PtGenList PtGenTree PtFileSel
PtTree
PtList
PtMenuButton
PtMultiText
PtNumeric PtNumericFloat
PtNumericInteger
PtDBContainer
PtFontSel
PtGroup PtMenu
PtMenuBar
PtMessage
PtHtml
PtPane PtBkgd
PtPrintSel
PtRegion
PtScrollArea
PtTerminal PtTty
PtUpDown
PtWindow PtIcon
PtGauge PtSlider
RtProgress
PtGraphic PtArc
PtBezier
PtEllipse
PtLine
PtPixel
PtPolygon
PtRect
PtGrid
PtLabel PtButton PtTab
PtMenuLabel
PtText
PtToggleButton PtOnOffButton
PtRaw
PtScrollbar
PtSeparator
RtMeter
RtTrend
PtTimer

The Photon widget hierarchy.

September 20, 2005 Chapter 2 ¯ Widgets 17

Common widget flags  2005, QNX Software Systems

☞ 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.

Common widget flags

Many widgets define flags resources that allow you to change the
widget’s appearance and/or behavior. This section discusses the flags
used by all or most widget classes.

When you want to: Use this bit: See:

Have a widget consume events Pt CONSUME EVENTS PtWidget
(Pt ARG EFLAGS)
Display help information in a Pt INTERNAL HELP PtWidget
balloon, not in the Helpviewer (Pt ARG EFLAGS)
Propagate damage to a widget’s Pt DAMAGE PARENT PtWidget
parent (Pt ARG EFLAGS)
Invoke certain callbacks when Pt CALLBACKS ACTIVE PtWidget
setting resources (Pt ARG FLAGS)
Use any mouse button to Pt ALL BUTTONS PtWidget
activate a widget (Pt ARG FLAGS)
Have a widget highlight and Pt AUTOHIGHLIGHT PtWidget
get focus when pointed to (Pt ARG FLAGS)
Block a widget and its Pt BLOCKED PtWidget
non-window children (Pt ARG FLAGS)
Prevent brothers in front of a Pt CLEAR (Pt ARG FLAGS) PtWidget
widget from intersecting with
its extent

continued. . .

18 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems Common widget flags

When you want to: Use this bit: See:

Clip the corners of a widget’s Pt CLIP HIGHLIGHT PtWidget
highlighting rectangle (Pt ARG FLAGS)
Determine if the widget needs Pt DAMAGED PtWidget
to be repaired (Pt ARG FLAGS)
Determine if a widget and its Pt DAMAGE FAMILY PtWidget
family need repairing (Pt ARG FLAGS)
Delay realization until done Pt DELAY REALIZE PtWidget
explicitly (Pt ARG FLAGS)
Determine if a widget is Pt DESTROYED PtWidget
marked for destruction (Pt ARG FLAGS)
Highlight a widget with an Pt ETCH HIGHLIGHT PtWidget
etched-line style (Pt ARG FLAGS)
Clip the corners of a widget’s Pt CLIP HIGHLIGHT PtWidget
highlighting rectangle (Pt ARG FLAGS)
Automatically free any Pt FREE MEMORY PtWidget
memory associated with a (Pt ARG FLAGS)
widget
Draw a dotted line around a Pt FOCUS RENDER PtWidget
widget to indicate focus (Pt ARG FLAGS)
Grant focus to a widget when Pt GETS FOCUS PtWidget
appropriate (Pt ARG FLAGS)
Dim a widget Pt GHOST (Pt ARG FLAGS) PtWidget
Highlight a widget with a Pt HIGHLIGHTED PtWidget
beveled or etched rectangle (Pt ARG FLAGS)
Determine if a call to Pt IN FLUX (Pt ARG FLAGS) PtWidget
PtContainerHold() has been
made on a widget

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 19

Common widget flags  2005, QNX Software Systems

When you want to: Use this bit: See:

Have a widget respond to Pt MENUABLE PtWidget
right-mouse-button clicks (Pt ARG FLAGS)
Indicate that a widget is a menu Pt MENU BUTTON PtWidget
item (Pt ARG FLAGS)
Determine if a widget is Pt OBSCURED PtWidget
completely hidden by its (Pt ARG FLAGS)
brothers
Determine if a widget Pt OPAQUE (Pt ARG FLAGS) PtWidget
completely obscures anything
behind it
Determine if a widget is a Pt PROCREATED PtWidget
procreated child of a compound (Pt ARG FLAGS)
widget
Determine if a widget is Pt REALIZED PtWidget
realized (Pt ARG FLAGS)
Determine if a widget is in the Pt REALIZING PtWidget
process of being realized (Pt ARG FLAGS)
Force a widget to have a region Pt REGION (Pt ARG FLAGS) PtWidget
Allow the user to select a Pt SELECTABLE PtWidget
widget (Pt ARG FLAGS)
Prevent a widget from Pt SELECT NOREDRAW PtWidget
changing its appearance when (Pt ARG FLAGS)
selected
Determine if a widget is “set” Pt SET (Pt ARG FLAGS) PtWidget
Make a widget toggle between Pt TOGGLE (Pt ARG FLAGS) PtWidget
set and unset when selected
Determine if a widget will be Pt WIDGET REBUILD PtWidget
rerealized when resource (Pt ARG FLAGS)
changes are applied

continued. . .

20 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems Common widget flags

When you want to: Use this bit: See:

Determine if a widget will be Pt WIDGET RESIZE PtWidget
resized when resource changes (Pt ARG FLAGS)
are applied
Control how a widget is resized All bits PtWidget
(Pt ARG RESIZE FLAGS)
Prevent balloons from being Pt DISABLE BALLOONS PtContainer
inflated in a container and its (Pt ARG CONTAINER FLAGS)
child containers
Prevent hotkey searches from Pt HOTKEY TERMINATOR PtContainer
going to parents of a container (Pt ARG CONTAINER FLAGS)
Process key events as hotkeys Pt HOTKEYS FIRST PtContainer
before passing them to children (Pt ARG CONTAINER FLAGS)
of a container
Prevent CUA from focusing on Pt BLOCK CUA FOCUS PtContainer
a container (Pt ARG CONTAINER FLAGS)
Cause a container to reextent Pt AUTO EXTENT PtContainer
when any of its children are (Pt ARG CONTAINER FLAGS)
realized
Allow CUA keys to function in Pt ENABLE CUA PtContainer
a container (and its children) (Pt ARG CONTAINER FLAGS)
Allows arrow key navigation in Pt ENABLE CUA ARROWS PtContainer
a container (and its children) (Pt ARG CONTAINER FLAGS)
Force a group of widgets to be Pt GROUP EQUAL SIZE PtGroup
the same size (Pt ARG GROUP FLAGS)
Allow only one widget of a Pt GROUP EXCLUSIVE PtGroup
group to be selected (Pt ARG GROUP FLAGS)
Allow an exclusive group to Pt GROUP NO SELECT ALLOWEDPtGroup
choices to have no selected (Pt ARG GROUP FLAGS)
item

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 21

What’s in a widget description?  2005, QNX Software Systems

When you want to: Use this bit: See:

Prevent movement among a Pt GROUP NO KEYS PtGroup
group using the arrow keys (Pt ARG GROUP FLAGS)
Prevent horizontal wrapping Pt GROUP NO KEY WRAP HORIZONTAL PtGroup
using arrow keys (Pt ARG GROUP FLAGS)
Prevent vertical wrapping using Pt GROUP NO KEY WRAP VERTICAL PtGroup
arrow keys (Pt ARG GROUP FLAGS)
Prevent horizontal and vertical Pt GROUP NO KEY WRAP PtGroup
wrapping using arrow keys (Pt ARG GROUP FLAGS)
Make a group of widgets the Pt GROUP EQUAL SIZE HORIZONTAL PtGroup
same width (Pt ARG GROUP FLAGS)
Make a group of widgets the Pt GROUP EQUAL SIZE VERTICAL PtGroup
same height (Pt ARG GROUP FLAGS)
Stretch the rightmost of a Pt GROUP STRETCH HORIZONTAL PtGroup
group of widgets (Pt ARG GROUP FLAGS)
Stretch the bottommost of a Pt GROUP STRETCH VERTICAL PtGroup
group of widgets (Pt ARG GROUP FLAGS)
Stretch the last of a group of Pt GROUP STRETCH FILL PtGroup
widgets (Pt ARG GROUP FLAGS)
Shift text down and to the right Pt LABEL SELECT SHIFT PtLabel
when selected (Pt ARG LABEL FLAGS)
Show a balloon if the pointer Pt SHOW BALLOON PtLabel
remains motionless over text (Pt ARG LABEL FLAGS)
Show a balloon if the pointer Pt BALLOON AS REQUIRED PtLabel
remains motionless over (Pt ARG LABEL FLAGS)
clipped text

What’s in a widget description?

You’ll find the following sections in a typical widget-class
description:

22 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems What’s in a widget description?

Class hierarchy
The ancestral classes a widget inherits its resources and behavior
from.

PhAB icon
The icon in PhAB’s widget bar for the widget.

Public header
The name of the header file containing the resource manifests, data
structures, and defines 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. The “New
resources” table for each widget contains the following columns of
information:

Resource The resource manifest.

C type The C data type this resource refers to.

Pt type How this resource should be set or queried. For more

information, see 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 will be the data
type the array is expected to contain; the second will
be the data type of the array counter (usually
short).

September 20, 2005 Chapter 2 ¯ Widgets 23

What’s in a widget description?  2005, QNX Software Systems

¯ Boolean — a bit that’s either on or off.

¯ Complex — a resource that needs special handling.
¯ Flag — a value in which each bit has a different
meaning.
¯ Link — a linked list.
¯ Pointer — a pointer that points to an address that
you specify.
¯ Scalar — a value that can be represented within a
single long (that is, a long, a short, or a char).
¯ String — a NULL-terminated UTF-8 string.
¯ Struct — an instance of the structure listed in the C
type column.

Default The default value(s) of a resource.

Inherited resources
The specific resources a 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.

24 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems What’s in a widget description?

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
The functions you can use to control the widget once it has been
created.

September 20, 2005 Chapter 2 ¯ Widgets 25

AwFileSelect  2005, QNX Software Systems
A PhAB file-selector widget

Class hierarchy:
PtWidget → AwFileSelect

PhAB icon:
None — instantiated by PhAB’s File Selector module.

Public header:
<photon/AwFileSelect.h>

Description:
The AwFileSelect widget displays itself as a dialog to provide
basic file open/save functionality for an application.

File Selector
Directory Path
/home/stever/phab/others/src

Files Directories
Makefile
Usemsg home
abHfiles stever
abOfiles phab
abSfiles others
abdefine.h src
abevents.h default
abimport.h
ablinks.h
abmain.c
abplatform
abvars.h
Selection File Spec

Open Cancel

An AwFileSelect widget.

AwFileSelect is a PhAB widget. A PhAB widget uses one or more

26 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems AwFileSelect

PhAB modules files as input and can be used only in an application

built with PhAB. It’s accessible in the Other module list when
creating modules for your application.

☞ PtFileSel is more versatile than this widget. You should use it

instead.

AwFileSelect shows a directory in two lists. One list shows the

files and the other list shows the folders. The initial starting directory
is taken from the Aw ARG DIRECTORY PATH resource. You can set
this value in the pre-realize setup function for the module. You can
also filter the types of files being shown in the file list by setting the
Aw ARG FILE SPEC resource. For example, the following code sets
up the file selector to display all files with the extension .c in the
user’s home directory:

open setup( PtWidget t *link instance, ApInfo t *apinfo,

PtCallbackInfo t *cbinfo )

{
char *home dir;
PtArg t args[2];

if ( !( home dir = getenv( "HOME" ) ) )

home dir = "/";

PtSetArg( &args[0], Aw ARG DIRECTORY PATH, home dir, 0 );

PtSetArg( &args[1], Aw ARG FILE SPEC, "*.c", 0 );
PtSetResources( ABW file selector, 2, args );

return( Pt CONTINUE );
}

If you’re using the widget to save a file, you can also specify the
filename to use by setting the Aw ARG FILE NAME resource.
The dialog contains two action buttons to give the user an indication
of what the dialog is going to do:

September 20, 2005 Chapter 2 ¯ Widgets 27

AwFileSelect  2005, QNX Software Systems

Button Meaning Default text

Action activate the file selection Open
Cancel cancel it Cancel

You can change the text for the buttons by setting the
Aw ARG ACTION TEXT or Aw ARG CANCEL TEXT resources. For
example, if the dialog is being used to save a file, you should change
Aw ARG ACTION TEXT to Save.
When the user activates the file selection by clicking on the Action
button, the Aw CB FS ACTION callback is invoked. This callback
passes widget data to indicate the directory, filename and filespec
values at the time the file selection was activated. You can access this
data in the callback by casting the callback data as follows:

AwFileSelectCallback t *fs = cbinfo->cbdata;

strcpy( folder, fs->dirpath );

strcpy( fname, fs->filename );
strcpy( fspec, fs->filespec );

Typically this information is saved globally in the application so that

the next time the dialog is displayed it shows the last values entered
by the user.
The Aw CB FS CANCEL callback is invoked if the user cancels the
dialog in any way without making a selection.

New resources:

Resource C type Pt type Default

Aw ARG ACTION TEXT char * String "Open"
Aw ARG CANCEL TEXT char * String "Cancel"

continued. . .

28 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems AwFileSelect

Resource C type Pt type Default

Aw ARG DIRECTORY PATH char * String "/"
Aw ARG FILE NAME char * String NULL
Aw ARG FILE SPEC char * String "*"
Aw CB FS ACTION PtCallback t * Link NULL
Aw CB FS CANCEL PtCallback t * Link NULL

Aw ARG ACTION TEXT

C type Pt type Default
char * String "Open"

The text to appear on the Action button.

Aw ARG CANCEL TEXT

C type Pt type Default
char * String "Cancel"

The text to appear on the Cancel button.

Aw ARG DIRECTORY PATH

C type Pt type Default
char * String "/"

The initial directory path before the dialog is displayed. The widget
uses this value to open the directory and display the files and folders
in the appropriate lists.

September 20, 2005 Chapter 2 ¯ Widgets 29

AwFileSelect  2005, QNX Software Systems

Aw ARG FILE NAME

C type Pt type Default
char * String NULL

Use this resource to set a default file name. It can also be used to
extract the file name in the action callback.

Aw ARG FILE SPEC

C type Pt type Default
char * String "*"

A filter that limits the files displayed in the file list. It’s typically used
when an application wants to show certain types of files. For example,
a graphical file viewer might set the file specification to *.gif to
limit the files to GIF files. The file specification has no effect on the
folder display list.

Aw CB FS ACTION
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks invoked when the user clicks on the action button
or double-clicks on a file in the file list. The application should use
these callbacks to perform the selected file operation.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Aw CB FS ACTION

reason subtype
0 (not used)

cbdata A pointer to a AwFileSelectCallback t structure:

30 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems AwFileSelect

¯ char *dirpath — the current directory path for the

filename being acted upon.
¯ char *filename — the name of the file.
¯ char *filespec — the current file specification (which
may have been changed by the user).
The dirpath and filename fields can be concatenated to
give you a full path to the selected file. The filespec can
be saved in a global variable to restore the file
specification if the dialog is displayed again.

These callbacks should return Pt CONTINUE.

Aw CB FS CANCEL
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks invoked when the user cancels the dialog in any
way. This includes clicking on the Cancel button or closing the dialog.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Aw CB FS CANCEL

reason subtype
0 (not used)

cbdata A pointer to a AwFileSelectCallback t structure:

¯ char *dirpath — the current directory path for the
filename being acted upon.
¯ char *filename — the name of the file.
¯ char *filespec — the current file specification (which
may have been changed by the user).

September 20, 2005 Chapter 2 ¯ Widgets 31

AwFileSelect  2005, QNX Software Systems

The dirpath and filename fields can be concatenated to

give you a full path to the selected file. The filespec can
be saved in a global variable to restore the file
specification if the dialog is displayed again.

These callbacks should return Pt CONTINUE.

Inherited resources:
This widget is self-contained and doesn’t use any resources inherited
from PtWidget.

32 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems AwMessage
PhAB message widget

Class hierarchy:
PtWidget → AwMessage

PhAB icon:
None — instantiated by PhAB’s Message module.

Public header:
<photon/AwMessage.h>

Description:
AwMessage displays a text-based message in a popup window. The
message can include up to three optional buttons, allowing the user to
select a course of action.

You’re using the Magic Gizmo Maker (version 1.0)

Ok

An AwMessage widget.

AwMessage is a PhAB widget. A PhAB widget uses one or more

PhAB modules files as input and can be used only in an application
built with PhAB. It’s accessible in the Other module list when
creating modules for your application.

☞ This widget is very similar to PtMessage and PtMessage is much

easier to work with. It’s primarily here for historical reasons and we
highly recommend using PtMessage instead.

September 20, 2005 Chapter 2 ¯ Widgets 33

AwMessage  2005, QNX Software Systems

New resources:

Resource C type Pt type Default

Aw ARG MSG BUTTON1 char * String "Ok"
Aw ARG MSG BUTTON2 char * String NULL
Aw ARG MSG BUTTON3 char * String NULL
Aw ARG MSG DEFAULT short Scalar 1
Aw ARG MSG FONT char * String "helv12"
Aw ARG MSG TEXT char * String NULL
Aw ARG MSG TITLE char * String NULL
Aw CB MSG BUTTON1 PtCallback t * Link NULL
Aw CB MSG BUTTON2 PtCallback t * Link NULL
Aw CB MSG BUTTON3 PtCallback t * Link NULL

Aw ARG MSG BUTTON1, Aw ARG MSG BUTTON2, Aw ARG MSG BUTTON3

C type Pt type Default
char * String See below

The labels for the three optional buttons that are displayed below the
message. If no label is provided for Aw ARG MSG BUTTON1, the
default of Ok is used. If no label is provided for the other two buttons,
they default to NULL, which means they won’t be displayed. These
defaults are useful for messages that simply provide information.

34 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems AwMessage

Do you want to delete the file?

Yes No Cancel

A typical AwMessage widget with three buttons.

You can assign a keyboard shortcut to each button. Simply place & in
front of the character that will act as the shortcut. For example, if you
specify &Save, the S will be underlined in the button. To select the
button, the user can press s or S.

☞ The function PtAskQuestion() duplicates the functionality of the

above example.

Aw ARG MSG DEFAULT

C type Pt type Default
short Scalar 1

The number of the default button (1, 2 or 3), which can be selected by
pressing Enter. The default button is initially given focus.

Aw ARG MSG FONT

C type Pt type Default
char * String "helv12"

The font in which the message will be displayed (12-point Helvetica

by default).

September 20, 2005 Chapter 2 ¯ Widgets 35

AwMessage  2005, QNX Software Systems

Aw ARG MSG TEXT

C type Pt type Default
char * String NULL

The message to be displayed.

Aw ARG MSG TITLE

C type Pt type Default
char * String NULL

An optional title for the window frame of the message. Defaults to

NULL for no title.

Aw CB MSG BUTTON1, Aw CB MSG BUTTON2, Aw CB MSG BUTTON3

C type Pt type Default
PtCallback t * Link NULL

Callback functions that will be invoked if the user selects one of the
buttons. These resources correspond with the buttons by number. So,
for example, if the user selects the button labeled with
Aw ARG MSG BUTTON1, Aw CB MSG BUTTON1 is invoked.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason The name of the callback resource (e.g.

Aw CB MSG BUTTON1) that caused this callback to be
invoked.
reason subtype
0 (not used).

event The raw event that caused the the callback to be invoked.

36 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems AwMessage

cbdata Always NULL for this widget.

These callbacks should return Pt CONTINUE.

Inherited resources:
This widget is self-contained and doesn’t use any resources inherited
from PtWidget.

September 20, 2005 Chapter 2 ¯ Widgets 37

PtArc  2005, QNX Software Systems
An elliptical arc

Class hierarchy:
PtWidget → PtBasic → PtGraphic → PtArc

PhAB icon:

Public header:
<photon/PtArc.h>

Description:
You can create an elliptical arc using the PtArc widget. The arc is
defined by:

¯ the origin

¯ an ellipse

¯ a start angle

¯ an end angle

Arcs, circles, ellipses, wedges, and chords created by PtArc.

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.

38 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtArc

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 ARC START and
Pt 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 will result
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

¯ 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.

September 20, 2005 Chapter 2 ¯ Widgets 39

PtArc  2005, QNX Software Systems

Pt ARG ARC START

C type Pt type Default
unsigned short Scalar 0

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

C type Pt type Default
unsigned short Scalar Pt ARC CURVE

The type of arc. Possible values:

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 AREA PtWidget

continued. . .

40 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtArc

Resource Inherited from Default override

Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DASH LIST PtGraphic
Pt ARG DASH SCALE PtGraphic
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic Pg TRANSPARENT
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG GRAPHIC FLAGS PtGraphic
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS 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

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 41

PtArc  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG ORIGIN PtGraphic
Pt ARG POINTS PtGraphic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY AS REQUIRED
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESCALE PtGraphic
Pt CB UNREALIZED PtWidget

42 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtBasic
A superclass of basic resources for most widgets

Class hierarchy:
PtWidget → PtBasic

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

¯ border colors

¯ draw color

¯ fill color

¯ fill pattern

September 20, 2005 Chapter 2 ¯ Widgets 43

PtBasic  2005, QNX Software Systems

Some widgets are associated with a command to be performed —

when the user clicks on the widget, the command is executed. These
widgets have Pt SELECTABLE set in their Pt ARG FLAGS resource.
PtBasic defines several actions involving the left pointer button for
its descendants. You can attach callbacks to any of these actions.

When you: The widget becomes: Callback invoked:

Press the left Armed Pt CB ARM
pointer button
while pointing at
the widget
Release the left Activated Pt CB ACTIVATE
pointer button
while pointing at
an armed widget
Release the left Disarmed Pt CB DISARM
pointer button
when the pointer is
outside the 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.

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 in its Pt ARG FLAGS. Pt CB MENU is invoked

44 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtBasic

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.

New resources:

Resource C type Pt type Default

Pt ARG BANDWIDTH THRESHOLD unsigned long Scalar 0
Pt ARG BOT BORDER COLOR PgColor t Scalar Pg DGRAY
Pt ARG COLOR PgColor t Scalar Pg BLACK
Pt ARG FILL COLOR PgColor t Scalar Pg GRAY
Pt ARG FILL PATTERN PgPattern t Struct Pg PAT FULL
Pt ARG HIGHLIGHT ROUNDNESS unsigned short Scalar 0
Pt ARG MARGIN HEIGHT unsigned short Scalar 0
Pt ARG MARGIN WIDTH unsigned short Scalar 0
Pt ARG TOP BORDER COLOR PgColor t Scalar Pg WHITE
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

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 45

PtBasic  2005, QNX Software Systems

Resource C type Pt type Default

Pt CB MENU PtCallback t * Link NULL
Pt CB REPEAT PtCallback t * Link NULL

Pt ARG BANDWIDTH THRESHOLD

C type Pt type Default
unsigned long Scalar 0

Defines the “graphics bandwidth” threshold that defines a slow

connection. This resource is used by only a few widgets.

Pt ARG BOT BORDER COLOR

C type Pt type Default
PgColor t Scalar Pg DGRAY

The color of the bottom and right sides of the border.

Pt ARG COLOR
C type Pt type Default
PgColor t Scalar Pg BLACK

The widget’s foreground or drawing color.

Pt ARG FILL COLOR

C type Pt type Default
PgColor t Scalar Pg GRAY

The widget’s background color.

46 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtBasic

Pt ARG FILL PATTERN

C type Pt type Default
PgPattern t Struct Pg PAT FULL

The widget’s background pattern. This resource can’t be edited in

PhAB.

Pt ARG HIGHLIGHT ROUNDNESS

C type Pt type Default
unsigned short Scalar 0

The radius, in pixels, of the widget’s borders. The default value of 0

results in square corners.

☞ 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 PtDBContainer.

Pt ARG MARGIN HEIGHT

C type Pt type Default
unsigned short Scalar 0

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

September 20, 2005 Chapter 2 ¯ Widgets 47

PtBasic  2005, QNX Software Systems

C type Pt type Default

unsigned short Scalar 0

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 TOP BORDER COLOR

C type Pt type Default
PgColor t Scalar Pg WHITE

The color of the top and left sides of the border.

Pt ARG TRANS PATTERN

C type Pt type Default
PgPattern t Struct Pg PAT NONE

The widget’s transparency pattern. You’ll find this handy for

“ghosting” widgets. This resource can’t be edited in PhAB.

Pt CB ACTIVATE
C type Pt type Default
PtCallback t * Link NULL

A list of 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.

48 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtBasic

☞ These callbacks are invoked only if the widget has Pt SELECTABLE

set in its Pt ARG FLAGS.
PtText, PtMultiText, and PtComboBox have a special version of
Pt CB ACTIVATE. For more information, see the documentation for
these widgets.

Each callback is passed a PtCallbackInfo t structure that

contains at least the following members:

reason The name of the callback resource (Pt CB ACTIVATE)

that caused this callback to be invoked.
reason subtype
0 (not used).

event A pointer to the event that caused the callback to be

invoked.

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.

September 20, 2005 Chapter 2 ¯ Widgets 49

PtBasic  2005, QNX Software Systems

☞ 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
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that the widget calls when it becomes armed. To

arm a widget, you typically press a pointer button while the screen
pointer is on top of the widget.

☞ These callbacks are invoked only if the widget has Pt SELECTABLE

set in its Pt ARG FLAGS.

Each callback is passed a PtCallbackInfo t structure that

contains at least the following members:

reason The name of the callback resource (Pt CB ARM) that

caused this callback to be invoked.
reason subtype
0 (not used).

event A pointer to the event that caused the callback to be

invoked.

cbdata NULL.

These callbacks should return Pt CONTINUE.

50 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtBasic

Pt CB DISARM
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that the widget calls when it becomes disarmed. To

disarm a widget, you typically release the left pointer button when not
pointing at an armed widget.

☞ These callbacks are invoked only if the widget has Pt SELECTABLE

set in its Pt ARG FLAGS.

Each callback is passed a PtCallbackInfo t structure that

contains at least the following members:

reason The name of the callback resource (Pt CB DISARM) that

caused this callback to be invoked.
reason subtype
0 (not used).

event A pointer to the event that caused the callback to be

invoked.

cbdata NULL.

These callbacks should return Pt CONTINUE.

Pt CB GOT FOCUS
C type Pt type Default
PtCallback t * Link NULL

A callback list invoked when a widget gets the focus or its focus
status changes (e.g. a child widget gets focus from its parent or the

September 20, 2005 Chapter 2 ¯ Widgets 51

PtBasic  2005, QNX Software Systems

focus switches from a child to its parent). The PtIsFocused() function

can be used to find the current focus state of any widget.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason The name of the callback resource (Pt CB GOT FOCUS)

that caused this callback to be invoked.
reason subtype
0 (not used).

event A pointer to the event that caused the callback to be

invoked.

cbdata NULL.

These callbacks should return Pt CONTINUE.

Pt CB LOST FOCUS
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that the widget calls when it loses input focus.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason The name of the callback resource (Pt CB LOST FOCUS)

that caused this callback to be invoked.
reason subtype
0 (not used).

event A pointer to the event that caused the callback to be

invoked.

cbdata NULL.

52 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtBasic

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
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that the widget calls when the user presses the right
mouse 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.

Each callback is passed a PtCallbackInfo t structure that

contains at least the following members:

reason The name of the callback resource (Pt CB MENU) that

caused this callback to be invoked.
reason subtype
0 (not used).

event A pointer to the event that caused the callback to be

invoked.

cbdata NULL.

These callbacks should return Pt CONTINUE.

September 20, 2005 Chapter 2 ¯ Widgets 53

PtBasic  2005, QNX Software Systems

Pt CB REPEAT
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that the widget calls 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).

☞ These callbacks are invoked only if the widget has Pt SELECTABLE

set in its Pt ARG FLAGS.

Each callback is passed a PtCallbackInfo t structure that

contains at least the following members:

reason The name of the callback resource (Pt CB REPEAT) that

caused this callback to be invoked.
reason subtype
0 (not used).

event A pointer to the event that caused the callback to be

invoked.

cbdata NULL.

These callbacks should return Pt CONTINUE.

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.

54 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtBasic

Resource Inherited from Default override

Pt ARG AREA PtWidget
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FLAGS PtWidget
Pt ARG HELP TOPIC PtWidget
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY AS REQUIRED
Pt ARG USER DATA PtWidget
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB HOTKEY PtWidget
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB UNREALIZED PtWidget

September 20, 2005 Chapter 2 ¯ Widgets 55

PtBezier  2005, QNX Software Systems
A Bézier curve

Class hierarchy:
PtWidget → PtBasic → PtGraphic → PtBezier

PhAB icon:

Public header:
<photon/PtBezier.h>

Description:
The PtBezier class draws a Bézier curve via PgDrawBezier().

A Bézier curve created by PtBezier.

The Pt ARG POINTS resource specifies the points in the Bézier

curve. These points are relative to the widget’s Pt ARG ORIGIN. For
more information, see PtGraphic.

New resources:

Resource C type Pt type Default

Pt ARG BEZIER FLAGS unsigned short Scalar 0

56 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtBezier

Pt ARG BEZIER FLAGS

C type Pt type Default
unsigned short Scalar 0

This resource is passed as the flags argument to PgDrawBezier(). For

more information, see the Photon Library Reference.

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 AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DASH LIST PtGraphic
Pt ARG DASH SCALE PtGraphic
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 57

PtBezier  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG FILL COLOR PtBasic Pg TRANSPARENT
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG GRAPHIC FLAGS PtGraphic
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS 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 ORIGIN PtGraphic
Pt ARG POINTS PtGraphic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY AS REQUIRED
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic

continued. . .

58 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtBezier

Resource Inherited from Default override

Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESCALE PtGraphic
Pt CB UNREALIZED PtWidget

September 20, 2005 Chapter 2 ¯ Widgets 59

PtBitmap  2005, QNX Software Systems
A bitmap

Class hierarchy:
PtWidget → PtBasic → PtBitmap

PhAB icon:

Public header:
<photon/PtBitmap.h>

Description:
PtBitmap draws a bitmap. PtBitmap can be set, unset, or made
unselectable. You can use it either in groups, button bars, menu bars,
or as a single button.

4 9 T A J

4 9 T A J

Bitmapped images.

☞ You must define a bitmap’s dimensions via Pt ARG DIM before

setting its Pt ARG BITMAP DATA and Pt ARG SET BITMAP DATA
resources. Once the bitmap’s data has been specified, don’t change
the dimensions.
You must set the Pt ARG SET BITMAP COLORS resource prior to
setting Pt ARG SET BITMAP DATA.

60 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtBitmap

New resources:

Resource C type Pt type Default

Pt ARG BITMAP BALLOON (PtWidget *)() Link NULL
Pt ARG BITMAP BALLOON COLOR PgColor t Scalar Pg BLACK
Pt ARG BITMAP BALLOON FILL COLOR PgColor t Scalar Pg BALLOONCOLOR

Pt ARG BITMAP BALLOON POSITION unsigned short Scalar Pt BITMAP BALLOON RIGHT

Pt ARG BITMAP COLORS PgColor t *, short Array NULL

Pt ARG BITMAP DATA char **, short Array NULL
Pt ARG BITMAP FLAGS short Flag 0
Pt ARG BITMAP TEXT char * String NULL
Pt ARG BMP SET BG COLOR PgColor t Scalar Pg GRAY
Pt ARG BMP SET BG FILL unsigned char Scalar Pt TRUE
Pt ARG SET BITMAP COLORS PgColor t *, short Array NULL
Pt ARG SET BITMAP DATA char **, short Array NULL

Pt ARG BITMAP BALLOON

C type Pt type Default
(PtWidget *)() Link NULL

By default, when a user pauses the pointer over this widget, the
widget will display a small yellow balloon. If you want to change the
look or default text of the balloon, you can use this resource to
override the default value supplied by the default inflate function.
Here’s a prototype of a sample inflate function:

PtWidget t *InflateBalloon( PtWidget t *window,

PtWidget t *widget,

September 20, 2005 Chapter 2 ¯ Widgets 61

PtBitmap  2005, QNX Software Systems

int position,
char *text,
char *font,
PgColor t fill color,
PgColor t text color );

where:

window The parent of the widget requiring the balloon.

widget The widget a balloon will be displayed over.

position The balloon’s position (see

Pt ARG BITMAP BALLOON POSITION below).

text The text to display (see Pt ARG BITMAP TEXT

below).

font The font for the text.

fill color The fill color (see

Pt ARG BITMAP BALLOON FILL COLOR below).

text color The balloon-text color (see

Pt ARG BITMAP BALLOON COLOR below).

In your function, you can either use the supplied values, or ignore
them and use values of your own.

Pt ARG BITMAP BALLOON COLOR

C type Pt type Default
PgColor t Scalar Pg BLACK

The balloon’s text color.

62 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtBitmap

Pt ARG BITMAP BALLOON FILL COLOR

C type Pt type Default
PgColor t Scalar Pg BALLOONCOLOR

The balloon’s fill color.

Pt ARG BITMAP BALLOON POSITION

C type Pt type Default
unsigned short Scalar Pt BITMAP BALLOON RIGHT

Indicates where the bitmap text will pop up. Possible values:

¯ Pt BITMAP BALLOON BOTTOM

¯ Pt BITMAP BALLOON INPLACE

¯ Pt BITMAP BALLOON LEFT

¯ Pt BITMAP BALLOON RIGHT

¯ Pt BITMAP BALLOON TOP

Pt ARG BITMAP COLORS

C type Pt type Default
PgColor t *, short Array NULL

An array of colors (1 for each bitplane). To set the number of

bitplanes, use the len argument to the PtSetArg() macro.
You must set this resource prior to setting Pt ARG BITMAP DATA.

Pt ARG BITMAP DATA

September 20, 2005 Chapter 2 ¯ Widgets 63

PtBitmap  2005, QNX Software Systems

C type Pt type Default

char **, short Array NULL

The bitmap data. Each bit represents a single pixel and each
horizontal line must be rounded up to a multiple of 8 bits. For more
information, see PgDrawBitmap(). To control the dimensions of the
bitmap, use Pt ARG AREA or Pt ARG DIM.

☞ You must define a bitmap’s dimensions via Pt ARG DIM before

setting its Pt ARG BITMAP DATA and Pt ARG SET BITMAP DATA
resources. Once the bitmap’s data has been specified, don’t change
the dimensions.

Pt ARG BITMAP FLAGS

C type Pt type Default
short Flag 0

Possible values:

Pt BITMAP SHOW BALLOON

If the pointer remains motionless for 1.25 seconds over the
bitmap, pop up a balloon with the bitmap’s text.

The default setting for this resource is 0; that is, no flags are set.

Pt ARG BITMAP TEXT

C type Pt type Default
char * String NULL

The text string to display in the balloon.

64 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtBitmap

Pt ARG BMP SET BG COLOR

C type Pt type Default
PgColor t Scalar Pg GRAY

The background color that the widget uses when it becomes armed
(that it, when it’s pressed in). Pt ARG BMP SET BG FILL must be
set to Pt TRUE for this resource to be used.

Pt ARG BMP SET BG FILL

C type Pt type Default
unsigned char Scalar Pt TRUE

Indicates whether or not Pt ARG BMP SET BG COLOR will be used

when the widget becomes armed. Possible values:

Pt TRUE Use the value of Pt ARG BMP SET BG COLOR.

Pt FALSE Ignore the value of Pt ARG BMP SET BG COLOR,

and use Pg TRANSPARENT instead.

Pt ARG SET BITMAP COLORS

C type Pt type Default
PgColor t *, short Array NULL

An array of colors (1 for each bitplane). To set the number of

bitplanes, use the len argument to the PtSetArg() macro.
You must set this resource prior to setting
Pt ARG SET BITMAP DATA.

September 20, 2005 Chapter 2 ¯ Widgets 65

PtBitmap  2005, QNX Software Systems

Pt ARG SET BITMAP DATA

C type Pt type Default
char **, short Array NULL

This resource defines the armed bitmap data. The format of the data is
the same as in Pt ARG BITMAP DATA (see above).

☞ You must define a bitmap’s dimensions via Pt ARG DIM before

setting its Pt ARG BITMAP DATA and Pt ARG SET BITMAP DATA
resources. Once the bitmap’s data has been specified, don’t change
the dimensions.
You must set the Pt ARG SET BITMAP COLORS resource prior to
setting Pt ARG SET BITMAP DATA.

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 AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget

continued. . .

66 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtBitmap

Resource Inherited from Default override

Pt ARG DATA PtWidget
Pt ARG DIM PtWidget See below.
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic 1
Pt ARG MARGIN WIDTH PtBasic 1
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Not used by this class.
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 67

PtBitmap  2005, QNX Software Systems

Resource Inherited from Default override

Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB UNREALIZED PtWidget

Pt ARG DIM You must define a bitmap’s dimensions via

Pt ARG DIM before setting its
Pt ARG BITMAP DATA and
Pt ARG SET BITMAP DATA resources. Once the
bitmap’s data has been specified, don’t change the
dimensions.

68 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtBkgd
A color-gradient, image, or bitmap background

Class hierarchy:
PtWidget → PtBasic → PtContainer → PtPane → PtBkgd

PhAB icon:

Public header:
<photon/PtBkgd.h>

Description:
The PtBkgd widget provides various background layouts.

A background image.

You can choose from the following background types:

¯ Color gradients — These let you vary hue, saturation, or

brightness to achieve various effects. For example, you could place
a background behind a window’s widgets that starts from dark blue
at the top and gradually fades to light blue at the bottom.

¯ Images — These let you display your favorite image file as a

background for your application. If the image is small or a texture,
you can tile it. Images are always opaque and won’t let the
window’s background show through.

September 20, 2005 Chapter 2 ¯ Widgets 69

PtBkgd  2005, QNX Software Systems

¯ Bitmaps — These are similar to images with one exception: they

let a window’s background show through.

New resources:

Resource C type Pt type Default

Pt ARG BKGD BRT FROM ushort t Scalar 0
Pt ARG BKGD BRT TO ushort t Scalar 255
Pt ARG BKGD HUE FROM ushort t Scalar 0
Pt ARG BKGD HUE TO ushort t Scalar 44000
Pt ARG BKGD IMAGE PhImage t * Alloc NULL
Pt ARG BKGD MIX ushort t Scalar 1
Pt ARG BKGD ORIENTATION ushort t Scalar Pt BKGD VERTICAL
Pt ARG BKGD PIXCOLORS PgColor t, short Array NULL
Pt ARG BKGD PIXMAP char * Alloc NULL
Pt ARG BKGD PIX HEIGHT ushort t Scalar 20
Pt ARG BKGD PIX WIDTH ushort t Scalar 20
Pt ARG BKGD SAT FROM ushort t Scalar 0
Pt ARG BKGD SAT TO ushort t Scalar 255
Pt ARG BKGD SPACING ushort t Scalar 0
Pt ARG BKGD STEPS ushort t Scalar 10
Pt ARG BKGD TILE ushort t Scalar Pt BKGD GRID
Pt ARG BKGD TYPE ushort t Scalar Pt BKGD BRIGHTNESS

70 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtBkgd

Pt ARG BKGD BRT FROM, Pt ARG BKGD BRT TO

C type Pt type Default
ushort t Scalar 0
255

These define a brightness range using the standard HSB

(hue/saturation/brightness) model. Values range from 0 to 255.

☞ The HSB model is also known as the HSV (hue/saturation/value)

model. For more information, see PgHSV().

Pt ARG BKGD HUE FROM, Pt ARG BKGD HUE TO

C type Pt type Default
ushort t Scalar 0
44000

These define a hue range using the standard HSB

(hue/saturation/brightness) model. Values range from 0 to 65535. The
hue determines the color background.

Pt ARG BKGD IMAGE

C type Pt type Default
PhImage t * Alloc NULL

This resource points to a PhImage t structure that defines an image

to be displayed. For more information, see PhImage t,
PgDrawImage() 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

September 20, 2005 Chapter 2 ¯ Widgets 71

PtBkgd  2005, QNX Software Systems

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.

☞ Remember that this is an Alloc resource. 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 MIX

C type Pt type Default
ushort t Scalar 1

For the Pt BKGD HUE, Pt BKGD SATURATION, and

Pt BKGD BRIGHTNESS background types. This resource determines
whether or not color dithering is used in the gradient. By default, it’s
turned on.

Pt ARG BKGD ORIENTATION

C type Pt type Default
ushort t Scalar Pt BKGD VERTICAL

For the Pt BKGD HUE, Pt BKGD SATURATION, and

Pt BKGD BRIGHTNESS background types. This resource sets the
gradient orientation. By default the orientation is horizontal. Possible
values:

¯ Pt BKGD HORIZONTAL

¯ Pt BKGD VERTICAL

72 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtBkgd

Pt ARG BKGD PIXCOLORS

C type Pt type Default
PgColor t Array NULL

For the Pt BKGD PIXMAP background type. An array of bitmap

colors that correspond to the planes defined in
Pt ARG BKGD PIXMAP.

Pt ARG BKGD PIXMAP

C type Pt type Default
char * Alloc NULL

For the Pt BKGD PIXMAP background type. A sequence of planes

provided in the format described in PgDrawBitmap().

Pt ARG BKGD PIX HEIGHT, Pt ARG BKGD PIX WIDTH

C type Pt type Default
ushort t Scalar 20

For the Pt BKGD PIXMAP background type. These resources indicate

the height and width of the bitmap in pixels.

Pt ARG BKGD SAT FROM, Pt ARG BKGD SAT TO

C type Pt type Default
ushort t Scalar 0
255

These define a saturation range using the standard HSB

(hue/saturation/brightness) model. Values range from 0 to 255. The
saturation determines the amount of color to be used. A high value
makes the color bright; a low one makes it look dim or gray.

September 20, 2005 Chapter 2 ¯ Widgets 73

PtBkgd  2005, QNX Software Systems

Pt ARG BKGD SPACING

C type Pt type Default
ushort t Scalar 0

The spacing, in pixels, between tiles.

Pt ARG BKGD STEPS

C type Pt type Default
ushort t Scalar 10

For the Pt BKGD HUE, Pt BKGD SATURATION, and

Pt BKGD BRIGHTNESS background types. This resource determines
the number of steps used in the gradient to get from the minimum to
the maximum value.

Pt ARG BKGD TILE

C type Pt type Default
ushort t Scalar Pt BKGD GRID

For the Pt BKGD PIXMAP and Pt BKGD IMAGE background types.

This resource determines which type of tiling will be used to display
the image. Possible values:

Pt BKGD GRID Repeat the image in grid fashion.

Pt BKGD ALT Repeat the image in alternating grid fashion.

Pt BKGD CENTER
Draw the image once and center it within the
container.

74 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtBkgd

Pt BKGD CENTER GRID

Center the image within container and then, if the
image is smaller than the container, tile the image
around the outside.

If you set this resource to zero, tiling will be disabled and the image
will be drawn once at the top-left corner.

Pt ARG BKGD TYPE

C type Pt type Default
ushort t Scalar Pt BKGD BRIGHTNESS

Determines which type of background will be displayed. Possible

values:

Pt BKGD HUE
Pt BKGD SATURATION
Pt BKGD BRIGHTNESS
These types let you display color gradients. The type you
choose affects how the resources are interpreted.
In general, you specify the range of values for the background
type you choose and enter only the “to” value for the other
resources. So, for example, if you chose Pt BKGD HUE, you
would enter both the “to” and “from” values for Pt BKGD HUE
but only the “to” values for Pt BKGD SATURATION and
Pt BKGD BRIGHTNESS.
The smoothness of the gradient is determined by
Pt ARG BKGD STEPS and Pt ARG BKGD MIX.
Pt BKGD PIXMAP
Pt BKGD IMAGE
These types let you display picture backgrounds.
You can use the Pt BKGD PIXMAP type for small pictures
drawn by hand where you need the background fill color to

September 20, 2005 Chapter 2 ¯ Widgets 75

PtBkgd  2005, QNX Software Systems

show through. If you select this type, the widget uses the
Pt ARG BKGD PIXMAP resource.
You use the Pt BKGD IMAGE type primarily to display images
imported from other sources. If you select this type, the widget
uses the Pt ARG BKGD IMAGE resource.

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 PtContainer Pt LEFT ANCHORED LEFT|
Pt RIGHT ANCHORED LEFT|
Pt TOP ANCHORED TOP|
Pt BOTTOM ANCHORED TOP
Pt ARG ANCHOR OFFSETS PtContainer
Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget

continued. . .

76 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtBkgd

Resource Inherited from Default override

Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY AS REQUIRED
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 77

PtBkgd  2005, QNX Software Systems

Resource Inherited from Default override

Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
Pt CB UNREALIZED PtWidget

78 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtButton
A button for initiating an action

Class hierarchy:
PtWidget → PtBasic → PtLabel → PtButton

PhAB icon:

Public header:
<photon/PtButton.h>

Description:
The PtButton class draws a button. Buttons let you initiate an action
within the application. Clicking the button invokes an application
callback.

Cancel

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, the shading is reversed to make it appear as though the button
is recessed. 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 use the PtButton widget class to create pushbutton widgets.
You specify a label for the pushbutton in the same way as for
PtLabel widgets.

September 20, 2005 Chapter 2 ¯ Widgets 79

PtButton  2005, QNX Software Systems

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 is shaded so that the button appears recessed. 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 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. It you wish to change only the color, the
Pt ARG ARM COLOR can be set when the image is a bitmap with
backfill turned on. The arm color will be 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 DATA 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 gets armed.

New resources:

80 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtButton

Resource C type Pt type Default

Pt ARG ARM COLOR PgColor t Scalar PgGray(170)
Pt ARG ARM DATA void * Alloc NULL
Pt ARG ARM FILL unsigned char Scalar Pt TRUE

Pt ARG ARM COLOR

C type Pt type Default
PgColor t Scalar PgGray(170)

The background color used when the button is armed (pressed in).

Pt ARG ARM DATA

C type Pt type Default
void * Alloc NULL

Contains a pointer. If the label type (Pt ARG LABEL TYPE — see
PtLabel) is Pt Z STRING, this resource points to a text string. If the
label type is Pt IMAGE, this resource points to a PhImage t
structure. For more information, see PtLabel.
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.

September 20, 2005 Chapter 2 ¯ Widgets 81

PtButton  2005, QNX Software Systems

☞ Remember that this is an Alloc resource. 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 ARM FILL

C type Pt type Default
unsigned char Scalar Pt TRUE

Determines whether or not Pt ARG ARM COLOR will be used.

Possible values:

Pt TRUE Use the value of Pt ARG ARM COLOR.

Pt FALSE Ignore the value of Pt ARG ARM COLOR.

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 ACCEL KEY PtLabel
Pt ARG AREA PtWidget
Pt ARG BALLOON COLOR PtLabel
Pt ARG BALLOON FILL COLOR PtLabel
Pt ARG BALLOON POSITION PtLabel

continued. . .

82 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtButton

Resource Inherited from Default override

Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic Pg GRAY
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget |=Pt SELECTABLE|
Pt HIGHLIGHTED
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG HORIZONTAL ALIGNMENT PtLabel Pt CENTER
Pt ARG LABEL BALLOON PtLabel
Pt ARG LABEL DATA PtLabel
Pt ARG LABEL FLAGS PtLabel
Pt ARG LABEL TYPE PtLabel
Pt ARG LINE SPACING PtLabel
Pt ARG MARGIN BOTTOM PtLabel
Pt ARG MARGIN HEIGHT PtBasic

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 83

PtButton  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG MARGIN LEFT PtLabel
Pt ARG MARGIN RIGHT PtLabel
Pt ARG MARGIN TOP PtLabel
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY AS REQUIRED
Pt ARG TEXT FONT PtLabel
Pt ARG TEXT STRING PtLabel
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG UNDERLINE TYPE PtLabel
Pt ARG UNDERLINE1 PtLabel
Pt ARG UNDERLINE2 PtLabel
Pt ARG USER DATA PtWidget
Pt ARG VERTICAL ALIGNMENT PtLabel Pt CENTER
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic

continued. . .

84 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtButton

Resource Inherited from Default override

Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB UNREALIZED PtWidget

September 20, 2005 Chapter 2 ¯ Widgets 85

PtCalendar  2005, QNX Software Systems
A calendar

Class hierarchy:
PtWidget → PtBasic → PtCalendar

PhAB icon:

Pt Calenda

Public header:
<photon/PtCalendar.h>

Description:
PtCalendar draws a calendar showing the day of the week, month
and year. The user 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:

86 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtCalendar

Resource C type Pt type Default

Pt ARG CALENDAR COLOR1 PgColor t Scalar Pg BLACK
Pt ARG CALENDAR COLOR2 PgColor t Scalar Pg DGREY
Pt ARG CALENDAR COLOR3 PgColor t Scalar Pg BLACK
Pt ARG CALENDAR COLOR4 PgColor t Scalar Pg BLACK
Pt ARG CALENDAR COLOR5 PgColor t Scalar Pg BLUE
Pt ARG CALENDAR DATE PtCalendarDate t Struct Current
date
Pt ARG CALENDAR FLAGS ulong t Flag See
below.
Pt ARG CALENDAR FONT1 char * String "lu12"
Pt ARG CALENDAR FONT2 char * String "lu12i"
Pt ARG CALENDAR FONT3 char * String "helv12"
Pt ARG CALENDAR FONT4 char * String "lu12b"
Pt ARG CALENDAR FONT5 char * String "helv12b"
Pt ARG CALENDAR HIGHLIGHT ulong t Scalar 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 Struct 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

September 20, 2005 Chapter 2 ¯ Widgets 87

PtCalendar  2005, QNX Software Systems

Pt ARG CALENDAR COLOR1

C type Pt type Default
PgColor t Scalar Pg BLACK

The color used to display the current month’s days.

Pt ARG CALENDAR COLOR2

C type Pt type Default
PgColor t Scalar Pg DGREY

The color used to display the next and previous month’s days.

Pt ARG CALENDAR COLOR3

C type Pt type Default
PgColor t Scalar Pg BLACK

The color used for the year and month name.

Pt ARG CALENDAR COLOR4

C type Pt type Default
PgColor t Scalar Pg BLACK

The color used for any highlighted days in the calendar (see
Pt ARG CALENDAR HIGHLIGHT).

Pt ARG CALENDAR COLOR5

C type Pt type Default
PgColor t Scalar Pg BLUE

88 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtCalendar

The color used for the names of the days of the week (see
Pt ARG CALENDAR WDAY NAMES).

Pt ARG CALENDAR DATE

C type Pt type Default
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

C type Pt type Default
ulong t 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.

September 20, 2005 Chapter 2 ¯ Widgets 89

PtCalendar  2005, QNX Software Systems

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

C type Pt type Default
char * String "lu12"

The font used for the current month’s days.

Pt ARG CALENDAR FONT2

C type Pt type Default
char * String "lu12i"

The font used for the next and previous month’s days.

Pt ARG CALENDAR FONT3

C type Pt type Default
char * String "helv12"

The font used for the year and month name.

90 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtCalendar

Pt ARG CALENDAR FONT4

C type Pt type Default
char * String "lu12b"

The font used for any highlighted days in the calendar (see
Pt ARG CALENDAR HIGHLIGHT).

Pt ARG CALENDAR FONT5

C type Pt type Default
char * String "helv12b"

The font used for the names of the days of the week (see
Pt ARG CALENDAR WDAY NAMES).

Pt ARG CALENDAR HIGHLIGHT

C type Pt type Default
ulong t Scalar 0

A long used to set bits that represent 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

C type Pt type Default
PgColor t Scalar Pg GREY

September 20, 2005 Chapter 2 ¯ Widgets 91

PtCalendar  2005, QNX Software Systems

The color used for the buttons used for moving to the next and
previous months.

Pt ARG CALENDAR MONTH NAMES

C type Pt type Default
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.

92 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtCalendar

☞ You can’t edit Pt ARG CALENDAR MONTH NAMES in PhAB.

Pt ARG CALENDAR SEL COLOR

C type Pt type Default
PgColor t Scalar Pg YELLOW

The color of the currently selected day of the month.

Pt ARG CALENDAR TIME T

C type Pt type Default
time t Struct 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

C type Pt type Default
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

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 93

PtCalendar  2005, QNX Software Systems

Element Value
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

C type Pt type Default
PgColor t Scalar Pg GREY

The color used for the buttons used for moving to next and previous
years.

Pt CB CALENDAR SELECT
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks invoked when a date is selected. Each callback is

passed a PtCallbackInfo t structure that contains at least the
following members:

reason The name of the callback resource

(Pt CB CALENDAR SELECT) that caused this callback to
be invoked.

94 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtCalendar

reason subtype
0 (not used).

event The event that caused the callback.

cbdata A pointer to a PtCalenderSelectCallback t

structure.

The PtCalenderSelectCallback 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.

These callbacks should return Pt CONTINUE.

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.

September 20, 2005 Chapter 2 ¯ Widgets 95

PtCalendar  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic Pg TRANSPARENT
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic 2
Pt ARG MARGIN WIDTH PtBasic 2
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY AS REQUIRED
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget

continued. . .

96 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtCalendar

Resource Inherited from Default override

Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB UNREALIZED PtWidget

September 20, 2005 Chapter 2 ¯ Widgets 97

PtClock  2005, QNX Software Systems
An analog, digital, or LED clock

Class hierarchy:
PtWidget → PtBasic → PtClock

PhAB icon:

Pt Clock

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.

This isn’t necessarily an accurate way to track time.

98 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtClock

☞ The widget may flicker excessively, particularly if a transparent fill

color is used. To reduce flicker:

¯ Use a nontransparent fill color.

¯ Disable the display of seconds.

¯ Place the clock in a PtDBContainer widget.

New resources:

Resource C type Pt type Default

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 "helv12"
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

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 99

PtClock  2005, QNX Software Systems

Resource C type Pt type Default

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

C type Pt type Default
PgColor t Scalar Pg WHITE

The fill color of the clock’s face (applicable only for analog clocks).

Pt ARG CLOCK FACE OUTLINE COLOR

C type Pt type Default
PgColor t Scalar Pg BLACK

The color of the line drawn around the clock face (applicable only for
analog clocks).

Pt ARG CLOCK FLAGS

C type Pt type Default
long Flag Pt CLOCK TRACK TIME |
Pt CLOCK SHOW SECONDS |
Pt CLOCK SHOW NUMBERS

Defines the clock’s behavior. Possible values are:

100 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtClock

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

C type Pt type Default
char * String "helv12"

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.

September 20, 2005 Chapter 2 ¯ Widgets 101

PtClock  2005, QNX Software Systems

Pt ARG CLOCK HOUR

C type Pt type Default
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. When setting this resource, a value of
Pt CLOCK CURRENT causes the clock to assume the current system
time setting.

Pt ARG CLOCK HOUR COLOR

C type Pt type Default
PgColor t Scalar Pg BLACK

The color to use when drawing the hours component.

Pt ARG CLOCK HOUR OFFSET

C type Pt type Default
short Scalar 0

Offset the clock setting by this amount when displaying the hours
field.

Pt ARG CLOCK MINUTE

C type Pt type Default
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). When setting this
resource, a value of Pt CLOCK CURRENT causes the clock to assume
the current system time setting.

102 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtClock

Pt ARG CLOCK MINUTE COLOR

C type Pt type Default
PgColor t Scalar Pg BLACK

The color to use when drawing the minutes component.

Pt ARG CLOCK MINUTE OFFSET

C type Pt type Default
short Scalar 0

Offset the clock setting by this amount when displaying the minutes
field.

Pt ARG CLOCK SECOND

C type Pt type Default
short Scalar Pt CLOCK CURRENT

The current second setting for the clock (reflecting the current system
clock setting if Pt CLOCK TRACK TIME is set). When setting this
resource, a value of Pt CLOCK CURRENT causes the clock to assume
the current system time setting.

Pt ARG CLOCK SECOND COLOR

C type Pt type Default
PgColor t Scalar Pg RED

The color to use when drawing the seconds component.

September 20, 2005 Chapter 2 ¯ Widgets 103

PtClock  2005, QNX Software Systems

Pt ARG CLOCK SECOND OFFSET

C type Pt type Default
short Scalar 0

Offset the clock setting by this amount when displaying the seconds
field.

Pt ARG CLOCK SEP1

C type Pt type Default
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

C type Pt type Default
PgColor t Scalar Pg BLACK

The color to use when drawing the separator character between hours
and minutes.

Pt ARG CLOCK SEP2

C type Pt type Default
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.

104 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtClock

Pt ARG CLOCK SEP2 COLOR

C type Pt type Default
PgColor t Scalar Pg BLACK

The color to use when drawing the separator character between

minutes and seconds.

Pt ARG CLOCK TYPE

C type Pt type Default
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

C type Pt type Default
PtCallback t * Link NULL

A list of 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.

September 20, 2005 Chapter 2 ¯ Widgets 105

PtClock  2005, QNX Software Systems

These callbacks are also invoked whenever a call to PtSetResources()

causes a time change, provided the Pt CALLBACKS ACTIVE flag is
set (see PtWidget).
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason The name of the callback resource

(Pt CB CLOCK TIME CHANGED) that caused this
callback to be invoked.
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

event The event that caused the callback. If event is NULL, the
callback was invoked because the time setting was
changed programmatically using a called to
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.

106 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtClock

¯ 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.

These callbacks should return Pt CONTINUE.

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 AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 107

PtClock  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic 1
Pt ARG MARGIN WIDTH PtBasic 1
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY AS REQUIRED
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB UNREALIZED PtWidget

108 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtComboBox
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.

Friday Friday
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
Sunday

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 The user must click a button to see the list.

September 20, 2005 Chapter 2 ¯ Widgets 109

PtComboBox  2005, QNX Software Systems

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 mouse, either click on an item or drag the
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 be scrolled.
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.

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

¯ Pt CB MODIFY VERIFY

¯ Pt CB MOTION NOTIFY

¯ Pt CB MOTION VERIFY

¯ Pt CB TEXT CHANGED

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

110 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtComboBox

PtComboBox also defines the following callbacks for the list:

¯ Pt CB CBOX ACTIVATE

¯ Pt CB CBOX CLOSE

New resources:

Resource C type Pt type Default

Pt ARG CBOX BUTTON BORDER WIDTH unsigned short Scalar 2
Pt ARG CBOX BUTTON BOT BORDER COLOR unsigned long Scalar Pg WHITE
Pt ARG CBOX BUTTON COLOR unsigned long Scalar Pg GREY
Pt ARG CBOX BUTTON TOP BORDER COLOR unsigned long Scalar Pg DGREY
Pt ARG CBOX BUTTON WIDTH unsigned short Scalar 17
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 CB CBOX ACTIVATE PtCallback t * Link NULL
Pt CB CBOX CLOSE PtCallback t * Link NULL

Pt ARG CBOX BUTTON BORDER WIDTH

C type Pt type Default
unsigned short Scalar 2

The width of the drop button border.

September 20, 2005 Chapter 2 ¯ Widgets 111

PtComboBox  2005, QNX Software Systems

Pt ARG CBOX BUTTON BOT BORDER COLOR

C type Pt type Default
unsigned long Scalar Pg WHITE

The bottom border color of the drop button.

Pt ARG CBOX BUTTON COLOR

C type Pt type Default
unsigned long Scalar Pg GREY

The fill color of the drop button.

Pt ARG CBOX BUTTON TOP BORDER COLOR

C type Pt type Default
unsigned long Scalar Pg DGREY

The top border color of the drop button.

Pt ARG CBOX BUTTON WIDTH

C type Pt type Default
unsigned short Scalar 17

The width of the drop button.

Pt ARG CBOX FLAGS

C type Pt type Default
unsigned long Flag 0

Possible values:

112 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtComboBox

Pt COMBOBOX STATIC
Make the list field is made static and remove the drop button. If
this bit is off, the list field is visible only when the drop button
is pressed. Default is not set.

Pt COMBOBOX TOP
Place the list field above the text field. If this bit is off, the list
field will be placed below the text field. Note: 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 COMBOBOX OPEN (read-only)

If this bit is set (1), it indicates that the list is currently open.

Pt COMBOBOX MAX WIDTH

Make the combo box size itself to fit the longest list item.

Pt ARG CBOX MAX VISIBLE COUNT

C type Pt type Default
unsigned short Scalar 0

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

C type Pt type Default
unsigned short Scalar 0

An index into Pt ARG ITEMS that indicates which list item is

currently selected.

September 20, 2005 Chapter 2 ¯ Widgets 113

PtComboBox  2005, QNX Software Systems

Pt CB CBOX ACTIVATE
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that the widget invokes when the list is activated
(i.e opened).
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB CBOX ACTIVATE.

event The event that caused the activation.

cbdata A value of NULL.

These callbacks should return Pt CONTINUE.

Pt CB CBOX CLOSE
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that are invoked when the user closes the
combobox’s list.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB CBOX CLOSE.

event The event that caused the closure.

cbdata A value of NULL.

These callbacks should return Pt CONTINUE.

114 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtComboBox

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.

Inherited resources:
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.

Resource Inherited from Default override

Pt ARG ACCEL KEY PtLabel Blocked by this
class.
Pt ARG ANCHOR FLAGS PtContainer
Pt ARG ANCHOR OFFSETS PtContainer
Pt ARG AREA PtWidget

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 115

PtComboBox  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG BALLOON COLOR PtLabel
Pt ARG BALLOON FILL COLOR PtLabel
Pt ARG BALLOON POSITION PtLabel
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this
class.
Pt ARG BALLOON COLOR PtGenList
Pt ARG BALLOON FILL COLOR PtGenList
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 2
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG COLUMNS PtText
Pt ARG CONTAINER FLAGS PtContainer
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR POSITION PtText
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EDIT MASK PtText
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic Pg TRANSPARENT
Pt ARG FILL PATTERN PtBasic

continued. . .

116 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtComboBox

Resource Inherited from Default override

Pt ARG FLAGS PtWidget |=Pt HIGHLIGHTED
|
Pt SET
&=˜Pt GETS FOCUS
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG HORIZONTAL ALIGNMENT PtLabel
Pt ARG ITEMS PtList
Pt ARG LABEL BALLOON PtLabel
Pt ARG LABEL DATA PtLabel
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
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

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 117

PtComboBox  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG LIST TOTAL HEIGHT PtGenList
Pt ARG MARGIN BOTTOM PtLabel
Pt ARG MARGIN HEIGHT PtBasic 2
Pt ARG MARGIN LEFT PtLabel
Pt ARG MARGIN RIGHT PtLabel
Pt ARG MARGIN TOP PtLabel
Pt ARG MARGIN WIDTH PtBasic 2
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
Pt ARG TEXT CURSOR WIDTH PtText
Pt ARG TEXT FLAGS PtText
Pt ARG TEXT FONT PtLabel
Pt ARG TEXT HIGHLIGHT BACKGROUND COLOR PtText

continued. . .

118 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtComboBox

Resource Inherited from Default override

Pt ARG TEXT HIGHLIGHT TEXT COLOR PtText
Pt ARG TEXT STRING PtLabel
Pt ARG TEXT SUBSTRING PtText
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TOP ITEM POS PtGenList
Pt ARG TRANS PATTERN PtBasic
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 USER DATA PtWidget
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 BALLOONS PtContainer
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 119

PtComboBox  2005, QNX Software Systems

Resource Inherited from Default override

Pt CB LIST INPUT PtList
Pt CB LOST FOCUS PtBasic
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 REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
Pt CB SCROLL MOVE PtGenList
Pt CB SELECTION PtList
Pt CB TEXT CHANGED PtText
Pt CB UNREALIZED PtWidget

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.

120 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtComboBox

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.

September 20, 2005 Chapter 2 ¯ Widgets 121

PtComboBox  2005, QNX Software Systems

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.

122 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems 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()

September 20, 2005 Chapter 2 ¯ Widgets 123

PtComboBoxListOpen()  2005, QNX Software Systems
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
Interrupt handler No
Signal handler No
Thread No

See also:
PtComboBoxListClose()

124 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtCompound
Superclass for all compound widgets

Class hierarchy:
PtWidget → PtBasic → PtContainer → PtCompound

PhAB icon:
None — not normally instantiated.

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.

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 PtContainer
Pt ARG ANCHOR OFFSETS PtContainer
Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG BOT BORDER COLOR PtBasic

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 125

PtCompound  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY AS REQUIRED
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer
Pt CB BLOCKED PtWidget

continued. . .

126 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtCompound

Resource Inherited from Default override

Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
Pt CB UNREALIZED PtWidget

September 20, 2005 Chapter 2 ¯ Widgets 127

PtContainer  2005, QNX Software Systems
Anchoring, layout, and geometry management for all container widgets

Class hierarchy:
PtWidget → PtBasic → PtContainer

PhAB icon:
None — not normally instantiated.

Public header:
<photon/PtContainer.h>

Description:
The PtContainer superclass provides anchoring, layout, and
geometry management for all container widgets. It also redirects
certain events — such as button press, release, repeat, and keys — to
the child that has focus.

New resources:

Resource C type Pt type Default

Pt ARG ANCHOR FLAGS unsigned Flag 0
Pt ARG ANCHOR OFFSETS PhRect t Struct 0, 0, 0,
0
Pt ARG CONTAINER FLAGS long Flag Pt ENABLE CUA
Pt CB BALLOONS PtBalloonCallback t * Link NULL
Pt CB FILTER PtRawCallback t * Link NULL
Pt CB RESIZE PtCallback t * Link NULL

128 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtContainer

Pt ARG ANCHOR FLAGS

C type Pt type Default
unsigned Flag 0

This resource specifies how the container is anchored to its parent.

The possible values are:

Pt LEFT ANCHORED RELATIVE

Interpret the upper-left x component of
Pt ARG ANCHOR OFFSETS as 1/100 of a percent. A value of
10000, for example, would equal 1 percent.

Pt RIGHT ANCHORED RELATIVE

Interpret the lower-right x component of
Pt ARG ANCHOR OFFSETS as 1/100 of a percent.

Pt TOP ANCHORED RELATIVE

Interpret the upper-left y component of
Pt ARG ANCHOR OFFSETS as 1/100 of a percent.

Pt BOTTOM ANCHORED RELATIVE

Interpret the lower-right y component of
Pt ARG ANCHOR OFFSETS as 1/100 of a percent.

Pt LEFT ANCHORED RIGHT

Anchor the container’s left extent to the right edge of its
parent’s canvas.
Pt RIGHT ANCHORED RIGHT
Anchor the container’s right extent to the right edge of its
parent’s canvas.
Pt TOP ANCHORED BOTTOM
Anchor the container’s top extent to the bottom edge of its
parent’s canvas.

September 20, 2005 Chapter 2 ¯ Widgets 129

PtContainer  2005, QNX Software Systems

Pt BOTTOM ANCHORED BOTTOM

Anchor the container’s bottom extent to the bottom edge of its
parent’s canvas.

Pt LEFT ANCHORED LEFT

Anchor the container’s left extent to the left edge of its parent’s
canvas.
Pt RIGHT ANCHORED LEFT
Anchor the container’s right extent to the left edge of its
parent’s canvas.

Pt TOP ANCHORED TOP

Anchor the container’s top extent to the top edge of its parent’s
canvas.
Pt BOTTOM ANCHORED TOP
Anchor the container’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 mouse pointer passes over the child
widget; otherwise delay the pop up for 1.25 seconds.

☞ Anchors override any Pt ARG RESIZE FLAGS settings that conflict

with Pt ARG ANCHOR OFFSETS or Pt ARG ANCHOR FLAGS
settings. If there is no conflict, the Pt ARG RESIZE FLAGS settings
will be honored.

Pt ARG ANCHOR OFFSETS

C type Pt type Default
PhRect t Struct 0, 0, 0, 0

130 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtContainer

The four values in this structure determine the anchor offsets of each
of the container’s sides. (An anchor offset is the distance between the
anchoring side of the parent and corresponding side of the child.)
Depending on the anchor flags you specify, the offsets will be either
absolute or relative.

☞ 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, will

override the Pt ARG AREA and Pt ARG DIM resources.
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 will remain true even as the parent is resized.

☞ Anchors override any Pt ARG RESIZE FLAGS settings that conflict

with Pt ARG ANCHOR OFFSETS or Pt ARG ANCHOR FLAGS
settings. If there is no conflict, the Pt ARG RESIZE FLAGS settings
will be honored.

September 20, 2005 Chapter 2 ¯ Widgets 131

PtContainer  2005, QNX Software Systems

Pt ARG CONTAINER FLAGS

C type Pt type Default
long Flag Pt ENABLE CUA

This resource controls the look and behavior of the container. Valid
bits include:

Pt DISABLE BALLOONS
Prevent balloons from being inflated in this or any child
container.
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 HOTKEYS FIRST
Key events that reach this container are processed as hotkeys
before being passed 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 BLOCK CUA FOCUS

Prevent CUA from focusing on this container.

Pt AUTO EXTENT
Cause the container to reextent when any of its children are
realized, moved, or resized.
Pt ENABLE CUA
Allow CUA keys to function in this container (and its children).

Pt ENABLE CUA ARROWS

Allow arrow key navigation in this container (and its children).

132 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtContainer

Pt CB BALLOONS
C type Pt type Default
PtBalloonCallback t * Link NULL

A list of balloon callbacks that the container invokes if the pointer

remains motionless for 1.25 seconds over the widget specified in the
callback structure.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason A value of Pt CB BALLOONS.

reason subtype
A value of Pt INFLATE BALLOON when the balloon
should be displayed, or Pt POP BALLOON when the
balloon should be removed.

cbdata A value of NULL.

These callbacks should return Pt CONTINUE.

By default, this callback list invokes the indicated widget’s inflate
function, which is specified by the following resources:

¯ Pt ARG BITMAP BALLOON (PtBitmap)

¯ 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

September 20, 2005 Chapter 2 ¯ Widgets 133

PtContainer  2005, QNX Software Systems

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 raw callback
that’s sensitive to Ph EV BOUNDARY, 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 FILTER
C type Pt type Default
PtRawCallback t * Link NULL

A list of raw callbacks invoked when an event that matches the

provided event mask is to be passed to a child of the container.

134 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtContainer

☞ These callbacks are invoked before the event is passed to the child.
Contrast this resource with the Pt CB RAW resource defined for
PtWidget.

Each callback is passed a PtCallbackInfo t structure that

contains at least the following members:

reason Pt CB FILTER

reason subtype
0 (not used).

cbdata A value of NULL.

These callbacks should return:

¯ Pt CONTINUE to pass the event to the child

Or

¯ Pt END to prevent any child from seeing the event.

Here’s some sample code that adds a Pt CB FILTER callback to a

widget:

PtRawCallback t cb;
PtArg t arg;

cb.event mask = Ph EV KEY;

cb.event f = my callback function;
cb.data = whatever;
PtSetArg( &arg, Pt CB FILTER, &cb, 1 );
PtSetResources( widget, 1, &arg );

Pt CB RESIZE

September 20, 2005 Chapter 2 ¯ Widgets 135

PtContainer  2005, QNX Software Systems

C type Pt type Default

PtCallback t * Link NULL

A list of 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

reason subtype
0 (not used).

cbdata A pointer to a PtContainerCallback t structure that

contains at least the following members:

PhRect t old size;

The extent of the container before the size has
changed.
PhRect t new size;
The new extent of the container after the size has
changed.

These callbacks should return Pt CONTINUE.

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 AREA PtWidget

continued. . .

136 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtContainer

Resource Inherited from Default override

Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY AS REQUIRED
(see below)
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 137

PtContainer  2005, QNX Software Systems

Resource Inherited from Default override

Pt CB ARM PtBasic
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB UNREALIZED PtWidget

Pt ARG RESIZE FLAGS

Anchors override any Pt ARG RESIZE FLAGS settings that
conflict with Pt ARG ANCHOR OFFSETS or
Pt ARG ANCHOR FLAGS settings. If there is no conflict, the
Pt ARG RESIZE FLAGS settings will be honored.

138 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtDBContainer
Double-buffered container for flicker-free drawing

Class hierarchy:
PtWidget → PtBasic → PtContainer → PtDBContainer

PhAB icon:

t DBCont ain

Public header:
<photon/PtDBContainer.h>

Description:
The Double Buffer container creates a memory context and forces all
its children’s draws to be directed to that context. The resulting image
is then drawn as an image to the default draw context. The result is
flicker-free widgets/animations. The PtDBContainer widget uses a
block of shared memory large enough to hold an image the size of its
canvas and will also cause the render shared library to be loaded if not
already present.

☞ If your application uses PtDBContainer, the render shared library,

phlib render 11, must be in your search path.

New resources:

Resource C type Pt type Default

Pt ARG DB IMAGE TYPE int Scalar Pg IMAGE PALETTE BYTE
Pt ARG DB MEMORY CONTEXT TYPE int Scalar Pm PHS CONTEXT

September 20, 2005 Chapter 2 ¯ Widgets 139

PtDBContainer  2005, QNX Software Systems

Pt ARG DB IMAGE TYPE

C type Pt type Default
int Scalar Pg IMAGE PALETTE BYTE

The type of image:

¯ Pg IMAGE PALETTE BYTE

¯ Pg IMAGE DIRECT 888

For more information, see PhImage t in the Photon Library

Reference.

Pt ARG DB MEMORY CONTEXT TYPE

C type Pt type Default
int Scalar Pm PHS CONTEXT

The type of memory context:

Pm PHS CONTEXT
Keeps the image in the Photon draw stream (PHS) as long as
possible

Pm IMAGE CONTEXT
Draws to the memory image immediately

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.

140 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtDBContainer

Resource Inherited from Default override

Pt ARG ANCHOR FLAGS PtContainer
Pt ARG ANCHOR OFFSETS PtContainer
Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic See below.
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY AS REQUIRED

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 141

PtDBContainer  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
Pt CB UNREALIZED PtWidget

Pt ARG FILL COLOR

You can’t set this resource to Pg TRANSPARENT. The widget
will ignore any attempt to do so.

142 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtDivider
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 allows the user to resize
the children by dragging “handles” placed between the children.

Divider
handles

Divider handles

Two PtDivider widgets: one contains a scroll area and 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.

September 20, 2005 Chapter 2 ¯ Widgets 143

PtDivider  2005, QNX Software Systems

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.

New resources:

Resource C type Pt type Default

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 ARG DIVIDER FLAGS

C type Pt type Default
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 will be resized and the right child will be moved.
Pt DIVIDER INVISIBLE
Never display the drag outline. This flag is useful mainly when
Pt DIVIDER NORESIZE is also set.

144 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtDivider

Pt ARG DIVIDER OFFSET

C type Pt type Default
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 the
Pt ARG DIVIDER OFFSET resource you can make the
Pt ARG DIVIDER SIZES resource relative to any arbitrary point.

Pt ARG DIVIDER SIZES (read-only)

C type Pt type Default
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
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that are invoked after each drag event received by
the widget.
If the widget has the Pt CALLBACKS ACTIVE bit set in its
Pt ARG FLAGS resource, these callbacks are also invoked when the
size of a child is changed by a call to PtSetResources().

September 20, 2005 Chapter 2 ¯ Widgets 145

PtDivider  2005, QNX Software Systems

Each callback is passed a PtCallbackInfo t structure that

contains at least the following members:

reason The name of the callback resource that caused this

callback to be invoked (Pt CB DIVIDER DRAG in this
case).
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 The received drag event, or NULL if a child is being

resized through PtSetResources().

cbdata A pointer to a PtDividerCallback t structure that

contains at least the following members:

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.

These callbacks should return Pt CONTINUE.

146 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtDivider

Exported subordinate children:

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.

Inherited resources:
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.

Resource Inherited from Default override

Pt ARG ANCHOR FLAGS PtContainer 0 (no anchors)
Pt ARG ANCHOR OFFSETS PtContainer
Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Ph BAUD CONSOLE
(see below)
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer Sets Pt AUTO EXTENT
and
Pt CHILD MOVED RESIZED
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 147

PtDivider  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget Clears
Pt DAMAGE ON FOCUS,
sets
Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG GROUP FLAGS PtGroup Sets
Pt GROUP STRETCH
flag
Pt ARG GROUP HORZ ALIGN PtGroup
Pt ARG GROUP ORIENTATION PtGroup Pt GROUP HORIZONTAL
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.
Pt ARG GROUP VERT ALIGN PtGroup 0
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget 0

continued. . .

148 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtDivider

Resource Inherited from Default override

Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
Pt CB UNREALIZED PtWidget

Pt ARG BANDWIDTH THRESHOLD

Defines the “graphics bandwidth” threshold that determines
whether the widget will resize the children after each received
drag event or only once, when the drag is completed — see
PtQuerySystemInfo().

September 20, 2005 Chapter 2 ¯ Widgets 149

PtDivider  2005, QNX Software Systems

Pt ARG GROUP ORIENTATION

The value of this resource can only be Pt GROUP HORIZONTAL
or Pt GROUP VERTICAL.

150 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtEllipse
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. 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 these points, Pt ARG DIM determines the height and
width (see PtWidget).

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.

September 20, 2005 Chapter 2 ¯ Widgets 151

PtEllipse  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DASH LIST PtGraphic
Pt ARG DASH SCALE PtGraphic
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG GRAPHIC FLAGS PtGraphic
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG LINE CAP PtGraphic
Pt ARG LINE JOIN PtGraphic
Pt ARG LINE WIDTH PtGraphic
Pt ARG MARGIN HEIGHT PtBasic

continued. . .

152 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtEllipse

Resource Inherited from Default override

Pt ARG MARGIN WIDTH PtBasic
Pt ARG ORIGIN PtGraphic
Pt ARG POINTS PtGraphic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY AS REQUIRED
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESCALE PtGraphic
Pt CB UNREALIZED PtWidget

September 20, 2005 Chapter 2 ¯ Widgets 153

PtFileSel  2005, QNX Software Systems
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.

/usr/photon
appbuilder
apps
bin
ODrivers
crt
11
Aplib_s11
Pa.pc
Pg.IGS
Pg.chips

A PtFileSel widget.

This widget is useful when a program allows users to open or save

files or directories. It reads a directory and displays the contents to the

154 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFileSel

user. Users can also use the widget to navigate a filesystem and
choose their 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 mouse 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
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

September 20, 2005 Chapter 2 ¯ Widgets 155

PtFileSel  2005, QNX Software Systems

¯ 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 set the widget to this mode, use the
Pt FS SINGLE LEVEL flag in the Pt ARG FS FLAGS resource.

156 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFileSel

..
ODrivers
crt
11
Aplib_s11
Pa.pc
Pg.IGS
Pg.chips
Pg.chipsdc
Pg.cirrblit
Pg.cirrnblit

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 also has a useful feature in that it will 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

September 20, 2005 Chapter 2 ¯ Widgets 157

PtFileSel  2005, QNX Software Systems

divider a child of the file selector. The information you requested will
be 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 would contain the name, size, and date information
in the proper columns, but your divider would be 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
re-read 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 that is 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 (i.e. not from a filesystem), 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:

158 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFileSel

...
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, NULL, 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);
PtSetArg(&args[1], Pt ARG FS ROOT DIR, "/", 0);
PtSetArg(&args[2], Pt ARG AREA, area, 0);
PtCreateWidget(PtFileSel, NULL, 3, args);
...

To display a single level of directories with a “..” to move up levels:

...
PtSetArg(&args[0], Pt ARG FS FLAGS,
Pt FS SHOW DIRS|Pt FS SINGLE LEVEL,
Pt FS ALL FLAGS);
PtSetArg(&args[1], Pt ARG FS ROOT DIR, "/", 0);
PtSetArg(&args[2], Pt ARG AREA, area, 0);
PtCreateWidget(PtFileSel, NULL, 3, args);
...

To display a combination of directories and files in tree mode:

...
PtSetArg(&args[0], Pt ARG FS FLAGS,
Pt FS SHOW DIRS|Pt FS SHOW FILES,
Pt FS ALL FLAGS);
PtSetArg(&args[1], Pt ARG FS ROOT DIR, "/", 0);
PtSetArg(&args[2], Pt ARG AREA, area, 0);
PtCreateWidget(PtFileSel, NULL, 3, args);
...

To show only hidden files (that is, a file whose name begins with a “.”
and isn’t normally displayed):

...

September 20, 2005 Chapter 2 ¯ Widgets 159

PtFileSel  2005, QNX Software Systems

PtSetArg(&args[0], Pt ARG FS FLAGS,

Pt FS SHOW FILES|Pt FS SHOW HIDDEN,
Pt FS ALL FLAGS);
PtSetArg(&args[1], Pt ARG FS ROOT DIR, "/", 0);
PtSetArg(&args[2], Pt ARG AREA, area, 0);
PtCreateWidget(PtFileSel, NULL, 3, args);
...

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 is read. You can use this callback to call something like
PtBkgdHandlerProcess(). By doing this, any pending Photon
events will be handled and all the screen damage will be 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

160 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFileSel

quit( PtWidget t *widget, void *data,

PtCallbackInfo t *info)
{
exit(EXIT SUCCESS);
return (Pt CONTINUE);
}

// open button callback

int
file open( PtWidget t *widget, void *data,
PtCallbackInfo t *info)
{
PtFileSelItem t *item;
char buffer[PATH MAX+NAME MAX + 40];

item = PtFSGetCurrent(fs);
if (item == NULL)
return(Pt CONTINUE);

strcpy(buffer, "The selected file is\n");

strcat(buffer, item->fullpath);

PtAskQuestion(window, "Selected File", buffer, NULL, "Ok",

NULL, NULL, 1);

return (Pt CONTINUE);

}

// state callback, will use the reason to block the

// widget for large directory opens
int
state cb( PtWidget t *widget,
struct fs dialog modal *user,
PtCallbackInfo t *info)
{
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,

September 20, 2005 Chapter 2 ¯ Widgets 161

PtFileSel  2005, QNX Software Systems

Pt BLOCKED);
PtSetArg(&args[1], Pt ARG CURSOR TYPE,
Ph CURSOR INHERIT, 0);
}
PtSetResources(widget, 2, args);
return (Pt CONTINUE);
}

// function to handle photon draw events and fix screen damage

int
handler cb(PtWidget t *widget,
struct fs dialog modal *user,
PtCallbackInfo t *info)
{
PtBkgdHandlerProcess();

return (Pt CONTINUE);

}

int main(void)
{
PtArg t args[10];
PtCallback t cb, cb2;
PhDim t win dim = { 300, 300 };
PhArea t area;
PtFileSelItem t *item;

// make the main window

PtSetArg( &args[0], Pt ARG WINDOW TITLE,
"PtFileSel Demo", 0 );
PtSetArg( &args[1], Pt ARG DIM, &win dim, 0 );
window = PtAppInit( NULL, NULL, NULL, 2, args );

// 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 );
PtSetArg(&args[1], Pt ARG FS FLAGS,
Pt FS SHOW DIRS|Pt FS SHOW FILES,
Pt FS ALL FLAGS );
PtSetArg(&args[2], Pt ARG FS ROOT DIR, "/", 0);
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

162 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFileSel

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:

Resource C type Pt type Default

Pt ARG FS FILE SPEC char * String "*"
Pt ARG FS FLAGS ulong t Scalar Pt FS SHOW DIRS
|
Pt FS SHOW FILES
Pt ARG FS FORMAT char * String NULL

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 163

PtFileSel  2005, QNX Software Systems

Resource C type Pt type Default

Pt ARG FS IMAGES PhImage t **, short Array PFM-style
images
(write-only)
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

C type Pt type Default
char * String "*"

A string used to limit the files listed by specifying a pattern that

filenames must match. The default is *, but it can be 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
C type Pt type Default
ulong t Scalar Pt FS SHOW DIRS | Pt FS SHOW FILES

Flags that control the appearance and behavior of the file selector:

Pt FS SHOW DIRS
Show directories.
Pt FS SHOW FILES
Show files.

164 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFileSel

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 SHOW ERRORS
Show files that had a read error.
Pt FS FREE ON COLLAPSE
Free items on every collapse. This means that every time an
item expands, all its child items are re-read from the disk.

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.

Pt FS SEEK KEY
Keyboard seek mode, valid only for single-level mode. Type
characters to seek an item.

Pt ARG FS FORMAT
C type Pt type Default
char * String NULL

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:

September 20, 2005 Chapter 2 ¯ Widgets 165

PtFileSel  2005, QNX Software Systems

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)

C type Pt type Default
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

166 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFileSel

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];
// assume you 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.

September 20, 2005 Chapter 2 ¯ Widgets 167

PtFileSel  2005, QNX Software Systems

☞ Set the flags member of the PhImage t structures to:

Ph RELEASE IMAGE | Ph RELEASE PALETTE |

Ph RELEASE TRANSPARENCY MASK | Ph RELEASE GHOST BITMAP

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 REFRESH
C type Pt type Default
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

C type Pt type Default
char * String NULL

The root directory for the File Selector. The default value is NULL or
none.

Pt CB FS BKGD HANDLER

continued. . .

168 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFileSel

C type Pt type Default

C type Pt type Default

PtCallback t * Link NULL

A list of 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. It’s useful for handling pending
Photon events.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB FS BKGD HANDLER

reason subtype
One of:
¯ 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[] The name of the item being added to the widget.

If this callback returns Pt END, the item isn’t added. If you wish to
translate an item to another encoding, you should use PxTranslate...
functions to do so, copy the new string into name, and return
Pt CONTINUE. You may also wish to process events.

September 20, 2005 Chapter 2 ¯ Widgets 169

PtFileSel  2005, QNX Software Systems

☞ 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,
PtCallbackInfo t *info)
{
PtArg t args[1];
PtFileSelBkgdCallback t *it = (void *) info->cbdata;
int srctaken = 0, dstmade = 0;
char dst[NAME MAX * 3] = {""};

if (info->reason subtype != Pt FS NEW ITEM)

return (Pt END);

// 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, 0, &dstmade) != -1)
strcpy(it->name, dst);

PtBkgdHandlerProcess();

return(Pt CONTINUE);
}

Pt CB FS SELECTION
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks invoked when the user selects an item. Each

callback is passed a PtCallbackInfo t structure that contains at
least the following members:

reason Pt CB FS SELECTION

170 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFileSel

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

These callbacks should return Pt CONTINUE.

Pt CB FS STATE
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks invoked when an item is expanded or collapsed.

Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB FS STATE

September 20, 2005 Chapter 2 ¯ Widgets 171

PtFileSel  2005, QNX Software Systems

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 disk is
read (useful for blocking the widget when reading
a large directory).
Pt FS STATE END
The callback is being called after the disk is read
(useful for unblocking the widget).

These callbacks should return Pt CONTINUE.

172 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFileSel

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 PtContainer
Pt ARG ANCHOR OFFSETS PtContainer
Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BALLOON COLOR PtGenList
Pt ARG BALLOON FILL COLOR PtGenList
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 173

PtFileSel  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG LIST COLUMN ATTR PtGenList
Pt ARG LIST COLUMN POS PtGenList
Pt ARG LIST FLAGS PtGenList
Pt ARG LIST FONT PtGenList
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 TOTAL HEIGHT PtGenList
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget
Pt ARG SCROLLBAR WIDTH PtGenList
Pt ARG SELECTION FILL COLOR PtGenList
Pt ARG SELECTION MODE PtGenList
Pt ARG SELECTION TEXT COLOR PtGenList
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TOP ITEM POS PtGenList
Pt ARG TRANS PATTERN PtBasic
Pt ARG TREE FLAGS PtGenTree

continued. . .

174 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFileSel

Resource Inherited from Default override

Pt ARG USER DATA PtWidget
Pt ARG VISIBLE COUNT PtGenList
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer Not used by this class.
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GEN TREE INPUT PtGenTree
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
Pt CB SCROLL MOVE PtGenList
Pt CB UNREALIZED PtWidget

Convenience functions:
The PtFileSel widget defines several convenience functions that
make it easier to use the file selector once it’s been created. Here’s a
brief overview:

September 20, 2005 Chapter 2 ¯ Widgets 175

PtFileSel  2005, QNX Software Systems

PtFileSelection()
Creates a file-selector dialog similar to the
AWFileSelect widget. See the Photon Library
Reference.
PtFSAddAfter()
Inserts an item after the specified item.
PtFSAddFirst()
Adds a root item to the widget.
PtFSAllItems() Fills a buffer with pointers to all items.

PtFSAllocItem()
Creates an item for a file-selector widget.
PtFSClearSelection()
Clears the selection.
PtFSDamageItem()
Redraws an item.
PtFSExpandParents()
If any ancestors of the given item are collapsed, this
function tries to expand them.
PtFSFolderCollapse()
Collapses an expandable item (directory).
PtFSFolderExpand()
Expands an expandable item (directory).
PtFSFreeAllItems()
Unlinks and frees all items.
PtFSFreeItems()
Frees an unlinked item.
PtFSGetCurrent()
Gets the current item.

176 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFileSel

PtFSGetSelIndexes()
Fills a buffer with indexes.

PtFSGoto() Sets the current item.

PtFSItemIndex()
Calculates the index of the specified item.

PtFSRemoveChildren()
Unlinks all the children of a given item.

PtFSRemoveItem()
Unlinks an item.
PtFSRemoveList()
Unlinks the root item.
PtFSRootItem()
Returns the first root item of the file selector.

PtFSSelect() Selects the specified item.

PtFSSelectedItems()
Fills a buffer with item pointers.

PtFSSetSelIndexes()
Sets the selection indexes.

PtFSShow() Sets the position so that the specified item is visible.

PtFSUnselect()
Unselects the specified item.

PtFSUnselectNonBrothers()
Unselects all items that aren’t siblings of the
specified item.

September 20, 2005 Chapter 2 ¯ Widgets 177

PtFSAddAfter()  2005, QNX Software Systems
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. This function
may be called 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
Interrupt handler No
Signal handler No
Thread No

See also:
PtFSAddFirst()

178 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFSAddFirst()
Add a root item to a file selector tree

Synopsis:
void PtFSAddFirst( PtWidget t *fs,
PtFileSelItem t *item,
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.
This function may be called 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
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 179

PtFSAddFirst()  2005, QNX Software Systems

See also:
PtFSAddAfter(), PtFSRootItem()

180 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems 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==NULL, the function allocates a buffer using malloc(), and the
buffer will be NULL-terminated. If buffer isn’t NULL, the function
won’t add a NULL to the end of it.

Returns:
A pointer to the buffer.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 181

PtFSAllocItem()  2005, QNX Software Systems
Create an item for a PtFileSel widget

Synopsis:
PtFileSelItem t * PtFSAllocItem(
PtFileSelWidget t *fs,
int type,
char const *info );

Description:
This function can be used 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 it will be set to NULL by
this function.

182 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFSAllocItem()

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.

// state callback, will use the reason to block the widget for
// large directory opens
int state cb( PtWidget t *widget,
struct fs dialog modal *user,
PtCallbackInfo t *info)
{
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);
PtSetArg(&args[1], Pt ARG CURSOR TYPE,
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);
PtSetArg(&args[1], Pt ARG CURSOR TYPE,
Ph CURSOR INHERIT, 0);
}
PtSetResources(widget, 2, args);
return (Pt CONTINUE);
}

September 20, 2005 Chapter 2 ¯ Widgets 183

PtFSAllocItem()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

184 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFSClearSelection()
Clear the selection

Synopsis:
void PtFSClearSelection( PtWidget t *widget );

Description:
This function clears the selection.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 185

PtFSDamageItem()  2005, QNX Software Systems
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
Interrupt handler No
Signal handler No
Thread No

186 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFSExpandParents()
Expand an item’s collapsed ancestors

Synopsis:
void PtFSExpandParents( PtWidget t *fs,
PtFileSelItem t *item,
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
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 187

PtFSFolderCollapse()  2005, QNX Software Systems
Collapse an expandable item (directory)

Synopsis:
void PtFSFolderCollapse( PtWidget t *fs,
PtFileSelItem t *item,
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 the event that’s passed to the callback.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

188 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFSFolderExpand()
Expand an expandable item (directory)

Synopsis:
int PtFSFolderExpand( PtWidget t *fs,
PtFileSelItem t *item,
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 the event that’s passed to the callback. If the item isn’t
expanded, the return value will reflect that.

Returns:
0 Success.

Pt END The item couldn’t be expanded.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 189

PtFSFreeAllItems()  2005, QNX Software Systems
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
Interrupt handler No
Signal handler No
Thread No

190 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFSFreeItems()
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 the PtFSRemoveChildren(),
PtFSRemoveItem(), or PtFSRemoveList() function to remove the
subtree items from a file selector widget before freeing the subtree.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 191

PtFSGetCurrent()  2005, QNX Software Systems
Get the current item

Synopsis:
PtFileSelItem t *PtFSGetCurrent(
PtWidget t const *widget );

Description:
This function returns a pointer to the current item.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

192 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFSGetSelIndexes()
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:
A pointer to the buffer.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 193

PtFSGoto()  2005, QNX Software Systems
Set the current item

Synopsis:
void PtFSGoto( PtWidget t *fs,
PtFileSelItem t *item );

Description:
This function sets the current item and (if necessary) the current
position so that the new current item is visible. If item is NULL, there
will be no current item.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

194 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFSItemIndex()
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
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 195

PtFSRemoveChildren()  2005, QNX Software Systems
Unlink the children of the specified item

Synopsis:
PtFileSelItem t *PtFSRemoveChildren(
PtFileSelItem t *item );

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.
This function won’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
Interrupt handler No
Signal handler No
Thread No

196 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFSRemoveItem()
Unlink an item

Synopsis:
void PtFSRemoveItem( PtWidget t *fs,
PtFileSelItem t *item );

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.
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 will 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
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 197

PtFSRemoveList()  2005, QNX Software Systems
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.
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 won’t be able
unlink first from its previous brother.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

198 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFSRootItem()
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
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 199

PtFSSelect()  2005, QNX Software Systems
Select the specified item

Synopsis:
void PtFSSelect( PtWidget t *widget,
PtFileSelItem t *item );

Description:
This function selects the given item.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

200 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFSSelectedItems()
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:
A pointer to the buffer.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 201

PtFSSetSelIndexes()  2005, QNX Software Systems
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
Interrupt handler No
Signal handler No
Thread No

202 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFSShow()
Set the position so that the specified item is visible

Synopsis:
void PtFSShow( PtWidget t *widget,
PtFileSelItem t *item );

Description:
This function sets the current position so that the given item is visible.
If item is NULL, the function does nothing. This allows you to do
something like this:

PtFSShow( widget, PtFSGetCurrent(widget) );

without checking to see if PtFSGetCurrent() returned NULL.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 203

PtFSUnselect()  2005, QNX Software Systems
Unselect the given item

Synopsis:
void PtFSUnselect( PtWidget t *widget,
PtFileSelItem t *item );

Description:
This function unselects the given item.

☞ PtFSUnselect() doesn’t support the Pt RANGE MODE selection mode.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

204 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFSUnselectNonBrothers()
Unselect all items that aren’t siblings of the specified item

Synopsis:
void PtFSUnselectNonBrothers(
PtWidget t *widget,
PtFileSelItem t *item );

Description:
This function unselects all the items that aren’t siblings of the given
item. If item is NULL, the current item is used.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 205

PtFontSel  2005, QNX Software Systems
A widget for selecting font attributes

Class hierarchy:
PtWidget → PtBasic → PtContainer → PtFontSel

PhAB icon:

Public header:
<photon/PtFontSel.h>

Description:
The PtFontSel widget allows user selection of a font family, style,
and size. It provides a combobox for selecting the family, an editable
combobox for selecting the font size, and buttons for selecting bold,
italic, and anti-aliased styles.

Helvetica

12 Bold It alic A/A

AaBbCcXxYyZ z

A PtFontSel widget.

New resources:

206 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFontSel

Resource C type Pt type Default

Pt ARG FONT DISPLAY unsigned Flag Pt FONTSEL ALL FONTS
Pt ARG FONT FLAGS unsigned Flag Pt FONTSEL SAMPLE
|
Pt FONTSEL AA CHECK
Pt ARG FONT NAME char * String "helv12"
Pt ARG FONT SAMPLE char * String "AaBbCcXxYyZz"
Pt ARG FONT SYMBOL long Scalar ’A’
Pt CB FONT MODIFY PtCallback t * Link NULL

Pt ARG FONT DISPLAY

C type Pt type Default
unsigned Flag Pt FONTSEL ALL FONTS

Flags to filter the inclusion of font families in the selection dialog (see
PtFontSelection() in the Photon Library Reference). These flags may
be ORed together — the value Pt FONTSEL ALL FONTS is provided
to override this filtering:

¯ 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.

Pt ARG FONT FLAGS

C type Pt type Default
unsigned Flag Pt FONTSEL SAMPLE |
Pt FONTSEL AA CHECK

September 20, 2005 Chapter 2 ¯ Widgets 207

PtFontSel  2005, QNX Software Systems

Flags to modify the appearance of the widget:

¯ Pt FONTSEL SAMPLE — Show a sample text string in the current

font.

¯ Pt FONTSEL AA CHECK — Only allow use of the anti-aliasing

(A/A) button to 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 ARG FONT NAME

C type Pt type Default
char * String "helv12"

The name of the initial font. This resource also reflects the currently
selected font.

Pt ARG FONT SAMPLE

C type Pt type Default
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

C type Pt type Default
long Scalar ’A’

A character used to filter the inclusion of font families in the selection

dialog. Only those fonts which define this character are included.
This resource may be used to display only Latin fonts (use ’A’) or
Cyrillic fonts (use Pk Cyrillic IO). The value
Pt FONTSEL ALL SYMBOLS may be used to override this filtering.

208 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFontSel

Pt CB FONT MODIFY
C type Pt type Default
PtCallback t * Link NULL

A list of callback functions invoked whenever the selected font is

modified.
If the widget has the Pt CALLBACKS ACTIVE bit set in its
Pt ARG FLAGS resource, this callback is also invoked when the
selected font is changed by a call to PtSetResources().
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB FONT MODIFY

cbdata A pointer to the name of the new font selection.

These callbacks should return Pt CONTINUE.

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 PtContainer
Pt ARG ANCHOR OFFSETS PtContainer
Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 209

PtFontSel  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer &=˜Pt GETS FOCUS
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget See below.
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget 0
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic

continued. . .

210 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtFontSel

Resource Inherited from Default override

Pt CB BALLOONS PtContainer
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
Pt CB UNREALIZED PtWidget

Pt ARG DIM The dimension of the PtFontSel widget is fixed

at 216 wide ¢ 136 high (when the
Pt FONTSEL SAMPLE bit of the
Pt ARG FONT FLAGS resource is set), or 216
wide ¢ 58 high (when the Pt FONTSEL SAMPLE
bit is clear).

Convenience functions:
The PtFontSel class defines the following convenience function:

PtFontSelection()
Display a modal dialog for selecting a font. See the Photon
Library Reference.

September 20, 2005 Chapter 2 ¯ Widgets 211

PtGauge  2005, QNX Software Systems
Common resources for gauge-type widgets

Class hierarchy:
PtWidget → PtBasic → PtGauge

PhAB icon:
None — not normally instantiated.

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:

Resource C type Pt type Default

Pt ARG GAUGE FLAGS short int Flag 0
Pt ARG GAUGE FONT char * String "helv12"
Pt ARG GAUGE H ALIGN unsigned char Scalar Pt CENTER
Pt ARG GAUGE MAXIMUM long Scalar 100
Pt ARG GAUGE MINIMUM long Scalar 0
Pt ARG GAUGE ORIENTATION char Scalar Pt HORIZONTAL
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

212 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGauge

Pt ARG GAUGE FLAGS

C type Pt type Default
short int Flag 0

Possible values:

Pt SHOW VALUE
Indicates whether or not the value of the gauge will be
displayed.

Pt VALUE XOR
XOR the value display with the background (i.e. invert the fill
of the type face).
Pt GAUGE MAX ON TOP
Pt GAUGE MAX ON RIGHT
Pt GAUGE MAX ON LEFT
Pt GAUGE MAX ON BOTTOM
The position of the maximum value.

The default setting for this resource is 0; that is, no flags have been
set.

Pt ARG GAUGE FONT

C type Pt type Default
char * String "helv12"

The font used for displaying the value, title, and any other text.

Pt ARG GAUGE H ALIGN

September 20, 2005 Chapter 2 ¯ Widgets 213

PtGauge  2005, QNX Software Systems

C type Pt type Default

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 MAXIMUM

C type Pt type Default
long Scalar 100

The maximum value of the gauge.

Pt ARG GAUGE MINIMUM

C type Pt type Default
long Scalar 0

The minimum value of the gauge.

Pt ARG GAUGE ORIENTATION

C type Pt type Default
char Scalar Pt HORIZONTAL

Indicates whether the gauge will be drawn vertically or horizontally.

Possible values:

¯ Pt HORIZONTAL
¯ Pt VERTICAL

214 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGauge

Pt ARG GAUGE V ALIGN

C type Pt type Default
unsigned char Scalar Pt CENTER

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

C type Pt type Default
long Scalar 0

The gauge’s current value.

Pt ARG GAUGE VALUE PREFIX

C type Pt type Default
char * String NULL

Text prefixed to the value displayed. For example, Red: would result
in Red:35.

Pt ARG GAUGE VALUE SUFFIX

C type Pt type Default
char * String NULL

Text appended to the value displayed. For example, % would result in

35%.

September 20, 2005 Chapter 2 ¯ Widgets 215

PtGauge  2005, QNX Software Systems

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 AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget

continued. . .

216 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGauge

Resource Inherited from Default override

Pt ARG RESIZE FLAGS PtWidget
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB UNREALIZED PtWidget

September 20, 2005 Chapter 2 ¯ Widgets 217

PtGenList  2005, QNX Software Systems
Generic superclass for list and tree widgets

Class hierarchy:
PtWidget → PtBasic → PtContainer → PtCompound →
PtGenList

PhAB icon:
None — not normally instantiated.

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 PtDivider widget.
Some child classes of PtGenList, such as PtList and PtTree, use
Tab characters as column separators.

Using scrollbars
The PtGenList widget creates a scroll bar if the list’s area isn’t large
enough to display all the items in the list. By default, the scroll bar is
displayed only when necessary. This behavior is controlled by the
Pt LIST SCROLLBAR ALWAYS and (the default)
Pt LIST SCROLLBAR AS REQUIRED bits in the
Pt ARG LIST FLAGS resource.

218 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGenList

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.

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:

September 20, 2005 Chapter 2 ¯ Widgets 219

PtGenList  2005, QNX Software Systems

Resource C type Pt type Default

Pt ARG BALLOON COLOR PgColor t Scalar Pg BLACK
Pt ARG BALLOON FILL COLOR PgColor t Scalar See
below
Pt ARG LIST COLUMN ATTR PtListColumnAttributes t *, short Array NULL
Pt ARG LIST COLUMN POS PtListColumn t *, short Array NULL
Pt ARG LIST FLAGS unsigned short Flag See
below
Pt ARG LIST FONT char * String "helv12"
Pt ARG LIST ITEM COUNT unsigned short Scalar 0
(read-
only)
Pt ARG LIST SB RES PtArg t, int Array
Pt ARG LIST SCROLL RATE short 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 Pg BLUE
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

continued. . .

220 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGenList

Resource C type Pt type Default

Pt ARG VISIBLE COUNT unsigned short Scalar 0
(read-
only)
Pt CB SCROLL MOVE PtCallback t * Link NULL

Pt ARG BALLOON COLOR

C type Pt type Default
PgColor t Scalar Pg BLACK

The balloon’s text color. See PgColor t in the Photon Library

Reference.

Pt ARG BALLOON FILL COLOR

C type Pt type Default
PgColor t Scalar Pg BALLOONCOLOR

The balloon’s fill color. See PgColor t in the Photon Library

Reference.

Pt ARG LIST COLUMN ATTR

C type Pt type Default
PtListColumnAttributes t *, short Array NULL

An array of PtListColumnAttributes t structures, each

containing at least the following:

short flags; The flags define the alignment of the text. The
possible values are:
¯ Pt LIST COLUMN LEFT

September 20, 2005 Chapter 2 ¯ Widgets 221

PtGenList  2005, QNX Software Systems

¯ Pt LIST COLUMN RIGHT

¯ Pt LIST COLUMN CENTER
¯ Pt LIST COLUMN DAMAGE ALWAYS
The Pt LIST COLUMN DAMAGE ALWAYS flag
tells the widget to 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. The
flag can be set 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 ARG LIST COLUMN POS

C type Pt type Default
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 FLAGS

C type Pt type Default
unsigned short Flag Pt LIST BALLOONS IN COLUMNS
|
Pt LIST SCROLLBAR AS REQUIRED

222 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGenList

Flags that control the appearance and behavior of the list. The
possible values are:

Pt LIST SHOW BALLOON

Show list balloons.
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 won’t be consumed
if the first item in the list is already the current
item.
Pt LIST HEADER AUTORESIZE
When the scrollbar is realized or unrealized, adjust
the width of the PtDivider widget (if there is
one).
Pt LIST INACTIVE
Make the list inactive.

Pt LIST NOBLIT Don’t blit when the Pt ARG TOP ITEM POS
resource is changed.

Pt LIST NON SELECT

Make the list read-only.

September 20, 2005 Chapter 2 ¯ Widgets 223

PtGenList  2005, QNX Software Systems

Pt LIST SCROLLBAR ALWAYS

Always display a scrollbar.

Pt LIST SCROLLBAR AS REQUIRED (on by default)

Display a scrollbar only if required.
Pt LIST SCROLLBAR AUTORESIZE
Resize the scrollbar automatically when the size of
the header changes.
Pt LIST SCROLLBAR GETS FOCUS
Let the scrollbar get focus.

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 ARG LIST FONT

C type Pt type Default
char * String "helv12"

The font used for the items in the list.

Pt ARG LIST ITEM COUNT (read-only)

C type Pt type Default
unsigned short Scalar 0

The number of items.

Pt ARG LIST SB RES

C type Pt type Default
PtArg t Array

224 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGenList

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 resources: the PtGenList widget won’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, the application must
supply a buffer and pass its address and length to the PtSetArg()
macro.
An equivalent of:

PtGetResources( scrollbar, N, args );

would be:

PtArg t tmp;
PtSetArg( &tmp, Pt ARG LIST SB RES, args, N );
PtGetResources( list, 1, &tmp );

Pt ARG LIST SCROLL RATE

C type Pt type Default
short Scalar 2

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.

September 20, 2005 Chapter 2 ¯ Widgets 225

PtGenList  2005, QNX Software Systems

Pt ARG LIST SEL COUNT (read-only)

C type Pt type Default
unsigned short Scalar 0

The number of selected items.

Pt ARG LIST TOTAL HEIGHT (read-only)

C type Pt type Default
unsigned Scalar 0

The total height (in pixels) of all items.

Pt ARG SCROLLBAR WIDTH

C type Pt type Default
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

C type Pt type Default
PgColor t Scalar Pg BLUE

The fill color for selected items. See PgColor t in the Photon
Library Reference.

Pt ARG SELECTION MODE

226 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGenList

C type Pt type Default

unsigned short Scalar See below

The selection mode. PtGenList supports the selection of items using

the mouse or the keyboard. The descriptions below assume the user
will be using a mouse. If a mouse isn’t available, the ↑ and ↓ keys on
the numeric pad can be used to highlight items in a list. The current
selection is accepted by the widget when Enter is pressed.

Pt BROWSE MODE (default)

To select an item using the mouse, the user either clicks on an
item or drags the the pointer down the list and releases the
mouse button when the correct item is highlighted. The user
can select only one item. If the user drags the mouse, the list
can be scrolled.
Pt MULTIPLE MODE
To select multiple items using the mouse, the user clicks on
more than one item. When the user clicks on a selected item,
the item is released.
Pt EXTENDED MODE
Click-Shift-click/drag and Ctrl-click combinations are supported
to select multiple items. To select all items between and
including two items in a list, the user clicks on the first item,
presses the Shift key, then clicks on or drags to any other item in
the list. To select multiple disjoint items, the user holds down
the Ctrl while clicking on selected items.
Pt SINGLE MODE
To select an item the user points to the item, then clicks the
mouse button. The user can select only one item. If the user
selects a second item, the first is released.

September 20, 2005 Chapter 2 ¯ Widgets 227

PtGenList  2005, QNX Software Systems

Pt RANGE MODE
To select a range of items the user points to the first item, drags
to the last item in the range, then releases the mouse button.
When the user is dragging the mouse, the list can be scrolled.

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 will 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 the user drags the mouse.

Pt SELECTION MODE NOSCROLL

Don’t scroll the widget if the user drags the mouse above or
below the widget.

Pt SELECTION MODE NOREST

Don’t restore the previous state if the mouse is released outside
the widget.

228 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGenList

Pt SELECTION MODE NOCLEAR

If the user clicks on an item, don’t clear the previous selection
(use with Pt SELECTION MODE MULTIPLE mode only).
Pt SELECTION MODE AUTO
Keyboard automatically selects the current item (unless Ctrl is
used).
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
Item can be deselected 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

September 20, 2005 Chapter 2 ¯ Widgets 229

PtGenList  2005, QNX Software Systems

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

C type Pt type Default
PgColor t Scalar Pg WHITE

The text color for selected items. See PgColor t in the Photon
Library Reference.

Pt ARG TOP ITEM POS

C type Pt type Default
unsigned short Scalar 1

The item index that appears at the top of the list. (The first item is 1.)
Note that unless the widget has been held (using PtContainerHold()),
setting the Pt ARG TOP ITEM POS resource will cause the widget to
draw if damaged and possibly blit afterwards. The widget doesn’t blit
when its fill color is set to Pg TRANSPARENT.

Pt ARG VISIBLE COUNT (read-only)

C type Pt type Default
unsigned short Scalar 0

The number of items currently visible.

230 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGenList

Pt CB SCROLL MOVE
C type Pt type Default
PtCallback t * Link NULL

A list of PtCallback t structures that define the callbacks that the

widget invokes when the top item position changes.
If the widget has the Pt CALLBACKS ACTIVE bit set in its
Pt ARG FLAGS resource, these callbacks are also invoked when the
top item position (Pt ARG TOP ITEM POS) is changed by a call to
PtSetResources().
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason The name of the callback resource

(Pt CB SCROLL MOVE) that caused this callback to be
invoked.
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

contains at least the following members:

unsigned action;
A value indicating what happened — see
below.
int position; A value corresponding to the handle’s
location.

September 20, 2005 Chapter 2 ¯ Widgets 231

PtGenList  2005, QNX Software Systems

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.

These callbacks should return Pt CONTINUE.

232 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGenList

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 PtContainer
Pt ARG ANCHOR OFFSETS PtContainer
Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 2
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 233

PtGenList  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG FLAGS PtWidget |= Pt HIGHLIGHTED
|
Pt ETCH HIGHLIGHT
|
Pt SET |
Pt GETS FOCUS |
Pt FOCUS RENDER
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic 0
Pt ARG MARGIN WIDTH PtBasic 0
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget 0
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget

continued. . .

234 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGenList

Resource Inherited from Default override

Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
Pt CB UNREALIZED PtWidget

Convenience functions:
Most of PtGenList’s convenience functions are useful only if you’re
creating a custom list widget; they’re described in the Creating a List
Widget chapter of the Building Custom Widget manual.
The following convenience functions and data structure are useful
when working with descendants of PtGenList:

PtGenListCreateTextBalloon()
Create a popup balloon for an item in the list.

PtGenListItem t
PtGenList item structure
PtGenListSetColumnBalloon()
Adjust the balloon text to correspond to a given column.

September 20, 2005 Chapter 2 ¯ Widgets 235

PtGenListCreateTextBalloon()  2005, QNX Software Systems
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 Pointer to the PtGenList widget.

parent Pointer to the widget’s parent window.

area Pt ARG AREA resource for the balloon.

string String for the balloon.

column Number of the column to extract from the string (see

below).

font Font for the label. If this is NULL, the font used for the
PtGenList widget is used.

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 will contain the string
"Two".

236 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGenListCreateTextBalloon()

Returns:
A pointer to the PtLabel widget.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 237

PtGenListItem t  2005, QNX Software Systems
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 following flags describe the state of the item:

Pt LIST ITEM SELECTED

This item is selected.
Pt LIST ITEM CURRENT
This item is the current item.
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.

The Pt LIST ITEM USED FLAGS macro defines the

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

238 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGenListItem t

It’s safe to set item flags before adding the item to a

widget — when you add the item to a widget, the
widget sets most of the flags to a correct value without
even looking at the current value. The following flags
are preserved if they don’t conflict with the current
state of the widget:

Pt LIST ITEM SELECTED

Preserved unless the selection mode is
Pt SINGLE MODE and another item is already
selected.
Pt LIST ITEM CURRENT
Preserved unless there’s already a current item in
the widget.

Don’t modify the flags directly after the item is in a

list; they’re set and cleared by the convenience
functions.

size 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
Building Custom Widgets

September 20, 2005 Chapter 2 ¯ Widgets 239

PtGenListSetColumnBalloon()  2005, QNX Software Systems
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 area argument so that it corresponds to the
given column rather than the entire item. If column is NULL, area
won’t be modified.

Returns:
A pointer to the adjusted area.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

240 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGenTree
A generic superclass for tree widgets

Class hierarchy:
PtWidget → PtBasic → PtContainer → PtCompound →
PtGenList → PtGenTree

PhAB icon:
None — not normally instantiated.

Public header:
<photon/PtGenTree.h>

Description:
The PtGenTree widget displays a tree of items. When the user
expands 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:

September 20, 2005 Chapter 2 ¯ Widgets 241

PtGenTree  2005, QNX Software Systems

Resource C type Pt type Default

Pt ARG TREE FLAGS unsigned int Flag Pt TREE HAS BUTTONS
|
Pt TREE HAS LINES
|
Pt TREE ROOT LINES
Pt CB GEN TREE INPUT PtCallback t * Link NULL

Pt ARG TREE FLAGS

C type Pt type Default
unsigned int Flag Pt TREE HAS BUTTONS |
Pt TREE HAS LINES |
Pt TREE ROOT LINES

Possible values are:

Pt TREE HAS BUTTONS

The [+] and [-] buttons are displayed.
Pt TREE HAS LINES
The lines are displayed.
Pt TREE ROOT LINES
The root items have lines (and maybe buttons).

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.

242 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGenTree

☞ The PtTree subclass defines some additional flags.

Pt CB GEN TREE INPUT

C type Pt type Default
PtCallback t * Link NULL

A list of callbacks invoked on mouse and key events. Each callback is

passed a PtCallbackInfo t structure that contains at least the
following members:

reason The name of the callback resource

(Pt CB GEN TREE INPUT) that caused this callback to be
invoked.
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 PtGenTreeInput t structure that

contains at least the following members:

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 after the event is normally
processed by the widget.
unsigned index;
The index of the item.
PhPoint t pos;
Pointer position relative to the item.

September 20, 2005 Chapter 2 ¯ Widgets 243

PtGenTree  2005, QNX Software Systems

int consumed; Initially set to Pt CONTINUE. The

callback function can suppress normal
handling of the event by setting this
field to another value. In the case of key
events, a value of Pt END causes the
event to be consumed, while Pt HALT
passes the event to the parent widget.
Mouse events are always consumed.
You can set it to anything else to
consume the event and suppress further
processing.

These callbacks should return Pt CONTINUE.

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 PtContainer
Pt ARG ANCHOR OFFSETS PtContainer
Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BALLOON COLOR PtGenList
Pt ARG BALLOON FILL COLOR PtGenList
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic

continued. . .

244 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGenTree

Resource Inherited from Default override

Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG LIST COLUMN ATTR PtGenList
Pt ARG LIST COLUMN POS PtGenList
Pt ARG LIST FLAGS PtGenList
Pt ARG LIST FONT PtGenList
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 TOTAL HEIGHT PtGenList
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN WIDTH PtBasic

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 245

PtGenTree  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget
Pt ARG SCROLLBAR WIDTH PtGenList
Pt ARG SELECTION FILL COLOR PtGenList
Pt ARG SELECTION MODE PtGenList
Pt ARG SELECTION TEXT COLOR PtGenList
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TOP ITEM POS PtGenList
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt ARG VISIBLE COUNT PtGenList
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer Not used by this class.
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget

continued. . .

246 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGenTree

Resource Inherited from Default override

Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
Pt CB SCROLL MOVE PtGenList
Pt CB UNREALIZED PtWidget

Convenience functions:
PtGenTree’s convenience functions are useful only if you’re creating
a custom tree widget; they’re described in the Creating a Tree Widget
chapter of the Building Custom Widget manual.
PtGenTree defines the following data structure:

PtGenTreeItem t
PtGenTree item structure

September 20, 2005 Chapter 2 ¯ Widgets 247

PtGenTreeItem t  2005, QNX Software Systems
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 [+] or [-] button (unless the widget disables
the buttons by setting Pt TREE HAS BUTTONS or
Pt TREE ROOT LINES 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).

248 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGenTreeItem t

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 this flag in your code, but:
¯ Make sure the item is collapsed before clearing the
flag.
¯ Call PgGenTreeDamageItem() 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 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.

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 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 will be
displayed between the current item and any other item
directly below.

September 20, 2005 Chapter 2 ¯ Widgets 249

PtGenTreeItem t  2005, QNX Software Systems

Classification:
Photon

See also:
PtGenList, PtGenListItem t, PtGenTree, PtTreeItem t
Building Custom Widgets

250 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGraphic
Common resources for graphical widgets

Class hierarchy:
PtWidget → PtBasic → PtGraphic

PhAB icon:
None — not normally instantiated.

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 widgets subclassed to PtGraphic.

☞ Don’t call the Pg... drawing primitives directly, as they won’t be

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

¯ polylines

¯ points

September 20, 2005 Chapter 2 ¯ Widgets 251

PtGraphic  2005, QNX Software Systems

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 (such as PtPane).

Creating vector graphics

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. 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 are relative to the

graphics widget’s origin.
The graphics widget’s origin is specified by the Pt ARG ORIGIN
resource. 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.
When drawing the points for the primitive or the curve, 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 on the PtGraphic widget class:

252 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGraphic

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.

For explanations of the values you may specify for these resources,
see the documentation for PgSetStrokeCap() and PgSetStrokeJoin().
Most of the graphics primitives can also be configured to draw a
closed curve. When this is done, the interior of the primitive may also
be filled using the fill color and style associated with the widget to
determine. These fill attributes are specified using the following
resources defined by the PtBasic widget class:

Pt ARG FILL COLOR

Color to use to fill the interior.
Pt ARG FILL PATTERN
Stipple pattern to use to fill the interior.

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.
Normally, you 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

September 20, 2005 Chapter 2 ¯ Widgets 253

PtGraphic  2005, QNX Software Systems

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 will be 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 will be 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

254 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGraphic

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.

September 20, 2005 Chapter 2 ¯ Widgets 255

PtGraphic  2005, QNX Software Systems

☞ Using this technique, you can create a complex drawing composed of

a number of sub-drawings. 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. Recall that each container
widget requires a Photon region, which is a Photon server resource
that consumes server memory. In a system with constrained memory,
many deeply nested drawings may consume excess amounts of server
resources.

Rescaling graphics widgets

The advantage of vector graphics is they use less space to define and
are easy to scale. They may be scaled independently in the x and y
directions.
To rescale any of your graphics primitives, you must multiply each
control point and the origin for the primitive by x and y scale factors.
The Pt CB RESCALE callback makes this easier.
This callback is invoked whenever the primitive’s size is redefined,
whether by a PtSetResources() call or directly by the parent.
The callback should be attached to an application function that scales
each point of the widget and its origin.
You can thus rescale an entire drawing by creating a resize function
for the container that implements the drawing. The resize function
repositions each of the children and multiplies their dimensions by the
scale factors for x and y. Graphics primitives will automatically be
scaled because their Pt CB RESCALE callbacks will be invoked.
If a container is used to create sub-drawings, the resize function must
be called for each container in order for the rescaling to be propagated
through all the sub-drawings. This can be handled by attaching the
same resize callback that was used for the drawing as the resize
callback for each sub-drawing.
To scale drawings correctly in this manner, follow these two steps:

256 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGraphic

1 Attach all the graphics widgets and sub-drawings to the

appropriate resize or rescale functions.

2 Determine the correct scale factors and rescale each of the

container’s children when the widget holding the drawing is
resized.

Attaching resize and rescale functions

A resize function is required for each container used for a drawing or

sub-drawing.
This resize function determines the x and y scale factors to apply to
the drawing. It looks at the new extents for the drawing widget to
determine the ratio of the new width and height compared to the
widget’s current width and height. It can use these as the scale factor,
or it may choose one of these values — presumably the smaller of the
two — to use as the scale factor for both width and height in order to
preserve the aspect ratio of the drawing (or sub-drawing).
The resize function then passes over each of its children and scales
the x and y members of the Pt ARG POS and Pt ARG DIM resources
by the x and y scale factors. In order for children to be resized
correctly, you must change their resize policy to Pt NEVER for both
the width and height. You can do this in your resize function or after
the graphics are realized.
The code below shows a resize function that performs the actions
indicated above. The function takes a PhDim t pointer as client data
indicating the old extents of the widget. These dimensions are
initialized when the widget is realized and updated whenever it’s
resized.
int resize( PtWidget t *wgt, void *client data,
PtCallbackInfo t *info)
{
PhPoint t *pos, newpos;
PhDim t *dim, newdim;
PtArg t arg[2];
PhDim t *old extents = (PhDim t *)client data;
PhRect t *extents = (PhRect t *)info->cbdata;
int width = extents->lr.x - extents->ul.x + 1;
int height = extents->lr.y - extents->ul.y + 1;
double xs = width;

September 20, 2005 Chapter 2 ¯ Widgets 257

PtGraphic  2005, QNX Software Systems

double ys = height;
PtWidget t *child = PtWidgetChildFront(wgt);

if (old extents)
{
xs = xs / old extents->w;
ys = ys / old extents->h;

while (child != NULL)

{
PtSetArg(&arg[0], Pt ARG POS, &pos, 0);
PtSetArg(&arg[1], Pt ARG DIM, &dim, 0);
PtGetResources(child, 2, arg);

if (dim && pos)

{
newpos = *pos;
newpos.x *= xs;
newpos.y *= ys;

newdim = *dim;
newdim.w *= xs;
newdim.h *= ys;

PtSetArg(&arg[0], Pt ARG DIM, &newdim, 0);

PtSetArg(&arg[1], Pt ARG POS, &newpos, 0);
PtSetResources(child, 2, arg);
}

child = PtWidgetBrotherBehind(child);
}
}
return Pt CONTINUE;
}

Calling PtAddCallback() after the widget is created attaches the resize

function to the resize callback. When the widget is created, a closure
is created for it and the address of closure is associated with the
callback in the call to PtAddCallback(). This closure is a dynamically
allocated data structure associated with one of more of a widget’s
callbacks; the closure contains state information for use by those
callbacks. In this case, the closure is a PhDim t that maintains the
widget’s current dimensions. The closure is initialized by a
Pt CB REALIZED callback that sets the dimensions to those of the
widget.
Any sub-drawings created using container-class widgets are also
attached to the same resize callback function and require a closure of
their own. The resize callback will be invoked on the sub-drawing

258 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGraphic

when the parent resizes the sub-drawing within the resize callback
invoked on the parent.
A scaling function is required for all the graphics primitives. This
function calculates x and y scale factors based on the extents passed
in the call data. It then scales the Pt ARG ORIGIN resource and each
point in the Pt ARG POINTS array by the scale factors. the scaling
function doesn’t try to modify the scale factor to preserve a particular
aspect ratio because this has already been done by its parent’s resize
function. The scaling function is attached to the Pt CB RESCALE
callback of each graphics widget after the widget is created.

Calculating the scale factor

The scaling function must be called with new scale factors in both the
x and y directions. The simplest way to get the scale factors is to get
the container widget’s old and new dimensions. The scale factors can
then be expressed as the ratio between the old and new dimensions.
The sample callback function below shows a simple function for
rescaling graphics primitives. As with the resize function given
previously, the widget’s current dimensions are obtained from the
closure passed to the callback function as client data.
int rescale( PtWidget t *wgt, void *client data,
PtCallbackInfo t *info)
{
PhDim t *old extents = (PhDim t *)client data;
PhArea t *area = (PhArea t *)info->cbdata;
PhDim t *dim;
PhPoint t *points;
PhPoint t neworg, *org;
short *npoints;
PtArg t arg[3];

PtSetArg(&arg[0], Pt ARG DIM, &dim, 0);

PtSetArg(&arg[1], Pt ARG POINTS, &points,
(ulong t)&npoints);
PtSetArg(&arg[2], Pt ARG ORIGIN, &org, 0);
PtGetResources(wgt, 3, arg);

if (old extents && dim && points)

{
double xs = dim->w;
double ys = dim->h;
PhPoint t *newpoints = (PhPoint t *)alloca(*npoints
* sizeof(PhPoint t));
int i;

September 20, 2005 Chapter 2 ¯ Widgets 259

PtGraphic  2005, QNX Software Systems

xs = xs / old extents->w;
ys = ys / old extents->h;
neworg.x = org->x * xs;
neworg.y = org->y * ys;

for (i = 0; i < *npoints; i++)

{
newpoints[i].x = points[i].x * xs;
newpoints[i].y = points[i].y * ys;
}

PtSetArg(&arg[0], Pt ARG POINTS, newpoints,

*npoints);
PtSetArg(&arg[1], Pt ARG ORIGIN, &neworg, 0);
PtSetResources(wgt, 2, arg);
}
return Pt CONTINUE;
}

Taken together with the resizing function given previously, this can be
used to create a rescalable picture as in the example below. This
example creates a drawing using a PtGroup and populates it with
three ellipses and an arc to create a simple happy face.
main(int argc, char *argv[])
{
PtAppContext t app;
PtArg t args[8];
int nargs;
PtWidget t *window, *container widget, *widget;
PhPoint t face[] = { {0,0}, {100,100} };
PhPoint t eye[] = { {0,0}, {6,10} };
PhPoint t mouth[] = { {0,0}, {79,49} };
PhPoint t org;
PhDim t *dim;
int resize(PtWidget t *, void *,
PtCallbackInfo t *);
int rescale(PtWidget t *, void *,
PtCallbackInfo t *);
int realized(PtWidget t *, void *,
PtCallbackInfo t *);

if ((window = PtAppInit(&app, &argc, argv, 0, NULL))

== NULL)
exit(EXIT FAILURE);

/* Create a container for the drawing */

nargs = 0;
PtSetArg(&args[nargs], Pt ARG GROUP ORIENTATION,
Pt GROUP ASIS, 0); nargs++;
PtSetArg(&args[nargs], Pt ARG ANCHOR FLAGS,
Pt LEFT ANCHORED LEFT|Pt RIGHT ANCHORED RIGHT|

Pt TOP ANCHORED TOP|Pt BOTTOM ANCHORED BOTTOM,

Pt IS ANCHORED); nargs++;
container widget = PtCreateWidget(PtGroup, window, nargs, args);

260 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGraphic

dim = (PhDim t *)malloc(sizeof(PhDim t));

PtAddCallback(container widget, Pt CB REALIZED, realized, dim);
PtAddCallback(container widget, Pt CB RESIZE, resize, dim);

nargs = 0;
dim = (PhDim t *)malloc(sizeof(PhDim t));
PtSetArg(&args[nargs], Pt ARG POINTS, face,
sizeof(face)/sizeof(face[0]));
nargs++;
PtSetArg(&args[nargs], Pt ARG FILL COLOR, Pg YELLOW, 0);
nargs++;
widget = PtCreateWidget(PtEllipse, container widget, nargs, args);
PtAddCallback(widget, Pt CB REALIZED, realized, dim);
PtAddCallback(widget, Pt CB RESCALE, rescale, dim);

nargs = 0;
dim = (PhDim t *)malloc(sizeof(PhDim t));
org.x = 10;
org.y = 30;
PtSetArg(&args[nargs], Pt ARG POINTS, mouth,
sizeof(mouth)/sizeof(mouth[0])); nargs++;
PtSetArg(&args[nargs], Pt ARG ORIGIN, &org, 0);
nargs++;
PtSetArg(&args[nargs], Pt ARG ARC START, 2300, 0);
nargs++;
PtSetArg(&args[nargs], Pt ARG ARC END, 3100, 0);
nargs++;
PtSetArg(&args[nargs], Pt ARG ARC TYPE, Pt ARC CHORD, 0);
nargs++;
PtSetArg(&args[nargs], Pt ARG FILL COLOR, Pg BLACK, 0);
nargs++;
widget = PtCreateWidget(PtArc, container widget, nargs, args);
PtAddCallback(widget, Pt CB REALIZED, realized, dim);
PtAddCallback(widget, Pt CB RESCALE, rescale, dim);

nargs = 0;
dim = (PhDim t *)malloc(sizeof(PhDim t));
org.x = 27;
org.y = 30;
PtSetArg(&args[nargs], Pt ARG POINTS, eye,
sizeof(eye)/sizeof(eye[0]));
nargs++;
PtSetArg(&args[nargs], Pt ARG ORIGIN, &org, 0);
nargs++;
PtSetArg(&args[nargs], Pt ARG FILL COLOR, Pg BLACK, 0);
nargs++;
widget = PtCreateWidget(PtEllipse, container widget, nargs, args);
PtAddCallback(widget, Pt CB REALIZED, realized, dim);
PtAddCallback(widget, Pt CB RESCALE, rescale, dim);

dim = (PhDim t *)malloc(sizeof(PhDim t));

nargs = 0;
org.x = 67;
PtSetArg(&args[nargs], Pt ARG POINTS, eye,
sizeof(eye)/sizeof(eye[0]));
nargs++;
PtSetArg(&args[nargs], Pt ARG ORIGIN, &org, 0);
nargs++;
PtSetArg(&args[nargs], Pt ARG FILL COLOR, Pg BLACK, 0);
nargs++;

September 20, 2005 Chapter 2 ¯ Widgets 261

PtGraphic  2005, QNX Software Systems

widget = PtCreateWidget(PtEllipse, container widget, nargs, args);

PtAddCallback(widget, Pt CB REALIZED, realized, dim);
PtAddCallback(widget, Pt CB RESCALE, rescale, dim);

PtRealizeWidget(window);

PtMainLoop();
}

int realized( PtWidget t *wgt, void *client data,

PtCallbackInfo t *info)
{
PhDim t *dim;
PhDim t *size = (PhDim t *)client data;
PtArg t arg[2];

info = info;

PtSetArg(&arg[0], Pt ARG DIM, &dim, 0);

PtGetResources(wgt, 1, arg);

if (size && dim)

*size = *dim;
return Pt CONTINUE;
}

Remember to consider the appearance of the drawing if the x and y

dimensions are scaled independently in this way. The drawing may
look odd if its original aspect ratio isn’t preserved. This will be
especially true if the drawing contains arcs — circular arcs will
become elliptical if the aspect ratio isn’t preserved.
You can preserve the aspect ratio of the original drawing by choosing
the same scale factor for the x and y dimensions. The scale factor is
best determined by:

¯ calculating scale factors for both the x and y dimensions, and

¯ choosing the smaller amount as the scale factor to be applied in

both the x and y dimensions.

To do this, calculate the two scale factors and use the minimum of the
two:

xs = new.x / old.x;
ys = new.x / old.x;
s = min(xs, ys);

262 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGraphic

Then scale the old dimensions by the value s to get the desired new
dimensions:

desired.x = s * old.x;
desired.y = s * old.x;

Now call the scaling function with the scale factors expressed by the
two dimensions, old, and desired.
You can easily modify the resize and scaling callback functions given
above to preserve the aspect ratio of all or part of a drawing. To do so,
change the closure to a structure that contains the widget dimensions
and change the callback functions accordingly.
The closure should also have a flag indicating whether or not the
aspect ratio is to be preserved. You could then add the following lines
after the calculation of the xs and ys scale factors:

if (old extents->preserve aspect)

xs = xs < ys ? xs : ys;

The aspect ratio of the entire drawing in our happy face example can
be preserved by setting the preserve aspect flag on the closure for the
PtGroup widget alone.

Scaling based on original coordinates

Scaling a graphic in the manner indicated above can introduce small

round-off errors in the calculation every time the scaling is performed.
After many successive recalculations, the graphic may no longer
appear correct.
For this reason, it may be a good idea to keep the original coordinates
of the graphical object around so that scaling can be performed from
them. Keep the array of control points and the origin for the graphic
in normalized integer coordinates. When you must scale the graphic,
simply calculate a new origin and coordinates by:

1 Scaling the original values by the widget’s dimensions.

2 Dividing by your normalization factor.

September 20, 2005 Chapter 2 ¯ Widgets 263

PtGraphic  2005, QNX Software Systems

You’ll need a way of obtaining the original coordinates inside your

callbacks. The simplest way is to have an object associated with each
of your graphics widgets. Define a structure, say Graphic t, for
these objects that maintains all the original coordinate data for the
graphics widget as well as any additional information you might like
to keep about the graphics primitive. This should consist of the
graphic control points, the origin, and a position and dimensions for
the widget. When you create the graphics widget, store the pointer to
this object in the Pt ARG USER DATA resource of the graphics
widget.
The rescaling function for graphics widgets must obtain the
Graphic t object associated with the widget and must calculate a
new origin and points based on the widget’s new dimensions and the
original coordinate data.
The resizing function should obtain the Graphic t object for each
child of the container and calculate a new position and dimension for
that child based on its original coordinate data and the container’s
scaling factor.
The following example illustrates how our happy face can be
implemented using this strategy:
#include <Pt.h>

typedef struct graphic str {

PhPoint t pos;
PhDim t dim;
PhPoint t org;
PhPoint t *points;
int n;
} Graphic;

static Graphic *widget to graphic(PtWidget t *w)

{
PtArg t arg[1];
void *data;
Graphic *graphic;

PtSetArg(&arg[0], Pt ARG USER DATA, &data, 0);

PtGetResources(w, 1, arg);

graphic = data ? *(Graphic **)data : NULL;

return graphic;
}

int rescale cb(PtWidget t *w, void *client data,

264 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGraphic

PtCallbackInfo t *info)
{
PtArg t args[2];
PhDim t factor;
PhDim t *dim;
PhRect t rect;
Graphic *self = widget to graphic(w);
PhPoint t org;
PhPoint t *points;
int n;

if (!self) return ( Pt CONTINUE );

if (!self->points) return ( Pt CONTINUE );

points = (PhPoint t *)alloca(self->n * sizeof(PhPoint t));

if (!points) return ( Pt CONTINUE );

PtBasicWidgetCanvas(PtWidgetParent(w), &rect);

PtSetArg(&args[0], Pt ARG DIM, &dim, 0);

PtGetResources(w, 1, args);

factor = *dim;

for (n = 0; n < self->n; n++)

{
points[n].x = ( self->points[n].x * factor.w ) /
100 + rect.ul.x;
points[n].y = ( self->points[n].y * factor.h ) /
100 + rect.ul.y;
}
org.x = ( self->org.x * factor.w ) /
100 + rect.ul.x;
org.y = ( self->org.y * factor.h ) /
100 + rect.ul.y;

PtSetArg(&args[0], Pt ARG POINTS, points, self->n);

PtSetArg(&args[0], Pt ARG ORIGIN, &org, 0);
PtSetResources(w, 2, args);

return ( Pt CONTINUE );
}

int resize cb(PtWidget t *w, void *client data,

PtCallbackInfo t *info)
{
PtArg t args[2];
PhPoint t pos;
PhDim t dim;
PhDim t *size;
PhDim t factor, nf;
PhRect t rect, prect;
PhRect t *extents = (PhRect t *)info->cbdata;
Graphic *self = widget to graphic(w);
PtWidget t *child = PtWidgetChildFront(w);

if (!self) return ( Pt CONTINUE );

PtBasicWidgetCanvas(PtWidgetParent(w), &prect);

September 20, 2005 Chapter 2 ¯ Widgets 265

PtGraphic  2005, QNX Software Systems

PtBasicWidgetCanvas(w, &rect);

PtSetArg(&args[0], Pt ARG DIM, &size, 0);

PtGetResources(w, 1, args);
nf = *size;

factor.w = extents->lr.x - extents->ul.x + 1;

factor.h = extents->lr.y - extents->ul.y + 1;

pos = self->pos;
dim = self->dim;

pos.x = ( pos.x * factor.w ) / 100 + prect.ul.x;

pos.y = ( pos.y * factor.h ) / 100 + prect.ul.y;

/* this is superfluous */
dim.w = ( dim.w * factor.w ) / 100;
dim.h = ( dim.h * factor.h ) / 100;

PtSetArg(&args[0], Pt ARG POS, &pos, 0);

PtSetResources(w, 1, args);

while (child != NULL)

{
Graphic *g = widget to graphic(child);

if (g)
{
pos = g->pos;
dim = g->dim;

pos.x = ( pos.x * factor.w ) / 100 + rect.ul.x;

pos.y = ( pos.y * factor.h ) / 100 + rect.ul.y;
dim.w = ( dim.w * factor.w ) / 100;
dim.h = ( dim.h * factor.h ) / 100;

PtSetArg(&args[0], Pt ARG POS, &pos, 0);

PtSetArg(&args[1], Pt ARG DIM, &dim, 0);
PtSetResources(child, 2, args);
}

child = PtWidgetBrotherBehind(child);
}

return ( Pt CONTINUE );
}

int main(int argc, char *argv[])

{
PtAppContext t app;
PtArg t args[8];
int nargs;
PhPoint t dim;
PhRect t offsets = {0, 0, 0, 0};
PtWidget t *window, *drawing, *widget;

static PhPoint t face pts[] = { {0,0}, {100,100} };

static PhPoint t eye pts[] = { {0,0}, {100,100} };
static PhPoint t mouth pts[] = { {0,0}, {100,100} };

266 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGraphic

Graphic *graphic;
Graphic smiley = {{0,0}, {100,100}, {0,0}, NULL, 0};
Graphic face = {{0,0}, {100,100}, {0,0}, &face pts,
sizeof(face pts)/sizeof(face pts[0])};
Graphic left eye = {{27,30}, {7,11}, {0,0}, &eye pts,
sizeof(eye pts)/sizeof(eye pts[0])};
Graphic right eye = {{67,30}, {7,11}, {0,0}, &eye pts,
sizeof(eye pts)/sizeof(eye pts[0])};
Graphic mouth = {{10,30}, {80,50}, {0,0}, &mouth pts,
sizeof(mouth pts)/sizeof(mouth pts[0])};

dim.x = 200;
dim.y = 200;
PtSetArg(&args[0], Pt ARG DIM, &dim, 0);

if ((window = PtAppInit(&app, &argc, argv, 0, NULL))

== NULL)
{
return EXIT FAILURE;
}

graphic = &smiley;
nargs = 0;
PtSetArg(&args[nargs], Pt ARG ANCHOR FLAGS,
Pt LEFT ANCHORED LEFT|Pt RIGHT ANCHORED RIGHT|
Pt TOP ANCHORED TOP|Pt BOTTOM ANCHORED BOTTOM,
Pt IS ANCHORED); nargs++;
PtSetArg(&args[nargs], Pt ARG ANCHOR OFFSETS,
&offsets, 0); nargs++;
PtSetArg(&args[nargs], Pt ARG GROUP ORIENTATION,
Pt GROUP ASIS, 0); nargs++;
PtSetArg(&args[nargs], Pt ARG USER DATA, &graphic,
sizeof (Graphic *)); nargs++;
PtSetArg(&args[nargs], Pt ARG POS, &smiley.pos, 0);
nargs++;
PtSetArg(&args[nargs], Pt ARG DIM, &smiley.dim, 0);
nargs++;
drawing = PtCreateWidget(PtGroup, window, nargs, args);
PtAddCallback(drawing, Pt CB RESIZE, resize cb, NULL);

graphic = &face;
nargs = 0;
PtSetArg(&args[nargs], Pt ARG FILL COLOR, Pg YELLOW, 0);
nargs++;
PtSetArg(&args[nargs], Pt ARG USER DATA, &graphic,
sizeof (Graphic *)); nargs++;
PtSetArg(&args[nargs], Pt ARG POS, &face.pos, 0);
nargs++;
PtSetArg(&args[nargs], Pt ARG DIM, &face.dim, 0);
nargs++;
widget = PtCreateWidget(PtEllipse, drawing, nargs, args);
PtAddCallback(widget, Pt CB RESCALE, rescale cb, NULL);

graphic = &mouth;
nargs = 0;
PtSetArg(&args[nargs], Pt ARG ARC START, 2300, 0);
nargs++;
PtSetArg(&args[nargs], Pt ARG ARC END, 3100, 0);
nargs++;
PtSetArg(&args[nargs], Pt ARG ARC TYPE, Pt ARC CHORD, 0);

September 20, 2005 Chapter 2 ¯ Widgets 267

PtGraphic  2005, QNX Software Systems

nargs++;
PtSetArg(&args[nargs], Pt ARG FILL COLOR, Pg BLACK, 0);
nargs++;
PtSetArg(&args[nargs], Pt ARG USER DATA, &graphic,
sizeof (Graphic *)); nargs++;
PtSetArg(&args[nargs], Pt ARG POS, &mouth.pos, 0);
nargs++;
PtSetArg(&args[nargs], Pt ARG DIM, &mouth.dim, 0);
nargs++;
widget = PtCreateWidget(PtArc, drawing, nargs, args);
PtAddCallback(widget, Pt CB RESCALE, rescale cb, NULL);

graphic = &left eye;

nargs = 0;
PtSetArg(&args[nargs], Pt ARG USER DATA, &graphic,
sizeof (Graphic *)); nargs++;
PtSetArg(&args[nargs], Pt ARG FILL COLOR, Pg BLACK, 0);
nargs++;
PtSetArg(&args[nargs], Pt ARG POS, &left eye.pos, 0);
nargs++;
PtSetArg(&args[nargs], Pt ARG DIM, &left eye.dim, 0);
nargs++;
widget = PtCreateWidget(PtEllipse, drawing, nargs, args);
PtAddCallback(widget, Pt CB RESCALE, rescale cb, NULL);

graphic = &right eye;

nargs = 0;
PtSetArg(&args[nargs], Pt ARG USER DATA, &graphic,
sizeof (Graphic *)); nargs++;
PtSetArg(&args[nargs], Pt ARG FILL COLOR, Pg BLACK, 0);
nargs++;
PtSetArg(&args[nargs], Pt ARG POS, &right eye.pos, 0);
nargs++;
PtSetArg(&args[nargs], Pt ARG DIM, &right eye.dim, 0);
nargs++;
widget = PtCreateWidget(PtEllipse, drawing, nargs, args);
PtAddCallback(widget, Pt CB RESCALE, rescale cb, NULL);

PtRealizeWidget(window);

PtMainLoop();

return EXIT SUCCESS;

}

Effects of positional parameters on scaling

It’s important to realize the effect that the position, origin, and
positional coordinates have when rescaling the widget. This will
affect how you choose to use these resources when you create the
graphics widgets and how you scale these resources in your resizing
and scaling functions.

268 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGraphic

The sample resizing function shown here modifies the position of each
of its children, and the sample scaling function modifies the origin
and all the points that define the primitive. This makes the positions
of all sub-drawing and primitives scale along with the drawing itself.
Since the widget’s origin and position allow independent control over
the widget’s position in addition to its size, you have maximum
flexibility in rescaling drawings. To rescale the drawing’s elements
without altering their positions, scale the points that define the
primitive and leave the position and origin alone.
In general, you should alter the widget’s position to affect the position
of the bounding box for the primitive that it will be clipped to. Use
the origin to translate the primitive so that part of it will be clipped.

!
CAUTION: You should always scale graphics based on their original
set of points. If you don’t use the original points, the aspect will be
lost after scaling.

New resources:

Resource C type Pt type Default

Pt ARG DASH LIST char, short Array NULL
Pt ARG DASH SCALE long Scalar 0
Pt ARG GRAPHIC FLAGS char Flag 0
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

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 269

PtGraphic  2005, QNX Software Systems

Resource C type Pt type Default

Pt CB RESCALE PtCallback t * Link NULL

Pt ARG DASH LIST

C type Pt type Default
char, short Array NULL

An array of bytes that describes the on and off bits for stroke
operations.

Pt ARG DASH SCALE

C type Pt type Default
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

C type Pt type Default
char Flag 0

Possible values:

Pt FLOAT POS
Adjusts the position and origin of the widget, but leaves the
graphic in place relative to the widget’s parent. The upper left
corner of the widget’s canvas will be 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.

270 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGraphic

Pt FLOAT ORIGIN
Adjusts the origin of the graphic, but leaves the widget in place
relative to its parent. The upper left corner of the bounding box
described by the point array will be 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 LINE CAP

C type Pt type Default
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

C type Pt type Default
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)

September 20, 2005 Chapter 2 ¯ Widgets 271

PtGraphic  2005, QNX Software Systems

Pt ARG LINE WIDTH

C type Pt type Default
long Scalar 0

The line width for any graphically based widget.

Pt ARG ORIGIN
C type Pt type Default
PhPoint t Struct 0,0

An offset from the upper left corner of the widget’s canvas. The
graphic will be rendered with its origin at:

(widget position) + (Pt ARG ORIGIN)

Pt ARG POINTS
C type Pt type Default
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 — depends on the type of graphics primitive being
defined.

Pt CB RESCALE
C type Pt type Default
PtCallback t * Link NULL

272 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGraphic

A list of callbacks that the widget invokes if its Pt ARG DIM or

Pt ARG AREA resources are modified. You can use this callback to
rescale the widget.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB RESCALE

reason subtype
0 (not used).

cbdata Points to a PhArea t structure that indicates the old area

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

These callbacks should return Pt CONTINUE.

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 AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CURSOR COLOR PtWidget

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 273

PtGraphic  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic Pg TRANSPARENT
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget

continued. . .

274 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGraphic

Resource Inherited from Default override

Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB UNREALIZED PtWidget

September 20, 2005 Chapter 2 ¯ Widgets 275

PtGrid  2005, QNX Software Systems
A grid pattern

Class hierarchy:
PtWidget → PtBasic → PtGrid

PhAB icon:

Public header:
<photon/PtGrid.h>

Description:
PtGrid draws a grid pattern via PgDrawGrid().

A PtGrid widget.

New resources:

Resource C type Pt type Default

Pt ARG DASH LIST char, short Array NULL
Pt ARG DASH SCALE long Scalar 0
Pt ARG GRID VERTICAL short Scalar 4

continued. . .

276 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGrid

Resource C type Pt type Default

Pt ARG GRID HORIZONTAL short Scalar 4
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 DASH LIST

C type Pt type Default
char, short Array NULL

An array of bytes that describes the on and off bits for stroke
operations (see PgSetStrokeDash() in the Library Reference).

Pt ARG DASH SCALE

C type Pt type Default
long Scalar 0

A value that indicates the number of pixels represented by each of the

bits in the dash list (see PgSetStrokeDash() in the Photon Library
Reference).

Pt ARG GRID HORIZONTAL

C type Pt type Default
short Scalar 4

The number of horizontal lines in the grid.

September 20, 2005 Chapter 2 ¯ Widgets 277

PtGrid  2005, QNX Software Systems

Pt ARG GRID VERTICAL

C type Pt type Default
short Scalar 4

The number of vertical lines in the grid.

Pt ARG LINE CAP

C type Pt type Default
unsigned short Scalar Pg BUTT CAP

Defines how the ends of thick lines are drawn; see PgSetStrokeCap()
in the Photon Library Reference. Possible values:

¯ Pg BUTT CAP

¯ Pg ROUND CAP

¯ Pg SQUARE CAP

Pt ARG LINE JOIN

C type Pt type Default
unsigned short Scalar Pg MITER JOIN

Defines how thick lines are connected; see PgSetStrokeJoin() in the

Photon Library Reference. Possible values:

¯ Pg BEVEL JOIN

¯ Pg BUTT JOIN

¯ Pg MITER JOIN

¯ Pg ROUND JOIN

¯ Pg QROUND JOIN — : quick rounded join.

278 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGrid

Pt ARG LINE WIDTH

C type Pt type Default
long Scalar 0

The line width for the grid pattern.

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 AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 279

PtGrid  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB UNREALIZED PtWidget

280 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGroup
A container that can arrange its children in rows and columns

Class hierarchy:
PtWidget → PtBasic → PtContainer → PtGroup

PhAB icon:
None — use PhAB’s Group Together button in the speedbar:

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, and PtGroup may give them
exclusive-selection behavior.

Done Apply Default Cancel

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:

September 20, 2005 Chapter 2 ¯ Widgets 281

PtGroup  2005, QNX Software Systems

Resource C type Pt type Default

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
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 GROUP FLAGS

C type Pt type Default
unsigned long Flag 0

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, the user can deselect the currently selected child without
having to select another child. To do this, the user simply clicks
on the currently selected child.

Pt GROUP NO KEYS
Prevent the group from using any keys (e.g. arrows).

282 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGroup

Pt GROUP NO KEY WRAP HORIZONTAL

Don’t use key that would cause horizontal wrap.
Pt GROUP NO KEY WRAP VERTICAL
Don’t use key 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 children in group same width.

Pt GROUP EQUAL SIZE VERTICAL

Make children in group same height.

Pt GROUP STRETCH HORIZONTAL

Stretch the rightmost children in group horizontally to fill its
canvas.
Pt GROUP STRETCH VERTICAL
Stretch the bottommost children in 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.

The default setting of this resource is 0; that is, no flags have been set.

☞ 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

September 20, 2005 Chapter 2 ¯ Widgets 283

PtGroup  2005, QNX Software Systems

C type Pt type Default

unsigned short Scalar Pt GROUP HORZ CENTER

Determines how the children are aligned 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

C type Pt type Default
unsigned short Scalar Pt GROUP HORIZONTAL

Possible values:

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

C type Pt type Default
unsigned short Scalar 0

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.

284 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGroup

Not used for an “as is” group; see Pt ARG GROUP ORIENTATION,
above.

Pt ARG GROUP SPACING

C type Pt type Default
unsigned short Scalar 0

If alignment is in effect, this resource defines how many pixels will

separate each child of the group.

☞ If you set this resource, you’ll automatically set

Pt ARG GROUP SPACING X and Pt ARG GROUP SPACING Y to
the same value.

Pt ARG GROUP SPACING X

C type Pt type Default
unsigned short Scalar 0

If alignment is in effect, this resource defines how many pixels will

separate each child of the group horizontally.

Pt ARG GROUP SPACING Y

C type Pt type Default
unsigned short Scalar 0

If alignment is in effect, this resource defines how many pixels will

separate each child of the group vertically.

Pt ARG GROUP VERT ALIGN

September 20, 2005 Chapter 2 ¯ Widgets 285

PtGroup  2005, QNX Software Systems

C type Pt type Default

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

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 PtContainer
Pt ARG ANCHOR OFFSETS PtContainer
Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer
Pt ARG CURSOR COLOR PtWidget

continued. . .

286 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtGroup

Resource Inherited from Default override

Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic Pg TRANSPARENT
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic 0
Pt ARG MARGIN WIDTH PtBasic 0
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY AS REQUIRED
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 287

PtGroup  2005, QNX Software Systems

Resource Inherited from Default override

Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
Pt CB UNREALIZED PtWidget

288 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtHtml
A widget for displaying HTML files

Class hierarchy:
PtWidget → PtBasic → PtContainer → PtHtml

PhAB icon:

Public header:
<photon/PtHtml.h>

☞ You’ll need some other definitions and header files, depending on

what kinds of images your widget will display. You need to define at
least one type of image. See “Supporting images” below.

Description:
The PtHtml widget displays files containing the Hypertext Markup
Language (HTML).

Bookset overview

User’s Guide
If you’re using Photon for the first time, this guide is your starting point.
It tells you how to start Photon, move around in the workspace, and
use Photon applications.

Installation & Configuration

This guide contains installation instructions, configuration options, and
an alphabetic reference of all Photon command- line utilities and

A PtHtml widget.

This widget supports HTML 1.0 with a few extensions (such as

simple table support), and can load files only from the local

September 20, 2005 Chapter 2 ¯ Widgets 289

PtHtml  2005, QNX Software Systems

filesystem. For this reason, the widget wouldn’t be useful in an

application such as a web browser, which would require many more
features.
Instead, the widget is intended to be used to create a custom
helpviewer or similar applications, which require the display of
formatted text and images with hyperlinks.
Given the filename of an HTML file, the widget will load and render
the HTML within the canvas (or viewport) of the widget. If the
rendered page is larger than the viewport, the widget will create
scrollbars so that the user can scroll around the page.
The widget lets you attach callbacks, which will be called before and
after a new file is loaded (for example if the user clicks on a
hyperlink), and before any inline images are loaded.

Elements
The following table summarizes the HTML elements and attributes
supported by the PtHtml class.
For some of the elements, the end tag is optional and is indicated by
square brackets.
The attributes are shown with the possible attribute values. Where
more than one option is shown, one of them must be selected.

Element Tags Attributes

Comment <!-- comment -->
Document <html>...</html>
Head <head>...</head>
Title <title>...</title>
Link <link> href=url, rel=string
Body <body>...</body>

continued. . .

290 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtHtml

Element Tags Attributes

Heading 1 <h1>...</h1> id=string,
align={left,center,right}
Heading 2 <h2>...</h2> id=string,
align={left,center,right}
Heading 3 <h3>...</h3> id=string,
align={left,center,right}
Heading 4 <h4>...</h4> id=string,
align={left,center,right}
Heading 5 <h5>...</h5> id=string,
align={left,center,right}
Heading 6 <h6>...</h6> id=string,
align={left,center,right}
Rule <hr> id=string
Paragraph <p>...[</p>] id=string
Linebreak <br> id=string
Image <img> src=url,
align={top,middle,bottom},
alt=string, id=string
Anchor <a>...</a> href=url, name=string,
id=string
Preformatted <pre>...</pre> id=string
Blockquote <blockquote>...</blockquote> id=string
Address <address>...</address> id=string
Note <note>...</note> src=url, id=string
Definition list <dl>...</dl> compact, id=string
Term <dt>...[</dt>] id=string

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 291

PtHtml  2005, QNX Software Systems

Element Tags Attributes

Description <dd>...[</dd>] id=string
Ordered list <ol>...</ol> id=string
Unordered list <ul>...</ul> id=string
List item <li>...[</li>] id=string
Emphasis <em>...</em> id=string
Strong <strong>...</strong> id=string
Code <code>...</code> id=string
Sample <samp>...</samp> id=string
Keyboard <kbd>...</kbd> id=string
Variable <var>...</var> id=string
Definition <dfn>...</dfn> id=string
Citation <cite>...</cite> id=string
Teletype <tt>...</tt> id=string
Bold <b>...</b> id=string
Italic <i>...</i> id=string
Underlined <u>...</u> id=string
Table <table>...</table> border,
align={left,center,right},
id=string
Table heading <th>...[</th>] align={left,center,right},
id=string
Table data <td>...[</td>] align={left,center,right},
id=string
Table row <tr>...[</tr>] id=string

292 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtHtml

Entities
The PtHtml widget supports the standard HTML 1.0 and ISO-8859
character entities. An entity starts with an ampersand, is followed by
the entity name, and ends with a semicolon (e.g. &copy; is rendered
as ).
PtHtml also supports the following entities:

Entity: Meaning: Rendered as:

&nbsp; Nonbreaking space Space
&emsp; Em-space Space
&ensp; En-space Space
&mdash; Em-dash Dash (-)
&ndash; En-dash Dash (-)
&ldquo; Left double quote “
&rdquo; Right double quote ”
&lsquo; Left single quote ‘
&rsquo; Right single quote ’
&trade; Trademark TM

Supporting images
To have the PtHtml widget support images, include code similar to
the following example somewhere in your program (e.g. in the
application’s init file):

/* image headers */
#define PX IMAGE MODULES
#define PX GIF SUPPORT
#define PX BMP SUPPORT
#include <photon/PxImage.h>

September 20, 2005 Chapter 2 ¯ Widgets 293

PtHtml  2005, QNX Software Systems

This will cause the code for displaying GIF and BMP images to be
linked into your program. For more information, see PxLoadImage()
in the Photon Library Reference.

Printing
To support printing, the html widget has a special page mode, which
you can set in the Pt ARG HTML FLAGS resource. When in page
mode, the widget tries to do a clean page break when the height of the
current page is greater than the vertical display area. The loaded file is
then divided into one or more pages.
The number of pages can be read from the Pt ARG HTML PAGES
resource. To display a particular page, you can set the
Pt ARG HTML PAGE N resource. To print the current page, you can
use the standard widget-printing mechanisms.

New resources:

Resource C type Pt type Default

Pt ARG HTML BORDER WIDTH short Scalar 1
Pt ARG HTML CURSOR BUSY short Scalar Ph CURSOR CLOCK
Pt ARG HTML CURSOR DEFAULT short Scalar Ph CURSOR POINTER
Pt ARG HTML CURSOR LINK short Scalar Ph CURSOR FINGER
Pt ARG HTML FILL COLOR PgColor t Scalar Pg GREY
Pt ARG HTML FLAGS long Flag 0
Pt ARG HTML H1 FONT char * String "helv24"
Pt ARG HTML H2 FONT char * String "helv18"
Pt ARG HTML H3 FONT char * String "helv14"
Pt ARG HTML H4 FONT char * String "helv12"

continued. . .

294 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtHtml

Resource C type Pt type Default

Pt ARG HTML H5 FONT char * String "helv10"
Pt ARG HTML H6 FONT char * String "helv08"
Pt ARG HTML LINK COLOR PgColor t Scalar Pg DBLUE
Pt ARG HTML PAGE BM short Scalar 5
Pt ARG HTML PAGE H int Scalar 0 (read-
only)
Pt ARG HTML PAGE LM short Scalar 5
Pt ARG HTML PAGE N long Scalar 0
Pt ARG HTML PAGE RM short Scalar 5
Pt ARG HTML PAGE TM short Scalar 5
Pt ARG HTML PAGE W int Scalar 0 (read-
only)
Pt ARG HTML PAGE X int Scalar 0
Pt ARG HTML PAGE Y int Scalar 0
Pt ARG HTML PAGES long Scalar 0 (read-
only)
Pt ARG HTML SCROLL COLOR PgColor t Scalar Pg GREY
Pt ARG HTML SCROLL FILL COLOR PgColor t Scalar Pg MGREY
Pt ARG HTML SCROLL HORIZONTAL short Scalar Pt ALWAYS
Pt ARG HTML SCROLL VERTICAL short Scalar Pt ALWAYS
Pt ARG HTML SCROLL WIDTH short Scalar 15
Pt ARG HTML TEXT FONT char * String "helv14"
Pt ARG HTML URL char * String NULL
Pt CB HTML ERROR PtCallback t * Link NULL

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 295

PtHtml  2005, QNX Software Systems

Resource C type Pt type Default

Pt CB HTML FILE POST PtCallback t * Link NULL
Pt CB HTML FILE PRE PtCallback t * Link NULL
Pt CB HTML IMAGE PtCallback t * Link NULL

Pt ARG HTML BORDER WIDTH

C type Pt type Default
short Scalar 1

The width of the inside border surrounding the canvas of the widget,
and the width of the border of the scrollbars. The width of the outside
border of the widget is set using the Pt ARG BORDER WIDTH
resource.

Pt ARG HTML CURSOR BUSY

C type Pt type Default
short Scalar Ph CURSOR CLOCK

The cursor when loading a file.

Pt ARG HTML CURSOR DEFAULT

C type Pt type Default
short Scalar Ph CURSOR POINTER

The default cursor.

Pt ARG HTML CURSOR LINK

296 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtHtml

C type Pt type Default

short Scalar Ph CURSOR FINGER

The cursor when over a link.

Pt ARG HTML FILL COLOR

C type Pt type Default
PgColor t Scalar Pg GREY

The RGB color value used to draw the background of the HTML
page.

Pt ARG HTML FLAGS

C type Pt type Default
long Flag 0

Flags for changing the behavior of the widget. The possible values
are:

¯ Pt HTML RELOAD — load a page even if its URL is the same as

the current page’s.

¯ Pt HTML PAGE MODE — put the widget into page mode for
printing.
For more information, see “Printing,” above.

Pt ARG HTML H1 FONT

C type Pt type Default
char * String "helv24"

The font to be used to display the heading level 1 text.

September 20, 2005 Chapter 2 ¯ Widgets 297

PtHtml  2005, QNX Software Systems

Pt ARG HTML H2 FONT

C type Pt type Default
char * String "helv18"

The font to be used to display the heading level 2 text.

Pt ARG HTML H3 FONT

C type Pt type Default
char * String "helv14"

The font to be used to display the heading level 3 text.

Pt ARG HTML H4 FONT

C type Pt type Default
char * String "helv12"

The font to be used to display the heading level 4 text.

Pt ARG HTML H5 FONT

C type Pt type Default
char * String "helv10"

The font to be used to display the heading level 5 text.

Pt ARG HTML H6 FONT

C type Pt type Default
char * String "helv08"

The font to be used to display the heading level 6 text.

298 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtHtml

Pt ARG HTML LINK COLOR

C type Pt type Default
PgColor t Scalar Pg DBLUE

The RGB color value used to draw links.

Pt ARG HTML PAGE BM

C type Pt type Default
short Scalar 5

The width of the bottom margin of the rendered HTML page.

Pt ARG HTML PAGE H (read-only)

C type Pt type Default
int Scalar 0

The height of the rendered HTML page.

Pt ARG HTML PAGE LM

C type Pt type Default
short Scalar 5

The width of the left margin of the rendered HTML page.

Pt ARG HTML PAGE N

C type Pt type Default
long Scalar 0

When the widget is in page mode (i.e. Pt HTML PAGE MODE is set in
Pt ARG HTML FLAGS), this resource holds the current page number.

September 20, 2005 Chapter 2 ¯ Widgets 299

PtHtml  2005, QNX Software Systems

You can set this resource to display a particular page. For more
information, see “Printing,” above.

Pt ARG HTML PAGE RM

C type Pt type Default
short Scalar 5

The width of the right margin of the rendered HTML page.

Pt ARG HTML PAGE TM

C type Pt type Default
short Scalar 5

The width of the top margin of the rendered HTML page.

Pt ARG HTML PAGE W (read-only)

C type Pt type Default
int Scalar 0

The width of the rendered HTML page.

Pt ARG HTML PAGE X

C type Pt type Default
int Scalar 0

The horizontal position (in pixels) of the top-left hand corner of the
viewport relative to the rendered HTML page. Horizontal scrolling
changes the x position.

300 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtHtml

Pt ARG HTML PAGE Y

C type Pt type Default
int Scalar 0

The vertical position (in pixels) of the top-left hand corner of the
viewport relative to the rendered HTML page. Vertical scrolling
changes the y position.

Pt ARG HTML PAGES (read-only)

C type Pt type Default
long Scalar 0

When the widget is in page mode (i.e. Pt HTML PAGE MODE is set in
Pt ARG HTML FLAGS), this resource holds the number of pages in
the current document. For more information, see “Printing,” above.

Pt ARG HTML SCROLL COLOR

C type Pt type Default
PgColor t Scalar Pg GREY

The RGB color value used to draw the slider of the scrollbars.

Pt ARG HTML SCROLL FILL COLOR

C type Pt type Default
PgColor t Scalar Pg MGREY

The RGB color value used to draw the trough of the scrollbars.

September 20, 2005 Chapter 2 ¯ Widgets 301

PtHtml  2005, QNX Software Systems

Pt ARG HTML SCROLL HORIZONTAL

C type Pt type Default
short Scalar Pt ALWAYS

The horizontal scrollbar mode. Possible values are:

¯ Pt ALWAYS

¯ Pt AS REQUIRED — the scrollbar is displayed only if the page

width is larger than the viewport width.

¯ Pt NEVER

Pt ARG HTML SCROLL VERTICAL

C type Pt type Default
short Scalar Pt ALWAYS

The vertical scrollbar mode. Possible values are:

¯ Pt ALWAYS

¯ Pt AS REQUIRED — the scrollbar is displayed only if the page

height is larger than the viewport height.

¯ Pt NEVER

Pt ARG HTML SCROLL WIDTH

C type Pt type Default
short Scalar 15

The width of the vertical scrollbar and the height of the horizontal
scrollbar, in pixels.

302 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtHtml

Pt ARG HTML TEXT FONT

C type Pt type Default
char * String "helv14"

The font to be used to display the body text.

Pt ARG HTML URL

C type Pt type Default
char * String NULL

The Universal Resource Locator (URL) of the HTML file to be

displayed. The URL can have the form:
//node/directory/file.html#name
When the URL resource is set, the widget loads and displays the
HTML file (and any images in the file), moving to the position of
identifier name on the page. If the given file path is relative (doesn’t
start with a forward slash) then an absolute path is constructed relative
to the currently displayed file.

Pt CB HTML ERROR
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks the widget invokes when the given URL can’t be
opened.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB HTML ERROR

cbdata A pointer to a PtHtmlCallback t structure that

contains at least the following member:

September 20, 2005 Chapter 2 ¯ Widgets 303

PtHtml  2005, QNX Software Systems

char *url; The URL of the file that couldn’t be loaded

by the widget.

These callbacks should return Pt CONTINUE.

Pt CB HTML FILE POST

C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that the widget invokes after loading an HTML file.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB HTML FILE POST

cbdata A pointer to a PtHtmlCallback t structure that

contains at least the following member:

char *url; The full URL of the currently loaded file.

This can be used to implement a history
mechanism by recording the URL.

These callbacks should return Pt CONTINUE.

Pt CB HTML FILE PRE

C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that the widget invokes before loading an HTML

file.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

304 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtHtml

reason Pt CB HTML FILE PRE

cbdata A pointer to a PtHtmlCallback t structure that

contains at least the following member:

char *url; The URL of the HTML file about to be

loaded. The URL is given exactly as it was
specified in the HTML file. The URL can
be changed here if another file should be
loaded instead, or set to NULL if no file
should be loaded.

These callbacks should return Pt CONTINUE.

Pt CB HTML IMAGE
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that the widget invokes before loading an image

file.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB HTML IMAGE

cbdata A pointer to a PtHtmlCallback t structure that

contains at least the following member:

char *url; The URL of the image about to be loaded.

The URL is given exactly as it was specified
in the HTML file. The URL can be changed
here if another file should be loaded instead,
or set to NULL if no file should be loaded.

These callbacks should return Pt CONTINUE.

September 20, 2005 Chapter 2 ¯ Widgets 305

PtHtml  2005, QNX Software Systems

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 PtContainer Pt TOP ANCHORED TOP
|
Pt RIGHT ANCHORED RIGHT
|
Pt BOTTOM ANCHORED BOTTOM
|
Pt LEFT ANCHORED LEFT
Pt ARG ANCHOR OFFSETS PtContainer
Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 1
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic Pg GREY

continued. . .

306 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtHtml

Resource Inherited from Default override

Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic 2
Pt ARG MARGIN WIDTH PtBasic 2
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget 0
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 307

PtHtml  2005, QNX Software Systems

Resource Inherited from Default override

Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
Pt CB UNREALIZED PtWidget

Convenience functions:
The following convenience functions are defined by the PtHtml class
for accessing some of the data in the HTML file. Here’s a brief
overview:

PtHtmlTitle() Returns the title of an HTML file.

PtHtmlLink() Returns links to related HTML documents.

308 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtHtmlLink()
Search for links to related HTML documents

Synopsis:
char * PtHtmlLink( PtWidget t *widget,
char *rel );

Description:
This function searches the current HTML file for the given widget,
looking for a <LINK> tag whose REL attribute matches the rel
argument. If the <LINK> tag is found, the function returns a pointer to
a string containing the href attribute.
For example, PtHtmlLink() would return the string sample.html if
called with the rel argument set to the string previous with the
following link tag in the HTML file:

<link href="sample.html" rel="previous">

Returns:
A pointer to the filename for the requested link, or NULL if the link
couldn’t be found.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 309

PtHtmlTitle()  2005, QNX Software Systems
Return the title of an HTML file

Synopsis:
char * PtHtmlTitle( PtWidget t * widget );

Description:
This function returns a pointer to a string containing the title of the
HTML file or NULL.
For example, PtHtmlTitle() returns the string This is the title
if the HTML file currently loaded by the widget has the following title
tag:

<title>This is the title</title>

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

310 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtIcon
A container for bitmap or image icons for use by PDM

Class hierarchy:
PtWidget → PtBasic → PtContainer → PtWindow → PtIcon

PhAB icon:
None — use PhAB’s Icon module.

Public header:
<photon/PtIcon.h>

Description:
A PtIcon widget behaves like a window, providing a container for
image or bitmap widgets. Normally two icon images are placed into a
PtIcon — a large 43¢43 icon for display through the Photon
Desktop Manager, and a small 15¢15 icon for display in the PDM
Taskbar.

An icon.

Use PhAB’s Icon module instead of this widget. See “Icon modules”
in the Working with Modules chapter of the Photon Programmer’s
Guide.

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.

September 20, 2005 Chapter 2 ¯ Widgets 311

PtIcon  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG ANCHOR FLAGS PtContainer Not used by this
class.
Pt ARG ANCHOR OFFSETS PtContainer Not used by this
class.
Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this
class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer Not used by this
class.
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget 43,43
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget |=Pt DELAY REALIZE
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG ICON WINDOW PtWindow

continued. . .

312 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtIcon

Resource Inherited from Default override

Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN WIDTH PtBasic
Pt ARG MAX HEIGHT PtWindow
Pt ARG MAX WIDTH PtWindow
Pt ARG MIN HEIGHT PtWindow
Pt ARG MIN WIDTH PtWindow
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Not used by this
class.
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt ARG WINDOW ACTIVE COLOR PtWindow Not used by this
class.
Pt ARG WINDOW CURSOR OVERRIDE PtWindow Not used by this
class.
Pt ARG WINDOW FRONT WINDOW PtWindow Not used by this
class.
Pt ARG WINDOW HELP ROOT PtWindow Not used by this
class.
Pt ARG WINDOW INACTIVE COLOR PtWindow Not used by this
class.
Pt ARG WINDOW MANAGED FLAGS PtWindow Ph WM ICON DEF MANAGED
Pt ARG WINDOW NOTIFY FLAGS PtWindow Ph WM ICON DEF NOTIFY|
Ph WM HIDE|
Ph WM CLOSE

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 313

PtIcon  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG WINDOW RENDER FLAGS PtWindow Ph WM ICON DEF RENDER
Pt ARG WINDOW STATE PtWindow Ph WM STATE ISTASKBAR
Pt ARG WINDOW TITLE PtWindow
Pt ARG WINDOW TITLE COLOR PtWindow Not used by this
class.
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer Not used by this
class.
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
Pt CB UNREALIZED PtWidget
Pt CB WINDOW PtWindow

continued. . .

314 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtIcon

Resource Inherited from Default override

Pt CB WINDOW CLOSING PtWindow Not used by this
class.
Pt CB WINDOW OPENING PtWindow Not used by this
class.
Pt CB WINDOW TRANSPORT PtWindow Not used by this
class.

September 20, 2005 Chapter 2 ¯ Widgets 315

PtLabel  2005, QNX Software Systems
A text, bitmap, or image label

Class hierarchy:
PtWidget → PtBasic → PtLabel

PhAB icon:

Public header:
<photon/PtLabel.h>

Description:
The PtLabel class provides a text string, bitmap, or image for
labeling other widgets. When you use PtLabel to display a bitmap
or image, you can have text pop up in a balloon to provide further
meaning to the image.
Enter string:

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 will appear above the object.
There’s no limit to the number of places you may wish to use label
objects, but the most frequent use 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.
Labels aren’t restricted to textual tags either. If you want to put a
graphical representation such as an icon beside an object, you may
use an image as the label.

316 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtLabel

Creating labels
You create labels using the PtLabel widget class. You can use text
and images for the label. The default label type is a null-terminated
text string.
To specify the type of label you want, you must 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 should be an image, typically a small

icon. The data for the widget is an image structure.

Pt TEXT IMAGE
The label will display an image and text. The
positioning of these two elements relative to each
other is determined by the
Pt ARG BALLOON POSITION resource.

The data for the label is specified in different ways for each type.
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 (like the palette in the Photon
Application Builder) to a textual representation of the same labels.
The label is switched 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.

September 20, 2005 Chapter 2 ¯ Widgets 317

PtLabel  2005, QNX Software Systems

To specify the font the label should be drawn with when text labels
are used, set the resource Pt ARG TEXT FONT to the name of the
font you want.
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 are specified using these
resources:

¯ 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. The values to specify for this horizontal alignment are:

¯ Pt LEFT — text is aligned to the left margin.

¯ Pt RIGHT — text is aligned to the right margin.

¯ Pt CENTER — text is centered between the left and right margins.

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. The values to specify for the vertical
alignment are:

¯ Pt TOP — text is aligned to the top margin.

¯ Pt BOTTOM — text is aligned to the bottom margin.

318 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtLabel

¯ Pt CENTER — text is centered between the top and bottom

margins.

Normally, the text displayed in the label widget will be aligned to the
widget’s top and left margins. 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 will be 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 DATA 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

September 20, 2005 Chapter 2 ¯ Widgets 319

PtLabel  2005, QNX Software Systems

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. The bit ordering
is most significant bit first. The two types of bitmap are:
¯ Pg BITMAP BACKFILL — a bitonal image — the two
colors are specified in the color palette.
¯ Pg BITMAP TRANSPARENT — a monochrome image
with transparent regions. “Ones” in the image data 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. The bit ordering
within a nibble is most significant bit first.
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.

320 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtLabel

¯ Pg IMAGE DIRECT 555 — 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 is 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 Photon Programmer’s Guide.

Balloons
Balloons are a very handy feature of the PtLabel widget class. You
use a balloon to display a line of text when the user’s pointer pauses
on top of a widget for more than a second.
This can be very useful in an application with a lot of labels or buttons
containing iconic images. Whenever the user pauses on an icon, a
little text box will pop 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 flag for the

Pt ARG LABEL FLAGS resource.

2 Set the Pt ARG BALLOON POSITION resource to define the

location.

The Pt ARG TEXT STRING resource defines the text displayed in the
balloon. If the entire string is visible within the widget, you probably
don’t need to set the Pt SHOW BALLOON flag. If the label has been

September 20, 2005 Chapter 2 ¯ Widgets 321

PtLabel  2005, QNX Software Systems

truncated or is currently displaying an iconic image, you can set the

flag and the balloon feature will be automatically enabled for the
widget.

New resources:

Resource C type Pt type Default

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 HORIZONTAL ALIGNMENT unsigned char Scalar Pt LEFT
Pt ARG LABEL BALLOON PtWidget t * (*)() Pointer Pt INFLATE BALLOON
Pt ARG LABEL DATA void * Alloc NULL
Pt ARG LABEL FLAGS char Flag Pt LABEL SELECT SHIFT

Pt ARG LABEL TYPE char Scalar Pt Z STRING

Pt ARG LINE SPACING ushort t 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 TEXT FONT char * String "helv12"
Pt ARG TEXT STRING char * String NULL
Pt ARG UNDERLINE1 unsigned short Scalar Pg BLACK
Pt ARG UNDERLINE2 unsigned short Scalar Pg TRANSPARENT

continued. . .

322 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtLabel

Resource C type Pt type Default

Pt ARG UNDERLINE TYPE unsigned short Scalar Pt NO ULINE
Pt ARG VERTICAL ALIGNMENT unsigned char Scalar Pt CENTER

Pt ARG ACCEL KEY

C type Pt type Default
char * String NULL

Lets you underline the accelerator key within the widget’s text string.
You typically use this resource for hotkeys.

Pt ARG BALLOON COLOR

C type Pt type Default
PgColor t Scalar Pg BLACK

Defines the balloon’s text color.

Pt ARG BALLOON FILL COLOR

C type Pt type Default
PgColor t Scalar Pt BALLOONCOLOR

Defines the balloon’s fill color.

Pt ARG BALLOON POSITION

C type Pt type Default
short Scalar Pt BALLOON RIGHT

Indicates where the label text will pop up. If Pt ARG LABEL TYPE is
Pt TEXT IMAGE, this reource controls the positioning of the text and
image elements relative to each other. Possible values:

September 20, 2005 Chapter 2 ¯ Widgets 323

PtLabel  2005, QNX Software Systems

¯ Pt BALLOON INPLACE

¯ Pt BALLOON TOP

¯ Pt BALLOON LEFT

¯ Pt BALLOON RIGHT

¯ Pt BALLOON BOTTOM

Pt ARG HORIZONTAL ALIGNMENT

C type Pt type Default
unsigned char Scalar Pt LEFT

The horizontal alignment for the text string. Possible values:

¯ Pt LEFT

¯ Pt CENTER

¯ Pt RIGHT

Pt ARG LABEL BALLOON

C type Pt type Default
PtWidget t * (*)() Pointer Pt INFLATE BALLOON

By default, when a user pauses the pointer over this widget, the
widget will display a small yellow balloon. If you want to change the
look or default text of the balloon, you can use this resource to
override the default inflate function.
Here’s a 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 );

324 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtLabel

where:

window The window widget of the widget that requires the

balloon.

widget The widget that requires the balloon.

position The balloon-position resource (see

Pt ARG BITMAP BALLOON POSITION in
PtBitmap).

text The text to display (see Pt ARG BITMAP TEXT in

PtBitmap).

font The font for the text.

fill color The fill color (see

Pt ARG BITMAP BALLOON FILL COLOR in
PtBitmap).

text color The balloon-text color (see

Pt ARG BITMAP BALLOON COLOR in PtBitmap).

You can use the supplied values in your inflate function or ignore
them and use your own values.

Pt ARG LABEL DATA

C type Pt type Default
void * Alloc NULL

A pointer. If the label type (see Pt ARG LABEL TYPE, below) is

Pt IMAGE, this resource is used to pass data to the widget.

September 20, 2005 Chapter 2 ¯ Widgets 325

PtLabel  2005, QNX Software Systems

☞ Remember that this is an Alloc resource. 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 LABEL FLAGS

C type Pt type Default
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 ARG LABEL TYPE

C type Pt type Default
char Scalar Pt Z STRING

326 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtLabel

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 DATA to display an image.

See PhImage t, 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.

Pt TEXT IMAGE
Display the image and text of the label. The
positioning of these two elements relative to each
other is determined by the
Pt ARG BALLOON POSITION resource.

Pt ARG LINE SPACING

C type Pt type Default
ushort t Scalar 0

The space, in pixels, between the lines of text in the label.

Pt ARG MARGIN BOTTOM

C type Pt type Default
unsigned short Scalar 0

The amount of space between the bottom of the label’s canvas and the
canvas defined by the basic widget.

September 20, 2005 Chapter 2 ¯ Widgets 327

PtLabel  2005, QNX Software Systems

Pt ARG MARGIN LEFT

C type Pt type Default
unsigned short Scalar 0

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

C type Pt type Default
unsigned short Scalar 0

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

C type Pt type Default
unsigned short Scalar 0

The amount of space between the top of the label’s canvas and the
canvas defined by the basic widget.

Pt ARG TEXT FONT

C type Pt type Default
char * String "helv12"

The font used for the label’s text string; see PgSetFont().

Pt ARG TEXT STRING

328 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtLabel

C type Pt type Default

char * String NULL

The text string to be displayed if Pt ARG LABEL TYPE is

Pt Z STRING or Pt TEXT IMAGE.

Pt ARG UNDERLINE1
C type Pt type Default
unsigned short Scalar Pg BLACK

The underline color for the first line.

Pt ARG UNDERLINE2
C type Pt type Default
unsigned short Scalar Pg TRANSPARENT

The underline color for the second line (used to create thick or
beveled underlines).

Pt ARG UNDERLINE TYPE

C type Pt type Default
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)

September 20, 2005 Chapter 2 ¯ Widgets 329

PtLabel  2005, QNX Software Systems

Pt ARG VERTICAL ALIGNMENT

C type Pt type Default
unsigned char Scalar Pt CENTER

The vertical alignment for the text string. Possible values:

¯ Pt TOP

¯ Pt CENTER

¯ Pt BOTTOM

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 AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget

continued. . .

330 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtLabel

Resource Inherited from Default override

Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic 2
Pt ARG MARGIN WIDTH PtBasic 2
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY AS REQUIRED
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 331

PtLabel  2005, QNX Software Systems

Resource Inherited from Default override

Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB UNREALIZED PtWidget

332 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtLine
A line

Class hierarchy:
PtWidget → PtBasic → PtGraphic → PtLine

PhAB icon:

Public header:
<photon/PtLine.h>

Description:
The PtLine widget is used 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.

September 20, 2005 Chapter 2 ¯ Widgets 333

PtLine  2005, QNX Software Systems

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 AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DASH LIST PtGraphic
Pt ARG DASH SCALE PtGraphic
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG GRAPHIC FLAGS PtGraphic
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic

continued. . .

334 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtLine

Resource Inherited from Default override

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 ORIGIN PtGraphic
Pt ARG POINTS PtGraphic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 335

PtLine  2005, QNX Software Systems

Resource Inherited from Default override

Pt CB REPEAT PtBasic
Pt CB RESCALE PtGraphic
Pt CB UNREALIZED PtWidget

336 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtList
A scrolling list of text items

Class hierarchy:
PtWidget → PtBasic → PtContainer → PtCompound →
PtGenList → 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.

Item 1
Item 2
Item 3

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).

Limitations
PtList widgets have a few limitations:

¯ They display only text. If you want to display an image to the left
of each item, use a PtTree instead.
¯ All items are in the same font.
¯ All unselected items are the same color

September 20, 2005 Chapter 2 ¯ Widgets 337

PtList  2005, QNX Software Systems

¯ All selected items are the same color.

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.

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, the Tab character is used in the item strings as a
column separator.

☞ 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.

338 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtList

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 scroll bar so the user can scroll through the whole
list.

☞ The Pt ARG VISIBLE COUNT resource is inherited from

PtGenList but is used differently. For PtGenList,
Pt ARG VISIBLE COUNT is a read-only resource that tells you the
number of visible items. For PtList, it’s the number of items you
want to display.

If specified, the number of visible items is used to calculate the

dimensions of the list (if no explicit dimensions were given). If you
give explicit dimensions of the widget, the number of visible items is
calculated based on those dimensions and the font metrics for the list
font.

September 20, 2005 Chapter 2 ¯ Widgets 339

PtList  2005, QNX Software Systems

Selection notification
The list widget uses the Pt CB SELECTION callback to notify your
application whenever the user has made a new selection. The cbdata
passed to the callback always contains a pointer to a
PtListCallback t structure. The selection policy in effect on 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 caused the callback to be invoked.

Handling single selections

Single selection and browse selection modes allow only a single

selection to be made. In browse mode, the selection isn’t made until
the user releases the pointer button after having dragged the pointer
over the list items.
In either case, the selection callback is invoked when the selection is
made. The single selected item is identified in the call data.
Three members of the callback data structure identify the item that
was 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, allow several

items to be selected at once. When the selection callback is invoked,
more than one item may have been added to the set of selected items.
The call data passed to the callback function includes the complete set
of selected items.
The set of selected items is provided by these members:

¯ sel item count — the number of currently selected items

340 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtList

¯ sel array — an array of indices 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:

Resource C type Pt type Default

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
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
C type Pt type Default
char **, short Array NULL

An array of pointers to text items to be displayed in the list.

Pt ARG LIST BALLOON

C type Pt type Default
PtListBalloonF t * Pointer See below

A function that inflates a balloon for the item the pointer is on.
PtListBalloonF t is a function type:

September 20, 2005 Chapter 2 ¯ Widgets 341

PtList  2005, QNX Software Systems

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 parameters are as follows:

¯ widget — the PtList widget

¯ parent — its parent window

¯ area — a PhArea t structure 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

C type Pt type Default
short Scalar 0

The spacing between the items in the list.

342 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtList

Pt ARG MODIFY ITEMS

C type Pt type Default
PtListModifyItems t Struct

Used internally by the convenience functions.

Pt ARG SELECTION INDEXES

C type Pt type Default
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
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that the widget invokes on each mouse and key
event. Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason The name of the callback resource (Pt CB LIST INPUT)

that caused this callback to be invoked.
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:

September 20, 2005 Chapter 2 ¯ Widgets 343

PtList  2005, QNX Software Systems

PhPoint t pos;
Mouse position relative to the item
(valid only for mouse events).
char * item; For mouse events, the item under the
cursor. For key events, the item that
will be the current item 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. The
callback function can suppress normal
handling of the event by setting this
field to another value. In the case of key
events, a value of Pt END causes the
event to be consumed, while Pt HALT
passes the event to the parent widget.
Mouse events are always consumed.

These callbacks should return Pt CONTINUE.

Pt CB SELECTION
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that the widget invokes whenever the user selects
an item from the list. Each callback is passed a PtCallbackInfo t
structure that contains at least the following members:

reason The name of the callback resource (Pt CB SELECTION)

that caused this callback to be invoked.

344 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtList

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 least the following members:

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.
ushort t *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.

September 20, 2005 Chapter 2 ¯ Widgets 345

PtList  2005, QNX Software Systems

☞ The item member of the PtListCallback t structure identifies the

item that the user just selected. 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.

These callbacks should return Pt CONTINUE.

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 PtContainer
Pt ARG ANCHOR OFFSETS PtContainer
Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BALLOON COLOR PtGenList
Pt ARG BALLOON FILL COLOR PtGenList
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget

continued. . .

346 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtList

Resource Inherited from Default override

Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG LIST COLUMN ATTR PtGenList
Pt ARG LIST COLUMN POS PtGenList
Pt ARG LIST FLAGS PtGenList
Pt ARG LIST FONT PtGenList
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 TOTAL HEIGHT PtGenList
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget
Pt ARG SCROLLBAR WIDTH PtGenList
Pt ARG SELECTION FILL COLOR PtGenList
Pt ARG SELECTION MODE PtGenList

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 347

PtList  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG SELECTION TEXT COLOR PtGenList
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TOP ITEM POS PtGenList
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt ARG VISIBLE COUNT PtGenList See below.
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer Not used by this class.
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
Pt CB SCROLL MOVE PtGenList
Pt CB UNREALIZED PtWidget

348 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtList

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 the 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.

Convenience functions:
The PtList widget defines several convenience functions that make
it easier to use the list once it’s been created. Here’s a brief overview:

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.

September 20, 2005 Chapter 2 ¯ Widgets 349

PtList  2005, QNX Software Systems

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.

350 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems 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. The 0 position indicates the last
position in the list; specifying this position appends the item or items
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
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 351

PtListDeleteAllItems()  2005, QNX Software Systems
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
Interrupt handler No
Signal handler No
Thread No

See also:
PtListDeleteItems(), PtListDeleteItemPos(), PtListRemovePositions()

352 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems 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 an index of 1, not 0.

Returns:
0 Success.

-1 The specified widget isn’t a PtList widget.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtListDeleteAllItems(), PtListDeleteItems(), PtListRemovePositions()

September 20, 2005 Chapter 2 ¯ Widgets 353

PtListDeleteItems()  2005, QNX Software Systems
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.

-1 The specified widget isn’t a PtList widget.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtListDeleteAllItems(), PtListDeleteItemPos(),
PtListRemovePositions()

354 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtListGotoPos()
Make an item the current item and display it

Synopsis:
void PtListGotoPos( PtWidget t *widget,
int pos );

Description:
This function sets the current item and (if necessary) the current
position so that the new current item is visible. The first item in the
widget has an index of 1. If pos is 0, there will be no current item.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtListShowPos()

September 20, 2005 Chapter 2 ¯ Widgets 355

PtListItemExists()  2005, QNX Software Systems
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
Interrupt handler No
Signal handler No
Thread No

See also:
PtListItemPos()

356 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems 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. If it finds the item, the function returns the item’s position.
Otherwise, it returns 0.

Returns:
n The position of the item.

0 The item wasn’t found.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtListItemExists()

September 20, 2005 Chapter 2 ¯ Widgets 357

PtListRemovePositions()  2005, QNX Software Systems
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 an index of 1, not 0. The
pos count argument specifies the number of entries in the pos list
array.

Returns:
0 Success.

-1 The specified widget isn’t a PtList widget.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtListDeleteAllItems(), PtListDeleteItemPos(), PtListDeleteItems()

358 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems 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 an index 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
Interrupt handler No
Signal handler No
Thread No

See also:
PtListReplaceItems()

September 20, 2005 Chapter 2 ¯ Widgets 359

PtListReplaceItems()  2005, QNX Software Systems
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. The search 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
Interrupt handler No
Signal handler No
Thread No

See also:
PtListReplaceItemPos()

360 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems 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 an index of 1, not 0.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtListUnselectPos()

September 20, 2005 Chapter 2 ¯ Widgets 361

PtListShowPos()  2005, QNX Software Systems
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
an index of 1, not 0.
If the item is already visible, this function does nothing.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtListGotoPos()

362 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems 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 an index 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
Interrupt handler No
Signal handler No
Thread No

See also:
PtListSelectPos()

September 20, 2005 Chapter 2 ¯ Widgets 363

PtMenu  2005, QNX Software Systems
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:
The PtMenu class provides popup and pulldown menus. Menus work
in either press-drag-release or click-move-click mode.

New Ctrl+N
Open... Ctrl+O
Save Ctrl+S
Save As...
Close

Import Files

Exit Ctrl+X

A PtMenu widget that contains various menu items.

☞ Use PhAB’s Menu module instead of this widget. See “Menu

modules” in the Working with Modules chapter of the Photon
Programmer’s Guide.

Although menus usually consist of PtMenuButton widgets, any type

of widget may become a menu item by making itself the child of a
PtMenu widget.

364 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMenu

If PtMenu has any PtLabel-class children that have the

Pt ARG ACCEL KEY resource defined, it will attach hotkey
callbacks on behalf of those children.

☞ A PtMenu widget blocks any nonmenu hotkeys while it’s displayed.

To make menu items selectable by the user, you must set the
Pt SELECTABLE flag in Pt ARG FLAGS (see PtWidget). PtMenu
will then set up callbacks on its children to alter their behavior where
necessary, thus ensuring that the children operate as the user expects.
For example, the children will 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 will be realized when necessary.
Menus display a list of possible selections and allow the user to
choose one of them. The selections displayed in a menu are usually
pushbuttons that activate application functions, but they may also be
used to display toggle buttons, cascaded menu buttons that invoke
submenus, or any other selectable widget.
Most applications will have a menu bar (usually a PtMenuBar
widget), a horizontal bar across the top of the application window.
The menu bar will have a number of entries within it. Each of these
entries is a menu button with an associated pull-down menu. A menu
button appears as a label until it’s selected. When the menu button is
selected, the button’s border is etched so that it takes on the same 3-D
appearance as a pushbutton.
A menu button is selected by clicking it. This causes the pulldown
menu associated with the menu button to be activated or dropped
down.
A menu may also be activated or popped up in response to an event
such as a pointer-button press inside another type of widget. Known
as a popup menu, this type of menu normally appears at the current
pointer position.

September 20, 2005 Chapter 2 ¯ Widgets 365

PtMenu  2005, QNX Software Systems

A menu is displayed when it’s activated; it may be in either of two

modes:

¯ press-drag-release

¯ click-stay

In press-drag-release mode, the user can drag the menu by pressing

the pointer button and holding it down to keep the menu on screen.
The user can initiate click-stay mode by clicking the pointer button —
that is, pressing and then releasing the pointer button without moving
the pointer. The menu stays up until a menu selection is made.
Using press-drag-release mode, the user drags the pointer to the
desired selection and releases the pointer button over the selection to
choose it. While dragging the pointer, the user will see a visual cue
that indicates which selection would be chosen if the pointer button
were released. The selection underneath the pointer is highlighted by
giving it a raised 3-D appearance.
Using click-stay mode, the user chooses a menu selection by pressing
the pointer button over top of the desired selection. Once a selection
is chosen, it’s given a raised 3-D appearance as a visual cue of the
selection.
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.

366 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMenu

Creating menus
To get either a pull-down or a popup menu, you must create a menu
pane. This container holds all the items in the menu. The pane is what
is actually displayed when the menu is activated.
You use the PtMenu widget class to create menu panes. The
Pt ARG MENU FLAGS resource controls the menu pane’s behavior
and appearance.
You use these flags to control:

¯ the sizing of the menu pane

¯ the lifetime of the menu

¯ the behavior of a submenu or cascaded menu.

You can specify a menu title to be displayed at the top of the menu
pane when the menu is activated. You can also specify the title’s font.
You use the Pt ARG MENU TITLE and
Pt ARG MENU TITLE FONT resources to specify these two title
attributes.
If you specify a title for the menu, it will appear visually distinct from
the menu’s selections by means of a separator placed below the title.
You can use the Pt ARG MENU TEXT FONT resource to control
what font is used for displaying menu items. This resource overrides
the normal default font for text items placed in the menu.

Populating the menu

As with other containers, items are placed in a menu by creating them

as children of the menu itself. The widgets you place in the menu will
behave according to their type. Widgets that have the
Pt SELECTABLE flag set in the Pt ARG FLAGS resource may be used
as menu selections. This includes buttons, toggles, and menu buttons.
Menu buttons within the menu allow cascaded submenus. For more
information on how to create cascaded submenus, see the section
“Cascaded Menus.”

September 20, 2005 Chapter 2 ¯ Widgets 367

PtMenu  2005, QNX Software Systems

Widgets that have the Pt AUTOHIGHLIGHT flag set automatically

have the visual cuing provided for the user. 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, separators and labels can be placed in the menu to make
a visual distinction between different sections of the menu and to
enhance its appearance.

Sizing

Normally, the menu pane will be made wide enough to fit the widest
menu item placed within it, and all the menu items will be made this
size as well. The Pt MENU AUTO flag 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’ll have to create a callback
function to position the menu and realize it in response to the user
action that activates it. When the user has made a selection, the menu
will unrealize 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, it should be destroyed after the user has made a
menu selection.
You can deal with the above case by creating the menu as a transient
menu. To make a menu transient, set the Pt MENU TRANSIENT flag

368 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMenu

on the Pt ARG MENU FLAGS resource when the menu is created.

This menu will destroy itself after a menu selection has been made.

☞ 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 pane 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
so that both press-drag-release and click-stay modes will 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, passing 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.
The following function can be used to display the pulldown menu:
int
postMenu( PtWidget t *w, void *client data,
PtCallbackInfo t *info)
{
if (client data)
{
PtWidget t *menu = (PtWidget t *)client data;

September 20, 2005 Chapter 2 ¯ Widgets 369

PtMenu  2005, QNX Software Systems

PtPositionMenu(menu, NULL);
PtRealizeWidget(menu);
}
return Pt CONTINUE;
}

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 won’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 pressed before activating the menu.
The event handler should position the menu with a call to
PtPositionMenu(). In this case, it should 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 a popup menu can be activated:

370 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMenu

int
postMenu( 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;

/* post the popup if the right button was pressed */

if (event && client data &&
(event->type & Ph EV BUT PRESS) &&
(ptr->buttons == 1))
{
PtWidget t *menu = (PtWidget t *)client data;

PtPositionMenu(menu, event);
PtRealizeWidget(menu);
}
return Pt CONTINUE;
}

The following code illustrates how you can create a popup 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 pane and create a menu pane 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.

September 20, 2005 Chapter 2 ¯ Widgets 371

PtMenu  2005, QNX Software Systems

You must, however, set a flag on the submenu’s menu pane to indicate
that it is a submenu. Set the Pt MENU CHILD flag on the
Pt ARG MENU FLAGS resource. 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
menu button’s Pt ARG BUTTON TYPE resource.
We can now look at the create file items() function in our previous
example to see 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, "helv14B", 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[1], Pt ARG TEXT FONT, "helv14B", 0);
PtSetArg(&arg[2], Pt CB ACTIVATE, noop, 1);
PtCreateWidget(PtButton, parent, 3, arg);

PtSetArg(&arg[0], Pt ARG TEXT STRING, "Import", 0);

PtSetArg(&arg[1], Pt ARG TEXT FONT, "helv14B", 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[1], Pt ARG TEXT FONT, "helv14B", 0);
PtSetArg(&arg[2], Pt CB ACTIVATE, quit callbacks, 1);
PtCreateWidget(PtButton, parent, 3, arg);
}

372 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMenu

Complete menu example

We can now put together a complete example using all the techniques
described above. In this example, we have 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.
Here’s the complete example:
#include <Pt.h>
#include <stdlib.h>

int
post menu cb(PtWidget t *w, void *client data, PtCallbackInfo t *info)
{
PtArg t arg[4];
void *data;
PhArea t *area;
unsigned short *border;
unsigned short *flags;

client data = client data; info = info;

if (client data)
{
PtWidget t *menu = (PtWidget t *)client data;

PtPositionMenu(menu, NULL);
PtRealizeWidget(menu);
}
return Pt CONTINUE;
}

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))
{
PtWidget t *menu = (PtWidget t *)client data;

PtPositionMenu(menu, event);
PtRealizeWidget(menu);
}
return Pt CONTINUE;

September 20, 2005 Chapter 2 ¯ Widgets 373

PtMenu  2005, QNX Software Systems

int
nop cb(PtWidget t *w, void *client data,
PtCallbackInfo t *info)
{
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);
return Pt CONTINUE;
}

int
quit cb(PtWidget t *w, void *client data, PtCallbackInfo t *info)
{
w = w; client data = client data; info = info;

exit(0);
return Pt CONTINUE;
}

void create import items(PtWidget t *parent)

{
PtArg t arg[3];
PtCallback t noop[] = { {nop cb, NULL} };

PtSetArg(&arg[0], Pt ARG TEXT STRING, "Image", 0);

PtSetArg(&arg[1], Pt ARG TEXT FONT, "helv14B", 0);
PtSetArg(&arg[2], Pt CB ACTIVATE, noop, 1);
PtCreateWidget(PtButton, parent, 3, arg);

PtSetArg(&arg[0], Pt ARG TEXT STRING, "Bitmap", 0);

PtSetArg(&arg[1], Pt ARG TEXT FONT, "helv14B", 0);
PtSetArg(&arg[2], Pt CB ACTIVATE, noop, 1);
PtCreateWidget(PtButton, parent, 3, arg);
}

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, "helv14B", 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[1], Pt ARG TEXT FONT, "helv14B", 0);
PtSetArg(&arg[2], Pt CB ACTIVATE, noop, 1);
PtCreateWidget(PtButton, parent, 3, arg);

374 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMenu

PtSetArg(&arg[0], Pt ARG TEXT STRING, "Import", 0);

PtSetArg(&arg[1], Pt ARG TEXT FONT, "helv14B", 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[1], Pt ARG TEXT FONT, "helv14B", 0);
PtSetArg(&arg[2], Pt CB ACTIVATE, quit callbacks, 1);
PtCreateWidget(PtButton, parent, 3, arg);
}

void create help items(PtWidget t *parent)

{
PtArg t arg[3];
PtCallback t noop[] = { {nop cb, NULL} };

PtSetArg(&arg[0], Pt ARG TEXT STRING, "About", 0);

PtSetArg(&arg[1], Pt ARG TEXT FONT, "helv14B", 0);
PtSetArg(&arg[2], Pt CB ACTIVATE, noop, 1);
PtCreateWidget(PtMenuButton, parent, 3, arg);
}

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;

if ((window = PtAppInit(&app, &argc, argv, 0, NULL)) == NULL)

exit(EXIT FAILURE);

PtSetArg(&arg[0], Pt ARG ANCHOR FLAGS,

Pt LEFT ANCHORED LEFT|Pt RIGHT ANCHORED RIGHT,
Pt IS ANCHORED);
PtSetArg(&arg[1], Pt ARG BORDER 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);

PtSetArg(&arg[1], Pt ARG TEXT FONT, "helv14B", 0);
fileButton = PtCreateWidget(PtMenuButton, group, 2, arg);

PtSetArg(&arg[0], Pt ARG TEXT STRING, "Help", 0);

PtSetArg(&arg[1], Pt ARG TEXT FONT, "helv14B", 0);
helpButton = PtCreateWidget(PtMenuButton, group, 2, arg);

September 20, 2005 Chapter 2 ¯ Widgets 375

PtMenu  2005, QNX Software Systems

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:

Resource C type Pt type Default

Pt ARG MENU FLAGS unsigned long Flag Pt MENU AUTO
Pt ARG MENU SPACING short Scalar Value of
Pt ARG BORDER WIDTH

continued. . .

376 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMenu

Resource C type Pt type Default

Pt ARG MENU TEXT FONT char * String NULL
Pt ARG MENU TITLE char * String NULL
Pt ARG MENU TITLE FONT char * String "helv12b"

Pt ARG MENU FLAGS

C type Pt type Default
unsigned long Flag Pt MENU AUTO

Menu flags. Possible values:

Pt MENU AUTO
Make all items the same width.
Pt MENU TRANSIENT
Destroy menu on closing. The menu might be destroyed before
the selected menu item’s callback is invoked.
Pt MENU CHILD
Allow this menu to override its parent menu.

Pt ARG MENU SPACING

C type Pt type Default
short Scalar Value of Pt ARG BORDER WIDTH

The amount of space, in pixels, between each menu item.

Pt ARG MENU TEXT FONT

September 20, 2005 Chapter 2 ¯ Widgets 377

PtMenu  2005, QNX Software Systems

C type Pt type Default

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

C type Pt type Default
char * String NULL

The menu title. If you want to remove a title, specify NULL.

Pt ARG MENU TITLE FONT

C type Pt type Default
char * String "helv12b"

The font used for displaying the title.

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 PtContainer Not used by this class.
Pt ARG ANCHOR OFFSETS PtContainer Not used by this class.
Pt ARG AREA PtWidget

continued. . .

378 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMenu

Resource Inherited from Default override

Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer Not used by this class.
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget |=Pt DELAY REALIZE|
Pt HIGHLIGHTED
Pt ARG GROUP FLAGS PtGroup Not used by this class.
Pt ARG GROUP HORZ ALIGN PtGroup Not used by this class.
Pt ARG GROUP ORIENTATION PtGroup Not used by this class.
Pt ARG GROUP ROWS COLS PtGroup Not used by this class.
Pt ARG GROUP SPACING PtGroup Not used by this class.
Pt ARG GROUP SPACING X PtGroup Not used by this class.
Pt ARG GROUP SPACING Y PtGroup Not used by this class.
Pt ARG GROUP VERT ALIGN PtGroup Not used by this class.
Pt ARG HELP TOPIC PtWidget

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 379

PtMenu  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic 1
Pt ARG MARGIN WIDTH PtBasic 1
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY AS REQUIRED
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer Not used by this class.
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer

continued. . .

380 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMenu

Resource Inherited from Default override

Pt CB UNREALIZED PtWidget

September 20, 2005 Chapter 2 ¯ Widgets 381

PtMenuBar  2005, QNX Software Systems
A container for managing menu buttons

Class hierarchy:
PtWidget → PtBasic → PtContainer → PtGroup →
PtMenuBar

PhAB icon:

Public header:
<photon/PtMenuBar.h>

Description:
The PtMenuBar class provides alignment of menu buttons and cursor
key navigation through menus.

File Edit View Options Application Window Help

A PtMenuBar that contains several menu buttons.

This widget is a container that provides automatic anchoring to the

top and sides of its parent, along with alignment of the children
(PtMenuButton).

☞ PtMenuButton widgets are the only type of children PtMenuBar

widgets can have.

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.

382 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMenuBar

Resource Inherited from Default override

Pt ARG ANCHOR FLAGS PtContainer Pt LEFT ANCHORED LEFT
|
Pt RIGHT ANCHORED RIGHT
|
Pt TOP ANCHORED TOP
|
Pt ANCHORS LOCKED
Pt ARG ANCHOR OFFSETS PtContainer
Pt ARG AREA PtWidget height = 29
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 2
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget |= Pt HIGHLIGHTED
Pt ARG GROUP FLAGS PtGroup
Pt ARG GROUP HORZ ALIGN PtGroup Pt GROUP HORZ LEFT

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 383

PtMenuBar  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG GROUP ORIENTATION PtGroup Pt GROUP HORIZONTAL
Pt ARG GROUP ROWS COLS PtGroup
Pt ARG GROUP SPACING PtGroup 10
Pt ARG GROUP SPACING X PtGroup Not used by this class.
Pt ARG GROUP SPACING Y PtGroup Not used by this class.
Pt ARG GROUP VERT ALIGN PtGroup Pt GROUP VERT TOP
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic 2
Pt ARG MARGIN WIDTH PtBasic 2
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic

continued. . .

384 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMenuBar

Resource Inherited from Default override

Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
Pt CB UNREALIZED PtWidget

September 20, 2005 Chapter 2 ¯ Widgets 385

PtMenuButton  2005, QNX Software Systems
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.
File

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:

386 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMenuButton

Resource C type Pt type Default

Pt ARG ACCEL FONT char * String "helv12b"
Pt ARG ACCEL TEXT char * String ""
Pt ARG BUTTON TYPE unsigned short Scalar Pt MENU TEXT
Pt ARG OFFSET unsigned short Scalar 0

☞ These resources are actually defined in <photon/PtMenuLabel.h>

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

Pt ARG ACCEL FONT

C type Pt type Default
char * String "helv12b"

The font used to render the hotkey accelerator text.

Pt ARG ACCEL TEXT

C type Pt type Default
char * String ""

The text that identifies which hotkey is bound to this widget.

Pt ARG BUTTON TYPE

C type Pt type Default
unsigned short Scalar Pt MENU TEXT

Possible values:

September 20, 2005 Chapter 2 ¯ Widgets 387

PtMenuButton  2005, QNX Software Systems

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 ARG OFFSET
C type Pt type Default
unsigned short Scalar 0

The x offset used to render the accelerator text.

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 ACCEL KEY PtLabel
Pt ARG ANCHOR FLAGS PtContainer Not used by this class.
Pt ARG ANCHOR OFFSETS PtContainer Not used by this class.
Pt ARG AREA PtWidget
Pt ARG BALLOON COLOR PtLabel
Pt ARG BALLOON FILL COLOR PtLabel
Pt ARG BALLOON POSITION PtLabel

continued. . .

388 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMenuButton

Resource Inherited from Default override

Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget Pt SELECTABLE|
Pt MENU BUTTON
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG HORIZONTAL ALIGNMENT PtLabel
Pt ARG LABEL BALLOON PtLabel
Pt ARG LABEL DATA PtLabel
Pt ARG LABEL FLAGS PtLabel
Pt ARG LABEL TYPE PtLabel
Pt ARG LINE SPACING PtLabel
Pt ARG MARGIN BOTTOM PtLabel

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 389

PtMenuButton  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN LEFT PtLabel
Pt ARG MARGIN RIGHT PtLabel
Pt ARG MARGIN TOP PtLabel
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY AS REQUIRED
Pt ARG TEXT FONT PtLabel
Pt ARG TEXT STRING PtLabel
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG UNDERLINE TYPE PtLabel
Pt ARG UNDERLINE1 PtLabel
Pt ARG UNDERLINE2 PtLabel
Pt ARG USER DATA PtWidget
Pt ARG VERTICAL ALIGNMENT PtLabel
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer

continued. . .

390 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMenuButton

Resource Inherited from Default override

Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
Pt CB UNREALIZED PtWidget

September 20, 2005 Chapter 2 ¯ Widgets 391

PtMessage  2005, QNX Software Systems
A text message in a popup window

Class hierarchy:
PtWidget → PtBasic → PtContainer → PtMessage

PhAB icon:
None — use PhAB’s Message module.

Public header:
<photon/PtMessage.h>

Description:
The PtMessage widget displays a text-based message in a popup
window. The message can include up to three optional buttons,
allowing the user to select a course of action.

Current A pplication has changed. Do you want to save the changes?

Yes No Cancel

A PtMessage widget.

New resources:

Resource C type Pt type Default

Pt ARG MSG BUTTON1 char * String "Ok"
Pt ARG MSG BUTTON2 char * String NULL
Pt ARG MSG BUTTON3 char * String NULL
Pt ARG MSG DEFAULT short Scalar 1

continued. . .

392 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMessage

Resource C type Pt type Default

Pt ARG MSG ESCAPE short Scalar 0
Pt ARG MSG FLAGS unsigned int Flag 0
Pt ARG MSG FONT char * String "helv12"
Pt ARG MSG TEXT char * String ""
Pt ARG MSG TITLE char * String NULL
Pt CB MSG BUTTON1 PtCallback t * Link NULL
Pt CB MSG BUTTON2 PtCallback t * Link NULL
Pt CB MSG BUTTON3 PtCallback t * Link NULL

Pt ARG MSG BUTTON1, Pt ARG MSG BUTTON2, Pt ARG MSG BUTTON3

C type Pt type Default
char * String See below

The labels for the three optional buttons that are displayed below the
message. If no value is provided for Pt ARG MSG BUTTON1, the
default label of “Ok” is used. If no label is provided for the other two
buttons, they default to NULL, which means they won’t be displayed.
These defaults are useful for messages that simply provide
information.
You can assign a keyboard shortcut to each button. Simply place & in
front of the character that will act as the shortcut. For example, if you
specify &Save, the S will be underlined in the button. To select the
button, the user can press s or S.
Note that the function PtAskQuestion() duplicates the functionality of
the above example. For more information, see the Photon Library
Reference. This function also makes the PtMessage dialog work as a
modal dialog.

September 20, 2005 Chapter 2 ¯ Widgets 393

PtMessage  2005, QNX Software Systems

Pt ARG MSG DEFAULT

C type Pt type Default
short Scalar 1

The number of the default button, which can be selected by pressing

Enter. The text of the default button is displayed in bold.

Pt ARG MSG ESCAPE

C type Pt type Default
short Scalar 0

The number of the button that Esc is bound to. If the value is 0 (the
default), the Esc is disabled; otherwise the callback for the specified
button is invoked when Esc is pressed.

Pt ARG MSG FLAGS

C type Pt type Default
unsigned int Flag 0

Flags that control the appearance of the message:

¯ Pt MSG CENTER ON PARENT — if this flag is set, the message is

centered on its parent.

Pt ARG MSG FONT

C type Pt type Default
char * String "helv12"

The font in which the message will be displayed. Default is Helvetica

12 point.

394 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMessage

Pt ARG MSG TEXT

C type Pt type Default
char * String ""

The text of the message.

Pt ARG MSG TITLE

C type Pt type Default
char * String NULL

This optional resource displays a title in the window frame of the

message. Defaults to NULL for no title.

Pt CB MSG BUTTON1, Pt CB MSG BUTTON2, Pt CB MSG BUTTON3

C type Pt type Default
PtCallback t * Link NULL

These resources define lists of callback functions that will be invoked

if the user selects one of the buttons. These resources correspond with
the buttons by number. So, for example, if the user selects the button
labeled with Pt ARG MSG BUTTON1, then Pt CB MSG BUTTON1
is invoked.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason The name of the callback resource (for example,

Pt CB MSG BUTTON1) that caused this callback to be
invoked.
reason subtype
0 (not used)

event The raw event that caused the the callback to be invoked.

September 20, 2005 Chapter 2 ¯ Widgets 395

PtMessage  2005, QNX Software Systems

cbdata Always NULL for this widget.

These callbacks should return Pt CONTINUE.

Inherited resources:
Although this widget is a subclass of the PtContainer superclass,
the only inherited resource it uses is Pt ARG POS for positioning the
message:

Resource Inherited from Default override

Pt ARG POS PtWidget

Convenience functions:
The PtMessage widget defines a convenience function that makes it
easier to use the widget once it’s been created. Here’s a brief
overview:

PtMessageGetWindow()
Get the widget pointer to the message’s window

396 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMessageGetWindow()
Get a widget pointer to a PtMessage widget’s window

Synopsis:
PtWidget t *PtMessageGetWindow( PtWidget t const *widget );

Description:
This function retrieves a pointer to a PtMessage widget’s window.

Returns:
A pointer to the window, or NULL if widget doesn’t point to a
PtMessage widget.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 397

PtMultiText  2005, QNX Software Systems
Multiline stylized text

Class hierarchy:
PtWidget → PtBasic → PtContainer → PtCompound →
PtMultiText

PhAB icon:

Public header:
<photon/PtMultiText.h>

Description:
The PtMultiText widget class provides display and entry of
multilined stylized text.

Photon has no shortage of graphical

widgets. There’s a widget to accomplish
everything from simple lines and
rectangles to complex multisegmented
thingamajiggers.

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

398 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMultiText

¯ 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

¯ optional automatic indentation

¯ anchoring

¯ many useful callbacks

¯ cursor visibility, editable or read-only options

¯ overstrike and insert editing modes

All these features can be controlled 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 CHAR|Pt EMT WORD );
PtSetResources( mtwidget, 1, &argt );

In the above example, we turned off character wrapping because word

wrapping is applied if both the word and character wrap flags are on.
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.

September 20, 2005 Chapter 2 ¯ Widgets 399

PtMultiText  2005, QNX Software Systems

☞ 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

400 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMultiText

¯ 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. The attributes are
set with the PtMultiTextAttributes t structure.

¯ Change the attributes of a range of text that’s already there via the
Pt ARG MULTITEXT RANGE ATTRIBUTES resource or the
PtTextModifyText() convenience function. The attributes are set
with the PtMultiTextAttributes t structure.

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

PtMultiLines t hello[] = {
{ "Hello\n", Pt DEFAULT FONT, Pt DEFAULT COLOR,
Pt INHERIT COLOR },
{ "World!", "time24", Pg BLUE, Pt INHERIT COLOR }
};

main() {
PtWidget t *window;
PtArg t args[2];

September 20, 2005 Chapter 2 ¯ Widgets 401

PtMultiText  2005, QNX Software Systems

int nargs = 0;
PhDim t dim = { 300, 150 };

if( !( window = PtAppInit( NULL, 0, NULL, 0, NULL ) ) )

exit( EXIT FAILURE );

PtSetArg( &args[nargs++], Pt ARG DIM, &dim, 0 );

PtSetArg( &args[nargs++], Pt ARG MULTITEXT SEGMENTS,
&hello, sizeof( hello )/sizeof(hello[0]) );
PtCreateWidget( PtMultiText, NULL, nargs, args );

PtRealizeWidget( window );

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
re-written 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;

if( !( window = PtAppInit( NULL, 0, NULL, 0, NULL ) ) )

exit( EXIT FAILURE );

PtSetArg( &args[nargs++], Pt ARG DIM, &dim, 0 );

mtext = PtCreateWidget( PtMultiText, NULL, nargs, args );
PtTextModifyText( mtext, NULL, NULL, 0, "Hello, \n", 8 );
attr.font = "time24";

402 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMultiText

PtMultiTextModifyText( mtext, NULL, NULL, -1,

"World! \n", 8, attr, Pt MT FONT );

PtRealizeWidget( window );

PtMainLoop();
}

Changing the attributes of a range of text

With a WYSIWYG editor, a user 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. The
attributes of a range of text can be modified 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 helv14 using PtMultiTextModifyAttributes():

PtMultiTextAttributes t attr;
int start, end;

if( PtTextGetSelection( text, &start, &end ) )

{
attr.font = "helv14";
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 helv14 using the
Pt ARG MULTITEXT RANGE ATTRIBUTES resource.

PtMultiTextAttributes t attr;
PtMultiTextControl t mtc;

September 20, 2005 Chapter 2 ¯ Widgets 403

PtMultiText  2005, QNX Software Systems

if( PtTextGetSelection( text, &mtc.tc.start, &mtc.tc.end ) )

{
PtArg t argt;
attr.font = "helv14";
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.

404 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMultiText

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 the application whenever the
cursor is moved, the callback can also notify the application when the
user has pressed the pointer button over a “hot-spot” used for a
hypertext link.
The data for a hypertext link itself can be stored 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

September 20, 2005 Chapter 2 ¯ Widgets 405

PtMultiText  2005, QNX Software Systems

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,
PtCallbackInfo t *info)
{
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);
}
return Pt CONTINUE;
}

void
init text(PtWidget t *text)

406 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMultiText

{
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
: &reg;

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 the user types more than
four lines, say six lines, the widget displays a scrollbar to let the user
know there are more than lines. Querying Pt ARG DIM gives the
dimension 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

September 20, 2005 Chapter 2 ¯ Widgets 407

PtMultiText  2005, QNX Software Systems

structure contains a PhRect t structure 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.

New resources:

Resource C type Pt type Default

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)

continued. . .

408 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMultiText

Resource C type Pt type Default

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

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 409

PtMultiText  2005, QNX Software Systems

Resource C type Pt type Default

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 provided convenience functions encompass the functionality of

the complex resources. For more info, see the Convenience functions
section.

Pt ARG MULTITEXT BOTTOM LINE (write-only)

C type Pt type Default
long Scalar None

Set the bottom line (top line + number of visible lines -1).

Pt ARG MULTITEXT FLAGS

C type Pt type Default
long Flag Pt EMT SCROLL TO CURSOR

Flags that affect the appearance and behavior of the widget. The valid
bits are:

410 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMultiText

Pt EMT AUTOINDENT
When Enter is pressed, the new line is indented 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)

C type Pt type Default
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)

C type Pt type Default
short Scalar None

How many lines are currently visible.

Pt ARG MULTITEXT QUERY CHARACTER (read-only)

C type Pt type Default
PtMultiTextQuery t * Complex None

September 20, 2005 Chapter 2 ¯ Widgets 411

PtMultiText  2005, QNX Software Systems

This resource is used to get information about a certain character.

This resource is classified as complex, thus requiring special
handling. When getting, value is a pointer to an instance of a
PtMultiTextQuery t. The len parameter is the character number
of the character to be queried (where the first character is character 0).

Pt ARG MULTITEXT QUERY LINE (read-only)

C type Pt type Default
PtMultiTextQuery t * Complex None

This resource is used to get information about a certain line. This

resource is classified as complex, thus requiring special handling.
When getting, value is a pointer to an instance of a
PtMultiTextQuery t. The len parameter is the line number of the
line to be queried (where the first line is line 1).

Pt ARG MULTITEXT RANGE ATTRIBUTES

C type Pt type Default
PtMultiTextControl t * Complex None

This resource modifies/queries the attributes of a specified range. It’s

classified as complex, thus requiring special handling. When setting,
value is a pointer to an instance of a PtMultiTextControl t
structure. The len parameter is 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

412 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMultiText

¯ Pt MT FLAGS

When getting, value is the address of a pointer to a

PtMultiTextInfo t structure, which is the same as
PtMultiTextControl t. The len parameter is a pointer to an
instance of a PtTextCallback t that defines the range to be
queried.

Pt ARG MULTITEXT ROWS (write-only)

C type Pt type Default
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)

C type Pt type Default
PtMultiLines t, short Array None

This resource provides an easy way 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

September 20, 2005 Chapter 2 ¯ Widgets 413

PtMultiText  2005, QNX Software Systems

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

C type Pt type Default
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} would produce tab
stops at 10, 30, 40, 50, 60, ... pixels.

Pt ARG MULTITEXT TOP LINE

C type Pt type Default
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

C type Pt type Default
short Flag Pt EMT WORD|Pt EMT NEWLINE

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.

414 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMultiText

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

C type Pt type Default
short Scalar 0

The horizontal scroll position (in pixels )

Pt ARG MULTITEXT Y SCROLL POS

C type Pt type Default
long Scalar 1

(The same as Pt ARG MULTITEXT TOP LINE.) Set or get the top
line or vertical scroll position in lines. (The first line is line 1.)

Pt ARG SCROLLBAR X DISPLAY

C type Pt type Default
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

September 20, 2005 Chapter 2 ¯ Widgets 415

PtMultiText  2005, QNX Software Systems

☞ In order to display a horizontal scrollbar, you’ll 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

C type Pt type Default
unsigned short Scalar 0 (use scrollbar default of 15)

The height of the horizontal scrollbar. If this resource is set to 0, the

default size of 15 is used.

Pt ARG SCROLLBAR Y DISPLAY

C type Pt type Default
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

C type Pt type Default
unsigned short Scalar 0 (use scrollbar default of 15)

The width of the vertical scrollbar. If this resource is set to 0, the

default size of 15 is used.

416 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMultiText

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 PtContainer 0 (no anchors)
Pt ARG ANCHOR OFFSETS PtContainer
Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this
class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG COLUMNS PtText
Pt ARG CONTAINER FLAGS PtContainer
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR POSITION PtText 0
Pt ARG CURSOR TYPE PtWidget Ph CURSOR INSERT
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 417

PtMultiText  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG FLAGS PtWidget |=Pt SET|
Pt HIGHLIGHTED|
Pt GETS FOCUS
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG HORIZONTAL ALIGNMENT PtLabel
Pt ARG LINE SPACING PtLabel
Pt ARG MARGIN BOTTOM PtLabel
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN LEFT PtLabel
Pt ARG MARGIN RIGHT PtLabel
Pt ARG MARGIN TOP PtLabel
Pt ARG MARGIN WIDTH PtBasic
Pt ARG MAX LENGTH PtText
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget
Pt ARG SELECTION RANGE PtText
Pt ARG TEXT CURSOR WIDTH PtText
Pt ARG TEXT FLAGS PtText
Pt ARG TEXT FONT PtLabel
Pt ARG TEXT HIGHLIGHT BACKGROUND COLOR PtText
Pt ARG TEXT HIGHLIGHT TEXT COLOR PtText
Pt ARG TEXT STRING PtLabel
Pt ARG TEXT SUBSTRING PtText

continued. . .

418 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMultiText

Resource Inherited from Default override

Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt ARG VERTICAL ALIGNMENT PtLabel
Pt CB ACTIVATE PtBasic See below.
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic See below.
Pt CB HOTKEY PtWidget
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 REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 419

PtMultiText  2005, QNX Software Systems

Resource Inherited from Default override

Pt CB TEXT CHANGED PtText See below.
Pt CB UNREALIZED PtWidget

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 contains at least the following
members:

reason Pt CB ACTIVATE

reason subtype
Indicates why the callback was invoked:
¯ 0 — the user clicked on the widget and it has
Pt SELECTABLE set in its Pt ARG FLAGS.
¯ Pt EDIT ACTIVATE — the user pressed Enter in the
text field.
¯ Pt CHANGE ACTIVATE — the text was modified, the
widget lost focus, and Pt CHANGE ACTIVATE is set in
the 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 * attributes;
PtMultiTextSegment t * seg;
void * extended data;

420 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMultiText

¯ 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().

September 20, 2005 Chapter 2 ¯ Widgets 421

PtMultiText  2005, QNX Software Systems

¯ 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.

These callbacks should return Pt CONTINUE.

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.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason The name of the callback resource that caused this

callback to be invoked.
reason subtype
If there are different ways to invoke the callback, this
member indicates which one. This value is usually 0.

event The event 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 the right of the first
character, and so on.

422 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMultiText

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.

These callbacks should return Pt CONTINUE.

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.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason The name of the callback resource that caused this

callback to be invoked.
reason subtype
If there are different ways to invoke the callback, this
member indicates which one. This value is usually 0.

event The event 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:

September 20, 2005 Chapter 2 ¯ Widgets 423

PtMultiText  2005, QNX Software Systems

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
character, and so on.
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.

These callbacks should return Pt CONTINUE.

Pt CB MODIFY VERIFY
Pt CB MODIFY VERIFY (Pt CB MODIFY NOTIFY), is inherited
from PtText, but the cbdata member of the callback information is
different for a PtMultiText widget.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason The name of the callback resource that caused this

callback to be invoked.
reason subtype
If there are different ways to invoke the callback, this
member indicates which one. This value is usually 0.
event The event 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:

424 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMultiText

¯ 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.

These callbacks should return Pt CONTINUE.

September 20, 2005 Chapter 2 ¯ Widgets 425

PtMultiText  2005, QNX Software Systems

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.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason The name of the callback resource that caused this

callback to be invoked.
reason subtype
If there are different ways to invoke the callback, this
member indicates which one. This value is usually 0.

event The event that caused this callback to be invoked.

cbdata A pointer to a PtMultiTextCallback t structure.

¯ The PtTextCallback t tc structure has the following members:

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.

426 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMultiText

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.

¯ 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.

If cbinfo->event is NULL, the cursor motion occurred because:

¯ The application set a resource on this widget that affects the cursor
position.
Or:

¯ The application called an API function that repositioned the cursor.

These callbacks should return Pt CONTINUE.

Convenience functions:
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()
Initializes a multitext attribute structure.

September 20, 2005 Chapter 2 ¯ Widgets 427

PtMultiText  2005, QNX Software Systems

PtMultiTextGetAttributes()
Gets the attributes of a PtMultiText widget.
PtMultiTextInfo()
Gets character/line information from a PtMultiText widget.
PtMultiTextInfo t
Information passed to PtMultiText callbacks

PtMultiTextLine t
Information about a line of text in a PtMultiText
PtMultiTextModifyAttributes()
Modifies the attributes of a PtMultiText widget.

PtMultiTextModifyText()
Modifies 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()
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.

428 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMultiLines t
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. An
array composed of of this structure can be passed to the
PtMultiText widget’s Pt ARG MULTITEXT SEGMENTS resource.
The members include:

string 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) or one of the following special values:

September 20, 2005 Chapter 2 ¯ Widgets 429

PtMultiLines t  2005, QNX Software Systems

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 following special values:

Pt INHERIT COLOR
Use the same color as the previous range.
Pt DEFAULT COLOR
Use the value of the Pt ARG FILL COLOR
resource.

Classification:
Photon

See also:
PtMultiText, PtMultiTextAttributes t

430 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMultiTextAttributes t
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) 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.

September 20, 2005 Chapter 2 ¯ Widgets 431

PtMultiTextAttributes t  2005, QNX Software Systems

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 following special values:

Pt INHERIT COLOR
Use the same color as the previous range.
Pt DEFAULT COLOR
Use the value of the Pt ARG FILL COLOR
resource.

flags For internal use.

tag To be used at the application’s discretion.

Classification:
Photon

See also:
PtMultiText, PtMultiTextInfo()

432 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMultiTextCallback t,
PtMultiTextControl t,
PtMultiTextInfo t
Information passed to PtMultiText callbacks
Synopsis:
typedef struct
{
PtTextCallback t tc;
PtMultiTextAttributes t *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

September 20, 2005 Chapter 2 ¯ Widgets 433

PtMultiTextCallback t,
PtMultiTextControl t,
PtMultiTextInfo t  2005, QNX Software Systems
See also:
PtMultiText, PtMultiTextAttributes t,
PtMultiTextSegment t, PtTextCallback t

434 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems 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
Interrupt handler No
Signal handler No
Thread No

See also:
PtTextGetSelection(), PtTextModifyText(), PtTextSetSelection(),
PtMultiTextAttributes t

September 20, 2005 Chapter 2 ¯ Widgets 435

PtMultiTextGetAttributes()  2005, QNX Software Systems
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 returns as 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"

436 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMultiTextGetAttributes()

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 );
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,

PtCallbackInfo t *cbinfo )
{
PtArg t argt;
FILE *fp;
char *text;
PtMultiTextAttributes t attrs;
int start = -1, end = 0, len;

if( !(fp = fopen( "notepad", "r" ) ) )

September 20, 2005 Chapter 2 ¯ Widgets 437

PtMultiTextGetAttributes()  2005, QNX Software Systems

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;
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

438 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMultiTextGetAttributes()

See also:
PtMultiTextCreateAttributes(), PtTextGetSelection(),
PtTextModifyText(), PtTextSetSelection(),
PtMultiTextAttributes t

September 20, 2005 Chapter 2 ¯ Widgets 439

PtMultiTextInfo()  2005, QNX Software Systems
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:

440 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMultiTextInfo()

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

¯ 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 will return 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
returns as 0, it indicates the first character in the
widget’s text buffer.

length The number of characters in the line.

September 20, 2005 Chapter 2 ¯ Widgets 441

PtMultiTextInfo()  2005, QNX Software Systems

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
Interrupt handler No
Signal handler No
Thread No

See also:
PtTextGetSelection(), PtTextModifyText(), PtTextSetSelection(),
PtMultiTextAttributes t

442 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMultiTextLine t
Information about a line of text in a PtMultiText

Synopsis:
typedef struct Pt emt text line
{
unsigned int first char;
unsigned int byte offset;
ushort t 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.
The members include:

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.

September 20, 2005 Chapter 2 ¯ Widgets 443

PtMultiTextLine t  2005, QNX Software Systems

Classification:
Photon

See also:
PtMultiText, PtMultiTextInfo(), PtMultiTextSegment t

444 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems 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.

September 20, 2005 Chapter 2 ¯ Widgets 445

PtMultiTextModifyAttributes()  2005, QNX Software Systems

Examples:
See PtMultiTextGetAttributes().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtTextGetSelection(), PtTextModifyText(), PtTextSetSelection(),
PtMultiTextAttributes t

446 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems 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:

1 The text inherits the segment’s attributes.

September 20, 2005 Chapter 2 ¯ Widgets 447

PtMultiTextModifyText()  2005, QNX Software Systems

2 The text is separated into its own segment, but keeps its
inherited values.

3 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

☞ This function causes a nondestructive deselect before attempting the

changes.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtTextGetSelection(), PtTextModifyText(), PtTextSetSelection(),
PtMultiTextAttributes t

448 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems 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. It’s used when getting the
Pt ARG MULTITEXT QUERY CHARACTER or
Pt ARG MULTITEXT QUERY LINE resource. When getting these
resources, the len member of the PtArg t structure indicates 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.

September 20, 2005 Chapter 2 ¯ Widgets 449

PtMultiTextQuery t  2005, QNX Software Systems

Classification:
Photon

See also:
PtMultiText, PtMultiTextSegment t, PtMultiTextLine t

450 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtMultiTextSegment t
Information about a segment of text in a PtMultiText

Synopsis:
typedef struct Pt emt text segment
{
PtMultiTextAttributes t attrs;
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. Its members 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

September 20, 2005 Chapter 2 ¯ Widgets 451

PtMultiTextSegment t  2005, QNX Software Systems

See also:
PtMultiText, PtMultiTextAttributes t

452 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtNumeric
A superclass for numeric widgets

Class hierarchy:
PtWidget → PtBasic → PtContainer → PtCompound →
PtNumeric

PhAB icon:
None — not normally instantiated.

Public header:
<photon/PtNumeric.h>

Description:
PtNumeric is a parent class for all numeric widgets. It creates a
PtText widget and a PtUpDown widget to allow the user to interact
with the widget. It also creates some of the base functionality of
numeric widgets.

New resources:

Resource C type Pt type Default

Pt ARG NUMERIC FLAGS long Flag See
below
Pt ARG NUMERIC PREFIX char * String NULL
Pt ARG NUMERIC SPACING int Scalar 1
Pt ARG NUMERIC SUFFIX char * String NULL
Pt ARG NUMERIC TEXT BORDER int Scalar 2
Pt ARG NUMERIC TEXT BOT BORDER COLOR PgColor t Scalar Pg DGREY
Pt ARG NUMERIC TEXT COLOR PgColor t Scalar Pg BLACK
Pt ARG NUMERIC TEXT FILL COLOR PgColor t Scalar Pg GREY

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 453

PtNumeric  2005, QNX Software Systems

Resource C type Pt type Default

Pt ARG NUMERIC TEXT FLAGS unsigned long Flag Pt CURSOR VISIBLE
|
Pt EDITABLE
|
Pt INSERT MODE
Pt ARG NUMERIC TEXT FONT char * String "helv12"
Pt ARG NUMERIC TEXT TOP BORDER COLOR PgColor t Scalar Pg WHITE
Pt ARG NUMERIC UPDOWN BORDER WIDTH int Scalar 2
Pt ARG NUMERIC UPDOWN WIDTH int Scalar 17

Pt ARG NUMERIC FLAGS

C type Pt type Default
long Flag Pt NUMERIC ENABLE UPDOWN |
Pt NUMERIC WRAP |
Pt NUMERIC AUTO HIGHLIGHT

Flags that control the widget’s appearance and behavior:

Pt NUMERIC AUTO HIGHLIGHT

Autohighlight text when selected.

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).

454 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtNumeric

Pt NUMERIC WRAP
Wrap numbers from minimum to maximum and from
maximum to minimum.

Pt ARG NUMERIC PREFIX

C type Pt type Default
char * String NULL

A prefix string to be added to all entered values.

Pt ARG NUMERIC SPACING

C type Pt type Default
int Scalar 1

The spacing, in pixels, between the text field and the up/down buttons.

Pt ARG NUMERIC SUFFIX

C type Pt type Default
char * String NULL

A suffix string to be added to all entered values.

Pt ARG NUMERIC TEXT BORDER

C type Pt type Default
int Scalar 2

The border width of the PtText widget.

September 20, 2005 Chapter 2 ¯ Widgets 455

PtNumeric  2005, QNX Software Systems

Pt ARG NUMERIC TEXT BOT BORDER COLOR

C type Pt type Default
PgColor t Scalar Pg DGREY

The bottom border color of the PtText widget.

Pt ARG NUMERIC TEXT COLOR

C type Pt type Default
PgColor t Scalar Pg BLACK

The color of the entered text.

Pt ARG NUMERIC TEXT FILL COLOR

C type Pt type Default
PgColor t Scalar Pg GREY

The fill color of the PtText widget.

Pt ARG NUMERIC TEXT FLAGS

C type Pt type Default
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” for
PtText.

456 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtNumeric

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 TEXT AUTO HIGHLIGHT

Highlight the text when the widget is given focus.
Default is off.

Pt ARG NUMERIC TEXT FONT

C type Pt type Default
char * String "helv12"

The font of the entered text.

Pt ARG NUMERIC TEXT TOP BORDER COLOR

C type Pt type Default
PgColor t Scalar Pg WHITE

The top border color of the PtText widget.

Pt ARG NUMERIC UPDOWN BORDER WIDTH

C type Pt type Default
int Scalar 2

The width, in pixels, of the borders of the up/down buttons.

September 20, 2005 Chapter 2 ¯ Widgets 457

PtNumeric  2005, QNX Software Systems

Pt ARG NUMERIC UPDOWN WIDTH

C type Pt type Default
int Scalar 17

The width, in pixels, of the PtUpDown widget.

Exported subordinate children:

Unless the resources are already defined in PtNumeric, the
PtNumeric class uses the resources of its exported subordinate child,
PtUpDown.
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.

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 PtContainer Not used by this
class.
Pt ARG ANCHOR OFFSETS PtContainer Not used by this
class.
Pt ARG AREA PtWidget
Pt ARG ARM COLOR PtButton
Pt ARG ARM DATA PtButton

continued. . .

458 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtNumeric

Resource Inherited from Default

override
Pt ARG ARM FILL PtButton Pg GRAY
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this
class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer Not used by this
class.
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic Pg TRANSPARENT
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget 0
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic 0
Pt ARG MARGIN WIDTH PtBasic 0
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY AS REQUIRED

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 459

PtNumeric  2005, QNX Software Systems

Resource Inherited from Default

override
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG UPDOWN ARM DATA BOTTOM PtUpDown
Pt ARG UPDOWN ARM DATA LEFT PtUpDown
Pt ARG UPDOWN ARM DATA RIGHT PtUpDown
Pt ARG UPDOWN ARM DATA TOP PtUpDown
Pt ARG UPDOWN BOTTOM BORDER COLOR PtUpDown
Pt ARG UPDOWN DATA BOTTOM PtUpDown
Pt ARG UPDOWN DATA LEFT PtUpDown
Pt ARG UPDOWN DATA RIGHT PtUpDown
Pt ARG UPDOWN DATA TOP PtUpDown
Pt ARG UPDOWN FILL COLOR PtUpDown
Pt ARG UPDOWN FLAGS PtUpDown
Pt ARG UPDOWN HIGHLIGHT ROUND PtUpDown
Pt ARG UPDOWN MARGIN HEIGHT PtUpDown
Pt ARG UPDOWN MARGIN WIDTH PtUpDown
Pt ARG UPDOWN ORIENTATION PtUpDown
Pt ARG UPDOWN SPACING PtUpDown
Pt ARG UPDOWN TOP BORDER COLOR PtUpDown
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer

continued. . .

460 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtNumeric

Resource Inherited from Default

override
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
Pt CB UNREALIZED PtWidget

September 20, 2005 Chapter 2 ¯ Widgets 461

PtNumericFloat  2005, QNX Software Systems
Floating-point numeric widget

Class hierarchy:
PtWidget → PtBasic → PtContainer → PtCompound →
PtNumeric → PtNumericFloat

PhAB icon:

t NumericFl

Public header:
<photon/PtNumericFloat.h>

Description:
The PtNumericFloat class is a numeric widget that allows you to
enter floating-point values between given minimum and maximum
values.

17.98

A PtNumericFloat widget.

A PtUpDown widget is also shown to let you increase or decrease the

value by a set amount. The widget allows a prefix and a suffix string
to be optionally added along with the ability to use comma separators
and set the precision of the number (i.e. the number of decimal
places, for example, 1,000.00).

New resources:

Resource C type Pt type Default

Pt ARG NUMERIC INCREMENT double * Struct 1.0

continued. . .

462 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtNumericFloat

Resource C type Pt type Default

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

C type Pt type Default
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

C type Pt type Default
double * Struct 1000000.00

The maximum value for the widget.

Pt ARG NUMERIC MIN

C type Pt type Default
double * Struct -1000000.00

The minimum value for the widget.

September 20, 2005 Chapter 2 ¯ Widgets 463

PtNumericFloat  2005, QNX Software Systems

Pt ARG NUMERIC PRECISION

C type Pt type Default
int Scalar 2

The precision or number of displayed decimal places of the widget’s

current value.

Pt ARG NUMERIC VALUE

C type Pt type Default
double * Struct 0.0

The current value of the widget.

Pt CB NUMERIC CHANGED
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks invoked when the widget’s value changes. Each

callback is passed a PtCallbackInfo t structure that contains at
least the following members:

reason The name of the callback resource

(Pt CB NUMERIC CHANGED) that caused this callback
to be invoked.
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 UPDOWN ACTIVATE — a button was
pressed to change the current value
¯ Pt NUMERIC UPDOWN REPEAT — a button was held
down to change the current value

464 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtNumericFloat

cbdata A pointer to a PtNumericFloatCallback t structure

that contains at least:
¯ double numeric value — the current value of the
widget

These callbacks should return Pt CONTINUE.

Exported subordinate children:

Unless the resources are already defined in PtNumericFloat, the
PtNumericFloat class uses the resources of its exported
subordinate child, PtUpDown.
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.

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 PtContainer Not used by
this class.
Pt ARG ANCHOR OFFSETS PtContainer Not used by
this class.
Pt ARG AREA PtWidget
Pt ARG ARM COLOR PtButton
Pt ARG ARM DATA PtButton

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 465

PtNumericFloat  2005, QNX Software Systems

Resource Inherited from Default

override
Pt ARG ARM FILL PtButton Pg GRAY
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by
this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer Not used by
this class.
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic Pg TRANSPARENT
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget 0
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic 0
Pt ARG MARGIN WIDTH PtBasic 0
Pt ARG NUMERIC FLAGS PtNumeric
Pt ARG NUMERIC PREFIX PtNumeric

continued. . .

466 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtNumericFloat

Resource Inherited from Default

override
Pt ARG NUMERIC SPACING PtNumeric
Pt ARG NUMERIC SUFFIX PtNumeric
Pt ARG NUMERIC TEXT BORDER PtNumeric
Pt ARG NUMERIC TEXT BOT BORDER COLOR PtNumeric
Pt ARG NUMERIC TEXT COLOR PtNumeric
Pt ARG NUMERIC TEXT FILL COLOR PtNumeric
Pt ARG NUMERIC TEXT FONT PtNumeric
Pt ARG NUMERIC TEXT TOP BORDER COLOR PtNumeric
Pt ARG NUMERIC UPDOWN BORDER WIDTH PtNumeric
Pt ARG NUMERIC UPDOWN WIDTH PtNumeric
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY AS REQUIRED
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG UPDOWN ARM DATA BOTTOM PtUpDown
Pt ARG UPDOWN ARM DATA LEFT PtUpDown
Pt ARG UPDOWN ARM DATA RIGHT PtUpDown
Pt ARG UPDOWN ARM DATA TOP PtUpDown
Pt ARG UPDOWN BOTTOM BORDER COLOR PtUpDown
Pt ARG UPDOWN DATA BOTTOM PtUpDown
Pt ARG UPDOWN DATA LEFT PtUpDown
Pt ARG UPDOWN DATA RIGHT PtUpDown
Pt ARG UPDOWN DATA TOP PtUpDown

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 467

PtNumericFloat  2005, QNX Software Systems

Resource Inherited from Default

override
Pt ARG UPDOWN FILL COLOR PtUpDown
Pt ARG UPDOWN FLAGS PtUpDown
Pt ARG UPDOWN HIGHLIGHT ROUND PtUpDown
Pt ARG UPDOWN MARGIN HEIGHT PtUpDown
Pt ARG UPDOWN MARGIN WIDTH PtUpDown
Pt ARG UPDOWN ORIENTATION PtUpDown
Pt ARG UPDOWN SPACING PtUpDown
Pt ARG UPDOWN TOP BORDER COLOR PtUpDown
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic See below.
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer Not used by
this class.
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget

continued. . .

468 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtNumericFloat

Resource Inherited from Default

override
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
Pt CB UNREALIZED PtWidget

Pt CB ACTIVATE
If cbinfo->reason subtype is Pt NUMERIC ACTIVATE, the
callback was invoked because the user changed the value and
pressed Enter while in PtNumericFloat’s text field.

September 20, 2005 Chapter 2 ¯ Widgets 469

PtNumericInteger  2005, QNX Software Systems
Integer numeric widget

Class hierarchy:
PtWidget → PtBasic → PtContainer → PtCompound →
PtNumeric → PtNumericInteger

PhAB icon:

Public header:
<photon/PtNumericInteger.h>

Description:
The PtNumericInteger class lets the user specify integer values
between given minimum and maximum values.

27

A PtNumericInteger widget.

A PtUpDown widget is also shown to allow the user to increase or

decrease the value by a set amount. The widget allows a prefix and a
suffix string to be optionally added along with the ability to use
comma separators (e.g. 1,000).
If you want the value to be displayed as a hexadecimal value, set
Pt NUMERIC HEXADECIMAL in the Pt ARG NUMERIC FLAGS
resource.

New resources:

470 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtNumericInteger

Resource C type Pt type Default

Pt ARG NUMERIC INCREMENT int Scalar 1
Pt ARG NUMERIC MAX int Scalar 1000000
Pt ARG NUMERIC MIN int Scalar -1000000
Pt ARG NUMERIC VALUE int Scalar 0
Pt CB NUMERIC CHANGED PtCallback t * Link NULL

Pt ARG NUMERIC INCREMENT

C type Pt type Default
int Scalar 1

The amount by which to increase or decrease the value when the

up/down buttons are pressed.

Pt ARG NUMERIC MAX

C type Pt type Default
int Scalar 1000000

The maximum value for the widget.

Pt ARG NUMERIC MIN

C type Pt type Default
int Scalar -1000000

The minimum value for the widget.

September 20, 2005 Chapter 2 ¯ Widgets 471

PtNumericInteger  2005, QNX Software Systems

Pt ARG NUMERIC VALUE

C type Pt type Default
int Scalar 0

The current value of the widget.

Pt CB NUMERIC CHANGED
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks invoked when the widget’s value changes. Each

callback is passed a PtCallbackInfo t structure that contains at
least the following members:

reason The name of the callback resource

(Pt CB NUMERIC CHANGED) that caused this callback
to be invoked.
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 UPDOWN ACTIVATE — a button was
pressed to change the current value.
¯ Pt NUMERIC UPDOWN REPEAT — a button was held
down to change the current value.

cbdata A pointer to a PtNumericIntegerCallback t

structure that contains at least:
¯ int numeric value — the current value of the widget.

These callbacks should return Pt CONTINUE.

472 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtNumericInteger

Exported subordinate children:

Unless the resources are already defined in PtNumericInteger, the
PtNumericInteger class uses the resources of its exported
subordinate child, PtUpDown.
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.

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 PtContainer Not used by
this class.
Pt ARG ANCHOR OFFSETS PtContainer Not used by
this class.
Pt ARG AREA PtWidget
Pt ARG ARM COLOR PtButton
Pt ARG ARM DATA PtButton
Pt ARG ARM FILL PtButton Pg GRAY
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by
this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG BOT BORDER COLOR PtBasic

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 473

PtNumericInteger  2005, QNX Software Systems

Resource Inherited from Default

override
Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer Not used by
this class.
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic Pg TRANSPARENT
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget 0
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic 0
Pt ARG MARGIN WIDTH PtBasic 0
Pt ARG NUMERIC FLAGS PtNumeric
Pt ARG NUMERIC PREFIX PtNumeric
Pt ARG NUMERIC SPACING PtNumeric
Pt ARG NUMERIC SUFFIX PtNumeric
Pt ARG NUMERIC TEXT BORDER PtNumeric
Pt ARG NUMERIC TEXT BOT BORDER COLOR PtNumeric
Pt ARG NUMERIC TEXT COLOR PtNumeric
Pt ARG NUMERIC TEXT FILL COLOR PtNumeric

continued. . .

474 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtNumericInteger

Resource Inherited from Default

override
Pt ARG NUMERIC TEXT FONT PtNumeric
Pt ARG NUMERIC TEXT TOP BORDER COLOR PtNumeric
Pt ARG NUMERIC UPDOWN BORDER WIDTH PtNumeric
Pt ARG NUMERIC UPDOWN WIDTH PtNumeric
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY AS REQUIRED
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG UPDOWN ARM DATA BOTTOM PtUpDown
Pt ARG UPDOWN ARM DATA LEFT PtUpDown
Pt ARG UPDOWN ARM DATA RIGHT PtUpDown
Pt ARG UPDOWN ARM DATA TOP PtUpDown
Pt ARG UPDOWN BOTTOM BORDER COLOR PtUpDown
Pt ARG UPDOWN DATA BOTTOM PtUpDown
Pt ARG UPDOWN DATA LEFT PtUpDown
Pt ARG UPDOWN DATA RIGHT PtUpDown
Pt ARG UPDOWN DATA TOP PtUpDown
Pt ARG UPDOWN FILL COLOR PtUpDown
Pt ARG UPDOWN FLAGS PtUpDown
Pt ARG UPDOWN HIGHLIGHT ROUND PtUpDown
Pt ARG UPDOWN MARGIN HEIGHT PtUpDown
Pt ARG UPDOWN MARGIN WIDTH PtUpDown
Pt ARG UPDOWN ORIENTATION PtUpDown

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 475

PtNumericInteger  2005, QNX Software Systems

Resource Inherited from Default

override
Pt ARG UPDOWN SPACING PtUpDown
Pt ARG UPDOWN TOP BORDER COLOR PtUpDown
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic See below.
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer Not used by
this class.
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
Pt CB UNREALIZED PtWidget

Pt CB ACTIVATE
If cbinfo->reason subtype is Pt NUMERIC ACTIVATE, the
callback was invoked because the user changed the value and
pressed Enter while in PtNumericInteger’s text field.

476 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtOnOffButton
An on/off button that can be set or unset

Class hierarchy:
PtWidget -> PtBasic -> PtLabel -> PtToggleButton ->
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.
About demo
On/Off Button

A PtOnOffButton widget.

New resources:

Resource C type Pt type Default

Pt ARG ONOFF STATE short Scalar 0 (off)
Pt CB ONOFF NEW VALUE PtCallback t * Link NULL

Pt ARG ONOFF STATE

September 20, 2005 Chapter 2 ¯ Widgets 477

PtOnOffButton  2005, QNX Software Systems

C type Pt type Default

short Scalar 0 (off)

Indicates the current state of the on/off button. If the button is off, this
resource has a value of 0; if the button is on, this resource has a
nonzero value.

Pt CB ONOFF NEW VALUE

C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that the widget invokes when the state of the on/off
button changes.
These callbacks are also invoked whenever a call to PtSetResources()
changes the state of the button, provided the Pt CALLBACKS ACTIVE
flag is set (see the description of Pt ARG FLAGS under PtWidget).
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB ONOFF NEW VALUE

reason subtype
0 (not used).

event The event that caused this callback to be invoked.

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.

These callbacks should return Pt CONTINUE.

478 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtOnOffButton

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 ACCEL KEY PtLabel
Pt ARG AREA PtWidget
Pt ARG BALLOON COLOR PtLabel
Pt ARG BALLOON FILL COLOR PtLabel
Pt ARG BALLOON POSITION PtLabel
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this
class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget |=Pt SELECTABLE
&=˜Pt TOGGLE

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 479

PtOnOffButton  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG HORIZONTAL ALIGNMENT PtLabel
Pt ARG INDICATOR COLOR PtToggleButton Pg MGRAY
Pt ARG INDICATOR DEPTH PtToggleButton
Pt ARG INDICATOR HEIGHT PtToggleButton
Pt ARG INDICATOR TYPE PtToggleButton
Pt ARG INDICATOR WIDTH PtToggleButton
Pt ARG LABEL BALLOON PtLabel
Pt ARG LABEL DATA PtLabel
Pt ARG LABEL FLAGS PtLabel
Pt ARG LABEL TYPE PtLabel
Pt ARG LINE SPACING PtLabel
Pt ARG MARGIN BOTTOM PtLabel
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN LEFT PtLabel
Pt ARG MARGIN RIGHT PtLabel
Pt ARG MARGIN TOP PtLabel
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY AS REQUIRED
Pt ARG SET COLOR PtToggleButton Pg GREEN
Pt ARG SET FILL PtToggleButton Not used by this
class.

continued. . .

480 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtOnOffButton

Resource Inherited from Default override

Pt ARG SPACING PtToggleButton
Pt ARG TEXT FONT PtLabel
Pt ARG TEXT STRING PtLabel
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG UNDERLINE TYPE PtLabel
Pt ARG UNDERLINE1 PtLabel
Pt ARG UNDERLINE2 PtLabel
Pt ARG USER DATA PtWidget
Pt ARG VERTICAL ALIGNMENT PtLabel
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB UNREALIZED PtWidget

September 20, 2005 Chapter 2 ¯ Widgets 481

PtPane  2005, QNX Software Systems
A container that provides anchoring and layout for its children

Class hierarchy:
PtWidget → PtBasic → PtContainer → PtPane

PhAB icon:

Public header:
<photon/PtPane.h>

Description:
PtPane is a container widget that provides anchoring and layout for
its children. Any child widgets that extend beyond the canvas of the
PtPane widget are clipped. You should find this widget useful for
screen layouts.
AppBuilder Preference Settings

General
Gen er a l Pr ef er en ces
Colors
Speedbar: On Off
Dragging

Other Module Display: As Sample As Resource List

Resource Names: Descriptive Header Manifest

Icon Descriptions: None Pop- Up

Edit Command: No Shell

View Command: No Shell

Print Command:
Done

A dialog box featuring several PtPane widgets.

482 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtPane

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 PtContainer Pt LEFT ANCHORED LEFT|
Pt RIGHT ANCHORED LEFT|
Pt TOP ANCHORED TOP|
Pt BOTTOM ANCHORED TOP
Pt ARG ANCHOR OFFSETS PtContainer
Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget 0

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 483

PtPane  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic

continued. . .

484 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtPane

Resource Inherited from Default override

Pt CB RESIZE PtContainer
Pt CB UNREALIZED PtWidget

September 20, 2005 Chapter 2 ¯ Widgets 485

PtPixel  2005, QNX Software Systems
A set of points

Class hierarchy:
PtWidget → PtBasic → PtGraphic → PtPixel

PhAB icon:

Public header:
<photon/PtPixel.h>

Description:
The PtPixel widget may be used 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).

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 AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget

continued. . .

486 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtPixel

Resource Inherited from Default override

Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic Pg BLACK
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DASH LIST PtGraphic Not used by this class.
Pt ARG DASH SCALE PtGraphic Not used by this class.
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic Pg TRANSPARENT
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG GRAPHIC FLAGS PtGraphic
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG LINE CAP PtGraphic Not used by this class.
Pt ARG LINE JOIN PtGraphic Not used by this class.
Pt ARG LINE WIDTH PtGraphic
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN WIDTH PtBasic
Pt ARG ORIGIN PtGraphic
Pt ARG POINTS PtGraphic
Pt ARG POS PtWidget

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 487

PtPixel  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG RESIZE FLAGS PtWidget
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESCALE PtGraphic
Pt CB UNREALIZED PtWidget

488 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtPolygon
A set of connected line segments

Class hierarchy:
PtWidget → PtBasic → PtGraphic → PtPolygon

PhAB icon:

Public header:
<photon/PtPolygon.h>

Description:
The PtPolygon widget may be used to draw a set of connected line
segments, called a “polyline”, from the vertices of the line segments.

PtPolygon can display open or closed polygons.

The points provided to the widget in the Pt ARG POINTS resource

specify 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.

September 20, 2005 Chapter 2 ¯ Widgets 489

PtPolygon  2005, QNX Software Systems

You can produce a polygon using this widget by specifying that the
curve must be closed. This is controlled by the
Pt ARG POLYGON FLAGS resource.
You can use the flags to specify:

¯ whether points in the polygon definition are relative to the previous

point or in absolute coordinates

¯ whether the polygon should be filled

¯ whether a polyline (open curve) or polygon (closed curve) is to be

drawn.

New resources:

Resource C type Pt type Default

Pt ARG POLYGON FLAGS unsigned short Flag 0

Pt ARG POLYGON FLAGS

C type Pt type Default
unsigned short Flag 0

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 STROKE
Stroke (outline) the polygon.
Pg POLY RELATIVE
Use relative coordinates to draw the polygon. Each
point is relative to the previous point.

490 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtPolygon

Pg POLY FILL Fill the polygon.

The default setting of this resource is 0; that is, no flags have been set.

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 AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DASH LIST PtGraphic
Pt ARG DASH SCALE PtGraphic
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 491

PtPolygon  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG GRAPHIC FLAGS PtGraphic
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS 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 ORIGIN PtGraphic
Pt ARG POINTS PtGraphic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic

continued. . .

492 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtPolygon

Resource Inherited from Default override

Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESCALE PtGraphic
Pt CB UNREALIZED PtWidget

September 20, 2005 Chapter 2 ¯ Widgets 493

PtPrintSel  2005, QNX Software Systems
A widget for selecting printing properties

Class hierarchy:
PtWidget → PtBasic → PtContainer → PtPrintSel

PhAB icon:

Public header:
<photon/PtPrintSel.h>

Description:
The PtPrintSel widget lets a user select a printer, change its
properties, and optionally select a range of pages and the number of
copies to print.
Select a Printer

Printer: Lexmark Tech Pubs Properties...

Location: Tech Pubs Print to File

Print Range Copies

All Pages Number Of Copies:
Pages
Collate M ethod:
Selection

A PtPrintSel widget.

New resources:

494 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtPrintSel

Resource C type Pt type Default

Pt ARG PRINT CONTEXT PpPrintContext t Struct NULL
Pt ARG PRINT FLAGS unsigned Flag See below
Pt CB PRINT PROPS PtCallback t * Link NULL

Pt ARG PRINT CONTEXT

C type Pt type Default
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 PpPrintCreatePC() to create a Print Context, and
PpPrintSetPC() 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 FLAGS

C type Pt type Default
unsigned Flag Pt PRINTSEL ALL PANES |
Pt PRINTSEL PROP APP |
Pt PRINTSEL NO SELECT RANGE

Flags to modify the appearance of the widget:

¯ Pt PRINTSEL ALL PANES — if this flag is set, all the panes of the
print selector are displayed; if cleared, the Print Range and Copies
panes aren’t displayed.

¯ Pt PRINTSEL PROP APP — enable the Properties button.

September 20, 2005 Chapter 2 ¯ Widgets 495

PtPrintSel  2005, QNX Software Systems

¯ Pt PRINTSEL NO PAGE RANGE — if this flag is set, you can’t

specify a range of pages to print.

¯ Pt PRINTSEL NO SELECT RANGE — disable the Selection button

in the Page Range pane.

¯ Pt PRINTSEL NO COPIES — disable the Number of Copies field.

¯ Pt PRINTSEL NO COLLATE — disable the Collate Method

buttons.

¯ Pt PRINTSEL NO PREVIEW — disable the Preview button.

Pt CB PRINT PROPS
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that are invoked when:

¯ the Properties button is pressed (reason subtype is

Pt PRINTSEL PROPERTIES)

¯ the Add Printer button (which appears instead of Properties if no

printer is installed) is pressed (reason subtype is
Pt PRINTSEL ADDNEW)

¯ the Properties or Add Printer process ends (reason subtype is

Pt PRINTSEL RETURN)

Each callback is passed a PtCallbackInfo t structure that

contains at least the following members:

reason Pt CB PRINT PROPS

reason subtype
Defines the Properties action:

496 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtPrintSel

Pt PRINTSEL PROPERTIES
The Properties button was selected. You might use
this callback to block access to the print selector’s
window while the Properties dialog is open (the
PtPrintSel widget blocks itself automatically).
Pt PRINTSEL ADDNEW
No printer has been installed. By default, this
callback invokes the Printer Installation program,
prsetup. See the Printing chapter in the User’s
Guide.
Pt PRINTSEL RETURN
The user has closed the Properties dialog. You
might use this callback to unblock access to the
print selector’s window (the PtPrintSel widget
unblocks itself automatically).

cbdata A pointer to a string that’s the printer’s name.

These callbacks should return Pt CONTINUE.

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 PtContainer
Pt ARG ANCHOR OFFSETS PtContainer
Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 497

PtPrintSel  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer &=˜Pt GETS FOCUS
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget See below.
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget 0
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic

continued. . .

498 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtPrintSel

Resource Inherited from Default override

Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
Pt CB UNREALIZED PtWidget

Pt ARG DIM The dimension of the PtPrintSel widget is fixed

at 418 wide ¢ 186 high (when the
Pt PRINTSEL ALL PANES bit of the
Pt ARG PRINT FLAGS resource is set), or 418
wide ¢ 95 high (when the
Pt PRINTSEL ALL PANES bit is clear).

Convenience functions:
The PtPrintSel class defines the following convenience function:

September 20, 2005 Chapter 2 ¯ Widgets 499

PtPrintSel  2005, QNX Software Systems

PtPrintSelection()
Display a modal dialog for initiating printing. See the Photon
Library Reference.

500 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtRaw
A widget for use with Photon drawing primitives

Class hierarchy:
PtWidget → PtBasic → PtRaw

PhAB icon:

Public header:
<photon/PtRaw.h>

Description:
The PtRaw class provides you with widget that lets you use the
Photon graphics drawing functions.

☞ 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 the Building Custom Widgets manual.

With a PtRaw canvas, 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, the 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 allow the
application programmer to maintain the original data structure and
re-render the contents of the canvas. If a significant amount of time
must be expended rendering the contents of the canvas, it’s better to
render them into an image and copy the image into the canvas when it
is damaged.

September 20, 2005 Chapter 2 ¯ Widgets 501

PtRaw  2005, QNX Software Systems

The canvas is considered damaged whenever one of the following

situations occurs:

¯ A Photon Expose event arrives at the canvas’s region.

¯ The widget was realized — the empty region has been drawn and
the contents of the canvas must be drawn.
¯ Region 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.

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 will 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 USER DATA
resource of the PtRaw widget, so that it can be obtained easily by
your draw function. 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.

502 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtRaw

Before your function begins drawing, it should establish its coordinate

space correctly. First, obtain the coordinates of the clip rectangle or
the widget canvas. This is done by calling PtBasicWidgetCanvas()
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 and translation for drawing. You determine the 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.

You should also set a translation 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 PtBasicWidgetCanvas() 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 will automatically be
translated by the amount you specified in the call to
PgSetTranslation().
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;

PtBasicWidgetCanvas(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

September 20, 2005 Chapter 2 ¯ Widgets 503

PtRaw  2005, QNX Software Systems

Pt ARG COLOR resource and the fill color to the value specified in
the Pt ARG FILL COLOR resource.
PtRaw lets you combine widgets and Pg* functions. You should use
this widget to cover any area in which “raw drawing” is to take place.
The draw function you specify for this widget will be called whenever
the area needs repair.
The coordinates for the Pg* calls made within the draw function are
relative to the canvas of PtRaw’s parent. The draw function must
handle its own clipping and highlighting.
If the draw function changes clipping (PtClipAdd()) or the current
translation (PgSetTranslation()) they must be restored before the draw
function returns.
Here’s an 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 BORDER 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, NULL, n, &args[0] );
.
.
.

void draw( PtWidget t *widget, PhTile t *damage )

{
PhRect t rect;

damage = damage;

PtSuperClassDraw( PtBasic, widget, damage );

//find our canvas

PtBasicWidgetCanvas( widget, &rect );

//clip to our basic canvas (it’s only polite).

PtClipAdd( widget, &rect );

//Do our drawing...

PgSetStrokeColor( Pg RED );

504 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtRaw

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 Programmer’s Guide.

New resources:

Resource C type Pt type Default

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 CONNECT F

C type Pt type Default
See below Pointer NULL

A function that creates any regions needed by the widget (normally

PtWidget does this for you):

int (*connect f) (PtWidget t *widget)

September 20, 2005 Chapter 2 ¯ Widgets 505

PtRaw  2005, QNX Software Systems

Pt ARG RAW DRAW F

C type Pt type Default
See below Pointer NULL

A function that renders the widget on the screen:

void (*draw f) (PtWidget t *widget, PhTile t *damage)

Pt ARG RAW EXTENT F

C type Pt type Default
See below Pointer NULL

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

C type Pt type Default
See below Pointer NULL

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)

506 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtRaw

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 AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 507

PtRaw  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG RESIZE FLAGS PtWidget
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB UNREALIZED PtWidget

508 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems 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, a radius must be specified in pixels for the curve at the
corners. You specify the corner radius using the
Pt ARG RECT ROUNDNESS resource.

New resources:

September 20, 2005 Chapter 2 ¯ Widgets 509

PtRect  2005, QNX Software Systems

Resource C Type Pt Type Default

Pt ARG RECT ROUNDNESS unsigned short Scalar 0

Pt ARG RECT ROUNDNESS

C type Pt type Default
unsigned short Scalar 0

Defines the number of pixels used for rounding the corners of the
rectangle.

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 AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DASH LIST PtGraphic
Pt ARG DASH SCALE PtGraphic

continued. . .

510 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtRect

Resource Inherited from Default override

Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG GRAPHIC FLAGS PtGraphic
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS 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 ORIGIN PtGraphic
Pt ARG POINTS PtGraphic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 511

PtRect  2005, QNX Software Systems

Resource Inherited from Default override

Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESCALE PtGraphic
Pt CB UNREALIZED PtWidget

512 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtRegion
A Photon region

Class hierarchy:
PtWidget → PtBasic → PtContainer → PtRegion

PhAB icon:
None — must be instantiated with 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 the data associated with a region, see
PhRegion t in the Photon Library Reference.

¯ For changes to this widget’s resource to take effect, you must set
the corresponding bit in Pt ARG REGION FIELDS.

New resources:

Resource C type Pt type Default

Pt ARG REGION DATA PhRegionDataHdr t * Alloc NULL
Pt ARG REGION FIELDS long Flag 0
Pt ARG REGION FLAGS long Flag 0
Pt ARG REGION HANDLE long Scalar widget pointer

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 513

PtRegion  2005, QNX Software Systems

Resource C type Pt type Default

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 OWNER PhConnectId t Scalar 0
Pt ARG REGION PARENT long Scalar 0
Pt ARG REGION SENSE long Flag 0

Pt ARG REGION DATA

C type Pt type Default
PhRegionDataHdr t * Alloc NULL

Defines the data to be attached to the region. For changes to this

resource to take effect, you must set the corresponding bit in
Pt ARG REGION FIELDS.

Pt ARG REGION FIELDS

C type Pt type Default
long Flag 0

Indicates which portions of the region should be modified, including

its flags, sensitivity, opacity, origin, position, etc. You must set these
bits in addition to setting the corresponding resource; otherwise the
setting of the resource will be ignored.
The following bits can be used to define a field in a region change
(PhRegionChange()) or open (PhRegionOpen()). For more
information, see <PhT.h>.

514 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtRegion

☞ 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 OWNER Pt ARG REGION OWNER
Ph REGION HANDLE Pt ARG REGION HANDLE
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 DATA Pt ARG REGION DATA
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.

September 20, 2005 Chapter 2 ¯ Widgets 515

PtRegion  2005, QNX Software Systems

Pt ARG REGION FLAGS

C type Pt type Default
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

For changes to this resource to take effect, you must set the
corresponding bit in Pt ARG REGION FIELDS.

Pt ARG REGION HANDLE

516 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtRegion

C type Pt type Default

long Scalar widget pointer

A widget pointer normally used by the widget library to determine

which widget is associated with a region. This resource should either
be set to 0 or left at its default. For changes to this resource to take
effect, you must set the corresponding bit in
Pt ARG REGION FIELDS.

Pt ARG REGION INFRONT

C type Pt type Default
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. For changes to
this resource to take effect, you must set the corresponding bit in
Pt ARG REGION FIELDS.

Pt ARG REGION INPUT GROUP

C type Pt type Default
short Scalar 0

Associates the region with the specified input group. For changes to
this resource to take effect, you must set the corresponding bit in
Pt ARG REGION FIELDS.

Pt ARG REGION OPAQUE

C type Pt type Default
long Flag 0

September 20, 2005 Chapter 2 ¯ Widgets 517

PtRegion  2005, QNX Software Systems

Define which events this region is opaque to. For changes to this
resources to take effect, you must set the corresponding bit(s) in
Pt ARG REGION FIELDS.

Pt ARG REGION OWNER

C type Pt type Default
PhConnectId t Scalar 0

Specifies the owner of the region. For changes to this resource to take
effect, you must set the corresponding bit in
Pt ARG REGION FIELDS.

Pt ARG REGION PARENT

C type Pt type Default
long Scalar 0

Specifies the ID (rid) of the region that will be this region’s parent.
For changes to this resource to take effect, you must set the
corresponding bit in Pt ARG REGION FIELDS.

Pt ARG REGION SENSE

C type Pt type Default
long Flag 0

Define which events this region is sensitive to. For changes to this
resources to take effect, you must set the corresponding bit(s) in
Pt ARG REGION FIELDS.

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.

518 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtRegion

Resource Inherited from Default override

Pt ARG ANCHOR FLAGS PtContainer Not used by this class.
Pt ARG ANCHOR OFFSETS PtContainer Not used by this class.
Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY AS REQUIRED

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 519

PtRegion  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
Pt CB UNREALIZED PtWidget

520 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtScrollArea
A viewport for viewing a large virtual area

Class hierarchy:
PtWidget → PtBasic → PtContainer → PtScrollArea

PhAB icon:

Public header:
<photon/PtScrollArea.h>

Description:
A PtScrollArea 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.

September 20, 2005 Chapter 2 ¯ Widgets 521

PtScrollArea  2005, QNX Software Systems

Max Vert 0
Posit ion Vert 0
Increment Vert 10
Max Horz 0
Posit ion Horz 0
Increment Horz 10
Scrollbar Horz Display Pt _NEVER
Scrollbar Vert Display Pt _ALWAYS
ScrollArea Flags 0x0
Anchor Flags 0xf 00
Cont ainer Flags 0x0
Color: Pen
Color: Fill
Border W idth 1
Color: Top Border
Color: Bot t om Border

A PtScrollArea widget acts as a viewport.

Like other widgets, PtScrollArea’s physical size is set with its

Pt ARG AREA resource. The virtual size depends on its
Pt ARG SCROLL AREA MAX X and
Pt ARG SCROLL AREA MAX Y resources.
PtScrollArea’s resize policy affects only its virtual size, not its
physical size. Its anchors, on the other hand, affect only its physical
size, with one exception: if the physical size exceeds the virtual size,
the virtual size temporarily grows to fill the physical canvas.
Any anchorable children of a PtScrollArea widget will 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

522 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtScrollArea

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.

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. In these cases, you should use scrollbars and directly
control which portion of the object is displayed.

Scrolling notification
When the user moves either the vertical or horizontal scrollbar to
change the viewport’s position, a callback may be invoked to notify
the application that the viewport has been moved. You may use this 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.
The callbacks provided by the PtScrollArea class and their
meanings are:

¯ Pt CB SCROLLED X — the horizontal scrollbar has been moved

¯ Pt CB SCROLLED Y — the vertical scrollbar has been moved

Scrolling control
The scrollbars provided by the scrollable area let the user 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.

September 20, 2005 Chapter 2 ¯ Widgets 523

PtScrollArea  2005, QNX Software Systems

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 SCROLL AREA INCREMENT X

¯ Pt ARG SCROLL AREA 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 also update the viewport’s position under program control.
To move the viewport, you simply set a new position using the
Pt ARG SCROLL AREA POS X and
Pt ARG SCROLL AREA POS Y resources.

Layout
Scrollable areas always use absolute positioning for the layout of their
children.

Anchors and resize policy

Anchors between a scrollable area and its parent will affect the
scrollable area’s visible area.
Children of the scrollable area are anchored to its virtual area.
The scrollable area’s resize policy is applied to its virtual area. You
can set the virtual area’s size directly by modifying the resources
associated with it. Otherwise, the area will change 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)

524 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtScrollArea

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 only by making another container, such as

a group widget, a child of the scrollable area.

New resources:

Resource C type Pt type Default

Pt ARG SCROLL AREA FLAGS unsigned short Flag 0
Pt ARG SCROLL AREA INCREMENT X unsigned short Scalar 10
Pt ARG SCROLL AREA INCREMENT Y unsigned short Scalar 10
Pt ARG SCROLL AREA MAX X unsigned short Scalar 0
Pt ARG SCROLL AREA MAX Y unsigned short Scalar 0
Pt ARG SCROLL AREA POS X unsigned short Scalar 0
Pt ARG SCROLL AREA POS Y unsigned short Scalar 0
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 ALWAYS

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 525

PtScrollArea  2005, QNX Software Systems

Resource C type Pt type Default

Pt ARG SCROLLBAR Y WIDTH unsigned short Scalar 0 (use
scrollbar
default
of 15)
Pt CB SCROLLED X PtCallback t * Link NULL
Pt CB SCROLLED Y PtCallback t * Link NULL

Pt ARG SCROLL AREA FLAGS

C type Pt type Default
unsigned short Flag 0

These flags control the behavior of the scroll area. Valid bits include:

Pt SCROLL AREA IGNORE KEYS

Prevents the scroll area from handling and consuming the arrow
keys, Pg Up, Pg Dn, Home, or End.
Pt SCROLL AREA TRACK FOCUS (default)
Scroll automatically to keep the currently focused widget
visible.

Pt ARG SCROLL AREA INCREMENT X

C type Pt type Default
unsigned short Scalar 10

The number of pixels that the widget will scroll when the user clicks
the horizontal arrow buttons.

526 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtScrollArea

Pt ARG SCROLL AREA INCREMENT Y

C type Pt type Default
unsigned short Scalar 10

The number of pixels that the widget will scroll when the user clicks
the vertical arrow buttons.

Pt ARG SCROLL AREA MAX X

C type Pt type Default
unsigned short 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 SCROLL AREA MAX Y

C type Pt type Default
unsigned short 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 SCROLL AREA POS X

C type Pt type Default
unsigned short Scalar 0

The horizontal position of the displayed portion of the scrollable area.

September 20, 2005 Chapter 2 ¯ Widgets 527

PtScrollArea  2005, QNX Software Systems

Pt ARG SCROLL AREA POS Y

C type Pt type Default
unsigned short Scalar 0

The vertical position of the displayed portion of the scrollable area.

Pt ARG SCROLLBAR X DISPLAY

C type Pt type Default
unsigned short Scalar Pt NEVER

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

C type Pt type Default
unsigned short Scalar 0 (use scrollbar default of 15)

The height (in pixels) of the horizontal scrollbar. The minimum

height is 6 pixels. If this resource is set to 0, the default height of 15
pixels is used.

Pt ARG SCROLLBAR Y DISPLAY

528 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtScrollArea

C type Pt type Default

unsigned short Scalar Pt ALWAYS

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

C type Pt type Default
unsigned short Scalar 0 (use scrollbar default of 15)

The width (in pixels) of the vertical scrollbar. The minimum width is
6 pixels. If this resource is set to 0, the default width of 15 pixels is
used.

Pt CB SCROLLED X, Pt CB SCROLLED Y
C type Pt type Default
PtCallback t * Link NULL

The list of callbacks that the PtScrollArea widget invokes when its
scrollbars are moved.
If the widget has the Pt CALLBACKS ACTIVE bit set in its
Pt ARG FLAGS resource, these callbacks are also invoked when the
positions of the scrollbars are changed by a call to PtSetResources().
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

September 20, 2005 Chapter 2 ¯ Widgets 529

PtScrollArea  2005, QNX Software Systems

reason Pt CB SCROLLED X or
Pt CB SCROLLED Y.

reason subtype 0 (not used).

cbdata A pointer to a PtScrollbarCallback t

structure that contains at least the following
members:
unsigned action;
where action can be 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 slider part of the scrollbar has been
moved to the maximum value.
Pt SCROLL TO MIN
The slider has been moved to the minimum
value.
Pt SCROLL DRAGGED
The slider part is being dragged.
Pt SCROLL RELEASED
The slider part has been released after having
been dragged.

530 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtScrollArea

int position; A value corresponding to the slider’s location.

These callbacks should return Pt CONTINUE.

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 PtContainer Pt RIGHT ANCHORED LEFT|
Pt BOTTOM ANCHORED TOP
Pt ARG ANCHOR OFFSETS PtContainer
Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG BOT BORDER COLOR PtBasic Not used by this class.
Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 531

PtScrollArea  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG FLAGS PtWidget |=Pt GETS FOCUS|
Pt HIGHLIGHTED|
Pt SET
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget

continued. . .

532 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtScrollArea

Resource Inherited from Default override

Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
Pt CB UNREALIZED PtWidget

September 20, 2005 Chapter 2 ¯ Widgets 533

PtScrollbar  2005, QNX Software Systems
A scrollbar

Class hierarchy:
PtWidget → PtBasic → 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
allow the handle to 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. Similarily, the height of a stepper arrow in a
vertical scrollbar is set to 3/4 of the scrollbar’s width.

534 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtScrollbar

A scrollbar can return values from minimum to maximum, minus the

size of the handle. 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 equals 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.
The handle’s size can also be programmatically controlled. These
parameters may be altered to visually represent information about an
object’s size and proportion viewed when the scrollbar is used for
scrolling.
Scrolling is the action of controlling how much of an object is
displayed when the object is too large to view all at once. When a
scrollbar is used for scrolling, the trough’s size visually represents the
scroll region — the total length of the object being viewed.
The edge of the handle represents the user’s 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 will control which portion of the
object is displayed. The 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.

September 20, 2005 Chapter 2 ¯ Widgets 535

PtScrollbar  2005, QNX Software Systems

If the pointer is: the handle will:

on either arrow move up or down one increment (holding
down the mouse button repeats the action)
in the trough move up or down one page increment (holding
down the mouse button repeats the action)
on the handle start a drag action

Keyboard actions

If the user presses: the handle will move:

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

536 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtScrollbar

Resource C type Pt type Default

Pt ARG DIRECTION int Boolean Off
Pt ARG INCREMENT long Scalar 1
Pt ARG MAXIMUM int Scalar 19
Pt ARG MINIMUM int Scalar 0
Pt ARG MIN SLIDER SIZE int Scalar 5
Pt ARG ORIENTATION int Boolean Pt VERTICAL
Pt ARG PAGE INCREMENT int Scalar -1
Pt ARG SCROLLBAR FLAGS short Scalar 0
Pt ARG SCROLL POSITION int Scalar 0
Pt ARG SHOW ARROWS int Boolean On
Pt ARG SLIDER SIZE int Scalar 1/10th of range
Pt CB SCROLL MOVE PtCallback t * Link NULL

Pt ARG DIRECTION
C type Pt type Default
int Boolean Off

Display the maximum value at the top or left, depending on the

orientation.

Pt ARG INCREMENT
C type Pt type Default
long Scalar 1

The value the widget will scroll by when the user clicks the arrow
buttons.

September 20, 2005 Chapter 2 ¯ Widgets 537

PtScrollbar  2005, QNX Software Systems

Pt ARG MAXIMUM
C type Pt type Default
int Scalar 19

The maximum scrollbar value.

Pt ARG MINIMUM
C type Pt type Default
int Scalar 0

The minimum scrollbar value.

Pt ARG MIN SLIDER SIZE

C type Pt type Default
int Scalar 5

The minimum length of the handle, in pixels.

Pt ARG ORIENTATION
C type Pt type Default
int Boolean Pt VERTICAL

The orientation of the scrollbar:

¯ Pt HORIZONTAL

¯ Pt VERTICAL

538 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtScrollbar

☞ Setting this resource sets or clears the Pt SCROLLBAR HORIZONTAL

bit of the Pt ARG SCROLLBAR FLAGS resource.

Pt ARG PAGE INCREMENT

C type Pt type Default
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

C type Pt type Default
short Scalar 0

Flags that control the appearance and behavior of the scrollbar. The
valid bits are:

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 HORIZONTAL
Make the scrollbar horizontal instead of vertical.
This flag is also set or cleared when you set the
Pt ARG ORIENTATION resource.
Pt SCROLLBAR INVERTED
Place the maximum at the bottom of a vertical scrollbar or the
right of a horizontal one.
Pt SCROLLBAR SHOW ARROWS
Display arrow buttons at the ends of the trough.

September 20, 2005 Chapter 2 ¯ Widgets 539

PtScrollbar  2005, QNX Software Systems

Pt ARG SCROLL POSITION

C type Pt type Default
int Scalar 0

The current handle value.

Pt ARG SHOW ARROWS

C type Pt type Default
int Boolean On

Indicates whether or not the scrollbar includes increment/decrement

arrow buttons. Default is on.

Pt ARG SLIDER SIZE

C type Pt type Default
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
C type Pt type Default
PtCallback t * Link NULL

The list of callbacks that the scrollbar invokes when the scroll
position changes.
If the widget has the Pt CALLBACKS ACTIVE bit set in its
Pt ARG FLAGS resource, this callback is also invoked when the
position of the scrollbar is changed by a call to PtSetResources().
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

540 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtScrollbar

reason Pt CB SCROLL MOVE

reason subtype
0 (not used).

event A pointer to the event associated with the callback.

cbdata A pointer to a PtScrollbarCallback t structure that

contains at least the following members:
¯ 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

September 20, 2005 Chapter 2 ¯ Widgets 541

PtScrollbar  2005, QNX Software Systems

PtSetResources(), and the widget has

the Pt CALLBACKS ACTIVE bit set in
its Pt ARG FLAGS resource.
¯ int position — a value corresponding to the handle’s
location.

These callbacks should return Pt CONTINUE.

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 AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Ph BAUD SLOW (see
below)
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 1
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic Pg GRAY
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic Pg MGRAY
Pt ARG FILL PATTERN PtBasic

continued. . .

542 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtScrollbar

Resource Inherited from Default override

Pt ARG FLAGS PtWidget |=Pt GETS FOCUS|
PtHIGHLIGHTED|
PtSET|
PtSELECTABLE|
Pt SELECT NOREDRAW
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic 2
Pt ARG MARGIN WIDTH PtBasic 2
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 543

PtScrollbar  2005, QNX Software Systems

Resource Inherited from Default override

Pt CB REPEAT PtBasic
Pt CB UNREALIZED PtWidget

Pt ARG BANDWIDTH THRESHOLD

The threshold value for graphics bandwidth (as reported by
PtQuerySystemInfo()) that defines a slow connection.

544 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtSeparator
A line for organizing menu items

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.

New Ctrl+N
Open... Ctrl+O
Save Ctrl+S
Save As...
Close

Import Files

Exit Ctrl+X

PtSeparator widgets are frequently used to organize the items in a menu.

New resources:

September 20, 2005 Chapter 2 ¯ Widgets 545

PtSeparator  2005, QNX Software Systems

Resource C type Pt type Default

Pt ARG SEP FLAGS short Flag Pt SEP HORIZONTAL
Pt ARG SEP TYPE unsigned short Scalar Pt SINGLE LINE

Pt ARG SEP FLAGS

C type Pt type Default
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 will be vertical. If
this bit is Pt SEP HORIZONTAL, the separator will be
horizontal.

Pt ARG SEP TYPE

C type Pt type Default
unsigned short Scalar Pt SINGLE LINE

Possible values:

¯ Pt SINGLE LINE
¯ Pt DOUBLE LINE
¯ Pt SINGLE DASH LINE
¯ Pt DOUBLE DASH LINE
¯ Pt ETCHED IN
¯ Pt ETCHED OUT
¯ Pt NOLINE

546 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtSeparator

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 AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic 0
Pt ARG MARGIN WIDTH PtBasic 0
Pt ARG POS PtWidget

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 547

PtSeparator  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG RESIZE FLAGS PtWidget
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB UNREALIZED PtWidget

548 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtSlider
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 serves as a numerical input mechanism that
allows the user to choose values within a specified range from
minimum to maximum.

100

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. The size of the handle is determined by
Pt ARG SLIDER HANDLE WIDTH and
Pt ARG SLIDER HANDLE HEIGHT or by the size of
Pt ARG SLIDER IMAGE.

Mouse actions
When the user presses the mouse button, the result depends on the
location of the pointer.

September 20, 2005 Chapter 2 ¯ Widgets 549

PtSlider  2005, QNX Software Systems

If the pointer is: Then:

In the trough The handle will move up or down one slider
multiple
On the handle A drag is started

Keyboard actions

If the user presses: The handle will:

↑ Move up one increment
↓ Move down one increment
→ Move right one increment
← Move left one increment
Pg Up Move up/right one “page”
Pg Down Move down/left one “page”
Home Move to the minimum value
End Move 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

orientation and on the setting of the Pt ARG GAUGE FLAGS
resource.

New resources:

550 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtSlider

Resource C type Pt type Default

Pt ARG SLIDER FLAGS short int Flag See
below
Pt ARG SLIDER HANDLE HEIGHT short int Scalar 40
Pt ARG SLIDER HANDLE WIDTH short int Scalar 15
Pt ARG SLIDER IMAGE void * Alloc NULL
Pt ARG SLIDER INCREMENT ushort t Scalar 1
Pt ARG SLIDER LABEL BR char * Alloc NULL
Pt ARG SLIDER LABEL BR COL PgColor t Scalar Pg BLACK
Pt ARG SLIDER LABEL TL char * Alloc NULL
Pt ARG SLIDER LABEL TL COL PgColor t Scalar Pg BLACK
Pt ARG SLIDER MULTIPLE ushort t Scalar 0
Pt ARG SLIDER ORIENTATION short Scalar Pt SLIDER MIN ON TOP

Pt ARG SLIDER TICK MAJOR COL PgColor t Scalar Pg BLACK

Pt ARG SLIDER TICK MAJOR DIV short int Scalar 10
Pt ARG SLIDER TICK MAJOR LEN short int Scalar 10
Pt ARG SLIDER TICK MINOR COL PgColor t Scalar Pg BLACK
Pt ARG SLIDER TICK MINOR DIV short int Scalar 0
Pt ARG SLIDER TICK MINOR LEN short int Scalar 0
Pt ARG SLIDER TROUGH COL PgColor t Scalar Pg GRAY
Pt ARG SLIDER TROUGH SIZE short int Scalar 4
Pt CB SLIDER MOVE PtCallback t * Link NULL

Pt ARG SLIDER FLAGS

September 20, 2005 Chapter 2 ¯ Widgets 551

PtSlider  2005, QNX Software Systems

C type Pt type Default

short int Flag Pt TICKS ON BOTTOM |
Pt SLIDER POINT DOWN

Valid flags:

Pt TICKS ON TOP, Pt TICKS ON LEFT

Ticks are placed on the top or left of the slider, depending on
the orientation.
Pt TICKS ON BOTTOM, Pt TICKS ON RIGHT
Ticks are placed on the bottom or right of the slider, depending
on the orientation.
Pt TICKS TOUCH TROUGH
Ticks touch the trough.
Pt TICKS ETCHED OUT
Ticks are etched out.
Pt TICKS ETCHED IN
Ticks are etched in.
Pt SLIDER POINT LEFT, Pt SLIDER POINT UP
The slider handle will point up or left, depending on the
orientation.
Pt SLIDER POINT RIGHT, Pt SLIDER POINT DOWN
The slider handle will point down or right, depending on the
orientation.
Pt SLIDER IMAGE
The slider handle will be the image specified by the
Pt ARG SLIDER IMAGE resource.

552 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtSlider

Pt ARG SLIDER HANDLE HEIGHT

C type Pt type Default
short int Scalar 40

The height of the slider handle.

Pt ARG SLIDER HANDLE WIDTH

C type Pt type Default
short int Scalar 15

The width of the slider handle.

Pt ARG SLIDER IMAGE

C type Pt type Default
void * Alloc NULL

The image that will be displayed as the handle if the

Pt ARG SLIDER FLAGS resource has the Pt SLIDER IMAGE flag set.

Pt ARG SLIDER INCREMENT

C type Pt type Default
ushort t Scalar 1

The slider increment when the cursor keys are pressed.

Pt ARG SLIDER LABEL BR

C type Pt type Default
char * Alloc NULL

September 20, 2005 Chapter 2 ¯ Widgets 553

PtSlider  2005, QNX Software Systems

The label string that’s placed at the bottom or right of the slider,
depending on the orientation.

Pt ARG SLIDER LABEL BR COL

C type Pt type Default
PgColor t Scalar Pg BLACK

The color of the bottom or right label.

Pt ARG SLIDER LABEL TL

C type Pt type Default
char * Alloc NULL

The label string that’s placed at the top or left of the slider, depending
on the orientation.

Pt ARG SLIDER LABEL TL COL

C type Pt type Default
PgColor t Scalar Pg BLACK

The color of the top or left label.

Pt ARG SLIDER MULTIPLE

C type Pt type Default
ushort t Scalar 0

The slider increment when the pointer is pressed in the trough, or Pg

Up or Pg Down is pressed.

554 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtSlider

Pt ARG SLIDER ORIENTATION

C type Pt type Default
short Scalar Pt SLIDER MIN ON TOP

The location of the minimum value for the slider: on the top or
bottom if the slider is vertical; on the left or right if the slider is
horizontal. The possible values are:

¯ Pt SLIDER MIN ON TOP

¯ Pt SLIDER MIN ON LEFT (same as Pt SLIDER MIN ON TOP)

¯ Pt SLIDER MIN ON BOTTOM

¯ Pt SLIDER MIN ON RIGHT (same as

Pt SLIDER MIN ON BOTTOM)

Pt ARG SLIDER TICK MAJOR COL

C type Pt type Default
PgColor t Scalar Pg BLACK

The color of the major ticks.

Pt ARG SLIDER TICK MAJOR DIV

C type Pt type Default
short int Scalar 10

The number of major divisions.

Pt ARG SLIDER TICK MAJOR LEN

September 20, 2005 Chapter 2 ¯ Widgets 555

PtSlider  2005, QNX Software Systems

C type Pt type Default

short int Scalar 10

The length of the major ticks.

Pt ARG SLIDER TICK MINOR COL

C type Pt type Default
PgColor t Scalar Pg BLACK

The color of the minor ticks.

Pt ARG SLIDER TICK MINOR DIV

C type Pt type Default
short int Scalar 0

The number of minor divisions per major division.

Pt ARG SLIDER TICK MINOR LEN

C type Pt type Default
short int Scalar 0

The length of the minor ticks.

Pt ARG SLIDER TROUGH COL

C type Pt type Default
PgColor t Scalar Pg GRAY

The color of the trough.

556 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtSlider

Pt ARG SLIDER TROUGH SIZE

C type Pt type Default
short int Scalar 4

The height or width of the trough, depending on the orientation. The

other dimension is obtained from the Pt ARG DIM resource, which is
inherited from PtWidget.

Pt CB SLIDER MOVE
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that the slider invokes when the handle position
changes.
If the widget has the Pt CALLBACKS ACTIVE bit set in its
Pt ARG FLAGS resource, these callbacks are also invoked when the
handle position is changed by a call to PtSetResources().
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB SLIDER MOVE

reason subtype
0 (not used).

cbdata A pointer to a PtSliderCallback t structure that

contains at least the following member:

int position; A value corresponding to the slider

handles location.

These callbacks should return Pt CONTINUE.

September 20, 2005 Chapter 2 ¯ Widgets 557

PtSlider  2005, QNX Software Systems

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 AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 1
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic Pg GRAY
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget |=Pt GETS FOCUS
Pt ARG GAUGE FLAGS PtGauge
Pt ARG GAUGE FONT PtGauge
Pt ARG GAUGE H ALIGN PtGauge Not used by this class.
Pt ARG GAUGE MAXIMUM PtGauge
Pt ARG GAUGE MINIMUM PtGauge

continued. . .

558 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtSlider

Resource Inherited from Default override

Pt ARG GAUGE ORIENTATION PtGauge Pt HORIZONTAL
Pt ARG GAUGE V ALIGN PtGauge Not used by this class.
Pt ARG GAUGE VALUE PtGauge
Pt ARG GAUGE VALUE PREFIX PtGauge Not used by this class.
Pt ARG GAUGE VALUE SUFFIX PtGauge Not used by this class.
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic 0
Pt ARG MARGIN WIDTH PtBasic 0
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 559

PtSlider  2005, QNX Software Systems

Resource Inherited from Default override

Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB UNREALIZED PtWidget

560 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTab
A tab button for initiating an action

Class hierarchy:
PtWidget → PtBasic → PtLabel → PtButton → PtTab

PhAB icon:

Pt Tab

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.

Print Search Options

A group of PtTab widgets positioned at the top of a PtPane.

When using PtTab, you might want to:

¯ 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.

September 20, 2005 Chapter 2 ¯ Widgets 561

PtTab  2005, QNX Software Systems

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

Resource C type Pt type Default

Pt ARG TAB FLAGS unsigned int Flag 0

Pt ARG TAB FLAGS

C type Pt type Default
unsigned int Flag 0

Flags that affect how the widget appears. The only bit defined is:

Pt TAB UPSIDE DOWN

Display the rounded corners on the bottom of the widget instead
of the top.

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 ACCEL KEY PtLabel
Pt ARG AREA PtWidget

continued. . .

562 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTab

Resource Inherited from Default override

Pt ARG ARM COLOR PtButton Pg GRAY
Pt ARG ARM DATA PtButton
Pt ARG ARM FILL PtButton
Pt ARG BALLOON COLOR PtLabel
Pt ARG BALLOON FILL COLOR PtLabel
Pt ARG BALLOON POSITION PtLabel
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 2
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic PgGray(170)
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget |=Pt CLIP HIGHLIGHT|
Pt TOGGLE
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic 3
Pt ARG HORIZONTAL ALIGNMENT PtLabel
Pt ARG LABEL BALLOON PtLabel

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 563

PtTab  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG LABEL DATA PtLabel
Pt ARG LABEL FLAGS PtLabel &=
˜Pt LABEL SELECT SHIFT
Pt ARG LABEL TYPE PtLabel
Pt ARG LINE SPACING PtLabel
Pt ARG MARGIN BOTTOM PtLabel
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN LEFT PtLabel
Pt ARG MARGIN RIGHT PtLabel
Pt ARG MARGIN TOP PtLabel
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget
Pt ARG TEXT FONT PtLabel
Pt ARG TEXT STRING PtLabel
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG UNDERLINE TYPE PtLabel
Pt ARG UNDERLINE1 PtLabel
Pt ARG UNDERLINE2 PtLabel
Pt ARG USER DATA PtWidget
Pt ARG VERTICAL ALIGNMENT PtLabel
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic

continued. . .

564 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTab

Resource Inherited from Default override

Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB UNREALIZED PtWidget

September 20, 2005 Chapter 2 ¯ Widgets 565

PtTerminal  2005, QNX Software Systems
A window that emulates a character-mode terminal

Class hierarchy:
PtWidget → PtBasic → PtContainer → PtTerminal

PhAB icon:

Public header:
<photon/PtTerm.h>

Description:
The PtTerminal class provides a text window emulating a character
terminal.
Pg.svga phrelay.110
Pg.svgadc psh
Pg.tvg9470 pterm
Pg.vga4 pv
Pg.wd pwm
Pg.xga pwmclock
Photon pwmopts
Photon.slib snapshot
Photon.slib11 web.server
acalib webclient
bdf_2_phf winview
colorbar
$

A PtTerminal widget.

Characters can be sent to the terminal with the PtTerminalPutc(),

PtTerminalPut() and PtTerminalPuts() functions, and keyboard input
to the terminal is available with 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

566 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminal

¯ scrolling

¯ other activities permitted through escape sequences. For

information about specific escape sequences, see Dev.con and
Dev.ansi in the QNX Utilities Reference.

☞ 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.

September 20, 2005 Chapter 2 ¯ Widgets 567

PtTerminal  2005, QNX Software Systems

Fonts
Application programs set the Pt ARG TERM FONT resource to set
an explicit font name or the Pt ARG TERM FONT INDEX resource
to choose a font from the list of supported fonts,
Pt ARG TERM FONT LIST.
If the Pt TERM KBFONT bit is set in Pt ARG TERM RESIZE FL, the
user can select a font using the keyboard:

¯ Pressing Ctrl – Alt – < or Ctrl – Alt – [ decrements the value of

Pt ARG TERM FONT INDEX by one (unless it’s already at 0) or
sets it to the maximum value (if the current value is -1).
¯ Pressing Ctrl – Alt – > or Ctrl – Alt – ] increments 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 the Pt TERM OPFONT flag is set, the font can be changed by escape
sequences:

¯ If the font is set using the Pt ARG TERM FONT resource and the
new font name is equal to one of the names on the current font list,
the Pt ARG TERM FONT INDEX resource 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, the
Pt ARG TERM FONT INDEX resource can be set to its index but
the current font isn’t changed.

568 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminal

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 the 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 the ANSI mode, the internal character set can be used for
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 Dev.ansi in the QNX Utilities

Reference.
ANSI character set
What’s used in the 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
display is encoded using the internal character set (in particular, all
the terminal fonts shipped with Photon use the PC character set rather

September 20, 2005 Chapter 2 ¯ Widgets 569

PtTerminal  2005, QNX Software Systems

than Unicode). The application can define an additional mapping; for

example, it’s possible to 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
There are four groups of resources that affect a terminal widget’s
geometry:

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.

570 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminal

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.

September 20, 2005 Chapter 2 ¯ Widgets 571

PtTerminal  2005, QNX Software Systems

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 would adjust the number of columns (xs) and the
margin height (ym).
Before any adjustments specified by the string are done,
Pt ARG TERM MARGINS resource is reset to the
Pt ARG MARGIN HEIGHT and/or Pt ARG MARGIN WIDTH
values.
Adjusting the dimension is always successful, while adjusting 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,

572 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminal

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

September 20, 2005 Chapter 2 ¯ Widgets 573

PtTerminal  2005, QNX Software Systems

¯ 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, the limits should be set before the size.
The minimum size (together with font and margins) determines also
minimal values for the Pt ARG DIM resource. There is no upper limit
for the dimensions because there is no upper limit for the
Pt ARG TERM MARGINS resource.

Console emulation
A PtSetResources() call for the Pt ARG TERM CONSOLE resource
works in a manner similar to the console write() function.
First, the application should fill a PtTerminalConsoleWrite t
structure with data corresponding to arguments of the console write()
function. The pointer to the structure is the argument of the
PtSetArg() macro. The PtSetResources() function transfers actual
screen data from the buffer given by the application to the widget’s
screen buffer. Then a damage event is generated in order to display
the new data. The function doesn’t check whether offset and length
given by the application don’t exceed the size of the buffer.
A PtGetResources() call for the Pt ARG TERM CONSOLE resource
directly returns a pointer to the buffer. If the 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.

574 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminal

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. Color numbers are indexes into this array. The default array
has 16 elements corresponding to 16 standard CGA colors.
The 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 from the default values too much.

Drawing and scrolling

The Pt ARG TERM DRAW MODES resource defines the widget’s
scrolling capability.

Scrolling optimization

If characters are given to the PtTerminalPut() function 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 the
Pt ARG BANDWIDTH THRESHOLD (see PtBasic),
Pt ARG TERM SCROLL, and Pt ARG TERM DRAW MODES
resources 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.

September 20, 2005 Chapter 2 ¯ Widgets 575

PtTerminal  2005, QNX Software Systems

Otherwise, the maximal value of n is the value of the

Pt ARG TERM SCROLL resource.

New resources:

Resource C type Pt type Default

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

continued. . .

576 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminal

Resource C type Pt type Default

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 PROTOCOL int Boolean 1
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"

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 577

PtTerminal  2005, QNX Software Systems

Resource C type Pt type Default

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

C type Pt type Default
PtTerminalAppState t Struct See below

A structure containing the application window state, which is needed

by the protocol engine (see the Pt CB TERM APP callback). This
structure also contains some other information that can be used by a
terminal emulator, such as the window title, size, and position.
The PtTerminalAppState t structure is defined as:

578 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminal

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 QNX Windows. A text-mode program written for
QNX Windows 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
otherwise ignored because their original meaning is too specific to
QNX Windows). The only exception is title — pterm uses it to set its
window title.
If you have a text-mode program that needs more compatibility with
the QNX Windows terminal emulator than pterm offers, 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.

September 20, 2005 Chapter 2 ¯ Widgets 579

PtTerminal  2005, QNX Software Systems

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 that QNX Windows would display on the

icon instead of the window title.

Pt ARG TERM CHARSETS

C type Pt type Default
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.

580 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminal

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

C type Pt type Default
PtTerminalColorMode t Struct Pt TERM COLOR MODE

A set of pointers to conversion functions, used internally by the

widget.

Pt ARG TERM COLOR TABLE

C type Pt type Default
PgColor t[], short Array CGA colors, 16

Color table used for display. Converts 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

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 581

PtTerminal  2005, QNX Software Systems

Index Color
2 GREEN
3 CYAN
4 RED
5 MAGENTA
6 BROWN
7 WHITE (light grey)
8 BRIGHT BLACK (dark grey)
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

C type Pt type Default
short Scalar 80

The number of character columns.

Pt ARG TERM CONSOLE

C type Pt type Default
PtTerminalConsoleWrite t Complex N/A

582 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminal

This resource can be used for accessing the “video memory” of the
widget. For more information, see the “Console emulation” part of
the “Description” section above.

Pt ARG TERM CUR COL

C type Pt type Default
short Scalar 0

The column number of cursor position.

Pt ARG TERM CUR POS

C type Pt type Default
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

C type Pt type Default
short Scalar 0

The line number of cursor position.

Pt ARG TERM CURSOR FLAGS

C type Pt type Default
short Flag Pt TERM CURSOR ON FOCUS

Flags affecting the cursor timer. Possible values are:

September 20, 2005 Chapter 2 ¯ Widgets 583

PtTerminal  2005, QNX Software Systems

¯ 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 only runs 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

C type Pt type Default
unsigned char Flag Pt TERM SCROLL RFSH

The 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 the PhBlit() function 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 whether it isn’t obscured or clipped by other widgets in
such a way that the PhBlit() function 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,

584 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminal

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

C type Pt type Default
char * String "pcterm14"

The name of the font used for display. For more information, see the
“Fonts” part of the “Description” section above.

☞ PtTerminal works only with fixed-width fonts. It ignores any

attempts to change to a proportional font.

Pt ARG TERM FONT INDEX

C type Pt type Default
short Scalar -1

Position of the current font on the font list, or -1 if the current font
isn’t on the list. Can be used to choose a font from the list, but cannot
be explicitly set to -1.

Pt ARG TERM FONT LIST

C type Pt type Default
char **, short Array NULL, 0

List of fonts (an array of pointers to strings).

September 20, 2005 Chapter 2 ¯ Widgets 585

PtTerminal  2005, QNX Software Systems

When this resource is being set, 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 the
“Fonts” part of the “Description” section above.

Pt ARG TERM FONT SIZE (read-only)

C type Pt type Default
PhDim t Struct Size of default font

The dimensions of the font used for display.

Pt ARG TERM MARGINS (read-only)

C type Pt type Default
PhRect t Struct 0, 0, 0, 0

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 the
“Geometry” part of the “Description” section above.

Pt ARG TERM MAXCOLS

C type Pt type Default
short Scalar 1000

The maximum number of character columns.

586 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminal

Pt ARG TERM MAXROWS

C type Pt type Default
short Scalar 1000

The maximum number of character rows.

Pt ARG TERM MAXSIZE

C type Pt type Default
PtTerminalRowCol t Struct 1000, 1000

Maximum screen size. The PtTerminalRowCol t structure

contains the following members:

¯ short r

¯ short c

Pt ARG TERM MINCOLS

C type Pt type Default
short Scalar 1

The minimum number of character columns.

Pt ARG TERM MINROWS

C type Pt type Default
short Scalar 1

The minimum number of character rows.

September 20, 2005 Chapter 2 ¯ Widgets 587

PtTerminal  2005, QNX Software Systems

Pt ARG TERM MINSIZE

C type Pt type Default
PtTerminalRowCol t Struct 1, 1

Minimum screen size. The PtTerminalRowCol t structure

contains the following members:

¯ short r

¯ short c

Pt ARG TERM OPTIONS

C type Pt type Default
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>). Some
of them are handled by the widget, some others can be handled by the
application.

Pt ARG TERM OPTMASK

C type Pt type Default
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 PROTOCOL

C type Pt type Default
short Boolean 1

588 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminal

The protocol:

0 QNX4

1 ANSI

Pt ARG TERM RESIZE FL

C type Pt type Default
unsigned short Flag All defined flags

Bit flags that affect terminal widget’s resizing. Valid values are:

¯ 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

C type Pt type Default
See below Pointer Pointer to static function

Pointer to a function used in geometry adjustments. The prototype is:

const char*(*)(char*, const char*)

September 20, 2005 Chapter 2 ¯ Widgets 589

PtTerminal  2005, QNX Software Systems

For more information, see the “Geometry” part of the “Description”

section above.

Pt ARG TERM RESIZE STR

C type Pt type Default
char * String "DF=sM:M=s"

A hint for the function used in geometry adjustments. For more

information, see the “Geometry” part of the “Description” section
above.

Pt ARG TERM ROWS

C type Pt type Default
short Scalar 25

The number of character rows.

Pt ARG TERM SCRLBK COUNT

C type Pt type Default
short Scalar 0

The current number of lines saved in the scrollback buffer.

Pt ARG TERM SCRLBK LIMIT

C type Pt type Default
short Scalar 0

The maximum of number of lines saved in the scrollback buffer.

590 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminal

Pt ARG TERM SCRLBK POS

C type Pt type Default
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

C type Pt type Default
short Scalar Pt TERM MAX ROWS

The maximum number of scrolls that will be delayed. For more

information, see the “Scrolling optimization” part of the
“Description” section above.

Pt ARG TERM SELECTION

C type Pt type Default
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.

September 20, 2005 Chapter 2 ¯ Widgets 591

PtTerminal  2005, QNX Software Systems

¯ 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 — mouse always
selects text.
¯ Pt TERM SELECTION NEVER — mouse 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

592 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminal

Pt ARG TERM SIZE

C type Pt type Default
PtTerminalRowCol t Struct 25, 80

Screen size, measured in characters. The PtTerminalRowCol t

structure contains the following members:

¯ short r

¯ short c

Pt ARG TERM VISUAL BELL

C type Pt type Default
short Scalar 20

Time, in milliseconds, of the screen flash when the ASCII BEL

character (Ctrl – G) is received.

Pt CB TERM APP
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks invoked whenever the Pt ARG TERM APP

resource changes, or a private escape sequence is received.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB TERM APP

reason subtype
The character or number defining the type of escape
sequence.
event NULL

September 20, 2005 Chapter 2 ¯ Widgets 593

PtTerminal  2005, QNX Software Systems

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>.
These callbacks should return Pt CONTINUE.

594 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminal

Pt CB TERM FONT
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks invoked after the font is changed. Each callback is

passed a PtCallbackInfo t structure that contains at least the
following members:

reason Pt CB TERM FONT

event NULL

cbdata A pointer to a PtTerminalFontChange t structure

that contains at least the following members:

const char * old font;

Defines the previous font.
const char * new font;
Defines the new font.

These callbacks should return Pt CONTINUE.

Pt CB TERM INPUT
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks invoked when keyboard or mouse input is delivered

to the widget. Each callback is passed a PtCallbackInfo t
structure that contains at least the following members:

reason Pt CB TERM INPUT

reason subtype
Can be one of:

September 20, 2005 Chapter 2 ¯ Widgets 595

PtTerminal  2005, QNX Software Systems

¯ 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.

event A pointer to a PhEvent t structure 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 least the following members:

unsigned short 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.

596 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminal

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.
These callbacks should return Pt CONTINUE.

Pt CB TERM OPTIONS
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks invoked whenever the Pt ARG TERM OPTIONS

resource changes. Each callback is passed a PtCallbackInfo t
structure that contains at least the following members:

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 contains at least the following members:

unsigned long old opts;

The previous value of the options.
unsigned long new opts;
The new value of the options.

These callbacks should return Pt CONTINUE.

September 20, 2005 Chapter 2 ¯ Widgets 597

PtTerminal  2005, QNX Software Systems

Pt CB TERM RESIZE
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks invoked when the terminal is about to change its

size (number of rows and/or columns).
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB TERM RESIZE

event NULL

cbdata A pointer to a PtTerminalSizeChange t structure

that contains at least the following members:

PtTerminalRowCol t old size;

Current size of the terminal.
PtTerminalRowCol t new size;
New size.

The PtTerminalRowCol t structure contains the

following members:
¯ 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 a PtSetResources() call is issued 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.
These callbacks should return Pt CONTINUE.

598 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminal

Pt CB TERM RESIZED
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks invoked after the size is changed.

Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB TERM RESIZED

event NULL

cbdata A pointer to a PtTerminalSizeChange t structure

that contains at least the following members:

PtTerminalRowCol t old size;

Previous size of the terminal.
PtTerminalRowCol t new size;
Current size.

The PtTerminalRowCol t structure contains the

following members:
¯ 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.
This callback should return Pt CONTINUE.

September 20, 2005 Chapter 2 ¯ Widgets 599

PtTerminal  2005, QNX Software Systems

Pt CB TERM SCRLBK
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks invoked whenever the

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 at least the following
members:

reason Pt CB TERM SCRLBK

reason subtype
0

event NULL

cbdata A pointer to a PtTerminalScrlbkCb t structure that

contains at least the following members:

short old count;

Previous value of the line count
short old pos; Previous value of the line position.
short new count;
New line count.
short new pos;
New line position.

☞ Functions invoked by this callback shouldn’t set any of the widget’s

resources.

These callbacks should return Pt CONTINUE.

600 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminal

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 PtContainer
Pt ARG ANCHOR OFFSETS PtContainer
Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Ph BAUD SLOW (see
below)
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic Pt INHERIT COLOR
(see below)
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG HELP TOPIC PtWidget

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 601

PtTerminal  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget 0
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer

continued. . .

602 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminal

Resource Inherited from Default override

Pt CB UNREALIZED PtWidget

Pt ARG BANDWIDTH THRESHOLD

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 the “Scrolling
optimization” part of the “Description” section.

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 ]

Convenience functions:
The PtTerminal widget defines several convenience functions and
data structures that make it easier to use the terminal once it’s been
created. Here’s a brief overview:

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.

September 20, 2005 Chapter 2 ¯ Widgets 603

PtTerminal  2005, QNX Software Systems

PtTerminalDefaultCharsets():
Get the default character sets used by PtTerminal.
PtTerminalFont()
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.

604 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminalCharset t,
PtTerminalCharsets t
Character sets used by PtTerminal
Synopsis:
typedef struct {
const wchar t *table;
unsigned char first, last;
...
} PtTerminalCharset t;

typedef struct {
PtTerminalCharset t const *AnsiCharset;
PtTerminalCharset t const *InternalCharset;
PtTerminalCharset t const *FontTranslation;
...
} 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;

September 20, 2005 Chapter 2 ¯ Widgets 605

PtTerminalCharset t,
PtTerminalCharsets t  2005, QNX Software Systems

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

Classification:
Photon

606 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminalCharset t,
PtTerminalCharsets t
See also:
PtTerminal, PtTerminalDefaultCharsets():

September 20, 2005 Chapter 2 ¯ Widgets 607

PtTerminalCopy()  2005, QNX Software Systems
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
Interrupt handler No
Signal handler No
Thread No

608 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminalCreateCsXlat()
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
Interrupt handler No
continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 609

PtTerminalCreateCsXlat()  2005, QNX Software Systems

Safety
Signal handler No
Thread No

See also:
PtTerminal, Pt ARG TERM CHARSETS,
PtTerminalCharsets t

610 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems 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
Interrupt handler No
Signal handler No
Thread No

See also:
PtTerminal, PtTerminalCharsets t

September 20, 2005 Chapter 2 ¯ Widgets 611

PtTerminalFont()  2005, QNX Software Systems
Convert font name to a fixed-width font name

Synopsis:
char *PtTerminalFont( 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, PtTerminalFont() 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 *size.

¯ If offs isn’t NULL, the function stores in *offs the position that
should be given to a drawing function in order to draw the
character cell starting at position (0, 0).

If the specified font doesn’t exist, the information about the default
font is returned.

Returns:
An allocated copy of the font name, or NULL if the appropriate font
doesn’t exist.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

612 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminalFont()

September 20, 2005 Chapter 2 ¯ Widgets 613

PtTerminalGetKeys()  2005, QNX Software Systems
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 are not modified. For more
information, see the Pt ARG TERM PROTOCOL resource associated
with the PtTerminal widget.

Classification:
Photon

614 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminalGetKeys()

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 615

PtTerminalGetSelection()  2005, QNX Software Systems
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 the caller’s responsibility to free() the buffer when it’s no longer
needed.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

616 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems 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 PROTOCOL resource
associated with the PtTerminal widget.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 617

PtTerminalPasteClipboard()  2005, QNX Software Systems
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 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
Interrupt handler No
Signal handler No
Thread No

618 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems 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 Pt CB TERM INPUT callback. The
given event is passed to the callback functions.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 619

PtTerminalPut(), PtTerminalPutc(),
PtTerminalPuts()  2005, QNX Software Systems
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 is not a terminal widget.

EBUSY Invalid recursion.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

620 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTerminalPut(), PtTerminalPutc(),
PtTerminalPuts()

September 20, 2005 Chapter 2 ¯ Widgets 621

PtTerminalSelectWord()  2005, QNX Software Systems
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 the cursor position if pos is NULL).
The PtTerminalRowCol t structure contains the following
members:

¯ 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
Interrupt handler No
Signal handler No
Thread No

622 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtText
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. Basic editing features are provided so you can alter
text that has been entered. A point-and-click model of editing is also
supported so that blocks of text can be operated on as a unit.

This is a text string.

aboutdlg

A PtText widget.

Photon provides two different text widgets:

¯ PtText — a small, simple widget that provides a single-line

data-entry field. The attributes of the text in the field can’t be
changed — the same font and color are used throughout the text
string.

¯ PtMultiText — a full-featured text editor that handles multiple

lines of text. Blocks of text may be selected and assigned different
text attributes (e.g. the text may be displayed in several different
fonts and colors).

Interaction model
The text entered 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.

September 20, 2005 Chapter 2 ¯ Widgets 623

PtText  2005, QNX Software Systems

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.

Selecting text
Clicking the mouse button once changes the cursor location to the
character position nearest the pointer location. Dragging the pointer
with the button pressed causes a range of text to be selected 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.
The range of text selected can be extended 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.
Any character you type after a range of text has been selected replaces
the selected range. A string specified by the application may also
replace the selected range.

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.

Setting text

You can set the widget’s text using the Pt ARG TEXT STRING
resource. You must give this resource a null-terminated C string as a
value.

624 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtText

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} };

main(int argc, char *argv[])

{
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);
if ((window = PtAppInit(&app, &argc, argv, nargs,
args)) == NULL)
exit(EXIT FAILURE);

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);

PtRealizeWidget(window);
PtMainLoop();
}

Getting text

The widget’s text can also be retrieved 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.

September 20, 2005 Chapter 2 ¯ Widgets 625

PtText  2005, QNX Software Systems

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. The range may be passed to other
convenience functions to modify the selected text.

Replacing text

Any block of text in the widget can be programmatically replaced by

a string using the PtTextModifyText() function. The parameters to this
function are:

widget 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 the text is changed by a call to
PtSetResources() or to a text widget function such as
PtTextModifyText(). There are two text modification callbacks:

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.

626 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtText

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 *);

main(int argc, char *argv[])

{
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++;
if ((window = PtAppInit(&app, &argc, argv, nargs,
args)) == NULL)
exit(EXIT FAILURE);

nargs = 0;
PtSetArg(&args[nargs], Pt ARG TEXT STRING, "Enter Text:", 0);
nargs++;
label = PtCreateWidget(PtLabel, window, nargs, args);

September 20, 2005 Chapter 2 ¯ Widgets 627

PtText  2005, QNX Software Systems

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);

PtRealizeWidget(window);

PtMainLoop();
}

int allcaps( PtWidget t *w, void *client data,

PtCallbackInfo t *info)
{
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.

628 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtText

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 — the user
most likely pressed the Delete key or the destructive backspace
key.

¯ If new insert is less than cur insert, the user pressed the
destructive backspace key.

¯ If new insert equals cur insert, the user pressed the Delete key.

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;

September 20, 2005 Chapter 2 ¯ Widgets 629

PtText  2005, QNX Software Systems

main(int argc, char *argv[])

{
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);
if ((window = PtAppInit(NULL, &argc, argv, nargs,
args)) == NULL)
exit(EXIT FAILURE);

nargs = 0;
PtSetArg( &args[nargs++], Pt ARG TEXT STRING,
"Enter Text:", 0);
label = PtCreateWidget(PtLabel, NULL, 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, NULL, 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, NULL, nargs, args);

PtRealizeWidget(window);

PtMainLoop();
}

int check passwd( PtWidget t *widget, void *client data,

PtCallbackInfo t *info )

630 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtText

// 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;
PtArg t args[1];

PtSetArg (&args[0], Pt ARG TEXT STRING, &passwd, 0 );

PtGetResources ( offscreen text, 1, args );
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 stars in the displayed
// widget.

PtTextCallback t *tcb = (PtTextCallback t *)info->cbdata;

static const char stars[] = "********************";
PtArg t args[1];

PtSetArg( &args[0], Pt ARG TEXT SUBSTRING, tcb, 0 );

PtSetResources( offscreen text, 1, args );
tcb->text = stars;

return Pt CONTINUE;
}

String changes

After the user has 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

September 20, 2005 Chapter 2 ¯ Widgets 631

PtText  2005, QNX Software Systems

editors to determine if the contents of the text buffer are “dirty” (i.e.
they’ve been modified by the user).
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).
An example of using this callback in form-filling applications is to
provide a visual cue to the user 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 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 provides callbacks that tell the 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 text field into this
one.
When the text widget obtains the focus by either of these two means,
any callbacks defined in the Pt CB GOT FOCUS callback list for the
widget are called. This is useful if the application wishes to alter the
appearance of a text widget that the user is entering text into, or to

632 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtText

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 the
next field or by clicking within another widget. This callback can be
used 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 performing any syntax checking done on the
fields within a form.

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

¯ The user moves the cursor by using the arrow keys.

Or:

¯ The user clicks the SELECT pointer button.

Or:

¯ The 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 the callback to be invoked.
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 describing
the user action. To differentiate between a pointer event and a
keypress event, look at the type of that event.

September 20, 2005 Chapter 2 ¯ Widgets 633

PtText  2005, QNX Software Systems

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. The doit member can be set to zero to
prevent the cursor movement from taking place.

Activate callback
The PtText widget provides an activate callback, Pt CB ACTIVATE,
that’s invoked when one of the following occurs:

¯ The user presses the Enter key within the widget. This signals that
any changes to the field are complete and the 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.

¯ The user clicks 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.

¯ The text was modified, the widget has lost focus, and
Pt CHANGE ACTIVATE is set in the 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

634 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtText

the dialog. In other words, for a prompt dialog, entering 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 allows a pattern to be
specified for the text entered into the text field. Any characters the
user enters must conform to this pattern or they’ll be rejected.

☞ Edit masks can be difficult to use and aren’t very flexible. It’s better to
use a Pt CB MODIFY VERIFY callback than an edit mask to
constrain input.

The string entered into a data-entry field often conforms to some

format. Edit masks are provided within the text widget to enforce the
entry of the information in the correct format.
A single edit mask may be provided 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 the user enters must match the corresponding
character in the edit mask.
Here are the characters that may be specified 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.

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 635

PtText  2005, QNX Software Systems

This character: Matches:

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.
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 the user has entered enough characters to reach that position,
the character is automatically inserted. After that, the character may
not be deleted or altered by the user.
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 the user
enters and automatically adds the space character.

Mouse actions
If the user: The widget:
Presses the mouse button Gets input focus
Presses the mouse button and drags the Extends the text selection
mouse
Releases the mouse button Ends the text selection

636 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtText

Keyboard actions
If the user presses: 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
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

New resources:

September 20, 2005 Chapter 2 ¯ Widgets 637

PtText  2005, QNX Software Systems

Resource C type Pt type Default

Pt ARG COLUMNS short Scalar 0
Pt ARG CURSOR POSITION int Scalar -1
Pt ARG EDIT MASK char * Scalar NULL
Pt ARG MAX LENGTH short 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 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
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
C type Pt type Default
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.

638 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtText

Pt ARG CURSOR POSITION

C type Pt type Default
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

C type Pt type Default
char * Scalar 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.

September 20, 2005 Chapter 2 ¯ Widgets 639

PtText  2005, QNX Software Systems

anything else Treated as a place holder, and appears as is,

without alteration, in the text field. The cursor
“steps over” place holders.

☞ Edit masks can be difficult to use and aren’t very flexible. It’s better to
use a Pt CB MODIFY VERIFY callback than an edit mask to verify
input.

Pt ARG MAX LENGTH

C type Pt type Default
short Scalar SHRT MAX

The maximum text length the widget accepts.

Pt ARG SELECTION RANGE

C type Pt type Default
See below Complex See below

This resource can be used to select a range of text or determine what

text is currently selected. This resource is complex, and requires
special handling:

When setting...
The value is a pointer to an instance of a PtTextControl t
structure. The start pos and end pos members of the structure
indicate the range of text to be highlighted (selected). When
you set the resource, if end pos is -1 or beyond the end of the
string, it’s set to the last character position of the widget’s text.
The doit member is always set to 1.
When getting...
The value is an address of a PtTextControl t pointer. The
start pos and end pos members hold the currently highlighted

640 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtText

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

C type Pt type Default
char Scalar 1

The width, in pixels, of the cursor.

Pt ARG TEXT FLAGS

C type Pt type Default
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).

September 20, 2005 Chapter 2 ¯ Widgets 641

PtText  2005, QNX Software Systems

Pt TEXT AUTO HIGHLIGHT

Highlight the text when the widget is given focus.
Default is off.

Pt ARG TEXT HIGHLIGHT BACKGROUND COLOR

C type Pt type Default
PgColor t Scalar Pt DEFAULT COLOR

The background color for highlighting. If this is

Pt DEFAULT COLOR, the default background color is used.

Pt ARG TEXT HIGHLIGHT TEXT COLOR

C type Pt type Default
PgColor t Scalar Pt DEFAULT COLOR

The text color for highlighting. If this is Pt DEFAULT COLOR, the

default text color is used.

Pt ARG TEXT SUBSTRING

C type Pt type Default
See below Complex See below

This resource can be used to get or set a substring of the widget’s text.
It’s a complex resource, so it needs special handling:

When setting...
The value is a pointer to an instance of a PtTextControl t
structure that defines which characters are to be deleted and
which are to be inserted. The following members are used:
¯ start pos — the beginning of the range to delete, or -1 if no
text is being deleted.

642 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtText

¯ end pos — the end of the range to delete, or -1 if no text is

being deleted.
¯ 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...
The value is an address of a pointer to 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 len isn’t used when setting or getting this resource.

Pt CB MODIFY NOTIFY / Pt CB TEXT CHANGED

C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that the widget invokes after the value of the text
string changes.

☞ It doesn’t matter which name you use for this resource.

If the widget has the Pt CALLBACKS ACTIVE bit set in its

Pt ARG FLAGS resource, this callback is also invoked when the text
is changed by a call to PtSetResources() or to a text widget function
such as PtTextModifyText().
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB MODIFY NOTIFY

September 20, 2005 Chapter 2 ¯ Widgets 643

PtText  2005, QNX Software Systems

reason subtype
0 (not used).

cbdata A pointer to a PtTextCallback t structure that

contains at least 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 the right of the first character, and
so on.
char *text; The text string.
int length; The length of the text string (not
including the NULL).

These callbacks should return Pt CONTINUE.

Pt CB MODIFY VERIFY
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that the widget invokes before the value of the text
string changes. To alter the input to the widget, you can modify the
members of the callback structure.
If the widget has the Pt CALLBACKS ACTIVE bit set in its
Pt ARG FLAGS resource, this callback is also invoked when the text
is changed by a call to PtSetResources() or to a text widget function
such as PtTextModifyText().
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB MODIFY VERIFY

644 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtText

reason subtype
0 (not used).

cbdata A pointer to a PtTextCallback t structure that

contains at least the following members:

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 the right of the first
character, and so on.
int new insert; Where the cursor will be after the
changes are applied.
char *text; The text to be inserted at cur insert.
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().

These callbacks should return Pt CONTINUE.

September 20, 2005 Chapter 2 ¯ Widgets 645

PtText  2005, QNX Software Systems

Pt CB MOTION NOTIFY
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that the widget invokes after the cursor is

repositioned.
If the widget has the Pt CALLBACKS ACTIVE bit set in its
Pt ARG FLAGS resource, this callback is also invoked when the
cursor is repositioned by a call to PtSetResources().
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB MOTION NOTIFY

reason subtype
0 (not used).

cbdata A pointer to a PtTextCallback t structure.

Pt CB MOTION VERIFY
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that the widget invokes before the cursor is

repositioned. Using this callback resource, you can modify or even
disallow cursor repositioning.
If the widget has the Pt CALLBACKS ACTIVE bit set in its
Pt ARG FLAGS resource, this callback is also invoked when the
cursor is repositioned by a call to PtSetResources().
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

646 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtText

reason Pt CB MOTION VERIFY

reason subtype
0 (not used).
cbdata A pointer to a PtTextCallback t structure that
contains at least the following members:

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; 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.

These callbacks should return Pt CONTINUE.

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.

September 20, 2005 Chapter 2 ¯ Widgets 647

PtText  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG ACCEL KEY PtLabel Not used by this class.
Pt ARG AREA PtWidget
Pt ARG BALLOON COLOR PtLabel
Pt ARG BALLOON FILL COLOR PtLabel
Pt ARG BALLOON POSITION PtLabel
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget Ph CURSOR INSERT
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic Pg GRAY
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget |=Pt SET|
Pt HIGHLIGHTED|
Pt GETS FOCUS
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG HORIZONTAL ALIGNMENT PtLabel
Pt ARG LABEL BALLOON PtLabel

continued. . .

648 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtText

Resource Inherited from Default override

Pt ARG LABEL DATA PtLabel Not used by this class.
Pt ARG LABEL FLAGS PtLabel &=˜Pt LABEL SELECT SHIFT
Pt ARG LABEL TYPE PtLabel Not used by this class.
Pt ARG LINE SPACING PtLabel Not used by this class.
Pt ARG MARGIN BOTTOM PtLabel
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN LEFT PtLabel
Pt ARG MARGIN RIGHT PtLabel
Pt ARG MARGIN TOP PtLabel
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Pt RESIZE Y AS REQUIRED|
Pt RESIZE Y INITIAL
Pt ARG TEXT FONT PtLabel
Pt ARG TEXT STRING PtLabel
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
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 USER DATA PtWidget
Pt ARG VERTICAL ALIGNMENT PtLabel Pt CENTER
Pt CB ACTIVATE PtBasic See below.
Pt CB ARM PtBasic

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 649

PtText  2005, QNX Software Systems

Resource Inherited from Default override

Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic See below.
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic See below.
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB UNREALIZED 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 contains at least the following
members:

reason Pt CB ACTIVATE

reason subtype
Indicates why the callback was invoked:
¯ 0 — the user clicked on the widget and it has
Pt SELECTABLE set in its Pt ARG FLAGS.
¯ Pt EDIT ACTIVATE — the user pressed Enter in the
text field.
¯ Pt CHANGE ACTIVATE — the text was modified, the
widget lost focus, and Pt CHANGE ACTIVATE is set in
the widget’s Pt ARG TEXT FLAGS.

650 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems 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
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 the cursor is to the left of the first
character, 1 to the right of the first character, and so on.
¯ char *text — the text string.
¯ int length — the length of the text string (not
including the \0).

These callbacks should return Pt CONTINUE.

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 PtCallbackInfo t structure that
contains at least the following members:

reason The name of the callback resource (for example,

Pt CB GOT FOCUS) that caused this callback to be
invoked.
reason subtype
0 (not used).

cbdata A pointer 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 the cursor is to the left of the first
character, 1 to the right of the first character, and so on.

September 20, 2005 Chapter 2 ¯ Widgets 651

PtText  2005, QNX Software Systems

¯ char *text — the text string.

¯ int length — the length of the text string (not
including the \0).

These callbacks should return Pt CONTINUE.

Convenience functions:
The PtText 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:

PtTextCallback t, PtTextControl t,
PtTextControlInfo t
Information passed to PtText callbacks

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.

652 Chapter 2 ¯ Widgets September 20, 2005

 PtTextCallback t,
 2005, QNX Software Systems
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

September 20, 2005 Chapter 2 ¯ Widgets 653

PtTextCallback t, PtTextControl t,
PtTextControlInfo t  2005, QNX Software Systems

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

654 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTextGetSelection()
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
Interrupt handler No
Signal handler No
Thread No

See also:
PtText, PtTextSetSelection()

September 20, 2005 Chapter 2 ¯ Widgets 655

PtTextModifyText()  2005, QNX Software Systems
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:

656 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTextModifyText()

¯ 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 will invoke its
Pt CB MODIFY NOTIFY / Pt CB TEXT CHANGED callbacks, if
any.

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
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 657

PtTextSetSelection()  2005, QNX Software Systems
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 the user moves the text cursor (via arrow keys or a mouse click),
the range is deselected nondestructively.

¯ If the user performs an action that would modify the widget’s text
in any way, the range is deleted and replaced by the user’s 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.

658 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTextSetSelection()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtText, PtTextGetSelection()

September 20, 2005 Chapter 2 ¯ Widgets 659

PtTimer  2005, QNX Software Systems
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. The time period is given in milliseconds. This widget is
intended to provide a non-accurate, resourceless time base for the
application. Setting the Pt ARG TIMER INITIAL resource to 0 or
unrealizing the widget disables the timer.

☞ 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.

New resources:

Resource C type Pt type Default

Pt ARG TIMER INITIAL long Scalar 0

continued. . .

660 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTimer

Resource C type Pt type Default

Pt ARG TIMER REPEAT long Scalar 0
Pt CB TIMER ACTIVATE PtCallback t * Link NULL

Pt ARG TIMER INITIAL

C type Pt type Default
long Scalar 0

Time in milliseconds before the first timer callback is activated.

Pt ARG TIMER REPEAT

C type Pt type Default
long Scalar 0

Time in milliseconds for the repeat rate of the timer once the initial
time period has expired.

Pt CB TIMER ACTIVATE
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that the widget invokes when the timer has expired.

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.

September 20, 2005 Chapter 2 ¯ Widgets 661

PtTimer  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG AREA PtWidget Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER 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 DATA PtWidget
Pt ARG DIM PtWidget Not used by this class.
Pt ARG EFLAGS PtWidget Not used by this class.
Pt ARG FLAGS PtWidget
Pt ARG HELP TOPIC 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 USER DATA PtWidget
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB HOTKEY PtWidget
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB UNREALIZED PtWidget

662 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtToggleButton
A toggle switch that’s either off or on

Class hierarchy:
PtWidget → PtBasic → PtLabel → 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.

Unset: Set:
Pt_ONE_OF_MANY Pt_ONE_OF_MANY

Pt_N_OF_MANY Pt_N_OF_MANY

Pt_ROUND Pt_ROUND

Pt_RADIO Pt_RADIO
Pt_TICK Pt_TICK

Pt_CHECK Pt_CHECK

Various button styles supported by PtToggleButton.

Creating toggle buttons

Like PtButton pushbuttons, toggle buttons inherit resources from
the PtLabel class. Therefore, you specify the label for toggle buttons
the same way you do for label and button widget classes.

September 20, 2005 Chapter 2 ¯ Widgets 663

PtToggleButton  2005, QNX Software Systems

A toggle button is displayed as a button with its label beside it. The
button is either set or unset. Normally the button will appear recessed
when it’s set. You can control this appearance with the
Pt ARG SET COLOR resource, which specifies the fill color for the
button’s interior when the button is set. This resource is ignored if the
value of the Pt ARG SET FILL resource isn’t set to Pt TRUE.
To determine whether or not the button is set, check the:

¯ Pt SET bit in the Pt ARG FLAGS resource

¯ callback data passed to the Pt CB ACTIVATE callbacks — see

PtBasic.

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 ) ;

PtSetArg (&argt[0], Pt ARG TEXT STRING,

"Button 2", 0 ) ;
button2 = PtCreateWidget (PtToggleButton, group,
1, argt ) ;

PtSetArg (&argt[0], Pt ARG TEXT STRING,

664 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtToggleButton

"Button 3", 0 ) ;
button3 = PtCreateWidget (PtToggleButton, group,
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:

Resource C type Pt type Default

Pt ARG INDICATOR COLOR PgColor t Scalar Pg GRAY
Pt ARG INDICATOR DEPTH unsigned short Scalar 2
Pt ARG INDICATOR HEIGHT unsigned short Scalar See below
Pt ARG INDICATOR TYPE unsigned char Scalar Pt N OF MANY
Pt ARG INDICATOR WIDTH unsigned short Scalar See below

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 665

PtToggleButton  2005, QNX Software Systems

Resource C type Pt type Default

Pt ARG SET COLOR PgColor t Scalar PgGray(170)
Pt ARG SET FILL unsigned char Scalar Pt TRUE
Pt ARG SPACING unsigned short Scalar 4

Pt ARG INDICATOR COLOR

C type Pt type Default
PgColor t Scalar Pg GRAY

The default fill color for the toggle button’s indicator.

Pt ARG INDICATOR DEPTH

C type Pt type Default
unsigned short Scalar 2

The border width, in pixels, of the indicator box.

Pt ARG INDICATOR HEIGHT

C type Pt type Default
unsigned short Scalar See below

The height of the indicator box. By default, the height is determined

by the font size.

Pt ARG INDICATOR TYPE

C type Pt type Default
unsigned char Scalar Pt N OF MANY

Determines how the indicator is drawn. Possible values:

666 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtToggleButton

¯ Pt ONE OF MANY — a diamond-shaped toggle indicator.

¯ Pt N OF MANY — a square-shaped toggle indicator.

¯ Pt ROUND — a round toggle indicator.

¯ Pt RADIO — a radio-button-shaped toggle indicator.

¯ Pt TICK — a square indicator with a tick mark in it.

¯ Pt CHECK — a square indicator with an X in it.

Pt ARG INDICATOR WIDTH

C type Pt type Default
unsigned short Scalar See below

The width of the indicator box. By default, the width is determined by

the font size.

Pt ARG SET COLOR

C type Pt type Default
PgColor t Scalar PgGray(170)

The background color used when the button is set (pressed in).

Pt ARG SET FILL

C type Pt type Default
unsigned char Scalar Pt TRUE

Indicates whether or not Pt ARG SET COLOR will be used. Possible

values:

¯ Pt TRUE — use the value of Pt ARG SET COLOR.

¯ Pt FALSE — ignore the value of Pt ARG SET COLOR.

September 20, 2005 Chapter 2 ¯ Widgets 667

PtToggleButton  2005, QNX Software Systems

Pt ARG SPACING
C type Pt type Default
unsigned short Scalar 4

The distance in pixels between the toggle indicator and the text label.

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 ACCEL KEY PtLabel
Pt ARG AREA PtWidget
Pt ARG BALLOON COLOR PtLabel
Pt ARG BALLOON FILL COLOR PtLabel
Pt ARG BALLOON POSITION PtLabel
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget 0
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget

continued. . .

668 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtToggleButton

Resource Inherited from Default override

Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget |=Pt SELECTABLE|
Pt TOGGLE
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG HORIZONTAL ALIGNMENT PtLabel
Pt ARG LABEL BALLOON PtLabel
Pt ARG LABEL DATA PtLabel
Pt ARG LABEL FLAGS PtLabel
Pt ARG LABEL TYPE PtLabel
Pt ARG LINE SPACING PtLabel
Pt ARG MARGIN BOTTOM PtLabel
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN LEFT PtLabel
Pt ARG MARGIN RIGHT PtLabel
Pt ARG MARGIN TOP PtLabel
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget
Pt ARG TEXT FONT PtLabel
Pt ARG TEXT STRING PtLabel
Pt ARG TOP BORDER COLOR PtBasic

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 669

PtToggleButton  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG TRANS PATTERN PtBasic
Pt ARG UNDERLINE TYPE PtLabel
Pt ARG UNDERLINE1 PtLabel
Pt ARG UNDERLINE2 PtLabel
Pt ARG USER DATA PtWidget
Pt ARG VERTICAL ALIGNMENT PtLabel
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB UNREALIZED PtWidget

670 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTree
A tree of items that collapse and expand as requested

Class hierarchy:
PtWidget → PtBasic → PtContainer → PtCompound →
PtGenList → PtGenTree → PtTree

PhAB icon:

Public header:
<photon/PtTree.h>

Description:
The PtTree widget displays a tree of items that collapse or expand
according to the user’s selections. PtTree assumes that each tree
item contains two images and a string.

September 20, 2005 Chapter 2 ¯ Widgets 671

PtTree  2005, QNX Software Systems

Photon microGUI
Building Custom Widgets
Installation & Configuration
About This Guide
Basic Installation
Configuring Photon
Photon Utilities
Photon Applications
Troubleshooting
Library Reference
Programmer’s Guide
User’s Guide
Widget Reference
QNX 4.23

The Photon Helpviewer uses a PtTree widget to give you quick access to
documentation.

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 inherited Pt ARG LIST COLUMN POS resource.

With both methods, the Tab character is used in the item strings as a
column separator.

672 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTree

☞ 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.

The array of all available images is actually stored within the widget’s
Pt ARG TREE IMAGES resource, and the items contain only indexes
into this array. The item structure, PtTreeItem t, also contains a
“user data” pointer that isn’t used by the widget. Note that there are
some functions that free items. None of these functions attempts to
free the user data.
The items should be allocated using the PtTreeAllocItem() function.
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. The tree widget passed to PtTreeAllocItem() must be the
same widget that the item will be added to. The PtTree widget will
free all its items automatically when it’s destroyed.
Use PtTreeAddFirst() and PtTreeAddAfter() to build a tree. For
example, suppose you wanted to build the following tree:

Item 1
Item 2
Item 2a
Item 3

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 = PtTreeAllocItem(tree wgt,text,-1,-1);

September 20, 2005 Chapter 2 ¯ Widgets 673

PtTree  2005, QNX Software Systems

PtTreeAddFirst(tree wgt,item,NULL);
brother = item;

/* Add "Item 2" as root item after "Item 1" */

text = "Item 2";

item = PtTreeAllocItem(tree wgt,text,-1,-1);
PtTreeAddAfter(tree wgt,item,brother);
brother = item;

/* Add "Item 2a" as first child of "Item 2" */

text = "Item 2a";

item = PtTreeAllocItem(tree wgt,text,-1,-1);
PtTreeAddFirst(tree wgt,item,brother);

/* Add "Item 3" as root item after "Item 2" */

text = "Item 3";

item = PtTreeAllocItem(tree wgt,text,-1,-1);
PtTreeAddAfter(tree wgt,item,brother);

New resources:

Resource C type Pt type Default

Pt ARG TREE BALLOON PtTreeBalloonF t * 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 SELECTION PtCallback t * Link NULL
Pt CB TREE STATE PtCallback t * Link NULL

Pt ARG TREE BALLOON

674 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTree

C type Pt type Default

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 Its parent window.

area A PhArea t structure that covers the item. The

area->pos member is relative to the parent window.

column The position of the column the pointer is on.

item The item the pointer is on.

coln The index of the column the pointer is on.

font The widget’s Pt ARG LIST FONT resource.

The default function does this:

return
PtGenListCreateTextBalloon(
widget, parent,
PtGenListSetColumnBalloon ( area, column ),
item->string, coln, font);

September 20, 2005 Chapter 2 ¯ Widgets 675

PtTree  2005, QNX Software Systems

Pt ARG TREE IMAGES

C type Pt type Default
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:

Ph RELEASE IMAGE | Ph RELEASE PALETTE |

Ph RELEASE TRANSPARENCY MASK | Ph RELEASE GHOST BITMAP

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.

Pt ARG TREE IMGMASK

C type Pt type Default
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:

Pt LIST ITEM SELECTED

The item is selected.
Pt LIST ITEM CURRENT
The item is the current item.

676 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTree

Pt TREE ITEM EXPANDABLE

The item can be expanded.
Pt TREE ITEM EXPANDED
The branches of this item are currently displayed.

Pt CB TREE SELECTION
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks invoked when an item is selected from the tree.

Each callback is passed a PtCallbackInfo t structure that
contains at least the 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

event The event that triggered this callback.

cbdata This points to a PtTreeCallback t structure that

contains at least the following members:

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 the item the
user clicked on. If the selection mode

September 20, 2005 Chapter 2 ¯ Widgets 677

PtTree  2005, QNX Software Systems

is set to Pt RANGE MODE, item is 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).

These callbacks should return Pt CONTINUE.

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
C type Pt type Default
PtCallback t * Link NULL

Defines the state callbacks. Each callback is passed a

PtCallbackInfo t structure that contains at least the following
members:

reason Pt CB TREE STATE

678 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTree

reason subtype
Pt TREE COLLAPSING or Pt TREE EXPANDING.

event The event that triggered this callback.

cbdata This points to a PtTreeCallback t structure that

contains at least the following members:

unsigned sel mode;

The current selection mode
(Pt ARG SELECTION MODE).
PtTreeItem t *item;
The item that’s being collapsed or
expanded.
int expand; If reason subtype is
Pt TREE EXPANDING, this may be
assigned a nonzero value to suppress
expansion.

These callbacks should return Pt CONTINUE.

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 PtContainer
Pt ARG ANCHOR OFFSETS PtContainer
Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 679

PtTree  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG BALLOON COLOR PtGenList
Pt ARG BALLOON FILL COLOR PtGenList
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG LIST COLUMN ATTR PtGenList
Pt ARG LIST COLUMN POS PtGenList
Pt ARG LIST FLAGS PtGenList
Pt ARG LIST FONT PtGenList
Pt ARG LIST ITEM COUNT PtGenList
Pt ARG LIST SB RES PtGenList

continued. . .

680 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTree

Resource Inherited from Default override

Pt ARG LIST SCROLL RATE PtGenList
Pt ARG LIST SEL COUNT PtGenList
Pt ARG LIST TOTAL HEIGHT PtGenList
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget
Pt ARG SCROLLBAR WIDTH PtGenList
Pt ARG SELECTION FILL COLOR PtGenList
Pt ARG SELECTION MODE PtGenList
Pt ARG SELECTION TEXT COLOR PtGenList
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TOP ITEM POS PtGenList
Pt ARG TRANS PATTERN PtBasic
Pt ARG TREE FLAGS PtGenTree See below.
Pt ARG USER DATA PtWidget
Pt ARG VISIBLE COUNT PtGenList
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer Not used by this class.
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 681

PtTree  2005, QNX Software Systems

Resource Inherited from Default override

Pt CB FILTER PtContainer
Pt CB GEN TREE INPUT PtGenTree
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
Pt CB SCROLL MOVE PtGenList
Pt CB UNREALIZED 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:

682 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTree

Neither ON_IMAGE ON_TREE

The Pt ARG TREE FLAGS for a PtTree widget.

Convenience functions:
The PtTree widget defines the following 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 adds 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

September 20, 2005 Chapter 2 ¯ Widgets 683

PtTree  2005, QNX Software Systems

PtTreeExpand() Expand an expandable item

PtTreeFreeAllItems()
Unlink and free all items
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

PtTreeItemIndex()
Calculate the index of the specified item
PtTreeModifyItem()
Change item resources
PtTreeRemoveChildren()
Unlink the children of the specified item
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

684 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTree

PtTreeSetSelIndexes()
Set the selection indexes

PtTreeShow() Set the position so that the specified item is visible

PtTreeUnselect()
Unselect the specified item

PtTreeUnselectNonBrothers()
Unselect all items that aren’t siblings of the
specified item

September 20, 2005 Chapter 2 ¯ Widgets 685

PtTreeAddAfter()  2005, QNX Software Systems
Insert an item after the specified item

Synopsis:
void 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().

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.

686 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTreeAddAfter()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtTree, PtTreeAddFirst(), PtTreeAllocItem(), PtTreeFreeAllItems(),
PtTreeFreeItems(), PtTreeItem t

September 20, 2005 Chapter 2 ¯ Widgets 687

PtTreeAddFirst()  2005, QNX Software Systems
Add a root item to a tree list

Synopsis:
void PtTreeAddFirst( PtWidget t *tree,
PtTreeItem t *item,
PtTreeItem t *parent );

Description:
This function adds a list of trees linked with the brother member of
the PtTreeItem t structure.
The parent argument identifies the parent item for the added items.
The new items will be 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().

The parent argument may also be NULL, in which case the item will
be added at the root level of the tree before any existing items at the
root level.
This function may be called with a NULL tree argument, as long as
parent points to an item that isn’t attached to any tree widget.

688 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTreeAddFirst()

The PtTreeAddFirst() function automatically sets the

Pt TREE ITEM EXPANDABLE flag in the parent item.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtTree, PtTreeAddAfter(), PtTreeAllocItem(), PtTreeFreeAllItems(),
PtTreeFreeItems(), PtTreeItem t, PtTreeRootItem(),

September 20, 2005 Chapter 2 ¯ Widgets 689

PtTreeAddImages()  2005, QNX Software Systems
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.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtTree
PhImage t in the Photon Library Reference

690 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems 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:
A pointer to the buffer.

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

September 20, 2005 Chapter 2 ¯ Widgets 691

PtTreeAllItems()  2005, QNX Software Systems

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtTree, PtTreeGetCurrent(), PtTreeGetSelIndexes(),
PtTreeItem t, PtTreeSelectedItems(), PtTreeSetSelIndexes()

692 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTreeAllocItem()
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 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 image must be already present in the widget: if an index given to
the PtTreeAllocItem() function isn’t smaller than the current image
count, it’s changed to -1. A value of -1 means “no image.”

☞ Use the PtTreeAddFirst() and PtTreeAddAfter() functions to add the

new item to a tree structure.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 693

PtTreeAllocItem()  2005, QNX Software Systems

See also:
PtTree, PtTreeAddAfter(), PtTreeAddFirst(), PtTreeAddImages(),
PtTreeFreeAllItems(), PtTreeFreeItems(), PtTreeItem t,
PtTreeModifyItem()

694 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTreeClearSelection()
Clear the selection

Synopsis:
void PtTreeClearSelection( PtWidget t *widget );

Description:
This function clears the selection.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtTree, PtTreeGetCurrent(), PtTreeGetSelIndexes(), PtTreeGoto(),
PtTreeSelect(), PtTreeSelectedItems(), PtTreeSetSelIndexes(),
PtTreeUnselect(), PtTreeUnselectNonBrothers()

September 20, 2005 Chapter 2 ¯ Widgets 695

PtTreeCollapse()  2005, QNX Software Systems
Collapse an expandable item

Synopsis:
void 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 be NULL if the item
doesn’t belong to any tree.
If tree != NULL, the Pt CB TREE STATE callback will be invoked.
The event argument is the event that will be passed to the callback.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtTree, PtTreeExpand(), PtTreeGetCurrent(), PtTreeGoto(),
PtTreeItem t, PtTreeShow()

696 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems 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 be NULL if the item doesn’t
belong to any tree.
If tree isn’t NULL, the Pt CB TREE STATE callback is invoked. The
event argument is the event that will be passed to the callback. If the
callback function prevents the expansion by setting the expand field in
the callback structure to a nonzero value, the function will return that
value. A value of 0 means successful expansion.

Returns:
A value of zero on successful expansion, otherwise the value that
prevented the expansion.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 697

PtTreeExpand()  2005, QNX Software Systems

See also:
PtTree, PtTreeCollapse(), PtTreeGetCurrent(), PtTreeGoto(),
PtTreeItem t, PtTreeShow()

698 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTreeFreeAllItems()
Unlink and free all items

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
deleted.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtTree, PtTreeAllocItem(), PtTreeFreeItems(),
PtTreeRemoveChildren(), PtTreeRemoveItem(), PtTreeRemoveList()

September 20, 2005 Chapter 2 ¯ Widgets 699

PtTreeFreeItems()  2005, QNX Software Systems
Free an unlinked item

Synopsis:
void PtTreeFreeItems( PtTreeItem t *item );

Description:
This function frees the subtrees (the item together with its brothers
and their children). The function assumes that the items don’t belong
to any tree — use the PtTreeRemoveChildren(), PtTreeRemoveItem(),
or PtTreeRemoveList() function to remove the subtree from a tree
widget before freeing the subtrees.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtTree, PtTreeAllocItem(), PtTreeFreeAllItems(),
PtTreeRemoveChildren(), PtTreeRemoveItem(), PtTreeRemoveList()

700 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTreeGetCurrent()
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.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtTree, PtTreeClearSelection(), PtTreeGetSelIndexes(),
PtTreeGoto(), PtTreeItem t, PtTreeRootItem(), PtTreeSelect(),
PtTreeSelectedItems(), PtTreeSetSelIndexes(), PtTreeShow(),
PtTreeUnselect(), PtTreeUnselectNonBrothers()

September 20, 2005 Chapter 2 ¯ Widgets 701

PtTreeGetSelIndexes()  2005, QNX Software Systems
Fill a buffer with indexes

Synopsis:
unsigned short *PtTreeGetSelIndexes(
PtWidget t *widget,
unsigned short *buffer );

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.

¯ 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.

☞ Items that belong to collapsed subtrees aren’t included in the buffer.

Returns:
A pointer to the buffer.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

702 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTreeGetSelIndexes()

See also:
PtTree, PtTreeClearSelection(), PtTreeGetCurrent(), PtTreeGoto(),
PtTreeItem t, PtTreeRootItem(), PtTreeSelect(),
PtTreeSelectedItems(), PtTreeSetSelIndexes(), PtTreeShow(),
PtTreeUnselect(), PtTreeUnselectNonBrothers()

September 20, 2005 Chapter 2 ¯ Widgets 703

PtTreeGoto()  2005, QNX Software Systems
Set the current item

Synopsis:
int PtTreeGoto( PtWidget t *list,
PtTreeItem t *item );

Description:
This function sets the current item and (if necessary) the current
position so that the new current item is visible. 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
Interrupt handler No
Signal handler No
Thread No

See also:
PtTree, PtTreeClearSelection(), PtTreeGetCurrent(), PtTreeGoto(),
PtTreeItem t, PtTreeRootItem(), PtTreeSelect(),
PtTreeSelectedItems(), PtTreeSetSelIndexes(), PtTreeShow(),
PtTreeUnselect(), PtTreeUnselectNonBrothers()

704 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTreeItem t
PtTree item structure

Synopsis:
typedef struct Pt tree item {
PtGenTreeItem t gen;
short set img, unset img;
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.

set img 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.

unset img The index of the image displayed when the item isn’t
set.

data A pointer to arbitrary user data. This isn’t used by the

widget.

string The string to be displayed for the item. This field is

allocated the appropriate amount of space when it’s set.

Use PtTreeAllocItem() to allocate and fill in this structure.

September 20, 2005 Chapter 2 ¯ Widgets 705

PtTreeItem t  2005, QNX Software Systems

Classification:
Photon

See also:
PtGenList, PtGenTree, PtGenTreeItem t, PtTree,
PtTreeAddAfter(), PtTreeAddFirst(), PtTreeAllItems(),
PtTreeAllocItem(), PtTreeFreeItems(), PtTreeGetCurrent(),
PtTreeItemIndex(), PtTreeModifyItem(), PtTreeRemoveItem(),
PtTreeRootItem(), PtTreeSelectedItems()

706 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTreeItemIndex()
Calculate the index of the given item within the list

Synopsis:
int PtTreeItemIndex( const PtTreeWidget t *list,
const PtTreeItem t *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 item, or 0 if it belongs to a collapsed subtree.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtTree, PtTreeAllItems(), PtTreeGetSelIndexes(), PtTreeItem t

September 20, 2005 Chapter 2 ¯ Widgets 707

PtTreeModifyItem()  2005, QNX Software Systems
Change item resources

Synopsis:
PtTreeItem t *PtTreeModifyItem( PtWidget t *tree,
PtTreeItem t *item,
const char *string,
short sel img,
short unsel img );

Description:
This function changes item resources.

¯ The item’s string is copied from string. If string==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.

☞ Don’t use this function to modify an item that hasn’t yet been added
to the tree.

Returns:
The new address of the item.

☞ This address may differ from the old one if the new string is longer.

Classification:
Photon

708 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTreeModifyItem()

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtTree, PtTreeAllocItem(), PtTreeItem t, PtTreeItemIndex()

September 20, 2005 Chapter 2 ¯ Widgets 709

PtTreeRemoveChildren()  2005, QNX Software Systems
Unlink the children of the specified item

Synopsis:
PtTreeItem t *PtTreeRemoveChildren(
PtTreeItem t *item );

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 won’t collapse the item. If the children are visible,
NULL will be returned. 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.

710 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTreeRemoveChildren()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtTree, PtTreeAddAfter(), PtTreeAddFirst(), PtTreeAllocItem(),
PtTreeFreeAllItems(), PtTreeFreeItems(), PtTreeItem t,
PtTreeModifyItem(), PtTreeRemoveItem(), PtTreeRemoveList()

September 20, 2005 Chapter 2 ¯ Widgets 711

PtTreeRemoveItem()  2005, QNX Software Systems
Unlink an item

Synopsis:
void PtTreeRemoveItem( PtWidget t *tree,
PtTreeItem t *item );

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

712 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTreeRemoveItem()

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtTree, PtTreeAddAfter(), PtTreeAddFirst(), PtTreeAllocItem(),
PtTreeFreeAllItems(), PtTreeFreeItems(), PtTreeItem t,
PtTreeModifyItem(), PtTreeRemoveChildren(), PtTreeRemoveList()

September 20, 2005 Chapter 2 ¯ Widgets 713

PtTreeRemoveList()  2005, QNX Software Systems
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
parent 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 be NULL if the items don’t belong to any tree.
Note that if tree==NULL and first has no parent but has a previous
brother, then the function won’t be able to find the previous brother
and won’t be able unlink first from its previous brother.

Classification:
Photon

Safety
Interrupt handler No
continued. . .

714 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTreeRemoveList()

Safety
Signal handler No
Thread No

See also:
PtTree, PtTreeAddAfter(), PtTreeAddFirst(), PtTreeAllocItem(),
PtTreeFreeAllItems(), PtTreeFreeItems(), PtTreeItem t,
PtTreeModifyItem(), PtTreeRemoveChildren(), PtTreeRemoveItem()

September 20, 2005 Chapter 2 ¯ Widgets 715

PtTreeRootItem()  2005, QNX Software Systems
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
Interrupt handler No
Signal handler No
Thread No

See also:
PtTree, PtTreeAddAfter(), PtTreeAddFirst(), PtTreeAllItems(),
PtTreeFreeAllItems(), PtTreeFreeItems(), PtTreeGetCurrent(),
PtTreeGoto(), PtTreeItem t, PtTreeSelect(), PtTreeShow()

716 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTreeSelect()
Select the specified item

Synopsis:
void PtTreeSelect( PtWidget t *widget,
PtTreeItem t *item );

Description:
This function selects the given item.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtTree, PtTreeClearSelection(), PtTreeGetCurrent(),
PtTreeGetSelIndexes(), PtTreeGoto(), PtTreeItem t,
PtTreeSelectedItems(), PtTreeSetSelIndexes(), PtTreeUnselect(),
PtTreeUnselectNonBrothers()

September 20, 2005 Chapter 2 ¯ Widgets 717

PtTreeSelectedItems()  2005, QNX Software Systems
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:

¯ 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.

☞ Items that belong to collapsed subtrees aren’t included in the buffer.

Returns:
A pointer to the buffer.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

718 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTreeSelectedItems()

See also:
PtTree, PtTreeClearSelection(), PtTreeGetCurrent(),
PtTreeGetSelIndexes(), PtTreeGoto(), PtTreeItem t,
PtTreeSelect(), PtTreeSetSelIndexes(), PtTreeUnselect(),
PtTreeUnselectNonBrothers()

September 20, 2005 Chapter 2 ¯ Widgets 719

PtTreeSetSelIndexes()  2005, QNX Software Systems
Set the selection indexes

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.
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 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
Interrupt handler No
Signal handler No
Thread No

See also:
PtTree, PtTreeClearSelection(), PtTreeGetCurrent(),
PtTreeGetSelIndexes(), PtTreeGoto(), PtTreeItem t,
PtTreeSelect(), PtTreeSelectedItems(), PtTreeUnselect(),
PtTreeUnselectNonBrothers()

720 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTreeShow()
Set the position so that the specified item is visible

Synopsis:
int PtTreeShow( PtWidget t *widget,
PtTreeItem t *item );

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 allows you
to do something like this:

PtTreeShow( widget, PtTreeGetCurrent(widget) );

without checking whether PtTreeGetCurrent() returned a NULL value.

Returns:
0 Success.

Nonzero item belongs to a collapsed subtree, and a callback

function prevented the subtree from being expanded

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 721

PtTreeShow()  2005, QNX Software Systems

See also:
PtTree, PtTreeClearSelection(), PtTreeCollapse(), PtTreeExpand(),
PtTreeGetCurrent(), PtTreeGetSelIndexes(), PtTreeGoto(),
PtTreeItem t, PtTreeRootItem(), PtTreeSelect()

722 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTreeUnselect()
Unselect the given item

Synopsis:
void PtTreeUnselect( PtWidget t *widget,
PtTreeItem t *item );

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
Interrupt handler No
Signal handler No
Thread No

See also:
PtTree, PtTreeClearSelection(), PtTreeGetCurrent(),
PtTreeGetSelIndexes(), PtTreeGoto(), PtTreeItem t,
PtTreeSelect(), PtTreeSelectedItems(), PtTreeSetSelIndexes(),
PtTreeUnselectNonBrothers()

September 20, 2005 Chapter 2 ¯ Widgets 723

PtTreeUnselectNonBrothers()  2005, QNX Software Systems
Unselect all items that aren’t siblings of the specified item

Synopsis:
void PtTreeUnselectNonBrothers(
PtWidget t *widget,
PtTreeItem t *item );

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.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtTree, PtTreeClearSelection(), PtTreeGetCurrent(),
PtTreeGetSelIndexes(), PtTreeGoto(), PtTreeItem t,
PtTreeSelect(), PtTreeSelectedItems(), PtTreeSetSelIndexes(),
PtTreeUnselect()

724 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTty
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.
0 33 //61/*/Dev32.pty.423D 20r RECV 0 12k 16k
1 40 //61/bin/Fsys.aha4scsi 22r RECV 0 73k 5193k
0 48 //61/bin/Csc2 21r RECV 0 49k 5877k
0 59 //135/bin/sh 24r RECV 0 16k 53k
0 67 //135/*/bin/Pq.m64 10o RECV 0 16k 20k
2 106 //135/*/bin/Photon 29o RECV 0 36k 6688k
2 109 //135/*/bin/phfont 10o WAIT -1 16k 28k
4 4035 //135/*/crt/m64bios.ms 10o REPLY 20 34k 45k
$

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. The Pt ARG TTY INPUT resource can also
be used 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

September 20, 2005 Chapter 2 ¯ Widgets 725

PtTty  2005, QNX Software Systems

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.

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 have to
open a device (by setting Pt ARG TTY FD, Pt ARG TTY PATH, or
Pt ARG TTY PSEUDO) before you can spawn a program on the
device (by setting Pt ARG TTY CMD or Pt ARG TTY ARGV).

☞ 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 resouces are order-dependent even though

they’re not action resources:

¯ Pt ARG TERM PROTOCOL

¯ Pt ARG TTY FDSET

¯ Pt ARG TTY FLAGS (Pt TTY SETENV and Pt TTY ARGV0)

¯ Pt ARG TTY SPAWN OPTIONS

726 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTty

Since the widget looks at the current value of those 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 "//0/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 FD, 0, 0 );
PtGetResources( ABW tty, 1, &arg );
if ( arg.value == -1 )
PtTerminalPuts( "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( "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.

September 20, 2005 Chapter 2 ¯ Widgets 727

PtTty  2005, QNX Software Systems

New resources:

Resource C type Pt type Default

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 FD 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 NULL
Pt ARG TTY INPUT WRITTEN unsigned short Scalar 0
(read-
only)
Pt ARG TTY MFD int Scalar -1
(read-
only)
Pt ARG TTY PATH char * String NULL
Pt ARG TTY PID pid t Scalar 0

continued. . .

728 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTty

Resource C type Pt type Default

Pt ARG TTY PRI int Scalar -1
Pt ARG TTY PSEUDO char * String NULL
Pt ARG TTY SPAWN OPTIONS PtSpawnOptions t const * Pointer NULL
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)

C type Pt type Default
char ** Pointer

When this resource is being set, 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 allows to 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.

September 20, 2005 Chapter 2 ¯ Widgets 729

PtTty  2005, QNX Software Systems

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

C type Pt type Default
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 this resource is
set, both the address and the length of a buffer must be given. The
widget then uses the given buffer. Several widgets may share a
common buffer, provided that none of them attaches a callback that
could cause a recursive invocation of the PtTerminalPut() function.

Pt ARG TTY BUFLEN

C type Pt type Default
unsigned short Scalar 1024

The length of the buffer used by the widget for reading data from the
device. If this resource is set, the widget allocates a buffer.

Pt ARG TTY CMD (write-only)

C type Pt type Default
char * String

When this resource is being set, 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.

730 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTty

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

C type Pt type Default
PtTerminalRowCol t Struct 0, 0

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)

C type Pt type Default
int Scalar 0

The exit status of the process spawned on the device. The value can
be examined using the POSIX macros described in the C Library
Reference, under waitpid(). The value is valid only after the child
process has terminated.

September 20, 2005 Chapter 2 ¯ Widgets 731

PtTty  2005, QNX Software Systems

Pt ARG TTY FD
C type Pt type Default
int Scalar -1

When this resource is set, the widget attaches itself to the given file
descriptor. The descriptor must be a character device open in a mode
that allows reading. Using a value of -1 forces the widget to detach
from any device it’s attached to.
When this resource is read, the current file descriptor is returned. If
the widget isn’t attached to any device, -1 is returned.

Pt ARG TTY FDSET

C type Pt type Default
unsigned short Scalar 7

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

C type Pt type Default
unsigned short Flag See below

The possible flags are as follows:

¯ Pt TTY DEVRESIZE — when the terminal’s size changes, the

device is resized.

732 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTty

¯ 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

C type Pt type Default
char *, unsigned short Array NULL

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.
The Pt ARG TTY INPUT WRITTEN resource can be used to find out
how many bytes the widget managed to read.

September 20, 2005 Chapter 2 ¯ Widgets 733

PtTty  2005, QNX Software Systems

Pt ARG TTY INPUT WRITTEN (read-only)

C type Pt type Default
unsigned short Scalar 0

The number of characters successfully written by the

Pt ARG TTY INPUT resource.

Pt ARG TTY MFD (read-only)

C type Pt type Default
int Scalar -1

The current “master” file descriptor. It’s equal to the Pt ARG TTY FD
resource unless the device has been opened using the
Pt ARG TTY PSEUDO resource, in which case this is the descriptor
of the “master” size of the pty.

Pt ARG TTY PATH

C type Pt type Default
char * String NULL

When this resource is set, the widget opens the given pathname for
reading and writing and attaches itself to the open device. The
pathname must be a character device.
The descriptor is greater than 2 and has the FD CLOEXEC flag set.
When this resource is read, the pathname of the current device is
returned. If the widget isn’t attached to any device or was attached
using the Pt ARG TTY FD resource, NULL is returned.

Pt ARG TTY PID

734 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTty

C type Pt type Default

pid t Scalar 0

Zero or the process ID of the process that has been spawned on the
device. The only value to which this resource can be explicitly set 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

C type Pt type Default
int Scalar -1

Priority of Photon pulses attached to the device — see

PtAppAddFdPri() in the Photon Library Reference.

Pt ARG TTY PSEUDO

C type Pt type Default
char * String NULL

When this resource is set, the widget attempts to find an unused

pseudo-tty device and attach to it. The resource value is used as a
prefix to which a string similar to /ttyp0 is appended. If a NULL is
given, //0/dev is used instead. If an empty string "" is given, /dev
is assumed and thus the default network root rather than the local
node is used. The application can also choose an explicit prefix or
scan a configuration-dependent prefix list.
If a pseudo tty has been opened in this way, the widget uses the
“master” end of the tty, but when reading the Pt ARG TTY FD or
Pt ARG TTY PATH resources, information about the “slave” end is
returned. The Pt ARG TTY PSEUDO resource can be read to obtain
the “master” device pathname.

September 20, 2005 Chapter 2 ¯ Widgets 735

PtTty  2005, QNX Software Systems

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 PROTOCOL resource. 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 greater than 2 and have the
FD CLOEXEC flag set.

Pt ARG TTY SPAWN OPTIONS

C type Pt type Default
PtSpawnOptions t const * Pointer NULL

A pointer to a PtSpawnOptions t structure that’s used for

spawning the child process.
If this resource is left as NULL, default values in

extern const PtSpawnOptions t PtTtyDefaultSpawnOptions

are used. For more information about this structure, see PtSpawn() in
the Photon Library Reference.

Pt CB TTY DEVSIZE
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks invoked when a resize event is received from the

device (and before the terminal widget is resized according to the new
size).
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason The name of the callback resource (Pt CB TTY DEVSIZE)

that caused this callback to be invoked.

736 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTty

event NULL

cbdata A pointer to a PtTerminalSizeChange t structure

that has at least following members:

PtTerminalRowCol t old size;

Previous size of the device.
PtTerminalRowCol t new size;
Current size.

The PtTerminalRowCol t structure contains the

following members:
¯ short r
¯ short c

These callbacks should return Pt CONTINUE.

Pt CB TTY OUTPUT
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks invoked when any output from the device is

received (and before the output is passed to the terminal widget)
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason The name of the callback resource (Pt CB TTY OUTPUT)

that caused this callback to be invoked.

event NULL

cbdata A pointer to a PtTtyOutput t structure that has at least

following members defined:

int length; The number of characters received.

September 20, 2005 Chapter 2 ¯ Widgets 737

PtTty  2005, QNX Software Systems

const char * buffer;

A pointer to buffer containing the
characters.

These callbacks should return Pt CONTINUE.

Pt CB TTY TERMINATED
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks invoked after the child process has terminated.

Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason The name of the callback resource

(Pt CB TTY TERMINATED) that caused this callback to
be invoked.

event NULL

cbdata A pointer to an int containing the

Pt ARG TTY EXIT STATUS resource.

These callbacks should return Pt CONTINUE.

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 PtContainer

continued. . .

738 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTty

Resource Inherited from Default override

Pt ARG ANCHOR OFFSETS PtContainer
Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Ph BAUD SLOW (see
below)
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic
Pt ARG CONTAINER FLAGS PtContainer
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget
Pt ARG TERM APP PtTerminal

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 739

PtTty  2005, QNX Software Systems

Resource Inherited from Default override

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 PROTOCOL PtTerminal

continued. . .

740 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTty

Resource Inherited from Default override

Pt ARG TERM RESIZE FL PtTerminal
Pt ARG TERM RESIZE FUN PtTerminal
Pt ARG TERM RESIZE STR PtTerminal
Pt ARG TERM ROWS PtTerminal
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 ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 741

PtTty  2005, QNX Software Systems

Resource Inherited from Default override

Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
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
Pt CB UNREALIZED PtWidget

Pt ARG BANDWIDTH THRESHOLD

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 the
“Scrolling optimization” part of the “Description” section for
PtTerminal.

Convenience functions:
The PtTty widget defines the following convenience functions:

PtTtyShell() Return the default user’s shell.

742 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtTtyShell()
Return the user’s 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
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 743

PtUpDown  2005, QNX Software Systems
Vertical or horizontal increment/decrement buttons

Class hierarchy:
PtWidget → PtBasic → PtContainer → 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:

Resource C type Pt type Default

Pt ARG UPDOWN ARM DATA BOTTOM void * Pointer NULL

continued. . .

744 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtUpDown

Resource C type Pt type Default

Pt ARG UPDOWN ARM DATA LEFT void * Pointer NULL
Pt ARG UPDOWN ARM DATA RIGHT void * Pointer NULL
Pt ARG UPDOWN ARM DATA TOP void * Pointer NULL
Pt ARG UPDOWN BOTTOM BORDER COLOR PgColor t Scalar Pg DGRAY
Pt ARG UPDOWN DATA BOTTOM void * Pointer NULL
Pt ARG UPDOWN DATA LEFT void * Pointer NULL
Pt ARG UPDOWN DATA RIGHT void * Pointer NULL
Pt ARG UPDOWN DATA TOP void * Pointer NULL
Pt ARG UPDOWN FILL COLOR PgColor t Scalar Pg GRAY
Pt ARG UPDOWN FLAGS long Scalar See
below
Pt ARG UPDOWN HIGHLIGHT ROUND unsigned short Scalar 0
Pt ARG UPDOWN MARGIN HEIGHT unsigned short Scalar 0
Pt ARG UPDOWN MARGIN WIDTH unsigned short Scalar 0
Pt ARG UPDOWN ORIENTATION int Scalar Pt VERTICAL
Pt ARG UPDOWN SPACING unsigned Scalar 0
Pt ARG UPDOWN TOP BORDER COLOR PgColor t Scalar Pg WHITE

Pt ARG UPDOWN ARM DATA BOTTOM,

Pt ARG UPDOWN ARM DATA LEFT,
Pt ARG UPDOWN ARM DATA RIGHT,
Pt ARG UPDOWN ARM DATA TOP
C type Pt type Default
void * Pointer NULL

An image (of type PhImage t — see the Photon Library Reference)

to display for the buttons when they’re pressed in.

September 20, 2005 Chapter 2 ¯ Widgets 745

PtUpDown  2005, QNX Software Systems

☞ 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.

Pt ARG UPDOWN BOTTOM BORDER COLOR

C type Pt type Default
PgColor t Scalar Pg DGRAY

The color of the outermost bottom and right borders.

Pt ARG UPDOWN DATA BOTTOM, Pt ARG UPDOWN DATA LEFT,

Pt ARG UPDOWN DATA RIGHT,
Pt ARG UPDOWN DATA TOP
C type Pt type Default
void * Pointer NULL

Images (of type PhImage t — see the Photon Library Reference) to

display for the buttons. The default images are arrows.

☞ Set the image’s flags as described for

Pt ARG UPDOWN ARM DATA BOTTOM.

Pt ARG UPDOWN FILL COLOR

C type Pt type Default
PgColor t Scalar Pg GRAY

746 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtUpDown

The background color.

Pt ARG UPDOWN FLAGS

C type Pt type Default
long Scalar Pt HIGHLIGHTED | Pt GETS FOCUS

These flags specify the appearance of the outermost borders:

Pt HIGHLIGHTED
Highlight the widget with a beveled or etched
rectangle. The appearance of the rectangle depends
on the Pt ARG BORDER WIDTH,
Pt ARG TOP BORDER COLOR, and
Pt ARG BOT BORDER COLOR resources.
Pt ETCH HIGHLIGHT
Highlight the widget with an etched-line style
(normally, a beveled rectangle is used).

Pt CLIP HIGHLIGHT
Clip the corners of the rectangle that highlights the
widget.

Pt BLOCKED Prevent the widget and all its non-window-class

children from interacting with Photon events.

Pt MENUABLE Make the widget respond to right-mouse-button

clicks (i.e. enable PtBasic’s Pt CB MENU
callback.
Pt GETS FOCUS
Allow the widget to be granted focus when
appropriate.

September 20, 2005 Chapter 2 ¯ Widgets 747

PtUpDown  2005, QNX Software Systems

☞ Use the Pt ARG FLAGS resource to change the appearance of the

inner borders. Only the following flags are supported for this widget:

¯ Pt HIGHLIGHTED

¯ Pt ETCH HIGHLIGHT

¯ Pt CLIP HIGHLIGHT

Pt ARG UPDOWN HIGHLIGHT ROUND

C type Pt type Default
unsigned short Scalar 0

The roundness of the outermost borders.

Pt ARG UPDOWN MARGIN HEIGHT

C type Pt type Default
unsigned short Scalar 0

The amount of vertical space between the outermost border and the
inner images.

Pt ARG UPDOWN MARGIN WIDTH

C type Pt type Default
unsigned short Scalar 0

The amount of horizontal space between the outermost border and the
inner images.

748 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtUpDown

Pt ARG UPDOWN ORIENTATION

C type Pt type Default
int Scalar Pt VERTICAL

The direction the arrows are pointing:

¯ Pt VERTICAL

¯ Pt HORIZONTAL

Pt ARG UPDOWN SPACING

C type Pt type Default
unsigned Scalar 0

The distance, in pixels, between the buttons.

Pt ARG UPDOWN TOP BORDER COLOR

C type Pt type Default
PgColor t Scalar Pg WHITE

The color of the outermost top and left borders.

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 PtContainer Not used by this class.

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 749

PtUpDown  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG ANCHOR OFFSETS PtContainer Not used by this class.
Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG ARM COLOR PtButton
Pt ARG ARM FILL PtButton
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic Not used by this class.
Pt ARG CONTAINER FLAGS PtContainer Not used by this class.
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic Not used by this class.
Pt ARG FILL PATTERN PtBasic Not used by this class.
Pt ARG FLAGS PtWidget See below.
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic Not used by this class.
Pt ARG MARGIN WIDTH PtBasic Not used by this class.
Pt ARG POS PtWidget

continued. . .

750 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtUpDown

Resource Inherited from Default override

Pt ARG RESIZE FLAGS PtWidget
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic See below.
Pt CB ARM PtBasic See below.
Pt CB BALLOONS PtContainer Not used by this class.
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic See below.
Pt CB FILTER PtContainer Not used by this class.
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer Not used by this class.
Pt CB UNREALIZED PtWidget

Pt ARG FLAGS
Only the following flags are supported for this widget:
¯ Pt HIGHLIGHTED
¯ Pt ETCH HIGHLIGHT

September 20, 2005 Chapter 2 ¯ Widgets 751

PtUpDown  2005, QNX Software Systems

¯ Pt CLIP HIGHLIGHT
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:

ulong t reason;
ulong t 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

752 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtWidget
Superclass for all widgets

Class hierarchy:
PtWidget

PhAB icon:
None — not normally instantiated.

Public header:
<photon/PtWidget.h>

Description:
PtWidget is the fundamental superclass. All widgets belong to a
subclass of PtWidget.

New resources:

Resource C type Pt type Default

Pt ARG AREA PhArea t Struct 0,0,0,0
Pt ARG BITMAP CURSOR PhCursorDef t * Alloc NULL
Pt ARG BORDER WIDTH unsigned short Scalar 2
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 short Flag 0
Pt ARG FLAGS long Flag 0
Pt ARG HELP TOPIC char * String NULL

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 753

PtWidget  2005, QNX Software Systems

Resource C type Pt type Default

Pt ARG POS PhPoint t Struct 0,0
Pt ARG RESIZE FLAGS long Flag 0
Pt ARG USER DATA void * Alloc NULL
Pt CB BLOCKED PtCallback t * Link NULL
Pt CB DESTROYED PtCallback t * Link NULL
Pt CB HOTKEY PtHotkeyCallback t * Link NULL
Pt CB RAW PtRawCallback t * Link NULL
Pt CB REALIZED PtCallback t * Link NULL
Pt CB UNREALIZED PtCallback t * Link NULL

Pt ARG AREA
C type Pt type Default
PhArea t Struct 0,0,0,0

The x, y, height, and width values for the widget. This resource isn’t
displayed in PhAB; PhAB sets it automatically when you move or
size the widget.

Pt ARG BITMAP CURSOR

C type Pt type Default
PhCursorDef t * Alloc NULL

Defines bitmaps for the cursor when the cursor type

(Pt ARG CURSOR TYPE) is set to Ph CURSOR BITMAP.
The PhCursorDef t structure is defined as follows:

typedef struct Ph cursor def {

PhRegionDataHdr t hdr;

754 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtWidget

PhPoint t size1;
PhPoint t offset1;
PgColor t color1;
char bytesperline1;
PhPoint t size2;
PhPoint t offset2;
PgColor t color2;
char bytesperline2;
char Spare[14];
char images[1];
} PhCursorDef t;

The members are:

hdr A pointer to the region data header, which is set

automatically by the widget. For information about
this structure, see PhRegionDataHdr t in the
Photon Library Reference.

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 bit planes.

bytesperline2 The number of bytes per line for the second bitmap
plane.

September 20, 2005 Chapter 2 ¯ Widgets 755

PtWidget  2005, QNX Software Systems

images The bitmap image data, as a series of

1-bit-per-pixel planes.

This resource can’t be edited in PhAB. You can draw the cursor as a
PtBitmap widget and have the application turn it into a
PhCursorDef t structure at runtime. For example:

PtArg t args[2];

ApDBase t *db = ApOpenDBase( ABM db );

ApBitmap t *ab = ApGetBitmapRes( bmpdb, "bitmap" );
unsigned len = sizeof(*d) + 2 * BMP SIZE;
PhCursorDef t *d = malloc( len );

memset( d, 0, sizeof(*d) );
d->size1.x = d->size2.x = BMP WIDTH;
d->size1.y = d->size2.y = BMP HEIGHT;
d->bytesperline1 = d->bytesperline2 = BMP BPL;
d->color1 = ab->colors[0];
d->color2 = ab->colors[1];
memcpy( d->images, ab->data[0], BMP SIZE );
memcpy( d->images + BMP SIZE, ab->data[1], BMP SIZE );
PtSetArg( &args[0], Pt ARG CURSOR TYPE, Ph CURSOR BITMAP , 0 );
PtSetArg( &args[2], Pt ARG BITMAP CURSOR, d, len );
PtSetResources( ABW base, 2, args );
free( d );

Pt ARG BORDER WIDTH

C type Pt type Default
unsigned short Scalar 2

The thickness of the widget’s border. This must not exceed 15 pixels.

Pt ARG CURSOR COLOR

C type Pt type Default
PgColor t Scalar Ph CURSOR DEFAULT COLOR

The color of the pointer when it’s inside the widget.

756 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtWidget

Pt ARG CURSOR TYPE

C type Pt type Default
unsigned short Scalar Ph CURSOR INHERIT

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 <photon/PhCursor.h>.

Pt ARG DATA
C type Pt type Default
void * Alloc NULL

This resource is used internally by the Photon libraries as well as by

compound widgets. It isn’t displayed in PhAB. For more information,
see the Building Custom Widgets guide.

September 20, 2005 Chapter 2 ¯ Widgets 757

PtWidget  2005, QNX Software Systems

☞ If you want to store arbitrary data in a widget, use its

Pt ARG USER DATA resource.

Pt ARG DIM
C type Pt type Default
PhDim t Struct 0,0

The height and width values for the widget.

This resource isn’t displayed in PhAB; PhAB sets it automatically
when you size the widget.

Pt ARG EFLAGS
C type Pt type Default
unsigned short Flag 0

Extended flags inherited by all widgets:

Pt CONSUME EVENTS
The widget will consume any event encountered whether or not
an action was performed as a result of that event.
Pt INTERNAL HELP
Help information for the widget is displayed in a balloon, not in
the Helpviewer. See the chapter on Context-Sensitive Help in
the Photon Programmer’s Guide.
Pt DAMAGE PARENT
If the widget is damaged for any reason, propagate the damage
to its parent.

758 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtWidget

Pt ARG FLAGS
C type Pt type Default
long Flag 0

Common flags used by all widgets. Except for those indicated as

read-only, these flags are all read/write. Possible values:

Pt CALLBACKS ACTIVE
For a few widgets, setting resources will cause
relevant callbacks to be invoked if this bit is set.
Otherwise callbacks are not invoked as a result of
setting resources. If a callback relies on 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 ALL BUTTONS
Indicates that any mouse button can activate the
widget. Default is the left button only.
Pt AUTOHIGHLIGHT
Causes the widget to highlight and get focus when
the cursor enters its extent, and to unhighlight and
lose focus when the cursor leaves.

Pt BLOCKED Prevents the widget and all its non-window-class

children from interacting with Photon events.
Pt CLEAR (read-only)
Prevents the widget’s brothers-in-front from
intersecting with its extent.
Pt CLIP HIGHLIGHT
Clips the corners of the highlighting rectangle.

September 20, 2005 Chapter 2 ¯ Widgets 759

PtWidget  2005, QNX Software Systems

Pt DAMAGED (read-only)
Indicates that the widget requires repair.
Pt DAMAGE FAMILY (read-only)
Indicates that the widget and all its children will be
repaired.
Pt DELAY REALIZE
Prevents the widget from becoming realized unless
it’s explicitly realized with PtRealizeWidget().
Pt DESTROYED (read-only)
The widget has been marked for destruction.
Pt ETCH HIGHLIGHT
Highlights the widget with an etched-line style
(normally, a beveled rectangle is used).
Pt FREE MEMORY
Indicates whether or not the widget may free
memory associated with any of its pointers. For
example, if this flag is set for a PtLabel widget
with an image structure and you destroy the
widget, the library frees the image memory as well
as the label’s image structure.

Using this bit might cause problems if, for example, more than one
☞ widget uses the same image. It’s better to use the image’s flags to
indicate which of the image’s allocated members should be freed. For
more information, see PhImage t in the Photon Library Reference.
Pt FOCUS RENDER
Draws a dotted line around the widget when it gets
focus.
Pt GETS FOCUS
Allows the widget to be granted focus when
appropriate.

760 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtWidget

Pt GHOST The widget is dimmed. 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
Highlights the widget with a beveled or etched
rectangle. The appearance of the rectangle depends
on the Pt ARG BORDER WIDTH,
Pt ARG TOP BORDER COLOR, and
Pt ARG BOT BORDER COLOR resources.
Pt IN FLUX (read-only)
Indicates that a call to PtContainerHold() has been
made on the widget.

Pt MENUABLE The widget will respond to right mouse clicks (i.e.

enables PtBasic’s Pt CB MENU callback.
Pt MENU BUTTON
Indicates that the widget is a menu item.

Pt OBSCURED (read-only)
Indicates that the widget is completely covered by
one other widget, or it’s completely beyond its
parent container’s canvas.

Pt OPAQUE (read-only)
Indicates that this widget completely obscures
everything behind it and inside its extent.

Pt PROCREATED (read-only)
Indicates that the widget is a procreated child of a
compound widget.
Pt REALIZED (read-only)
Indicates that the widget is realized.

September 20, 2005 Chapter 2 ¯ Widgets 761

PtWidget  2005, QNX Software Systems

Pt REALIZING (read-only)
Indicates that the widget is in the process of being
realized.

Pt REGION Forces the widget to have a region.

Pt SELECTABLE
Indicates that the user can select (repeat, arm,
disarm, and activate) this widget. The widget will
usually provide visual feedback when selected.
Pt SELECT NOREDRAW
Indicates that the widget won’t change its
appearance when set or unset. This is meaningful
only when the widget is selectable.

Pt SET Indicates that the widget is in a “set” state.

Generally, this indicates that the widget has been
selected.

Pt TOGGLE Indicates that pressing the mouse button on this

widget will cause it to toggle between being set
and unset. Normally, selectable widgets act as push
buttons — they become set when you press the
mouse button and unset when you release the
button.
Pt WIDGET REBUILD (read-only)
Indicates that the widget will be rebuilt
(re-realized) when the widget engine is finished
applying resource changes.
Pt WIDGET RESIZE (read-only)
Indicates that the widget will be resized when the
widget engine is finished applying resource
changes.

The default setting of this resource is 0; that is, no flags have been set.

762 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtWidget

Pt ARG HELP TOPIC

C type Pt type Default
char * String NULL

The meaning of this resource depends on the Pt ARG EFLAGS

extended flags:

¯ 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 PxHelp*() functions and the chapter on
Context-Sensitive Help in the Photon Programmer’s Guide.

Pt ARG POS
C type Pt type Default
PhPoint t Struct 0,0

Defines the x and y values for the widget. This resource isn’t
displayed in PhAB; PhAB sets it automatically when you move the
widget.

Pt ARG RESIZE FLAGS

C type Pt type Default
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

September 20, 2005 Chapter 2 ¯ Widgets 763

PtWidget  2005, QNX Software Systems

¯ 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 will grow or shrink to honor
that policy. If the policy is ...ALWAYS, the widget will resize itself to
fit its data — the dimensions specified via Pt ARG DIM or
Pt ARG AREA won’t apply. If the policy is ...AS REQUIRED, the
widget will resize itself to fit its data only if its current canvas size is
inadequate to contain that data. In other words, it will grow, but won’t
shrink, to fit its data.

764 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtWidget

If the widget has the ...INITIAL bit set, the resize policy will be
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 the Photon Programmer’s Guide.

Pt ARG USER DATA

C type Pt type Default
void * Alloc NULL

Attaches an arbitrary user-defined data structure to the widget.

Pt CB BLOCKED
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that the widget invokes whenever it must ignore an

event due to being blocked.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB BLOCKED

event The event that was blocked for this widget.

cbdata NULL

These callbacks should return Pt CONTINUE.

Pt CB DESTROYED

September 20, 2005 Chapter 2 ¯ Widgets 765

PtWidget  2005, QNX Software Systems

C type Pt type Default

PtCallback t * Link NULL

The callbacks that the widget invokes when it is destroyed. You’ll find
this resource useful for cleaning up variables or memory associated
with the widget.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB DESTROYED

event An event structure filled with NULLs.

cbdata A value of NULL.

These callbacks should return Pt CONTINUE.

Pt CB HOTKEY
C type Pt type Default
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 will call the function specified in that structure. If a function
isn’t specified, the widget invokes its Pt CB ACTIVATE callback list.

☞ 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
Programmer’s Guide.

766 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtWidget

Each callback is passed a PtCallbackInfo t structure that

contains at least the following members:

reason Pt CB HOTKEY

event A pointer to an PhEvent t structure.

cbdata A pointer to a PtHotkeyCallback t structure that has

at least the following members:

unsigned short key sym cap;

short flags;
unsigned long key mods;
PtWidget t *widget;
void * data;
void * (event f )( PtWidget t *,
void *, PtCallbackInfo t *);

where:

key sym cap The key cap of the invoking keystroke.

flags Can contain the following:
Pt HOTKEY SYM
Interpret key sym cap as a key sym;
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
hot keys.
key mods The key modifiers active for the invoking
keystroke.
widget A pointer to the widget that attached the
callback.

September 20, 2005 Chapter 2 ¯ Widgets 767

PtWidget  2005, QNX Software Systems

data A pointer to user-defined data associated

with the callback, also passed as the
second parameter to the callback function.
event f If not NULL, a pointer to the function to
invoke. If NULL, the widget’s
Pt CB ACTIVATE callback is invoked.

These callbacks should return Pt CONTINUE.

Pt CB RAW
C type Pt type Default
PtRawCallback t * Link NULL

A list of raw callbacks that the widget invokes if the raw event it
receives matches the event mask provided in the PtRawCallback t
structure.

☞ These callbacks are invoked after the widget has processed the event,
and then only for events that the widget doesn’t consume. Contrast
this with the Pt CB FILTER resource defined by PtContainer.

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 “Manipulating event
handlers in your code” in the Creating Widgets in Application Code
chapter of the Photon Programmer’s Guide.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB RAW

event The raw Photon event that triggered this callback.

cbdata A value of NULL.

These callbacks should return Pt CONTINUE.

768 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtWidget

Pt CB REALIZED
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that the widget invokes whenever it is realized.

Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB REALIZED

event An event structure filled with NULLs.

cbdata A value of NULL.

These callbacks should return Pt CONTINUE.

Pt CB UNREALIZED
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks that the widget invokes whenever it is unrealized.

Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB UNREALIZED

event An event structure filled with NULLs.

cbdata A value of NULL.

These callbacks should return Pt CONTINUE.

September 20, 2005 Chapter 2 ¯ Widgets 769

PtWindow  2005, QNX Software Systems
An application window that’s managed by the Photon Window Manager

Class hierarchy:
PtWidget → PtBasic → PtContainer → PtWindow

PhAB icon:
None — use PhAB’s Window or Dialog module.

Public header:
<photon/PtWindow.h>

Description:
The PtWindow class provides an application window and a standard
appearance for all other windows. Windows are always managed by
the Photon Window Manager (the PtForwardWindowEvent() function
sends window events to the Window Manager).

Photon Image View er

File

A PtWindow widget.

770 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtWindow

☞ ¯ Use PhAB’s Window module instead of this widget. See “Window

modules” in the Working with Modules chapter of the Photon
Programmer’s Guide.

¯ A PtWindow widget is the top-level widget of the application. If

you try to use another class for the top-level widget, the behavior
will be undefined — you’ll likely get a fatal error.

¯ In addition to the sections below, see the Window Management

chapter of the Photon Programmer’s Guide.

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.

Setting the window’s icon

You can provide a window that will be displayed as the icon for the
window whenever the window is iconified. This is controlled by the
Pt ARG ICON WINDOW resource. Set the value of the resource to a
widget to be displayed as the icon window. If the widget doesn’t
belong to the PtIcon widget class or one of its subclasses, then the
behavior when the user iconifies the window is undefined.
If you don’t specify an icon window for the application, but you
create a widget of the class PtIcon as a child of the application
window, that widget will be used to display the icon for the
application. Otherwise, an icon window will be created for the
window automatically. The default icon window is a small beveled
square in the Taskbar.

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

September 20, 2005 Chapter 2 ¯ Widgets 771

PtWindow  2005, QNX Software Systems

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 set the string displayed in the window’s title bar with the
Pt ARG WINDOW TITLE resource. You should set the resource to
the string to be displayed.

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:

Element Bit
Border Ph WM RENDER BORDER
Resize handles Ph WM RENDER RESIZE
Title bar Ph WM RENDER TITLE
Window menu Ph WM RENDER MENU
Minimize button Ph WM RENDER MIN
Maximize Button Ph WM RENDER MAX
Close Button Ph WM RENDER CLOSE
Help Button Ph WM RENDER HELP

The Pt ARG WINDOW RENDER FLAGS resource also has either of

the following two bits set:

¯ Ph WM RENDER ASAPP

¯ Ph WM RENDER ASICON

772 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtWindow

The value of these bits determines whether the window is displayed as

an application window or an icon window. These windows differ in
the window management functions included in the window menu.
By default, the value of the Pt ARG WINDOW RENDER FLAGS
resource is set to the value of the manifest constant
Ph WM APP DEF RENDER. This displays the window as an
application window with a border, resize handles, a title bar, a
minimize button, a maximize button, a window menu, and an icon
representation.

Controlling window resizing

You can use the following four resources to control the minimum and
maximum sizes that the Window Manager will allow the user to resize
the window:

¯ Pt ARG MAX HEIGHT

¯ Pt ARG MAX WIDTH

¯ Pt ARG MIN HEIGHT

¯ Pt ARG MIN WIDTH

If these are set to 0, default values specified by the window manager

are used.

Enabling Window Manager functions

The Window Manager can provide many operations on a window.

You can control how the Window Manager operates on your windows
by setting the Pt ARG WINDOW MANAGED FLAGS resource on the
PtWindow widget.
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 allows the user to perform that operation. If a flag isn’t set,
the Window Manager disables the operation.

September 20, 2005 Chapter 2 ¯ Widgets 773

PtWindow  2005, QNX Software Systems

Each operation is identified by the name of the flag that

enables/disables it. Here are the operations the Window Manager lets
the user perform on a window:

Ph WM CLOSE Close the window. If the window is the main

window for the application, the application itself
is terminated.

Ph WM RESIZE Change the size of the window.

Ph WM MOVE Move the window to a new location.

Ph WM TOFRONT
Move the window to the front of the window
stacking order.

Ph WM TOBACK Move the window to the back of the window

stacking order.

Ph WM HIDE Minimize/hide the window. The window can be

restored from the Taskbar button.

Ph WM MAX Maximize the size of the window. The window is

resized to fit the entire screen.
Ph WM BACKDROP
Use the window as the backdrop for the
workspace.
Ph WM RESTORE
Restore the window to its state prior to an iconify
or maximize operation.

Ph WM FOCUS Give focus to the window.

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.

774 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtWindow

Ph WM TERMINATE
Terminate the application. This operation is used
for graceful shutdown of the windowing system.

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 callback for the window widget.
The window callback list belongs to the Pt CB WINDOW resource.
The callback data for this callback consists of a pointer to a window
event structure, PhWindowEvent t (described in the Photon Library
Reference).

Application icons
The PtIcon class provides an icon widget, a specialized form of
PtWindow widget. An icon is the same as a PtWindow widget in all
regards except for the following:

¯ rendering — the icon window is rendered as an icon (i.e.

Ph WM RENDER ASICON)

¯ icon representation — an icon widget may be automatically used

as the icon representation for its parent.

If the application window is iconified and doesn’t have an icon

representation specified, a search will be made for an icon widget
child to use as the icon representation.
Typically, icons are defined using a PtLabel widget with the
Pt IMAGE label flag set. The label widget also sets the
Pt ARG LABEL DATA resource to a PhImage t structure, which is

September 20, 2005 Chapter 2 ¯ Widgets 775

PtWindow  2005, QNX Software Systems

used to render the icon. For more information about the PhImage t
structure, see the Photon Library Reference.

☞ ¯ You don’t have to use PtLabel widgets for icons. They’re

mentioned here because they’re a convenient way to display
graphical images usually found in icons.

¯ 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.

There are two ways to associate the PtIcon widget with a window.
You can either:

¯ Create the PtIcon widget as a child widget to the window widget

Or:

¯ Create the PtIcon widget by itself and use the PtIcon instance
pointer as a resource value for the Pt ARG ICON WINDOW,
which you can set for the window at any time. You’ll also need to
set the Ph WM RENDER ASICON flag in the window’s render
flags.

If you create a PtWindow widget but don’t define a PtIcon widget

for it, then the PtWindow widget will automatically create two default
icons for you.
The default icon is a single label that matches the window’s title.
Unless the window’s title is short, the icon text will get clipped.
The default small icon is a 15¢15 3-D rectangle.
The following code shows how to create a window containing two
icons:
int n;

776 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtWindow

PtWidget t *window, *icon;

PhArea t area;
PtArg t args[6];

/* setup window resources */

/* ... */
PtSetArg( &args[n], Pt ARG WINDOW RENDER FLAGS,
Ph WM RENDER ASICON, Ph WM RENDER ASICON );
n++;
window = PtCreateWidget( PtWindow, NULL, n, args );

memset(&area, 0, sizeof(area));
area.size.w = 14;
area.size.h = 14;
PtSetArg( &args[0], Pt ARG DIM, &area.size, 0 );
PtSetArg( &args[1], Pt ARG FILL COLOR, Pg GREY, 0 );
icon = PtCreateWidget( PtIcon, window, 2, args );

/* widget is taskbar icon */

area.pos.x = 0;
area.pos.y = 0;
area.size.w = 14;
area.size.h = 14;
PtSetArg( &args[0], Pt ARG AREA, &area, 0 );
PtSetArg( &args[1], Pt ARG BORDER WIDTH, 1, 0);
PtSetArg( &args[2], Pt ARG TOP BORDER COLOR, Pg DGREY, 0 );
PtCreateWidget( PtButton, icon, 3, args );

PtRealizeWidget( window );

Layout and sizing

The window widget will position each of its children at the location
specified by their Pt ARG AREA or Pt ARG POS resources. This is
known as absolute positioning.
The size of the window widget is initially determined to be the
minimum size needed to contain all its children at their requested
locations, with a margin maintained around the children. This
calculation is performed when the window is realized.
Most applications will normally have a menu bar and a work area.
The menu bar should be a group widget with its right side anchored to
the right side of the main window. The work area may be the main
window itself, but you may want to place another widget such as a

September 20, 2005 Chapter 2 ¯ Widgets 777

PtWindow  2005, QNX Software Systems

scroll area beneath the menu bar. As with the menu bar, this widget
should have its right side anchored to the right side of the main
window. The bottom of the widget should also be anchored to the
bottom of the main window.
The geometry management issues of layout, sizing, and anchoring of
children are discussed in more detail in the Photon Programmer’s
Guide.

Creating subwindows
Some parts of the UI such as tool bars, 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 cannot 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:

Resource C type Pt type Default

Pt ARG ICON WINDOW PtWidget t Pointer See
below
Pt ARG MAX HEIGHT short Scalar 0
(See
below)
Pt ARG MAX WIDTH short Scalar 0
(See
below)

continued. . .

778 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtWindow

Resource C type Pt type Default

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 CURSOR OVERRIDE int Boolean Pt FALSE
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 short Flag See
below.
Pt ARG WINDOW NOTIFY FLAGS unsigned short Flag See
below.
Pt ARG WINDOW RENDER FLAGS unsigned short Flag See
below.
Pt ARG WINDOW STATE unsigned short 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

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 779

PtWindow  2005, QNX Software Systems

Resource C type Pt type Default

Pt CB WINDOW TRANSPORT PtCallback t * Link NULL

Pt ARG ICON WINDOW

C type Pt type Default
PtWidget t Pointer See below

The widget ID of the icon that the window is to display. If this

resource is NULL, the window will search its children for a PtIcon
widget; if none is found, a default icon is used.

Pt ARG MAX HEIGHT

C type Pt type Default
short Scalar 0 (See below)

The maximum height of the widget. If this is set to 0, the default

value specified by the window manager is used.

Pt ARG MAX WIDTH

C type Pt type Default
short Scalar 0 (See below)

The maximum width of the widget. If this is set to 0, the default value
specified by the window manager is used.

Pt ARG MIN HEIGHT

C type Pt type Default
short Scalar 0 (See below)

780 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtWindow

The minimum height of the widget. If this is set to 0, the default value
specified by the window manager is used.

Pt ARG MIN WIDTH

C type Pt type Default
short Scalar 0 (See below)

The minimum width of the widget. If this is set to 0, the default value
specified by the window manager is used.

Pt ARG WINDOW ACTIVE COLOR

C type Pt type Default
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 CURSOR OVERRIDE

C type Pt type Default
int Boolean Pt FALSE

Allows this window’s cursor to override the cursors of the window’s

children.

Pt ARG WINDOW FRONT WINDOW

C type Pt type Default
PhRid t Scalar 0

Specifies the region ID of the window that this window is to be be

positioned behind.

September 20, 2005 Chapter 2 ¯ Widgets 781

PtWindow  2005, QNX Software Systems

Pt ARG WINDOW HELP ROOT

C type Pt type Default
char * String NULL

Defines the root topic path for the window. For more information, see
the PxHelp*() functions in the Photon Library Reference and the
Context-Sensitive Help chapter of the Photon Programmer’s Guide.

Pt ARG WINDOW INACTIVE COLOR

C type Pt type Default
PgColor t Scalar Pg DEFAULT WM 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

C type Pt type Default
unsigned short 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

continued. . .

782 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtWindow

If you set this bit: the Window Manager:

Ph WM CONSWITCH Moves the window to keep it on the visible
display whenever the virtual Photon
console is switched
Ph WM FFRONT Allow the window to become force front
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 RESIZE Resizes the application
Ph WM RESTORE Restores the window after it has been
iconified, maximized, or hidden
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 combines some of these flags. For more information, see
<PhWm.h>.

Pt ARG WINDOW NOTIFY FLAGS

C type Pt type Default
unsigned short Flag Ph WM RESIZE|Ph WM CLOSE|
Ph WM HELP

Controls for which events the Pt CB WINDOW callbacks are invoked.

This resource doesn’t cause the window manager to perform actions

September 20, 2005 Chapter 2 ¯ Widgets 783

PtWindow  2005, QNX Software Systems

(for that, use Pt ARG WINDOW MANAGED FLAGS). You can set
any of the bits listed for Pt ARG WINDOW MANAGED FLAGS.

Pt ARG WINDOW RENDER FLAGS

C type Pt type Default
unsigned short 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 ASICON
Render it as an icon.

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 HELP
If the window has a title bar, include a help button.
Ph WM RENDER MAX
If the window has a title bar, include a maximize button.
Ph WM RENDER MIN
If the window has a title bar, include a minimize button.
Ph WM RENDER MENU
If the window has a title bar, include a menu button.

784 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtWindow

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 TITLE | \
Ph WM RENDER MENU | \
Ph WM RENDER MIN | \
Ph WM RENDER MAX )

Pt ARG WINDOW STATE

C type Pt type Default
unsigned short Flag Ph WM STATE ISFOCUS

Controls what state the window will appear in when it is opened. 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
Pt ARG WINDOW MANAGED FLAGS.
Ph WM STATE ISFRONT
Open the base window in front of the windows of all
applications. Child windows will open behind the last forced

September 20, 2005 Chapter 2 ¯ Widgets 785

PtWindow  2005, QNX Software Systems

front window in the family. See

Pt ARG WINDOW MANAGED FLAGS.
Ph WM STATE ISICONIFIED
Open the window and iconify it.

Ph WM STATE ISHIDDEN
Open as a normal window but don’t display it.

Ph WM STATE ISMAX
Open as a maximized window.
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 ISBLOCKED
Block input to the window.

☞ You can change the state by setting Pt ARG WINDOW STATE before
the window is realized. After it’s been realized, you’ll need to call
PtForwardWindowEvent() or PtForwardWindowTaskEvent().

Pt ARG WINDOW TITLE

C type Pt type Default
char * String "Untitled"

The string that the Window Manager displays in the title bar.

Pt ARG WINDOW TITLE COLOR

C type Pt type Default
PgColor t Scalar Pg DEFAULT WM COLOR

786 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtWindow

The color of the window’s title (i.e. the text). This overrides the color
specified by the window manager.

Pt CB WINDOW
C type Pt type Default
PtCallback t * Link NULL

The list of callbacks that the widget invokes when it receives an event
from the Window Manager. See Pt ARG WINDOW NOTIFY FLAGS.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB WINDOW

reason subtype
0 (not used).

event A pointer to the event that caused the callback to be

invoked.

cbdata A pointer to a PhWindowEvent t (described in the

Photon Library Reference).

These callbacks should return Pt CONTINUE.

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 Photon Programmer’s Guide.

Pt CB WINDOW CLOSING
C type Pt type Default
PtCallback t * Link NULL

The list of callbacks that the widget invokes when the window is
being closed. It’s invoked before the window’s region is removed.

September 20, 2005 Chapter 2 ¯ Widgets 787

PtWindow  2005, QNX Software Systems

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.

☞ 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.

Each callback is passed a PtCallbackInfo t structure that

contains at least the following members:

reason Pt CB WINDOW CLOSING

reason subtype
0 (not used).

event Not supplied.

cbdata Not supplied.

These callbacks should return Pt CONTINUE.

Pt CB WINDOW OPENING
C type Pt type Default
PtCallback t * Link NULL

The list of callbacks that the widget invokes 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.

788 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtWindow

☞ 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.

Each callback is passed a PtCallbackInfo t structure that

contains at least the following members:

reason Pt CB WINDOW OPENING

reason subtype
0 (not used)

event An empty event structure.

cbdata NULL

These callbacks should return Pt CONTINUE.

Pt CB WINDOW TRANSPORT
C type Pt type Default
PtCallback t * Link NULL

The list of callbacks that the widget invokes when the window is
being transported through a Jump Gate.
Each callback is passed a PtCallbackInfo t structure that
contains at least the following members:

reason Pt CB WINDOW TRANSPORT

reason subtype
Not used
event The Ph EV WM event that triggered this callback.

September 20, 2005 Chapter 2 ¯ Widgets 789

PtWindow  2005, QNX Software Systems

cbdata Internal use only

These callbacks should return Pt CONTINUE.

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.

☞ A window can’t have a border or margins, so the following inherited

resources aren’t supported:

¯ Pt ARG BORDER WIDTH

¯ Pt ARG BOT BORDER COLOR

¯ Pt ARG MARGIN HEIGHT

¯ Pt ARG MARGIN WIDTH

¯ Pt ARG TOP BORDER COLOR

Resource Inherited from Default override

Pt ARG ANCHOR FLAGS PtContainer Not used by this class.
Pt ARG ANCHOR OFFSETS PtContainer Not used by this class.
Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget Not used by this class.
Pt ARG BOT BORDER COLOR PtBasic Not used by this class.
Pt ARG COLOR PtBasic

continued. . .

790 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtWindow

Resource Inherited from Default override

Pt ARG CONTAINER FLAGS PtContainer
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS
Pt ARG FILL COLOR PtBasic
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
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 RESIZE FLAGS PtWidget |=Pt RESIZE XY AS REQUIRED
Pt ARG TOP BORDER COLOR PtBasic Not used by this class.
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BALLOONS PtContainer
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 791

PtWindow  2005, QNX Software Systems

Resource Inherited from Default override

Pt CB DISARM PtBasic
Pt CB FILTER PtContainer
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB RESIZE PtContainer
Pt CB UNREALIZED PtWidget

Convenience functions:
The PtWindow widget defines the following convenience functions:

PtWindowFocus()
Gives a window focus.
PtWindowGetState()
Returns the current state of a window.
PtWindowToBack()
Moves a window to the back of the workspace.

PtWindowToFront()
Brings a window to the front and gives it focus.

792 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtWindowFocus()
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
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 793

PtWindowFocus()  2005, QNX Software Systems

See also:
PtWindowToBack(), PtWindowToFront()
PtForwardWindowEvent() in the Photon Library Reference

794 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems 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 PtIcon widget, or the window wasn’t realized.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 795

PtWindowGetState()  2005, QNX Software Systems

Safety
Thread No

796 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems PtWindowToBack()
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:
PtWidget t *my window;

/* move my window to the back */

PtWindowToBack( my window );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 797

PtWindowToBack()  2005, QNX Software Systems

See also:
PtWindowFocus(), PtWindowToFront()
PtForwardWindowEvent(), PtWidgetToBack(), PtWidgetToFront() in
the Photon Library Reference

798 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems 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:
PtWidget t *my window;

/* bring my window to the front */

PtWindowToFront( my window );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Widgets 799

PtWindowToFront()  2005, QNX Software Systems

See also:
PtWindowToBack(), PtWindowFocus()
PtForwardWindowEvent(), PtWidgetToBack(), PtWidgetToFront() in
the Photon Library Reference

800 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems RtMeter
A realtime meter

Class hierarchy:
PtWidget → PtBasic → RtMeter

PhAB icon:

Public header:
<photon/realtime/RtMeter.h>

Description:
The RtMeter widget is drawn as a half circle with divisional ticks at
1/4, 1/2, and 3/4 of the arc.

100

An RtMeter widget.

The needle can be moved with the mouse, the keyboard or

programmatically:

With the mouse

A single mouse click moves the meter to the current mouse
position; mouse motion with a button held down causes the
needle to follow the mouse, through meter values.

With the keyboard

Two keys can be set up to move the needle:
¯ Rt ARG METER KEY LEFT to move to the left
¯ Rt ARG METER KEY RIGHT to move to the right

September 20, 2005 Chapter 2 ¯ Widgets 801

RtMeter  2005, QNX Software Systems

Programatically
The Rt ARG METER NEEDLE POSITION resource can be
used to set the needle position programmatically.

Up to 3 severity arcs can be drawn in colors to indicate different levels

of the meter:

¯ Arc 1 — Rt ARG METER MIN NEEDLE POSITION to

Rt ARG METER LEVEL1 POS

¯ Arc 2 — Rt ARG METER LEVEL1 POS to

Rt ARG METER LEVEL2 POS

¯ Arc 3 — Rt ARG METER LEVEL2 POS to

Rt 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 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(RtMeter, parent, 1, args)
...

Creating a 1-arc meter

To create a 1-arc meter that can be moved by clicking the mouse
buttons, has a minimum value of 0, has a maximum of 1000, and
notifies you when the user moves the needle:

802 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems RtMeter

1000

A one-arc RtMeter widget.

...
PhArea t area = { { 10, 10 }, { 200, 200 } };
PtCallback t cb[1] = { {moved cb, NULL} };

PtSetArg(&args[0], Pt ARG AREA, &area, 0);

PtSetArg(&args[1], Rt ARG METER MAX NEEDLE POSITION,
1000, 0);
PtSetArg(&args[2], Rt CB METER MOVED, &cb[1], 0);
PtCreateWidget(RtMeter, parent, 3, args)
...

int moved cb(PtWidget t *widget, void *data,

PtCallbackInfo t *info)
{
RtMeterCallback 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

To create 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

will move 0, 10, 20, ... when you press the up-arrow key):

September 20, 2005 Chapter 2 ¯ Widgets 803

RtMeter  2005, QNX Software Systems

...
PhArea t area = { { 10, 10 }, { 200, 200 } };
PtCallback t cb[1] = { {moved cb, NULL} };

PtSetArg(&args[0], Pt ARG AREA, &area, 0);

PtSetArg(&args[1], Rt ARG METER KEY LEFT, Pk Down, 0);
PtSetArg(&args[2], Rt ARG METER KEY RIGHT, Pk Up, 0);
PtSetArg(&args[3], Rt ARG METER INCREMENT, 10, 0);
PtSetArg(&args[4], Rt CB METER MOVED, &cb[1], 0);
PtCreateWidget( RtMeter, parent, 5, args );
...

int moved cb( PtWidget t *widget, void *data,

PtCallbackInfo t *info)
{
RtMeterCallback t *mydata;
mydata = info->cbdata;

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 RtMeter inside a PtDBContainer widget.

Full meter example

#include <stdio.h>
#include <Pt.h>
#include <photon/realtime/RtMeter.h>

PtWidget t *window, *meter, *quit, *sev lbl, *pos lbl;

// callback for meter moved

804 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems RtMeter

int meter cb( PtWidget t *widget, void *data,

PtCallbackInfo t *info)
{
RtMeterCallback t *mydata;
char pos[10], sev[5];
PtArg t args[2];

mydata = info->cbdata;
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);

return (Pt CONTINUE);

}

// callback for the quit button

int quit cb( PtWidget t *widget, void *data,
PtCallbackInfo t *info)
{
exit (EXIT SUCCESS);
return Pt CONTINUE;
}

void 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;

PtSetArg( &args[n++], Pt ARG WINDOW TITLE,

"RtMeter Demo", 0 );
PtSetArg( &args[n++], Pt ARG DIM, &win dim, 0 );
window = PtAppInit( NULL, &argc, argv, n, args );

// draw the meter with 3 arcs and a callback for meter moved
n = 0;
PtSetArg( &args[n++], Pt ARG AREA, &meter area, 0 );

September 20, 2005 Chapter 2 ¯ Widgets 805

RtMeter  2005, QNX Software Systems

PtSetArg( &args[n++], Rt ARG METER MAX NEEDLE POSITION,

1000, 0 );
PtSetArg( &args[n++], Rt ARG METER TEXT FONT, "helv12", 0 );
PtSetArg( &args[n++], Rt CB METER MOVED, &callbacks[0], 0 );

// If you don’t want your meter to be selectable, add

// the following:
//
// PtSetArg( &args[n++], Rt ARG METER FLAGS,
// RtM NON SELECTABLE, RtM NON SELECTABLE );

meter = PtCreateWidget( RtMeter, 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 BORDER 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 BORDER 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

806 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems RtMeter

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 );

PtRealizeWidget( window );

PtMainLoop();
}

New resources:

Resource C type Pt type Default

Rt ARG METER COLOR PgColor t Scalar Pg BLACK
Rt ARG METER FLAGS unsigned short Flag RtM SELECTABLE
Rt ARG METER FONT COLOR PgColor t Scalar Pg BLACK
Rt ARG METER INCREMENT int Scalar 5
Rt ARG METER KEY LEFT int Scalar Pk Left
Rt ARG METER KEY RIGHT int Scalar Pk Right
Rt ARG METER LEVEL1 COLOR PgColor t Scalar Pg GREEN
Rt ARG METER LEVEL1 POS short Scalar 50
Rt ARG METER LEVEL2 COLOR PgColor t Scalar Pg YELLOW
Rt ARG METER LEVEL2 POS short Scalar 75
Rt ARG METER LEVEL3 COLOR PgColor t Scalar Pg RED
Rt ARG METER MAX NEEDLE POSITION short Scalar 100
Rt ARG METER MIN NEEDLE POSITION short Scalar 0
Rt ARG METER NEEDLE COLOR PgColor t Scalar Pg WHITE

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 807

RtMeter  2005, QNX Software Systems

Resource C type Pt type Default

Rt ARG METER NEEDLE POSITION short Scalar 0
Rt ARG METER NUM SEVERITY LEVELS short Scalar 3
Rt ARG METER TEXT FONT char * String "helv10"
Rt CB METER MOVED PtCallback t * Link NULL

Rt ARG METER COLOR

C type Pt type Default
PgColor t Scalar Pg BLACK

The color for the center circle, outline of the meter, and divisional
ticks.

Rt ARG METER FLAGS

C type Pt type Default
unsigned short Flag RtM SELECTABLE

The valid bits are:

RtM NON SELECTABLE

Make the meter noninteractive.
RtM SELECTABLE
Make the meter interactive.
RtM NO TEXT
Don’t display the minimum and maximum text strings.

808 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems RtMeter

Rt ARG METER FONT COLOR

C type Pt type Default
PgColor t Scalar Pg BLACK

The font color for the minimum and maximum strings.

Rt ARG METER INCREMENT

C type Pt type Default
int Scalar 5

The increment used when the keyboard is used to move the meter’s
needle. Every press of the assigned keys will move the meter this
distance.

Rt ARG METER KEY LEFT

C type Pt type Default
int Scalar Pk Left

The key, as defined in <photon/PkKeyDef.h>, that’s to be used to

move the meter’s needle to the left. The default value is the left arrow,
Pk Left.

☞ Pt ARG FLAGS must have Pt GETS FOCUS set.

Rt ARG METER KEY RIGHT

C type Pt type Default
int Scalar Pk Right

The key, as defined in <photon/PkKeyDef.h>, that’s to be used to

move the meter’s needle to the right. The default value is the right
arrow, Pk Right.

September 20, 2005 Chapter 2 ¯ Widgets 809

RtMeter  2005, QNX Software Systems

☞ Pt ARG FLAGS must have Pt GETS FOCUS set.

Rt ARG METER LEVEL1 COLOR

C type Pt type Default
PgColor t Scalar Pg GREEN

The color of the first severity arc.

Rt ARG METER LEVEL1 POS

C type Pt type Default
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.

Rt ARG METER LEVEL2 COLOR

C type Pt type Default
PgColor t Scalar Pg YELLOW

The color of the second severity arc.

Rt ARG METER LEVEL2 POS

C type Pt type Default
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.

810 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems RtMeter

Rt ARG METER LEVEL3 COLOR

C type Pt type Default
PgColor t Scalar Pg RED

The color of the third severity arc.

Rt ARG METER MAX NEEDLE POSITION

C type Pt type Default
short Scalar 100

The maximum needle position; also the value drawn as the maximum.

Rt ARG METER MIN NEEDLE POSITION

C type Pt type Default
short Scalar 0

The minimum needle position; also the value drawn as the minimum.

Rt ARG METER NEEDLE COLOR

C type Pt type Default
PgColor t Scalar Pg WHITE

The color of the meter’s needle.

Rt ARG METER NEEDLE POSITION

C type Pt type Default
short Scalar 0

The current needle position, somewhere between the minimum and

maximum needle position. If the position is above the maximum, the

September 20, 2005 Chapter 2 ¯ Widgets 811

RtMeter  2005, QNX Software Systems

maximum is used; if the position is below the minimum, the

minimum is used.

Rt ARG METER NUM SEVERITY LEVELS

C type Pt type Default
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.

Rt ARG METER TEXT FONT

C type Pt type Default
char * String "helv10"

The font for the minimum and maximum strings.

Rt CB METER MOVED
C type Pt type Default
PtCallback t * Link NULL

A list of callbacks invoked when the needle is moved. Each callback

is passed a PtCallbackInfo t structure that contains at least the
following members:

reason The name of the callback resource

(Rt CB METER MOVED) that caused this callback to be
invoked.
reason subtype
Why the callback was invoked:
¯ Rt KEY MOVED — the needle moved due to a key
event; event is a Ph EV KEY event

812 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems RtMeter

¯ Rt MOUSE MOVED — the needle moved due to a

mouse event; event is a Ph EV PTR MOTION BUTTON
or Ph EV BUT PRESS event
¯ Rt ARG MOVED — the needle moved because
Rt ARG METER NEEDLE POSITION was set; event
is NULL
For more information, see PhEvent t in the Photon
Library Reference.

event The event that caused the callback. If event is NULL, then
the callback was invoked because the
Rt ARG METER NEEDLE POSITION resource was set.

cbdata A pointer to an RtMeterCallback 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.

These callbacks should return Pt CONTINUE.

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 AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 813

RtMeter  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic Not used by this class.
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic Pg TRANSPARENT
Pt ARG FILL PATTERN PtBasic Not used by this class.
Pt ARG FLAGS PtWidget Pt GETS FOCUS
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic 2
Pt ARG MARGIN WIDTH PtBasic 2
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY AS REQUIRED
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic

continued. . .

814 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems RtMeter

Resource Inherited from Default override

Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB UNREALIZED PtWidget

September 20, 2005 Chapter 2 ¯ Widgets 815

RtProgress  2005, QNX Software Systems
A realtime progress bar

Class hierarchy:
PtWidget → PtBasic → PtGauge → RtProgress

PhAB icon:

Public header:
<photon/realtime/RtProgress.h>

Description:
The RtProgress widget draws a progress bar and (optionally) the
corresponding value in front of it.

55%

An RtProgress 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.

New resources:

Resource C type Pt type Default

Rt ARG PROGRESS BAR COLOR PgColor t Scalar Pg RED
Rt ARG PROGRESS DIVISIONS unsigned short Scalar 1
Rt ARG PROGRESS GAP unsigned short Scalar 4
Rt ARG PROGRESS SPACING unsigned short Scalar 0

816 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems RtProgress

Rt ARG PROGRESS BAR COLOR

C type Pt type Default
PgColor t Scalar Pg RED

The color of the progress bar.

Rt ARG PROGRESS DIVISIONS

C type Pt type Default
unsigned short Scalar 1

The number of divisions (1 means continuous).

Rt ARG PROGRESS GAP

C type Pt type Default
unsigned short Scalar 4

The gap (in pixels) between the progress bar and the text (if the text
isn’t on top of the bar).

Rt ARG PROGRESS SPACING

C type Pt type Default
unsigned short Scalar 0

The spacing (in pixels) between divisions (see

Rt ARG PROGRESS DIVISIONS).

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.

September 20, 2005 Chapter 2 ¯ Widgets 817

RtProgress  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic Pg BLACK
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic Pg GRAY
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG GAUGE FLAGS PtGauge
Pt ARG GAUGE FONT PtGauge
Pt ARG GAUGE H ALIGN PtGauge
Pt ARG GAUGE MAXIMUM PtGauge
Pt ARG GAUGE MINIMUM PtGauge
Pt ARG GAUGE ORIENTATION PtGauge
Pt ARG GAUGE V ALIGN PtGauge
Pt ARG GAUGE VALUE PtGauge
Pt ARG GAUGE VALUE PREFIX PtGauge

continued. . .

818 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems RtProgress

Resource Inherited from Default override

Pt ARG GAUGE VALUE SUFFIX PtGauge
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic
Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY AS REQUIRED
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB UNREALIZED PtWidget

September 20, 2005 Chapter 2 ¯ Widgets 819

RtTrend  2005, QNX Software Systems
A realtime trend graph

Class hierarchy:
PtWidget → PtBasic → RtTrend

PhAB icon:

Public header:
<photon/realtime/RtTrend.h>

Description:
An RtTrend 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.

An RtTrend widget.

820 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems RtTrend

New resources:

Resource C type Pt type Default

Rt ARG TREND ATTRIBUTES RtTrendAttr t *, short Array 1 or
(1,1,1,1..)
Rt ARG TREND COLOR LIST PgColor t *, short Array NULL
Rt ARG TREND COUNT int Scalar 1
Rt ARG TREND DATA short *, int Array None
(write-
only)
Rt ARG TREND FLAGS long Flag See
below
Rt ARG TREND GRID COLOR PgColor t Scalar Pg GRAY
Rt ARG TREND GRID X short int Scalar 5
Rt ARG TREND GRID Y short int Scalar 5
Rt ARG TREND INC short int Scalar 1
Rt ARG TREND MAX short int Scalar SHRT MAX
Rt ARG TREND MIN short int Scalar SHRT MIN
Rt ARG TREND PALETTE END unsigned short Scalar 256

Rt ARG TREND ATTRIBUTES

C type Pt type Default
RtTrendAttr 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 RtTrendAttr t, which contains at least the
following member:

September 20, 2005 Chapter 2 ¯ Widgets 821

RtTrend  2005, QNX Software Systems

int map An index into Rt ARG TREND COLOR LIST to

indicate the color that the trend will use. 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 Rt ARG TREND COLOR LIST (which is
the same as Pt ARG COLOR)
2 the second color in Rt ARG TREND COLOR LIST
3 etc.

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.
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. Thus, to set the attributes for all trends at the same time, set
PtSetArg’s len argument to 0 and have the value argument point to an
array of RtTrendAttr 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};
RtTrendAttr t one attr, several attr[3];
PtArg t args[2];
PtWidget t trend widget;

.
.
.

/* Set up the color list. */

PtSetArg (&args[0], Rt ARG TREND COLOR LIST,
trend color array, 4);
PtSetResources (trend widget, 1, args);

822 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems RtTrend

/* 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], Rt ARG TREND ATTRIBUTES,

several attr, 0);
PtSetResources (trend widget, 1, args);

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 RtTrendAttr t. For example, the following would
change the color of trend 2 to Pg GREEN:

one attr.map = 1;
PtSetArg (&args[0], Rt ARG TREND ATTRIBUTES,
&one attr, 2);
PtSetResources (trend widget, 1, args);

☞ 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.

Rt ARG TREND COLOR LIST

C type Pt type Default
PgColor t *, short Array NULL

The list of colors that the trend may use. To assign one of these colors
to a trend, use the Rt ARG TREND ATTRIBUTES resource.

☞ The first color in this list is always the same as Pt ARG COLOR.

September 20, 2005 Chapter 2 ¯ Widgets 823

RtTrend  2005, QNX Software Systems

Rt ARG TREND COUNT

C type Pt type Default
int Scalar 1

The number of trends that the widget will display.

Rt ARG TREND DATA (write-only)

C type Pt type Default
short *, int Array None

The data displayed by the trends. This resource is used to set the data;
it can’t be used 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 will be
cleared.
If you wish to replace some of the data for one trend, call
RtTrendChangeTrendData(). To replace data in all trends, call
RtTrendChangeData().

Rt ARG TREND FLAGS

824 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems RtTrend

C type Pt type Default

long Flag Rt TREND HORIZONTAL | Rt GRID |
Rt TREND RIGHT TO LEFT |
Rt GRID IS TRANSLUCENT

Flags that control the appearance of the widget. Possible values:

Rt GRID Draw a grid.

If this flag is set, you must also set exactly one of
Rt GRID IS TRANSLUCENT,
Rt GRID ABOVE TRENDS, or
Rt TRENDS ABOVE GRID.
Rt GRID IS TRANSLUCENT
Make the grid translucent, appearing over the trends.
The grid is displayed only if Rt GRID is set.
Rt GRID ABOVE TRENDS
Make the grid opaque, appearing over the trends.
The grid is displayed only if Rt GRID is set.

Rt GRID FORCE
Draw a grid even if the graphics device doesn’t support
hardware blitting. Some flickering may occur.

Rt PIXEL Draw the trend with PgDrawPixelArray() instead of

PgDrawPolygon().
Rt TRENDS ABOVE GRID
Make the grid opaque, appearing under the trends.
The grid is displayed only if Rt GRID is set.

Rt TREND HORIZONTAL
Make the trends horizontal.

September 20, 2005 Chapter 2 ¯ Widgets 825

RtTrend  2005, QNX Software Systems

If this is set, you must also set exactly one of

Rt TREND LEFT TO RIGHT and
Rt TREND RIGHT TO LEFT.
Rt TREND VERTICAL
Make the trends vertical.
If this is set, you must also set exactly one of
Rt TREND TOP TO BOTTOM and
Rt TREND BOTTOM TO TOP.
Rt TREND LEFT TO RIGHT
Make the trends move from left to right. You can use
this only with Rt TREND HORIZONTAL.

Rt TREND RIGHT TO LEFT

Make the trends move from right to left. You can use
this only with Rt TREND HORIZONTAL.

Rt TREND TOP TO BOTTOM

Make the trends move from the top to the bottom of the
widget. You can use this only with
Rt TREND VERTICAL.
Rt TREND BOTTOM TO TOP
Make the trends move from the bottom to the top of the
widget. You can use this only with
Rt TREND VERTICAL.

☞ If you set Rt ARG TREND FLAGS to an invalid value, the widget

will draw only the background.

Rt ARG TREND GRID COLOR

826 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems RtTrend

C type Pt type Default

PgColor t Scalar Pg GRAY

The color of the grid, specified as an RGB value. The grid is

displayed only if Rt GRID is set in Rt ARG TREND FLAGS.

Rt ARG TREND GRID X

C type Pt type Default
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 Rt GRID is set in
Rt ARG TREND FLAGS.

Rt ARG TREND GRID Y

C type Pt type Default
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 Rt GRID is set in
Rt ARG TREND FLAGS.

Rt ARG TREND INC

C type Pt type Default
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.

September 20, 2005 Chapter 2 ¯ Widgets 827

RtTrend  2005, QNX Software Systems

Rt ARG TREND MAX

C type Pt type Default
short int Scalar SHRT MAX

The maximum data value for all the trends.

Rt ARG TREND MIN

C type Pt type Default
short int Scalar SHRT MIN

The minimum data value for all the trends.

Rt ARG TREND PALETTE END

C type Pt type Default
unsigned short Scalar 256

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 RtTrend
widget and you want to make sure their palette entries don’t overlap.
Each RtTrend widget uses:

¯ two palette entries for each entry in the

Rt 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 Rt 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.

828 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems RtTrend

The value of Rt ARG TREND PALETTE END should be a multiple

of N. If it isn’t, it’s rounded down to a multiple of N.

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 AREA PtWidget
Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.
Pt ARG BITMAP CURSOR PtWidget
Pt ARG BORDER WIDTH PtWidget
Pt ARG BOT BORDER COLOR PtBasic
Pt ARG COLOR PtBasic Pg RED
Pt ARG CURSOR COLOR PtWidget
Pt ARG CURSOR TYPE PtWidget
Pt ARG DATA PtWidget
Pt ARG DIM PtWidget
Pt ARG EFLAGS PtWidget
Pt ARG FILL COLOR PtBasic Pg BLACK
Pt ARG FILL PATTERN PtBasic
Pt ARG FLAGS PtWidget
Pt ARG HELP TOPIC PtWidget
Pt ARG HIGHLIGHT ROUNDNESS PtBasic
Pt ARG MARGIN HEIGHT PtBasic

continued. . .

September 20, 2005 Chapter 2 ¯ Widgets 829

RtTrend  2005, QNX Software Systems

Resource Inherited from Default override

Pt ARG MARGIN WIDTH PtBasic
Pt ARG POS PtWidget
Pt ARG RESIZE FLAGS PtWidget
Pt ARG TOP BORDER COLOR PtBasic
Pt ARG TRANS PATTERN PtBasic
Pt ARG USER DATA PtWidget
Pt CB ACTIVATE PtBasic
Pt CB ARM PtBasic
Pt CB BLOCKED PtWidget
Pt CB DESTROYED PtWidget
Pt CB DISARM PtBasic
Pt CB GOT FOCUS PtBasic
Pt CB HOTKEY PtWidget
Pt CB LOST FOCUS PtBasic
Pt CB MENU PtBasic
Pt CB RAW PtWidget
Pt CB REALIZED PtWidget
Pt CB REPEAT PtBasic
Pt CB UNREALIZED PtWidget

Convenience functions:
The RtTrend widget defines the following convenience functions
that make it easier to use the widget once it’s been created:

RtTrendChangeData()
Replace some samples for all trends

830 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems RtTrend

RtTrendChangeTrendData()
Replace some samples for one trend

September 20, 2005 Chapter 2 ¯ Widgets 831

RtTrendChangeData(),
RtTrendChangeTrendData()  2005, QNX Software Systems
Replace some samples for one or all trends
Synopsis:
void RtTrendChangeData( PtWidget t *widget,
short const *newdata,
unsigned last sample,
unsigned nsamples);

void RtTrendChangeTrendData( PtWidget t *widget,

unsigned tn,
short const *newdata,
unsigned last sample,
unsigned nsamples);

Description:
These functions allow you to 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 is already in a trend, not
to add data to the end of the trends.

RtTrendChangeTrendData() lets you change data for a single trend.

The widget argument must be a widget of type RtTrend. 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.

832 Chapter 2 ¯ Widgets September 20, 2005

 2005, QNX Software Systems RtTrendChangeData(),
RtTrendChangeTrendData()
Old samples Movement New samples

last_sample + nsamples -1 last_sample

newdata[0] newdata[nsamples -1]

Replacing trend samples with RtTrendChangeData() or

RtTrendChangeTrendData().

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].

¯ ...

September 20, 2005 Chapter 2 ¯ Widgets 833

RtTrendChangeData(),
RtTrendChangeTrendData()  2005, QNX Software Systems

¯ 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.
RtTrendChangeData() allows you to change the data for all the trends.
Its arguments are similar to those of RtTrendChangeTrendData() with
the following exceptions:

¯ tn is not passed to RtTrendChangeData()

¯ 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.

Calling RtTrendChangeData() is similar to calling

RtTrendChangeTrendData() in the following loop:

for (i=0; i<TREND COUNT; ++i) {

RtTrendChangeTrendData (widget, i, newdata, last sample,
nsamples);
newdata += nsamples;
}

The only difference is that RtTrendChangeData() redraws the widget

once; the loop would redraw it once per iteration.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

834 Chapter 2 ¯ Widgets September 20, 2005

 Glossary

September 20, 2005 Glossary 835

 2005, QNX Software Systems

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 absolute or proportional distance between the edges of a
container-class child widget and the parent widget it’s anchored to.

anchor
A constraint mechanism used to manage what happens to a
container-class child 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.

September 20, 2005 Glossary 837

  2005, QNX Software Systems

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 the screen.

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

838 Glossary September 20, 2005

 2005, QNX Software Systems

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.

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.

September 20, 2005 Glossary 839

  2005, QNX Software Systems

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 PtPane.

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
keyboard 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.

840 Glossary September 20, 2005

 2005, QNX Software Systems

DayMinder
A Photon application that you can use to organize your daily schedule
and activities.

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 provided by the Photon Desktop Manager. The
desktop consists of nine consoles or workspaces.

desktop manager
See Photon Desktop Manager.

device region
The region located in the middle of the event space, with application
regions behind it and driver regions in front of it.

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.

September 20, 2005 Glossary 841

  2005, QNX Software Systems

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.

ditto
A QNX utility that lets you attach a local console or terminal to a
remote console. See also phditto.

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 draw events.

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.

842 Glossary September 20, 2005

 2005, QNX Software Systems

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 or 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 another widget (as opposed to an application)
whose resources you can access through the parent.

exposure
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.

September 20, 2005 Glossary 843

  2005, QNX Software Systems

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.

844 Glossary September 20, 2005

 2005, QNX Software Systems

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.

September 20, 2005 Glossary 845

  2005, QNX Software Systems

icon module
A PhAB module that holds the icons used by the Photon Desktop
Manager for launch buttons and by the Photon Window Manager for
the taskbar.

image
A rectangular array of color values, where each color value 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 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 member of a class; for example, “Lassie” is an instance of the class
“dog.” In Photon, an instance is usually a widget instance. When an
instance 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 the instance can be accessed in an application’s code.

846 Glossary September 20, 2005

 2005, QNX Software Systems

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.

Jump Gate
A mechanism that “transports” an application from one QNX node to
another.

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.

September 20, 2005 Glossary 847

  2005, QNX Software Systems

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.

Message Pad
A Photon application that lets you post notes on your computer’s
screen or send them to other users over the network.

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.

848 Glossary September 20, 2005

 2005, QNX Software Systems

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.

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.

PDM
See Photon Desktop Manager.

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 Photon from a
Microsoft Windows environment.

September 20, 2005 Glossary 849

  2005, QNX Software Systems

PhinX
Photon in X. An application that accesses Photon from an X Window
System environment.

Photon Desktop Manager (PDM)

An application that provides a “control panel” that lets you launch
applications, move around the desktop, and change the desktop’s
settings.

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.

phsac
A utility that displays system activity.

picture module
A PhAB module that contains an arrangement of widgets that can be
displayed in another widget or used as a widget database.

850 Glossary September 20, 2005

 2005, QNX Software Systems

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 some printers, 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.

September 20, 2005 Glossary 851

  2005, QNX Software Systems

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-event 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.

852 Glossary September 20, 2005

 2005, QNX Software Systems

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.

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.

September 20, 2005 Glossary 853

  2005, QNX Software Systems

Taskbar
An area in which the Photon Window Manager 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.

854 Glossary September 20, 2005

 2005, QNX Software Systems

vsin
A utility that displays system information.

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.

September 20, 2005 Glossary 855

  2005, QNX Software Systems

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 screen.

856 Glossary September 20, 2005

 Index

! PtScrollArea 526
enabling
“set” state 762 PtContainer 132
Pt CB ACTIVATE 49 PtText 633
PtTextSetSelection() 658
RtMeter 809
autohighlighting 759
A AwFileSelect See PtFileSel
instead
accelerators 323
AwFileSelectCallback t 30,
menu items 364
31
activation
AwMessage See PtMessage
any mouse button 759
instead
defined 44
Pt CB ACTIVATE 48, 665
anchor flags 129, 131
and resize flags 138 B
anchor offsets 129, 130
arc widget See PtArc Bézier curve widget See
area 754 PtBezier
arming background
defined 44 color 46
Pt CB ARM 50 pattern 47
arrow keys widget See PtBkgd
disabling balloons
PtGroup 282 callback 133

September 20, 2005 Index 857

Index  2005, QNX Software Systems

customizing 324 callbacks

disabling 132 activate 48, 665
fill color 323 arguments 7
popping up immediately 130 arm 50
position 321, 323 balloon 133
PtBalloonCallback t 5 blocked 765
text color 323 destroyed 766
bandwidth, graphics threshold 46 disarm 51
basic widget See PtBasic filter 134
beveled highlighting 760 got focus 51
bitmap widget hotkey 766
background See PtBkgd invoking when resources are
general purpose See set 759
PtBitmap lost focus 52
label See PtLabel menu 44, 53
blocking 759 PtBalloonCallback t 5
hotkeys 766 PtCallback t 7
Pt CB BLOCKED 765 PtCallbackInfo t 9
border PtHotkeyCallback t 11
color PtRawCallback t 13
bottom, right 46 raw events 768
top, left 48 realized 769
roundness 47 repeat 54
width 756 resizing 136
browse mode 227 return value 8
button widget right mouse button 44, 53
menu See PtMenuButton unrealized 769
on/off See PtOnOffButton chord 40
pushbutton See PtButton circle widget See PtEllipse
toggle See PtToggleButton class hierarchy 17
up/down See PtUpDown clipped highlighting rectangle 759
clock widget See PtClock
color
background 46
C border
bottom, right 46
calendar widget See PtCalendar top, left 48

858 Index September 20, 2005

 2005, QNX Software Systems Index

fill 46 data, user-defined 665, 765

foreground 46 destruction
color-gradient widget See PtBkgd marking for 760
column widget See PtGroup Pt CB DESTROYED 766
combobox widget See device emulator widget See PtTty
PtComboBox dimensions 754, 758
compound widget See also dimming 48, 761
PtCompound disarming
procreated child 761 defined 44
container widget Pt CB DISARM 51
double-buffered See divider widget See PtDivider
PtDBContainer double-buffered container widget
flags 132 See PtDBContainer
general purpose See drawing
PtContainer color 46
contributed widgets xix flicker-free See
conventions, typographical xvii PtDBContainer
creating a drawing 253 using graphical widgets 251,
Ctrl-click selection 227 253
CUA (Common User Access) using primitive graphics
enabling 132 functions 501
enabling arrow keys 132
preventing focusing 132
cursor
bitmap 754 E
color 756
type 757 ellipse widget See PtEllipse
elliptical arc widget See PtArc
etched highlighting 760
events
D blocking 759, 765
consuming 758
damage hotkeys
family 760 callback 766
propagating to parent 758 PtHotkeyCallback t 11
widget 760 terminating searches for 132
dashed lines 270 key

September 20, 2005 Index 859

Index  2005, QNX Software Systems

consuming 223 extended 758

processing as hotkeys generic list 222
first 132 generic list column 221
pending generic tree 242, 248
PtFileSel 169 graphic 270
Ph EV BUT REPEAT 54 group 282
raw menu 377
callback 768 region 516
filter callback 134 resize 763
PtRawCallback t 13 widget 759
repeat callback 54 flicker-free drawing See
window manager 775, 783, PtDBContainer
787 floating-point number widget See
extended flags 758 PtNumericFloat
extended-selection mode 227 flux 761
extent See also resizing focus
preventing intersections getting 759
with 759 granting 760
recalculating Pt CB GOT FOCUS 51
automatically 132 Pt CB LOST FOCUS 52
rendering 760
font selector widget See
PtFontSel
F foreground color 46

FD CLOEXEC 734
file folder widget See PtTab
file selector widget See G
PtFileSel
fill gauge widget See PtGauge
color 46 generic list widget See
pattern 47 PtGenList
filter callback 134 generic tree widget See
flags PtGenTree
anchor 129, 131 ghosting 48, 761
common, summarized 18 graphics
container 132 bandwidth threshold 46

860 Index September 20, 2005

 2005, QNX Software Systems Index

vector 252 callback 766

rescaling 256 menu items 364
graphics primitives functions 501 PtHotkeyCallback t 11
graphics primitives widget terminating searches for 132
arc See PtArc HTML widget See PtHtml
Bézier curve See PtBezier hyperlinks 290, 309, 405
bitmap See PtBitmap
circle, ellipse See PtEllipse
flags 270
line See PtLine I
pixels See PtPixel
icon widget See PtIcon
polygon See PtPolygon
rectangle See PtRect image widget
background See PtBkgd
superclass See PtGraphic
label See PtLabel
grid widget See PtGrid
increment/decrement button widget
group widget See PtGroup
See PtUpDown
integer widget See
PtNumericInteger
H
height 754, 758
help J
button 772, 784
Jump Gate 789
in a balloon 758
information 763
root 782
topic path 763 K
highlighting
automatically 759 key events
beveled rectangle 760 consuming 223
clipping corners 759 processing as hotkeys first 132
etched 760
requesting 761
hotkeys
accelerator key 323 L
blocking 766
label widget See PtLabel

September 20, 2005 Index 861

Index  2005, QNX Software Systems

line widget See PtLine making actions the same for all
lines, dashed 270 buttons 45, 759
list widget right button action 44, 761
superclass See PtGenList Pt CB MENU 44, 53
text items See PtList multiline text widget See
with text-entry field See PtMultiText
PtComboBox multiple choice widget See
PtComboBox
multiple-select mode 227

M
margins N
height 47
width 48 navigation See CUA (Common
matrix widget See PtGroup User Access)
memory context 139, 140 numeric widget
memory, freeing floating-point See
automatically 760 PtNumericFloat
when destroying a widget 766 integer See
menu PtNumericInteger
enabling mouse button 761 range of values See
item, indicating 761 PtSlider
Pt CB MENU 44, 53 superclass See PtNumeric
menu bar widget See PtMenuBar
menu button widget See
PtMenuButton
O
menu widget See PtMenu
message widget See PtMessage obscuring 761
meter widget See RtMeter on/off button widget See
mouse PtOnOffButton
left button actions 44 opacity 761
click count 49
Pt CB ACTIVATE 48, 665
Pt CB ARM 50
Pt CB DISARM 51 P
pane widget See PtPane

862 Index September 20, 2005

 2005, QNX Software Systems Index

pathname delimiter in QNX Ph KBD REGION 516

Momentics documentation Ph NO COMPRESSION 516
xviii Ph PRINT REGION 516
pattern Ph PTR REGION 516
background 47 Ph WINDOW REGION 516
fill 47 Ph WM APP DEF MANAGED 783
transparency 48 Ph WM APP DEF RENDER 773
Pg BEVEL JOIN 271 Ph WM BACKDROP 782
Pg BUTT CAP 271 Ph WM CLOSE 782
Pg BUTT JOIN 271 Ph WM CONSWITCH 782
Pg CLOSED 490 Ph WM FFRONT 782
PgColor t 429, 431 Ph WM FOCUS 782
Pg IMAGE DIRECT 888 140 Ph WM HELP 782
Pg IMAGE PALETTE BYTE 140 Ph WM HIDE 782
Pg MITER JOIN 271 Ph WM MAX 782
Pg POLY FILL 491 Ph WM MENU 782
Pg POLY RELATIVE 490 Ph WM MOVE 782
Pg POLY STROKE 490 Ph WM RENDER ASAPP 772, 784
Pg QROUND JOIN 271 Ph WM RENDER ASICON 772,
Pg ROUND CAP 271 784
Pg ROUND JOIN 271 Ph WM RENDER BORDER 772,
Pg SQUARE CAP 271 784
Ph AUXPTR REGION 516 Ph WM RENDER CLOSE 772, 784
Ph BAUD SLOW 542 Ph WM RENDER HELP 772, 784
Ph CURSOR BITMAP 754, 757 Ph WM RENDER MAX 772, 784
PhCursorDef t 754 Ph WM RENDER MENU 772, 784
Ph CURSOR INHERIT 757 Ph WM RENDER MIN 772, 784
Ph CURSOR NO INHERIT 757 Ph WM RENDER RESIZE 772, 785
Ph CURSOR SET 516 Ph WM RENDER TITLE 772, 785
Ph EV BOUNDARY 133, 134 Ph WM RESIZE 782
Ph EV PTR MOTION NOBUTTON 134 Ph WM RESTORE 782
Ph EV PTR STEADY 133 Ph WM STATE ISALTKEY 785
Ph FOLLOW IG SIZE 516 Ph WM STATE ISBACKDROP 785
Ph FORCE BOUNDARY 134, 516 Ph WM STATE ISBLOCKED 786
Ph FORCE FRONT 516 Ph WM STATE ISFOCUS 786
Ph GRAFX REGION 516 Ph WM STATE ISFRONT 786
Ph INPUTGROUP REGION 516 Ph WM STATE ISHIDDEN 786

September 20, 2005 Index 863

Index  2005, QNX Software Systems

Ph WM STATE ISICONIFIED 786 Pt ARG POINTS 38

Ph WM STATE ISMAX 786 start angle 40
Ph WM TOBACK 782 type 40
Ph WM TOFRONT 782 Pt ARC CHORD 40
Ph WND MGR REGION 516 Pt ARC CURVE 40
pie wedge 40 Pt ARC PIE 40
pixel widget See PtPixel Pt ARG ACCEL FONT 387
Pm IMAGE CONTEXT 140 Pt ARG ACCEL KEY
Pm PHS CONTEXT 140 PtLabel 323
pointer PtMenuButton 386
left button actions 44 Pt ARG ACCEL TEXT 387
click count 49 Pt ARG ANCHOR FLAGS 129,
Pt CB ACTIVATE 48, 665 131
Pt CB ARM 50 Pt ARG ANCHOR OFFSETS 129,
Pt CB DISARM 51 130
making actions the same for all Pt ARG ARC END 39
buttons 45, 759 Pt ARG ARC START 40
right button action 44, 761 Pt ARG ARC TYPE 40
Pt CB MENU 44, 53 Pt ARG AREA
points widget See PtPixel PtContainer 131
polygon widget See PtPolygon PtScrollArea 522, 527
position 754, 763 PtTerminal 570, 571
PpPrintContext t 495 PtWidget 754
primitive graphics functions 501 Pt ARG ARM COLOR 80, 81
print selector widget See Pt ARG ARM DATA 80, 81
PtPrintSel Pt ARG ARM FILL 80, 82
procreated child 761 Pt ARG BALLOON COLOR
progress widget See RtProgress PtGenList 221
Pt ALL BUTTONS 44, 54, 759 PtLabel 323
PtArc 38 Pt ARG BALLOON FILL COLOR
control points 38 PtGenList 221
end angle 39 PtLabel 323
Pt ARG ARC END 39 Pt ARG BALLOON POSITION
Pt ARG ARC START 40 317, 321, 323
Pt ARG ARC TYPE 40 Pt ARG BANDWIDTH THRESHOLD
Pt ARG DIM 38 PtBasic 46
Pt ARG ORIGIN 38 PtDivider 149

864 Index September 20, 2005

 2005, QNX Software Systems Index

PtScrollbar 544 Pt ARG BORDER WIDTH

PtTerminal 575, 603 PtHtml 296
PtTty 742 PtMenu 377
Pt ARG BEZIER FLAGS 57 PtWidget 756
Pt ARG BITMAP BALLOON 61 Pt ARG BOT BORDER COLOR
Pt ARG BITMAP BALLOON COLOR 46
62 Pt ARG BUTTON TYPE 371, 387
Pt ARG BITMAP BALLOON FILL COLOR Pt ARG CALENDAR COLOR1 88
63 Pt ARG CALENDAR COLOR2 88
Pt ARG BITMAP BALLOON POSITION Pt ARG CALENDAR COLOR3 88
63 Pt ARG CALENDAR COLOR4 88
Pt ARG BITMAP COLORS 63 Pt ARG CALENDAR COLOR5 88
Pt ARG BITMAP CURSOR 754 Pt ARG CALENDAR DATE 89
Pt ARG BITMAP DATA 64 Pt ARG CALENDAR FLAGS 89
Pt ARG BITMAP FLAGS 64 Pt ARG CALENDAR FONT1 90
Pt ARG BITMAP TEXT 64 Pt ARG CALENDAR FONT2 90
Pt ARG BKGD BRT FROM 71 Pt ARG CALENDAR FONT3 90
Pt ARG BKGD BRT TO 71 Pt ARG CALENDAR FONT4 91
Pt ARG BKGD HUE FROM 71 Pt ARG CALENDAR FONT5 91
Pt ARG BKGD HUE TO 71 Pt ARG CALENDAR HIGHLIGHT
Pt ARG BKGD IMAGE 71 91
Pt ARG BKGD MIX 72 Pt ARG CALENDAR MONTH BTN COLOR
Pt ARG BKGD ORIENTATION 91
72 Pt ARG CALENDAR MONTH NAMES
Pt ARG BKGD PIXCOLORS 73 92
Pt ARG BKGD PIX HEIGHT 73 Pt ARG CALENDAR SEL COLOR
Pt ARG BKGD PIXMAP 73 93
Pt ARG BKGD PIX WIDTH 73 Pt ARG CALENDAR TIME T 93
Pt ARG BKGD SAT FROM 73 Pt ARG CALENDAR WDAY NAMES
Pt ARG BKGD SAT TO 73 93
Pt ARG BKGD SPACING 74 Pt ARG CALENDAR YEAR BTN COLOR
Pt ARG BKGD STEPS 74 94
Pt ARG BKGD TILE 74 Pt ARG CBOX BUTTON BORDER WIDTH
Pt ARG BKGD TYPE 75 111
Pt ARG BMP SET BG COLOR Pt ARG CBOX BUTTON BOT BORDER COLOR
65 112
Pt ARG BMP SET BG FILL 65

September 20, 2005 Index 865

Index  2005, QNX Software Systems

Pt ARG CBOX BUTTON COLOR Pt ARG CLOCK TYPE 105

112 Pt ARG COLOR
Pt ARG CBOX BUTTON TOP BORDER COLOR PtBasic 46
112 PtMultiText 400, 430, 431
Pt ARG CBOX BUTTON WIDTH PtRaw 503
112 RtTrend 823
Pt ARG CBOX FLAGS 112 Pt ARG COLUMNS 638
Pt ARG CBOX MAX VISIBLE COUNT Pt ARG CONTAINER FLAGS 132
113 Pt ARG CURSOR COLOR 756
Pt ARG CBOX SEL ITEM 113 Pt ARG CURSOR POSITION 639
Pt ARG CLOCK FACE COLOR Pt ARG CURSOR TYPE 757
100 Pt ARG DASH LIST
Pt ARG CLOCK FACE OUTLINE COLOR PtGraphic 270
100 PtGrid 277
Pt ARG CLOCK FLAGS 100 Pt ARG DASH SCALE
Pt ARG CLOCK FONT 101 PtGraphic 270
Pt ARG CLOCK HOUR 102 PtGrid 277
Pt ARG CLOCK HOUR COLOR Pt ARG DATA 757
102 Pt ARG DB IMAGE TYPE 140
Pt ARG CLOCK HOUR OFFSET Pt ARG DB MEMORY CONTEXT TYPE
102 140
Pt ARG CLOCK MINUTE 102 Pt ARG DIM
Pt ARG CLOCK MINUTE COLOR PtArc 38
103 PtBitmap 68
Pt ARG CLOCK MINUTE OFFSET PtEllipse 151
103 PtFontSel 211
Pt ARG CLOCK SECOND 103 PtMultiText 407
Pt ARG CLOCK SECOND COLOR PtPrintSel 499
103 PtRect 509
Pt ARG CLOCK SECOND OFFSET PtSlider 557
104 PtTerminal 570–572, 574
Pt ARG CLOCK SEP1 104 PtText 638
Pt ARG CLOCK SEP1 COLOR PtWidget 758
104 Pt ARG DIRECTION 537
Pt ARG CLOCK SEP2 104 Pt ARG DIVIDER FLAGS 144
Pt ARG CLOCK SEP2 COLOR Pt ARG DIVIDER OFFSET 145
105 Pt ARG DIVIDER SIZES 145

866 Index September 20, 2005

 2005, QNX Software Systems Index

Pt ARG EDIT MASK 639 Pt ARG FS FORMAT 165

Pt ARG EFLAGS 758, 763 Pt ARG FS IMAGES 166
Pt ARG FILL COLOR Pt ARG FS REFRESH 168
PtBasic 46 Pt ARG FS ROOT DIR 168
PtDBContainer 142 Pt ARG GAUGE FLAGS 213
PtMultiText 400, 430, 432 Pt ARG GAUGE FONT 213
PtRaw 503 Pt ARG GAUGE H ALIGN 214
PtTerminal 603 Pt ARG GAUGE MAXIMUM 214
RtTrend 822 Pt ARG GAUGE MINIMUM 214
Pt ARG FILL PATTERN 47 Pt ARG GAUGE ORIENTATION
Pt ARG FLAGS 214
menu items 365 Pt ARG GAUGE V ALIGN 215
PtBasic 44, 49, 54 Pt ARG GAUGE VALUE 215
PtClock 105 Pt ARG GAUGE VALUE PREFIX
PtDivider 145 215
PtFontSel 209 Pt ARG GAUGE VALUE SUFFIX
PtGenList 231 215
PtMenu 367 Pt ARG GRAPHIC FLAGS 270
PtMultiText 420 Pt ARG GRID HORIZONTAL 277
PtOnOffButton 478 Pt ARG GRID VERTICAL 278
PtScrollArea 529 Pt ARG GROUP FLAGS 282
PtScrollbar 540 toggle buttons 664
PtSlider 557 Pt ARG GROUP HORZ ALIGN
PtText 634, 643, 644, 646, 284
650, 656 Pt ARG GROUP ORIENTATION
PtToggleButton 664 PtDivider 149
PtTty 725 PtGroup 284
PtUpDown 748, 751 Pt ARG GROUP ROWS COLS
PtWidget 759 284
RtMeter 809, 810 Pt ARG GROUP SPACING 285
Pt ARG FONT DISPLAY 207 Pt ARG GROUP SPACING X 285
Pt ARG FONT FLAGS 207 Pt ARG GROUP SPACING Y 285
Pt ARG FONT NAME 208 Pt ARG GROUP VERT ALIGN
Pt ARG FONT SAMPLE 208 286
Pt ARG FONT SYMBOL 208 Pt ARG HELP TOPIC 763
Pt ARG FS FILE SPEC 164 Pt ARG HIGHLIGHT ROUNDNESS
Pt ARG FS FLAGS 164 47

September 20, 2005 Index 867

Index  2005, QNX Software Systems

Pt ARG HORIZONTAL ALIGNMENT Pt ARG HTML SCROLL VERTICAL

318, 324 302
Pt ARG HTML BORDER WIDTH Pt ARG HTML SCROLL WIDTH
296 302
Pt ARG HTML CURSOR BUSY Pt ARG HTML TEXT FONT 303
296 Pt ARG HTML URL 303
Pt ARG HTML CURSOR DEFAULT Pt ARG ICON WINDOW 771, 780
296 Pt ARG INCREMENT 537
Pt ARG HTML CURSOR LINK Pt ARG INDICATOR COLOR
297 666
Pt ARG HTML FILL COLOR 297 Pt ARG INDICATOR DEPTH
Pt ARG HTML FLAGS 297 666
Pt ARG HTML H1 FONT 297 Pt ARG INDICATOR HEIGHT
Pt ARG HTML H2 FONT 298 666
Pt ARG HTML H3 FONT 298 Pt ARG INDICATOR TYPE 666
Pt ARG HTML H4 FONT 298 Pt ARG INDICATOR WIDTH 667
Pt ARG HTML H5 FONT 298 Pt ARG ITEMS 340, 341, 341
Pt ARG HTML H6 FONT 298 Pt ARG LABEL BALLOON 324
Pt ARG HTML LINK COLOR Pt ARG LABEL DATA 319, 325
299 Pt ARG LABEL FLAGS 321, 326
Pt ARG HTML PAGE BM 299 Pt ARG LABEL TYPE
Pt ARG HTML PAGE H 299 PtButton 80
Pt ARG HTML PAGE LM 299 PtLabel 317, 326
Pt ARG HTML PAGE N 299 Pt ARG LINE CAP
Pt ARG HTML PAGE RM 300 PtGraphic 271
Pt ARG HTML PAGES 301 PtGrid 278
Pt ARG HTML PAGE TM 300 Pt ARG LINE JOIN
Pt ARG HTML PAGE W 300 PtGraphic 271
Pt ARG HTML PAGE X 300 PtGrid 278
Pt ARG HTML PAGE Y 301 Pt ARG LINE SPACING
Pt ARG HTML SCROLL COLOR PtLabel 327
301 PtMultiText 399
Pt ARG HTML SCROLL FILL COLOR Pt ARG LINE WIDTH
301 PtGraphic 272
Pt ARG HTML SCROLL HORIZONTAL PtGrid 279
302 Pt ARG LIST BALLOON 341

868 Index September 20, 2005

 2005, QNX Software Systems Index

Pt ARG LIST COLUMN ATTR Pt ARG MENU TITLE 367, 378

221 Pt ARG MENU TITLE FONT
Pt ARG LIST COLUMN POS 367, 378
PtGenList 222 Pt ARG MIN HEIGHT 780
PtList 338 Pt ARG MINIMUM 538
PtTree 672 Pt ARG MIN SLIDER SIZE 538
Pt ARG LIST FLAGS Pt ARG MIN WIDTH 781
PtGenList 218, 222 Pt ARG MODIFY ITEMS 343
Pt ARG LIST FONT 224 Pt ARG MSG BUTTON1 393
Pt ARG LIST ITEM COUNT 224 Pt ARG MSG BUTTON2 393
Pt ARG LIST SB RES 218, 224 Pt ARG MSG BUTTON3 393
Pt ARG LIST SCROLL RATE 225 Pt ARG MSG DEFAULT 394
Pt ARG LIST SEL COUNT 226 Pt ARG MSG ESCAPE 394
Pt ARG LIST SPACING 342 Pt ARG MSG FLAGS 394
Pt ARG LIST TOTAL HEIGHT Pt ARG MSG FONT 394
226 Pt ARG MSG TEXT 395
Pt ARG MARGIN BOTTOM 318, Pt ARG MSG TITLE 395
327 Pt ARG MULTITEXT BOTTOM LINE
Pt ARG MARGIN HEIGHT 410
PtBasic 47 Pt ARG MULTITEXT FLAGS 410
PtTerminal 570–572, 586 Pt ARG MULTITEXT NUM LINES
Pt ARG MARGIN LEFT 318, 328 411
Pt ARG MARGIN RIGHT 318, Pt ARG MULTITEXT NUM LINES VISIBLE
328 411
Pt ARG MARGIN TOP 318, 328 Pt ARG MULTITEXT QUERY CHARACTER
Pt ARG MARGIN WIDTH 411
PtBasic 48 Pt ARG MULTITEXT QUERY LINE
PtTerminal 570–572, 586 407, 412
Pt ARG MAX HEIGHT 780 Pt ARG MULTITEXT RANGE ATTRIBUTES
Pt ARG MAXIMUM 538 401, 403, 412
Pt ARG MAX LENGTH 640 Pt ARG MULTITEXT ROWS 413
Pt ARG MAX WIDTH 780 Pt ARG MULTITEXT SEGMENTS
Pt ARG MENU FLAGS 365, 367, 400, 401, 413
368, 371, 377 Pt ARG MULTITEXT TABS 414
Pt ARG MENU SPACING 377 Pt ARG MULTITEXT TOP LINE
Pt ARG MENU TEXT FONT 414
367, 378

September 20, 2005 Index 869

Index  2005, QNX Software Systems

Pt ARG MULTITEXT WRAP FLAGS Pt ARG NUMERIC UPDOWN BORDER WIDTH

399, 414 457
Pt ARG MULTITEXT X SCROLL POS Pt ARG NUMERIC UPDOWN WIDTH
415 458
Pt ARG MULTITEXT Y SCROLL POS Pt ARG NUMERIC VALUE
415 PtNumericFloat 464
Pt ARG NUMERIC FLAGS 454 PtNumericInteger 472
Pt ARG NUMERIC INCREMENT Pt ARG OFFSET 388
PtNumericFloat 463 Pt ARG ONOFF STATE 478
PtNumericInteger 471 Pt ARG ORIENTATION 538
Pt ARG NUMERIC MAX Pt ARG ORIGIN 252, 253, 272
PtNumericFloat 463 PtArc 38
PtNumericInteger 471 PtBezier 56
Pt ARG NUMERIC MIN PtEllipse 151
PtNumericFloat 463 PtLine 333
PtNumericInteger 471 PtPolygon 489
Pt ARG NUMERIC PRECISION Pt ARG PAGE INCREMENT 539
464 Pt ARG POINTS
Pt ARG NUMERIC PREFIX 455 PtArc 38
Pt ARG NUMERIC SPACING PtBezier 56
455 PtEllipse 151
Pt ARG NUMERIC SUFFIX 455 PtGraphic 252, 272
Pt ARG NUMERIC TEXT BORDER PtLine 333
455 PtPixel 486
Pt ARG NUMERIC TEXT BOT BORDER COLOR PtPolygon 489
456 PtRect 509
Pt ARG NUMERIC TEXT COLOR Pt ARG POLYGON FLAGS 489,
456 490
Pt ARG NUMERIC TEXT FILL COLOR Pt ARG POS
456 PtRect 509
Pt ARG NUMERIC TEXT FLAGS PtWidget 763
456 Pt ARG PRINT CONTEXT 495
Pt ARG NUMERIC TEXT FONT Pt ARG PRINT FLAGS 495, 499
457 Pt ARG RAW CONNECT F 505
Pt ARG NUMERIC TEXT TOP BORDER COLOR Pt ARG RAW DRAW F 502, 506
457 Pt ARG RAW EXTENT F 506
Pt ARG RAW INIT F 506

870 Index September 20, 2005

 2005, QNX Software Systems Index

Pt ARG RECT ROUNDNESS 509, PtMultiText 416

510 PtScrollArea 528
Pt ARG REGION DATA 514 Pt ARG SCROLLBAR Y DISPLAY
Pt ARG REGION FIELDS 514 PtMultiText 400, 416
Pt ARG REGION FLAGS 516 PtScrollArea 522, 529
Pt ARG REGION HANDLE 517 Pt ARG SCROLLBAR Y WIDTH
Pt ARG REGION INFRONT 517 PtMultiText 416
Pt ARG REGION INPUT GROUP PtScrollArea 529
517 Pt ARG SCROLL POSITION 540
Pt ARG REGION OPAQUE 517 Pt ARG SELECTION FILL COLOR
Pt ARG REGION OWNER 518 226
Pt ARG REGION PARENT 518 Pt ARG SELECTION INDEXES
Pt ARG REGION SENSE 518 343
Pt ARG RESIZE FLAGS Pt ARG SELECTION MODE
PtContainer 130, 138 PtGenList 227
PtWidget 763 PtTree 677, 679
Pt ARG SCROLL AREA FLAGS Pt ARG SELECTION RANGE
526 640
Pt ARG SCROLL AREA INCREMENT X Pt ARG SELECTION TEXT COLOR
526 230
Pt ARG SCROLL AREA INCREMENT Y Pt ARG SEP FLAGS 546
527 Pt ARG SEP TYPE 546
Pt ARG SCROLL AREA MAX X Pt ARG SET BITMAP COLORS
522, 527 65
Pt ARG SCROLL AREA MAX Y Pt ARG SET BITMAP DATA 66
522, 527 Pt ARG SET COLOR 667
Pt ARG SCROLL AREA POS X Pt ARG SET FILL 667
527 Pt ARG SHOW ARROWS 540
Pt ARG SCROLL AREA POS Y Pt ARG SLIDER FLAGS 552
528 Pt ARG SLIDER HANDLE HEIGHT
Pt ARG SCROLLBAR FLAGS 539 553
Pt ARG SCROLLBAR WIDTH Pt ARG SLIDER HANDLE WIDTH
226 553
Pt ARG SCROLLBAR X DISPLAY Pt ARG SLIDER IMAGE 553
PtMultiText 400, 415 Pt ARG SLIDER INCREMENT
PtScrollArea 522, 528 553
Pt ARG SCROLLBAR X HEIGHT Pt ARG SLIDER LABEL BR 553

September 20, 2005 Index 871

Index  2005, QNX Software Systems

Pt ARG SLIDER LABEL BR COL Pt ARG TERM CONSOLE 574,

554 582
Pt ARG SLIDER LABEL TL 554 Pt ARG TERM CUR COL 583
Pt ARG SLIDER LABEL TL COL Pt ARG TERM CUR POS 583
554 Pt ARG TERM CUR ROW 583
Pt ARG SLIDER MULTIPLE 554 Pt ARG TERM CURSOR FLAGS
Pt ARG SLIDER ORIENTATION 583
555 Pt ARG TERM DRAW MODES
Pt ARG SLIDER SIZE 539, 540 575, 584
Pt ARG SLIDER TICK MAJOR COL Pt ARG TERM FONT 568, 570,
555 571, 585
Pt ARG SLIDER TICK MAJOR DIV Pt ARG TERM FONT INDEX
555 568, 570, 585
Pt ARG SLIDER TICK MAJOR LEN Pt ARG TERM FONT LIST 568,
556 585
Pt ARG SLIDER TICK MINOR COL Pt ARG TERM FONT SIZE 586
556 Pt ARG TERM MARGINS 570,
Pt ARG SLIDER TICK MINOR DIV 572, 574, 586
556 Pt ARG TERM MAXCOLS 574,
Pt ARG SLIDER TICK MINOR LEN 586
556 Pt ARG TERM MAXROWS 574,
Pt ARG SLIDER TROUGH COL 587
556 Pt ARG TERM MAXSIZE 574,
Pt ARG SLIDER TROUGH SIZE 587, 598
557 Pt ARG TERM MINCOLS 573,
Pt ARG SPACING 668 587
Pt ARG TAB FLAGS 562 Pt ARG TERM MINROWS 573,
Pt ARG TERM APP 578 587
Pt ARG TERM CHARSETS 570, Pt ARG TERM MINSIZE 573,
580 588, 598
Pt ARG TERM COLOR MODE Pt ARG TERM OPTIONS 588
581 Pt ARG TERM OPTMASK 588
Pt ARG TERM COLOR TABLE Pt ARG TERM PROTOCOL 588
575, 581 Pt ARG TERM RESIZE FL 589
Pt ARG TERM COLS 570, 571, Pt ARG TERM RESIZE FUN
582, 598, 599 570, 589

872 Index September 20, 2005

 2005, QNX Software Systems Index

Pt ARG TERM RESIZE STR 570, Pt ARG TOP ITEM POS 230, 238
573, 590 Pt ARG TRANS PATTERN 48
Pt ARG TERM ROWS 570, 571, Pt ARG TREE BALLOON 675
590, 598, 599 Pt ARG TREE FLAGS
Pt ARG TERM SCRLBK COUNT PtGenTree 242, 248
590 PtTree 682
Pt ARG TERM SCRLBK LIMIT Pt ARG TREE IMAGES 673, 676
590 Pt ARG TREE IMGMASK 676
Pt ARG TERM SCRLBK POS Pt ARG TTY ARGV 729
591 Pt ARG TTY BUFFER 730
Pt ARG TERM SCROLL 575, 591 Pt ARG TTY BUFLEN 730
Pt ARG TERM SELECTION 591 Pt ARG TTY CMD 729, 730
Pt ARG TERM SIZE 570–572, Pt ARG TTY DEVSIZE 731
593, 598, 599 Pt ARG TTY EXIT STATUS 731,
Pt ARG TERM VISUAL BELL 738
593 Pt ARG TTY FD 732
Pt ARG TEXT CURSOR WIDTH Pt ARG TTY FDSET 732
641 Pt ARG TTY FLAGS 732
Pt ARG TEXT FLAGS 420, 634, Pt ARG TTY INPUT 733
641, 650 Pt ARG TTY INPUT WRITTEN
Pt ARG TEXT FONT 734
PtLabel 317, 328 Pt ARG TTY MFD 734
PtMultiText 400, 429, 431 Pt ARG TTY PATH 734
Pt ARG TEXT HIGHLIGHT BACKGROUND COLOR Pt ARG TTY PID 730, 735
642 Pt ARG TTY PRI 735
Pt ARG TEXT HIGHLIGHT TEXT COLOR Pt ARG TTY PSEUDO 735
642 Pt ARG TTY SPAWN OPTIONS
Pt ARG TEXT STRING 736
PtLabel 317, 321, 329 Pt ARG UNDERLINE1 329
PtMultiText 400, 413 Pt ARG UNDERLINE2 329
Pt ARG TEXT SUBSTRING Pt ARG UNDERLINE TYPE 329
PtMultiText 400 Pt ARG UPDOWN ARM DATA BOTTOM
PtText 642 745
Pt ARG TIMER INITIAL 661 Pt ARG UPDOWN ARM DATA LEFT
Pt ARG TIMER REPEAT 661 745
Pt ARG TOP BORDER COLOR Pt ARG UPDOWN ARM DATA RIGHT
48 745

September 20, 2005 Index 873

Index  2005, QNX Software Systems

Pt ARG UPDOWN ARM DATA TOP Pt ARG WINDOW ACTIVE COLOR

745 781
Pt ARG UPDOWN BOTTOM BORDER COLOR Pt ARG WINDOW CURSOR OVERRIDE
746 781
Pt ARG UPDOWN DATA BOTTOM Pt ARG WINDOW FRONT WINDOW
746 781
Pt ARG UPDOWN DATA LEFT Pt ARG WINDOW HELP ROOT
746 782
Pt ARG UPDOWN DATA RIGHT Pt ARG WINDOW INACTIVE COLOR
746 782
Pt ARG UPDOWN DATA TOP Pt ARG WINDOW MANAGED FLAGS
746 773, 782
Pt ARG UPDOWN FILL COLOR Pt ARG WINDOW NOTIFY FLAGS
746 775, 783
Pt ARG UPDOWN FLAGS 747 Pt ARG WINDOW RENDER FLAGS
Pt ARG UPDOWN HIGHLIGHT ROUND 772, 784
748 Pt ARG WINDOW STATE 785
Pt ARG UPDOWN MARGIN HEIGHT Pt ARG WINDOW TITLE 786
748 Pt ARG WINDOW TITLE COLOR
Pt ARG UPDOWN MARGIN WIDTH 786
748 Pt AUTO EXTENT 132
Pt ARG UPDOWN ORIENTATION Pt AUTOHIGHLIGHT 367, 759
749 Pt BACKFILL TEXT 326
Pt ARG UPDOWN SPACING 749 Pt BALLOON AS REQUIRED 326
Pt ARG UPDOWN TOP BORDER COLOR Pt BALLOON BOTTOM 324
749 PtBalloonCallback t 5
Pt ARG USER DATA Pt BALLOONCOLOR 323
PtRaw 502 Pt BALLOON INPLACE 324
PtToggleButton 665 Pt BALLOON LEFT 324
PtWidget 765 Pt BALLOON RIGHT 324
Pt ARG VERTICAL ALIGNMENT Pt BALLOONS ON 130
318, 330 Pt BALLOON TOP 324
Pt ARG VISIBLE COUNT PtBasic 43
PtComboBox 120 activate callback 48, 49
PtGenList 230 arm callback 50
PtList 339, 348 behavior 44
border color

874 Index September 20, 2005

 2005, QNX Software Systems Index

bottom, right 46 Pt CB MENU 44, 53

top, left 48 enabling 761
border roundness 47 Pt CB REPEAT 54
disarm callback 51 repeat callback 54
fill color 46 right mouse button
fill pattern 47 callback 44, 53
foreground color 46 selectable 44
got focus callback 51 transparency pattern 48
graphics bandwidth PtBezier 56
threshold 46 Pt ARG BEZIER FLAGS 57
lost focus callback 52 Pt ARG ORIGIN 56
margins Pt ARG POINTS 56
height 47 PtBitmap 60
width 48 balloon
menu callback 44, 53 enabling 64
Pt ARG BANDWIDTH THRESHOLD fill color 63
46 function 61
Pt ARG BOT BORDER COLOR position 63
46 text 64
Pt ARG COLOR 46 text color 62
Pt ARG FILL COLOR 46 bitmap data
Pt ARG FILL PATTERN 47 armed 66
Pt ARG FLAGS 44, 49, 54 normal 64
Pt ARG HIGHLIGHT ROUNDNESS colors
47 armed 65
Pt ARG MARGIN HEIGHT normal 63
47 dimensions 68
Pt ARG MARGIN WIDTH 48 fill color
Pt ARG TOP BORDER COLOR armed 65
48 armed, enabling 65
Pt ARG TRANS PATTERN flags 64
48 Pt ARG BITMAP BALLOON
Pt CB ACTIVATE 44, 48, 49 61
Pt CB ARM 44, 50 Pt ARG BITMAP BALLOON COLOR
Pt CB DISARM 44, 51 62
Pt CB GOT FOCUS 51 Pt ARG BITMAP BALLOON FILL COLOR
Pt CB LOST FOCUS 52 63

September 20, 2005 Index 875

Index  2005, QNX Software Systems

Pt ARG BITMAP BALLOON POSITION Pt ARG BKGD HUE FROM

63 71
Pt ARG BITMAP COLORS Pt ARG BKGD HUE TO 71
63 Pt ARG BKGD IMAGE 71
Pt ARG BITMAP DATA 64 Pt ARG BKGD MIX 72
Pt ARG BITMAP FLAGS 64 Pt ARG BKGD ORIENTATION
Pt ARG BITMAP TEXT 64 72
Pt ARG BMP SET BG COLOR Pt ARG BKGD PIXCOLORS
65 73
Pt ARG BMP SET BG FILL Pt ARG BKGD PIX HEIGHT
65 73
Pt ARG DIM 68 Pt ARG BKGD PIXMAP 73
Pt ARG SET BITMAP COLORS Pt ARG BKGD PIX WIDTH
65 73
Pt ARG SET BITMAP DATA Pt ARG BKGD SAT FROM
66 73
Pt BITMAP BALLOON BOTTOM 63 Pt ARG BKGD SAT TO 73
Pt BITMAP BALLOON INPLACE 63 Pt ARG BKGD SPACING 74
Pt BITMAP BALLOON LEFT 63 Pt ARG BKGD STEPS 74
Pt BITMAP BALLOON RIGHT 63 Pt ARG BKGD TILE 74
Pt BITMAP BALLOON TOP 63 Pt ARG BKGD TYPE 75
Pt BITMAP SHOW BALLOON 64 saturation range 73
PtBkgd 69 steps, number of 74
brightness range 71 tiling
dithering, enabling 72 spacing 74
hue range 71 type 74
image 71 type 75
orientation 72 Pt BKGD ALT 74
pixmap Pt BKGD BRIGHTNESS 75
colors 73 Pt BKGD CENTER 74
data 73 Pt BKGD CENTER GRID 74
height 73 Pt BKGD GRID 74
width 73 Pt BKGD HORIZONTAL 72
Pt ARG BKGD BRT FROM Pt BKGD HUE 75
71 Pt BKGD IMAGE 75
Pt ARG BKGD BRT TO 71 Pt BKGD PIXMAP 75
Pt BKGD SATURATION 75

876 Index September 20, 2005

 2005, QNX Software Systems Index

Pt BKGD VERTICAL 72 name, color 88

Pt BLOCK CUA FOCUS 132 name, font 90
Pt BLOCKED 747, 759, 761 names 92
Pt BOTTOM ANCHORED BOTTOM 130 next/previous buttons,
Pt BOTTOM ANCHORED RELATIVE 129 color 91
Pt BOTTOM ANCHORED TOP 130 next/previous buttons,
Pt BROWSE MODE 110, 171, 227 displaying 89
PtButton 79 next/previous days,
armed displaying 90
color 80, 81 next/previous, day color 88
data 80, 81 next/previous, font 90
fill 80, 82 Pt ARG CALENDAR COLOR1
behavior 80 88
creating 79 Pt ARG CALENDAR COLOR2
label type 80 88
Pt ARG ARM COLOR 80, 81 Pt ARG CALENDAR COLOR3
Pt ARG ARM DATA 80, 81 88
Pt ARG ARM FILL 80, 82 Pt ARG CALENDAR COLOR4
Pt ARG LABEL TYPE 80 88
visual feedback 80 Pt ARG CALENDAR COLOR5
PtCalendar 86 88
date Pt ARG CALENDAR DATE
current 89, 93 89
selection callback 94 Pt ARG CALENDAR FLAGS
days 89
highlighted 91 Pt ARG CALENDAR FONT1
highlighted, color 88 90
highlighted, font 91 Pt ARG CALENDAR FONT2
name, color 88 90
name, font 91 Pt ARG CALENDAR FONT3
names 93 90
selected, color 93 Pt ARG CALENDAR FONT4
flags 89 91
grid, displaying 90 Pt ARG CALENDAR FONT5
month 91
current, day color 88 Pt ARG CALENDAR HIGHLIGHT
current, day font 90 91

September 20, 2005 Index 877

Index  2005, QNX Software Systems

Pt ARG CALENDAR MONTH BTN COLOR Pt CB DIVIDER DRAG 145

91 Pt CB FONT MODIFY 209
Pt ARG CALENDAR MONTH NAMES Pt CB MODIFY NOTIFY
92 643, 657
Pt ARG CALENDAR SEL COLOR Pt CB MODIFY VERIFY
93 644, 656
Pt ARG CALENDAR TIME T Pt CB MOTION NOTIFY
93 646
Pt ARG CALENDAR WDAY NAMES Pt CB MOTION VERIFY 646
93 Pt CB ONOFF NEW VALUE
Pt ARG CALENDAR YEAR BTN COLOR 478
94 Pt CB SCROLLED X 529
Pt CB CALENDAR SELECT Pt CB SCROLLED Y 529
94 Pt CB SCROLL MOVE 231,
year 540
color 88 Pt CB SLIDER MOVE 557
font 90 Pt CB TEXT CHANGED
next/previous buttons, 643, 657
color 94 PtTextModifyText() 656
next/previous buttons, Pt CB ACTIVATE
displaying 89 hotkeys 766
Pt CALENDAR DATE SELECTED 95 PtBasic 44, 48, 49
Pt CALENDAR MONTH BTNS 89 PtGroup 665
Pt CALENDAR MONTH SELECTED 95 PtMultiText 420
Pt CALENDAR SHOW GRID 90 PtNumericFloat 469
Pt CALENDAR SHOW NEXT 90 PtNumericInteger 476
Pt CALENDAR SHOW PREV 90 PtText 634, 650
Pt CALENDAR WDAY SELECTED 95 PtToggleButton 664
Pt CALENDAR YEAR BTNS 89 PtUpDown 752
Pt CALENDAR YEAR SELECTED 95 Pt CB ARM
PtCalenderSelectCallback t PtBasic 44, 50
95 PtMenuButton 369
PtCallback t 7 PtUpDown 752
PtCallbackInfo t 9 Pt CB BALLOONS 133
Pt CALLBACKS ACTIVE 759 Pt CB BLOCKED 765
Pt CB CLOCK TIME CHANGED Pt CB CALENDAR SELECT 94
105 Pt CB CBOX ACTIVATE 114

878 Index September 20, 2005

 2005, QNX Software Systems Index

Pt CB CBOX CLOSE 114 PtText 644, 656

Pt CB CLOCK TIME CHANGED Pt CB MOTION NOTIFY
105 PtMultiText 423
Pt CB DESTROYED 766 PtText 646
Pt CB DISARM Pt CB MOTION VERIFY
PtBasic 44, 51 PtMultiText 426
PtUpDown 752 PtText 646
Pt CB DIVIDER DRAG 145 Pt CB MSG BUTTON1 395
Pt CB FILTER 134 Pt CB MSG BUTTON2 395
Pt CB FONT MODIFY 209 Pt CB MSG BUTTON3 395
Pt CB FS BKGD HANDLER 169 Pt CB NUMERIC CHANGED
Pt CB FS SELECTION 170 PtNumericFloat 464
Pt CB FS STATE 171 PtNumericInteger 472
Pt CB GEN TREE INPUT 243 Pt CB ONOFF NEW VALUE 478
Pt CB GOT FOCUS Pt CB PRINT PROPS 496
PtBasic 51 Pt CB RAW 768
PtMultiText 422 Pt CB REALIZED 769
PtText 651 Pt CB REPEAT 54
Pt CB HOTKEY 766 Pt CB RESCALE 256, 272
Pt CB HTML ERROR 303 Pt CB RESIZE 136
Pt CB HTML FILE POST 304 Pt CB SCROLLED X 529
Pt CB HTML FILE PRE 304 Pt CB SCROLLED Y 529
Pt CB HTML IMAGE 305 Pt CB SCROLL MOVE
Pt CB LIST INPUT 343 PtGenList 231
Pt CB LOST FOCUS PtScrollbar 540
PtBasic 52 Pt CB SELECTION 340, 344
PtMultiText 422 Pt CB SLIDER MOVE 557
PtText 651 Pt CB TERM APP 593
Pt CB MENU Pt CB TERM FONT 595
enabling 761 Pt CB TERM INPUT 595, 618,
PtBasic 44, 53 619
PtMenuButton 369 Pt CB TERM OPTIONS 597
Pt CB MODIFY NOTIFY Pt CB TERM RESIZE 598
PtMultiText 423 Pt CB TERM RESIZED 599
PtText 643, 657 Pt CB TERM SCRLBK 600
Pt CB MODIFY VERIFY Pt CB TEXT CHANGED
PtMultiText 424 PtMultiText 423

September 20, 2005 Index 879

Index  2005, QNX Software Systems

PtText 643, 657 current setting 102

Pt CB TIMER ACTIVATE 661 offset 103
Pt CB TREE SELECTION 677 Pt ARG CLOCK FACE COLOR
Pt CB TREE STATE 678 100
Pt CB TTY DEVSIZE 736 Pt ARG CLOCK FACE OUTLINE COLOR
Pt CB TTY OUTPUT 737 100
Pt CB TTY TERMINATED 738 Pt ARG CLOCK FLAGS 100
Pt CB UNREALIZED 769 Pt ARG CLOCK FONT 101
Pt CB WINDOW 787 Pt ARG CLOCK HOUR 102
Pt CB WINDOW CLOSING 787 Pt ARG CLOCK HOUR COLOR
Pt CB WINDOW OPENING 788 102
Pt CB WINDOW TRANSPORT Pt ARG CLOCK HOUR OFFSET
789 102
Pt CHANGE ACTIVATE 420, 456, Pt ARG CLOCK MINUTE
634, 641, 650 102
Pt CLEAR 759 Pt ARG CLOCK MINUTE COLOR
Pt CLIP HIGHLIGHT 747, 759 103
PtClock 98 Pt ARG CLOCK MINUTE OFFSET
24-hour display 100 103
AM/PM indicator 101 Pt ARG CLOCK SECOND
analog 105 103
digital 105 Pt ARG CLOCK SECOND COLOR
face 103
color 100 Pt ARG CLOCK SECOND OFFSET
numbers, displaying 101 104
outline color 100 Pt ARG CLOCK SEP1 104
flags 100 Pt ARG CLOCK SEP1 COLOR
flicker, reducing 99 104
font 101 Pt ARG CLOCK SEP2 104
hour Pt ARG CLOCK SEP2 COLOR
color 102 105
current setting 102 Pt ARG CLOCK TYPE 105
leading zero, adding 101 Pt ARG FLAGS 105
offset 102 Pt CB CLOCK TIME CHANGED
LED/LCD 105 105
minute second
color 103 color 103

880 Index September 20, 2005

 2005, QNX Software Systems Index

current setting 103 closing from code 123

displaying 101 determining if open 113
offset 104 item, selected 113
separator items, maximum visible 113
character 104 items, number visible 120
color 104, 105 opening from code 124
time placing above text 113
changed callback 105 static 112
updating every second 101 types 109
type 105 maximizing width 113
Pt CLOCK 24 HOUR 100 Pt ARG CBOX BUTTON BORDER WIDTH
Pt CLOCK ANALOG 105 111
Pt CLOCK DIGITAL 105 Pt ARG CBOX BUTTON BOT BORDER COLOR
Pt CLOCK HOUR CHANGED 106 112
Pt CLOCK LED 105 Pt ARG CBOX BUTTON COLOR
Pt CLOCK MINUTE CHANGED 106 112
Pt CLOCK PAD HOURS 101 Pt ARG CBOX BUTTON TOP BORDER COLOR
Pt CLOCK SECOND CHANGED 106 112
Pt CLOCK SHOW AMPM 101 Pt ARG CBOX BUTTON WIDTH
Pt CLOCK SHOW NUMBERS 101 112
Pt CLOCK SHOW SECONDS 101 Pt ARG CBOX FLAGS 112
PtClockTimeCallback t 106 Pt ARG CBOX MAX VISIBLE COUNT
Pt CLOCK TRACK TIME 101 113
PtComboBox 109 Pt ARG CBOX SEL ITEM
behavior 110 113
convenience functions 121 Pt ARG VISIBLE COUNT
drop button 120
activation callback 114 Pt CB CBOX ACTIVATE 114
border width 111 Pt CB CBOX CLOSE 114
bottom border color 112 PtComboBoxListClose() 123
fill color 112 PtComboBoxListOpen() 124
suppressing 112 Pt COMBOBOX MAX WIDTH 113
top border color 112 Pt COMBOBOX OPEN 113
width 112 Pt COMBOBOX STATIC 112
flags 112 Pt COMBOBOX TOP 113
list PtCompound 125
close callback 114 Pt CONSUME EVENTS 758

September 20, 2005 Index 881

Index  2005, QNX Software Systems

PtContainer 128 Pt DAMAGE FAMILY 760

anchor flags 129, 131 Pt DAMAGE PARENT 758
anchor offsets 129, 130 PtDBContainer 139
balloons fill color 142
callback 133 image type 140
disabling 132 memory context type 140
popping up immediately 130 Pt ARG DB IMAGE TYPE
CUA 140
enabling 132 Pt ARG DB MEMORY CONTEXT TYPE
enabling arrow keys 132 140
preventing focusing 132 Pt ARG FILL COLOR 142
filter callback 134 Pt DEFAULT COLOR 430–432
flags 132 Pt DEFAULT FONT 429, 431
hotkeys, terminating searches Pt DELAY REALIZE 760
for 132 Pt DESTROYED 760
key events, processing as Pt DISABLE BALLOONS 132
hotkeys first 132 PtDivider 143
Pt ARG ANCHOR FLAGS bandwidth threshold 149
129, 131 drag outline, suppressing 144
Pt ARG ANCHOR OFFSETS dragging callback 145
129, 130 flags 144
Pt ARG AREA 131 group orientation 149
Pt ARG CONTAINER FLAGS in a list 223
132 offset 145
Pt ARG DIM 131 Pt ARG BANDWIDTH THRESHOLD
Pt ARG RESIZE FLAGS 130, 149
138 Pt ARG DIVIDER FLAGS
Pt CB BALLOONS 133 144
Pt CB FILTER 134 Pt ARG DIVIDER OFFSET
Pt CB RESIZE 136 145
reextent, forcing 132 Pt ARG DIVIDER SIZES 145
resize callback 136 Pt ARG FLAGS 145
PtContainerCallback t 136 Pt ARG GROUP ORIENTATION
PtContainerHold() 230, 761 149
Pt CONTINUE 8 Pt CB DIVIDER DRAG 145
Pt CURSOR VISIBLE 457, 641 resizing
Pt DAMAGED 760 both children 144

882 Index September 20, 2005

 2005, QNX Software Systems Index

preventing 144 files

sizes of realized children 145 hidden 165
PtDividerCallback t 146 information 157, 165
Pt DIVIDER INVISIBLE 144 listing 164
Pt DIVIDER NORESIZE 144 names, pattern for 164
Pt DIVIDER RESIZE BOTH 144 flags 164
Pt DOUBLE DASH LINE 546 items
Pt DOUBLE LINE 546 adding 178, 179
Pt DOUBLE ULINE 329 allocating 182
Pt EDITABLE 457, 641 collapsing 155, 171, 188
Pt EDIT ACTIVATE 420, 650 damaging 186
PtEllipse 151 expanding 155, 171, 189
height 151 expanding parents 187
Pt ARG DIM 151 freeing 190, 191
Pt ARG ORIGIN 151 freeing when collapsing 165
Pt ARG POINTS 151 getting all 181
width 151 getting current 192
Pt EMT AUTOINDENT 411 getting selected 193, 201
Pt EMT CHAR 414 images for 166
Pt EMT FORCED SCROLL 411 index of 195
Pt EMT FULL LINES 411 redrawing 186
Pt EMT NEWLINE 415 removing 196–198
Pt EMT SCROLL TO CURSOR 411 rereading 168
Pt EMT WORD 399, 414 root 199
Pt ENABLE CUA 132 scrolling to 203
Pt ENABLE CUA ARROWS 132 selecting 200, 202
Pt ETCHED IN 546 selection callback 170
Pt ETCHED OUT 546 selection, clearing 185
Pt ETCH HIGHLIGHT 747, 760 setting current 194
Pt EXTENDED MODE 171, 227 unselecting 204, 205
PtFileSel 154 keyboard seek mode 165
background handler 169 Pt ARG FS FILE SPEC 164
convenience functions 175 Pt ARG FS FLAGS 164
custom headers 157 Pt ARG FS FORMAT 165
directories, listing 164 Pt ARG FS IMAGES 166
events, processing Pt ARG FS REFRESH 168
pending 169 Pt ARG FS ROOT DIR 168

September 20, 2005 Index 883

Index  2005, QNX Software Systems

Pt CB FS BKGD HANDLER Pt FONTSEL AA CHECK 208

169 Pt FONTSEL ALL FONTS 207
Pt CB FS SELECTION 170 Pt FONTSEL BITMAP 207
Pt CB FS STATE 171 Pt FONTSEL FIXED 207
read error 165 Pt FONTSEL PROP 207
reading directories 158 Pt FONTSEL SAMPLE 208, 211
root directory 168 Pt FONTSEL SCALABLE 207
sample code 158 Pt FREE MEMORY 760
seeking files 165 PtFSAddAfter() 178
single-level mode 156, 165 PtFSAddFirst() 179
tree mode 156 PtFSAllItems() 181
PtFileSelBkgdCallback t PtFSAllocItem() 182
169 PtFSClearSelection() 185
PtFileSelCallback t 172 PtFSDamageItem() 186
PtFileSelItem t 155 Pt FS DIR CL 155, 167
Pt FLOAT ORIGIN 271 Pt FS DIR OP 155, 167
Pt FLOAT POS 270 Pt FS DLINK CL 155, 167
Pt FOCUS RENDER 760 Pt FS DLINK OP 155, 167
PtFontSel 206 Pt FS ERROR 156, 167
convenience functions 211 PtFSExpandParents() 187
dimensions 211 Pt FS FILE 155, 167
flags 207 Pt FS FLINK 155, 167
font PtFSFolderCollapse() 188
currently selected 208 PtFSFolderExpand() 189
families, filtering 207 PtFSFreeAllItems() 190
initial 208 PtFSFreeItems() 191
modified callback 209 Pt FS FREE ON COLLAPSE 165
Pt ARG DIM 211 PtFSGetCurrent() 192
Pt ARG FLAGS 209 PtFSGetSelIndexes() 193
Pt ARG FONT DISPLAY 207 PtFSGoto() 194
Pt ARG FONT FLAGS 207 PtFSItemIndex() 195
Pt ARG FONT NAME 208 Pt FS NEW DIR 155
Pt ARG FONT SAMPLE 208 Pt FS NEW ITEM 169
Pt ARG FONT SYMBOL 208 Pt FS OLD DIR 155
Pt CB FONT MODIFY 209 Pt FS OLD ITEM 169
required symbol 208 PtFSRemoveChildren() 196
sample text 208 PtFSRemoveItem() 197

884 Index September 20, 2005

 2005, QNX Software Systems Index

PtFSRemoveList() 198 Pt ARG GAUGE VALUE SUFFIX

PtFSRootItem() 199 215
Pt FS SEEK KEY 165 value
PtFSSelect() 200 current 215
PtFSSelectedItems() 201 displaying 213
PtFSSetSelIndexes() 202 inverting fill color 213
PtFSShow() 203 maximum 214
Pt FS SHOW DIRS 164 maximum, position of 213
Pt FS SHOW ERRORS 165 minimum 214
Pt FS SHOW FILES 164 prefix 215
Pt FS SHOW HIDDEN 165 suffix 215
Pt FS SINGLE LEVEL 165 vertical alignment 215
Pt FS STATE END 172 Pt GAUGE MAX ON BOTTOM 213
Pt FS STATE START 172 Pt GAUGE MAX ON LEFT 213
PtFSUnselect() 204 Pt GAUGE MAX ON RIGHT 213
PtFSUnselectNonBrothers() 205 Pt GAUGE MAX ON TOP 213
PtGauge 212 PtGenList 218
flags 213 balloon
font 213 adjusting for a column 240
horizontal alignment 214 creating 236
orientation 214 fill color 221
Pt ARG GAUGE FLAGS 213 for individual columns 223
Pt ARG GAUGE FONT 213 showing 223
Pt ARG GAUGE H ALIGN text color 221
214 when clipping occurs 223
Pt ARG GAUGE MAXIMUM blitting, disabling 223
214 browse mode 227
Pt ARG GAUGE MINIMUM column flags 221
214 column positions 222
Pt ARG GAUGE ORIENTATION compose selection modes,
214 defining 228
Pt ARG GAUGE V ALIGN convenience functions 235
215 events, consuming 223
Pt ARG GAUGE VALUE 215 extended mode 227
Pt ARG GAUGE VALUE PREFIX flags 222
215 font 224
inactivating 223

September 20, 2005 Index 885

Index  2005, QNX Software Systems

items Pt ARG LIST TOTAL HEIGHT

browsing 227 226
Ctrl-click 227 Pt ARG SCROLLBAR WIDTH
number of 224 226
number selected 226 Pt ARG SELECTION FILL COLOR
number visible 230 226
selected, color of 226 Pt ARG SELECTION MODE
selected, text color 230 227
selecting a range 227 Pt ARG SELECTION TEXT COLOR
selecting many 227 230
selecting one 227 Pt ARG TOP ITEM POS 230
Shift-click 227 Pt ARG VISIBLE COUNT
top one displayed 230 230
total height 226 Pt CB SCROLL MOVE 231
keyboard actions 219 PtDivider as child 218
mouse actions 219 adjusting size 223
multiple mode 227 range-select mode 227
Pt ARG BALLOON COLOR read-only 223
221 scroll callback 231
Pt ARG BALLOON FILL COLOR scroll rate 225
221 scrollbar
Pt ARG FLAGS 231 always 224
Pt ARG LIST COLUMN ATTR as required 224
221 color 218, 224
Pt ARG LIST COLUMN POS granting focus to 224
222 resizing 224
Pt ARG LIST FLAGS 218, resources 218, 224
222 width 226
Pt ARG LIST FONT 224 scrollbars 218
Pt ARG LIST ITEM COUNT selection mode 227
224 single-select mode 227
Pt ARG LIST SB RES 218, snapping to the number of
224 items 224
Pt ARG LIST SCROLL RATE text alignment 221
225 PtGenListCreateTextBalloon() 236
Pt ARG LIST SEL COUNT PtGenListSetColumnBalloon() 240
226 PtGenTree 241

886 Index September 20, 2005

 2005, QNX Software Systems Index

buttons Pt ARG GRAPHIC FLAGS

displaying 242, 248 270
displaying for root items 242 Pt ARG LINE CAP 271
convenience functions 247 Pt ARG LINE JOIN 271
flags 242, 248 Pt ARG LINE WIDTH 272
items Pt ARG ORIGIN 252, 253,
extending background to the 272
left 242 Pt ARG POINTS 252, 272
extending to the right 242 Pt CB RESCALE 256, 272
lines rescale callback 272
displaying 242, 248 PtGrid 276
displaying for root items 242 lines
mouse and key event cap style 278
callback 243 dash scaling 277
Pt ARG TREE FLAGS 242, dash style 277
248 horizontal, number of 277
Pt CB GEN TREE INPUT join style 278
243 vertical, number of 278
PtGenTreeInput t 243 width 279
Pt GETS FOCUS 725, 747, 760, Pt ARG DASH LIST 277
809, 810 Pt ARG DASH SCALE 277
Pt GHOST 761 Pt ARG GRID HORIZONTAL
PtGraphic 251 277
dash Pt ARG GRID VERTICAL
scaling 270 278
style 270 Pt ARG LINE CAP 278
flags 270 Pt ARG LINE JOIN 278
lines Pt ARG LINE WIDTH 279
cap style 271 PtGroup 281
join style 271 callbacks
width 272 activate 665
origin 252, 272 children
floating 271 aligning 284
points 252, 272 exclusive choice 282
position, floating 270 forcing equal height 283
Pt ARG DASH LIST 270 forcing equal size 282
Pt ARG DASH SCALE 270 forcing equal width 283

September 20, 2005 Index 887

Index  2005, QNX Software Systems

horizontal alignment 284 Pt GROUP EQUAL SIZE VERTICAL

no choice 282 283
spacing between 285 Pt GROUP EXCLUSIVE 282, 664
stretching horizontally 283 Pt GROUP HORIZONTAL 284
stretching vertically 283 Pt GROUP NO KEYS 282
vertical alignment 286 Pt GROUP NO KEY WRAP 283
flags 282 Pt GROUP NO KEY WRAP HORIZONTAL
horizontal wrapping, 283
preventing 283 Pt GROUP NO KEY WRAP VERTICAL
keys, preventing use of 282 283
number of rows and Pt GROUP NO SELECT ALLOWED 282
columns 284 Pt GROUP STRETCH FILL 283
orientation 284 Pt GROUP STRETCH HORIZONTAL 283
Pt ARG GROUP FLAGS Pt GROUP STRETCH VERTICAL 283
282, 664 Pt GROUP VERTICAL 284
Pt ARG GROUP HORZ ALIGN Pt HIGHLIGHTED 747, 761
284 PtHotkeyCallback t 11, 766
Pt ARG GROUP ORIENTATION Pt HOTKEY IGNORE MODS 11
284 Pt HOTKEYS FIRST 132
Pt ARG GROUP ROWS COLS Pt HOTKEY SYM 11
284 Pt HOTKEY TERMINATOR 132
Pt ARG GROUP SPACING PtHtml 289
285 border width 296
Pt ARG GROUP SPACING X convenience functions 308
285 cursor
Pt ARG GROUP SPACING Y busy 296
285 default 296
Pt ARG GROUP VERT ALIGN over a link 297
286 error callback 303
Pt CB ACTIVATE 665 flags 297
vertical wrapping, fonts
preventing 283 body text 303
Pt GROUP ASIS 284 heading level 1 297
Pt GROUP EQUAL SIZE 282 heading level 2 298
Pt GROUP EQUAL SIZE HORIZONTAL heading level 3 298
283 heading level 4 298
heading level 5 298

888 Index September 20, 2005

 2005, QNX Software Systems Index

heading level 6 298 Pt ARG HTML H2 FONT

HTML elements 290 298
HTML entities 293 Pt ARG HTML H3 FONT
HTML page 298
bottom margin 299 Pt ARG HTML H4 FONT
current 299 298
fill color 297 Pt ARG HTML H5 FONT
height 299 298
left margin 299 Pt ARG HTML H6 FONT
number of pages 301 298
right margin 300 Pt ARG HTML LINK COLOR
top margin 300 299
viewport position 300, 301 Pt ARG HTML PAGE BM
width 300 299
images 293 Pt ARG HTML PAGE H 299
link color 299 Pt ARG HTML PAGE LM
links, finding 309 299
page mode 297, 299, 301 Pt ARG HTML PAGE N 299
post-loading callback 304 Pt ARG HTML PAGE RM
preloading callback 304 300
preloading image callback 305 Pt ARG HTML PAGES 301
Pt ARG BORDER WIDTH Pt ARG HTML PAGE TM
296 300
Pt ARG HTML BORDER WIDTH Pt ARG HTML PAGE W 300
296 Pt ARG HTML PAGE X 300
Pt ARG HTML CURSOR BUSY Pt ARG HTML PAGE Y 301
296 Pt ARG HTML SCROLL COLOR
Pt ARG HTML CURSOR DEFAULT 301
296 Pt ARG HTML SCROLL FILL COLOR
Pt ARG HTML CURSOR LINK 301
297 Pt ARG HTML SCROLL HORIZONTAL
Pt ARG HTML FILL COLOR 302
297 Pt ARG HTML SCROLL VERTICAL
Pt ARG HTML FLAGS 297 302
Pt ARG HTML H1 FONT Pt ARG HTML SCROLL WIDTH
297 302

September 20, 2005 Index 889

Index  2005, QNX Software Systems

Pt ARG HTML TEXT FONT position 321, 323

303 text 321
Pt ARG HTML URL 303 text color 323
Pt CB HTML ERROR 303 creating 317
Pt CB HTML FILE POST flags 321, 326
304 font 317, 328
Pt CB HTML FILE PRE 304 horizontal alignment 318, 324
Pt CB HTML IMAGE 305 image
reloading, forcing 297 data 319, 325
scrollbars position 317, 323
height and width 302 line spacing 327
horizontal modes 302 margins
slider color 301 bottom 318, 327
trough color 301 left 318, 328
vertical modes 302 right 318, 328
title, finding 310 top 318, 328
URL (Universal Resource Pt ARG ACCEL KEY 323
Locator) 303 Pt ARG BALLOON COLOR
PtHtmlCallback t 303–305 323
PtHtmlLink() 309 Pt ARG BALLOON FILL COLOR
Pt HTML RELOAD 297 323
PtIcon 311 Pt ARG BALLOON POSITION
Pt IMAGE 81, 327 317, 321, 323
Pt INFLATE BALLOON 5, 133 Pt ARG HORIZONTAL ALIGNMENT
Pt IN FLUX 761 318, 324
Pt INHERIT COLOR 430–432 Pt ARG LABEL BALLOON
Pt INHERIT FONT 429, 431 324
Pt INSERT MODE 457, 641 Pt ARG LABEL DATA 319,
Pt INTERNAL HELP 758, 763 325
PtLabel 316 Pt ARG LABEL FLAGS 321,
accelerator key 323 326
backfilling text 326 Pt ARG LABEL TYPE 317,
balloons 326
customizing 324 Pt ARG LINE SPACING 327
enabling 326 Pt ARG MARGIN BOTTOM
enabling if clipped 326 318, 327
fill color 323

890 Index September 20, 2005

 2005, QNX Software Systems Index

Pt ARG MARGIN LEFT 318, checking existence of 356

328 deleting a range 353
Pt ARG MARGIN RIGHT deleting all 352
318, 328 deleting specific 354
Pt ARG MARGIN TOP 318, determining position of 357
328 displaying in columns 338
Pt ARG TEXT FONT 317, getting 339
328 number displayed 339
Pt ARG TEXT STRING 317, removing by position 358
321, 329 replacing 360
Pt ARG UNDERLINE1 329 replacing by position 359
Pt ARG UNDERLINE2 329 selected 343
Pt ARG UNDERLINE TYPE selecting by position 361
329 setting the current 355
Pt ARG VERTICAL ALIGNMENT showing by position 362
318, 330 spacing between 342
shifting when selected 326 unselecting 363
text 317, 329 mouse and key event
position 317, 323 callback 343
type 317, 326 Pt ARG ITEMS 340, 341
underline color 329 Pt ARG LIST BALLOON 341
underline type 329 Pt ARG LIST COLUMN POS
vertical alignment 318, 330 338
Pt LABEL SELECT SHIFT 326 Pt ARG LIST SPACING 342
Pt LEFT ANCHORED LEFT 130 Pt ARG MODIFY ITEMS
Pt LEFT ANCHORED RELATIVE 129 343
Pt LEFT ANCHORED RIGHT 129 Pt ARG SELECTION INDEXES
PtLine 333 343
Pt ARG ORIGIN 333 Pt ARG VISIBLE COUNT
Pt ARG POINTS 333 339, 348
PtList 337 Pt CB LIST INPUT 343
balloon function 341 Pt CB SELECTION 340, 344
convenience functions 349 PtDivider as child 338
creating 338 selection callback 340, 344
items selection policy
adding 351 browse 340
array of 340, 341 extended 340

September 20, 2005 Index 891

Index  2005, QNX Software Systems

multiple 340 PtListRemovePositions() 358

single 340 PtListReplaceItemPos() 359
PtListAddItems() 351 PtListReplaceItems() 360
Pt LIST BALLOON AS REQUIRED Pt LIST SCROLLBAR ALWAYS 218,
223 224
Pt LIST BALLOONS IN COLUMNS Pt LIST SCROLLBAR AS REQUIRED
223 218, 224
Pt LIST BOUNDARY KEY EVENTS Pt LIST SCROLLBAR AUTORESIZE
223 224
PtListCallback t 340, 345 Pt LIST SCROLLBAR GETS FOCUS
PtListColumn t 222 224
PtListColumnAttributes t Pt LIST SCROLL LIST 231
221 Pt LIST SCROLL SCROLLBAR 231
Pt LIST COLUMN CENTER 222 Pt LIST SELECTION BROWSE 171,
Pt LIST COLUMN DAMAGE ALWAYS 677
222 Pt LIST SELECTION CANCEL 171,
Pt LIST COLUMN LEFT 221 677
Pt LIST COLUMN RIGHT 222 Pt LIST SELECTION FINAL 171,
PtListDeleteAllItems() 352 677
PtListDeleteItemPos() 353 PtListSelectPos() 361
PtListDeleteItems() 354 Pt LIST SHOW BALLOON 223
PtListGotoPos() 355 PtListShowPos() 362
Pt LIST HEADER AUTORESIZE 223 Pt LIST SNAP 224
Pt LIST INACTIVE 223 PtListUnselectPos() 363
PtListInput t 343 PtMenu 364
Pt LIST ITEM ABOVE 238 activating via an event
Pt LIST ITEM BELOW 238 handler 370
Pt LIST ITEM CURRENT 238, 239, appearance, controlling 367
676 cascaded menus 371
Pt LIST ITEM DAMAGED 238 click-stay mode 366
PtListItemExists() 356 creating 367
PtListItemPos() 357 destroying 369
Pt LIST ITEM SELECTED 238, destroying on closing 377
239, 676 example 373
Pt LIST ITEM USED FLAGS 238 flags 365, 368, 371, 377
Pt LIST NOBLIT 223 items
Pt LIST NON SELECT 223 accelerators 364

892 Index September 20, 2005

 2005, QNX Software Systems Index

font 367, 378 Pt MENU AUTO 368, 377

forcing equal widths 377 PtMenuBar 382. See also PtMenu
hotkeys 364 anchoring 382
making selectable 365 children 382
selecting 366 PtMenuButton 386
spacing between 377 accelerator
widget types 364 displaying 388
labels 368 font 387
lifetime 368 key 386
menu bar 365 text 387
overriding parent menu 377 x offset 388
PhAB’s Menu module, using arm callback 369
instead 364 menu callback 369
populating 367 menu position 388
popup 365, 370 Pt ARG ACCEL FONT 387
positioning 369 Pt ARG ACCEL KEY 386
press-drag-release mode 366 Pt ARG ACCEL TEXT 387
Pt ARG BORDER WIDTH Pt ARG BUTTON TYPE 371,
377 387
Pt ARG FLAGS 367 Pt ARG OFFSET 388
Pt ARG MENU FLAGS 365, Pt CB ARM 369
367, 368, 371, 377 Pt CB MENU 369
Pt ARG MENU SPACING type 387
377 Pt MENU BUTTON 761
Pt ARG MENU TEXT FONT Pt MENU CHILD 365, 371, 377
367, 378 Pt MENU DOWN 388
Pt ARG MENU TITLE 367, Pt MENU RIGHT 371, 388
378 Pt MENU TEXT 388
Pt ARG MENU TITLE FONT Pt MENU TRANSIENT 368, 377
367, 378 PtMessage 392
pulldown 369 buttons
separators 368 binding Enter to 394
sizing 368 binding Esc to 394
submenus 365 callbacks 395
title 367, 378 default 394
title font 367, 378 keyboard shortcuts 393
Pt MENUABLE 44, 747, 761 labels 393

September 20, 2005 Index 893

Index  2005, QNX Software Systems

centering on parent 394 attributes

convenience functions 396 creating 435
flags 394 getting 412, 436
font 394 modifying 403, 412, 445,
Pt ARG MSG BUTTON1 393 447
Pt ARG MSG BUTTON2 393 character information,
Pt ARG MSG BUTTON3 393 getting 411, 440
Pt ARG MSG DEFAULT 394 color 429, 431
Pt ARG MSG ESCAPE 394 convenience functions 427
Pt ARG MSG FLAGS 394 cursor tracking, enabling 411
Pt ARG MSG FONT 394 dimensions 407
Pt ARG MSG TEXT 395 features 398
Pt ARG MSG TITLE 395 flags 410, 420
Pt CB MSG BUTTON1 395 flags, wrapping 414
Pt CB MSG BUTTON2 395 font 403, 429, 431
Pt CB MSG BUTTON3 395 got focus callback 422
text 395 hyperlinks 405
title 395 indentation, automatic 411
window widget, getting a pointer lines
to 397 bottom 410
PtMessageGetWindow() 397 displaying if there’s
Pt MSG CENTER ON PARENT 394 room 411
Pt MT BACKGROUND 412, 445, getting information 412, 440
448 number of 411
Pt MT BACKGROUND COLOR 412, number visible 411
445, 448 spacing 399
Pt MT FLAGS 413, 445, 448 top 414, 415
Pt MT FONT 412, 445, 448 lost focus callback 422
Pt MT FOREGROUND 412, 445, modify notify callback 423
448 modify verify callback 424
Pt MT QUERY CHAR 441 motion notify callback 423
Pt MT TAG 405, 412, 445, 448 motion verify callback 426
Pt MT TEXT COLOR 412, 445, 448 Pt ARG COLOR 400, 430,
PtMultiLines t 401, 413, 429 431
Pt MULTIPLE MODE 171, 227 Pt ARG DIM 407
PtMultiText 398 Pt ARG FILL COLOR 400,
activate callback 420 430, 432

894 Index September 20, 2005

 2005, QNX Software Systems Index

Pt ARG FLAGS 420 Pt ARG SCROLLBAR Y WIDTH

Pt ARG LINE SPACING 399 416
Pt ARG MULTITEXT BOTTOM LINE Pt ARG TEXT FLAGS 420
410 Pt ARG TEXT FONT 400,
Pt ARG MULTITEXT FLAGS 429, 431
410 Pt ARG TEXT STRING 400,
Pt ARG MULTITEXT NUM LINES 413
411 Pt ARG TEXT SUBSTRING
Pt ARG MULTITEXT NUM LINES VISIBLE 400
411 Pt CB ACTIVATE 420
Pt ARG MULTITEXT QUERY CHARACTER Pt CB GOT FOCUS 422
411 Pt CB LOST FOCUS 422
Pt ARG MULTITEXT QUERY LINE Pt CB MODIFY NOTIFY
407, 412 423
Pt ARG MULTITEXT RANGE ATTRIBUTES Pt CB MODIFY VERIFY 424
401, 403, 412 Pt CB MOTION NOTIFY
Pt ARG MULTITEXT ROWS 423
413 Pt CB MOTION VERIFY 426
Pt ARG MULTITEXT SEGMENTS Pt CB TEXT CHANGED
400, 401, 413 422, 423
Pt ARG MULTITEXT TABS rows, number of 413
414 scrollbars
Pt ARG MULTITEXT TOP LINE displaying 415, 416
414 height 416
Pt ARG MULTITEXT WRAP FLAGS position 415
399, 414 width 416
Pt ARG MULTITEXT X SCROLL POS scrolling, automatic 411
415 tab stops 414
Pt ARG MULTITEXT Y SCROLL POS text
415 changed callback 423
Pt ARG SCROLLBAR X DISPLAY inserting 402
400, 415 modifying 447
Pt ARG SCROLLBAR X HEIGHT multisegment 413
416 ranges of 401
Pt ARG SCROLLBAR Y DISPLAY setting 400
400, 416 setting attributes 401
wrapping 399

September 20, 2005 Index 895

Index  2005, QNX Software Systems

carriage return 415 Pt ARG NUMERIC FLAGS

end of line 414 454
word break 414 Pt ARG NUMERIC PREFIX
PtMultiTextAttributes t 455
431 Pt ARG NUMERIC SPACING
PtMultiTextCallback t 404, 455
433 Pt ARG NUMERIC SUFFIX
PtMultiTextControl t 404, 455
412, 433 Pt ARG NUMERIC TEXT BORDER
PtMultiTextCreateAttributes() 435 455, 456
PtMultiTextGetAttributes() 436 Pt ARG NUMERIC TEXT BOT BORDER COLOR
PtMultiTextInfo t 433 456
PtMultiTextInfo() 440 Pt ARG NUMERIC TEXT FILL COLOR
PtMultiTextLine t 407, 443 456
PtMultiTextModifyAttributes() 403, Pt ARG NUMERIC TEXT FLAGS
445 456
PtMultiTextModifyText() 400–402, Pt ARG NUMERIC TEXT FONT
447 457
PtMultiTextQuery t 407, 411, Pt ARG NUMERIC TEXT TOP BORDER COLOR
412, 449 457
PtMultiTextSegment t 451 Pt ARG NUMERIC UPDOWN BORDER WIDTH
Pt NOLINE 546 457
Pt NO ULINE 329 Pt ARG NUMERIC UPDOWN WIDTH
PtNumeric 453 458
buttons replace mode 457
border width 457 spacing 455
displaying 454 text
width 458 autohighlighting 454
callbacks border color, bottom 456
activate, invoking when losing border color, top 457
focus 456 border width 455
cursor, displaying 457 color 456
editable 457 fill color 456
flags 454, 456 font 457
highlighting hexadecimal 454
when given focus 457 inserting commas 454
insert mode 457 prefix 455

896 Index September 20, 2005

 2005, QNX Software Systems Index

suffix 455 Pt CB ACTIVATE 476

wrapping 454 Pt CB NUMERIC CHANGED
Pt NUMERIC AUTO HIGHLIGHT 454 472
Pt NUMERIC CHANGED 464, 472 value
Pt NUMERIC ENABLE UPDOWN 454 changed callback 472
PtNumericFloat 462 current 472
activate callback 469 hexadecimal 470
increment 463 maximum 471
precision 464 minimum 471
Pt ARG NUMERIC INCREMENT PtNumericIntegerCallback t
463 472
Pt ARG NUMERIC MAX 463 Pt NUMERIC UPDOWN ACTIVATE 464,
Pt ARG NUMERIC MIN 463 472
Pt ARG NUMERIC PRECISION Pt NUMERIC UPDOWN REPEAT 464,
464 472
Pt ARG NUMERIC VALUE Pt NUMERIC USE SEPARATORS 454
464 Pt NUMERIC WRAP 454
Pt CB ACTIVATE 469 Pt OBSCURED 761
Pt CB NUMERIC CHANGED PtOnOffButton 477
464 Pt ARG FLAGS 478
value Pt ARG ONOFF STATE 478
changed callback 464 Pt CB ONOFF NEW VALUE
current 464 478
maximum 463 Pt OPAQUE 761
minimum 463 PtPane 482
PtNumericFloatCallback t PtPixel 486
465 Pt ARG POINTS 486
Pt NUMERIC HEXADECIMAL 454 PtPolygon 489
PtNumericInteger 470 closed 490
activate callback 476 filled 491
increment 471 flags 489, 490
Pt ARG NUMERIC INCREMENT outlined 490
471 Pt ARG ORIGIN 489
Pt ARG NUMERIC MAX 471 Pt ARG POINTS 489
Pt ARG NUMERIC MIN 471 Pt ARG POLYGON FLAGS
Pt ARG NUMERIC VALUE 489, 490
472 relative coordinates 490

September 20, 2005 Index 897

Index  2005, QNX Software Systems

stroked 490 Pt PRINTSEL RETURN 496, 497

Pt POP BALLOON 5, 133 Pt PROCREATED 761
PtPositionMenu() 369 Pt RANGE MODE 171, 227, 677
PtPrintSel 494 not supported
Collate Method button, byPtTreeUnselect() 723
disabling 496 PtRaw 501
convenience functions 499 clipping
Copies field, disabling 496 restoring 504
dimensions 499 setting 502
flags 495, 499 color 503
page range connect function 505
disabling 496 custom widgets 501
disabling Selection damage 501
button 496 data model 502
panes, displaying all 495 data, user-defined 502
Preview button, disabling 496 drawing
print context 495 function 502
print properties callback 496 drawing function 506
Properties button, example 504
enabling 495 extent function 506
Pt ARG DIM 499 fill color 503
Pt ARG PRINT CONTEXT initialization function 506
495 Pt ARG COLOR 503
Pt ARG PRINT FLAGS 495, Pt ARG FILL COLOR 503
499 Pt ARG RAW CONNECT F
Pt CB PRINT PROPS 496 505
Pt PRINTSEL ADDNEW 496, 497 Pt ARG RAW DRAW F 502,
Pt PRINTSEL ALL PANES 495, 499 506
Pt PRINTSEL NO COLLATE 496 Pt ARG RAW EXTENT F
Pt PRINTSEL NO COPIES 496 506
Pt PRINTSEL NO PAGE RANGE 496 Pt ARG RAW INIT F 506
Pt PRINTSEL NO PREVIEW 496 Pt ARG USER DATA 502
Pt PRINTSEL NO SELECT RANGE redrawing 501
496 scaling 503
Pt PRINTSEL PROP APP 495 translation
Pt PRINTSEL PROPERTIES 496, restoring 504
497 setting 503

898 Index September 20, 2005

 2005, QNX Software Systems Index

PtRawCallback t 13, 768 Pt ARG REGION PARENT

Pt REALIZED 761 518
Pt REALIZING 762 Pt ARG REGION SENSE
PtRect 509 518
dimensions 509 region
points 509 in front 517
position 509 parent 518
Pt ARG DIM 509 resources, changing 514
Pt ARG POINTS 509 sensitivity 518
Pt ARG POS 509 REGION 762
Pt
Pt ARG RECT ROUNDNESS RESIZE X ALWAYS 763
Pt
509, 510 RESIZE X AS REQUIRED 763
Pt
rounding corners 509, 510 RESIZE X BITS 764
Pt
PtRegion 513 RESIZE X INITIAL 764
Pt
data 514 RESIZE XY ALWAYS 764
Pt
flags 516 RESIZE XY AS REQUIRED 764
Pt
handle 517 RESIZE XY BITS 764
Pt
input group 517 RESIZE XY INITIAL 764
Pt
instantiation 513 RESIZE Y ALWAYS 764
Pt
opacity 517 RESIZE Y AS REQUIRED 764
Pt
owner 518 RESIZE Y BITS 764
Pt
Pt ARG REGION DATA 514 RESIZE Y INITIAL 764
Pt
Pt ARG REGION FIELDS RIGHT ANCHORED LEFT 130
Pt
514 Pt RIGHT ANCHORED RELATIVE 129
Pt ARG REGION FLAGS Pt RIGHT ANCHORED RIGHT 129
516 PtScrollArea 521
Pt ARG REGION HANDLE anchors 524
517 arrow keys, ignoring 526
Pt ARG REGION INFRONT displayed portion,
517 position 527, 528
Pt ARG REGION INPUT GROUP flags 526
517 layout 524
Pt ARG REGION OPAQUE Pt ARG AREA 522, 527
517 Pt ARG FLAGS 529
Pt ARG REGION OWNER Pt ARG SCROLL AREA FLAGS
518 526

September 20, 2005 Index 899

Index  2005, QNX Software Systems

Pt ARG SCROLL AREA INCREMENT X Pt SCROLL AREA TRACK FOCUS 526

526 PtScrollbar 534
Pt ARG SCROLL AREA INCREMENT Y arrow buttons, displaying 539
527 bandwidth threshold 544
Pt ARG SCROLL AREA MAX X current position 540
522, 527 displaying arrow buttons 540
Pt ARG SCROLL AREA MAX Y flags 539
522, 527 handle length
Pt ARG SCROLL AREA POS X current 540
527 minimum 538
Pt ARG SCROLL AREA POS Y increment
528 page 539
Pt ARG SCROLLBAR X DISPLAY step 537
522, 528 inverted 539
Pt ARG SCROLLBAR X HEIGHT keyboard actions 536
528 maximum value 538
Pt ARG SCROLLBAR Y DISPLAY placement of 537
522, 529 minimum value 538
Pt ARG SCROLLBAR Y WIDTH mouse actions 535
529 orientation 538, 539
Pt CB SCROLLED X 529 Pt ARG BANDWIDTH THRESHOLD
Pt CB SCROLLED Y 529 544
resize policy 524 Pt ARG DIRECTION 537
scrollbars Pt ARG FLAGS 540
displaying 522, 528, 529 Pt ARG INCREMENT 537
height 528 Pt ARG MAXIMUM 538
increment 526, 527 Pt ARG MINIMUM 538
scrolled callback 529 Pt ARG MIN SLIDER SIZE
width 529 538
scrolling Pt ARG ORIENTATION 538
control 523 Pt ARG PAGE INCREMENT
notification 523 539
to focused widget 526 Pt ARG SCROLLBAR FLAGS
size 539
physical 522 Pt ARG SCROLL POSITION
virtual 522, 527 540
Pt SCROLL AREA IGNORE KEYS 526 Pt ARG SHOW ARROWS 540

900 Index September 20, 2005

 2005, QNX Software Systems Index

Pt ARG SLIDER SIZE 539, Pt SELECTION MODE TOGGLE 229

540 Pt SELECT NOREDRAW 762
Pt CB SCROLL MOVE 540 PtSeparator
rendering as if focused 539 flags 546
scrolled callback 540 orientation 546
PtScrollbarCallback t 530 Pt ARG SEP FLAGS 546
Pt SCROLLBAR FOCUSED 539 Pt ARG SEP TYPE 546
Pt SCROLLBAR HORIZONTAL 539 type 546
Pt SCROLLBAR INVERTED 539 PtSET 664, 762
Pt SCROLLBAR SHOW ARROWS 539 PtSHOW BALLOON 321, 326
Pt SCROLL DECREMENT 232, PtSHOW VALUE 213
530, 541 PtSINGLE DASH LINE 546
Pt SCROLL DRAGGED 232, 530, PtSINGLE LINE 546
541 PtSINGLE MODE 171, 227
Pt SCROLL INCREMENT 232, 530, PtSINGLE ULINE 329
541 PtSlider
Pt SCROLL PAGE DECREMENT 232, dimensions 557
530, 541 flags 552
Pt SCROLL PAGE INCREMENT 232, handle
530, 541 direction 552
Pt SCROLL RELEASED 232, 530, height 553
541 image 552, 553
Pt SCROLL SET 232, 541 width 553
Pt SCROLL TO MAX 232, 530, 541 increment 553
Pt SCROLL TO MIN 232, 530, 541 increment, multiple 554
Pt SELECTABLE 44, 365, 367, 420, keyboard actions 550
634, 650, 762 label
Pt SELECTION MODE AUTO 229 bottom/right 553
Pt SELECTION MODE MULTIPLE 228 color, bottom/right 554
Pt SELECTION MODE NOCLEAR 229 color, top/left 554
Pt SELECTION MODE NOFOCUS 229 top/left 554
Pt SELECTION MODE NOMOVE 228 mouse actions 549
Pt SELECTION MODE NONE 228 movement callback 557
Pt SELECTION MODE NOREST 228 orientation 555
Pt SELECTION MODE NOSCROLL 228 Pt ARG DIM 557
Pt SELECTION MODE RANGE 228 Pt ARG FLAGS 557
Pt SELECTION MODE SINGLE 228 Pt ARG SLIDER FLAGS 552

September 20, 2005 Index 901

Index  2005, QNX Software Systems

Pt ARG SLIDER HANDLE HEIGHT etched in 552

553 etched out 552
Pt ARG SLIDER HANDLE WIDTH on bottom 552
553 on left 552
Pt ARG SLIDER IMAGE 553 on right 552
Pt ARG SLIDER INCREMENT on top 552
553 touching trough 552
Pt ARG SLIDER LABEL BR ticks, major
553 color 555
Pt ARG SLIDER LABEL BR COL length 556
554 number of 555
Pt ARG SLIDER LABEL TL ticks, minor
554 color 556
Pt ARG SLIDER LABEL TL COL length 556
554 number of 556
Pt ARG SLIDER MULTIPLE trough
554 color 556
Pt ARG SLIDER ORIENTATION size 557
555 PtSliderCallback t 557
Pt ARG SLIDER TICK MAJOR COL Pt SLIDER IMAGE 552
555 Pt SLIDER MIN ON BOTTOM 555
Pt ARG SLIDER TICK MAJOR DIV Pt SLIDER MIN ON LEFT 555
555 Pt SLIDER MIN ON RIGHT 555
Pt ARG SLIDER TICK MAJOR LEN Pt SLIDER MIN ON TOP 555
556 Pt SLIDER POINT DOWN 552
Pt ARG SLIDER TICK MINOR COL Pt SLIDER POINT LEFT 552
556 Pt SLIDER POINT RIGHT 552
Pt ARG SLIDER TICK MINOR DIV Pt SLIDER POINT UP 552
556 PtTab 561
Pt ARG SLIDER TICK MINOR LEN displaying upside down 562
556 flags 562
Pt ARG SLIDER TROUGH COL Pt ARG TAB FLAGS 562
556 typical usage 561
Pt ARG SLIDER TROUGH SIZE Pt TAB UPSIDE DOWN 562
557 Pt TERM ANCHOR PARENT HEIGHT
Pt CB SLIDER MOVE 557 589
ticks

902 Index September 20, 2005

 2005, QNX Software Systems Index

Pt TERM ANCHOR PARENT WIDTH cursor

589 blinking 584
Pt TERM ANCHOR WINDOWS ONLY not checking for speed 584
589 position 583
Pt TERM COLOR MODE 581 timer 584
Pt TERM CTRLBRK INPUT 596 escape sequences 588
Pt TERM CURSOR ALWAYS 584 flags 583, 584
Pt TERM CURSOR NEVER 584 font
Pt TERM CURSOR NOSPEEDCHK 584 changed callback 595
Pt TERM CURSOR ON FOCUS 584 enabling escape
Pt TERM CURSOR TIMER 584 sequences 589
PtTerminal 566 index 568, 585
ANSI protocol 589 list of 568, 585
application window state 578 maintaining widget size 589
callback 593 name 568, 585
bandwidth, not checking 585 setting via keyboard 589
blitting 584 size 586
character sets 569, 580 verifying 612
creating translation function reentrancy 570
tables 609 geometry 570
characters, outputting 620 input callback 595
clipboard line-editing keys, getting 614
copying to 608 margins 586
pasting from 618 name, getting 617
clipped, assuming widget options 588
isn’t 584 changed callback 597
color disabling 588
coding 575 protocol 588
mode 581 Pt ARG AREA 570, 571
table 581 Pt ARG BANDWIDTH THRESHOLD
columns 575, 603
current 583 Pt ARG DIM 570–572, 574
maximum number of 586 Pt ARG FILL COLOR 603
minimum number of 587 Pt ARG MARGIN HEIGHT
number of 582 570–572, 586
console emulation 574 Pt ARG MARGIN WIDTH
convenience functions 603 570–572, 586

September 20, 2005 Index 903

Index  2005, QNX Software Systems

Pt ARG TERM APP 578 Pt ARG TERM MINCOLS

Pt ARG TERM CHARSETS 573, 587
570, 580 Pt ARG TERM MINROWS
Pt ARG TERM COLOR MODE 573, 587
581 Pt ARG TERM MINSIZE
Pt ARG TERM COLOR TABLE 573, 588, 598
575, 581 Pt ARG TERM OPTIONS
Pt ARG TERM COLS 570, 588
571, 582, 598, 599 Pt ARG TERM OPTMASK
Pt ARG TERM CONSOLE 588
574, 582 Pt ARG TERM PROTOCOL
Pt ARG TERM CUR COL 588
583 Pt ARG TERM RESIZE FL
Pt ARG TERM CUR POS 589
583 Pt ARG TERM RESIZE FUN
Pt ARG TERM CUR ROW 570, 589
583 Pt ARG TERM RESIZE STR
Pt ARG TERM CURSOR FLAGS 570, 573, 590
583 Pt ARG TERM ROWS 570,
Pt ARG TERM DRAW MODES 571, 590, 598, 599
575, 584 Pt ARG TERM SCRLBK COUNT
Pt ARG TERM FONT 568, 590
570, 571, 585 Pt ARG TERM SCRLBK LIMIT
Pt ARG TERM FONT INDEX 590
568, 570, 585 Pt ARG TERM SCRLBK POS
Pt ARG TERM FONT LIST 591
568, 585 Pt ARG TERM SCROLL 575,
Pt ARG TERM FONT SIZE 591
586 Pt ARG TERM SELECTION
Pt ARG TERM MARGINS 591
570, 572, 574, 586 Pt ARG TERM SIZE
Pt ARG TERM MAXCOLS 570–572, 593, 598, 599
574, 586 Pt ARG TERM VISUAL BELL
Pt ARG TERM MAXROWS 593
574, 587 Pt CB TERM APP 593
Pt ARG TERM MAXSIZE Pt CB TERM FONT 595
574, 587, 598

904 Index September 20, 2005

 2005, QNX Software Systems Index

Pt CB TERM INPUT 595, selection

618, 619 current 591
Pt CB TERM OPTIONS 597 getting current 616
Pt CB TERM RESIZE 598 pasting current 619
Pt CB TERM RESIZED 599 size limits 573
Pt CB TERM SCRLBK 600 video memory 574, 582
QNX 4 protocol 589 visual bell 593
redrawing word, selecting 622
always 584 PtTerminalAppState t 578
on first scroll 584 PtTerminalCharset t 605
resizing 570 PtTerminalCharsets t 605
adjusting after 572 PtTerminalCopy() 608
flags 589 PtTerminalCreateCsXlat() 609
hint 590 PtTerminalDefaultCharsets() 611
parent widget 589 PtTerminalFont() 612
post-resize callback 599 PtTerminalFontChange t 595
pre-resize callback 598 PtTerminalGetKeys() 614
resize function 589 PtTerminalGetSelection() 616
resize function, default 573 PtTerminalInput t 596
rows PtTerminalName() 617
current 583 PtTerminalOptionChange t
maximum number of 587 597
minimum number of 587 PtTerminalPasteClipboard() 618
number of 590 PtTerminalPasteSelection() 619
screen size 593 PtTerminalPut() 620
maximum 587 PtTerminalPutc() 620
minimum 588 PtTerminalPuts() 620
scrollback buffer PtTerminalRowCol t 583
callback 600 PtTerminalScrlbkCb t 600
maximum number of PtTerminalSelectWord() 622
lines 590 PtTerminalSizeChange t 598,
number of lines saved 590 599, 737
position in 591 Pt TERM KBFONT 568, 589
scrolling optimization 575, Pt TERM KBFORCE 568, 589
584 Pt TERM KEYBOARD INPUT 596
scrolls, maximum number Pt TERM MOUSE INPUT 596
delayed 591 Pt TERM OPFONT 568, 589

September 20, 2005 Index 905

Index  2005, QNX Software Systems

Pt TERM PASTE INPUT 596 highlighting

Pt TERM PASTE NF INPUT 596 background color 642
Pt TERM PROTOCOL INPUT 596 text color 642
Pt TERM SCROLL NOBLIT 584 when given focus 642
Pt TERM SCROLL NOHWCHK 584 input filter 639
Pt TERM SCROLL NOSPEEDCHK 575, insert mode 641
585 maximum length 640
Pt TERM SCROLL NOVISCHK 584 modify-notify callback 643
Pt TERM SCROLL RFSH 584 modify-verify callback 644
Pt TERM SELECTING 592 modifying the contents of 656
Pt TERM SELECTION ALWAYS 592 motion-notify callback 646
Pt TERM SELECTION BLOCK 591 motion-verify callback 646
Pt TERM SELECTION FIRST KEEP Pt ARG COLUMNS 638
592 Pt ARG CURSOR POSITION
Pt TERM SELECTION FLAGS KEEP 639
592 Pt ARG DIM 638
Pt TERM SELECTION LAST KEEP Pt ARG EDIT MASK 639
592 Pt ARG FLAGS 634, 643,
Pt TERM SELECTION NEVER 592 644, 646, 650, 656
Pt TERM SELECTION NONE 591 Pt ARG MAX LENGTH 640
Pt TERM SELECTION STREAM 592 Pt ARG SELECTION RANGE
Pt TERM SELECTION TYPE KEEP 640
592 Pt ARG TEXT CURSOR WIDTH
PtText 623 641
activate callback 650 Pt ARG TEXT FLAGS 634,
invoking when losing 641, 650
focus 641 Pt ARG TEXT HIGHLIGHT BACKGROUND COLOR
changed callback 643 642
columns Pt ARG TEXT HIGHLIGHT TEXT COLOR
number of 638 642
convenience functions 652 Pt ARG TEXT SUBSTRING
cursor position 639 642
cursor width 641 Pt CB ACTIVATE 634, 650
cursor, displaying 641 Pt CB GOT FOCUS 651
edit mask 639 Pt CB LOST FOCUS 651
editable 641 Pt CB MODIFY NOTIFY
flags 634, 641, 650 643, 657

906 Index September 20, 2005

 2005, QNX Software Systems Index

Pt CB MODIFY VERIFY Pt ARG TIMER REPEAT

644, 656 661
Pt CB MOTION NOTIFY Pt CB TIMER ACTIVATE
646 661
Pt CB MOTION VERIFY 646 repetition time 661
Pt CB TEXT CHANGED Pt TOGGLE 762
643, 657 Pt CB ACTIVATE 49
replace mode 641 PtToggleButton 663
selection “set”
getting current 655 background color 667
range 640 background color,
setting 658 enabling 667
substring, getting or checking to see if 664
setting 642 activate callback 664
Pt TEXT AUTO HIGHLIGHT 457, creating 663
642 exclusive choice 664
PtTextCallback t 404, grouping 664
421–423, 425, 426, indicator
644–647, 651, 653 depth 666
PtTextControl t 404, 653 fill color 666
PtTextControlInfo t 653 height 666
PtTextGetSelection() 403, 655 types 663, 666
Pt TEXT IMAGE 327 width 667
PtTextModifyText() 400–402, 656 Pt ARG FLAGS 664
PtTextSetSelection() 658 Pt ARG INDICATOR COLOR
Pt TICKS ETCHED IN 552 666
Pt TICKS ETCHED OUT 552 Pt ARG INDICATOR DEPTH
Pt TICKS ON BOTTOM 552 666
Pt TICKS ON LEFT 552 Pt ARG INDICATOR HEIGHT
Pt TICKS ON RIGHT 552 666
Pt TICKS ON TOP 552 Pt ARG INDICATOR TYPE
Pt TICKS TOUCH TROUGH 552 666
PtTimer 660 Pt ARG INDICATOR WIDTH
expiration callback 661 667
initial time 661 Pt ARG SET COLOR 667
Pt ARG TIMER INITIAL 661 Pt ARG SET FILL 667
Pt ARG SPACING 668

September 20, 2005 Index 907

Index  2005, QNX Software Systems

Pt ARG USER DATA 665 selection, getting 702, 718

Pt CB ACTIVATE 664 selection, setting 720
spacing 668 showing 721
user-defined data 665 unselecting 723
Pt TOP ANCHORED BOTTOM 129 unselecting nonbrothers 724
Pt TOP ANCHORED RELATIVE 129 Pt ARG LIST COLUMN POS
Pt TOP ANCHORED TOP 130 672
PtTree 671 Pt ARG SELECTION MODE
balloon 677, 679
function 675 Pt ARG TREE BALLOON
location 682 675
columns 672 Pt ARG TREE FLAGS 682
convenience functions 683 Pt ARG TREE IMAGES 673,
flags 682 676
images 673, 676 Pt ARG TREE IMGMASK
adding 690 676
mask 676 Pt CB TREE SELECTION
selecting 676 677
items Pt CB TREE STATE 678
adding after 686 PtDivider as child 672
adding first 688 selection callback 677
allocating 673, 693 selection mode 677, 679
collapsing 696 state-change callback 678
current, getting 701 PtTreeAddAfter() 686
current, setting 704 PtTreeAddFirst() 688
expanding 697 PtTreeAddImages() 690
freeing 700 PtTreeAllItems() 691
freeing all 699 PtTreeAllocItem() 693
getting all 691 Pt TREE BALLOON ON IMAGE 682
index, getting 707 Pt TREE BALLOON ON TREE 682
modifying 708 PtTreeCallback t 677
removing 712, 714 PtTreeClearSelection() 695
removing children 710 PtTreeCollapse() 696
root item, getting 716 Pt TREE COLLAPSING 172, 678
scrolling to 704 PtTreeExpand() 697
selecting 717 Pt TREE EXPANDING 172, 678
selection, clearing 695 PtTreeFreeAllItems() 699

908 Index September 20, 2005

 2005, QNX Software Systems Index

PtTreeFreeItems() 700 command 730

PtTreeGetCurrent() 701 convenience functions 742
PtTreeGetSelIndexes() 702 device
PtTreeGoto() 704 pathname 734
Pt TREE HAS BUTTONS 242, 248 resized callback 736
Pt TREE HAS LINES 242 resizing automatically 732
Pt TREE ITEM EXPANDABLE 179, size 731
248, 677 size, limiting to terminal 733
Pt TREE ITEM EXPANDED 249, size, same as terminal 733
677 environment variables,
PtTreeItemIndex() 707 modifying 731, 733
PtTreeModifyItem() 708 exit status 731
PtTreeRemoveChildren() 710 file descriptor 732
PtTreeRemoveItem() 712 master 734
PtTreeRemoveList() 714 set 732
PtTreeRootItem() 716 flags 732
Pt TREE ROOT LINES 242, 248 LINES 731
PtTreeSelect() 717 output callback 737
PtTreeSelectedItems() 718 Photon pulses, priority 735
PtTreeSetSelIndexes() 720 process
PtTreeShow() 721 arguments 729
Pt TREE TO LEFT 242 ID 735
Pt TREE TO RIGHT 242 terminated callback 738
PtTreeUnselect() 723 program name, using asargv[0]
PtTreeUnselectNonBrothers() 724 733
PtTty 725 pseudo-tty device 735
argv[0], using program name Pt ARG BANDWIDTH THRESHOLD
as 733 742
bandwidth threshold 742 Pt ARG FLAGS 725
buffer 730 Pt ARG TTY ARGV 729
size 730 Pt ARG TTY BUFFER 730
using 733 Pt ARG TTY BUFLEN 730
characters Pt ARG TTY CMD 729, 730
number written to Pt ARG TTY DEVSIZE 731
device 734 Pt ARG TTY EXIT STATUS
to be written to device 733 731, 738
COLUMNS 731 Pt ARG TTY FD 732

September 20, 2005 Index 909

Index  2005, QNX Software Systems

Pt
ARG TTY FDSET 732 color, right 746
ARG TTY FLAGS 732
Pt color, top 749
ARG TTY INPUT 733
Pt inner, customizing 748
ARG TTY INPUT WRITTEN
Pt roundness 748
734 buttons
Pt ARG TTY MFD 734 images, armed 745
Pt ARG TTY PATH 734 images, normal 746
Pt ARG TTY PID 730, 735 spacing between 749
Pt ARG TTY PRI 735 events, blocking 747
Pt ARG TTY PSEUDO 735 flags 747
Pt ARG TTY SPAWN OPTIONS focus, granting 747
736 highlighting
Pt CB TTY DEVSIZE 736 clipping 747
Pt CB TTY OUTPUT 737 enabling 747
Pt CB TTY TERMINATED etched 747
738 margin
shell, returning name of 743 height 748
spawn options 736 width 748
TERM 731 orientation 749
widget, resizing Pt ARG FLAGS 748, 751
automatically 733 Pt ARG UPDOWN ARM DATA BOTTOM
Pt TTY ARGV0 729, 730, 733 745
Pt TTY BUF PRIVATE 733 Pt ARG UPDOWN ARM DATA LEFT
Pt TTY DEVFORCE 733 745
Pt TTY DEVLIMIT 733 Pt ARG UPDOWN ARM DATA RIGHT
Pt TTY DEVRESIZE 732 745
PtTtyOutput t 737 Pt ARG UPDOWN ARM DATA TOP
Pt TTY SETENV 731, 733 745
PtTtyShell() 743 Pt ARG UPDOWN BOTTOM BORDER COLOR
Pt TTY TERMRESIZE 733 746
Pt ULINE ETCHED IN 329 Pt ARG UPDOWN DATA BOTTOM
Pt ULINE ETCHED OUT 329 746
PtUpDown 744 Pt ARG UPDOWN DATA LEFT
background color 746 746
borders Pt ARG UPDOWN DATA RIGHT
color, bottom 746 746
color, left 749

910 Index September 20, 2005

 2005, QNX Software Systems Index

Pt ARG UPDOWN DATA TOP color 756

746 type 757
Pt ARG UPDOWN FILL COLOR damage
746 indicating for family 760
Pt ARG UPDOWN FLAGS indicating for widget 760
747 propagating to parent 758
Pt ARG UPDOWN HIGHLIGHT ROUND destroyed callback 766
748 destruction, marked for 760
Pt ARG UPDOWN MARGIN HEIGHT dimensions 754, 758
748 etched highlighting 760
Pt ARG UPDOWN MARGIN WIDTH events, consuming 758
748 extended flags 758
Pt ARG UPDOWN ORIENTATION extent, preventing intersections
749 with 759
Pt ARG UPDOWN SPACING flags 759
749 flux 761
Pt ARG UPDOWN TOP BORDER COLOR focus, granting 760
749 ghosting 761
Pt CB ACTIVATE 752 height 754, 758
Pt CB ARM 752 help information 758, 763
Pt CB DISARM 752 highlighting
right-mouse-button clicks, automatically 759
making responsive to 747 clipping corners 759
Pt VALUE XOR 213 requesting 761
PtWidget 753 hotkey callback 766
“set” state 762 memory, freeing
activation by any mouse automatically 760
button 759 menu button 761
area 754 menuable 761
autohighlighting 759 obscured 761
blocked callback 765 opaque 761
blocking 759 position 754, 763
border width 756 procreated child 761
callbacks, invoking when Pt ARG AREA 754
resources are set 759 Pt ARG BITMAP CURSOR
cursor 754
bitmap 754

September 20, 2005 Index 911

Index  2005, QNX Software Systems

Pt ARG BORDER WIDTH user-defined data 765

756 width 754, 758
Pt ARG CURSOR COLOR x, y coordinates 754, 763
756 Pt WIDGET REBUILD 762
Pt ARG CURSOR TYPE 757 Pt WIDGET RESIZE 762
Pt ARG DATA 757 PtWindow 770
Pt ARG DIM 758 active color 781
Pt ARG EFLAGS 758, 763 Alt function key combinations
Pt ARG FLAGS 759 785
Pt ARG HELP TOPIC 763 application 784
Pt ARG POS 763 backdrop 782, 785
Pt ARG RESIZE FLAGS 763 block input 786
Pt ARG USER DATA 765 border 784
Pt CB BLOCKED 765 children, layout and sizing 777
Pt CB DESTROYED 766 close button 784
Pt CB HOTKEY 766 closing 782
Pt CB RAW 768 callback 787
Pt CB REALIZED 769 convenience functions 792
Pt CB UNREALIZED 769 cursors, overriding
raw event callback 768 children’s 781
realizing flags
callback 769 managed 773, 782
delaying 760 notify 775, 783
indicating completion 761 render 772, 784
indicating in progress 762 focus
whenever resources are gaining and losing 782
set 762 giving 793
redrawing, preventing 762 giving when opened 786
region, forcing to have 762 force front 782, 786
render focus 760 height
resizing maximum 780
flags 763 minimum 780
whenever resources are help
set 762 button 784
selectable 762 context-sensitive 782
toggling, enabling 762 root 782
unrealized callback 769 hiding 782, 786

912 Index September 20, 2005

 2005, QNX Software Systems Index

icon 771, 775, 784 Pt ARG WINDOW TITLE COLOR

icon widget ID 780 786
iconifying 786 Pt CB WINDOW 787
in front 786 Pt CB WINDOW CLOSING
inactive color 782 787
maximize button 784 Pt CB WINDOW OPENING
maximizing 782, 786 788
menu button 784 Pt CB WINDOW TRANSPORT
minimize button 784 789
moving 782 resizing 773, 782
opening callback 788 handles 785
Pt ARG ICON WINDOW restoring 782
771, 780 sending to back 782, 797
Pt ARG MAX HEIGHT 780 sending to front 782, 799
Pt ARG MAX WIDTH 780 state 785
Pt ARG MIN HEIGHT 780 getting 795
Pt ARG MIN WIDTH 781 subwindows 778
Pt ARG WINDOW ACTIVE COLOR switching consoles
781 automatically 782
Pt ARG WINDOW CURSOR OVERRIDE title
781 bar 785
Pt ARG WINDOW FRONT WINDOW color 786
781 text 786
Pt ARG WINDOW HELP ROOT transport callback 789
782 width
Pt ARG WINDOW INACTIVE COLOR maximum 780
782 minimum 781
Pt ARG WINDOW MANAGED FLAGS window event callback 787
773, 782 window in front 781
Pt ARG WINDOW NOTIFY FLAGS window manager 771
775, 783 window menu 782
Pt ARG WINDOW RENDER FLAGS PtWindowFocus() 793
772, 784 PtWindowGetState() 795
Pt ARG WINDOW STATE PtWindowToBack() 797
785 PtWindowToFront() 799
Pt ARG WINDOW TITLE Pt Z STRING 81, 327
786 pushbutton widget See PtButton

September 20, 2005 Index 913

Index  2005, QNX Software Systems

PWM 770 Rt ARG METER COLOR 808

Rt ARG METER FLAGS 808
Rt ARG METER FONT COLOR
809
R Rt ARG METER INCREMENT
809
range-select mode 227 Rt ARG METER KEY LEFT 801,
raw drawing widget See PtRaw 809
raw events 13, 768 Rt ARG METER KEY RIGHT
realizing 801, 809
delaying 760 Rt ARG METER LEVEL1 COLOR
done 761 810
in progress 762 Rt ARG METER LEVEL1 POS
Pt CB REALIZED 769 810
whenever resources are set 762 Rt ARG METER LEVEL2 COLOR
realtime widget 810
meter See RtMeter Rt ARG METER LEVEL2 POS
progress See RtProgress 810
trend See RtTrend Rt ARG METER LEVEL3 COLOR
rebuilding 762 811
rectangle widget See PtRect Rt ARG METER MAX NEEDLE POSITION
redrawing, preventing 762 811
region Rt ARG METER MIN NEEDLE POSITION
forcing a widget to have 762 811
region widget See PtRegion Rt ARG METER NEEDLE COLOR
render shared library 139 811
resizing Rt ARG METER NEEDLE POSITION
callback 136 802, 811, 813
flags 763 Rt ARG METER NUM SEVERITY LEVELS
and anchor flags 138 812
graphical widgets 257 Rt ARG METER TEXT FONT
policy 255, 763 812
whenever resources are set 762 Rt ARG MOVED 813
resources Rt ARG PROGRESS BAR COLOR
inheritance of 18 817
types 23 Rt ARG PROGRESS DIVISIONS
row widget See PtGroup 817

914 Index September 20, 2005

 2005, QNX Software Systems Index

Rt ARG PROGRESS GAP 817 flickering 804

Rt ARG PROGRESS SPACING font 812
817 interactive 808
Rt ARG TREND ATTRIBUTES key
821, 823 increment 809
Rt ARG TREND COLOR LIST left 801, 809
821, 823, 828 movement with 801
Rt ARG TREND COUNT 824 right 801, 809
Rt ARG TREND DATA 824 levels, number of 812
Rt ARG TREND FLAGS 825 maximum 811
Rt ARG TREND GRID COLOR minimum 811
827 mouse movement 801
Rt ARG TREND GRID X 827 needle movement callback 812
Rt ARG TREND GRID Y 827 no text 808
Rt ARG TREND INC 827 noninteractive 808
Rt ARG TREND MAX 828 position
Rt ARG TREND MIN 828 level 1 810
Rt ARG TREND PALETTE END level 2 810
828 maximum 811
Rt CB METER MOVED 812 minimum 811
Rt GRID 825 needle 802, 811
Rt GRID ABOVE TRENDS 825 Pt ARG FLAGS 809, 810
Rt GRID FORCE 825 Rt ARG METER COLOR 808
Rt GRID IS TRANSLUCENT 825 Rt ARG METER FLAGS 808
Rt KEY MOVED 812 Rt ARG METER FONT COLOR
RtMeter 801 809
color Rt ARG METER INCREMENT
center 808 809
font 809 Rt ARG METER KEY LEFT
level 1 810 801, 809
level 2 810 Rt ARG METER KEY RIGHT
level 3 811 801, 809
needle 811 Rt ARG METER LEVEL1 COLOR
outline 808 810
ticks 808 Rt ARG METER LEVEL1 POS
examples 802 810
flags 808

September 20, 2005 Index 915

Index  2005, QNX Software Systems

Rt ARG METER LEVEL2 COLOR Rt ARG PROGRESS SPACING

810 817
Rt ARG METER LEVEL2 POS spacing
810 bar and text 817
Rt ARG METER LEVEL3 COLOR divisions 817
811 RtTrend 820
Rt ARG METER MAX NEEDLE POSITION attributes 821
811 color list 823
Rt ARG METER MIN NEEDLE POSITION convenience functions 830
811 flags 825
Rt ARG METER NEEDLE COLOR grid
811 color 827
Rt ARG METER NEEDLE POSITION drawing 825
802 forcing display of 825
Rt ARG METER NEEDLE POSITION horizontal lines, number
811, 813 of 827
Rt ARG METER NUM SEVERITY LEVELS opaque, over trends 825
812 translucent 825
Rt ARG METER TEXT FONT vertical lines, number of 827
812 palette entries, range of 828
Rt CB METER MOVED 812 Pt ARG COLOR 823
severity arcs 802 Pt ARG FILL COLOR 822
size 802 Rt ARG TREND ATTRIBUTES
RtM NON SELECTABLE 808 821, 823
RtM NO TEXT 808 Rt ARG TREND COLOR LIST
Rt MOUSE MOVED 813 821, 823, 828
RtM SELECTABLE 808 Rt ARG TREND COUNT
Rt PIXEL 825 824
RtProgress 816 Rt ARG TREND DATA 824
color 817 Rt ARG TREND FLAGS 825
number of divisions 817 Rt ARG TREND GRID COLOR
Rt ARG PROGRESS BAR COLOR 827
817 Rt ARG TREND GRID X 827
Rt ARG PROGRESS DIVISIONS Rt ARG TREND GRID Y 827
817 Rt ARG TREND INC 827
Rt ARG PROGRESS GAP Rt ARG TREND MAX 828
817 Rt ARG TREND MIN 828

916 Index September 20, 2005

 2005, QNX Software Systems Index

Rt ARG TREND PALETTE END Shift-click selection 227

828 single-select mode 227
trends slider widget See PtSlider
data 824 space, sharing among widgets See
data, replacing 832 PtDivider
direction of movement 826 superclass widget See PtWidget
distance between points 827
drawing as pixels 825
drawing over grid 825
horizontal 825 T
maximum value 828
minimum value 828 Tab character, use as column
number of 824 separator 338, 672
vertical 826 tab widget See PtTab
Rt TREND BOTTOM TO TOP 826 terminal emulator widget See
RtTrendChangeData() 832 PtTerminal
RtTrendChangeTrendData() 832 attached to a device See
Rt TREND HORIZONTAL 825 PtTty
Rt TREND LEFT TO RIGHT 826 text widget
Rt TREND RIGHT TO LEFT 826 label See PtLabel
Rt TRENDS ABOVE GRID 825 multiline See PtMultiText
Rt TREND TOP TO BOTTOM 826 single-line See PtText
Rt TREND VERTICAL 826 with list of choices See
PtComboBox
threshold, graphics bandwidth 46
time widget See PtClock
S timer widget See PtTimer
toggle button widget See
scroll area widget See PtToggleButton
PtScrollArea toggling
scrollbar widget See enabling 762
PtScrollbar Pt CB ACTIVATE 49
selecting state, checking 49
enabling 762 transparency pattern 48
widgets 44 tree widget
selection mode 227 general purpose See PtTree
shared memory 139

September 20, 2005 Index 917

Index  2005, QNX Software Systems

superclass See also hierarchy 17

PtGenTree width 754, 758
trend widget See RtTrend window manager 770
typographical conventions xvii window widget See PtWindow

U X
unrealizing x, y coordinates 754, 763
Pt CB UNREALIZED 769
up/down button widget See
PtUpDown
UPDOWN BOTTOM 752
UPDOWN LEFT 752
UPDOWN RIGHT 752
UPDOWN TOP 752
URL (Universal Resource
Locator) 303
user-defined data 665, 765

V
vector graphics 252
rescaling 256
viewport widget See
PtScrollArea

W
wedge 40
widget See also PtWidget
contributed xix
description, contents of 22

918 Index September 20, 2005