Photon microGUI

Building Custom Widgets

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 and Photon microGUI are registered trademarks of QNX Software Systems in certain jurisdictions. All other trademarks and registered trademarks
belong to their respective owners.
 Contents

About This Manual xv

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

1 Overview 1
Subclassing widgets 4
Design considerations 4
A quick look at a widget 6
Widget header file 7
Widget source file 8
Types of widgets 11
Class hierarchy 11
Basic widgets 11
Container widgets 12
Compound widgets 13

2 Life Cycle of a Widget 15

Basic widgets 17
Instantiating the widget 17
Realizing a widget instance 20
After realizing a widget 26
Destroying a widget 27
Container widgets 28
Anchoring 28

September 20, 2005 Contents iii

  2005, QNX Software Systems

Child constraints 29
Child redirection 30
Compound widgets 30
Exporting subordinate widgets 32

3 Anatomy of a Widget 33
Defining resources 35
Resource manifests 35
PtResourceRec t resource records 37
Defining the widget class 47
Widget class structure 47
Widget class resource table 51
PtBasic class resource additions 53
Class methods 55
Defaults method 56
Initialization method 56
Extent method 58
Connection method 60
Realization method 62
Draw method 62
Unrealization method 65
Destruction method 67
Set Resources method 67
Get Resources method 68
Got Focus method 68
Lost Focus method 69
Calc Opaque Rect method 70
Widget actions 71
Raw callback list 72
Container widget anatomy 74
Child-constraint support 74
Child-redirector function 78
Fundamental methods 79

iv Contents September 20, 2005

 2005, QNX Software Systems

Compound widget anatomy 81

Blocking resources 86
Compound redirection 87
Fundamental methods 88

4 Using Widget Superclasses 93

PtWidget 95
Class hierarchy 95
Class flags 95
Methods 95
Widget actions 97
Resource definitions 97
Functions 98
PtBasic 99
Class hierarchy 99
Class extensions 99
Methods 100
Widget actions 102
Resource definitions 103
Functions 104
PtContainer 105
Class hierarchy 105
Class extensions 105
Methods 106
Widget actions 109
Resource definitions 111
Functions 111
PtCompound 114
Class hierarchy 114
Class extensions 114
Methods 115
Widget actions 116
Resource definitions 116

September 20, 2005 Contents v

  2005, QNX Software Systems

Functions 116
PtGenList 116
Class hierarchy 116
Class extensions 116
Methods 117
Widget actions 121
Resource definitions 122
Functions 123
PtGenTree 125
Class hierarchy 125
Class extensions 125
Methods 126
Widget actions 128
Resource definitions 128
Functions 129
PtLabel 129
Class hierarchy 129
Methods 129
Widget actions 131
Resource definitions 131
Functions 132
PtGraphic 133
Class hierarchy 133
Methods 133
Widget actions 135
Resource definitions 135
Functions 135
PtGauge 136
Class hierarchy 136
Methods 136
Widget actions 137
Resource definitions 137

vi Contents September 20, 2005

 2005, QNX Software Systems

Functions 138

5 Creating a List Widget 139

Overview 141
Item structure 141
Widget instance structure 143
Methods 145
Convenience functions 149
PtGenListAddItems() 153
PtGenListAllItems() 155
PtGenListClearSelection() 156
PtGenListDamageItem() 157
PtGenListDrawBackground() 158
PtGenListDrawString() 159
PtGenListFirstItem() 161
PtGenListGetCurrent() 162
PtGenListGetSelIndexes() 163
PtGenListGoto() 164
PtGenListHold() 165
PtGenListItemIndex() 166
PtGenListItemRealloc() 167
PtGenListLastItem() 168
PtGenListLockItem() 169
PtGenListRelease() 170
PtGenListRemoveItems() 171
PtGenListResize() 173
PtGenListSelect() 174
PtGenListSelectedItems() 175
PtGenListSetGflags() 176
PtGenListSetSelIndexes() 177
PtGenListShow() 178
PtGenListUnlockItem() 179
PtGenListUnselect() 180

September 20, 2005 Contents vii

  2005, QNX Software Systems

PtSuperClassGenListDraw() 181
PtSuperClassGenListInflate() 182
PtSuperClassGenListKey() 183
PtSuperClassGenListMouse() 184
PtSuperClassGenListSelect() 185

6 Creating a Tree Widget 187

Overview 189
Item structure 189
Methods 190
Convenience functions 192
PtGenTreeAddAfter() 195
PtGenTreeAddFirst() 196
PtGenTreeAllItems() 197
PtGenTreeClearSelection() 198
PtGenTreeCollapse() 199
PtGenTreeDamageItem() 200
PtGenTreeExpand() 201
PtGenTreeExpandParents() 202
PtGenTreeFreeAllItems() 203
PtGenTreeFreeItems() 204
PtGenTreeGetCurrent() 205
PtGenTreeGetSelIndexes() 206
PtGenTreeGoto() 207
PtGenTreeItemIndex() 208
PtGenTreeItemRealloc() 209
PtGenTreeItemResize() 210
PtGenTreeRemoveChildren() 211
PtGenTreeRemoveItem() 212
PtGenTreeRemoveList() 213
PtGenTreeResize() 214
PtGenTreeRootItem() 215
PtGenTreeSelect() 216

viii Contents September 20, 2005

 2005, QNX Software Systems

PtGenTreeSelectedItems() 217
PtGenTreeSetSelIndexes() 218
PtGenTreeShow() 219
PtGenTreeUnselect() 220
PtGenTreeUnselectNonBrothers() 221
PtSuperClassGenTreeDrawItem() 222
PtSuperClassGenTreeItemState() 223

7 Binding Widgets into PhAB 225

Widget design considerations 227
Single-value resources 227
When to add custom widgets to palette files 228
Displaying your custom widget 228
Creating an icon for the PhAB widget bar 228
Importing a picture module 229
Creating a widget description table 230
Widget class name (w=) 231
Widget hierarchy (h=) 231
List of resources (r=) 232
List of callbacks (c=, k=, e=) 236
Inherited resources and callbacks (i=, n=) 237
Base widget (b=) 237
Create-type definition (t=) 238
Cursor styles (s=) 239
Default values (d=) 239
Adding the widget palette file to PhAB 241

8 Widget Building Library API 243

PtAddWidgetData() 250
PtAnchorWidget() 252
PtApplyAnchors() 253
PtAttemptResize() 254
PtCalcAnchorOffsets() 256

September 20, 2005 Contents ix

  2005, QNX Software Systems

PtCalcRegion() 257
PtChildBoundingBox() 259
PtClipAdd() 260
PtClipRemove() 262
PtCompoundRedirect() 263
PtContainerChildRedirect() 264
PtContainerDeregister() 266
PtContainerRegister() 267
PtCoreChangeRegion() 268
PtCreateWidgetClass() 270
PtDamageExposed() 273
PtDestroyCallbackList() 275
PtDestroyHotkeyCallbacks() 276
PtDestroyRawCallbacks() 277
PtFindNextWidgetData() 278
PtFindResourceRecord() 280
PtFindWidgetData() 282
PtGetAnchoredExtent() 283
PtGetStruct() 285
PtInvokeCallbackList() 287
PtInvokeResizeCallbacks() 288
PtMoveResizeWidget() 289
PtRemoveWidgetData() 290
PtResizePolicy() 291
PtSetExtentFromArea() 292
PtSetStruct() 293
PtSetValue() 295
PtSuperClassCalcOpaque() 296
PtSuperClassChildCreated() 297
PtSuperClassChildDestroyed() 298
PtSuperClassChildGettingFocus() 299
PtSuperClassChildGettingResources() 300

x Contents September 20, 2005

 2005, QNX Software Systems

PtSuperClassChildLosingFocus() 301
PtSuperClassChildMovedResized() 302
PtSuperClassChildRealized() 303
PtSuperClassChildSettingResources() 304
PtSuperClassChildUnrealized() 305
PtSuperClassConnect(), PtSuperClassConnectFrom() 306
PtSuperClassDraw() 307
PtSuperClassExtent() 309
PtSuperClassGetResources() 311
PtSuperClassGotFocus() 312
PtSuperClassInit(), PtSuperClassInitFrom() 313
PtSuperClassLostFocus() 314
PtSuperClassRawEvent(), PtSuperClassRawEventFrom() 315
PtSuperClassRealized() 316
PtSuperClassSetResources() 317
PtUpdateVisibility() 319
PtWidgetAbove() 320

A Miscellaneous Widget-Building Tips 321

Glossary 325

Index 347

September 20, 2005 Contents xi

 List of Figures
The header file and source file for a widget class. 6
Button widgets. 11
A container with toggle-button children. 12
A compound widget. 13
Methods being chained up. 21
Inherited methods. 22
Default anchoring for a container widget. 29

September 20, 2005 List of Figures xiii

 About This Manual

September 20, 2005 About This Manual 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 Manual 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 Manual September 20, 2005

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

What you’ll find in this guide

The Building Custom Widgets manual accompanies the Photon
Developer’s Toolkit and is intended for Photon programmers who
want to create custom widgets. This manual contains everything you
need to know about building your own Photon widgets. Sample code
is used throughout this manual to demonstrate new concepts.

When you want to: Go to:

Learn about widget concepts, Overview
attributes, and behavior
Initialize a widget class, set up a Life Cycle of a Widget
widget instance structure, or set
application resources
Define a widget class, its Anatomy of a Widget
resources, methods, or actions
Choose a widget superclass to Using Widget Superclasses
base your custom widget on
Customize a list widget Creating a List Widget
Customize a tree widget Creating a Tree Widget
Add a custom widget to the Binding Widgets into PhAB
PhAB widget palette
Manage widgets using the Widget Building Library API
supplied convenience functions
Read widget-building tips Miscellaneous Widget-Building
Tips
Look up Photon terms Glossary

September 20, 2005 About This Manual xix

 Chapter 1
Overview

In this chapter. . .
Subclassing widgets 4
Design considerations 4
A quick look at a widget 6
Types of widgets 11

September 20, 2005 Chapter 1 ¯ Overview 1

 2005, QNX Software Systems

When you build an application, you typically use the standard widgets
provided with the Photon widget library. But occasionally you’ll have
a reason for not using these standard widgets.
For example, Photon widgets require a fair amount of memory, so if
you’re drawing a diagram having several PtRect, PtLine and
PtPolygon widgets, it might be better to create a single widget that
can draw the entire diagram using Pg*() graphic primitives.
Another reason for creating a custom widget is the need for a user
interface object whose features aren’t supported by standard widgets.
In this case, you have three options:

¯ Code the required user interface functionality directly into your

application.

¯ Use the raw widget, PtRaw — see the Raw Drawing and
Animation chapter of the Photon Programmer’s Guide.

¯ Build a custom widget.

Placing custom user-interface code within a widget has its advantages:

¯ The widget becomes a self-contained module that can be used

within other applications.

¯ The widget can take advantage of the Photon widget engine, which
has several features available only to widgets (e.g. automatic
routing of events to the appropriate widgets, which allows widgets
to automatically redraw and repair themselves when required).

¯ The user-interface code is separated from the application-specific

code (the primary goal of widgets).

The process of building a widget in Photon is very straightforward.

Because all widgets follow a specific structure or layout, you can start
with a standard widget template or an existing widget that has similar
functionality. Many example widgets and templates are provided in
the /qnx4/phtk/src/widgets directory.

September 20, 2005 Chapter 1 ¯ Overview 3

Subclassing widgets  2005, QNX Software Systems

Subclassing widgets
Building a custom widget is also known as subclassing a widget
because widgets are always built as descendants of existing widget
superclasses. Subclassing lets you enhance or modify the behavior
associated with an existing widget superclass, provided you
understand how the superclass is implemented. The Using Widget
Superclasses chapter describes the most common widget superclasses.

When creating a custom widget, you should subclass it under

PtBasic or one of PtBasic’s subclasses. The PtBasic superclass
is the ancestral widget class of most standard Photon widgets.
Subclassing a widget under PtBasic lets the widget inherit the
features common to most Photon widgets, such as support for
keyboard traversal, highlighting, and focus. If you create a widget that
doesn’t support these common features, it may look out of place in a
Photon application.

!
CAUTION:
If you’ll be adding a custom widget to the Photon Application Builder
(PhAB) widget palette, there are a few special design considerations
you must be aware of. Before you begin designing your widget, read
the Binding Widgets into PhAB chapter.

Design considerations
Part of building a custom widget involves deciding what it will look
like and how the user will interact with it. You’ll need to decide on
the resources that control the widget and pick an appropriate widget
superclass to start with.

Appearance Designing the look of a widget involves an exercise

in visualization. The widget’s appearance could
depend on whether a user will interact with the
widget. You should also consider whether a
developer may need to customize your widget. Once

4 Chapter 1 ¯ Overview September 20, 2005

 2005, QNX Software Systems Design considerations

you’ve decided on the look, you can start designing

the widget’s attributes.

Attributes Widget attributes are defined as resources within your

widget. The resources should be all things that the
developer can customize. The resources should also
define all the callbacks your widget will generate.
When deciding on these attributes, consider how to
represent them in the widget’s instance structure. For
example, will the attribute be a string, a structure, or
a pointer to an allocated array? Each of these
attributes (whether they are read, write, or read/write)
will be your widget’s resources.

Widget actions
If your widget will be interactive, you’ll have to
determine which Photon events your widget will be
sensitive to. These events must be set up in the
class-creation function.
You can have all events go through the same
function, or you can define a function for each event
type. The functions that handle events should read
the event data and take the appropriate action. For
example, a click on your widget might change its
internal state. If appropriate, your widget may need
to be damaged so a subsequent redraw operation can
reflect the widget’s new state.

Superclass More often than not, some or most of the resources

your widget requires are already available within an
existing widget superclass. When you build your
widget as a subclass of a superclass, much of your
widget’s behavior will be inherited from the
superclass.

September 20, 2005 Chapter 1 ¯ Overview 5

A quick look at a widget  2005, QNX Software Systems

A quick look at a widget

A widget is usually made up of two files:

¯ a header file, which defines the widget’s instance structure and

resource declarations needed by applications to use the widget

¯ a source code file, which contains the widget’s class structure and
the actual code to implement the widget. This code includes
methods, class-level functions that define how the widget
initializes itself, draws itself, calculates its extent, and so on.

The following diagram depicts the header and source code files for a
simple example of a widget, ShadowedBox.
Widget header file Widget source file
ShadowedBox.h ShadowedBox.c

Resource
declarations
Class methods

Instance structure

Class-creation function

The header file and source file for a widget class.

This sample widget will draw a shadowed box, define a resource for
changing the color of the shadow, and define a resource for specifying
the offset of the shadow.
This sample widget will be subclassed as follows:
PtWidget → PtBasic → ShadowedBox
Since ShadowedBox will be a subclass of PtBasic, it will inherit all
the resources and behavior of this standard Photon widget.

6 Chapter 1 ¯ Overview September 20, 2005

 2005, QNX Software Systems A quick look at a widget

Widget header file

Photon widgets comprise two structures: the class structure and the
instance structure. The class structure is defined in the source file and
is discussed in the next section. The instance structure is contained in
the header file, as shown below in an excerpt from the
ShadowedBox.h header file:

/* ShadowedBox.h - widget header file */

#include <Pt.h>

/* widget resources */
#define SBW SHADOW COLOR Pt RESOURCE( Pt USER( 0 ), 0 )
#define SBW SHADOW OFFSET Pt RESOURCE( Pt USER( 0 ), 1 )

/* widget instance structure */

typedef struct shadowed box widget{
PtBasicWidget t basic;
PgColor t shadow color;
short shadow offset;
} ShadowedBoxWidget;

/* widget class pointer */

extern PtWidgetClassRef t *ShadowedBox;

Instance structure members

Each instance of a widget has its own copy of the instance structure,
which carries the complete widget state including everything that can
be unique to that instance. Widgets define public resource manifests,
which correspond to the members of the instance structure.
The first member of the instance structure must be the instance
structure of the widget’s immediate superclass. ShadowedBox is a
subclass of PtBasic, so the first member of its instance structure is
of type PtBasicWidget t.
When a widget class is created, the members of the instance structure
are given default values or can be set using resource manifests. The
instance structure members can be changed by calling
PtSetResources() and read by calling PtGetResources().

September 20, 2005 Chapter 1 ¯ Overview 7

A quick look at a widget  2005, QNX Software Systems

The header file also defines an external reference to the widget class
pointer.

Widget source file

The organization of the source file is quite simple. First, it defines the
class structure. There’s only one copy of the class structure, which all
widget instances use. It’s initialized through the class-creation
function when the first instance of this class is created.

Class structure members

The class structure’s members contain pointers to methods and
resources that control how the Photon library handles instances of this
class.
The following class structure is found in the ShadowedBox.c source
file:
/* ShadowedBox.c - widget source file */

#include "ShadowedBox.h"

/* prototype declarations */
PtWidgetClass t *CreateShadowedBoxClass( void );

/* widget class pointer - class structure, create function */

PtWidgetClassRef t WShadowedBox = { NULL,
CreateShadowedBoxClass };
PtWidgetClassRef t *ShadowedBox = &WShadowedBox;

//
// ShadowedBox defaults function
//
static void shadowedbox dflts( PtWidget t *widget )
{
ShadowedBoxWidget *sb = ( ShadowedBoxWidget * ) widget;
PtBasicWidget t *basic = ( PtBasicWidget t * ) widget;

basic->fill color = Pg WHITE;

sb->shadow color = Pg BLACK;
sb->shadow offset = 4;
}

//
// ShadowedBox draw function
//

8 Chapter 1 ¯ Overview September 20, 2005

 2005, QNX Software Systems A quick look at a widget

static void shadowedbox draw( PtWidget t *widget, PhTile t *damage )

{
ShadowedBoxWidget *sb = ( ShadowedBoxWidget * ) widget;
PtBasicWidget t *basic = ( PtBasicWidget t * ) widget;
PhRect t shadow rect, rect;
PgColor t color;

// We want to use basic’s draw function to get borders

// and default focus rendering... but we don’t want it to
// fill the background with the basic fill color,
// so we set the fill color to transparent for Basic’s draw func.
color = basic->fill color;
basic->fill color = Pg TRANSPARENT;
PtSuperClassDraw( PtBasic, widget, damage );

// we don’t want to draw outside our canvas! So we clip.

PtBasicWidgetCanvas( widget, &rect );
PtClipAdd( widget, &rect );

basic->fill color = color;

shadow rect = rect;
shadow rect.ul.x += sb->shadow offset;
shadow rect.ul.y += sb->shadow offset;
PgSetStrokeColor( sb->shadow color );
PgSetFillColor( sb->shadow color );
PgDrawRect( &shadow rect, Pg DRAW FILL STROKE );

PgSetFillTransPat( basic->trans pattern );

PgSetStrokeColor( basic->color );
PgSetFillColor( color );
rect.lr.x -= sb->shadow offset;
rect.lr.y -= sb->shadow offset;
PgDrawRect( &rect, Pg DRAW FILL STROKE );

/* remove the clipping */

PtClipRemove();
}

//
// ShadowedBox class creation function
//
PtWidgetClass t *CreateShadowedBoxClass( void )
{
// define our resources
static PtResourceRec t resources[] = {
SBW SHADOW COLOR, Pt CHANGE REDRAW, 0,
Pt ARG IS NUMBER( ShadowedBoxWidget, shadow color ), 0,
SBW SHADOW OFFSET, Pt CHANGE RESIZE REDRAW, 0,
Pt ARG IS NUMBER( ShadowedBoxWidget, shadow offset ), 0,
};

September 20, 2005 Chapter 1 ¯ Overview 9

A quick look at a widget  2005, QNX Software Systems

// set up our class member values

static PtArg t args[] = {
{ Pt SET VERSION, 110},
{ Pt SET STATE LEN, sizeof( ShadowedBoxWidget ) },
{ Pt SET DFLTS F, (long)shadowedbox dflts },
{ Pt SET DRAW F, (long)shadowedbox draw },
{ Pt SET FLAGS, 0, Pt RECTANGULAR },
{ Pt SET NUM RESOURCES,
sizeof( resources ) / sizeof( resources[0] ) },
{ Pt SET RESOURCES, (long)resources,
sizeof( resources ) / sizeof( resources[0] ) },
};

// create the widget class

return( ShadowedBox->wclass = PtCreateWidgetClass(
PtBasic, 0, sizeof( args )/sizeof( args[0] ), args ) );
}

In the source file above, the class definition defines the

shadowedbox dflts() and shadowedbox draw() functions for the
Defaults and Draw methods. It also defines how the
SBW SHADOW COLOR and SBW SHADOW OFFSET resources are
handled.
As you can see from this example, creating a simple widget doesn’t
take a lot of code. You can take this example widget from the
/qnx4/phtk/src/widgets directory and try using it in your own
application.
Let’s review the fundamental structure of a widget source code file:

Section Example
Header files #include "ShadowedBox.h"
Class pointer PtWidgetClassRef t *ShadowedBox
declaration
Method functions shadowedbox dflts(), shadowedbox draw()

continued. . .

10 Chapter 1 ¯ Overview September 20, 2005

 2005, QNX Software Systems Types of widgets

Section Example
Class-creation CreateShadowedBoxClass()
function

Types of widgets
The Photon library supplies a number of widget classes that can be
used as the basis for custom widgets. To make this easy to
understand, we’ve categorized widgets into three general types:

¯ Basic

¯ Container

¯ Compound

Class hierarchy
All Photon widgets are based on the PtWidget core widget class. It
defines the characteristics common to all standard widgets, such as
position and dimension. Even if your widget is different from any
other widget, it will still inherit the features of the PtWidget widget
class. Most custom widgets, however, will be subclassed under one of
the other widget superclasses.

Basic widgets
Basic widgets are single-entity objects. They don’t contain other
widgets and aren’t built from other widgets. An example would be a
button widget.

Done Apply Default Cancel

Button widgets.

September 20, 2005 Chapter 1 ¯ Overview 11

Types of widgets  2005, QNX Software Systems

You can’t put other widgets inside a button, and the button itself isn’t
built from other widgets. Our sample ShadowedBox widget is a basic
widget.
Although we call them “basic” widgets, this is only a classification
and doesn’t imply that they can’t be powerful. In fact, one of the most
complex widgets in the Photon library, PtText, is a basic widget.

Container widgets
Container widgets can have other widgets as children. Containers
have the option of managing the geometry of their children (e.g.
PtGroup) or leaving the widgets as they are (e.g. PtPane).
The PtContainer class extends the PtBasic class definition to
include many new methods for controlling and reacting to the widget
children placed inside the container. Using these new methods, a
container could, for example, detect when a new child is added and
automatically resize itself to accommodate the new widget.
Widget children can be selectively blocked by a redirector function.
This is useful when you want to create a widget that accepts only
specific widgets as children (e.g. PtMenuBar accepts only
PtMenuButton widgets as children). All other widgets are redirected
to the container’s parent widget. This causes them to be created at the
same level as the container instead of as a child of the container.
Containers also add anchoring features that allow children to be
anchored to their parent.

None Center
Done
Center Tile Tile
Alternate Disable

A container with toggle-button children.

12 Chapter 1 ¯ Overview September 20, 2005

 2005, QNX Software Systems Types of widgets

Compound widgets
Compound widgets are built from exported subordinate widgets. The
exporting mechanism allows access to the underlying widgets using
their resources and convenience functions. This reduces the need to
duplicate every subordinate widget resource in the compound
widget’s resource list.
You have to set up resources only for new functionality or for
resolving conflicts when more than one of the same widget class has
been exported. A blocking mechanism lets compound widgets block
access to any of the subordinate resources. This lets you prevent any
actions that would adversely affect the look and behavior of the
compound widget.
Since the PtCompound class is a descendant of PtContainer, it
inherits all the functionality of a container widget. This means
compound widgets can be anchored and can support child widgets
other than the ones they’re built from. Since this feature isn’t usually
desired, you can use a compound widget’s redirector function to
automatically reject the addition of unwanted widgets.
A good example of a compound widget is PtComboBox — it’s built
using the PtText and PtList widget classes and adds its own
functionality.
Raw event

Search for exact match

A compound widget.

Another good example is PtDivider — it’s built using a PtGroup

widget; separator bars are added automatically between the widgets in
the group.

September 20, 2005 Chapter 1 ¯ Overview 13

 Chapter 2
Life Cycle of a Widget

In this chapter. . .
Basic widgets 17
Container widgets 28
Compound widgets 30

September 20, 2005 Chapter 2 ¯ Life Cycle of a Widget 15

 2005, QNX Software Systems Basic widgets

This chapter examines the life cycle of a basic widget using the
ShadowedBox widget as an example. We’ll show you how to create,
use, and destroy this widget. We’ll also outline the life cycle
differences between basic, container, and compound widgets.

Basic widgets
If we were building an application and wanted to use the custom
ShadowedBox widget (a “basic” widget), we would simply create it
by calling PtCreateWidget():
PtWidget t *box;
PhArea t area = { 10, 10, 100, 100 };
PtArg t args[2];

PtSetArg( &args[0], Pt ARG AREA, &area, 0 );

PtSetArg( &args[1], SBW SHADOW COLOR, Pg BLUE, 0 );
box = PtCreateWidget( ShadowedBox, NULL, 2, args );
PtRealizeWidget( box );

What happens when we call PtCreateWidget()? What does the widget

library do? Let’s follow through the widget creation process and
examine the various parts of the widget code as they get executed.

Instantiating the widget

The first step, instantiating the widget, creates an instance of the
widget class. The process of instantiating a widget is as follows:

1 The widget class is created and initialized.

2 All members of the widget instance structure are initialized to

default values.

3 The resources specified through PtCreateWidget() are applied.

Creating and initializing the widget class

When a widget is created via a call to PtCreateWidget(), the specified
widget class (i.e. ShadowedBox) is first checked to see if it has been
initialized. Since this is the first time this widget has been created, the
widget’s initialization function is called to create the widget class.

September 20, 2005 Chapter 2 ¯ Life Cycle of a Widget 17

Basic widgets  2005, QNX Software Systems

In the ShadowedBox.c source file, the widget class is defined as a

class reference structure:
PtWidgetClassRef t WShadowedBox = { NULL,
CreateShadowedBoxClass };
PtWidgetClassRef t *ShadowedBox = &WShadowedBox;

The first member is the widget class pointer, which is initialized to

NULL. The second member is the widget class-creation function. If
the value of the class pointer is NULL, the class-creation function is
called and it sets the widget class pointer in the structure.
Let’s look at CreateShadowedBoxClass() from our example to see
how it defines the ShadowedBox class:
//
// ShadowedBox class creation function
//
PtWidgetClass t *CreateShadowedBoxClass( void )
{
// define our resources
static PtResourceRec t resources[] = {
SBW SHADOW COLOR, Pt CHANGE REDRAW, 0,
Pt ARG IS NUMBER( ShadowedBoxWidget, shadow color ), 0,
SBW SHADOW OFFSET, Pt CHANGE RESIZE REDRAW, 0,
Pt ARG IS NUMBER( ShadowedBoxWidget, shadow offset ), 0,
};

// set up our class member values

static PtArg t args[] = {
{ Pt SET VERSION, 110},
{ Pt SET STATE LEN, sizeof( ShadowedBoxWidget ) },
{ Pt SET DFLTS F, (long)shadowedbox dflts },
{ Pt SET DRAW F, (long)shadowedbox draw },
{ Pt SET FLAGS, 0, Pt RECTANGULAR },
{ Pt SET NUM RESOURCES,
sizeof( resources ) / sizeof( resources[0] ) },
{ Pt SET RESOURCES, (long)resources,
sizeof( resources ) / sizeof( resources[0] ) },
};

// create the widget class

return( ShadowedBox->wclass = PtCreateWidgetClass(
PtBasic, 0, sizeof( args )/sizeof( args[0] ), args ) );
}

The class definition includes:

18 Chapter 2 ¯ Life Cycle of a Widget September 20, 2005

 2005, QNX Software Systems Basic widgets

Resources array
The static array resources defines the class resources. The class
resources are accessed through a table of resources unique to
the ShadowedBox class.
Widget class array
The static array args defines the ShadowedBox class. It defines
ShadowedBox’s class methods and its table of resources.
The args array is passed to PtCreateWidgetClass() as follows:

return( ShadowedBox->wclass = PtCreateWidgetClass(

PtBasic, 0, sizeof( args )/sizeof( args[0] ), args )
);

In PtCreateWidgetClass(), space is allocated for the

ShadowedBox class and its superclass’s structure (i.e.
PtBasic) is copied in. Then the args array is used to set up the
custom class and its table of unique resources.

Setting default values

After the ShadowedBox class is initialized, space is allocated for its
instance structure. The Defaults methods of all ancestors of the
ShadowedBox class are called next, ending with ShadowedBox’s
Defaults method (e.g. shadowedbox dflts()):

//
// ShadowedBox defaults function
//
static void shadowedbox dflts( PtWidget t *widget )
{
ShadowedBoxWidget *sb = ( ShadowedBoxWidget * ) widget;
PtBasicWidget t *basic = ( PtBasicWidget t * ) widget;

basic->fill color = Pg WHITE;

sb->shadow color = Pg BLACK;
sb->shadow offset = 4;
}

To access the private members of the instance structure, this Defaults

method casts the widget pointer to a ShadowedBoxWidget pointer

September 20, 2005 Chapter 2 ¯ Life Cycle of a Widget 19

Basic widgets  2005, QNX Software Systems

and a PtBasicWidget t pointer. It then defaults the fill color

member to Pg WHITE, the shadow color member to Pg BLACK and
the shadow offset member to 4.

Setting application resources

After the Defaults method is called, the array of resources provided to
PtCreateWidget() is applied. In the example source code, these two
resources are passed in args:

PtSetArg( &args[0], Pt ARG AREA, &area, 0 );

PtSetArg( &args[1], SBW SHADOW COLOR, Pg BLUE, 0 );

The first resource manifest, Pt ARG AREA, sets the widget area
(position and size). Because this resource isn’t defined by the
ShadowedBox class, it’s handled by the first superclass that defines
Pt ARG AREA (i.e. PtWidget).
The second resource manifest SBW SHADOW COLOR is handled by
the ShadowedBox class. Because ShadowedBox doesn’t define a
method for setting the resource value, the Photon widget library takes
care of assigning a new value to this instance structure member (i.e.
the value is changed from the default, Pg BLACK, to Pg BLUE).
Finally, PtCreateWidget() returns the widget pointer and the
application receives access to a newly created instance of the
ShadowedBox class:

box = PtCreateWidget( ShadowedBox, NULL, 2, args );

Now box points to an instance of the ShadowedBox class, but the

widget itself won’t be displayed until it’s realized.

Realizing a widget instance

There are a number of class methods used in the process of realizing a
widget. These methods are executed in a specific order that we’ll call
“steps”:

20 Chapter 2 ¯ Life Cycle of a Widget September 20, 2005

 2005, QNX Software Systems Basic widgets

Step What it does

Initialization method Initializes the widget instance.
Extent method Calculates the actual widget extent based
on the area specified.
Connection method Creates any optional Photon regions.
Realization method Performs any operations required
immediately prior to drawing.
Draw method Draws the widget.

The ShadowedBox example doesn’t define an Initialization method,

an Extent method, or a Connection method. These methods are
handled by PtWidget or PtBasic.

Processing methods
Before we get into a detailed discussion of the individual methods
used in a widget class, we need to look at their usage in general. Class
methods can be chained up or down or inherited.
When a method is chained, the method of each class in the widget
hierarchy is executed. Execution can start at the lowest class (e.g.
ShadowedBox) in the hierarchy and go up, or at the highest class (i.e.
PtWidget) and go down.

Methods being chained up.

Some chained methods can be stopped. This means any class in the
hierarchy can stop the chaining process to prevent the superclass or
subclassed methods from being executed. When chaining is stopped,

September 20, 2005 Chapter 2 ¯ Life Cycle of a Widget 21

Basic widgets  2005, QNX Software Systems

the class stopping the chain is responsible for supplying the

equivalent functionality otherwise provided by another class.
Inherited methods work differently: one method only is called, as
determined by the lowest class in the hierarchy to define it (e.g. our
ShadowedBox class doesn’t define an Extent method, so the Extent
method is inherited from the PtBasic superclass).

Inherited methods.

This means PtBasic’s Extent method is used to determine the size of

the ShadowedBox widget. Inherited methods make building a widget
class easier because only the methods unique to a class need to be
defined.
Let’s look at the class methods in more detail. The following table
shows whether the methods of a basic widget are chained or inherited:

Method Processing Processing note

Defaults Chained down Can’t be stopped
Initialization Chained up Return Pt END to stop
Extent Inherited
Connection Chained up Return Pt END to stop
Realization Inherited
Draw Inherited

continued. . .

22 Chapter 2 ¯ Life Cycle of a Widget September 20, 2005

 2005, QNX Software Systems Basic widgets

Method Processing Processing note

Unrealization Chained up Can’t be stopped
Destruction Chained up Can’t be stopped
Set Resources Inherited
Get Resources Inherited

PtBasic extends these methods with three other methods. These

methods are available only to subclasses of PtBasic:

Method Processing
Got Focus Inherited
Lost Focus Inherited
Calc Opaque Rect Inherited

Initialization method
This is the first class method called during the realization process.
This method is chained up; the Initialization method of the
ShadowedBox class would be called first, followed by the
Initialization method of the PtBasic class, ending with PtWidget’s
Initialization method.

Extent method
This inherited method is used to determine the exact size of the
widget based on default values and/or the widget’s position, size,
margins, borders, and highlighting information, as set by the program.
An Extent method isn’t defined for ShadowedBox, so the Extent
method is inherited from the PtBasic superclass.

September 20, 2005 Chapter 2 ¯ Life Cycle of a Widget 23

Basic widgets  2005, QNX Software Systems

Connection method
The Connection method is chained up. It’s used primarily for creating
any Photon regions needed by a widget. Due to its simplicity, the
ShadowedBox widget doesn’t require any regions — a superclass
method will create regions for ShadowedBox only if needed (e.g. a
custom cursor is defined).

Realization method
The Realization method is used to adjust any region attributes prior to
the actual drawing of a widget. Because ShadowedBox doesn’t define
a Realization method, it’s inherited from a superclass.

Draw method
This is the last class method called during the realization process. It’s
used to render a widget on the screen. This method can be inherited,
but since ShadowedBox defines its own Draw method (shown
below), it’s executed instead of a superclass’s Draw method:

//
// ShadowedBox draw function
//
static void shadowedbox draw( PtWidget t *widget, PhTile t *damage )
{
ShadowedBoxWidget *sb = ( ShadowedBoxWidget * ) widget;
PtBasicWidget t *basic = ( PtBasicWidget t * ) widget;
PhRect t shadow rect, rect;
PgColor t color;

// We want to use basic’s draw function to get borders

// and default focus rendering... but we don’t want it to
// fill the background with the basic fill color,
// so we set the fill color to transparent for Basic’s draw func.
color = basic->fill color;
basic->fill color = Pg TRANSPARENT;
PtSuperClassDraw( PtBasic, widget, damage );

// we don’t want to draw outside our canvas! So we clip.

PtBasicWidgetCanvas( widget, &rect );
PtClipAdd( widget, &rect );

basic->fill color = color;

shadow rect = rect;
shadow rect.ul.x += sb->shadow offset;

24 Chapter 2 ¯ Life Cycle of a Widget September 20, 2005

 2005, QNX Software Systems Basic widgets

shadow rect.ul.y += sb->shadow offset;

PgSetStrokeColor( sb->shadow color );
PgSetFillColor( sb->shadow color );
PgDrawRect( &shadow rect, Pg DRAW FILL STROKE );

PgSetFillTransPat( basic->trans pattern );

PgSetStrokeColor( basic->color );
PgSetFillColor( color );
rect.lr.x -= sb->shadow offset;
rect.lr.y -= sb->shadow offset;
PgDrawRect( &rect, Pg DRAW FILL STROKE );

/* remove the clipping */

PtClipRemove();
}

Let’s look at the code in more detail. From the function declaration:

static void shadowedbox draw( PtWidget t *widget, PhTile t *damage )

The Draw method is passed two arguments. The widget argument is

the widget’s pointer and the damage argument is a list of damage
rectangles to be applied to the widget when it’s drawn.

☞ The program can use the damage list to make intelligent decisions
about what to draw. However, drawing operations for most widgets
are minimal and any extra processing might not be worthwhile.

Notice the widget pointer is of type PtWidget t, which means the

pointer must be cast to a ShadowedBoxWidget pointer to allow
access to the ShadowedBox widget’s internal structure members.
Since PtBasic is a superclass of ShadowedBox, we can cast the
widget pointer to a PtBasicWidget t structure too; this allows
access to the basic widget members without resorting to sb->basic.

ShadowedBoxWidget *sb = ( ShadowedBoxWidget * ) widget;

PtBasicWidget t *basic = ( PtBasicWidget t * ) widget;

Since the Draw method isn’t chained, all drawing of the

ShadowedBox widget, including the borders and highlighting
common to all Photon-style widgets, must be done within the Draw

September 20, 2005 Chapter 2 ¯ Life Cycle of a Widget 25

Basic widgets  2005, QNX Software Systems

method of the ShadowedBox class. For convenience, the Photon

widget building library allows you to call the draw method of a
superclass using PtSuperClassDraw() as shown below:
// We want to use basic’s draw function to get borders
// and default focus rendering... but we don’t want it to
// fill the background with the basic fill color,
// so we set the fill color to transparent for Basic’s draw func.
color = basic->fill color;
basic->fill color = Pg TRANSPARENT;
PtSuperClassDraw( PtBasic, widget, damage );

After this, we add clipping so we won’t draw beyond the widget’s

canvas:
// we don’t want to draw outside our canvas! So we clip.
PtBasicWidgetCanvas( widget, &rect );
PtClipAdd( widget, &rect );

The rest of the code in the Draw method determines the widget’s
position and size based on its area and margins, and then draws a
shadowed box using low-level Photon Pg*() graphics functions.
Before leaving the Draw method, the clipping we added is removed
by calling PtClipRemove().
When the draw buffer is flushed later on, the widget appears on the
screen.

After realizing a widget

After a widget is realized, it must be ready to:

¯ handle any changes made to its resources

¯ redraw itself when damaged or exposed

Fortunately, both of these operations are handled automatically

because of the way widget classes are defined — the resource list
specifies what should be done if the value of a resource changes:
static PtResourceRec t resources[] = {
SBW SHADOW COLOR, Pt CHANGE REDRAW, 0,
Pt ARG IS NUMBER( ShadowedBoxWidget, shadow color ), 0,

26 Chapter 2 ¯ Life Cycle of a Widget September 20, 2005

 2005, QNX Software Systems Basic widgets

SBW SHADOW OFFSET, Pt CHANGE RESIZE REDRAW, 0,

Pt ARG IS NUMBER( ShadowedBoxWidget, shadow offset ), 0,
};

In the example source code for ShadowedBox, both resources are

defined with a Pt*REDRAW manifest so they’re automatically marked
as damaged. This causes a redraw if the value changes.
When a widget is damaged for any reason, the Photon library
automatically invokes the widget’s Draw method to repair the
damage. If any of the inherited resources are changed, they’re handled
according to the resource declaration of the first superclass to define
that resource.

Destroying a widget
The widget must handle its own destruction. This process involves:
¯ unrealizing the widget
¯ destroying the widget

Unrealization method
The purpose of this method is to undo everything of consequence
done during realization. The Unrealization method is responsible for:
¯ removing any open regions owned by a widget
¯ erasing the widget from the screen through the widget library
¯ making the widget noninteractive
This method is chained up. Since the ShadowedBox class doesn’t
define an Unrealization method, PtBasic’s Unrealization method
will be called, followed by PtWidget’s Unrealization method.

Destruction method
This method is responsible for releasing any system resources used by
a widget but not referenced by a widget resource. Like the
Unrealization method, it’s chained up. This lets all classes in the
hierarchy release system resources in turn.

September 20, 2005 Chapter 2 ¯ Life Cycle of a Widget 27

Container widgets  2005, QNX Software Systems

Other methods
The remaining class methods aren’t described in this section, but you
should now have a general understanding of the overall process. The
Anatomy of a Widget chapter describes these methods in detail. Let’s
now look at some of the additional requirements for container and
compound classes.

Container widgets
The life cycle of a container widget is similar to that of a basic
widget. The main difference is that container widgets must support
widget children, including the following features:

¯ anchoring

¯ child constraints

¯ child redirection

Anchoring
If container widgets are already realized or in the process of being
realized, they’re automatically anchored by the widget library.

28 Chapter 2 ¯ Life Cycle of a Widget September 20, 2005

 2005, QNX Software Systems Container widgets

Parent container Container

Child Child

Child Child

Anchoring

Default anchoring for a container widget.

PtAnchorWidget() and PtApplyAnchors() in the widget-building

library allow anchoring to be applied at any time, provided the parent
widget’s extent is valid.
The Extent method of a container class is very important — it must
enforce its resize policy based on its children. This means a container
widget may need to determine its size based on the positions and sizes
of its children. For this reason, all child widgets are extented before
the container is extented.

Child constraints
The container class extends the PtBasic class definition with a
number of child-constraint methods. These methods let a container
adjust itself automatically according to any changes made to its
children. These child-constraint methods include:

¯ Child Created

¯ Child Realized

¯ Child Moved/Resized

September 20, 2005 Chapter 2 ¯ Life Cycle of a Widget 29

Compound widgets  2005, QNX Software Systems

¯ Child Unrealized

¯ Child Destroyed

¯ Child Setting Resources

¯ Child Getting Resources

¯ Child Getting Focus

¯ Child Losing Focus

A container dynamically identifies which child constraints need to be

handled by setting and clearing bits in the flags member of its instance
of the class structure. For example:

cntr->flags |= Pt CHILD CREATED;

Any child-constraint method a container will support must have its bit
set in cntr->flags or the method won’t be invoked.

Child redirection
A custom container class can optionally provide a child-redirector
function to restrict certain widget classes from being added to the
container. This function allows the container to redirect parentage to
other widgets inside or outside the container itself. The
child-redirector function is usually defined at the end of the Default
method. For example:

PtContainerChildRedirect( widget, PtSampContainerRedirect );

The PtMenuBar widget uses this feature to prevent certain types of

widgets from being added to a menu bar. For more information, see
“Container widget anatomy” in the Anatomy of a Widget chapter.

Compound widgets
The compound class is used to design widgets made from other
widgets. The compound class is a subclass of the container class, so it

30 Chapter 2 ¯ Life Cycle of a Widget September 20, 2005

 2005, QNX Software Systems Compound widgets

inherits the functionality described above for containers. In addition,

the compound class adds a mechanism for exporting subordinate
widgets. This is achieved by extending the container class definition
to include:

¯ the number of subordinates

¯ a list of subordinates
¯ the number of blocked resources
¯ a list of blocked resources

The exporting mechanism lets users set and get the resources of
subordinate widgets by treating the compound widget as if it actually
were the subordinate widget.
A good example is the PtComboBox widget — it’s built from a text
widget and a list widget. It also defines its own behavior by supplying
a pull-down button beside the text widget for accessing the list widget.
You can change the subordinate widgets inside a compound widget
using the resources defined for the subordinate widgets. For example,
you could change the PtText widget inside a PtComboBox widget
by using the widget pointer of the PtCompound widget as follows:
PtArg t args[1];

PtSetArg( &args[0], Pt ARG TEXT STRING,

"Subordinate Text" 0 );
PtSetResources( mycombobox widget pointer, 1, args );

This is a very powerful feature that greatly simplifies the construction

of compound widgets since resources don’t have to be duplicated.
However, changing the resources of subordinate widgets could
destroy the look and feel of a compound widget. For this reason, we
recommend that you consider using the blocking mechanism in a
custom compound class. The blocking mechanism lets the compound
class discard attempts to set specific resources on its subordinate
widgets. The compound class can override any resource defined by its
superclasses or by its subordinate widgets.

September 20, 2005 Chapter 2 ¯ Life Cycle of a Widget 31

Compound widgets  2005, QNX Software Systems

Exporting subordinate widgets

A compound widget identifies the widgets it intends to export in the
class-creation function. This is done by setting values for the number
of subordinates and the list of subordinates.
Each widget specified in the list of subordinates must be created in the
Defaults method of the compound class.
For more information, see “Compound widget anatomy” in the
Anatomy of a Widget chapter. For an example, the
/qnx4/phtk/src/widgets directory contains source code for a
compound widget called PtSampCompound.

32 Chapter 2 ¯ Life Cycle of a Widget September 20, 2005

 Chapter 3
Anatomy of a Widget

In this chapter. . .
Defining resources 35
Defining the widget class 47
Class methods 55
Widget actions 71
Container widget anatomy 74
Compound widget anatomy 81

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 33

 2005, QNX Software Systems Defining resources

The first part of this chapter discusses requirements applicable to all

widget classes:

This section: Describes:

Defining resources All aspects of defining resources
Defining the widget class The widget class structure and each of
its fields
Class methods Every class method and how each is
used
Widget actions How to make your widget interactive

You’ll find information about the additional requirements for building

container and compound widgets at the end of the chapter.

Defining resources
There are two steps to defining the resources of your widget class
(aside from deciding what they should be in the first place):

1 Defining the resource manifests and numbers.

2 Defining the resource records to provide access to the resources

of the widget class via resource manifests.

Resource manifests
Define the resources to introduce for a widget class (i.e. the resources
that don’t already exist in any of the widget superclasses). This is
done in the widget’s header file (e.g. PtButton.h) as a series of
#define statements:

/*
* PtButton public
*/

/* Resources */
#define Pt ARG ARM COLOR Pt RESOURCE( 6, 0 )

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 35

Defining resources  2005, QNX Software Systems

#define Pt ARG ARM DATA Pt RESOURCE( 6, 1 )

#define Pt ARG ARM FILL Pt RESOURCE( 6, 2 )

/* PtButton instance structure */

typedef struct Pt button widget {
PtLabelWidget t label;
PgColor t arm color;
void *arm data;
void *unarmed data;
uchar t arm fill;
} PtButtonWidget t;

All resource manifest names and numbers must be unique. In the

above example, Pt ARG ARM COLOR represents a unique resource
manifest name, Pt RESOURCE( 6, 0 ) represents a unique
resource number, and the resource itself has a corresponding entry in
the widget instance structure called arm color.
When you build a new widget, you need to pick a unique widget
number for it. The header file PtT.h contains two macros to help you
do this:
Pt RESOURCE( widget number, resource number)
Pt USER( widget number )

☞ The Pt USER() macro is designed for widgets being created for

in-house use only. If you intend to distribute the widgets you create as
a public domain or commercial library, please contact QSSL
Customer Service. They’ll give you a unique range of widget
numbers and assign your widget set a prefix. This will prevent your
widget library from conflicting with another third party’s commercial
widget library.

In your first in-house widget, use:

#define MY 1ST WIDGET RESOURCE1 Pt RESOURCE( Pt USER( 1 ), 0 );
#define MY 1ST WIDGET RESOURCE2 Pt RESOURCE( Pt USER( 1 ), 1 );

In your second in-house widget, use:

#define MY 2ND WIDGET RESOURCE1 Pt RESOURCE( Pt USER( 2 ), 0 );
#define MY 2ND WIDGET RESOURCE2 Pt RESOURCE( Pt USER( 2 ), 1 );

36 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Defining resources

The macro Pt USER( 1 ) defines a widget number that allows up to

1000 resources: it specifies the widget number 5,001,000. The macro
Pt USER( 2 ) defines the number 5,002,000, and so on.
The second part of the Pt RESOURCE() macro defines the resource
number: Pt RESOURCE( Pt USER( 2 ), 5 ) defines the
resource number 5,002,005. The widget defined by Pt USER( 2 )
can define unique resources numbers from 5,002,000 to 5,002,999.

PtResourceRec t resource records

Resource records are used to connect the resource manifests described
above with the widget’s structure members. The resource records are
defined as a table in the source code file and are passed as an
argument when you first create the widget class.
This is a table of PtResourceRec t items. This structure is
declared as follows:
typedef struct Pt resource rec {
unsigned long type;
void (*mod f)( PtWidget t *, PtArg t const * );
int (*query f)( PtWidget t const *, PtArg t * );
unsigned long arg value;
unsigned long arg len;
} PtResourceRec t;

type member
The value (manifest) to which this record is connected through a
widget instance member. For example, Pt ARG FLAGS.

mod f member
The function to call when this resource is being set by the user. This
member recognizes several special convenience values other than the
address of a function. Special values include:

Pt CHANGE INVISIBLE
Set the widget member but otherwise leave the widget
unaffected.

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 37

Defining resources  2005, QNX Software Systems

Pt CHANGE REDRAW
Change the widget member and damage the widget (this causes
a redraw).
Pt CHANGE INTERIOR
Same as Pt CHANGE REDRAW, except the widget’s canvas
alone is damaged (the borders aren’t redrawn).

Pt CHANGE RESIZE
Change the widget structure member and flag the widget for
resize. The resize is held off until the end of the
PtSetResources() call in case other Pt CHANGE RESIZE-type
resources are set in the same call. The resize is performed via
PtMoveResizeWidget(), and the Extent method of the widget
class is called.
Pt CHANGE RESIZE REDRAW
Same as Pt CHANGE RESIZE, but forces a redraw even if the
widget’s dimensions or extent aren’t changed.

Pt CHANGE PREVENT
Don’t change the widget structure member and don’t affect the
widget. Indicates a read-only resource.

Pt CHANGE CANVAS
Invalidate the widget’s canvas so that it’s recalculated the next
time it’s requested. Additionally, resize the widget.
Pt CHANGE CANVAS REDRAW
The same as Pt CHANGE CANVAS, but force the widget to be
redrawn even if its canvas and extent aren’t changed.

query f member
The function to call when this resource is being queried via
PtGetResources(). If no function is provided (i.e query f is NULL),
the resource is reported in the normal manner (see PtSetArg() and
PtGetResources() in the Photon Library Reference).

38 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Defining resources

The special values of the query f field member include:

Pt QUERY PREVENT
Prevents access to the resource. Any pointers provided are set
to NULL. Indicates a write-only resource.

arg value and arg len members

These are bit-encoded fields that set members of a widget structure.
The arg value member is used for all resources; arg len is used to set
a second widget structure member. For an array, arg len has the type
and offset of the array counter. For a Boolean value, arg len is a
bitmask. Unless the resource is an array or Boolean type, arg len is
normally 0.
The data encoded into these fields includes:

¯ the data type of the member this resource is associated with

¯ the offset from the address of the widget structure to the member
to get/set

¯ if necessary for struct or array resources, the size of the

structure member.

The following macros make using arg value and arg len more
convenient:

¯ Pt ARG IS NUMBER

¯ Pt ARG IS FLAGS

¯ Pt ARG IS STRING

¯ Pt ARG IS STRUCT

¯ Pt ARG IS POINTER

¯ Pt ARG IS ALLOC

¯ Pt ARG IS LINK

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 39

Defining resources  2005, QNX Software Systems

¯ Pt ARG IS CALLBACK LIST (or Pt ARG IS CALLBACK)

¯ Pt ARG IS BOOLEAN

¯ Pt ARG IS ARRAY

The sections that follow describe the values of the arg value and
arg len members for each type of resource. For most resources,
arg len isn’t used; unless mentioned otherwise below, set it to 0.

☞ Memory for some of the resources (indicated below) is allocated and

freed as needed. If you have a Destruction method, you don’t need to
free the memory for these resources. If you do free any memory, you
must set the pointers freed to NULL or unexpected results may occur.

Scalar resources

arg value C type of member1

Pt ARG IS NUMBER(wgt, member1) char, short, or long
(signed or unsigned)

Flags resources

arg value C type of member1

Pt ARG IS FLAGS(wgt, member1) char, short, or long
(preferably unsigned)

For Flags resources, the “mask” isn’t part of the resource — it’s just a
way of telling the resource-setting API which bits the application
wants to preserve.

40 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Defining resources

String resources

arg value C type of member1

Pt ARG IS STRING(wgt, member1) char *

This resource is allocated, based on the value returned by strlen(); see

the note above.

Struct resources

arg value C type of member1

Pt ARG IS STRUCT(wgt, member1) Any type

These are widget members that are of a fixed size. When setting such
resources, you pass a pointer to the value, and the value is copied into
the widget structure. This type is useful for structures, as well as other
data types that won’t fit into a long (such as float or double).

Pointer resources

arg value C type of member1

Pt ARG IS POINTER(wgt, member1) Any type of pointer,
including void *

The widget does a shallow copy of the pointer’s value.

Alloc resources

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 41

Defining resources  2005, QNX Software Systems

arg value C type of member1

Pt ARG IS ALLOC(wgt, member1) Any type of pointer,
including void *

Space is allocated for the resource, with the size specified by the
application; see the note above.

Link resources

arg value C type of member1

Pt ARG IS LINK(wgt, member1) A pointer to a structure

The structure must start with a “next” pointer. Space is allocated for
the resource; see the note above.

Callback resources

arg value C type of member1

Pt ARG IS CALLBACK LIST(wgt, member1) A pointer to a
structure

The structure must start with a “next” pointer. Space is allocated for
the resource; see the note above.

Boolean resources

42 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Defining resources

arg value C type of member1

Pt ARG IS BOOLEAN(wgt, member1) char, short, int, or
long (preferably
unsigned)

The arg len is the bitmask. It’s not stored anywhere in the widget —
it’s just a constant that determines in which bit of the widget structure
the resource is stored.

Array resources

arg value C type of member1

Pt ARG IS ARRAY(wgt, member1) A pointer to some type

This type of resource also uses arg len:

arg len C type of member2

Pt ARG IS NUMBER(wgt, member2) char, short, or long

The size of each array element is the size of the type pointed to by
member1. Space is allocated for the resource; see the note above.

Examples
Now let’s look at some sample resource declarations. First let’s look
back at our original widget example, the ShadowedBox widget. It
defines two resources in the header file:
/* widget resources */
#define SBW SHADOW COLOR Pt RESOURCE( Pt USER( 0 ), 0 )
#define SBW SHADOW OFFSET Pt RESOURCE( Pt USER( 0 ), 1 )

/* widget instance structure */

typedef struct shadowed box widget{
PtBasicWidget t basic;
PgColor t shadow color;

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 43

Defining resources  2005, QNX Software Systems

short shadow offset;

} ShadowedBoxWidget;

The source code file defines the table of resources, which connects the
resources to the widget class:

static PtResourceRec t resources[] = {

SBW SHADOW COLOR, Pt CHANGE REDRAW, 0,
Pt ARG IS NUMBER( ShadowedBoxWidget, shadow color ), 0,
SBW SHADOW OFFSET, Pt CHANGE RESIZE REDRAW, 0,
Pt ARG IS NUMBER( ShadowedBoxWidget, shadow offset ), 0,
};

Let’s examine the first resource in the table in more detail:

¯ SBW SHADOW COLOR is the type member, which we defined as

a unique resource number at the top of the widget code.

¯ Pt CHANGE REDRAW is the mod f member, which tells the

library how this resource should be handled if the resource is set. It
could be either a special value (as in the example) or a function
within the source file code. In the example, Pt CHANGE REDRAW
tells the library that the widget needs to be redrawn if the resource
value changes.

¯ The next member, 0, is the query f member, which tells the library
how this resource should be retrieved. It can be one of:
- 0, which causes the widget library to retrieve the resource based
on the information provided by the arg value and arg len bit
fields
- a function within the source file
- Pt QUERY PREVENT

¯ The next member is arg value. This is a bit-encoded field. In our

example, Pt ARG IS NUMBER indicates that the widget structure
member associated with this resource is a value of type char,
short, or long.

¯ The last member, arg len, is 0 (not used).

44 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Defining resources

Now let’s look at a more detailed example. In the widget header file
we have:
/* widget resources */
#define MW ARG MY CHARACTER Pt RESOURCE( Pt USER(1), 0 )
#define MW ARG MY STRING Pt RESOURCE( Pt USER(1), 1 )
#define MW ARG MY SHORT Pt RESOURCE( Pt USER(1), 2 )
#define MW ARG MY FLAGS Pt RESOURCE( Pt USER(1), 3 )
#define MW ARG MY FLAG BIT Pt RESOURCE( Pt USER(1), 4 )
#define MW ARG MY POINT ARRAY Pt RESOURCE( Pt USER(1), 5 )
#define MW ARG MY TAG DATA Pt RESOURCE( Pt USER(1), 6 )
#define MW CB MY CALLBACK Pt RESOURCE( Pt USER(1), 7 )

#define MW MY FLAG BIT 0x04000000

/* widget instance structure */

typedef struct my widget{
PtBasicWidget t basic; //Subclass of PtBasic.
char character;
char *my string;
short my short;
long flags;
PhPoint t *points; //Array of points.
ushort t num points;
void *tag data;
PtCallbackList t *my callbacks; //Linked list of callbacks.
} MyWidget t;

In the class-creation function in the source code file we have:

static const PtResourceRec t resources = {
Pt ARG POS, arg pos override, 0,
Pt ARG IS NUMBER( PtWidget t, area.pos ), 0,

MW ARG MY CHARACTER, Pt CHANGE REDRAW, 0,

Pt ARG IS NUMBER( MyWidget t, character ), 0,

MW ARG MY STRING, Pt CHANGE RESIZE REDRAW, 0,

Pt ARG IS STRING( MyWidget t, my string ), 0,

MW ARG MY SHORT, set my short, get my short, 0, 0,

MW ARG MY FLAGS, Pt CHANGE INVISIBLE, 0,

Pt ARG IS FLAGS( MyWidget t, flags ), 0,

MW ARG MY FLAG BIT, Pt CHANGE INVISIBLE, 0,

Pt ARG IS BOOLEAN ( MyWidget t, flags ),
MW MY FLAG BIT,

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 45

Defining resources  2005, QNX Software Systems

MW ARG MY POINT ARRAY, Pt CHANGE RESIZE REDRAW, 0,

Pt ARG IS ARRAY( MyWidget t, points ),
Pt ARG IS NUMBER( MyWidget t, num points ),

MW ARG MY TAG DATA, Pt CHANGE INVISIBLE, 0,

Pt ARG IS ALLOC( MyWidget t, tag data ), 0,

MW CB MY CALLBACK, Pt CHANGE INVISIBLE, 0,

Pt ARG IS CALLBACK LIST( MyWidget t, my callback ), 0,
}

Pt ARG POS is inherited from PtWidget. Here we’re overriding its

mod f() function with one of its own.
The MW ARG MY SHORT resource and mod f()/query f() functions
could look like this:
static void set my short( PtWidget t *widget, PtArg t *argt )
{
MyWidget t *mw = (MyWidget t *)widget;

if( mw->my short == (short)argt->value )

return; // don’t do work if nothing is changing.

mw->my short = argt->value;

// My widget needs to redraw when my short changes...

PtDamageWidget( widget );
}

static int get my short( PtWidget t *widget, PtArg t *argt )

{
MyWidget t *mw = (MyWidget t *)widget;

if( argt->value )
// The address of a pointer to a short is in argt->value
*(short **)argt->value = &mw->my short;
else
argt->value = (long) mw->my short;
return Pt TRUE;
/* The only time one would return Pt FALSE is if no data
is given as a result of the query */
}

For more examples of resources and mod f()/query f() functions, see
the /qnx4/phtk/src/widgets and /qnx4/phtk/src/contrib
directories, which contain many widget examples and templates.

46 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Defining the widget class

Defining the widget class

In Photon, a widget class is defined much a like a widget. You set up a
list of arguments or class resources and call PtCreateWidgetClass().
This list is used to set the field members of the widget class structure
that Photon uses to determine how to handle the widget.

Widget class structure

Let’s look at the general form of a PtWidgetClass t structure:

struct Pt widget class {

struct Pt widget class *superclass;
PtWidgetClassRef t *class ref;
unsigned class len;
unsigned state len;
unsigned long flags;
void (*dflts f)( PtWidget t * );
int (*init f)( PtWidget t * );
void (*extent f)( PtWidget t * );
int (*connect f)( PtWidget t * );
void (*draw f)( PtWidget t *,
PhTile t * );
int (*unrealize f)( PtWidget t * );
int (*realized f)( PtWidget t * );
int (*destroy f)( PtWidget t * );
PtResourceRec t *resources;
unsigned num resources;
PtRawCallbackList t *callbacks;
PhSoul t widget souls;
int (*setres f)( PtWidget t *, int,
PtArg t * );
int (*getres f)( PtWidget t *, int,
PtArg t * );
short version;
short spare;
};

typedef struct Pt widget class PtWidgetClass t;

Widget class structure description

Let’s look at the PtWidgetClass t structure one member at time:

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 47

Defining the widget class  2005, QNX Software Systems

PtWidgetClass t *superclass
A pointer to the superclass of this widget class.
This value defines the superclass this class inherits
from. If a widget class is at the top of the
hierarchy, this pointer is NULL.

PtWidgetClassRef t *class ref

A pointer to the class ref structure for this widget
class.
unsigned class len
The size of this widget class (this differs from the
superclass only if the class extends the superclass
definition).
unsigned state len
The size of the widget instance structure for this
widget class.

unsigned long flags

A general flag field for widget classes. Valid
widget flag bits are:

Pt CONTAINER The widget class is a container.

Pt RECTANGULAR
Rectangular widgets are opaque
when filled. Opaque widgets
don’t damage widgets below
them when they’re modified
(unless their size or position is
modified).
Pt CLEAN RESOURCES
(set, cleared, and used internally)
Indicates that all resources in a
widget class’s resource list are
in a single range. This is used as
an optimization allowing a

48 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Defining the widget class

widget’s resources to be indexed

as an array.
Pt UNCLEAN RESOURCES
Prevents the resources of a
widget class from being
indexed. This is necessary if the
widget class defines resources
only to override a superclass
(i.e. the widget class doesn’t
define any new resources).
Pt INDEX RESOURCES
(set, cleared, and used internally)
Indicates the resources are clean
and continuously sequential —
the resources may be indexed
instead of traversed.
Pt FORCE UNREALIZE
(set automatically when required)
The Unrealization method
(unrealize f()) for this class and
its superclasses is called when
this widget is unrealized.
Pt DISJOINT
(e.g. PtWindow, PtMenu, PtRegion)
Indicates that widgets of this
class own regions that aren’t
children of the regions of their
widget parents. Any clipping set
by the parent of a disjoint
widget won’t be applied to the
disjoint widget. The regions of
disjoint widgets are sensitive
and opaque to expose events.
Pt NO INHERITED RESOURCES
Prevents the search for a
resource from walking up
through superclasses. Only the

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 49

Defining the widget class  2005, QNX Software Systems

resources for this class are

handled; all others are ignored.
This doesn’t prevent resources
from being propagated to
procreated widgets.
This is handy for allowing
common resources such as
Pt ARG COLOR to pass to
procreated children without
having to write a
resource-redirection function.
Pt OCCLUSIVE Drawing routines skip all
children of a widget derived
from an occlusive class. The
rendering of these children is
the responsibility of the
occlusive widget.

void (*dflts f )(PtWidget t *)

Defines the Defaults method.
int (*init f )(PtWidget t)
Defines the Initialization method.
void (*extent f )(PtWidget t *)
Defines the Extent method.
int (*connect f )(PtWidget t *)
Defines the Connection method.
void (*draw f )(PtWidget t *, PhTile t *)
Defines the Draw method.
void (*unrealized f )(PtWidget t *)
Defines the Unrealization method.
void (*destroy f )(PtWidget t *)
Defines the Destruction method.

50 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Defining the widget class

PtResourceRec t *resources
An array of resources the widget class handles
directly when a user calls PtSetResources() or
PtGetResources().
unsigned num resources
The number of resources in the resources array.

PtRawCallbackList t *callbacks
The list of widget actions (raw callbacks) for the
widget class. If a function in the callback list has
an event mask matching the event being handled,
that function is invoked.
PhSoul t widget souls
Used for managing the memory associated with
instances of this widget class.

int (*setres f )(PtWidget t *, int, PtArg t *)

Defines the Set Resources method that’s called
when a user calls PtSetResources() on a widget of
this class.

int (*getres f )(PtWidget t *, int, PtArg t *)

Defines the Get Resources method that’s called
when a user calls PtGetResources() on a widget of
this class.

short version The version number of the widget with respect to

the widget library. The version number should be
at least 110.

Widget class resource table

Not all members of the widget class structure can be set directly;
some are used internally by the widget library. The members you can
change using the class resource manifests are:

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 51

Defining the widget class  2005, QNX Software Systems

Member Description Resource manifest

state len Instance length Pt SET STATE LEN
flags Flags Pt SET FLAGS
dflts f Defaults method Pt SET DFLTS F
init f Initialization method Pt SET INIT F
extent f Extent method Pt SET EXTENT F
connect f Connection method Pt SET CONNECT F
draw f Draw method Pt SET DRAW F
unrealized f Unrealization method Pt SET UNREALIZE F
realized f Realization method Pt SET REALIZED F
destroy f Destruction method Pt SET DESTROY F
resources Table of resources Pt SET RESOURCES
num resources Number of resources Pt SET NUM RESOURCES
callbacks Raw callbacks Pt SET RAW CALLBACKS
setres f Set Resources method Pt SET SETRESOURCES F
getres f Get Resources method Pt SET GETRESOURCES F
version Version number Pt SET VERSION

When defining a custom widget class, you can extend the definition of
its superclass with new “class-level” methods and/or callbacks. For
example, the PtWidget class is extended by PtBasic, which adds
new class methods for providing focus notification. This was done as
shown in the following excerpt from the PtBasic.h header file:

52 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Defining the widget class

typedef struct Pt basic widget class {

PtWidgetClass t core;
void (*got focus f)( PtWidget t *,
PhEvent t * );
void (*lost focus f)( PtWidget t *,
PhEvent t * );
void (*calc opaque f)( PtWidget t * );
} PtBasicWidgetClass t;

#define Pt SET GOT FOCUS F (Pt ARG IS POINTER(PtBasicWidgetClass t,got focus f))
#define Pt SET LOST FOCUS F (Pt ARG IS POINTER(PtBasicWidgetClass t,lost focus f))
#define Pt SET CALC OPAQUE F (Pt ARG IS POINTER(PtBasicWidgetClass t,calc opaque f))

When a class definition is extended in this way, the new class

structure size must be passed as the second parameter to
PtCreateWidgetClass():

PtBasic->wclass = PtCreateWidgetClass( PtWidget,

sizeof(PtBasicWidgetClass t ),... );

If the class isn’t extended, the second parameter may be passed as 0.

Also, when the class is extended, you must define new Pt SET*
manifests to provide access to the new class members from the create
class function.

PtBasic class resource additions

The PtBasic widget class provides the following three additional
structure members:

Member Description Resource manifest

got focus f Got Focus method Pt SET GOT FOCUS F
lost focus f Lost Focus method Pt SET LOST FOCUS F
calc opaque f Calc Opaque Rect Pt SET CALC OPAQUE F
method

Let’s look at the class resource table from our ShadowedBox example
in more detail:

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 53

Defining the widget class  2005, QNX Software Systems

static PtArg t args[] = {

{ Pt SET VERSION, 110},
{ Pt SET STATE LEN, sizeof( ShadowedBoxWidget ) },
{ Pt SET DFLTS F, (long)shadowedbox dflts },
{ Pt SET DRAW F, (long)shadowedbox draw },
{ Pt SET FLAGS, 0, Pt RECTANGULAR },
{ Pt SET NUM RESOURCES,
sizeof( resources ) / sizeof( resources[0] ) },
{ Pt SET RESOURCES, (long)resources,
sizeof( resources ) / sizeof( resources[0] ) },
};

Pt SET VERSION Tells the widget library what style this widget is.
For your widgets, this value is always at least 110
(110 corresponds to Photon 1.10 style).
Pt SET STATE LEN
Defines the length of the widget instance structure.

Pt SET DFLTS F Defines the Defaults method, which is called to set

default values for the widget when it’s first
created. In our example, this function is called
shadowedbox dflts().
Pt SET DRAW F Defines the Draw method (e.g.
shadowedbox draw()), which is called when the
widget needs to be drawn.
Pt SET FLAGS Defines behavioral flags related to this widget
class. This example turns off the
Pt RECTANGULAR flag, which indicates the
widget can’t take advantage of flicker-free,
opaque-drawing methods.
Pt SET NUM RESOURCES
Defines the number of resources in the table.
Pt SET RESOURCES
Defines the table of resources unique to this
widget, as described above.

54 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Class methods

Class methods
This section describes the role and responsibilities of the class
methods defined in the widget class structure. The fundamental
methods defined by PtWidget are:

¯ Defaults

¯ Initialization

¯ Extent

¯ Connection

¯ Realization

¯ Draw

¯ Unrealization

¯ Destruction

¯ Set Resources

¯ Get Resources

The PtBasic widget extends these with three additional methods:

¯ Got Focus

¯ Lost Focus

¯ Calc Opaque Rect

These are the methods you write to define the functionality of your
widget. Not all methods need to be defined and coded by a widget
class; they can be inherited from a superclass. Almost all widgets
need at least the Draw method, since the primary purpose of building
a custom widget is to draw something.

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 55

Class methods  2005, QNX Software Systems

Defaults method
Type: Chained down, unstoppable
This method sets the default values for all widget instance structure
members. It’s called during the creation of a widget instance (call to
PtCreateWidget()). When a widget instance is first created, all
members of the instance structure are zeroed out and then the
Defaults method for each parent class (starting from PtWidget at the
top) are called in sequence from top to bottom. This allows the
lower-level classes to override the default values set by the parent
classes in the hierarchy. Here’s an example showing how to initialize
PtBasic variables:

static void basic dflts( PtWidget t *widget )

{

PtBasicWidget t *basic = (PtBasicWidget t *) widget;

widget->border width = 2;
widget->cursor color = Ph CURSOR DEFAULT COLOR;
widget->resize flags |= Pt RESIZE XY AS REQUIRED;

basic->color = Pg BLACK;
basic->fill color = Pg GREY;
basic->top border color = Pg WHITE;
basic->bot border color = Pg DGREY;
basic->flags = Pt DAMAGE ON FOCUS;
}

Although the instance variables in this example are specific to

PtBasic, the initialization technique is common to all Defaults
methods.

Initialization method
Type: Chained up, stoppable
This is the first method called when a widget is realizing (call to
PtRealizeWidget()). The Initialization method does final checks to
ensure the widget is “extentable.” This check ensures all members
used in the subsequent Extent method are correctly assigned.

56 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Class methods

The Initialization method is also the best place to create unexported

subordinate widgets. Unexported subordinate widgets are used by the
widget but not available to the user. For example, a dialog widget like
PtMessage uses other widgets (PtWindow, PtLabel, and
PtButton) but doesn’t allow the user to act directly on the
subordinate widgets. Instead, the widget provides new unique
resources used internally to set the subordinate widgets. For more
information about exported subordinate widgets, see “Compound
widget anatomy” later in this chapter.
Initialization is executed each time the widget is realized. The
Initialization method is called first for this widget followed by its
parent superclass and so on until the core widget class (PtWidget) is
reached. Any widget class in the chain can terminate the chaining
process by returning Pt END.
Here’s an example showing how a PtContainer widget is
initialized:

static in PtContainerInit( PtWidget t *widget )

{
PtContainerRegister( widget );
return( Pt CONTINUE );
}

The Initialization method is also used to register widgets for balloon

handling. All container widgets provide a default balloon-handling
mechanism. If you want your widget to support popup help balloons,
you must register the widget with the container in this function.
Here’s an excerpt from the PtLabel code:

static int label init( PtWidget t *widget )

{
PtLabelWidget t *label = (PtLabelWidget t *) widget;
PtBalloonCallback t bcalls;
PtArg t argt;

if( (label->flags & Pt SHOW BALLOON)

&& ( !( label->flags & Pt BALLOON REGISTERED ) ) )
{
bcalls.widget = widget;
bcalls.event f = label balloon callback;
PtSetArg( &argt, Pt CB BALLOONS, &bcalls, 0 );

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 57

Class methods  2005, QNX Software Systems

PtSetResources( widget->parent, 1, &argt );

label->flags |= Pt BALLOON REGISTERED;

}
return Pt CONTINUE;
}

Extent method
Type: Inherited
This is the second method called during the realization of a widget
(call to PtRealizeWidget()). The Extent method is responsible for
determining the widget’s screen real estate (bounding box) with
regard to its resize policy. The Extent method is called frequently
during the life of a widget — whenever the widget is moved or
resized, or resources marked as Pt CHANGE RESIZE or
Pt CHANGE RESIZE REDRAW are modified.
The following are examples of these types of resources, as defined by
the PtWidget class:
static PtResourceRec t resources[] = {
{ Pt ARG AREA, Pt CHANGE RESIZE, 0,
Pt ARG IS STRUCT(PtWidget t, area) },

{ Pt ARG POS, Pt CHANGE RESIZE, 0,

Pt ARG IS STRUCT(PtWidget t, area.pos) },

{ Pt ARG DIM, Pt CHANGE RESIZE, 0,

Pt ARG IS STRUCT(PtWidget t, area.size) },
};

In addition, the Extent method is called whenever any other resource

causes a widget to change size or position. The following example
code is taken from PtLabel:
static PtResourceRec t resources[] = {
{ Pt ARG LABEL TYPE, Pt CHANGE RESIZE REDRAW, 0,
Pt ARG IS NUMBER(PtLabelWidget t, type), 0 },
};

58 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Class methods

The widget engine uses the extent calculated in this method to

determine when this widget is involved in an event, when the widget
needs to be repaired, and which other widgets need to be repaired
when this one changes.
Every widget class inherits the Extent method of its superclass. If this
method is suitable, you won’t need to provide your own Extent
method. If the superclass’s Extent method isn’t quite what your
widget needs, you should provide only what the widget’s superclass
doesn’t provide, then call the Extent method of the superclass to do
the rest of the work.
It’s unusual to write an Extent method that calculates the entire extent
without using the superclass’s method. Quite often you’ll want most,
but not all, of the superclass’s extent behavior. There’s usually a way
to prevent the Extent method of the superclass from performing any
set of extenting behaviors (see the “Extent method” sections in the
Using Widget Superclasses chapter for details).
Extenting a widget usually involves four stages:

1 Calculate the canvas. Check the chapter on Using Widget

Superclasses for canvas services. The canvas is the area within
which a widget must restrict its rendering. The most commonly
used canvas function is PtBasicWidgetCanvas().
2 Calculate the render rectangle. This is the bounding box area
required for this widget to display all its data, including points,
widget children, any text strings, etc.
3 Call PtAttemptResize(), passing to it the widget, canvas, and
render rectangle. PtAttemptResize() applies the widget’s resize
policy automatically and modifies the widget’s dimensions as
required to ensure the widget conforms to its resize policy.
If a widget’s canvas can’t be resized to encompass the render
rectangle, PtAttemptResize() sets the Pt UCLIP bit in the
widget’s resize flags. The widget’s Draw method should check
the Pt UCLIP bit. If this bit is set, the Draw method should
apply clipping to prevent the widget from rendering outside its
canvas.

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 59

Class methods  2005, QNX Software Systems

4 Call
PtSuperClassExtent( PtBasic, widget)

to have the final extent calculation performed. The Extent

method of PtBasic uses the widget’s position, dimension,
border width, and flags to determine the extent.

Here’s an example showing how to apply these guidelines:

mywidget extent( PtWidget t *widget )
{
MyWidgetUnion t *mwu = (MyWidgetUnion t *)widget;
PhRect t canvas, render;

PtBasicWidgetCanvas( widget, &canvas );

render.ul = render.lr = canvas.ul;
PgExtentText( &render, &render.ul, mwu->label.font,
mwu->label.string, 0 );
PtAttemptResize( widget, &canvas, &render );
PtSuperClassExtent( PtBasic, widget );
}

Connection method
Type: Chained up, stoppable
This is the third method called during the realization of a widget (call
to PtRealizeWidget()). The Connection method creates any required
Photon regions. Generally, it isn’t necessary to explicitly create your
own region since the Connection method of PtWidget does this for
you.
However, it may be beneficial to create your own region if you need to
modify the region based on the current environment. For example,
PtMenu widgets have to modify a region whenever they’re displayed:

static int menu connect( PtWidget t *widget )

{
PhRegion t region;
unsigned fields;
PhRect t rect;
PtMenuWidget t *menu = (PtMenuWidget t *)widget;
PtWidget t *wp;

60 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Class methods

/* calculate menu region */

fields = UINT MAX;
if( !PtCalcRegion( &fields, widget, &region, &rect ) )
return( -1 );

/* open menu region */

region.parent = menu->ff wgt->rid;
region.events opaque |= Ph EV DRAW | Ph EV PTR ALL;
region.events opaque &= ˜Ph EV KEY; region.events sense
|= Ph EV PTR ALL; region.events sense &= ˜Ph EV KEY;
region.flags = 0;
fields |= Ph REGION PARENT | Ph REGION EV SENSE |
Ph REGION EV OPAQUE;
fields &= ˜( Ph REGION BEHIND | Ph REGION IN FRONT );
widget->rid = PhRegionOpen( fields, &region, &rect, NULL );
wp = widget;
while( PtWidgetIsClass( wp, PtMenu ) )
{ menu pdr start( wp );
if ( !wp->parent )
break;
wp = wp->parent->parent;
}
if( widget->parent &&
PtWidgetIsClassMember( widget->parent, PtContainer ) )
{ if( !( menu->flags & Pt MENU CHILD ) )
{
// If the menu is off a window, focus that window.
PhEvent t event;
memset( &event, 0, sizeof( event ) );
menu->prev focus =
PtContainerFindFocus( widget->parent );
if( widget->parent->class rec->flags & Pt DISJOINT )
PtContainerNullFocus( widget->parent, &event );
else
{
int flags = widget->parent->flags;
widget->parent->flags |= Pt GETS FOCUS;
PtContainerGiveFocus(
widget->parent, &event );
widget->parent->flags = flags;
}
} else
menu->flags |= Pt MENU SUBFOCUS;
((PtContainerWidget t *)widget->parent)->focus = widget;
}
wp = PtFindDisjoint( widget );
for( wp = wp->parent;
wp && (PtWidgetIsClassMember(wp, PtMenu)
|| PtWidgetIsClassMember(wp, PtMenuButton));
wp = wp->parent);

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 61

Class methods  2005, QNX Software Systems

if( wp )
{
wp = PtFindDisjoint( wp );
if (PtWidgetIsClassMember( wp, PtWindow ))
((PtContainerWidget t *)wp)->last focus = NULL;
if( !( PtWindowGetState( wp ) & Ph WM STATE ISFOCUS ) ) {
PtWindowFocus( wp );
}
}
}

/* stop init chaining */

return( Pt END );
}

If you create your own region, the Connection method of PtWidget

won’t create another region — it modifies the current region. To
prevent modification of the current region, have the widget class
return Pt END.

Realization method
Type: Inherited
This method is called after a widget has been realized. Its function is
similar to that of the Pt CB REALIZED callback, but unlike the
Pt CB REALIZED callback, it can’t be accessed by any developer
using your widget.
This method is used primarily by compound widgets to perform any
postrealize operations, such as realizing any subordinate widgets that
couldn’t be realized to this point. It’s the last method to be called
prior to the Draw method, and it’s invoked just prior to the user’s
Pt CB REALIZED callbacks. For more information, see the section
on “Compound widget anatomy.”

Draw method
Type: Inherited
This is the last method called during the realization process. The
Draw method is used to render the widget on the screen during

62 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Class methods

realization and is called to redraw a widget afterwards whenever that

widget is damaged.
When a widget is damaged, a pointer to the damaged widget and a list
of tiles describing the damage are passed to the Draw method. The
first tile in the damage list reveals the total extent of the damage (its
bounding box encompasses all remaining tiles). The remaining tiles
contain the actual extents damaged. Unless the widget is complex or
passes a lot of draw data (large images) and can be sped up by
drawing damaged areas only, you should ignore the damage list.
The widget library uses the damage list to clip parts that shouldn’t be
drawn. If you plan to use the damage tiles, make sure to translate the
widget canvas using the widget’s offset. Use PtWidgetOffset() to
obtain the offset — the damage list is relative to the disjoint parent
widget (usually a PtWindow widget).
The Draw method restricts its updates to the canvas of the damaged
widget. This is done by setting a clipping rectangle if necessary.
Here’s a drawing example taken from the code for PtButton:
static void button draw( PtWidget t *widget, PhTile t *damage )
{
PtButtonWidget t *button = (PtButtonWidget t *)widget;
PgColor t tcolor;

button->label.data = button->unarmed data;

/* set fill color to arm color if required */
if ( widget->flags & Pt SET )
{
if( button->arm fill == 1 )
{
tcolor = button->label.basic.fill color;
button->label.basic.fill color = button->arm color;
}
if( button->arm data )
button->label.data = button->arm data;
}

/* draw button - includes highlight */

PtSuperClassDraw( PtLabel, widget, damage );

/* restore fill color */

if ( widget->flags & Pt SET )
{
if ( button->arm fill == 1 )

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 63

Class methods  2005, QNX Software Systems

button->label.basic.fill color = tcolor;

}
}

The following code excerpt (from PtArc) shows how setting the
Pt UCLIP bit in the widget’s resize flags affects clipping:

PtBasicWidgetCanvas( widget, &rect );

if ( widget->resize flags & Pt UCLIP )
PtClipAdd( widget, &rect );
PgDrawArc( &pos, &dim, start, end, arc->type | flags );
if ( widget->resize flags & Pt UCLIP )
PtClipRemove( );

Using the Pg library safely

You’ll use the Pg* functions in your widget’s Draw method, but you
need to use them safely. Here are some things to remember:

PgSetClipping()
PgSetMultiClip()
PgSetUserClip()
These are used by the library. The only safe way
of changing clipping in a widget’s Draw method is
to use PtClipAdd() and PtClipRemove() (see the
Widget Building Library API chapter).

PgSetDrawMode()
PgSetPlaneMask()
PgSetStrokeCap()
PgSetTranslation()
PgSetUnderline()
These aren’t set by the library, but widgets assume
they’re set to their default values. If your Draw
method changes any of them, you have to restore
it.

64 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Class methods

PgSetPalette()
PgSetFillDither()
PgSetFillTransPat()
PgSetStrokeTransPat()
PgSetTextTransPat()
PgSetStrokeWidth()
PgSetStrokeDash()
PgSetStrokeDither()
PgSetStrokeJoin()
These are automatically reset to the default after a
widget’s Draw method returns. It’s safe to change
them.
PgSetFillColor()
PgSetStrokeColor()
PgSetTextColor()
PgSetFillXORColor()
PgSetStrokeXORColor()
PgSetTextXORColor()
There’s no default for these. Set them as needed
before drawing and don’t worry about restoring
them.

PgSetRegion() This is set by the library. If you change it, be sure

to restore it.

For more information about these functions, see the Photon Library
Reference.

Unrealization method
Type: Chained up
This method is called when a widget is being unrealized. The
Unrealization method is responsible for removing any regions created
by a widget (widget->rid is removed automatically by the PtWidget
class’s Unrealization method). The Unrealization method should free
any memory that would be reallocated during the realization process.

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 65

Class methods  2005, QNX Software Systems

The following example shows the PtMessage widget being

unrealized:

static void message unrealize( PtWidget t *widget )

{
PtMessageWidget t *msg = (PtMessageWidget t *) widget;

/* Destroy the message dialog as it’s recreated

through realization */
if ( msg->dlg )
PtDestroyWidget( msg->dlg );
}

The Unrealization method is also used to deregister widgets. For

example, if a label widget registered a balloon in its Initialization
method, it must deregister the balloon in the Unrealization method or
the balloon will try to inflate whenever the mouse pointer pauses over
the last location of the widget. Here’s an example taken from the code
for PtLabel:

static int label unrealize(PtWidget t *widget )

{ PtLabelWidget t *label = (PtLabelWidget t*)widget;
PtBalloonCallback t bcalls;
PtArg t arg;

if(label->balloon widget)
PtDestroyWidget( label->balloon widget );

bcalls.widget = widget;
bcalls.event f = label balloon callback;

if( label->flags & Pt SHOW BALLOON ){

PtSetArg( &arg, Pt CB BALLOONS, &bcalls, Pt LINK DELETE );
PtSetResources( widget->parent, 1, &arg );
}
label->flags &= ˜Pt BALLOON REGISTERED;
return Pt CONTINUE;
}

66 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Class methods

Destruction method
Type: Chained up, unstoppable
This method is called when a widget is being destroyed by the
application. The Destruction method is responsible for releasing all
resources allocated by a widget class during its lifetime. The
Destruction method doesn’t deal with memory allocated by a widget’s
superclass, because each class is responsible for freeing its own
memory. Here’s an example taken from the code for PtButton:
static int button destroy( PtWidget t *widget )
{
PtButtonWidget t *button = (PtButtonWidget t *)widget;

if( ( button->unarmed data ) || ( button->arm data ) )

{
button->label.data = NULL;
if( widget->flags & Pt FREE MEMORY )
{
if( button->unarmed data )
{
free( ((PhImage t *)button->unarmed data)->image );
free( ((PhImage t *)button->unarmed data)->palette );
}
if( ( button->arm data ) &&
( button->arm data != button->unarmed data ))
{
free( ((PhImage t *)button->arm data)->image );
free( ((PhImage t *)button->arm data)->palette );
}
}
}
return( Pt CONTINUE );
}

In the sample code above, button->unarmed data and

button->arm data aren’t freed — this is done automatically by the
widget library.

Set Resources method

Type: Inherited
This method is used to take over the standard resource setting process
built into the Photon library. Compound widgets are the only widgets

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 67

Class methods  2005, QNX Software Systems

that set this method (see the section on “Compound widget

anatomy”).

Get Resources method

Type: Inherited
This method is used to take over the standard resource retrieval
process built into the Photon library. Compound widgets are the only
widgets that set this method (see the section on “Compound widget
anatomy”).

Got Focus method

Type: Inherited
This method is used by subclasses of PtBasic only. It’s called when
a widget gets focus. If your widget gets focus in such a way that the
whole widget need not be redrawn, clear the Pt DAMAGE ON FOCUS
flag (from PtBasic) and damage the appropriate area when your
widget gets focus.
This method isn’t chained. If your class defines a Got Focus method,
you’ll have to either call PtSuperClassLostFocus() to preserve
automatic highlighting and widget-level Got Focus method behavior
or implement the behavior in the Got Focus method of your class.
Here’s an excerpt from the code for PtBasic:

static basic got focus( PtWidget t *widget,

PhEvent t *event)
{
PtBasicWidget t *basic =( PtBasicWidget t *) widget;
PtCallbackInfo t cbinfo;
PtArg t arg;

/* damage the widget so that focus rendering

will take effect */
if( ( widget->flags & Pt FOCUS RENDER ) &&
( basic->flags & Pt DAMAGE ON FOCUS ) )
PtDamageWidget( widget );

/* setup callback structure */

cbinfo.reason subtype = 0;
cbinfo.event = event;

68 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Class methods

cbinfo.cbdata = NULL;

/* an autohighlight widget with focus should invoke ARM */

if( widget->flags & Pt AUTOHIGHLIGHT )
{
PtSetArg( &arg, Pt ARG FLAGS,
Pt HIGHLIGHTED, Pt HIGHLIGHTED);
PtSetResources( widget, 1, &arg );
cbinfo.reason = Pt CB ARM;
PtInvokeCallbackList( basic->arm, widget, &cbinfo );
}

/* invoke got focus callback */

cbinfo.reason = Pt CB GOT FOCUS;
PtInvokeCallbackList( basic->got focus, widget, &cbinfo );
return Pt CONTINUE;
}

Lost Focus method

Type: Inherited
This method is used by subclasses of PtBasic only. It’s called when
a widget loses focus. This method isn’t chained. If your class defines
a Lost Focus method, you’ll have to either call
PtSuperClassLostFocus() to preserve automatic highlighting and
widget-level Lost Focus method behavior or implement the behavior
in the Lost Focus method of your class. Here’s an excerpt from the
code for PtBasic:

static basic lost focus( PtWidget t *widget, PhEvent t *event )

{
PtBasicWidget t *basic =( PtBasicWidget t *) widget;
PtCallbackInfo t cbinfo;
PtArg t arg;
PhRect t wrect, rect = widget->extent;

if( (widget->flags & Pt FOCUS RENDER) &&

( basic->flags & Pt DAMAGE ON FOCUS ) )
if( basic->fill color == Pg TRANSPARENT )
{
PtTranslateRect( &rect,
(PhPoint t*)PtBasicWidgetCanvas( widget->parent,
&wrect ) );
PtDamageExtent( widget->parent, &rect );

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 69

Class methods  2005, QNX Software Systems

}else
PtDamageWidget( widget );
cbinfo.reason subtype = 0;
cbinfo.event = event;
cbinfo.cbdata = NULL;
if( widget->flags & Pt AUTOHIGHLIGHT )
{
PtSetArg( &arg, Pt ARG FLAGS, 0, Pt HIGHLIGHTED );
PtSetResources( widget, 1, &arg );
cbinfo.reason = Pt CB DISARM;
PtInvokeCallbackList( basic->disarm, widget, &cbinfo );
}
cbinfo.reason = Pt CB LOST FOCUS;
PtInvokeCallbackList( basic->lost focus, widget, &cbinfo );
return Pt CONTINUE;
}

Calc Opaque Rect method

Type: Inherited
This method is used only by subclasses of PtBasic. It sets or clears
the widget’s Pt OPAQUE flag (Pt ARG FLAGS resource) and the
Pt RECTANGULAR widget class flag.
When the Pt OPAQUE flag is set for a widget, it means the widget
draws over the entire widget extent area. This allows the widget
library to be smart about redrawing the widget, because it knows that
nothing beneath the widget needs to be redrawn. This flag is essential
for creating flicker-free effects. If any part of the widget is transparent
(i.e. any widget beneath can be seen), the Pt OPAQUE flag must be
cleared. Here’s an excerpt from the code for PtBasic:
static void basic calc opaque( PtWidget t *widget )
{
PtBasicWidget t *basic = (PtBasicWidget t *) widget;

/* if widget is transparent or round it can’t be opaque */

if ( basic->fill color == Pg TRANSPARENT ||
basic>roundness )
widget->flags &= ˜Pt OPAQUE;
else
/* must have RECTANGULAR class flag set */
if ( widget->class rec->flags &
Pt RECTANGULAR ) {

70 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Widget actions

widget->flags |= Pt OPAQUE;
basic opaque rect( widget );
}
}

static void basic opaque rect( PtWidget t *widget )

{
if( widget->flags & Pt HIGHLIGHTED )
memcpy( &widget->opaque rect,
&widget->extent, sizeof( PhRect t ) );
else
PtWidgetCanvas( widget, &widget->opaque rect );
}

Widget actions
Widget actions are used to make a widget interactive. For example,
when you click a button widget, you can see it press in and then pop
out again. This is achieved by setting up raw callbacks sensitive to
specific Photon events. The way a widget interacts with events defines
the widget’s behavior.
The callbacks list, Pt SET RAW CALLBACKS (see the “Widget class
resource table” section earlier in this chapter), defines a widget’s
response if it’s different from the behavior of its superclasses. This
method is defined in the same manner as Pt CB RAW. The primary
difference is that the class’s raw callback list is invoked before the
user’s raw callback list. Here’s an excerpt from the code for PtBasic:
static PtRawCallback t callback = {

Ph EV BUT PRESS | Ph EV BUT RELEASE |

Ph EV BUT REPEAT | Ph EV BOUNDARY,
basic callback
};

static PtArg t args[] = {

.
.
.
{ Pt SET RAW CALLBACKS, &callback },
.
.
.
};

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 71

Widget actions  2005, QNX Software Systems

In the example above, whenever the widget receives one of the four
events (Ph EV BUT PRESS, Ph EV BUT RELEASE,
Ph EV BUT REPEAT, or Ph EV BOUNDARY), the basic callback()
function is invoked. This function can check the event type and act
accordingly.
For clarity, let’s walk through a simplified description of the “click”
process of a PtButton widget.
First, PtButton receives the Ph EV BUT PRESS event. The widget
interprets the press event, changes the widget flags to Pt SET (possibly
causing the widget to be damaged and redrawn), and then invokes the
Pt CB ARM callback.
When the user releases the mouse button, PtButton receives a
Ph EV BUT RELEASE release event. The widget clears the Pt SET
flag and then invokes the Pt CB DISARM and Pt CB ACTIVATE
callbacks.
The action PtButton takes when the button is released is a little
more complicated, because the widget actually doing the work is
PtBasic, not PtButton. The PtButton class doesn’t define any
raw callbacks because the handling done by PtBasic is sufficient.
The PtBasic class handles the common Photon arm, disarm, repeat,
activate, and menu callbacks for all widgets.

Raw callback list

Type: Chained up, stoppable
The class’s list of raw callbacks is used to make a widget sensitive to
raw Photon event messages. This allows the widget to define a
specific behavior related to external events or user interaction. Since
there are a great many different things that could be done as a result of
Photon events, be sure to look at the sample widgets provided in
/qnx4/phtk/src/widgets (the PtScrollbar widget is a good
example).
Returning Pt HALT from a class’s raw callback prevents any
superclass (or the user) from processing the event. The event is

72 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Widget actions

propagated up through the widget hierarchy and may be handled by a

parent widget.
Returning Pt END from a class’s raw callback prevents any
superclass, user, or parent widget from processing the event. This is
called consuming the event. Here’s an example taken from the code
for PtTimer:
static timer callback( PtWidget t *widget, void *data,
PtCallbackInfo t *cbinfo )
{
PtTimerWidget t *timer = (PtTimerWidget t *)widget;
PtCallbackInfo t cbi;

data,cbinfo;
cbi.reason = Pt CB TIMER ACTIVATE;
if( timer->state == Pt TIMER INITIAL )
cbi.reason subtype = Pt TIMER INITIAL;
else
cbi.reason subtype = Pt TIMER REPEAT;
timer->state = Pt TIMER REPEAT;
PtInvokeCallbackList( timer->activate, widget, &cbi );
if( timer->msec repeat && timer->state == Pt TIMER REPEAT )
PtTimerArm( widget, timer->msec repeat );
return( Pt CONTINUE );
}

//
// PtTimer class-creation function
//

PtWidgetClass t *PtCreateTimerClass( void )

{
static const PtResourceRec t resources[] = {
Pt ARG AREA, Pt CHANGE PREVENT, 0,
Pt ARG IS STRUCT( PtTimerUnion t, core.area ), 0,
Pt ARG DIM, Pt CHANGE PREVENT, 0,
Pt ARG IS STRUCT( PtTimerUnion t, core.area.size ), 0,
Pt ARG POS, Pt CHANGE PREVENT, 0,
Pt ARG IS STRUCT( PtTimerUnion t, core.area.pos ), 0,
Pt ARG TIMER INITIAL, timer modify, 0,
Pt ARG IS NUMBER( PtTimerWidget t, msec value ), 0,
Pt ARG TIMER REPEAT, timer modify, 0,
Pt ARG IS NUMBER( PtTimerWidget t, msec repeat ), 0,
Pt CB TIMER ACTIVATE, Pt CHANGE INVISIBLE, 0,
Pt ARG IS CALLBACK LIST( PtTimerWidget t, activate ), 0,
};

static const PtRawCallback t callback[] = {

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 73

Container widget anatomy  2005, QNX Software Systems

Ph EV TIMER, timer callback

};

static const PtArg t args[] = {

{ Pt SET VERSION, 110},
{ Pt SET STATE LEN, sizeof( PtTimerWidget t ) },
{ Pt SET DFLTS F, (long) timer dflts },
{ Pt SET EXTENT F, (long) PtNullWidget f },
{ Pt SET REALIZED F, (long) timer realized },
{ Pt SET UNREALIZE F, (long) timer unrealize },
{ Pt SET RAW CALLBACKS, (long) callback, 1 },
{ Pt SET FLAGS, Pt FORCE UNREALIZE, Pt FORCE UNREALIZE },
{ Pt SET RESOURCES, (long) resources,
sizeof( resources ) / sizeof( resources[0] ) },
{ Pt SET NUM RESOURCES, sizeof( resources ) /
sizeof( resources[0] ) },
};

return( PtTimer->wclass = PtCreateWidgetClass( PtWidget, 0,

sizeof( args )/sizeof( args[0] ), args ) );
}

Container widget anatomy

This section applies to creating PtContainer class widgets:
PtWidget → PtBasic → PtContainer → MyContainer

Child-constraint support
Container widgets extend the PtBasic widget class definition with a
number of constraint methods. These methods allow the container to
adjust itself automatically according to changes made to its children.
The container class extension is shown in the example code below
(taken from the PtContainer.h header file):
typedef struct Pt container widget class {
PtBasicWidgetClass t basic;
void (*child created f)( ... );
int (*child settingresource f)( ... );
int (*child gettingresource f)( ... );
void (*child realized f)( ... );
void (*child unrealized f)( ... );
void (*child destroyed f)( ... );

74 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Container widget anatomy

void (*child move resize f)( ... );

int (*child getting focus f)( ... );
int (*child losing focus f)( ... );
} PtContainerClass t;

Constraint methods can be individually enabled or disabled by setting

or clearing the appropriate container->flags bits. You can enable or
disable all the constraint methods at once by setting or clearing
Pt IGNORE CONSTRAINTS.

Method Description Resource manifest

child created f Child Created Pt SET CHILD CREATED F
child settingresource f Child Setting Resource Pt SET CHILD SETTINGRESOURCE F
child gettingresource f Child Getting Resource Pt SET CHILD GETTINGRESOURCE F
child realized f Child Realized Pt SET CHILD REALIZED F
child unrealized f Child Unrealized Pt SET CHILD UNREALIZED F
child destroyed f Child Destroyed Pt SET CHILD DESTROYED F
child move resize f Child Moved/Resized Pt SET CHILD MOVED RESIZED F
child getting focus f Child Getting Focus Pt SET CHILD GETTING FOCUS F
child losing focus f Child Losing Focus Pt SET CHILD LOSING FOCUS F

For convenience, the Photon widget building library lets you call
these methods from a superclass using the provided functions. For
more information, see the Widget Building Library API chapter.

Child Created method

Type: Inherited
Constraint flag: Pt CHILD CREATED
Called whenever a new child is being created in this widget or one of
its subordinate widgets. Here’s an excerpt taken from the code for
PtGroup:
static void child created( PtWidget t *widget,

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 75

Container widget anatomy  2005, QNX Software Systems

PtWidget t *child )
{
PtCallback t callback = { group exclusive callback,
NULL };
PtGroupUnion t *group = (PtGroupUnion t *)widget;
PtArg t argt[2];
int n = 0;

callback.data = widget;

if( group->basic.activate ) {
PtSetArg( &argt[n++], Pt CB ACTIVATE,
&group->basic.activate->cb, 0 );
}
if( group->group.group flags & Pt GROUP EXCLUSIVE ) {
PtSetArg( &argt[n++], Pt CB ACTIVATE, &callback, 0 );
}
if( n )
PtSetResources( child, n, argt );
}

Child Realized method

Type: Inherited
Constraint flag: Pt CHILD REALIZED
Called whenever a child is realized below this container in the
hierarchy.

Child Moved/Resized method

Type: Inherited
Constraint flag: Pt CHILD MOVED RESIZED
Called whenever a child is moved or resized below this container in
the hierarchy.

Child Unrealized method

Type: Inherited
Constraint flag: Pt CHILD UNREALIZED
Called whenever a child is unrealized below this container in the
hierarchy.

76 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Container widget anatomy

Child Destroyed method

Type: Inherited
Constraint flag: Pt CHILD DESTROYED
Called whenever a direct child of this widget or a direct child of one
of its subordinates is destroyed.

Child Setting Resource method

Type: Inherited
Constraint flag: Pt CHILD SETTING RESOURCE
Called whenever a resource is being set on a direct child of this
widget or one of its subordinates.

Child Getting Resource method

Type: Inherited
Constraint flag: Pt CHILD GETTING RESOURCE
Called whenever a resource is being retrieved from a direct child of
this widget or one of its subordinates.

Child Getting Focus method

Type: Inherited
Constraint flag: Pt CHILD GETTING FOCUS
Called whenever a child of this widget or one of its subordinates is
about to be given focus.

Child Losing Focus method

Type: Inherited
Constraint flag: Pt CHILD LOSING FOCUS
Called whenever a child of this widget or one of its subordinates is
about to lose focus.

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 77

Container widget anatomy  2005, QNX Software Systems

Child-redirector function
Container widgets provide a mechanism for redirecting child widgets
as they are added to a container. You can use this mechanism to
prevent certain widget classes from being added as direct children or
redirect those children to other containers within the container (this
feature is typically used by PtCompound widgets).
The child-redirector function is specified in the Defaults method and
indicates where children should be attached in the widget hierarchy.
Redirection is achieved by calling the PtContainerChildRedirect()
function, which passes the name of the redirector function.
The arguments to the redirector function are a widget pointer and the
class type of the widget being added to the container. Using this
information, the redirector function determines whether to accept the
widget into the container or redirect the widget to another container,
such as the parent of the container widget.
A good example is the PtMenuBar widget. This widget accepts only
PtMenuButton widgets. Its Defaults method could be written
something like this:
PtContainerChildRedirect( widget, menubar redirect );

The menubar redirect() function would look like this:

static PtWidget t *menubar redirect(
PtWidget t *menubar,
PtWidgetClassRef t *cref )
{
if (cref != PtMenuButton )
return menubar->parent;
return menubar;
}

The widget returned by the function becomes the parent for the
widget being added.
You can use PtCompoundRedirect() as the default child-redirector
function for any containers that won’t accept other widgets.
PtCompoundRedirect() redirects child creation to the parent of the
container widget. This causes a new widget to become a sibling of the
container widget rather than a child of the container widget.

78 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Container widget anatomy

Fundamental methods
When using container widgets, you must provide a number of
container-specific processes within the fundamental methods in
addition to those common to every widget.

Defaults method
To enable the container-constraint methods, set the appropriate bits in
container->flags. You can turn on all bits as follows:

ctnr->flags |= Pt CONTAINER CONSTRAINT BITS;

Only the constraint methods whose bits are on are invoked. If you
turn a bit on and the corresponding constraint method is undefined,
the bit is ignored. For example:

ctnr->flags |= Pt CHILD CREATED;

For each bit set in the flag, you should provide a constraint method in
the argument list of the class-creation function:

static PtArg t args[] = {

.
.
.
{ Pt SET CHILD CREATED F, child created },
.
.
.
};

The child created() function should modify the child or container as

required to suit the situation.

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 79

Container widget anatomy  2005, QNX Software Systems

☞ The Common User Access (CUA) mechanism built into the Photon
library automatically passes focus around the application. If you want
to prevent widgets inside the container from getting focus, set the
Pt BLOCK CUA FOCUS flag. The PtMenuBar widget does this (i.e.
you can’t press the Tab key to move the focus from a widget outside a
menubar to a widget inside a menubar).

Extent method
This method is responsible for determining the “screen real estate” of
a widget. Anchoring is applied in this method. Widgets subclassed
under PtContainer normally call the Extent method of
PtContainer to do the final extent calculation and anchor the
widget according to its anchor flags. When a widget’s extent has been
calculated, its widget->extent valid flag should be set to Pt TRUE.
The following example demonstrates how to handle anchoring if you
choose to not let the PtContainer class do it for you (see also
PtSuperClassExtent()):

mycontainerwidget extent( PtWidget t *widget )

{
PtWidget t *widget
PhRect t canvas, old extent;
PhArea t area;

// Store the old size for comparison later.

old extent = widget->extent;
PtSetAreaFromExtent( widget, &old extent, &area );

if( PtResizePolicy( widget ) )

{
PhRect t render;
render.lr.x = render.lr.y = SHRT MIN;
render.ul.x = render.ul.y = SHRT MAX;
PtChildBoundingBox( widget, &canvas, &render );
PtTranslateRect( &render, &canvas.ul );
PtAttemptResize( widget, &render, &canvas );
}
PtSuperClassExtent( PtBasic, widget );
widget->extent valid = Pt TRUE;

// Containers must anchor their children. Flux to

80 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Compound widget anatomy

// minimize flicker.

PtStartFlux( widget );
if( widget->parent && widget->parent->extent valid
&& (ctnr->anchor flags & Pt IS ANCHORED ) &&
!( widget->class rec->flags &
(Pt DISJOINT|Pt DISCONTINUOUS) ) )
PtAnchorWidget( widget );
else
if( !(ctnr->anchor flags & Pt ANCHORS LOCKED ) &&
memcmp( &widget->area.size, &area.size,
sizeof(PhDim t) ) )
for( wlp = ctnr->ctnrs; wlp; wlp = next )
{
next = wlp->next;
if( ((PtContainerWidget t *)wlp->widget)->anchor flags &
Pt IS ANCHORED )
PtAnchorWidget( wlp->widget );
}
PtEndFlux( widget );

// If the size changes, accommodate the new size.

if( memcmp( &old extent, &widget->extent,
sizeof( old extent ) ) )
{
if( ( widget->flags & Pt REALIZED ) && (widget->rid) )
PtCoreChangeRegion( Ph REGION ORIGIN | Ph REGION RECT,
widget );
if( !(ctnr->anchor flags & Pt ANCHORS LOCKED)
&& memcmp( &widget->area.size,
&area.size, sizeof(PhDim t) ) )
PtInvokeResizeCallbacks( widget );
}
}

Realization method
If your container creates any subordinate widgets with the
Pt DELAY REALIZE flag set, they can be realized in the Realization
method.

Compound widget anatomy

This section applies to creating PtCompound class widgets:

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 81

Compound widget anatomy  2005, QNX Software Systems

PtWidget → PtBasic → PtContainer → PtCompound →

MyCompound
The PtCompound superclass supports extended functionality
provided by “exported” subordinate children. The export mechanism
allows users to set/get the resources of subordinate children through a
compound widget without defining any of these resources in the
compound widget. Compound widgets can modify or block the
default resources inherited by their exported subordinate children.

☞ Widgets don’t have to be a subclass of PtCompound to export

subordinate widgets. However, because PtContainer provides
powerful child-constraint and child-redirection mechanisms, we
recommend that if you’re building a widget that creates subordinate
children, you should subclass that widget to PtContainer (if not
PtCompound). This greatly simplifies the management of
subordinate children. It also makes the widget easier to use since new
resources don’t have to be learned.

To achieve this exporting mechanism, the compound class extends the

PtContainer widget class definition as shown below:

typedef struct Pt compound class {

PtContainerClass t container;
ushort t num subordinates;
ushort t *subordinates;
ushort t num blocked resources;
ulong t *blocked resources;
} PtCompoundClass t;

The members of this structure are:

num subordinates (Resource manifest

Pt SET NUM SUBORDINATES)
The number of subordinate widgets (in the subordinate offset
array) to be exported. This value must be supplied when
defining an array of offsets.

82 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Compound widget anatomy

subordinates (Resource manifest Pt SET SUBORDINATES)

An array of offsets to widget pointers to subordinate widgets.
Every widget defined in the array of offsets must be created in
the Defaults method of the compound widget.
num blocked resources (Resource manifest
Pt SET NUM BLOCKED RESOURCES)
The number of resources in the array of blocked resources.
blocked resources (Resource manifest
Pt SET BLOCKED RESOURCES)
An array of resources to be blocked.

Here’s a sample class-creation function from PtComboBox:

//
// PtComboBox class-creation function
//

PtWidgetClass t *PtCreateComboBoxClass( void )

{
static const PtResourceRec t resources[] = {
Pt ARG POS, Pt CHANGE RESIZE, 0,
Pt ARG IS STRUCT( PtComboBoxUnion t,
core.area.pos ),
0,
Pt ARG DIM, combobox modify dim, 0,
Pt ARG IS STRUCT( PtComboBoxUnion t,
core.area.size ),
0,
Pt ARG FLAGS, combobox modify, 0,
Pt ARG IS FLAGS( PtWidget t, flags ), 0,

// ----- snip : lots of resource definitions removed -----

Pt ARG CBOX ITEMS, set list res, get list res, 0, 0,

Pt ARG CBOX SPACING, set list res, get list res, 0, 0,
Pt ARG CBOX VISIBLE COUNT, set list res, get list res, 0, 0,

// ----- snip : lots of resource definitions removed -----

};

static const ushort t subs[] =

{
offsetof( PtComboBoxWidget t, text wgt ),
offsetof( PtComboBoxWidget t, list wgt ),

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 83

Compound widget anatomy  2005, QNX Software Systems

};

static const PtRawCallback t callback = {

Ph EV KEY, combobox callback, NULL
};

static const ulong t blocked[] = {

Pt ARG SELECTION MODE,
Pt ARG SEL INDEXES
};

static const PtArg t args[] = {

{ Pt SET VERSION, 110},
{ Pt SET STATE LEN, sizeof( PtComboBoxWidget t ) },
{ Pt SET DFLTS F, (long) combobox dflts },
{ Pt SET FLAGS, Pt TRUE, Pt COMPOUND },
{ Pt SET RAW CALLBACKS, (long) &callback },
{ Pt SET RESOURCES, (long) resources,
sizeof( resources ) /sizeof( resources[0] ) },
{ Pt SET NUM RESOURCES,
sizeof( resources ) / sizeof( resources[0] ) },
{ Pt SET EXTENT F, (long) combobox extent },
{ Pt SET CONNECT F, (long) combobox init },
{ Pt SET NUM SUBORDINATES,
sizeof( subs ) /sizeof( subs[0] ) },
{ Pt SET SUBORDINATES, (long) subs,
sizeof( subs ) / sizeof( subs[0] ) },
{ Pt SET NUM BLOCKED RESOURCES,
sizeof( blocked ) / sizeof( blocked[0] ) },
{ Pt SET BLOCKED RESOURCES, (long) blocked,
sizeof( blocked ) /sizeof( blocked[0] ) },
{ Pt SET CHILD MOVED RESIZED F,
(long) combobox child resize },
{ Pt SET GOT FOCUS F, (long) combobox got focus },
};

return( PtComboBox->wclass = PtCreateWidgetClass(

PtCompound, 0, sizeof( args )/sizeof( args[0] ),
args ) );
}

☞ In the example code shown above, the PtComboBox widget creates

subordinate widgets and sets the pointers text wgt and list wgt in the
Defaults method to the appropriate widget pointer.

In the following example, the widget class MyCompound creates

subordinate widgets PtText, RtProgress, PtScrollArea, and a

84 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Compound widget anatomy

few PtLabels. The PtText, RtProgress, and PtScrollArea

widgets are exported, but the PtLabel widgets aren’t. All resources
are applied to the subordinate widgets. No extra code is required for
MyCompound:
.
.
.
n = 0;
PtSetArg( &argt[n], Pt ARG POS, &pos, 0 ); n++;
PtSetArg( &argt[n], Pt ARG TEXT STRING, "A text field",
0 ); n++;
PtSetArg( &argt[n], Pt ARG SCROLL AREA MAX X, 1000, 0 ); n++;
PtSetArg( &argt[n], Pt CB SCROLLED X, &callback, 1 ); n++;
PtSetResources( MyCompound, n, argt );
.
.
.
n = 0;

To get the resources afterwards:

.
.
.
n = 0;
n = 0;
PtSetArg( &argt[n], Pt ARG POS, &phpoint ptr, 0 ); n++;
PtSetArg( &argt[n], Pt ARG TEXT STRING, &char ptr, 0 ); n++;
PtSetArg( &argt[n], Pt ARG SCROLL AREA MAX X, &short ptr,
0 ); n++;
PtGetResources( MyCompound, n, argt );
.
.
.
n = 0;

When the Pt CB SCROLLED X callback is invoked, the first

parameter widget is a pointer to MyCompound, not to the subordinate.
The PtCompound class also makes it easy to block specific resources
from hitting any subordinate.
What happens when you export two or more subordinate widgets
supporting the same resource? For example, both a button and a text
field accept the resource Pt ARG TEXT STRING; if they’re exported
with no supporting code, then setting the resource on the compound
widget will set the resource on both subordinates.
When getting the resource, the value is retrieved from the first
exported widget supporting the resource. If you don’t want this to

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 85

Compound widget anatomy  2005, QNX Software Systems

happen, set up a resource-redirector function at the end of the

compound widget’s Defaults method.
You can have a compound widget override the resource (see
Pt ARG TEXT STRING in the example above) by defining it, then
using the mod f() function (named in the mod f field member of the
PtResourceRec t structure) to apply the resource to the
appropriate subordinate. See PtSampCompound.c in the
/qnx4/phtk/src/widgets directory for more examples of
redirecting resources.
Any resources defined for a subclass of a PtCompound widget won’t
automatically be applied to a subordinate widget, exported or
otherwise. If you define resource redirectors for all user-modified
resources of subordinates, consider subclassing your widget below
PtContainer instead of PtCompound.

Blocking resources
The exporting mechanism provides a resource-blocking mechanism.
You can selectively block resources, making them inaccessible to
subordinate widgets.
Suppose you’ve built a compound widget comprising an exported
PtSlider widget, and you want the slider thumb to stay the same
size always — blocking access to the Pt ARG SLIDER SIZE resource
would prevent the slider from being resized.
You may also find that you have more than one occurrence of a single
type of widget as subordinate widget. For example, your widget
might have a vertical and a horizontal scrollbar. In this case, you
should block Pt ARG SCROLL POSITION and create two new
resources: Pt ARG X SCROLL POSITION and
Pt ARG Y SCROLL POSITION. The Set Resources method for each
would set the Pt ARG SCROLL POSITION resource of the
appropriate subordinate scrollbar widget.

86 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Compound widget anatomy

Compound redirection
The PtCompound class provides a standard child-redirector function
called PtCompoundRedirect(). This function prevents the user from
creating widgets in your compound widget and redirects the user’s
widget to another container instead. To target another widget, redirect
child creation at the end of the Defaults method after all subordinate
widgets have been created. For example:
Static void defaults( PtWidget t *)
{
.
.
.
PtContainerChildRedirect( widget, PtCompoundRedirect );
return;
}

In the template for the PtSampCompound widget, new children are

redirected to one of the procreated subordinate widgets, scroll area,
by calling PtValidParent() (described in the Photon Library
Reference):
PtWidget t * PtSampContainerRedirect( PtWidget t *widget )
{
PtWidget t *parent;

if( ( parent =
PtValidParent( samp->scroll area,
widget->class ref ) ) == widget )
return PtWidgetParent( widget );
return( parent );

/*
* Returning samp->scroll area would allow the child
* to be created as a direct child of samp->scroll area.
* This may be undesirable, as scroll area is a container
* widget that redirects its children.
*/
}

PtValidParent() honors any child-redirector functions existing in

subordinate widgets and their subordinates. PtValidParent() should be
used only to redirect parentage to a subordinate child. This prevents
infinite loops when the child’s redirector function returns control.

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 87

Compound widget anatomy  2005, QNX Software Systems

Fundamental methods
Compound widgets require a few fundamental methods in addition to
those common to every widget.

Defaults method
For compound widgets, all exported subordinate widgets must be
created in the Defaults method. To export widgets, set the following
in the class-creation function:

Pt SET SUBORDINATES
An array of offsets to the subordinate widget pointers.
Pt SET NUM SUBORDINATES
The number of entries in the array.

Resources of subordinate widgets may be overridden, overloaded, or

blocked. Subordinate widgets can be created but not realized in the
Defaults method.
For the container-constraint mechanisms to work correctly, the
Pt PROCREATED flag has to be set in each subordinate widget, and
the Pt ARG DATA (not Pt ARG USER DATA) resource has to point
back to the parent widget. Otherwise, you’ll be greeted with a
SIGSEGV error.

☞ Your custom widget shouldn’t set its own Pt ARG DATA resource
because this resource is used internally by the Photon libraries. It is
safe to set it in your widget’s subordinate children.

Here’s an example from PtComboBox:

static void combobox dflts( PtWidget t *widget )
{
PtComboBoxUnion t *combobox = (PtComboBoxUnion t *)widget;
PtArg t args[13];
int n = 0;
PtCallback t callback;

88 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Compound widget anatomy

combobox->core.flags |= Pt HIGHLIGHTED | Pt SET;

combobox->core.flags &= ˜Pt GETS FOCUS;
combobox->core.resize flags = Pt RESIZE XY ALWAYS;
combobox->basic.fill color = Pg TRANSPARENT;
combobox->basic.margin height = 0;
combobox->basic.margin width = 0;
widget->border width = combobox->combobox.border width = 2;
combobox->combobox.butn size.w = 17;
combobox->combobox.butn border width = 2;
combobox->combobox.butn bot border color = Pg DGREY;
combobox->combobox.butn top border color = Pg WHITE;
combobox->combobox.butn color = Pg GREY;

callback.event f = combobox action;

callback.data = (void*)widget;

PtSetArg( &args[n], Pt ARG RAW DRAW F,

combobox draw button, 0 ); n++;
PtSetArg( &args[n], Pt ARG FLAGS,
Pt HIGHLIGHTED | Pt SELECTABLE
| Pt PROCREATED | Pt DELAY REALIZE,
Pt HIGHLIGHTED | Pt SELECTABLE
| Pt PROCREATED | Pt DELAY REALIZE ); n++;

PtSetArg( &args[n], Pt ARG DIM,

&combobox->combobox.butn size, 0 ); n++;
PtSetArg( &args[n], Pt CB ARM, &callback, 1 ); n++;
PtSetArg( &args[n], Pt CB REPEAT, &callback, 1 ); n++;
PtSetArg( &args[n], Pt ARG MARGIN HEIGHT, 4, 0 ); n++;
PtSetArg( &args[n], Pt ARG MARGIN WIDTH, 4, 0 ); n++;
PtSetArg( &args[n], Pt ARG BORDER WIDTH, 0, 0 ); n++;
PtSetArg( &args[n], Pt ARG DATA, &widget,
sizeof( widget ) );n++;
combobox->combobox.butn wgt = PtCreateWidget( PtRaw, widget,
n, args );

callback.event f = combobox text callback;

callback.data = (void*)widget;

n = 0;
PtSetArg( &args[n], Pt ARG BORDER WIDTH, 0, 0 ); n++;
PtSetArg( &args[n], Pt ARG MARGIN HEIGHT, 2, 0 ); n++;
PtSetArg( &args[n], Pt ARG MARGIN WIDTH, 2, 0 ); n++;
PtSetArg( &args[n], Pt ARG FLAGS, Pt PROCREATED,
Pt PROCREATED ); n++;
PtSetArg( &args[n], Pt ARG DATA, &widget,
sizeof( widget ) );n++;
PtSetArg( &args[n], Pt CB TEXT CHANGED, &callback, 1); n++;
PtSetArg( &args[n], Pt CB MODIFY VERIFY, &callback, 1); n++;
PtSetArg( &args[n], Pt CB MOTION VERIFY, &callback, 1); n++;

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 89

Compound widget anatomy  2005, QNX Software Systems

PtSetArg( &args[n], Pt CB ACTIVATE, &callback, 1); n++;

PtSetArg( &args[n], Pt CB GOT FOCUS, &callback, 1); n++;
PtSetArg( &args[n], Pt CB LOSING FOCUS, &callback, 1); n++;
combobox->combobox.text wgt = PtCreateWidget( PtText, widget,
n, args );

n = 0;
callback.event f = combobox list callback;
callback.data = (void*)widget;
PtSetArg( &args[n], Pt ARG BORDER WIDTH,
combobox->combobox.border width, 0 ); n++;
PtSetArg( &args[n], Pt ARG SCROLLBAR WIDTH,
combobox->combobox.butn size.w, 0 ); n++;
PtSetArg( &args[n], Pt ARG SEL MODE,
Pt SELECTION MODE SINGLE | Pt SELECTION MODE AUTO,
0 ); n++;
PtSetArg( &args[n], Pt ARG FLAGS,
Pt PROCREATED | Pt DELAY REALIZE,
Pt GETS FOCUS | Pt ETCH HIGHLIGHT
| Pt PROCREATED | Pt DELAY REALIZE );n++;
PtSetArg( &args[n], Pt CB SELECTION, &callback, 1 );n++;
PtSetArg( &args[n], Pt CB LIST INPUT, &callback, 1 );n++;
PtSetArg( &args[n], Pt ARG DATA, &widget,
sizeof( widget ) );n++;
combobox->combobox.list wgt = PtCreateWidget( PtList, widget,
n, args );

n = 0;
callback.event f = combobox action;
callback.data = (void*)widget;
PtSetArg( &args[n], Pt CB ARM, &callback, 1 ); n++;
PtSetResources( combobox->combobox.text wgt, n, args );

PtContainerChildRedirect( widget, PtCompoundRedirect );

}

Realization method
The Realization method is the last class-member function called
before the Draw method. It’s where you realize subordinate widgets
created in the Defaults method. Here’s an example from
PtComboBox:

static int combobox realized( PtWidget t *widget )

{
PtComboBoxWidget t *combobox = (PtComboBoxWidget t *)widget;
long flags;

90 Chapter 3 ¯ Anatomy of a Widget September 20, 2005

 2005, QNX Software Systems Compound widget anatomy

if ( combobox->flags & Pt COMBOBOX STATIC )

PtRealizeWidget( combobox->list wgt );
else {
PtRealizeWidget( combobox->butn wgt );
}
return Pt CONTINUE;
}

Get Resources and Set Resources methods

To date, the PtCompound widget class is the only class to redefine the
Get Resources and Set Resources methods, which are used internally.
You don’t have to set a function for this method unless you intend to
duplicate the behavior of PtCompound.

Destruction method
The Destruction method must destroy any redirected callback lists of
exported subordinates having callback resources set on them.

September 20, 2005 Chapter 3 ¯ Anatomy of a Widget 91

 Chapter 4
Using Widget Superclasses

In this chapter. . .
PtWidget 95
PtBasic 99
PtContainer 105
PtCompound 114
PtGenList 116
PtGenTree 125
PtLabel 129
PtGraphic 133
PtGauge 136

September 20, 2005 Chapter 4 ¯ Using Widget Superclasses 93

 2005, QNX Software Systems PtWidget

This chapter describes the common widget superclasses. Use this

information to determine whether a superclass’s method does what
you need for your widget. With this knowledge you can decide
whether to take over the method (override inheritance), add a method
to the chain, or use the PtSuperClass* functions.

☞ It’s important to read the specifications of each of your widget’s

superclasses before using any of the PtSuperClass*() functions.

PtWidget
The PtWidget superclass provides the fundamental functionality of
all Photon widgets.

Class hierarchy
PtWidget

Class flags
Pt RECTANGULAR

Methods
PtWidget defines the class methods described below.

Defaults method
None.

Initialization method
None.

Extent method
Calculates the extent of the widget without accounting for borders or
margins. The extent is calculated based on the widget’s position
(Pt ARG POS) and dimension (Pt ARG DIM). For disjoint widgets
(e.g. PtWindow widgets), the position is assumed to be (0, 0).

September 20, 2005 Chapter 4 ¯ Using Widget Superclasses 95

PtWidget  2005, QNX Software Systems

Connection method
Determines if the widget needs a region, and if so, what events the
region should be opaque and/or sensitive to.
If the widget has a bitmap cursor defined, it’s set up as region data. If
the widget already has a region, that region is updated with the
opaque/sense and region data. This is done through
PhRegionChange().
If the widget doesn’t have a region but one is required, it’s created
through PhRegionOpen().
Finally, if the widget isn’t a window, any hotkey callbacks attached to
the widget are registered with the nearest disjoint parent (of
PtWindow class). This is done through PtSetResources().

Realization method
None.

Unrealization method
If the widget has a region, the region is closed. All descendants
(widget->rid members) are set to 0. If the widget isn’t a window, any
attached hotkey callbacks are detached from its disjoint parent.
The extent of this widget is damaged on the parent. All children of
this widget are unrealized. Any of these widgets having a
constraining parent with Pt SET CHILD UNREALIZED F defined has
that function invoked. Any of these having a Pt CB UNREALIZED
callback chain has that callback chain invoked (from the top down).

Destruction method
Called when a widget instance is being removed. Frees
widget->widget data. Any memory automatically allocated by a
resource is released (this memory shouldn’t be freed in the
Destruction method). Any resources you free must have the pointer
set to NULL to prevent the widget engine from freeing the memory a
second time. The following resource types automatically allocate and
release memory:

96 Chapter 4 ¯ Using Widget Superclasses September 20, 2005

 2005, QNX Software Systems PtWidget

¯ Pt ARG IS ALLOC

¯ Pt ARG IS ARRAY

¯ Pt ARG IS CALLBACK LIST

¯ Pt ARG IS LINK

¯ Pt ARG IS STRING

Widget actions
None.

Resource definitions
Pt ARG AREA, Pt CHANGE RESIZE, 0,
Pt ARG IS STRUCT( PtWidget t, area ), 0,

Pt ARG CURSOR TYPE, core modify cursor, 0,

Pt ARG IS NUMBER( PtWidget t, cursor type ), 0,

Pt ARG CURSOR COLOR, core modify cursor, 0,

Pt ARG IS NUMBER( PtWidget t, cursor color ), 0,

Pt ARG DATA, Pt CHANGE INVISIBLE, 0,

Pt ARG IS ALLOC( PtWidget t, data ), 0,

Pt ARG DIM, Pt CHANGE RESIZE, 0,

Pt ARG IS STRUCT( PtWidget t, area.size ), 0,

Pt ARG FLAGS, PtModifyFlags, 0,

Pt ARG IS NUMBER( PtWidget t, flags ), 0,

Pt ARG EFLAGS, PtModifyEflags, 0,

Pt ARG IS FLAGS( PtWidget t, eflags),

Pt ARG POS, Pt CHANGE RESIZE, 0,

Pt ARG IS STRUCT( PtWidget t, area.pos ), 0,

Pt ARG RESIZE FLAGS, Pt CHANGE RESIZE, 0,

Pt ARG IS FLAGS( PtWidget t, resize flags ), 0,

Pt CB DESTROYED, Pt CHANGE INVISIBLE, 0,

Pt ARG IS LINK( PtWidget t, destroyed ), 0,

Pt CB HOTKEY, core modify hotkey callbacks, 0,

Pt ARG IS LINK( PtWidget t, hotkeys ), 0,

September 20, 2005 Chapter 4 ¯ Using Widget Superclasses 97

PtWidget  2005, QNX Software Systems

Pt CB RAW, core modify raw callbacks, 0,

Pt ARG IS LINK( PtWidget t, callbacks ), 0,

Pt CB REALIZED, Pt CHANGE INVISIBLE, 0,

Pt ARG IS LINK( PtWidget t, realized ), 0,

Pt CB UNREALIZED, Pt CHANGE INVISIBLE, 0,

Pt ARG IS LINK( PtWidget t, unrealized ), 0,

Pt ARG USER DATA, Pt CHANGE INVISIBLE, 0,

Pt ARG IS ALLOC( PtWidget t, user data ), 0,

Pt ARG HELP TOPIC, Pt CHANGE INVISIBLE, 0,

Pt ARG IS ALLOC( PtWidget t, help topic ), 0,

Pt CB BLOCKED, Pt CHANGE INVISIBLE, 0,

Pt ARG IS LINK( PtWidget t, blocked ), 0,

Pt ARG BITMAP CURSOR, bitmap cursor change, 0,

Pt ARG IS ALLOC( PtWidget t, bitmap cursor ), 0,

Functions
static core modify cursor()
Sets the resource via direct assignment and if realized, sets the
Ph REGION CURSOR bit in widget->flags. If this flag is on
when the PtUpdate() function is called (see the Photon Library
Reference), a PhRegionChange() will be performed to change
the region’s cursor or create a region if one doesn’t exist.

static core modify raw callbacks()

Sets the resource via PtSetStruct() and adjusts the widget’s
region sensitivity.

static core modify hotkey callbacks()

Sets the resource via PtSetStruct() and if realized, attaches any
hotkey callbacks of a nonwindow widget to its disjoint parent.

98 Chapter 4 ¯ Using Widget Superclasses September 20, 2005

 2005, QNX Software Systems PtBasic

int PtModifyFlags()
Knocks down the read-only flag bits from the mask and applies
the remaining flag to widget->flags. A change in the following
flag bits may cause the widget to change:

Pt AUTOHIGHLIGHT
Requires a region and sensitivity to
Ph EV BOUNDARY events via PhRegionChange() or
the Connection method of PtWidget.
Pt ETCH HIGHLIGHT
Resize by setting the Pt WIDGET RESIZE bit in
widget->flags.
Pt SET If Pt SELECT NOREDRAW isn’t set in the widget
flags, the widget will force a redraw by calling
PtDamageWidget().
Pt HIGHLIGHTED
The widget will force a redraw by calling
PtDamageWidget().

PtBasic
Provides fundamental Photon widget behavior and callbacks.

Class hierarchy
PtWidget → PtBasic

Class extensions
The PtBasic widget adds three class-level methods to fundamental
widget functionality. For complete descriptions, see “Class methods”
in the Anatomy of a Widget chapter.

September 20, 2005 Chapter 4 ¯ Using Widget Superclasses 99

PtBasic  2005, QNX Software Systems

typedef struct Pt basic widget class {

PtWidgetClass t core;
void (*got focus f)( PtWidget t *, PhEvent t * );
void (*lost focus f)( PtWidget t *, PhEvent t * );
void (*calc opaque f)( PtWidget t * );
} PtBasicWidgetClass t;

#define Pt SET GOT FOCUS F (Pt ARG IS POINTER(PtBasicWidgetClass t,got focus f))
#define Pt SET LOST FOCUS F (Pt ARG IS POINTER(PtBasicWidgetClass t,lost focus f))
#define Pt SET CALC OPAQUE F (Pt ARG IS POINTER(PtBasicWidgetClass t,calc opaque f))

Methods
PtBasic defines the class methods described below.

Defaults method
widget->border width = 2;
widget->cursor color = Ph CURSOR DEFAULT COLOR;
widget->resize flags |= Pt RESIZE XY AS REQUIRED;
basic->color = Pg BLACK;
basic->fill color = Pg GREY;
basic->top border color = Pg WHITE;
basic->bot border color = Pg DGREY;
basic->flags = Pt DAMAGE ON FOCUS;

Initialization method
None.

Extent method
Invokes the Extent method of PtWidget via PtSuperClassExtent().
The resulting extent is then adjusted to account for borders and
margins.
The Extent method calculates the widget’s opaque rectangle and
determines whether the widget’s Pt OPAQUE flag is set. The opaque
rectangle, widget->opaque, indicates:

¯ the rectangle under which damage needn’t occur if this widget is

damaged

100 Chapter 4 ¯ Using Widget Superclasses September 20, 2005

 2005, QNX Software Systems PtBasic

¯ what should be damaged if this widget changes position or

dimension

This rectangle is the area capable of obscuring any widgets beneath.

Widgets completely obscured by another widget aren’t drawn.

Connection method
Checks the PtBasic class structure member calc opaque f . If not
NULL, the function is invoked. The calc opaque f() function is
responsible for setting or clearing a widget’s Pt OPAQUE flag. If the
widget has a rectangular area blocking anything beneath, the
Pt OPAQUE flag should be set and widget->opaque rect should
identify that rectangular area. Otherwise, the Pt OPAQUE flag should
be cleared.

☞ If a widget’s fill color is Pg TRANSPARENT or has a

basic->roundness that’s greater than 0, the widget shouldn’t be
flagged as opaque.

Realization method
Inherited from PtWidget.

Draw method
PtBasic’s Draw method draws a rectangle filled with the current fill
color. The widget’s border is rendered if the Pt HIGHLIGHTED bit of
the widget flags is set and the border width is greater than 0.
If the Pt SET bit is set, the border is rendered inverted (i.e. the top
border color is used to draw the bottom border and vice versa).
PtBasic’s Draw method also handles focus rendering.

Unrealization method
None.

September 20, 2005 Chapter 4 ¯ Using Widget Superclasses 101

PtBasic  2005, QNX Software Systems

Destruction method
None.

Got Focus method

Damages widgets having both the Pt FOCUS RENDER and
Pt DAMAGE ON FOCUS flags set. Highlights and invokes the
basic->arm (Pt CB ARM) callback list if this widget has the
Pt AUTOHIGHLIGHT flag set. Invokes the basic->got focus
(Pt CB GOT FOCUS) callback list using PtInvokeCallbackList().

Lost Focus method

Damages widgets having both the Pt FOCUS RENDER and
Pt DAMAGE ON FOCUS flags set. Unhighlights and invokes the
basic->disarm (Pt CB DISARM) callback list if this widget has the
Pt AUTOHIGHLIGHT flag set. Invokes the basic->got focus
(Pt CB LOST FOCUS) callback list via PtInvokeCallbackList().

Calc Opaque Rect method

Sets or clears the widget’s Pt OPAQUE flag (Pt ARG FLAGS
resource) based on the widget’s fill color, roundness, and current
value of the Pt RECTANGULAR flag in the widget class structure.

Widget actions
PtBasic is sensitive to the following events:

Ph EV BUT PRESS
The widget sets/clears Pt SET flags, invokes Pt CB ARM (and
possibly Pt CB ACTIVATE if a toggle button is selected) and
Pt CB MENU (if the right mouse button is pressed).

Ph EV BUT REPEAT
The widget invokes the Pt CB REPEAT callbacks.

102 Chapter 4 ¯ Using Widget Superclasses September 20, 2005

 2005, QNX Software Systems PtBasic

Ph EV BUT RELEASE
The widget invokes the Pt CB DISARM callbacks. If a real
release (as opposed to a phantom release) is received, the
widget also invokes Pt CB ACTIVATE.

Ph EV BOUNDARY
The widget manages highlighting of widgets with the
Pt AUTOHIGHLIGHT flag set.

The raw callbacks return Pt CONTINUE to allow chaining to continue.

☞ If your widget class defines Pt SET RAW CALLBACKS, keep this in

mind: if your raw callback is sensitive to one of the events listed
above and the callback returns Pt END or Pt HALT, PtBasic behavior
for that event won’t occur unless you invoke PtBasic’s raw handlers
within the callback prior to returning. This can be done via
PtSuperClassRawEvent().

Resource definitions
Pt ARG BORDER WIDTH, Pt CHANGE RESIZE, 0,
Pt ARG IS NUMBER( PtWidget t, border width ), 0,

Pt ARG FLAGS, basic modify flags, 0,

Pt ARG IS FLAGS( PtWidget t, flags ), 0,

Pt ARG BOT BORDER COLOR, Pt CHANGE REDRAW, 0,

Pt ARG IS NUMBER( PtBasicWidget t, bot border color ), 0,

Pt ARG COLOR, Pt CHANGE REDRAW, 0,

Pt ARG IS NUMBER( PtBasicWidget t, color ), 0,

Pt ARG FILL COLOR, basic modify, 0,

Pt ARG IS NUMBER( PtBasicWidget t, fill color ), 0,

Pt ARG FILL PATTERN, Pt CHANGE REDRAW, 0,

Pt ARG IS STRUCT( PtBasicWidget t, fill pattern ), 0,

Pt ARG MARGIN HEIGHT, Pt CHANGE RESIZE REDRAW, 0,

Pt ARG IS NUMBER( PtBasicWidget t, margin height ), 0,

Pt ARG MARGIN WIDTH, Pt CHANGE RESIZE REDRAW, 0,

Pt ARG IS NUMBER( PtBasicWidget t, margin width ), 0,

September 20, 2005 Chapter 4 ¯ Using Widget Superclasses 103

PtBasic  2005, QNX Software Systems

Pt ARG TOP BORDER COLOR, Pt CHANGE REDRAW, 0,

Pt ARG IS NUMBER( PtBasicWidget t, top border color ), 0,

Pt CB ARM, Pt CHANGE INVISIBLE, 0,

Pt ARG IS CALLBACK LIST( PtBasicWidget t, arm ), 0,

Pt CB DISARM, Pt CHANGE INVISIBLE, 0,

Pt ARG IS CALLBACK LIST( PtBasicWidget t, disarm ), 0,

Pt CB ACTIVATE, Pt CHANGE INVISIBLE, 0,

Pt ARG IS CALLBACK LIST( PtBasicWidget t, activate ), 0,

Pt CB GOT FOCUS, Pt CHANGE INVISIBLE, 0,

Pt ARG IS CALLBACK LIST( PtBasicWidget t, got focus ), 0,

Pt CB LOST FOCUS, Pt CHANGE INVISIBLE, 0,

Pt ARG IS CALLBACK LIST( PtBasicWidget t, lost focus ), 0,

Pt CB REPEAT, Pt CHANGE INVISIBLE, 0,

Pt ARG IS CALLBACK LIST( PtBasicWidget t, repeat ), 0,

Pt ARG TRANS PATTERN, Pt CHANGE REDRAW, 0,

Pt ARG IS STRUCT( PtBasicWidget t, trans pattern ), 0,

Pt ARG HIGHLIGHT ROUNDNESS, basic modify, 0,

Pt ARG IS NUMBER( PtBasicWidget t, roundness ), 0,

Functions
static void basic modify flags()
For Pt ARG FLAGS, this function:
¯ recalculates the opaque rectangle if a highlighting flag is
changing
¯ damages the widget if the Pt GHOST flag is changing
¯ lets any other flag changes be handled via
PtSuperClassSetResources()
void basic modify()
Sets the fill color and roundness values. Invokes the Connection
method of PtBasic (which invokes the Calc Opaque Rect

104 Chapter 4 ¯ Using Widget Superclasses September 20, 2005

 2005, QNX Software Systems PtContainer

method), and reexamines the widget’s clear/opaque status via

PtUpdateVisibility().

Setting the Pt CONSUME EVENTS bit of PtWidget’s eflags resource

☞ controls whether a widget consumes any event it’s given. Container
widgets set this bit by default to prevent events from passing through
to the subclassed widgets beneath them.

PtContainer
This superclass provides a new origin, clipping, and constraints for
widget children. If you’re creating a widget with children, we
recommend you make your widget a subclass of PtContainer or
one of its subclasses.

☞ A container can have its own Draw method to render any

widget-specific data (other than children).

Class hierarchy
PtWidget → PtBasic → PtContainer

Class extensions
typedef struct Pt container widget class {
PtBasicWidgetClass t basic;
void (*child created f)( PtWidget t *widget,
PtWidget t *child );
int (*child settingresource f)(PtWidget t *widget,
PtWidget t *child, PtArg t *argt);
int (*child gettingresource f)(PtWidget t *widget,
PtWidget t *child, PtArg t *argt );
void (*child realized f)( PtWidget t *widget,
PtWidget t *child );
void (*child unrealized f)( PtWidget t *widget,
PtWidget t *child );
void (*child destroyed f)( PtWidget t *widget,
PtWidget t *child );
void (*child move resize f)( PtWidget t *widget,
PtWidget t *child, PhArea t *current area,
PhRect t *current extent, PhArea t *old area,

September 20, 2005 Chapter 4 ¯ Using Widget Superclasses 105

PtContainer  2005, QNX Software Systems

PhRect t *old extent );

int (*child getting focus f)( PtWidget t *widget,
PtWidget t *child, PhEvent t *event );
int (*child losing focus f)( PtWidget t *widget,
PtWidget t *child, PhEvent t *event );
} PtContainerClass t;

#define Pt SET CHILD SETTINGRESOURCE F \

(Pt ARG IS POINTER(PtContainerClass t, \
child settingresource f))
#define Pt SET CHILD GETTINGRESOURCE F \
(Pt ARG IS POINTER(PtContainerClass t, \
child gettingresource f))
#define Pt SET CHILD REALIZED F \
(Pt ARG IS POINTER(PtContainerClass t, child realized f))
#define Pt SET CHILD UNREALIZED F \
(Pt ARG IS POINTER(PtContainerClass t, child unrealized f))
#define Pt SET CHILD CREATED F \
(Pt ARG IS POINTER(PtContainerClass t, child created f))
#define Pt SET CHILD DESTROYED F \
(Pt ARG IS POINTER(PtContainerClass t, child destroyed f))
#define Pt SET CHILD MOVED RESIZED F \
(Pt ARG IS POINTER(PtContainerClass t, \
child move resize f))
#define Pt SET CHILD GETTING FOCUS F \
(Pt ARG IS POINTER(PtContainerClass t, \
child getting focus f))
#define Pt SET CHILD LOSING FOCUS F \
(Pt ARG IS POINTER(PtContainerClass t, child lost focus f))

Methods
PtContainer defines the class methods described below.

Defaults method
PtBasicWidget t *basic = (PtBasicWidget t *)widget;
PtContainerWidget t *ctnr =(PtContainerWidget t *)widget;

// Disjoint widgets store the system info in effect at

// their coordinates.
if( widget->class rec->flags & Pt DISJOINT )
ctnr->sysinfo = calloc( 1, sizeof( PhSysInfo t ) );
basic->margin width = 0;
basic->margin height = 0;

// containers, by default are to consume forwarded events

// even if they are not selectable.

106 Chapter 4 ¯ Using Widget Superclasses September 20, 2005

 2005, QNX Software Systems PtContainer

widget->eflags |= Pt CONSUME EVENTS;

widget->border width = 0;
widget->resize flags &= ˜Pt RESIZE XY BITS;
ctnr->anchor flags = Pt ANCHORS INVALID;
ctnr->flags = Pt CANVAS INVALID;
PtSetParentWidget( widget );

Initialization method
Registers with its parent for anchoring services. Registration is done
via PtContainerRegister().

Extent method
Finds the bounding box of widget children and applies its resize
policy. The extent is calculated, and if the canvas is different as a
result, all registered child containers are anchored. If the extent or
canvas is different, the resize callback list of the widget is invoked.
See PtSuperClassExtent() for a sample Extent method of a container.

Connection method
None.

Realization method
None.

Draw method
Inherited from PtBasic.

Unrealization method
Deregisters a widget from its parent. Destroys the current balloon
and sets it to NULL (if not NULL already).

Destruction method
Deregisters a widget from its parent.

September 20, 2005 Chapter 4 ¯ Using Widget Superclasses 107

PtContainer  2005, QNX Software Systems

Got Focus method

Inherited from PtBasic.

Lost Focus method

Inherited from PtBasic.

Calc Opaque Rect method

Inherited from PtBasic.

Child Created method

None.

Child Realized method

static void container child realized( PtWidget t *widget,
PtWidget t *child )
{
PtContainerWidget t *ctnr = (PtContainerWidget t *)widget;
PhRect t canvas;

if( ( ctnr->flags & Pt IGNORE CONSTRAINTS )

|| ( child->flags & Pt PROCREATED )
)
return;
if( ctnr->flags & Pt AUTO EXTENT )
{ // do an extent, which may cause children to be
// rearranged/resized - if so, ignore resize changes
ctnr->flags |= Pt IGNORE CONSTRAINTS;
PtMoveResizeWidget( widget, 0 );
ctnr->flags &= ˜Pt IGNORE CONSTRAINTS;
}
}

Child Moved/Resized method

Calls the Child Realized method with correct parameters:
static void container child moved resized( PtWidget t *wp,
PtWidget t *child, PhArea t *current area,
PhRect t *current extent, PhArea t *old area,
PhRect t *old extent );
{
container child realized( wp, child );
}

108 Chapter 4 ¯ Using Widget Superclasses September 20, 2005

 2005, QNX Software Systems PtContainer

Child Unrealized method

None.

Child Destroyed method

None.

Child Setting Resources method

None.

Child Getting Resources method

None.

Child Getting Focus method

None.

Child Losing Focus method

None.

Widget actions
Raw callbacks are supported for Ph EV BUT PRESS,
Ph EV BUT RELEASE, Ph EV BUT REPEAT, and Ph EV KEY events.
If there are callbacks in the Pt CB FILTER callback chain having an
event mask that matches the current event type, those callbacks are
invoked. If the value returned by a filter callback is greater than 0, that
value is returned. If there are balloons registered with this container,
the balloon list is checked to determine if a balloon needs to be
inflated and/or deflated.
If the event is a Ph EV KEY event, the event is given to the focused
child of the container, if there is one. If the event isn’t consumed by
the container, the hotkey chain of the nearest disjoint parent is
processed to see if the key is a hotkey. If a matching hotkey definition
is found, the hotkey callback is invoked and the event is consumed (by
returning Pt END).

September 20, 2005 Chapter 4 ¯ Using Widget Superclasses 109

PtContainer  2005, QNX Software Systems

If the event is a button press, release, or repeat, each child widget

intersecting the event is found via PtContainerHit() until one of these
widgets consumes the event.
When an intersecting widget is found, the event rectangle is translated
relative to the upper-left corner of the intersecting widget’s canvas.
Once translation has been performed, the event is given to the
intersecting widget via absorbed = PtEventHandler(). Upon return,
the event rectangle is detranslated by the same amount.
If all the following are true:

¯ the event was a button press

¯ the event hasn’t yet directed focus

¯ the current intersecting widget has the Pt GETS FOCUS flag set

then focus is given to that widget and event->processing flags has its
Ph DIRECTED FOCUS bit set. If the return from PtEventHandler()
was Pt END, the event is considered consumed and Pt END is
returned.
An extra step is performed if the event is a press and Pt ->current is
NULL: the absorbing widget is recorded for the purposes of delivering
phantom releases to the appropriate widget at a later time.

if( ( absorbed != Pt CONTINUE ) && wp &&

cbinfo->event->type == Ph EV BUT PRESS &&
! Pt ->current )
{ if ( wp->flags & Pt DESTROYED )
Pt ->current = (PtWidget t *)Pt END;
else
Pt ->current = wp;
}

Once the event has been consumed or there are no more intersecting
events, Pt END is returned. Otherwise, absorbed is returned.

110 Chapter 4 ¯ Using Widget Superclasses September 20, 2005

 2005, QNX Software Systems PtContainer

Resource definitions
static const PtRawCallback t callback = {
Pt EV REDIRECTED, container callback, NULL
};
static const PtResourceRec t resources[] = {
// overridden resources
Pt ARG AREA, container modify area, 0,
Pt ARG IS STRUCT( PtWidget t, area ), 0,
Pt ARG DIM, container modify area, 0,
Pt ARG IS STRUCT( PtWidget t, area.size ), 0,
Pt ARG POS, container modify area, 0,
Pt ARG IS STRUCT( PtWidget t, area.pos ), 0,
Pt ARG RESIZE FLAGS, container modify area, 0,
Pt ARG IS FLAGS( PtWidget t, resize flags ), 0,
// new resources
Pt ARG ANCHOR OFFSETS, container modify area, 0,
Pt ARG IS STRUCT( PtContainerWidget t,
anchor offset), 0,
Pt ARG ANCHOR FLAGS, container modify area, 0,
Pt ARG IS NUMBER( PtContainerWidget t,
anchor flags ), 0,
Pt ARG FOCUS, container modify, 0,
Pt ARG IS POINTER( PtContainerWidget t, focus ), 0,
Pt CB RESIZE, Pt CHANGE INVISIBLE, 0,
Pt ARG IS CALLBACK LIST( PtContainerWidget t,
resize ), 0,
Pt CB BALLOONS, container set balloons, 0,
Pt ARG IS LINK( PtContainerWidget t, balloons ), 0,
Pt ARG CONTAINER FLAGS, container modify flags, 0,
Pt ARG IS FLAGS( PtContainerWidget t, flags ), 0,
Pt CB FILTER, Pt CHANGE INVISIBLE, 0,
Pt ARG IS LINK( PtContainerWidget t, filters ), 0,
};

Functions
container modify area()
If area, pos, or dim is being modified, the container’s anchors
are invalidated and unlocked:
container->flags |= Pt ANCHORS INVALID;
container->flags &= ˜Pt ANCHORS LOCKED;

The Pt ANCHORS INVALID bit indicates that the widget can’t

be anchored using the values in the anchor offsets member until
these values are recalculated.

September 20, 2005 Chapter 4 ¯ Using Widget Superclasses 111

PtContainer  2005, QNX Software Systems

The Pt ANCHORS LOCKED bit indicates that the anchor offsets

for the container are valid and shouldn’t be recalculated due to
the change that just occurred. This bit is set when
Pt ARG ANCHOR OFFSETS is set. If
Pt ARG ANCHOR OFFSETS is set, the anchors are validated
and locked. If Pt ARG RESIZE FLAGS is being modified, the
anchors are invalidated and the widget is flagged for resize:

widget->flags |= Pt WIDGET RESIZE;

container modify()
static void container modify( PtWidget t *widget,
PtArg t *arg )
{
PtContainerWidget t *container =
(PtContainerWidget t *)widget;
PhEvent t event;

memset( &event, 0, sizeof( event ) );

switch( arg->type )
{
case Pt ARG FOCUS:
// If the widget is already focused or isn’t
// the immediate child of this container,
// do nothing.

if (( container->focus ==
(PtWidget t *)arg->value )
|| ( !arg->value )
|| (((PtWidget t *)arg->value)->parent !=
widget))
return;

// otherwise, give the target widget focus.

PtContainerGiveFocus( (PtWidget t *)arg->value,
&event );
}
}

container set balloons()

Registers/deregisters balloons with the container and
increments/decrements the container’s balloon count
(container->balloon count). If the balloon count is nonzero, the

112 Chapter 4 ¯ Using Widget Superclasses September 20, 2005

 2005, QNX Software Systems PtContainer

balloons active bit located in container->anchor flags is set;

otherwise, it’s cleared.
A raw callback function to check the balloon list is added if the
balloon count is nonzero and the balloons active bit was not set.
The callback is removed if the balloon count goes to zero and
the balloons active bit was set.
container modify flags()
Container flags are set/cleared. If one of the bits affected was
the Pt AUTO EXTENT bit, several constraint functions are
enabled or disabled and the widget is (potentially) scheduled to
have its Extent method executed.

container modify flags( PtWidget t *widget, PtArg t *argt )

{
PtContainerWidget t *ctnr =
(PtContainerWidget t *)widget;
int changed;

argt->len &= ˜Pt CONTAINER RO FLAGS;

changed = ctnr->flags;
changed ˆ= ctnr->flags = ( ctnr->flags & ˜argt->len ) |
( argt->value & argt->len );

if( changed & Pt AUTO EXTENT )

{ if( ctnr->flags & Pt AUTO EXTENT )
{
// Turn on constraints and schedule
// for extenting.

ctnr->flags |= Pt CHILD REALIZED |

Pt CHILD UNREALIZED |
Pt CHILD MOVED RESIZED;
widget->flags |= Pt WIDGET RESIZE;
}else
{ //turn off constraints.
ctnr->flags &= ˜(Pt CHILD REALIZED |
Pt CHILD UNREALIZED |
Pt CHILD MOVED RESIZED );
}
}
}

September 20, 2005 Chapter 4 ¯ Using Widget Superclasses 113

PtCompound  2005, QNX Software Systems

PtCompound
This class is used for creating widgets whose functionality (in part) is
derived from exported subordinate widgets.

Class hierarchy
PtWidget → PtBasic → PtContainer → PtCompound

Class extensions
typedef struct Pt compound class {
PtContainerClass t container;
ushort t num subordinates;
ushort t *subordinates;
ushort t num blocked resources;
ulong t *blocked resources;
} PtCompoundClass t;

#define Pt SET NUM SUBORDINATES \

(Pt ARG IS NUMBER(PtCompoundClass t,num subordinates))

#define Pt SET SUBORDINATES \

(Pt ARG IS POINTER(PtCompoundClass t,subordinates)

#define Pt SET NUM BLOCKED RESOURCES \

(Pt ARG IS NUMBER(PtCompoundClass t,num blocked resources))

#define Pt SET BLOCKED RESOURCES \

(Pt ARG IS POINTER(PtCompoundClass t,blocked resources)

Pt SET NUM SUBORDINATES

Indicates the number of subordinate widgets to be exported.

Pt SET SUBORDINATES
An array of offsets to widget pointers to subordinate widgets.
These widgets must be created in the compound widget’s
Defaults method.
Pt SET NUM BLOCKED RESOURCES
Indicates the number of resources to block.

114 Chapter 4 ¯ Using Widget Superclasses September 20, 2005

 2005, QNX Software Systems PtCompound

Pt SET BLOCKED RESOURCES

An array of resources to block.

Methods
PtCompound defines the class methods described below.

Defaults method
Inherits all defaults from PtContainer.

Initialization method
None.

Extent method
Inherited from PtContainer.

Connection method
None.

Realization method
None.

Draw method
Inherited from PtContainer.

Unrealization method
None.

Destruction method
Destroys the redirected callback lists of exported subordinates having
callback resources set on them.

September 20, 2005 Chapter 4 ¯ Using Widget Superclasses 115

PtGenList  2005, QNX Software Systems

Got Focus method

Inherited from PtBasic.

Lost Focus method

Inherited from PtContainer.

Calc Opaque Rect method

Inherited from PtBasic.

Widget actions
None.

Resource definitions
None.

Functions
None.

PtGenList
This class is used for creating list widgets.

Class hierarchy
PtWidget → PtBasic → PtContainer → PtCompound →
PtGenList

Class extensions
typedef void PtGenListDrawF t(
PtGenListWidget t *widget, PtGenListItem t *item,
unsigned index,unsigned nitems, PhRect t *where
);

typedef int PtGenListMouseF t(

PtGenListWidget t *wgt, PtGenListItem t *item,
unsigned index, PhPoint t *where, PhEvent t const *ev
);

116 Chapter 4 ¯ Using Widget Superclasses September 20, 2005

 2005, QNX Software Systems PtGenList

typedef int PtGenListKeyF t(

PtGenListWidget t *wgt, PhEvent t const *ev,
PhKeyEvent t *kev,PtGenListItem t *newcur,
unsigned newpos
);

typedef void PtGenListSelectF t(

PtGenListWidget t *wgt, PtGenListItem t *item, int pos,
int nitems, int subtype, PhEvent t const *ev
);

typedef PtWidget t *PtGenListInflateF t(

PtWidget t *widget, PtWidget t *parent,
PtGenListItem t *item, unsigned index,
int column, PhArea t *area
);

typedef struct Pt gen list widget class {

PtCompoundClass t compound;
PtGenListDrawF t *list draw f;
PtGenListMouseF t *list mouse f;
PtGenListKeyF t *list key f;
PtGenListSelectF t *list select f;
PtGenListInflateF t *list inflate f;
}
PtGenListClass t;

#define Pt SET LIST DRAW F \

Pt ARG IS POINTER( PtGenListClass t, list draw f )
#define Pt SET LIST MOUSE F \
Pt ARG IS POINTER( PtGenListClass t, list mouse f )
#define Pt SET LIST KEY F \
Pt ARG IS POINTER( PtGenListClass t, list key f )
#define Pt SET LIST SELECT F \
Pt ARG IS POINTER( PtGenListClass t, list select f )
#define Pt SET LIST INFLATE F \
Pt ARG IS POINTER( PtGenListClass t, list inflate f )

Methods
PtGenList defines the class methods described below.

September 20, 2005 Chapter 4 ¯ Using Widget Superclasses 117

PtGenList  2005, QNX Software Systems

Defaults method
widget->flags
|= Pt HIGHLIGHTED | Pt ETCH HIGHLIGHT | Pt SET
| Pt GETS FOCUS | Pt FOCUS RENDER;
widget->eflags &= ˜Pt DAMAGE ON FOCUS;
widget->resize flags &= ˜Pt RESIZE XY BITS;
widget->border width = 2;
list->flags = Pt LIST SCROLLBAR AS REQUIRED;
list->sel mode = Pt BROWSE MODE;
list->scroll rate = 2;
list->selection fill color = Pg BLUE;
list->selection text color = Pg WHITE;
list->balloon bg = Pg BALLOONCOLOR;
list->balloon fg = Pg BLACK;
list->font = strdup( "helv12" );
basic->margin width =
basic->margin height = 0;
basic->flags &= ˜Pt DAMAGE ON FOCUS;
list->slider width = 15;
list->top item = 1;

Initialization method
None.

Extent method
If a PtDivider widget is the child, the Extent method:

¯ calls the Extent method of PtDivider via PtExtentWidget()

¯ adjusts the size of the PtDivider widget according to the resize

policy and the Pt LIST SNAP flag

Then the Extent method of PtCompound is invoked via

PtSuperClassExtent().

Connection method
None.

118 Chapter 4 ¯ Using Widget Superclasses September 20, 2005

 2005, QNX Software Systems PtGenList

Realization method
Realizes the scrollbar if necessary and registers a balloon callback
with the parent.

Draw method
Renders the widget’s border, margins, and (possibly) background.
Then the List Draw method is called to draw the list.

Unrealization method
Deregisters a balloon callback with the parent.

Destruction method
None.

Got Focus method

If the Pt FOCUS RENDER flag is set, the Got Focus method damages
the current item. If the Pt SELECTION MODE AUTO flag is set but the
Pt SELECTION MODE NOFOCUS flag isn’t set and no items are
selected, the current item is selected. Then the Got Focus method of
PtCompound is invoked via PtSuperClassGotFocus().

Lost Focus method

If necessary, the current item is damaged. Then the Lost Focus
method of PtCompound is invoked via PtSuperClassLostFocus().

Calc Opaque Rect method

Inherited from PtBasic.

Child Created method

Sets the child-redirector function to PtCompoundRedirect() via
PtContainerChildRedirect(). This prevents the list widget from
having more than one PtDivider child.

September 20, 2005 Chapter 4 ¯ Using Widget Superclasses 119

PtGenList  2005, QNX Software Systems

Child Realized method

If the child isn’t the scrollbar (it’s a divider), the Child Realized
method:

¯ Sets list->divider to the widget pointer of the child.

¯ Adjusts the top margin.

¯ Sets the orientation of the child to horizontal.

¯ Sets the child’s Pt ARG DIVIDER OFFSET resource and the

Pt CALLBACKS ACTIVE flag.

¯ Copies the Pt ARG DIVIDER SIZES resource of the child to the

Pt ARG LIST COLUMN POS resource of the list widget.

¯ Attaches a function to the Pt CB DIVIDER DRAG callback list.

Child Moved/Resized method

If the child is a divider (i.e. list->divider), the Child Moved/Resized
method sets the divider’s Pt ARG DIVIDER OFFSET resource and
adjusts the top margin of the list widget.

Child Unrealized method

If the child is the same as list->divider, the Child Unrealized method
adjusts the top margin, removes the callback, and sets list->divider to
NULL.

Child Destroyed method

Sets the child-redirector function to a private function that accepts a
PtDivider child only.

Child Setting Resources method

Inherited from PtContainer.

120 Chapter 4 ¯ Using Widget Superclasses September 20, 2005

 2005, QNX Software Systems PtGenList

Child Getting Resources method

Inherited from PtContainer.

Child Getting Focus method

Inherited from PtContainer.

Child Losing Focus method

Inherited from PtContainer.

List Draw method

None.

List Mouse method

None.

List Key method

None.

List Select method

None.

List Inflate method

None.

Widget actions
PtGenList is sensitive to the following events:

¯ Ph EV KEY

¯ Ph EV BUT PRESS

¯ Ph EV PTR MOTION BUTTON

¯ Ph EV BUT RELEASE

¯ Ph EV BUT REPEAT

September 20, 2005 Chapter 4 ¯ Using Widget Superclasses 121

PtGenList  2005, QNX Software Systems

The callback function invokes the List Key or List Mouse method and
performs the selection.

☞ If your widget class defines Pt SET RAW CALLBACKS, keep this in

mind: if your raw callback is sensitive to one of the events listed
above and the callback returns Pt END or Pt HALT, PtGenList
behavior for that event won’t occur unless you invoke PtGenList’s
raw handlers within the callback prior to returning. This can be done
via PtSuperClassRawEvent().

Resource definitions
{ Pt ARG AREA, arg resize, NULL,
Pt ARG IS STRUCT( PtWidget t, area )
},
{ Pt ARG DIM, arg resize, NULL,
Pt ARG IS STRUCT( PtWidget t, area.size )
},
{ Pt ARG POS, arg resize, NULL,
Pt ARG IS STRUCT( PtWidget t, area.pos )
},
{ Pt ARG MARGIN HEIGHT, arg resize, NULL,
Pt ARG IS NUMBER( PtGenListWidget t, bot margin )
},
{ Pt ARG MARGIN WIDTH, arg resize, NULL,
Pt ARG IS NUMBER( PtGenListWidget t, margin width )
},
{ Pt ARG LIST FLAGS, arg flags, NULL,
Pt ARG IS FLAGS( PtGenListWidget t, flags )
},
{ Pt ARG LIST FONT, arg font, NULL,
Pt ARG IS STRING( PtGenListWidget t, font )
},
{ Pt ARG SCROLLBAR WIDTH, arg resize, NULL,
Pt ARG IS NUMBER( PtGenListWidget t, slider width )
},
{ Pt ARG SELECTION MODE, arg selmode, NULL,
Pt ARG IS NUMBER( PtGenListWidget t, sel mode )
},
{ Pt ARG TOP ITEM POS, arg top pos, NULL,
Pt ARG IS NUMBER( PtGenListWidget t, top item )
},
{ Pt ARG VISIBLE COUNT, Pt CHANGE PREVENT, NULL,
Pt ARG IS NUMBER( PtGenListWidget t, displayed count )
},
{ Pt ARG SELECTION FILL COLOR, Pt CHANGE REDRAW, NULL,

122 Chapter 4 ¯ Using Widget Superclasses September 20, 2005

 2005, QNX Software Systems PtGenList

Pt ARG IS NUMBER( PtGenListWidget t, selection fill color )

},
{ Pt ARG SELECTION TEXT COLOR, Pt CHANGE REDRAW, NULL,
Pt ARG IS NUMBER( PtGenListWidget t, selection text color)
},
{ Pt ARG LIST ITEM COUNT, Pt CHANGE PREVENT, NULL,
Pt ARG IS NUMBER( PtGenListWidget t, item count )
},
{ Pt ARG LIST SEL COUNT, Pt CHANGE PREVENT, NULL,
Pt ARG IS NUMBER( PtGenListWidget t, sel count )
},
{ Pt ARG LIST TOTAL HEIGHT, Pt CHANGE PREVENT, NULL,
Pt ARG IS NUMBER( PtGenListWidget t, total height )
},
{ Pt ARG LIST SB RES, arg setsb, arg getsb
},
{ Pt ARG LIST SCROLL RATE, Pt CHANGE INVISIBLE, NULL,
Pt ARG IS NUMBER( PtGenListWidget t, scroll rate )
},
{ Pt ARG LIST COLUMN POS, arg columns, NULL,
Pt ARG IS ARRAY( PtGenListWidget t, columns ),
Pt ARG IS NUMBER( PtGenListWidget t, ncolumns )
},
{ Pt ARG LIST COLUMN ATTR, Pt CHANGE REDRAW, NULL,
Pt ARG IS ARRAY( PtGenListWidget t, col attrs ),
Pt ARG IS NUMBER( PtGenListWidget t, ncol attrs )
},
{ Pt CB SCROLL MOVE, Pt CHANGE INVISIBLE, NULL,
Pt ARG IS CALLBACK LIST( PtGenListWidget t, scroll )
} };

Functions
static void arg resize()
This function:
¯ adjusts the number of displayed items
¯ resizes the scrollbar
¯ adjusts the Pt ARG DIVIDER OFFSET resource of the
widget pointed to by list->divider
static void arg font()
This function:

September 20, 2005 Chapter 4 ¯ Using Widget Superclasses 123

PtGenList  2005, QNX Software Systems

¯ allocates a copy of the new font name and frees the old string
¯ stores the height of the new font in list->font height
static void arg top pos()
This function:
¯ calculates a new range of displayed items
¯ blits some of the currently visible items to their new
positions (blits only the items that will remain visible after
the change)
¯ adjusts the scrollbar position
¯ invokes the Pt CB SCROLL MOVE callback
static void arg selmode()
This function:
¯ clears the current selection
¯ if the new value is valid, sets list->sel mode,
list->sel xmode, and list->sel flags
static void arg flags()
For Pt ARG LIST FLAGS, this function:
¯ adjusts the Pt BLOCKED flag of the scrollbar if the
Pt LIST INACTIVE flag is changed
¯ adjusts the Pt GETS FOCUS flag of the scrollbar if the
Pt LIST SCROLLBAR GETS FOCUS flag is changed
¯ adjusts list->sel xmode and list->sel flags if the
Pt LIST NON SELECT flag is changed

static void arg setsb()

This function:
¯ checks if allowed resources were specified
¯ calls PtSetResources() for the scrollbar
static void arg getsb()
Calls PtGetResources() for the scrollbar.

124 Chapter 4 ¯ Using Widget Superclasses September 20, 2005

 2005, QNX Software Systems PtGenTree

static void arg columns()

This function:
¯ saves the new value
¯ damages the appropriate portions of the widget

For more information, see the chapter on Creating a List Widget.

PtGenTree
This class is used for creating tree widgets.

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

Class extensions
typedef void PtGenTreeDrawItemF t(
PtGenTreeWidget t *wgt, PtGenTreeItem t *item,
PhRect t const *where, int lmargin, int rmargin
);

typedef int PtGenTreeItemStateF t(

PtGenTreeWidget t *wgt, PtGenTreeItem t *item,
PhEvent t const *event, int reason
);

typedef struct Pt gen tree widget class {

PtGenListClass t list;
PtGenTreeDrawItemF t *tree draw item f;
PtGenTreeItemStateF t *tree state f;
}
PtGenTreeClass t;

#define Pt SET TREE DRAW F \

Pt ARG IS POINTER( PtGenTreeClass t, tree draw item f )
#define Pt SET TREE STATE F \
Pt ARG IS POINTER( PtGenTreeClass t, tree state f )

September 20, 2005 Chapter 4 ¯ Using Widget Superclasses 125

PtGenTree  2005, QNX Software Systems

Methods
PtGenTree defines the class methods described below.

Defaults method
tree->flags = Pt TREE HAS BUTTONS | Pt TREE HAS LINES |
Pt TREE ROOT LINES;
tree->list.gflags = Pt GEN LIST SHOW DAMAGED |
Pt GEN LIST ITEM BACKGROUND;

Initialization method
None.

Extent method
Inherited from PtGenList.

Connection method
None.

Realization method
None.

Draw method
Inherited from PtGenList.

Unrealization method
None.

Destruction method
None.

Got Focus method

Inherited from PtGenList.

126 Chapter 4 ¯ Using Widget Superclasses September 20, 2005

 2005, QNX Software Systems PtGenTree

Lost Focus method

Inherited from PtGenList.

Calc Opaque Rect method

Inherited from PtBasic.

Child Created method

Inherited from PtGenList.

Child Realized method

Inherited from PtGenList.

Child Moved/Resized method

Inherited from PtGenList.

Child Unrealized method

Inherited from PtGenList.

Child Destroyed method

Inherited from PtGenList.

Child Setting Resources method

Inherited from PtContainer.

Child Getting Resources method

Inherited from PtContainer.

Child Getting Focus method

Inherited from PtContainer.

Child Losing Focus method

Inherited from PtContainer.

September 20, 2005 Chapter 4 ¯ Using Widget Superclasses 127

PtGenTree  2005, QNX Software Systems

List Draw method

For each visible item that has the Pt LIST ITEM DAMAGED flag set,
the List Draw method calls the Tree Draw Item method and draws the
tree ornaments.

List Mouse method

Invokes the Pt CB GEN TREE INPUT callback list. Depending on
the result of the callback and the pointer position, the List Mouse
method returns Pt CONTINUE, returns Pt END, or calls
PtGenTreeCollapse() or PtGenTreeExpand() and returns Pt END.

List Key method

Invokes the Pt CB GEN TREE INPUT callback list. Depending on
the result of the callback and the key code, the List Key method
returns Pt CONTINUE, returns Pt END, or calls PtGenTreeCollapse()
or PtGenTreeExpand() and returns Pt HALT.

Tree Draw Item method

None.

Tree Item State method

None.

Widget actions
None.

Resource definitions
{ Pt ARG TREE FLAGS, arg flags, NULL,
Pt ARG IS FLAGS( PtGenTreeWidget t, flags )
},
{ Pt CB GEN TREE INPUT, Pt CHANGE INVISIBLE, NULL,
Pt ARG IS CALLBACK LIST( PtGenTreeWidget t, input cb )
} };

128 Chapter 4 ¯ Using Widget Superclasses September 20, 2005

 2005, QNX Software Systems PtLabel

Functions
static void arg flags()
This function:
¯ adjusts list->gflags if the Pt TREE TO RIGHT flag has
changed
¯ damages the widget or marks it for resizing

For more information, see the chapter on Creating a Tree Widget.

PtLabel
The PtLabel class provides fundamental multiline-text string and
image handling.

Class hierarchy
PtWidget → PtBasic → PtLabel

Methods
PtLabel defines the class methods described below.

Defaults method
widget->flags |= Pt FOCUS RENDER;
widget->resize flags |= Pt RESIZE XY AS REQUIRED;
label->basic.fill color = Pg TRANSPARENT;
label->font = strdup( "helv12" );
label->flags |= Pt LABEL SELECT SHIFT;
label->uline1 = Pg BLACK;
label->uline2 = Pg TRANSPARENT;
label->uline type =(ushort t) Pt NO ULINE;
label->type = Pt Z STRING;
label->basic.margin width = 2;
label->basic.margin height = 2;
label->margin top = 0;
label->margin bottom = 0;
label->margin left = 0;
label->margin right = 0;
label->h alignment = Pt LEFT;
label->v alignment = Pt CENTER;
label->string = strdup("");
label->inflate f = PtInflateBalloon;

September 20, 2005 Chapter 4 ¯ Using Widget Superclasses 129

PtLabel  2005, QNX Software Systems

label->balloon fill color = Pg BALLOONCOLOR;

label->balloon color = Pg BLACK;

Initialization method
None.

Extent method
Determines the required canvas size based on the widget’s text string
or image data in conjunction with label->type (Pt Z STRING,
Pt TEXT IMAGE ), margins, etc. The Extent method also takes into
account multiple lines of text and underlining.

Connection method
If label->flags has the Pt SHOW BALLOON flag set, a balloon
callback is attached to the parent widget.

Realization method
Inherited from PtBasic.

Draw method
Calls the Draw method of PtBasic via PtSuperClassDraw(). Draws
the text in the label using the specified font, color, etc.

Unrealization method
If this label has a balloon displayed (label->balloon widget != NULL),
that widget is destroyed. If label->flags has the Pt SHOW BALLOON
flag set, it detaches the balloon callback from the parent.

Destruction method
If widget->flags has the Pt FREE MEMORY flag set, any memory used
for the label’s image and palette is freed.

130 Chapter 4 ¯ Using Widget Superclasses September 20, 2005

 2005, QNX Software Systems PtLabel

Got focus method

Inherited from PtBasic.

Lost Focus method

Inherited from PtBasic.

Calc Opaque Rect method

If label->type is Pt Z STRING, the Calc Opaque Rect method is called
via PtSuperClassCalcOpaque().
If label->type is Pt IMAGE, label->flags has its Pt OPAQUE flag set.
If label->type is Pt BITMAP and label->data->image->type is
Pg BITMAP BACKFILL, the Pt OPAQUE bit of widget->flags is set.

Widget actions
None.

Resource definitions
Pt ARG HORIZONTAL ALIGNMENT, Pt CHANGE REDRAW, 0,
Pt ARG IS NUMBER( PtLabelWidget t, h alignment ), 0,

Pt ARG LABEL DATA, Pt CHANGE RESIZE REDRAW, 0,

Pt ARG IS ALLOC( PtLabelWidget t, data ), 0,

Pt ARG LABEL FLAGS, label modify flags, 0,

Pt ARG IS FLAGS( PtLabelWidget t, flags ),0,

Pt ARG LABEL TYPE, Pt CHANGE RESIZE REDRAW, 0,

Pt ARG IS NUMBER( PtLabelWidget t, type), 0,

Pt ARG MARGIN BOTTOM, Pt CHANGE RESIZE REDRAW, 0,

Pt ARG IS NUMBER( PtLabelWidget t, margin bottom ), 0,

Pt ARG MARGIN LEFT, Pt CHANGE RESIZE REDRAW, 0,

Pt ARG IS NUMBER( PtLabelWidget t, margin left ), 0,

Pt ARG MARGIN RIGHT, Pt CHANGE RESIZE REDRAW, 0,

Pt ARG IS NUMBER( PtLabelWidget t, margin right ), 0,

Pt ARG MARGIN TOP, Pt CHANGE RESIZE REDRAW, 0,

Pt ARG IS NUMBER( PtLabelWidget t, margin top ), 0,

September 20, 2005 Chapter 4 ¯ Using Widget Superclasses 131

PtLabel  2005, QNX Software Systems

Pt ARG SELECT SHIFT, Pt CHANGE REDRAW, 0,

Pt ARG IS BOOLEAN( PtLabelWidget t, flags ),
Pt LABEL SELECT SHIFT,

Pt ARG TEXT FONT, Pt CHANGE RESIZE REDRAW, 0,

Pt ARG IS STRING( PtLabelWidget t, font ), 0,

Pt ARG TEXT STRING, PtModifyLabelString, 0,

Pt ARG IS STRING( PtLabelWidget t, string ), 0,

Pt ARG UNDERLINE1, Pt CHANGE RESIZE REDRAW, 0,

Pt ARG IS NUMBER( PtLabelWidget t, uline1), 0,

Pt ARG UNDERLINE2, Pt CHANGE RESIZE REDRAW, 0,

Pt ARG IS NUMBER( PtLabelWidget t, uline2), 0,

Pt ARG UNDERLINE TYPE, Pt CHANGE RESIZE REDRAW, 0,

Pt ARG IS NUMBER( PtLabelWidget t, uline type), 0 ,

Pt ARG VERTICAL ALIGNMENT, Pt CHANGE REDRAW, 0,

Pt ARG IS NUMBER( PtLabelWidget t, v alignment ), 0,

Pt ARG BALLOON POSITION, Pt CHANGE INVISIBLE, 0,

Pt ARG IS NUMBER( PtLabelWidget t, balloon pos ), 0,

Pt ARG LABEL BALLOON, Pt CHANGE INVISIBLE, 0,

Pt ARG IS POINTER( PtLabelWidget t, inflate f), 0,

Pt ARG ACCEL KEY, Pt CHANGE RESIZE REDRAW, 0,

Pt ARG IS STRING( PtLabelWidget t, accel key ), 0,

Pt ARG BALLOON FILL COLOR, Pt CHANGE INVISIBLE, 0,

Pt ARG IS NUMBER( PtLabelWidget t, balloon fill color ), 0,

Pt ARG BALLOON COLOR, Pt CHANGE INVISIBLE, 0,

Pt ARG IS NUMBER( PtLabelWidget t, balloon color ), 0,

Pt ARG LINE SPACING, Pt CHANGE RESIZE REDRAW, 0,

Pt ARG IS NUMBER( PtLabelWidget t, line spacing ), 0,

Functions
static int label modify flags( PtWidget t *widget,
PtArg t *argt );

If the Pt SHOW BALLOON flag is being set, the balloon callback is

attached to the parent. If the Pt SHOW BALLOON flag is being

132 Chapter 4 ¯ Using Widget Superclasses September 20, 2005

 2005, QNX Software Systems PtGraphic

cleared, the balloon callback is detached from the parent. The value
of label->flags is based on argt->value and argt->len. This is
typically done as follows:
label->flags = (label->flags & ˜argt->len) | argt->value;

int PtModifyLabelString( PtWidget t *widget,

PtArg t *argt );

This frees the current string, allocates enough space for the new
string, copies in the new string, flags the widget to be resized
(widget->flags |= Pt WIDGET RESIZE;), and damages the widget.
If a balloon is displayed, the balloon is destroyed and a new balloon is
inflated with the new string. If label->flags has the
Pt BALLOON AS REQUIRED bit set, the new balloon will be created
only if the label will be clipped by its parent.

PtGraphic
This class provides standard graphic resources such as
Pt ARG POINTS and Pt ARG ORIGIN.

Class hierarchy
PtWidget → PtBasic → PtGraphic

Methods
PtGraphic defines the class methods described below.

Defaults method
static void graphic dflts( PtWidget t *widget )
{
PtGraphicWidget t *graphic =
(PtGraphicWidget t *)widget;

graphic->line width = 0L;

graphic->line cap = Pg BUTT CAP;
graphic->line join = Pg MITER JOIN;
graphic->basic.margin height = 0;

September 20, 2005 Chapter 4 ¯ Using Widget Superclasses 133

PtGraphic  2005, QNX Software Systems

graphic->basic.margin width = 0;
graphic->basic.fill color = Pg TRANSPARENT;
graphic->npoints = 0;
graphic->point array = NULL;
}

Initialization method
None.

Extent method
Determines the render rectangle for the graphic widget, given the
area, point array, and current settings of graphic flags.

Connection method
None.

Realization method
None.

Draw method
Inherited from PtBasic.

Unrealization method
None.

Destruction method
None.

Got Focus method

Inherited from PtBasic.

Lost Focus method

Inherited from PtBasic.

134 Chapter 4 ¯ Using Widget Superclasses September 20, 2005

 2005, QNX Software Systems PtGraphic

Calc Opaque Rect method

Inherited from PtBasic.

Widget actions
None.

Resource definitions
static PtResourceRec t resources[] = {
Pt ARG AREA, graphic modify area, 0,
Pt ARG IS STRUCT( PtWidget t, area ), 0,
Pt ARG DIM, graphic modify area, 0,
Pt ARG IS STRUCT( PtWidget t, area.size ), 0,
Pt ARG DASH LIST, Pt CHANGE REDRAW, 0,
Pt ARG IS ARRAY( PtGraphicWidget t, dash list ),
Pt ARG IS NUMBER( PtGraphicWidget t, dash len ),
Pt ARG GRAPHIC FLAGS, Pt CHANGE RESIZE, 0,
Pt ARG IS FLAGS( PtGraphicWidget t, flags ),0,
Pt ARG LINE WIDTH, Pt CHANGE RESIZE REDRAW, 0,
Pt ARG IS NUMBER( PtGraphicWidget t,
line width ), 0,
Pt ARG LINE JOIN, Pt CHANGE REDRAW, 0,
Pt ARG IS NUMBER( PtGraphicWidget t,
line join ), 0,
Pt ARG LINE CAP, Pt CHANGE REDRAW, 0,
Pt ARG IS NUMBER( PtGraphicWidget t, line cap ), 0,
Pt ARG ORIGIN, Pt CHANGE RESIZE REDRAW, 0,
Pt ARG IS STRUCT( PtGraphicWidget t, origin ), 0,
Pt ARG POINTS, Pt CHANGE RESIZE REDRAW, 0,
Pt ARG IS ARRAY( PtGraphicWidget t, point array),
Pt ARG IS NUMBER( PtGraphicWidget t, npoints),
Pt CB RESCALE, Pt CHANGE INVISIBLE, 0,
Pt ARG IS LINK( PtGraphicWidget t, rescale ) |
Pt ARG PARM(sizeof( PtCallback t)), 0,
Pt ARG DASH SCALE, Pt CHANGE REDRAW, 0,
Pt ARG IS NUMBER( PtGraphicWidget t,
dash scale ), 0,
};

Functions
graphic modify area()
Updates the widget’s area or dimension and invokes the
Pt CB RESCALE callback.

September 20, 2005 Chapter 4 ¯ Using Widget Superclasses 135

PtGauge  2005, QNX Software Systems

PtGauge
This class provides standard gauge resources such as maximum,
minimum, and orientation.

Class hierarchy
PtWidget → PtBasic → PtGauge

Methods
PtGauge defines the class methods described below.

Defaults method
static void gauge dflts( PtWidget t *widget )
{
PtGaugeWidget t *gauge = (PtGaugeWidget t *)widget;
static const char helv12[] = "helv12";

gauge->font = malloc( sizeof(helv12) );

if( gauge->font != NULL )
strcpy( gauge->font, helv12 );
gauge->flags = 0;
gauge->orientation = Pt HORIZONTAL;
gauge->value = 0;
gauge->minimum = 0;
gauge->maximum = 100;
}

Initialization method
None.

Extent method
Inherited from PtBasic.

Connection method
None.

136 Chapter 4 ¯ Using Widget Superclasses September 20, 2005

 2005, QNX Software Systems PtGauge

Realization method
None.

Draw method
Inherited from PtBasic.

Unrealization method
None.

Destruction method
None.

Got Focus method

Inherited from PtBasic.

Lost Focus method

Inherited from PtBasic.

Calc Opaque Rect method

Inherited from PtBasic

Widget actions
None.

Resource definitions
static const PtResourceRec t resources[] = {
Pt ARG GAUGE FLAGS, Pt CHANGE INVISIBLE, 0,
Pt ARG IS FLAGS( PtGaugeWidget t, flags ), 0,
Pt ARG GAUGE FONT, Pt CHANGE INVISIBLE, 0,
Pt ARG IS STRING( PtGaugeWidget t, font ), 0,
Pt ARG GAUGE MINIMUM, Pt CHANGE INVISIBLE, 0,
Pt ARG IS NUMBER( PtGaugeWidget t, minimum ), 0,
Pt ARG GAUGE MAXIMUM, Pt CHANGE INVISIBLE, 0,
Pt ARG IS NUMBER( PtGaugeWidget t, maximum ), 0,
Pt ARG GAUGE VALUE, Pt CHANGE INVISIBLE, 0,
Pt ARG IS NUMBER( PtGaugeWidget t, value ), 0,
Pt ARG GAUGE ORIENTATION, Pt CHANGE INVISIBLE, 0,
Pt ARG IS NUMBER( PtGaugeWidget t, orientation ), 0,
};

September 20, 2005 Chapter 4 ¯ Using Widget Superclasses 137

PtGauge  2005, QNX Software Systems

Functions
None.

138 Chapter 4 ¯ Using Widget Superclasses September 20, 2005

 Chapter 5
Creating a List Widget

In this chapter. . .
Overview 141
Convenience functions 149
PtGenListAddItems() 153
PtGenListAllItems() 155
PtGenListClearSelection() 156
PtGenListDamageItem() 157
PtGenListDrawBackground() 158
PtGenListDrawString() 159
PtGenListFirstItem() 161
PtGenListGetCurrent() 162
PtGenListGetSelIndexes() 163
PtGenListGoto() 164
PtGenListHold() 165
PtGenListItemIndex() 166
PtGenListItemRealloc() 167
PtGenListLastItem() 168
PtGenListLockItem() 169
PtGenListRelease() 170
PtGenListRemoveItems() 171
PtGenListResize() 173
PtGenListSelect() 174
PtGenListSelectedItems() 175
PtGenListSetGflags() 176
PtGenListSetSelIndexes() 177
PtGenListShow() 178
PtGenListUnlockItem() 179
PtGenListUnselect() 180
PtSuperClassGenListDraw() 181
PtSuperClassGenListInflate() 182

September 20, 2005 Chapter 5 ¯ Creating a List Widget 139

  2005, QNX Software Systems

PtSuperClassGenListKey() 183
PtSuperClassGenListMouse() 184
PtSuperClassGenListSelect() 185

140 Chapter 5 ¯ Creating a List Widget September 20, 2005

 2005, QNX Software Systems Overview

Overview
The Photon library provides the generic list widget class PtGenList
for creating custom list widgets. The PtGenList class displays a
vertical list of any number of items. A user can select one or more
items from this list, depending on the selection policy.
The child class shouldn’t override the Draw method or consume
mouse or key events. Instead, it should define a List Draw method for
drawing and may define a Mouse and/or Key Event method if
additional handling of those event types is required. Usually, the child
class will also define a Selection method that will be called by the
PtGenList event handler.

Item structure
The PtGenList class never allocates or frees items. This is the
responsibility of the child class. The PtGenList class expects each
item to be represented by a PtGenListItem t structure.
When you call a PtGenList*() convenience function, you give it a
pointer to the PtGenListItem t structure as an item. When
PtGenList calls one of your methods, it provides a pointer to the
PtGenListItem t structure as an item.
Since a child class will most likely need additional data describing the
item, it will usually define its item as a structure whose first member
is PtGenListItem t. This makes conversions to and from
PtGenListItem t easy.
The child class is responsible for allocating items and adding them to
the widget. Before adding an item to the widget, the members of the
item structure should be set to the required values. After the item has
been added to the widget, the PtGenListItem t structure shouldn’t
be modified directly — convenience functions can be used instead.
The PtGenListItem t structure is defined as follows:

typedef struct Pt genlist item {

unsigned flags;
PhDim t size;
PtGenListItem t *next, *prev;

September 20, 2005 Chapter 5 ¯ Creating a List Widget 141

Overview  2005, QNX Software Systems

}
PtGenListItem t;

flags The following flags describe the state of the item:

Pt LIST ITEM SELECTED

This item is selected. Use PtGenListSelect() and
PtGenListUnselect() to modify this flag.
Pt LIST ITEM CURRENT
This item is the current item. Use
PtGenListGoto() to modify this flag.
Pt LIST ITEM DAMAGED
This item should be redrawn. Use
PtGenListDamageItem() to force a redraw.
Pt LIST ITEM ABOVE
This item is above the visible range of items.
Use the Pt ARG TOP ITEM POS resource or
PtGenListShow() 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 or
PtGenListShow() 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.

size Width and height of the item. If the child class needs
to modify the size of an item after it has been added to
the widget, it should use the PtGenListLockItem() and
PtGenListUnlockItem() convenience functions. If the
widget has columns, the widths of the items are
ignored.

142 Chapter 5 ¯ Creating a List Widget September 20, 2005

 2005, QNX Software Systems Overview

next, prev The widget uses these links to find the next and
previous items in the list. These links shouldn’t be
modified after the item has been added to the widget.
The next link is used for linking items before they’re
added to a widget (see PtGenListAddItems()).

Widget instance structure

Some members of the PtGenListWidget t structure may be used
by the child class. In general, the structure members shouldn’t be
modified directly; use the provided resources and convenience
functions instead.

☞ For information on the correspondence between structure members

and resources, see the “Resource definitions” section for PtGenList
in the chapter on Using Widget Superclasses.

gflags Flags that affect the behavior of the widget. The

child class will probably set all or most of these flags
to a fixed value; however, if a class has to modify
gflags after the widget has been created, use
PtGenListSetGflags().

Pt GEN LIST NO BACKGROUND

If set, the Draw method won’t draw the
background (under the items) or margins.
Pt GEN LIST ITEM BACKGROUND
If this flag is set but the
Pt GEN LIST NO BACKGROUND flag is clear,
the Draw method will draw the background
beneath each item and call the List Draw
method once for each item that needs to be
drawn.
Pt GEN LIST NO CLIPPING
If this flag is clear, the Draw method will set
clipping to the widget’s canvas before calling

September 20, 2005 Chapter 5 ¯ Creating a List Widget 143

Overview  2005, QNX Software Systems

the List Draw method. The clipping won’t be

set if no items are wider than the canvas.
Pt GEN LIST SHOW DAMAGED
If this flag is set, the Draw method will scan
the damage list and set the
Pt LIST ITEM DAMAGE flag in the items that
need to be drawn. The List Draw method
won’t be called at all if no items are damaged.
Pt GEN LIST FULL WIDTH
If this flag is set, the space to the right of an
item is considered part of the item — the
width stored in the item is treated as a
suggested minimum. If that space is damaged,
the item will be marked as damaged. If this
flag isn’t set, the space to the right of an item
is treated like the margin. Mouse clicks on that
space are ignored.
Pt GEN LIST NO AUTOFOCUS
If this flag is clear, giving focus to the widget
when there’s no current item in that widget
will automatically set the current item to the
first displayed item.
Pt LIST BALLOONS IN COLUMNS
If this flag is set and the widget has columns,
the widget will destroy and recreate the
balloon when the mouse pointer crosses
column boundaries.
sel xmode and sel xflags
The “decomposed” value of the current selection
mode. The value of sel xmode can be one of:
¯ Pt SELECTION MODE(
Pt SELECTION MODE NONE )
¯ Pt SELECTION MODE(
Pt SELECTION MODE SINGLE )

144 Chapter 5 ¯ Creating a List Widget September 20, 2005

 2005, QNX Software Systems Overview

¯ Pt SELECTION MODE(
Pt SELECTION MODE MULTIPLE )
¯ Pt SELECTION MODE(
Pt SELECTION MODE RANGE )

The sel xflags member contains the “flags” part of

the current selection mode:
¯ Pt SELECTION FLAGS(
Pt SELECTION MODE NOSCROLL )
¯ Pt SELECTION FLAGS(
Pt SELECTION MODE NOMOVE )
¯ Pt SELECTION FLAGS(
Pt SELECTION MODE NOREST )
¯ Pt SELECTION FLAGS(
Pt SELECTION MODE AUTO )
¯ Pt SELECTION FLAGS(
Pt SELECTION MODE NOCLEAR )
¯ Pt SELECTION FLAGS(
Pt SELECTION MODE TOGGLE )
¯ Pt SELECTION FLAGS(
Pt SELECTION MODE NOFOCUS )

current item The pointer to the current item.

cur ndx The index of the current item (the first item on the
list has an index of 1).

Methods
The methods described in this section are defined in the PtGenList
class.

September 20, 2005 Chapter 5 ¯ Creating a List Widget 145

Overview  2005, QNX Software Systems

List Draw method

The Draw method calls the List Draw method with the following
arguments:

PtGenListWidget t *widget
The widget pointer.
PtGenListItem t *items
A pointer to the first item that needs to be redrawn.
unsigned index
The index of the item to be redrawn (the first item on the list has
an index of 1).
unsigned nitems
The number of items the function should look at.
PhRect t *where
The extent of the items (the function is allowed to modify the
PhRect t structure pointed to by where).

List Mouse method

The list class’s raw callbacks invoke the Mouse List method on every
mouse event if the mouse points to an item. The function can return a
value other than Pt CONTINUE to suppress normal mouse handling.
The List Mouse method is called with the following arguments:

PtGenListWidget t *widget
The widget pointer.
PtGenListItem t *item
The item under the mouse cursor.
unsigned index
The index of that item (the first item on the list has an index of
1).

146 Chapter 5 ¯ Creating a List Widget September 20, 2005

 2005, QNX Software Systems Overview

PhRect t *where
Mouse position relative to the item (the function is allowed to
modify the PhPoint t structure pointed to by where).

PhEvent t const *event

The event.

List Key method

The list class’s raw callbacks invoke the List Key method on every
key event. This method should return one of the following values:

Pt CONTINUE
The PtGenList class will normally process the data
contained in the PhKeyEvent t structure (see the
Photon Library Reference. Note that the class’s raw
callbacks are allowed to modify the contents of that
structure.

Pt END The widget will ignore the event and the class’s raw
callbacks will return Pt CONTINUE immediately.

Pt HALT The event will be consumed by the widget, but

PtGenList itself won’t take any further action. The
class’s raw callbacks return Pt END immediately.

The List Key method is called with the following arguments:

PtGenListWidget t *widget
The widget pointer.

PhEvent t const *event

The event.
PhKeyEvent t *kevent
The event data (can be modified by the function).

September 20, 2005 Chapter 5 ¯ Creating a List Widget 147

Overview  2005, QNX Software Systems

PtGenListItem t *newcur
The new current item (if the event is processed
normally).

int index The index of that item (the first item on the list has an
index of 1).

List Select method

The list class’s raw callbacks invoke the List Select method when an
item is selected or unselected. The arguments are:

PtGenListWidget t *list
The widget pointer.

PtGenListItem t *item
In Pt SELECTION MODE RANGE selection mode,
the first selected item. In other modes, the item that
has been selected or unselected.

int index The index of that item (the first item on the list has
an index of 1).

int nitems The current number of selected items (the same as

list->sel count).

int subtype The selection subtype.

PhEvent t const *event

The event.

List Inflate method

The List Inflate method is called whenever a balloon widget needs to
be created. The List Inflate method should create a balloon and return
its widget pointer.
The List Inflate method is called with the following arguments:

148 Chapter 5 ¯ Creating a List Widget September 20, 2005

 2005, QNX Software Systems Convenience functions

PtWidget t *widget
The list widget.
PtWidget t *parent
The parent widget for the balloon.
PtGenListItem t *item
The item under the mouse pointer.

unsigned index
The index of that item (the first item on the list has
an index of 1).

int column The index of the column under the mouse pointer, or
-1 if the pointer isn’t on a column or the widget has
no columns.
PhArea t *area
The area (relative to the parent widget)
corresponding to the entire item. Use
PtGenListSetColumnBalloon() to adjust the area to
the specified column if you’re not using
PtGenListCreateTextBalloon(). These functions are
described in the Photon Widget Reference.

Convenience functions
The PtGenList class defines the following convenience functions:

PtGenListAddItems()
Add items to a list.
PtGenListAllItems()
Get pointers to all the items in a list.

PtGenListClearSelection()
Clear the selection.

September 20, 2005 Chapter 5 ¯ Creating a List Widget 149

Convenience functions  2005, QNX Software Systems

PtGenListDamageItem()
Redraw an item when its data has been changed.
PtGenListDrawBackground()
Draw the background of a list.
PtGenListDrawString()
Draw a string.

PtGenListFirstItem()
Return a pointer to the first item in a list.

PtGenListGetCurrent()
Return a pointer to the current item in a list.

PtGenListGetSelIndexes()
Get the indexes of the selected items.
PtGenListGoto()
Set the current item so that the new current item is visible.
PtGenListHold()
Prevent visible repair of a list widget.

PtGenListItemIndex()
Find the index of an item.
PtGenListItemRealloc()
Reallocate memory for an item.

PtGenListLastItem()
Return a pointer to the last item in a list.

PtGenListLockItem()
Lock an item so it can be resized.
PtGenListRelease()
Release a hold on visible repairs of a list widget.

150 Chapter 5 ¯ Creating a List Widget September 20, 2005

 2005, QNX Software Systems Convenience functions

PtGenListRemoveItems()
Remove items from a list.
PtGenListResize()
Resize a list widget.

PtGenListSelect()
Select an item in a list.
PtGenListSelectedItems()
Get pointers to the selected items.

PtGenListSetGflags()
Modify the gflags field of the widget.

PtGenListSetSelIndexes()
Set the selection indexes.
PtGenListShow()
Set the current position so a given item is visible.

PtGenListUnlockItem()
Unlock an item so it can be updated.
PtGenListUnselect()
Unselect an item in a list.
PtSuperClassGenListDraw()
Invoke the Draw List method in a superclass.

PtSuperClassGenListInflate()
Invoke the List Inflate method in a superclass.

PtSuperClassGenListKey()
Invoke the List Key method in a superclass.

PtSuperClassGenListMouse()
Invoke the List Mouse method in a superclass.

September 20, 2005 Chapter 5 ¯ Creating a List Widget 151

Convenience functions  2005, QNX Software Systems

PtSuperClassGenListSelect()
Invoke the List Select method in a superclass.

152 Chapter 5 ¯ Creating a List Widget September 20, 2005

 2005, QNX Software Systems PtGenListAddItems()
Add items to a list

Synopsis:
void PtGenListAddItems( PtWidget t *list,
PtGenListItem t *items,
PtGenListItem t *after );

Description:
This function adds items to a widget. The arguments are:

items A list linked with the next field (the prev field is ignored).

after If after is NULL, add the items at the beginning of the list.
If after isn’t NULL, it must point to an item in the widget
and items will be added after that item.

In all selection modes except Pt SELECTION MODE RANGE, if

there’s no current item in the widget and some of the added items
have the Pt LIST ITEM CURRENT flag set, the first of them will
become the current item. In all other items, the flag will be cleared.
If no item is currently selected and the mode is set to
Pt SELECTION MODE SINGLE, the first of the added items having
the Pt LIST ITEM SELECTED flag set will become the selected item.
This flag on all other items is cleared.
In Pt SELECTION MODE MULTIPLE mode and
Pt SELECTION MODE NONE mode, all items with the
Pt LIST ITEM SELECTED flag will be selected.
In Pt SELECTION MODE RANGE mode, the behavior depends on
whether there’s a selected range in the widget and how the after item
is located relative to the selected range. In particular, if you remove a
range of items and then reinsert them in the same place, the selected
range will be restored. However, the “direction” of the range may be
reversed.
If no items are selected in Pt SELECTION MODE RANGE mode but a
range of added items has the Pt LIST ITEM SELECTED flag set, these

September 20, 2005 Chapter 5 ¯ Creating a List Widget 153

PtGenListAddItems()  2005, QNX Software Systems

items will become the selected range. The current item will be either
the first or last item in this range, depending on the setting of the
Pt LIST ITEM CURRENT flag of the first selected item.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

154 Chapter 5 ¯ Creating a List Widget September 20, 2005

 2005, QNX Software Systems PtGenListAllItems()
Get pointers to all the items in a list

Synopsis:
PtGenListItem t **PtGenListAllItems(
PtWidget t *widget,
PtGenListItem t **buffer );

Description:
This function fills the given buffer with pointers to all the list items.
If buffer is NULL, the function allocates a buffer by calling malloc(),
and the buffer is NULL-terminated (or zero-terminated). It’s the
caller’s responsibility to free the buffer when it’s no longer needed.
If buffer isn’t NULL, the function doesn’t add a NULL or zero to the
end.

Returns:
A pointer to a buffer containing pointers to all the items in the list, or
NULL.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Creating a List Widget 155

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

Synopsis:
void PtGenListClearSelection( PtWidget t *widget );

Description:
This function clears the selection.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

156 Chapter 5 ¯ Creating a List Widget September 20, 2005

 2005, QNX Software Systems PtGenListDamageItem()
Redraw an item when its data has been changed

Synopsis:
void PtGenListDamageItem( PtWidget t *list,
PtGenListItem t *item );

Description:
Call this function to redraw the item when its data has been changed.
If the size changes too, use PtGenListLockItem() and
PtGenListUnlockItem() instead.

☞ If you’re modifying more than one item, you should use

PtGenListHold() and PtGenListRelease() to avoid multiple calls to the
Draw method.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Creating a List Widget 157

PtGenListDrawBackground()  2005, QNX Software Systems
Draw the background of a list

Synopsis:
void PtGenListDrawBackground(
PtWidget t *list,
PtGenListItem t const *items,
unsigned nitems,
PhRect t const *where,
int lmarg,
int rmarg );

Description:
This function can be used by a child class of PtGenList for drawing
the background. If the Pt GEN LIST SHOW DAMAGED bit is set in
list->gflags, the function draws only the background for damaged
items.
The values of the list, items, nitems, and where arguments should be
the same as those used to call the List Draw method. The lmarg and
rmarg arguments define additional “margins” — by setting them to a
positive value, you can shorten the selection bar.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

158 Chapter 5 ¯ Creating a List Widget September 20, 2005

 2005, QNX Software Systems PtGenListDrawString()
Draw a string

Synopsis:
void PtGenListDrawString( PtWidget t *list,
const char *string,
PhRect t const *where,
int lmarg,
int rmarg );

Description:
This function can be used by a child class of PtGenList for drawing
strings. The list and where arguments should be the same as those
used to call the List Draw method. The string argument is the string
to display. Any Tab characters in the string are interpreted as column
separators.
The where argument defines the rectangle in which the text will be
positioned. The x values for the rectangle should be the same as those
used in the where argument of the List Draw method. The y values
define the vertical position of the string to be drawn between the given
values.
The lmarg and rmarg arguments define additional margins. The value
of lmarg is added to the from value of the first column, and rmarg is
subtracted from the to value of the last column. If the widget doesn’t
have columns, the width of the widget’s canvas is used as a column.

Examples:
Here’s an excerpt showing the List Draw method of a widget (taken
from PtList):

static PtGenListDrawF t list draw;

static void list draw(

PtGenListWidget t *const glist, PtGenListItem t *items,
unsigned index, unsigned nitems, PhRect t *where
) {
PtBasicWidget t *const basic = (PtBasicWidget t*) glist;
PtGenListDrawBackground( glist, items, nitems, where,
0, 0 );
do {

September 20, 2005 Chapter 5 ¯ Creating a List Widget 159

PtGenListDrawString()  2005, QNX Software Systems

short bot;
bot = where->ul.y + items->size.h;
if ( items->flags & Pt LIST ITEM DAMAGED ) {
where->lr.y = bot - 1;
PgSetTextColor(
items->flags & Pt LIST ITEM SELECTED
? glist->selection text color
: basic->color
);
PtGenListDrawString( glist, STRING(items), where,
0, 0 );
}
where->ul.y = bot;
items = items->next;
} while ( --nitems );
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

160 Chapter 5 ¯ Creating a List Widget September 20, 2005

 2005, QNX Software Systems PtGenListFirstItem()
Return a pointer to the first item in a list

Synopsis:
PtGenListItem t *PtGenListFirstItem(
PtWidget t const *list );

Description:
This function returns a pointer to the first item in the list.

Returns:
A pointer to the first item.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Creating a List Widget 161

PtGenListGetCurrent()  2005, QNX Software Systems
Return a pointer to the current item in a list

Synopsis:
PtGenListItem t *PtGenListGetCurrent(
PtWidget t const *widget );

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

Returns:
A pointer to the current item.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

162 Chapter 5 ¯ Creating a List Widget September 20, 2005

 2005, QNX Software Systems PtGenListGetSelIndexes()
Get the indexes of the selected items

Synopsis:
unsigned short *PtGenListGetSelIndexes(
PtWidget t *widget,
unsigned short *buffer );

Description:
This function fills the given buffer with the indexes of the currently
selected items. The first item in the widget has an index of 1, not 0.
If buffer is NULL, the function will allocate a buffer using malloc(),
and the buffer will be NULL-terminated (or zero-terminated). It’s the
caller’s responsibility to free the buffer when it’s no longer needed.
If buffer isn’t NULL, the function adds a NULL to the end only if there
are no selected items.

Returns:
A pointer to the buffer.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Creating a List Widget 163

PtGenListGoto()  2005, QNX Software Systems
Set the current item so that the new current item is visible

Synopsis:
void PtGenListGoto( PtWidget t *list,
PtGenListItem 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 won’t be a current item.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

164 Chapter 5 ¯ Creating a List Widget September 20, 2005

 2005, QNX Software Systems PtGenListHold()
Prevent visible repair of a list widget

Synopsis:
void PtGenListHold( PtWidget t *widget );

Description:
This function is a list-aware version of the PtHold() function. After a
call to PtGenListHold(), the PtGenListDamageItem() function simply
sets the Pt LIST ITEM DAMAGED flag in the item instead of calling
PtDamageExtent().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtGenListRelease()

September 20, 2005 Chapter 5 ¯ Creating a List Widget 165

PtGenListItemIndex()  2005, QNX Software Systems
Find the index of an item

Synopsis:
int PtGenListItemIndex(
PtWidget t const *list,
PtGenListItem t const *item );

Description:
This function calculates the index of the given item within the list.
The index of the first item is 1.

Returns:
The index of the given item.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

166 Chapter 5 ¯ Creating a List Widget September 20, 2005

 2005, QNX Software Systems PtGenListItemRealloc()
Reallocate memory for an item

Synopsis:
PtGenListItem t *PtGenListItemRealloc(
PtGenListItem t *item,
PtWidget t *list,
size t size );

Description:
This function isn’t used by the PtGenList widget itself. It may be
used to reallocate memory if the item was allocated using malloc().
The given size should include the size of the PtGenListItem t
structure. If the item is moved to a different address by the realloc()
function, PtGenListItemRealloc() will repair the list links.

Returns:
A pointer to the reallocated item.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Creating a List Widget 167

PtGenListLastItem()  2005, QNX Software Systems
Return a pointer to the last item in a list

Synopsis:
PtGenListItem t *PtGenListLastItem(
PtWidget t const *list );

Description:
This function returns a pointer to the last item in the list.

Returns:
A pointer to the last item.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

168 Chapter 5 ¯ Creating a List Widget September 20, 2005

 2005, QNX Software Systems PtGenListLockItem()
Lock an item so it can be resized

Synopsis:
void PtGenListLockItem( PtWidget t *list,
PtGenListItem t *item );

Description:
Use this function if the size field of a list item must be changed. A call
to PtGenListLockItem() is needed first to save the old size of the item
before the item can be modified. The PtGenListUnlockItem() function
should be called last to update and resize or redisplay the widget if
necessary.

☞ Only one item per widget can be locked at a time. If you resize a large
number of items, set all sizes and then call PtGenListResize().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Creating a List Widget 169

PtGenListRelease()  2005, QNX Software Systems
Release a hold on visible repairs of a list widget

Synopsis:
void PtGenListRelease( PtWidget t *widget );

Description:
This function is a list-aware version of PtRelease().
After a call to PtGenListHold(), PtGenListDamageItem() simply sets
the Pt LIST ITEM DAMAGED flag in the item instead of calling
PtDamageExtent().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtGenListHold()

170 Chapter 5 ¯ Creating a List Widget September 20, 2005

 2005, QNX Software Systems PtGenListRemoveItems()
Remove items from a list

Synopsis:
PtGenListItem t *PtGenListRemoveItems(
PtWidget t *list,
PtGenListItem t *first,
PtGenListItem t *last );

Description:
This function removes the given sublist list from the PtGenList
widget. If first or last is a NULL pointer, the first or last items of the
entire list will be used. Both arguments may point to the same item,
but last must not precede first in the list.
The function returns the first removed item (or NULL if the list was
empty). The function inserts NULL in the next field of the last
removed item and the prev field of the first removed item. This
ensures the returned value (if not NULL) will always point to the first
item of a NULL-terminated, double-linked list. No other fields in any
of the removed items are modified.
If the current item is removed, there won’t be a current item on the list
unless the selection mode is Pt SELECTION MODE RANGE and only
part of the selected range is removed. In this case, the current item is
set to the first or last of the remaining selected items.

Returns:
The first removed item; NULL if the list was empty.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
continued. . .

September 20, 2005 Chapter 5 ¯ Creating a List Widget 171

PtGenListRemoveItems()  2005, QNX Software Systems

Safety
Thread No

172 Chapter 5 ¯ Creating a List Widget September 20, 2005

 2005, QNX Software Systems PtGenListResize()
Resize a list widget

Synopsis:
void PtGenListResize( PtWidget t *widget );

Description:
This function resizes the given list widget.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtGenListLockItem(), PtGenListUnlockItem()

September 20, 2005 Chapter 5 ¯ Creating a List Widget 173

PtGenListSelect()  2005, QNX Software Systems
Select an item in a list

Synopsis:
void PtGenListSelect( PtWidget t *widget,
PtGenListItem t *item );

Description:
This function selects the given item in the list.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

174 Chapter 5 ¯ Creating a List Widget September 20, 2005

 2005, QNX Software Systems PtGenListSelectedItems()
Get pointers to the selected items

Synopsis:
PtGenListItem t **PtGenListSelectedItems(
PtWidget t *widget,
PtGenListItem t **buffer );

Description:
This function fills the given buffer with pointers to the currently
selected items.
If buffer is NULL, the function will allocate a buffer using malloc(),
and the buffer will be NULL-terminated (or zero-terminated). It’s the
caller’s responsibility to free the buffer when it’s no longer needed.
If buffer isn’t NULL, the function adds a NULL to the end only if there
are no selected items.

Returns:
A pointer to the buffer.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Creating a List Widget 175

PtGenListSetGflags()  2005, QNX Software Systems
Modify the gflags field of the widget

Synopsis:
unsigned PtGenListSetGflags( PtWidget t *widget,
unsigned value,
unsigned mask );

Description:
This function modifies the gflags field of the widget. The bits defined
by mask will be set to the value defined by value.

Returns:
The old value of gflags.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

176 Chapter 5 ¯ Creating a List Widget September 20, 2005

 2005, QNX Software Systems PtGenListSetSelIndexes()
Set the selection indexes

Synopsis:
int PtGenListSetSelIndexes(
PtWidget t *widget,
const unsigned short *buffer
int count );

Description:
This function lets you set the selection indexes. It assumes that buffer
points to a sorted array of indexes. The first item in the widget has an
index of 1, not 0.
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 or out-of-range indexes.

☞ In Pt SELECTION MODE RANGE mode, only the first index and

count are used.

Returns:
The number of items actually selected.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Creating a List Widget 177

PtGenListShow()  2005, QNX Software Systems
Set the current position so a given item is visible

Synopsis:
void PtGenListShow( PtWidget t *list,
PtGenListItem t *item );

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

PtGenListShow( list, item->next );

without having to make sure item->next isn’t NULL.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

178 Chapter 5 ¯ Creating a List Widget September 20, 2005

 2005, QNX Software Systems PtGenListUnlockItem()
Unlock an item so it can be updated

Synopsis:
void PtGenListUnlockItem( PtWidget t *list,
PtGenListItem t *item );

Description:
Use this function if the size field of a list item must be changed. A call
to PtGenListLockItem() is needed first to save the old size of the item
before the item can be modified. The PtGenListUnlockItem() function
should be called last to update and resize or redisplay the widget if
necessary.

☞ Only one item per widget can be locked at a time. If you resize a large
number of items, set all sizes and then call PtGenListResize().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Creating a List Widget 179

PtGenListUnselect()  2005, QNX Software Systems
Unselect an item in a list

Synopsis:
void PtGenListUnselect( PtWidget t *widget,
PtGenListItem t *item );

Description:
This function unselects the given item. PtGenListUnselect() has no
effect in the Pt SELECTION MODE RANGE selection mode.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

180 Chapter 5 ¯ Creating a List Widget September 20, 2005

 2005, QNX Software Systems PtSuperClassGenListDraw()
Invoke the List Draw method in a superclass

Synopsis:
void PtSuperClassGenListDraw(
PtWidgetClassRef t *cref ,
PtWidget t *widget,
PtGenListItem t *item,
unsigned index,
unsigned nitems,
PhRect t *where );

Description:
This function can be used to invoke the List Draw method of the class
defined by cref .

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Creating a List Widget 181

PtSuperClassGenListInflate()  2005, QNX Software Systems
Invoke the List Inflate method in a superclass

Synopsis:
PtWidget t *PtSuperClassGenListInflate(
PtWidgetClassRef t *cref ,
PtWidget t *wgt,
PtWidget t *parent,
PtGenListItem t *item,
unsigned index,
int column,
PhArea t *area );

Description:
This function can be used to invoke the List Inflate method of the
class defined by cref .

Returns:
A widget pointer to the balloon instance created by this function.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

182 Chapter 5 ¯ Creating a List Widget September 20, 2005

 2005, QNX Software Systems PtSuperClassGenListKey()
Invoke the List Key method in a superclass

Synopsis:
int PtSuperClassGenListKey(
PtWidgetClassRef t *cref ,
PtWidget t *wgt,
PhEvent t *ev,
PhKeyEvent t *kev,
PtGenListItem t *newcur,
unsigned newpos );

Description:
This function can be used to invoke the List Key method of the class
defined by cref .

Returns:
A nonzero value if the key event was consumed, 0 otherwise.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Creating a List Widget 183

PtSuperClassGenListMouse()  2005, QNX Software Systems
Invoke the List Mouse method in a superclass

Synopsis:
int PtSuperClassGenListMouse(
PtWidgetClassRef t *cref ,
PtWidget t *wgt,
PtGenListItem t *item,
unsigned index,
PhPoint t *where,
PhEvent t *ev );

Description:
This function can be used to invoke the List Mouse method of the
class defined by cref .

Returns:
A nonzero value if the event was consumed, 0 otherwise.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

184 Chapter 5 ¯ Creating a List Widget September 20, 2005

 2005, QNX Software Systems PtSuperClassGenListSelect()
Invoke the List Select method in a superclass

Synopsis:
void PtSuperClassGenListSelect(
PtWidgetClassRef t *cref ,
PtWidget t *wgt,
PtGenListItem t *item,
int pos,
int nitems,
int subtype,
PhEvent t *ev );

Description:
This function can be used to invoke the List Select method of the class
defined by cref .

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Creating a List Widget 185

 Chapter 6
Creating a Tree Widget

In this chapter. . .
Overview 189
Convenience functions 192
PtGenTreeAddAfter() 195
PtGenTreeAddFirst() 196
PtGenTreeAllItems() 197
PtGenTreeClearSelection() 198
PtGenTreeCollapse() 199
PtGenTreeDamageItem() 200
PtGenTreeExpand() 201
PtGenTreeExpandParents() 202
PtGenTreeFreeAllItems() 203
PtGenTreeFreeItems() 204
PtGenTreeGetCurrent() 205
PtGenTreeGetSelIndexes() 206
PtGenTreeGoto() 207
PtGenTreeItemIndex() 208
PtGenTreeItemRealloc() 209
PtGenTreeItemResize() 210
PtGenTreeRemoveChildren() 211
PtGenTreeRemoveItem() 212
PtGenTreeRemoveList() 213
PtGenTreeResize() 214
PtGenTreeRootItem() 215
PtGenTreeSelect() 216
PtGenTreeSelectedItems() 217
PtGenTreeSetSelIndexes() 218
PtGenTreeShow() 219
PtGenTreeUnselect() 220
PtGenTreeUnselectNonBrothers() 221

September 20, 2005 Chapter 6 ¯ Creating a Tree Widget 187

  2005, QNX Software Systems

PtSuperClassGenTreeDrawItem() 222
PtSuperClassGenTreeItemState() 223

188 Chapter 6 ¯ Creating a Tree Widget September 20, 2005

 2005, QNX Software Systems Overview

Overview
The PtGenTree class is a subclass of PtGenList. You can use a
PtGenTree widget to display a hierarchy of items as lists in a tree.
When an item in the hierarchy has an item or list of items below it,
that item can be expanded. An expanded item drops a list to reveal all
items in the next level below. An expanded item can be collapsed.
When an expandable item is collapsed, the list rolls up and its items
are concealed. An item can be marked as expandable even if it doesn’t
have a list of items below it — you can add the list of items just
before the expandable item is expanded.
Any PtGenTree widget can contain multiple items at the root level,
which contains the first level of items to display. Root-level items
have no other items/levels above them — they represent the top of the
hierarchy.
A child class of PtGenTree isn’t supposed to define a List Draw
method. Instead, it should define a Tree Draw Item method that will
be called by the List Draw method of PtGenTree.

☞ PtGenTree’s Draw List method assumes that the

Pt GEN LIST SHOW DAMAGED flag is set. The child class should
never clear this flag.

The PtGenTree class doesn’t use recursive functions. The amount of

stack needed by any PtGenTree*() function doesn’t depend on the
tree’s size or depth.

Item structure
The item structure used by PtGenTree is defined as follows:
typedef struct Pt gentree item {
PtGenListItem t list;
struct Pt gentree item *father, *son, *brother;
PhDim t dim;
}
PtGenTreeItem t;

September 20, 2005 Chapter 6 ¯ Creating a Tree Widget 189

Overview  2005, QNX Software Systems

list The item structure used by the PtGenList superclass. The

PtGenTree class defines some new flags that can be set in
item->list.flags:

Pt TREE ITEM EXPANDABLE

Set this flag to mark an item as expandable. When you
add a branch to an item, PtGenTreeAddFirst() sets this
flag in the parent item automatically.
Pt TREE ITEM EXPANDED
The branches of this item are currently on display.

father, son, brother

Tree links. You can use them to traverse the tree structure, but
don’t modify them directly — it’s safer to 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.

Methods
Tree Draw Item method
The List Draw method calls the Tree Draw Item method with the
following arguments:

PtGenTreeWidget t *widget
The widget pointer.

190 Chapter 6 ¯ Creating a Tree Widget September 20, 2005

 2005, QNX Software Systems Overview

PtGenTreeItem t *item
A pointer to the item that needs to be redrawn.
PhRect t const *where
The extent of the item.

int lmargin If positive, an additional left margin that should be

added to the first column.

int rmargin If positive, an additional right margin that should be

added to the last column.

The PtGenTree List Draw method is responsible for drawing the

lines and boxes representing the tree structure. The Tree Draw Item
method should draw only the item. For example, the Tree Draw Item
method of PtTree draws only the image and the string.

Tree Item State method

PtGenTreeExpand() and PtGenTreeCollapse() call the Tree Item State
method with the following arguments:

PtGenTreeWidget t *widget
The widget pointer.

PtGenTreeItem t *item
A pointer to the item that is being collapsed or
expanded.

PhEvent t *event
The event argument to PtGenTreeExpand() or
PtGenTreeCollapse().

int reason Either Pt TREE EXPANDING or

Pt TREE COLLAPSING.

If reason is Pt TREE EXPANDING, the item is about to be expanded.

The Tree Item State method can update the item’s branches before the

September 20, 2005 Chapter 6 ¯ Creating a Tree Widget 191

Convenience functions  2005, QNX Software Systems

actual expansion. After the function returns, the widget will display a
list of items in the expanded branch.
If an item in the list has its Pt TREE ITEM EXPANDED flag set, the
items below will be displayed too. The Tree Item State method can
return a value other than Pt CONTINUE to prevent expansion —
PtGenTreeExpand() returns this value.
If reason is Pt TREE COLLAPSING, the item has been collapsed. Its
branches are concealed and the Tree Item State method can free the
associated items.

Convenience functions
The PtGenTree class defines the following convenience functions:

PtGenTreeAddAfter()
Add items after a given item.
PtGenTreeAddFirst()
Add items in front of any existing items.
PtGenTreeAllItems()
Get pointers to all the items in the tree.
PtGenTreeClearSelection()
Clear the selection.
PtGenTreeCollapse()
Collapse a subtree.
PtGenTreeDamageItem()
Redraw an item when its data has changed.
PtGenTreeExpand()
Expand a given subtree.
PtGenTreeExpandParents()
Expand any collapsed ancestors of a given item.

192 Chapter 6 ¯ Creating a Tree Widget September 20, 2005

 2005, QNX Software Systems Convenience functions

PtGenTreeFreeAllItems()
Free all the items in a tree.
PtGenTreeFreeItems()
Free the items in a subtree.
PtGenTreeGetCurrent()
Get a pointer to the current item.

PtGenTreeGetSelIndexes()
Get the indexes of the selected items.
PtGenTreeGoto()
Set the current item and position so that a given item is visible.

PtGenTreeItemIndex()
Calculate the index of a given item.
PtGenTreeItemRealloc()
Reallocate an item.
PtGenTreeItemResize()
Resize an item.
PtGenTreeRemoveChildren()
Unlink all the children of a given item.

PtGenTreeRemoveItem()
Remove a given item and its children from its parents and
siblings.

PtGenTreeRemoveList()
Remove a given items and its siblings from their parent.

PtGenTreeResize()
Resize many items.

PtGenTreeRootItem()
Get a pointer to the first root item.

September 20, 2005 Chapter 6 ¯ Creating a Tree Widget 193

Convenience functions  2005, QNX Software Systems

PtGenTreeSelect()
Select a given item.
PtGenTreeSelectedItems()
Get pointers to the selected items.
PtGenTreeSetSelIndexes()
Set the selection indexes.
PtGenTreeShow()
Set the current position so that a given item is visible.

PtGenTreeUnselect()
Unselect a given item.

PtGenTreeUnselectNonBrothers()
Unselect all items that aren’t siblings of a given item.

PtSuperClassGenTreeDrawItem()
Invoke the Tree Draw Item method of a given superclass.

PtSuperClassGenTreeItemState()
Invoke the Tree Item State method of a superclass.

194 Chapter 6 ¯ Creating a Tree Widget September 20, 2005

 2005, QNX Software Systems PtGenTreeAddAfter()
Add items after a given item

Synopsis:
void PtGenTreeAddAfter( PtWidget t *tree,
PtGenTreeItem t *items,
PtGenTreeItem t *brother );

Description:
This function inserts a list of trees linked with the brother field.
PtGenTreeAddAfter() assumes that items points to a list of trees. The
tree variable points to a PtGenTree widget. The new items are added
to the specified tree below the specified brother.
This function may be called with a NULL tree argument, as long as
brother points to an item that isn’t attached to any tree widget.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Creating a Tree Widget 195

PtGenTreeAddFirst()  2005, QNX Software Systems
Add items in front of any existing items

Synopsis:
void PtGenTreeAddFirst( PtWidget t *tree,
PtGenTreeItem t *item,
PtGenTreeItem t *parent );

Description:
This function adds a list of trees 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 item is 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.
PtGenTreeAddFirst() automatically sets the
Pt TREE ITEM EXPANDABLE flag in the parent item.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

196 Chapter 6 ¯ Creating a Tree Widget September 20, 2005

 2005, QNX Software Systems PtGenTreeAllItems()
Get pointers to all the items in the tree

Synopsis:
PtGenTreeItem t **PtGenTreeAllItems(
PtWidget t *widget,
PtGenTreeItem t **buffer );

Description:
This function fills a buffer with pointers to all items in the widget. If
buffer is NULL, the function allocates a buffer using malloc() and the
buffer is NULL-terminated. If buffer isn’t NULL, the function doesn’t
add a NULL at the end.

Returns:
A pointer to the buffer.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Creating a Tree Widget 197

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

Synopsis:
void PtGenTreeClearSelection( PtWidget t *widget );

Description:
This function clears the selection.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

198 Chapter 6 ¯ Creating a Tree Widget September 20, 2005

 2005, QNX Software Systems PtGenTreeCollapse()
Collapse a subtree

Synopsis:
void PtGenTreeCollapse( PtWidget t *tree,
PtGenTreeItem 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 isn’t NULL, the Tree Item State method of that widget is called.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Creating a Tree Widget 199

PtGenTreeDamageItem()  2005, QNX Software Systems
Redraw an item when its data has changed

Synopsis:
void PtGenTreeDamageItem( PtWidget t *tree,
PtGenTreeItem t *item );

Description:
Call this function to redraw the given item when its data has changed.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

200 Chapter 6 ¯ Creating a Tree Widget September 20, 2005

 2005, QNX Software Systems PtGenTreeExpand()
Expand a given subtree

Synopsis:
int PtGenTreeExpand( PtWidget t *tree,
PtGenTreeItem 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 Tree Item State method of that widget is called.
If it returns a value other than Pt CONTINUE, the item isn’t expanded
and PtGenTreeExpand() returns the same value.

Returns:
The value returned by the Tree Item State method.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Creating a Tree Widget 201

PtGenTreeExpandParents()  2005, QNX Software Systems
Expand any collapsed ancestors of a given item

Synopsis:
int PtGenTreeExpandParents( PtWidget t *tree,
PtGenTreeItem t *item,
PhEvent t *event );

Description:
If any ancestors of the given item are collapsed, this function attempts
to expand them.

Returns:
The value returned by the Tree Item State method.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

202 Chapter 6 ¯ Creating a Tree Widget September 20, 2005

 2005, QNX Software Systems PtGenTreeFreeAllItems()
Free all the items in a tree

Synopsis:
void PtGenTreeFreeAllItems( PtWidget t *tree );

Description:
This function unlinks and frees all items in the tree widget.

☞ This function isn’t called automatically when the PtGenTree widget

is being deleted, because the widget doesn’t assume that its items
have been allocated.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Creating a Tree Widget 203

PtGenTreeFreeItems()  2005, QNX Software Systems
Free the items in a subtree

Synopsis:
void PtGenTreeFreeItems( PtGenTreeItem t *item );

Description:
This function frees the subtree item, together with its siblings and
their children. The function assumes that the items don’t belong to
any tree. (Use PtGenTreeRemoveItem(), PtGenTreeRemoveList(), or
PtGenTreeRemoveChildren() to remove the subtree before freeing it.)

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

204 Chapter 6 ¯ Creating a Tree Widget September 20, 2005

 2005, QNX Software Systems PtGenTreeGetCurrent()
Get a pointer to the current item

Synopsis:
PtGenTreeItem t *PtGenTreeGetCurrent(
const PtWidget t *widget );

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

Returns:
A pointer to the current item.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Creating a Tree Widget 205

PtGenTreeGetSelIndexes()  2005, QNX Software Systems
Get the indexes of the selected items

Synopsis:
unsigned short *PtGenTreeGetSelIndexes(
PtWidget t *widget,
unsigned short *buffer );

Description:
This function fills a buffer with indexes of all the selected items in the
widget. The first item in the widget has an index of 1, not 0.
If buffer is NULL, the function will allocate a buffer using malloc(),
and the buffer will be zero-terminated.
If buffer isn’t NULL, the function adds a NULL to the end only if there
are no selected items.

Returns:
A pointer to the buffer containing the indexes.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

206 Chapter 6 ¯ Creating a Tree Widget September 20, 2005

 2005, QNX Software Systems PtGenTreeGoto()
Set the current item and position so that a given item is visible

Synopsis:
int PtGenTreeGoto( PtWidget t *tree,
PtGenTreeItem 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.
PtGenTreeGoto() can be called with an item whose ancestor is
collapsed, in which case the ancestor is expanded.

Returns:
The value returned by the Tree Item State method.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Creating a Tree Widget 207

PtGenTreeItemIndex()  2005, QNX Software Systems
Calculate the index of a given item

Synopsis:
int PtGenTreeItemIndex(
const PtWidget t *tree,
const PtGenTreeTtem t *item );

Description:
This function calculates the index of the given item within the tree.
The index of the first item is 1.

Returns:
The index of the item.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

208 Chapter 6 ¯ Creating a Tree Widget September 20, 2005

 2005, QNX Software Systems PtGenTreeItemRealloc()
Reallocate an item

Synopsis:
PtGenTreeItem t *PtGenTreeItemRealloc(
PtGenTreeItem t *item,
PtWidget t *tree,
size t newsize );

Description:
This function should be used to reallocate an item. It will repair any
links damaged if the realloc() function moves the item to a different
address. The tree argument must point to the tree that contains the
item or be NULL if the item doesn’t belong to any tree.

Returns:
A pointer to the reallocated item.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Creating a Tree Widget 209

PtGenTreeItemResize()  2005, QNX Software Systems
Resize an item

Synopsis:
void PtGenTreeItemResize( PtGenTreeItem t *item,
PtWidget t *tree );

Description:
This function is used to resize one item. It should be called after the
dimensions of an item (item->dim) have been changed. You don’t
need to call this function if item doesn’t belong to any tree or if a
subtree containing the item is collapsed.

☞ If you’re resizing many items, use PtGenTreeResize() instead.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

210 Chapter 6 ¯ Creating a Tree Widget September 20, 2005

 2005, QNX Software Systems PtGenTreeRemoveChildren()
Unlink all the children of a given item

Synopsis:
PtGenTreeItem t *PtGenTreeRemoveChildren(
PtGenTreeItem t *item );

Description:
This function unlinks all the children of the given item and returns the
pointer to the first of them. You can then give the pointer to
PtGenTreeFreeItems().
This function doesn’t collapse the item. If the children are visible,
NULL is returned. Call PtGenTreeCollapse() before
PtGenTreeRemoveItem() to make sure the item is collapsed.

Returns:
A pointer to the first unlinked child.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Creating a Tree Widget 211

PtGenTreeRemoveItem()  2005, QNX Software Systems
Remove a given item and its children from its parents and siblings

Synopsis:
void PtGenTreeRemoveItem( PtWidget t *tree,
PtGenTreeItem t *item );

Description:
This function unlinks the given item (together with its children) from
its parent and brothers (if any) and sets item->parent and
item->brother to NULL. The tree argument must point to the
PtGenTree widget containing item or be NULL if item doesn’t
belong to any tree.
If tree is NULL and item has no parent but has a previous sibling, then
PtGenTreeRemoveItem() isn’t able to find the previous sibling and
unlinks item from its sibling. The function does nothing if
item->parent and tree are NULL.
PtGenTreeRemoveItem() never clears the
Pt TREE ITEM EXPANDABLE flag in the item’s parent.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

212 Chapter 6 ¯ Creating a Tree Widget September 20, 2005

 2005, QNX Software Systems PtGenTreeRemoveList()
Remove a given items and its siblings from their parent

Synopsis:
void PtGenTreeRemoveList( PtWidget t *tree,
PtGenTreeItem t *first );

Description:
This function unlinks the item first and its siblings (together with their
children) from their parent (and previous sibling) and sets their parent
fields to NULL. The tree argument must point to the widget that
contains the items or be NULL if the items don’t belong to any tree.
If tree is NULL and first has no parent but has a previous sibling,
PtGenTreeRemoveList() can’t find the previous sibling and can’t
unlink first from its previous sibling.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Creating a Tree Widget 213

PtGenTreeResize()  2005, QNX Software Systems
Resize many items

Synopsis:
void PtGenTreeResize( PtWidget t *widget );

Description:
This function is used to resize many items. You should call it after the
size field of a number of tree items has changed — modify item->dim
directly in all items, then call PtGenTreeResize() once.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

214 Chapter 6 ¯ Creating a Tree Widget September 20, 2005

 2005, QNX Software Systems PtGenTreeRootItem()
Get a pointer to the first root item

Synopsis:
PtGenTreeItem t *PtGenTreeRootItem(
PtWidget t const *tree );

Description:
This function returns a pointer to the first root item of the tree.

Returns:
A pointer to the first root item.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Creating a Tree Widget 215

PtGenTreeSelect()  2005, QNX Software Systems
Select a given item

Synopsis:
void PtGenTreeSelect( PtWidget t *widget,
PtGenTreeItem t *item );

Description:
This function selects the given item. As with other PtGenTree*()
functions, the tree argument should be set to NULL if item doesn’t
belong to a widget.
If tree isn’t NULL and none of item’s ancestors is collapsed,
PtGenListSelect() is called. If tree is NULL or some of the ancestors
of the item are collapsed, PtGenTreeSelect() simply sets the
Pt LIST ITEM SELECTED flag in the item.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

216 Chapter 6 ¯ Creating a Tree Widget September 20, 2005

 2005, QNX Software Systems PtGenTreeSelectedItems()
Get pointers to the selected items

Synopsis:
PtGenTreeItem t **PtGenTreeSelectedItems(
PtWidget t *widget,
PtGenTreeItem t **buffer );

Description:
This function fills a buffer with pointers to the currently selected
items. If buffer is NULL, the function allocates a buffer using
malloc(), and the buffer is NULL-terminated.
If buffer isn’t NULL, the function adds a NULL to the end only if there
are no selected items.

Returns:
A pointer to the buffer.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Creating a Tree Widget 217

PtGenTreeSetSelIndexes()  2005, QNX Software Systems
Set the selection indexes

Synopsis:
int PtGenTreeSetSelIndexes(
PtWidget t *widget,
unsigned short const *buffer,
int count );

Description:
This function sets the selection indexes. It assumes that buffer points
to a sorted array of indexes. The first item in the widget has an index
of 1, not 0.
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 or out-of-range indexes.
When the selection mode is Pt SELECTION MODE RANGE, only the
first index and the count are used.

Returns:
The number of items actually selected.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

218 Chapter 6 ¯ Creating a Tree Widget September 20, 2005

 2005, QNX Software Systems PtGenTreeShow()
Set the current position so that a given item is visible

Synopsis:
int PtGenTreeShow( PtWidget t *widget,
PtGenTreeItem 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:

PtGenTreeShow( widget, PtGenTreeGetCurrent(widget) );

without checking whether PtGenTreeGetCurrent() returned a NULL

value.
PtGenTreeShow() can be called with an item whose ancestor is
collapsed, in which case the ancestor will be expanded.

Returns:
The value returned by the Tree Item State method.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Creating a Tree Widget 219

PtGenTreeUnselect()  2005, QNX Software Systems
Unselect a given item

Synopsis:
void PtGenTreeUnselect( PtWidget t *widget,
PtGenTreeItem t *item );

Description:
This function unselects the given item.

☞ PtGenTreeUnselect() doesn’t support Pt SELECTION MODE RANGE

selection mode.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

220 Chapter 6 ¯ Creating a Tree Widget September 20, 2005

 2005, QNX Software Systems PtGenTreeUnselectNonBrothers()
Deselect all items that aren’t siblings of a given item

Synopsis:
void PtGenTreeUnselectNonBrothers(
PtWidget t *wgt,
PtGenTreeItem t *item );

Description:
This function deselects 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

September 20, 2005 Chapter 6 ¯ Creating a Tree Widget 221

PtSuperClassGenTreeDrawItem()  2005, QNX Software Systems
Invoke the Tree Draw Item method of a given superclass

Synopsis:
void PtSuperClassGenTreeDrawItem(
PtWidgetClassRef t *cref ,
PtWidget t *wgt,
PtGenTreeItem t *item,
PhRect t const *where,
int lmargin,
int rmargin );

Description:
This function invokes the Tree Draw Item method of the class defined
by cref .

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

222 Chapter 6 ¯ Creating a Tree Widget September 20, 2005

 2005, QNX Software Systems PtSuperClassGenTreeItemState()
Invoke the Tree Item State method of a superclass

Synopsis:
int PtSuperClassGenTreeItemState(
PtWidgetClassRef t *cref ,
PtWidget t *wgt,
PtGenTreeItem t *item,
PhEvent t *event,
int reason );

Description:
This function invokes the Tree Item State method of the class defined
by cref .

Returns:
The value returned by the specified Tree Item State method.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Creating a Tree Widget 223

 Chapter 7
Binding Widgets into PhAB

In this chapter. . .
Widget design considerations 227
Creating an icon for the PhAB widget bar 228
Creating a widget description table 230
Adding the widget palette file to PhAB 241

September 20, 2005 Chapter 7 ¯ Binding Widgets into PhAB 225

 2005, QNX Software Systems Widget design considerations

This chapter discusses adding custom widgets to PhAB, including

widget design considerations as well as the steps to follow for:

¯ Creating an icon for the PhAB widget bar

¯ Creating a widget description table

¯ Adding the widget palette file to PhAB

☞ Since PhAB hasn’t been linked to include your custom widget, PhAB
won’t be able to display it. Instead, PhAB will display a default
widget (PtBasic or PtContainer) in its place for visual feedback
and dimensions.
The Control Panel will let you access all the resources and callbacks
you defined in the widget description table for your custom widget,
but they won’t take effect until you actually run the application.

Widget design considerations

This section describes the issues you need to consider when you add
custom widgets to the PhAB widget bar:

¯ Single-value resources

¯ When to add custom widgets to palette files

¯ Displaying your custom widget

Single-value resources
PhAB has builtin editors for handling certain types of single-value
resources. It also provides multiple-value editors for some resource
types. If you design your resources to use the types supported by
PhAB, developers will be able to use the widget in PhAB easily. If
you define resources that have no associated editor in PhAB,
developers will be able to set and use these resources only through
application code. The list of currently supported types can be found in
the section on “Creating a widget description table.”

September 20, 2005 Chapter 7 ¯ Binding Widgets into PhAB 227

Creating an icon for the PhAB widget bar  2005, QNX Software Systems

When to add custom widgets to palette files

When you define a widget class, you assign it a widget number. This
number is combined with the resource number to create a series of
unique resource numbers for the widget. When you add the widget to
the PhAB widget palette, you define these resource values in the
widget palette file.
PhAB uses these numbers when it stores the widget in the module
files. If you change the resource number or widget number after it has
been used in a PhAB application, you won’t be able to continue using
the old widget (defined in the PhAB module) because the resource
numbers will no longer match. For this reason, you should add
widgets to the PhAB palette file only when almost all the widget’s
functionality has been completed and the resource numbers will no
longer change.

Displaying your custom widget

Since PhAB doesn’t link your widget directly into its executable, you
won’t be able to see the widget change visually when you make
changes to the resources. The widget will display properly when you
actually compile, link, and test the application.
Remember to include the widget header file in the application header
so that the generated abmain.c file will know about your widget.
Also, add your widget to the MYOBJ object list in the Makefile.

☞ If you’re using Watcom 10.6 or later, the MYOBJ object list will be
defined in the indOfiles file.

Creating an icon for the PhAB widget bar

Widget icons are stored in picture modules. A picture module can
contain any number of widgets icons. You can create icons in PhAB
by creating an application with a single picture module (see
“Importing a picture module” below).

228 Chapter 7 ¯ Binding Widgets into PhAB September 20, 2005

 2005, QNX Software Systems Creating an icon for the PhAB widget bar

In the picture module, create a PtBitmap widget for each custom

widget you build. To ensure that your icons fit in the widget bar, make
each of these PtBitmap widgets 20 pixels high and 28 pixels wide.
Using the pixmap editor, draw a picture that represents the type of
custom widget you built.
Give the PtBitmap widget an instance name. The instance name
must be formatted as follows:
classname wgt
For example, you could call a PtSlider widget PtSlider wgt.

Importing a picture module

A good way to create a new picture module is to import one of
PhAB’s existing palette picture modules. To do this:
1 Create a new PhAB application.
2 Choose the Import/PhAB module option.
3 Change to the /qnx4/phtk/appbuilder directory and load
the ptpalette.wgtp file.
This will show you an example layout that works well in the
PhAB widget selector. This picture module has a lot more
widgets than just the PtBitmap widgets; when PhAB loads the
picture module as a database, any widget that isn’t a PtBitmap
widget (i.e. whose name doesn’t conform to the
classname wgt naming convention) will be ignored.
4 Delete all the icons you don’t need and leave yourself enough
to match the number of custom widgets you’ve made.
5 Use the pixmap editor to change the icon(s) into something
appropriate for your widget(s).
6 Rename the instance name to match your widget’s class name
(e.g. ShadowedBox wgt).
7 Rename the picture module from ptpalette to another name
of your preference.

September 20, 2005 Chapter 7 ¯ Binding Widgets into PhAB 229

Creating a widget description table  2005, QNX Software Systems

8 Save the application.

Creating a widget description table

The description table for a single widget is stored in a widget palette
file. The widget description table must describe all the resources and
callbacks your custom widget understands.
The palette file can contain any number of widget description tables
but must contain at least one. The name of your palette file must end
with a .pal extension (e.g. mywidgets.pal). To get a good idea of
what a palette file should contain, look at the
/qnx4/phtk/appbuilder/ptpalette.pal file.
The start of a new widget in the file is defined by a widget class name
definition. This is followed by the widget hierarchy, resources,
callbacks, type definition, and finally some initial default values to use
when the widget is first created.
The widget description table defines the following settings:

¯ widget class name (w=)

¯ widget hierarchy (h=)

¯ list of resources (r=)

¯ list of callbacks (c=, k=, e=)

¯ inherited resources and callbacks (i=, n=)

¯ base widget (b=)

¯ create-type definition (t=)

¯ cursor styles (s=)

¯ default values (d=)

230 Chapter 7 ¯ Binding Widgets into PhAB September 20, 2005

 2005, QNX Software Systems Creating a widget description table

Widget class name (w=)

This setting starts the definition of a new widget:

w=class name

Example:

w=ShadowedBox

☞ Don’t include spaces before or after the equals sign (=).

When PhAB encounters a class name setting, it allocates space in its

internal list for the widget. Any settings found afterwards are applied
to this widget until a new widget class name setting is encountered.

Widget hierarchy (h=)

This setting defines the widget hierarchy:

h=number of levels
highest class name
[next highest class name]
.
.
.
custom widget class name

Example:

h=3
PtWidget
PtBasic
ShadowedBox

The h= setting indicates the number of levels in the hierarchy. This is

followed by the widget class hierarchy names in descending order of
inheritance.
The widget hierarchy setting tells PhAB which class in the widget’s
hierarchy to use when different classes of widgets are selected. For

September 20, 2005 Chapter 7 ¯ Binding Widgets into PhAB 231

Creating a widget description table  2005, QNX Software Systems

example, if you select a PtLabel and PtButton widget at the same

time, the PhAB Control Panel must show you resources that apply to
both widgets. PhAB does this by walking up the hierarchy list until it
finds the identical class name for both widgets.

List of resources (r=)

If you want to be able to edit a resource in PhAB, you’ll need either
an r= entry (for new resources or inherited resources with a different
default value) or an i= entry (for inherited resources) — see
“Inherited resources and callbacks (i=, n=)” below.
The r= setting defines a resource for the widget:
r=manifest name,desc name,resource no,reserved,select ind,type,default value[,additional info]
[additional info 1
additional info 2
.
.
.
additional info n]

Example:
r=SBW SHADOW COLOR,Shadow Color,5000000,0,1,crgb,0x0
r=Pt ARG HORIZONTAL ALIGNMENT,Horizontal Alignment,3000,0,1,short,2,3
Pt LEFT,0
Pt RIGHT,1
Pt CENTER,2

☞ Don’t create resource entries for the Pt ARG POS and Pt ARG DIM
resources. All widgets must support these, so PhAB handles them
internally.

The arguments of the resource entry have the following meanings:

manifest name The valid C manifest name to access this resource

from application code.

232 Chapter 7 ¯ Binding Widgets into PhAB September 20, 2005

 2005, QNX Software Systems Creating a widget description table

desc name A descriptive version of the manifest name, which

is easier to understand and takes up less space
(allowing the Control Panel to stay small).

resource no The actual resource number (e.g.

Pt USER(0)=5000000, Pt USER(1)=5001000,
and so on —
Pt RESOURCE(Pt USER(2),5)=5002005).

reserved Always use a value of 0.

select ind Indicates whether this resource supports multiple

selections. A value of 0 will hide the resource
when two or more widgets are selected. A value of
1 enables the resource.

type Indicates the type of editor PhAB should use for

this resource. Valid types are:

pixmap Supports the creation/modification of

PhImage t structures.
bitmap Used only by PtBitmap widget (don’t
use this).
points Used internally by PhAB for
multisegment lines. PhAB manages this
resource type so you can use the points
array provided by PtGraphic.
list Array of text strings.
crgb Color value made of PgColor t.
font Font specification (string).
multi Multiline text string.
short Numeric value.
string Single-line text string.
datas Single-line text string (Alloc type).
flag Flag resource.

September 20, 2005 Chapter 7 ¯ Binding Widgets into PhAB 233

Creating a widget description table  2005, QNX Software Systems

code A pointer to a function (see

Pointer-to-function resources below).
double A double value.
float A float value.

default value This is the default value in the widget code itself.
It’s very important for this value to exactly match
the real default value in the widget, because PhAB
doesn’t generate resource entries in the module
files if it seems the resource matches the default
value. This keeps the size of the module file to a
minimum. If the default value you specify doesn’t
match, the widget may not behave as expected
because a required resource setting will be missing
from the module file.

additional info This optional value can be used to specify

additional information about the resource:
¯ A list of flag pairs for flag-type resources; see
“Option and flag pairs” below.
¯ A list of option pairs for short-type resources;
see “Option and flag pairs” below.
¯ A function prototype of code-type resources;
see “Pointer-to-function resources” below.
The value can be specified as:
¯ The number of lines of additional information
following the r= line.
If there aren’t any lines of additional
information, omit additional info. Don’t specify
a value of 0.
¯ The widget class for which the resource has
been defined earlier, and from which you want
to copy the additional information. This is
useful, for example, if the resource’s description
or default value is different for the two widgets,

234 Chapter 7 ¯ Binding Widgets into PhAB September 20, 2005

 2005, QNX Software Systems Creating a widget description table

but the additional information is the same. If the

resource is the same in both widgets, it’s easier
to use an i= entry to make this widget inherit it
from the other.

Option and flag pairs

For short and flag resources, additional info specifies the possible
values. Each line is in the form:

description,value

where description is the text that PhAB is to display in the editor, and
value is the corresponding value.

Pointer-to-function resources
For a resource that’s a pointer to a function (i.e. type is code),
additional info specifies the number of following lines that define the
function’s prototype. The prototype should contain an @ in place of
the function name, but no terminating semicolon.
The default value specifies the code that will be used for the function
body whenever PhAB generates a function for the resource. If the
code will fit on the line and doesn’t contain any commas, you can
specify it directly as default value. Otherwise, put the code on the
lines that follow the function prototype, and set default value to be
the number of lines of code.
Here are some examples:
r=ARG SIMPLEFUNCTION,A function,5000001,5000001,1,return 0;,1
int @( void )

r=Pt ARG RAW DRAW F,Draw Function,24000,24000,1,code,1,1

void @( PtWidget t *widget, PhTile t *damage )
PtSuperClassDraw( PtBasic, widget, damage );

r=Pt ARG LIST BALLOON,Inflate Function,23031,23031,1,code,6,5

PtWidget t *@(
PtWidget t *widget, PtWidget t *parent,
PhArea t *area, PtListColumn t const *column, int coln,
const char *item, unsigned index, const char *font

September 20, 2005 Chapter 7 ¯ Binding Widgets into PhAB 235

Creating a widget description table  2005, QNX Software Systems

)
return
PtGenListCreateTextBalloon(
widget, parent,
PtGenListSetColumnBalloon( area, column ),
item, coln, font
);

List of callbacks (c=, k=, e=)

These settings define callbacks:

c|k|e=manifest name,desc name,resource num,reserved

Example:

c=Pt CB ACTIVATE,Activate,2009,0
k=Pt CB HOTKEY,Hotkey,1010,0
e=Pt CB RAW,Raw Event,1011,0

Photon supports three different types of callbacks. These are standard

widget callbacks (c=), hotkey callbacks (k=), and raw event callbacks
(e=). Make sure you use the type that matches the definition of the
callback in the widget.
The arguments of the callback entries are identical and have the
following meanings:

manifest name The valid C manifest name to access this resource

through application code.

desc name A descriptive version of the manifest name, which

is easier to understand and takes up less space
(allowing the Control Panel to stay small).

resource no The actual resource number (e.g.

Pt USER(0)=5000000,
Pt USER(1)=5001000, and so on —
Pt RESOURCE(Pt USER(2),5)=5002005).

236 Chapter 7 ¯ Binding Widgets into PhAB September 20, 2005

 2005, QNX Software Systems Creating a widget description table

reserved Always use a value of 0.

Callbacks can also be inherited from other widgets. See “Inherited

resources and callbacks (i=, n=)”, below.

Inherited resources and callbacks (i=, n=)

Resource descriptions can be shared by multiple widget classes. This
saves memory on runtime and helps keep the palette files consistent
(e.g. if a new flag is added to a resource of a parent class, you don’t
have to add it to the description of each child class manually).
These settings can be used to inherit resource or callback definitions
from a widget defined earlier:

i=widget[,from[,to]]
n=widget[,from[,to]]

The i= line copies resources (defined by r= or i= lines). The n= line

copies callbacks (defined by c=, k=, e=, or i= lines).
The from and to values are numbers that specify the resource numbers
to be copied. If both are given, they define a range. If only the from
value is given, it specifies one resource. If neither from nor to is given,
all resources/callbacks will be copied.
The i= entry can be used only if the resource definitions for the child
and parent classes are identical. If there are any differences (for
example, the child class overrides the default value), you’ll need to
use an r= resource definition — but the child class can still inherit
any additional info that the parent class defines or inherits. For more
information, see “List of resources (r=).”

Base widget (b=)

This setting tells PhAB to use container emulation:

b=Container

September 20, 2005 Chapter 7 ¯ Binding Widgets into PhAB 237

Creating a widget description table  2005, QNX Software Systems

Since PhAB can’t display your widget directly, it must use a

substitute widget in its place. If the widget isn’t a container and you
don’t set this value, PhAB will use a PtBasic widget to emulate your
widget. If the widget is a container, set the value as shown above and
PhAB will use PtContainer to emulate your widget.

Create-type definition (t=)

This setting defines the type of creation mode to use:

t=number

Example:

t=2

The type definition tells PhAB how this widget should be created. For
example, if t=1, PhAB automatically creates the widget as soon as
the user clicks in the module. This is because type 1 indicates the
widget has a preset size. A value of t=2 means the user can drag out
the size when creating the widget.
Valid values for number range from 1 through 6 and have the
following meanings:

When number is: Create type is:

1 Preset, resizable
2 Resizable on create
3 Line (2 points)
4 Preset, Nonresizable
5 Polygon (multipoint)
6 Bezier (multipoint with handles)

238 Chapter 7 ¯ Binding Widgets into PhAB September 20, 2005

 2005, QNX Software Systems Creating a widget description table

For more information, see “Creating a widget” in the Creating

Widgets in PhAB chapter of the Photon Programmer’s Guide.

Cursor styles (s=)

This setting determines the cursor style when creating the widget:

s=start cursor style[,drag cursor style]

Example:

s=0xe914,0xe914

This setting defines the look of the cursor when the widget is being
created in PhAB. The value you choose for a cursor style setting (s=)
will depend on the value you specify for the create type setting (t=).
For consistency with other widgets in PhAB, we recommend that you
assign cursor style values according to the table below:

If create type is: Cursor style should be:

t=1 s=0xe906
t=2 s=0xe914,0xe914
t=3 s=0xe906
t=4 s=0xe906
t=5 s=0xe906
t=6 s=0xe906

Default values (d=)

This setting lets you give the widget some default values to override
the defaults built into the widget:

d=class name,no of resource definitions

definition 1

September 20, 2005 Chapter 7 ¯ Binding Widgets into PhAB 239

Creating a widget description table  2005, QNX Software Systems

definition 2
.
.
.
definition n

Each definition consists of three values:

¯ resource number

¯ resource type

¯ resource value

For example:

// Resizable example.
d=ShadowedBox,1
1005
dim
1,1

// Preset example.
d=PtPrintSel,1
1005
dim
418,285

Each resource definition is made up of three lines, and only simple

resource types can be used. In the example above, the Pt ARG DIM
(1005) resource is set to 1 pixel high and 1 pixel wide. This is a good
starting point for a widget with a create type number of 2.

!
CAUTION: You must always give a widget a default value and
starting dimension. If you don’t, you’ll get unexpected results.
If t=1 or t=4, set the dim resource to the preset size. If the value is
anything else, set dim to 1,1. The dim resource is defined as
“width,height” in pixels.

240 Chapter 7 ¯ Binding Widgets into PhAB September 20, 2005

 2005, QNX Software Systems Adding the widget palette file to PhAB

Adding the widget palette file to PhAB

To add the widget palette file to PhAB:

1 After creating the palette picture module and palette description

file, make sure both files have consistent names (e.g.
mywidgets.wgtp and mywidgets.pal).

2 Copy both files to the /qnx4/phtk/appbuilder directory.

3 Add a line for your new palette to the palette definition file,
palette.def. The syntax of the entry is:
p=palette file name,description
(e.g. p=mywidgets,My Custom Widgets).

4 Save the palette definition file and restart PhAB.

You should now be able to go into the Options/Customize WidgetBar

option in PhAB and select your widget. This will add your widget to
the PhAB widget bar.

☞ Be sure to modify your application’s Makefile so that it’s linked with

your new widget. Include your widget header in the global
application header defined in the Application Start-up Info dialog.

September 20, 2005 Chapter 7 ¯ Binding Widgets into PhAB 241

 Chapter 8
Widget Building Library API

September 20, 2005 Chapter 8 ¯ Widget Building Library API 243

 2005, QNX Software Systems

This chapter contains descriptions of the following functions, which

are included in the widget building library API:

PtAddWidgetData()
Add data to the widget data chain
PtAnchorWidget()
Anchor the provided widget
PtApplyAnchors()
Anchor a container and its children
PtAttemptResize()
Adjust the size of a widget
PtCalcAnchorOffsets()
Calculate anchor offsets

PtCalcRegion() Determine whether or not a widget needs a region

PtChildBoundingBox()
Calculate a widget’s canvas and its children’s
bounding boxes

PtClipAdd() Add a clipping rectangle to the stack

PtClipRemove() Take a clipping rectangle off the stack

PtCompoundRedirect()
Redirect widgets to a parent
PtContainerChildRedirect()
Set the pointer to the child-redirector function
PtContainerDeregister()
Deregister a container from its parent
PtContainerRegister()
Register a container with its parent

September 20, 2005 Chapter 8 ¯ Widget Building Library API 245

  2005, QNX Software Systems

PtCoreChangeRegion()
Determine if a region is required
PtCreateWidgetClass()
Create a widget class
PtDamageExposed()
Damage the specified widgets

PtDestroyCallbackList()
Free the specified callbacks

PtDestroyHotkeyCallbacks()
Free the specified hotkey callbacks

PtDestroyRawCallbacks()
Free the specified raw callbacks

PtFindNextWidgetData()
Find the next appropriate data block

PtFindResourceRecord()
Find the record associated with a resource
PtFindWidgetData()
Find the first data block of a given type and subtype

PtGetAnchoredExtent()
Calculate a new anchor rectangle

PtGetStruct() Retrieve the specified resource

PtInvokeCallbackList()
Invoke a callback list
PtInvokeResizeCallbacks()
Invoke the resize callbacks of the specified
container

246 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems

PtMoveResizeWidget()
Synchronize a widget’s extent
PtRemoveWidgetData()
Remove data from the widget data chain
PtResizePolicy()
Determine whether a widget has a resize policy
PtSetExtentFromArea()
Calculate the extent of a widget
PtSetStruct() Set the specified resource
PtSetValue() Set the value of a resource using mod f

PtSuperClassCalcOpaque()
Call the Calc Opaque Rect method of the specified
superclass
PtSuperClassChildCreated()
Invoke a Child Created method
PtSuperClassChildDestroyed()
Invoke a Child Destroyed method
PtSuperClassChildGettingFocus()
Invoke a Child Getting Focus method
PtSuperClassChildGettingResources()
Invoke a Child Getting Resources method
PtSuperClassChildLosingFocus()
Invoke a Child Losing Focus method
PtSuperClassChildMovedResized()
Invoke a Child Moved/Resized method
PtSuperClassChildRealized()
Invoke a Child Realized method

September 20, 2005 Chapter 8 ¯ Widget Building Library API 247

  2005, QNX Software Systems

PtSuperClassChildSettingResources()
Invoke a Child Setting Resources method
PtSuperClassChildUnrealized()
Invoke a Child Unrealized method

PtSuperClassConnect(), PtSuperClassConnectFrom()
Invoke the Connection method of the specified
widget class
PtSuperClassDraw()
Invoke the Draw method of the specified superclass
PtSuperClassExtent()
Invoke the Extent method of the specified
superclass
PtSuperClassGetResources()
Get the specified resource
PtSuperClassGotFocus()
Invoke the Got Focus method of the specified
superclass
PtSuperClassInit(), PtSuperClassInitFrom()
Invoke the Initialize method of the specified widget
class
PtSuperClassLostFocus()
Invoke the Lost Focus method of the specified
superclass

PtSuperClassRawEvent(), PtSuperClassRawEventFrom()
Invoke the raw callback list of the specified widget
class
PtSuperClassRealized()
Invoke the Realization method of the specified
widget class

248 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems

PtSuperClassSetResources()
Set resources
PtUpdateVisibility()
Tell the widget library about a change in visibility

PtWidgetAbove()
Identify the position of a widget in the hierarchy
relative to another widget

September 20, 2005 Chapter 8 ¯ Widget Building Library API 249

PtAddWidgetData()  2005, QNX Software Systems
Add data to the widget data chain

Synopsis:
int PtAddWidgetData( PtWidget t *widget,
PtWidgetClassRef t *type,
long subtype,
void *data );

Description:
This function adds a piece of data to the widget data chain. The data
provided must be in a block of memory allocated by malloc(). This
data can be retrieved by calling PtFindWidgetData() or
PtFindNextWidgetData().
The widget argument points to the widget whose chain the data
should be added to. The type is the class of the widget adding the
data. The subtype is used to discriminate between multiple blocks of
data added by the same widget class. The subtype shouldn’t be -1, as
this value has special meaning when searching for a specific block
within the widget data chain. The data argument is a pointer to the
data to be added to the widget data chain.

Returns:
0 on success; -1 if an error occurred (e.g. out of memory).

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

250 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtAddWidgetData()

See also:
PtFindWidgetData(), PtFindNextWidgetData(),
PtRemoveWidgetData()

September 20, 2005 Chapter 8 ¯ Widget Building Library API 251

PtAnchorWidget()  2005, QNX Software Systems
Anchor the provided widget

Synopsis:
void PtAnchorWidget( PtWidget t *widget );

Description:
This function anchors the provided widget. If the widget’s anchor
offsets have yet to be calculated, they’re calculated along with the
anchor offsets for all child containers. No other action takes place.
If the widget’s anchor offsets have been calculated, the widget and all
its children’s dimensions are adjusted to honor their anchor flags.

☞ PtAnchorWidget() is used by PtApplyAnchors().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtApplyAnchors(), PtCalcAnchorOffsets()

252 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtApplyAnchors()
Anchor a container and its children

Synopsis:
int PtApplyAnchors( PtWidget t *container );

Description:
This function performs any necessary anchoring on the provided
container widget and all its registered children.

Returns:
1 Successful completion.

0 An error occurred; container isn’t a PtContainer widget.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtAnchorWidget(), PtContainerDeregister(), PtContainerRegister()

September 20, 2005 Chapter 8 ¯ Widget Building Library API 253

PtAttemptResize()  2005, QNX Software Systems
Adjust the size of a widget

Synopsis:
int PtAttemptResize( PtWidget t *widget,
PhRect t const *canvas,
PhRect t const *render );

Description:
This function adjusts the size of the widget based on the differences
between canvas and render and on the widget’s resize flags.
The widget’s actual size is modified (widget->area.size). If the resize
policy of the widget prevents PtAttemptResize() from adjusting the
widget’s size (i.e. the canvas won’t fit within the provided render
rectangle), PtAttemptResize() sets the Pt UCLIP bit of the widget’s
resize flags. If this bit is set, the widget’s Draw method should apply
clipping via PtClipAdd() prior to rendering its data.

Returns:
1 Successful completion.

0 No resize occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

254 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtAttemptResize()

See also:
PgExtentText(), PtChildBoundingBox(), PtClipAdd(),
PtClipRemove(), PtWidgetCanvas()

September 20, 2005 Chapter 8 ¯ Widget Building Library API 255

PtCalcAnchorOffsets()  2005, QNX Software Systems
Calculate anchor offsets

Synopsis:
void PtCalcAnchorOffsets( PtWidget t *container,
PhRect t const * anchor rect );

Description:
This function calculates the anchor offsets for the given container
widget based on its current anchor flags, its parent’s canvas rectangle,
and the provided anchor rect.
The container’s anchor offsets are calculated such that a subsequent
call to PtGetAnchoredExtent() yields a corrected new anchor rect
with respect to the canvas rectangle of the parent and the anchor flags
in effect.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtAnchorWidget(), PtApplyAnchors(), PtGetAnchoredExtent()

256 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtCalcRegion()
Determine whether or not a widget needs a region

Synopsis:
int PtCalcRegion( unsigned int *fields,
PtWidget t *widget,
PhRegion t *region,
PhRect t *rect );

Description:
This function determines whether or not the given widget needs a
region and stores information about the region in the structure pointed
to by region.
The fields argument specifies which fields of the structure pointed to
by region the function should fill in. For more information about the
fields, see PhRegionOpen() in the Photon Library Reference.
The rectangle for the region is stored in the structure pointed to by
rect.

Returns:
0 The widget doesn’t need a region.

1 The widget needs a region.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 8 ¯ Widget Building Library API 257

PtCalcRegion()  2005, QNX Software Systems

See also:
PhRegionOpen()

258 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtChildBoundingBox()
Calculate a widget’s canvas and its children’s bounding boxes

Synopsis:
PhRect t *PtChildBoundingBox( PtWidget t *widget,
PhRect t *canvas,
PhRect t *render );

Description:
This function calculates the canvas of widget and finds the bounding
box of widget’s children relative to the origin of the parent’s position.
If the canvas parameter isn’t NULL, it’s set to the canvas rectangle of
the PtBasic-class level for the specified widget.
The render parameter is set to this bounding box and is also the
returned pointer. The render parameter must be provided.

Returns:
A pointer to the render rectangle.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtBasicWidgetCanvas(), PtSuperClassExtent()

September 20, 2005 Chapter 8 ¯ Widget Building Library API 259

PtClipAdd()  2005, QNX Software Systems
Add a clipping rectangle to the stack

Synopsis:
int PtClipAdd( PtWidget t *widget,
PhRect t *rect );

Description:
This function adds a clipping rectangle to the clipping stack. The
rectangle added to the clipping stack is the intersection of the last
rectangle on the stack and the provided rectangle rect.
Prior to entering a widget’s Draw method, the canvas rectangle
derived from the PtBasic-class level is pushed onto the clipping
stack. This prevents any children from drawing beyond the canvas of
the parent container.
A widget can, however, draw beyond its own canvas or extent unless
additional clipping is performed. PtAttemptResize() will set the
Pt UCLIP bit of a widget’s resize flags if the widget requires additional
clipping (to prevent it from drawing beyond its own canvas).

Returns:
The current level of stack clipping.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

260 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtClipAdd()

See also:
PtAttemptResize(), PtClipRemove(), PtWidgetCanvas()

September 20, 2005 Chapter 8 ¯ Widget Building Library API 261

PtClipRemove()  2005, QNX Software Systems
Take a clipping rectangle off the stack

Synopsis:
int PtClipRemove();

Description:
This function pops the last clipping rectangle off the clipping stack.

Returns:
The current level of stack clipping.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtAttemptResize(), PtClipAdd(), PtWidgetCanvas()

262 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtCompoundRedirect()
Redirect widgets to a parent

Synopsis:
PtWidget t *PtCompoundRedirect(
PtWidget t *container,
PtWidgetClassRef t *child cref );

Description:
This function returns the parent of a compound widget, making the
compound widget seem like a simple widget (i.e. users can’t place
widgets inside container).
This is especially useful for rejecting widgets or redirecting widgets
to subordinate containers (e.g. PtScrollArea does this).
This redirector function can be added to a custom compound widget
by calling PtContainerChildRedirect().

Returns:
A pointer to the parent of the given compound widget.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtContainerChildRedirect()

September 20, 2005 Chapter 8 ¯ Widget Building Library API 263

PtContainerChildRedirect()  2005, QNX Software Systems
Set the pointer to the child-redirector function

Synopsis:
int PtContainerChildRedirect(
PtWidget t *container,
PtWidget t *(*redirect)(
PtWidget t *container,
PtWidgetClassRef t *child class ref ));

Description:
This function sets the provided container’s child-redirector function
to the given redirect function. The child-redirector function is invoked
whenever a user attempts to create a widget within the immediate
child of container.
The container parameter in the callback must be a pointer to the
container itself. The child class ref pointer points to the child’s class
reference, which indicates what class of widget is being created.
The PtWidget t * return type of your redirector function will be
used as the ultimate parent of the newly created widget.

Returns:
0 Successful completion.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

264 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtContainerChildRedirect()

See also:
PtCompoundRedirect()

September 20, 2005 Chapter 8 ¯ Widget Building Library API 265

PtContainerDeregister()  2005, QNX Software Systems
Deregister a container from its parent

Synopsis:
void PtContainerDeregister( PtWidget t *container );

Description:
This function deregisters container from its parent. This prevents
container from being included in anchoring operations.
The deregister operation is done by PtContainer’s Unrealization
method. If you override PtContainer’s Unrealization method, you
should call PtContainerDeregister() to remove container from its
parent’s list of children before any anchoring is applied.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtContainerRegister()

266 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtContainerRegister()
Register a container with its parent

Synopsis:
void PtContainerRegister( PtWidget t *container );

Description:
This function registers container with its parent for anchoring.
Anchoring is done by PtContainer’s Extent method. If you override
this method and want to use PtContainer’s anchoring mechanism,
you must register each widget instance in your Extent method.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtContainerDeregister()

September 20, 2005 Chapter 8 ¯ Widget Building Library API 267

PtCoreChangeRegion()  2005, QNX Software Systems
Determine if a region is required

Synopsis:
void PtCoreChangeRegion( unsigned int fields,
PtWidget t *widget );

Description:
This function examines the current state of widget with respect to
fields and determines if widget requires a region. If a region is
required, PtCoreChangeRegion() determines what attributes (e.g.
sensitivity) are required.
PtCoreChangeRegion() may call one of the following functions with
appropriate attributes:

If the widget: This function is called:

Is a subclass of PtWindow PhWindowChange()
Already has a region PhRegionChange()
Doesn’t have a region PhRegionOpen()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

268 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtCoreChangeRegion()

See also:
PhRegionChange(), PhRegionOpen(), PhWindowChange()

September 20, 2005 Chapter 8 ¯ Widget Building Library API 269

PtCreateWidgetClass()  2005, QNX Software Systems
Create a widget class

Synopsis:
PtWidgetClass t *PtCreateWidgetClass(
PtWidgetClassRef t *superclass ref ,
unsigned int size,
unsigned int num args,
PtArg t const *args );

Description:
This function creates a new widget class based on superclass ref . If
the specified superclass hasn’t yet been created, it’s created now.
The arguments are as follows:

superclass ref
The class reference of the superclass this class is to be
a subclass of.

size The size of the new widget class. If this is 0, the size of
the superclass is used; if nonzero, it must be at least as
large as the superclass.

num args The number of entries in the arg array.

args The array of class attributes and member functions to

be applied when creating the new class.

If the size parameter is zero, the new class is the same size as the
specified superclass. Otherwise size bytes are allocated for the new
class. The specified superclass is then copied into the newly allocated
class (inheritance). The version, resources, num resources, callbacks,
dflts f , connect f , init f , unrealize f , and destroy f members are
cleared because they shouldn’t be inherited.

270 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtCreateWidgetClass()

Returns:
A pointer to the newly created class:

base->superclass = superclass ? superclass->wclass:NULL;

Examples:
This example is from the ShadowedBox sample widget.

//
// ShadowedBox class-creation function
//
PtWidgetClass t *PtCreateBasicClass( void )
{
static const PtResourceRec t resources[] =
{
{ SBW SHADOW COLOR, Pt CHANGE REDRAW, 0,
Pt ARG IS NUMBER( ShadowedBoxWidget, shadow color ) },
{ SBW SHADOW OFFSET, Pt CHANGE REDRAW, 0,
Pt ARG IS NUMBER( ShadowedBoxWidget, shadow offset ) }
};

static const PtArg t args[] =

{
{ Pt SET VERSION, 110},
{ Pt SET STATE LEN, sizeof( ShadowedBoxWidget ) },
{ Pt SET DFLTS F, (long)shadowbox dflts },
{ Pt SET DRAW F, (long)shadowedbox draw },
{ Pt SET FLAGS, 0, Pt RECTANGULAR },
{ Pt SET RESOURCES, (long) resources },
{ Pt SET NUM RESOURCES,
sizeof( resources )/sizeof( resources[0] ) }
};

return( ShadowedBox->wclass = PtCreateWidgetClass(

PtBasic, 0, sizeof( args )/sizeof( args[0] ), args ) );
}

Classification:
Photon

September 20, 2005 Chapter 8 ¯ Widget Building Library API 271

PtCreateWidgetClass()  2005, QNX Software Systems

Safety
Interrupt handler No
Signal handler No
Thread No

272 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtDamageExposed()
Damage the specified widgets

Synopsis:
void PtDamageExposed( PtWidget t *widget,
PhTile t *tile );

Description:
This function damages the list of rectangles given in tile on the parent
of widget. The tile list should include rectangles relative to the
widget’s origin. The damage may extend beyond the extent of the
widget.

☞ This function frees the tile list automatically.

Examples:
To redraw a transparent widget due to a data change:

tile = PhGetTile();
PtWidgetExtent( widget, &tile->rect );
tile->next = NULL;
PtDamageExposed( widget, tile );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 8 ¯ Widget Building Library API 273

PtDamageExposed()  2005, QNX Software Systems

See also:
PhGetTile()

274 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtDestroyCallbackList()
Free the specified callbacks

Synopsis:
int PtDestroyCallbackList(
PtCallbackList t **cbp );

Description:
This function frees the entire callback list pointed to by cbp. The cbp
argument is set to NULL when PtDestroyCallbackList() is successful.

☞ The widget library automatically frees all allocated resources

including callback lists when a widget is destroyed.

Returns:
0 Successful completion.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtDestroyHotkeyCallbacks(), PtDestroyRawCallbacks()

September 20, 2005 Chapter 8 ¯ Widget Building Library API 275

PtDestroyHotkeyCallbacks()  2005, QNX Software Systems
Free the specified hotkey callbacks

Synopsis:
void PtDestroyHotkeyCallbacks( PtWidget t *widget );

Description:
This function frees all hotkey callbacks connected to widget.

☞ The widget library automatically frees all allocated resources

including lists when a widget is destroyed.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtDestroyCallbackList(), PtDestroyRawCallbacks()

276 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtDestroyRawCallbacks()
Free the specified raw callbacks

Synopsis:
void PtDestroyRawCallbacks( PtWidget t *widget );

Description:
This function frees all raw callbacks connected to widget.

☞ The widget library automatically frees all allocated resources

including callback lists when a widget is destroyed.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtDestroyCallbackList(), PtDestroyHotkeyCallbacks()

September 20, 2005 Chapter 8 ¯ Widget Building Library API 277

PtFindNextWidgetData()  2005, QNX Software Systems
Find the next appropriate data block

Synopsis:
void * PtFindNextWidgetData(
PtWidget t *widget,
PtDataHdr t *data node,
PtWidgetClassRef t *type,
long subtype,
PtDataHdr t ** node )

Description:
This function (starting from data node) finds the next widget data
block that matches the type and subtype provided. If data node is
NULL, the first instance of data that matches the type and subtype
provided will be found. If type is NULL, any type will match. If
subtype is -1, any subtype will match.
If node is provided, it’s set to point to the widget data node that
contained the returned data, so you can continue the search from that
node.

Returns:
A void pointer to the widget data, or NULL if it wasn’t found.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

278 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtFindNextWidgetData()

See also:
PtAddWidgetData(), PtFindWidgetData(), PtRemoveWidgetData()

September 20, 2005 Chapter 8 ¯ Widget Building Library API 279

PtFindResourceRecord()  2005, QNX Software Systems
Find the record associated with a resource

Synopsis:
PtResourceRec t const * PtFindResourceRecord(
long type,
PtWidgetClass t const *a class );

Description:
This function finds the resource record for the resource given by type
in the a class class or any of its superclasses. This function may be
used in your own Set Resource/Get Resource methods.

Returns:
A pointer to a resource record, or NULL if an error occurred.

Examples:
my label setcolor( PtWidget t *widget, PgColor t color )
{
PtResourceRec t *res rec;
PtArg t argt;
PtSetArg( &argt, Pt ARG COLOR, color, 0 );
// This should actually check for NULL failure
res rec = PtFindResourceRecord( Pt ARG COLOR,
PtLabel->wclass );
PtSetValue( widget, res rec, &argt );
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

280 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtFindResourceRecord()

See also:
PtSetValue()

September 20, 2005 Chapter 8 ¯ Widget Building Library API 281

PtFindWidgetData()  2005, QNX Software Systems
Find the first widget data block of a given type and subtype

Synopsis:
void * PtFindWidgetData(
PtWidget t *widget,
PtWidgetClassRef t *type,
long subtype,
PtDataHdr t ** node );

Description:
This function finds the first widget data block that matches the type
and subtype provided. If type is NULL, any type will match. If
subtype is -1, any subtype will match.
If node is provided, it’s set to point to the widget data node that
contained the returned data, so you can continue the search from that
node.

Returns:
A void pointer to the widget data, or NULL if it wasn’t found.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtAddWidgetData(), PtFindNextWidgetData(),
PtRemoveWidgetData()

282 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtGetAnchoredExtent()
Calculate a new anchor rectangle

Synopsis:
int PtGetAnchoredExtent( PtWidget t *container,
PhRect t const *old anchor rect,
PhRect t *new anchor rect );

Description:
This function calculates a new anchor rectangle new anchor rect
using the canvas rectangle derived from the PtBasic-class level and
the anchor flags and offsets associated with container.
The anchor flags and anchor offsets are calculated by
PtCalcAnchorOffsets(). All parameters must be provided. The
new anchor rect argument is used only if PtGetAnchoredExtent()
returns a value of 1.

Returns:
0 An error occurred — the widget shouldn’t be anchored (i.e. it
isn’t a container widget); there’s no anchor flags set; or
new anchor rect == old anchor rect.

-1 The widget’s anchor offsets were calculated.

1 The widget’s anchor offsets were used to yield

new anchor rect.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 8 ¯ Widget Building Library API 283

PtGetAnchoredExtent()  2005, QNX Software Systems

See also:
PtCalcAnchorOffsets()

284 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtGetStruct()
Retrieve the specified resource

Synopsis:
int PtGetStruct( char *base,
PtResourceRec t const *mod,
PtArg t *arg );

Description:
This function retrieves the resource specified by arg from the widget
at address base as described by mod.
If the value and len members of arg are non-NULL, they’re assumed
to contain the addresses of pointers of the type appropriate for the
resource. The pointers are set to point to the resource’s value in the
widget’s internal memory.

☞ Don’t use these pointers to change the resource’s value.

If either of the value and len members of arg is NULL, the retrieved
resources are stored in these members.

Returns:
0 Successful completion.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 8 ¯ Widget Building Library API 285

PtGetStruct()  2005, QNX Software Systems

See also:
PtSetStruct(), PtSuperClassGetResources(),
PtSuperClassSetResources()

286 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtInvokeCallbackList()
Invoke a callback list

Synopsis:
int PtInvokeCallbackList( PtCallbackList t *cb list,
PtWidget t *widget,
PtCallbackInfo t *cbinfo );

Description:
This function invokes the provided callback list cb list.
The widget argument is passed as the first parameter to each callback
in the list. The cb data member of each item in the list is passed as
the second parameter. The cbinfo argument is passed to each callback
in the list as the third parameter.

Returns:
A return status from the callback list:

¯ Pt CONTINUE

¯ Pt HALT

¯ Pt END

If the returned status is Pt END, have your function consume the event
(i.e. return Pt END).

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 8 ¯ Widget Building Library API 287

PtInvokeResizeCallbacks()  2005, QNX Software Systems
Invoke the resize callbacks of the specified container

Synopsis:
int PtInvokeResizeCallbacks( PtWidget t *container );

Description:
This function sets up a cbinfo structure and invokes the resize
callbacks attached to the specified container. If the provided
container widget isn’t a subclass of PtContainer, no action is
performed.

Returns:
0 Successful completion.

-1 An error occurred; container isn’t a container widget.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

288 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtMoveResizeWidget()
Synchronize a widget’s extent

Synopsis:
int PtMoveResizeWidget( PtWidget t *widget,
unsigned blit );

Description:
This function synchronizes a widget’s extent with its position and size
resources. Any region adjustments, blits, or damages are performed
automatically.
This function calls the widget’s Extent method to calculate its new
extent. The value of blit can be:

0 No blit.

Pt BLIT FORCE
Always blit (may cause unexpected effects).

Pt BLIT Blit when possible.

Returns:
0 No action.

Nonzero The widget was modified or damage was generated.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 8 ¯ Widget Building Library API 289

PtRemoveWidgetData()  2005, QNX Software Systems
Remove data from the widget data chain

Synopsis:
int PtRemoveWidgetData(
PtWidget t *widget,
PtWidgetClassRef t *type,
long subtype );

Description:
This function removes a piece of data from the widget data chain and
frees the memory allocated for the data.
The widget argument points to the widget whose chain the data
should be removed from. The type is the class of the widget removing
the data. The subtype is used to discriminate between multiple blocks
of data added by the same widget class.

Returns:
0 if the data was found and released; -1 if it couldn’t be found.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtAddWidgetData(), PtFindWidgetData(), PtFindNextWidgetData()

290 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtResizePolicy()
Determine whether a widget has a resize policy

Synopsis:
int PtResizePolicy( PtWidget t *widget );

Description:
This function determines whether a resize policy is currently in effect
for the specified widget.

Returns:
0 No resize policy.

Nonzero A resize policy is in effect.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 8 ¯ Widget Building Library API 291

PtSetExtentFromArea()  2005, QNX Software Systems
Calculate the extent of a widget

Synopsis:
PhRect t * PtSetExtentFromArea(
PtWidget t *widget,
PhArea t const *area,
PhRect t *extent );

Description:
This function calculates the extent rectangle of widget and places the
result in extent. The extent is calculated based on area and the
widget’s borders only (i.e. no anchoring or resize policy is enforced).

Returns:
A pointer to the extent rectangle.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

292 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtSetStruct()
Set the specified resource

Synopsis:
int PtSetStruct( char *base,
PtResourceRec t const *mod,
PtArg t const *arg );

Description:
This function sets the resource specified by arg on the widget at
address base in the manner described by mod. The arg argument
indicates which resource to modify as well as the value to modify that
resource with. The mod argument is a resource record that describes
the type of resource being modified.
Unlike PtSetValue(), PtSetStruct() doesn’t examine the mod f
member of mod (e.g. for a Pt CHANGE RESIZE flag). It sets the
appropriate structure members based on mod->value and mod->len.
If you want to do the extra widget processing as well as set the
appropriate structure members, use PtSetValue(). For a cleaner
solution, consider using PtSuperClassSetResources().

Returns:
0 No change.

1 A change was made.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 8 ¯ Widget Building Library API 293

PtSetStruct()  2005, QNX Software Systems

See also:
PtGetStruct(), PtSetValue(), PtSuperClassGetResources(),
PtSuperClassSetResources()

294 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtSetValue()
Set the value of a resource using mod f

Synopsis:
int PtSetValue( PtWidget t *widget,
PtResourceRec t const *mod,
PtArg t const *args );

Description:
This function sets the value of a particular resource using the
information provided in mod including the mod f member.
Consider calling PtSuperClassSetResources() for a cleaner solution.
To set structure members without any further action, use PtSetStruct().

Returns:
0 Nothing has changed.

1 Value has changed.

2 Value and length have changed.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtSetStruct(), PtSuperClassSetResources()

September 20, 2005 Chapter 8 ¯ Widget Building Library API 295

PtSuperClassCalcOpaque()  2005, QNX Software Systems
Call the Calc Opaque Rect method of specified superclass

Synopsis:
void PtSuperClassCalcOpaque(
PtWidgetClassRef t *cref ,
PtWidget t *widget );

Description:
This function calls the Calc Opaque Rect method of the specified
superclass. Typically, this function calculates the rectangle
representing the portion of the widget that isn’t transparent and sets or
clears the widget’s Pt OPAQUE flag.
The opaque rectangle for a widget is usually its canvas rectangle or
the canvas rectangle derived from its PtBasic-class level.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

296 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtSuperClassChildCreated()
Invoke a Child Created method

Synopsis:
void PtSuperClassChildCreated(
PtWidgetClassRef t *cref ,
PtWidget t *widget,
PtWidget t *child );

Description:
This function invokes the Child Created method of the container class
specified by cref . The widget argument is a pointer to the widget
whose Child Created method is being invoked. The child argument is
a pointer to the newly created widget.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 8 ¯ Widget Building Library API 297

PtSuperClassChildDestroyed()  2005, QNX Software Systems
Invoke a Child Destroyed method

Synopsis:
void PtSuperClassChildDestroyed(
PtWidgetClassRef t *cref ,
PtWidget t *widget,
PtWidget t *child );

Description:
This function invokes the Child Destroyed method of the container
class specified by cref . The widget argument is a pointer to the widget
whose Child Destroyed method is being invoked. The child argument
is a pointer to the widget that has just been destroyed.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

298 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtSuperClassChildGettingFocus()
Invoke a Child Getting Focus method

Synopsis:
int PtSuperClassChildGettingFocus(
PtWidgetClassRef t *cref ,
PtWidget t *widget,
PtWidget t *child,
PhEvent t *event );

Description:
This function invokes the Child Getting Focus method of the
container class specified by cref . The widget argument is a pointer to
the widget whose child is getting focus. The child argument is a
pointer to the widget that’s getting focus. The event argument is the
event that’s causing the change in focus.

Returns:
Pt END The container prevented the child from having
focus.

Pt CONTINUE The child may obtain focus.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 8 ¯ Widget Building Library API 299

PtSuperClassChildGettingResources()  2005, QNX Software
Systems
Invoke a Child Getting Resources method
Synopsis:
int PtSuperClassChildGettingResources(
PtWidgetClassRef t *cref ,
PtWidget t *widget,
PtWidget t *child,
PtArg t *argt);

Description:
This function invokes the Child Getting Resources method of the
container class specified by cref . The widget argument is a pointer to
the widget whose child is having one of its resources set. The child
argument is a pointer to the widget that’s having one of its resources
set. The argt argument describes the resource being set and what its
new value will be.

Returns:
Pt END The container prevented the resource query from
receiving further processing — the container may
have already satisfied the query.

Pt CONTINUE The resource query may be applied to the child.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

300 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtSuperClassChildLosingFocus()
Invoke a Child Losing Focus method

Synopsis:
int PtSuperClassChildLosingFocus(
PtWidgetClassRef t *cref ,
PtWidget t *widget,
PtWidget t *child,
PhEvent t *event );

Description:
This function invokes the Child Losing Focus method of the container
class specified by cref . The widget argument is a pointer to the widget
whose child is losing focus. The child argument is a pointer to the
widget that’s losing focus. The event argument is the event that’s
causing the change in focus.

Returns:
Pt END The container prevented the child from losing
focus.

Pt CONTINUE The child may lose focus.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 8 ¯ Widget Building Library API 301

PtSuperClassChildMovedResized()  2005, QNX Software Systems
Invoke a Child Moved/Resized method

Synopsis:
void PtSuperClassChildMovedResized(
PtWidgetClassRef t *cref ,
PtWidget t *widget,
PtWidget t *child,
PhArea t *current area,
PhRect t *current extent,
PhArea t *old area,
PhRect t *old extent );

Description:
This function invokes the Child Moved Resized method of the
container class specified by cref . The widget argument is a pointer to
the widget whose child was resized. The child argument is a pointer
to the widget that was resized.
The current area argument is the widget’s current area (after the
resize). The current extent argument is the widget’s current extent
(after the resize).
The old area argument is the widget’s old area (before the resize).
The old extent argument is the widget’s old extent (before the resize).

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

302 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtSuperClassChildRealized()
Invoke a Child Realized method

Synopsis:
void PtSuperClassChildRealized(
PtWidgetClassRef t *cref ,
PtWidget t *widget,
PtWidget t *child );

Description:
This function invokes the Child Realized method of the container
class specified by cref . The widget argument is a pointer to the widget
whose Child Realized method is being invoked. The child argument is
a pointer to the widget that has been realized.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 8 ¯ Widget Building Library API 303

PtSuperClassChildSettingResources()  2005, QNX Software
Systems
Invoke a Child Setting Resources method
Synopsis:
int PtSuperClassChildSettingResources(
PtWidgetClassRef t *cref ,
PtWidget t *widget,
PtWidget t *child,
PtArg t const *argt );

Description:
This function invokes the Child Setting Resources method of the
container class specified by cref . The widget argument is a pointer to
the widget whose child is having one of its resources set. The child
argument is a pointer to the widget that’s having one of its resources
set. The argt argument describes the resource being set and what its
new value will be.

Returns:
Pt END The container prevented any further changes to the
resource — the container may have already
applied the change to the child.

Pt CONTINUE Further changes to the child’s resource may be

applied.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

304 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtSuperClassChildUnrealized()
Invoke a Child Unrealized method

Synopsis:
void PtSuperClassChildUnrealized(
PtWidgetClassRef t *cref ,
PtWidget t *widget,
PtWidget t *child );

Description:
This function invokes the Child Unrealized method of the container
class specified by cref . The widget argument is a pointer to the widget
whose Child Unrealized method is being invoked. The child argument
is a pointer to the widget that has just been unrealized.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 8 ¯ Widget Building Library API 305

PtSuperClassConnect(),
PtSuperClassConnectFrom()  2005, QNX Software Systems
Invoke Connection method of specified widget class
Synopsis:
int PtSuperClassConnect(
PtWidgetClassRef t *cref ,
PtWidget t *widget);

int PtSuperClassConnectFrom(
PtWidgetClassRef t *cref ,
PtWidget t *widget );

Description:
PtSuperClassConnect() invokes the Connection method of the
specified widget class cref .
PtSuperClassConnectFrom() calls the Connection methods of all
superclasses starting with the superclass specified by cref .

Returns:
Pt CONTINUE
The connection callback chain can continue
Pt HALT or Pt END
The connection callbacks should stop.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

306 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtSuperClassDraw()
Invoke the Draw method of the specified superclass

Synopsis:
void PtSuperClassDraw( PtWidgetClassRef t *wc ref ,
PtWidget t *widget,
PhTile t const *damage );

Description:
This function invokes the Draw method of the specified superclass
wc ref . Use this function to save code and complexity in your
subclass’s Draw method.

Examples:
static void my draw( PtWidget t *widget, PhTile t *damage )
{
// draw fill & borders as needed.
PtSuperClassDraw( PtBasic, widget, damage );

PtBasicWidgetCanvas( widget, &canvas );

// Check if PtAttemptResize() function set Pt UCLIP flag

// in the Extent method.
if( widget->resize flags & Pt UCLIP )
PtClipAdd( widget, &canvas );

PgDrawLine( canvas.ul, canvas.lr );

PgDrawLine( canvas.lr, canvas.ul );

if( widget->resize flags & Pt UCLIP )

PtClipRemove();
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
continued. . .

September 20, 2005 Chapter 8 ¯ Widget Building Library API 307

PtSuperClassDraw()  2005, QNX Software Systems

Safety
Thread No

308 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtSuperClassExtent()
Invoke the Extent method of the specified superclass

Synopsis:
void PtSuperClassExtent( PtWidgetClassRef t *wc ref ,
PtWidget t *widget );

Description:
This function invokes the Extent method of the specified superclass
wc ref .
The PtLabel class’s Extent method handles multiline text (with
underlining and margins) and the resize policy.
The PtContainer class’s Extent method handles the resize policy
and anchoring for subclasses of PtContainer.
The PtGraphic class’s Extent method calculates an extent based on
an array of points, line weight, origin, and resize policy.

Examples:
To have a widget honor a minimum x dimension resource:
static void my container extent( PtWidget t *widget )
{
MyWidget t *mw = (MyWidget t *)widget;
PhRect t canvas, render, old extent;

old extent = widget->extent;

if( PtResizePolicy( widget ) )

{
PtChildBoundingBox( widget, &canvas, &render );
if( render.lr.x - render.ul.x + 1 < mw->min x )
render.lr.x = render.ul.x + mw->min x -1;
PtAttemptResize( widget, &canvas, &render );
}else if( widget->area.size.x < mw->min x )
widget->area.size.x = mw->min x;

PtSuperClassExtent( PtBasic, widget );

// Apply anchoring.
PtApplyAnchors( widget );

if( memcmp( &widget->area, &old area, sizeof( old area ) ) )

PtInvokeResizeCallbacks( widget );

September 20, 2005 Chapter 8 ¯ Widget Building Library API 309

PtSuperClassExtent()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

310 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtSuperClassGetResources()
Get the specified resource

Synopsis:
int PtSuperClassGetResources(
PtWidgetClassRef t *wc ref ,
PtWidget t *widget,
int num args,
PtArg t *args );

Description:
This function gets resources given by num args and args in the
manner defined by wc ref . This is extremely helpful when overriding
the query f member of an overridden resource.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 8 ¯ Widget Building Library API 311

PtSuperClassGotFocus()  2005, QNX Software Systems
Invoke the Got Focus method of the specified superclass

Synopsis:
void PtSuperClassGotFocus( PtWidgetClassRef t *cref ,
PtWidget t *widget,
PhEvent t *event );

Description:
This function invokes the Got Focus method of the superclass
specified by cref .
The PtBasic class’s Got Focus method is the method that normally
invokes the widget’s Got Focus method or the user-level Got Focus
callback.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

312 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtSuperClassInit(),
PtSuperClassInitFrom()
Invoke Initialize method of specified widget class
Synopsis:
int PtSuperClassInit( PtWidgetClassRef t *cref ,
PtWidget t *widget );

int PtSuperClassInitFrom( PtWidgetClassRef t *cref ,

PtWidget t *widget );

Description:
PtSuperClassInit() invokes the Initialize method of the specified
widget class cref .
PtSuperClassInitFrom() calls the Initialize method of all superclasses
starting with the superclass specified by cref . When
PtSuperClassInitFrom() is used in a Initialize method, Pt END should
be returned.

Returns:
Pt CONTINUE
The Initialization method chain can continue.
Pt HALT or Pt END
The Initialization method chaining should stop.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 8 ¯ Widget Building Library API 313

PtSuperClassLostFocus()  2005, QNX Software Systems
Invoke the Lost Focus method of the specified superclass

Synopsis:
int PtSuperClassLostFocus(
PtWidgetClassRef t *cref ,
PtWidget t *widget,
PhEvent t *event );

Description:
This function invokes the Lost Focus method of the superclass
specified by cref .
The PtBasic class’s Lost Focus method is the one that normally
invokes the widget’s Lost Focus method or the user-level Lost Focus
callback.

Returns:
The maximum value returned by the Lost Focus callback chain.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

314 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtSuperClassRawEvent(),
PtSuperClassRawEventFrom()
Invoke the raw callback list of the specified widget class
Synopsis:
int PtSuperClassRawEvent( PtWidgetClassRef t *cref ,
PtWidget t *widget
void *data,
PtCallbackInfo t *cbinfo );

int PtSuperClassRawEventFrom(
PtWidgetClassRef t *cref ,
PtWidget t *widget,
void *data,
PtCallbackInfo t *cbinfo );

Description:
PtSuperClassRawEvent() invokes the raw callback list of the specified
widget class.
PtSuperClassRawEventFrom() calls the raw callback lists of all
superclasses starting with the superclass specified by cref . When
PtSuperClassRawEventFrom() is used in a class’s raw callback, the
callback should return Pt END.

Returns:
Pt END if the event was consumed, Pt CONTINUE if it wasn’t.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 8 ¯ Widget Building Library API 315

PtSuperClassRealized()  2005, QNX Software Systems
Invoke Realization function of specified widget class

Synopsis:
void PtSuperClassRealized( PtWidgetClassRef t *cref ,
PtWidget t *widget );

Description:
This function invokes the Realization method of the specified widget
class cref .

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

316 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtSuperClassSetResources()
Set resources

Synopsis:
int PtSuperClassSetResources(
PtWidgetClassRef t *wc ref ,
PtWidget t *widget,
int num args,
PtArg t const *args )

Description:
This function sets the resources given by num args and args in the
manner defined by wc ref . This is extremely helpful when overriding
the query f member of an overridden resource.

Returns:
The number of resources set.

Examples:
my modify area( PtWidget t *widget, PtArg t *argt )
{
MyWidget t *mw = (MyWidget t *)widget;

mw->area changed = Pt TRUE;

// Apply the resource the same way a superclass does.
PtSuperClassSetResources(
widget->class rec->superclass->cref,
widget, 1, argt );

// Set the resource so that it’s treated

// like a PtBasic class widget.
PtSuperClassSetResources( PtBasic, widget, 1, argt );
}

Classification:
Photon

September 20, 2005 Chapter 8 ¯ Widget Building Library API 317

PtSuperClassSetResources()  2005, QNX Software Systems

Safety
Interrupt handler No
Signal handler No
Thread No

318 Chapter 8 ¯ Widget Building Library API September 20, 2005

 2005, QNX Software Systems PtUpdateVisibility()
Tell the widget library about a change in visibility

Synopsis:
PtUpdateVisibility( PtWidget t *widget,
PhRect t *rect );

Description:
This function tells the widget library that a change has occurred that
may affect the visibility of widgets that intersect with the provided
rect in the given container widget. This change may make the
intersecting widgets completely obscured, completely unobscured, or
partially obscured. This information is used to optimize refreshing the
screen:

¯ Widgets that are completely obscured aren’t drawn (since you

wouldn’t see them anyway).

¯ Widgets that are completely unobscured are drawn and don’t cause
widgets above them to be repaired (a completely unobscured
widget has no intersecting widgets above it).

¯ Otherwise a widget is drawn when damaged and causes all

intersecting widgets above it to be repaired.

Returns:
0 on success; -1 if widget isn’t a container.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 8 ¯ Widget Building Library API 319

PtWidgetAbove()  2005, QNX Software Systems
Identify position of widget in hierarchy relative to another widget

Synopsis:
PtWidget t * PtWidgetAbove( PtWidget t *root,
PtWidget t *widget );

Description:
This function returns the widget in front of widget, provided the
returned widget isnt any higher in the hierarchy than root.

Returns:
A pointer to the widget above, or root if there isnt one; NULL if
widget is the same as root, or widget is NULL.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtWidgetBrotherBehind(), PtWidgetBrotherInFront(),
PtWidgetChildBack(), PtWidgetChildFront(), PtWidgetFamily(),
PtWidgetParent(), PtWidgetTree(), PtWidgetTreeTraverse()

320 Chapter 8 ¯ Widget Building Library API September 20, 2005

 Appendix A
Miscellaneous Widget-Building
Tips

September 20, 2005 Appendix: A ¯ Miscellaneous Widget-Building Tips 321

 2005, QNX Software Systems

Here are some general widget-building tips (in no particular order):

¯ Never call PgSetRegion().

¯ Never call PtDamageWidget() from a Draw method.

¯ Never call Pg... functions from anywhere except the Draw method.

¯ You don’t need to call PtDamageWidget() after calling

PtRealizeWidget().

¯ In the modify functions, don’t call the widget’s Extent method

directly. Instead, set Pt WIDGET RESIZE in the widget’s
Pt ARG FLAGS resource; the widget library will calculate the
widget’s extent and perform any visual cleanup at the appropriate
time.

¯ If you must calculate the extent immediately, call

PtExtentWidget(), not your widget’s Extent method.

¯ Use PtSetResources() to set the resources of subordinate

(procreated) widgets.

¯ Avoid calling PgFlush() — the library will call it automatically

when required.

¯ Never call PtBkgdHandlerProcess() from a Draw method.

September 20, 2005 Appendix: A ¯ Miscellaneous Widget-Building Tips 323

 Glossary

September 20, 2005 Glossary 325

 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 327

  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

328 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 329

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

330 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 331

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

332 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 333

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

334 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 335

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

336 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 337

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

338 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 339

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

340 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 341

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

342 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 343

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

344 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 345

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

346 Glossary September 20, 2005

 Index

A C
anchors 12 Calc Opaque Rect method 70, 296
container widgets 28, 107, 309 inheriting 23
invalidating 111 PtBasic 52, 53, 70, 102
Extent method 80, 107, 309 PtCompound 116
PtAnchorWidget() 252 PtContainer 108
PtApplyAnchors() 253 PtGauge 137
PtCalcAnchorOffsets() 256 PtGenList 119
PtContainerDeregister() 266 PtGenTree 127
PtContainerRegister() 267 PtGraphic 135
PtGetAnchoredExtent() 283 PtLabel 131
PtSetExtentFromArea() 292 callbacks 5, 236
PtSuperClassExtent() 309 balloon 119, 130, 132
attributes See resources class-level See methods
common 72
describing in PhAB 230, 236
freeing 275
B hotkey 96, 98, 109, 236
freeing 276
basic widgets 11. See also inheriting 237
PtBasic invoking 287
behavior Pt ARG IS CALLBACK 40
defining in widget class 5 Pt ARG IS CALLBACK LIST
inheriting from superclass 5 40, 42, 97
Pt CB ACTIVATE 72, 103

September 20, 2005 Index 347

Index  2005, QNX Software Systems

PtCB ARM 72, 102 PtGenTree 127

PtCB DISARM 72, 102, 103 Child Getting Focus 77, 299
PtCB DIVIDER DRAG 120 PtContainer 109
PtCB FILTER 109 PtGenList 121
PtCB GEN TREE INPUT PtGenTree 127
128 Child Getting Resources 77,
Pt CB GOT FOCUS 102 300
Pt CB LOST FOCUS 102 PtContainer 109
Pt CB MENU 102 PtGenList 121
Pt CB REALIZED 62 PtGenTree 127
Pt CB REPEAT 102 Child Losing Focus 77, 301
Pt CB RESCALE 135 PtContainer 109
Pt CB SCROLLED X 85 PtGenList 121
Pt CB SCROLL MOVE 124 PtGenTree 127
Pt CB UNREALIZED 96 Child Moved Resized 302
raw 51, 71, 72, 103, 113, 122, Child Moved/Resized 76
236, 315 PtContainer 108
freeing 277 PtGenList 120
PtBasic 102 PtGenTree 127
PtCompound 116 Child Realized 76, 303
PtContainer 109 PtContainer 108
PtGauge 137 PtGenList 120
PtGenTree 128 PtGenTree 127
PtGraphic 135 Child Setting Resources 77,
PtLabel 131 304
PtWidget 97 PtContainer 109
resize 107 PtGenList 120
invoking 288 PtGenTree 127
child-constraint methods 29 Child Unrealized 76, 305
Child Created 75, 297 PtContainer 109
PtContainer 108 PtGenList 120
PtGenList 119 PtGenTree 127
PtGenTree 127 child-redirector function 30, 78, 87
PtGroup 75 setting 264
Child Destroyed 77, 298 children
PtContainer 109 anchoring 12, 107, 309
PtGenList 120 blocking resources 12

348 Index September 20, 2005

 2005, QNX Software Systems Index

redirecting parentage 13 sample PtSampCompound

class widget 32
creation function 18 Set Resources method 67
constraint methods 79 Connection method 20, 50, 51, 60
example 45 chaining 22
exporting subordinate PtBasic 101
widgets 32, 88 PtCompound 115
initializing class structure 8 PtContainer 107
PtComboBox 83 PtGauge 136
PtTimer 73 PtGenList 118
setting up event-handling 5 PtGenTree 126
ShadowedBox 18, 271 PtGraphic 134
defining behavior of 5 PtLabel 130
hierarchy 11 PtMenu 60
pointer 8 PtSuperClassConnect() 306
resource table 51 PtSuperClassConnectFrom() 306
structure PtWidget 60, 62, 96
example 8–10 ShadowedBox 24
initializing 8 container widgets 12, 28, 74–81,
class-level callbacks See methods 105
clipping 59, 63, 64, 105, 254 anchoring 12, 28
balloon 133 balloons 57
disjoint widgets 49 child-constraint methods 29
PtClipAdd() 26, 260 child-redirector function 78
PtClipRemove() 26, 262 controlling children 12
PtGenList 144 exporting subordinate
Common User Access (CUA) 80 widgets 82
compound widgets 13, 30, 81–91, Extent method 29
114 Pt CONSUME EVENTS 105
blocking resources 82 Pt CONTAINER 48
Defaults method 32 redirector function 30
exporting subordinate conventions, typographical xvii
widgets 13, 30, 32, 82 CUA (Common User Access) 80
Get Resources method 68
PtCompoundRedirect() 263
Realization method 62

September 20, 2005 Index 349

Index  2005, QNX Software Systems

D PtContainer 107
PtGauge 137
Defaults method 50, 51, 56, 85 PtGenList 119
chaining 22 PtGenTree 126
compound widgets 32 PtGraphic 134
PtBasic 100 PtLabel 130
PtComboBox 84, 88 repairing damage 27
PtCompound 88, 115 ShadowedBox 24, 54
PtContainer 78, 79, 87, 106 using the Pg library safely 64
PtGauge 136
PtGenList 118
PtGenTree 126
PtGraphic 133 E
PtLabel 129
PtMenuBar 78 events
PtWidget 95 Connection method 96
ShadowedBox 10, 19, 54 consuming 105
Destruction method 27, 40, 50, 51, expose 49
67 focusing 110
chaining 22 handling in widget class 5
PtBasic 102 mask 109
PtButton 67 Ph EV BOUNDARY 72, 99
PtCompound 91, 115 Ph EV BUT PRESS 72, 102,
PtContainer 107 109
PtGauge 137 Ph EV BUT RELEASE 72, 103,
PtGenList 119 109
PtGenTree 126 Ph EV BUT REPEAT 72, 102,
PtGraphic 134 109
PtLabel 130 Ph EV KEY 109
PtWidget 96 Pt CB FILTER 109
Draw method 20, 50, 51, 55, 59, Pt CB RAW 71
62, 254, 307, 323 Pt CONSUME EVENTS 105
inheriting 22 PtEventHandler() 110
list widgets 141, 143, 144 PtGenList 121, 146, 147
PtBasic 101 Pt SET RAW CALLBACKS 103
PtButton 63 PtSuperClassRawEvent() 103,
PtCompound 115 315

350 Index September 20, 2005

 2005, QNX Software Systems Index

PtSuperClassRawEventFrom() 315 Pt CHILD LOSING FOCUS 77

raw callbacks 51, 71, 72, 103, Pt DAMAGE ON FOCUS 68
109, 236 Pt FOCUS RENDER 119
Extent method 20, 38, 50, 51, 58, Pt GEN LIST NO AUTOFOCUS
289, 309, 323 144
container widgets 29 Pt GETS FOCUS 110, 124
inheriting 22 Pt LIST SCROLLBAR GETS FOCUS
PtBasic 100 124
PtCompound 115, 118 Pt SELECTION MODE NOFOCUS
PtContainer 80, 107, 267 119, 145
PtDivider 118 PtSuperClassChildGettingFocus()
PtGauge 136 299
PtGenList 118 PtSuperClassChildLosingFocus()
PtGenTree 126 301
PtGraphic 134 PtSuperClassGotFocus() 312
PtLabel 130 PtSuperClassLostFocus() 68,
PtWidget 95 69, 314
ShadowedBox 23

G
F
Get Resources method 51, 68
focus 101 inheriting 22
Common User Access PtCompound 91
(CUA) 80 PtFindResourceRecord() 280
getting 23, 30, 53, 68, 75, 77, Got Focus method 68, 312
102, 110 inheriting 23
preventing 80 PtBasic 52, 53, 102
PtGenList 119 PtButton 68
losing 23, 30, 53, 69, 75, 77, PtCompound 116
102 PtContainer 108
PtGenList 119 PtGauge 137
Ph DIRECTED FOCUS 110 PtGenTree 126
Ph EV KEY 109 PtGraphic 134
PtBasic 4 PtLabel 131
Pt CHILD GETTING FOCUS 77

September 20, 2005 Index 351

Index  2005, QNX Software Systems

H List Inflate method

list widgets 148
header file PtGenList 121
example code 7 PtSuperClassGenListInflate()
hotkey callbacks 96, 98, 109, 236 182
freeing 276 List Key method
list widgets 141, 147
PtGenList 121
PtGenTree 128
I PtSuperClassGenListKey() 183
List Mouse method
Initialization method 20, 50, 51, 56
list widgets 141, 146
chaining 22
PtGenList 121
PtBasic 100
PtGenTree 128
PtCompound 115
PtSuperClassGenListMouse() 184
PtContainer 107
List Select method
PtGauge 136
list widgets 148
PtGenList 118
PtGenList 121
PtGenTree 126
PtSuperClassGenListSelect()
PtGraphic 134
185
PtLabel 130
list widgets 141–152. See also
PtWidget 95
PtGenList
ShadowedBox 23
methods
instance structure
Draw 141, 143, 144
example 7
List Draw 141, 143, 144,
setting/getting members 7
146
List Inflate 148
List Key 141, 147
L List Mouse 141, 146
List Select 148
List Draw method Lost Focus method 69, 314
list widgets 141, 143, 144, 146 inheriting 23
PtGenList 121 PtBasic 52, 53, 69, 102
PtGenTree 128, 189, 191 PtCompound 116
PtList 159 PtContainer 108
PtSuperClassGenListDraw() 181 PtGauge 137
tree widgets 189 PtGenTree 127

352 Index September 20, 2005

 2005, QNX Software Systems Index

PtGraphic 134 ShadowedBox 24

PtLabel 131 Defaults 50, 51, 56, 78, 85
chaining 22
compound widgets 32
PtBasic 100
M PtComboBox 84, 88
PtCompound 88, 115
methods 6, 8 PtContainer 78, 79, 87,
Calc Opaque Rect 70, 296 106
inheriting 23 PtGauge 136
PtBasic 52, 53, 70, 102 PtGenList 118
PtCompound 116 PtGenTree 126
PtContainer 108 PtGraphic 133
PtGauge 137 PtLabel 129
PtGenList 119 PtMenuBar 78
PtGenTree 127 PtWidget 95
PtGraphic 135 ShadowedBox 10, 19, 54
PtLabel 131 Destruction 27, 40, 50, 51, 67
chaining 21 chaining 22
stopping 21 PtBasic 102
child-constraint See PtButton 67
child-constraint methods PtCompound 91, 115
Connection 20, 50, 51, 60 PtContainer 107
chaining 22 PtGauge 137
PtBasic 101 PtGenList 119
PtCompound 115 PtGenTree 126
PtContainer 107 PtGraphic 134
PtGauge 136 PtLabel 130
PtGenList 118 PtWidget 96
PtGenTree 126 Draw 20, 50, 51, 55, 59, 62,
PtGraphic 134 254, 307, 323
PtLabel 130 inheriting 22
PtMenu 60 list widgets 141, 143, 144
PtSuperClassConnect() 306 PtBasic 101
PtSuperClassConnectFrom() PtButton 63
306 PtCompound 115
PtWidget 60, 62, 96 PtContainer 107

September 20, 2005 Index 353

Index  2005, QNX Software Systems

PtGauge 137 PtGenTree 126

PtGenList 119 PtGraphic 134
PtGenTree 126 PtLabel 131
PtGraphic 134 inheriting 21, 22
PtLabel 130 Initialization 20, 50, 51, 56
repairing damage 27 chaining 22
ShadowedBox 24, 54 PtBasic 100
using the Pg library PtCompound 115
safely 64 PtContainer 107
Extent 20, 29, 38, 50, 51, 58, PtGauge 136
289, 309, 323 PtGenList 118
inheriting 22 PtGenTree 126
PtBasic 100 PtGraphic 134
PtCompound 115, 118 PtLabel 130
PtContainer 80, 107, 267, PtWidget 95
309 ShadowedBox 23
PtDivider 118 List Draw
PtGauge 136 list widgets 141, 143, 144,
PtGenList 118 146
PtGenTree 126 PtGenList 121
PtGraphic 134, 309 PtGenTree 128, 189, 191
PtLabel 130, 309 PtList 159
PtWidget 95 PtSuperClassGenListDraw()
ShadowedBox 23 181
Get Resources 51, 68 tree widgets 189
inheriting 22 List Inflate
PtCompound 91 list widgets 148
PtFindResourceRecord() PtGenList 121
280 PtSuperClassGenListInflate()
Got Focus 68, 312 182
inheriting 23 List Key
PtBasic 52, 53, 102 list widgets 141, 147
PtButton 68 PtGenList 121
PtCompound 116 PtGenTree 128
PtContainer 108 PtSuperClassGenListKey()
PtGauge 137 183
PtGenList 119 List Mouse

354 Index September 20, 2005

 2005, QNX Software Systems Index

list widgets 141, 146 PtFindResourceRecord()

PtGenList 121 280
PtGenTree 128 Tree Draw Item
PtSuperClassGenListMouse() PtGenTree 128
184 PtSuperClassGenTreeDrawItem()
List Select 222
list widgets 148 tree widgets 189–191
PtGenList 121 Tree Item State
PtSuperClassGenListSelect() PtGenTree 128
185 PtSuperClassGenTreeItemState()
Lost Focus 69, 314 223
inheriting 23 tree widgets 191, 199, 201
PtBasic 52, 53, 69, 102 Unrealization 27, 49–51, 65
PtCompound 116 chaining 22
PtContainer 108 PtBasic 101
PtGauge 137 PtCompound 115
PtGenList 119 PtContainer 107, 266
PtGenTree 127 PtGauge 137
PtGraphic 134 PtGenList 119
PtLabel 131 PtGenTree 126
processing 21 PtGraphic 134
Realization 20, 51, 62, 316 PtLabel 66, 130
inheriting 22 PtMessage 65
PtBasic 101 PtWidget 65, 96
PtComboBox 90 ShadowedBox 27
PtCompound 90, 115
PtContainer 81, 107
PtGauge 137
PtGenList 119 P
PtGenTree 126
PtGraphic 134 pathname delimiter in QNX
PtLabel 130 Momentics documentation
PtWidget 96 xviii
ShadowedBox 24 Pg... functions 323
Set Resources 51, 67 Pg BITMAP BACKFILL 131
inheriting 22 PgFlush() 323
PtCompound 91 PgSetClipping() 64

September 20, 2005 Index 355

Index  2005, QNX Software Systems

PgSetDrawMode() 64 API functions 245

PgSetFillColor() 65 widget superclasses 11
PgSetFillDither() 65 PhRegionChange() 96, 98
PgSetFillTransPat() 65 Ph REGION CURSOR 98
PgSetFillXORColor() 65 PhRegionOpen() 96
PgSetMultiClip() 64 PtAddWidgetData() 250
PgSetPalette() 65 Pt ANCHORS INVALID 111
PgSetPlaneMask() 64 Pt ANCHORS LOCKED 111
PgSetRegion() 65, 323 PtAnchorWidget() 29, 252
PgSetStrokeCap() 64 PtApplyAnchors() 29, 253
PgSetStrokeColor() 65 PtArc
PgSetStrokeDash() 65 Pt UCLIP 64
PgSetStrokeDither() 65 Pt ARG DATA 88
PgSetStrokeJoin() 65 Pt ARG DIM 95, 232
PgSetStrokeTransPat() 65 Pt ARG DIVIDER OFFSET 120,
PgSetStrokeWidth() 65 123
PgSetStrokeXORColor() 65 Pt ARG DIVIDER SIZES 120
PgSetTextColor() 65 Pt ARG FLAGS 70, 102, 104, 323
PgSetTextTransPat() 65 Pt ARG IS ALLOC 39, 41, 97
PgSetTextXORColor() 65 Pt ARG IS ARRAY 40, 43, 97
PgSetTranslation() 64 Pt ARG IS BOOLEAN 40, 42
PgSetUnderline() 64 Pt ARG IS CALLBACK 40
PgSetUserClip() 64 Pt ARG IS CALLBACK LIST 40,
Pg TRANSPARENT 101 42, 97
PhAB, adding custom widgets 4, Pt ARG IS FLAGS 39, 40
227–241 Pt ARG IS LINK 39, 42, 97
Ph DIRECTED FOCUS 110 Pt ARG IS NUMBER 39, 40, 43
Ph EV BOUNDARY 72, 99, 103 Pt ARG IS POINTER 39, 41
Ph EV BUT PRESS 72, 102, 109, Pt ARG IS STRING 39, 41, 97
121 Pt ARG IS STRUCT 39, 41
Ph EV BUT RELEASE 72, 103, Pt ARG LIST COLUMN POS 120
109, 121 Pt ARG LIST FLAGS 124
Ph EV BUT REPEAT 72, 102, 109, Pt ARG POS 95, 232
121 Pt ARG TOP ITEM POS 142
Ph EV KEY 109, 121 PtAttemptResize() 59, 254
Ph EV PTR MOTION BUTTON 121 Pt AUTO EXTENT 113
Photon library Pt AUTOHIGHLIGHT 99, 102, 103

356 Index September 20, 2005

 2005, QNX Software Systems Index

Pt BALLOON AS REQUIRED 133 Pt CB

GEN TREE INPUT 128
PtBasic 99 Pt CB
GOT FOCUS 102
additional resources 53 Pt CB
LOST FOCUS 102
methods 55 Pt CB
MENU 102
Calc Opaque Rect 52, 53, Pt CB
RAW 71
70, 102 Pt CB
REALIZED 62
Connection 101 Pt CB
REPEAT 102
Defaults 100 Pt CB
RESCALE 135
Destruction 102 Pt CB
SCROLLED X 85
Draw 101 Pt CB
SCROLL MOVE 124
Extent 100 Pt CB
UNREALIZED 96
Got Focus 52, 53, 68, 102 Pt CHANGE CANVAS 38
Initialization 100 Pt CHANGE CANVAS REDRAW 38
Lost Focus 52, 53, 69, 102 Pt CHANGE INTERIOR 38
Realization 101 Pt CHANGE INVISIBLE 37
Unrealization 101 Pt CHANGE PREVENT 38
Pt DAMAGE ON FOCUS 68 Pt CHANGE REDRAW 38
subclassing 4 Pt CHANGE RESIZE 38, 58
widget actions 102 Pt CHANGE RESIZE REDRAW 38,
PtBasicWidgetCanvas() 59 58
Pt BITMAP 131 PtChildBoundingBox() 259
PtBkgdHandlerProcess() 323 Pt CHILD CREATED 75
Pt BLOCK CUA FOCUS 80 Pt CHILD DESTROYED 77
Pt BLOCKED 124 Pt CHILD GETTING FOCUS 77
PtButton Pt CHILD GETTING RESOURCE 77
methods Pt CHILD LOSING FOCUS 77
Destruction 67 Pt CHILD MOVED RESIZED 76
Draw 63 Pt CHILD REALIZED 76
widget actions 72 Pt CHILD SETTING RESOURCE 77
PtCalcAnchorOffsets() 256, 283 Pt CHILD UNREALIZED 76
PtCalcRegion() 257 Pt CLEAN RESOURCES 49
Pt CALLBACKS ACTIVE 120 PtClipAdd() 26, 64, 260
Pt CB ACTIVATE 72, 103 PtClippAdd() 64
Pt CB ARM 72, 102 PtClipRemove() 26, 64, 262
Pt CB DISARM 72, 102, 103 PtComboBox
Pt CB DIVIDER DRAG 120 class-creation function 83
Pt CB FILTER 109

September 20, 2005 Index 357

Index  2005, QNX Software Systems

exported subordinate Realization 81, 107

children 31 Unrealization 107, 266
methods widget actions 109
Defaults 84, 88 Pt CONTAINER 48
Realization 90 PtContainerChildRedirect() 78,
PtCompound 114 119, 264
methods Pt CONTAINER CONSTRAINT BITS 79
Calc Opaque Rect 116 PtContainerDeregister() 266
Connection 115 PtContainerHit() 109
Defaults 88, 115 PtContainerRegister() 107, 267
Destruction 91, 115 PtCoreChangeRegion() 268
Draw 115 PtCreateWidget() 17, 20, 56
Extent 115, 118 PtCreateWidgetClass() 19, 53, 270
Get Resources 91 PtDamageExposed() 273
Got Focus 116 PtDamageExtent() 165, 170
Initialization 115 Pt DAMAGE ON FOCUS 68, 102
Lost Focus 116 PtDamageWidget() 99, 323
Realization 90, 115 Pt DELAY REALIZE 81
Set Resources 91 PtDestroyCallbackList() 275
Unrealization 115 PtDestroyHotkeyCallbacks() 276
widget actions 116 PtDestroyRawCallbacks() 277
PtCompoundRedirect() 78, 87, 119, Pt DISJOINT 49
263 PtDivider
Pt CONSUME EVENTS 105 methods
PtContainer 74–81, 105 Extent 118
initializing 57 Pt END 73
methods See also Pt ETCH HIGHLIGHT 99
child-constraint methods PtEventHandler() 110
Calc Opaque Rect 108 PtExtentWidget() 118, 323
Connection 107 PtFindNextWidgetData() 278
Defaults 78, 79, 87, 106 PtFindResourceRecord() 280
Destruction 107 PtFindWidgetData() 282
Draw 107 Pt FOCUS RENDER 102, 119
Extent 80, 107, 267 Pt FORCE UNREALIZE 49
Got Focus 108 Pt FREE MEMORY 130
Initialization 107 PtGauge 136
Lost Focus 108 methods

358 Index September 20, 2005

 2005, QNX Software Systems Index

Calc Opaque Rect 137 PtGenListDrawBackground() 158

Connection 136 PtGenListDrawString() 159
Defaults 136 PtGenListFirstItem() 161
Destruction 137 Pt GEN LIST FULL WIDTH 144
Draw 137 PtGenListGetCurrent() 162
Extent 136 PtGenListGetSelIndexes() 163
Got Focus 137 PtGenListGoto() 142, 164
Initialization 136 PtGenListHold() 157, 165, 170
Lost Focus 137 Pt GEN LIST ITEM BACKGROUND
Realization 137 143
Unrealization 137 PtGenListItemIndex() 166
widget actions 137 PtGenListItemRealloc() 167
PtGenList 116, 141–152 PtGenListLastItem() 168
methods PtGenListLockItem() 142, 157,
Calc Opaque Rect 119 169, 179
Connection 118 Pt GEN LIST NO AUTOFOCUS 144
Defaults 118 Pt GEN LIST NO BACKGROUND 143
Destruction 119 Pt GEN LIST NO CLIPPING 144
Draw 119 PtGenListRelease() 157, 170
Extent 118 PtGenListRemoveItems() 171
Got Focus 119 PtGenListResize() 169, 173, 179
Initialization 118 PtGenListSelect() 142, 174
List Draw method 121 PtGenListSelectedItems() 175
List Inflate method 121 PtGenListSetColumnBalloon() 149
List Key method 121 PtGenListSetGflags() 143, 176
List Mouse method 121 PtGenListSetSelIndexes() 177
List Select method 121 PtGenListShow() 142, 178
Lost Focus 119 Pt GEN LIST SHOW DAMAGED 144,
Realization 119 158, 189
Unrealization 119 PtGenListUnlockItem() 142, 157,
widget actions 121 169, 179
PtGenListAddItems() 143, 153 PtGenListUnselect() 142, 180
PtGenListAllItems() 155 PtGenTree 125, 189–194
PtGenListClearSelection() 156 methods
PtGenListCreateTextBalloon() 149 Calc Opaque Rect 127
PtGenListDamageItem() 142, 157, Connection 126
165, 170 Defaults 126

September 20, 2005 Index 359

Index  2005, QNX Software Systems

Destruction 126 PtGenTreeSelectedItems() 217

Draw 126 PtGenTreeSetSelIndexes() 218
Extent 126 PtGenTreeShow() 219
Got Focus 126 PtGenTreeUnselect() 220
Initialization 126 PtGenTreeUnselectNonBrothers() 221
List Draw 128, 189, 191 PtGetAnchoredExtent() 283
List Key 128 PtGetResources() 38, 51
List Mouse 128 Pt GETS FOCUS 110, 124
Lost Focus 127 PtGetStruct() 285
Realization 126 Pt GHOST 104
Tree Draw Item 128 PtGraphic 133
Tree Item State 128 methods
Unrealization 126 Calc Opaque Rect 135
widget actions 128 Connection 134
PtGenTreeAddAfter() 195 Defaults 133
PtGenTreeAddFirst() 190, 196 Destruction 134
PtGenTreeAllItems() 197 Draw 134
PtGenTreeClearSelection() 198 Extent 134
PtGenTreeCollapse() 128, 191, 199 Got Focus 134
PtGenTreeDamageItem() 200 Initialization 134
PtGenTreeExpand() 128, 191, 192, Lost Focus 134
201 Realization 134
PtGenTreeExpandParents() 202 Unrealization 134
PtGenTreeFreeAllItems() 203 widget actions 135
PtGenTreeFreeItems() 204 PtGroup
PtGenTreeGetCurrent() 205 methods
PtGenTreeGetSelIndexes() 206 Child Created 75
PtGenTreeGoto() 207 Pt HALT 72
PtGenTreeItemIndex() 208 Pt HIGHLIGHTED 99, 101
PtGenTreeItemRealloc() 209 PtHold() 165
PtGenTreeItemResize() 210 Pt IGNORE CONSTRAINTS 75
PtGenTreeRemoveChildren() 211 Pt IMAGE 131
PtGenTreeRemoveItem() 212 Pt INDEX RESOURCES 49
PtGenTreeRemoveList() 213 PtInvokeCallbackList() 102, 287
PtGenTreeResize() 214 PtInvokeResizeCallbacks() 288
PtGenTreeRootItem() 215 PtLabel 129
PtGenTreeSelect() 216 methods

360 Index September 20, 2005

 2005, QNX Software Systems Index

Calc Opaque Rect 131 Unrealization 65

Connection 130 unexported subordinate
Defaults 129 children 56
Destruction 130 PtModifyFlags() 99
Draw 130 PtMoveResizeWidget() 289
Extent 130 Pt NO INHERITED RESOURCES 50
Got Focus 131 Pt OCCLUSIVE 50
Initialization 130 Pt OPAQUE 70, 100–102, 131, 296
Lost Focus 131 Pt PROCREATED 88
Realization 130 Pt QUERY PREVENT 39, 44
Unrealization 66, 130 PtRealizeWidget() 56, 58, 60, 323
widget actions 131 Pt RECTANGULAR 48, 70, 95, 102
PtList PtRelease() 170
methods PtRemoveWidgetData() 290
List Draw 159 PtResizePolicy() 291
Pt LIST BALLOONS IN COLUMNS Pt RESOURCE() 37
144 PtResourceRec t 37
Pt LIST INACTIVE 124 PtSampCompound
Pt LIST ITEM ABOVE 142 redirecting children 87
Pt LIST ITEM BELOW 142 redirecting resources 86
Pt LIST ITEM CURRENT 142 Pt SELECTION FLAGS 145
Pt LIST ITEM DAMAGED 128, Pt SELECTION MODE 144
142, 165, 170 Pt SELECTION MODE AUTO 119,
Pt LIST ITEM SELECTED 142, 216 145
Pt LIST ITEM USED FLAGS 142 Pt SELECTION MODE MULTIPLE 145
Pt LIST NON SELECT 124 Pt SELECTION MODE NOCLEAR 145
Pt LIST SCROLLBAR GETS FOCUS Pt SELECTION MODE NOFOCUS 119,
124 145
Pt LIST SNAP 118 Pt SELECTION MODE NOMOVE 145
PtMenu Pt SELECTION MODE NONE 144
methods Pt SELECTION MODE NOREST 145
Connection 60 Pt SELECTION MODE NOSCROLL 145
PtMenuBar Pt SELECTION MODE RANGE 145,
methods 148, 171, 177, 220
Defaults 78 Pt SELECTION MODE SINGLE 144
PtMessage Pt SELECTION MODE TOGGLE 145
methods Pt SELECT NOREDRAW 99

September 20, 2005 Index 361

Index  2005, QNX Software Systems

Pt SET 72, 99, 101, 102 Pt SET RAW CALLBACKS 51, 71,
PtSetArg() 38 103, 122
Pt SET BLOCKED RESOURCES 83, Pt SET REALIZED F 51
115 Pt SET RESOURCES 51, 54
Pt SET CALC OPAQUE F 53 PtSetResources() 38, 51, 96, 323
Pt SET CHILD CREATED F 75 Pt SET SETRESOURCES F 51
Pt SET CHILD DESTROYED F 75 Pt SET STATE LEN 51, 54
Pt SET CHILD GETTING FOCUS F PtSetStruct() 98, 293, 295
75 Pt SET SUBORDINATES 83, 88,
Pt SET CHILD GETTINGRESOURCE F 114
75 Pt SET UNREALIZE F 51
Pt SET CHILD LOSING FOCUS F PtSetValue() 293, 295
75 Pt SET VERSION 51, 54
Pt SET CHILD MOVED RESIZED F Pt SHOW BALLOON 130, 132
75 PtSuperClassCalcOpaque() 131,
Pt SET CHILD REALIZED F 75 296
Pt SET CHILD SETTINGRESOURCE F PtSuperClassChildCreated() 297
75 PtSuperClassChildDestroyed() 298
Pt SET CHILD UNREALIZED F 75, PtSuperClassChildGettingFocus() 299
96 PtSuperClassChildGettingResources()
Pt SET CONNECT F 51 300
Pt SET DESTROY F 51 PtSuperClassChildLosingFocus() 301
Pt SET DFLTS F 51, 54 PtSuperClassChildMovedResized() 302
Pt SET DRAW F 51, 54 PtSuperClassChildRealized() 303
Pt SET EXTENT F 51 PtSuperClassChildSettingResources()
PtSetExtentFromArea() 292 304
PtSET FLAGS 51, 54 PtSuperClassChildUnrealized() 305
Pt SET GETRESOURCES F 51 PtSuperClassConnect() 306
Pt SET GOT FOCUS F 53 PtSuperClassConnectFrom() 306
Pt SET INIT F 51 PtSuperClassDraw() 25, 130, 307
Pt SET LOST FOCUS F 53 PtSuperClassExtent() 100, 107,
Pt SET NUM BLOCKED RESOURCES 118, 309
83, 114 PtSuperClassGenListDraw() 181
Pt SET NUM RESOURCES 51, 54 PtSuperClassGenListInflate() 182
Pt SET NUM SUBORDINATES 82, PtSuperClassGenListKey() 183
88, 114 PtSuperClassGenListMouse() 184
PtSuperClassGenListSelect() 185

362 Index September 20, 2005

 2005, QNX Software Systems Index

PtSuperClassGenTreeDrawItem() 222 Initialization 95

PtSuperClassGenTreeItemState() 223 Realization 96
PtSuperClassGetResources() 311 Unrealization 65, 96
PtSuperClassGotFocus() 119, 312 widget actions 97
PtSuperClassInit() 313 PtWidgetAbove() 320
PtSuperClassInitFrom() 313 PtWidgetOffset() 63
PtSuperClassLostFocus() 68, 69, Pt WIDGET RESIZE 133, 323
119, 314 Pt Z STRING 130, 131
PtSuperClassRawEvent() 103, 122,
315
PtSuperClassRawEventFrom() 315
PtSuperClassRealized() 316 R
PtSuperClassSetResources() 104,
293, 295, 317 raw callbacks 51, 71, 72, 103, 113,
Pt TEXT IMAGE 130 122, 236, 315
PtTimer freeing 277
widget actions 73 PtBasic 102
Pt TREE COLLAPSING 191, 192 PtCompound 116
Pt TREE EXPANDING 191 PtContainer 109
Pt TREE ITEM EXPANDABLE 190, PtGauge 137
196, 212 PtGenTree 128
Pt TREE ITEM EXPANDED 190, PtGraphic 135
192 PtLabel 131
Pt TREE TO RIGHT 129 PtWidget 97
Pt UCLIP 59, 64, 254 Realization method 20, 51, 62, 316
Pt UNCLEAN RESOURCES 49 inheriting 22
PtUpdate() 98 PtBasic 101
PtUpdateVisibility() 105 PtComboBox 90
Pt USER() 36, 37 PtCompound 90, 115
PtValidParent() 87 PtContainer 81, 107
PtWidget 58, 95 PtGauge 137
extending 52 PtGenList 119
methods 55 PtGenTree 126
Connection 60, 62, 96 PtGraphic 134
Defaults 95 PtLabel 130
Destruction 96 PtWidget 96
Extent 95 ShadowedBox 24

September 20, 2005 Index 363

Index  2005, QNX Software Systems

redirector function 12 PtGraphic 135

child 30, 78, 87 Pt INDEX RESOURCES 49
setting 264 PtLabel 131
resource 85 Pt NO INHERITED RESOURCES
resize callbacks 107 50
invoking 288 PtSetStruct() 293
resources PtSetValue() 295
blocking 31, 82, 83, 86, 114, PtSuperClassChildGettingResources()
115 300
children 12 PtSuperClassChildSettingResources()
exported subordinates 13 304
causing damage 27 PtSuperClassGetResources() 311
Child Getting Resource PtSuperClassSetResources() 317
method 77 Pt UNCLEAN RESOURCES 49
Child Setting Resource records 37
method 77 redirector function 85
class resource table 51 Set Resources method 67, 91
default values in PhAB 239 types 39
defining 5, 19, 35
describing in PhAB 230, 232
editing in PhAB 227, 228
freeing 67, 96 S
freeing memory 40
Get Resources method 68 Set Resources method 51, 67
getting 85 inheriting 22
inheriting 5, 237 PtCompound 91
manifests 36 PtFindResourceRecord() 280
numbers 36 ShadowedBox
PtBasic 103 class resource table 53
Pt CLEAN RESOURCES 49 class structure 8
PtContainer 111 class-creation function 18, 271
PtCreateWidget() 20 defined 6–10
PtFindResourceRecord() 280 life cycle 17
PtGauge 137 methods
PtGenList 122 chaining 21
PtGenTree 128 Connection 24
PtGetStruct() 285 Defaults 10, 19, 54

364 Index September 20, 2005

 2005, QNX Software Systems Index

Draw 24, 54 PtSuperClassGenTreeDrawItem()

Extent 23 222
inheriting 22 tree widgets 189–191
Initialization 23 Tree Item State method
Realization 24 PtGenTree 128
Unrealization 27 PtSuperClassGenTreeItemState()
resource declarations 43 223
source file 8 tree widgets 191, 199, 201
sample code 8–10 tree widgets 189–194. See also
structures PtGenTree
class 8 methods
instance 7 List Draw 189
subordinate widgets Tree Draw Item 189–191
blocking resources 13, 31 Tree Item State 191, 199,
exported 13, 30, 82, 114 201
blocking resources 86 typographical conventions xvii
creating 88
distinguishing resources 85
identifying 32
Pt ARG DATA 88 U
Pt PROCREATED 88
Pt SET NUM SUBORDINATES 88, Unrealization method 27, 49–51,
114 65
Pt SET SUBORDINATES 88, chaining 22
114 PtBasic 101
PtValidParent() 87 PtCompound 115
realizing 90 PtContainer 107, 266
setting resources 323 PtGauge 137
unexported 56 PtGenList 119
PtGenTree 126
PtGraphic 134
PtLabel 66, 130
T PtMessage 65
PtWidget 65, 96
tips for building widgets 323 ShadowedBox 27
Tree Draw Item method
PtGenTree 128

September 20, 2005 Index 365

Index  2005, QNX Software Systems

W freeing 67, 96
freeing memory 40
widgets Get Resources method 68,
actions 51, 71 91
adding to PhAB 227–241 getting 85
basic 11 inheriting 5, 237
categories 11 manifests 36
classes numbers 36
defining 47–54 PtBasic 103
methods 55–71 Pt CLEAN RESOURCES 49
compound 13 PtContainer 111
container 12 PtCreateWidget() 20
data chain 250, 278, 282, 290 PtFindResourceRecord()
description table 230 280
designing 4 PtGauge 137
handling events 51, 71 PtGenList 122
instantiating 17 PtGenTree 128
life cycle 17 PtGetStruct() 285
main components 6 PtGraphic 135
managing children 12 Pt INDEX RESOURCES 49
reasons to customize 3 PtLabel 131
redirecting 13 Pt NO INHERITED RESOURCES
repairing damage 27 50
resources PtSetStruct() 293
blocking 12, 13, 31, 82, 83, PtSetValue() 295
86, 114, 115 PtSuperClassChildGettingResources()
causing damage 27 300
Child Getting Resource PtSuperClassChildSettingResources()
method 77 304
Child Setting Resource PtSuperClassGetResources()
method 77 311
class resource table 51 PtSuperClassSetResources()
default values in PhAB 239 317
defining 5, 19, 35 Pt UNCLEAN RESOURCES
describing in PhAB 230, 49
232 records 37
editing in PhAB 227, 228

366 Index September 20, 2005

 2005, QNX Software Systems Index

Set Resources method 67,

91
subclassing 4
PtBasic 4
PtCompound 13
PtContainer 12
PtGenList 116
PtWidget 11
superclass types 11
tips for building 323

September 20, 2005 Index 367