Photon microGUI

Library Reference

For Photon 1.14

 2005, QNX Software Systems

 1996 – 2005, QNX Software Systems. All rights reserved.

Published under license by:

QNX Software Systems Co.

175 Terence Matthews Crescent
Kanata, Ontario
K2M 1W8
Canada
Voice: +1 613 591-0931
Fax: +1 613 591-3579
Email: [email protected]
Web: http://www.qnx.com/

Publishing history
December 1996 First edition
April 1998 Second edition

Electronic edition published 2005.

Technical support options

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

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

About This Reference xxi

Typographical conventions xxiii
Note to Windows users xxiv
What you’ll find in this reference xxv
Assumptions xxvi

1 Summary of Entries 1
Categories 3
Entries arranged by category 7
Background processing 7
Bitmaps and Images 7
Blitting 8
Characters, translating 8
Clipboard operations 9
Clipping 9
Colors — converting and parsing 10
Configuration files 11
Coordinates, translating 12
Cursors/pointers 13
Data chains 13
Dragging 13
Draw contexts 14
Drawing attributes 14
Events 16
Font handling 17

September 20, 2005 Contents iii

  2005, QNX Software Systems

Geometry 18
Graphical contexts 19
Input/Output events 19
Interprocess Communication (IPC) 20
Jump Gates 21
Key events, translating 21
Memory contexts 21
Messages and questions 22
Modal dialogs 22
Modules 23
Multibyte-character strings 23
Online help 24
Photon Application Builder functions 24
Photon services, connecting and disconnecting 25
Primitive drawing routines 25
Printing 27
Processes 27
Regions 28
Shared memory 29
Signals 29
Strings, translating 29
System information 30
Text 30
Tiles 30
Wide characters 31
Widgets 31
Window Manager 60

2 Ap — PhAB 63
ApAddClass() 66
ApAppendTranslation() 68
ApBitmap t 70
ApCloseDBase() 72

iv Contents September 20, 2005

 2005, QNX Software Systems

ApCopyWidget() 74
ApCreateModule() 76
ApCreateWidget() 80
ApCreateWidgetFamily() 83
ApDeleteWidget() 86
ApError() 88
ApFreeBitmapRes() 91
ApGetBitmapRes() 93
ApGetImageRes() 96
ApGetInstance() 98
ApGetItemText() 100
ApGetTextRes() 102
ApGetWidgetPtr() 104
ApInfo t 106
ApInstanceName() 108
ApModifyItemState() 110
ApModifyItemText() 112
ApModuleFunction() 114
ApModuleLocation() 116
ApModuleParent() 118
ApName() 120
ApOpenDBase(), ApOpenDBaseFile() 122
ApResClose() 124
ApSaveDBaseFile() 125
ApSetTranslation() 127
ApWidget() 129

3 mbstr — Multibyte-Character 131

mbstrblen() 134
mbstrchr() 136
mbstrlen() 138
mbstrnchr() 139
mbstrncmp() 141

September 20, 2005 Contents v

  2005, QNX Software Systems

mbstrnlen() 142
mbstrrchr() 144

4 Pf — Font Server 147

PfAttach() 150
PfDetach() 152
PfExtentComponents() 153
PfExtentText() 155
PfFractionalExtentText() 157
PfFractionalRenderText() 159
PfGlyph() 161
PfLoadFont() 163
PfLoadMetrics() 165
PfQueryFont() 166
PfQueryFonts() 168
PfRenderText() 171
PfUnloadMetrics() 173

5 Pg — Graphics 175
PgBackgroundShadings() 178
PgBlueValue() 179
PgClearDrawBuffer() 180
PgClearTranslation() 182
PgCMY() 183
PgColor t 185
PgColorHSV t 187
PgColorMatch() 188
PgCreateGC() 189
PgDefaultFill() 190
PgDefaultGC() 191
PgDefaultMode() 192
PgDefaultStroke() 193
PgDefaultText() 194

vi Contents September 20, 2005

 2005, QNX Software Systems

PgDestroyGC() 195
PgDrawArc() 196
PgDrawBevelBox(), PgDrawIBevelBox() 200
PgDrawBeveled() 203
PgDrawBezier(), PgDrawBeziermx() 207
PgDrawBitmap(), PgDrawBitmapmx() 210
PgDrawEllipse() 213
PgDrawGrid() 216
PgDrawImage(), PgDrawImagemx() 218
PgDrawLine(), PgDrawILine() 221
PgDrawPhImagemx() 223
PgDrawPixel(), PgDrawIPixel() 225
PgDrawPixelArray(), PgDrawPixelArraymx() 226
PgDrawPolygon(), PgDrawPolygonmx() 228
PgDrawRect(), PgDrawIRect() 232
PgDrawRepBitmap(), PgDrawRepBitmapmx() 235
PgDrawRepImage(), PgDrawRepImagemx() 239
PgDrawRoundRect() 242
PgDrawSpan(), PgDrawSpanmx() 245
PgDrawString(), PgDrawStringmx() 248
PgDrawText(), PgDrawTextmx(), PgDrawTextChars() 250
PgDrawTextArea() 255
PgDrawTImage(), PgDrawTImagemx() 257
PgDrawTrend(), PgDrawTrendmx() 259
PgExtentText() 262
PgFlush(), PgFFlush() 264
PgGetGC() 266
PgGetPalette() 267
PgGray() 268
PgGrayValue() 270
PgGreenValue() 271
PgHSV() 272

September 20, 2005 Contents vii

  2005, QNX Software Systems

PgHSV2RGB() 275
PgRedValue() 276
PgRGB() 277
PgRGB2HSV() 279
PgSetClipping() 281
PgSetDrawBufferSize() 283
PgSetDrawMode() 285
PgSetFillColor() 287
PgSetFillDither() 289
PgSetFillTransPat() 293
PgSetFillXORColor() 295
PgSetFont() 297
PgSetGC() 299
PgSetMultiClip() 300
PgSetPalette() 302
PgSetPlaneMask() 305
PgSetRegion() 307
PgSetStrokeCap() 308
PgSetStrokeColor() 310
PgSetStrokeDash() 311
PgSetStrokeDither() 314
PgSetStrokeJoin() 316
PgSetStrokeTransPat() 319
PgSetStrokeWidth(), PgSetStrokeFWidth() 320
PgSetStrokeXORColor() 322
PgSetTextColor() 323
PgSetTextDither() 324
PgSetTextTransPat() 326
PgSetTextXORColor() 327
PgSetTranslation() 328
PgSetUnderline() 330
PgSetUserClip(), PgSetUserClipAbsolute() 332

viii Contents September 20, 2005

 2005, QNX Software Systems

PgShmemAttach() 334
PgShmemCleanup() 336
PgShmemCreate() 338
PgShmemDestroy() 340
PgShmemDetach() 341

6 Ph — Photon 343
PhAddMergeTiles() 346
PhArea t 348
PhAttach() 349
PhBlit() 353
PhChannelAttach() 355
PhClipboardCopy() 357
PhClipboardCopyString() 359
PhClipboardPasteFinish() 361
PhClipboardPasteStart() 362
PhClipboardPasteString() 364
PhClipboardPasteType() 366
PhClipboardPasteTypeN() 368
PhClipHeader 370
PhClipTilings() 371
PhCoalesceTiles() 373
PhCopyTiles() 374
PhDCGetCurrent() 375
PhDCSetCurrent() 376
PhDetach() 379
PhDeTranslateTiles() 380
PhDim t 381
PhEvent t 382
PhEventArm() 400
PhEventEmit() 401
PhEventEmitmx() 404
PhEventNext() 407

September 20, 2005 Contents ix

  2005, QNX Software Systems

PhEventPeek() 409
PhEventRead() 411
PhEventRegion t 414
PhFreeTiles() 415
PhGetConnectId() 416
PhGetConnectInfo() 417
PhGetData() 419
PhGetMsgSize() 420
PhGetRects() 422
PhGetTile() 423
PhImage t 424
PhInitDrag() 430
PhIntersectTilings() 433
PhKeyEvent t 434
PhKeyToMb() 438
PhLibVersion() 439
PhMakeGhostBitmap() 441
PhMakeTransBitmap() 442
PhMergeTiles() 446
PhMoveCursorAbs() 447
PhMoveCursorRel() 449
PhPoint t 451
PhQueryCursor() 452
PhQueryRids() 455
PhQuerySystemInfo() 459
PhReattach() 461
PhRect t 463
PhRectsToTiles() 464
PhRegion t 465
PhRegionChange() 470
PhRegionClose() 472
PhRegionDataFindType() 473

x Contents September 20, 2005

 2005, QNX Software Systems

PhRegionDataHdr t 474
PhRegionOpen() 476
PhRegionQuery() 481
PhReleaseImage() 483
PhSortTiles() 485
PhTile t 486
PhTilesToRects() 487
PhTimerArm() 488
PhTo8859 1() 490
PhTranslateTiles() 491
PhWindowChange() 492
PhWindowClose() 494
PhWindowEvent t 495
PhWindowOpen() 499
PhWindowQueryVisible() 501

7 Pm — Memory 503
PmMemCreateMC() 506
PmMemFlush() 510
PmMemReleaseMC() 512
PmMemSetChunkSize() 513
PmMemSetMaxBufSize() 514
PmMemSetType() 515
PmMemStart() 516
PmMemStop() 518

8 Pp — Printing 519
PpLoadPrinter() 522
PpPrintClose() 524
PpPrintCreatePC() 526
PpPrintGetPC() 528
PpPrintNewPage() 532
PpPrintOpen() 534

September 20, 2005 Contents xi

  2005, QNX Software Systems

PpPrintReleasePC() 536
PpPrintSetPC() 537
PpPrintStart() 543
PpPrintStop() 546
PpPrintWidget() 547

9 Pt — Widget Toolkit 551

PtAddCallback() 554
PtAddCallbacks() 556
PtAddData() 558
PtAddEventHandler() 560
PtAddEventHandlers() 562
PtAddHotkeyHandler() 563
PtAppAddFd(), PtAppAddFdPri() 567
PtAppAddInput() 570
PtAppAddSignalProc() 574
PtAppAddWorkProc() 576
PtAppCreatePulse() 580
PtAppDeletePulse() 582
PtAppInit() 584
PtAppPulseTrigger() 586
PtAppRemoveFd() 588
PtAppRemoveInput() 589
PtAppRemoveSignal() 590
PtAppRemoveSignalProc() 592
PtAppRemoveWorkProc() 594
PtAppSetFdMode() 596
PtArg t 598
Pt ARG() 599
PtAskQuestion() 601
PtBasicWidgetCanvas() 604
PtBkgdHandlerProcess() 606
PtCalcAbsPosition() 608

xii Contents September 20, 2005

 2005, QNX Software Systems

PtChannelCreate() 610
PtChildType() 611
PtClearWidget() 613
PtConsoleSwitch() 615
PtContainerBox() 617
PtContainerFindFocus() 619
PtContainerFocusNext() 620
PtContainerFocusPrev() 622
PtContainerGiveFocus() 624
PtContainerHit() 629
PtContainerHold() 631
PtContainerNullFocus() 633
PtContainerRelease() 635
PtCreateWidget() 637
PtDamageExtent() 639
PtDamageWidget() 641
PtDestroyWidget() 643
PtDeTranslateRect() 645
PtEndFlux() 646
PtEventHandler() 648
PtExtentWidget() 649
PtExtentWidgetFamily() 650
PtFdProcF t, PtFdProc t 651
PtFileSelection() 652
PtFindChildClass() 661
PtFindChildClassMember() 663
PtFindContainer() 665
PtFindData() 666
PtFindDisjoint() 667
PtFindFocusChild() 669
PtFindGuardian() 670
PtFindNextData() 672

September 20, 2005 Contents xiii

  2005, QNX Software Systems

PtFlush() 674
PtFontSelection() 675
PtForwardWindowEvent() 678
PtForwardWindowTaskEvent() 680
PtFrameSize() 682
PtGetAbsPosition() 684
PtGetControlFlags() 685
PtGetParent() 686
PtGetParentWidget() 688
PtGetRcvidPid() 689
PtGetResources() 691
PtGlobalFocusNext() 693
PtGlobalFocusNextContainer() 694
PtGlobalFocusNextFrom() 695
PtGlobalFocusPrev() 697
PtGlobalFocusPrevContainer() 698
PtGlobalFocusPrevFrom() 699
PtHit() 701
PtHold() 702
PtInflateBalloon() 704
PtInit() 706
PtInputCallbackProcF t, PtInputCallbackProc t 708
PtIsFluxing() 709
PtIsFocused() 710
PtLabelWidgetCanvas() 711
PtMainLoop() 713
PtMessageBox() 714
PtModalEnd() 715
PtModalStart() 716
PtNextTopLevelWidget() 719
PtPositionMenu() 720
PtPrintSelection() 721

xiv Contents September 20, 2005

 2005, QNX Software Systems

PtProcessEvent() 724
PtPulseArmFd() 725
PtPulseArmPid() 727
PtPulseDeliver() 729
PtPulseDisarm() 731
PtQuerySystemInfo() 732
PtRealizeWidget() 734
PtReattach() 736
PtRectIntersect() 738
PtRectUnion() 739
PtRelease() 740
PtRemoveCallback() 741
PtRemoveCallbacks() 743
PtRemoveData() 745
PtRemoveEventHandler() 747
PtRemoveEventHandlers() 749
PtRemoveHotkeyHandler() 750
PtReParentWidget() 752
PtReRealizeWidget() 754
PtResizeEventMsg() 755
PtSendEventToWidget() 757
PtSetAreaFromExtent() 759
PtSetAreaFromWidgetCanvas() 761
PtSetArg() 762
PtSetParentWidget() 764
PtSetResources() 766
PtSignalProcF t, PtSignalProc t 768
PtSpawn() 769
PtSpawnDeleteCallback() 772
PtSpawnSetCallback() 773
PtSpawnWait() 774
PtStartFlux() 776

September 20, 2005 Contents xv

  2005, QNX Software Systems

PtSyncPhoton() 777
PtSyncWidget() 779
PtTimerArm() 780
PtTranslateRect() 781
PtUnlinkData() 782
PtUnrealizeWidget() 783
PtUpdate() 784
PtValidParent() 785
PtWidgetArea() 787
PtWidgetBrotherBehind() 788
PtWidgetBrotherInFront() 789
PtWidgetCanvas() 790
PtWidgetChildBack() 792
PtWidgetChildFront() 794
PtWidgetClass() 795
PtWidgetClassFlags() 797
PtWidgetDim() 799
PtWidgetExtent() 800
PtWidgetFamily() 802
PtWidgetFlags() 804
PtWidgetHelpHit() 805
PtWidgetInsert() 806
PtWidgetIsClass() 808
PtWidgetIsClassMember() 810
PtWidgetIsRealized() 812
PtWidgetOffset() 813
PtWidgetParent() 815
PtWidgetRid() 817
PtWidgetSkip() 818
PtWidgetToBack() 820
PtWidgetToFront() 822
PtWidgetTree() 824

xvi Contents September 20, 2005

 2005, QNX Software Systems

PtWidgetTreeTraverse() 826
PtWidgetVisibleExtent() 830
PtWindowConsoleSwitch() 831
PtWorkProcF t, PtWorkProc t 832

10 Px — Extended 833
PxConfigClose() 836
PxConfigDeleteEntry() 837
PxConfigDeleteSection() 838
PxConfigForceEmptySection() 840
PxConfigNextSection() 842
PxConfigNextString() 844
PxConfigOpen() 846
PxConfigReadBool() 849
PxConfigReadChar() 851
PxConfigReadInt() 853
PxConfigReadLong() 855
PxConfigReadShort() 857
PxConfigReadString() 859
PxConfigSection() 861
PxConfigWriteBool() 862
PxConfigWriteChar() 864
PxConfigWriteInt() 866
PxConfigWriteLong() 868
PxConfigWriteShort() 870
PxConfigWriteString() 872
PxCRC() 874
PxHelpQuit() 875
PxHelpSearch() 876
PxHelpTopic() 879
PxHelpTopicRoot() 881
PxHelpTopicTree() 882
PxHelpUrl() 884

September 20, 2005 Contents xvii

  2005, QNX Software Systems

PxHelpUrlRoot() 886
PxLoadImage() 887
PxTerminalBuildCharsets() 895
PxTerminalLoadCharsets() 897
PxTerminalSaveCharsets() 899
PxTranslateFromUTF() 901
PxTranslateList() 904
PxTranslateSet() 906
PxTranslateStateFromUTF() 909
PxTranslateStateToUTF() 911
PxTranslateToUTF() 913
PxTranslateUnknown() 916

11 wc — Wide-Character 919
wctolower() 922

Glossary 923

Index 945

xviii Contents September 20, 2005

 List of Figures
Predefined dither patterns. 290
Styles for capping lines. 308
Styles for joining lines. 317
Numbering for Photon’s virtual consoles. 615
An example of the dialog created by PtFileSelection(). 655

September 20, 2005 List of Figures xix

 About This Reference

September 20, 2005 About This Reference xxi

 2005, QNX Software Systems Typographical conventions

Typographical conventions
Throughout this manual, we use certain typographical conventions to
distinguish technical terms. In general, the conventions we use
conform to those found in IEEE POSIX publications. The following
table summarizes our conventions:

Reference Example
Code examples if( stream == NULL )
Command options -lR
Commands make
Environment variables PATH
File and pathnames /dev/null
Function names exit()
Keyboard chords Ctrl – Alt – Delete
Keyboard input something you type
Keyboard keys Enter
Program output login:
Programming constants NULL
Programming data types unsigned short
Programming literals 0xFF, "message string"
Variable names stdin
User-interface components Cancel

We format single-step instructions like this:

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

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

September 20, 2005 About This Reference xxiii

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.

xxiv About This Reference September 20, 2005

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

What you’ll find in this reference

The Photon Library Reference accompanies the Photon Development
System and is intended for application developers. It describes the
data types, structures, and functions that are defined in the Photon
API.
This reference contains the following chapters:

¯ Summary of Entries

¯ Ap — PhAB

¯ mbstr — Multibyte-Character

¯ Pf — Font Server

¯ Pg — Graphics

¯ Ph — Photon

¯ Pm — Memory

¯ Pp — Printing

¯ Pt — Widget Toolkit

¯ Px — Extended

¯ wc — Wide-Character

¯ Glossary

☞ ¯ For functions that deal with specific widgets, see the Widget
Reference.

¯ For functions that deal with creating widget classes, see Building
Custom Widgets.

In general, the Photon libraries aren’t thread-safe. In a multithreaded

program, only the thread that called PtInit() is allowed to call Photon

September 20, 2005 About This Reference xxv

Assumptions  2005, QNX Software Systems

functions. The only exception is PtPulseDeliver() — you can use it in

other threads to send notifications to the Photon thread.
To use the datatypes and functions in an application:

¯ If you’re using the Photon Application Builder (PhAB), the

appropriate header files are automatically included in your
application.

¯ If you aren’t using PhAB but your application uses widgets,

include <Pt.h>.

¯ If you aren’t using PhAB or widgets, include <Ph.h>.

Assumptions
We assume the following:

¯ The Photon microGUI and the Photon Development System are

installed on your system. If they aren’t, see the installation notes
that came with your software.

¯ You already know the basics of using Photon. If not, see the
Photon User’s Guide.

xxvi About This Reference September 20, 2005

 Chapter 1
Summary of Entries

In this chapter. . .
Categories 3
Entries arranged by category 7

September 20, 2005 Chapter 1 ¯ Summary of Entries 1

 2005, QNX Software Systems Categories

This chapter groups the datatypes and functions according to their

purpose. You can use this chapter to determine what you need to
perform a task.
The first two letters of a datatype’s or function’s name identify the
chapter in which it’s described, as follows:

If prefix is: See the following chapter:

Ap PhAB
mbstr Multibyte-Character
Pf Font Server
Pg Graphics
Ph Photon
Pm Memory
Pp Printing
Pt Widget Toolkit
Px Extended
wc Wide-Character

☞ ¯ For datatypes and functions that deal with specific widgets, see the
Widget Reference.

¯ For functions that deal with creating widget classes, see Building
Custom Widgets.

Categories
The following categories have been used to group the datatypes and
functions:

¯ Background processing

September 20, 2005 Chapter 1 ¯ Summary of Entries 3

Categories  2005, QNX Software Systems

¯ Bitmaps and Images

¯ Blitting

¯ Characters, translating

¯ Clipboard operations

¯ Clipping

¯ Colors — converting and parsing

¯ Configuration files

¯ Coordinates, translating

¯ Cursors/pointers

¯ Data chains

¯ Dragging

¯ Draw contexts

¯ Drawing attributes
- Fill attributes
- Stroke (line) attributes

¯ Events

¯ Font handling

¯ Geometry

¯ Graphical contexts

¯ Input/Output events

¯ Interprocess Communication (IPC)

¯ Jump Gates

¯ Key events, translating

4 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Categories

¯ Memory contexts

¯ Messages and questions

¯ Modal dialogs

¯ Modules

¯ Multibyte-character strings

¯ Online help

¯ Photon Application Builder functions

¯ Photon services, connecting and disconnecting

¯ Primitive drawing routines

¯ Printing

¯ Processes

¯ Regions

¯ Shared memory

¯ Signals

¯ Strings, translating

¯ System information

¯ Text

¯ Tiles

¯ Wide characters

¯ Widgets:
- Callbacks and hotkey handlers
- Class hierarchy
- Creating and destroying

September 20, 2005 Chapter 1 ¯ Summary of Entries 5

Categories  2005, QNX Software Systems

- Custom widgets
- Damaging
- Databases
- Family hierarchy
- Finding in an area
- Focus
- Geometry
- Library initialization
- Menus
- PtComboBox
- PtFileSel
- PtGenList
- PtGenTree
- PtHtml
- PtList
- PtMessage
- PtMultiText
- PtTerminal
- PtText
- PtTree
- PtTty
- PtWindow
- Realizing and unrealizing
- Resources
- RtTrend
- Updates — forcing and holding off

¯ Window Manager

6 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

Entries arranged by category

Background processing
PtAppAddWorkProc()
Add a WorkProc (background) function

PtAppRemoveWorkProc()
Remove a WorkProc processing function

PtWorkProcF t, PtWorkProc t
Pointer to a work procedure function

Bitmaps and Images

PgDrawBitmap(), PgDrawBitmapmx()
Draw a bitmap

PgDrawImage(), PgDrawImagemx()
Draw an image

PgDrawPhImagemx()
Draw an image that’s contained in a PhImage t
structure
PgDrawTImage(), PgDrawTImagemx()
Draw an image with a transparency mask

PgDrawRepBitmap(), PgDrawRepBitmapmx()
Draw a bitmap several times

PgDrawRepImage(), PgDrawRepImagemx()
Draw an image several times

PhImage t Data and characteristics of an image

PhMakeGhostBitmap()
Create a ghost bitmap for an image

September 20, 2005 Chapter 1 ¯ Summary of Entries 7

Entries arranged by category  2005, QNX Software Systems

PhMakeTransBitmap()
Create a transparency mask for an image
PhReleaseImage()
Release allocated members of an image structure
PxCRC() Calculate a CRC for a block of data

PxLoadImage()
Read or query a graphic file

Blitting
PhBlit() Blit an area within a region

Characters, translating
PxTerminalBuildCharsets()
Create character set tables based on translation tables
PxTerminalLoadCharsets()
Load character-set information from a file
PxTerminalSaveCharsets()
Save character-set information in a file
PxTranslateFromUTF()
Translate characters from Unicode UTF-8
PxTranslateList()
Create a list of all supported character translations
PxTranslateSet()
Install a new character set translation
PxTranslateStateFromUTF()
Translate characters from UTF-8, using an internal state buffer
PxTranslateStateToUTF()
Translate characters to UTF-8, using an internal state buffer

8 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

PxTranslateToUTF()
Translate characters to UTF-8
PxTranslateUnknown()
Control how unknown encodings are handled

Clipboard operations
PhClipboardCopy()
Copy data to the clipboard

PhClipboardCopyString()
Copy string-only data to the clipboard

PhClipboardPasteFinish()
Release all memory associated with a paste operation

PhClipboardPasteStart()
Begin a paste operation

PhClipboardPasteString()
Paste string-only data from the clipboard

PhClipboardPasteType()
Search clipboard for an entry by type

PhClipboardPasteTypeN()
Search clipboard for an entry by order

PhClipHeader
Clipboard header structure

Clipping
PgSetClipping()
Limit the extent of drawing

September 20, 2005 Chapter 1 ¯ Summary of Entries 9

Entries arranged by category  2005, QNX Software Systems

PgSetMultiClip()
Set a list of rectangles to clip drawing
PgSetUserClip()
Restrict subsequent draws
PgSetUserClipAbsolute()
Restrict subsequent draws

PtWidgetVisibleExtent()
Calculate the visible portion of a widget

Colors — converting and parsing

PgBackgroundShadings()
Calculate top and bottom shading colors

PgBlueValue() Extract the blue component from a color value

PgCMY() Convert cyan, magenta, and yellow values to

composite color format

PgColor t Composite color value

PgColorHSV t Hue-Saturation-Value color value

PgColorMatch() Query for best colors matches

PgGetPalette() Query for current color palette

PgGray() Generate the RGB value for a shade of gray

PgGrayValue() Extract color brightness

PgGreenValue() Extract the green component from a color value

PgHSV() Convert hue, saturation, and value to composite

color format

PgHSV2RGB() Convert HSV colors to RGB

10 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

PgRedValue() Extract the red component from a color

PgRGB() Convert red, green, and blue values to composite

color format

PgRGB2HSV() Convert RGB colors to HSV

Configuration files
PxConfigClose()
Close the current configuration file

PxConfigDeleteEntry()
Delete an entry from a configuration file

PxConfigDeleteSection()
Delete a section from a configuration file

PxConfigForceEmptySection()
Create an empty section in a configuration file

PxConfigNextSection()
Seek the beginning of the next section of a configuration file

PxConfigNextString()
Get the next entry in the current section

PxConfigOpen()
Open a configuration file

PxConfigReadBool()
Read a Boolean value from a configuration file

PxConfigReadChar()
Read a character parameter from a configuration file

PxConfigReadInt()
Read an integer parameter from a configuration file

September 20, 2005 Chapter 1 ¯ Summary of Entries 11

Entries arranged by category  2005, QNX Software Systems

PxConfigReadLong()
Read a long integer parameter from a configuration file
PxConfigReadShort()
Read a short integer parameter from a configuration file
PxConfigReadString()
Read a string parameter from a configuration file

PxConfigSection()
Seek the start of a given section in a configuration file

PxConfigWriteBool()
Write a Boolean parameter in a configuration file

PxConfigWriteChar()
Write a character parameter in a configuration file

PxConfigWriteInt()
Write an integer parameter in a configuration file

PxConfigWriteLong()
Write a long integer parameter in a configuration file

PxConfigWriteShort()
Write a short integer parameter in a configuration file

PxConfigWriteString()
Write a string parameter in a configuration file

Coordinates, translating
PgClearTranslation()
Restore the current translation to the default
PgSetTranslation()
Translate draw commands horizontally and vertically

12 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

PtDeTranslateRect()
Detranslate a rectangle (subtract offset)
PtTranslateRect()
Translate a rectangle (add offset)

Cursors/pointers
PhMoveCursorAbs()
Move cursor to absolute position

PhMoveCursorRel()
Move cursor to relative position

PhQueryCursor()
Collect cursor information

Data chains
PtAddData() Add data to the provided data chain

PtFindData() Find the first data block of a given type and subtype

PtFindNextData()
Find the next data block of a given type and subtype
PtRemoveData()
Remove a link from a data chain

PtUnlinkData() Remove the provided data link from the data chain

Dragging
PhInitDrag() Initiate a drag operation

September 20, 2005 Chapter 1 ¯ Summary of Entries 13

Entries arranged by category  2005, QNX Software Systems

Draw contexts
PhDCGetCurrent()
Get the currently active Draw Context
PhDCSetCurrent()
Set the currently active Draw Context

Drawing attributes
General attributes
PgSetDrawMode()
Set draw mode
PgSetPalette() Set the color palette

PgSetPlaneMask()
Protect video memory from being modified

Fill attributes
PgSetFillColor()
Set exact fill color
PgSetFillDither()
Set specific dither pattern and colors
PgSetFillTransPat()
Set draw transparency
PgSetFillXORColor()
Set a color for XOR drawing

Line (stroke) attributes

PgSetStrokeCap()
Set what the ends of lines look like
PgSetStrokeColor()
Set the color of subsequent outlines

14 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

PgSetStrokeDash()
Set dashed lines
PgSetStrokeDither()
Apply a color pattern to outlines
PgSetStrokeFWidth()
Set line thickness
PgSetStrokeJoin()
Set how lines are joined
PgSetStrokeTransPat()
Use a masking pattern to set draw transparency on outlines
PgSetStrokeXORColor()
Use the XOR of a color to draw outlines
PgSetStrokeWidth()
Set line thickness

Text attributes
PgSetFont() Set text font

PgSetTextColor()
Set text color
PgSetTextDither()
Set text dither pattern
PgSetTextTransPat()
Set draw transparency
PgSetTextXORColor()
Set a color for XOR drawing
PgSetUnderline()
Set colors for underlining text

September 20, 2005 Chapter 1 ¯ Summary of Entries 15

Entries arranged by category  2005, QNX Software Systems

Events
PhEvent t Data structure describing an event

PhEventArm() Arm the currently attached Photon channel

PhEventEmit() Emit an event

PhEventEmitmx()
Emit an event when the event-specific data isn’t
contiguous in memory

PhEventNext() Provide synchronous event notification

PhEventPeek() Check to see if an event is pending

PhEventRead() Provide asynchronous event notification

PhEventRegion t
Emitter and collector of an event

PhGetData() Get data for an event

PhGetMsgSize() Get message size

PhGetRects() Get an event’s rectangle set

PhKeyEvent t Data structure describing a key event

PhTimerArm() Arm a timer event

PhWindowEvent t
Data structure describing a window action
PtAddEventHandler()
Add a single Pt CB RAW entry to a widget
PtAddEventHandlers()
Add several Pt CB RAW entries to a widget
PtBkgdHandlerProcess()
Process all outstanding Photon events

16 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

PtEventHandler()
Determine the widgets involved in an event
PtForwardWindowEvent()
Forward a window event

PtMainLoop() Implement an application main loop

PtProcessEvent() Standard Photon event-handling function

PtRemoveEventHandler()
Remove a single Pt CB RAW entry from a widget

PtRemoveEventHandlers()
Remove several Pt CB RAW entries from a widget

PtResizeEventMsg()
Resize the event buffer
PtSendEventToWidget()
Give an event to a widget

PtTimerArm() Arm a timer event on a widget

Font handling
PfAttach() Attach to a font server

PfDetach() Detach from a font server

PfExtentComponents()
Calculate the extent of a text string and invoke a
callback

PfExtentText() Calculate the extent rectangle of a text string

PfFractionalExtentText()
Calculate the extent rectangle of a text string,
using fractional scaling

September 20, 2005 Chapter 1 ¯ Summary of Entries 17

Entries arranged by category  2005, QNX Software Systems

PfFractionalRenderText()
Render a string, using fractional scaling, via a
callback function

PfGlyph() Obtain the metrics and/or bitmap for the specified

character

PfLoadFont() Preload a font within the font server

PfLoadMetrics() Load metric information for the given font

PfQueryFont() Get information about a font

PfQueryFonts() Construct a list of fonts

PfRenderText() Render a string via a callback function

PfUnloadMetrics()
Unload metric information for the given font

PtFontSelection()
Create a font-selection dialog

Geometry
PhArea t Position and dimensions of a rectangular area

PhDim t Dimensions of an area

PhPoint t Coordinates of a single point

PhRect t Coordinates of a rectangle

PtRectIntersect() Find the intersection of two rectangles

PtRectUnion() Find the union of two rectangles

18 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

Graphical contexts
PgClearDrawBuffer()
Reset the current draw buffer
PgCreateGC() Allocate a graphics context
PgDefaultFill() Reset fill attribute to its default value
PgDefaultGC() Reset all graphics context attributes to their default
system values
PgDefaultMode()
Reset draw mode and plane mask to their default
values
PgDefaultStroke()
Reset stroke attribute to its system default
PgDefaultText() Reset text attribute to its system default
PgDestroyGC() Release resources of a graphics context

PgFlush(), PgFFlush()
Explicitly flush the current draw buffer
PgGetGC() Get current graphics context

PgSetDrawBufferSize()
Resize a draw buffer
PgSetGC() Set current graphics context
PgSetRegion() Determine which region will emit draw events

Input/Output events
PtAppAddFd() Add a file-descriptor function

PtAppAddFdPri()
Add a file-descriptor function, specifying a
priority

September 20, 2005 Chapter 1 ¯ Summary of Entries 19

Entries arranged by category  2005, QNX Software Systems

PtAppRemoveFd()
Remove a file-descriptor function
PtAppSetFdMode()
Change the mode that’s of interest to an FD
handler

PtPulseArmFd() Create a pulse message to be sent to another

process

PtFileSelection() Create a file-selection dialog

PtFdProcF t, PtFdProc t
Pointer to a file-descriptor function

Interprocess Communication (IPC)

PhChannelAttach()
Create or attach a channel
PtAppAddInput()
Add an input processing function
PtAppCreatePulse()
Create a Photon pulse
PtAppDeletePulse()
Delete a Photon pulse
PtAppPulseTrigger()
Deliver a pulse to yourself
PtAppRemoveInput()
Remove an input processing entry

PtChannelCreate()
Make sure the widget library is using a channel

20 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

PtGetRcvidPid()
Get the process ID (PID) from the receive ID (RCVID)
PtInputCallbackProcF t, PtInputCallbackProc t
Pointer to a input callback function
PtPulseArmFd()
Create a pulse message to be sent to another process

PtPulseArmPid()
Create a pulse message to be sent to another process

PtPulseDeliver()
Send a pulse to another process

PtPulseDisarm()
Release resources allocated for a pulse message

Jump Gates
PtReattach() Send an application through the jump gate

PxCRC() Calculate a cyclic redundancy check for a block of

data

Key events, translating

PhKeyToMb() Get the UTF-8 value of a key event

PhTo8859 1() Get the ISO8859-1 value of a key event

Memory contexts
PmMemCreateMC()
Create a memory context

PmMemFlush() Flush a memory context

September 20, 2005 Chapter 1 ¯ Summary of Entries 21

Entries arranged by category  2005, QNX Software Systems

PmMemReleaseMC()
Release a memory context
PmMemSetChunkSize()
Set the increment for growing a memory context’s
draw buffer
PmMemSetMaxBufSize()
Set the maximum size of a memory context’s draw
buffer
PmMemSetType()
Set the type of a memory context

PmMemStart() Make a memory context active

PmMemStop() Deactivate a memory context

Messages and questions

ApError() Display an error message dialog

PtAskQuestion()
Display a question and request a response from the user

PtMessageBox()
Pop up a message box

Modal dialogs
PtModalEnd() Terminate modal-window processing

PtModalStart() Initiate modal-window processing

PtProcessEvent()
Standard Photon event-handling function

22 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

Modules
These functions can be used only by applications made with the
Photon Application Builder.

ApCreateModule()
Create an instance of modules built with PhAB
ApGetInstance()
Get the module link instance pointer for a widget
ApGetWidgetPtr()
Get the instance pointer for a widget in a given
module
ApModuleFunction()
Specify the setup function for a PhAB internal link
callback
ApModuleLocation()
Specify the module location for a PhAB internal link

ApModuleParent()
Specify the parent for a window module

ApWidget() Determine the widget that initiated a link callback

Multibyte-character strings
mbstrblen() Find the number of multibyte characters in part of a
string

mbstrchr() Search for a multibyte character in a string

mbstrlen() Find the length of a multibyte-character string

mbstrnchr() Search for a multibyte character in part of a string

mbstrncmp() Compare part of a multibyte-character string

September 20, 2005 Chapter 1 ¯ Summary of Entries 23

Entries arranged by category  2005, QNX Software Systems

mbstrnlen() Find the number of bytes used by n characters of a

multibyte-character string

mbstrrchr() Search backwards for a multibyte character in a

string

Online help
PtWidgetHelpHit()
Find the first widget at a given position that has a
help topic

PxHelpQuit() Exit the Helpviewer

PxHelpSearch() Search for text in help information

PxHelpTopic() Display the help text identified by the given topic

path
PxHelpTopicRoot()
Specify the root of help topic paths
PxHelpTopicTree()
Load a new help topic tree

PxHelpUrl() Display the help text at the given URL

PxHelpUrlRoot() Display help text relative to the given URL

Photon Application Builder functions

These functions can be used only by applications made with the
Photon Application Builder.

ApBitmap t PhAB bitmap structure

ApInfo t PhAB information structure

ApInstanceName()
Return the widget’s instance name string

24 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

ApName() Return a PhAB name value for the specified widget

ApResClose() Close the file of module resource records

Photon services, connecting and disconnecting

PhAttach() Open a communications channel

PhDetach() Free all resources consumed by a Photon channel

PhLibVersion() Get the version number of the Photon libraries

PhReattach() Change the current Photon channel

PtReattach() Send an application through the jump gate

Primitive drawing routines

PgDrawArc() Draw an arc, pie, or chord

PgDrawBevelBox(), PgDrawIBevelBox()
Draw a beveled box
PgDrawBeveled()
Draw a beveled rectangle or arrow

PgDrawBezier(), PgDrawBeziermx()
Draw a stroked and/or filled Bézier curve
PgDrawBitmap(), PgDrawBitmapmx()
Draw a bitmap
PgDrawEllipse()
Draw an ellipse

PgDrawGrid() Draw a grid

PgDrawImage(), PgDrawImagemx()
Draw an image

September 20, 2005 Chapter 1 ¯ Summary of Entries 25

Entries arranged by category  2005, QNX Software Systems

PgDrawLine(), PgDrawILine()
Draw a single line
PgDrawPixel(), PgDrawIPixel()
Draw a single point
PgDrawPixelArray(), PgDrawPixelArraymx()
Draw multiple points

PgDrawPolygon(), PgDrawPolygonmx()
Draw a stroked and/or filled polygon

PgDrawRect(), PgDrawIRect()
Draw a rectangle

PgDrawRepBitmap(), PgDrawRepBitmapmx()
Draw a bitmap several times

PgDrawRepImage(), PgDrawRepImagemx()
Draw an image several times

PgDrawRoundRect()
Draw a rounded rectangle

PgDrawSpan(), PgDrawSpanmx()
Draw a list of spans

PgDrawString(), PgDrawStringmx()
Draw a string of characters

PgDrawText(), PgDrawTextmx()
Draw text
PgDrawTextArea()
Draw text within an area
PgDrawTextChars()
Draw the specified number of text characters

26 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

PgDrawTrend(), PgDrawTrendmx()
Draw a trend graph

Printing
PpLoadPrinter() Initialize a print context with information for a
given printer

PpPrintClose() Close a print context

PpPrintCreatePC()
Create a print context

PpPrintGetPC() Extract data from a print context

PpPrintNewPage()
Place a page break in the draw stream for a print
context

PpPrintOpen() Prepare for printing

PpPrintReleasePC()
Release a print context

PpPrintSetPC() Set data in a print context

PpPrintStart() Make a print context the active one

PpPrintStop() Deactivate a print context

PpPrintWidget() Print a widget

PtPrintSelection()
Create a print-selection dialog

Processes
PtSpawn() Spawn a new process

September 20, 2005 Chapter 1 ¯ Summary of Entries 27

Entries arranged by category  2005, QNX Software Systems

PtSpawnDeleteCallback()
Remove a child-termination callback
PtSpawnSetCallback()
Change the callback in a PtSpawn() control structure

PtSpawnWait()
Spawn a process and wait for its termination

Regions
PhQueryRids() Get a list of regions

PhRegion t A region

PhRegionChange()
Change the definition of a region

PhRegionClose()
Remove a region

PhRegionDataFindType()
Find a data type within a region’s data

PhRegionDataHdr t
Data that’s attached to a region

PhRegionOpen() Open a region

PhRegionQuery()
Retrieve information about a region

PtQuerySystemInfo()
Query the system for information

PtWidgetRid() Get a widget’s region ID

28 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

Shared memory
PgShmemAttach()
Record a shared memory reference
PgShmemCleanup()
Remove shared memory references
PgShmemCreate()
Create a block of shared memory
PgShmemDestroy()
Remove a block of shared memory
PgShmemDetach()
Remove a shared memory reference

Signals
PtAppAddSignalProc()
Add Photon signalling to a context
PtAppRemoveSignal()
Remove specific signal handling from a context
PtAppRemoveSignalProc()
Remove Photon signalling from a context
PtSignalProcF t, PtSignalProc t
Pointer to a signal-handling function

Strings, translating
ApAppendTranslation()
Append external translation files to an application’s translation
list
ApGetTextRes()
Get a translated text string from a widget database

September 20, 2005 Chapter 1 ¯ Summary of Entries 29

Entries arranged by category  2005, QNX Software Systems

ApSetTranslation()
Change the current translation to another language

System information
PhGetConnectId()
Get the connection ID of the calling process

PhGetConnectInfo()
Get information about a Photon channel
PhQueryCursor()
Collect cursor information
PhQuerySystemInfo()
Query the system for information about a given region

PtQuerySystemInfo()
Query the system for information about a given widget

Text
PgExtentText()
Calculate the extent of a string of text

See also the PtMultiText and PtText convenience functions.

Tiles
PhAddMergeTiles()
Merge two list tiles, eliminating overlap

PhClipTilings() Clip one list of tiles from another

PhCoalesceTiles()
Combine a list of tiles

PhCopyTiles() Copy a list of tiles

30 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

PhDeTranslateTiles()
Subtract x and y offsets from the vertices of a list
of tiles

PhFreeTiles() Return a list of tiles to the internal tile pool

PhGetTile() Retrieve a tile from the internal tile pool

PhIntersectTilings()
Determine the intersection of two lists of tiles

PhMergeTiles() Remove all overlap from a list of tiles

PhRectsToTiles() Create a list of tiles from an array of rectangles

PhSortTiles() Sort a list of tiles

PhTile t A list of rectangles

PhTilesToRects() Create an array of rectangles from a list of tiles

PhTranslateTiles()
Add x and y offsets to the vertices of a list of tiles

Wide characters
wctolower() Return the lowercase equivalent of a wide character

Widgets
Callbacks and hotkey handlers
PtAddCallback()
Add a single callback entry to a callback list

PtAddCallbacks()
Add several callback entries to a callback list
PtAddEventHandler()
Add a single Pt CB RAW entry to a widget

September 20, 2005 Chapter 1 ¯ Summary of Entries 31

Entries arranged by category  2005, QNX Software Systems

PtAddEventHandlers()
Add several Pt CB RAW entries to a widget
PtAddHotkeyHandler()
Add a single hotkey handler entry to a widget
PtBalloonCallback t
Balloon callback structure — see the Photon Widget Reference
PtCallback t
Regular callback structure — see the Photon Widget Reference

PtCallbackInfo t
Specific callback information — see the Photon Widget
Reference
PtHotkeyCallback t
Hotkey handler structure — see the Photon Widget Reference

PtRawCallback t
Event handler structure — see the Photon Widget Reference
PtRemoveCallback()
Remove a single callback entry from a callback list

PtRemoveCallbacks()
Remove several callback entries from a callback list
PtRemoveEventHandler()
Remove a single Pt CB RAW entry from a widget
PtRemoveEventHandlers()
Remove several Pt CB RAW entries from a widget
PtRemoveHotkeyHandler()
Remove a single hotkey handler entry from a widget

32 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

Class hierarchy
PtWidgetClass()
Return the class of a widget

PtWidgetIsClass()
Determine whether a widget is a specific class type

PtWidgetIsClassMember()
Determine whether a widget belongs to a specified class

Creating and destroying widgets

Pt ARG() Macro for creating statically initialized argument lists

PtClearWidget()
Destroy all widgets within a container

PtCreateWidget()
Create a widget

PtDestroyWidget()
Remove a widget from the widget hierarchy

PtInflateBalloon()
Create a balloon widget

PtSetArg() Build argument lists for widgets

Custom widgets
These functions are described in the Building Custom Widgets.

PtAddWidgetData()
Add data to the widget data chain
PtAnchorWidget()
Anchor the provided widget

September 20, 2005 Chapter 1 ¯ Summary of Entries 33

Entries arranged by category  2005, QNX Software Systems

PtApplyAnchors()
Anchor a widget and its children
PtAttemptResize()
Adjust the size of a widget
PtCalcAnchorOffsets()
Update the anchoring values (rules) for the given
widget

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
PtCoreChangeRegion()
Determine if a region is required
PtCreateWidgetClass()
Create a widget class

34 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

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
PtMoveResizeWidget()
Synchronize a widget’s extent

PtRemoveWidgetData()
Remove data from the widget data chain

September 20, 2005 Chapter 1 ¯ Summary of Entries 35

Entries arranged by category  2005, QNX Software Systems

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
PtSuperClassChildSettingResources()
Invoke a Child Setting Resources method
PtSuperClassChildUnrealized()
Invoke a Child Unrealized method

36 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

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

PtSuperClassSetResources()
Set resources
PtUpdateVisibility()
Tell the widget library about a change in visibility

September 20, 2005 Chapter 1 ¯ Summary of Entries 37

Entries arranged by category  2005, QNX Software Systems

PtWidgetAbove()
Identify the position of a widget in the hierarchy
relative to another widget

Damaging widgets
PtDamageExtent()
Mark an area of a widget as damaged so that it will
be redrawn
PtDamageWidget()
Mark a widget as damaged so it will be redrawn

PtEndFlux() Decrement the global and container flux count

PtIsFluxing() Determine whether a container or its family is in

flux

PtStartFlux() Increment the global and container flux count

Databases
These functions can be used only by applications made with the
Photon Application Builder.

ApAddClass() Indicate the widgets likely to be encountered in a

widget database
ApCloseDBase()
Close a widget database

ApCopyWidget() Copy a widget from a PhAB widget database

ApCreateWidget()
Create a widget by copying it from a PhAB widget
database
ApCreateWidgetFamily()
Create a widget by copying it from a PhAB widget
database

38 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

ApDeleteWidget()
Remove widgets from a widget database
ApFreeBitmapRes()
Free a bitmap resource structure
ApGetBitmapRes()
Extract bitmap data from a widget in a widget
database
ApGetImageRes()
Extract the image data from a widget in a widget
database
ApGetTextRes() Get a translated text string from a widget database
ApOpenDBase() Open a picture module as a widget database

ApOpenDBaseFile()
Open a picture module as a widget database
ApSaveDBaseFile()
Save a widget database as an external file

Family hierarchy
PtChildType() Determine the relationship between two widgets

PtCreateWidget()
Create a widget
PtFindChildClass()
Find the first child that matches the specified class
PtFindChildClassMember()
Find the first child that’s a subclass of the specified
class
PtFindContainer()
Return the nearest container parent

September 20, 2005 Chapter 1 ¯ Summary of Entries 39

Entries arranged by category  2005, QNX Software Systems

PtFindDisjoint() Return the nearest disjoint parent widget

PtFindFocusChild()
Find the closest focusable child widget
PtFindGuardian()
Find the widget responsible for another widget’s
actions

PtGetParent() Find the nearest widget with the same parent class

PtGetParentWidget()
Return the current default widget parent
PtNextTopLevelWidget()
Get a pointer to the next top-level widget
PtReParentWidget()
“Reparent” a widget to a new container
PtSetParentWidget()
Set the current parent widget

PtValidParent() Identify a valid parent for a widget

PtWidgetBrotherBehind()
Get the brother behind a widget
PtWidgetBrotherInFront()
Get the brother in front of a widget
PtWidgetChildBack()
Get the child that’s farthest back in a container
PtWidgetChildFront()
Get the child at the very front of a container
PtWidgetFamily()
Traverse the widget hierarchy

40 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

PtWidgetInsert() Insert a widget in the widget family hierarchy

PtWidgetParent()
Get a widget’s parent

PtWidgetSkip() Skip to a widget in the next hierarchy

PtWidgetToBack()
Move a widget behind all its brothers

PtWidgetToFront()
Move a widget in front of all its brothers

PtWidgetTree() Walk the widget tree from front to back

PtWidgetTreeTraverse()
Walk the widget family hierarchy from front to
back

Finding widgets in an area

PtContainerBox()
Find the next widget in an area

PtContainerHit()
Find the nth widget in an area

PtHit() Identify a widget in the specified container

Focus
PtContainerFindFocus()
Find the widget that currently has focus

PtContainerFocusNext()
Give focus to the next Pt GETS FOCUS widget
within the same container

September 20, 2005 Chapter 1 ¯ Summary of Entries 41

Entries arranged by category  2005, QNX Software Systems

PtContainerFocusPrev()
Give focus to the previous Pt GETS FOCUS widget
within the same container
PtContainerGiveFocus()
Give focus to a widget
PtContainerNullFocus()
Truncate the focus chain at the specified widget

PtFindFocusChild()
Find the closest focusable child widget

PtGlobalFocusNext()
Give focus to next widget

PtGlobalFocusNextContainer()
Give focus to another container’s widget

PtGlobalFocusNextFrom()
Give focus to the next widget behind the specified
widget

PtGlobalFocusPrev()
Give focus to previous widget

PtGlobalFocusPrevContainer()
Give focus to widget in previous container

PtGlobalFocusPrevFrom()
Give focus to widget previous to the specified
widget

PtIsFocused() Determine to what degree a widget is focused

42 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

Geometry
PtBasicWidgetCanvas()
Determine the PtBasic canvas for a widget

PtCalcAbsPosition()
Calculate the position of a widget based on a position and
another widget

PtExtentWidget()
Force a widget to calculate its extent

PtExtentWidgetFamily()
Force a widget and its children to calculate their extents

PtGetAbsPosition()
Get the absolute position of a widget

PtLabelWidgetCanvas()
Determine the PtLabel canvas for a widget

PtSetAreaFromExtent()
Set the extent of a widget

PtSetAreaFromWidgetCanvas()
Set the canvas of a widget

PtWidgetArea()
Retrieve a copy of a widget’s area

PtWidgetCanvas()
Determine the PtWidget canvas for a widget

PtWidgetDim()
Retrieve a copy of a widget’s dimension

PtWidgetExtent()
Get a widget’s extent

September 20, 2005 Chapter 1 ¯ Summary of Entries 43

Entries arranged by category  2005, QNX Software Systems

PtWidgetOffset()
Find the offset of a widget’s origin from its disjoint parent
PtWidgetVisibleExtent()
Calculate the visible portion of a widget

Library initialization
PtAppInit() Initialize an application and create the main window
PtInit() Initialize the widget library

Menus
These functions can be used only with menu modules created in
PhAB:

ApGetItemText()
Get the text for a menu item
ApModifyItemState()
Modify the state of menu items
ApModifyItemText()
Modify the text for a menu item

This function is to be used with a PtMenu widget:

PtPositionMenu()
Set a menu’s position

PtComboBox
These functions are described in the Photon Widget Reference.

PtComboBoxListOpen()
Open a combobox list
PtComboBoxListClose()
Close an open combobox list

44 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

PtFileSel
These functions are described in the Photon Widget Reference.

PtFSAddAfter()
Insert an item after the specified item

PtFSAddFirst()
Add a root item to the widget

PtFSAllItems() Fill a buffer with pointers to all items

PtFSAllocItem()
Create an item for a file-selector widget

PtFSClearSelection()
Clear the selection
PtFSDamageItem()
Redraw an item
PtFSExpandParents()
If any ancestors of the given item are collapsed, this
function tries to expand them.

PtFSFolderCollapse()
Collapse an expandable item (directory)

PtFSFolderExpand()
Expand an expandable item (directory)

PtFSFreeAllItems()
Unlink and free all items
PtFSFreeItems()
Free an unlinked item
PtFSGetCurrent()
Get the current item

September 20, 2005 Chapter 1 ¯ Summary of Entries 45

Entries arranged by category  2005, QNX Software Systems

PtFSGetSelIndexes()
Fill a buffer with indexes

PtFSGoto() Set the current item

PtFSItemIndex()
Calculate the index of the specified item

PtFSRemoveChildren()
Unlink all the children of a given item

PtFSRemoveItem()
Unlink an item
PtFSRemoveList()
Unlink the root item
PtFSRootItem()
Return the first root item of the file selector

PtFSSelect() Select the specified item

PtFSSelectedItems()
Fill a buffer with item pointers

PtFSSetSelIndexes()
Set the selection indexes

PtFSShow() Set the position so that the specified item is visible

PtFSUnselect()
Unselect the specified item

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

46 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

PtGenList
These functions are described in the Photon Widget Reference.

PtGenListCreateTextBalloon()
Create a popup balloon for an item in the list
PtGenListItem t
PtGenList item structure
PtGenListSetColumnBalloon()
Adjust the balloon text to correspond to a given column

These functions are described in the Building Custom Widgets.

PtGenListAddItems()
Add items to a list
PtGenListAllItems()
Get pointers to all the items in a list
PtGenListClearSelection()
Clear the selection
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

September 20, 2005 Chapter 1 ¯ Summary of Entries 47

Entries arranged by category  2005, QNX Software Systems

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

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

48 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

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
PtSuperClassGenListSelect()
Invoke the List Select method in a superclass

PtGenTree
This data structure is described in the Photon Widget Reference.

PtGenTreeItem t
PtGenTree item structure

These functions are described in the Building Custom Widgets.

PtGenTreeAddAfter()
Add items after a given item

September 20, 2005 Chapter 1 ¯ Summary of Entries 49

Entries arranged by category  2005, QNX Software Systems

PtGenTreeAddFirst()
Add items in front of any existing items
PtGenTreeAllItems()
Get pointers to all the items in the tree
PtGenTreeClearSelection()
Clear the selection
PtGenTreeCollapse()
Collapse a subtree

PtGenTreeDamageItem()
Redraw an item when its data has changed

PtGenTreeExpand()
Expand a given subtree

PtGenTreeExpandParents()
Expand any collapsed ancestors of a given item

PtGenTreeFreeAllItems()
Free all the items in a tree
PtGenTreeFreeItems()
Free the items in a subtree
PtGenTreeGetCurrent()
Get a pointer to the current item
PtGenTreeGetSelIndexes()
Get the indexes of the selected items
PtGenTreeGoto()
Set the current item and position so that a given item is visible

PtGenTreeItemIndex()
Calculate the index of a given item

50 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

PtGenTreeItemRealloc()
Reallocate an item
PtGenTreeItemResize()
Resize an item
PtGenTreeRemoveChildren()
Unlink all the children of a given item
PtGenTreeRemoveItem()
Remove a given item and its children from its parents and
siblings
PtGenTreeRemoveList()
Remove a given items and its siblings from their parent
PtGenTreeResize()
Resize many items
PtGenTreeRootItem()
Get a pointer to the first root item
PtGenTreeSelect()
Select a given item
PtGenTreeSelectedItems()
Get pointers to the selected items
PtGenTreeSetSelIndexes()
Set the selection indexes
PtGenTreeShow()
Set the current position so that a given item is visible
PtGenTreeUnselect()
Unselect a given item
PtGenTreeUnselectNonBrothers()
Unselect all items that aren’t siblings of a given item

September 20, 2005 Chapter 1 ¯ Summary of Entries 51

Entries arranged by category  2005, QNX Software Systems

PtSuperClassGenTreeDrawItem()
Invoke the Tree Draw Item method of a given superclass
PtSuperClassGenTreeItemState()
Invoke the Tree Item State method of a superclass

PtHtml
These functions are described in the Photon Widget Reference.

PtHtmlTitle() Return the title of an HTML file

PtHtmlLink() Return links to related HTML documents

PtList
These functions are described in the Photon Widget Reference.

PtListAddItems()
Add one or more items to the list at a specified position
PtListDeleteAllItems()
Remove all the items from the list
PtListDeleteItemPos()
Delete a range of items by position
PtListDeleteItems()
Delete items in the list by name
PtListGotoPos()
Make the item at the specified position the current item and
display it.
PtListItemExists()
Determine whether or not an item exists within the list
PtListItemPos()
Determine the position of an item within the list

52 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

PtListRemovePositions()
Remove the items at the specified positions
PtListReplaceItemPos()
Replace items by position number
PtListReplaceItems()
Replace items by item text

PtListSelectPos()
Select the item at the specified position

PtListShowPos()
Display the item at the specified position

PtListUnselectPos()
Unselect the item at the specified position

PtMessage
This function is described in the Photon Widget Reference.

PtMessageGetWindow()
Get the widget pointer to the message’s window

PtMultiText
These functions are described in the Photon Widget Reference.

PtMultiLines t
Structure for setting multiline text and attributes

PtMultiTextAttributes t
Attributes for multiline text
PtMultiTextCallback t, PtMultiTextControl t
Information passed to PtMultiText callbacks

September 20, 2005 Chapter 1 ¯ Summary of Entries 53

Entries arranged by category  2005, QNX Software Systems

PtMultiTextCreateAttributes()
Initialize a multitext attribute structure
PtMultiTextGetAttributes()
Get the attributes of a PtMultiText widget
PtMultiTextInfo()
Get character/line information from a PtMultiText widget
PtMultiTextInfo t
Information passed to PtMultiText callbacks
PtMultiTextLine t
Information about a line of text in a PtMultiText
PtMultiTextModifyAttributes()
Modify the attributes of a PtMultiText widget
PtMultiTextModifyText()
Modify the contents of a PtMultiText widget
PtMultiTextQuery t
Structure for getting information about a line or character
PtMultiTextSegment t
Information about a segment of text in a PtMultiText

PtTerminal
These functions are described in the Photon Widget Reference.

PtTerminalCharset t, PtTerminalCharsets t
Character sets used by PtTerminal
PtTerminalCopy()
Copy the current selection to the clipboard
PtTerminalCreateCsXlat().
Create a translation table for PtTerminal’s character sets

54 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

PtTerminalDefaultCharsets()
Get the default character sets used by PtTerminal
PtTerminalFont()
Examine a font
PtTerminalGetKeys()
Get the terminal line-editing keys
PtTerminalGetSelection()
Get a copy of the current selection
PtTerminalName()
Get the terminal’s termcap/terminfo name
PtTerminalPasteClipboard()
Paste the contents of the clipboard into the terminal
PtTerminalPasteSelection()
Paste the current selection into the terminal
PtTerminalPut(), PtTerminalPutc(), PtTerminalPuts()
Output text to the terminal
PtTerminalSelectWord()
Select a word

PtText
These functions are described in the Photon Widget Reference.

PtTextCallback t, PtTextControl t,
PtTextControlInfo t
Information passed to PtText callbacks
PtTextGetSelection()
Get the selected range from a PtText widget
PtTextModifyText()
Modify the contents of a PtText widget

September 20, 2005 Chapter 1 ¯ Summary of Entries 55

Entries arranged by category  2005, QNX Software Systems

PtTextSetSelection()
Set the selected range for a PtText widget

PtTree
These functions are described in the Photon Widget Reference.

PtTreeAddAfter()
Insert an item after the specified item

PtTreeAddFirst()
Add a root item to the widget, or add an item as the
first child of a specified item

PtTreeAddImages()
Add images to the PtTree’s widgets image list

PtTreeAllItems() Fill a buffer with pointers to all items

PtTreeAllocItem()
Allocate a new item
PtTreeClearSelection()
Clear the selection
PtTreeCollapse()
Collapse an expandable item

PtTreeExpand() Expand an expandable item

PtTreeFreeAllItems()
Unlink and free all items
PtTreeFreeItems()
Free an unlinked item
PtTreeGetCurrent()
Get the current item

56 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

PtTreeGetSelIndexes()
Fill a buffer with indexes of selected items
PtTreeGoto() Set the current item
PtTreeItem t PtTree item structure

PtTreeItemIndex()
Calculate the index of the specified item
PtTreeModifyItem()
Change item resources
PtTreeRemoveChildren()
Unlink the children of the specified item
PtTreeRemoveItem()
Unlink an item
PtTreeRemoveList()
Unlink the given item and any siblings that follow
PtTreeRootItem()
Return the first root item of the tree
PtTreeSelect() Select the specified item
PtTreeSelectedItems()
Fill a buffer with pointers to the selected items
PtTreeSetSelIndexes()
Set the selection indexes
PtTreeShow() Set the position so that the specified item is visible
PtTreeUnselect()
Unselect the specified item
PtTreeUnselectNonBrothers()
Unselect all items that aren’t siblings of the
specified item

September 20, 2005 Chapter 1 ¯ Summary of Entries 57

Entries arranged by category  2005, QNX Software Systems

PtTty
This function is described in the Photon Widget Reference.

PtTtyShell() Return the default user’s shell

PtWindow
These functions are described in the Photon Widget Reference.

PtWindowFocus()
Give a window focus
PtWindowGetState()
Return the current state of a window
PtWindowToBack()
Move a window to the back of the workspace
PtWindowToFront()
Bring a window to the front and gives it focus

Realizing and unrealizing widgets

PtDestroyWidget()
Remove a widget from the widget hierarchy
PtRealizeWidget()
Initialize a widget and its children
PtReRealizeWidget()
Force a widget to unrealize and then rerealize itself
PtUnrealizeWidget()
Unrealize a widget
PtWidgetIsRealized()
Determine whether a widget is realized

58 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

Resources
PtArg t Which resource is affected when you get or set
resources

Pt ARG() Macro for creating statically initialized argument lists

PtGetControlFlags()
Get the flags from the Pt control structure
PtGetResources()
Retrieve one or more resource values for a widget

PtSetArg() Build argument lists for widgets

PtSetResources()
Set one or more resources for a widget
PtWidgetClassFlags()
Retrieve a widget’s class structure flags
PtWidgetFlags()
Retrieve a widget’s flags

RtTrend
These functions are described in the Photon Widget Reference.

RtTrendChangeData()
Replace some samples for all trends
RtTrendChangeTrendData()
Replace some samples for one trend

Updates — forcing and holding off

PtContainerHold()
Prevent repairs to a container widget and its
children

September 20, 2005 Chapter 1 ¯ Summary of Entries 59

Entries arranged by category  2005, QNX Software Systems

PtContainerRelease()
Decrement the hold count for a widget

PtEndFlux() Decrement the global and container flux count

PtFlush() Immediately repair widget damage

PtHold() Prevent visible repair of all widgets

PtRelease() Decrement the global widget hold count

PtStartFlux() Prevent changes from being applied to a widget

PtSyncPhoton()
Synchronize Photon
PtSyncWidget()
Synchronize a widget

PtUpdate() Decrement the global hold count

Window Manager
PhWindowChange()
Modify the attributes of a window’s region
PhWindowClose()
Close a window
PhWindowQueryVisible()
Query a visible extent
PhWindowOpen()
Create a window region
PtConsoleSwitch()
Switch to another virtual console
PtForwardWindowEvent()
Forward a window event

60 Chapter 1 ¯ Summary of Entries September 20, 2005

 2005, QNX Software Systems Entries arranged by category

PtForwardWindowTaskEvent()
Forward a window event to a task

PtFrameSize() Estimate the size of the window frame

PtWindowConsoleSwitch()
Switch to the console a given window’s displayed
on

See also the list of PtWindow convenience functions.

September 20, 2005 Chapter 1 ¯ Summary of Entries 61

 Chapter 2
Ap — PhAB

September 20, 2005 Chapter 2 ¯ Ap — PhAB 63

 2005, QNX Software Systems

This chapter describes the functions and data structures that are
associated with the Photon Application Builder (PhAB).

☞ These functions and data structures can be used only by applications

built with PhAB.

September 20, 2005 Chapter 2 ¯ Ap — PhAB 65

ApAddClass()  2005, QNX Software Systems
Indicate the widgets likely to be encountered in a widget database

Synopsis:
#include <Ap.h>

int ApAddClass(
char const * class name string,
PtWidgetClassRef t * const *wgt class);

Description:
This function lets you indicate which widget classes you’re likely to
encounter when you call ApOpenDBaseFile(). The class name string
is the name of the class (for example, "PtButton"). The wgt class is
a predefined widget class; specify the name of the class preceded by
an ampersand (for example, &PtButton).
When you link your application, only those widgets it needs are
linked into it. If you access widgets that aren’t in your application
because they’re in an external database, you must add them to your
internal class table so that they can be linked in at compile time.
Any widgets used when you build a PhAB application are
automatically included in the internal class table (see the generated
abmain.c file). When you use widgets from an external database,
PhAB doesn’t know which widgets you need to access, so you’ll have
to use this function to include them.

☞ This function keeps a pointer to the string pointed to by

class name string; don’t modify this string after calling
ApAddClass().

Returns:
0 Success

-1 Failure — there isn’t enough memory to add the widget class

66 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApAddClass()

Examples:
base setup ( ... )
{

ApAddClass ("RtProgress", &RtProgress);

return (Pt CONTINUE);

}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
ApOpenDBaseFile()
Accessing PhAB Modules from Code chapter of the Photon
Programmer’s Guide

September 20, 2005 Chapter 2 ¯ Ap — PhAB 67

ApAppendTranslation()  2005, QNX Software Systems
Append external translation files to an application’s translation list

Synopsis:
#include <Ap.h>

int ApAppendTranslation( char const *filename,

char const *lang extension );

Description:
This function is used to append external translation files to the
application’s translation list. It takes the translation file identified by
filename, appends the lang extension and looks for the translation file
in the directory defined by the ABLPATH environment variable. If
lang extension is NULL, the current language extension is used.
This is useful when you want to share common text strings among
many different applications. Essentially, you create a standalone
application that contains a single picture module (widget database) of
text strings. Then you use the PhAB Language Editor to translate the
strings in this module. Once the database is created and translated,
you can access it from another application.

Returns:
0 Success

-1 Unable to read the translation file

Examples:
Assuming ABLPATH has been set to
/usr/photon/translations:

ApDBase t *mytext db;

/* Open the text database. */

mytext db = ApOpenDBaseFile( "/fullpath/mytext db.wgtp" );

/* Set the translation to German. */

ApSetTranslation( "de DE" );

68 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApAppendTranslation()

/* Append the external German translation file to the

current list. This will read the translation file
"/usr/photon/translations/mystrings.de DE" and append
it to the application’s current translation list. */

ApAppendTranslation( "mystrings", "de DE" );

/* Get a translated text string. */

text = ApGetTextRes( mytext db, "msg001" );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
ApOpenDBase(), ApOpenDBaseFile(), ApSetTranslation(),
ApGetTextRes()

September 20, 2005 Chapter 2 ¯ Ap — PhAB 69

ApBitmap t  2005, QNX Software Systems
PhAB bitmap structure

Synopsis:
#include <Ap.h>

typedef struct {
short nplanes;
short nbytes;
PgColor t *colors;
char **data;
} ApBitmap t;

Description:
This data structure describes a PhAB bitmap. The members include at
least:

nplanes The number of bitmap planes. Each plane has one

associated color in the color list.

nbytes The number of bytes used by each bitmap plane.

colors An array of colors corresponding to the number of

planes. For example:

color[0] = Color of plane 0

color[1] = Color of plane 1
...

data The bitmap image data. The format of the data is a series
of 1-bit-per-pixel planes.

Classification:
Photon

70 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApBitmap t

See also:
ApFreeBitmapRes(), ApGetBitmapRes()

September 20, 2005 Chapter 2 ¯ Ap — PhAB 71

ApCloseDBase()  2005, QNX Software Systems
Close a widget database

Synopsis:
#include <Ap.h>

int ApCloseDBase( ApDBase t *db );

Description:
ApCloseDBase() closes a widget database that has been opened with
ApOpenDBase() or ApOpenDBaseFile().
Closing a widget database deallocates its memory. If you’re finished
using a widget database, close it to free up the memory.

☞ If you use a widget database to create widgets that have PhImage t

data attached to them, don’t close the database until those widgets are
destroyed. Closing the database frees the memory used by the image.
If you must close the database, make sure to copy the image data
within your application code and to reset the image data resource to
point to your new copy.

Returns:
0 Successful completion

Examples:
ApDBase t *mydbase;

mydbase = ApOpenDBase( ABM mypicture );

ApCreateWidget( mydbase, "this widget", 10, 10, 0, NULL );

ApCreateWidget( mydbase, "that widget", 50, 10, 0, NULL );

ApCloseDBase( mydbase );

72 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApCloseDBase()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
ApOpenDBase(), ApOpenDBaseFile()
Accessing PhAB Modules from Code chapter of the Photon
Programmer’s Guide

September 20, 2005 Chapter 2 ¯ Ap — PhAB 73

ApCopyWidget()  2005, QNX Software Systems
Copy a widget from a PhAB widget database

Synopsis:
#include <Ap.h>

int ApCopyWidget( ApDBase t const *from dbase,

char const *from name,
ApDBase t *to dbase,
char const *to name );

Description:
ApCopyWidget() copies a widget from one PhAB widget database to
another. The from name parameter indicates which widget to copy
from the database, and to name lets you rename the copy. Only one
widget can be copied at a time. If you copy a container-class widget,
only the container widget is copied, not its children.

Returns:
0 Success.

-1 Failure.

Examples:
ApDBase t *from dbase, *to dbase;

from dbase = ApOpenDBaseFile( "/home/me/mydbase.wgtp" );

to dbase = ApOpenDBaseFile( "/home/joe/his dbase.wgtp" );
ApCopyWidget( from dbase, "my icon", to dbase, "his icon" );
ApSaveDBaseFile( to dbase, "/home/joe/his dbase.wgtp" );

Classification:
Photon

74 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApCopyWidget()

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
ApOpenDBase(), ApOpenDBaseFile(), ApSaveDBaseFile()

September 20, 2005 Chapter 2 ¯ Ap — PhAB 75

ApCreateModule()  2005, QNX Software Systems
Create an instance of modules built with PhAB

Synopsis:
#include <Ap.h>

int ApCreateModule(
ApEventLink t const *link callback,
PtWidget t *widget,
PtCallbackInfo t *cbinfo );

Description:
ApCreateModule() is used to manually create instances of modules
built with PhAB. It’s used differently when creating a picture module;
see “Usage with picture modules,” below.

Usage with window, dialog, menu, and other modules

Before you can create an instance of a module, you must create an
internal link to the module using the Internal Links dialog accessible
from PhAB’s Application menu. For every internal link in the list,
PhAB generates a manifest that you can use with ApCreateModule()
to create the module.
This function and PhAB’s link callbacks behave in very similar ways.
If you define a location and a setup function for the internal link, the
module appears at the specified location, and the setup function is
called. All link callbacks attached to widgets inside the module are
handled properly.
This function can be very handy in situations where a regular link
callback can’t be used. For example, a menu item may need to display
one dialog or another, depending on certain conditions in your
application code. In this case, you can attach a code link callback to
the menu item and in the code function you can create the appropriate
module.

76 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApCreateModule()

☞ A module created with ApCreateModule() becomes a standard Photon

widget (e.g. PtWindow, PtMenu) that you can destroy later using
PtDestroyWidget() if you want to close the module.

ApCreateModule() is also useful when modules need to be displayed

without direct user interaction.
The widget argument is used only if you’re creating a module with a
location relative to another widget. Otherwise, you can set it to NULL.
It’s passed to the module’s setup function as apinfo->widget.
The cbinfo argument is used only if you’re creating a module relative
to the pointer position. Otherwise, you can set it to NULL.
This code creates one of two dialogs:

/* the following 2 lines are generated by PhAB */

#define ABM mydialog1 &internal links[ABI mydialog1]
#define ABM mydialog2 &internal links[ABI mydialog2]

mycallback( PtWidget t *widget, ...,

PtCallbackInfo t *cbinfo )
{
/* check conditions */
if ( condition1 ) {
ApCreateModule( ABM mydialog1, widget, cbinfo );
} else {
ApCreateModule( ABM mydialog2, widget, cbinfo );
}
}

To specify the parent for a window module, use ApModuleParent().

Usage with picture modules

ApCreateModule() is the only way to create picture modules because
pictures don’t have a direct link callback. You can’t attach a link
callback from a widget to a picture module. Instead, design your
picture module as you would a window or dialog module, and then
add the picture to the internal callbacks list. PhAB generates the
necessary manifests for you to access the picture from within your
application code.

September 20, 2005 Chapter 2 ¯ Ap — PhAB 77

ApCreateModule()  2005, QNX Software Systems

For a more detailed description of picture modules and their usage,

see “Picture modules” in the Working with Modules chapter of the
Programmer’s Guide.
The widget argument is used differently by pictures. Since pictures
don’t have an associated location, widget is used to specify the picture
module’s container widget.
The following example illustrates the use of ApCreateModule() when
creating a picture:

/* the following line is generated by PhAB */

#define ABM mypicture &internal links[ABI mypicture]

mycallback( PtWidget t *widget, ...,

PtCallbackInfo t *cbinfo )
{
/* clear out container widget */
PtClearWidget( ABW mycontainer );

/* create the picture inside ’mycontainer’ */

ApCreateModule( ABM mypicture, ABW mycontainer,
cbinfo );

/* force the container to be updated */

PtReRealizeWidget( ABW mycontainer );
}

Returns:
¯ If there are no setup functions associated with the internal link:

Pt CONTINUE
Success.
-1 An error occurred.

¯ If there are any setup functions associated with the internal link,
ApCreateModule() returns the value returned by the last one called:

Pt CONTINUE
Normal return value.

78 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApCreateModule()

Pt END (Prerealize function for window and dialog modules

only) The creation of the module was aborted and the
widgets were destroyed.
Pt HALT (Prerealize functions for window modules only) The
module wasn’t realized. The widgets weren’t
destroyed and the module can be realized later.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
ApModuleLocation(), ApModuleFunction(), ApModuleParent()
“Module setup functions” in the Working with Code chapter, and
“Picture modules” in the Working with Modules chapter of the
Programmer’s Guide.

September 20, 2005 Chapter 2 ¯ Ap — PhAB 79

ApCreateWidget()  2005, QNX Software Systems
Create a widget by copying it from a PhAB widget database

Synopsis:
#Include <Ap.h>

PtWidget t *ApCreateWidget( ApDBase t const *db,

char const *wgt name,
int x,
int y,
int nargs,
PtArg t const *args );

Description:
This function is used to create widgets by copying a widget from a
PhAB widget database. This is very useful when you need to create
many instances of the same widget. For example, a file manager may
want to draw a file folder for each directory it displays.
The widget is created as a child of the default parent, which is usually
the most recently created container. To change the default parent, call
PtSetParentWidget().

☞ Before loading widgets from an external database, you should call

ApAddClass() for each widget class that you’ll likely encounter in it.
This will add the widget classes to the internal widget class table.

The arguments to ApCreateWidget() are as follows:

db points to a widget database opened with either

ApOpenDBase() or ApOpenDBaseFile()

wgt name the instance name of one of the widgets inside the
database

x and y convenience arguments for specifying the position of

the widget when it’s created

80 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApCreateWidget()

If y is -1, the widget’s original position is used.

☞
nargs and args
the standard resource argument counter and argument
list used by PtCreateWidget()

ApCreateWidget() creates only the widget named by wgt name

regardless of its class. ApCreateWidgetFamily() creates the named
widget and, for container class widgets, any children of the widget.

Returns:
A pointer to the widget created for wgt name, or NULL on failure.

Examples:
ApDBase t *mydbase;
PtArg t args[2];

mydbase = ApOpenDBase( ABM mypicture );

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

"This Widget", 0 );
ApCreateWidget( mydbase, "my label widget", 10, 10, 1,
args );

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

"That Widget", 0 );
PtSetArg( &args[1], Pt ARG FILL COLOR, Pg WHITE, 0 );
ApCreateWidget( mydbase, "my label widget", 10, 30, 2,
args );

ApCloseDBase( mydbase );

Classification:
Photon

September 20, 2005 Chapter 2 ¯ Ap — PhAB 81

ApCreateWidget()  2005, QNX Software Systems

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
ApCloseDBase(), ApCreateWidgetFamily(), ApOpenDBase(),
ApOpenDBaseFile(), ApSaveDBaseFile(), PtCreateWidget(),
PtSetParentWidget()
Accessing PhAB Modules from Code chapter of the Photon
Programmer’s Guide

82 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApCreateWidgetFamily()
Create a widget family by copying it from a PhAB widget database

Synopsis:
#Include <Ap.h>

PtWidget t *ApCreateWidgetFamily(
ApDBase t const *db,
char const *wgt name,
int x,
int y,
int nargs,
PtArg t const *args );

Description:
This function is used to create widgets by copying a widget family
from a PhAB widget database. This is very useful when you need to
create many instances of the same widget. For example, a file
manager may want to draw a file folder for each directory it displays.
The root of the widget family is created as a child of the default
parent, which is usually the most recently created container. To
change the default parent, call PtSetParentWidget().

☞ Before loading widgets from an external database, you should call

ApAddClass() for each widget class that you’ll likely encounter in it.
This will add the widget classes to the internal widget class table.

The arguments to ApCreateWidgetFamily() are as follows:

db points to a widget database opened with either

ApOpenDBase() or ApOpenDBaseFile()

wgt name the instance name of one of the widgets inside the
database

x and y convenience arguments for specifying the position of

the widget when it’s created

September 20, 2005 Chapter 2 ¯ Ap — PhAB 83

ApCreateWidgetFamily()  2005, QNX Software Systems

If y is -1, the widget’s original position is used.

☞
nargs and args
the standard resource argument counter and argument
list used by PtCreateWidget()

ApCreateWidgetFamily() creates the named widget and, for container

class widgets, any children of the widget.

☞ The pointers of the widget’s children aren’t directly available using

this function. If you need access to the container’s children, you’ll
need to call ApCreateWidget() for the container and each widget
inside it. If you create them in the same hierarchical order as defined
in the database, the parent-child relationship will be maintained.

Returns:
A pointer to the widget created for wgt name, or NULL on failure.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
ApCloseDBase(), ApCreateWidget(), ApOpenDBase(),
ApOpenDBaseFile(), ApSaveDBaseFile(), PtCreateWidget(),
PtSetParentWidget()

84 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApCreateWidgetFamily()

Accessing PhAB Modules from Code chapter of the Photon

Programmer’s Guide

September 20, 2005 Chapter 2 ¯ Ap — PhAB 85

ApDeleteWidget()  2005, QNX Software Systems
Remove widgets from a widget database

Synopsis:
#include <Ap.h>

int ApDeleteWidget( ApDBase t *db,

char const *wgt name );

Description:
ApDeleteDBWidget() removes the widget named wgt name from the
widget database indicated by db. Only a single widget is deleted with
this function; if a container widget is deleted, its child widgets remain
in the database.

Returns:
0 Successful completion

-1 Failure

Examples:
ApDBase t *my dbase;

my dbase = ApOpenDBaseFile( "/home/me/mydbase.wgtp" );

ApDeleteWidget( my dbase, "my icon" );

ApSaveDBaseFile( my dbase, "/home/me/mydbase.wgtp" );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

86 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApDeleteWidget()

See also:
ApCopyWidget(), ApOpenDBase(), ApOpenDBaseFile(),
ApSaveDBaseFile()
Accessing PhAB Modules from Code chapter of the Photon
Programmer’s Guide

September 20, 2005 Chapter 2 ¯ Ap — PhAB 87

ApError()  2005, QNX Software Systems
Display an error message dialog

Synopsis:
#include <Ap.h>

void ApError( PtWidget t *widget,

int errnum,
char const *app prefix,
char const *error message,
char const *location );

Description:
ApError() displays an error message dialog on the screen. This is a
modeless dialog that doesn’t wait for a user response. It displays a
formatted error message and a single OK button for acknowledgment.
The arguments are:

widget A pointer to the parent widget for the error message

dialog.

errnum The standard errno value set by the operation that

failed. The errno variable and its values are defined in
<errno.h>.

app prefix A string of prefix letters for identifying the

application. For example, PhAB is the prefix for the
Photon Application Builder.

error message
The error text to be displayed.

location The location in the code where the error occurred. If

you don’t want the location displayed, specify NULL.

ApError() builds the message, in order, from the following:

¯ app prefix

¯ error message

88 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApError()

¯ the string associated with the value of errnum

¯ location, if specified

Examples:
If you call ApError() as follows, specifying the location,

ApError( ABW base, errno, "PhAB", "Unable to save file",

FILE );

then the error dialog is formatted as:

PhAB: Unable to save file(Permission denied) in

(save function.c)

In the example above, FILE is a compiler directive to insert the

name of the source file, and (Permission denied) is the string
associated with the current value of errno.
If you make the same call, but omit the location,

ApError( ABW base, errno, "PhAB", "Unable to save file",

NULL );

then the error dialog is formatted as:

PhAB: Unable to save file(Permission denied)

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Ap — PhAB 89

ApError()  2005, QNX Software Systems

See also:
PtAskQuestion()
PtMessage in the Widget Reference

90 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApFreeBitmapRes()
Free a bitmap resource structure

Synopsis:
void ApFreeBitmapRes (ApBitmap t *bitmap);

Description:
This function frees a bitmap resource structure returned by
ApGetBitmapRes(). It doesn’t free the bitmap planes or colors
because they point back into the widget database.

☞ You can’t change the number of planes in a PtBitmap widget unless

the Pt FREE MEMORY flag is set in the widget’s Pt ARG FLAGS
resource. If you set this flag in conjunction with ApGetBitmapRes(),
you must make a copy of the data before setting the resources, so that
bitmap data isn’t freed from the widget database.

Examples:
ApBitmap t *bitmap;

bitmap = ApGetBitmapRes (db, "icon");

PtSetArg (&args[0], Pt ARG BITMAP COLORS, bitmap->colors,
bitmap->nplanes);
PtSetArg (&args[1], Pt ARG BITMAP DATA, bitmap->data, 0);
PtSetResources (ABW bitmap wgt, 2, args);
ApFreeBitmapRes (bitmap);

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Ap — PhAB 91

ApFreeBitmapRes()  2005, QNX Software Systems

See also:
ApBitmap t, ApGetBitmapRes()
Accessing PhAB Modules from Code chapter of the Photon
Programmer’s Guide

92 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApGetBitmapRes()
Extract bitmap data from a widget in a widget database

Synopsis:
#include <Ap.h>

ApBitmap t *ApGetBitmapRes(
ApDBase t const *dbase,
char const *wgt name );

Description:
This function lets you extract bitmap images from a PtBitmap
widget in a PhAB widget database.
The dbase argument points to a widget database opened with either
ApOpenDBase() or ApOpenDBaseFile(). The wgt name argument is
the instance name of one of the widgets inside the database.
This function doesn’t give you the height and width of the extracted
image. You must use the extracted bitmap data in another PtBitmap
widget that has the exact same dimensions.
This function is mainly used to perform simple animation. You can
create a series of tiles, using PtBitmap widgets of the same
dimensions, in a PhAB widget database; to create the animation,
cycle through the tiles by pulling out the bitmaps in sequence,
updating another PtBitmap widget that is visible within the
application window.
Depending on the size of the bitmaps being used and the background
colors, the animation will be relatively free of flicker. To get the best
look and performance out of your animations, we recommend that
you use PtLabel widgets and images rather than PtBitmap widgets,
especially if the bitmaps are fairly large (that is, greater than 64
pixels); see ApGetImageRes().

September 20, 2005 Chapter 2 ¯ Ap — PhAB 93

ApGetBitmapRes()  2005, QNX Software Systems

☞ You can’t change the number of planes in a PtBitmap widget unless

the Pt FREE MEMORY flag is set in the widget’s Pt ARG FLAGS
resource. If you set this flag in conjunction with ApGetBitmapRes(),
you must make a copy of the data before setting the resources, so that
bitmap data isn’t freed from the widget database.

Returns:
A pointer to the bitmap data structure (see ApBitmap t), or NULL if
the widget or data couldn’t be found.

☞ Don’t free the pointer returned by the function. It points directly to

the data within the widget database. When the database is closed, the
pointer is freed automatically.

Examples:
This example replaces the image stored in a bitmap widget. For this
example to work, the old and new bitmaps must have the same
dimensions, number of colors/planes, and order of colors.

ApBitmap t *bitmap;
PtArg t args[1];

mydbase = ApOpenDBase( ABM mypicture );

bitmap = ApGetBitmapRes( mydbase, "mybitmap" );

if ( bitmap ) {
PtSetArg( &args[0], Pt ARG BITMAP DATA,
bitmap->data, 0 );
PtSetResources( ABW bitmap wgt, 1, args );
}

ApCloseDBase( mydbase );

94 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApGetBitmapRes()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
ApBitmap t, ApFreeBitmapRes(), ApGetImageRes(),
ApOpenDBase(), ApOpenDBaseFile(), ApCloseDBase()
Accessing PhAB Modules from Code chapter of the Photon
Programmer’s Guide

September 20, 2005 Chapter 2 ¯ Ap — PhAB 95

ApGetImageRes()  2005, QNX Software Systems
Extract the image data from a widget

Synopsis:
#include <Ap.h>

PhImage t *ApGetImageRes(
ApDBase t const *dbase,
char const *wgt name );

Description:
ApGetImageRes() lets you extract images from a widget in a PhAB
widget database.
The dbase argument is the widget database pointer returned from
ApOpenDBase(). The wgt name argument is the name of widget
within the database that has the image you’re trying to extract.
This function is mainly used to perform simple animation. You can
create a series of tiles, using any widget that supports images, in a
PhAB widget database; to create the animation, cycle through the tiles
by pulling out the images in sequence, updating another widget that is
visible within the application window.

Returns:
A pointer to a PhImage t structure, or NULL if the widget or image
data couldn’t be found.

☞ This function returns a pointer into the widget database; don’t close
the database while still using the image. If you must close the widget
database, do the following first:

1 Copy the image data and palette.

2 Update the PhImage t structure to point to the new copies of

the data.

96 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApGetImageRes()

Examples:
PhImage t *image;
PtArg t args[1];

mydbase = ApOpenDBase( ABM mypicture );

image = ApGetImageRes( mydbase, "myimage" );

/* update the label widget with the new image */

if ( image ) {
PtSetArg( &args[0], Pt ARG LABEL DATA,
image, sizeof( *image ) );
PtSetResources( ABW label wgt, 1, args );
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
ApGetBitmapRes(), ApOpenDBase(), ApOpenDBaseFile(),
PgDrawPhImagemx(), PhImage t, PhReleaseImage(),
PhMakeGhostBitmap(), PhMakeTransBitmap(), PxLoadImage()
“Animation” in the Raw Drawing and Animation chapter, and the
Accessing PhAB Modules from Code chapter of the Photon
Programmer’s Guide

September 20, 2005 Chapter 2 ¯ Ap — PhAB 97

ApGetInstance()  2005, QNX Software Systems
Get the module link instance pointer for a widget

Synopsis:
#include <Ap.h>

PtWidget t *ApGetInstance( PtWidget t *widget );

Description:
ApGetInstance() is used to obtain the widget’s module link instance
pointer. For most modules, PhAB generates manifests that let you
access the widgets within that module directly, provided only one
instance of the module exists at a time.
Because window modules allow you to have multiple instances, you
can’t always use the direct access manifests; the manifest will only be
valid for the last instance of the window. For windows, you may need
either to save the module link instance pointer when creating the
window, or to use this function within the callback to determine the
origin of the callback.

Returns:
The module link instance pointer for the widget, or NULL if it cannot
be determined.

Examples:
PtArg t args[1];

mywindow callback( PtWidget t *widget, ... )

{
PtWidget t *window;

/* from which window did this come? */

if ( window = ApGetInstance( widget ) ) {
/* set the widget selected to red */
PtSetArg( &args[0], Pt ARG FILL COLOR,
Pg RED, 0 );
PtSetResources( ApGetWidgetPtr( window,
ApName( widget ) ), 1, args );
}

return( Pt CONTINUE );
}

98 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApGetInstance()

☞ An interesting observation about this callback example is that it

doesn’t know which window is being modified or which widget gets
changed. It acts on whatever widget the user selects.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
ApGetWidgetPtr()

September 20, 2005 Chapter 2 ¯ Ap — PhAB 99

ApGetItemText()  2005, QNX Software Systems
Get the text for a menu item

Synopsis:
#include <Ap.h>

char * ApGetItemText( ApMenuLink t *menu,

int item name);

Description:
ApGetItemText() is used to extract the text of a menu item in a PhAB
menu module. The menu argument is a pointer to a PhAB menu link
structure. The item name argument is the ABN name of the menu
item, as generated by PhAB. If a language translation is in effect, the
translated string is returned rather than the default text built into the
application.

Returns:
A pointer to a text string or translated text, or NULL if the ABN name
is invalid.

!
CAUTION: Don’t free the returned text string, or your application
will crash.

If you call ApModifyItemText() after calling ApGetItemText() for the

same menu item, the string returned by ApGetItemText() becomes
invalid.

Examples:
text = ApGetItemText( &mymenu, ABN item1 );

Classification:
Photon

100 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApGetItemText()

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
ApModifyItemText()

September 20, 2005 Chapter 2 ¯ Ap — PhAB 101

ApGetTextRes()  2005, QNX Software Systems
Get a translated text string from a widget database

Synopsis:
#include <Ap.h>

char *ApGetTextRes( ApDBase t const *db,

char const *name );

Description:
ApGetTextRes() extracts the translated text string from the database
identified by db using name as the widget instance name identifier.

Returns:
The translated text string if successful, NULL if not found, or name or
db if invalid.

Examples:
ApDBase t *mydbase;
char *string;

mydbase = ApOpenDBase( ABM mypicture);

string = ApGetTextRes( mydbase, "msg1" );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

102 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApGetTextRes()

See also:
ApGetBitmapRes(), ApGetImageRes(), ApOpenDBase(),
ApOpenDBaseFile()
Accessing PhAB Modules from Code chapter of the Photon
Programmer’s Guide

September 20, 2005 Chapter 2 ¯ Ap — PhAB 103

ApGetWidgetPtr()  2005, QNX Software Systems
Get the instance pointer for a widget in a given module

Synopsis:
#include <Ap.h>

PtWidget t *ApGetWidgetPtr( PtWidget t *link instance,

int wgt name );

Description:
ApGetWidgetPtr() is used to obtain the widget’s instance pointer
within the specified link instance. For most modules, PhAB generates
manifests that let you access the widgets within the module directly,
provided only one instance of the module exists at a time.
Because window modules allow you to have multiple instances you
can’t always use the direct access manifests; the manifest will only be
valid for the last instance of the window. For windows, you may need
either to save the link instance pointer when creating the window, or
to use this function to find the correct link instance for the callback.
Once you determine the module link instance, you’ll need to extract
the widget pointer from it.
The wgt name argument is the ABN name value of the widget. PhAB
automatically generates these name values for you when you generate
your code.

Returns:
A pointer to the the widget within the module link instance, or NULL
if one was not found.

Examples:
PtArg t args[1];

mywindow callback( PtWidget t *widget, ... )

{
PtWidget t *window;

/* from which window did this come? */

if ( window = ApGetInstance( widget ) ) {
/* set the widget selected to red */

104 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApGetWidgetPtr()

PtSetArg( &args[0], Pt ARG FILL COLOR,

Pg RED, 0 );
PtSetResources(
ApGetWidgetPtr( window, ABN mywidget ),
1, args );
}

return( Pt CONTINUE );
}

☞ If you compare this example with the one for ApGetInstance(), you’ll
notice a subtle difference. This example modifies a specific widget
identified by ABN mywidget, while the other example modifies any
widget affected by the callback.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
ApGetInstance()

September 20, 2005 Chapter 2 ¯ Ap — PhAB 105

ApInfo t  2005, QNX Software Systems
PhAB information structure

Synopsis:
#include <Ap.h>

typedef struct {
short reason;
PtWidget t *widget;
} ApInfo t;

Description:
This structure is used as the second argument to most functions
generated by PhAB, including code callbacks and module-setup
functions.
The possible values for reason are:

Value Description
ABR PRE REALIZE Pre-realize setup function
ABR POST REALIZE Post-realize setup function
ABR CODE Code-type callback
ABR DONE Done-type callback
ABR CANCEL Cancel-type callback

The widget argument is a pointer to the widget that invoked the

callback function. This is very useful in setup functions to determine
which widget initiated the link callback.

Classification:
Photon

106 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApInfo t

See also:
ApWidget()
PtCallback t in the Photon Widget Reference
“Module setup functions” and “Code-callback functions” in the
Working with Code chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 2 ¯ Ap — PhAB 107

ApInstanceName()  2005, QNX Software Systems
Return the widget’s instance name string

Synopsis:
#include <Ap.h>

char * ApInstanceName( PtWidget t *widget );

Description:
ApInstanceName() returns a widget’s instance string name if it’s
defined. The string name is the name given to the widget in the
Widget Instance Name field of the Control Panel. By default, string
names are not saved with the widget, in order to save memory.
To embed string names in the widget, you must enable this feature:

1 In PhAB, select the Startup Info/Modules command from the

Application menu.

2 In the Application Startup Information dialog, click the Incl

Names button.

Returns:
The widget’s instance name string, or NULL if the widget doesn’t
have string name data attached.

Examples:
my callback( PtWidget t *widget, ... )
{

if ( strcmp( ApInstanceName( widget ),

"done button" ) == 0 ) {
/* done button processing */
}

108 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApInstanceName()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Ap — PhAB 109

ApModifyItemState()  2005, QNX Software Systems
Modify the state of menu items

Synopsis:
#include <Ap.h>

int ApModifyItemState( ApMenuLink t *menu,

int state,
int item no,
item no, ..., NULL );

Description:
ApModifyItemState() modifies the state of menu items in a PhAB
menu module. The arguments are:

menu A pointer to a PhAB menu link structure.

state The state you want to set for the menu items:
¯ AB ITEM DIM - disabled
¯ AB ITEM NORMAL - enabled and not set
¯ AB ITEM SET - set on (toggle item)

item no, item no, ..., NULL

A list of menu items, followed by NULL to terminate the
list. The menu items are values that are generated by PhAB
for each menu item in a menu module.

You can call ApModifyItemState() at any time to set the menu item
states and the effect will be seen when the menu is displayed. This
lets you set menu item states as soon as conditions within your
application change.

Returns:
1 Successful completion

110 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApModifyItemState()

Examples:
In this example, mymenu is a pointer to the address of the menu name,
which is equivalent to the instance name for the menu module.

/* Dim the ABN opt1, ABN opt2, and ABN opt3 menu items. */
ApModifyItemState( &mymenu, AB ITEM DIM, ABN opt1, ABN opt2,
ABN opt3, NULL );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
ApGetItemText(), ApModifyItemText()
“Enabling, disabling, or toggling menu items” in the Working with
Code chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 2 ¯ Ap — PhAB 111

ApModifyItemText()  2005, QNX Software Systems
Modify the text for a menu item

Synopsis:
#include <Ap.h>

int ApModifyItemText( ApMenuLink t *menu,

int item num,
char const *new text );

Description:
ApModifyItemText() modifies the text for a menu item in a PhAB
menu module. The arguments are:

menu A pointer to a PhAB menu link structure.

item num The number of the menu item, as generated by PhAB.

new text A pointer to the replacement menu item text.

☞ ApModifyItemText() stores the address given by new text; it doesn’t

make a copy of the string pointed to by new text. Don’t modify the
string after calling this function

You can call ApModifyItemText() at any time to set the menu item text
and the effect will be seen when the menu is displayed. This allows to
you set menu item text as soon as conditions within your application
change.

Returns:
0 The item number isn’t valid.

1 Success.

112 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApModifyItemText()

Examples:
In this example, mymenu is a pointer to the address of the menu name,
which is equivalent to the instance name for the menu module.

/* Change ABN opt1 to say "New Option 1 Text" */

ApModifyItemText( &mymenu, ABN opt1, "New Option 1 Text" );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
ApGetItemText(), ApModifyItemState()
“Changing menu-item text” in the Working with Code chapter of the
Photon Programmer’s Guide

September 20, 2005 Chapter 2 ¯ Ap — PhAB 113

ApModuleFunction()  2005, QNX Software Systems
Specify the setup function for a PhAB internal link callback

Synopsis:
#include <Ap.h>

void ApModuleFunction( ApEventLink t *link callback,

int (*function)(),
int realize flags );

Description:
ApModuleFunction() is used to specify the setup function for a PhAB
internal link callback. The realize flags argument indicates when the
setup function should be called:

¯ AB FUNC PRE REALIZE

¯ AB FUNC POST REALIZE

¯ AB FUNC BOTH

When you create an internal link callback, PhAB lets you specify the
setup function. ApModuleFunction() lets you change that setup
function. The new function is retained until changed again.

Examples:
ApModuleFunction( ABM mydialog, setup module, AB FUNC BOTH );
ApCreateModule( ABM mydialog, NULL, NULL );

setup module( PtWidget t *widget, ... ) {

/* setup processing for module */
}

Classification:
Photon

114 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApModuleFunction()

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
ApCreateModule()

September 20, 2005 Chapter 2 ¯ Ap — PhAB 115

ApModuleLocation()  2005, QNX Software Systems
Specify the module location for a PhAB internal link

Synopsis:
#Include <Ap.h>

void ApModuleLocation( ApEventLink t *link callback,

int loc type,
int x offset,
int y offset );

Description:
ApModuleLocation() is used to specify the module location for a
PhAB internal link. The loc type is one of the following:

¯ AB LOC BELOW WGT

¯ AB LOC ABOVE WGT

¯ AB LOC RIGHT WGT

¯ AB LOC LEFT WGT

¯ AB LOC TOP LEFT

¯ AB LOC TOP RIGHT

¯ AB LOC BOT LEFT

¯ AB LOC BOT RIGHT

¯ AB LOC CENTER

¯ AB LOC REL CURSOR

¯ AB LOC REL MODULE

¯ AB LOC DEFAULT — let the window manager determine the

position. The offsets are ignored.

¯ AB LOC ABSOLUTE — x offset and y offset are the absolute

coordinates for the module.

116 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApModuleLocation()

The x offset and y offset pixel values are applied to the location
determined from the loc type. For example, if you want a dialog to
appear 100 pixels from the top right edge of the screen, set the x offset
to -100 and the loc type to AB LOC TOP RIGHT.
When you create an internal link in PhAB, you can set the location.
This function lets you change that value if required. The new location
will remain in effect until changed again.

Examples:
/* place the module in the center of the screen */
ApModuleLocation( ABM mydialog, AB LOC CENTER, 0, 0 );
ApCreateModule( ABM mydialog, NULL, NULL );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Ap — PhAB 117

ApModuleParent()  2005, QNX Software Systems
Specify the parent for a window module

Synopsis:
#Include <Ap.h>

void ApModuleParent( ApEventLink t *link callback,

int parent,
PtWidget t *widget );

Description:
ApModuleParent() lets you specify the parent module for a Window
module. The parent is one of the following:

AB PARENT The widget argument points to the window module’s

new parent.

AB NO PARENT
The window module should have no parent. The
widget argument is ignored.

☞ This function works only with window modules.

Examples:
Change my window to have no parent at all:

ApModuleParent( ABM my window, AB NO PARENT, NULL );

ApCreateModule( ABM my window, NULL, NULL );

Change new window to have the base window as its parent:

ApModuleParent( ABM new window, AB PARENT, ABW base );

ApCreateModule( ABM new window, NULL, NULL );

118 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApModuleParent()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Ap — PhAB 119

ApName()  2005, QNX Software Systems
Return a PhAB name value for the specified widget

Synopsis:
#include <Ap.h>

int ApName( PtWidget t *widget );

Description:
ApName() returns a PhAB name value for the specified widget. This
name value can be compared with the global name values PhAB
generates for your application code. These name values make it easier
to access and compare widgets in callback functions. It also lets you
use the same callback function for more than one widget.

Returns:
A PhAB name value, or -1 if the widget doesn’t have a name.

Examples:
my callback( PtWidget t *widget, ... )
{
if ( ApName( widget ) == ABN widget1 ) {
/* do widget1 processing */
} else {
if ( ApName( widget ) == ABN widget2 ) {
/* do widget2 processing */
} else {
/* do something else? */
}
}
}

☞ ABN widget1 and ABN widget2 are name values generated by PhAB
for widgets in your application with instance names of widget1 and
widget2.

120 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApName()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Ap — PhAB 121

ApOpenDBase(), ApOpenDBaseFile()  2005, QNX Software
Systems
Open a module as a widget database
Synopsis:
#include <Ap.h>

ApDBase t *ApOpenDBase(
ApEventLink t const *link callback );

ApDBase t *ApOpenDBaseFile( char const *path );

Description:
These functions open a module as a widget database:

¯ ApOpenDBase() takes an internal link manifest generated by

PhAB.

¯ ApOpenDBaseFile() lets you open external module files as widget

databases. External module files supported have a .wgtp, .wgti,
.wgtd, or .wgtw extension.

Typically, the module is a picture, but it can also be a window or

dialog.

☞ Before calling ApOpenDBaseFile(), you should call ApAddClass() for

each widget class that you’ll likely encounter in the database. This
will add the widget classes to the internal widget class table.

Returns:
A pointer to a PhAB picture database structure, or NULL for failure.

Examples:
ApDBase t *mydbase;
PtArg t args[2];

mydbase = ApOpenDBase( ABM mypicture );

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

"This Widget", 0 );
ApCreateWidget( mydbase, "my label widget", 10, 10, 1,
args );

122 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApOpenDBase(),
ApOpenDBaseFile()

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

"That Widget", 0 );
PtSetArg( &args[1], Pt ARG FILL COLOR, Pg WHITE, 0 );
ApCreateWidget( mydbase, "my label widget", 10, 30, 2,
args );

ApCloseDBase( mydbase );

If the widget database is an external file, it can be opened using

ApOpenDBaseFile() instead of ApOpenDBase():

mydbase = ApOpenDBaseFile( "mypicture.wgtp" );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
ApAddClass(), ApCreateWidget(), ApCreateWidgetFamily()
Accessing PhAB Modules from Code chapter of the Photon
Programmer’s Guide

September 20, 2005 Chapter 2 ¯ Ap — PhAB 123

ApResClose()  2005, QNX Software Systems
Close the file of module resource records

Synopsis:
void ApResClose ( void );

Description:
All PhAB applications have module resource records bound into the
executable. A PhAB application opens its own binary file to access
these records, and keeps the file open for better performance until the
application loses focus. Once the file is closed, it isn’t reopened
unless a module record is required.
If your application has only a single base window or dialogs that are
infrequently used, you can force the binary file to be closed by calling
this function. This reduces the number of file descriptors in use, as
well as freeing resources used for accessing other nodes in a
networking environment.

Examples:
In the post-realize callback of the base window:

if (apinfo->reason == ABR POST REALIZE) {

ApResClose ();
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

124 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApSaveDBaseFile()
Save a widget database as an external file

Synopsis:
#include <Ap.h>

int ApSaveDBaseFile( ApDBase t const *db,

char const *path );

Description:
ApSaveDBaseFile() saves a widget database as an external file. Both
internally bound widget databases and previously loaded external
widget databases can be saved as external files.

Returns:
0 Successful completion

-1 Failure

Examples:
/* Open a PhAB picture database, delete my icon,
and save the database again. */
ApDBase t *my dbase;

my dbase = ApOpenDBaseFile( "/home/me/mydbase.wgtp" );

ApDeleteWidget( my dbase, "my icon" );

ApSaveDBaseFile( my dbase, "/home/me/mydbase.wgtp" );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Ap — PhAB 125

ApSaveDBaseFile()  2005, QNX Software Systems

See also:
ApCloseDBase(), ApCopyWidget(), ApDeleteWidget(),
ApOpenDBase(), ApOpenDBaseFile()
Accessing PhAB Modules from Code chapter of the Photon
Programmer’s Guide

126 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApSetTranslation()
Change the current translation to another language

Synopsis:
#include <Ap.h>

int ApSetTranslation( char const *lang ext );

Description:
ApSetTranslation() changes the current translation file to the one
defined by lang ext. If lang ext is NULL, the translation is set to the
default (i.e. the original language used in the application). If the
extension pointed to by lang ext is invalid, the translation file isn’t
changed.
When you run your application outside of PhAB, it looks for the
translation files as follows:

1 in the directories listed in the ABLPATH environment variable,

if defined. This list takes the form:
dir:dir:dir:dir

Unlike the PATH environment variable, the current directory

must be indicated by a period, not an empty string. An empty
string in ABLPATH indicates the directory where the
executable is.

2 in the same directory as the executable, if the ABLPATH

environment variable isn’t defined

Returns:
0 Successful completion.

-1 The translation extension is invalid.

September 20, 2005 Chapter 2 ¯ Ap — PhAB 127

ApSetTranslation()  2005, QNX Software Systems

Examples:
/* Set the current translation to German: */

ApSetTranslation( "de DE");

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
ApAppendTranslation(), ApOpenDBase(), ApOpenDBaseFile(),
ApGetTextRes()

128 Chapter 2 ¯ Ap — PhAB September 20, 2005

 2005, QNX Software Systems ApWidget()
Determine the widget that initiated a link callback

Synopsis:
#include <Ap.h>

PtWidget t *ApWidget( PtCallbackInfo t *cbinfo );

Description:
ApWidget() is used within module setup functions to determine the
widget that initiated the link callback.

Returns:
A pointer to the initiating widget.

Examples:
mysetup function( ..., PtCallbackInfo t cbinfo ) {
if (ApName(ApWidget(cbinfo)) == ABN widget1) {
/* setup based on widget1 */
} else {
if (ApName(ApWidget(cbinfo)) == ABN widget2) {
/* setup based on widget2 */
} else {
/* common setup */
}
}
return( Pt CONTINUE );
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 2 ¯ Ap — PhAB 129

ApWidget()  2005, QNX Software Systems

See also:
For another method of determining the widget that initiated a link
callback, see the ApInfo t structure.

130 Chapter 2 ¯ Ap — PhAB September 20, 2005

 Chapter 3
mbstr — Multibyte-Character

September 20, 2005 Chapter 3 ¯ mbstr — Multibyte-Character 131

 2005, QNX Software Systems

The Photon libraries provide multibyte string functions that are useful
if you’re using multibyte-character strings. Use the functions
described in this chapter instead of the usual 8-bit-character functions
such as strlen().

September 20, 2005 Chapter 3 ¯ mbstr — Multibyte-Character 133

mbstrblen()  2005, QNX Software Systems
Find the number of multibyte characters in part of a string

Synopsis:
#include <photon/PhProto.h>

int mbstrblen( char const *text,

int max bytes,
int width,
int *bytes );

Description:
The mbstrblen() function returns the number of multibyte characters
made up of max bytes bytes in the string text, and sets bytes to the
number of bytes used to compose the number of multibyte characters
returned.
The width argument must be the maximum number of bytes used to
represent a single character, or 0 to accept the default value of 3.
The bytes argument won’t equal max bytes if there are fewer than
max bytes bytes in the string, or if the last byte doesn’t fall at the end
of a multibyte character.

Returns:
The number of multibyte characters made up of max bytes bytes in
the string text.

Classification:
Photon

Safety
Interrupt handler No
Signal handler Yes
Thread Yes

134 Chapter 3 ¯ mbstr — Multibyte-Character September 20, 2005

 2005, QNX Software Systems mbstrblen()

See also:
mbstrlen(), mbstrnlen()

September 20, 2005 Chapter 3 ¯ mbstr — Multibyte-Character 135

mbstrchr()  2005, QNX Software Systems
Search for a multibyte character in a string

Synopsis:
#include <photon/PhProto.h>

char * mbstrchr( char const *string,

char const *mbchar,
int *count );

Description:
The mbstrchr() function searches for a character in string that
matches mbchar. If such a match occurs in string, count (if provided)
is set to the number of multibyte characters the matching character is
from the beginning of the string. For example, if mbchar matches the
first character in string, count is set to 0. If mbchar matches the
second character in string, count is set to 1.
A pointer to the beginning of the matching character within string is
returned. If no match is found, the function returns NULL and doesn’t
change count.

Returns:
A pointer to the matching character, if found, or NULL if not found

Examples:
#include <Pt.h>
main()
{
char string[] = "Hello there: äîòéü found";
char mbchar[] = "é";
int count;
char *p;

if( p = mbstrchr( string, mbchar, &count ) )

printf(
"character found: character offset %d\n byte offset %d\n",
count, p - string );
else
printf( " Not found " );
}

136 Chapter 3 ¯ mbstr — Multibyte-Character September 20, 2005

 2005, QNX Software Systems mbstrchr()

Classification:
Photon

Safety
Interrupt handler No
Signal handler Yes
Thread Yes

See also:
mbstrnchr(), mbstrrchr()

September 20, 2005 Chapter 3 ¯ mbstr — Multibyte-Character 137

mbstrlen()  2005, QNX Software Systems
Find the length of a multibyte character string

Synopsis:
#include <photon/PhProto.h>

int mbstrlen( char const *text,

int char width,
int *bytes );

Description:
The mbstrlen() function returns the number of multibyte characters in
the string text, and sets bytes to the number of bytes in text.
The char width must be set to the maximum number of bytes used to
represent a single character. Setting char width to 0 will use the
maximum character width.

Returns:
The number of multibyte characters in the string.

Classification:
Photon

Safety
Interrupt handler No
Signal handler Yes
Thread Yes

See also:
mbstrblen(), mbstrnlen()

138 Chapter 3 ¯ mbstr — Multibyte-Character September 20, 2005

 2005, QNX Software Systems mbstrnchr()
Search for a multibyte character in part of a string

Synopsis:
#include <photon/PhProto.h>

char * mbstrnchr( char const *string,

char const *mbchar,
int num,
int *count );

Description:
This function searches for a multibyte character in string that matches
mbchar. The match must occur in the first num multibyte characters.
If such a match is found, count (if provided) is set to the number of
multibyte characters the matching character is from the beginning of
the string. For example, if mbchar matches the first character in
string, count is set to 0. If mbchar matches the second character in
string, count is set to 1.

Returns:
A pointer to the beginning of the matching character within string. If
no match is found within num characters, the function returns NULL
and doesn’t change count.

Examples:
Search the first 5 multibyte characters for a match to the provided
UTF-8 character:

#include <Pt.h>
main()
{
char string[] = "Hello there: äîòéü found";
char mbchar[] = "é";
int count;
char *p;

if( p = mbstrnchr( string, mbchar, 5, &count ) )

printf(
"character found: character offset %d\n byte offset %d\n",
count, p - string );

September 20, 2005 Chapter 3 ¯ mbstr — Multibyte-Character 139

mbstrnchr()  2005, QNX Software Systems

else
printf( " Not found " );
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler Yes
Thread Yes

See also:
mbstrchr(), mbstrrchr()

140 Chapter 3 ¯ mbstr — Multibyte-Character September 20, 2005

 2005, QNX Software Systems mbstrncmp()
Compare part of a multibyte-character string

Synopsis:
#include <photon/PhProto.h>

int mbstrncmp( char const *str1,

char const *str2,
int len,
int char width );

Description:
This function compares len multibyte characters from str1 with str2.
The char width parameter must be set to the maximum number of
bytes used to represent a single character.

Returns:
An integer less than, equal to, or greater than zero, indicating that str1
is less than, equal to, or greater than str2.

Classification:
Photon

Safety
Interrupt handler No
Signal handler Yes
Thread Yes

September 20, 2005 Chapter 3 ¯ mbstr — Multibyte-Character 141

mbstrnlen()  2005, QNX Software Systems
Find the number of bytes used by a multibyte-character string

Synopsis:
#include <photon/PhProto.h>

int mbstrnlen( char const *text,

int max len,
int char width,
int *num );

Description:
The mbstrnlen() function returns the number of bytes occupied by
max len characters in the string text.
The char width parameter must be set to the maximum number of
bytes used to represent a single character or 0 to accept the default
value of 3.
The num parameter is set to the number of characters formed by the
number of bytes returned. This will be different from max len if there
are fewer than max len multibyte characters in text.

Returns:
The number of bytes occupied by max len characters in the string text.

Classification:
Photon

Safety
Interrupt handler No
Signal handler Yes
Thread Yes

142 Chapter 3 ¯ mbstr — Multibyte-Character September 20, 2005

 2005, QNX Software Systems mbstrnlen()

See also:
mbstrblen(), mbstrnlen()

September 20, 2005 Chapter 3 ¯ mbstr — Multibyte-Character 143

mbstrrchr()  2005, QNX Software Systems
Search backwards for a multibyte character in a string

Synopsis:
#include <photon/PhProto.h>

char *mbstrrchr( char const *string base,

char const *start char,
char const *mbchar,
int *count );

Description:
This function searches backwards from start char to string base
(inclusive) for a multibyte character that matches mbchar. If such a
match is found, count (if provided) is set to the number of multibyte
characters the matching character is from the start of the search. For
example, if mbchar matches the start char character in string, count
is set to 0. If mbchar matches the previous character in string, count
is set to 1.
A pointer to the beginning of the matching character within
string base is returned. If no match is found, the function returns
NULL and doesn’t change count.
Note that start char doesn’t need to be on a character boundary.

Returns:
A pointer to the matched character, or NULL if none was found.

Examples:
Search from the end of a string for a match to the provided UTF-8
character:

#include <Pt.h>
main()
{
char string[] = "Hello there: äîòéü found";
char mbchar[] = "é";
int count;
char *p;

144 Chapter 3 ¯ mbstr — Multibyte-Character September 20, 2005

 2005, QNX Software Systems mbstrrchr()

if( p = mbstrrchr( string, string + strlen( string ) - 1,

mbchar, &count ) )
printf(
"character found: \n%d characters from the end.\n",
count );
printf( "byte offset %d.\n", p - string );
else
printf( " Not found " );
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler Yes
Thread Yes

See also:
mbstrchr(), mbstrnchr()

September 20, 2005 Chapter 3 ¯ mbstr — Multibyte-Character 145

 Chapter 4
Pf — Font Server

September 20, 2005 Chapter 4 ¯ Pf — Font Server 147

 2005, QNX Software Systems

These functions provide font services to Photon applications and

drivers. Using them, you can:

¯ Calculate text extents and metrics.

¯ Generate bitmaps of character strings.

September 20, 2005 Chapter 4 ¯ Pf — Font Server 149

PfAttach()  2005, QNX Software Systems
Attach to font server

Synopsis:
#include <photon/Pf.h>

struct Pf ctrl *PfAttach( const char *device,

long size );

Description:
This function attaches to the font server. The device parameter
specifies the prefix name of the server; if it’s NULL, the prefix is the
value in the PHFONT environment variable, or /dev/phfont if this
isn’t set. The size parameter specifies the size of a shared-memory
region to set up between the task and the server for returning text
bitmaps (normally required only by graphics drivers). If this is -1, the
value of the PHFONTMEM environment variable is used; if 0, no
such memory region is created.
This routine is normally called by PhAttach() as part of the standard
Photon initialization sequence. This routine is also automatically
invoked by the Pf library when it detects that the font server has been
restarted. The font control structure pointer is stored in the global
Photon Ph control structure as Ph ->font.
Instead of calling this function directly, set the two environment
variables (PHFONT and PHFONTMEM) to the new values before
performing standard Photon initialization.

Returns:
A pointer to an internal control structure if successful, NULL
otherwise.

Classification:
Photon

150 Chapter 4 ¯ Pf — Font Server September 20, 2005

 2005, QNX Software Systems PfAttach()

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 4 ¯ Pf — Font Server 151

PfDetach()  2005, QNX Software Systems
Detach from font server

Synopsis:
#include <photon/Pf.h>

void PfDetach( struct Pf ctrl *pf );

Description:
This function detaches the task from the font server. The pf parameter
must be the control structure returned by a previous call to PfAttach().
All memory used by this structure is also released, including any
shared-memory region and local metrics code.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

152 Chapter 4 ¯ Pf — Font Server September 20, 2005

 2005, QNX Software Systems PfExtentComponents()
Calculate the extent of a text string and invoke a callback

Synopsis:
#include <photon/Pf.h>

PhRect t *PfExtentComponents(
PhRect t *extent,
PhPoint t const *pos,
const char *font,
const char *str,
int len,
void (*func)(PhRect t *,
const char *,
const char *, int) );

Description:
This function calculates the extent of a text string as per
PfExtentText(), and also invokes a user callback function func for each
component of the string (a run of characters sourced from a single
font).
This facility is used by the phrelay utility to determine which font
files have to be downloaded to the remote system in order to correctly
render a string.
The callback function is passed an extent rectangle, the filename of
the font required, and the string and length of the character run.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 4 ¯ Pf — Font Server 153

PfExtentComponents()  2005, QNX Software Systems

See also:
PfExtentText()

154 Chapter 4 ¯ Pf — Font Server September 20, 2005

 2005, QNX Software Systems PfExtentText()
Calculate the extent rectangle of a text string

Synopsis:
#include <photon/Pf.h>

PhRect t *PfExtentText( PhRect t *extent,

PhPoint t const *pos,
const char *font,
const char *str,
int len);

Description:
This function calculates the extent rectangle of a text string. The base
font is given by font; this determines the ascender/descender values of
the extent. The width is dependent on the string — the actual font
used by characters within the string may be different than this base
font (as specified in the fontext and fontmap files).
The string str is a Unicode, multibyte string of len bytes. If len is 0,
strlen(str) is assumed.
The text extent is returned in a rectangle, with ul.x being the left
bearing, lr.x-min(ul.x,0)+1 the right, ul.y the ascender, and
lr.y the descender. The baseline of the font is at position y=0; the
width of the string.
The resulting extent is offset by the point passed in pos. If this is
NULL, no offset is applied.
If metrics for the base font have been loaded locally (see
PfLoadMetrics()) then this extent may be calculated internally;
otherwise a request is sent to the font server.

Returns:
A pointer to the extent rectangle (extent) if successful, NULL
otherwise.

September 20, 2005 Chapter 4 ¯ Pf — Font Server 155

PfExtentText()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PfFractionalExentText(), PfLoadMetrics(), PgExtentText()

156 Chapter 4 ¯ Pf — Font Server September 20, 2005

 2005, QNX Software Systems PfFractionalExtentText()
Calculate the extent rectangle of a text string, using fractional scaling

Synopsis:
#include <photon/Pf.h>

PhRect t *PfFractionalExtentText(
PhRect t *extent,
PhPoint t const *pos,
const char *font,
long xsize,
long ysize,
const char *str,
int len);

Description:
This function calculates the extent rectangle of a text string. The base
font is given by font; this determines the ascender/descender values of
the extent. The xsize and ysize arguments define the size of the font in
16.16 fixed-point format.

☞ This function is valid only for scalable fonts. No font mappings are
performed.

The string str is a Unicode, multibyte string of len bytes. If len is 0,

strlen(str) is assumed.
The text extent is returned in a rectangle, with ul.x being the left
bearing, lr.x-min(ul.x,0)+1 the right, ul.y the ascender, and
lr.y the descender. The baseline of the font is at position y=0; the
width of the string.
The resulting extent is offset by the point passed in pos. If this is
NULL, no offset is applied.
If metrics for the base font have been loaded locally (see
PfLoadMetrics()) then this extent may be calculated internally;
otherwise a request is sent to the font server.

September 20, 2005 Chapter 4 ¯ Pf — Font Server 157

PfFractionalExtentText()  2005, QNX Software Systems

Returns:
A pointer to the extent rectangle (extent) if successful, NULL
otherwise.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PfExtentText(), PfFractionalRenderText(), PfLoadMetrics(),
PgExtentText()

158 Chapter 4 ¯ Pf — Font Server September 20, 2005

 2005, QNX Software Systems PfFractionalRenderText()
Render a string, using fractioanl scaling, via a callback function

Synopsis:
#include <photon/Pf.h>

int PfFractionalRenderText(
const char *font,
long xsize,
long ysize,
const char *str,
int len,
PhPoint t const *pos,
PhRect t const *clip,
void (*func)( const PhPoint t *,
const FontRender *));

Description:
This function renders the given string via a user callback function.
The base font is given by font. The xsize and ysize arguments define
the size of the font in 16.16 fixed-point format.
The actual fonts used by the string depend on the characters in it and
the information in the fontext and fontmap files. The string str is a
Unicode, multibyte string of len bytes. If len is 0, strlen(str) is
assumed.
The text is to be rendered at the location specified by pos, and clipped
to the rectangle specified by clip. If clip is NULL, it’s ignored. The
font server performs coarse character clipping only.
When a request to construct the bitmap is sent to the font server, the
string bitmap is returned, for efficiency, in the shared-memory region
created through the initial call to PfAttach().
This function is normally used only by graphics drivers, but may be
useful for application programs that have to obtain text bitmap data
directly.
The user callback function func() is called with the desired pen
location and the metrics of the bitmap. If the entire bitmap doesn’t fit

September 20, 2005 Chapter 4 ¯ Pf — Font Server 159

PfFractionalRenderText()  2005, QNX Software Systems

in the allocated memory, multiple calls to the font server and the user
function can be made, advancing the pen as appropriate between calls.
The FontRender metrics structure contains at least the following
members:

PhPoint t size
The bounding size of the bitmap (in pixels).

PhPoint t offset
The offset of the bitmap (the upper-left of the extent).

int width The width of the bitmap.

short bpl The number of bytes per line.

short bpp The number of bits per pixel (1 for normal output, 4
for anti-aliased).
unsigned char *bmptr
A pointer to the bitmap data (stored row-wise).

Returns:
0 Success.

-1 An error occurred; the value of errno is set appropriately.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

160 Chapter 4 ¯ Pf — Font Server September 20, 2005

 2005, QNX Software Systems PfGlyph()
Obtain the metrics and/or bitmap for the specified character

Synopsis:
#include <photon/Pf.h>

int PfGlyph( const char *font,

long symbol,
FontRender *metrics,
unsigned char *bitmap,
int size,
FontName fontused);

Description:
This routine is useful for obtaining arbitrary character glyphs, such as
cursors. The PfGlyph() function obtains from the base font the
metrics and/or bitmap for the character specified by symbol. When
metrics is non-NULL, it must point to a FontRender structure that
will be filled in with the character metrics (see PfRenderText()).
When bitmap is non-NULL, it must point to an area of size bytes that
the character bitmap will be placed in. It may be rendered as a
bitmap/image in conjunction with the metrics information. The actual
font used to supply the character will be placed in the string pointed
to by fontused if non-NULL.

Returns:
0 Success.

-1 An error occurred; the value of errno is set appropriately.

Classification:
Photon

Safety
Interrupt handler No
continued. . .

September 20, 2005 Chapter 4 ¯ Pf — Font Server 161

PfGlyph()  2005, QNX Software Systems

Safety
Signal handler No
Thread No

See also:
PfRenderText()

162 Chapter 4 ¯ Pf — Font Server September 20, 2005

 2005, QNX Software Systems PfLoadFont()
Preload a font within the font server

Synopsis:
#include <photon/Pf.h>

int PfLoadFont( const char *font,

unsigned flags,
FontName fontused );

Description:
This function preloads a font (from disk into memory) within the font
server in order to speed up subsequent use of that font. By default, a
font is loaded only when required by a PgExtentText() or
PgDrawText() call. The font parameter specifies the name of the
desired font (e.g. helv12).
The flags parameter consists of zero or more of the
PHFONT LOAD METRICS or PHFONT LOAD IMAGES flags, which
indicate if the font metrics and/or bitmaps should be preloaded. If no
flags are specified, the validity of the input font name is checked.
If fontused is non-NULL, the string it points to will be set to the real
name of the font, which may be different than the input if the font is
unknown or mapped as an alias to another font (via the fontmap file).

Returns:
0 Success.

-1 An error occurred; the value of errno is set appropriately.

Classification:
Photon

Safety
Interrupt handler No
continued. . .

September 20, 2005 Chapter 4 ¯ Pf — Font Server 163

PfLoadFont()  2005, QNX Software Systems

Safety
Signal handler No
Thread No

See also:
PgExtentText(), PgDrawText()

164 Chapter 4 ¯ Pf — Font Server September 20, 2005

 2005, QNX Software Systems PfLoadMetrics()
Load metric information for the given font

Synopsis:
#include <photon/Pf.h>

int PfLoadMetrics( const char *font );

Description:
This function loads metric information for the given font from the
font server into memory and links this font into a list of available
local metrics.
Subsequent text extents of this base font, involving characters solely
within this font, will be performed locally by the task itself rather than
by the font server. This may result in faster operation of
extent-intensive tasks, such as HTML viewers, at a cost of about 1400
bytes of memory per font (for a standard font that defines characters
0x20-0xFF).

Returns:
0 Success.

-1 An error occurred; the value of errno is set appropriately.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 4 ¯ Pf — Font Server 165

PfQueryFont()  2005, QNX Software Systems
Get information about a font

Synopsis:
#include <photon/Pf.h>

int PfQueryFont( const char *font,

FontQueryInfo *info);

Description:
This function gets information about the font specified by font after
first mapping font to a valid font name (if appropriate). The
FontQueryInfo structure pointed to by info is filled in. It contains at
least:

FontName font Internal name of the font (e.g. helv12b).

FontDescription desc
Textual name of the font family (e.g. Helvetica).
short size Point size of the font.

unsigned short style

Style and attributes of this font, made up of the
following bits:
¯ PHFONT INFO PROP — proportional-width
font.
¯ PHFONT INFO FIXED — fixed-width font.
¯ PHFONT INFO PLAIN — plain/regular style.
¯ PHFONT INFO BOLD — bold style.
¯ PHFONT INFO ITALIC — italic style.
¯ PHFONT INFO BLDITC — bold italic style.
short ascender
Ascender value of the font (in pixels).
short descender
Descender value of the font (in pixels).

166 Chapter 4 ¯ Pf — Font Server September 20, 2005

 2005, QNX Software Systems PfQueryFont()

short width Width of widest character in this font.

long lochar Lowest character value defined in this font.

long hichar Highest character value defined in this font.

Returns:
0 Successful completion.

-1 An error occurred (errno is set).

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 4 ¯ Pf — Font Server 167

PfQueryFonts()  2005, QNX Software Systems
Construct a list of fonts

Synopsis:
#include <photon/Pf.h>

int PfQueryFonts( long symbol,

unsigned flags,
FontDetails list[],
int n );

Description:
This function constructs a list of all fonts that may be used to render
the character specified by the symbol parameter. For example, use
’A’ to get a list of normal/Latin fonts, or 0x3A9 (omega) to get a list
of Greek fonts. (See PkKeyDef.h or ISO/EIC 10646-1 for a list of
symbols.)
The list of fonts is further filtered by the flags parameter, which may
contain any combination of the following:

Set this: To select:

PHFONT SCALABLE Scalable fonts
PHFONT BITMAP Bitmapped fonts
PHFONT PROP Proportional fonts
PHFONT FIXED Fixed-width fonts
PHFONT ALL FONTS All fonts

Up to n matching font family entries are placed in the user-provided

list.

168 Chapter 4 ¯ Pf — Font Server September 20, 2005

 2005, QNX Software Systems PfQueryFonts()

☞ If n is 0 and list is NULL, PfQueryFonts() returns the number of

matching fonts but doesn’t try to fill in the list. You can use this
feature to determine the number of items to allocate for the list.

The entries in the list are of type FontDetails, and contain the
following fields:

FontDescription desc
Textual name of the font family (e.g. Helvetica).

FontName stem Base stem of the font family (e.g. helv).

short losize Lowest point size available for this font. If losize
and hisize are both 0, the font is scalable.

short hisize Highest point size available for this font. If hisize
and losize are both 0, the font is scalable.
unsigned short flags
Various stylistic/attribute flags for this font family:
¯ PHFONT INFO PROP — proportional-width
font.
¯ PHFONT INFO FIXED — fixed-width font.
¯ PHFONT INFO PLAIN — plain/regular style.
¯ PHFONT INFO BOLD — bold style.
¯ PHFONT INFO ITALIC — italic style.
¯ PHFONT INFO BLDITC — bold italic style.

Returns:
The number of matching fonts found, or -1 on error.

September 20, 2005 Chapter 4 ¯ Pf — Font Server 169

PfQueryFonts()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtFontSel (in the Photon Widget Reference)

170 Chapter 4 ¯ Pf — Font Server September 20, 2005

 2005, QNX Software Systems PfRenderText()
Render a string via a callback function

Synopsis:
#include <photon/Pf.h>

int PfRenderText(
const char *font,
const char *str,
int len,
PhPoint t const *pos,
PhRect t const *clip,
void (*func)( const PhPoint t *,
const FontRender *));

Description:
This function renders the given string via a user callback function.
The base font is given by font. The actual fonts used by the string
depend on the characters in it and the information in the fontext and
fontmap files. The string str is a Unicode, multibyte string of len
bytes. If len is 0, strlen(str) is assumed.
The text is to be rendered at the location specified by pos, and clipped
to the rectangle specified by clip. If clip is NULL, it’s ignored. The
font server performs coarse character clipping only.
When a request to construct the bitmap is sent to the font server, the
string bitmap is returned, for efficiency, in the shared-memory region
created through the initial call to PfAttach().
This function is normally used only by graphics drivers, but may be
useful for application programs that have to obtain text bitmap data
directly.
The user callback function func() is called with the desired pen
location and the metrics of the bitmap. If the entire bitmap doesn’t fit
in the allocated memory, multiple calls to the font server and the user
function can be made, advancing the pen as appropriate between calls.
The FontRender metrics structure contains at least the following
members:

September 20, 2005 Chapter 4 ¯ Pf — Font Server 171

PfRenderText()  2005, QNX Software Systems

PhPoint t size
The bounding size of the bitmap (in pixels).
PhPoint t offset
The offset of the bitmap (the upper-left of the extent).

int width The width of the bitmap.

short bpl The number of bytes per line.

short bpp The number of bits per pixel (1 for normal output, 4
for anti-aliased).
unsigned char *bmptr
A pointer to the bitmap data (stored row-wise).

Returns:
0 Success.

-1 An error occurred; the value of errno is set appropriately.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PfFractionalRenderText()

172 Chapter 4 ¯ Pf — Font Server September 20, 2005

 2005, QNX Software Systems PfUnloadMetrics()
Unload metric information for the given font

Synopsis:
#include <photon/Pf.h>

int PfUnloadMetrics( const char *font );

Description:
This function unloads the local metrics for the given font from
memory and releases any memory used for their storage. Subsequent
text extents of this base font are resolved by the font server rather than
being performed locally.

Returns:
0 Success.

-1 An error occurred: the value of errno is set appropriately.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 4 ¯ Pf — Font Server 173

 Chapter 5
Pg — Graphics

September 20, 2005 Chapter 5 ¯ Pg — Graphics 175

 2005, QNX Software Systems

The Photon graphics functions build a buffer of draw commands. The

application sends these commands to the Photon Manager, which in
turn sends them to the graphics driver. The graphics driver then
renders the commands on the screen.
Photon supports a set of simple, dual-purpose draw primitives that
you can stroke (that is, draw as an outline) or fill, or both. These
primitives include arcs, ellipses, polygons, rectangles, and rounded
rectangles.

☞ Instead of calling the Pg* functions directly, you should use widgets
whenever possible because widgets handle interaction with the user
and look after redrawing themselves when damaged. If you need to
do raw drawing, create a PtRaw
widget, and call the drawing primitives in its draw function. For more
information, see the Raw Drawing and Animation
chapter of the Photon Programmer’s Guide.

September 20, 2005 Chapter 5 ¯ Pg — Graphics 177

PgBackgroundShadings()  2005, QNX Software Systems
Calculate top and bottom shading colors

Synopsis:
void PgBackgroundShadings(PgColor t bg,
PgColor t *ts,
PgColor t *bs);

Description:
This function calculates the top and bottom shading colors that may
be used in a border to give an object a 3D appearance. Where possible
(based on the brightness of the background color), the top border
color will be lighter than the background and the bottom border color
will be darker than the background. Either of ts or bs may be NULL if
that component isn’t required.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

178 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgBlueValue()
Extract the blue component from a color value

Synopsis:
int PgBlueValue( PgColor t color );

Description:
This macro extracts the blue color component from a composite color
value (a PgColor t type). The result is between 0 and 255.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

Caveats:
PgBlueValue() is a macro.

See also:
PgCMY(), PgGreenValue(), PgHSV(), PgRedValue() PgRGB(),
PgSetFillColor(), PgSetFillDither()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 179

PgClearDrawBuffer()  2005, QNX Software Systems
Reset the current draw buffer

Synopsis:
void PgClearDrawBuffer( void );

Description:
This function resets the current draw buffer without flushing.

Examples:
/*
* Draw the following group of 3 lines
*/
PgDrawILine( 100, 100, 200, 300 );
PgDrawILine( 200, 300, 700, 700 );
PgDrawILine( 700, 700, 0, 0 );
PgFlush();

/*
* Don’t draw the following group of 3 lines
*/
PgDrawILine( 50, 100, 50, 300 );
PgDrawILine( 300, 20, 30, 700 );
PgDrawILine( 500, 700, 0, 100 );
PgClearDrawBuffer();
PgFlush();

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

180 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgClearDrawBuffer()

See also:
PgFlush(), PgSetDrawBufferSize()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 181

PgClearTranslation()  2005, QNX Software Systems
Restore the current translation to the default

Synopsis:
void PgClearTranslation( void );

Description:
This function restores the current translation to the default (0,0).

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgSetTranslation()

182 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgCMY()
Convert cyan, magenta, and yellow values to composite color format

Synopsis:
PgColor t PgCMY( int C, int M, int Y );

Description:
This macro converts cyan, magenta, and yellow values into a
PgColor t structure. It lets you approximate print-industry colors.
The values for C, M, and Y range from 0 to 255. If you set all three
arguments to 0, the color is white; if you set all three to 255, the color
is black.

Returns:
A composite color value.

Examples:

Color Composite color value

Black PgCMY( 255, 255, 255 );
White PgCMY( 0, 0, 0 );
Red PgCMY( 0, 255, 255 );
Green PgCMY( 255, 0, 255 );
Blue PgCMY( 255, 255, 0 );
Orange PgCMY( 0, 90, 255 );
Slate Blue PgCMY( 175, 160, 121 );

Classification:
Photon

September 20, 2005 Chapter 5 ¯ Pg — Graphics 183

PgCMY()  2005, QNX Software Systems

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgColor t, PgBlueValue(), PgGreenValue(), PgHSV(),
PgRedValue(), PgRGB(), PgSetFillColor(), PgSetFillDither()

184 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgColor t
Composite color value

Synopsis:
unsigned long PgColor t;

Description:
The PgColor t type definition describes a composite color value.
The lowest 8 bits contain the blue value, the next 8 bits contain the
green value, and the next 8 bits after that the red value:

Reserved Red Green Blue

0000 0000 rrrr rrrr gggg gggg bbbb bbbb

At least the following colors are defined in <photon/Pg.h>:

Pg BLACK Pg MAGENTA
Pg DGRAY Pg CYAN
Pg MGRAY Pg DGREEN
Pg GRAY Pg DCYAN
Pg WHITE Pg DBLUE
Pg RED Pg BROWN
Pg GREEN Pg PURPLE
Pg BLUE Pg CELIDON
Pg YELLOW

The following colors are also defined in <photon/Pg.h>:

Pg DEVICE COLOR
Interprets up to the least significant 24 bits as the value to put
into video memory.

September 20, 2005 Chapter 5 ¯ Pg — Graphics 185

PgColor t  2005, QNX Software Systems

This facility depends on the video hardware, and behaves differently

☞ depending on the graphics driver.
Pg INVERT COLOR
Use with PgSetDrawMode(Pg DRAWMODE XOR) for high
visibility XOR drawing.
Pg MIX COLOR
OR with color to enable color mixing.

Pg TRANSPARENT
Subsequent draw events won’t be rendered.

We’ve defined the following colors for compatibility with standard

VGA colors:

Pg VGA0 Pg VGA8
Pg VGA1 Pg VGA9
Pg VGA2 Pg VGAA
Pg VGA3 Pg VGAB
Pg VGA4 Pg VGAC
Pg VGA5 Pg VGAD
Pg VGA6 Pg VGAE
Pg VGA7 Pg VGAF

Classification:
Photon

See also:
PgBlueValue(), PgCMY(), PgColorHSV t PgGreenValue(),
PgHSV2RGB(), PgRedValue(), PgRGB(), PgRGB2HSV(),
PgSetFillColor(), PgSetFillDither(), PgSetStrokeColor(),
PgSetStrokeDither(), PgSetTextColor(), PgSetTextDither()

186 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgColorHSV t
Hue-saturation-value color value

Synopsis:
typedef struct {
unsigned short hue;
unsigned char sat, vid;
} PgColorHSV t;

Description:
The PgColorHSV t structure describes a hue-saturation-value color.
It’s used to convert a color defined as red, green, and blue into HSV. It
contains at least the following members:

unsigned short hue

Color angle; see PgHSV().

unsigned char sat

Color saturation.
unsigned char vid
Color value, or brightness.

Classification:
Photon

See also:
PgColor t, PgHSV(), PgHSV2RGB(), PgRGB2HSV()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 187

PgColorMatch()  2005, QNX Software Systems
Query for best color matches

Synopsis:
int PgColorMatch(int n,
PgColor t const *in,
PgColor t *out);

Description:
This function queries the graphics driver for the best color matches
for a number of color values. This is particularly useful with a
palette-based graphics driver.
An array of n colors from the in array is passed to the driver, which
selects the closest match for each color and returns these in the out
array.
With a true or direct color driver, the color is returned unchanged.
With a palette-based driver, the closest color is found by computing
within a RGB color cube the Cartesian distance between the color and
each palette entry, and selecting the closest entry of a similar intensity.

Returns:
0 Successful completion.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

188 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgCreateGC()
Allocate a graphics context

Synopsis:
PhGC t *PgCreateGC( int unused );

Description:
This function allocates a graphics context. A graphics context
contains the entire draw state, including color, clipping, and current
region.

☞ If your application calls both Pg and Pt functions, you must provide

one graphics context for the Pg functions and a separate context for
the Pt functions. To do this, call PgSetGC() every time you switch
from one API to the other.

PgCreateGC() doesn’t use its argument; set it to 0.

Returns:
A pointer to a graphics context, or NULL if an error occurs.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDestroyGC(), PgSetDrawBufferSize(), PgSetGC()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 189

PgDefaultFill()  2005, QNX Software Systems
Reset fill attribute to its default value

Synopsis:
void PgDefaultFill( PhGC t *GC );

Description:
This function resets the fill attribute portion of the provided graphics
context to its system default.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDefaultGC(), PgDefaultText(), PgDefaultMode(),
PgDefaultStroke()

190 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDefaultGC()
Reset all graphics context attributes to their default system values

Synopsis:
void PgDefaultGC( PhGC t *GC );

Description:
This function resets all attributes of the provided graphics context to
their system defaults.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDefaultMode(), PgDefaultFill(), PgDefaultText(),
PgDefaultStroke()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 191

PgDefaultMode()  2005, QNX Software Systems
Reset draw mode and plane mask to their default values

Synopsis:
void PgDefaultMode( PhGC t *GC );

Description:
This function resets the draw mode and plane mask portions of the
provided graphics context to their system defaults.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDefaultGC(), PgDefaultFill(), PgDefaultText(), PgDefaultStroke(),
PgSetDrawMode(), PgSetPlaneMask()

192 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDefaultStroke()
Reset stroke attribute to its system default

Synopsis:
void PgDefaultStroke( PhGC t *GC );

Description:
This function resets the stroke attribute portion of the provided
graphics context to its system default.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDefaultGC(), PgDefaultFill(), PgDefaultText(), PgDefaultMode()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 193

PgDefaultText()  2005, QNX Software Systems
Reset text attribute to its system default

Synopsis:
void PgDefaultText( PhGC t *GC );

Description:
This function resets the text attribute portion of the provided graphics
context to system defaults.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDefaultGC(), PgDefaultFill(), PgDefaultMode(),
PgDefaultStroke()

194 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDestroyGC()
Release resources of a graphics context

Synopsis:
void PgDestroyGC( PhGC t *GC );

Description:
This function releases any resources consumed by the specified
graphics context. If the draw buffer for that context contains draw
commands, the buffer is flushed before it’s released.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgCreateGC(), PgGetGC(), PgSetGC()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 195

PgDrawArc()  2005, QNX Software Systems
Draw an arc, pie, or chord

Synopsis:
int PgDrawArc( PhPoint t const *center,
PhPoint t const *radii,
unsigned int start,
unsigned int end,
int flags );

Description:
This function builds a command in the draw buffer to draw an arc.
The center argument defines the arc’s center, and radii defines the
arc’s x and y radii.
The start and end arguments define the start and end angles (both
arguments are specified in bi-grads; see below). The arc is drawn
counter-clockwise, from the start angle to the end angle. To draw a
complete circle, make the two angles equal to each other. An angle of
0 bi-grads is on the horizon to the right of the center.

☞ A circle is divided into 65536 gradations called binary gradations or

bi-grads. Thus, 0x2000 is 45 degrees, 0x4000 is 90 degrees,
0x8000 is 180 degrees, and 0xC000 is 270 degrees.

The flags argument controls what type of arc is drawn:

To draw: Set flags to:

A curve with the end points connected by a Pg ARC CHORD
straight line.
A curve with the end points connected to the Pg ARC PIE
arc’s center.
The curve alone. Pg ARC

You can OR one of the following into any flags value:

¯ Pg DRAW STROKE — draw as a line.

196 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawArc()

¯ Pg DRAW FILL — fill the arc.

¯ Pg DRAW FILL STROKE — fill the arc, then stroke it.

Returns:
0 Success.

-1 The draw buffer is too small to hold the current draw state and
the draw command.

Examples:
The following example:

DrawFillArc() {
PhPoint t c = { 80, 60 };
PhPoint t r = { 72, 52 };

PgSetFillColor( Pg RED );
PgDrawArc( &c, &r, 0x0000, 0x4000, Pg DRAW FILL |
Pg ARC CHORD);
PgSetFillColor( Pg YELLOW );
PgDrawArc( &c, &r, 0x5555, 0x9555, Pg DRAW FILL |
Pg ARC PIE);
PgSetStrokeColor( Pg WHITE );
PgSetFillColor( Pg PURPLE );
PgDrawArc( &c, &r, 0xAAAA, 0xEAAA,
Pg DRAW FILL STROKE | Pg ARC PIE);
}

will draw:

The following example:

September 20, 2005 Chapter 5 ¯ Pg — Graphics 197

PgDrawArc()  2005, QNX Software Systems

DrawStrokeArc() {
PhPoint t c = { 80, 60 };
PhPoint t r = { 72, 52 };

PgSetStrokeColor( Pg WHITE );
PgDrawArc( &c, &r, 0x0000, 0x4000, Pg DRAW STROKE |
Pg ARC CHORD );
PgSetStrokeColor( Pg YELLOW );
PgDrawArc( &c, &r, 0x5555, 0x9555, Pg DRAW STROKE |
Pg ARC PIE );
PgSetStrokeColor( Pg YELLOW );
PgDrawArc( &c, &r, 0xAAAA, 0xEAAA, Pg DRAW STROKE |
Pg ARC );
}

will draw:

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
To draw stroked arcs, see also:

198 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawArc()

PgSetStrokeCap(), PgSetStrokeColor(), PgSetStrokeDash(),

PgSetStrokeDither(), PgSetStrokeJoin(), PgSetStrokeWidth()
To draw filled arcs, see also:
PgSetFillColor(), PgSetFillDither(), PgSetFillTransPat()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 199

PgDrawBevelBox(), PgDrawIBevelBox()  2005, QNX Software
Systems
Draw a beveled box
Synopsis:
int PgDrawBevelBox( PhRect t const *rect,
PgColor t secondary,
short width,
int flags );

int PgDrawIBevelBox( int x1, int y1,

int x2, int y2,
PgColor t secondary,
short width,
int flags );

Description:
These functions build a command in the draw buffer to draw a
beveled box. This box is used for the outlines of buttons and panes.
The upper and left edges of the box are drawn in the current stroke
color; the lower and right edges are drawn in the secondary color. The
width argument determines the thickness of the lines.

☞ For PgDrawBevelBox(), the width parameter must be ≤ 15.

When you increase the thickness, the lines grow toward the middle of
the beveled box. The maximum width is given by Pg BEVEL MAX.
The flags argument must be one of the following:

¯ Pg DRAW STROKE — draw as a line.

¯ Pg DRAW FILL — fill the box.

¯ Pg DRAW FILL STROKE — fill the box, then stroke it.

☞ PgDrawBevelBox() requires a pointer to a PhRect t structure,

whereas PgDrawIBevelBox() takes individual arguments.

200 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawBevelBox(),
PgDrawIBevelBox()
Returns:
0 Success.

-1 The draw buffer is too small to hold the current draw state and
the draw command.

Examples:
The following example:

DrawBevelBox() {
PhRect t r = { 8, 8, 152, 112 };
PgSetFillColor( Pg GREY );
PgSetStrokeColor( Pg WHITE );
PgDrawBevelBox( &r, Pg DGREY, 4,
Pg DRAW FILL STROKE );
}

will draw:

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Pg — Graphics 201

PgDrawBevelBox(), PgDrawIBevelBox()  2005, QNX Software

Systems

See also:
PgDrawBeveled(), PgDrawRect(), PgSetFillColor(),
PgSetFillDither(), PgSetFillTransPat(), PgSetStrokeColor(),
PgSetStrokeDither(), PgSetStrokeTransPat()

202 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawBeveled()
Draw a beveled rectangle or arrow

Synopsis:
int PgDrawBeveled( PhRect t const *rect,
PhPoint t const *radii,
PgColor t secondary,
short width,
int flags );

Description:
This function builds a command in the draw buffer to draw a beveled
rectangle or arrow. The rect parameter defines the area that the object
will fill. The flags parameter defines how the object will be drawn,
and includes options for defining the types of corners that it will have.
The upper and left edges of the object are drawn in the current stroke
color; the lower and right edges are drawn in the secondary color.
The width argument determines the thickness of the lines. When you
increase the thickness, the lines grow toward the middle of the
beveled object.
The flags argument must be one of the following:

Pg BEVEL CLIP
Draw a box with clipped corners. The radii argument
determines how much each corner is clipped.
Pg BEVEL ROUND
Draw a box with rounded corners. The radii argument
determines how much each corner is rounded.
Pg BEVEL SQUARE
Draw a box with square corners (default). The radii argument
isn’t used with this option. The corners will look like those
created by PgDrawBevelBox().
Pg BEVEL AUP
Draw an arrow pointing up. The radii argument isn’t used with
this option.

September 20, 2005 Chapter 5 ¯ Pg — Graphics 203

PgDrawBeveled()  2005, QNX Software Systems

Pg BEVEL ADOWN
Draw an arrow pointing down. The radii argument isn’t used
with this option.

Pg BEVEL ALEFT
Draw an arrow pointing left. The radii argument isn’t used with
this option.

Pg BEVEL ARIGHT
Draw an arrow pointing right. The radii argument isn’t used
with this option.

You can OR the flags argument with one of the following:

¯ Pg DRAW STROKE — draw as a line.

¯ Pg DRAW FILL — fill the box.

¯ Pg DRAW FILL STROKE — fill the box, then stroke it.

You can also OR the flags argument with the following:

¯ Pg BEVEL SET — swap the upper-left and lower-right colors; this

makes the beveled object appear to be set.

Returns:
0 Success.

-1 The draw buffer is too small to hold the current draw state and
the draw command.

Examples:
The following example:

DrawBeveled() {
PhRect t rc = { 8, 8, 152, 56 };
PhRect t rr = { 8, 64, 152, 112 };
PhPoint t pc = { 8, 8 };
PhPoint t pr = { 12, 12 };

204 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawBeveled()

PgSetFillColor( Pg GREY );
PgSetStrokeColor( Pg WHITE );
PgDrawBeveled( &rc, &pc, Pg DGREY, 2,
Pg DRAW FILL STROKE | Pg BEVEL CLIP );
PgDrawBeveled( &rr, &pr, Pg DGREY, 2,
Pg DRAW FILL STROKE | Pg BEVEL ROUND );
}

will draw:

The following example:

DrawBevelArrow() {
PhRect t rup = { 20, 4, 44, 16 };
PhRect t rdown = { 20, 48, 44, 60 };
PhRect t rleft = { 4, 20, 16, 44 };
PhRect t rright = { 48, 20, 60, 44 };

PgSetFillColor( Pg GREY );
PgSetStrokeColor( Pg WHITE );
PgDrawBeveled( &rup, NULL, Pg DGREY, 1,
Pg DRAW FILL STROKE | Pg BEVEL AUP );
PgDrawBeveled( &rdown, NULL, Pg DGREY, 1,
Pg DRAW FILL STROKE | Pg BEVEL ADOWN );
PgDrawBeveled( &rleft, NULL, Pg DGREY, 1,
Pg DRAW FILL STROKE | Pg BEVEL ALEFT );
PgDrawBeveled( &rright, NULL, Pg DGREY, 1,
Pg DRAW FILL STROKE | Pg BEVEL ARIGHT );
}

will draw:

September 20, 2005 Chapter 5 ¯ Pg — Graphics 205

PgDrawBeveled()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDrawBevelBox(), PgDrawRect(), PgDrawIRect(),
PgDrawRoundRect(), PgSetFillColor(), PgSetFillDither(),
PgSetFillTransPat(), PgSetStrokeColor(), PgSetStrokeDither(),
PgSetStrokeTransPat()

206 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawBezier(), PgDrawBeziermx()
Draw a stroked and/or filled bézier

Synopsis:
int PgDrawBezier( PhPoint t const *ptr,
int num,
PhPoint t const *pos,
int flags );

int PgDrawBeziermx( PhPoint t const *ptr,

int num,
PhPoint t const *pos,
int flags );

Description:
These functions build a command in the draw buffer to draw a
multisegment Bézier curve from an array of points.
Each Bézier curve is defined by 4 points. The last point of a curve
becomes the first point of the next curve. The first and fourth points
are anchor points; the line passes through these. The second and third
points are control points; the curve is “pulled” toward these points.
The flags argument must be one of the following:

¯ Pg DRAW STROKE — draw a stroked curve.

¯ Pg DRAW FILL — draw a filled curve.

¯ Pg DRAW FILL STROKE — draw a filled curve, then stroke it.

You can OR flags with any combination of the following:

¯ Pg CLOSED — connect the last point to the first.

¯ Pg RELATIVE — use relative coordinates to draw the curve. Each

point is relative to the previous point.

For absolute coordinates, pos is added to each point pointed to by ptr.

For relative coordinates, the first coordinate is the sum of pos and the
first point of the array; any subsequent coordinate is the sum of the
previous point and the next point of the array.

September 20, 2005 Chapter 5 ¯ Pg — Graphics 207

PgDrawBezier(), PgDrawBeziermx()  2005, QNX Software Systems

☞ If you call the “mx” form of this function, the data isn’t physically
copied into the draw buffer. Instead, a pointer to the array is stored
until the draw buffer is flushed. Make sure you call PgFlush() before
you modify the point array.

Returns:
0 Success.
-1 The draw buffer is too small to hold the current draw state, the
draw command, and the data. Increase the size of the draw
buffer or decrease the number of points.

Examples:
The following example:
DrawFillStrokeBezier() {
PhPoint t o = { 0, 0 };
PhPoint t p[] = {43, 71, -92, -18, 344, -6, 20, 99};

PgSetStrokeDash( "\1", 1, 0x10000 );

PgSetStrokeColor( Pg GRAY );
PgDrawPolygon( &p, 4, &o,
Pg DRAW STROKE | Pg CLOSED );
PgSetStrokeDash( NULL, 0, 0 );
PgSetStrokeColor( Pg YELLOW );
PgSetFillColor( Pg PURPLE );
PgDrawBezier( &p, 4, &o,
Pg DRAW FILL STROKE | Pg CLOSED );
}

will draw:

208 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawBezier(), PgDrawBeziermx()

The dotted lines show where the control points are relative to the
anchor points.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDrawPolygon(), PgFlush()
To draw stroked Bézier curves, see also:
PgSetStrokeColor(), PgSetStrokeCap(), PgSetStrokeDash(),
PgSetStrokeDither(), PgSetStrokeJoin(), PgSetStrokeWidth()
To draw filled Bézier curves, see also:
PgSetFillColor(), PgSetFillDither(), PgSetFillTransPat()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 209

PgDrawBitmap(), PgDrawBitmapmx()  2005, QNX Software
Systems
Draw a bitmap
Synopsis:
int PgDrawBitmap( void const *ptr,
int flags,
PhPoint t const *pos,
PhPoint t const *size,
int bpl,
long tag );

int PgDrawBitmapmx( void const *ptr,

int flags,
PhPoint t const *pos,
PhPoint t const *size,
int bpl,
long tag );

Description:
These functions build a command in the draw buffer to draw a bitmap.
The function starts the bitmap at pos and extends it down and to the
right according to size.
The bpl argument indicates the number of bytes per line of image data
(that is, the offset from one line of data to the next). To calculate the
size of the data transferred to the graphics driver, multiply bpl by
size.y. You can determine the size and bpl arguments with the value
returned by a PxLoadImage() call.
The data pointed to by ptr is one bit per pixel. If the pixel value is 1,
the pixel is drawn with the color set by PgSetTextColor() or
PgSetTextDither(). If the pixel value is 0, the pixel is drawn as
transparent unless you’ve set flags to Pg BACK FILL. With
Pg BACK FILL, the pixel is drawn with the color set by
PgSetFillColor() or PgSetFillDither(). The pixels are drawn most
significant bit first.
The tag argument is used for data caching by programs such as
phrelay. This argument is ignored if you set it to 0. To calculate a
tag value, use PxCRC().

210 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawBitmap(),
PgDrawBitmapmx()

☞ If you call the “mx” form of this function, the data isn’t physically
copied into the draw buffer. Instead, a pointer to the array is stored
until the draw buffer is flushed. Make sure you call PgFlush() before
you modify the bitmap.
If the data is in shared memory, the mx form of this function will
automatically pass a shared memory reference instead of the bitmap.

Returns:
0 Successful completion

-1 The draw buffer is too small to hold the current draw state, the
draw command, and one pixel line of the image. Increase the
size of the draw buffer or decrease the width of the image.

Examples:
The following example:
PhPoint t TestBitmapSize = { 64, 64 };
int TestBitmapBPL = 8;
char TestBitmap[64*8] = { "512 bytes of bitmap data" };

DrawSimpleBitmap() {
PhPoint t p = { 8, 8 };

PgSetTextColor( Pg WHITE );
PgDrawBitmap( TestBitmap, 0, &p,
&TestBitmapSize, TestBitmapBPL, 0 );
}

will draw:

The following example:

DrawBackFillBitmap() {

September 20, 2005 Chapter 5 ¯ Pg — Graphics 211

PgDrawBitmap(), PgDrawBitmapmx()  2005, QNX Software

Systems

PhPoint t p = { 8, 8 };

PgSetTextColor( Pg WHITE );
PgSetFillColor( Pg PURPLE );
PgDrawBitmap( TestBitmap, Pg BACK FILL, &p,
&TestBitmapSize, TestBitmapBPL, 0 );
}

will draw:

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDrawRepBitmap(), PgFlush(), PgSetFillColor(), PgSetFillDither(),
PgSetTextColor(), PgSetTextDither(), PgShmemCreate(), PxCRC(),
PxLoadImage()

212 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawEllipse()
Draw an ellipse

Synopsis:
int PgDrawEllipse( PhPoint t const *center,
PhPoint t const *radii,
unsigned int flags );

Description:
This function builds a command in the draw buffer to draw an ellipse.
The center argument defines the ellipse’s center and radii defines its x
and y radii.
The flags argument must be one of the following:

¯ Pg DRAW STROKE — draw as a line.

¯ Pg DRAW FILL — fill the ellipse.

¯ Pg DRAW FILL STROKE — fill the ellipse, then stroke it.

To have the function interpret the center and radii arguments as the
upper-left and lower-right coordinates respectively, OR flags with
Pg EXTENT BASED.

Returns:
0 Success.

-1 The draw buffer is too small to hold the current draw state and
the draw command.

Examples:
The following example:

DrawStrokeElli() {
PhPoint t c = { 80, 60 };
PhPoint t r = { 72, 52 };

PgSetStrokeColor( Pg WHITE );
PgDrawEllipse( &c, &r, Pg DRAW STROKE );
}

September 20, 2005 Chapter 5 ¯ Pg — Graphics 213

PgDrawEllipse()  2005, QNX Software Systems

will draw:

The following example:

DrawFillElli() {
PhPoint t c = { 80, 60 };
PhPoint t r = { 72, 52 };

PgSetFillColor( Pg PURPLE );
PgDrawEllipse( &c, &r, Pg DRAW FILL );
}

will draw:

The following example:

DrawFillStrokeElli() {
PhPoint t c = { 80, 60 };
PhPoint t r = { 72, 52 };

PgSetFillColor( Pg PURPLE );
PgSetStrokeColor( Pg WHITE );

PgDrawEllipse( &c, &r, Pg DRAW FILL STROKE );

}

214 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawEllipse()

will draw:

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDrawRoundRect(), PgSetFillColor(), PgSetFillDither(),
PgSetFillTransPat(), PgSetStrokeColor(), PgSetStrokeDither(),
PgSetStrokeTransPat()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 215

PgDrawGrid()  2005, QNX Software Systems
Draw a grid

Synopsis:
int PgDrawGrid( PhRect t const *r,
PhPoint t const *g );

Description:
This function fills the rectangle specified by r with the number of
divisions specified by g. The number of lines drawn equals the
number of divisions plus 1.
This function builds a draw command to draw the grid. The size of
the grid is defined by the r argument with g.x+1 vertical lines and
g.y+1 horizontal lines. If g.x is 0, no vertical lines are drawn; if g.y is
0, no horizontal lines are drawn.

Returns:
0 Success.
-1 The draw buffer is too small to hold the current draw state and
the draw command.

Examples:
The following example uses PgDrawGrid() to make a grid of 8
squares by 8 squares; each square is 8 by 8 pixels:
void GridStandard() {
PhRect t r = { 8, 8, 72, 72 };
PhPoint t g = { 8, 8 };

PgSetStrokeColor( Pg WHITE );
PgDrawGrid( &r, &g );
}

This code draws:

216 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawGrid()

The following example uses PgDrawGrid() to generate 20 ticks.

Every 5th tick is made larger by calling PgDrawGrid() again with
different parameters:

void GridTicks() {
PhRect t r = { 8, 24, 108, 28 };
PhPoint t g = { 20, 0 };

PgSetStrokeColor( Pg WHITE );
PgDrawGrid( &r, &g );
r.ul.y-=1;
r.lr.y+=1;
g.x=4;
PgSetStrokeWidth( 3 );
PgSetStrokeCap( Pg POINT CAP );
PgDrawGrid( &r, &g );
PgSetStrokeWidth( 0 );
}

This code draws:

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgSetStrokeColor(), PgSetStrokeWidth()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 217

PgDrawImage(), PgDrawImagemx()  2005, QNX Software Systems
Draw an image

Synopsis:
int PgDrawImage( void const *ptr,
int type,
PhPoint t const *pos,
PhDim t const *size,
int bpl,
long tag );

int PgDrawImagemx( void const *ptr,

int type,
PhPoint t const *pos,
PhDim t const *size,
int bpl,
long tag );

Description:
These functions build a command in the draw buffer to draw an
image. The functions start the image at pos and extend it down and to
the right according to size.

☞ Instead of using this function, we recommend using a PhImage t

structure and calling PgDrawPhImagemx(). To make one of the
colors in the image transparent, call PhMakeTransBitmap().

The bpl argument indicates the number of bytes per line of image data
(that is, the offset from one line of data to the next).
To calculate the size of the data transferred to the graphics driver,
multiply bpl by size.y. You can determine the size and bpl arguments
with the value returned by PxLoadImage().
The tag argument is used for data caching by programs such as
phrelay. To calculate the tag, use PxCRC(). This argument is
ignored if you set it to 0.
The type argument controls how the image data pointed to by ptr is
interpreted by the graphics driver. For information on the different
types of images, see PhImage t.

218 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawImage(), PgDrawImagemx()

☞ If you call the “mx” form of this function, the data isn’t physically
copied into the draw buffer. Instead, a pointer to the array is stored
until the draw buffer is flushed. Make sure you call PgFlush() before
you modify the image.
If the data is in shared memory, the mx form of this function will
automatically pass a shared memory reference instead of the image.

Returns:
0 Success.

-1 The draw buffer is too small to hold the current draw state, the
draw command, and one pixel line of the image. Increase the
size of the draw buffer or decrease the width of the image.

Examples:
The following example:
PhImage t *pimage;

InitPalImage() {
if (pimage != NULL) return;
if ((pimage = PxLoadImage( "mackface.bmp", NULL )) == NULL) {
perror( "Unable to load image" );
return;
}
}

DrawPalImage() {
PhPoint t p = { 0, 0 };

InitPalImage();
if (pimage == NULL) return;
if ((pimage->palette != NULL) && (pimage->colors > 0))
PgSetPalette( pimage->palette, 0, 0, pimage->colors,
Pg PALSET SOFT, 0 );
PgDrawImage( pimage->image, pimage->type, &p,
&pimage->size, pimage->bpl, 0 );
}

will draw:

September 20, 2005 Chapter 5 ¯ Pg — Graphics 219

PgDrawImage(), PgDrawImagemx()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDrawTImage(), PgFlush(), PgSetFillColor(), PgSetPalette(),
PgShmemCreate(), PhMakeTransBitmap(), PxCRC(), PxLoadImage()

220 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawLine(), PgDrawILine()
Draw a single line

Synopsis:
int PgDrawLine( PhPoint t const *p1,
PhPoint t const *p2 );

int PgDrawILine( int x1, int y1,

int x2, int y2 );

Description:
These functions build a command in the draw buffer to draw a line.
Note that PgDrawLine() requires two pointers to PhPoint t,
whereas PgDrawILine() takes individual arguments.

Returns:
0 Success.

-1 The draw buffer is too small to hold the current draw state and
the draw command.

Examples:
The following example:

DrawLines() {
PgSetStrokeColor( Pg RED );
PgDrawILine( 8, 8, 152, 8 );
PgSetStrokeColor( Pg GREEN );
PgDrawILine( 8, 8, 152, 60 );
PgSetStrokeColor( Pg YELLOW );
PgDrawILine( 8, 8, 152, 112 );
}

will draw:

September 20, 2005 Chapter 5 ¯ Pg — Graphics 221

PgDrawLine(), PgDrawILine()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgSetStrokeCap(), PgSetStrokeColor(), PgSetStrokeDash(),
PgSetStrokeDither(), PgSetStrokeJoin(), PgSetStrokeWidth()

222 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawPhImagemx()
Draw an image that’s contained in a PhImage t structure

Synopsis:
int PgDrawPhImagemx( PhPoint t const *pos,
PhImage t const *image,
int flags );

Description:
This function draws the provided image at position pos. The image
parameter must be a pointer to a PhImage t structure that defines the
image to be rendered. If the image has a transparency mask, it’s used.
The currently defined valid bits for the flags parameter are:

Pg GHOST or Pt GHOST
Render the image using the ghost bitmap as a transparency
mask.

Returns:
0 Success.

-1 The draw buffer couldn’t be resized enough to fit a single scan

line of the image (insufficient memory).

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Pg — Graphics 223

PgDrawPhImagemx()  2005, QNX Software Systems

See also:
ApGetImageRes(), PhImage t, PhMakeGhostBitmap(),
PhMakeTransBitmap(), PhReleaseImage(), PxLoadImage()

224 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawPixel(), PgDrawIPixel()
Draw a point

Synopsis:
int PgDrawPixel( PhPoint t const *pt );

int PgDrawIPixel( int x,

int y );

Description:
These functions build a command in the draw buffer to draw a pixel.
For PgDrawPixel(), the pt argument points to a pixel location; for
PgDrawIPixel(), x and y specify the location.

Returns:
0 Successful completion

-1 The draw buffer is too small to hold the current draw state, the
draw command, and the data. Increase the size of the draw
buffer.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDrawPixelArray(), PgDrawPixelArraymx(), PgFlush(),
PgSetStrokeColor(), PgSetStrokeDither()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 225

PgDrawPixelArray(), PgDrawPixelArraymx()  2005, QNX
Software Systems
Draw multiple points

Synopsis:
int PgDrawPixelArray( PhPoint t const *ptr,
int num,
PhPoint t const *pos );

int PgDrawPixelArraymx( PhPoint t const *ptr,

int num,
PhPoint t const *pos );

Description:
These functions build a command in the draw buffer to draw an array
of pixels. The ptr argument points to an array of pixel locations; num
indicates how many points to draw; and the value of pos is added to
every pixel location.

☞ If you call the “mx” form of this function, the data isn’t physically
copied into the draw buffer. Instead, a pointer to the array is stored
until the draw buffer is flushed. Make sure you call PgFlush() before
you modify the pixel array.

Returns:
0 Success.

-1 The draw buffer is too small to hold the current draw state, the
draw command, and the data. Increase the size of the draw
buffer or decrease the number of points.

Classification:
Photon

Safety
Interrupt handler No
continued. . .

226 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawPixelArray(),
PgDrawPixelArraymx()

Safety
Signal handler No
Thread No

See also:
PgDrawPixel(), PgDrawIPixel(), PgFlush(), PgSetStrokeColor(),
PgSetStrokeDither()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 227

PgDrawPolygon(), PgDrawPolygonmx()  2005, QNX Software
Systems
Draw a stroked and/or filled polygon
Synopsis:
int PgDrawPolygon( PhPoint t const *ptr,
int num,
PhPoint t const *pos,
int flags );

int PgDrawPolygonmx( PhPoint t const *ptr,

int num,
PhPoint t const *pos,
int flags );

Description:
These functions build a command in the draw buffer to draw a
polygon from an array of points, pointed to by ptr, with num entries.

☞ The array of points must fit in the draw buffer, even if you use
PgDrawPolygonmx().

The flags argument must be one of the following:

Pg DRAW STROKE
Draw a stroked polygon.

Pg DRAW FILL
Draw a filled polygon.

Pg DRAW FILL STROKE

Draw a filled polygon, then stroke it.

You can OR flags with any combination of the following:

Pg CLOSED Connect the last point to the first.

Pg RELATIVE Use relative coordinates to draw the polygon. Each

point is relative to the previous point.

228 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawPolygon(),
PgDrawPolygonmx()
For absolute coordinates, pos is added to each point pointed to by ptr.
For relative coordinates, the first coordinate is the sum of pos and the
first point of the array; any subsequent coordinate is the sum of the
previous point and the next point of the array.

☞ If you call the “mx” form of this function, the data isn’t physically
copied into the draw buffer. Instead, a pointer to the array is stored
until the draw buffer is flushed. Make sure you call PgFlush() before
you modify the point array.

Returns:
0 Successful completion

-1 The draw buffer is too small to hold the current draw state, the
draw command, and the data. Increase the size of the draw
buffer or decrease the number of points.

Examples:
The following example:

DrawFillStrokePoly() {
PhPoint t o = { 0, 0 };
PhPoint t p[] = { 80, 8, 120, 120, 16, 32,
136, 32, 40, 120 };

PgSetStrokeColor( Pg WHITE );
PgSetFillColor( Pg PURPLE );
PgDrawPolygon( &p, 5, &o, Pg DRAW FILL STROKE |
Pg CLOSED );
}

will draw:

September 20, 2005 Chapter 5 ¯ Pg — Graphics 229

PgDrawPolygon(), PgDrawPolygonmx()  2005, QNX Software

Systems

The following example:

DrawRelPoly() {
PhPoint t o = { 0, 0 };
PhPoint t p[] = { 80, 8, 40, 112, -104, -88,
120, 0, -96, 88 };

PgSetStrokeColor( Pg WHITE );
PgSetFillColor( Pg PURPLE );
PgDrawPolygon( &p, 5, &o, Pg DRAW FILL STROKE |
Pg CLOSED |
Pg RELATIVE );
}

will draw:

The following example:

DrawUnclosedPoly() {
PhPoint t o = { 0, 0 };
PhPoint t p[] = { 80, 8, 120, 120, 16, 32,
136, 32, 40, 120 };

PgSetStrokeColor( Pg WHITE );
PgSetFillColor( Pg PURPLE );
PgDrawPolygon( &p, 5, &o, Pg DRAW FILL STROKE );
}

230 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawPolygon(),
PgDrawPolygonmx()

will draw:

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgFlush()
To draw stroked polygons, see also:
PgSetStrokeColor(), PgSetStrokeCap(), PgSetStrokeDash(),
PgSetStrokeDither(), PgSetStrokeJoin(), PgSetStrokeWidth()
To draw filled polygons, see also:
PgSetFillColor(), PgSetFillDither(), PgSetFillTransPat()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 231

PgDrawRect(), PgDrawIRect()  2005, QNX Software Systems
Draw a rectangle

Synopsis:
int PgDrawRect( PhRect t const *rect,
unsigned int flags );

int PgDrawIRect( int ulx, int uly,

int lrx, int lry,
unsigned int flags );

Description:
These functions build a command in the draw buffer to draw a
rectangle. Note that PgDrawRect() requires a pointer to a PhRect t
structure whereas PgDrawIRect() takes individual arguments.
The flags argument must be one of the following:

Pg DRAW STROKE
Draw as a line.
Pg DRAW FILL
Fill the rectangle.
Pg DRAW FILL STROKE
Fill the rectangle, then stroke it.

For PgDrawIRect(), ulx and uly are the coordinates of the upper-left
corner, and lrx and lry are those for the lower-right.

Returns:
0 Success.

-1 The draw buffer is too small to hold the current draw state and
the draw command.

232 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawRect(), PgDrawIRect()

Examples:
The following example:
DrawFillRect() {
PgSetFillColor( Pg PURPLE );
PgDrawIRect( 8, 8, 152, 112, Pg DRAW FILL );
}

will draw:

The following example:

DrawStrokeRect() {
PgSetStrokeColor( Pg WHITE );
PgDrawIRect( 8, 8, 152, 112, Pg DRAW STROKE );
}

will draw:

The following example:

DrawFillStrokeRect() {
PgSetFillColor( Pg PURPLE );
PgSetStrokeColor( Pg WHITE );
PgDrawIRect( 8, 8, 152, 112, Pg DRAW FILL STROKE );
}

September 20, 2005 Chapter 5 ¯ Pg — Graphics 233

PgDrawRect(), PgDrawIRect()  2005, QNX Software Systems

will draw:

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDrawBeveled(), PgDrawRoundRect(), PgSetFillColor(),
PgSetFillDither(), PgSetFillTransPat()

234 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawRepBitmap(),
PgDrawRepBitmapmx()
Draw a bitmap several times
Synopsis:
int PgDrawRepBitmap( void const *ptr,
int flags,
PhPoint t const *pos,
PhPoint t const *size,
int bpl,
PhPoint t const *rep,
PhPoint t const *space,
long tag );

int PgDrawRepBitmapmx( void const *ptr,

int flags,
PhPoint t const *pos,
PhPoint t const *size,
int bpl,
PhPoint t const *rep,
PhPoint t const *space,
long tag );

Description:
These functions build a command in the draw buffer to repeatedly
draw the bitmap pointed to by ptr. For an explanation of bitmaps, see
PgDrawBitmap().
These functions:

¯ Draw the first bitmap at pos and the next bitmap space.x pixels to
the right.
¯ Draw the bitmap rep.x times in the x direction and rep.y times in
the y direction.
¯ Draw each row of bitmaps space.y pixels below the previous row.

If you OR flags with Pg REPBM ALTERNATE, all the bitmaps are

drawn twice; the second time the position is offset by half of space.x
and space.y.
The bpl argument indicates the number of bytes per line of image data
(that is, the offset from one line of data to the next). To calculate the

September 20, 2005 Chapter 5 ¯ Pg — Graphics 235

PgDrawRepBitmap(), PgDrawRepBitmapmx()  2005,

QNX Software Systems

size of the data transferred to the graphics driver, multiply bpl by

size.y. You can determine the size and bpl arguments with the value
returned by PxLoadImage().
The data pointed to by ptr is one bit per pixel. If the pixel value is 1,
the pixel is drawn with the color set by PgSetTextColor() or
PgSetTextDither(). If the pixel value is 0, the pixel is drawn as
transparent unless you’ve set flags to Pg BACK FILL. With
Pg BACK FILL, the pixel is drawn with the color set by
PgSetFillColor() or PgSetFillDither(). The pixels are drawn most
significant bit first.
The tag argument is used for data caching by programs such as
phrelay. To calculate the tag, use PxCRC(). This argument is
ignored if you set it to 0.

☞ If you call the “mx” form of this function, the data isn’t physically
copied into the draw buffer. Instead, a pointer to the bitmap is stored
until the draw buffer is flushed. Make sure you call PgFlush() before
you modify the bitmap.
If the data is in shared memory, the mx form of this function
automatically passes a shared memory reference instead of the
bitmap.

Returns:
0 Success.

-1 The draw buffer is too small to hold the current draw state, the
draw command, and one pixel line of the image. Increase the
size of the draw buffer, or decrease the width of the image.

Examples:
The following example:

DrawRepBitmap() {
PhPoint t p = { -32, -32 };
PhPoint t rep = { 5, 3 };

236 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawRepBitmap(),
PgDrawRepBitmapmx()

PgSetTextColor( Pg WHITE );
PgDrawRepBitmap( TestBitmap, 0, &p,
&TestBitmapSize, TestBitmapBPL,
&rep, &TestBitmapSize, 0 );
}

draws:

The following example:

DrawAltRepBitmap() {
PhPoint t p = { 0, 0 };
PhPoint t rep = { 3, 2 };
PhPoint t space;

space.x = TestBitmapSize.x * 2;
space.y = TestBitmapSize.y * 2;

PgSetTextColor( Pg WHITE );
PgDrawRepBitmap( TestBitmap, Pg REPBM ALTERNATE, &p,
&TestBitmapSize, TestBitmapBPL,
&rep, &space, 0 );
}

draws:

September 20, 2005 Chapter 5 ¯ Pg — Graphics 237

PgDrawRepBitmap(), PgDrawRepBitmapmx()  2005,

QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDrawBitmap(), PgDrawRepImage(), PgDrawRepImagemx(),
PgFlush(), PgSetFillColor(), PgSetFillDither(), PgSetTextColor(),
PgSetTextDither(), PxCRC(), PxLoadImage()

238 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawRepImage(),
PgDrawRepImagemx()
Draw an image several times
Synopsis:
int PgDrawRepImage( void const *ptr,
int flag,
PhPoint t const *pos,
PhPoint t const *area,
int bpl,
PhPoint t const *rep,
PhPoint t const *space,
long tag );

int PgDrawRepImagemx( void const *ptr,

int flag,
PhPoint t const *pos,
PhPoint t const *area,
int bpl,
PhPoint t const *rep,
PhPoint t const *space,
long tag );

Description:
The PgDrawRepImage() and PgDrawRepImagemx() functions build a
command in the draw buffer to repeatedly draw the image pointed to
by ptr. These functions:

¯ Draw the first image at pos and the next image space.x pixels to
the right.

¯ Draw the image rep.x times in the x direction and rep.y times in
the y direction.

¯ Draw each row of images space.y pixels below the previous row.

If you OR flags with Pg REPBM ALTERNATE, all the images are

drawn twice; the second time the position is offset by half of space.x
and space.y.
The image formats are as described for PhImage t. Specify the
image format by ORing it into the flags argument.

September 20, 2005 Chapter 5 ¯ Pg — Graphics 239

PgDrawRepImage(), PgDrawRepImagemx()  2005, QNX

Software Systems

The bpl argument indicates the number of bytes per line of image data
(that is, the offset from one line of data to the next). To calculate the
size of the data transferred to the graphics driver, multiply bpl by
size.y. You can determine the size and bpl arguments with the value
returned by PxLoadImage().
The tag argument is used for data caching by programs such as
phrelay. To calculate the tag, use PxCRC(). This argument is
ignored if you set it to 0.

☞ If you call the “mx” form of this function, the data isn’t physically
copied into the draw buffer. Instead, a pointer to the image is stored
until the draw buffer is flushed. Make sure you call PgFlush() before
you modify the image.
If the data is in shared memory, the mx form of this function
automatically passes a shared memory reference instead of the image.

Returns:
0 Success.

-1 The draw buffer is too small to hold the current draw state, the
draw command, and one pixel line of the image. Increase the
size of the draw buffer, or decrease the width of the image.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

240 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawRepImage(),
PgDrawRepImagemx()
See also:
PgDrawImage(), PgDrawRepBitmap(), PgDrawRepBitmapmx(),
PgFlush(), PhImage t, PxCRC(), PxLoadImage()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 241

PgDrawRoundRect()  2005, QNX Software Systems
Draw a rounded rectangle

Synopsis:
int PgDrawRoundRect( PhRect t const *rect,
PhPoint t const *radii,
unsigned flags );

Description:
This function builds a command in the draw buffer to draw a rounded
rectangle. The rect argument defines the extent of the rectangle and
radii defines the roundness of the corners, in pixels.
The flags argument must be one of the following:

¯ Pg DRAW STROKE — draw as an outline.

¯ Pg DRAW FILL — fill the rectangle.

¯ Pg DRAW FILL STROKE — fill the rectangle, then stroke it.

Since the value of radii is truncated to the size of the rectangle, you
should find this function useful for drawing ellipses within a
rectangular area (see example below).

Returns:
0 Success.

-1 The draw buffer is too small to hold the current draw state and
the draw command.

Examples:
The following example:

DrawStrokeRRect() {
PhRect t rect = { 8, 8, 152, 112 };
PhPoint t radii = { 32, 32 };

PgSetStrokeColor( Pg WHITE );
PgDrawRoundRect( &rect, &radii, Pg DRAW STROKE );
}

242 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawRoundRect()

will draw:

The following example:

DrawFillRRect() {
PhRect t rect = { 8, 8, 152, 112 };
PhPoint t radii = { 32, 32 };

PgSetFillColor( Pg PURPLE );
PgDrawRoundRect( &rect, &radii, Pg DRAW FILL );
}

will draw:

The following example:

DrawFillStrokeRRect() {
PhRect t rect = { 8, 8, 152, 112 };
PhPoint t radii = { 1000, 1000 };

PgSetFillColor( Pg PURPLE );
PgSetStrokeColor( Pg WHITE );
PgDrawRoundRect( &rect, &radii, Pg DRAW FILL STROKE );
}

will draw:

September 20, 2005 Chapter 5 ¯ Pg — Graphics 243

PgDrawRoundRect()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDrawBeveled(), PgDrawIRect(), PgDrawRect(), PgSetFillColor(),
PgSetFillDither(), PgSetFillTransPat()

244 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawSpan(), PgDrawSpanmx()
Draw a list of spans

Synopsis:
int PgDrawSpan( PgSpan t const *ptr,
int num,
PhPoint t const *pos,
int flags );

int PgDrawSpanmx( PgSpan t const *ptr,

int num,
PhPoint t const *pos,
int flags );

Description:
These low-level draw primitives let you render complex shapes not
supported by the Photon graphics drivers.
The functions draw a list of spans. The spans are defined as a list of
PgSpan t records. Here are the members of PgSpan t:

short x1 starting x position

short x2 last x position

short y y position

The number of spans is defined by the num parameter. The location of

the spans is offset by the pos parameter.
You can set flags to one of the following:

¯ Pg DRAW FILL — draw with fill parameters.

¯ Pg DRAW STROKE — draw with stroke parameters.

¯ Pg DRAW TEXT — draw with text parameters.

September 20, 2005 Chapter 5 ¯ Pg — Graphics 245

PgDrawSpan(), PgDrawSpanmx()  2005, QNX Software Systems

☞ If you call the “mx” form of this function, the data isn’t physically
copied into the draw buffer. Instead, a pointer to the list of spans is
stored until the draw buffer is flushed. Make sure you call PgFlush()
before you modify the list.

Returns:
0 Success.

-1 The draw buffer is too small to hold the current draw state, the
draw command and the data. Increase the size of the draw
buffer, or decrease the number of points.

Examples:
The following example:

void DrawSpan() {
PgSpan t spans[152];
PgSpan t *sp = spans;
PhPoint t p = { 12, 10 };
int i, v, n=0;

for (i=0; i<=100; i++) {

sp->x1 = (i*i)>>6;
v = 100 - i;
sp->x2 = 160 - ((v*v)>>6);
sp->y = i;
sp++; n++;
}
for (i=0; i<=50; i++) {
sp->x1 = 100 - ((i*i)>>6);
v = 50 - i;
sp->x2 = 60 + ((v*v)>>6);
sp->y = i+25;
sp++; n++;
}
PgSetFillColor( Pg WHITE );
PgDrawSpan( spans, n, &p, Pg DRAW FILL );
}

will draw:

246 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawSpan(), PgDrawSpanmx()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDrawPolygon(), PgSetFillColor(), PgSetStrokeColor(),
PgSetTextColor(), PgFlush()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 247

PgDrawString(), PgDrawStringmx()  2005, QNX Software Systems
Draw a string of characters

Synopsis:
int PgDrawString( char const *ptr,
PhPoint t const *pos );

int PgDrawStringmx( char const *ptr,

PhPoint t const *pos );

Description:
These convenience functions for PgDrawText() and PgDrawTextmx()
calculate the length of the string internally using strlen(). They then
pass the string, along with its length, its position, and a flags setting of
0, to the corresponding text function.

☞ If you call the “mx” form of this function, the data isn’t physically
copied into the draw buffer. Instead, a pointer to the string is stored
until the draw buffer is flushed. Make sure you call PgFlush() before
you modify the text.

Returns:
0 Success.

-1 The draw buffer is too small to hold the current draw state, the
draw command, and the data. Increase the size of the draw
buffer, or decrease the size of the string.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

248 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawString(), PgDrawStringmx()

See also:
PgDrawText(), PgDrawTextArea(), PgFlush(), PgSetTextColor(),
PgSetTextDither(), PgSetTextTransPat(), PgSetTextXORColor(),
PgSetUnderline(), PhPoint t
strlen() (in the C Library Reference)

September 20, 2005 Chapter 5 ¯ Pg — Graphics 249

PgDrawText(), PgDrawTextmx(),
PgDrawTextChars()  2005, QNX Software Systems
Draw text
Synopsis:
int PgDrawText( char const *ptr,
int len,
PhPoint t const *pos,
int flags );

int PgDrawTextmx( char const *ptr,

int len,
PhPoint t const *pos,
int flags );

int PgDrawTextChars( char const *ptr,

int len,
PhPoint t const *pos,
int flags );

Description:
Each of these functions builds a command in the draw buffer to draw
the text indicated by ptr at location pos.
The len parameter specifies the number of bytes required to store the
string. For pure ASCII strings (characters 0 to 127), this is the number
of characters. For multibyte strings, len may be larger than the
number of characters. For double-byte strings, len is twice the
number of characters.
By default, the function assumes that all strings consist of multibyte
characters that conform to the ISO/IEC 10646-1 UTF-1 multibyte
format. However, if Pg TEXT WIDECHAR is set, the function
assumes each character is represented by 2 bytes that conform to the
ISO/IEC 10646-1 UCS-2 double-byte format.

☞ PgDrawTextChars() assumes that len is the number of characters to

draw. Using this number, PgDrawTextChars() determines the number
of bytes required to store the string.

250 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawText(), PgDrawTextmx(),
PgDrawTextChars()

In order to: You can:

Define the color of the text Use PgSetTextColor() or
PgSetTextDither()
Mask the text Use PgSetTextTransPat()
Fill the extent of the text Set the background color with
PgSetFillColor() or PgSetFillDither()
and specify the Pg BACK FILL flag to
PgDrawText() or PgDrawTextmx()
Underline the text Use PgSetUnderline()

By default, the text is left-aligned (Pg TEXT LEFT), and the text is
drawn with pos->y as its baseline. You can set flags to a combination
of:

Pg BACK FILL Fill the text extent with fill-color parameters.

Pg TEXT WIDECHAR
The text is specified as wide characters. Each
character is represented by 16 bits.

Pg TEXT LEFT Left align text to pos (text is drawn to the right).

Pg TEXT RIGHT Right align text to pos (text is drawn to the left).

Pg TEXT CENTER
Center text horizontally on pos.

Pg TEXT TOP Top align text to pos (text is drawn below).

Pg TEXT BOTTOM
Bottom align text to pos (text is drawn above).

Pg TEXT MIDDLE
Center text vertically on pos.

September 20, 2005 Chapter 5 ¯ Pg — Graphics 251

PgDrawText(), PgDrawTextmx(),
PgDrawTextChars()  2005, QNX Software Systems

☞ If you call the “mx” forms of these functions, the data isn’t physically
copied into the draw buffer. Instead, a pointer to the string is stored
until the draw buffer is flushed. Make sure you call PgFlush() before
you modify the text.

Returns:
0 Success.
-1 The draw buffer is too small to hold the current draw state, the
draw command and the data. Increase the size of the draw
buffer, or decrease the size of the string.

Examples:
The following example:
DrawSimpleText() {
char *s = "Hello World!";
PhPoint t p = { 8, 30 };

PgSetFont( "helv18" );
PgSetTextColor( Pg WHITE );
PgDrawText( s, strlen( s ), &p, 0 );
}

will draw:

Hello W orld!

The following example:

DrawBackFillText() {
char *s = "Hello World!";
PhPoint t p = { 8, 30 };

PgSetFont( "helv18" );
PgSetTextColor( Pg WHITE );
PgSetFillColor( Pg PURPLE );
PgDrawText( s, strlen( s ), &p, Pg BACK FILL );
}

252 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawText(), PgDrawTextmx(),
PgDrawTextChars()

will draw:

Hello W orld!

The following example:

DrawUnderlineText() {
char *s = "Hello World!";
PhPoint t p = { 8, 30 };

PgSetFont( "helv18" );
PgSetTextColor( Pg WHITE );
PgSetUnderline( Pg RED, Pg TRANSPARENT, 0 );
PgDrawText( s, strlen( s ), &p, 0 );
PgSetUnderline( Pg TRANSPARENT, Pg TRANSPARENT, 0 );
}

will draw:

Hello W orld!

The following example:

DrawBackFillUnderlineText() {
char *s = "Hello World!";
PhPoint t p = { 8, 30 };

PgSetFont( "helv18" );
PgSetTextColor( Pg WHITE );
PgSetFillColor( Pg PURPLE );
PgSetUnderline( Pg RED, Pg TRANSPARENT, 0 );
PgDrawText( s, strlen( s ), &p, Pg BACK FILL );
PgSetUnderline( Pg TRANSPARENT, Pg TRANSPARENT, 0 );
}

will draw:

Hello W orld!

September 20, 2005 Chapter 5 ¯ Pg — Graphics 253

PgDrawText(), PgDrawTextmx(),
PgDrawTextChars()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDrawString(), PgFlush(), PgSetFillColor(), PgSetFillDither(),
PgSetFillTransPat(), PgSetFont(), PgSetTextColor(),
PgSetTextDither(), PgSetTextTransPat(), PgSetTextXORColor(),
PgSetUnderline(), PhPoint t

254 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawTextArea()
Draw text within an area

Synopsis:
int PgDrawTextArea( char const *ptr,
int len,
PhRect t const *rect,
int flags );

Description:
This function draws text within an area. This area is clipped to the
dimensions of the rectangle specified by rect.
By default, the text is left-aligned (Pg TEXT LEFT), and the text is
drawn with its baseline centered inside the drawing area.
The flags can be a combination of:

Pg BACK FILL Fill the text extent with fill-color parameters.

Pg TEXT WIDECHAR
The text is specified as wide characters. Each
character is represented by 16 bits.

Pg TEXT LEFT Align text to left edge of rect (rect->ul.l).

Pg TEXT RIGHT Align text to right edge of rect (rect->lr.r).

Pg TEXT CENTER
Center text horizontally within rect.

Pg TEXT TOP Align text to top edge of rect (rect->ul.y).

Pg TEXT BOTTOM
Align text to bottom edge of rect (rect->lr.y).

Pg TEXT MIDDLE
Center text vertically within rect.

September 20, 2005 Chapter 5 ¯ Pg — Graphics 255

PgDrawTextArea()  2005, QNX Software Systems

Returns:
0 Success.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

Caveats:
PgDrawTextArea() doesn’t work in any context that involves the
render library, such as printing or Phindows. If your application needs
to use the render library, you should:

1 Calculate the position at which to print the text, based on the

extent of the text and the desired alignment inside the drawing
area.

2 Set a clipping rectangle with PgSetUserClip() or

PgSetUserClipAbsolute().

3 Call PgDrawText() to display the text.

See also:
PgDrawString(), PgDrawText(), PgFlush(), PgSetFillColor(),
PgSetFillDither(), PgSetFillTransPat(), PgSetFont(),
PgSetTextColor(), PgSetTextDither(), PgSetTextTransPat(),
PgSetTextXORColor(), PgSetUnderline(), PgSetUserClip(),
PgSetUserClipAbsolute(), PhRect t

256 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawTImage(),
PgDrawTImagemx()
Draw an image with a transparency mask
Synopsis:
int PgDrawTImage( void const *ptr,
int type,
PhPoint t const *pos,
PhDim t const *size,
int bpl,
long tag,
void const *TransPtr,
int TransBPL );

int PgDrawTImagemx( void const *ptr,

int type,
PhPoint t const *pos,
PhDim t const *size,
int bpl,
long tag,
void const *TransPtr,
int TransBPL );

Description:
These functions build a command in the draw buffer to draw an image
with a transparency mask. These functions take the same parameters
as PgDrawImage() and PgDrawImagemx() with two additions,
TransPtr and TransBPL.

☞ Instead of using this function, we recommend using a PhImage t

structure and calling PgDrawPhImagemx(). To make one of the
colors in the image transparent, call PhMakeTransBitmap().

The TransPtr argument points to a bitmap that’s TransBPL bytes

wide. This defines a bitmap that only allows the image to draw where
there’s a value of 1 in the bitmap. Any value of 0 in the bitmap
prevents the image from drawing. The leftmost pixel corresponds to
the top bit of the first byte in the mask.

September 20, 2005 Chapter 5 ¯ Pg — Graphics 257

PgDrawTImage(), PgDrawTImagemx()  2005, QNX Software

Systems

Returns:
0 Successful completion

-1 The draw buffer is too small to hold the current draw state, the
draw command, and one pixel line of the image. Increase the
size of the draw buffer or decrease the width of the image.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDrawImage(), PhImage t, PhMakeTransBitmap()

258 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawTrend(), PgDrawTrendmx()
Draw a trend graph

Synopsis:
int PgDrawTrend( short const *ptr,
PhPoint t const *pos,
int num,
int delta,
int buflen,
int bufoff ,
unsigned flags );

int PgDrawTrendmx( short const *ptr,

PhPoint t const *pos,
int num,
int delta,
int buflen,
int bufoff ,
unsigned flags );

Description:
These functions build a command in the draw buffer to draw a trend
graph.
The ptr argument points to an array of short values. Each of these
values is used as either the x or the y coordinate; the other coordinate
is calculated by adding delta to the previous value.
For example, if flags is Pg TREND VERT, the coordinates would be
calculated as follows:

pos.x + *(ptr+0), pos.y + (delta * 0)

pos.x + *(ptr+1), pos.y + (delta * 1)
pos.x + *(ptr+2), pos.y + (delta * 2)
...
pos.x + *(ptr+num-1), pos.y + (delta * (num-1))

The pos argument defines the origin of the trend graph and the num
argument controls the number of values to be drawn.
The flags argument controls how the trend will be drawn. It must be
one of the following:

September 20, 2005 Chapter 5 ¯ Pg — Graphics 259

PgDrawTrend(), PgDrawTrendmx()  2005, QNX Software Systems

Pg TREND HORIZ
Draw a horizontal graph. The ptr values become the y axis and
the delta values are added to the x coordinate.
Pg TREND VERT
Draw a vertical graph. The ptr values become the x axis and the
delta values are added to the y coordinate.

The buflen and bufoff arguments aren’t currently used, and must be
set to 0 for future compatibility.

☞ If you call the “mx” form of this function, the data isn’t physically
copied into the draw buffer. Instead, a pointer to the array is stored
until the draw buffer is flushed. Make sure you call PgFlush() before
you modify the array.
If the data is in shared memory, the mx form of this function will
automatically pass a shared memory reference instead of the array.

Returns:
0 Success.
-1 The draw buffer is too small to hold the current draw state, the
draw command and the data. Increase the size of the draw
buffer, or decrease the number of points.

Examples:
The following example:
void HTrend() {
short data[512];
PhPoint t p = { 0, 80 };
int i;

for (i=0; i<512; i++) data[i] = (i & 127) - 64;

PgSetStrokeColor( Pg WHITE );
PgDrawTrend( &data, &p, 256, 2, 0, 0,
Pg TREND HORIZ );

260 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgDrawTrend(), PgDrawTrendmx()

will draw:

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDrawPolygon(), PgSetStrokeColor(), PgSetStrokeWidth(),
PgFlush()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 261

PgExtentText()  2005, QNX Software Systems
Calculate the extent of a string of text

Synopsis:
PhRect t *PgExtentText( PhRect t *extent,
PhPoint t const *pos,
char const *font,
char const *str,
unsigned n );

Description:
This function determines the extent that would be occupied if str were
rendered at pos, using font. The extent information is returned in both
extent and in the return value for the function. If you pass extent as
NULL, the function returns NULL.
The function calculates the extent of the first n characters of the
string. To have the function calculate the extent of the entire string,
set n to zero. If you pass pos as NULL, it’s assumed to be (0,0).

Returns:
A pointer to a PhRect t structure, or NULL if an error occurred.

Examples:
The following fragment determines the extent of a string drawn with
the helv18BI font:

PhRect t extent;

if( PgExtentText( &extent, NULL, "helv18BI",

"Hello World!", 0 ) ) {
printf( "Ascent: %d Descent: %d Width: %d\n",
-extent.ul.y, extent.lr.y,
extent.lr.x - extent.ul.x + 1 );
} else
printf( "Error.\n" );

262 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgExtentText()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDrawText(), PgSetFont()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 263

PgFlush(), PgFFlush()  2005, QNX Software Systems
Explicitly flush the current draw buffer

Synopsis:
int PgFlush( void );

int PgFFlush( unsigned int flags );

Description:
These functions flush the current draw buffer and then clear it. Most
applications call PgFlush(); you need to call PgFFlush() only if you
need to specify the type of draw event.
Normally, you set flags to Ph NORMAL DRAW; this is the same as
calling PgFlush(). But if your application has received an expose
event with a subtype of Ph CAPTURE EXPOSE, you should
encapsulate your drawing events by calling
PgFFlush( Ph START DRAW );

before drawing anything, and

PgFFlush( Ph DONE DRAW );

after the entire exposed region has been redrawn. If you’re using
widgets, PtEventHandler() makes both these calls automatically.
Any function that builds a command in the draw buffer calls
PgFlush() automatically when the draw buffer becomes full.

Returns:
0 Successful completion.

-1 An error occurred.

Examples:
/*
* Place a group of 3 lines in the draw buffer
*/
PgDrawILine( 100, 100, 200, 300 );
PgDrawILine( 200, 300, 700, 700 );

264 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgFlush(), PgFFlush()

PgDrawILine( 700, 700, 0, 0 );

/*
* Emit a draw event that contains those 3 lines
*/
PgFlush();

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgClearDrawBuffer(), PgSetDrawBufferSize(), PhEvent t

September 20, 2005 Chapter 5 ¯ Pg — Graphics 265

PgGetGC()  2005, QNX Software Systems
Get current graphics context

Synopsis:
PhGC t *PgGetGC( void );

Description:
This function gets the current graphics context.

Returns:
A pointer to the current graphics context.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgCreateGC(), PgDestroyGC(), PgSetGC()

266 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgGetPalette()
Query for current color palette

Synopsis:
int PgGetPalette(PgColor t *palette);

Description:
This function queries the graphics driver for the current palette. A
palette is an array of Pg MAX PALETTE (256) RGB colors. The
palette parameter must be a pointer to a suitably-sized array, which
will be filled with the color values representing the current palette.
This function is useful for graphical image utilities such as pv, which
can perform improved dithering with knowledge of the graphics
palette.

Returns:
0 Successful completion.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Pg — Graphics 267

PgGray()  2005, QNX Software Systems
Generate the RGB value for a shade of gray

Synopsis:
PgColor t PgGray( int level );

Description:
This macro converts a gray value into a PgColor t structure.
The level argument ranges from 0 (black) to 255 (white). Intermediate
values produce various shades of gray. For a complete description of
composite color values, see PgSetFillColor().

Returns:
A composite color value.

Examples:

Color Gray value

Black PgGray( 0 );
White PgGray( 255 );
Medium Gray PgGray( 160 );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

268 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgGray()

See also:
PgBlueValue(), PgCMY(), PgGreenValue(), PgHSV(), PgRedValue(),
PgRGB(), PgSetFillColor(), PgSetFillDither()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 269

PgGrayValue()  2005, QNX Software Systems
Extract color brightness

Synopsis:
int PgGrayValue( PgColor t color );

Description:
This macro converts a color into its corresponding level of gray. The
calculation is based on 30% red, 59% green, and 11% blue, resulting
in a value between 0 and 255.

Returns:
The gray component of the color.

Examples:
// Convert pal[i] into monochrome
pal[i] = PgGray( PgGrayValue( pal[i] ) );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgBlueValue(), PgCMY(), PgGreenValue(), PgHSV(), PgRedValue(),
PgRGB(), PgSetFillColor(), PgSetFillDither()

270 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgGreenValue()
Extract the green component from a color value

Synopsis:
int PgGreenValue( PgColor t color );

Description:
This macro extracts the green color component from a composite
color value (a PgColor t type). The result is between 0 and 255.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

Caveats:
PgGreenValue() is a macro.

See also:
PgBlueValue(), PgCMY(), PgHSV(), PgRedValue() PgRGB(),
PgSetFillColor(), PgSetFillDither()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 271

PgHSV()  2005, QNX Software Systems
Convert hue, saturation, and value to composite color format

Synopsis:
PgColor t PgHSV( unsigned H, int S, int V );

Description:
This function converts hue, saturation, and value into a PgColor t
structure.
A color circle is divided into 65536 gradations (called binary
gradations or bi-grads). Hue is in bi-grads, starting with red at 0 (0
degrees), green at 0x5555 (120 degrees), and blue at 0xAAAA (240
degrees):

Hue Color
0x0000 Red
0x2AAA Yellow
0x5555 Green
0x8000 Cyan
0xAAAA Blue
0xD555 Magenta
0xFFFF Almost red

The values for saturation and value range from 0 to 255:

Saturation Effect
0 Gray
128 Muted
255 Pure color

272 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgHSV()

Value Effect
0 Black
128 Dark
255 Full brightness

Returns:
A composite color value.

Examples:

Color HSV value

Black PgHSV( 0, 0, 0 );
White PgHSV( 0, 0, 255 );
Red PgHSV( 0, 255, 255 );
Green PgHSV( 0x5555, 255, 255 );
Blue PgHSV( 0xAAAA, 255, 255 );
Orange PgHSV( 0x1400, 255, 255 );
Slate Blue PgHSV( 0xA000, 121, 134 );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Pg — Graphics 273

PgHSV()  2005, QNX Software Systems

See also:
PgBlueValue(), PgCMY(), PgGreenValue(), PgHSV2RGB(),
PgRedValue(), PgRGB(), PgRGB2HSV(), PgSetFillColor(),
PgSetFillDither()

274 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgHSV2RGB()
Convert HSV colors to RGB

Synopsis:
PgColor t PgHSV2RGB( PgColorHSV t hsv color );

Description:
This function converts hue-saturation-value colors to composite color
values.
If you write a color selection function that allows the user to change
RGB and HSV values, you should maintain the RGB and HSV values
separately. If the user changes the HSV value, you would use
PgHSV2RGB() to calculate the new RGB value. For example:

RGBvalue = PgHSV2RGB( HSVvalue );

Returns:
A composite color value.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgColor t, PgColorHSV t, PgHSV(), PgRGB2HSV(),
PgSetFillColor()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 275

PgRedValue()  2005, QNX Software Systems
Extract the red component from a color value

Synopsis:
int PgRedValue( PgColor t color );

Description:
This macro extracts the red color component from a composite color
value (a PgColor t type). The result is between 0 and 255.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

Caveats:
PgRedValue() is a macro.

See also:
PgBlueValue(), PgCMY(), PgGreenValue(), PgHSV(), PgRGB(),
PgSetFillColor(), PgSetFillDither()

276 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgRGB()
Convert red, green, and blue values to composite color format

Synopsis:
PgColor t PgRGB( int R, int G, int B );

Description:
This macro converts red, green, and blue values into a composite
color value (a PgColor t type). The values for red, green, and blue
range from 0 to 255. If you set all three arguments to 0, the color is
black; if you set all three to 255, the color is white.

Examples:

Color RGB value

Black PgRGB( 0, 0, 0 );
White PgRGB( 255, 255, 255 );
Red PgRGB( 255, 0, 0 );
Green PgRGB( 0, 255, 0 );
Blue PgRGB( 0, 0, 255 );
Orange PgRGB( 255, 165, 0 );
Slate Blue PgRGB( 80, 95, 134 );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Pg — Graphics 277

PgRGB()  2005, QNX Software Systems

See also:
PgBlueValue(), PgCMY(), PgGreenValue(), PgHSV(), PgRedValue(),
PgSetFillColor(), PgSetFillDither()

278 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgRGB2HSV()
Convert RGB colors to HSV

Synopsis:
PgColorHSV t PgRGB2HSV( PgColor t rgb color );

Description:
This function converts composite color values into
hue-saturation-value.
If you write a color selection function that allows the user to change
RGB and HSV values, you should maintain the RGB and HSV values
separately. So if the user changes the RGB value, you would use
PgRGB2HSV() to calculate the new HSV value. For example:

HSVvalue = PgRGB2HSV( RGBvalue );

☞ When you convert RGB values into HSV, colors close to black, white,
or gray might not convert to correct hue values.

Returns:
A hue-saturation-value value.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Pg — Graphics 279

PgRGB2HSV()  2005, QNX Software Systems

See also:
PgColor t, PgColorHSV t, PgHSV(), PgHSV2RGB(),
PgSetFillColor()

280 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetClipping()
Limit the extent of drawing

Synopsis:
void PgSetClipping( unsigned short n,
PhRect t const *rects );

Description:
This function lets you limit the extent of drawing by specifying which
rectangles to draw in. Note that you can never draw outside of the
current region.
The n argument contains the number of clip rectangles; rects contains
an array of n clip rectangles, relative to the origin of the current
region. To reset the clipping rectangle to the full size of the region,
you should pass 0 rectangles.
All subsequent draws will be clipped to the intersection of the
clipping rectangles set by PgSetClipping(), PgSetMultiClip(), and
PgSetUserClip(), and PgSetRegion().

☞ PhAttach(), PhReattach(), and PgSetRegion() reset the clipping

rectangle to the full size of the region.
Don’t call PgSetClipping() in a widget’s draw function; use
PtClipAdd() and PtClipRemove() instead. For more information, see
the Building Custom Widgets guide.

This function flushes the draw buffer.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Pg — Graphics 281

PgSetClipping()  2005, QNX Software Systems

See also:
PgFlush(), PgSetMultiClip(), PgSetRegion(), PgSetUserClip(),
PhAttach(), PhReattach()
PtClipAdd(), PtClipRemove() in the Building Custom Widgets guide.

282 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetDrawBufferSize()
Resize a draw buffer

Synopsis:
int PgSetDrawBufferSize(
unsigned short cmd buf len );

Description:
This function resizes the current draw buffer. The default size,
allocated with every PhAttach(), is at least 1K. The draw buffer stores
all drawing data except for data stored in shared memory.
If the draw buffer contains unflushed data when this function is called,
the function will flush the data before reallocating the buffer.

Returns:
0 Success.

-1 An error occurred.

Examples:
// Allocate a 16K draw buffer
PgSetDrawBufferSize( 16 * 1024 );

☞ To reduce the memory requirements of the graphics driver, you should

limit draw buffers to 16K.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Pg — Graphics 283

PgSetDrawBufferSize()  2005, QNX Software Systems

See also:
PgClearDrawBuffer(), PgFlush(), PhAttach(), PhGetMsgSize()

284 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetDrawMode()
Set draw mode

Synopsis:
int PgSetDrawMode( int mode );

Description:
This function controls how pixels are combined with video memory.
You can set mode to one of the following:

mode value Description

Pg DRAWMODE OPAQUE Use default draw mode (the draw
overwrites the screen).
Pg DRAWMODE XOR XOR drawn pixels with the screen.
Pg DRAWMODE AND AND drawn pixels with the screen.
Pg DRAWMODE OR OR drawn pixels with the screen.

☞ The effect of this function depends on the physical video mode. If the
video mode is “true color,” the RGB value being drawn will modify
the RGB value of the pixel that’s in video memory. If the video mode
is palette based, the palette index of the draw color will modify the
palette index of the pixel that’s in video memory.

To facilitate XOR drawing, you can use the special draw color
Pg INVERT COLOR. This color remains highly visible regardless of
video mode (see PgSetFillColor()). If the video mode is true color,
the graphics driver will XOR the screen pixels with pure white. If the
video mode is palette based, the driver will invert the pixel index.

Returns:
The previous drawing mode.

September 20, 2005 Chapter 5 ¯ Pg — Graphics 285

PgSetDrawMode()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDefaultFill(), PgDefaultMode(), PgSetFillColor(),
PgSetFillDither(), PgSetFillTransPat(), PgSetFillXORColor(),
PgSetStrokeColor(), PgSetStrokeDither(), PgSetStrokeTransPat(),
PgSetStrokeXORColor(), PgSetTextColor(), PgSetTextDither(),
PgSetTextTransPat(), PgSetTextXORColor()

286 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetFillColor()
Set the fill color

Synopsis:
PgColor t PgSetFillColor( PgColor t color );

Description:
This function sets the fill color used for subsequent draws. If the
driver doesn’t support 24-bit color, it selects the nearest color
available to the one requested. If you OR the color with
Pg MIX COLOR, most drivers try to mix two available colors to
produce the requested color.
This function overrides the color defined by PgSetFillDither().

Returns:
The previous color.

Examples:
// Set draw color to white
PgSetFillColor( Pg WHITE );

// Set draw color to a washed-out orange color;

// dither if necessary
PgSetFillColor( PgRGB( 255, 165, 80 ) | Pg MIX COLOR );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Pg — Graphics 287

PgSetFillColor()  2005, QNX Software Systems

See also:
PgCMY(), PgColor t, PgDefaultFill(), PgGray(), PgHSV(),
PgRGB(), PgSetDrawMode(), PgSetFillDither(), PgSetFillTransPat(),
PgSetFillXORColor(), PgSetStrokeColor(), PgSetTextColor()

288 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetFillDither()
Set the dither pattern and colors for fills

Synopsis:
void PgSetFillDither( PgColor t c1,
PgColor t c0,
PgPattern t pat );

Description:
This function combines two colors according to the pattern defined by
pat and applies the pattern to fills.
The c1 argument represents the color used for “on” bits in the dither
pattern and c0 represents the color used for “off” bits. The driver
always selects the colors closest to c1 and c0.
The dither pattern is an array of 8 bytes, aligned with the upper-left
corner of the application’s region. This pattern repeats itself every 8
pixels horizontally and every 8 pixels vertically.
This function overrides the color defined by the appropriate
PgSetFillColor() function. For basic colors, see PgColor t.
At least the following patterns are defined in <photon/Pg.h>:

September 20, 2005 Chapter 5 ¯ Pg — Graphics 289

PgSetFillDither()  2005, QNX Software Systems

Predefined dither patterns.

Examples:
// Set the fill to be black with every 8th
// vertical line being white
PgSetFillDither( Pg WHITE, Pg BLACK, Pg PAT VERT8 );

// Set the fill to be red bricks with dark gray mortar

290 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetFillDither()

PgSetFillDither(Pg DGRAY, Pg RED,

"\x20\x20\xFF\x02\x02\x02\xFF\x20" );

Here’s the code that produced the sample of predefined dither

patterns:
typedef struct {
char *name;
PgPattern t p;
} DithersListStruct;

DithersListStruct DithersList[] = {
"Pg PAT DEFAULT", Pg PAT DEFAULT,
"Pg PAT HALF", Pg PAT HALF,
"Pg PAT BACK HALF", Pg PAT BACK HALF,
"Pg PAT CHECKB8", Pg PAT CHECKB8,
"Pg PAT CHECKB4", Pg PAT CHECKB4,
"Pg PAT DIAMOND", Pg PAT DIAMOND,
"Pg PAT HORIZ8", Pg PAT HORIZ8,
"Pg PAT HORIZ4", Pg PAT HORIZ4,
"Pg PAT HORIZ2", Pg PAT HORIZ2,
"Pg PAT VERT8", Pg PAT VERT8,
"Pg PAT VERT4", Pg PAT VERT4,
"Pg PAT VERT2", Pg PAT VERT2,
"Pg PAT DIAGF8", Pg PAT DIAGF8,
"Pg PAT DIAGF4", Pg PAT DIAGF4,
"Pg PAT DIAGB8", Pg PAT DIAGB8,
"Pg PAT DIAGB4", Pg PAT DIAGB4,
"Pg PAT BRICK", Pg PAT BRICK,
"Pg PAT WEAVE", Pg PAT WEAVE,
"Pg PAT RXHATCH8", Pg PAT RXHATCH8,
"Pg PAT RXHATCH4", Pg PAT RXHATCH4,
"Pg PAT RXHATCH2", Pg PAT RXHATCH2,
"Pg PAT DXHATCH8", Pg PAT DXHATCH8,
"Pg PAT DXHATCH4", Pg PAT DXHATCH4,

};

#define DithersListNum \
(sizeof( DithersList ) / sizeof( DithersListStruct ) )
#define DithersListCHeight 20
#define DithersListWinY (DithersListNum*DithersListCHeight)

Dithers() {
DithersListStruct *DLPtr = DithersList;
PhPoint t p;
PhRect t r;
int i, y;

September 20, 2005 Chapter 5 ¯ Pg — Graphics 291

PgSetFillDither()  2005, QNX Software Systems

PgSetFont( "helv14b" );
PgSetTextColor( Pg BLACK );
PgSetStrokeColor( Pg BLACK );
for (y=i=0; i<DithersListNum;
i++, y+=DithersListCHeight, DLPtr++) {
p.x = 2;
p.y = y+14;
PgDrawText( DLPtr->name,
strlen( DLPtr->name ), &p, 0 );
PgSetFillDither( Pg WHITE, Pg DBLUE, DLPtr->p );
r.ul.x = 160; r.lr.x = 320;
r.ul.y = y; r.lr.y = y+DithersListCHeight;
PgDrawRect( &r, Pg DRAW FILL STROKE );
}
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgCMY(), PgColor t, PgDefaultFill(), PgGray(), PgHSV(),
PgRGB(), PgSetFillColor(), PgSetFillTransPat(),
PgSetFillXORColor(), PgSetStrokeDither(), PgSetTextDither()

292 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetFillTransPat()
Set the draw transparency for fills

Synopsis:
void PgSetFillTransPat( PgPattern t pat );

Description:
This function sets a masking pattern and applies it to fills. You should
use it in combination with PgSetFillColor() or PgSetFillDither().
This function uses the same patterns as PgSetFillDither(), To disable
transparency and draw normally, specify the Pg PAT DEFAULT
pattern.

☞ Because of speed considerations, some graphics drivers don’t draw

strokes with a transparency mask and, as a result, ignore the stroke
transparency pattern.

Examples:
// let background show through for half the pixels
PgSetFillTransPat( Pg PAT HALF );

// disable transparency mask, draw normally

PgSetFillTransPat( Pg PAT DEFAULT );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Pg — Graphics 293

PgSetFillTransPat()  2005, QNX Software Systems

See also:
PgDefaultFill(), PgSetDrawMode(), PgSetFillColor(),
PgSetFillDither(), PgSetFillXORColor(), PgSetStrokeTransPat(),
PgSetTextTransPat()

294 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetFillXORColor()
Set the fill color for XOR drawing

Synopsis:
void PgSetFillXORColor( PgColor t frgd,
PgColor t bkgd );

Description:
This function sets the draw color for fills. When an application XORs
this color with the color bkgd, the result is the color frgd.
Since XOR is a reflexive function, frgd and bkgd may be reversed.

Examples:
The following example:

DrawXOR() {
char *s = "Hello World!";
PhPoint t p = { 8, 30 };
PhRect t r;

PgSetFont( "helv18" );
PgSetTextColor( Pg YELLOW );
PgSetFillColor( Pg PURPLE );
PgDrawText( s, strlen( s ), &p, Pg BACK FILL );
PgExtentText( &r, &p, "helv18", s, strlen( s ) );
r.lr.x -= (r.lr.x - r.ul.x) / 2;
PgSetDrawMode( Pg DRAWMODE XOR );
PgSetFillXORColor( Pg YELLOW, Pg PURPLE );
PgDrawRect( &r, Pg DRAW FILL );
PgSetDrawMode( Pg DRAWMODE OPAQUE );
}

will draw:

September 20, 2005 Chapter 5 ¯ Pg — Graphics 295

PgSetFillXORColor()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgColor t, PgDefaultFill(), PgSetDrawMode(), PgSetFillColor(),
PgSetFillDither(), PgSetFillTransPat(), PgSetStrokeXORColor(),
PgSetTextXORColor()

296 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetFont()
Set text font

Synopsis:
void PgSetFont( char const *font file );

Description:
This function sets the font for text subsequently drawn with
PgDrawText() or PgDrawString(). Font names are in the format:
face size [style]
where face refers to the face of the font. For example:

cour Courier
helv Helvetica
ncen New Century Schoolbook
time Times Roman
lu Lucida
lut Lucida Terminal
lub Lucida Bright
swiss Swiss 721 (a scalable font)

The size argument refers to the ascent height in pixels of a

proportional font or the total height of a fixed font.
The style argument is optional. If specified, it may contain any
combination of the following:

a anti-aliased
b bold
i italic

For a complete list of available fonts, check the /usr/photon/font

directory.

September 20, 2005 Chapter 5 ¯ Pg — Graphics 297

PgSetFont()  2005, QNX Software Systems

Examples:
// use Helvetica, 12p, Normal
PgSetFont( "helv12" );
// use Helvetica, 14p, Bold Italic
PgSetFont( "helv14bi" );
// use Times Roman, 24p, Italic
PgSetFont( "time24i" );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDrawString(), PgDrawText(), PgSetFillColor(), PgSetFillDither(),
PgSetFillTransPat(), PgSetUnderline()

298 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetGC()
Set current graphics context

Synopsis:
PhGC t *PgSetGC( PhGC t *GC );

Description:
This function sets the current graphics context to GC.

Returns:
A pointer to the previous graphics context.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgCreateGC(), PgDestroyGC(), PgGetGC()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 299

PgSetMultiClip()  2005, QNX Software Systems
Set a list of rectangles to clip drawing

Synopsis:
int PgSetMultiClip( int num,
PhRect t const *clip list );

Description:
This function sets a list of rectangles to clip subsequent drawing
operations. The rectangles are always relative to the origin of the
current region. To disable this clipping, set clip list to NULL or num
to 0.
All subsequent drawing operations will be clipped to the intersection
of the clipping rectangles set by PgSetClipping(), PgSetMultiClip(),
and PgSetUserClip().

☞ PhAttach(), PhReattach(), and PgSetRegion() reset the clipping

rectangle to the full size of the region.

This function emits a draw command.

Returns:
0 Success.

-1 Unable to allocate enough memory (using malloc()) to store

the clipping rectangles.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

300 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetMultiClip()

See also:
PgSetClipping(), PgSetUserClip(), PgSetClipping(), PgSetUserClip()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 301

PgSetPalette()  2005, QNX Software Systems
Set the color palette

Synopsis:
int PgSetPalette( PgColor t const *palette,
long palette id,
short first color,
short num colors,
int flags,
long tag );

Description:
This function sets the palette for subsequent draw commands. The
palette can be either the graphics driver’s palette, or a private
hardware or software palette. The palette argument points to a static
buffer containing the palette; first color denotes the first color to set,
and num colors defines how many palette entries to set.
The graphics driver uses the palette id tag for caching. If the
palette id is 0, the tag will be used, as long as it is not 0 as well. If
palette id and tag are both 0, your region’s unique number is used as
the palette ID. To have the graphics driver release a cached palette, set
num colors to -1,
A palette can operate in one of several modes. To determine the
mode, set flags to one of the following:

Pg PALSET HARD
Used primarily for palette-based images; see PhImage t.
Setting this palette type changes the physical palette. All colors
set with a PgSet...Color() function will be chosen from this
palette, for this process only. Other processes will continue to
choose colors from the global palette and may appear incorrect.
When you release the hardware palette, the other processes will
return to their previous colors without being redrawn. You
should always release the hardware palette when your window
loses focus.

302 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetPalette()

Direct-color and fixed-color graphics drivers will change this palette

☞
type to Pg PALSET SOFT.
Pg PALSET HARDINACTIVE
Same as Pg PALSET HARD, but doesn’t change the physical
palette. You can use this to restore the global palette.
Pg PALSET SOFT
Used primarily for palette-based images; see PhImage t.
Since this type is completely handled by software in the
graphics driver, it doesn’t affect the driver’s physical palette.
Colors set with this palette type are unique to your graphics
context.
Pg PALSET HARDLOCKED
Used for palette cycling or hardware-based flashing colors.
Setting this type of palette prevents set colors from being
involved in automatic color selection. To access these locked
colors, you should OR the index with Pg INDEX COLOR when
setting a color value; see PgSetFillColor().
To ensure that no other process is currently using the specified
colors, you can OR this type with Pg PALSET FORCE EXPOSE
— this causes the screen to redraw.
Pg PALSET GLOBAL
Changes the physical palette. To ensure that all processes look
correct, you can OR this type with Pg PALSET FORCE EXPOSE
to force all windows to redraw.

You can OR the above palette types with Pg PALSET FORCE EXPOSE
to force an expose from the graphics driver. This is useful when
changing palettes; the expose causes all applications to redraw with
the new palette.
The tag argument is used for data caching by programs such as
phrelay. To calculate the tag, use PxCRC(). This argument is
ignored if you set it to 0.

September 20, 2005 Chapter 5 ¯ Pg — Graphics 303

PgSetPalette()  2005, QNX Software Systems

Returns:
0 Success.

-1 The draw buffer is too small to hold the current draw state and
the draw command.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDrawImage(), PgSetFillColor(), PgSetStrokeColor(),
PgSetTextColor(), PhImage t, PxCRC()

304 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetPlaneMask()
Protect video memory from being modified

Synopsis:
unsigned long PgSetPlaneMask( unsigned long mask);

Description:
This function protects planes of video memory from being modified.
Each bit in the specified mask corresponds to a plane of video
memory: a value of 0 enables access to the plane, a value of 1 protects
the plane.

☞ The effect of this function depends on the physical video mode. If the
video mode is “true color,” the mask will protect parts of the RGB
value of the pixel that’s in video memory. If the video mode is palette
based, the mask will protect parts of the palette index of the pixel
that’s in video memory.
This function works only on some 8-bit drivers.

Returns:
The previous mask.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Pg — Graphics 305

PgSetPlaneMask()  2005, QNX Software Systems

See also:
PgDefaultMode(), PgSetFillColor(), PgSetStrokeColor(),
PgSetTextColor()

306 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetRegion()
Determine which region will emit draw events

Synopsis:
void PgSetRegion( PhRid t rid );

Description:
This function determines which region will emit subsequent draw
events. It also resets the clipping rectangle to the full size of the
region. Note that all draws are clipped to the region that emits them.
If the draw buffer contains unflushed data when this function is called,
the function will flush the data before changing the current region.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgFlush(), PgSetClipping()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 307

PgSetStrokeCap()  2005, QNX Software Systems
Set what the ends of lines look like

Synopsis:
int PgSetStrokeCap( int cap );

Description:
This function determines how the ends of thick lines are drawn. You
can set cap to one of the following:

Pg_BUTT_CAP

Pg_POINT_CAP

Pg_ROUND_CAP

Pg_SQUARE_CAP

Styles for capping lines.

The default is Pg BUTT CAP.

☞ The dotted lines in the above examples were added to illustrate how
the caps relate to the original lines; they don’t normally appear.

Returns:
The previous cap value.

Classification:
Photon

Safety
Interrupt handler No
continued. . .

308 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetStrokeCap()

Safety
Signal handler No
Thread No

See also:
PgDefaultStroke(), PgDrawEllipse(), PgDrawLine(),
PgDrawPolygon(), PgDrawRect(), PgDrawRoundRect(),
PgSetDrawMode(), PgSetStrokeDash(), PgSetStrokeDither(),
PgSetStrokeJoin(), PgSetStrokeTransPat(), PgSetStrokeWidth(),
PgSetStrokeXORColor(),

September 20, 2005 Chapter 5 ¯ Pg — Graphics 309

PgSetStrokeColor()  2005, QNX Software Systems
Set the stroke color

Synopsis:
PgColor t PgSetStrokeColor( PgColor t color );

Description:
This function sets the stroke color used for subsequent draws.
If the driver doesn’t support 24-bit color, it selects the nearest color
available to the one requested. If you OR the color with
Pg MIX COLOR, most drivers try to mix two available colors to
produce the requested color.
This function overrides the color defined by PgSetStrokeDither().

Returns:
The previous color.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgCMY(), PgColor t, PgDefaultStroke(), PgGray(), PgHSV(),
PgRGB(), PgSetDrawMode(), PgSetFillColor(), PgSetStrokeCap(),
PgSetStrokeDash(), PgSetStrokeDither(), PgSetStrokeJoin(),
PgSetStrokeTransPat(), PgSetStrokeWidth(), PgSetStrokeXORColor(),
PgSetTextColor()

310 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetStrokeDash()
Set dashed lines

Synopsis:
void PgSetStrokeDash( unsigned char const *DashList,
int ListLen,
long DashScale );

Description:
This function defines a dash list that’s used to draw lines. The
DashList argument points to an array of up to 16 characters. The
values alternate between stroke values and space values: the first
value defines a stroke length, the next defines a space length, the next
after that defines a stroke length, and so on.
The values in DashList are scaled by the DashScale argument, which
is 16.16 fixed point. The upper 16 bits are the integer part and the
lower 16 the fractional part. The fractional part is in 65536ths, not
10ths, 100ths, etc.
For example, to specify a decimal scaling factor of 1.5:

1 Put 1 in the upper 16 bits.

2 Put 0.5 * 65536 = 32768 (i.e. 0x8000) in the lower 16 bits.

The resulting scaling parameter is 0x00018000.

To specify a decimal scaling of 47.75:

1 Put 47 (i.e. 0x2F) in the upper 16 bits.

2 Put 0.75 * 65536 = 49152 (i.e. 0xC000) in the lower 16 bits.

The resulting scaling parameter is 0x002FC000.

Examples:
The following example:
typedef struct {
char *name;
int l;
char *p;

September 20, 2005 Chapter 5 ¯ Pg — Graphics 311

PgSetStrokeDash()  2005, QNX Software Systems

} DashListStruct;

/* NOTE: dash patterns are in octal */

DashListStruct DashList[] = {
"solid", 0, NULL,
"dotted", 1, "\1",
"bigger dots", 1, "\2",
"dashed", 2, "\10\4",
"long dash", 2, "\40\4",
"dash dot dot", 6, "\40\2\1\2\1\2",
"long pattern", 16,
"\3\2\5\2\10\2\13\2\15\2\13\2\10\2\5\2",
"complex", 7, "\20\1\14\2\11\3\6",
};
#define DashListNum \
(sizeof( DashList ) / sizeof( DashListStruct ))
#define DashListCHeight 20
#define DashListWinY \
(DashListNum*DashListCHeight)

Dashes() {
DashListStruct *DLPtr = DashList;
PhPoint t p;
PhRect t r;
int i, y;

PgSetFont( "helv14b" );
PgSetTextColor( Pg WHITE );
PgSetStrokeColor( Pg WHITE );
for (y=i=0; i<DashListNum; i++,
y+=DashListCHeight, DLPtr++) {
p.x = 2;
p.y = y+14;
PgDrawText( DLPtr->name, strlen( DLPtr->name ),
&p, 0 );
PgSetStrokeDash( DLPtr->p, DLPtr->l, 0x10000 );
PgSetFillDither( Pg WHITE, Pg DBLUE, DLPtr->p );
PgDrawILine( 100, y+(DithersListCHeight/2),
320, y+(DithersListCHeight/2) );
}
}

will draw:

312 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetStrokeDash()

solid
dotted
bigger dots
dashed
long dash
dash dot dot
long pattern
complex

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDefaultStroke(), PgDrawLine(), PgDrawPolygon(), PgDrawRect(),
PgSetDrawMode(), PgSetStrokeCap(), PgSetStrokeDither(),
PgSetStrokeJoin(), PgSetStrokeTransPat(), PgSetStrokeWidth(),
PgSetStrokeXORColor()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 313

PgSetStrokeDither()  2005, QNX Software Systems
Set the stroke dither pattern

Synopsis:
void PgSetStrokeDither( PgColor t c1,
PgColor t c0,
PgPattern t pat );

Description:
This function combines two colors according to the pattern defined by
pat and applies the pattern to outlines.
The c1 argument represents the color used for “on” bits in the dither
pattern and c0 represents the color used for “off” bits. The driver
always selects the colors closest to c1 and c0.
The dither pattern is an array of 8 bytes, aligned with the upper-left
corner of the application’s region. This pattern repeats itself every 8
pixels horizontally and every 8 pixels vertically. For a sample of
dither patterns, see PgSetFillDither().

☞ Because of speed considerations, some graphics drivers don’t dither

strokes. If a driver doesn’t support dithering, it uses c1 to draw
strokes.

This function overrides the color defined by PgSetStrokeColor(). For

basic colors, see PgColor t.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

314 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetStrokeDither()

See also:
PgCMY(), PgColor t, PgDefaultStroke(), PgGray(), PgHSV(),
PgRGB(), PgSetDrawMode(), PgSetFillDither(), PgSetStrokeCap(),
PgSetStrokeColor(), PgSetStrokeDash(), PgSetStrokeJoin(),
PgSetStrokeTransPat(), PgSetStrokeWidth(), PgSetStrokeXORColor(),
PgSetTextDither()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 315

PgSetStrokeJoin()  2005, QNX Software Systems
Set how lines are joined

Synopsis:
int PgSetStrokeJoin( int join );

Description:
This function determines how thick lines are connected. You can set
join to one of the following:

316 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetStrokeJoin()

Pg_BEVEL_JOIN

Pg_BUTT_JOIN

Pg_MITER_JOIN

Pg_QROUND_JOIN

Pg_ROUND_JOIN

Styles for joining lines.

The default is Pg MITER JOIN. Pg QROUND JOIN gives a quick

simulated rounded join.

September 20, 2005 Chapter 5 ¯ Pg — Graphics 317

PgSetStrokeJoin()  2005, QNX Software Systems

☞ The dotted lines in the above examples were added to illustrate how
the joints relate to the original lines; they do not normally appear.

Returns:
The previous join value.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDefaultStroke(), PgDrawEllipse(), PgDrawLine(),
PgDrawPolygon(), PgDrawRect(), PgDrawRoundRect(),
PgSetDrawMode(), PgSetStrokeCap(), PgSetStrokeColor(),
PgSetStrokeDash(), PgSetStrokeDither() PgSetStrokeTransPat(),
PgSetStrokeWidth(), PgSetStrokeXORColor(),

318 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetStrokeTransPat()
Set the draw transparency for strokes

Synopsis:
void PgSetStrokeTransPat( PgPattern t pat );

Description:
This function sets a masking pattern and applies it to outlines. You
should use it in combination with PgSetStrokeColor() or
PgSetStrokeDither().
This function uses the same patterns as PgSetFillDither(). To disable
transparency and draw normally, specify the Pg PAT DEFAULT
pattern.

☞ Because of speed considerations, some graphics drivers don’t draw

strokes with a transparency mask and, as a result, ignore the stroke
transparency pattern.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDefaultStroke(), PgSetDrawMode(), PgSetFillTransPat(),
PgSetStrokeCap(), PgSetStrokeColor(), PgSetStrokeDash(),
PgSetStrokeDither(), PgSetStrokeJoin(), PgSetStrokeWidth(),
PgSetStrokeXORColor(), PgSetTextTransPat()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 319

PgSetStrokeWidth(), PgSetStrokeFWidth()  2005, QNX
Software Systems
Set line thickness
Synopsis:
int PgSetStrokeWidth( int width );

long PgSetStrokeFWidth( long width );

Description:
These functions set the thickness of lines.
If you call PgSetStrokeWidth(), the width argument takes an integer
that indicates the width of the line in pixels. But if you call
PgSetStrokeFWidth(), the width argument takes a pixel width
multiplied by 65,536 (0x10000). For example, specifying a value of
0x80000 will set the line width to 8 pixels.

☞ The minimum line width for PgSetStrokeFWidth() is one pixel.

Returns:
The previous width.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

Caveats:
We don’t recommend using a line width greater than one pixel. Some
graphics drivers might give unexpected results.

320 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetStrokeWidth(),
PgSetStrokeFWidth()
See also:
PgDefaultStroke(), PgDrawEllipse(), PgDrawLine(),
PgDrawPolygon(), PgDrawRect(), PgDrawRoundRect(),
PgSetDrawMode(), PgSetStrokeCap(), PgSetStrokeColor(),
PgSetStrokeDash(), PgSetStrokeDither(), PgSetStrokeJoin(),
PgSetStrokeTransPat(), PgSetStrokeXORColor()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 321

PgSetStrokeXORColor()  2005, QNX Software Systems
Set the stroke color for XOR drawing

Synopsis:
void PgSetStrokeXORColor( PgColor t frgd,
PgColor t bkgd );

Description:
This function sets the draw color for outlines. When an application
XORs this color with the color bkgd, the result is the color frgd.
Since XOR is a reflexive function, frgd and bkgd may be reversed.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgColor t, PgDefaultStroke(), PgSetDrawMode(),
PgSetFillXORColor(), PgSetStrokeCap(), PgSetStrokeColor(),
PgSetStrokeDash(), PgSetStrokeDither(), PgSetStrokeJoin(),
PgSetStrokeTransPat(), PgSetStrokeWidth(), PgSetTextXORColor()

322 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetTextColor()
Set the text and bitmap color

Synopsis:
PgColor t PgSetTextColor( PgColor t color );

Description:
This function sets the color used for text and bitmaps in subsequent
draws.
If the driver doesn’t support 24-bit color, it selects the nearest color
available to the one requested. If you OR the color with
Pg MIX COLOR, most drivers try to mix two available colors to
produce the requested color.
This function overrides the color defined by PgSetTextDither().

Returns:
The previous color.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgCMY(), PgColor t, PgDefaultText(), PgDrawString(),
PgDrawText(), PgDrawTextArea(), PgExtentText(), PgGray(),
PgHSV(), PgRGB(), PgSetDrawMode(), PgSetFillColor(),
PgSetStrokeColor(), PgSetTextDither(), PgSetTextTransPat(),
PgSetTextXORColor(), PgSetUnderline()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 323

PgSetTextDither()  2005, QNX Software Systems
Set the dither pattern for text and bitmap

Synopsis:
void PgSetTextDither( PgColor t c1,
PgColor t c0,
PgPattern t pat );

Description:
This function combines two colors according to the pattern defined by
pat and applies the pattern to text and bitmaps.
The c1 argument represents the color used for “on” bits in the dither
pattern and c0 represents the color used for “off” bits. The driver
always selects the colors closest to c1 and c0.
The dither pattern is an array of 8 bytes, aligned with the upper-left
corner of the application’s region. This pattern repeats itself every 8
pixels horizontally and every 8 pixels vertically. For a sample of
dither patterns, see PgSetFillDither().
This function overrides the color defined by PgSetTextColor(). For
basic colors, see PgColor t.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgColor t, PgDefaultText(), PgDrawString(), PgDrawText(),
PgDrawTextArea(), PgExtentText(), PgGray(), PgHSV(), PgRGB(),
PgSetDrawMode(), PgSetFillDither(), PgSetStrokeDither(),

324 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetTextDither()

PgSetTextColor(), PgSetTextTransPat(), PgSetTextXORColor(),

PgSetUnderline()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 325

PgSetTextTransPat()  2005, QNX Software Systems
Set the draw transparency for text and bitmaps

Synopsis:
void PgSetTextTransPat( PgPattern t pat );

Description:
This function sets a masking pattern and applies it to text and
bitmaps. You should use it in combination with PgSetTextColor() or
PgSetTextDither().
This function uses the same patterns as PgSetFillDither(). To disable
transparency and draw normally, specify the Pg PAT DEFAULT
pattern.

☞ Because of speed considerations, some graphics drivers don’t draw

strokes with a transparency mask and, as a result, ignore the stroke
transparency pattern.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDefaultText(), PgDrawString(), PgDrawText(), PgDrawTextArea(),
PgExtentText(), PgGray(), PgHSV(), PgRGB(), PgSetDrawMode(),
PgSetFillTransPat(), PgSetStrokeTransPat(), PgSetTextColor(),
PgSetTextDither(), PgSetTextXORColor(), PgSetUnderline()

326 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetTextXORColor()
Set the text and bitmap color for XOR drawing

Synopsis:
void PgSetTextXORColor( PgColor t frgd,
PgColor t bkgd );

Description:
This function sets the draw color for text and bitmaps. When an
application XORs this color with the color bkgd, the result is the color
frgd.
Since XOR is a reflexive function, frgd and bkgd may be reversed.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgColor t, PgDefaultText(), PgDrawString(), PgDrawText(),
PgDrawTextArea(), PgExtentText(), PgSetDrawMode(),
PgSetFillXORColor(), PgSetStrokeXORColor(), PgSetTextColor(),
PgSetTextDither(), PgSetTextTransPat(), PgSetUnderline()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 327

PgSetTranslation()  2005, QNX Software Systems
Translate draw commands horizontally and vertically

Synopsis:
void PgSetTranslation ( PhPoint t const *translation,
int flags );

Description:
This function causes all subsequent draw commands to be translated
by translation->x pixels horizontally and translation->y pixels
vertically. The default translation is (0,0). You can set flags to:

0 translation is absolute, and replaces the current

translation.

Pg RELATIVE translation is relative to the current translation, and

is added to it.

Examples:
Draw a square from (100,100) to (200,200):

PhPoint t translation;

PgSetFillColor( Pg RED );
translation.x = translation.y = 100;
PgSetTranslation( &translation, Pg RELATIVE );
PgDrawIRect( 0, 0, 100, 100, Pg DRAW FILL );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

328 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetTranslation()

See also:
PgClearTranslation()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 329

PgSetUnderline()  2005, QNX Software Systems
Set colors for underlining text

Synopsis:
void PgSetUnderline( PgColor t c1,
PgColor t c2,
int flags );

Description:
This function sets the color or colors used for underlining text:

c1 c2 Underline
Pg TRANSPARENT N/A Disabled
Any color Pg TRANSPARENT Single underline
Any color Any color Double underline

You should find double underlining useful for scored underlining

(where c2 is a shadow color) or for thick underlining (where both c1
and c2 are the same color).
No flags are currently defined.
This function affects only the drawing operations that involve text:

¯ PgDrawString()

¯ PgDrawText()

¯ PgDrawTextArea()

Classification:
Photon

Safety
Interrupt handler No
continued. . .

330 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetUnderline()

Safety
Signal handler No
Thread No

See also:
PgColor t, PgDefaultText(), PgDrawString(), PgDrawText(),
PgDrawTextArea(), PgExtentText(), PgSetDrawMode(),
PgSetTextColor(), PgSetTextDither(), PgSetTextTransPat(),
PgSetTextXORColor()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 331

PgSetUserClip(), PgSetUserClipAbsolute()  2005, QNX
Software Systems
Restrict subsequent draws

Synopsis:
void PgSetUserClip( PhRect t const *ClipRect );

void PgSetUserClipAbsolute( PhRect t const *ClipRect );

Description:
These functions restrict all subsequent draws to the area defined by
ClipRect. To disable the user clipping rectangle, pass ClipRect as
NULL.
PgSetUserClip() sets the user clipping rectangle relative to the current
translation whereas PgSetUserClipAbsolute() sets the rectangle
independent of the current translation.
The user clipping area is set independent of the clipping that’s set by
PgSetClipping() and PgSetMultiClip().
All subsequent draws will be clipped to the intersection of the
clipping rectangles set by PgSetClipping(), PgSetMultiClip(), and
PgSetUserClip().
Unlike PgSetClipping(), these functions don’t flush the draw buffer.

☞ PhAttach(), PhReattach(), and PgSetRegion() reset the clipping

rectangle to the full size of the region.

This function emits a draw command.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
continued. . .

332 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgSetUserClip(),
PgSetUserClipAbsolute()

Safety
Thread No

See also:
PgClearTranslation(), PgSetClipping(), PgSetMultiClip(),
PgSetTranslation(), PhAttach(), PhReattach(), PgSetRegion()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 333

PgShmemAttach()  2005, QNX Software Systems
Record a shared memory reference

Synopsis:
int PgShmemAttach( char const *name,
unsigned long size,
void *addr );

Description:
This function records a reference to an existing block of shared
memory (that is, a block created with shm open(), sized with ltrunc(),
and mapped into the process’s address space with mmap()).
PgShmemCleanup() is called automatically by atexit() when your
program terminates normally. If your program terminates abnormally,
it should call PgShmemCleanup() explicitly.

Returns:
0 Successful completion.

-1 An error occurred (errno will be set).

Errors:
See the errors for shm open() in the C Library Reference.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

334 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgShmemAttach()

See also:
PgDrawBitmapmx(), PgDrawImagemx(), PgShmemCleanup(),
PgShmemCreate(), PgShmemDestroy(), PgShmemDetach()
shm open(), ltrunc(), mmap() in the C Library Reference

September 20, 2005 Chapter 5 ¯ Pg — Graphics 335

PgShmemCleanup()  2005, QNX Software Systems
Remove shared memory references

Synopsis:
void PgShmemCleanup();

Description:
This function removes all shared memory references defined with
PgShmemCreate() and PgShmemAttach(). If the block was created
with PgShmemCreate(), the block will be unlinked.
PgShmemCleanup() is called automatically by atexit() when your
program terminates normally. If your program terminates abnormally,
it should call PgShmemCleanup() explicitly.

Examples:
This code fragment shows how you can use PgShmemCleanup() in a
signal handler:

void ExitCleanup( int sig ) {

sig = sig;
PgShmemCleanup();
exit( 1 );
}

main( ... ) {
.
.
.
signal( SIGTERM, ExitCleanup );
signal( SIGHUP, ExitCleanup );
signal( SIGQUIT, ExitCleanup );
signal( SIGINT, ExitCleanup );

/* main loop */
.
.
.
}

336 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgShmemCleanup()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgShmemAttach(), PgShmemCreate()
atexit() in the C Library Reference

September 20, 2005 Chapter 5 ¯ Pg — Graphics 337

PgShmemCreate()  2005, QNX Software Systems
Create a block of shared memory

Synopsis:
void *PgShmemCreate( unsigned long size,
char const *name );

Description:
This function creates a block of shared memory. The size argument
determines the size of the block.
If you pass name as NULL, this function will generate a unique name
in the form Pg########; this is the preferred mode of operation. If
you pass a name, make sure that it isn’t already in use.

☞ You must use the “mx” form of a draw function to pass the shared
memory reference. Otherwise, the data is copied into the draw event.

PgShmemCleanup() is called automatically by atexit() when your

program terminates normally. If your program terminates abnormally,
it should call PgShmemCleanup() explicitly.

Returns:
A local pointer to shared memory. If an error occurs, it returns NULL
and sets errno.

Errors:
See the errors for shm open() in the C Library Reference.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
continued. . .

338 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgShmemCreate()

Safety
Thread No

See also:
PgDrawBitmapmx(), PgDrawImagemx(), PgShmemAttach(),
PgShmemCleanup(), PgShmemDestroy(), PgShmemDetach()

September 20, 2005 Chapter 5 ¯ Pg — Graphics 339

PgShmemDestroy()  2005, QNX Software Systems
Remove a block of shared memory

Synopsis:
int PgShmemDestroy( void *addr );

Description:
This function removes a block of shared memory created with
PgShmemCreate() The block is referenced by the address returned
from PgShmemCreate().

Returns:
0 Successful completion.

-1 An error occurred (errno will be set).

Errors:
See the errors for shm unlink() in the C Library Reference.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgShmemCreate()

340 Chapter 5 ¯ Pg — Graphics September 20, 2005

 2005, QNX Software Systems PgShmemDetach()
Remove a shared memory reference

Synopsis:
int PgShmemDetach( void *addr );

Description:
This function removes a shared memory reference previously attached
with PgShmemAttach().

☞ The shared memory object will persist until no other applications

refer to it. Don’t use the same name for another shared memory
object, especially right after detaching the first one.

Returns:
0 Successful completion.

-1 An error occurred; errno is set.

Errors:
See the errors for shm unlink() in the C Library Reference.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 5 ¯ Pg — Graphics 341

PgShmemDetach()  2005, QNX Software Systems

See also:
PgShmemAttach()

342 Chapter 5 ¯ Pg — Graphics September 20, 2005

 Chapter 6
Ph — Photon

September 20, 2005 Chapter 6 ¯ Ph — Photon 343

 2005, QNX Software Systems

These functions handle operations that directly involve the Photon

Manager. Using these functions, you can:

¯ Open Photon channels.

¯ Create, destroy, or modify regions that are independent of the

widget hierarchy.

¯ Query the Photon Manager for information about regions.

¯ Initiate drag operations.

¯ Collect or emit events.

September 20, 2005 Chapter 6 ¯ Ph — Photon 345

PhAddMergeTiles()  2005, QNX Software Systems
Merge two list tiles, eliminating overlap

Synopsis:
PhTile t * PhAddMergeTiles( PhTile t *tiles,
PhTile t *add tiles,
int *added );

Description:
PhAddMergeTiles() merges the list of tiles pointed to by add tiles into
the list pointed to by tiles and returns a pointer to the resulting list.
This function makes sure that the tiles don’t overlap.

Returns:
A pointer to the merged list. This isn’t always the same as the tiles
pointer.

☞ Don’t free() the list of tiles; instead, use PhFreeTiles() to return the
tiles to the internal pool.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhClipTilings(), PhCoalesceTiles(), PhCopyTiles(),
PhDeTranslateTiles(), PhFreeTiles(), PhGetTile(),

346 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhAddMergeTiles()

PhIntersectTilings(), PhMergeTiles(), PhRectsToTiles(),

PhSortTiles(), PhTile t, PhTilesToRects(), PhTranslateTiles()

September 20, 2005 Chapter 6 ¯ Ph — Photon 347

PhArea t  2005, QNX Software Systems
Position and dimensions of a rectangular area

Synopsis:
typedef struct Ph area {
PhPoint t pos;
PhDim t size;
} PhArea t;

Description:
The PhArea t structure describes the position and dimensions of a
rectangular area. It’s used extensively by the widget (Pt*()) functions
(see the Photon Widget Reference). This structure contains at least the
following members:

pos Upper-left corner of the area.

size Size of the area.

Classification:
Photon

See also:
PhDim t, PhPoint t

348 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhAttach()
Open a communications channel

Synopsis:
struct Ph ctrl *PhAttach(
char const *name,
PhChannelParms t const *parms );

Description:
This function opens a communications channel to a Photon Manager.
The channel becomes the current channel.

☞ The application must call the PhAttach() function before it calls any
other Photon functions. Both PtInit() and PtAppInit() invoke this
function.

A Photon channel contains:

¯ an FD that can be used to send QNX messages to Photon

¯ an optional proxy that can be triggered by the Photon Manager

¯ a draw buffer for graphics commands

The name argument contains the name registered by a Photon

Manager. If you pass NULL, the function uses the PHOTON
environment variable. If PHOTON isn’t set, the function uses
/dev/photon instead.
The parms argument lets you fine-tune the resources of the channel.
Passing NULL to this argument gets the channel defaults:

¯ channel attached to a proxy (to be used for asynchronous events)

¯ maximum queue size (max q entries) of 10 events

¯ no special flags on the channel

If you don’t pass NULL to parms, you should pass a pointer to a

PhChannelParms t structure, which contains at least:

September 20, 2005 Chapter 6 ¯ Ph — Photon 349

PhAttach()  2005, QNX Software Systems

mpid t proxy;
unsigned long max q entries;
unsigned long flags;

where:

proxy Your own proxy instead of the one that the channel
would otherwise obtain. This member is valid
only if you set the Ph NO PROXY bit in flags.

max q entries The maximum number of queues likely to be

needed. The Photon Manager may override this
value.

flags Defined flags:

Ph NO PROXY Don’t allow the channel to obtain

a proxy unless the proxy member
of PhChannelParms t contains
a proxy. This flag prevents the
PhEventArm()/PhEventRead()
combination from working. You
should find this flag useful when
proxies are a limited resource.
Ph NO HOLD Don’t block the client if it
overflows another application’s
event queue.
Ph DYNAMIC BUFFER
If there’s a pending Photon event
that’s larger than the client’s
event buffer, send an event that
indicates how large the client’s
buffer needs to be to receive the
entire event message. For more
information, see PhEventNext(),
PhEventRead(), and
PhGetMsgSize().

350 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhAttach()

☞ If you attach communications channels to multiple Photon managers,

you’ll have to keep track of which regions belong to which manager.

Returns:
A pointer to a control structure.

Examples:
promiscuous call( void )
{
struct Ph ctrl *ph1, *ph2, *ph3;

ph1 = PhAttach( NULL, NULL );

if( ph1 )
printf( "ph1 is the current channel to: "
"the local Photon kernel\n" );
ph2 = PhAttach( "/dev/photon", NULL );
if( ph2 )
printf( "ph2 is the current channel to: "
"the local Photon kernel\n" );
ph3 = PhAttach( "//83/dev/photon", NULL );
if( ph3 )
printf( "ph3 is the current channel to: "
"the Photon kernel on node 83\n" );
if( !ph1 | !ph2 | !ph3 )
return( -1 );

PhReattach( ph1 );
printf( "ph1 is the current channel again\n" );
PhDetach( ph1 );
printf( "there is no current channel\n" );
PhReattach( ph3 );
printf( "ph3 is the current channel again\n" );
PhDetach( ph2 );
PhDetach( ph3 );
printf( "all Photon channels closed\n" );
return( 0 );
}

September 20, 2005 Chapter 6 ¯ Ph — Photon 351

PhAttach()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgSetDrawBufferSize(), PhDetach(), PhEventNext(), PhEventArm(),
PhEventRead(), PhGetMsgSize(), PhReattach(), PtInit(), PtAppInit()

352 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhBlit()
Blit an area within a region

Synopsis:
int PhBlit( PhRid t rid,
const PhRect t *rect,
const PhPoint t *offset );

Description:
This function “blits” the area that is defined by rect and whose origin
is defined by the origin of the region specified by rid. The area is
blitted by the given offset. Other windows aren’t affected by the blit.

Returns:
0 Success.

-1 The blit failed, possibly because rid was incorrect or the

Photon Manager wasn’t running.

Examples:
PhRect t rect = { 10,10,20,20};
PhPoint t offset = { -5, 5 };
PhRect t exposed = { 15, 10, 20, 15 };

// Blit the area bounded by (10,10), (20,20)

// five pixels left and five pixels down.

PhBlit( PtWidgetRid( region widget ), &rect, &offset );

PtDamageExtent( region widget, &exposed );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Ph — Photon 353

PhBlit()  2005, QNX Software Systems

See also:
PtWidgetRid()

354 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhChannelAttach()
Create or use a channel (Neutrino only)

Synopsis:
int PhChannelAttach( int channel,
int connection,
struct sigevent t const *event );

Description:
Use this function if you want the library to create a channel or use a
channel that you’ve created.

Neutrino This function is for Neutrino only.

The event argument describes how Photon is to notify your

application. If your application is using the widget library, pass NULL
for event. For more information, see sigevent t and ionotify() in
the Neutrino Library Reference.
To create a channel and a connection:

PhChannelAttach( 0, -1, NULL )

To attach a channel chid and create a connection:

PhChannelAttach( chid, -1, NULL )

To attach channel chid and connection coid:

PhChannelAttach( chid, coid, NULL )

Returns:
A channel ID, or -1 on error (errno is set).

September 20, 2005 Chapter 6 ¯ Ph — Photon 355

PhChannelAttach()  2005, QNX Software Systems

Errors:
EBUSY A channel is already attached and chid is nonzero
and differs from the current channel ID, or
connection isn’t -1 and differs from the currently
used connection

EINVAL channel is 0, but connection isn’t -1

other values ChannelCreate() or ConnectAttach() failed

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

356 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhClipboardCopy()
Copy data to the clipboard

Synopsis:
int PhClipboardCopy( unsigned short ig,
int n,
PhClipHeader const clip[] );

Description:
This function copies data to the clipboard. Each input group has its
own private clipboard, which can be selected through the ig
parameter. You can determine the current input group as follows:

¯ If you have the event that triggered the clipboard operation, use its
input group (e.g. cbinfo->event->input group) if it’s nonzero.

¯ If that fails, get the value of the PHIG environment variable. If

this value is nonzero, use it.

¯ If neither of the above if nonzero, specify an input group of 1.

Multiple representations of the data may be placed on the clipboard.

The number of different types is specified with the n parameter. Each
type has a header structure in the clip array. For more information, see
PhClipHeader.

Returns:
0 Successful completion.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
continued. . .

September 20, 2005 Chapter 6 ¯ Ph — Photon 357

PhClipboardCopy()  2005, QNX Software Systems

Safety
Signal handler No
Thread No

See also:
PhClipboardCopy(), PhClipboardCopyString(),
PhClipboardPasteFinish(), PhClipboardPasteStart(),
PhClipboardPasteString(), PhClipboardPasteType(),
PhClipboardPasteTypeN(), PhClipHeader

358 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhClipboardCopyString()
Copy string-only data to the clipboard

Synopsis:
int PhClipboardCopyString( unsigned short ig,
const char *string );

Description:
This function is a simple cover function for copying string-only data
to the clipboard. It builds a PhClipHeader entry:

{ "TEXT", strlen(string), string }

and then calls PhClipboardCopy() to perform the operation. The

string must end with \0.
Each input group has its own private clipboard, which you can select
through the ig parameter. You can determine the current input group
as follows:

¯ If you have the event that triggered the clipboard operation, use its
input group (e.g. cbinfo->event->input group) if it’s nonzero.

¯ If that fails, get the value of the PHIG environment variable. If

this value is nonzero, use it.

¯ If neither of the above if nonzero, specify an input group of 1.

Returns:
0 Successful completion.

-1 An error occurred.

Classification:
Photon

September 20, 2005 Chapter 6 ¯ Ph — Photon 359

PhClipboardCopyString()  2005, QNX Software Systems

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhClipboardCopy(), PhClipboardPasteFinish(),
PhClipboardPasteStart(), PhClipboardPasteString(),
PhClipboardPasteType(), PhClipboardPasteTypeN(), PhClipHeader

360 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhClipboardPasteFinish()
Release all memory associated with a paste operation

Synopsis:
void PhClipboardPasteFinish( void *cbdata );

Description:
This function releases all memory associated with the current paste
operation (begun with PhClipboardPasteStart()). The cbdata
argument is the pointer returned by PhClipboardPasteStart().
PhClipboardPasteFinish() function should be called only after all
paste operations have been completed and the required data has been
extracted from the clipboard.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhClipboardCopy(), PhClipboardCopyString(),
PhClipboardPasteStart(), PhClipboardPasteString(),
PhClipboardPasteType(), PhClipboardPasteTypeN(), PhClipHeader

September 20, 2005 Chapter 6 ¯ Ph — Photon 361

PhClipboardPasteStart()  2005, QNX Software Systems
Begin a paste operation

Synopsis:
void *PhClipboardPasteStart( unsigned short ig );

Description:
Call this function to begin a paste operation from the clipboard
associated with the given input group ig. You can determine the
current input group as follows:

¯ If you have the event that triggered the clipboard operation, use its
input group (e.g. cbinfo->event->input group) if it’s nonzero.

¯ If that fails, get the value of the PHIG environment variable. If

this value is nonzero, use it.

¯ If neither of the above if nonzero, specify an input group of 1.

The function allocates memory buffers to hold all clipboard data

types, which are scanned to provide data to PhClipboardPasteType().

Returns:
A pointer to an internal structure describing the clipboard data, or
NULL if an error occurred. The pointer must be passed to
PhClipboardPasteType() and PhClipboardPasteFinish().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

362 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhClipboardPasteStart()

See also:
PhClipboardCopy(), PhClipboardCopyString(),
PhClipboardPasteFinish(), PhClipboardPasteString(),
PhClipboardPasteType(), PhClipboardPasteTypeN(), PhClipHeader

September 20, 2005 Chapter 6 ¯ Ph — Photon 363

PhClipboardPasteString()  2005, QNX Software Systems
Paste string-only data from the clipboard

Synopsis:
char *PhClipboardPasteString( unsigned short ig );

Description:
This function is a simple cover function for pasting string-only data
from the clipboard. The function calls PhClipboardPasteStart(),
requests data of type TEXT using PhClipboardPasteType(), and
finishes with PhClipboardPasteFinish().
Each input group has its own private clipboard, which you can select
through the ig parameter. You can determine the current input group
as follows:

¯ If you have the event that triggered the clipboard operation, use its
input group (e.g. cbinfo->event->input group) if it’s nonzero.

¯ If that fails, get the value of the PHIG environment variable. If

this value is nonzero, use it.

¯ If neither of the above if nonzero, specify an input group of 1.

This function allocates the resultant string with strdup(). Your

application must free() this memory after use.

Returns:
A pointer to the text string extracted from the clipboard, or NULL if
there was no available data or an error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
continued. . .

364 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhClipboardPasteString()

Safety
Thread No

See also:
PhClipboardCopy(), PhClipboardCopyString(),
PhClipboardPasteFinish(), PhClipboardPasteStart(),
PhClipboardPasteType(), PhClipboardPasteTypeN(), PhClipHeader
strdup(), free() in the QNX 4 C Library Reference

September 20, 2005 Chapter 6 ¯ Ph — Photon 365

PhClipboardPasteType()  2005, QNX Software Systems
Search clipboard for an entry by type

Synopsis:
PhClipHeader *PhClipboardPasteType(
void *cbdata,
PhClipType type );

Description:
This function searches the clipboard data for an entry of the specified
type (an 8-character string, such as TEXT). The cbdata argument is the
pointer returned by PhClipboardPasteStart().

Returns:
A pointer to a header structure describing the requested data, or NULL
if no matching type was located on the clipboard. For more
information, see PhClipHeader.

☞ This data is held in memory and used by PhClipboardPasteStart() and

PhClipboardPasteFinish(). If your application needs this information,
copy the data to a permanent location.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

366 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhClipboardPasteType()

See also:
PhClipboardCopy(), PhClipboardCopyString(),
PhClipboardPasteFinish(), PhClipboardPasteStart(),
PhClipboardPasteString(), PhClipboardPasteTypeN(),
PhClipHeader

September 20, 2005 Chapter 6 ¯ Ph — Photon 367

PhClipboardPasteTypeN()  2005, QNX Software Systems
Search clipboard for an entry by order

Synopsis:
PhClipHeader *PhClipboardPasteTypeN( void *cbdata,
int n);

Description:
This function searches the clipboard data for the nth entry and returns
a header structure to it. This allows clipboard-viewing applications to
obtain all data types from the clipboard without prior knowledge of
the types.
The cbdata argument is the pointer returned by
PhClipboardPasteStart().

Returns:
A pointer to a header structure describing the requested data, or NULL
if no matching type was located on the clipboard. For more
information, see PhClipHeader.

☞ This data is held in memory and used by PhClipboardPasteStart() and

PhClipboardPasteFinish(). If your application needs this information,
copy the data to a permanent location.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

368 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhClipboardPasteTypeN()

See also:
PhClipboardCopy(), PhClipboardCopyString(),
PhClipboardPasteFinish(), PhClipboardPasteStart(),
PhClipboardPasteString(), PhClipboardPasteType(), PhClipHeader

September 20, 2005 Chapter 6 ¯ Ph — Photon 369

PhClipHeader  2005, QNX Software Systems
Clipboard header structure

Synopsis:
typedef char PhClipType[8];

typedef struct {
PhClipType type;
unsigned short length;
void *data;
} PhClipHeader;

#define Ph CLIPBOARD TYPE TEXT "TEXT"

#define Ph CLIPBOARD MAX TYPES 5

Description:
This data structure describes clipboard data. Its members include:

type The type of data — an 8-char string (e.g. TEXT or BMAP).

length The length of the data (pointed to by data).

data A pointer to the data itself (of length bytes).

Classification:
Photon

See also:
PhClipboardCopy(), PhClipboardCopyString(),
PhClipboardPasteFinish(), PhClipboardPasteStart(),
PhClipboardPasteString(), PhClipboardPasteType(),
PhClipboardPasteTypeN()

370 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhClipTilings()
Clip one list of tiles from another

Synopsis:
PhTile t *PhClipTilings(
PhTile t *tiles,
PhTile t const * const clip tiles,
PhTile t **intersection );

Description:
This function clips the list of tiles pointed to by clip tiles from the list
pointed to by tiles. If intersection isn’t NULL, it’s set to point to the
list of intersections that are clipped out of the tiles list.
The clip tiles list isn’t modified.

☞ Don’t free() a list of tiles; instead, use PhFreeTiles() to return the tiles
to the internal pool.

Returns:
A pointer to the clipped list of tiles, or NULL if clip tiles encompasses
tiles.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Ph — Photon 371

PhClipTilings()  2005, QNX Software Systems

See also:
PhAddMergeTiles(), PhCoalesceTiles(), PhCopyTiles(),
PhDeTranslateTiles(), PhFreeTiles(), PhGetTile(),
PhIntersectTilings(), PhMergeTiles(), PhRectsToTiles(),
PhSortTiles(), PhTile t, PhTilesToRects(), PhTranslateTiles()

372 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhCoalesceTiles()
Combine a list of tiles

Synopsis:
PhTile t * PhCoalesceTiles( PhTile t *tiles );

Description:
PhCoalesceTiles() combines the tiles in the list pointed to by tiles as
much as possible. This function works best on a sorted, merged list of
tiles.

☞ Don’t free() the list of tiles; instead, use PhFreeTiles() to return the
tiles to the internal pool.

Returns:
A pointer to the list, which is always the same as the pointer given.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhAddMergeTiles(), PhClipTilings(), PhCopyTiles(),
PhDeTranslateTiles(), PhFreeTiles(), PhGetTile(),
PhIntersectTilings(), PhMergeTiles(), PhRectsToTiles(),
PhSortTiles(), PhTile t, PhTilesToRects(), PhTranslateTiles()

September 20, 2005 Chapter 6 ¯ Ph — Photon 373

PhCopyTiles()  2005, QNX Software Systems
Copy a list of tiles

Synopsis:
PhTile t * PhCopyTiles( PhTile t const * const tile );

Description:
This function creates a copy of the list of tiles pointed to by tile.

☞ Don’t free() the list of tiles; instead, use PhFreeTiles() to return the
tiles to the internal pool.

Returns:
A pointer to the copy.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhAddMergeTiles(), PhClipTilings(), PhCoalesceTiles(),
PhDeTranslateTiles(), PhFreeTiles(), PhGetTile(),
PhIntersectTilings(), PhMergeTiles(), PhRectsToTiles(),
PhSortTiles(), PhTile t, PhTilesToRects(), PhTranslateTiles()

374 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhDCGetCurrent()
Get the current draw context

Synopsis:
PhDrawContext t *PhDCGetCurrent( void );

Description:
This function returns a pointer to the currently active draw context,
which may be a print context, memory context, or draw context.

Returns:
A pointer to the currently active draw context.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhDCSetCurrent()

September 20, 2005 Chapter 6 ¯ Ph — Photon 375

PhDCSetCurrent()  2005, QNX Software Systems
Set the currently active draw context

Synopsis:
PhDrawContext t *PhDCSetCurrent(
void *draw context );

Description:
This function makes the provided draw context active. Calling this
function with NULL makes the default draw context active. The
default draw context emits draws to graphics drivers via Photon.
A draw context is anything that defines the flow of the draw stream.
Print Contexts and Memory contexts are types of draw contexts — it
may help to think of them as specialized subclasses of the draw
context.
Contexts that may be set using this function:

Draw contexts There’s usually only one basic draw context per
application. Draw contexts are used to deliver the
draw stream to graphics drivers via Photon.

Print contexts created via PpPrintCreatePC(). Print contexts are

used to produce printed output from Photon
applications.

Memory contexts
created via PmMemCreateMC(). Memory contexts
are used to draw into memory to build images for
manipulation or display.

Returns:
The old draw context, or NULL if the new context can’t be made
current (active), in which case errno has specifics of the error.

376 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhDCSetCurrent()

Examples:
In the following example, the print context pc is made active by
calling PpPrintStart(). PpPrintStart() returns the context that the
print context is replacing. The returned context is stored to enable us
to restore the context that was active at the time we decided to start
printing.

PhDrawContext t *dc;
PpPrintContext t *pc;
PmMemoryContext t *mc;
...
if( ( dc = PpPrintStart( pc ) ) == -1 )
{
perror( "unable to activate print context" );
}
else{
// do print stuff

// Then restore context which was active before we

// started printing. This is equivalent to doing
// a PpPrintStop() followed by a PmMemStart(), or
// PpPrintStart(), depending on what type of draw
// context was active previously.

PhDCSetCurrent( dc );
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Ph — Photon 377

PhDCSetCurrent()  2005, QNX Software Systems

See also:
PhDCGetCurrent(), PmMemCreateMC(), PpPrintCreatePC(),
PpPrintStart()

378 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhDetach()
Free all resources consumed by a Photon channel

Synopsis:
int PhDetach( struct Ph ctrl *Ph );

Description:
This function frees all resources consumed by the Photon channel Ph.
If Ph is the current channel, no current channel will exist after this
function is called.
Ph is a pointer to a Photon control structure returned by a previous
call to PhAttach().

Returns:
0 Successful completion.

-1 An error occurred.

Examples:
See PhAttach().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhAttach(), PhReattach()

September 20, 2005 Chapter 6 ¯ Ph — Photon 379

PhDeTranslateTiles()  2005, QNX Software Systems
Subtract x and y offsets from the vertices of a list of tiles

Synopsis:
PhTile t * PhDeTranslateTiles(
PhTile t *tile,
PhPoint t const *point subtract );

Description:
This function subtracts the coordinates of point subtract from the
vertices of each tile in the list pointed to by tile.

☞ Don’t free() the list of tiles; instead, use PhFreeTiles() to return the
tiles to the internal pool.

Returns:
The same pointer as tile.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhAddMergeTiles(), PhClipTilings(), PhCoalesceTiles(),
PhCopyTiles(), PhFreeTiles(), PhGetTile(), PhIntersectTilings(),
PhMergeTiles(), PhRectsToTiles(), PhSortTiles(), PhTile t,
PhTilesToRects(), PhTranslateTiles()

380 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhDim t
Dimensions of an area

Synopsis:
typedef struct Ph dim {
unsigned short w, h;
} PhDim t;

Description:
The PhDim t structure defines the dimensions of an area. It contains
at least the following members:

w Width of the area.

h Height of the area.

Classification:
Photon

See also:
PhArea t, PhPoint t

September 20, 2005 Chapter 6 ¯ Ph — Photon 381

PhEvent t  2005, QNX Software Systems
Data structure describing an event

Synopsis:
typedef struct Ph event {
unsigned long type;
unsigned short subtype;
unsigned short processing flags;
PhEventRegion t emitter;
PhEventRegion t collector;
unsigned short input group;
unsigned short flags;
unsigned long timestamp;
PhPoint t translation;
unsigned short num rects;
unsigned short data len;
} PhEvent t;

Description:
The PhEvent t structure describes an event. It contains at least the
following members:

type One — and only one — of the predefined event

types:
¯ Ph EV BOUNDARY
¯ Ph EV BUT PRESS
¯ Ph EV BUT RELEASE
¯ Ph EV BUT REPEAT
¯ Ph EV COVERED
¯ Ph EV DRAG
¯ Ph EV DRAW
¯ Ph EV EXPOSE
¯ Ph EV INFO
¯ Ph EV KEY
¯ Ph EV PTR MOTION BUTTON
¯ Ph EV PTR MOTION NOBUTTON

382 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhEvent t

¯ Ph EV SERVICE
¯ Ph EV SYSTEM
¯ Ph EV TIMER
¯ Ph EV WM
These types are described below. The event type
determines how the data associated with the event is
interpreted.

subtype Further information about the event. For the possible

values of subtype, see the description of each event
type.
processing flags
Flags used or set in processing the event:
¯ Ph BACK EVENT — the event has gone down the
widget family hierarchy and is now on its way
back up.
¯ Ph DIRECTED FOCUS — the event has caused
focus to change.
¯ Ph FAKE EVENT — set this bit if the event is a
fake one created by your application.
¯ Ph FOCUS BRANCH — focus is changing, and
the current widget is on the focus path, but isn’t
the destination.
¯ Ph TYPE SPECIFIC — a mask for bits that are
specific to the type of event.
¯ Ph USER RSRVD BITS — a mask for bits that you
can use for your own purposes.

emitter Which region emitted the event. An application can

emit an event from a region — even one it doesn’t
own — by setting emitter to the ID of that region.
Applications can use this approach when they target
the device region by setting the
Ph EVENT INCLUSIVE flag.

September 20, 2005 Chapter 6 ¯ Ph — Photon 383

PhEvent t  2005, QNX Software Systems

collector Which region collected the event. When a process

has many regions open, collector lets the process
distinguish which of its regions was involved.

input group The number of the input group. A value of 0 means

there’s no input group.

flags Event-modifier flags. You can OR the following

values into flags:

Ph EVENT ABSOLUTE
Forces the rectangle set associated with the
event to be relative to the root region’s origin.
By default, the coordinates of the rectangle set
are relative to the origin of the emitting region.
Ph EVENT DIRECT
Emits the event directly from emitter to
collector.
Ph EVENT INCLUSIVE
Emits the event first to the emitting region and
then through the event space. Using this flag,
an application can guarantee that the emitter
sees the event (assuming the emitter is sensitive
to that event type).
Ph EMIT TOWARD
Emits the event toward the user. By default,
events are emitted away from the user.

timestamp When the event was emitted, in milliseconds. The

Photon Manager generates this member.

translation The translation between the emitting region’s origin

and the collecting region’s origin. An application
uses this member to convert coordinates that are
relative to the emitter’s region to coordinates that are
relative to the collector’s region.

384 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhEvent t

For example, let’s say the graphics driver wants to

render Ph EV DRAW events. When these events
reach the driver, they contain coordinates relative to
the region that emitted them. To render these events
within its own region, the graphics driver uses
translation to convert the coordinates.

num rects The number of rectangles associated with the event.

To extract the list of rectangles, see PhGetRects().

data len The length of the data associated with the event.
Since event data is optional, you can set data len to 0
when there’s no data. To extract the data from an
event, see PhGetData().

Ph EV BOUNDARY

Emitted when the pointer crosses region boundaries. The subtype

member of the PhEvent t structure indicates one of the following
boundary conditions:

Ph EV PTR ENTER
Emitted when the pointer enters a region. By default, enter
events are emitted to the frontmost region that’s under the
pointer, but only if that region is opaque or sensitive to
Ph EV EXPOSE events.
An application can still force the Photon Manager to emit
boundary events to the frontmost region under the pointer even
if that region isn’t sensitive or opaque to Ph EV EXPOSE. To do
so, the application sets the region’s Ph FORCE BOUNDARY flag
(see the description of PhRegion t).

September 20, 2005 Chapter 6 ¯ Ph — Photon 385

PhEvent t  2005, QNX Software Systems

Before entering a region, the pointer usually first enters the ancestors
☞ of that region. But with some pointing devices (for example,
touchscreens), the pointer may bypass the ancestors and enter the
region directly. If this happens, the Photon Manager emits an enter
event to the region as well as to its ancestors.
Ph EV PTR LEAVE
Emitted when the pointer leaves a region. A leave condition
occurs only when the pointer enters a region that’s not a child of
the previously entered region. (Child regions are always located
within the bounds of their parents. Thus, the pointer doesn’t
have to leave a parent to enter its child.)

Ph EV PTR STEADY
Emitted when the pointer remains motionless for 1.25 seconds.
Another Ph EV PTR STEADY won’t be emitted until the user
moves the pointer and then lets it remain motionless again.

Ph EV PTR UNSTEADY
Emitted when the pointer is moved after a Ph EV PTR STEADY
is emitted. Another Ph EV PTR UNSTEADY won’t be emitted
until the user allows the pointer to remain motionless and then
moves it again.

Ph EV BUT PRESS

Emitted when the user presses a button on a pointing device. This

event’s rectangle set consists of a point source that indicates the
current pointer focus. The event data is a PhPointerEvent t
structure that contains at least the following members:

PhPoint t pos
Indicates the untranslated, absolute position of the
current pointer focus. As a rule, you should use the
event’s rectangle set to determine coordinate positions.
However, for situations that demand absolute

386 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhEvent t

coordinates (for example, calibrating a touchscreen),

you can use pos.

unsigned char click count

Indicates the number of clicks (for example, a value of 2
indicates a double-click). See the
Ph EV RELEASE ENDCLICK subtype for
Ph EV BUT RELEASE.

short z Can be used with touchscreens to indicate touch

pressure.

unsigned char flags

Indicates that the z field is valid.
unsigned short button state
Indicates the current state of the buttons.
unsigned short buttons
Indicates which buttons the user pressed. For your
convenience, we’ve defined the following manifests:
¯ Ph BUTTON SELECT — normally the left button.
Because a pointing device might provide only this
button, you should design most applications such
that the user has the option to use this button to
perform any task.
¯ Ph BUTTON MENU — can be used to invoke menus
when they’re available.
¯ Ph BUTTON ADJUST — use is currently unspecified.

unsigned long key mods

The modifier keys that are currently pressed. See
PhKeyEvent t.

September 20, 2005 Chapter 6 ¯ Ph — Photon 387

PhEvent t  2005, QNX Software Systems

Ph EV BUT RELEASE

Emitted when the user releases a pointing-device button. This event’s

rectangle set consists of a point source that indicates the current
pointer focus. The event data is a PhPointerEvent t structure (see
Ph EV BUT PRESS). However, in this case, the buttons member
indicates the buttons that were released.
This event type has the following subtypes:

Ph EV RELEASE REAL
Emitted at the current position of the pointer (that is, where the
user actually released the button).

Ph EV RELEASE PHANTOM
Emitted where the user pressed the button.

Ph EV RELEASE ENDCLICK
Emitted when multiclicks are no longer possible, i.e. when the
user moves the mouse or stops clicking for a while.

Ph EV BUT REPEAT

Emitted when the user presses an auto-repeating button on a pointing

device. This event is emitted each time the button repeats. Its
rectangle set consists of a point source that indicates where the button
was pressed. The event data is a PhPointerEvent t structure (see
Ph EV BUT PRESS).

Ph EV COVERED

(Not yet implemented) Emitted by the Photon Manager when a region

is created. The event travels away from the user and appears to
originate from the newly created region.
Since any regions now covered by the new region see the covered
event, an application can use this event to determine if its regions are
partially covered. With this information, the application can then take
appropriate action. For example, an animation program that consumes

388 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhEvent t

many processor cycles might choose to cease animation when

covered, then resume animation when exposed again.
This event’s rectangle set describes only those areas that have become
covered. This event has no associated data.

Ph EV DRAG

Used by an application to initiate drag events, to determine their

completion, and to indicate intermediate drag-motion events.
The event data is a PhDragEvent t structure that contains at least
the following members:

PhRid t rid Indicates the region that initiated the drag

operation. The application needs to set rid when
the drag is initiated.
unsigned short flags
Indicates which edges of the drag rectangle track
the pointer. You can OR the following values into
flags:
¯ Ph DRAG NOBUTTON — Allow the drag to
start even if the user isn’t holding down a
button.
¯ Ph DRAG KEY MOTION — During the drag,
emit drag events with the
Ph EV DRAG KEY EVENT or the
Ph EV DRAG MOTION EVENT subtype (these
subtypes are described below).
¯ Ph DRAG TRACK — No drag outline is drawn,
and Ph EV DRAG MOVE events are emitted to
the initiating region. This flag is used by
applications that wish to implement their own
visual interpretation of drag operations.
¯ Ph TRACK LEFT — left edge tracks the pointer.
¯ Ph TRACK RIGHT — right edge tracks the
pointer.

September 20, 2005 Chapter 6 ¯ Ph — Photon 389

PhEvent t  2005, QNX Software Systems

¯ Ph TRACK TOP — top edge tracks the pointer.

¯ Ph TRACK BOTTOM — bottom edge tracks the
pointer.
¯ Ph TRACK DRAG — all edges track the pointer
(same as using all four of the above values).

PhRect t rect Contains the coordinates of the initial, current, or

final drag rectangle, depending on the drag-event
subtype value.
PhRect t boundary
Contains the coordinates of the rectangle that
constrains the drag operation.

The Ph EV DRAG event can have any of the following subtypes:

Ph EV DRAG BOUNDARY
Emitted when rect hits a boundary. The flags member of the
PhDragEvent t structure specifies which boundary.

Ph EV DRAG COMPLETE
When the user completes the drag operation, the device region
emits a Ph EV DRAG event with this subtype toward the root
region so that the initiating application collects the event. This
event is direct.
Ph EV DRAG INIT
To initiate a drag operation, an application must emit a
Ph EV DRAG event with this subtype to the device region. The
Photon Manager takes care of the user’s interaction with the
screen pointer and the drag outline.
The PhInitDrag() function, which emits Ph EV DRAG INIT,
provides a convenient way to initiate drag operations.

Ph EV DRAG KEY EVENT

Emit the event with a PhKeyEvent t structure.

390 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhEvent t

Ph EV DRAG MOTION EVENT

Emit the event with a PhPointerEvent t structure.
Ph EV DRAG MOVE
Indicates intermediate drag motion. The Photon Manager emits
this drag-event subtype if the Ph DRAG TRACK flag was set in
the flag member of the PhDragEvent t structure when the
drag operation was initiated.

Ph EV DRAG START
Emitted when the server begins the drag operation.

Ph EV DRAW

Emitted by the Pg functions when applications perform draw

operations. The event travels toward the user and is collected by the
graphics driver.
The event data is a PhDrawEvent t structure that contains at least
the following members:

unsigned short cmd buffer size

Size of the draw buffer, in bytes.

unsigned long id
An ID number that’s unique for each application in this Photon
space. The Pg functions set this number, which is used to
optimize drawing operations.

Ph EV EXPOSE

Emitted by the Photon Manager on behalf of a region being moved,

resized, or removed from the event space. The event travels away
from the user and appears to originate from the removed region.
Since any regions now exposed see the expose event, an application
can determine which of its regions have been uncovered. It can then
redraw any portion of the regions that become visible by passing the

September 20, 2005 Chapter 6 ¯ Ph — Photon 391

PhEvent t  2005, QNX Software Systems

rectangle set to PgSetClipping(). This event’s rectangle set describes

those areas that are now exposed. This event has no associated data.
The Ph EV EXPOSE event can have any of the following subtypes:

Ph NORMAL EXPOSE
Emitted when a region is moved, resized, or removed from the
event space. This is the most common type of expose.

Ph CAPTURE EXPOSE
Emitted by an application (typically a printer driver) that wishes
to receive an encapsulated draw event starting with:

PgFFlush (Ph START DRAW);

and ending with:

PgFFlush (Ph DONE DRAW);

when the applications that received the expose have completed

their updates.
This type of event indicates that the expose wasn’t caused by a
region change. You can use this event type to collect data for
the purpose of producing some form of hardcopy.

Ph GRAPHIC EXPOSE
Emitted by a graphics driver. This subtype indicates that no
region was moved, removed, or resized to generate the expose
event.

Ph EV INFO

All regions must always be transparent to Ph EV INFO events. They

are emitted by applications or service providers to disseminate
information or respond to requests. The currently defined subtypes
are:

392 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhEvent t

Ph EV INVALIDATE SYSINFO
Emitted by Photon as regions are moved, created, or
destroyed. The application must ask Photon for
updated system information should a need for this
information arise. This is handled automatically by
the widget library. The event data is NULL.

Ph EV FEP Emitted primarily by FEP service providers to inform

applications of their presence or impending absence.
The data portion of the event is a PhFEPInfo t
structure that contains at least the following members:

long type The valid types are:

¯ Ph FEP REGISTER — a FEP has
been launched (all applications
can see the event), or is
responding to a
Ph FEP BROADCAST service
message (seen only by the
application requesting the
broadcast).
¯ Ph FEP DEREGISTER — a FEP is
shutting down.
long subtype The language type of the FEP. The
valid subtypes are:
¯ Ph FEP JAPANESE
¯ Ph FEP CHINESE
¯ Ph FEP KOREAN
long len Not currently used.
char data[1] Not currently used.

September 20, 2005 Chapter 6 ¯ Ph — Photon 393

PhEvent t  2005, QNX Software Systems

Ph EV KEY

Emitted when a key state changes (for example, the user presses or
releases a key). This event’s rectangle set consists of a point source
that indicates the current focus. The event data is a PhKeyEvent t
structure.
The processing flags member of the PhEvent t structure for this
event type also include:

Ph NOT CUAKEY
Force PtContainer not to use the key for traversal (CUA).

Ph NOT HOTKEY
Force PtContainer not to treat the key as a hotkey.

Ph EV PTR MOTION BUTTON

Emitted when the user moves the pointing device while pressing a
button. This event’s rectangle set consists of a point source that
indicates the current pointer focus. The event data is a
PhPointerEvent t structure (see Ph EV BUT PRESS). The buttons
member indicates which buttons the user is pressing.

Ph EV PTR MOTION NOBUTTON

Emitted when the user moves the pointing device without pressing a
button. This event’s rectangle set consists of a point source that
indicates the current pointer focus. The event data is a
PhPointerEvent t structure (see Ph EV BUT PRESS).

☞ Large numbers of Ph EV PTR MOTION NOBUTTON events can slow

down your system. To avoid this, you should make your applications
sensitive to Ph EV PTR MOTION BUTTON whenever possible, rather
than to Ph EV PTR MOTION NOBUTTON.

394 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhEvent t

Ph EV SERVICE

These events may be emitted by applications requesting services or

providing information to services, other applications that provide
some kind of service in a Photon system. The currently defined
subtypes are:

Ph EV REMOTE WM
Handled by relay-type services such as phrelay.
Normally only emitted by a Window Manager to
synchronize a remote Window Manager’s state. The
event data is a PhRemoteWMEvent t structure that
contains at least the following members:

short type Valid values of type are

REMOTE WM WINDOW or
REMOTE WM TITLE.
short len Not used.

If type is REMOTE WM WINDOW, the window

member is also defined. The window member has at
least the following members:

ushort t xpos New absolute x coordinate of the

window.
ushort t ypos New absolute y coordinate of the
window.
ushort t height
New height dimension of the
window.
ushort t width New width dimension of the
window.
short flags Valid flag bits are:
REMOTE FLAG FIXED
Window shouldn’t be
resized by the Window

September 20, 2005 Chapter 6 ¯ Ph — Photon 395

PhEvent t  2005, QNX Software Systems

Manager; the application

resizes it.
REMOTE FLAG INITIAL
New window.
REMOTE FLAG IS ORIGIN
Use xpos, ypos as the new
origin.
REMOTE FLAG NO DIM
The dim variable shouldn’t
be modified.

If type is REMOTE WM TITLE, the title member is

defined as follows:

char title[64] A title for the window.

Ph EV FEP Handled by Front End Processor (FEP) service

providers (e.g. Japanese input). The event data is a
PhFEPService t structure that contains at least the
following members:

long type The valid types are:

Ph FEP BROADCAST
Request a broadcast
from FEP service.
If a FEP is present,
it responds with an
Ph FEP REGISTER
register event.
Ph FEP RECT Give rectangle (for
pre-edit window
and cursor) to FEP
services. The
pre-edit rectangle is
defined by the event
rectangle. The

396 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhEvent t

cursor rectangle is
defined by this
structure’s rectangle
member.
Ph FEP NORECT
Invalidate rectangle
in FEP service.
Ph FEP ACTIVATE
Request activation
of FEP filter.
Ph FEP DEACTIVATE
Request
deactivation of FEP
filter.
long len Not used.
PhRect t rect The cursor rectangle relative to the
event rectangle.
long num rids The number of regions that are
parents of this region (the region
owned by the currently focused
widget). An array of num rids RIDs
should be appended to the event
data. The first RID in this list should
be the RID of the focused widget;
otherwise num rids should be set to
0.

Ph EV SYSTEM

Ph EV SYSTEM events are emitted when Photon or a service wants to

inform applications of changes in the system. The event data is a
PhSystemEvent t union. The valid member is dictated by the
subtype of the system event.
If the event subtype is Ph SYSTEM REGION CHANGE, the valid
union member is RegionChange, which contains at least the following
members:

September 20, 2005 Chapter 6 ¯ Ph — Photon 397

PhEvent t  2005, QNX Software Systems

PhRid t rid ID of the region that changed.

PhPoint t origin
Origin of the region, relative to its parent rid.

PhRect t rect
Its rectangle, relative to its origin.

ulong t flags The region’s flags.

ulong t fields
A set of bits indicating which fields of the
PhRegion t structure were modified:

¯ 0xFFFFFFFF — the region was opened.

¯ 0x00000000 — the region was closed.
¯ Other values — fields with a 1 bit were changed.
For more information, see:
¯ PhRegion t
¯ PhRegionOpen()
¯ PhRegionChange()
¯ <PhT.h>
unsigned short input group
Nonzero if the region being changed belongs to an
input group.

Ph EV TIMER

Emitted by an application directly to the Device region to request a

reciprocal event after a specific amount of time has elapsed (arm a
timer). This is usually done via PtTimerArm() or PhTimerArm().
It is also emitted by Photon when an armed timer expires. In both
cases, the event data is a PhTimerEvent t structure that contains
the following members:

398 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhEvent t

unsigned msec
unsigned zero
PhEventRegion t region

region.rid is the RID, and region.handle is a pointer to the widget

specified as the handle in a PtTimerArm() call.
When this event is received by the widget library, it delivers the event
directly to the widget designated by region.handle. It’s best to avoid
setting region.handle to anything other than a valid widget pointer.

Ph EV WM

Both the Window Manager and applications can emit this event. The
Window Manager emits this event when an application has asked to
be notified. An application can emit this event to communicate to the
Window Manager regarding windows.
Ph EV WM can have the following subtype:

Ph EV WM EVENT
The rectangle set of the event has no useful value. The event
data is a PhWindowEvent t structure.

Classification:
Photon

See also:
PhGetData(), PhGetRects(), PhKeyEvent t, PhWindowEvent t
Events chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 6 ¯ Ph — Photon 399

PhEventArm()  2005, QNX Software Systems
Arm the currently attached Photon channel

Synopsis:
int PhEventArm( void );

Description:
This function arms the current Photon channel so that the channel will
trigger the application’s event proxy when an event becomes
available. If an event is already available, the proxy is triggered
immediately.

Returns:
0 Successful completion.

-1 An error occurred.

Examples:
See PhEventRead().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhAttach(), PhEventNext(), PhEventPeek(), PhEventRead()

400 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhEventEmit()
Emit an event

Synopsis:
int PhEventEmit( PhEvent t const *event,
PhRect t const *rects,
void const *data );

Description:
This function emits the event described by the given PhEvent t
structure. The rects argument points to an array of PhRect t
structures that define the rectangles associated with the event, and
data points to variable-length event-specific data.
If event->num rects isn’t 0, then rects must point to an array of
event->num rects valid rectangles.
If event->data len isn’t 0, then data must point to a buffer of at least
event->data len bytes.
The collector and translation fields in the PhEvent t structure are
filled in only after a copy of the event is enqueued to an application.

Returns:
0 Success

-1 An error occurred, or no further events are pending. Check the

value of errno:
¯ If errno is ENOMSG, Photon had no messages enqueued to
your application at the time you emitted the event.
¯ If errno isn’t ENOMSG, an error occurred.

These return codes are useful for applications that spend most of their
time emitting events and want to retrieve an event only if there’s one
pending for them.

September 20, 2005 Chapter 6 ¯ Ph — Photon 401

PhEventEmit()  2005, QNX Software Systems

Examples:
The following example emits an expose event from the device region.
Because the event will cover the entire event space, any visible part of
the event space will be refreshed:

#include <stdio.h>
#include <time.h>
#include <Ph.h>

main( int argc, char *argv[] )

{
PhEvent t event;
PhRect t rect;

if( NULL == PhAttach( NULL, NULL ) ) {

fprintf( stderr,
"Couldn’t attach Photon channel.\n");
exit( EXIT FAILURE );
}
event.type = Ph EV EXPOSE;
event.subtype = 0;
event.flags = 0;
event.num rects = 1;
event.data len = 0;
rect.ul.x = rect.ul.y = SHRT MIN;
rect.lr.x = rect.lr.y = SHRT MAX;
PhEventEmit( &event, &rect, NULL );
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

402 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhEventEmit()

See also:
PhEventEmitmx(), PhEventNext(), PhEventPeek(), PhEventRead(),
PtSendEventToWidget()
“Emitting events” in the Events chapter of the Photon Programmer’s
Guide.

September 20, 2005 Chapter 6 ¯ Ph — Photon 403

PhEventEmitmx()  2005, QNX Software Systems
Emit an event when the event-specific data isn’t contiguous in memory

Synopsis:
int PhEventEmitmx( PhEvent t const *event,
PhRect t const *rects,
int mxparts,
iov t *mx );

Description:
This function provides an alternative to PhEventEmit(). You’ll find it
useful when the event-specific data isn’t contiguous in memory.
PhEventEmitmx() is used internally by PgFlush() (which emits a draw
event) to avoid copying large amounts of variable-length data, such as
bitmaps, into the draw buffer. Instead of copying the data, the library
builds mx entries to that data and then passes the mx entry list to
PhEventEmitmx(), which in turn emits the draw event.
The mx argument points to an array of mx entries, and mxparts
contains the number of mx entries pointed to by mx. You should leave
the first 3 mx entries blank; these will be filled in by the
PhEventEmitmx() call. You’re free to use the remaining entries to
build a description of the data to be attached to the event.
The event argument points to the standard event data structure and
rects points to an array of rectangles. For the restrictions that apply to
rects and to the attached data, see PhEventEmit().

Returns:
0 Successful completion.

-1 An error occurred, or no further events are pending. Check the

value of errno:
¯ If errno is ENOMSG, Photon had no messages enqueued to
your application at the time you emitted the event.
¯ If errno isn’t ENOMSG, an error occurred.

404 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhEventEmitmx()

These return codes are useful for applications that spend most of their
time emitting events and want to retrieve an event only if there’s one
pending for them.

Examples:
The following example emits a pointer press event. (A PhEventEmit()
call would be just as efficient and slightly more convenient...)

#include <stdio.h>
#include <time.h>
#include <Ph.h>

main( int argc, char *argv[] )

{
PhEvent t event;
PhRect t rect;
PhPointerEvent t ptr event;
struct mxfer entry mx[4];

if( NULL == PhAttach( NULL, NULL ) ) {

fprintf( stderr,
"Could not attach a Photon channel.\n");
exit( EXIT FAILURE );
}
event.type = Ph EV BUT PRESS;
event.subtype = 0;
event.src.rid = Ph DEV RID;
event.flags = 0;
event.num rects = 1;
event.data len = sizeof( ptr event );
rect.ul.x = rect.lr.x = 100;
rect.ul.y = rect.lr.y = 200;
ptr event.flags = 0;
ptr event.buttons = Ph BUTTON SELECT;
setmx( &mx[3], &ptr event, sizeof( ptr event ) );
PhEventEmitmx( &event, &rect, 4, mx );
}

Classification:
Photon

September 20, 2005 Chapter 6 ¯ Ph — Photon 405

PhEventEmitmx()  2005, QNX Software Systems

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgFlush(), PhEventEmit()
Sendmx(), setmx() (in the C Library Reference)

406 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhEventNext()
Provide synchronous event notification

Synopsis:
int PhEventNext( void *buffer,
unsigned size );

Description:
This function provides a completely synchronous event-notification
mechanism. It causes the application to become REPLY-blocked on
the currently attached Photon channel until an event occurs.
If the application’s event queue contains an event when this call is
made, Photon replies immediately with that event.

Returns:
Ph EVENT MSG
Successful completion.
Ph RESIZE MSG
The Ph DYNAMIC BUFFER flag was set in PhAttach(), and
there’s a pending Photon event that’s larger than the client’s
event buffer. This event that indicates how large the client’s
buffer needs to be to receive the entire event message.

-1 An error occurred.

Examples:
#define EVENT SIZE sizeof( PhEvent t ) + 1000

main( int argc, char *argv[] )

{
PhEvent t *event;

if( initialize() == -1 )
exit( EXIT FAILURE );

if( NULL == ( event = malloc( EVENT SIZE ) ) )

exit( EXIT FAILURE );

while( 1 ) {
switch( PhEventNext( event, EVENT SIZE ) ) {

September 20, 2005 Chapter 6 ¯ Ph — Photon 407

PhEventNext()  2005, QNX Software Systems

case Ph EVENT MSG:

PtEventHandler( event );
break;
case -1:
perror( "PhEventNext failed" );
break;
}
}
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhAttach(), PhEventPeek(), PhEventRead(), PhGetMsgSize()

408 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhEventPeek()
Check to see if an event is pending

Synopsis:
int PhEventPeek( void *buffer,
unsigned size );

Description:
This function lets you check if an event is pending on the current
Photon channel:

¯ When there’s an event pending, Photon replies immediately with

that event, and this function returns Ph EVENT MSG.

¯ If no message is available, this function returns 0.

Since this function is nonblocking, you should find it useful for

applications that need to run continuously and still interact with
Photon.

Returns:
Ph EVENT MSG
Successful completion.
Ph RESIZE MSG
The Ph DYNAMIC BUFFER flag was set in PhAttach(), and
there’s a pending Photon event that’s larger than the client’s
event buffer. This event that indicates how large the client’s
buffer needs to be to receive the entire event message.

0 No message was available.

-1 An error occurred.

Examples:
#define EVENT SIZE sizeof( PhEvent t ) + 1000

main( int argc, char *argv[] )

{
int go = 1, count = 0;

September 20, 2005 Chapter 6 ¯ Ph — Photon 409

PhEventPeek()  2005, QNX Software Systems

PhEvent t *event;

if( initialize() == -1 )
exit( EXIT FAILURE );

if( NULL == ( event = malloc( EVENT SIZE ) ) )

exit( EXIT FAILURE );

while( go ) {
if(( ++count & 15) == 0) {
PgFlush();
switch( PhEventPeek( event, EVENT SIZE ) {
case Ph EVENT MSG:
PtEventHandler( event );
break;
case -1:
perror( "PhEventPeek failed" );
break;
}
}
iterate graphics process();
}
exit( 0 );
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhAttach(), PhEventArm(), PhEventNext(), PhEventRead()

410 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhEventRead()
Provide asynchronous event notification

Synopsis:
int PhEventRead( pid t pid,
void *buffer,
unsigned size );

Description:
This function provides an asynchronous event-notification
mechanism. You’ll find it useful for applications that need to interact
with Photon but also need to collect proxies or messages from other
processes.
Typically, this function is called with the pid returned by Receive() to
see if the message received was a proxy triggered by Photon.
If pid is the application’s event proxy, PhEventRead() retrieves the
event and rearms Photon. Otherwise, it returns 0. (The event proxy
was attached automatically by a previous call to PhAttach().)
Photon may close a region (for example, via the window manager)
before you read the pending event. As a result, PhEventRead() may
indicate that no event is pending even though you were notified
otherwise. In this case, PhEventRead() returns -1 and sets errno to
ENOMSG.
You must call PhAttach() and PhEventArm() before the first call to
this function.

Returns:
Ph EVENT MSG
Successful completion.
Ph RESIZE MSG
The Ph DYNAMIC BUFFER flag was set in PhAttach(), and
there’s a pending Photon event that’s larger than the client’s
event buffer. This event that indicates how large the client’s
buffer needs to be to receive the entire event message.
0 No message was available.

September 20, 2005 Chapter 6 ¯ Ph — Photon 411

PhEventRead()  2005, QNX Software Systems

-1 An error occurred.

Examples:
#define EVENT SIZE sizeof( PhEvent t ) + 1000

main( int argc, char *argv[] )

{
pid t pid;
PhEvent t *event;
struct app msg msg;

if( initialize() == -1 )
exit( EXIT FAILURE );

if( NULL == ( event = malloc( EVENT SIZE ) ) )

exit( EXIT FAILURE );
PhEventArm();

while( 1 ) {
pid = Receive( 0, &msg, sizeof( msg ) );
switch( PhEventRead( pid, event, EVENT SIZE ) ) {
case Ph EVENT MSG:
PtEventHandler( event );
break;
case 0:
process app msg( &msg );
break;
case -1:
perror( "PhEventRead failed" );
break;
}
}
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

412 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhEventRead()

See also:
PhAttach(), PhEventArm(), PhEventNext(), PhEventPeek()
Receive() in the C Library Reference.

September 20, 2005 Chapter 6 ¯ Ph — Photon 413

PhEventRegion t  2005, QNX Software Systems
Emitter and the collector of an event

Synopsis:
typedef struct Ph event region {
PhRid t rid;
long handle;
} PhEventRegion t;

Description:
The PhEventRegion t structure describes the emitter and the
collector of events. It contains at least the following members:

PhRid t rid The ID of a region. This member lets an application

determine which of its regions emitted or collected
an event.

long handle The user-definable handle that the application

specifies when it opens the region. Applications
can use handle to quickly pass a small amount of
information along with events. For example, the
widget (Pt*()) functions use handle internally.
If the region described by a PhEventRegion t
structure isn’t owned by the application that
collected the event, then the Photon Manager sets
handle to 0.

Classification:
Photon

See also:
PhEvent t

414 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhFreeTiles()
Return a list of tiles to the internal tile pool

Synopsis:
void PhFreeTiles( PhTile t * tile);

Description:
This function returns the given list of tiles to the internal tile pool.
Photon maintains an internal pool of tiles because they’re frequently
used, and using a pool reduces the amount of time spent allocating
and freeing the tiles. Use PhGetTile() to get a tile from the pool, and
this function to return a list of tiles to the pool. Don’t free() a
PhTile t structure.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhAddMergeTiles(), PhClipTilings(), PhCoalesceTiles(),
PhCopyTiles(), PhDeTranslateTiles(), PhGetTile(),
PhIntersectTilings(), PhMergeTiles(), PhRectsToTiles(),
PhSortTiles(), PhTile t, PhTilesToRects(), PhTranslateTiles()

September 20, 2005 Chapter 6 ¯ Ph — Photon 415

PhGetConnectId()  2005, QNX Software Systems
Get the connection ID of the calling process

Synopsis:
PhConnectId t PhGetConnectId( void );

Description:
This function returns the connection ID of the calling process.

Returns:
The connection ID of the calling process, or -1 on error.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhGetConnectInfo()

416 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhGetConnectInfo()
Get information about a Photon channel

Synopsis:
PhConnectId t PhGetConnectInfo(
PhConnectId t coid,
PhConnectInfo t *buf );

Description:
This function fills *buf with information about the specified Photon
channel. If coid is zero, information about the calling process is
returned. If it isn’t zero but doesn’t match any existing channel, then
the next monotonically greater channel ID is used. If coid is greater
than any existing channel ID, -1 is returned and errno is set to ESRCH.
The PhConnectInfo t structure includes at least the following:

typedef struct Ph psinfo {

unsigned long flags;
PhChannelParms t parms;
PhConnectId t block;
unsigned num q entries;
unsigned buf len;
PhConnectId t id;
nid t nid;
pid t pid;
} PhConnectInfo t;

Returns:
The channel ID (the same as buf->id), or -1 if the call fails.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Ph — Photon 417

PhGetConnectInfo()  2005, QNX Software Systems

See also:
PhGetConnectId()

418 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhGetData()
Get data for an event

Synopsis:
void *PhGetData( PhEvent t const *event );

Description:
This function returns a pointer to an event-specific data structure. For
a complete description of the data structures returned with each event
type, see the description of the PhEvent t structure.
You can determine the size of the data from event->data len.

Returns:
A pointer to an event-specific data structure.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhEvent t, PhGetRects()

September 20, 2005 Chapter 6 ¯ Ph — Photon 419

PhGetMsgSize()  2005, QNX Software Systems
Get message size

Synopsis:
unsigned PhGetMsgSize( PhEvent t const *event buf );

Description:
This function returns the size of buffer necessary to contain the event
that couldn’t fit into the current buffer. You typically use this function
after PhEventRead(), PhEventPeek(), or PhEventNext() has returned a
value of Ph RESIZE MSG.
These functions can return Ph RESIZE MSG only if the application set
the Ph DYNAMIC BUFFER flag when it attached the Photon channels;
see PhAttach().

Returns:
The size of the buffer required to accommodate the entire event.

Examples:
The following fragment shows how you can use PhGetMsgSize() to
maintain a dynamic event buffer:

PhEvent t *event buf;

unsigned event buf size;
case Ph EVENT MSG:
PtEventHandler( event buf );
break;
case Ph RESIZE MSG:
event buf size = PhGetMsgSize( event buf );
if( !( event buf = realloc( event buf,
event buf size ) ) )
{
errno = ENOMEM;
return( -1 );
}
break;

420 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhGetMsgSize()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhAttach(), PhEventNext(), PhEventPeek(), PhEventRead()

September 20, 2005 Chapter 6 ¯ Ph — Photon 421

PhGetRects()  2005, QNX Software Systems
Get an event’s rectangle set

Synopsis:
PhRect t *PhGetRects( PhEvent t const *event );

Description:
This function gets the rectangle set associated with the specified
event. The number of rectangles in the event’s rectangle set is given
by event->num rects.
In the case of an expose event, this function returns a pointer to the
list of rectangles that need to be repaired. In the case of a pointer
event, only one rectangle is associated with the event — the one
associated with the current position of the pointer.
For more information on the meaning of the rectangle set for different
event types, see the event types described for the PhEvent t
structure.

Returns:
A pointer to the rectangles associated with the event.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhEvent t, PhGetData()

422 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhGetTile()
Retrieve a tile from the internal tile pool

Synopsis:
PhTile t *PhGetTile( void );

Description:
Photon maintains an internal pool of tiles because tiles are frequently
used, and using the pool reduces the amount of time allocating and
freeing the tiles. This function retrieves a tile from the internal tile
pool. The tile isn’t initialized.

☞ Don’t free() the tile; instead, use PhFreeTiles() to return the tile to the
pool.

Returns:
A pointer to the new tile, or NULL if an error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhAddMergeTiles(), PhClipTilings(), PhCoalesceTiles(),
PhCopyTiles(), PhDeTranslateTiles(), PhFreeTiles(),
PhIntersectTilings(), PhMergeTiles(), PhRectsToTiles(),
PhSortTiles(), PhTile t, PhTilesToRects(), PhTranslateTiles()

September 20, 2005 Chapter 6 ¯ Ph — Photon 423

PhImage t  2005, QNX Software Systems
Data and characteristics of an image

Synopsis:
typedef struct PhImage
{
int type;
ulong t image tag;
int bpl;
PhDim t size;
ulong t palette tag;
int colors;
int xscale;
int yscale;
char format;
char flags;
char ghost bpl;
char spare1;
char *ghost bitmap;
int mask bpl;
char *mask bm;
PgColor t *palette;
char *image;
} PhImage t;

Description:
The PhImage t structure describes the data and characteristics of an
image. When you give an image to a PtLabel subclass widget, this
is the structure you must provide. To get a pointer to this structure,
use PxLoadImage(). To free the allocated members of this structure,
call PhReleaseImage().
The structure contains at least the following members:

int type The graphic type. For more info, see the
discussion on the type argument in
PgDrawImage().

424 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhImage t

ulong t image tag

The image-data tag, a cyclic redundancy check
(CRC) that’s used extensively by phrelay to
cache images.
This tag is filled in automatically for images
created in PhAB or by PxLoadImage(). If you’re
creating an image in some other way, you should
fill in the tag by calling PxCRC(), passing it the
image pixel data and the size of that data.

int bpl The number of bytes in each line of the image.

PhDim t size The size of the image.

ulong t palette tag

The palette-data tag.

int colors The number of colors in the image.

int xscale The x scale factor for the image.

int yscale The y scale factor for the image.

char format Not used.

char flags The image flags. The valid bits are:

¯ Ph RELEASE IMAGE — free the image data.
¯ Ph RELEASE PALETTE — free the palette data.

¯ Ph RELEASE TRANSPARENCY MASK — free

the transparency mask bitmap.
¯ Ph RELEASE GHOST BITMAP — free the
bitmap used for ghosting.
¯ Ph RELEASE IMAGE ALL — free all the
above.

September 20, 2005 Chapter 6 ¯ Ph — Photon 425

PhImage t  2005, QNX Software Systems

The freeing is done automatically by widgets if

these bits are set. Calling PhReleaseImage() with
an image frees any resources that have the
corresponding bit set in the image flags.
char ghost bpl The number of bytes per line for the ghosting
bitmap.
char *ghost bitmap
A pointer to the transparency mask for ghosting an
image. The leftmost pixel corresponds to the top
bit of the first byte in the mask.
int mask bpl The number of bytes per line for the transparency
mask.
char *mask bm
A pointer to the transparency mask. The leftmost
pixel corresponds to the top bit of the first byte in
the mask.
PgColor t *palette
The image palette.
char *image The image pixel data.

Image types
The types of image are:

Pg IMAGE PALETTE BYTE

This format packs 1 pixel per byte, allowing up to 256 colors.
This format indexes directly into the current palette; see
PgSetPalette(). If no palette is set, the function chooses colors
from the global palette; this may cause colors to look different
on each system.
Pg IMAGE PALETTE NIBBLE
This format packs 2 pixels per byte, allowing up to 16 colors.
The first pixel is in the upper half of the byte, the second is in

426 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhImage t

the lower half. These pixel values index directly into the current
palette. If no palette is set, the function chooses colors from the
global palette.

Pg IMAGE DIRECT 8888

This format is an array of 4-byte color entries. The first byte is
the red component, the second is the green, the third is the blue,
and the fourth is reserved.
Pg IMAGE DIRECT 888
This format packs each pixel into 3 bytes. Using this format,
you can represent a full 24-bit color image. Here’s the bit order:

RRRR.RRRR.GGGG.GGGG.BBBB.BBBB

Pg IMAGE DIRECT 555

This format packs each pixel into 2 bytes. Although it allows
only 32 levels of each color, this format provides reasonable
image reproduction with less data. Here’s the bit order:

xRRR.RRGG.GGGB.BBBB

Pg IMAGE DIRECT 565

This format packs each pixel into 2 bytes and matches the
display format of most 16-bit, direct-color, graphics drivers.
Here’s the bit order:

RRRR.RGGG.GGGB.BBBB

September 20, 2005 Chapter 6 ¯ Ph — Photon 427

PhImage t  2005, QNX Software Systems

Pg IMAGE DIRECT 444

This format requires 2 bytes per pixel. This format matches the
high-speed color lookup tables used by palette-based graphics
drivers and provides the fastest method of drawing direct-color
images with palette-based graphics drivers. Here’s the bit order:

xxxx.RRRR.GGGG.BBBB

Pg IMAGE GRADIENT BYTE

This format uses 1 byte per pixel. The colors are
algorithmically generated as a gradient between the color set by
PgSetFillColor() and the color set by PgSetTextColor(). A pixel
value of 0 produces the fill color, a pixel value of 255 produces
the text color, and a pixel value of 128 produces an even blend
of the two.
Pg IMAGE GRADIENT NIBBLE
This format packs 2 pixels per byte, allowing up to 16 levels.
The first pixel is in the upper half of the byte and the second
pixel is in the lower half. The colors are algorithmically
generated as a gradient between the color set by
PgSetFillColor() and the color set by PgSetTextColor(). A pixel
value of 0 produces the fill color, a pixel value of 15 produces
the text color, and a pixel value of 8 produces an even blend of
the two.

For convenience, you can AND Pg IMAGE CLASS MASK with the
image type to determine the image’s class:

Pg IMAGE CLASS PALETTE

The image requires a palette defined by PgSetPalette().
Pg IMAGE CLASS GRADIENT
The image requires first and last colors defined by
PgSetFillColor() and PgSetTextColor().

428 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhImage t

Pg IMAGE CLASS DIRECT

Each pixel defines its red, blue, and green components.

Classification:
Photon

See also:
ApGetImageRes(), PgDrawPhImagemx(), PhMakeGhostBitmap(),
PhMakeTransBitmap(), PhReleaseImage(), PmMemCreateMC(),
PmMemFlush(), PxLoadImage()

September 20, 2005 Chapter 6 ¯ Ph — Photon 429

PhInitDrag()  2005, QNX Software Systems
Initiate a drag operation

Synopsis:
int PhInitDrag( PhRid t rid,
unsigned flags,
const PhRect t *rect,
const PhRect t *boundary,
unsigned int input group,
const PhDim t *min,
const PhDim t *max,
const PhDim t *step );

Description:
This function starts a drag. Normally, when the drag has completed,
the application collects a Ph EV DRAG event that describes the results
of the operation. But if the application closes the region that has
initiated the drag operation, the operation completes without returning
a Ph EV DRAG event.
The flags argument determines how the drag operation will behave.
Defined values:

Ph TRACK LEFT
Left edge of drag rectangle tracks pointer.
Ph TRACK RIGHT
Right edge of drag rectangle tracks pointer.
Ph TRACK TOP
Top edge of drag rectangle tracks pointer.
Ph TRACK BOTTOM
Bottom edge of drag rectangle tracks pointer.
Ph TRACK DRAG
All edges of drag rectangle track pointer.
Ph DRAG TRACK
Emit drag events to track the drag, but don’t rubber-band.

430 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhInitDrag()

Ph DRAG KEY MOTION

Emit Ph EV KEY, Ph EV PTR MOTION BUTTON and
Ph EV PTR MOTION NOBUTTON events with the Ph EV DRAG
subtype during the drag. These events are normally suppressed
during a drag.

Ph DRAG NOBUTTON
Start the drag even if no buttons are held down.

The rect argument represents a rectangle to be dragged (or

“rubber-banded”) on screen, and boundary represents a rectangular
constraint area. The edges of the rectangle may not exceed this area.
The coordinates in rect and boundary are relative to the origin of the
region that initiates the drag; this region is specified by rid.
The min and max arguments define the minimum and maximum size
for the drag rectangle returned in the drag events. (The application
receives the events in absolute coordinates.) The step argument’s
width (w) and height (h) members indicate the drag granularity.
Any attempt to initiate a drag operation while another is in progress in
the same input group will fail.
You should set the input group argument to the the input-group value
supplied with the event in cbinfo (see example).

Returns:
0 Successful completion.

-1 An error occurred.

Examples:
drag lower left( PhRect t *rect, PhRect t *boundary,
PtCallbackInfo t *cbinfo )
{
PhInitDrag( my region, Ph TRACK LEFT | Ph TRACK BOTTOM,
rect, boundary,
cbinfo->event->input group,
NULL, NULL, NULL );
}

September 20, 2005 Chapter 6 ¯ Ph — Photon 431

PhInitDrag()  2005, QNX Software Systems

raw callback( PtWidget t *widget, void *data,

PtCallbackInfo t *cbinfo)
{
PhRect t *rect;
PhDragEvent t *drag;
...

switch( cbinfo->event->type )
{
case Ph EV DRAG:
drag = (PhDragEvent t *)PhGetData( cbinfo->event );
rect = &drag->rect;
// drag rectangle in ABSOLUTE coordinates.
PtTranslateRect( rect,
&cbinfo->event->translation );
// rect is now relative to the region the drag
// was initiated on.
...
}
...
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhEvent t, PhGetData(), PtTranslateRect()
“Dragging” in the Events chapter of the Photon Programmer’s Guide

432 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhIntersectTilings()
Determine the intersection of two lists of tiles

Synopsis:
PhTile t *PhIntersectTilings(
PhTile t const * const tile1,
PhTile t const * const tile2,
unsigned short *num intersect tiles );

Description:
This function creates a new list of tiles that’s the intersection of the
lists pointed to by tile1 and tile2. The original lists aren’t modified.

Returns:
A pointer to the new list, or NULL if there’s no intersection.

☞ Don’t free() the list of tiles; instead, use PhFreeTiles() to return the
tiles to the internal pool.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhAddMergeTiles(), PhClipTilings(), PhCoalesceTiles(),
PhCopyTiles(), PhDeTranslateTiles(), PhFreeTiles(), PhGetTile(),
PhMergeTiles(), PhRectsToTiles(), PhSortTiles(), PhTile t,
PhTilesToRects(), PhTranslateTiles()

September 20, 2005 Chapter 6 ¯ Ph — Photon 433

PhKeyEvent t  2005, QNX Software Systems
Data structure describing a key event

Synopsis:
typedef struct Ph ev key data {
unsigned long key mods;
unsigned long key flags;
unsigned long key cap;
unsigned long key sym;
unsigned char key scan;
unsigned char key zero1;
unsigned short key zero2;
PhPoint t pos;
unsigned short button state;
} PhKeyEvent t;

Description:
This structure describes a key event. It includes at least:

key mods Some keys (e.g. Shift or Num Lock) modify other
keys. When a modifier key is pressed or released, it’s
evaluated through a table and the key mods field is
updated accordingly. This evaluation is done before
the key event is sent.
The key mod is a combination of the following bits:
¯ Pk KM Shift
¯ Pk KM Ctrl
¯ Pk KM Alt
¯ Pk KM AltGr
¯ Pk KM Shl3 — not used.
¯ Pk KM Mod6 — not used.
¯ Pk KM Mod7 — not used.
¯ Pk KM Mod8 — not used.
¯ Pk KM Shift Lock
¯ Pk KM Ctrl Lock

434 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhKeyEvent t

¯ Pk KM Alt Lock
¯ Pk KM AltGr Lock
¯ Pk KM Shl3 Lock — not used.
¯ Pk KM Mod6 Lock — not used.
¯ Pk KM Mod7 Lock — not used.
¯ Pk KM Mod8 Lock — not used.
¯ Pk KM Caps Lock
¯ Pk KM Num Lock
¯ Pk KM Scroll Lock
If the Shift key is pressed, the Shift modifier is on; if
it’s released, the Shift modifier is off. Because some
keys occur twice on the keyboard, a key release
doesn’t guarantee that the corresponding modifier is
off — the matching key may still be pressed.

key flags Flags that indicate the status of the key:

¯ Pk KF Key Down — the key has been pressed.
¯ Pk KF Key Repeat — the key is repeating.
¯ Pk KF Scan Valid — the key scan member is valid.

¯ Pk KF Sym Valid — the key sym member is valid;

this bit is set only on a key press, not a release.
¯ Pk KF Cap Valid — the key cap member is valid.
¯ Pk KF Compose — a compose sequence is in
progress.

key cap The unique scan code produced by the key, without
any modifiers. This member is valid only if
Pk KF Cap Valid is set in the key flags.

key sym The value of the key with modifiers applied to it.
This member is valid only if Pk KF Sym Valid is set
in the key flags.

September 20, 2005 Chapter 6 ¯ Ph — Photon 435

PhKeyEvent t  2005, QNX Software Systems

This field holds the value that’s used for text entry; it
can also be used in a switch statement to determine
a key’s function.

key scan The hardware-dependent scan code for the key. This
member is valid only if Pk KF Scan Valid is set in the
key flags.

pos The current mouse-pointer position.

button state The current state of the pointing-device buttons (i.e.

which buttons are currently pressed):
¯ Ph BUTTON SELECT
¯ Ph BUTTON MENU
¯ Ph BUTTON ADJUST

All flags and key symbols are defined in <photon/PkKeyDef.h>.

Before using the key cap, key scan, or key sym members, check the
key flags to make sure they’re valid. The key cap identifies the key
that caused the event, while key sym defines the character (or function
key code) that the event carries, if any.
The keyboard is divided into groups, as dictated by ISO 9995. When
a key in the text group is pressed and the Ctrl or Alt modifier is on, the
keyboard driver doesn’t generate a key sym. If the key is in any other
key group, the driver generates a key sym.
For any key press event, there’s a corresponding release event. For
example, if you press the A key, key cap is set to a in both the press
and release (and any repeats), but only the press and repeats have a
valid key sym. Its value may be a, A, or perhaps an accented character
or some symbol, depending on whether or not this keystroke
completed a compose sequence.

436 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhKeyEvent t

Classification:
Photon

See also:
PhEvent t
Events chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 6 ¯ Ph — Photon 437

PhKeyToMb()  2005, QNX Software Systems
Get the UTF-8 value of a key event

Synopsis:
int PhKeyToMb( char *buffer,
PhKeyEvent t const *keyevent );

Description:
This function stores, in buffer, a valid UTF-8 char array for the given
key event, if one exists.

Returns:
The number of bytes in the UTF-8 code, or -1 if there’s no valid
UTF-8 code for the given event.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhGetData(), PhTo8859 1()
<photon/PkKeyDef.h>

438 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhLibVersion()
Get the version number of the Photon libraries

Synopsis:
unsigned PhLibVersion( void );

Library:
ph

Description:
This function returns the version of the Photon library that you’re
using.
You can use Ph LIB VERSION (defined in <PhT.h>) to determine the
library version when you’re compiling or running your application.

Returns:
The version number of the Photon libraries, expressed as:

major version * 100 + minor version

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Ph — Photon 439

PhLibVersion()  2005, QNX Software Systems

See also:
“Photon libraries” in the Introduction chapter of the Photon
Programmer’s Guide

440 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhMakeGhostBitmap()
Create a ghost bitmap for an image

Synopsis:
int PhMakeGhostBitmap( PhImage t *image );

Description:
This function takes a PhImage t pointer and creates a ghost bitmap
for the image. The ghost bitmap is stored in the image’s data structure.
The image argument must point to a valid PhImage t structure. It
can point to a regular or transparent image.
The ghost image is used when either Pt GHOST or Pg GHOST is
passed as a flag to PgDrawPhImagemx().

Returns:
0 The image was successfully created.

-1 The image wasn’t created. The image parameter may have

been NULL, or the allocation of the bitmap may have failed.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhImage t

September 20, 2005 Chapter 6 ¯ Ph — Photon 441

PhMakeTransBitmap()  2005, QNX Software Systems
Create a transparency mask for an image

Synopsis:
int PhMakeTransBitmap( PhImage t *image,
PgColor t trans color );

Description:
This function creates a transparent bitmap or transparency mask for
the given image, provided there isn’t one already.
The trans color argument is the color in the image’s palette to be
made transparent. If more than one entry in the palette contains this
color, the first one found is used. You can pass an index into the
palette as trans color by ORing it with Pg INDEX COLOR. For
example:

if ( PhMakeTransBitmap( my image,
n | Pg INDEX COLOR ) == 0 )
{
.
.
.
}

The resulting bitmap is stored in the mask bm member of the

PhImage t structure. This function sets the image’s
Ph RELEASE TRANSPARENCY MASK flag.

☞ This function currently supports only Pg IMAGE PALETTE NIBBLE

and Pg IMAGE PALETTE BYTE images.

To draw the image using the transparency mask, use

PgDrawPhImagemx().

Returns:
0 Success.

-1 An error occurred.

442 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhMakeTransBitmap()

Examples:
/*
* This is code for a PhAB application that demonstrates
* how to make a transparency mask for an image. This
* also shows how to take that image and to put it into
* a label widget and to draw it into a PtRaw’s canvas.
*/

/* Standard headers */
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <string.h>

/* Toolkit headers */
#include <Ph.h>
#include <Pt.h>
#include <Ap.h>

/* Local headers */
#include "abimport.h"
#include "proto.h"

ApDBase t *database;
PhImage t trans image;

/*
* Setup function for the base window
*/
int
base window setup( PtWidget t *link instance,
ApInfo t *apinfo,
PtCallbackInfo t *cbinfo )
{
PhImage t *imgptr;
PtArg t arg;

// Get the original image from an image-type

// label widget that we’ve put in a PhAB picture
// module - don’t close the database since we’ll
// still be using its image and palette data

database = ApOpenDBase( ABM our picture module );

imgptr = ApGetImageRes( database, "image label" );

// Copy it so that we don’t change the original

// PhImage t; we’ll still be using the same image
// and palette data though

memcpy( &trans image, imgptr, sizeof(PhImage t) );

September 20, 2005 Chapter 6 ¯ Ph — Photon 443

PhMakeTransBitmap()  2005, QNX Software Systems

// all white pixels will be transparent

PhMakeTransBitmap( &trans image, Pg WHITE );

// Put the image that contains the transparency mask

// into another image-type label

PtSetArg( &arg, Pt ARG LABEL DATA, &trans image,

sizeof(PhImage t) );
PtSetResources( ABW destination label, 1, &arg );

/* eliminate ’unreferenced’ warnings */

link instance = link instance, apinfo = apinfo;
cbinfo = cbinfo;

return( Pt CONTINUE );
}

/*
* Draw function (Pt ARG RAW DRAW F) for a PtRaw widget
*/
void
raw draw f( PtWidget t *widget, PhTile t *damage )
{
PhPoint t pos = {0, 0};
PhRect t rect;

damage = damage;

PtSuperClassDraw( PtBasic, widget, damage );

// Find our canvas

PtBasicWidgetCanvas( widget, &rect );

// Set translation so that drawing is relative to

// the PtRaw widget, not its parent.
PgSetTranslation( &rect.ul, Pg RELATIVE );

// Clip to our basic canvas (it’s only polite).

PtClipAdd( widget, &rect );

// Do our drawing...
PgDrawPhImagemx( &pos, &trans image, 0 );

// Remove our translation and clipping

rect.ul.x *= -1; // subtract what we added above
rect.ul.y *= -1;
PgSetTranslation( &rect.ul, Pg RELATIVE );
PtClipRemove();

444 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhMakeTransBitmap()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDrawPhImagemx(), PhImage t

September 20, 2005 Chapter 6 ¯ Ph — Photon 445

PhMergeTiles()  2005, QNX Software Systems
Remove all overlap from a list of tiles

Synopsis:
PhTile t * PhMergeTiles( PhTile t *tiles );

Description:
This function removes all overlap from the list of tiles pointed to by
tiles.

Returns:
The same pointer as tiles.

☞ Don’t free() the list of tiles; instead, use PhFreeTiles() to return the
tiles to the internal pool.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhAddMergeTiles(), PhClipTilings(), PhCoalesceTiles(),
PhCopyTiles(), PhDeTranslateTiles(), PhFreeTiles(), PhGetTile(),
PhIntersectTilings(), PhRectsToTiles(), PhSortTiles(), PhTile t,
PhTilesToRects(), PhTranslateTiles()

446 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhMoveCursorAbs()
Move cursor to absolute position

Synopsis:
void PhMoveCursorAbs( int input group,
int x,
int y );

Description:
This function moves the cursor for input group to the absolute
coordinates specified by x and y.
You can determine the current input group as follows:

¯ If you have the event that triggered the clipboard operation, use its
input group (e.g. cbinfo->event->input group) if it’s nonzero.

¯ If that fails, get the value of the PHIG environment variable. If

this value is nonzero, use it.

¯ If neither of the above if nonzero, specify an input group of 1.

☞ This function contravenes the standards put forth by the OSF/Motif

Style Guide. Most users will be disconcerted if your program changes
the pointer position. See section 2.2.3.2 of the OSF/Motif Style Guide
(ISBN 0-13-640491-X).

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Ph — Photon 447

PhMoveCursorAbs()  2005, QNX Software Systems

See also:
PhMoveCursorRel(), PhQueryCursor()

448 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhMoveCursorRel()
Move cursor to relative position

Synopsis:
void PhMoveCursorRel( int input group,
int x,
int y );

Description:
This function moves the cursor for input group to the coordinates
specified by x and y relative to the current cursor position.
You can determine the current input group as follows:

¯ If you have the event that triggered the clipboard operation, use its
input group (e.g. cbinfo->event->input group) if it’s nonzero.

¯ If that fails, get the value of the PHIG environment variable. If

this value is nonzero, use it.

¯ If neither of the above if nonzero, specify an input group of 1.

☞ This function contravenes the standards put forth by the OSF/Motif

Style Guide. Most users will be disconcerted if your program changes
the pointer position. See section 2.2.3.2 of the OSF/Motif Style Guide
(ISBN 0-13-640491-X).

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Ph — Photon 449

PhMoveCursorRel()  2005, QNX Software Systems

See also:
PhMoveCursorAbs(), PhQueryCursor()

450 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhPoint t
Coordinates of a single point

Synopsis:
typedef struct Ph point {
short x, y;
} PhPoint t;

Description:
The PhPoint t structure describes the coordinates of a single point.
It contains at least the following members:

x X-axis coordinate.

y Y-axis coordinate.

Classification:
Photon

See also:
PhArea t, PhDim t

September 20, 2005 Chapter 6 ¯ Ph — Photon 451

PhQueryCursor()  2005, QNX Software Systems
Collect cursor information

Synopsis:
int PhQueryCursor( unsigned short ig,
PhCursorInfo t *buf );

Description:
This function collects information about the cursor for input group ig
and places this information in the provided structure pointed to by
buf .
You can determine the current input group as follows:

¯ If you have the event that triggered the clipboard operation, use its
input group (e.g. cbinfo->event->input group) if it’s nonzero.

¯ If that fails, get the value of the PHIG environment variable. If

this value is nonzero, use it.

¯ If neither of the above if nonzero, specify an input group of 1.

The PhCursorInfo t structure is defined in <photon/PhT.h> and

contains at least:

PhPoint t pos
Last position, in absolute coordinates.
PhRid t region
Region that currently contains the cursor.
PhRid t ig region
Region representing the input group.
PgColor t color
Cursor color.
PhPoint t last press
Location of last Ph EV BUT PRESS event.

452 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhQueryCursor()

unsigned long msec

msec of last press.
PhPoint t steady
Last steady base point.
PhRid t dragger
Region currently dragging.
PhRect t drag boundary
Area to restrict dragging to.
PhRid t phantom rid
Region ID to deliver phantom to.
unsigned short type
Cursor type (from cursor font).
unsigned short ig
Input group number.
unsigned short button state
Flags that indicate which pointer buttons changed their state:
¯ Ph BUTTON SELECT
¯ Ph BUTTON MENU
¯ Ph BUTTON ADJUST
unsigned char click count
The number of button clicks.
unsigned long key mods
Flags indicating which modifier keys are currently held down.

Returns:
0 Successful completion.
-1 An error occurred.

September 20, 2005 Chapter 6 ¯ Ph — Photon 453

PhQueryCursor()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhMoveCursorAbs(), PhMoveCursorRel()

454 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhQueryRids()
Get a list of regions

Synopsis:
int PhQueryRids( unsigned flags,
PhRid t rid,
unsigned input group,
unsigned type,
unsigned sense,
PhRid t emitter,
const PhRect t *rect,
PhRid t rids[],
int num );

Description:
This function builds a list of up to num regions in the rids array. The
other parameters specify which regions are to be included in the list:

flags The possible flag bits are:

¯ Ph RIDQUERY IG POINTER — use input group’s
pointer position as rect.
¯ Ph RIDQUERY TOWARD — act as if the event
were emitted towards the user (away from the
root region).

rid Consider regions that intersect with the region with

this ID. Set rid to 0 to consider all regions.

input group Consider regions that belong to this input group (0

means any). You can determine the current input
group as follows:
¯ If you have the event that triggered the clipboard
operation, use its input group (e.g.
cbinfo->event->input group) if it’s nonzero.
¯ If that fails, get the value of the PHIG
environment variable. If this value is nonzero,
use it.

September 20, 2005 Chapter 6 ¯ Ph — Photon 455

PhQueryRids()  2005, QNX Software Systems

¯ If neither of the above if nonzero, specify an

input group of 1.

type Consider regions of these types:

¯ Ph WINDOW REGION
¯ Ph WND MGR REGION
¯ Ph GRAFX REGION
¯ Ph PTR REGION
¯ Ph KBD REGION
¯ Ph PRINT REGION
¯ Ph INPUTGROUP REGION
¯ Ph AUXPTR REGION
¯ Ph FORCE FRONT
¯ Ph FORCE BOUNDARY
Set type to 0 (i.e. all bits off) to consider all types of
regions.

sense Consider regions that are sensitive or opaque to

these event types. The possible bits are:
¯ Ph EV KEY
¯ Ph EV BUT PRESS
¯ Ph EV BUT RELEASE
¯ Ph EV PTR MOTION NOBUTTON
¯ Ph EV PTR MOTION BUTTON
¯ Ph EV BOUNDARY
¯ Ph EV EXPOSE
¯ Ph EV DRAW
¯ Ph EV AMIN
¯ Ph EV DRAG
¯ Ph EV COVERED
¯ Ph EV BLIT

456 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhQueryRids()

¯ Ph EV SYSTEM
¯ Ph EV WM
¯ Ph EV BUT REPEAT
¯ Ph EV RAW
¯ Ph EV TIMER
¯ Ph EV LB SYSTEM
¯ Ph EV SERVICE
¯ Ph EV INFO
Set sense to 0 (i.e. all bits off) to consider regions
regardless of their sensitivity.

emitter The region to begin the query from.

rect A pointer to a structure that specifies the area

(relative to emitter’s origin) that other regions must
intersect to be considered in the query. This can be
NULL.

Returns:
The number of regions found, or -1 if an error occurred.

☞ If this function returns -1, check errno. If it’s ENOMSG, there are no
pending Photon events; this isn’t really an error.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Ph — Photon 457

PhQueryRids()  2005, QNX Software Systems

458 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhQuerySystemInfo()
Query the system for information about a given region

Synopsis:
PhSysInfo t * PhQuerySystemInfo(
PhRid t rid,
PhRect t const *rect,
PhSysInfo t *sysinfo );

Description:
This function queries the system for information for the region with
the given rid:

¯ system bandwidth

¯ graphics drivers and their capabilities

¯ pointing devices

¯ keyboard devices

The information is stored in the buffer pointed to by sysinfo. Photon

reports information about itself and system regions that intersect the
rectangular area specified by rect. If rect is NULL, the area is the
extent of the given region.

Returns:
A pointer to the PhSysInfo t structure passed to the function, or
NULL if an error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Ph — Photon 459

PhQuerySystemInfo()  2005, QNX Software Systems

See also:
PtQuerySystemInfo()
For a description of PhSysInfo t and the information it provides,
see PhT.h and “System information” in the Regions chapter of the
Programmer’s Guide.

460 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhReattach()
Change the current Photon channel

Synopsis:
struct Ph ctrl *PhReattach( struct Ph ctrl *Ph );

Description:
This function lets you change the current Photon channel if more than
one channel has been opened. The function flushes the draw buffer
before changing the channel.
The Ph argument points to a Photon control structure returned by a
previous call to PhAttach().
If Ph is NULL, this function simply returns a pointer to the current
Photon control structure.

Returns:
Returns a pointer to the previous Photon channel.

Examples:
See PhAttach().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Ph — Photon 461

PhReattach()  2005, QNX Software Systems

See also:
PhAttach(), PhDetach()

462 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhRect t
Coordinates of a rectangle

Synopsis:
typedef struct Ph rect {
PhPoint t ul, lr;
} PhRect t;

Description:
The PhRect t structure describes the coordinates of a rectangle. It
contains at least the following members:

ul Upper-left corner.

lr Lower-right corner.

Classification:
Photon

See also:
PhPoint t

September 20, 2005 Chapter 6 ¯ Ph — Photon 463

PhRectsToTiles()  2005, QNX Software Systems
Create a list of tiles from an array of rectangles

Synopsis:
PhTile t * PhRectsToTiles( PhRect t *rects,
int num rects );

Description:
This function creates a list of tiles from the array of rectangles pointed
to by rects, with num rects entries.

Returns:
A pointer to the list of tiles.

☞ Don’t free() the list of tiles; instead, use PhFreeTiles() to return the
tiles to the internal pool.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhAddMergeTiles(), PhClipTilings(), PhCoalesceTiles(),
PhCopyTiles(), PhDeTranslateTiles(), PhFreeTiles(), PhGetTile(),
PhIntersectTilings(), PhMergeTiles(), PhSortTiles(), PhTile t,
PhTilesToRects(), PhTranslateTiles()

464 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhRegion t
Data structure that describes a region

Synopsis:
typedef struct Ph region {
PhRid t rid;
long handle;
PhConnectId t owner;
ulong t flags;
ushort t state;
unsigned long events sense;
unsigned long events opaque;
PhPoint t origin;
PhRid t parent,
child,
bro in front,
bro behind;
PgColor t cursor color;
ushort t input group;
ushort t data len;
unsigned long zero[2];
ushort t cursor type;
} PhRegion t;

Description:
The PhRegion t structure describes a region. It contains at least the
following members:

PgColor t cursor color

The cursor color for this region.

unsigned short cursor type

Sets the cursor type for this region. See
<PhCursor.h>. A cursor type of
Ph CURSOR INHERIT indicates this region inherits
the cursor from the parent region.
If you OR cursor type with
Ph CURSOR NO INHERIT, then children of this
region won’t inherit its cursor type. The children

September 20, 2005 Chapter 6 ¯ Ph — Photon 465

PhRegion t  2005, QNX Software Systems

inherit the cursor from their first ancestor that

doesn’t have the Ph CURSOR NO INHERIT flag set.

PhRid t rid This region’s ID. The Photon Manager assigns this
when the region is opened.

long handle A user-definable handle that is included as part of

the event structure. Applications can use handle to
quickly pass a small amount of information along
with events. For example, the widget toolkit
functions (Pt*()) use handle to point to a widget in
memory so that they can quickly find the
appropriate callback.
PhConnectId t owner
Indicates the owner of this region. See
PhGetConnectInfo().
unsigned long flags
Controls certain aspects of this region and also
indicates the region’s type. Of the following flags,
Ph FORCE BOUNDARY and Ph FORCE FRONT
affect how the region behaves. The others simply
indicate the region type.
These type flags are set by the API functions for the
convenience of applications that wish to identify a
region’s purpose. For example, an application can
use these flags when querying the Photon Manager
for a list of regions that have a specific type.
You can OR the following into flags:

Ph FORCE BOUNDARY
Forces the Photon Manager to
emit Ph EV BOUNDARY events
to this region. If you don’t set
this flag, the Photon Manager
determines if the region should

466 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhRegion t

get boundary events by

verifying that the region is
opaque or sensitive to
Ph EV EXPOSE events.
Ph FORCE FRONT
Forces the Photon Manager to
place this region in front of any
of its brothers that don’t have
this flag set, and behind any
brothers that do have this flag
set.
Ph GRAFX REGION
Indicates that this region
belongs to a graphics driver.
Ph INPUTGROUP REGION
Indicates that this region is an
input group.
Ph KBD REGION
Indicates that this region
belongs to an input/keyboard
driver.
Ph PTR REGION Indicates that this region
belongs to an pointer/mouse
driver.
Ph WINDOW REGION
Indicates that this region is a
window.
Ph WND MGR REGION
Indicates that the Window
Manager owns this region.

unsigned long events sense

Determines which event types this region is
sensitive to. If an event is one of these types and it

September 20, 2005 Chapter 6 ¯ Ph — Photon 467

PhRegion t  2005, QNX Software Systems

passes through the region, the event is enqueued to

the application.

unsigned long events opaque

Determines which event types this region is opaque
to. If an event is one of these types and it passes
through the region, any portion of the event that
intersects with the region is clipped out.

PhPoint t origin
Determines the region’s origin relative to its
parent’s origin. All coordinates returned in events
and elsewhere in this structure are relative to origin.
In almost all cases, the coordinates used by the API
functions are relative to the origin of the caller’s
region. However, when emitting events, the
application may use absolute coordinates by setting
the Ph EVENT ABSOLUTE flag.

PhRid t parent
Indicates the region’s parent.

PhRid t child Indicates the frontmost child region (that is, closest
to the user). If no child regions exist, the Photon
Manager sets child to -1.

PhRid t bro in front

Indicates the brother region that’s located
immediately in front. If there’s no brother in front,
the Photon Manager sets bro in front to -1.

PhRid t bro behind

Indicates the brother region that’s located
immediately behind. If there’s no brother behind,
the Photon Manager sets bro behind to -1.

468 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhRegion t

unsigned short data len

The length of the data portion of this region. The
data is stored in a single block of memory; to get a
copy of it, call PhRegionQuery().
The region data may consist of blocks of data of
different types, each preceded by a
PhRegionDataHdr t structure. There’s at most
one block of a given type. To find a specific type of
data in the region’s data, call
PhRegionDataFindType().
If you need to change the region data, modify your
copy or create a new block (starting with a
PhRegionDataHdr t structure) and pass it to
PhRegionChange().
unsigned short input group
Indicates the number of the input group. A value of
0 means this region isn’t an input group.

Classification:
Photon

See also:
PgSetRegion(), PhRegionChange(), PhRegionClose(),
PhRegionDataFindType(), PhRegionDataHdr t, PhRegionOpen(),
PhRegionQuery()
Regions chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 6 ¯ Ph — Photon 469

PhRegionChange()  2005, QNX Software Systems
Change the definition of a region

Synopsis:
int PhRegionChange( unsigned long fields,
unsigned long flags,
PhRegion t const *info,
PhRect t const *rect,
void const *data );

Description:
This function changes the definition of the region specified by
info->rid. The fields argument describes which fields in the info
structure are to be changed — for more information, see
PhRegionOpen().
The rect argument points to the rectangle associated with the region,
and data points to data associated with the region. If you don’t
specify the region’s rectangle and data in the fields argument, you can
set rect and data to NULL.
The data consists of one or more PhRegionDataHdr t structures,
each followed immediately by the appropriate type of data. This data
is merged into any existing region data, replacing the blocks of the
same types as given in data.
The flags argument controls whether or not an expose event will be
emitted to this region, when necessary. You can OR the following into
flags:

Ph EXPOSE REGION
If part of the region becomes exposed, send a Ph EV EXPOSE
event to the region.

Ph EXPOSE FAMILY
If part of the region becomes exposed, send a Ph EV EXPOSE
event to the region’s descendants.

470 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhRegionChange()

Returns:
0 Successful completion.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhRegion t, PhRegionClose(), PhRegionDataHdr t,
PhRegionOpen()

September 20, 2005 Chapter 6 ¯ Ph — Photon 471

PhRegionClose()  2005, QNX Software Systems
Remove a region

Synopsis:
int PhRegionClose( PhRid t rid );

Description:
This function removes the specified region from the current Photon
Manager. If the specified region has child regions, they’re removed as
well.

Returns:
0 Successful completion.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhRegion t, PhRegionChange(), PhRegionOpen()

472 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhRegionDataFindType()
Find a data type within a region’s data

Synopsis:
PhRegionDataHdr t *
PhRegionDataFindType(
PhRegion t const *region,
PhRegionDataHdr t const *data,
short type);

Description:
This function finds the specified type of data within the provided
region’s data block. For a list of types, see the description of
PhRegionDataHdr t.

Returns:
A pointer to a PhRegionDataHdr t structure that matches the
specified data type. If no data entries within the region’s data block
match the specified type, the function returns NULL.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhRegion t, PhRegionDataHdr t, PhRegionChange(),
PhRegionQuery()

September 20, 2005 Chapter 6 ¯ Ph — Photon 473

PhRegionDataHdr t  2005, QNX Software Systems
Data that’s attached to a region

Synopsis:
typedef struct Ph region data hdr {
unsigned short len;
unsigned short type;
} PhRegionDataHdr t;

Description:
The PhRegionDataHdr t structure describes data that’s attached to
a region. It includes at least the following members:

len The length of the data, in bytes. The data immediately

follows the PhRegionDataHdr t structure in the region’s
block of data.

type The type of data, which indicates the data structure used:

Type Structure
Ph RDATA WINDOW PhWindowInfo t
Ph RDATA CURSOR PhCursorDef t
Ph RDATA IG PhIgRegionData t
Ph RDATA GFXINFO PhGrafxRegionData t
Ph RDATA KBDINFO PhKbdRegionData t
Ph RDATA PTRINFO PhPtrRegionData t
Ph RDATA WMCONFIG WmConfig t
Ph RDATA GFXDETAIL PhGrafxDetail t
Ph RDATA INPMGRINFO Internal use only
Ph RDATA CLIPBOARD PhClipHeader
Ph RDATA USER User-defined

474 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhRegionDataHdr t

Classification:
Photon

See also:
PhRegion t, PhRegionDataFindType()

September 20, 2005 Chapter 6 ¯ Ph — Photon 475

PhRegionOpen()  2005, QNX Software Systems
Open a region

Synopsis:
PhRid t PhRegionOpen( unsigned fields,
PhRegion t const *info,
PhRect t const *rect,
void const *data );

Description:
This function opens a new region. The fields argument describes
which members specified by info will be used. If some fields aren’t
specified, the function sets the corresponding members of the new
region to their defaults.
The info argument is a template region used when opening the new
region. You must set the parent member of info; Photon fills in the
other family members.
The rect argument points to the rectangle associated with the region,
and data points to the data associated with the region.

fields bit Argument Default

Ph REGION OWNER info->owner (you)
Ph REGION HANDLE info->handle 0
Ph REGION FLAGS info->flags 0
Ph REGION EV OPAQUE info->events opaque 0
Ph REGION EV SENSE info->events sense 0
Ph REGION ORIGIN info->origin {0, 0}
Ph REGION PARENT info->parent Ph ROOT RID
Ph REGION BEHIND info->bro behind See PhRegion t
Ph REGION IN FRONT info->bro in front See PhRegion t
Ph REGION RECT rect {{0, 0}, {0, 0}}

continued. . .

476 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhRegionOpen()

fields bit Argument Default

Ph REGION DATA info->data len, data {0, 0}
Ph REGION CURSOR info->cursor type, cursor color 0 to inherit

Returns:
A positive region ID, or -1 if an error occurred.

Examples:
The following example opens a region out of the root region. The new
region will sense any mouse motion events that pass through it, and
draw a rectangle at the current position of the pointer. If the user
clicks in the region, the program will terminate. If a window manager
is running, this region will be in front of the window manager. The
window manager won’t be aware of the region.

#include <stdio.h>
#include <Ph.h>

PhRid t open region( void )

{
PhRegion t region;
PhRect t dimensions, rect;
PhRid t rid;

memset(&region, 0, sizeof(region));
/* Wish to have pointer motion
* events enqueued to us.
*/
region.events sense = Ph EV PTR MOTION |
Ph EV BUT RELEASE;

/* Wish to be opaque to all pointer-type

* events and be visually opaque.
*/
region.events opaque = Ph EV PTR ALL | Ph EV DRAW |
Ph EV EXPOSE;
/* Origin at (100,100) relative to root */
region.origin.x = region.origin.y = 100;
region.parent = Ph ROOT RID;
/* Open region from (absolute) (100,100)
to (300,300) */

September 20, 2005 Chapter 6 ¯ Ph — Photon 477

PhRegionOpen()  2005, QNX Software Systems

rect.ul.x = rect.ul.y = 0;
rect.lr.x = rect.lr.y = 200;

rid = PhRegionOpen( Ph REGION PARENT |

Ph REGION EV SENSE |
Ph REGION EV OPAQUE |
Ph REGION ORIGIN |
Ph REGION RECT,
&region, &rect, NULL );

/* If open was successful, black out the region */

if( rid != -1 ) {
PgSetRegion( rid );
PgSetFillColor( Pg BLACK );
PgDrawRect( &rect, Pg DRAW FILL );
PgFlush();
}
return( rid );
}

void draw at cursor( PhPoint t *pos )

{
PhRect t rect;
static int count = 0;
PgColor t color;

rect.ul.x = pos->x - 10;

rect.ul.y = pos->y - 10;
rect.lr.x = pos->x + 10;
rect.lr.y = pos->y + 10;
switch( ++ count % 3 ) {
case 0:
PgSetFillColor( Pg RED );
break;
case 1:
PgSetFillColor( Pg GREEN );
break;
default:
PgSetFillColor( Pg BLUE );
}
PgDrawRect( &rect, Pg DRAW FILL );
PgFlush();
}

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

{
PhEvent t *event;
int go = 1;

if( NULL == PhAttach( NULL, NULL ) ) {

478 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhRegionOpen()

fprintf( stderr, "Couldn’t attach a "

"Photon channel.\n" );
exit( EXIT FAILURE );
}

if( -1 == open region() ) {

fprintf( stderr, "Couldn’t open region.\n" );
exit( EXIT FAILURE );
}
event = (PhEvent t *)malloc( sizeof( PhEvent t )
+ 1000 );
if( event == NULL ) {
fprintf( stderr,
"Couldn’t allocate event buffer.\n" );
exit( EXIT FAILURE );
}
while( go ) {
if( PhEventNext( event, sizeof( PhEvent t )
+ 1000 ) == Ph EVENT MSG ) {
if( (event->type & Ph EV PTR MOTION) != 0 )
draw at cursor( (PhPoint t *)PhGetRects( event ) );
else
go = 0;
} else
fprintf( stderr, "Error.\n" );
}

return 0;
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Ph — Photon 479

PhRegionOpen()  2005, QNX Software Systems

See also:
PgSetRegion(), PhAttach(), PhRegion t, PhRegionChange(),
PhRegionClose()

480 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhRegionQuery()
Retrieve information about a region

Synopsis:
int PhRegionQuery( PhRid t rid,
PhRegion t *region,
PhRect t *rect,
void *data,
unsigned data len );

Description:
This function returns information about the region identified by rid.
Upon completion, region and rect contain a description of the region.
If the region has data attached to it, then the data, up to data len
bytes, is copied into data. This data may consist of smaller blocks of
data of different types, each preceded by a PhRegionDataHdr t
structure. To find a specific type of data in the region’s data, call
PhRegionDataFindType().

Returns:
0 Success.

-1 An error occurred.

Examples:
The following example gets information about the device region:
PhRegion t region; PhRect t rect;

if( !PhRegionQuery( Ph DEV RID, &region,

&rect, NULL, 0 ) ) {
printf( "Sensitive to: %.8x Opaque to: %.8x\n",
region.events sense, region.events opaque );
printf( "Located at: {(%d,%d),(%d,%d)}\n",
region.origin.x + rect.ul.x,
region.origin.y + rect.ul.y,
region.origin.x + rect.lr.x,
region.origin.y + rect.lr.y );
}

September 20, 2005 Chapter 6 ¯ Ph — Photon 481

PhRegionQuery()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhRegion t, PhRegionChange(), PhRegionOpen()

482 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhReleaseImage()
Release the allocated members of an image

Synopsis:
void PhReleaseImage( PhImage t *image );

Description:
This function releases the allocated members of the PhImage t
pointed to by image, based on the value of image->flags. The valid
flags are:

¯ Ph RELEASE IMAGE

¯ Ph RELEASE PALETTE

¯ Ph RELEASE TRANSPARENCY MASK

¯ Ph RELEASE GHOST BITMAP

¯ Ph RELEASE IMAGE ALL — free all the above.

This function doesn’t release the image structure itself.

☞ Widgets that use images call PhReleaseImage() automatically when

the widget is destroyed or the image is changed. If you set
Pt FREE MEMORY in the widget’s Pt ARG FLAGS resource, the
Ph RELEASE IMAGE ALL flag is set before calling
PhReleaseImage().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 6 ¯ Ph — Photon 483

PhReleaseImage()  2005, QNX Software Systems

See also:
ApGetImageRes(), PgDrawPhImagemx(), PhImage t,
PhMakeGhostBitmap(), PhMakeTransBitmap(), PmMemCreateMC(),
PmMemFlush(), PxLoadImage()

484 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhSortTiles()
Sort a list of tiles

Synopsis:
PhTile t * PhSortTiles( PhTile t *tiles );

Description:
This function sorts the given list of tiles by the y coordinate then the x
coordinate. Sorting a list of tiles usually results in a smaller merged
list.

☞ Don’t free() the list of tiles; instead, use PhFreeTiles() to return the
tiles to the internal pool.

Returns:
The same pointer as tiles.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhAddMergeTiles(), PhClipTilings(), PhCoalesceTiles(),
PhCopyTiles(), PhDeTranslateTiles(), PhFreeTiles(), PhGetTile(),
PhIntersectTilings(), PhMergeTiles(), PhRectsToTiles(), PhTile t,
PhTilesToRects(), PhTranslateTiles()

September 20, 2005 Chapter 6 ¯ Ph — Photon 485

PhTile t  2005, QNX Software Systems
A list of rectangles

Synopsis:
typedef struct Ph tile {
PhRect t rect;
struct Ph tile *next;
} PhTile t;

Description:
The PhTile t structure is used to build linked lists of rectangles. It
includes at least the following members:

rect The rectangle.

next A pointer to the next tile in the list.

☞ Photon maintains an internal pool of tiles because they’re frequently

used, and using a pool reduces the amount of time spent allocating
and freeing the tiles. Use PhGetTile() to get a tile from the pool, and
PhFreeTiles() to return a list of tiles to the pool.

Classification:
Photon

See also:
PhAddMergeTiles(), PhClipTilings(), PhCoalesceTiles(),
PhCopyTiles(), PhDeTranslateTiles(), PhFreeTiles(), PhGetTile(),
PhIntersectTilings(), PhMergeTiles(), PhRectsToTiles(),
PhSortTiles(), PhTilesToRects(), PhTranslateTiles()

486 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhTilesToRects()
Create an array of rectangles from a list of tiles

Synopsis:
PhRect t * PhTilesToRects( PhTile t *tiles,
int *num rects );

Description:
This function allocates an array of num rects PhRect t structures
and fills it with the rectangles described by the list of tiles pointed to
by tiles.

☞ Don’t free() the list of tiles; instead, use PhFreeTiles() to return the
tiles to the internal pool.

Returns:
A pointer to the array of rectangles.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhAddMergeTiles(), PhClipTilings(), PhCoalesceTiles(),
PhCopyTiles(), PhDeTranslateTiles(), PhFreeTiles(), PhGetTile(),
PhIntersectTilings(), PhMergeTiles(), PhRectsToTiles(),
PhSortTiles(), PhTile t, PhTranslateTiles()

September 20, 2005 Chapter 6 ¯ Ph — Photon 487

PhTimerArm()  2005, QNX Software Systems
Arm a timer event

Synopsis:
int PhTimerArm ( PhRid t rid,
long handle,
unsigned msec );

Description:
The PhTimerArm() arms a timer event on the region specified by rid
to be triggered after msec milliseconds. The handle argument is
returned in the timer event. See PhT.h for information about the
timer event structure.

☞ Don’t use PhTimerArm() in an application that uses widgets — use

PtTimerArm() instead.

Returns:
0 Successful completion.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

488 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhTimerArm()

See also:
PtTimerArm()

September 20, 2005 Chapter 6 ¯ Ph — Photon 489

PhTo8859 1()  2005, QNX Software Systems
Get the ISO8859-1 value of a key event

Synopsis:
int PhTo8859 1( PhKeyEvent t const *keyevent );

Description:
This function returns a valid ISO8859-1 code for the given key event,
if one exists. If there’s no valid ISO8859-1 code for the given event,
the function returns -1.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhGetData(), PhKeyToMb()
<photon/PkKeyDef.h>

490 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhTranslateTiles()
Add x and y offsets to the vertices of a list of tiles

Synopsis:
PhTile t * PhTranslateTiles(
PhTile t *tile,
PhPoint t const *point add );

Description:
This function adds the coordinates of point add to the vertices of each
tile in the list pointed to by tile.

☞ Don’t free() the list of tiles; instead, use PhFreeTiles() to return the
tiles to the internal pool.

Returns:
The same pointer as tile.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhAddMergeTiles(), PhClipTilings(), PhCoalesceTiles(),
PhCopyTiles(), PhDeTranslateTiles(), PhFreeTiles(), PhGetTile(),
PhIntersectTilings(), PhMergeTiles(), PhRectsToTiles(),
PhSortTiles(), PhTile t, PhTilesToRects()

September 20, 2005 Chapter 6 ¯ Ph — Photon 491

PhWindowChange()  2005, QNX Software Systems
Modify the attributes of a window’s region

Synopsis:
int PhWindowChange(
unsigned fields,
unsigned flags,
const PhRegion t *region,
const PhRect t *rect,
const PhWindowInfo t *win info );

Description:
This function allows you to modify the attributes and window
information of a window’s region. The Window Manager is notified
of this change and will respond accordingly.

☞ Don’t use this function in an application that uses widgets.

This function changes the definition of the window region specified

by region->rid. The fields argument describes which fields in the
region structure are to be used to effect the changes.
The rect argument points to the rectangle associated with the region,
and win info points to the window information that will replace the
current win info on the window region.
The flags argument controls whether or not an expose event will be
emitted to this region, when necessary. You can OR the following into
flags:

Ph EXPOSE REGION
If part of the region becomes exposed, send a Ph EV EXPOSE
event to the region.

Ph EXPOSE FAMILY
If part of the region becomes exposed, send a Ph EV EXPOSE
event to the region’s descendants.

492 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhWindowChange()

Returns:
0 Successful completion.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhWindowOpen(), PhRegionClose()
See PhWm.h for a description of PhWindowInfo t.

September 20, 2005 Chapter 6 ¯ Ph — Photon 493

PhWindowClose()  2005, QNX Software Systems
Close a window

Synopsis:
int PhWindowClose( PhRid t window rid );

Description:
This function closes a window with the given region ID, window rid,
previously opened by PhWindowOpen().

Returns:
0 Successful completion.

-1 An error occurred. Either a nonwindow RID was given, or the

function can’t communicate with Photon or the Window
Manager.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhWindowOpen()

494 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhWindowEvent t
Data structure describing a window action

Synopsis:
typedef struct Ph window event {
ulong t event f ;
ulong t state f ;
PhRid t rid;
PhPoint t pos;
PhDim t size;
ushort t event state;
ushort t input group;
ulong t rsvd[4];
} PhWindowEvent t;

Description:
Using the PhWindowEvent t structure, your application can
determine what kind of window action just occurred, or can tell the
window manager to perform a specific action on its behalf.
This structure contains at least the following members:

unsigned long event f

The type of the window event. The flags you can
set in this member are the same as those for
Pt ARG WINDOW MANAGED FLAGS and
Pt ARG WINDOW NOTIFY FLAGS resources of
the PtWindow widget (described in the Photon
Widget Reference):
¯ Ph WM CLOSE — the window is to be closed.
¯ Ph WM FOCUS — the window is to gain/lose
focus.
¯ Ph WM MENU — the window menu is
requested or dismissed.
¯ Ph WM TOFRONT — the window is to be
moved to the front.
¯ Ph WM TOBACK — the window is to be moved
to the back.

September 20, 2005 Chapter 6 ¯ Ph — Photon 495

PhWindowEvent t  2005, QNX Software Systems

¯ Ph WM CONSWITCH — the window is to

switch consoles.
¯ Ph WM RESIZE — the window is to be resized.

¯ Ph WM MOVE — the window is to be moved.

¯ Ph WM HIDE — the window is to be hidden or
unhidden.
¯ Ph WM MAX — the window is to be
maximized.
¯ Ph WM BACKDROP — the window is to be
made into a backdrop.
¯ Ph WM RESTORE — the window is to be
restored.
¯ Ph WM HELP — the help button is pressed.
¯ Ph WM FFRONT — the window is to be made
force-front or not force-front.
Some events can have two meanings; see the
description of the event state member.
unsigned long state f
The current state of the window:
¯ Ph WM STATE ISNORMAL — a normal
window.
¯ Ph WM STATE ISHIDDEN — window is
hidden.
¯ Ph WM STATE ISMAX — window is
maximized.
¯ Ph WM STATE ISICONIFIED — window is
iconified.
¯ Ph WM STATE ISTASKBAR — window is a
taskbar.
¯ Ph WM STATE ISBACKDROP — window
forms the workspace backdrop.

496 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhWindowEvent t

PhRid t rid The ID of the affected region.

short event state

Indicates that the Window Manager has completed
or been asked to complete the requested action. If
the event is emitted to the Window Manager, the
event is performed by the Window Manager. If an
application collects the event, the Window
Manager has completed the event.
The following operations have two event states;
you can OR one of these states into event state:
¯ Ph WM FFRONT — either
Ph WM EVSTATE FFRONT or
Ph WM EVSTATE FFRONT DISABLE.
¯ Ph WM FOCUS — either
Ph WM EVSTATE FOCUS or
Ph WM EVSTATE FOCUSLOST.
¯ Ph WM HIDE — either Ph WM EVSTATE HIDE
or Ph WM EVSTATE UNHIDE.
¯ Ph WM MENU — either
Ph WM EVSTATE MENU or
Ph WM EVSTATE MENU FINISH.
¯ All other toggle events — either
Ph WM EVSTATE PERFORM or
Ph WM EVSTATE INVERSE.

PhPoint t pos The position of the window. This member is valid

only for Ph WM BACKDROP, Ph WM MAX,
Ph WM MOVE, Ph WM RESIZE, and
Ph WM RESTORE events.

PhDim t size Indicates the width and height of the window. This
member is only for Ph WM BACKDROP,
Ph WM MAX, Ph WM RESIZE, and
Ph WM RESTORE events.

September 20, 2005 Chapter 6 ¯ Ph — Photon 497

PhWindowEvent t  2005, QNX Software Systems

ushort t input group

The input group associated with the event.

Classification:
Photon

See also:
PtForwardWindowEvent(), PtForwardWindowTaskEvent()
Window Management chapter of the Photon Programmer’s Guide.

498 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhWindowOpen()
Create a window region

Synopsis:
PhRid t PhWindowOpen(
unsigned fields,
const PhRegion t *region,
const PhRect t *rect,
const PhWindowInfo t *win info );

Description:
This function creates a window region that will be managed by the
Window Manager in the Photon event space. The Window Manager
will provide a region to act as a frame in addition to the region created
by the calling application.
The fields argument describes which members specified by region
will be used. If some fields aren’t specified, the function sets the
corresponding members of the new region to their default values.
The region argument is a template region used when opening the new
region. You must set the parent member of region; Photon fills in the
other family members.
The rect argument points to the rectangle associated with the region,
and win info points to a description of the window’s attributes, as
specified in the PhWindowInfo t structure (see PhWm.h).

Returns:
The region ID of the new window’s interior (not the RID of the
frame).
If an error occurred, this function returns:

-1 The function couldn’t communicate with Photon.

0 The region couldn’t be created (e.g. the system is out of

memory).

September 20, 2005 Chapter 6 ¯ Ph — Photon 499

PhWindowOpen()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhWindowChange(), PhRegionChange(), PhWindowClose(),
PhRegionOpen()
See PhWm.h for a description of PhWindowInfo t.

500 Chapter 6 ¯ Ph — Photon September 20, 2005

 2005, QNX Software Systems PhWindowQueryVisible()
Query a visible extent

Synopsis:
int PhWindowQueryVisible( unsigned flag,
PhRid t rid,
unsigned input group,
PhRect t *rect );

Description:
If rid is zero, this function calculates the visible extent based on the
region type specified in flag.
If rid is nonzero, PhWindowQueryVisible() calculates the visible
extent by finding every region intersecting with rid that matches the
region type specified in flag.
The input group argument indicates which input group the visible
extent must intersect with:

¯ If you have an event, use its input group field if it’s nonzero.
¯ If you don’t have an event, use the value of the PHIG environment
variable (if defined and nonzero).
¯ As a last resort, specify an input group of 1.

You must set flags to one of the following:

Ph QUERY GRAPHICS
Return a graphics driver rectangle.
Ph QUERY INPUT GROUP
Return input group’s rectangle.
Ph QUERY EXACT
The visible extent that the function finds must match both
input group and rid; otherwise, rid is a hint.
Ph QUERY IG POINTER
Use the current location of input group’s pointer (rid is
ignored).

September 20, 2005 Chapter 6 ¯ Ph — Photon 501

PhWindowQueryVisible()  2005, QNX Software Systems

Ph QUERY IG REGION
Use input group’s rectangle.

If flags is 0, Ph QUERY GRAPHICS is assumed.

PhWindowQueryVisible() places the visible extent in rect.

Returns:
0 The rect argument is valid.

-1 The rect argument is invalid.

Examples:
Determine the absolute coordinates of the current console:

PhRect t extent;

if( PhWindowQueryVisible( Ph QUERY GRAPHICS, 0,

input group, &extent ) == 0 ) {
printf( "Upper left: (%d,%d) Lower right: (%d,%d)\n",
extent.ul.x, extent.ul.y,
extent.lr.x, extent.lr.y );
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

502 Chapter 6 ¯ Ph — Photon September 20, 2005

 Chapter 7
Pm — Memory

September 20, 2005 Chapter 7 ¯ Pm — Memory 503

 2005, QNX Software Systems

The functions described in this chapter support memory contexts.

September 20, 2005 Chapter 7 ¯ Pm — Memory 505

PmMemCreateMC()  2005, QNX Software Systems
Create a memory context

Synopsis:
PmMemoryContext t * PmMemCreateMC(
PhImage t *mc image,
PhDim t *dim,
PhPoint t *translation );

Description:
This function creates a memory context. A memory context is used to
draw into a local memory image buffer. You must create a memory
context before calling any other Photon Memory (Pm) functions. The
memory context provides definition, control, and access to the
memory image.
The parameters for this function are:

mc image The resulting image’s type and dimensions. For more

information, see below.

dim The source size of the draw stream. If the image

dimension is different from the source dimension, any
drawing done to the memory context will be scaled as
necessary to fit the source dimension exactly into the
image dimension.

translation The amount the draw stream will be translated when

being rendered into the memory image buffer.

If the image member of the PhImage t structure pointed to by

mc image (i.e. mc image->image) is NULL, PmMemCreateMC() uses
calloc() to allocate its own buffer. In this case, PmMemReleaseMC()
frees the allocated image buffer.
If mc image->image isn’t NULL, PmMemCreateMC() uses it instead
of allocating its own buffer. The size of the buffer depends on the type
and dimensions specified for mc image. In this case,
PmMemReleaseMC() doesn’t free the buffer.

506 Chapter 7 ¯ Pm — Memory September 20, 2005

 2005, QNX Software Systems PmMemCreateMC()

☞ If you want the image to be in shared memory, allocate the shared

space for the image data, instead of letting PmMemCreateMC() do it.

The mc image->type member indicates the type of image that’s

generated. The type must be one of:

¯ Pg IMAGE DIRECT 888

¯ Pg IMAGE PALETTE BYTE

If the type member is Pg IMAGE PALETTE BYTE or

Pg IMAGE PALETTE NIBBLE, the palette member is used to define
the palette. If the palette member is NULL, the default palette is used.
The image member of the PhImage t structure filled in by
PmMemFlush() is a pointer to the mc image->image buffer.

Returns:
A pointer to the new memory context, or NULL if there isn’t enough
memory to allocate one.

Examples:
/* pmmemtobutton.c

This demonstrates how to draw into an image. This example

uses the PmMem*() functions to draw into a memory context.
When finished drawing, the memory context is then dumped
into an image. The image is then used as the image
displayed on a button.

To compile, you must link with phrender s.lib. For example:

cc -w3 -opmmemtobutton -lphrender s -lphoton s pmmemtobutton.c

*/

#include <mem.h>
#include <photon/PhRender.h>
#include <Pt.h>

main( int argc, char *argv[] )

{
PhArea t area = { 80, 20, 80, 40 };

September 20, 2005 Chapter 7 ¯ Pm — Memory 507

PmMemCreateMC()  2005, QNX Software Systems

PhDim t dim = { 240, 80 };

PhImage t image;
PtArg t arg[3];
PtWidget t *button, *window;
short bytes per pixel = 3;

PtSetArg( &arg[0], Pt ARG WINDOW TITLE,

"Memory Context Sample", 0 );
PtSetArg( &arg[1], Pt ARG DIM, &dim, 0 );
window = PtAppInit( NULL, &argc, argv, 2, arg );

memset( image, 0, sizeof(PhImage t) );

image->type = Pg IMAGE DIRECT 888; // 3 bytes per pixel
// with this type

// If we want the image to be in shared memory, we must allocate

// the shared space for the image data, instead of letting
// PmMemCreateMC() do it.

image->size = *dim;
image->image = PgShmemCreate(
dim->w * dim->h * bytes per pixel,
NULL );

create image( &image, &area.size );

PtSetArg( &arg[0], Pt ARG LABEL TYPE, Pt IMAGE, 0 );

PtSetArg( &arg[1], Pt ARG AREA, &area, 0 );
PtSetArg( &arg[2], Pt ARG LABEL IMAGE, &image, 0 );
button = PtCreateWidget( PtButton, NULL, 3, arg );

PtRealizeWidget( window );
PtMainLoop();

// Shared memory for the image is cleaned up by an

// internal function that’s called when the program
// exits.
}

void
create image( PhImage t *image, PhDim t *dim )
{
PhPoint t translation = { 0, 0 }, center, radii;
PmMemoryContext t *mc;

mc = PmMemCreateMC( image, dim, &translation );

PmMemStart( mc );
// now all drawing goes into the memory context

508 Chapter 7 ¯ Pm — Memory September 20, 2005

 2005, QNX Software Systems PmMemCreateMC()

// draw whatever we want to appear in the image

center.x = dim->w / 2;
center.y = dim->h / 2;
radii = center;
PgSetFillColor( Pg WHITE );
PgSetStrokeColor( Pg RED );
PgDrawEllipse( &center, &radii, Pg DRAW FILL STROKE );
PgSetStrokeColor( Pg GREEN );
PgDrawILine( 0, 0, dim->w-1, dim->h-1 );

PmMemFlush( mc, image ); // get the image

PmMemStop( mc );
// now all drawing goes to the default drawing context

PmMemReleaseMC( mc );
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgShmemCreate(), PgShmemDestroy(), PhImage t, PmMemFlush(),
PmMemReleaseMC()
“Flickerless animation” in the Raw Drawing and Animation chapter
of the Photon Programmer’s Guide

September 20, 2005 Chapter 7 ¯ Pm — Memory 509

PmMemFlush()  2005, QNX Software Systems
Flush a memory context to its bitmap

Synopsis:
int PmMemFlush( PmMemoryContext t *mc,
PhImage t *image );

Description:
This function forces any unprocessed draw-stream commands to be
processed. Then, the PhImage t structure pointed to by image is
filled in with information from the memory image. The image can
then be rendered via any of the PgDrawImage*() or
PgDrawPhImagemx() functions.

Returns:
0 Success.

-1 An invalid memory context was provided.

Examples:
See PmMemCreateMC().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

510 Chapter 7 ¯ Pm — Memory September 20, 2005

 2005, QNX Software Systems PmMemFlush()

See also:
PhImage t
“Flickerless animation” in the Raw Drawing and Animation chapter
of the Photon Programmer’s Guide

September 20, 2005 Chapter 7 ¯ Pm — Memory 511

PmMemReleaseMC()  2005, QNX Software Systems
Release a memory context

Synopsis:
void PmMemReleaseMC( PmMemoryContext t *mc );

Description:
This function releases the draw context, and shuts down and frees any
resources created by the provided memory context.

☞ This function doesn’t release the image buffer if PmMemCreateMC()

didn’t create it.

If the provided memory context is active at the time of this call, the
default draw context automatically becomes the current draw context.

Examples:
See PmMemCreateMC().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PmMemCreateMC()
“Flickerless animation” in the Raw Drawing and Animation chapter
of the Photon Programmer’s Guide

512 Chapter 7 ¯ Pm — Memory September 20, 2005

 2005, QNX Software Systems PmMemSetChunkSize()
Set the increment for growing a memory context’s draw buffer

Synopsis:
void PmMemSetChunkSize( PmMemoryContext t *mc,
int size );

Description:
This function sets the increment to be used when growing the
memory context’s draw buffer.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PmMemCreateMC(), PmMemReleaseMC(), PmMemSetMaxBufSize(),
PmMemSetType()
“Flickerless animation” in the Raw Drawing and Animation chapter
of the Photon Programmer’s Guide

September 20, 2005 Chapter 7 ¯ Pm — Memory 513

PmMemSetMaxBufSize()  2005, QNX Software Systems
Set the maximum size of a memory context’s draw buffer

Synopsis:
void PmMemSetMaxBufSize( PmMemoryContext t *mc,
int size );

Description:
This function sets the maximum size that the memory context’s draw
buffer will grow to. The larger the buffer, the less often a flush will be
required, and the faster the application will be. The default size of the
draw buffer is 4K.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PmMemCreateMC(), PmMemReleaseMC(), PmMemSetChunkSize(),
PmMemSetType()
“Flickerless animation” in the Raw Drawing and Animation chapter
of the Photon Programmer’s Guide

514 Chapter 7 ¯ Pm — Memory September 20, 2005

 2005, QNX Software Systems PmMemSetType()
Set the type of a memory context

Synopsis:
void PmMemSetType( PmMemoryContext t *mc,
int type );

Description:
This function sets the type of the memory context pointed to by mc.
The valid types are:

Pm PHS CONTEXT
Renders the draw buffer to image only when necessary (i.e.
when the draw buffer is full, or PmMemFlush() is explicitly
called). Otherwise, the only effect a flush has is to expand the
draw buffer when necessary.

Pm IMAGE CONTEXT
The draw stream is rendered to the image on every flush.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PmMemCreateMC(), PmMemReleaseMC(), PmMemSetChunkSize(),
PmMemSetMaxBufSize()
“Flickerless animation” in the Raw Drawing and Animation chapter
of the Photon Programmer’s Guide

September 20, 2005 Chapter 7 ¯ Pm — Memory 515

PmMemStart()  2005, QNX Software Systems
Make a memory context active

Synopsis:
PhDrawContext t * PmMemStart(
PmMemoryContext t *mc );

Description:
This function makes the provided memory context mc active. That is,
from this point until the memory context is deactivated, everything
drawn becomes part of the memory image.
All subsequent Photon draw commands are routed through this
memory context until:

¯ the memory context is made inactive by a call to PmMemStop() or

PmMemReleaseMC()
Or

¯ a different memory, print, or draw context is made active. In this

case, the memory context is automatically deactivated as if
PmMemStop() had been called

Returns:
A pointer to the previously active draw context, or NULL if the
provided context couldn’t be made active — see errno for details.

Errors:
ENOMEM There wasn’t enough memory for the context’s work
buffers.

Examples:
See PmMemCreateMC().

516 Chapter 7 ¯ Pm — Memory September 20, 2005

 2005, QNX Software Systems PmMemStart()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PmMemCreateMC(), PmMemReleaseMC(), PmMemStop()
“Flickerless animation” in the Raw Drawing and Animation chapter
of the Photon Programmer’s Guide

September 20, 2005 Chapter 7 ¯ Pm — Memory 517

PmMemStop()  2005, QNX Software Systems
Deactivate a memory context

Synopsis:
PhDrawContext t * PmMemStop(
PmMemoryContext t *mc );

Description:
This function deactivates the memory context mc, if it’s active,
making the default draw context active. This means that draw
commands are sent to Photon (i.e. draws will no longer be affecting
the memory image).

Returns:
The mc argument if the memory context was successfully deactivated,
or NULL if it wasn’t active at the time of this call.

Examples:
See PmMemCreateMC().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PmMemCreateMC(), PmMemReleaseMC(), PmMemStart()
“Flickerless animation” in the Raw Drawing and Animation chapter
of the Photon Programmer’s Guide

518 Chapter 7 ¯ Pm — Memory September 20, 2005

 Chapter 8
Pp — Printing

September 20, 2005 Chapter 8 ¯ Pp — Printing 519

 2005, QNX Software Systems

This chapter describes the functions that Photon provides to support a

wide range of printing needs.

September 20, 2005 Chapter 8 ¯ Pp — Printing 521

PpLoadPrinter()  2005, QNX Software Systems
Initialize a print context with information for a given printer

Synopsis:
int PpLoadPrinter( PpPrintContext t *pc,
char const *name );

Description:
This function initializes the provided print context with the printer file
information for the printer section named name. If name isn’t
provided, this function loads the attributes of the default printer as
specified in the printer files. The files used by this function are:

¯ $HOME/.photon/print/config

¯ $PHOTON PATH/print/printers

The value of PHOTON PATH depends on your installation:

/usr/photon
Before Photon 1.13.
/qnx4/photon
Photon 1.13 or later.

Returns:
0 Success.

-1 No name was specified and no default printer could be found,

or the printer definition loaded didn’t define a destination
device or filename, so no output can be generated.

Examples:
PpPrintContext t *pc = PpPrintCreatePC();
PpLoadPrinter( pc, "PostScript Printer");
PpPrintOpen( pc );

PpPrintStart( pc );

// Draw stuff

522 Chapter 8 ¯ Pp — Printing September 20, 2005

 2005, QNX Software Systems PpLoadPrinter()

PpPrintStop( pc );
PpPrintClose( pc );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 8 ¯ Pp — Printing 523

PpPrintClose()  2005, QNX Software Systems
Close a print context

Synopsis:
int PpPrintClose( PpPrintContext t *pc );

Description:
This function completes the current print job for the provided print
context, pc. If the print context is active, it’s deactivated as if
PpPrintStop() had been called.

☞ The print context is deactivated, but isn’t destroyed, so it can be used

for future print jobs with little or no reconfiguration.

When this function returns, the printed output has been generated and
sent to the destination specified in the print context.

Returns:
0 Success.

-1 The print context couldn’t be made active, probably because

the required print driver couldn’t be launched. See errno for
the specific error.

Examples:
See PpPrintStart().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

524 Chapter 8 ¯ Pp — Printing September 20, 2005

 2005, QNX Software Systems PpPrintClose()

See also:
PpPrintCreatePC(), PpPrintGetPC(), PpPrintNewPage(),
PpPrintOpen(), PpPrintReleasePC(), PpPrintSetPC(),
PpPrintStart(), PpPrintStop(), PpPrintWidget()

September 20, 2005 Chapter 8 ¯ Pp — Printing 525

PpPrintCreatePC()  2005, QNX Software Systems
Create a print context

Synopsis:
PpPrintContext t *PpPrintCreatePC( void );

Description:
This function creates a print context. You must create a print context
before calling any other Photon Print (Pp) functions.
The print context describes all aspects of a print job required by the
printing functions and the print drivers: Pp.pcl, Pp.ps, Pp.epc2,
and so on.

Returns:
A pointer to the new print context, or NULL if there isn’t enough
memory to allocate one.

Examples:
See PpPrintStart().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PpPrintClose(), PpPrintGetPC(), PpPrintNewPage(), PpPrintOpen(),
PpPrintReleasePC(), PpPrintSetPC(), PpPrintStart(), PpPrintStop(),
PpPrintWidget(), PtPrintSelection()

526 Chapter 8 ¯ Pp — Printing September 20, 2005

 2005, QNX Software Systems PpPrintCreatePC()

Printing chapter of the Programmer’s Guide

September 20, 2005 Chapter 8 ¯ Pp — Printing 527

PpPrintGetPC()  2005, QNX Software Systems
Extract data from a print context

Synopsis:
void * PpPrintGetPC( PpPrintContext t *pc,
int member,
const void ** const data);

Description:
Use this function to query the attributes of a print context.

☞ Don’t extract values directly from the data structure. Your application
might not work if the structure changes in the future.

The arguments are as follows:

pc The print context, created by PpPrintCreatePC().

data the address of a pointer to the data type of the member

being queried. This pointer will be set to point to the
member within the print context structure. Don’t use it
to modify the print context; use only PpPrintSetPC().

member The member of the print context to query, as given in the

table below. (For a description of the members, see the
chapter on Printing in the Programmer’s Guide.)

Member Data
Pp PC NAME address of a char * (string)
Pp PC LOCATION address of a char * (string)
Pp PC DEVICE address of a char * (string)
Pp PC DRIVER address of a char * (string)
Pp PC NONPRINT MARGINS address of a PhRect t *

continued. . .

528 Chapter 8 ¯ Pp — Printing September 20, 2005

 2005, QNX Software Systems PpPrintGetPC()

Member Data
Pp PC PROP APP address of a char * (string)
Pp PC PREVIEW APP address of a char * (string)
Pp PC FILENAME address of a char * (string)
Pp PC COMMENT address of a char * (string)
Pp PC DATE address of a char * (string)
Pp PC USER ID address of a char * (string)
Pp PC PAGE RANGE address of a char * (string)
Pp PC SOURCE OFFSET address of a PhPoint t *
Pp PC SOURCE SIZE address of a PhDim t *
Pp PC SOURCE RESOLUTION address of a PhDim t *
Pp PC SOURCE COLORS address of a ulong t *
Pp PC SCALE address of a PhPoint t *
Pp PC MARGINS address of a PhRect t *
Pp PC INTENSITY address of a ulong t *
Pp PC PRINTER RESOLUTION address of a PhDim t *
Pp PC PAPER SIZE address of a PhDim t *
Pp PC COLLATING MODE address of a char * ( value )
Pp PC DITHERING address of a char * ( value )
Pp PC COPIES address of a char * ( value )
Pp PC ORIENTATION address of a char * ( value )
Pp PC DUPLEX address of a char * ( value )
Pp PC PAPER TYPE address of a char * ( value )
Pp PC PAPER SOURCE address of a char * ( value )

continued. . .

September 20, 2005 Chapter 8 ¯ Pp — Printing 529

PpPrintGetPC()  2005, QNX Software Systems

Member Data
Pp PC INKTYPE address of a char * ( value )
Pp PC COLOR MODE address of a char * ( value )
Pp PC DO PREVIEW address of a char * ( value )
Pp PC JOB NAME address of a char * (string)
Pp PC CONTROL address of a PpPCControl t *

Returns:
A pointer to the requested data, or NULL if an unrecognized member
was specified.

Examples:
int get it( PtWidget t *widget, ApInfo t *apinfo,
PtCallbackInfo t *cbinfo )

PhDim t *dim;
void *pc data;
PpPrintContext t *pc;

/* Eliminate ’unreferenced’ warnings */

widget = widget, apinfo = apinfo, cbinfo = cbinfo;

pc = PpPrintCreatePC();

// Pop up the standard print dialog to fill in the PC

PtPrintSelection( NULL, NULL,
"Select Printer", pc, 0 );

// Get some stuff from the pc

// A string:
PpPrintGetPC( pc, Pp PC NAME, &pc data );
printf( "printer: %s\n", (char *)pc data );

// A structure ( PhDim t ):
PpPrintGetPC( pc, Pp PC PAPER SIZE, &pc data );
printf( "paper height: %d, width: %d\n",
((PhDim t *)pc data)->h, ((PhDim t *)pc data)->w );

530 Chapter 8 ¯ Pp — Printing September 20, 2005

 2005, QNX Software Systems PpPrintGetPC()

// A long value:
PpPrintGetPC( pc, Pp PC INTENSITY, &pc data );
printf( "intensity: %ld\n", *(long *)pc data );

// A number stored in a char:

PpPrintGetPC( pc, Pp PC COPIES, &pc data );
printf( "copies : %d\n", *(char *)pc data );

// Of course, the correct type can be used to

// get the member:
PpPrintGetPC( pc, Pp PC PAPER SIZE, &dim );
printf( "paper height: %d, width: %d\n", dim->h, dim->w );

PpPrintReleasePC( pc );

return Pt CONTINUE;
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PpPrintClose(), PpPrintCreatePC(), PpPrintGetPC(),
PpPrintNewPage(), PpPrintReleasePC(), PpPrintSetPC(),
PpPrintStart(), PpPrintStop(), PpPrintWidget()

September 20, 2005 Chapter 8 ¯ Pp — Printing 531

PpPrintNewPage()  2005, QNX Software Systems
Place a page break in the draw stream for a Print Context

Synopsis:
int PpPrintNewPage( PpPrintContext t *pc );

Description:
This function places a New Page command in the draw stream for the
specified print context, pc, followed by all the changes made to the
print context since PpPrintNewPage() was called or the print context
was opened (initialized).
If the print context isn’t currently active, PpPrintStart() is called
before the New Page command is inserted. The draw context that was
active when the call was made is restored before PpPrintNewPage()
returns.

Returns:
0 Success.

-1 The print context couldn’t be made active, probably because

the required working files couldn’t be created. See errno for
the specific error.

Examples:
See PpPrintStart().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

532 Chapter 8 ¯ Pp — Printing September 20, 2005

 2005, QNX Software Systems PpPrintNewPage()

See also:
PpPrintClose(), PpPrintCreatePC(), PpPrintGetPC(),
PpPrintOpen(), PpPrintReleasePC(), PpPrintSetPC(),
PpPrintStart(), PpPrintStop(), PpPrintWidget()

September 20, 2005 Chapter 8 ¯ Pp — Printing 533

PpPrintOpen()  2005, QNX Software Systems
Initialize the current print job

Synopsis:
int PpPrintOpen( PpPrintContext t *pc );

Description:
This function initializes the current print job. This includes opening
the destination device or file and writing out the print-start command
and any modified portions of the print context.
The pc argument is a pointer to the print context for the print job. This
must have been created by PpPrintCreatePC(), and may have been
configured by calls to PpPrintSetPC(), or by the PtPrintSel widget.
You normally call this function after setting up the print context with
PpPrintSetPC() and/or the PtPrintSelection() convenience function.
If the Pp PC DEVICE or Pp PC FILENAME member of the print
context isn’t specified, the printer in Pp PC NAME is used to
determine the print destination. If Pp PC NAME isn’t specified either,
the default printer definition is used. If a print destination still isn’t set
in the print context, PpPrintOpen() fails and errno is set to ESRCH.

☞ Photon draw operations won’t be routed through the print context

until you call PpPrintStart().

Returns:
0 Success.

-1 The print context couldn’t be made active, probably because

the required working files couldn’t be created. See errno for
the specific error.

Errors:
ESRCH No output target is specified in the print context and no
printer definition could be found

534 Chapter 8 ¯ Pp — Printing September 20, 2005

 2005, QNX Software Systems PpPrintOpen()

Examples:
See PpPrintStart().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PpPrintClose(), PpPrintCreatePC(), PpPrintGetPC(),
PpPrintNewPage(), PpPrintReleasePC(), PpPrintSetPC(),
PpPrintStart(), PpPrintStop(), PpPrintWidget()

September 20, 2005 Chapter 8 ¯ Pp — Printing 535

PpPrintReleasePC()  2005, QNX Software Systems
Release a print context

Synopsis:
void PpPrintReleasePC( PpPrintContext t *pc );

Description:
This function releases the draw context, shuts down, and frees the
resources used by the provided print context.
If the provided print context’s draw context is the current draw
context, the default draw context automatically becomes the current
draw context.

Examples:
See PpPrintStart().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PpPrintClose(), PpPrintCreatePC(), PpPrintGetPC(),
PpPrintNewPage(), PpPrintOpen(), PpPrintSetPC(), PpPrintStart(),
PpPrintStop(), PpPrintWidget()

536 Chapter 8 ¯ Pp — Printing September 20, 2005

 2005, QNX Software Systems PpPrintSetPC()
Modify the attributes of a print context

Synopsis:
int PpPrintSetPC( PpPrintContext t *pc,
int mod level,
int lock,
int member,
void const * const data);

Description:
This function provides a mechanism to modify the attributes of a print
context.

☞ Don’t modify the print context directly, as the appropriate changed

bits won’t be set and the application may stop working if the print
context structure is redefined in future.

The arguments are as follows:

pc The print context, created by PpPrintCreatePC()

mod level A value indicating the modifier of the context. The

possible values are:
¯ PRINTER GLOBAL — modified based on
information in the global printer file
(/usr/photon/print/printers)
¯ PRINTER LOCAL — modified based on info in the
local printer file
($HOME/.photon/print/config)
¯ INITIAL PC — modified directly by the
application.
¯ INTERACTIVE PC — modified based on user input.

Interactive overrides initial, which overrides local,

which overrides global.

September 20, 2005 Chapter 8 ¯ Pp — Printing 537

PpPrintSetPC()  2005, QNX Software Systems

The PtPrintSel widget reads the Photon printer files

and modifies the provided print context with the
definitions within those files. The mod level used for
the changes on the print context are dictated by which
file the definitions are read from:
¯ Modifications made to the print context based on
information in the global printer definition file,
/usr/photon/print/printers, are done with
a modification level of PRINTER GLOBAL.
¯ Modifications made to the print context based on
information in the local print file,
$HOME/.photon/print/printers, are done
with a modification level of PRINTER LOCAL.
¯ When the user interacts with the widget in order to
change the print settings, and therefore the print
context, the modifications are made with a
mod level of INTERACTIVE PC.
¯ When setting defaults on a print context before
launching a print dialog via PtPrintSelection() or
using the PtPrintSel widget, you’d normally use
a modification level of INITIAL PC. This level
prevents the contents of the printer definition files
from overriding your default, but still allows the
user to modify those print settings interactively in
the widget.
If you want to prevent the user from modifying
members of the print context you have set, specify a 1
in the lock field when calling PpPrintSetPC().
lock If nonzero, the PtPrintSel widget and properties
applications won’t override or allow modification of
the member. Its value is locked. Locked members have
their controls dimmed and inactive in the
PtPrintSel widget or PtPrintSelection() dialog.

data A pointer to the data to be assigned to the specified

print context member.

538 Chapter 8 ¯ Pp — Printing September 20, 2005

 2005, QNX Software Systems PpPrintSetPC()

member The member of the print context to modify, as given in

the table below. (For a description of the members, see
the chapter on Printing in the Programmer’s Guide.)

☞ In the following table:

¯ “String” indicates a char * pointer to a null-terminated sequence

of characters

¯ “char *” indicates a char * pointer to a value in the range 0x0 to

0xFF

Member Data
Pp PC NAME String
Pp PC LOCATION String
Pp PC DEVICE String
Pp PC DRIVER String
Pp PC NONPRINT MARGINS PhRect t *
Pp PC PROP APP String
Pp PC PREVIEW APP String
Pp PC FILENAME String
Pp PC COMMENT String
Pp PC DATE String
Pp PC USER ID String
Pp PC PAGE RANGE String
Pp PC SOURCE OFFSET PhPoint t *
Pp PC SOURCE SIZE PhDim t *

continued. . .

September 20, 2005 Chapter 8 ¯ Pp — Printing 539

PpPrintSetPC()  2005, QNX Software Systems

Member Data
Pp PC SOURCE RESOLUTION PhPoint t *
Pp PC SOURCE COLORS int *
Pp PC SCALE PhPoint t *
Pp PC MARGINS PhRect t *
Pp PC INTENSITY int *
Pp PC PRINTER RESOLUTION PhPoint t *
Pp PC PAPER SIZE PhDim t *
Pp PC COLLATING MODE char *
Pp PC DITHERING char *
Pp PC COPIES char *
Pp PC ORIENTATION char *
Pp PC DUPLEX char *
Pp PC PAPER TYPE char *
Pp PC PAPER SOURCE char *
Pp PC INKTYPE char *
Pp PC COLOR MODE char *
Pp PC DO PREVIEW char *
Pp PC JOB NAME String
Pp PC CONTROL Read only: see PpPrintGetPC()

By default, all members are 0 or NULL.

Returns:
0 Success.

-1 An error occurred. See errno for details.

540 Chapter 8 ¯ Pp — Printing September 20, 2005

 2005, QNX Software Systems PpPrintSetPC()

Errors:
EPERM The specified member was set by a modification level
that supersedes mod level:

INTERACTIVE PC supersedes
INITIAL PC, which supersedes
PRINTER LOCAL, which supersedes
PRINTER GLOBAL

For example,

PpPrintSetPC( pc, PRINTER GLOBAL, 0,

Pp PC COLLATING MODE,
PaperCollateABCABCABC );
// succeeds as it’s the first setting

PpPrintSetPC( pc, PRINTER LOCAL, 0,

Pp PC COLLATING MODE,
PaperCollateAAABBBCCC );
// succeeds because PRINTER LOCAL supersedes PRINTER GLOBAL

PpPrintSetPC( pc, PRINTER LOCAL, 0,

Pp PC COLLATING MODE,
PaperCollateABCABCABC );
// succeeds because changes at the same mod level
// are permitted. PRINTER LOCAL == PRINTER LOCAL

PpPrintSetPC( pc, PRINTER GLOBAL, 0,

Pp PC COLLATING MODE,
PaperCollateAAABBBCCC );
// fails with errno == EPERM because changes by
// a lower mod level are NOT permitted.
// PRINTER GLOBAL < PRINTER LOCAL

EACCES The specified member couldn’t be changed because it’s

locked.

ESRCH An unknown member was specified.

September 20, 2005 Chapter 8 ¯ Pp — Printing 541

PpPrintSetPC()  2005, QNX Software Systems

Examples:
set my apps Pp prefs( PpPrintContext t *pc )
{
char do preview = 1, duplex = some value;
PpPrintSetPC( pc, INITIAL PC, 0,
Pp PC DO PREVIEW, &do preview );
PpPrintSetPC( pc, INITIAL PC, 0,
Pp PC DUPLEX, &duplex );
PpPrintSetPC( pc, INITIAL PC, 0,
Pp PC COMMENT,
"Hey, this is a comment!" );
// etc...
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PpPrintClose(), PpPrintCreatePC(), PpPrintGetPC(),
PpPrintNewPage(), PpPrintOpen(), PpPrintReleasePC(),
PpPrintStart(), PpPrintStop(), PpPrintWidget()
Printing in the Programmer’s Guide

542 Chapter 8 ¯ Pp — Printing September 20, 2005

 2005, QNX Software Systems PpPrintStart()
Activate a print context

Synopsis:
PhDrawContext t *PpPrintStart(
PpPrintContext t *pc );

Description:
This function makes the provided print context pc active (i.e. from
this point until the print context is deactivated, everything drawn is
part of the printed output). The print context is initialized if this hasn’t
already been done by a call to PpPrintOpen().
All subsequent Photon draw commands are routed through this print
context until:

¯ the print context is made inactive by a call to PpPrintStop() or

PpPrintClose()
Or

¯ a different memory or print context is made active. In this case, the

print context is automatically deactivated as if PpPrintStop() had
been called.

You can print widgets by damaging them and then calling PtFlush().

☞ A widget that’s damaged while a print context is active isn’t clipped

by its parent; if you want the widget to be clipped, damage the parent
instead.

Returns:
A pointer to the previously active draw context, or NULL if the print
context couldn’t be made active — see errno for the specific error.

Errors:
ESRCH No output target is specified in the print context and no
printer definition could be found

September 20, 2005 Chapter 8 ¯ Pp — Printing 543

PpPrintStart()  2005, QNX Software Systems

Examples:
To print the contents of a scroll area:

int print it( PtWidget t *widget, void *data,

PtCallbackInfo t *cbinfo )
{
PhDim t dim;

...

pc = PpPrintCreatePC();

// Set the default printer for this app only.

// This overrides the default printer set via
// the "prsetup" utility
PpPrintSetPC( pc, INITIAL PC, 0, Pp PC NAME, "R&D" );

// Pop up the standard print dialog and respond accordingly.

switch( PtPrintSelection( ABW base, &pos, "Select Printer",
pc, 0 ) )
{

// The user has selected print or preview -- PpPrintClose()

// handles the difference.

case Pt PRINTSEL PRINT:

case Pt PRINTSEL PREVIEW:
PtFlush(); // Ensure no draws are pending.

// Set the source size to be the size of the scroll

// area’s canvas. The contents of the canvas will
// be scaled to fit the page.
PtWidgetDim( PtValidParent( ABW my scrollarea ),
&dim );
PpPrintSetPC( pc, INITIAL PC, 0, Pp PC SOURCE SIZE,
&dim );
PpPrintOpen( pc );
if( PpPrintStart( pc ) )
{
// Force the canvas of the ScrollArea widget
// to draw.
PtDamageWidget(
PtValidParent( ABW my scrollarea ) );
PtFlush();
}

// Deactivate the pc and produce the printed output.

PpPrintClose( pc );

544 Chapter 8 ¯ Pp — Printing September 20, 2005

 2005, QNX Software Systems PpPrintStart()

case Pt PRINTSEL CANCEL:

break;
}

// Release the pc and its resources.

PpPrintReleasePC( pc );

return Pt CONTINUE;
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PpPrintClose(), PpPrintCreatePC(), PpPrintGetPC(),
PpPrintNewPage(), PpPrintOpen(), PpPrintReleasePC(),
PpPrintSetPC(), PpPrintStop(), PpPrintWidget()

September 20, 2005 Chapter 8 ¯ Pp — Printing 545

PpPrintStop()  2005, QNX Software Systems
Deactivate a print context

Synopsis:
void PpPrintStop( PpPrintContext t *pc );

Description:
This function deactivates the print context pc, if it’s active, making the
default draw context active. This means that draw commands are sent
to Photon (i.e. printing is turned off).

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PpPrintClose(), PpPrintCreatePC(), PpPrintGetPC(),
PpPrintNewPage(), PpPrintOpen(), PpPrintReleasePC(),
PpPrintSetPC(), PpPrintStart(), PpPrintWidget()

546 Chapter 8 ¯ Pp — Printing September 20, 2005

 2005, QNX Software Systems PpPrintWidget()
Print a widget

Synopsis:
void PpPrintWidget( PpPrintContext t *pc,
PtWidget t *widget,
PhPoint t const *trans,
PhRect t const *clip rect,
ulong t opt );

Description:
This function prints the specified widget using the provided print
context. The arguments are:

pc A print context obtained via PpPrintCreatePC() and

initialized via PpPrintSetPC() and PpPrintOpen().

widget The widget to be printed. This widget doesn’t need to

be realized to be printed and won’t be clipped by its
parent while printing.

trans If non-NULL, the amount to translate the widget by

when drawing it into the print context. Passing a trans
equal to the position of the widget makes the widget
print at 0,0 on the printed output.

clip rect If non-NULL, the rectangle to be clipped to.

This isn’t implemented yet; set clip rect to NULL.

☞
opt A value that indicates any special resizing to be done:
¯ Pt PP RESIZE PC — set the source size of the print
context to be the size of the widget. The widget is
scaled to fit the page.
¯ Pt PP RESIZE WIDGET — set the dimension of the
widget to match the drawable area of the destination
page. The widget is resized to fit the page, as
opposed to being scaled to fit the page.

September 20, 2005 Chapter 8 ¯ Pp — Printing 547

PpPrintWidget()  2005, QNX Software Systems

¯ Pt PP NO RESIZE — Don’t modify the source size of

the print context or the widget’s dimensions. It’s
important to set the source size of the print context
before calling PpPrintWidget() with this option.

☞ Be sure to call PtFlush() after calling PpPrintWidget().

Examples:
#include <Ph.h>
#include <Pt.h>

main()
{
int n;
PhArea t area, sev area = {0,0,400,400};
PpPrintContext t *pc;

PtInit( NULL );
pc = PpPrintCreatePC();
PpPrintOpen( pc );

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

PtRealizeWidget(
PtCreateWidget( PtWindow, NULL, 1, args ) );

n = 0;
PtSetArg( &args[n++], Pt ARG AREA, &sev area, 0 );
PtSetArg( &args[n++], Pt ARG FILL COLOR, Pg BLUE, 0);
button = PtCreateWidget( PtButton, NULL, n, args );
PpPrintStart( pc );
PtWidgetArea( button, &area);
PpPrintWidget( pc, button,
&area.pos,
NULL,
Pt PP RESIZE PC );
PtFlush();
PpPrintStop( pc );

PtMainLoop();
}

548 Chapter 8 ¯ Pp — Printing September 20, 2005

 2005, QNX Software Systems PpPrintWidget()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PpPrintClose(), PpPrintCreatePC(), PpPrintGetPC(),
PpPrintNewPage(), PpPrintOpen(), PpPrintReleasePC(),
PpPrintSetPC(), PpPrintStart(), PpPrintStop()
Printing in the Programmer’s Guide

September 20, 2005 Chapter 8 ¯ Pp — Printing 549

 Chapter 9
Pt — Widget Toolkit

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 551

 2005, QNX Software Systems

The widget toolkit functions let you create or destroy widgets, or

manipulate widgets and the relationships between them. These
functions gather detailed information about widgets and their
environment.

☞ For widget extension functions (which extend the attributes of a

widget beyond its resources) and convenience functions (which
simplify control over certain widget resources), see the Widget
Reference
.

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 553

PtAddCallback()  2005, QNX Software Systems
Add a single callback entry to a callback list

Synopsis:
void PtAddCallback( PtWidget t *widget,
unsigned long callback type,
PtCallbackF t *callback,
void *data );

Description:
This function adds a callback to the callback list indicated by
callback type (e.g. Pt CB ACTIVATE).

☞ Some types of callback resources have special routines that you

should use instead of this one:

Pt CB HOTKEY
PtAddHotkeyHandler()

Pt CB RAW PtAddEventHandler() or PtAddEventHandlers()

The callback argument points to a function that takes this form:

int (*callback)(PtWidget t *, void *, PtCallbackInfo t *)

Examples:
activated( PtWidget t *widget, void *data,
PtCallbackInfo t *info)
{
//suppress compiler warnings concerning unused arguments.
widget = widget, data = data, info = info;

exit( 0 );
}

main()
{
PtArg t argt;
PtWidget t *window, *widget;

554 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAddCallback()

window = PtAppInit( NULL, NULL, NULL, 0, NULL );

PtSetArg( &argt, Pt ARG TEXT STRING,
"Press Me To Quit", 0 );
button = PtCreateWidget( PtButton, NULL, 1, &args );

//add an activate callback to the button.

PtAddCallback( button, Pt CB ACTIVATE,
activated, NULL );

PtRealizeWidget( window );
PtMainLoop();
//unnecessary
PtRemoveCallback( button, Pt CB ACTIVATE,
activated, NULL );
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtAddCallbacks(), PtAddEventHandler(), PtAddEventHandlers(),
PtAddHotkeyHandler(), PtRemoveCallback(), PtRemoveCallbacks()
Creating Widgets in Application Code chapter of the Photon
Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 555

PtAddCallbacks()  2005, QNX Software Systems
Add several callback entries to a callback list

Synopsis:
void PtAddCallbacks( PtWidget t *widget,
unsigned long callback type,
PtCallback t const *callback defs,
unsigned int num callbacks );

Description:
This function adds the number of callbacks specified by
num callbacks to the callback list specified by callback type (e.g.
Pt CB ACTIVATE).

☞ Some types of callback resources have special routines that you

should use instead of this one:

Pt CB HOTKEY
PtAddHotkeyHandler()

Pt CB RAW PtAddEventHandler() or PtAddEventHandlers()

The callback defs argument contains the address of an array of

PtCallback t structures. See <PtT.h>.

Examples:
PtWidget t *widget
PtCallback t callbacks[]={
my first callback, NULL ,
my second callback, "Number 2",
my last callback, NULL
};
.
.
.
PtAddCallbacks( widget, Pt CB ACTIVATE, callbacks, 3 );

556 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAddCallbacks()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtAddCallback(), PtAddEventHandler(), PtAddEventHandlers(),
PtAddHotkeyHandler(), PtRemoveCallback(), PtRemoveCallbacks(),
Creating Widgets in Application Code chapter of the Photon
Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 557

PtAddData()  2005, QNX Software Systems
Add data to the provided data chain

Synopsis:
int PtAddData( PtDataHdr t **ptr,
long type,
long subtype,
void *data,
long len,
PtDataRemoveF t *remove );

Description:
This function adds a piece of data to the provided data chain. The data
provided must be in a block of memory created by malloc(). This data
can be retrieved by calling PtFindData(), or PtFindNextData().
The arguments are:

ptr The address of the pointer to the chain the data should be
added to.

type A unique data type.

subtype Used to distinguish multiple blocks of data added as the

same type. This argument shouldn’t be -1 because -1 has
special meaning when searching for a specific block
within the provided data chain.

data A pointer to the data to be added to the provided data

chain.

len The size of the block of data added, or 0 if it isn’t

required.

Returns:
0 on success, or -1 if an error (e.g. out of memory) occurred.

558 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAddData()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtFindData(), PtFindNextData(), PtRemoveData(), PtUnlinkData()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 559

PtAddEventHandler()  2005, QNX Software Systems
Add a single event handler entry to a widget

Synopsis:
void PtAddEventHandler( PtWidget t *widget,
unsigned long event mask,
PtCallbackF t *callback,
void *data );

Description:
This function adds the specified callback to the Pt CB RAW callback
list that belongs to widget. The widget invokes this callback whenever
an event type that matches one of the bits in event mask intersects
with the widget.
The callback argument points to a function that takes this form:

int (*callback)(PtWidget t *, void *, PtCallbackInfo t *)

Examples:
PtWidget t *widget;

PtRawCallback t callbacks[] = {
Ph EV PTR MOTION BUTTON,
motion button callback,
NULL,
Ph EV BUT PRESS | Ph EV BUT RELEASE,
start end callback,
"some data"
}
...
//add both event handlers
PtAddEventHandlers( widget, callbacks, 2 );
...
//remove both event handlers
PtRemoveEventHandlers( widget, callbacks, 2 );
...
//add the motion button event handler
PtAddEventHandler( widget, Ph EV PTR MOTION BUTTON,
motion button callback, NULL );
...
//remove the motion button event handler
PtRemoveEventHandler( widget, Ph EV PTR MOTION BUTTON,
motion button callbacks, NULL )

560 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAddEventHandler()

...
//add both event handlers
PtAddEventHandlers( widget, callbacks, 2 );
...
//remove the motion button event handler
PtRemoveEventHandler( widget, Ph EV PTR MOTION BUTTON,
motion button callbacks, NULL )

// at this point widget still has the Ph EV BUT

// Press/Release event handler

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtRemoveEventHandler(), PtAddCallback(), PtAddCallbacks(),
PtAddEventHandlers(), PtAddHotkeyHandler()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 561

PtAddEventHandlers()  2005, QNX Software Systems
Add several event handler entries to a widget

Synopsis:
void PtAddEventHandlers(
PtWidget t *widget,
PtRawCallback t const *callback defs,
unsigned int num handlers );

Description:
This function adds the number of event handlers specified by
num handlers to the Pt CB RAW callback list that belongs to widget.
The callback defs argument contains the address of an array of
PtRawCallback t structures. See <PtT.h>.

Examples:
See PtAddEventHandler().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtRemoveEventHandlers(), PtAddCallback(), PtAddCallbacks(),
PtAddEventHandler(), PtAddHotkeyHandler()

562 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAddHotkeyHandler()
Add a single hotkey handler entry to a widget

Synopsis:
void PtAddHotkeyHandler( PtWidget t *widget,
unsigned key sym cap,
unsigned key mods,
short flags,
void *data,
PtCallbackF t *callback );

Description:
This function adds the specified callback to the Pt CB HOTKEY
callback list that belongs to the specified widget. The widget will
invoke this callback whenever all three of the following conditions are
met:

¯ The widget’s window has focus.

¯ The widget is selectable (not required if the widget is a window).

¯ The widget’s window receives a key event that matches

key sym cap and key mods (that is, the key is not consumed by
another widget).

The flags argument can contain the following:

Pt HOTKEY SYM
Interpret key sym cap as a key sym; the default is to interpret it
as a key cap.

Pt HOTKEY IGNORE MODS

Ignore the key mods argument. This flag is typically used in
menus, where you want both upper- and lowercase letters to be
accepted as hot keys.

The callback argument points to a function that takes this form:

int (*callback)(PtWidget t *, void *, PtCallbackInfo t *)

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 563

PtAddHotkeyHandler()  2005, QNX Software Systems

Hotkey entries are stacked. As a result, the last hotkey attached is the
first to be checked.
If a hotkey callback is triggered, the key event is consumed and no
other hotkey callbacks will be invoked. If callback is NULL, the
widget’s Pt CB ACTIVATE callback list is invoked when the hotkey is
pressed.
Note the following:

¯ Key caps, key mods, and key syms are defined in

<photon/PkKeydef.h>.

¯ Key mods are prefixed with Pk KM .

¯ Key caps and key syms are prefixed with only Pk .

Hotkeys are handled at the window level. So if two widgets within the
same window happen to register the same hotkey definition, only the
callback for the last duplicate hotkey is invoked.
Hotkey callbacks are automatically registered when the owner widget
is realized, and automatically removed when the owner widget is
unrealized.

Examples:
PtWidget t *widget1, *widget2, *widget3, *window;
.
.
.
// add a hotkey to the window on the key sym
// for Escape.

PtAddHotkeyHandler( window, Pk Escape, 0,

Pt HOTKEY SYM,
NULL, escape callback );

// add a hotkey handler for the digit "1" to

// widget1 that ignores the states of Ctrl/Alt/Shift.

PtAddHotkeyHandler( widget1, Pk 1, 0,
Pt HOTKEY IGNORE MODS,
NULL, one callback );

// add a hotkey handler for the digit "2" to widget2

// that will be triggered only if the CTRL modifier

564 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAddHotkeyHandler()

// is pressed when "2" is hit.

PtAddHotkeyHandler( widget2, Pk 2, Pk KM CTRL, 0,

NULL, ctrl 2 callback );

// add a hotkey handler for the digit 3 to widget3.

// When triggered, widget3’s activate callback will be
// invoked with a reason type of Pt CB ACTIVATE and a
// reason subtype of Pt CB HOTKEY.

PtAddHotkeyHandler( widget3, Pk 3, 0, 0, NULL, NULL );

// Remove the hotkey handlers.

PtRemoveHotkeyHandler( window, Pk Escape, 0,

Pt HOTKEY SYM,
NULL, escape callback );
PtRemoveHotkeyHandler( widget1, Pk 1, 0,
Pt HOTKEY IGNORE MODS,
NULL, one callback );
PtRemoveHotkeyHandler( widget2, Pk 2, Pk KM CTRL, 0,
NULL, ctrl 2 callback );
PtRemoveHotkeyHandler( widget3, Pk 3, 0, 0,
NULL, NULL );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtRemoveHotkeyHandler(), PtAddCallback(), PtAddCallbacks(),
PtAddEventHandler(), PtAddEventHandlers()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 565

PtAddHotkeyHandler()  2005, QNX Software Systems

“Hotkey callbacks” in the Editing Resources and Callbacks in PhAB

chapter of the Photon Programmer’s Guide.

566 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAppAddFd(), PtAppAddFdPri()
Install a file-descriptor function

Synopsis:
int PtAppAddFd( PtAppContext t app,
int fd,
unsigned mode,
PtFdProc t fun,
void *data);

int PtAppAddFdPri( PtAppContext t app,

int fd,
unsigned mode,
PtFdProc t fun,
void *data,
int priority):

Description:
These functions install an “FD function” that will inform the
application about device events.
The app argument is the address of the application context, a structure
that manages all the data associated with this application. For Photon
1.1x, this must be specified as NULL, so that the default context is
used.
The mode argument defines what kind of conditions the application is
interested in:

Pt FD READ Data available for reading.

Pt FD WRITE Buffer space available for writing.
Pt FD OBAND Out-of-band data available.

These values correspond to conditions defined for the ionotify() or

select() functions. You can OR two or all three values together. You
can change the mode later by calling PtAppSetFdMode()
Multiple FD functions attached to the same file descriptor aren’t
supported. PtAppAddFd() fails with errno set to EBUSY if you try to
attach another function to the same FD.

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 567

PtAppAddFd(), PtAppAddFdPri()  2005, QNX Software Systems

The fun argument defines the function to be called. This function

should match the following prototype:
typedef int PtFdProcF t( int fd, void *data, unsigned mode );
typedef PtFdProcF t *PtFdProc t;

The fd and data arguments will have the same value as the fd and data
arguments to PtAppAddFd(). The mode argument will indicate which
conditions were actually met.
If the fun function returns a value other than Pt CONTINUE, it will be
removed automatically from the list of fd functions.
There are other flags that you can add to the mode argument to
PtAppAddFd(). They can be used for optimizing the performance by
avoiding unnecessary messages. Note that these flags aren’t
necessarily implemented for both QNX 4 and Neutrino; if a flag isn’t
implemented, it’s defined as zero.

Pt FD NOPOLL Tells the library that you’re not particularly

interested in the value of the mode argument to
your function. Under QNX 4, this may save one
message to the resource manager per call to your
function. In those cases, the mode argument to
your function will have a value of Pt FD NOPOLL.
Pt FD DRAIN When used together with Pt FD READ, tells the
library that your function will drain the input
completely. Under Neutrino, the
NOTIFY ACTION TRANARMC action will be used
when possible. This will save one message to the
resource manager per call to your function. Note
that even if no input is pending when you call
PtAppAddFd(), your function may be called soon
with the mode argument set to zero. You should
then make sure that the input queue is drained
completely.

For PtAppAddFdPri(), the priority parameter specifies the priority of

the Photon pulse that’s created (see PtAppCreatePulse()).

568 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAppAddFd(), PtAppAddFdPri()

Returns:
0 Success.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtAppCreatePulse(), PtAppRemoveFd(), PtAppSetFdMode()
“Other I/O mechanisms” in the Interprocess Communication and
Lengthy Operations chapter of the Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 569

PtAppAddInput()  2005, QNX Software Systems
Add an input processing function

Synopsis:
PtInputId t *PtAppAddInput(
PtAppContext t app context,
pid t pid,
PtInputCallbackProc t input func,
void *data );

Description:
This routine adds a function to a PtMainLoop() input-event
processing chain.
The app argument is the address of the application context, a structure
that manages all the data associated with this application. For Photon
1.1x, this must be specified as NULL, so that the default context is
used.
The input function is executed whenever the application receives a
message from process pid. If pid is negative, it’s the ID of a Photon
pulse.
If you specify a pid of 0, the input function will be called for every
non-Photon event message that’s received, but only if there’s no input
function that catches messages from the sending pid specifically.
The rcvid argument that the input function will get may have a
different value:

¯ In case of real processes under Neutrino, the input function gets

the rcvid — which is the value that you’ll need for replying, just
like the PID under QNX 4. To retrieve the ID of the process, use
PtGetRcvidPid().

¯ Under QNX 4, the rcvid is the same as the PID, and the
PtGetRcvidPid() function is a macro that returns its argument:
#define PtGetRcvidPid( pid ) (pid)

¯ In the case of Photon pulses, the rcvid argument won’t necessarily

have the same value as the pulse PID, either. In QNX 4, it’s the

570 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAppAddInput()

PID of a proxy. In Neutrino, the rcvid matches the pulse PID on

bits defined by NOTIFY DATA MASK (see ionotify() in the
Neutrino Library Reference), but the other bits will be taken from
the Neutrino pulse or signal that was received.

The input func argument points to the input function to be invoked.

The function takes this form:
int (*input func)(void *data, pid t rcvid,
void *message, size t size);

You can declare the function to be of type

PtInputCallbackProcF t to take advantage of the compiler’s
type-checking.
The data argument points to user data that’s passed to the input entry
function.

☞ ¯ If the input function changes the display, it should call PtFlush() to

make sure the display is updated.

¯ If the input function returns a value other than Pt CONTINUE, the

function is removed from the input entry chain.

Returns:
A pointer to a PtInputId t structure that uniquely identifies the
specified input function for the given application context. If an error
occurs, the function returns NULL.

Examples:
// From /qnx4/phtk/apps/msgpass register name.c
int
msg handler( void *data, pid t rcvid,
void *message, ushort t size)
{
struct msg s
{
unsigned type;
unsigned color;
} *msg;

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 571

PtAppAddInput()  2005, QNX Software Systems

msg = ( struct msg s * ) message;

Reply( rcvid, "OK!", 4);
switch(msg->type)
{
case 10:
printf("got:: type = %d, color = %d,
size = %d\n",msg->type,
msg->color, size);
color = msg->color;
color chg( ABW PtRegBut, NULL, NULL );
PtFlush();
break;
}
return( Pt CONTINUE );
}

/****************************************************/
/*** The following function would normally ***/
/*** be placed in an AppBuilder Init function. ***/
/*** See Application menu, Startup Info. The ***/
/*** function is set up here as a button callback ***/
/*** to clarify the sample’s operation. ***/
/****************************************************/
int
register name( PtWidget t *widget, void *data,
PtCallbackInfo t *cbinfo )
{
PtArg t args[5];
PtInputId t *ipid;

static nid t name = -1;

if ( -1 == name )
{
name = qnx name attach( 0, "Photon App" );
if( name == -1 )
return( Pt CONTINUE );
}
PtSetArg( &args[0], Pt ARG TEXT STRING,
"Registered!", 0);
PtSetResources( ABW PtRegBut, 1, &args );

ipid = PtAppAddInput( NULL, 0, msg handler, NULL );

return( Pt CONTINUE );
//added to illustrate removal of input routine....
PtAppRemoveInput( NULL, ipid );
}

572 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAppAddInput()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtMainLoop(), PtAppRemoveInput(), PtSetParentWidget(),
PtResizeEventMsg()
“Receiving QNX messages” in the Interprocess Communication and
Lengthy Operations chapter of the Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 573

PtAppAddSignalProc()  2005, QNX Software Systems
Add Photon signalling to a context

Synopsis:
int PtAppAddSignalProc( PtAppContext t app,
sigset t const *set,
PtSignalProc t func,
void *data);

Description:
This function adds Photon signal handling to the context app.
The app argument is the address of the application context, a structure
that manages all the data associated with this application. For Photon
1.1x, this must be specified as NULL, so that the default context is
used.
All signals in the set set are trapped and directed to a function that
synchronizes with the Photon widget library and, at the next safe
point, invokes the user-supplied function func().
The user callback function is declared as follows:

int func(int signal, void *data)

You can declare the function to be of type PtSignalProcF t to take

advantage of the compiler’s type-checking.
It’s invoked with the signal number and user data as parameters. It
should return Pt CONTINUE to remain installed, or Pt END to have the
callback removed for this signal.
You can add more than one function for a set of signals or set of
intersecting signals. All handlers for a signal are called, but the order
they’re called in is unspecified.
The Photon widget library isn’t signal-safe — normal signal handling
functions must not call Photon library functions or alter Photon
globals. Because this mechanism synchronizes with the widget
library before calling the user function, no such limitations are placed
on processing within handler functions installed via this routine.

574 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAppAddSignalProc()

Returns:
0 Success.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtAppRemoveSignal(), PtAppRemoveSignalProc()
Interprocess Communication and Lengthy Operations in the Photon
Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 575

PtAppAddWorkProc()  2005, QNX Software Systems
Add a WorkProc (background) function

Synopsis:
PtWorkProcId t *PtAppAddWorkProc(
PtAppContext t app context,
PtWorkProc t work func,
void *data );

Description:
This function adds a WorkProc entry to the WorkProc (background)
process stack. The entry becomes the current WorkProc entry.

☞ WorkProc functions don’t run concurrently; only the one at the top of
the stack runs.

When there are no events pending from Photon, the current WorkProc
entry’s function is invoked by PtMainLoop().
The app argument is the address of the application context, a structure
that manages all the data associated with this application. For Photon
1.1x, this must be specified as NULL, so that the default context is
used.
The work func argument points to the WorkProc function to be
invoked when no Photon events are pending. The function takes this
form:
int (*work func)(void *data)
You can declare the function to be of type PtWorkProcF t to take
advantage of the compiler’s type-checking.

576 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAppAddWorkProc()

☞ ¯ If the WorkProc function changes the display, it should call

PtFlush() to make sure the display is updated.

¯ If the WorkProc function pointed to by work func returns a value

other than Pt CONTINUE, it’s removed from the WorkProc stack
and the next WorkProc entry on the stack becomes the current
entry.

Returns:
A pointer to a PtWorkProcId t structure that identifies the specified
WorkProc entry for the given application context. If an error occurs,
the function returns NULL.

Examples:
This example comes from the Rebound demo, which you’ll find in
/qnx4/phtk/apps/rebound. These are the callbacks that start and
stop the rebounding work procedure, rebound process(), which is in
src/rb process.

// From src/start rebound.c

int
start rebound( PtWidget t *widget, void *data,
PtCallbackInfo t *cbinfo )
{
PtArg t args[2];

if(stopped) {
if ( delay value == 0 ) {
if ( !bkgd id ) // is one running?
bkgd id = PtAppAddWorkProc( NULL, rebound process,
ABW rb pane );
PtSetArg( &args[0], Pt ARG TIMER INITIAL, 0, 0 );
PtSetResources( ABW timer wgt, 1, args );
} else {
if ( bkgd id )
PtAppRemoveWorkProc( NULL, bkgd id );
PtSetArg( &args[0], Pt ARG TIMER INITIAL, 1, 0 );
PtSetArg( &args[1], Pt ARG TIMER REPEAT,
SPEED MULTIPLY*delay value, 0 );
PtSetResources( ABW timer wgt, 2, args );

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 577

PtAppAddWorkProc()  2005, QNX Software Systems

}
stopped = 0;
}

return( Pt CONTINUE );
}

// From src/stop rebound.c

int
stop rebound( PtWidget t *widget, void *data,
PtCallbackInfo t *cbinfo )
{
PtArg t args[1];

if ( bkgd id ) {
PtAppRemoveWorkProc( NULL, bkgd id );
bkgd id = NULL;
}
PtSetArg( &args[0], Pt ARG TIMER INITIAL, 0, 0 );
PtSetResources( ABW timer wgt, 1, args );

stopped = 1;

return( Pt CONTINUE );
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtMainLoop(), PtAppRemoveWorkProc(), PtSetParentWidget()

578 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAppAddWorkProc()

Interprocess Communication and Lengthy Operations in the Photon

Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 579

PtAppCreatePulse()  2005, QNX Software Systems
Create a Photon pulse

Synopsis:
pid t PtAppCreatePulse( PtAppContext t app,
int priority );

Description:
This function creates a Photon pulse. Under QNX 4, a proxy is
created. Under Neutrino, a pulse or realtime signal will be used.
The app argument is the address of the application context, a structure
that manages all the data associated with this application. For Photon
1.1x, this must be specified as NULL, so that the default context is
used.
The priority parameter specifies the priority of the pulse. If priority is
-1, the pulse’s priority is the same as that of the calling process.

Returns:
A pulse PID (a negative value that’s guaranteed never to be -1), or 0 if
an error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtAppDeletePulse(), PtAppPulseTrigger(), PtChannelCreate(),
PtPulseArmFd(), PtPulseArmPid(), PtPulseDeliver(),
PtPulseDisarm()

580 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAppCreatePulse()

Interprocess Communication and Lengthy Operations in the Photon

Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 581

PtAppDeletePulse()  2005, QNX Software Systems
Delete a Photon pulse

Synopsis:
int PtAppDeletePulse( PtAppContext t app,
pid t pulse pid );

Description:
This function deletes the Photon pulse identified by pulse pid (and the
proxy in QNX 4). The pulse pid identifies a pulse created by
PtAppCreatePulse().
The app argument is the address of the application context, a structure
that manages all the data associated with this application. For Photon
1.1x, this must be specified as NULL, so that the default context is
used.

☞ If the application creates and destroys pulses frequently, the pulse ID

will be reused eventually. At least several hundred pulses can be
safely created and destroyed before that happens. If a pulse ID is
reused but notifications are still generated with the old pulse, they
may or may not be delivered to the new pulse handler.

Returns:
0 Success.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

582 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAppDeletePulse()

See also:
PtAppCreatePulse(), PtAppPulseTrigger(), PtChannelCreate(),
PtPulseArmFd(), PtPulseArmPid(), PtPulseDeliver(),
PtPulseDisarm()
Interprocess Communication and Lengthy Operations in the Photon
Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 583

PtAppInit()  2005, QNX Software Systems
Initialize an application and create the main window

Synopsis:
PtWidget t *PtAppInit( PtAppContext t *app context,
int *argc,
char **argv,
int num args,
PtArg t const *args );

Description:
This function:

¯ Initializes the connection to the Photon Manager.

¯ Initializes the widget library.

¯ Creates a default application context (app context) if one doesn’t

exist.

¯ Creates a main window using the num args and args arguments —
these are the same arguments passed to PtCreateWidget().

Returns:
A pointer to the main window, or NULL if an error occurs.

Examples:
See PtContainerGiveFocus().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

584 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAppInit()

See also:
PhAttach(), PtCreateWidget(), PtInit(), PtMainLoop()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 585

PtAppPulseTrigger()  2005, QNX Software Systems
Deliver a pulse to yourself

Synopsis:
int PtAppPulseTrigger( PtAppContext t app,
pid t pulse );

Description:
This function allows an application to deliver a pulse to itself:

¯ In Neutrino, this function uses (pulse | NOTIFY COND MASK) to

identify the pulse (and its handler), but the value of the pulse
argument is delivered.

¯ In QNX 4, the value of pulse must match the pulse PID exactly.

The app argument is the address of the application context, a structure

that manages all the data associated with this application. For Photon
1.1x, this must be specified as NULL, so that the default context is
used. The pulse argument is a pulse ID returned by
PtAppCreatePulse().

Returns:
0 Success.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

586 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAppPulseTrigger()

See also:
PtAppCreatePulse(), PtAppDeletePulse(), PtChannelCreate(),
PtPulseArmFd(), PtPulseArmPid(), PtPulseDeliver(),
PtPulseDisarm()
Interprocess Communication and Lengthy Operations in the Photon
Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 587

PtAppRemoveFd()  2005, QNX Software Systems
Remove a file-descriptor function

Synopsis:
int PtAppRemoveFd( PtAppContext t app, int fd );

Description:
This function removes an FD function, fd, from the of input handlers
for the application.
The app argument is the address of the application context, a structure
that manages all the data associated with this application. For Photon
1.1x, this must be specified as NULL, so that the default context is
used.

Returns:
0 Success.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtAppAddFd(), PtAppAddFdPri(), PtAppSetFdMode()
“Other I/O mechanisms” in the Interprocess Communication and
Lengthy Operations chapter of the Programmer’s Guide

588 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAppRemoveInput()
Remove an input processing entry

Synopsis:
void PtAppRemoveInput( PtAppContext t app context,
PtInputId t *input id );

Description:
This routine removes an input entry from the input-event processing
chain.
The app context argument indicates which application context the
input entry will be removed from. If you specify NULL, the function
will try to remove the entry from the default context.
The input id argument points to a PtInputId t structure that
describes the input entry to be removed. (This structure was returned
by a previous call to PtAppAddInput().)

Examples:
See PtAppAddInput().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtAppAddInput(), PtMainLoop()
“Receiving QNX messages” in the Interprocess Communication and
Lengthy Operations chapter of the Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 589

PtAppRemoveSignal()  2005, QNX Software Systems
Remove specific signal handling from a context

Synopsis:
int PtAppRemoveSignal( PtAppContext t app,
sigset t const *set,
PtSignalProc t proc,
void *data );

Description:
This function removes Photon signal handling from the context app:

¯ If set is NULL, this function removes all items that match proc and
data.

¯ If set isn’t NULL, this function removes one instance of each

specified signal from a list item that matches proc and data. In
other words, if you attach it twice, you have to remove it twice.

Currently only the default app context (app == NULL) is supported.

Returns:
0 Success.

-1 Nothing has been removed.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

590 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAppRemoveSignal()

See also:
PtAppAddSignalProc(), PtAppRemoveSignalProc()
Interprocess Communication and Lengthy Operations in the
Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 591

PtAppRemoveSignalProc()  2005, QNX Software Systems
Remove Photon signalling from a context

Synopsis:
int PtAppRemoveSignalProc( PtAppContext t app,
sigset t const *set);

Description:
This function removes Photon signal handling from the context app.
All signals in the set set which were previously trapped are set back to
the default handler (SIG DFL), and any outstanding notification of
these signals is canceled.

!
CAUTION: This function will remove any handlers for the given
signals used internally by the libraries. You should use
PtAppRemoveSignal() instead.

Currently only the default app context (app == NULL) is supported.

Returns:
0

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

592 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAppRemoveSignalProc()

See also:
PtAppAddSignalProc(), PtAppRemoveSignal()
Interprocess Communication and Lengthy Operations in the
Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 593

PtAppRemoveWorkProc()  2005, QNX Software Systems
Remove a WorkProc processing function

Synopsis:
void PtAppRemoveWorkProc(
PtAppContext t app context,
PtWorkProcId t *WorkProc id );

Description:
This routine removes a WorkProc function from the WorkProc
event-processing stack.
The app context argument indicates which application context the
WorkProc function will be removed from. To remove the entry from
the default context, specify NULL.
The WorkProc id argument points to a PtWorkProcId t structure
that describes the WorkProc entry to be removed. (This structure was
returned by a previous call to PtAppAddWorkProc().)

Examples:
See PtAppAddWorkProc().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtAppAddWorkProc(), PtMainLoop()

594 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAppRemoveWorkProc()

Interprocess Communication and Lengthy Operations in the Photon

Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 595

PtAppSetFdMode()  2005, QNX Software Systems
Change the mode that’s of interest to an FD handler

Synopsis:
int PtAppSetFdMode( PtAppContext t app,
int fd,
unsigned mode );

Description:
This function changes the mode that’s of intereset to the handler for
the given file descriptor, fd.
The app argument is the address of the application context, a structure
that manages all the data associated with this application. For Photon
1.1x, this must be specified as NULL, so that the default context is
used.
The mode argument defines what kind of conditions the application is
interested in:

Pt FD READ Data available for reading.

Pt FD WRITE Buffer space available for writing.

Pt FD OBAND Out-of-band data available.

These values correspond to conditions defined for the ionotify() or

select() functions. You can OR the values together.

Returns:
0 Success.

-1 An error occurred; errno is set.

Errors:
EINVAL The fd or mode argument is invalid.

ESRCH There’s no handler registered for the file descriptor.

596 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAppSetFdMode()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtAppAddFd(), PtAppAddFdPri(), PtAppRemoveFd()
“Other I/O mechanisms” in the Interprocess Communication chapter
of the Photon Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 597

PtArg t  2005, QNX Software Systems
Which resource is affected when you get or set resources

Synopsis:
typedef struct Pt arg entry {
long type;
long value;
long len;
} PtArg t;

Description:
You use the PtArg t structure extensively when dealing with widget
resources. It’s the first argument in the PtSetArg() macro.
This structure contains at least the following members:

type The resource type (for example, Pt ARG TEXT STRING) to

be set or queried.

value Either the value to set the resource to or, if you’re querying
the resource, the address of a pointer.

len The purpose of this member is determined by the Pt type of

the resource.

For more information, see the Manipulating Resources in Application

Code chapter of the Photon Programmer’s Guide.

Classification:
Photon

See also:
Pt ARG(), PtCreateWidget(), PtGetResources() PtSetArg(),
PtSetResources()
Manipulating Resources in Application Code chapter of the Photon
Programmer’s Guide.

598 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems Pt ARG()
Macro for creating statically initialized argument lists

Synopsis:
#define Pt ARG( type, value, len ) { ... }

Description:
This macro lets you have statically initialized argument lists as an
alternative to using PtSetArg(). For example, instead of:

PhPoint t pos;
PtArg t args[ 2 ];
pos.x = 100;
pos.y = 150;

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

PtSetArg( &args[1], Pt ARG TEXT STRING, "Blah", 0 );
PtCreateWidget( PtLabel, NULL, 2, args );

you can write:

static const PhPoint t pos = { 100, 150 };

static const PtArg t args[] = {
Pt ARG( Pt ARG POS, &pos, 0 ),
Pt ARG( Pt ARG TEXT STRING, "Blah", 0 )
};

PtCreateWidget( PtLabel, NULL, sizeof(args) / sizeof(args[0]), args );

This makes adding or removing items easier and safer because the
compiler counts the items in the array for you. And as a bonus, it
generates less code than the first version.

☞ If you have to calculate some of the values at runtime, you’ll need to

use PtSetArg() to intialize the argument list.

Classification:
Photon

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 599

Pt ARG()  2005, QNX Software Systems

Safety
Interrupt handler No
Signal handler No
Thread No

Caveats:
Pt ARG() is a macro.

See also:
PtArg t, PtGetResources(), PtSetArg(), PtSetResources()
Manipulating Resources in Application Code chapter of the Photon
Programmer’s Guide.

600 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAskQuestion()
Display a question and request a response from the user

Synopsis:
int PtAskQuestion( PtWidget t *parent,
char const *title,
char const *question,
char const *font,
char const *btn1,
char const *btn2,
char const *btn3,
int def btn );

Description:
This function displays a dialog that asks the user a question and that
contains up to three buttons so the user can answer the question. The
function works modally, which means that it processes Photon events
and won’t return until the user chooses a reply.
The title argument defines a title for the dialog. If you don’t want a
title, set the argument to NULL.
The question argument lets you specify the question you want to ask.
The font argument lets you choose the font for the question text; the
default is helv12.
The btn1, btn2, and btn3 arguments let you specify the text of buttons
1, 2, and 3. Buttons 2 and 3 are optional, so if you don’t want to
display one or both of these, set the corresponding argument to NULL.
All three button-text arguments let you to define shortcut keys.
Simply place & in front of the character that will act as the shortcut.
For example, if you specify &Yes, the Y will be underlined in the
button. To select the button, the user can press y or Y.
The def btn argument specifies the number of the button that will act
as the default when the user presses Enter. The text of the default
button is always displayed in bold.
Note that the user can change the default by pressing Tab.

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 601

PtAskQuestion()  2005, QNX Software Systems

Returns:
The number of the button the user selected.

Examples:
switch( PtAskQuestion( base wgt, NULL,
"File has not been saved. Save it?",
"helv14", "&Save", "&Discard",
"&Cancel", 1 ) ) {

case 1: /* yes */
/* save and return back */
if ( Pt HALT == file save( widget, data,
cbinfo ) )
return;
break;

case 2: /* no */
/* continue processing */
break;

case 3: /* cancel */
/* return back */
return;
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

602 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtAskQuestion()

See also:
ApError()
PtMessage in the Widget Reference

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 603

PtBasicWidgetCanvas()  2005, QNX Software Systems
Determine the PtBasic canvas for a widget

Synopsis:
PhRect t *PtBasicWidgetCanvas(
PtWidget t *widget,
PhRect t *canvas rect );

Description:
This function determines the canvas rectangle for the specified
widget’s PtBasic-class level. This canvas rectangle describes the
area inside the widget’s border and margins. The canvas rect
argument should point to an instance of a PhRect t structure; if you
pass canvas rect as NULL, the function returns NULL.

Returns:
A pointer to the canvas of the PtBasic widget. If an error occurs, the
function returns NULL.

Examples:
Return the rectangle inside PtWidget’s border:

PtWidgetCanvas( labelwidget, &rect);

Return the rectangle inside PtWidget’s border and PtBasic’s

margins:

PtBasicWidgetCanvas( labelwidget, &rect);

Return the rectangle inside PtWidget’s border, PtBasic’s margins,

and PtLabel’s margins:

PtLabelWidgetCanvas( labelwidget, &rect);

604 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtBasicWidgetCanvas()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtLabelWidgetCanvas(), PtWidgetCanvas(), PtWidgetExtent()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 605

PtBkgdHandlerProcess()  2005, QNX Software Systems
Process all outstanding Photon events

Synopsis:
void PtBkgdHandlerProcess( void );

Description:
This function processes all outstanding Photon events, calling
PtProcessEvent() for each event. You should call this routine
periodically during a costly or complex processing loop when you
won’t be giving control to the widget library. This gives the widget
library an opportunity to redraw widgets that have been damaged or
exposed if, for example, the user drags a window around.

☞ It’s safe to call PtBkgdHandlerProcess() in callbacks, work

procedures, and input procedures, but not in a widget’s Draw method
or a PtRaw widget’s drawing function.

Examples:
{
int done = 0;
while ( !done )
{

/* Handle all pending Photon events */

PtBkgdHandlerProcess( );
/* Do some work, setting done if finished */
}
}

Classification:
Photon

Safety
Interrupt handler No
continued. . .

606 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtBkgdHandlerProcess()

Safety
Signal handler No
Thread No

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 607

PtCalcAbsPosition()  2005, QNX Software Systems
Calculate the position of a widget based on a position and another widget

Synopsis:
int PtCalcAbsPosition( PtWidget t *reference,
PhPoint t const *pos,
PhDim t const *dim,
PhPoint t *new pos );

Description:
This function calculates the position of a new widget with dimensions
dim, according to the reference widget and pos values passed.
The reference argument is a pointer to a widget you wish to position
the new widget relative to. The pos argument is an offset from the
reference widget or from the top left corner of the screen. The dim
argument gives the dimensions of the new widget to be positioned and
must not be NULL. The new pos argument must be a pointer to a
PhPoint t structure. The calculated position is stored in it.
The position is calculated as follows:

Reference Position Position returned

NULL NULL center of the screen
NULL non-NULL offset pos from the top left corner of the
screen
non-NULL NULL center of reference widget
non-NULL non-NULL offset pos from the reference widget’s
top left corner

Returns:
0 Success

-1 An error occurred. The dim or new pos values might have

been NULL.

608 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtCalcAbsPosition()

Examples:
If you have a main application window and want to center a dialog on
it, you could do the following:

PtWidget t *window; // The main window

PhDim t dim = { 100, 100 }; // The size the dialog
// is going to be
PhPoint t pos; // The position of the dialog,
// to be determined
int err;

...
// make a main window
window = PtAppInit( &app, &argc, argv, n args, args );
...
err = PtCalcAbsPosition(window, NULL, &dim, &pos);
...
// Create the dialog and position it at ’pos’ --
// it will be centered on the window.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 609

PtChannelCreate()  2005, QNX Software Systems
Make sure the widget library is using a channel

Synopsis:
int PtChannelCreate( void );

Description:
In QNX 4, this function simply returns 1.
In Neutrino, this function makes sure that the widget library is using a
channel (rather than realtime signals) for notification. It returns the
channel number (or -1 on failure).

Returns:
There’s no such thing as a channel in QNX 4, so this function simply
returns 1.
In Neutrino, this function returns the channel number, or -1 on failure.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

610 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtChildType()
Determine the relationship between two widgets

Synopsis:
int PtChildType( PtWidget t *parent,
PtWidget t *child );

Description:
This function returns Pt IMMEDIATE CHILD if the provided child is
the immediate child of parent or Pt SUBORDINATES CHILD if the
child is a child of a procreated child of parent. Otherwise Pt FALSE is
returned.

Returns:
Pt IMMEDIATE CHILD
The provided child is the immediate child of parent.

Pt SUBORDINATES CHILD
The child is a child of a procreated child of parent.

Pt FALSE Neither of the above is true.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtWidgetBrotherBehind(), PtWidgetBrotherInFront(),
PtWidgetChildBack(), PtWidgetChildFront(), PtWidgetParent()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 611

PtChildType()  2005, QNX Software Systems

“Ordering widgets” in the Creating Widgets in Application Code

chapter of the Photon Programmer’s Guide

612 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtClearWidget()
Destroy all widgets within a container

Synopsis:
int PtClearWidget(PtWidget t *widget);

Description:
This function destroys all the widgets within the specified
container-class widget. If the specified widget isn’t a container, no
action is taken.

Returns:
0 Successful completion.

-1 An error occurred (the widget wasn’t a container).

Examples:
main()
{
PtWidget t *group, *window;
PtArg t argt;
PtArg t argts[3];
PhPoint t pos ={ 10,10 };

PtInit( NULL );
PtSetArg( &argt, Pt ARG POS, &pos, 0 );
window = PtCreateWidget( PtWindow, parent, 1, &argt );

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

PtSetArg( &argts[1], Pt ARG GROUP ORIENTATION,
Pt GROUP VERTICAL, 0 );
group = PtCreateWidget( PtGroup, window, 1, &argt );

PtSetArg( &argt, Pt ARG TEXT STRING, "Button", 0 );

PtCreateWidget( PtButton, group, 1, &argt );

//using same string as previous button...

PtCreateWidget( PtButton, group, 1, &argt );

PtCreateWidget( PtButton, group, 1, &argt );

PtRealizeWidget( window );

PtContainerHold( group );
PtClearWidget( group );

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 613

PtClearWidget()  2005, QNX Software Systems

//destroys all widgets within the group,

//clearing it...

//add new children to the group

PtSetArg( &argt, Pt ARG TEXT STRING,
"New Button", 0 );
PtRealizeWidget( PtCreateWidget( PtButton, group, 1,
&argt ) );
PtSetArg( &argt, Pt ARG TEXT STRING,
"New Button2", 0 );
PtRealizeWidget( PtCreateWidget( PtButton, group, 1,
&argt ) );

//force the group to re-align its children and resize.

PtExtentWidget( group );

PtContainerRelease( group );
PtMainLoop();
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtContainerHold(), PtContainerRelease(), PtDestroyWidget(),
PtExtentWidget(), PtWidgetChildBack()

614 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtConsoleSwitch()
Switch to another virtual console

Synopsis:
int PtConsoleSwitch( int console );

Description:
This function causes PWM to switch the current display to the virtual
console console (where console is a number in the range 0 to 8):

0 1 2

3 4 5

6 7 8

Numbering for Photon’s virtual consoles.

Virtual consoles are numbered from 0 through 8, with 0 at the top left,
and 8 at the lower right. The coordinates of the top left corner of
console 0 are (0,0). The coordinates of the other consoles depend on
your screen size.

Returns:
0 Success.

-1 An error occurred. Check the value of errno for more

information.

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 615

PtConsoleSwitch()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtWindowConsoleSwitch()

616 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtContainerBox()
Find the next widget in an area

Synopsis:
PtWidget t * PtContainerBox( PtWidget t *container,
PtWidget t *start,
PhRect t const *rect );

Description:
This function returns a pointer to the first widget within the specified
container that intersects with the provided rectangle.
The widget identified by start tells the function where to start looking
for intersections. First, the function checks start’s brother behind.
Then, it then checks the brother behind that, and so on.

Returns:
If no widget after start intersects with rect or if the provided container
pointer doesn’t actually point to a container, the function returns
NULL.

Examples:
PtWidget t *target widget, *my pane;
...

// In my pane’s RAW callback:

int
my raw cb( PtWidget t *container, void *data,
PtCallbackInfo t *cbinfo )
{
...
rect = PhGetRects( cbinfo->event );
if( target widget = PtContainerBox( widget,
PtWidgetChildFront( container ) , &rect ) )
PtDestroyWidget( target widget );
...

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 617

PtContainerBox()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhGetRects(), PtContainerHit(), PtWidgetChildFront()

618 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtContainerFindFocus()
Find the currently focused widget

Synopsis:
PtWidget t *PtContainerFindFocus(
PtWidget t *family member );

Description:
This function finds the focused widget for the widget hierarchy that
contains family member.

Returns:
A pointer to the currently focused widget, or NULL if family member
is passed as NULL.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtContainerGiveFocus(), PtContainerNullFocus(),
PtContainerFocusNext(), PtContainerFocusPrev(),
PtGlobalFocusNext(), PtGlobalFocusNextFrom(),
PtGlobalFocusPrev(), PtGlobalFocusPrevFrom(), PtIsFocused()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 619

PtContainerFocusNext()  2005, QNX Software Systems
Give focus to the next Pt GETS FOCUS widget

Synopsis:
PtWidget t *PtContainerFocusNext(
PtWidget t *widget,
PhEvent t *event );

Description:
This function gives focus to the next widget that has Pt GETS FOCUS
set in its Pt ARG FLAGS and is in the same container as the currently
focused widget in widget’s family. If no widget has the
Pt GETS FOCUS flag set, the container’s focus is nullified (that is,
none of its children will have focus).
The event argument contains the event that’s passed to the lost-focus
callback of the widget losing focus and to the got-focus callback of
the widget getting focus.
If event isn’t provided, a NULL event is generated for you.

Returns:
A pointer to the newly focused widget.

Examples:
See PtContainerGiveFocus().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

620 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtContainerFocusNext()

See also:
PtContainerFocusPrev(), PtContainerGiveFocus(),
PtContainerNullFocus()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 621

PtContainerFocusPrev()  2005, QNX Software Systems
Give focus to the previous Pt GETS FOCUS widget

Synopsis:
PtWidget t *PtContainerFocusPrev(
PtWidget t *widget,
PhEvent t *event );

Description:
This function gives focus to the previous widget that has
Pt GETS FOCUS set in its Pt ARG FLAGS and is in the same
container as the currently focused widget in widget’s family. If no
widget has the Pt GETS FOCUS flag set, the container’s focus is
nullified (that is, none of its children will have focus).
The event argument contains the event that’s passed to the lost-focus
callback of the widget losing focus and to the got-focus callback of
the widget getting focus.
If event isn’t provided, a NULL event is generated for you.

Returns:
A pointer to the newly focused widget.

Examples:
See PtContainerGiveFocus().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

622 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtContainerFocusPrev()

See also:
PtContainerFocusNext(), PtContainerGiveFocus(),
PtContainerNullFocus(), PtWidgetExtent()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 623

PtContainerGiveFocus()  2005, QNX Software Systems
Give focus to a widget

Synopsis:
PtWidget t *PtContainerGiveFocus(
PtWidget t *widget,
PhEvent t *event );

Description:
This function gives focus to the specified widget, even if the widget’s
Pt GETS FOCUS flag isn’t set.

☞ If the container is a PtWindow, use PtWindowFocus() instead of this

function — see the Photon Widget Reference.

The event argument contains the event that will be passed to the
lost-focus callback of the widget losing focus and to the got-focus
callback of the widget getting focus.
If event isn’t provided, a NULL event is generated for you.

Returns:
A pointer to the newly focused widget. This is usually the same as the
widget argument, but it could be NULL if one of the following is true:

¯ The widget argument is NULL.

¯ The given widget is disjoint (e.g. a window).

¯ The widget is blocked; that is, it has Pt BLOCKED set in its

Pt ARG FLAGS resource (see PtWidget in the Photon Widget
Reference).

¯ The widget has been destroyed before the attempt to give it focus.

¯ The event passed (if not NULL) has already caused focus to
change, as indicated by:
event->processing flags & Ph DIRECTED FOCUS

624 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtContainerGiveFocus()

This function could also return a pointer to a different widget if that

widget for some reason refused to relinquish focus (i.e. its
Pt CB LOST FOCUS callback returned Pt END — see PtBasic in
the Photon Widget Reference). This usually happens if the
requirements of an entry field haven’t been met and must be met
before any other action can be taken.

☞ The widget library never refuses to relinquish focus. If a widget does

this, it’s because of a Pt CB LOST FOCUS callback in your
application.

Examples:
first( PtWidget t *widget, void *data,
PtCallbackInfo t *cbinfo )
{
//like selecting texta
PtWidget t *text = (PtWidget t *)data;
PtContainerGiveFocus( text, cbinfo->event );
}

next( PtWidget t *widget, void *data,

PtCallbackInfo t *cbinfo )
{
//like hitting tab
PtGlobalFocusNext( widget, cbinfo->event );
}

prev( PtWidget t *widget, void *data,

PtCallbackInfo t *cbinfo )
{
//like hitting shift-tab
PtGlobalFocusPrev( widget, cbinfo->event );
}

none( PtWidget t *widget, void *data,

PtCallbackInfo t *cbinfo )
{
PtContainerNullFocus( PtFindDisjoint (widget),
cbinfo->event );
}

main()
{
PtWidget t *window, *texta, *textb, *textc,
*button;

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 625

PtContainerGiveFocus()  2005, QNX Software Systems

PhPoint t pos ={ 0, 0 };
PhRect t rect;
int n;
PtArg t argt[5];
PtCallback t focus cbs[] = {
{ first, NULL },
{ next, NULL },
{ prev, NULL },
{ none, NULL }
};

window = PtAppInit( NULL, NULL, NULL, 0, NULL);

n = 0;
PtSetArg( &argt[n], Pt ARG POS, &pos, 0 ); n++;
PtSetArg( &argt[n], Pt ARG TEXT STRING,
"First Field", 0 ); n++;
texta = PtCreateWidget( PtText, NULL, n, argt );
PtExtentWidget( texta );
PtWidgetExtent( texta, &rect );
pos.y += rect.lr.y + 10;

n = 0;
PtSetArg( &argt[n], Pt ARG POS, &pos, 0 ); n++;
PtSetArg( &argt[n], Pt ARG TEXT STRING,
"First Field", 0 ); n++;
textb = PtCreateWidget( PtText, NULL, n, argt );
PtExtentWidget( textb );
PtWidgetExtent( textb, &rect );
pos.y += rect.lr.y + 10;

n = 0;
PtSetArg( &argt[n], Pt ARG POS, &pos, 0 ); n++;
PtSetArg( &argt[n], Pt ARG TEXT STRING,
"First Field", 0 ); n++;
textc = PtCreateWidget( PtText, NULL, n, argt );
PtExtentWidget( textc );
PtWidgetExtent( textc, &rect );
pos.y += rect.lr.y + 15;

focus cbs[0].data = (void *)texta;

n = 0;
PtSetArg( &argt[n], Pt ARG POS, &pos, 0 ); n++;
PtSetArg( &argt[n], Pt CB ACTIVATE,
focus cbs[0], 1 ); n++;
PtSetArg( &argt[n], Pt ARG TEXT STRING,
"First", 0 ); n++;
button = PtCreateWidget( PtButton, NULL, n, argt );
PtExtentWidget( button );

626 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtContainerGiveFocus()

PtWidgetExtent( button, &rect );

pos.x += rect.lr.x + 10;

n = 0;
PtSetArg( &argt[n], Pt ARG POS, &pos, 0 ); n++;
PtSetArg( &argt[n], Pt CB ACTIVATE,
focus cbs[1], 1 ); n++;
PtSetArg( &argt[n], Pt ARG TEXT STRING,
"Next", 0 ); n++;
button = PtCreateWidget( PtButton, NULL, n, argt );
PtExtentWidget( button );
PtWidgetExtent( button, &rect );
pos.x += rect.lr.x + 10;

n = 0;
PtSetArg( &argt[n], Pt ARG POS, &pos, 0 ); n++;
PtSetArg( &argt[n], Pt CB ACTIVATE,
focus cbs[2], 1 ); n++;
PtSetArg( &argt[n], Pt ARG TEXT STRING,
"Prev", 0 ); n++;
button = PtCreateWidget( PtButton, NULL, n, argt );
PtExtentWidget( button );
PtWidgetExtent( button, &rect );
pos.x += rect.lr.x + 10;

n = 0;
PtSetArg( &argt[n], Pt ARG POS, &pos, 0 ); n++;
PtSetArg( &argt[n], Pt CB ACTIVATE,
focus cbs[2], 1 ); n++;
PtSetArg( &argt[n], Pt ARG TEXT STRING,
"None", 0 ); n++;
button = PtCreateWidget( PtButton, NULL, n, argt );
PtExtentWidget( button );
PtWidgetExtent( button, &rect );

pos.x += rect.lr.x + 10;

PtRealizeWidget( window );
PtMainLoop();
}

Classification:
Photon

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 627

PtContainerGiveFocus()  2005, QNX Software Systems

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtContainerFocusNext(), PtContainerFocusPrev(),
PtContainerNullFocus()
PtWindowFocus() in the Photon Widget Reference

628 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtContainerHit()
Find the nth widget in an area

Synopsis:
PtWidget t *PtContainerHit( PtWidget t *container,
unsigned n,
PhRect t const *rect );

Description:
This function returns a pointer to the nth widget within the specified
container that intersects with the provided rectangle. The coordinates
of the rectangle are relative to the given container’s canvas. If no
widget intersects with rect, or if there are fewer than n intersections,
the function returns NULL.

Examples:
PtWidget t *target widget, *my pane;

// In my pane’s RAW callback:

my raw cb( PtWidget t *container, void *data,
PtCallbackInfo t *cbinfo )
{
PhRect t *rect;
PtWidget t *container;
PtWidget t *target widget;

// ...
rect = PhGetRects( cbinfo->event );
container = PtFindContainer( widget );
target widget = PtContainerHit( container, 1, rect );
if (target widget)
PtDestroyWidget( target widget );
// ...
}

Classification:
Photon

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 629

PtContainerHit()  2005, QNX Software Systems

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhGetRects(), PtContainerBox()

630 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtContainerHold()
Prevent repairs to a container widget and its children

Synopsis:
int PtContainerHold( PtWidget t *container widget );

Description:
This function prevents repairs to the specified container widget and to
all its children. Repairs aren’t made until the application makes a
corresponding call to PtContainerRelease().
When the widgets are eventually released, they aren’t repaired
separately. Instead, only the container parent widget is repaired. As a
result, the children are all repaired simultaneously.

☞ PtContainerHold() and PtContainerRelease() increment/decrement

the flux count for the specified container widget. This count is
different from the global hold count, which is used by PtHold() and
PtRelease() to hold all widgets.

Returns:
The container widget’s current hold count.

Examples:
See PtClearWidget().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 631

PtContainerHold()  2005, QNX Software Systems

See also:
PtContainerRelease(), PtFlush(), PtHold(), PtRelease()

632 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtContainerNullFocus()
Nullify the focus of a widget

Synopsis:
PtWidget t *PtContainerNullFocus(
PtWidget t *widget,
PhEvent t *event );

Description:
This function nullifies the focus of the specified widget’s parent. As a
result, none of parent’s children has focus.
The event argument contains the event to be passed to the lost-focus
callback of the parent widget and any of its children that were part of
the focus chain at the time of this function call.
If event isn’t provided, a NULL event is generated for you.

Returns:
A pointer to the widget where the focus chain stops. On successful
completion, this is widget’s parent.

Examples:
See PtContainerGiveFocus().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 633

PtContainerNullFocus()  2005, QNX Software Systems

See also:
PtContainerFocusNext(), PtContainerFocusPrev(),
PtContainerGiveFocus()

634 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtContainerRelease()
Decrement the hold count for a widget

Synopsis:
int PtContainerRelease( PtWidget t *container widget );

Description:
This function decrements the hold count for the specified container
widget. The count was incremented by a previous call to
PtContainerHold(). When the count reaches 0, the widgets are
repaired.
When the widgets are eventually released, they aren’t repaired
separately. Instead, only the container parent widget is repaired. As a
result, the children are all repaired simultaneously.

☞ PtContainerHold() and PtContainerRelease() increment/decrement a

hold count for the specified container widget. This count is different
from the global hold count, which is used by PtHold() and
PtRelease() to hold all widgets.

Returns:
The container widget’s current hold count.

Examples:
See PtClearWidget().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 635

PtContainerRelease()  2005, QNX Software Systems

See also:
PtContainerHold(), PtHold(), PtFlush(), PtRelease()

636 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtCreateWidget()
Create a widget

Synopsis:
PtWidget t *PtCreateWidget(
PtWidgetClassRef t *class,
PtWidget t *parent,
unsigned n args,
PtArg t const *args );

Description:
This function creates a widget in the current widget hierarchy. The
class argument points to the desired widget class and the parent
argument points to the desired parent widget. If you set parent to
NULL, the default parent, which is the most recently created
container, will be used.
The n args argument contains the number of arguments being passed
to the widget library and the args argument points to an array
containing n args arguments.
Since this function modifies and allocates only local data structures, it
doesn’t result in any interaction with the Photon Manager. The user
doesn’t see the widget until it’s realized.

☞ Widgets that belong to the PtContainer class become the current

parent widget when created. If you’re creating multiple
PtContainer-class widgets, make sure each one is placed in the
correct container. To do this, either specify the desired parent in
parent or call PtSetParentWidget().

Returns:
A pointer to the newly created widget, or NULL if an error occurs.

Examples:
See PtClearWidget() and PtSetArg().

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 637

PtCreateWidget()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtDestroyWidget(), PtGetParentWidget(), PtReParentWidget(),
PtSetArg(), PtSetParentWidget(), PtWidgetParent()
“Creating widgets” in the Creating Widgets in Application Code
chapter of the Photon Programmer’s Guide

638 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtDamageExtent()
Mark an area of a widget as damaged so that it will be redrawn

Synopsis:
int PtDamageExtent( PtWidget t *widget,
PhRect t const *extent );

Description:
This function marks the specified widget as damaged and adds extent
to the clipping list that will be used the next time the widget engine
redraws this widget.
All widgets in front of the damaged widget that intersect with extent
will be redrawn. If the damaged widget’s fill color is transparent, all
widgets behind it that intersect extent will be redrawn. In all cases, the
clipping will be set to extent.
The widget library takes care of updating widgets whenever resources
are modified. So you don’t normally use this function unless you’re
mixing Pg calls with widget calls, and want a widget to redraw and
repair itself directly.

Returns:
0 Success.

-1 An error occurred. This function fails if the widget isn’t a

container and doesn’t reside in a container, or if there isn’t
enough memory to expand the damage list.

Examples:
See PhBlit().

Classification:
Photon

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 639

PtDamageExtent()  2005, QNX Software Systems

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtDamageWidget()

640 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtDamageWidget()
Mark a widget as damaged so it will be redrawn

Synopsis:
int PtDamageWidget( PtWidget t *widget );

Description:
This function adds the specified widget’s extent to the damage list of
the widget’s first window parent. This effectively marks the widget as
being damaged so that it will be redrawn.
The widget library takes care of updating widgets whenever resources
are modified. So you don’t normally use this function unless you’re
mixing Pg*() calls with widget calls, and want a widget to redraw and
repair itself directly.

Returns:
0 Successful completion.
-1 An error occurred.

Examples:
int mycallback( PtWidget t *widget, void *data,
PtCallbackInfo t *cbinfo )

{
PgGC t *wgtlib gc;

/* my context is global */
wgtlib gc = PgSetGC( &my context );

/* draw objects on top of the widget */

Pgxxx... calls

/* restore the widget library’s GC */

PgSetGC( wgtlib gc );

/* mark the widget as damaged so that it will

be redrawn */
PtDamageWidget( widget );

return( Pt CONTINUE );
}

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 641

PtDamageWidget()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtDamageExtent()

642 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtDestroyWidget()
Remove a widget from the widget family hierarchy

Synopsis:
int PtDestroyWidget( PtWidget t *widget );

Description:
This function performs the following on the specified widget:

¯ unrealizes it, if necessary

¯ destroys its children

¯ removes it from the widget family hierarchy

¯ flags it for destruction by adding it to the destroyed list.

The widget’s resources aren’t freed until the return of

PtEventHandler().

☞ You might get callbacks from the widget after PtDestroyWidget() has
returned. To determine if this is happening, check the widget’s
Pt DESTROYED flag. For example:

if (PtWidgetFlags(widget) & Pt DESTROYED)

{
return( Pt CONTINUE );
}

Returns:
0 Success.

-1 An error occurred.

Examples:
See PtWidgetChildBack().

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 643

PtDestroyWidget()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtEventHandler(), PtCreateWidget(), PtRealizeWidget(),
PtUnrealizeWidget(), PtWidgetFlags()
Pt ARG FLAGS, Pt CB DESTROYED, resources of PtWidget in the
Widget Reference
“Widget life cycle” in the Introduction to the Photon Programmer’s
Guide

644 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtDeTranslateRect()
Detranslate a rectangle (subtract offset)

Synopsis:
PhRect t *PtDeTranslateRect(
PhRect t *rect,
PhPoint t const *delta );

Description:
This convenience function subtracts delta->x from rect->ul.x and
rect->lr.x, and subtracts delta->y from rect->ul.y and rect->lr.y.
You’ll find this function handy for translating events, extents, or
canvases so they become relative to various points.

Returns:
A pointer to the rect argument.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtTranslateRect()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 645

PtEndFlux()  2005, QNX Software Systems
Decrement the global and container flux count

Synopsis:
int PtEndFlux( PtWidget t *container );

Description:
This function decrements the global flux count as well as the
container’s flux count. If the container’s flux count is 0 or becomes 0
due to the decrement, the container’s extent is added to the container’s
damaged visibility list. All widgets under this rectangle will
recalculate their visibility flags, widget->flags (Pt CLEAR and/or
Pt OBSCURED). This doesn’t cause the widgets within the container
to redraw.

☞ This function is a milder form of PtContainerRelease(), which forces

the redraw of all the widgets in a container.

Any widgets or area that should be repaired must be damaged

manually after the flux count goes to 0.

Returns:
0 Successful completion.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

646 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtEndFlux()

See also:
PtStartFlux(), PtHold(), PtRelease(), PtContainerHold(),
PtContainerRelease(), PtDamageExtent(), PtDamageWidget()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 647

PtEventHandler()  2005, QNX Software Systems
Determine the widgets involved in an event

Synopsis:
int PtEventHandler( PhEvent t *event );

Description:
This function determines which widgets were involved in an event
and invokes the appropriate callback functions. By doing this, the
function enables widgets to interact with the user and to repair
themselves when they’ve been exposed.

Returns:
0 Successful completion.

-1 An error occurred.

Examples:
See PhEventNext().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhEventNext(), PhEventPeek(), PhEventRead()

648 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtExtentWidget()
Force a widget to calculate its extent

Synopsis:
PtWidget t *PtExtentWidget( PtWidget t *widget );

Description:
This function forces the specified widget to calculate its extent. You
can use this function to force PtGroup to redo the layout of its
children.

Returns:
A pointer to the widget.

Examples:
See PtContainerGiveFocus().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtExtentWidgetFamily(), PtReRealizeWidget(), PtWidgetExtent()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 649

PtExtentWidgetFamily()  2005, QNX Software Systems
Force a widget and its children to calculate their extents

Synopsis:
int PtExtentWidgetFamily( PtWidget t *widget );

Description:
This function forces the specified widget and all its descendants to
calculate their extents.

Returns:
0 Successful completion.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtExtentWidget(), PtReRealizeWidget(), PtWidgetExtent()

650 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtFdProcF t, PtFdProc t
Pointer to a file-descriptor function

Synopsis:
typedef int PtFdProcF t( int fd, void *data, unsigned mode );
typedef PtFdProcF t *PtFdProc t;

Description:
These data types define pointers to file-descriptor functions. The
PtFdProcF t type is the function type that the PtFdProc t type
points to. This allows you to do something like this:

PtFdProcF t my fd proc;

int my fd proc( int fd, void *data unsigned mode) {

...
}

The compiler should detect any inconsistencies between the two

declarations of my fd proc() and give you an error (which is better
than a “pointer mismatch” warning on the call to PtAppAddFd()).

Classification:
Photon

See also:
PtAppAddFd()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 651

PtFileSelection()  2005, QNX Software Systems
Create a file-selector dialog

Synopsis:
int PtFileSelection( PtWidget t *parent,
PhPoint t const *pos,
char const *title,
char const *root dir,
char const *file spec,
char const *btn1,
char const *btn2,
char const *format,
PtFileSelectionInfo t *info,
int flags );

Description:
This function creates a file selector dialog that lets the user browse
files and directories. The dialog allows the selection of a file and/or
directory and fills a PtFileSelectionInfo t structure with
information about the selected item and the dialog.
This function has its own event-processing loop.
The arguments are as follows:

parent The dialog’s parent, which can be NULL (see below).

pos The dialog’s position, which can be NULL (see below).

title The dialog’s title. If NULL, the string File Selector

is used.

root dir The current directory for the file selector widget. The
default is / if this parameter is NULL. You can pass a
directory or a full path for a file.

file spec The file specification to look for. The default is * if this
parameter is NULL.

btn1 The string for button 1. The default is Open. This is the
button that returns the selected-file information. When
activated, it sets info->ret to Pt FSDIALOG BTN1.

652 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtFileSelection()

If you want to have a hotkey for this button, place an

ampersand (&) in front of the appropriate character in
the string. For example, to have the string Select with
s as a hotkey, pass &Select as btn1.

btn2 The string for button 2. The default is Cancel. When

activated, it sets info->ret to Pt FSDIALOG BTN2. If you
want to have a hotkey for this button, place an
ampersand (&) in front of the appropriate character in
the string.

format A string to be used with the Pt ARG FS FORMAT

resource of the PtFileSel widget. It determines what
information is displayed and in what order. If you don’t
want the divider shown, pass NULL as this parameter,
and only the filenames are be displayed. See the
description of PtFileSel for the format of this string.

info This is a mandatory parameter. The function returns the

selected file in the path portion of this structure. The
PtFileSelectionInfo t structure includes at least
the following members:
¯ short ret — the return code, either
Pt FSDIALOG BTN1 or Pt FSDIALOG BTN2.
¯ char path[PATH MAX + NAME MAX + 1] — the
full path of the selected item.
¯ PhDim t dim — the dimensions of the dialog when
the selection was completed. You can specify the
size of the dialog by setting this field before calling.
PtFileSelection().
¯ PhPoint t pos — the position of the dialog when
the selection was completed.
¯ char format[80] — the format string of the dialog
when the selection was completed.
¯ char fspec[80] — the file spec of the dialog when
the selection was completed.

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 653

PtFileSelection()  2005, QNX Software Systems

flags Flags for the dialog. The default is to show all

information, and corresponds to a value of 0. The
possible values are:
¯ Pt FSDIALOG NO FCHECK — don’t check files for
validity. This is good for a Save dialog.
¯ Pt FSDIALOG NO FSPEC — don’t display the File
Spec widget.
¯ Pt FSDIALOG NO UP BUTTON — disables the
display of the Up Directory button.
¯ Pt FSDIALOG SHOW HIDDEN — shown hidden
files.

The PtFileSelection() function creates a dialog to simplify file and

directory selection:

654 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtFileSelection()

File Selector

Path: /usr/photon

Name Siz e Date

.. 84875 Nov 16 11:46
appbuilder 4096 May 28 17:35
apps 2048 May 05 18:06
bin 10240 May 27 16:37
cache 34304 May 29 09:32
common 2048 Jan 14 14:52
config 4096 Feb 11 12:22

Filename:

Pattern:

Select Done

An example of the dialog created by PtFileSelection().

The dialog is positioned according to the pos parameter: if NULL, the

dialog is centered on the screen; if parent is NULL, the dialog is
placed at the absolute coordinates of pos; otherwise it’s placed at the
relative offset of pos within parent.
You can specify the dimensions of the dialog by setting the info->dim
field before calling this function.
The dialog consists of:

Path text field You can type a directory name to open or a full
path to a file. It behaves in the following manner:
¯ If you enter a directory that exists, that
directory is displayed.

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 655

PtFileSelection()  2005, QNX Software Systems

¯ If you enter a path to a file that exists and you

didn’t set the Pt FSDIALOG NO FCHECK flag,
the file is automatically selected.
¯ If you enter a path to a file that doesn’t exist and
you didn’t set the Pt FSDIALOG NO FCHECK
flag, the closest directory is selected and the
Filename text field is cleared.
¯ If you enter a path to a file, the directory
portion exists, and you’ve set the
Pt FSDIALOG NO FCHECK flag, the file is
shown in the File text widget.
¯ If you enter a path to a file, the directory
portion doesn’t exist, and you’ve set the
Pt FSDIALOG NO FCHECK flag, the closest
directory is selected and the Filename text field
is cleared.
¯ Just like in the shell, a tilde (˜) can be used to
indicate a home directory.
Up Directory button
Clicking on this moves you up one directory level.
PtFileSel widget
Displays files and directories in single level mode.
Filename text field
Displays the selected file and allows you to enter
your own. It behaves in the following manner:
¯ If you enter a file that exists in the current
directory and you didn’t set the
Pt FSDIALOG NO FCHECK flag, the file is
automatically selected.
¯ If you enter a file that doesn’t exist in the
current directory and you didn’t set the
Pt FSDIALOG NO FCHECK flag, the file widget
is cleared.

656 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtFileSelection()

¯ If you enter a file that does or doesn’t exist in

the current directory and you’ve set the
Pt FSDIALOG NO FCHECK flag, the file is
automatically selected.
¯ If you type .., you’ll move up one directory
level

Pattern text field Only the files whose names match this pattern are
displayed. This pattern doesn’t apply to
directories.

Button 1 Used to select a file or directory. When this button

is clicked, the dialog is destroyed and a
PtFileSelectionInfo t structure is filled in:
ret is Pt FSDIALOG BTN1 and path contains the
full path of the selected item.

Button 2 Used to cancel the selection. When this button is

clicked, the dialog is destroyed and a
PtFileSelectionInfo t structure is filled in:
ret is Pt FSDIALOG BTN2 and path contains
nothing.

Returns:
0 Success.

-1 An error occurred.

Examples:
#include <Pt.h>
#include <photon/PtFileSel.h>
#include <sys/stat.h>
#include <string.h>
#include <stdio.h>

// global widget pointers

PtWidget t *window, *sel btn, *quit btn,
*label, *sel label;
// info structure for the dialog
PtFileSelectionInfo t in;

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 657

PtFileSelection()  2005, QNX Software Systems

// default position for the dialog

PhPoint t pos = {100, 100};
// format string to be reused
char format[80];

int
make fs( PtWidget t *widget,
struct fs dialog modal *user,
PtCallbackInfo t *info)
{
PtArg t args[1];
int err;

// make the file selection dialog

err = PtFileSelection(window, &pos,
NULL, "/", NULL, "&Select",
"&Done", format, &in,
Pt FSDIALOG NO FCHECK);

// save the position and format for making a future dialog

pos.x = in.pos.x;
pos.y = in.pos.y;
strcpy(format, in.format);

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

"The Selected file was:", 0);
PtSetResources(label, 1, args);

PtSetArg(&args[0], Pt ARG TEXT STRING, in.path, 0);

PtSetResources(sel label, 1, args);

return(Pt CONTINUE);
}

void
quit( PtWidget t *widget,
struct fs dialog modal *user,
PtCallbackInfo t *info)
{
exit (EXIT SUCCESS);
}

main()
{
PtArg t args[10];
PhArea t area;
PhDim t dim = { 300, 200 };

in.dim.w = 0;
in.dim.h = 0;

658 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtFileSelection()

// setup a default format string

strcpy(format, "nsd");

// make the main window

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

// make a label
area.pos.x = 20;
area.pos.y = 30;
PtSetArg( &args[0], Pt ARG POS, &area.pos, 0 );
PtSetArg( &args[1], Pt ARG TEXT FONT, "helv12b", 0 );
PtSetArg( &args[2], Pt ARG TEXT STRING,
"There is no selected file", 0);
label = PtCreateWidget( PtLabel, window, 3, args );

// make a second label

area.pos.x = 30;
area.pos.y = 60;
PtSetArg( &args[0], Pt ARG POS, &area.pos, 0 );
PtSetArg( &args[1], Pt ARG TEXT FONT, "helv12b", 0 );
sel label = PtCreateWidget( PtLabel, window, 2, args );

// make a button for selecting files

area.size.w = 80;
area.size.h = 20;
area.pos.x = 120;
area.pos.y = 170;
PtSetArg( &args[0], Pt ARG AREA, &area, 0 );
PtSetArg( &args[1], Pt ARG TEXT STRING, "Select File", 0);
sel btn = PtCreateWidget( PtButton, window, 2, args );
PtAddCallback(sel btn, Pt CB ACTIVATE, &make fs, NULL);

// make a button for quitting

area.size.w = 80;
area.size.h = 20;
area.pos.x = 210;
area.pos.y = 170;
PtSetArg( &args[0], Pt ARG AREA, &area, 0 );
PtSetArg( &args[1], Pt ARG TEXT STRING, "Quit", 0);
quit btn = PtCreateWidget( PtButton, window, 2, args );
PtAddCallback(quit btn, Pt CB ACTIVATE, &quit, NULL);

PtRealizeWidget( window );

PtMainLoop();
}

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 659

PtFileSelection()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

660 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtFindChildClass()
Find the first child that matches the specified class

Synopsis:
PtWidget t *PtFindChildClass(
PtWidgetClassRef t *class,
PtWidget t *widget );

Description:
This function finds the first child widget of the specified container,
widget, that matches the specified class.

☞ Some container widgets, including PtDivider, PtMenuBar,

PtMultiText, and PtScrollArea redirect children to an alternate
parent. For all container widgets, it’s best to call PtValidParent() to
determine the “real” parent of the children. For example, to find a
PtButton in a PtScrollArea:

child = PtFindChildClass( PtButton,

PtValidParent( my scrollarea, PtButton ));

Returns:
A pointer to a PtWidget t structure, or NULL if an error occurs.

Examples:
main()
{
PtArg t argt;
PtWidget t *window, *pane, *button;

// Create a window that contains a pane, which in turn

// contains a button.

window = PtAppInit (NULL, NULL, NULL, 0, NULL)

PtSetArg( &argt, Pt ARG RESIZE FLAGS,
Pt TRUE, Pt RESIZE XY ALWAYS );
pane = PtCreateWidget( PtPane, NULL, 1, &argt );

PtSetArg( &argt, Pt ARG TEXT STRING, "Sample", 0 );

PtCreateWidget( PtButton, NULL, 1, &argt );

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 661

PtFindChildClass()  2005, QNX Software Systems

// The following call finds the button because PtButton

// is a subclass of PtLabel.

button = PtFindChildClassMember( PtLabel, pane );

// The following call does not find the button because

// PtButton is not equivalent to the PtLabel class.

button = PtFindChildClass( PtLabel, pane );

// The following call finds the button because PtButton

// is in the class PtButton.

button = PtFindChildClass( PtButton, pane );

}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtFindChildClassMember(), PtValidParent(),
PtWidgetBrotherBehind(), PtWidgetBrotherInFront(),
PtWidgetChildBack(), PtWidgetFamily(), PtWidgetParent()

662 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtFindChildClassMember()
Find the first child that’s a subclass of the specified class

Synopsis:
PtWidget t *PtFindChildClassMember(
PtWidgetClassRef t *class,
PtWidget t *widget );

Description:
This function finds the first child widget of the specified container
that’s a subclass of the specified class. For example, PtMultiText,
PtText, PtButton, and PtLabel are all subclasses of PtLabel.

☞ Some container widgets, including PtDivider, PtMenuBar,

PtMultiText, and PtScrollArea redirect children to an alternate
parent. For all container widgets, it’s best to call PtValidParent() to
determine the “real” parent of the children. For example, to find a
subclass of PtLabel in a PtScrollArea:

child = PtFindChildClassMember( PtLabel,

PtValidParent( my scrollarea, PtLabel ));

Returns:
A pointer to a PtWidget t structure, or NULL if an error occurs.

Examples:
See PtFindChildClass().

Classification:
Photon

Safety
Interrupt handler No
continued. . .

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 663

PtFindChildClassMember()  2005, QNX Software Systems

Safety
Signal handler No
Thread No

See also:
PtWidgetBrotherBehind(), PtWidgetBrotherInFront(),
PtWidgetChildBack(), PtWidgetFamily(), PtWidgetParent()

664 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtFindContainer()
Return the nearest container parent

Synopsis:
PtWidget t *PtFindContainer( PtWidget t *widget );

Description:
This function returns the nearest container parent (which could be
widget itself).

☞ Some container widgets, including PtDivider, PtMenuBar,

PtMultiText, and PtScrollArea redirect children to an alternate
parent. For all container widgets, it’s best to call PtValidParent() to
determine the “real” parent of the children.

Returns:
A pointer to the nearest container parent of widget, or NULL if no
container parent was found.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 665

PtFindData()  2005, QNX Software Systems
Find the first data block of a given type and subtype

Synopsis:
void * PtFindData( PtDataHdr **ptr,
long type,
long subtype,
long *len,
PtDataHdr t ** node );

Description:
This function finds the first data block that matches the type and
subtype provided. If type is 0, any type will match. If subtype is -1,
any subtype will match.
If node is provided, it’s set to point to the data node that contained
the returned data in order to be able to continue the search from that
node. If len is provided, it’s set the the length of the data item as set
when the data was originally added to the chain.

Returns:
A pointer to the data, or NULL if no matching data was found.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtAddData(), PtFindNextData(), PtRemoveData(), PtUnlinkData()

666 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtFindDisjoint()
Return the nearest disjoint parent widget

Synopsis:
PtWidget t *PtFindDisjoint( PtWidget t *widget );

Description:
This function returns the nearest disjoint parent widget (which could
be widget itself). 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. A disjoint widget’s
class rec has the Pt DISJOINT flag set.
Examples of widgets that are disjoint include:

¯ PtWindow

¯ PtMenu

¯ PtRegion

Examples of widgets that aren’t disjoint include:

¯ PtButton

¯ PtPane

¯ PtRect

Returns:
A widget pointer to the nearest disjoint parent of widget, or NULL if
no disjoint container parent was found.

Classification:
Photon

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 667

PtFindDisjoint()  2005, QNX Software Systems

Safety
Interrupt handler No
Signal handler No
Thread No

668 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtFindFocusChild()
Find the closest focusable child widget

Synopsis:
PtWidget t *PtFindFocusChild( PtWidget t *widget );

Description:
This function finds the closest focusable child widget of widget. If no
focusable children are found, widget is returned.

Returns:
The pointer passed in widget if no focusable children are found, or a
pointer to the first focusable child of widget.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtContainerFindFocus()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 669

PtFindGuardian()  2005, QNX Software Systems
Find the widget responsible for another widget’s actions

Synopsis:
PtWidget t *PtFindGuardian( PtWidget t *child,
int superior only );

Description:
This function returns the widget that’s responsible for the child’s
actions. This is either the child’s natural parent or, if the child is
Pt PROCREATED, the widget that the child is a subordinate of (its
superior widget).
If the superior only value is nonzero, this function returns only a
pointer to a superior widget as a guardian. If the child hasn’t been
procreated, the function returns NULL. (Only procreated widgets have
superiors.)

Returns:
A pointer to the child widget’s legal guardian, or NULL if the child
widget has no guardian.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtGetParent(), PtValidParent(), PtWidgetParent()

670 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtFindGuardian()

“Ordering widgets” in the Creating Widgets in Application Code

chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 671

PtFindNextData()  2005, QNX Software Systems
Find the next data block of a given type and subtype

Synopsis:
void * PtFindNextData( PtDataHdr t **ptr,
PtDataHdr t *data,
long type,
long subtype,
long *len,
PtDataHdr t ** node );

Description:
This function finds the next data block, from data node, that matches
the type and subtype provided. If data node is NULL, the first instance
of data that matches the type and subtype provided is found. If type is
0, any type will match. If subtype is -1, any subtype will match.
If node is provided, it’s set to point to the data node that contained
the returned data in order to be able to continue the search from that
node. If len is provided, it’s set the the length of the data item as set
when the data was originally added to the chain.

Returns:
A pointer to the data, or NULL if no matching data was found.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

672 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtFindNextData()

See also:
PtAddData(), PtFindData(), PtRemoveData(), PtUnlinkData()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 673

PtFlush()  2005, QNX Software Systems
Immediately repair widget damage

Synopsis:
int PtFlush( void );

Description:
This function ensures that any widget damage is repaired (ignoring
container holding), and then calls PgFlush() to flush buffered draw
commands from your application to the graphics driver.
You’ll need to call this function explicitly if you’re drawing
somewhere “outside” the standard Photon event loop (for example, in
an input procedure) or if you want changes to the widgets to be made
immediately.

Returns:
The new value of the global hold count.

Examples:
See PtClearWidget().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtContainerHold(), PtContainerRelease(), PtHold(), PtRelease()

674 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtFontSelection()
Display a modal dialog for selecting a font

Synopsis:
const char *PtFontSelection( PtWidget t *parent,
const PhPoint t *pos,
const char *title,
const char *font,
long symbol,
unsigned flags,
const char *sample);

Description:
This function displays a modal dialog allowing the user to select a
text font. The dialog is parented off the parent widget, which may be
NULL; if non-NULL, that parent widget is blocked and its cursor is
changed to reflect this.
The dialog is positioned according to the pos parameter: if NULL, the
dialog is centered on the screen; if parent is NULL, the dialog is
placed at the absolute coordinates of pos; otherwise it’s placed at the
relative offset of pos within parent.
The title of the dialog is given by title; if this is NULL a default title of
“Select Text Font” is used.
The initial font selected in the dialog is given by font.
The symbol parameter specifies which character will be used to
construct the list of available font families (refer to PfQueryFonts() in
the Library Reference); if -1L is specified a default symbol ’A’
(standard Latin fonts) is used.
The flags parameter is used to limit the inclusion of fonts based on
certain characteristics:

To include: Use this flag:

Scalable fonts PHFONT SCALABLE

continued. . .

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 675

PtFontSelection()  2005, QNX Software Systems

To include: Use this flag:

Bitmapped fonts PHFONT BITMAP
Proportional fonts PHFONT PROP
Fixed-width fonts PHFONT FIXED

You can OR the flags together to obtain a suitable mask. The default
is PHFONT ALL FONTS (which is every option set).
The sample parameter sets the text string used to display a sample of
the selected font; if NULL the default of AaBbCcXxYyZz is used.
The modal dialog is constructed and the user may select a text font
using comboboxes for the family and size, and buttons for the style. A
sample of text using the font is dynamically updated.
The user may click a Cancel button or close the window to cancel the
selection, or click an OK button to accept it.

Returns:
A pointer to the new font string if one selected, NULL otherwise. This
string is obtained using the strdup() function, so the application
should free() it once finished with the font name.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

676 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtFontSelection()

See also:
PtFontSel in the Photon Widget Reference

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 677

PtForwardWindowEvent()  2005, QNX Software Systems
Forward a window event

Synopsis:
int PtForwardWindowEvent(
PhWindowEvent t const *window event );

Description:
This function forwards the provided window event to the window
manager.

Returns:
0 Success.

-1 The message couldn’t be forwarded, possibly because either

the Photon Manager or pwm wasn’t running.

Examples:
int give a window focus( PtWidget t *widget )
{
PhWindowEvent t WE;

if( !widget || !PtWidgetIsClassMember( widget, PtWindow ))

return -1;
memset( &WE, 0, sizeof (WE));
WE.event f = Ph WM FOCUS;
WE.rid = PtWidgetRid( widget );
WE.event state = Ph WM EVSTATE FOCUS;
return PtForwardWindowEvent( &WE );
}

Classification:
Photon

Safety
Interrupt handler No
continued. . .

678 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtForwardWindowEvent()

Safety
Signal handler No
Thread No

See also:
PhWindowEvent t, PtForwardWindowTaskEvent()
PtWindowFocus(), PtWindowToBack(), PtWindowToFront() in the
Photon Widget Reference
Window Management chapter of the Photon Programmer’s Guide.

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 679

PtForwardWindowTaskEvent()  2005, QNX Software Systems
Forward a window event, given a process ID

Synopsis:
int PtForwardWindowTaskEvent(
PhConnectId t task,
PhWindowEvent t const *evt);

Description:
This function is similar to PtForwardWindowEvent() — instead of
specifying the destination region ID in the message, the connection
ID of the task is specified. This ID is translated to the main window
for this task.
In addition, a special pseudo-event (Ph WM SUPERSELECT) is
recognized. This causes the window (and any child windows) to be
moved to the current console and brought in front of any other
windows. Also, the first nonblocked window is given focus.

Returns:
0 Success.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

680 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtForwardWindowTaskEvent()

See also:
PhGetConnectId(), PhGetConnectInfo(), PhWindowEvent t,
PtForwardWindowEvent()
PtWindowFocus(), PtWindowToBack(), PtWindowToFront() in the
Photon Widget Reference
Window Management chapter of the Photon Programmer’s Guide.

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 681

PtFrameSize()  2005, QNX Software Systems
Determine the size of the window frame borders

Synopsis:
void PtFrameSize( ulong t render,
int border size,
int *left border,
int *top border,
int *right border,
int *bottom border );

Description:
This function returns the size of the frame borders, based on the
rendering flags you pass in the render argument. You should pass the
same flags that were used to define the window.
For most windows, you can set border size to 0. But if your window
sets a border width (Pt ARG BORDER WIDTH), you should pass
that value instead.
The function sets the remaining arguments to the frame’s left, top,
right, and bottom borders. These values are in pixels.

Examples:
int
my setup( PtWidget t *widget, void *data,
PtCallbackInfo t *cbinfo )

{
int xoff, yoff, woff, hoff;
short x, y;
PtArg t args[3];
PhArea t *area, tarea;
PhRect t rect;

/* Note: This is a PhAB prerealize setup function

* for a dialog module
*/

/* ensure dialog is totally visible */

PtSetArg( &args[0], Pt ARG AREA, &area, 0 );
PtGetResources( widget, 1, &args );
tarea = *area;
PtFrameSize( Ph WM APP DEF RENDER, 0, &xoff, &yoff,
&woff, &hoff );

682 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtFrameSize()

PhWindowQueryVisible( 0, 0, 0, &rect );
if ( ( tarea.x + tarea.w + xoff + woff ) > rect.xLR )
tarea.x = rect.xLR - tarea.w - xoff - woff;
if ( ( tarea.y + tarea.h + yoff + hoff ) > rect.yLR )
tarea.y = rect.yLR - tarea.h - yoff - hoff;
if ( tarea.x < rect.xUL )
tarea.x = rect.xUL;
if ( tarea.y < rect.yUL )
tarea.y = rect.yUL;
if ( area->x != tarea.x || area->y != tarea.y ) {
PtSetArg( &args[0], Pt ARG AREA, &tarea, 0 );
PtSetResources( widget, 1, &args );
}

return( Pt CONTINUE );
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhWindowQueryVisible()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 683

PtGetAbsPosition()  2005, QNX Software Systems
Get the absolute position of a widget

Synopsis:
void PtGetAbsPosition( PtWidget t *widget,
short *x,
short *y );

Description:
This function gets the absolute position of a widget (i.e. the
coordinates of the upper left corner of the widget’s border). The
coordinates are returned in x and y.

☞ For a window, the x and y coordinates don’t include the frame that’s
added by the window manager. Windows don’t usually have borders.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtWidgetOffset()

684 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtGetControlFlags()
Get the flags from the Pt control structure

Synopsis:
int PtGetControlFlags( void );

Description:
This function returns the flags of the Pt control structure. The valid
Pt flag bits are:

Pt FEP PRESENT
An FEP is present.

Pt FEP QUERIED
A search for any existing FEPs has been done.

Pt IN EXPOSE
The widget library is currently processing an expose event.

Returns:
The control flags.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 685

PtGetParent()  2005, QNX Software Systems
Find the nearest widget with the same parent class

Synopsis:
PtWidget t *PtGetParent(
PtWidget t *widget,
PtWidgetClassRef t *parent class );

Description:
This function examines the specified widget’s hierarchy, and tries to
find the nearest widget in the hierarchy (including the specified
widget itself) that matches the specified parent class.

Returns:
A pointer to the matching widget, or NULL if an error occurs.

Examples:
PtWidget t *window;

// Get main window widget and make it a parent for drawing.

window = PtGetParent( widget, PtWindow );

PtSetParentWidget( window );
PgSetRegion( PtWidgetRid(window) );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

686 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtGetParent()

See also:
PtSetParentWidget(), PtWidgetParent()
“Ordering widgets” in the Creating Widgets in Application Code
chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 687

PtGetParentWidget()  2005, QNX Software Systems
Return the current default widget parent

Synopsis:
PtWidget t *PtGetParentWidget( void );

Description:
The PtGetParentWidget() function returns the current default widget
parent.

Returns:
A pointer to the current default parent.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtCreateWidget(), PtGetParent(), PtReParentWidget(),
PtSetParentWidget(), PtWidgetParent(),
“Ordering widgets” in the Creating Widgets in Application Code
chapter of the Photon Programmer’s Guide

688 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtGetRcvidPid()
Get the PID from a RCVID

Synopsis:
pid t PtGetRcvidPid( int rcvid );

Description:
This function should be used to obtain the process ID (PID) from the
receive ID (RCVID). It might be needed if a nonspecific input
procedure attaches a specific input procedure.

Returns:
The PID, or -1 on error.

Examples:
int general input proc( void *data, pid t rcvid,
void *msg, size t size)
{
PtAppAddInput( NULL, PtGetRcvidPid(rcvid),
function, data );
#if defined( QNXNTO )
MsgReplyv( rcvid, ... );
#else
Reply( rcvid, ... );
#endif
return Pt END;
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 689

PtGetRcvidPid()  2005, QNX Software Systems

See also:
PtAppAddInput()

690 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtGetResources()
Retrieve resource values for a widget

Synopsis:
int PtGetResources( PtWidget t *widget,
int n args,
PtArg t *args );

Description:
This function sets pointers to resource values within the specified
widget. The args array indicates which resources are desired, and
n args indicates the number of items in the args array.
You must initialize the args array with PtSetArg() or Pt ARG() before
calling PtGetResources(). The Pt type of a resource determines how
that resource should be set or queried. You use the Pt type when
setting a resource entry with PtSetArg().
For more information, see the Manipulating Resources in Application
Code chapter of the Photon Programmer’s Guide.

!
CAUTION: Because PtGetResources() returns pointers directly into
the internals of the widget, don’t modify those values directly. If you
wish to retrieve the value of a given resource and then modify that
value:

1 Get the resource.

2 Copy the resource to a temporary variable.

3 Modify the temporary variable.

4 Using the modified copy, set the resource.

Returns:
0 Success.

-1 An error occurred.

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 691

PtGetResources()  2005, QNX Software Systems

Examples:
Determine a widget’s color, and determine whether or not the widget
is highlighted:

PtArg t args[2];
PgColor t *color;
unsigned long *flags;
PtWidget t *widget;

PtSetArg( &args[0], Pt ARG FILL COLOR, &color, 0 );

PtSetArg( &args[1], Pt ARG FLAGS, &flags, 0 );
PtGetResources( widget, 2, args );

printf( "Color: %08lx Highlighted: %s\n", *color,

*flags & Pt HIGHLIGHTED ? "Yes":"No" );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtArg t, Pt ARG(), PtSetArg(), PtSetResources()
Manipulating Resources in Application Code chapter of the Photon
Programmer’s Guide.

692 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtGlobalFocusNext()
Give focus to next widget

Synopsis:
PtWidget t *PtGlobalFocusNext( PtWidget t *widget,
PhEvent t *event );

Description:
This function finds the currently focused widget in the same disjoint
widget (window, region, menu) as widget and moves the focus to the
next focusable widget.
The widget that’s given focus receives event as the reason. If event
isn’t provided, a NULL event is generated for you.

Returns:
The widget that was given focus, or NULL if no focusable widgets are
found.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtContainerGiveFocus(), PtContainerNullFocus(),
PtContainerFocusNext(), PtContainerFocusPrev(),
PtGlobalFocusNextContainer(), PtGlobalFocusNextFrom(),
PtGlobalFocusPrev(), PtGlobalFocusPrevFrom(),
PtGlobalFocusPrevContainer(), PtIsFocused()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 693

PtGlobalFocusNextContainer()  2005, QNX Software Systems
Give focus to another container’s widget

Synopsis:
PtWidget t *PtGlobalFocusNextContainer(
PtWidget t *widget,
PhEvent t *event );

Description:
This function finds the currently focused widget in the same disjoint
widget (window, region, menu) as widget and moves the focus to the
next focusable widget in a different container. The widget that’s given
focus will receive event as the reason.
If event isn’t provided, a NULL event will be generated for you.

Returns:
The widget that was given focus, or NULL if no focusable widgets are
found.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtContainerGiveFocus(), PtContainerNullFocus(),
PtContainerFocusNext(), PtContainerFocusPrev(),
PtGlobalFocusNext(), PtGlobalFocusNextFrom(),
PtGlobalFocusPrev(), PtGlobalFocusPrevFrom(),
PtGlobalFocusPrevContainer(), PtIsFocused()

694 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtGlobalFocusNextFrom()
Give focus to the next widget behind the specified widget

Synopsis:
PtWidget t *PtGlobalFocusNextFrom(
PtWidget t *widget,
PhEvent t *event );

Description:
Unlike PtGlobalFocusNext(), this function doesn’t find the currently
focused widget first. PtGlobalFocusNextFrom() moves the focus to
the next focusable widget after widget in the same disjoint widget
(window, region, menu) as widget.
The widget that’s given focus receives event as the reason. If event
isn’t provided, a NULL event is generated for you.

Returns:
The widget that was given focus, or NULL if no focusable widgets are
found.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtContainerGiveFocus(), PtContainerNullFocus(),
PtContainerFocusNext(), PtContainerFocusPrev(),
PtGlobalFocusNext(), PtGlobalFocusNextContainer(),

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 695

PtGlobalFocusNextFrom()  2005, QNX Software Systems

PtGlobalFocusPrev(), PtGlobalFocusPrevFrom(),
PtGlobalFocusPrevContainer(), PtIsFocused()

696 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtGlobalFocusPrev()
Give focus to the previous widget

Synopsis:
PtWidget t *PtGlobalFocusPrev( PtWidget t *widget,
PhEvent t *event );

Description:
This function finds the currently focused widget in the same disjoint
widget (window, region, menu) as widget and moves the focus to the
previous focusable widget.
The widget that’s given focus receives event as the reason. If event
isn’t provided, a NULL event is generated for you.

Returns:
The widget that was given focus, or NULL if no focusable widgets are
found.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtContainerGiveFocus(), PtContainerNullFocus(),
PtContainerFocusNext(), PtContainerFocusPrev(),
PtGlobalFocusNext(), PtGlobalFocusNextContainer(),
PtGlobalFocusNextFrom(), PtGlobalFocusPrevFrom(),
PtGlobalFocusPrevContainer(), PtIsFocused()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 697

PtGlobalFocusPrevContainer()  2005, QNX Software Systems
Give focus to widget in previous container

Synopsis:
PtWidget t *PtGlobalFocusPrevContainer(
PtWidget t *widget,
PhEvent t *event );

Description:
This function finds the currently focused widget in the same disjoint
widget (window, region, menu) as widget and moves the focus to the
previous focusable widget in another container. The widget that’s
given focus will receive event as the reason.
If event isn’t provided, a NULL event will be generated for you.

Returns:
The widget that was given focus, or NULL if no focusable widgets are
found.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtContainerGiveFocus(), PtContainerNullFocus(),
PtContainerFocusNext(), PtContainerFocusPrev(),
PtGlobalFocusNext(), PtGlobalFocusNextContainer(),
PtGlobalFocusNextFrom(), PtGlobalFocusPrev(),
PtGlobalFocusPrevFrom(), PtIsFocused()

698 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtGlobalFocusPrevFrom()
Give focus to widget previous to the specified widget

Synopsis:
PtWidget t *PtGlobalFocusPrevFrom(
PtWidget t *widget,
PhEvent t *event );

Description:
Unlike PtGlobalFocusPrev(), this function doesn’t find the currently
focused widget first. PtGlobalFocusNextFrom() will move the focus
to the first focusable widget previous to widget in the same disjoint
widget (window, region, menu) as widget.
The widget that’s given focus receives event as the reason. If event
isn’t provided, a NULL event is generated for you.

Returns:
The widget that was given focus, or NULL if no focusable widgets are
found.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtContainerGiveFocus(), PtContainerNullFocus(),
PtContainerFocusNext(), PtContainerFocusPrev(),
PtGlobalFocusNext(), PtGlobalFocusNextContainer(),

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 699

PtGlobalFocusPrevFrom()  2005, QNX Software Systems

PtGlobalFocusNextFrom(), PtGlobalFocusPrev(),
PtGlobalFocusPrevContainer(), PtIsFocused()

700 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtHit()
Identify a widget in the specified container

Synopsis:
PtWidget t *PtHit( PtWidget t *container,
unsigned n,
PhRect t const *rect );

Description:
This function returns container’s nth child widget whose extent
intersects with rect. The rect argument should be relative to
container’s basic widget canvas. PtHit() ignores unrealized or
procreated widgets.

Returns:
0 Success.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 701

PtHold()  2005, QNX Software Systems
Prevent visible repair of all widgets

Synopsis:
int PtHold( void );

Description:
This function prevents visible repair of all widgets until the
application makes a corresponding call to PtRelease().
A global hold count is incremented when PtHold() is called, and
decremented when PtRelease() is called. When the hold count
reaches 0, the widgets are repaired.
A global hold count of 0 simply means that the application doesn’t
want to prevent widgets from repairing themselves. The widgets
manage their own damage repair and may not take immediate action
even if the count is 0.

☞ Each damaged widget that has been held by PtHold() and then
released by PtRelease() is repaired separately.

PtHold() and PtRelease() affect all widgets while PtContainerHold()

and PtContainerRelease() prevent only child widgets of a container
from being repaired.

Returns:
The new value of the global hold count.

Examples:
See PtClearWidget().

Classification:
Photon

702 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtHold()

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtContainerHold(), PtContainerRelease(), PtFlush(), PtRelease()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 703

PtInflateBalloon()  2005, QNX Software Systems
Create a balloon widget

Synopsis:
PtWidget t *PtInflateBalloon( PtWidget t *win,
PtWidget t *me,
int position,
char const *string,
char const *font,
PgColor t fill,
PgColor t text color );

Description:
This function creates a label widget as a child of win. The widget is
placed according to position, relative to me. The string sting is
rendered inside the label widget using a text color of text color, and
the font specified in font. The widget itself is filled with the color
specified in fill.
Valid values for position include:

¯ Pt BALLOON RIGHT

¯ Pt BALLOON LEFT

¯ Pt BALLOON TOP

¯ Pt BALLOON BOTTOM

¯ Pt BALLOON INPLACE

Returns:
A pointer to the newly created balloon widget, or NULL if win isn’t a
disjoint widget (e.g. PtWindow, PtRegion, etc.) or me is NULL.

Classification:
Photon

704 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtInflateBalloon()

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 705

PtInit()  2005, QNX Software Systems
Initialize the widget library

Synopsis:
int PtInit( char const *name );

Description:
This function initializes the widget library. If no Photon channel is
currently attached, this function calls PhAttach() with the given
Photon server name (//2/dev/photon, for example). If there is a
current channel, PhAttach() isn’t called.
Once a channel is attached, PtInit() installs all the widgets supplied
by QNX Software Systems.

Returns:
0 Successful completion.

-1 An error occurred.

Examples:
See PtClearWidget().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

706 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtInit()

See also:
PhAttach()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 707

PtInputCallbackProcF t,
PtInputCallbackProc t  2005, QNX Software Systems
Pointer to an input callback function

Synopsis:
typedef int PtInputCallbackProcF t( void *, pid t,
void *, size t);
typedef PtInputCallbackProcF t *PtInputCallbackProc t;

Description:
These data types define pointers to input callback functions. The
PtInputCallbackProcF t type is the function type that the
PtInputCallbackProc t type points to. This allows you to do
something like this:

PtInputCallbackProcF t my input callback;

int my input callback( void *, pid t, void *, size t ) {

...
}

The compiler should detect any inconsistencies between the two

declarations of my input callback() and give you an error (which is
better than a “pointer mismatch” warning on the call to
PtAppAddInput()).

Classification:
Photon

See also:
PtAppAddInput()

708 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtIsFluxing()
Determine whether a container or its family is in flux

Synopsis:
int PtIsFluxing( PtWidget t *container );

Description:
This function determines whether container or any parent widget of
container is currently in flux.

Returns:
1 container’s family is in flux.

0 container’s family isn’t in flux.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtStartFlux(), PtEndFlux()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 709

PtIsFocused()  2005, QNX Software Systems
Determine to what degree a widget is focused

Synopsis:
int PtIsFocused( PtWidget t *widget );

Description:
This function returns a value indicating to what degree a widget is
focused.

Returns:
0 The widget isn’t focused.

1 The widget is on the focus branch.

2 The widget is the focus leaf.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtContainerFindFocus(), PtContainerFocusNext(),
PtContainerFocusPrev(), PtGlobalFocusNext(),
PtGlobalFocusNextFrom(), PtGlobalFocusPrev(),
PtGlobalFocusPrevFrom()

710 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtLabelWidgetCanvas()
Determine the PtLabel canvas for a widget

Synopsis:
PhRect t *PtLabelWidgetCanvas(
PtWidget t *widget,
PhRect t *canvas rect );

Description:
This function determines the canvas rectangle for the specified
widget’s PtLabel-class level. This canvas rectangle describes the
area inside PtWidget’s border, PtBasic’s margins, and PtLabel’s
margins.
The canvas rect argument should point to an instance of a PhRect t
structure; if you pass canvas rect as NULL, the function returns NULL.

Returns:
A pointer to the canvas of the PtBasic widget, or NULL if an error
occurred.

Examples:
Return the area inside PtWidget’s border:

PtWidgetCanvas( labelwidget, &rect);

Return the area inside PtWidget’s border and PtBasic’s margins:

PtBasicWidgetCanvas( labelwidget, &rect);

Return the area inside PtWidget’s border, PtBasic’s margins, and

PtLabel’s margins:

PtLabelWidgetCanvas( labelwidget, &rect);

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 711

PtLabelWidgetCanvas()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtLabelWidgetCanvas(), PtWidgetCanvas(), PtWidgetExtent()

712 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtMainLoop()
Implement an application main loop

Synopsis:
void PtMainLoop( void );

Description:
This is a convenience function that implements an application main
loop using PhEventNext() and PtEventHandler(). Background
processing (WorkProcs) and handling of non-Photon messages
(inputs) are also supported by this function.
PtMainLoop() allocates an event buffer and resizes it as necessary.
You can set the size yourself by calling PtResizeEventMsg().
To terminate normally, your applications should call exit() (see the C
Library Reference) within a callback function.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhEventNext(), PtAppAddInput(), PtAppAddWorkProc(),
PtEventHandler(), PtResizeEventMsg()
“Receiving QNX messages” in the Interprocess Communications and
Lengthy Procedures chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 713

PtMessageBox()  2005, QNX Software Systems
Pop up a message box

Synopsis:
int PtMessageBox( PtWidget t *parent,
char const *title,
char const *question,
char const *font,
char const *btn );

Description:
This function displays a message that blocks input to the specified
parent widget until the message has been acknowledged. If no parent
is specified, blocking won’t occur, but the message will persist until
it’s acknowledged. If specified, the parent must be a window.
This function returns immediately.

Returns:
0 Success.

-1 Failure occurred due to lack of memory.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

714 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtModalEnd()
Terminate modal-window processing

Synopsis:
void PtModalEnd( int hold count );

Description:
This function terminates a modal-processing loop that was initiated
by PtModalStart(). The hold count argument must be the count value
that was returned by PtModalStart().

Examples:
See PtModalStart().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtModalStart()
“Modal dialogs” in the “Lengthy operations” section of the
Interprocess Communication and Lengthy Operations chapter of the
Programmer’s Guide.

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 715

PtModalStart()  2005, QNX Software Systems
Initiate modal-window processing

Synopsis:
int PtModalStart ( void );

Description:
This function initiates modal processing. To do so, it holds the current
process loop so that another subloop can be started.
Once the subloop is complete, you must call PtModalEnd() to resume
processing of the initial process loop.

☞ If you want the parent or any windows in the application to refuse

input while the modal dialog is displayed, you need to block them
programmatically by setting the Pt BLOCKED flag.

Returns:
The hold count needed for PtModalEnd().

Examples:
/* Module to handle immediate responses */
#include "imports.h"
#include <Ph.h>
#include <Pt.h>
#include <photon/PtMessage.h>

void
askresponse( PtWidget t *, int *, PtCallbackInfo t *);

int AskQuestion( PtWidget t *parent, char *title,

char *question, char *font,
char *btn1, char *btn2, char *btn3,
int def btn )
{
int n = 0, block = 1, count;
int answer;
PtArg t args[15];
PtCallback t callback;
extern struct Pt ctrl Pt ;

callback.event f = askresponse;
callback.data = &answer;

716 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtModalStart()

/* initialize answer */
answer = 0;

if ( title ) {
PtSetArg( &args[n], Pt ARG MSG TITLE,
title, 0 ); n++;
}
if ( question ) {
PtSetArg( &args[n], Pt ARG MSG TEXT,
question, 0 ); n++;
}
if ( font ) {
PtSetArg( &args[n], Pt ARG MSG FONT,
font, 0 ); n++;
}
if ( btn1 ) {
PtSetArg( &args[n], Pt ARG MSG BUTTON1,
btn1, 0 ); n++;
}
if ( btn2 ) {
PtSetArg( &args[n], Pt ARG MSG BUTTON2,
btn2, 0 ); n++;
}
if ( btn3 ) {
PtSetArg( &args[n], Pt ARG MSG BUTTON3,
btn3, 0 ); n++;
}
PtSetArg( &args[n], Pt ARG MSG DEFAULT,
def btn, 0 ); n++;
PtSetArg( &args[n], Pt CB MSG BUTTON1,
&callback, 0 ); n++;
PtSetArg( &args[n], Pt CB MSG BUTTON2,
&callback, 0 ); n++;
PtSetArg( &args[n], Pt CB MSG BUTTON3,
&callback, 0 ); n++;
PtRealizeWidget( PtCreateWidget( PtMessage, NULL,
n, args ) );

/* loop until response received */

count = PtModalStart();
while( !answer )
PtProcessEvent( );
PtModalEnd( count );

return( answer );
}

STATIC void askresponse( PtWidget t *widget,

int *answer,

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 717

PtModalStart()  2005, QNX Software Systems

PtCallbackInfo t *cbinfo )
{

/* get rid of warning */

widget = widget;

switch( cbinfo->reason ) {

case Pt CB MSG BUTTON1:

*answer = 1;
break;

case Pt CB MSG BUTTON2:

*answer = 2;
break;

case Pt CB MSG BUTTON3:

*answer = 3;
break;

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtModalEnd(), PtProcessEvent()
“Modal dialogs” in the “Lengthy operations” section of the
Interprocess Communication and Lengthy Operations chapter of the
Programmer’s Guide.

718 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtNextTopLevelWidget()
Get a pointer to the next top-level widget

Synopsis:
PtWidget t * PtNextTopLevelWidget( PtWidget t *widget );

Description:
This function gets a pointer to the next top-level widget after the
given widget.

Returns:
A pointer to the next top-level widget, or NULL if there isn’t one.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtFindFocusChild(), PtGetParent(), PtValidParent(),
PtWidgetParent(), PtWidgetSkip()
“Ordering widgets” in the Creating Widgets in Application Code
chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 719

PtPositionMenu()  2005, QNX Software Systems
Set a menu’s position

Synopsis:
void PtPositionMenu( PtWidget t *menu,
PhEvent t *event );

Description:
This function sets the Pt ARG POS resource of the provided menu
widget. How the function sets this resource is determined by the type
of its parent and the specified event.
If the provided menu is a child of a PtMenuButton widget, the menu
is positioned relative to that menu button (to the right or below,
depending on the menu button’s flags).
If the provided menu isn’t a child of a PtMenuButton widget and the
specified event is a pointer event, the menu is positioned at the event’s
position. If the event isn’t a pointer event and the menu has a parent,
the menu is positioned at the upper-left corner of that parent.
If the provided menu isn’t a child of a PtMenuButton widget and the
specified event isn’t a pointer event, the menu is positioned at 0,0.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

720 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtPrintSelection()
Display a modal dialog for selecting print options

Synopsis:
int PtPrintSelection( PtWidget t *parent,
PhPoint t const *pos,
const char *title,
PpPrintContext t *context,
unsigned flags);

Description:
This function displays a modal dialog allowing the user to select print
options and initiate printing. The dialog is parented off the parent
widget, which may be NULL; if non-NULL, that parent widget is
blocked and its cursor is changed to reflect this.
The dialog is positioned according to the pos parameter: if NULL, the
dialog is centered on the screen; if parent is NULL, the dialog is
placed at the absolute coordinates of pos; otherwise it’s placed at the
relative offset of pos within parent.
The title of the dialog is given by title; if this is NULL a default title of
“Select Printer” is used.
The context parameter is a Print Context that was created by the
PpPrintCreatePC() function. This context must be supplied and is
filled in with details of the selected printer:

¯ At the start of this function, the print context is examined and any
fields modified at or below the INITIAL PC level are propagated
into the PtPrintSel.

¯ The context is updated (at the INTERACTIVE PC level) with any

changes made to the widget by the user.

The flags parameter is used to enable or disable parts of the user

interface. Valid flags are:

Pt PRINTSEL ALL PANES

If this flag is set, all the panes of the print selector are displayed;
if cleared, the Print Range and Copies panes aren’t displayed.

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 721

PtPrintSelection()  2005, QNX Software Systems

Pt PRINTSEL PROP APP

If set, the Properties button is enabled.
Pt PRINTSEL NO PAGE RANGE
If this flag is set, you can’t specify a range of pages to print.
Pt PRINTSEL NO SELECT RANGE
If this is set, the Selection button in the Page Range pane is
disabled.
Pt PRINTSEL NO COPIES
If this flag is set, the Number of Copies field is disabled.

Pt PRINTSEL NO COLLATE
If this is set, the Collate Method buttons are disabled.
Pt PRINTSEL DFLT LOOK
Use the default look (equivalent to Pt PRINTSEL ALL PANES |
Pt PRINTSEL PROP APP | Pt PRINTSEL NO SELECT RANGE)

You can OR the flags together to obtain a suitable mask.

The user may click one of these buttons:

¯ Print — initiate printing

¯ Preview — view the material to be printed

¯ Cancel — cancel the operation

Returns:
An integer that indicates which button was pressed:

¯ Pt PRINTSEL PRINT

¯ Pt PRINTSEL PREVIEW

¯ Pt PRINTSEL CANCEL

722 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtPrintSelection()

The do preview member of the print context is also set to indicate

whether Print or Preview was selected. This means that the context
can be passed to the printing function, which will spawn the
print-preview application if necessary.

Examples:
See PpPrintStart().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PpPrintClose(), PpPrintCreatePC(), PpPrintGetPC(),
PpPrintNewPage(), PpPrintOpen(), PpPrintReleasePC(),
PpPrintSetPC(), PpPrintStart(), PpPrintStop(), PpPrintWidget()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 723

PtProcessEvent()  2005, QNX Software Systems
Standard Photon event-handling function

Synopsis:
void PtProcessEvent( void );

Description:
This function is used primarily for modal-dialog-event handling.
If a Photon event is pending, this function processes the event and
returns. If no event is pending, or if no work procedure has been
defined, the function puts the application into REPLY-blocked mode.

Examples:
See PtModalStart().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

724 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtPulseArmFd()
Arm a pulse for delivery from a process with a given file descriptor

Synopsis:
PtPulseMsgId t *PtPulseArmFd( PtAppContext t app,
pid t pulse,
int fd,
PtPulseMsg t *msg );

Description:
This function arms a pulse and creates a “pulse message” to be sent to
another process. The other process can use the pulse message and
PtPulseDeliver() to send the pulse.
The app argument is the address of the application context, a structure
that manages all the data associated with this application. For Photon
1.1x, this must be specified as NULL, so that the default context is
used.
The pulse argument is a pulse ID returned by PtAppCreatePulse().
The fd argument is a file descriptor associated with the process that’s
going to deliver the pulse back to this process.
The msg argument points a pulse message that’s created by the
function. You’ll need to send it to the process that’s going to deliver
the pulse.
When the pulse is no longer needed, you should call PtPulseDisarm()
to release any resources that PtPulseArmFd() allocated (e.g. a virtual
proxy in QNX 4).

Returns:
A pointer to the pulse message ID, or NULL if an error occurred.

Classification:
Photon

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 725

PtPulseArmFd()  2005, QNX Software Systems

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtAppCreatePulse(), PtAppDeletePulse(), PtAppPulseTrigger(),
PtChannelCreate(), PtPulseArmPid(), PtPulseDeliver(),
PtPulseDisarm()
Interprocess Communication and Lengthy Operations in the
Programmer’s Guide

726 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtPulseArmPid()
Arm a pulse for delivery from a process with a given pid

Synopsis:
PtPulseMsgId t *PtPulseArmPid( PtAppContext t app,
pid t pulse,
pid t pid,
PtPulseMsg t *msg);

Description:
This function arms a pulse and creates a “pulse message” to be sent to
another process. The other process can use the pulse message and
PtPulseDeliver() to send the pulse back to this process.
The app argument is the address of the application context, a structure
that manages all the data associated with this application. For Photon
1.1x, this must be specified as NULL, so that the default context is
used.
The pulse argument is a pulse ID returned by PtAppCreatePulse().
The pid is a process ID of a process on the same node as this process,
or a virtual circuit ID for a process on a different node. In either case,
this argument identifies the process that will deliver the pulse to the
process calling this function.

☞ If you also have a file descriptor associated with the process that’s
going to deliver the pulse, you should use PtPulseArmFd(), to arm the
pulse.

The msg argument points a pulse message that’s created by the

function. You’ll need to send it to the process that’s going to deliver
the pulse.
When the pulse is no longer needed, you should call
PtPulseDisarm(), passing it the pulse-message ID returned by
PtPulseArmPid(). Doing this releases any resources that
PtPulseArmPid() allocated (e.g. a virtual proxy in QNX 4).

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 727

PtPulseArmPid()  2005, QNX Software Systems

Returns:
A pointer to the pulse message ID, or NULL if an error occurs.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtAppCreatePulse(), PtAppDeletePulse(), PtAppPulseTrigger(),
PtChannelCreate(), PtPulseArmFd(), PtPulseDeliver(),
PtPulseDisarm()
Interprocess Communication and Lengthy Operations in the Photon
Programmer’s Guide

728 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtPulseDeliver()
Deliver a pulse to a process

Synopsis:
int PtPulseDeliver( pid t rcvid,
PtPulseMsg t const *pulse );

Description:
This function sends a Photon pulse to a process. Before this function
can be called by the process that’s delivering the pulse, the process
that’s going to receive it must:

¯ Create the pulse by calling PtAppCreatePulse().

¯ Arm it by calling PtPulseArmFd() or PtPulseArmPid(), creating a

pulse message.

¯ Send it (by some method) to the process that’s going to deliver the
pulse.

The rcvid argument to PtPulseDeliver() is the ID obtained when the

pulse deliverer received the pulse message from the pulse recipient.
The pulse argument is a pointer to the pulse message created by
PtPulseArmFd() or PtPulseArmPid().

☞ A non-Photon application can call this function; there’s a macro

version of it defined in <photon/PtPulseDeliver.h>. If you use
it, you won’t have to link your application with the Photon libraries.

Returns:
A nonnegative number, or -1 if an error occurs — errno indicates the
type of error detected.

Classification:
Photon

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 729

PtPulseDeliver()  2005, QNX Software Systems

Safety
Interrupt handler No
Signal handler Yes
Thread Yes

Caveats:
The version of this function defined in
<photon/PtPulseDeliver.h> is a macro.

See also:
PtAppCreatePulse(), PtAppDeletePulse(), PtAppPulseTrigger(),
PtChannelCreate(), PtPulseArmFd(), PtPulseArmPid(),
PtPulseDisarm()
Interprocess Communication and Lengthy Operations in the Photon
Programmer’s Guide

730 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtPulseDisarm()
Release resources allocated for a pulse

Synopsis:
void PtPulseDisarm( PtPulseMsgId t *mid );

Description:
This function releases any resources that PtPulseArmFd() or
PtPulseArmPid() allocated (e.g. a virtual proxy in QNX 4). You
should call PtPulseDisarm() when the pulse is no longer needed. The
mid argument points to a pulse message ID returned by
PtPulseArmFd() or PtPulseArmPid().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtAppCreatePulse(), PtAppDeletePulse(), PtAppPulseTrigger(),
PtChannelCreate(), PtPulseArmFd(), PtPulseArmPid(),
PtPulseDeliver()
Interprocess Communication and Lengthy Operations in the Photon
Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 731

PtQuerySystemInfo()  2005, QNX Software Systems
Query the system for information

Synopsis:
PhSysInfo t * PtQuerySystemInfo(
PtWidget t *widget,
PhSysInfo t *sys ptr );

Description:
This function queries the system for information on the given widget:

¯ system bandwidth

¯ graphics drivers and their capabilities

¯ pointing devices

¯ keyboard devices.

The information is stored in the buffer pointed to by sys ptr.

This function calls PhQuerySystemInfo(), but buffers the information,
reducing the number of messages sent to the Photon server. It calls
PhQuerySystemInfo() if the data has been made invalid since the
previous call because:

¯ the window containing the widget was moved or resized

¯ you switched consoles

¯ a graphics or input driver was started or stopped

¯ someone started or stopped dittoing you

¯ ...

The rectangular area passed to PhQuerySystemInfo() is the extent of

the window containing the widget (or the widget itself if it’s a
window).

732 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtQuerySystemInfo()

Returns:
A pointer to the PhSysInfo t structure passed to the function, or
NULL if an error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhQuerySystemInfo()
For a description of PhSysInfo t and the information it provides,
see PhT.h and “System information” in the Regions chapter of the
Programmer’s Guide.

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 733

PtRealizeWidget()  2005, QNX Software Systems
Initialize a widget and its children

Synopsis:
int PtRealizeWidget( PtWidget t *widget );

Description:
This function initializes a widget and its children, making them
visible to the user and possibly making them interactive. To create a
hierarchy of widgets, you typically make successive calls to
PtCreateWidget(), and then call PtRealizeWidget(), passing it the root
of the hierarchy.

☞ Some widgets (for example, menus) have Pt DELAY REALIZE set in

their Pt ARG FLAGS. Such delay-realized widgets aren’t visibly
rendered when their ancestors are realized. Although they’re present
in the hierarchy, delay-realized widgets become visible only when the
application realizes them specifically with a call to PtRealizeWidget().
An application might do this, for example, if the user requested it to
activate a menu.

Returns:
0 Success.

-1 Out of memory, or an invalid widget class was specified.

Examples:
See PtContainerGiveFocus() and PtClearWidget().

Classification:
Photon

Safety
Interrupt handler No
continued. . .

734 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtRealizeWidget()

Safety
Signal handler No
Thread No

See also:
PtCreateWidget(), PtDestroyWidget(), PtUnrealizeWidget()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 735

PtReattach()  2005, QNX Software Systems
Send an application through the jump gate

Synopsis:
int PtReattach( char *device );

Description:
This function provides Photon’s “jump gate” mechanism — it
unrealizes all top-level widgets in an application, disconnects them
from the current Photon server, connects to the Photon server
indicated by device (e.g. //88/dev/photon), and realizes the
top-level widgets at the new location.
As a result, the PHOTON environment variable is set and the user
interface is rehosted to the new Photon server.

Returns:
0 Success.

-1 Unable to connect to device due to insufficient memory.

Examples:
int transport edit activate( PtWidget t *widget,
void *data, PtCallbackInfo t cbinfo );
{
PtTextCallback t *tcb=cbinfo->cbdata;
PtReattach( tcb->text );
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

736 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtReattach()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 737

PtRectIntersect()  2005, QNX Software Systems
Find the intersection of two rectangles

Synopsis:
int PtRectIntersect( PhRect t *rect1,
PhRect t const *rect2 );

Description:
This function finds the intersection of two rectangles. If rectangles
rect1 and rect2 intersect, this function sets rect1 to that intersection.

Returns:
≠0 There was an intersection.

0 There was no intersection.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

738 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtRectUnion()
Determine a bounding box for two rectangles

Synopsis:
int PtRectUnion( PhRect t *rect1,
PhRect t const *rect2 );

Description:
This function changes the rectangle pointed to by rect1 to a rectangle
that encompasses rect2 using rect1 as a starting point. The result is a
bounding box for the two original rectangles.

Returns:
0 The resulting rectangle is inverted (only possible if inverted
rectangles are provided as parameters i.e. ul > lr ).

1 The resulting rectangle is a regular rectangle (i.e. ul < lr).

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 739

PtRelease()  2005, QNX Software Systems
Decrement the global widget hold count

Synopsis:
int PtRelease( void );

Description:
This function decrements the global widget hold count, which was
previously incremented by a call to PtHold(). When the count reaches
0, the widgets are repaired.

☞ This function is the same as PtUpdate().

PtHold() and PtRelease() affect all widgets, while PtContainerHold()

and PtContainerRelease(), prevent only child widgets of a container
from being repaired.

Returns:
The new value of the global hold count.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtContainerHold(), PtContainerRelease(), PtFlush(), PtHold()

740 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtRemoveCallback()
Remove a single callback entry from a callback list

Synopsis:
void PtRemoveCallback( PtWidget t *widget,
unsigned long callback type,
PtCallbackF t *callback,
void *data );

Description:
This function removes the first callback entry that matches callback
and data. It removes the entry from the callback type callback list that
belongs to widget.

☞ Some types of callback resources have special routines that you

should use instead of this one:

Pt CB HOTKEY
PtRemoveHotkeyHandler()

Pt CB RAW PtRemoveEventHandler() or
PtRemoveEventHandlers()

The callback argument points to a function that takes this form:

int (*callback)( PtWidget t *, void *,

PtCallbackInfo t *)

Examples:
See PtAddCallback().

Classification:
Photon

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 741

PtRemoveCallback()  2005, QNX Software Systems

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtAddCallback(), PtAddCallbacks(), PtRemoveCallbacks(),
PtRemoveEventHandler(), PtRemoveEventHandlers(),
PtRemoveHotkeyHandler()
Creating Widgets in Application Code chapter of the Photon
Programmer’s Guide

742 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtRemoveCallbacks()
Remove several callback entries from a callback list

Synopsis:
void PtRemoveCallbacks(
PtWidget t *widget,
unsigned long callback type,
PtCallback t const *callback defs,
unsigned int num callbacks );

Description:
This function removes the first callback entries that exactly match an
entry in the callback defs array. It removes these entries from the
callback type callback list that belongs to widget. The num callbacks
argument specifies the length of the array.

☞ Some types of callback resources have special routines that you

should use instead of this one:

Pt CB HOTKEY
PtRemoveHotkeyHandler()

Pt CB RAW PtRemoveEventHandler() or
PtRemoveEventHandlers()

Examples:
See PtAddCallback().

Classification:
Photon

Safety
Interrupt handler No
continued. . .

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 743

PtRemoveCallbacks()  2005, QNX Software Systems

Safety
Signal handler No
Thread No

See also:
PtAddCallback(), PtAddCallbacks(), PtRemoveCallback(),
PtRemoveEventHandler(), PtRemoveEventHandlers(),
PtRemoveHotkeyHandler()
Creating Widgets in Application Code chapter of the Photon
Programmer’s Guide

744 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtRemoveData()
Remove a link from a data chain

Synopsis:
int PtRemoveData( PtDataHdr t **ptr,
long type,
long subtype );

Description:
This function removes a link from the ptr data chain. If a remove
function is provided, it’s called prior to the release of the node and
data:

¯ If the remove function returns Pt END, the node shouldn’t be

removed, no action is taken, and PtRemoveData() returns EOK.

¯ If the remove function returns Pt CONTINUE, the data is freed.

¯ It the remove function returns Pt END or Pt HALT, the data isn’t be

freed here as it may have been freed by the remove function.

Returns:
-1 The data wasn’t found.

Pt CONTINUE
The data was found and released.

Pt HALT The data was found, the node was released, and the data
was taken care of by the remove function.

Pt END The node wasn’t removed; refused by the remove

function.

Classification:
Photon

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 745

PtRemoveData()  2005, QNX Software Systems

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtAddData(), PtFindData(), PtFindNextData(), PtUnlinkData()

746 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtRemoveEventHandler()
Remove a single event-handler entry from a widget

Synopsis:
void PtRemoveEventHandler(
PtWidget t *widget,
unsigned long event mask,
PtCallbackF t *callback,
void *data );

Description:
This function removes the first callback entry that matches
event mask, callback, and data. It removes the entry from the
Pt CB RAW callback list that belongs to widget
The callback argument points to a function that takes this form:

int (*callback)(PtWidget t *, void *, PtCallbackInfo t *)

Examples:
See PtAddEventHandler().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 747

PtRemoveEventHandler()  2005, QNX Software Systems

See also:
PtAddEventHandler(), PtRemoveCallback(), PtRemoveCallbacks(),
PtRemoveEventHandlers(), PtRemoveHotkeyHandler()

748 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtRemoveEventHandlers()
Remove several event-handler entries from a widget

Synopsis:
void PtRemoveEventHandlers(
PtWidget t *widget,
PtRawCallback t const *callback defs,
int num handlers );

Description:
This function removes the first handler entries that exactly match an
entry in the callback defs array. It removes the entries from the
Pt CB RAW callback list that belongs widget. The num handlers
argument specifies the length of the array.
The PtRawCallback t structure is defined in PtT.h.

Examples:
See PtAddEventHandler().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtAddEventHandlers(), PtRemoveCallback(), PtRemoveCallbacks(),
PtRemoveEventHandler(), PtRemoveHotkeyHandler()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 749

PtRemoveHotkeyHandler()  2005, QNX Software Systems
Remove a single hotkey handler entry from a widget

Synopsis:
void PtRemoveHotkeyHandler(
PtWidget t *widget,
unsigned key sym cap,
unsigned key mods,
short flags,
void *data,
PtCallbackF t *callback );

Description:
This function removes the specified callback if the callback matches
key sym cap, key mods, flags, data, and callback. The function
removes the callback from the Pt CB HOTKEY callback list that
belongs to widget.
The callback argument points to a function that takes this form:

int (*callback)(PtWidget t *, void *, PtCallbackInfo t *)

Examples:
See PtAddHotkeyHandler().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

750 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtRemoveHotkeyHandler()

See also:
PtAddHotkeyHandler(), PtRemoveCallback(), PtRemoveCallbacks(),
PtRemoveEventHandler(), PtRemoveEventHandlers(),
PtRemoveHotkeyHandler()
“Hotkey callbacks” in the Editing Resources and Callbacks in PhAB
chapter of the Photon Programmer’s Guide.

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 751

PtReParentWidget()  2005, QNX Software Systems
“Reparent” a widget to a new container

Synopsis:
int PtReParentWidget( PtWidget t *widget,
PtWidget t *parent );

Description:
This function takes the specified widget from its current parent and
gives it to the specified parent. The parent must be a container widget.

Returns:
0 Successful completion.

-1 The widget couldn’t be re-parented.

Examples:
PtWidget t *label, *window1, *window2;

/* create widget within window1 */

...
label = PtCreateWidget( PtLabel, window1, 5, args );

/* use widget within window1 */

...

/* re-parent label to window2 */

PtReParentWidget( label, window2 );

/* use widget within window2 */

...

Classification:
Photon

Safety
Interrupt handler No
continued. . .

752 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtReParentWidget()

Safety
Signal handler No
Thread No

See also:
PtCreateWidget(), PtFindGuardian(), PtGetParent(), PtValidParent(),
PtWidgetParent()
“Ordering widgets” in the Creating Widgets in Application Code
chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 753

PtReRealizeWidget()  2005, QNX Software Systems
Force a widget to unrealize and then rerealize itself

Synopsis:
int PtReRealizeWidget( PtWidget t *widget );

Description:
This function forces the specified widget and all its descendants to
unrealize and rerealize themselves.

☞ This function is heavy handed, so use it sparingly. As we add more

advanced geometry negotiation to the widget engine, this function
will become obsolete.

Returns:
0 Successful completion.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtRealizeWidget(), PtUnrealizeWidget()

754 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtResizeEventMsg()
Resize the event buffer

Synopsis:
int PtResizeEventMsg( PtAppContext t app,
int msg size );

Description:
This function resizes the Photon event buffer, which receives all
events on behalf of a Photon application. Using this function to
increase the acceptable message size allows larger non-Photon
messages to be received by the Photon application without requiring
Readmsgmx() (see the C Library Reference).

☞ PtResizeEventMsg() won’t reduce the message buffer beyond a

certain minimum size. This is so that the widget library will continue
to function.

The app argument is the address of the application context, a structure

that manages all the data associated with this application. For Photon
1.1x, this must be specified as NULL, so that the default context is
used.

Returns:
0 Successful completion.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 755

PtResizeEventMsg()  2005, QNX Software Systems

See also:
“Receiving QNX messages” in the Interprocess Communications and
Lengthy Procedures chapter of the Photon Programmer’s Guide

756 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtSendEventToWidget()
Give an event to a widget

Synopsis:
int PtSendEventToWidget( PtWidget t *widget,
PhEvent t *event );

Description:
This function allows an event to be given directly to any widget for
processing.

☞ The widget expects the event to be followed immediately by the

associated set of rectangles and event data. See the example below.

Returns:
0 Successful completion.

-1 An error occurred.

Examples:
// Send a Phantom release event to a widget.

Phantom( PtWidget t *widget, PhEvent t *event )

{
struct{
PhEvent t event;
PhRect t rect;
PhPointerEvent t pevent;
} new event;

memset( &new event.rect, -1 ,

sizeof( new event.rect ) );

if( event ) {
new event.event = *event;
}

new event.event.processing flags = Ph FAKE EVENT;

new event.event.type = Ph EV BUT RELEASE;
new event.event.subtype = Ph EV RELEASE PHANTOM;;
new event.pevent.click count = 1;
new event.pevent.buttons = Ph BUTTON SELECT;
new event.event.num rects = 1;

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 757

PtSendEventToWidget()  2005, QNX Software Systems

PtSendEventToWidget( widget,
(PhEvent t *) &new event);
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhEventEmit()

758 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtSetAreaFromExtent()
Set an area based on the extent of a widget

Synopsis:
PhArea t * PtSetAreaFromExtent(
PtWidget t *widget,
PhRect t const *extent rect,
PhArea t *area);

Description:
This function sets area to an area that would produce the extent
extent rect, given the attributes, borders, etc. of widget.

☞ The area argument must be provided and have its own storage. This
function doesn’t allocate any memory.

Returns:
A pointer to the area argument, or NULL if an error occurred.

Examples:
// Change widget so its extent will be {5,5,25,15}.
PhRect t extent = { 5,5,25,15 };
PhArea t area;

// Produce area required for widget’s extent

// to match "extent."

PtSetAreaFromExtent( widget, &extent, &area);

PtSetArg( &argt, Pt ARG AREA, &area, 0 );
PtSetResources( widget, 1, &argt );

Classification:
Photon

Safety
Interrupt handler No
continued. . .

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 759

PtSetAreaFromExtent()  2005, QNX Software Systems

Safety
Signal handler No
Thread No

See also:
PtSetAreaFromWidgetCanvas()

760 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtSetAreaFromWidgetCanvas()
Set an area based on the canvas of a widget

Synopsis:
PhArea t * PtSetAreaFromWidgetCanvas(
PtWidget t *widget,
PhRect t const *canvas rect,
PhArea t *area)

Description:
This function sets area to an area that produces a widget canvas of
canvas rect, given the attributes, borders, etc. of widget.

☞ The area argument must be provided and have its own storage. This
function doesn’t allocate any memory.

Returns:
A pointer to the area argument, or NULL if an error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtSetAreaFromExtent()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 761

PtSetArg()  2005, QNX Software Systems
Build argument lists for widgets

Synopsis:
PtSetArg( PtArg t *arg,
long type,
long value,
long len );

Description:
This macro builds argument lists to be used with PtCreateWidget(),
PtSetResources(), and PtGetResources().

☞ ¯ If the values don’t need to be calculated at runtime, you might be

able to use Pt ARG() instead to initialize the argument list.

¯ A common mistake is to think that this macro actually sets the

resources. It doesn’t; be sure to call PtCreateWidget(),
PtSetResources(), or PtGetResources().

The arg argument is normally part of an array of PtArg t data

structures. The type argument contains the resource manifest and
value contains the value of the argument being passed. The way the
len argument is used depends on the resource type.
For information on getting and setting resources, see the
Manipulating Resources in Application Code chapter of the Photon
Programmer’s Guide.

Examples:
PtArg t args[4];
PhPoint t pos = { 100, 100 };

/* Position the widget at (100,100) */

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

/* Make its primary color blue; in this case, blue text */

PtSetArg( &args[1], Pt ARG COLOR, Pg BLUE, 0 );

/* Set the string drawn with the widget */

762 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtSetArg()

PtSetArg( &args[2], Pt ARG TEXT STRING, "Button", 0 );

/* Place the button widget in the widget hierarchy */

PtCreateWidget( PtButton, NULL, 3, args );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtArg t, Pt ARG(), PtGetResources(), PtSetResources(),
PtCreateWidget()
Manipulating Resources in Application Code chapter of the Photon
Programmer’s Guide.

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 763

PtSetParentWidget()  2005, QNX Software Systems
Set the current parent widget

Synopsis:
PtWidget t *PtSetParentWidget( PtWidget t *widget );

Description:
This function sets the current parent widget. Some widget classes (for
example, windows, lists and menus) call this function when they’re
created.

☞ Widgets that belong to the PtContainer class become the current

parent widget when created. If you’re creating multiple
PtContainer-class widgets, you must ensure that each one is placed
in the correct container.
To do this, either call PtSetParentWidget() or specify the appropriate
widget in the parent argument to PtCreateWidget().
If the widget argument is NULL and you then call PtCreateWidget()
with a NULL parent argument, the new widget has no parent.

Returns:
A pointer to the previous parent widget, or NULL if there is none.

Examples:
See PtWidgetChildBack().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

764 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtSetParentWidget()

See also:
PtCreateWidget(), PtFindGuardian(), PtGetParent(),
PtGetParentWidget(), PtReParentWidget(), PtValidParent(),
PtWidgetParent()
“Ordering widgets” in the Creating Widgets in Application Code
chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 765

PtSetResources()  2005, QNX Software Systems
Set resources for a widget

Synopsis:
int PtSetResources( PtWidget t *widget,
int n args,
PtArg t const *args );

Description:
This function sets resources for the specified widget. The args array
indicates which resources to set, and n args indicates the number of
items in the args array. Before calling this function, you must
initialize the args array with PtSetArg() or Pt ARG().
For more information, see the Manipulating Resources in Application
Code chapter of the Photon Programmer’s Guide.
If the widget has been realized, changing its resources may change
how it appears on the screen.

Returns:
0 At least one of the given resources was applied to the widget.

-1 The widget wasn’t modified because it doesn’t contain the

given resources or the values of the resources were the same as
those already stored in the widget.

☞ A return code of 0 doesn’t necessarily mean that all the resources

were successfully set. The only way to be sure that a resource was set
is to set it, then get it and compare the values.

Examples:
Turn the widget blue and highlight it:
PtArg t args[2];
PtWidget t *widget;

PtSetArg( &args[0], Pt ARG FILL COLOR, Pg BLUE, 0 );

PtSetArg( &args[1], Pt ARG FLAGS,

766 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtSetResources()

Pt HIGHLIGHTED, Pt HIGHLIGHTED );
PtSetResources( widget, 2, args );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtArg t, Pt ARG(), PtGetResources(), PtSetArg()
Manipulating Resources in Application Code chapter of the Photon
Programmer’s Guide.

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 767

PtSignalProcF t, PtSignalProc t  2005, QNX Software
Systems
Pointer to a signal-handling function

Synopsis:
typedef int PtSignalProcF t( int, void *);
typedef PtSignalProcF t *PtSignalProc t;

Description:
These data types define pointers to signal-handling functions. The
PtSignalProcF t type is the function type that the
PtSignalProc t type points to. This allows you to do something
like this:

PtSignalProcF t my signal proc;

int my signal proc( int, void * ) {

...
}

The compiler should detect any inconsistencies between the two

declarations of my signal proc() and give you an error (which is
better than a “pointer mismatch” warning on the call to
PtAppAddSignalProc()).

Classification:
Photon

See also:
PtAppAddSignalProc(), PtAppRemoveSignal(),
PtAppRemoveSignalProc()
Interprocess Communication in the Photon Programmer’s Guide

768 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtSpawn()
Spawn a new process

Synopsis:
pid t PtSpawn( const char *cmd,
const char * const *argv,
const char * const *env,
const PtSpawnOptions t *opt,
PtSpawnCbF t *cb,
void *data,
PtSpawnCbId t **csp );

Description:
This function spawns a new process and optionally installs a callback
that’s called when the child process terminates. The arguments are as
follows:

cmd The program to be started. If it doesn’t contain a

slash, directories listed in the PATH environment
variable are searched.

argv A pointer to an argument vector. The last member of

argv must be a NULL pointer.

env Environment variables for the new process. If it’s

NULL, the value of the global variable extern char
**environ is used.

opt A pointer to a PtSpawnOptions t structure that

can be used to specify some extra details of how the
child should be spawned.

Under QNX 4, PtSpawnOptions t is the same as

QNX 4 struct qnx spawn globs (see
qnx spawn options in the C Library Reference).
Under Neutrino, PtSpawnOptions t consists of:
Neutrino
iov An fd-redirection array.

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 769

PtSpawn()  2005, QNX Software Systems

options A structure of type inheritance (see

spawn() in the Neutrino Library Reference).

If opt is NULL, the function uses the defaults

specified in

extern const PtSpawnOptions t PtSpawnDefaults;

If you want to specify a non-NULL value for opt, it’s

a good idea to modify a copy of the default structure.
For example:

PtSpawnOptions t my opts;
my opts = PtSpawnDefaults;
my opts.iov[1] = fd; // Redirect stdout

cb and data A callback to be called after the child process

terminates, and data to pass to the callback.
PtSpawnCbF t is a function type:

typedef void PtSpawnCbF t( void *data,

int status );

If cb isn’t NULL, PtSpawn() attaches a signal handler

for SIGCHLD that calls waitpid() to determine
whether the child process has terminated. If waitpid()
succeeds, the function specified by cb is called, and
the signal handler is removed.
If cb is NULL, PtSpawn() doesn’t attach any signal
handlers or call waitpid().
If you don’t need a callback but you also don’t want
to have to worry about zombie processes, specify cb
as PtSpawnNoCb — it’s an empty callback function
defined in the library.

770 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtSpawn()

csp If non-NULL, the function stores in *csp a pointer to

a control structure that can be later used to change or
remove the callback. See PtSpawnSetCallback() and
PtSpawnDeleteCallback().

☞ This control structure exists only until the termination callback is

called; don’t call PtSpawnSetCallback() or PtSpawnDeleteCallback()
after the callback has been called.

If cb is NULL but csp isn’t, no callback is attached, and *csp is set to

NULL.

Returns:
The process ID of the spawned process, or -1 on error.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtSpawnSetCallback(), PtSpawnDeleteCallback(), PtSpawnWait()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 771

PtSpawnDeleteCallback()  2005, QNX Software Systems
Remove a child-termination callback

Synopsis:
void PtSpawnDeleteCallback( PtSpawnCbId t *cs );

Description:
This function can be used to remove a callback function for a child
process created by a previous call to PtSpawn(). The cs argument is
the control structure created by that call to PtSpawn() and returned via
the csp argument.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtSpawn(), PtSpawnSetCallback(), PtSpawnWait()

772 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtSpawnSetCallback()
Change the callback in a PtSpawn() control structure

Synopsis:
void PtSpawnSetCallback( PtSpawnCbId t *cs,
PtSpawnCbF t *cb,
void *data );

Description:
This function can be used to specify a new callback function to be
called when a child process created by a previous call to PtSpawn()
terminates. The cs argument is the control structure created by that
call to PtSpawn() and returned via the csp argument.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtSpawn(), PtSpawnDeleteCallback(), PtSpawnWait()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 773

PtSpawnWait()  2005, QNX Software Systems
Spawn a process and wait for its termination

Synopsis:
int PtSpawnWait( const char *cmd,
const char **argv,
const char **env,
const PtSpawnOptions t *opt,
pid t *pidp );

Description:
This function spawns a new process and waits for its termination.
While the child process is running, Photon events are processed.
If pidp isn’t NULL, the process ID of the spawned command is stored
in *pidp. This can be used if callback functions need to communicate
with the running child process.
The meaning of all the other arguments is the same as for the
PtSpawn() function.

Returns:
The termination status of the child (see waitpid()), or -1 if the child
process couldn’t be started.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

774 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtSpawnWait()

See also:
PtSpawn(), PtSpawnSetCallback(), PtSpawnDeleteCallback()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 775

PtStartFlux()  2005, QNX Software Systems
Increment the global and container flux count

Synopsis:
int PtStartFlux( PtWidget t *container );

Description:
This function increments the global flux count as well as the
container’s flux count. If either flux count is > 0, no internal damage
is recorded for any widgets under any circumstances.
This function is especially useful for reducing flicker when many
changes are being made to overlapping widgets.

Returns:
The container’s new flux count, or -1 if an error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtEndFlux(), PtHold(), PtRelease(), PtContainerHold(),
PtContainerRelease()

776 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtSyncPhoton()
Synchronize Photon

Synopsis:
void PtSyncPhoton();

Description:
This function forces a flush of the current draw buffer and then
disposes of the memory used by any destroyed widgets. This ensures
that:

¯ all pending widget updates are performed

¯ all widgets pending destruction are removed

☞ This is normally done for you in the standard event-processing loop.

Most applications don’t need to call PtSyncPhoton() explicitly; it’s of
particular importance to applications that modify or destroy widgets
associated with a work or input process.
Never call PtSyncPhoton() in the callback of a widget that you’ve
destroyed.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 777

PtSyncPhoton()  2005, QNX Software Systems

See also:
PtAppAddWorkProc(), PtAppAddInput()

778 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtSyncWidget()
Synchronize widget

Synopsis:
int PtSyncWidget( PtWidget t *widget );

Description:
This function ensures that all flagged actions (such as a complete
rebuild, a resize including extenting, and any required region changes)
are performed on the specified widget.

Returns:
0 Success.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtAppAddInput(), PtAppAddWorkProc(), PtFlush(), PtUpdate()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 779

PtTimerArm()  2005, QNX Software Systems
Arm a timer event on a widget

Synopsis:
int PtTimerArm( PtWidget t *widget,
unsigned msec );

Description:
This function arms a timer event to be trigger after msec milliseconds.
When the timer event is triggered, it’s sent to the widget specified by
widget. For this widget to receive the event, it must provide a raw
callback of type Ph EV TIMER.

☞ Any pending timers for a widget are removed automatically when the
widget is unrealized.

Returns:
0 Successful completion.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhTimerArm()

780 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtTranslateRect()
Translate a rectangle (add offset)

Synopsis:
PhRect t *PtTranslateRect( PhRect t *rect,
PhPoint t const *delta );

Description:
This convenience function adds delta->x to rect->ul.x and rect->lr.x,
and adds delta->y to rect->ul.y and rect->lr.y.
You’ll find this function handy for translating events, extents, or
canvases so that they become relative to various points.

Returns:
The pointer passed in rect.

Examples:
See PhInitDrag().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtDeTranslateRect()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 781

PtUnlinkData()  2005, QNX Software Systems
Remove the provided data link from the data chain

Synopsis:
int PtUnlinkData( PtDataHdr t **ptr,
PtDataHdr t *node );

Description:
This function removes the provided data link from the data chain. The
link is freed, but its data isn’t.

Returns:
0 on success, or -1 if node couldn’t be found in the data list.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtAddData(), PtFindData(), PtFindNextData(), PtRemoveData()

782 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtUnrealizeWidget()
Unrealize a widget

Synopsis:
int PtUnrealizeWidget( PtWidget t *widget );

Description:
This function unrealizes the specified widget and all its children: the
widgets are removed from the display, and the widget engine will no
longer invoke their callbacks.
Unrealized widgets still exist in the widget hierarchy and can be
realized again.

Returns:
0 Successful completion.

-1 An error occurred.

Examples:
See PtWidgetChildBack().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtDestroyWidget(), PtRealizeWidget()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 783

PtUpdate()  2005, QNX Software Systems
Decrement the global hold count

Synopsis:
int PtUpdate( void );

Description:
This function decrements the global widget hold count, which was
previously incremented by a call to PtHold(). When the count reaches
0, the widgets are repaired.

☞ This function is the same as PtRelease().

PtHold() and PtRelease() affect all widgets, while PtContainerHold()

and PtContainerRelease(), prevent only child widgets of a container
from being repaired.

Returns:
The current hold count, or -1 if an error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtContainerHold(), PtContainerRelease(), PtFlush(), PtHold(),
PtModalStart(), PtRelease()

784 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtValidParent()
Identify a valid parent for the specified widget

Synopsis:
PtWidget t * PtValidParent(
PtWidget t *widget parent,
PtWidgetClassRef t *class ref );

Description:
This function determines the real parent widget for widgets of type
class ref , given that its parent is specified as widget parent when
created or reparented. Examples of a class ref include PtWidget,
PtBasic, PtLabel, RtMeter, and so on.
The real parent of a widget might not be the specified widget parent
in special circumstances where the specified parent widget redirects
the child to an alternate parent. Some examples:

¯ PtScrollArea redirects all widgets created as its children or

reparented to it to its virtual canvas (a container widget within the
scroll area).

¯ PtMenuBar redirects all widgets that aren’t of type

PtMenuButton to the PtMenuBar’s parent (i.e. PtMenuBar
accepts only PtMenuButton widgets as its children).

Returns:
A pointer to the widget that will be the real parent of any widgets of
type class ref created in or reparented to widget parent.

Examples:
PtWidget t *
MyRedirector( PtWidget t *widget )
{
MyWidget t *my = (MyWidget t * ) widget;

PtWidget t *parent;
if( ( parent =
PtValidParent( my->scroll area,
widget->class ref ) ) == widget )
return PtWidgetParent( widget );

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 785

PtValidParent()  2005, QNX Software Systems

return( parent );

/*
* Returning my->scroll area would allow the child
* to be created as a direct child of my->scroll area.
* This would be undesirable because scroll area is a
* compound widget, which also needs to redirect its
* children to work correctly.
*/
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtFindGuardian(), PtGetParent(), PtGetParentWidget(),
PtReParentWidget(), PtSetParentWidget(), PtWidgetParent()
“Ordering widgets” in the Creating Widgets in Application Code
chapter of the Photon Programmer’s Guide

786 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtWidgetArea()
Retrieve a copy of a widget’s area

Synopsis:
PhArea t * PtWidgetArea( PtWidget t *widget,
PhArea t *area );

Description:
This function retrieves a copy of widget’s area and stores it in the
PhArea t structure pointed to by area.

Returns:
The same pointer as area, or NULL if widget or area is NULL.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhArea t, PtWidgetDim()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 787

PtWidgetBrotherBehind()  2005, QNX Software Systems
Get the brother behind a widget

Synopsis:
PtWidget t *PtWidgetBrotherBehind(
PtWidget t *widget);

Description:
This function returns a pointer to the brother behind widget. If there’s
no brother behind widget, the function returns NULL.

Examples:
See PtWidgetChildBack().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtWidgetBrotherInFront(), PtWidgetChildBack(),
PtWidgetChildFront(), PtWidgetParent()
“Ordering widgets” in the Creating Widgets in Application Code
chapter of the Photon Programmer’s Guide

788 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtWidgetBrotherInFront()
Get the brother in front of a widget

Synopsis:
PtWidget t *PtWidgetBrotherInFront(
PtWidget t *widget );

Description:
This function returns a pointer to the brother in front of widget. If
there’s no brother in front of widget, the function returns NULL.

Examples:
See PtWidgetChildBack().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtWidgetBrotherBehind(), PtWidgetChildBack(),
PtWidgetChildFront(), PtWidgetParent()
“Ordering widgets” in the Creating Widgets in Application Code
chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 789

PtWidgetCanvas()  2005, QNX Software Systems
Determine the PtWidget canvas for a widget

Synopsis:
PhRect t *PtWidgetCanvas( PtWidget t *widget,
PhRect t *canvas rect );

Description:
This function determines the canvas rectangle for the specified
widget’s PtWidget-class level. This canvas rectangle describes the
area inside the widget’s border. The canvas rect argument should
point to an instance of a PhRect t structure; if you pass canvas rect
as NULL, the function returns NULL.

Returns:
A pointer to the widget’s canvas, or NULL if an error occurs.

Examples:
Return the area inside the widget’s border:

PtWidgetCanvas( labelwidget, &rect);

Return the area inside PtWidget’s border and PtBasic’s margins:

PtBasicWidgetCanvas( labelwidget, &rect);

Return the area inside PtWidget’s border, PtBasic’s margins, and

PtLabel’s margins. This is the rectangle in which the label is
permitted to render:

PtLabelWidgetCanvas( labelwidget, &rect);

Classification:
Photon

790 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtWidgetCanvas()

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtBasicWidgetCanvas(), PtLabelWidgetCanvas(), PtWidgetExtent()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 791

PtWidgetChildBack()  2005, QNX Software Systems
Get the child that’s farthest back in a container

Synopsis:
PtWidget t *PtWidgetChildBack( PtWidget t *widget );

Description:
This function returns a pointer to the child that’s farthest back in the
specified container widget. If widget doesn’t have any children, the
function returns NULL.

Examples:
#include <Pt.h>

int main ()
{
PtWidget t *window, *group, *child;
PhPoint t pos;
PtArg t argt[5];

if (PtInit(NULL) == -1)
exit(EXIT FAILURE);

if ((window = PtCreateWidget(PtWindow, NULL,

0, NULL)) == NULL)
exit(EXIT FAILURE);

pos.x = pos.y = 0;
PtSetArg( &argt[0], Pt ARG POS, &pos, 0 );
PtSetArg( &argt[1], Pt ARG RESIZE FLAGS,
Pt TRUE, Pt RESIZE XY ALWAYS );
PtSetArg( &argt[2], Pt ARG GROUP ORIENTATION,
Pt GROUP HORIZONTAL, 0 );
group = PtCreateWidget( PtGroup, NULL,
3, argt );

// Create some buttons in the group.

PtSetArg( &argt[0], Pt ARG TEXT STRING, "Child 1", 0 );
PtCreateWidget( PtButton, NULL, 1, argt );

PtSetArg( &argt[0], Pt ARG TEXT STRING, "Child 2", 0 );

PtCreateWidget( PtButton, NULL, 1, argt );
PtSetArg( &argt[0], Pt ARG TEXT STRING, "Child 3", 0 );
PtCreateWidget( PtButton, NULL, 1, argt );

// Make the front child red, and the backmost one blue.

792 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtWidgetChildBack()

PtSetArg( &argt[0], Pt ARG COLOR, Pg RED, 0);

child = PtWidgetChildFront( group );
PtSetResources ( child, 1, argt );

PtSetArg( &argt[0], Pt ARG COLOR, Pg BLUE, 0);

child = PtWidgetChildBack( group );
PtSetResources ( child, 1, argt );

PtRealizeWidget (window);

PtMainLoop();
return EXIT SUCCESS;

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtWidgetBrotherBehind(), PtWidgetBrotherInFront(),
PtWidgetChildFront(), PtWidgetInsert(), PtWidgetParent(),
PtWidgetToBack(), PtWidgetToFront()
PtWindowToBack() PtWindowToFront() in the Photon Widget
Reference.
“Ordering widgets” in the Creating Widgets in Application Code
chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 793

PtWidgetChildFront()  2005, QNX Software Systems
Get the the child at the very front of a container

Synopsis:
PtWidget t *PtWidgetChildFront(
PtWidget t *widget );

Description:
This function returns a pointer to the child at the very front of the
specified container widget. If widget doesn’t have any children, the
function returns NULL.

Examples:
See PtWidgetChildBack().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtWidgetBrotherBehind(), PtWidgetBrotherInFront(),
PtWidgetChildBack(), PtWidgetInsert(), PtWidgetParent(),
PtWidgetToBack(), PtWidgetToFront()
PtWindowToBack() PtWindowToFront() in the Photon Widget
Reference.
“Ordering widgets” in the Creating Widgets in Application Code
chapter of the Photon Programmer’s Guide

794 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtWidgetClass()
Return the class of a widget

Synopsis:
PtWidgetClassRef t *PtWidgetClass(
PtWidget t *widget );

Description:
This function lets you determine a widget’s class. Using the
PtWidgetClassRef t pointer, you can create new widgets of the
same class or check for specific widget classes.

Returns:
A pointer to a PtWidgetClassRef t, or NULL if the widget is
NULL.

Examples:
/* check the class type of a widget */
if ( PtWidgetClass( widget ) == PtWindow ) {
/* window processing */
}
else {
/* nonwindow processing */
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 795

PtWidgetClass()  2005, QNX Software Systems

See also:
PtWidgetIsClass(), PtWidgetIsClassMember()

796 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtWidgetClassFlags()
Retrieve a widget’s class structure flags

Synopsis:
unsigned long PtWidgetClassFlags(
PtWidget t *widget );

Description:
This function retrieves widget’s class structure flags:

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
widget’s resources to be indexed as an array.
Pt CONTAINER
The widget class is a container.
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 FORCE UNREALIZE (set automatically when required)
The class Unrealization function (unrealize f()) for this class
and its superclasses will be called when this widget is
unrealized.
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 NO INHERITED RESOURCES
Prevents the search for a resource from walking up through
superclasses. Only the resources for this class are handled; all
others are ignored. This doesn’t prevent resources from being
propagated to procreated widgets.

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 797

PtWidgetClassFlags()  2005, QNX Software Systems

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.
Pt RECTANGULAR
Rectangular widgets are opaque when filled. Opaque widgets
don’t damage widgets below them when they are modified
(unless their size or position is modified).

Pt UNCLEAN RESOURCES
Prevents the resources of a widget class from being indexed.
This is necessary if the widget class only defines resources to
override a superclass (i.e. the widget class doesn’t define any
new resources).

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtWidgetClass(), PtWidgetFlags()

798 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtWidgetDim()
Retrieve a copy of a widget’s dimension

Synopsis:
PhDim t * PtWidgetDim( PtWidget t *widget,
PhDim t *dim );

Description:
This function retrieves a copy of widget’s dimension and stores it in
the PhDim t structure pointed to by dim.

Returns:
The same pointer as dim, or NULL if widget or dim is NULL.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PhDim t, PtWidgetArea()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 799

PtWidgetExtent()  2005, QNX Software Systems
Get a widget’s extent

Synopsis:
PhRect t *PtWidgetExtent( PtWidget t *widget,
PhRect t *extent );

Description:
This function sets the specified PhRect t structure to the extent of
the specified widget and returns a pointer to that structure.

Returns:
The same pointer as extent, or NULL if no PhRect t structure is
provided or if the widget pointer is invalid.

☞ A widget’s extent isn’t calculated until the widget is either realized or

forced to calculate the extent by a call to PtExtentWidget(). If the
widget hasn’t been realized, be sure to call PtExtentWidget() first.

Examples:
PhRect t extent;
PtWidget t *labelwidget;

PtRealizeWidget( labelwidget );
PtWidgetExtent( labelwidget, &extent);

See also PtContainerGiveFocus().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

800 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtWidgetExtent()

See also:
PhRect t, PtExtentWidget(), PtRealizeWidget()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 801

PtWidgetFamily()  2005, QNX Software Systems
Traverse the widget hierarchy

Synopsis:
PtWidget t *PtWidgetFamily( PtWidget t *root,
PtWidget t *current );

Description:
This function walks the depth of the widget hierarchy, starting from
the top widget.

Returns:
A pointer to the next widget below root in the widget hierarchy. When
the hierarchy has been fully traversed, the function returns NULL.

Examples:
PtWidget t *mycontainer;
PtWidget t *root;
PtWidget t *current;
int n;
.
.
.
mycontainer = PtCreateWidget( PtContainer, NULL, n, args );
.
.
.
/*
* Set and highlight all PtLabel widgets
* within "mycontainer"
*/
root = current = mycontainer;
PtSetArg( &arg, Pt ARG FLAGS, Pt TRUE,
Pt HIGHLIGHTED|Pt SET);
while( current = PtWidgetFamily( root, current ) )
if( PtWidgetIsClass( current, PtLabel) )
PtSetResources( current, 1, &arg );
PtRealizeWidget( mycontainer );

See also PtWidgetChildBack().

Classification:
Photon

802 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtWidgetFamily()

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtWidgetBrotherBehind(), PtWidgetBrotherInFront(),
PtWidgetChildBack(), PtWidgetChildFront(), PtWidgetParent(),
PtWidgetSkip(), PtWidgetToBack(), PtWidgetToFront(),
PtWidgetTree(), PtWidgetTreeTraverse()
“Ordering widgets” in the Creating Widgets in Application Code
chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 803

PtWidgetFlags()  2005, QNX Software Systems
Retrieve a widget’s flags

Synopsis:
long PtWidgetFlags( PtWidget t *widget );

Description:
This function retrieves a widget’s flags. For the meanings of the bits
in this flag variable, see:

¯ The description of the Pt ARG FLAGS resource for PtWidget in

the Widget Reference
Or

¯ PtWidget.h

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtWidgetClassFlags()

804 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtWidgetHelpHit()
Find the first widget at a given position that has a help topic

Synopsis:
PtWidget t * PtWidgetHelpHit(
PtWidget t *container,
PhPoint t const *pos );

Description:
This function finds the first widget inside the given container at the
given position that contains a help topic (i.e. Pt ARG HELP TOPIC
contains a non-NULL string). The arguments are:

container A pointer to the container to be searched for widgets.

pos A pointer to the position. The position is relative to the

container widget’s canvas.

Returns:
A pointer to the widget found; NULL if none was found.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtContainerHit()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 805

PtWidgetInsert()  2005, QNX Software Systems
Insert a widget in the widget family hierarchy

Synopsis:
int PtWidgetInsert ( PtWidget t *widget,
PtWidget t *new sibling,
int behind );

Description:
This function inserts widget into the widget family hierarchy as a
brother of the widget new sibling, based on the value of behind:

0 Insert widget in front of new sibling.

1 Insert widget behind new sibling.

Use this function to insert a widget into the focus order of a group.
For example, if you have widget A and widget C with a focus order of
A→C, you could insert widget B into the focus order after widget A
by making the following call:

PtWidgetInsert (B, A, 0);

The focus order would then be A→B→C.

Returns:
0 Success.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

806 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtWidgetInsert()

See also:
PtGetParentWidget(), PtWidgetBrotherBehind(),
PtWidgetBrotherInFront(), PtWidgetChildBack(),
PtWidgetChildFront(), PtWidgetInsert(), PtWidgetParent(),
PtWidgetToBack(), PtWidgetToFront()
“Ordering widgets” in the Creating Widgets in Application Code
chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 807

PtWidgetIsClass()  2005, QNX Software Systems
Determine whether a widget is a specific class type

Synopsis:
int PtWidgetIsClass( PtWidget t *widget,
PtWidgetClassRef t *class );

Description:
This function determines whether the specified widget is of the
specified widget class.

Returns:
0 The widget isn’t of the given class type.

1 The widget is of the given class type.

Examples:
Test to see if widget is a PtLabel-class widget:

if( PtWidgetIsClass( widget, PtLabel ) )

printf( "PtLabel-class widget\n" );
else
printf( "non PtLabel-class widget\n" );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

808 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtWidgetIsClass()

See also:
PtWidgetIsClassMember()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 809

PtWidgetIsClassMember()  2005, QNX Software Systems
Determine whether a widget belongs to a specified class

Synopsis:
int PtWidgetIsClassMember(
PtWidget t *widget,
PtWidgetClassRef t *class );

Description:
This function determines whether or not the specified widget is a
member of the specified widget class. You can use this function to
determine whether the widget is of the specified class or a subclass of
the specified class.

Returns:
0 widget isn’t a member of the given class.

1 widget is a member of the given class.

Examples:
Test to see if widget belongs to the PtGraphic class (i.e. is it a line,
rectangle, polygon, etc.):

if( PtWidgetIsClassMember( widget, PtGraphic ) )

printf( "PtGraphic-class widget\n" );
else
printf( "non-PtGraphic-class widget\n" );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

810 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtWidgetIsClassMember()

See also:
PtWidgetIsClass()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 811

PtWidgetIsRealized()  2005, QNX Software Systems
Determine whether or not a widget is realized

Synopsis:
int PtWidgetIsRealized ( PtWidget t *widget );

Description:
This function checks to see if the given widget is realized.

Returns:
A nonzero value if the widget is realized, otherwise 0.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

812 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtWidgetOffset()
Find the offset of a widget’s origin

Synopsis:
PhPoint t *PtWidgetOffset( PtWidget t *widget,
PhPoint t *offset );

Description:
This function determines the offset of widget’s origin from its disjoint
parent widget.

Returns:
A pointer to a PhPoint t structure that’s the offset of the widget’s
origin from its parent window (the widget’s position is relative to this
point), or NULL if an error occurs.

Examples:
PtArg t arg;
PhPoint t *widget pos;

PtSetArg( &arg, Pt ARG POS, &widget pos, 0);

PtGetResources( labelwidget, 1, &arg );

if(PtWidgetOffset( labelwidget, &point))

{
widget position relative to window.x =
point.x + widget pos->x;
widget position relative to window.y =
point.y + widget pos->y;
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
continued. . .

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 813

PtWidgetOffset()  2005, QNX Software Systems

Safety
Thread No

See also:
PtGetAbsPosition(), PtTranslateRect()

814 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtWidgetParent()
Get a widget’s parent

Synopsis:
PtWidget t *PtWidgetParent( PtWidget t *widget );

Description:
This function returns a pointer to the parent of the specified widget. If
no parent exists, the function returns NULL.

☞ Some container widgets, including PtDivider, PtMenuBar,

PtMultiText, and PtScrollArea redirect children to an alternate
parent. For all container widgets, it’s best to call PtValidParent() to
determine the “real” parent of the children.

Examples:
See PtWidgetChildBack().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtCreateWidget(), PtFindGuardian(), PtGetParent(),
PtGetParentWidget(), PtReParentWidget(), PtSetParentWidget(),
PtValidParent(), PtWidgetBrotherBehind(),
PtWidgetBrotherInFront(), PtWidgetChildBack(),
PtWidgetChildFront()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 815

PtWidgetParent()  2005, QNX Software Systems

“Ordering widgets” in the Creating Widgets in Application Code

chapter of the Photon Programmer’s Guide

816 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtWidgetRid()
Get a widget’s region ID

Synopsis:
PhRid t PtWidgetRid( PtWidget t *widget );

Description:
This function returns the region ID of the specified widget. If widget
doesn’t have a region, the function returns 0.

Examples:
See PtGetParent().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtWidgetBrotherBehind(), PtWidgetBrotherInFront(),
PtWidgetChildFront(), PtWidgetChildBack(), PtWidgetFamily(),
PtWidgetParent(), PtWidgetToBack(), PtWidgetToFront()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 817

PtWidgetSkip()  2005, QNX Software Systems
Skip to a widget in the next hierarchy

Synopsis:
PtWidget t * PtWidgetSkip( PtWidget t *root,
PtWidget t *widget );

Description:
This function skips the hierarchy rooted at widget but does not return
widgets any higher than root.

Returns:
A pointer to a widget in the next hierarchy, or NULL if there isn’t
another hierarchy to skip to.

Examples:
// Set the fill color of all REALIZED widgets to white.

PtArg t argt;
int flags, skip = 0;
PtSetArg( &argt, Pt ARG FILL COLOR, Pt WHITE, 0 );

for( wp = widget; wp;

wp = skip ? PtWidgetSkip(root, wp )
: PtWidgetFamily( root, wp ) ){
skip = 0;
flags = PtWidgetFlags( wp );

if( !( flags & Pt REALIZED ) ) {

// completely skip this hierarchy.
skip = 1;
continue;
}
PtSetResources( wp, 1, &argt );
}

Classification:
Photon

818 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtWidgetSkip()

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtNextTopLevelWidget(), PtWidgetBrotherBehind(),
PtWidgetBrotherInFront(), PtWidgetChildBack(),
PtWidgetChildFront(), PtWidgetFamily(), PtWidgetTree(),
PtWidgetTreeTraverse()
“Ordering widgets” in the Creating Widgets in Application Code
chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 819

PtWidgetToBack()  2005, QNX Software Systems
Move a widget behind all its brothers

Synopsis:
int PtWidgetToBack( PtWidget t *widget );

Description:
This function moves the specified widget behind all its brothers (i.e.
away from the user). All of widget’s children are moved too. Any
widgets damaged as a result of this operation are automatically
repaired.

☞ This function doesn’t work for PtWindow widgets — their positions

are controlled by the Window Manager. To move a window to the
back of the workspace, use PtWindowToBack(), which is described in
the Photon Widget Reference.

Returns:
0 Successful completion.

-1 An error occurred.

Examples:
See PtWidgetChildBack().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

820 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtWidgetToBack()

See also:
PtWidgetBrotherBehind(), PtWidgetBrotherInFront(),
PtWidgetChildBack(), PtWidgetChildFront(), PtWidgetInsert(),
PtWidgetParent(), PtWidgetToFront()
PtWindowToBack() PtWindowToFront() in the Photon Widget
Reference.
“Ordering widgets” in the Creating Widgets in Application Code
chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 821

PtWidgetToFront()  2005, QNX Software Systems
Move a widget in front of all its brothers

Synopsis:
int PtWidgetToFront( PtWidget t *widget );

Description:
This function moves the specified widget in front of all its brothers
(i.e. toward the user). All of widget’s children are moved too. Any
widgets damaged as a result of this operation are automatically
repaired.

☞ This function doesn’t work for PtWindow widgets — their positions

are controlled by the Window Manager. To move a window to the
front of the workspace, use PtWindowToFront(), which is described in
the Photon Widget Reference.

Returns:
0 Successful completion.

-1 An error occurred.

Examples:
See PtWidgetChildBack().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

822 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtWidgetToFront()

See also:
PtWidgetBrotherBehind(), PtWidgetBrotherInFront(),
PtWidgetChildBack(), PtWidgetChildFront(), PtWidgetInsert(),
PtWidgetParent(), PtWidgetToBack()
PtWindowToBack() PtWindowToFront() in the Photon Widget
Reference.
“Ordering widgets” in the Creating Widgets in Application Code
chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 823

PtWidgetTree()  2005, QNX Software Systems
Walk the widget tree from front to back

Synopsis:
int PtWidgetTree( PtWidget t *root,
PtWidget t **cur,
int D );

Description:
This function walks the widget tree pointed to by root from front to
back. The cur argument is the address of a pointer to the current
widget in the tree. The D argument is the direction control.

☞ This function performs a simple traversal of the widget tree. If you

need more control over how the tree is traversed (for example,
specifying the direction, or skipping certain branches), use
PtWidgetTreeTraverse().

To start the traversal, set cur to be the address of a pointer to the root
widget, and set D to Pt TRAVERSE START. Use the result returned by
PtWidgetTree() as the value of D for the next call.
The traversal is done when PtWidgetTree() returns
Pt TRAVERSE DONE.

Returns:
Pt TRAVERSE DONE
All the widgets in the tree have been traversed.
Any other value
Pass this value as D in the next call.

Examples:
PtWidget t *cur, *window;
int d;
.
.
.
cur=window
d=Pt TRAVERSE START;
while( ( d=PtWidgetTree( window, &cur, d ) ) != Pt TRAVERSE DONE)

824 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtWidgetTree()

PtSetResources( cur, 1, argt );

.
.
.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtNextTopLevelWidget(), PtValidParent(), PtWidgetBrotherBehind(),
PtWidgetBrotherInFront(), PtWidgetChildBack(),
PtWidgetChildFront(), PtWidgetFamily(), PtWidgetParent(),
PtWidgetSkip(), PtWidgetTreeTraverse()
“Ordering widgets” in the Creating Widgets in Application Code
chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 825

PtWidgetTreeTraverse()  2005, QNX Software Systems
Walk the widget family hierarchy from front to back

Synopsis:
int PtWidgetTreeTraverse(
PtWidget t *root,
PtWidget t **current,
int direction,
int (*skip f )( PtWidget t *widget,
void *data ),
void *data );

Description:
This function walks the widget family hierarchy from the frontmost
widget of the current branch to root.
If a skip f() function is provided, it’s called prior to the traversal into
each branch of the family hierarchy. If the skip f() function returns a
value other than Pt CONTINUE, that branch may be skipped. The
skip f() function is passed the current widget (root of the branch to be
traversed next) and data, as provided in the last parameter to
PtWidgetTreeTraverse().
The direction parameter controls the direction of the traversal to the
next current widget. To begin a traversal, a direction of
Pt TRAVERSE START should be passed. New direction values are
returned by the function and should be used in subsequent calls
during the traversal.
The direction value returned is treated primarily as a bit field in which
the bottom four bits (0xF) are reserved for direction and general state
control. These bits are:

Pt TRAVERSE ROOT
current is root.
Pt TRAVERSE LAST
current is last widget in hierarchy to be processed.
Pt TRAVERSE BACK
Walk towards root.

826 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtWidgetTreeTraverse()

Pt TRAVERSE FORCE
Return the return value from skip f unaltered (the return value
is usually ORed with direction prior to return).

When the traversal is complete direction equals Pt TRAVERSE DONE

(0).
The return value from skip f(), if not Pt CONTINUE, is ORed with the
current direction control value unless the Pt TRAVERSE FORCE bit is
set in that return value. This result is returned to the calling function
(the function invoking PtWidgetTreeTraverse()). If the return value
from skip f() is Pt CONTINUE, the branch is stepped into without
returning from PtWidgetTreeTraverse().

Returns:
0 Successful completion of traversal.

-1 An error occurred.

Other values Traversal is in progress.

Examples:
Example 1 — Implementation of PtWidgetTree():

static int
skip delay realize( PtWidget t *widget, void *data )
{
data;
return (
(
(
( widget->flags & ( Pt DELAY REALIZE |
Pt REALIZED ) )
== Pt DELAY REALIZED
)
) ? Pt TRAVERSE BACK : Pt CONTINUE );
}

int
PtWidgetTree( PtWidget t *root, PtWidget t **cur, int D )

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 827

PtWidgetTreeTraverse()  2005, QNX Software Systems

{
return PtWidgetTreeTraverse( root, cur, D,
skip delay realize, NULL );
}

Example 2 — Find the frontmost widget in ABW pane1

(unconditionally):
PtWidget t *current;

(void) PtWidgetTreeTraverse( NULL, &current, Pt TRAVERSE START,

NULL, NULL );
// current now points to the widget at the very front
// of ABW pane1

Example 3 — Find the frontmost widget in ABW pane1 that isn’t

within a disjoint child:
#define FOUND DISJOINT 0x10

skip disjoint( PtWidget t *widget, void *data )

{
return( PtWidgetClassFlags( widget ) & Pt DISJOINT ?
FOUND DISJOINT : Pt CONTINUE );
}

.
.
.
dir = Pt TRAVERSE START;
while( dir = PtWidgetTreeTraverse( NULL, &current,
dir, skip disjoint, NULL ) )
if( !( dir & FOUND DISJOINT ) )
break;
.
.
.

Example 4 — Walk the widget family hierarchy from the frontmost

descendant within ABW pane1 back to ABW base (skipping disjoint
subhierarchies):
#define FOUND DISJOINT 0x10
skip disjoint( PtWidget t *widget, void *data )
{
return( PtWidgetClassFlags( widget ) & Pt DISJOINT ?
FOUND DISJOINT : Pt CONTINUE );
}

828 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtWidgetTreeTraverse()

.
.
.
current = ABW pane1;
dir = Pt TRAVERSE START;
while( dir = PtWidgetTreeTraverse( ABW base, &current, dir,
skip disjoint, NULL ) )
{
if ( dir & FOUND DISJOINT )
// current is the disjoint widget
continue;
//do stuff with current...
}
.
.
.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtNextTopLevelWidget(), PtWidgetBrotherBehind(),
PtWidgetBrotherInFront(), PtWidgetChildBack(),
PtWidgetChildFront(), PtWidgetFamily(), PtWidgetParent(),
PtWidgetSkip(), PtWidgetTree()
“Ordering widgets” in the Creating Widgets in Application Code
chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 829

PtWidgetVisibleExtent()  2005, QNX Software Systems
Calculate the visible portion of a widget

Synopsis:
int PtWidgetVisibleExtent ( PtWidget t *widget,
PhRect t *rect );

Description:
This function determines the portion of a rectangle, rect, that isn’t
clipped by any parent of widget.

Returns:
0 No portion of rect is visible

1 Success — rect contains the portion of the original rectangle

that isn’t clipped by any of widget’s parents

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

830 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 2005, QNX Software Systems PtWindowConsoleSwitch()
Switch to the console a given window’s displayed on

Synopsis:
int PtWindowConsoleSwitch( PhRid t rid );

Description:
This function causes PWM to switch the current display to the
console where the window specified by rid is located. The rid is the
region of a task window, and may be obtained with PtWidgetRid().

Returns:
0 Success.

-1 An error occurred; errno is set.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PtConsoleSwitch(), PtWidgetRid()

September 20, 2005 Chapter 9 ¯ Pt — Widget Toolkit 831

PtWorkProcF t, PtWorkProc t  2005, QNX Software Systems
Pointer to a work procedure function

Synopsis:
typedef int PtWorkProcF t( void *);
typedef PtWorkProcF t *PtWorkProc t;

Description:
These data types define pointers to work procedures. The
PtWorkProcF t type is the function type that the PtWorkProc t
type points to. This allows you to do something like this:

PtWorkProcF t my work proc;

int my work proc( void *data ) {

...
}

The compiler should detect any inconsistencies between the two

declarations of my work proc() and give you an error (which is better
than a “pointer mismatch” warning on the call to
PtAppAddWorkProc()).

Classification:
Photon

See also:
PtAppAddWorkProc()

832 Chapter 9 ¯ Pt — Widget Toolkit September 20, 2005

 Chapter 10
Px — Extended

September 20, 2005 Chapter 10 ¯ Px — Extended 833

 2005, QNX Software Systems

These functions extend Photon’s basic functionality. Using them, you

can:

¯ Access the Photon helpviewer.

¯ Load graphic files (GIF, BMP, JPG, JPEG and so on).

¯ Create CRCs.

¯ Access textual configuration files.

¯ Translate characters to and from UTF-8.

☞ These functions are supplied only in static form in the Photon library
phexlib3r.lib. You’ll need to link with this library explicitly.

September 20, 2005 Chapter 10 ¯ Px — Extended 835

PxConfigClose()  2005, QNX Software Systems
Close the current configuration file

Synopsis:
#include <photon/PxProto.h>

int PxConfigClose( void );

Description:
This function closes the currently opened configuration file (opened
using PxConfigOpen()). It doesn’t do anything if there’s no currently
opened configuration file.

Returns:
Pt TRUE The file was opened and is now closed.

Pt FALSE Otherwise.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxConfigOpen()

836 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxConfigDeleteEntry()
Delete an entry from a configuration file

Synopsis:
#include <photon/PxProto.h>

int PxConfigDeleteEntry( const char *section,

const char *entry );

Description:
Use this function to delete the entry entry from the section section in
the configuration file.

☞ The configuration file must have been opened for PXCONFIG WRITE
— see PxConfigOpen().

Returns:
Pt TRUE The entry is deleted.

Pt FALSE Otherwise.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxConfigDeleteSection(), PxConfigOpen()

September 20, 2005 Chapter 10 ¯ Px — Extended 837

PxConfigDeleteSection()  2005, QNX Software Systems
Delete a section from a configuration file

Synopsis:
#include <photon/PxProto.h>

int PxConfigDeleteSection( const char *section);

Description:
This function deletes the section section from the configuration file.

☞ The file must have been opened for PXCONFIG WRITE — see
PxConfigOpen().

All entries within the section (up to either the beginning of the next
[] section or end-of-file) are deleted. The internal current section is
cleared.

Returns:
Pt TRUE The section is deleted.

Pt FALSE Otherwise.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

838 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxConfigDeleteSection()

See also:
PxConfigDeleteEntry(), PxConfigForceEmptySection(),
PxConfigOpen()

September 20, 2005 Chapter 10 ¯ Px — Extended 839

PxConfigForceEmptySection()  2005, QNX Software Systems
Create an empty section in a configuration file

Synopsis:
#include <photon/PxProto.h>

int PxConfigForceEmptySection( const char *section );

Description:
This function creates an empty section section if one doesn’t exist.

☞ The file must have been opened for PXCONFIG WRITE — see
PxConfigOpen().

Normally sections are created as necessary by the PxConfigWrite*()

functions to hold entries, but sometimes the mere presence of a
configuration section conveys application information. The new
section is made the internal current section.

Returns:
Pt TRUE The section is created or exists.

Pt FALSE Otherwise.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

840 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxConfigForceEmptySection()

See also:
PxConfigDeleteSection(), PxConfigOpen()

September 20, 2005 Chapter 10 ¯ Px — Extended 841

PxConfigNextSection()  2005, QNX Software Systems
Seek the beginning of the next section of a configuration file

Synopsis:
#include <photon/PxProto.h>

const char *PxConfigNextSection( void );

Description:
Seek the start of the next section, and return the name of this section;
this section is made the internal current section. This may be used to
process a configuration file consisting of unknown sections, but where
each section has known entries.

Returns:
A string containing the next section name if one exists, NULL
otherwise

☞ This string is a shared static character array that will be overwritten

by subsequent calls to PxConfigSection() or PxConfigNextSection().

Examples:
char *section;
while ((section = PxConfigNextSection()) != NULL) {
PxConfigReadShort(NULL, "Size", 0, &recsize);
PxConfigReadShort(NULL, "Max", 0, &maxrecs);
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
continued. . .

842 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxConfigNextSection()

Safety
Thread No

See also:
PxConfigNextString(), PxConfigOpen(), PxConfigSection()

September 20, 2005 Chapter 10 ¯ Px — Extended 843

PxConfigNextString()  2005, QNX Software Systems
Get the next entry in the current section

Synopsis:
#include <photon/PxProto.h>

const char *PxConfigNextString( char *value,

short maxlen );

Description:
This function returns the next entry in the current section as a string.
A pointer to the entry name is returned, and its configuration value
(up to a maximum of maxlen-1 characters) is copied as a string into
the buffer at address value. This may be used to process a
configuration section consisting of unknown entries, but where each
entry is to be processed in a similar fashion.

Returns:
A string containing the next entry name within the current section if
one exists, NULL otherwise.

☞ ¯ This string is a shared static character array that will be

overwritten by subsequent calls to PxConfigNextString().

¯ If PxConfigNextString() detects the end of the section, it returns

NULL. If you call PxConfigNextString() again, it gets the next
entry in the next section.

Examples:
char *env, val[128];
if (PxConfigSection("Environment") != NULL)
while ((env = PxConfigNextString(val, sizeof(val))) != NULL)
setenv(env, val, ˜0);

844 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxConfigNextString()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxConfigNextSection(), PxConfigOpen(), PxConfigSection()

September 20, 2005 Chapter 10 ¯ Px — Extended 845

PxConfigOpen()  2005, QNX Software Systems
Open a configuration file

Synopsis:
#include <photon/PxProto.h>

int PxConfigOpen( const char *cfgfile,

int mode);

Description:
PxConfigOpen() opens the configuration file specified by cfgfile for
reading. The file should be closed using PxConfigClose() when the
configuration procedure is complete. Only one configuration file may
be opened at any one time.
The mode parameter is a bitfield specifying what operations may be
performed on the configuration file; it consists of any number of the
following values:

PXCONFIG READ
Allow reading of the config file. This access is always
permitted.

PXCONFIG WRITE
Allow writing (modification) of the config file, using
PxConfigWrite*() and PxConfigDelete*().
PXCONFIG CREATE
Create a new config file, erasing the file if it exists (be sure to
specify PXCONFIG WRITE as well).

The configuration file consists of simple text and is divided into

sections, introduced by [section name]. Section names are currently
limited to 50 characters. Each section is made up of entries (one per
line) of the form:

entry name = value

846 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxConfigOpen()

Entry names are currently limited to 64 characters. Values are limited

to 512 characters. Comments follow #, anywhere on a line. Here’s an
example:

[WWW Section]
Heading Font = swiss
Body Font = dutch
Link Color = 0000FF
Visited Color = 008080
Cache Size = 10240

[File Section]
File Font = swiss12
Print Command = lp @
Display Mode = 1

See PxConfigSection() for further details on the configuration.

Returns:
Pt TRUE The given configuration file exists and has been
opened.

Pt FALSE Otherwise.

Examples:
if (PxConfigOpen(fname, PXCONFIG READ)) {
// read parameters from the file
PxConfigClose();
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 10 ¯ Px — Extended 847

PxConfigOpen()  2005, QNX Software Systems

See also:
PxConfigClose(), PxConfigDeleteEntry(), PxConfigDeleteSection(),
PxConfigForceEmptySection(), PxConfigNextSection(),
PxConfigNextString(), PxConfigReadBool(), PxConfigReadChar(),
PxConfigReadInt(), PxConfigReadLong(), PxConfigReadShort(),
PxConfigReadString(), PxConfigSection(), PxConfigWriteBool(),
PxConfigWriteChar(), PxConfigWriteInt(), PxConfigWriteLong(),
PxConfigWriteShort(), PxConfigWriteString()

848 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxConfigReadBool()
Read a Boolean value from a configuration file

Synopsis:
#include <photon/PxProto.h>

int PxConfigReadBool( const char *section,

const char *entry,
int dflt,
int *value);

Description:
PxConfigReadBool() reads a Boolean parameter from the specified
section and entry of the configuration file. If section is NULL, the
function reads the value from entry in the current section.
PxConfigReadBool() accepts the (case-insensitive) values ON or OFF,
YES or NO, TRUE or FALSE, and stores the integer equivalent (zero or
nonzero) in *value. If any other value is given (or if none is given),
the default value dflt is put into *value instead. If the required section
or entry doesn’t exist, the default value is stored in *value.

Returns:
Pt TRUE if the required section/entry exists and the given value is
valid, otherwise Pt FALSE.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 10 ¯ Px — Extended 849

PxConfigReadBool()  2005, QNX Software Systems

See also:
PxConfigOpen(), PxConfigReadChar(), PxConfigReadInt(),
PxConfigReadLong(), PxConfigReadShort(), PxConfigReadString(),
PxConfigWriteBool(), PxConfigWriteChar(), PxConfigWriteInt(),
PxConfigWriteLong(), PxConfigWriteShort(), PxConfigWriteString()

850 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxConfigReadChar()
Read a character parameter from a configuration file

Synopsis:
#include <photon/PxProto.h>

int PxConfigReadChar( const char *section,

const char *entry,
char dflt,
char *value );

Description:
PxConfigReadChar() reads a character parameter from the specified
section and entry of the configuration file. If section is NULL, the
function reads the value from entry in the current section.
PxConfigReadChar() accepts digits (signed and unsigned) within the
char range, or a single letter, and stores the value in *value. For all
other (invalid or nonexistent) values, the default value dflt is stored
instead. If the required section or entry doesn’t exist, the default value
is stored in *value.

Returns:
Pt TRUE if the required section/entry exists and the given value is
valid, otherwise Pt FALSE.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 10 ¯ Px — Extended 851

PxConfigReadChar()  2005, QNX Software Systems

See also:
PxConfigOpen(), PxConfigReadBool(), PxConfigReadInt(),
PxConfigReadLong(), PxConfigReadShort(), PxConfigReadString(),
PxConfigWriteBool(), PxConfigWriteChar(), PxConfigWriteInt(),
PxConfigWriteLong(), PxConfigWriteShort(), PxConfigWriteString()

852 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxConfigReadInt()
Read an integer parameter from a configuration file

Synopsis:
#include <photon/PxProto.h>

int PxConfigReadInt( const char *section,

const char *entry,
int dflt,
int *value );

Description:
PxConfigReadInt() reads an integer parameter from the specified
section and entry of the configuration file and stores it in *value.
If section is NULL, the function reads the value from entry in the
current section. If the required section or entry doesn’t exist, the
default value is stored in *value.
The value can be signed. The characters after the sign determine the
base:

Character(s): Base:
0x or 0X Hexadecimal
0 Octal
Other digits Decimal

If the entry doesn’t contain a valid int, the default value dflt is stored
in *value.

Returns:
Pt TRUE if the required section/entry exists and the given value is
valid, otherwise Pt FALSE.

September 20, 2005 Chapter 10 ¯ Px — Extended 853

PxConfigReadInt()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxConfigOpen(), PxConfigReadBool(), PxConfigReadChar(),
PxConfigReadLong(), PxConfigReadShort(), PxConfigReadString(),
PxConfigWriteBool(), PxConfigWriteChar(), PxConfigWriteInt(),
PxConfigWriteLong(), PxConfigWriteShort(), PxConfigWriteString()

854 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxConfigReadLong()
Read a long integer parameter from a configuration file

Synopsis:
#include <photon/PxProto.h>

int PxConfigReadLong( const char *section,

const char *entry,
long dflt,
long *value );

Description:
PxConfigReadLong() reads a long parameter from the specified
section and entry of the configuration file and stores it in *value.
If section is NULL, the function reads the value from entry in the
current section. If the required section or entry doesn’t exist, the
default value is stored in *value.
The value can be signed. The characters after the sign determine the
base:

Character(s): Base:
0x or 0X Hexadecimal
0 Octal
Other digits Decimal

If the entry doesn’t contain a valid long, the default value dflt is
stored in *value.

Returns:
Pt TRUE if the required section/entry exists and the given value is
valid, otherwise Pt FALSE.

September 20, 2005 Chapter 10 ¯ Px — Extended 855

PxConfigReadLong()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxConfigOpen(), PxConfigReadBool(), PxConfigReadChar(),
PxConfigReadInt(), PxConfigReadShort(), PxConfigReadString(),
PxConfigWriteBool(), PxConfigWriteChar(), PxConfigWriteInt(),
PxConfigWriteLong(), PxConfigWriteShort(), PxConfigWriteString()

856 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxConfigReadShort()
Read a short integer parameter from a configuration file

Synopsis:
#include <photon/PxProto.h>

int PxConfigReadShort( const char *section,

const char *entry,
short dflt,
short *value );

Description:
PxConfigReadShort() reads a short parameter from the specified
section and entry of the configuration file and stores it in *value.
If section is NULL, the function reads the value from entry in the
current section. If the required section or entry doesn’t exist, the
default value is stored in *value.
The value can be signed. The characters after the sign determine the
base:

Character(s): Base:
0x or 0X Hexadecimal
0 Octal
Other digits Decimal

If the entry doesn’t contain a valid short, the default value dflt is
stored in *value.

Returns:
Pt TRUE if the required section/entry exists and the given value is
valid, otherwise Pt FALSE.

September 20, 2005 Chapter 10 ¯ Px — Extended 857

PxConfigReadShort()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxConfigOpen(), PxConfigReadBool(), PxConfigReadChar(),
PxConfigReadInt(), PxConfigReadLong(), PxConfigReadString(),
PxConfigWriteBool(), PxConfigWriteChar(), PxConfigWriteInt(),
PxConfigWriteLong(), PxConfigWriteShort(), PxConfigWriteString()

858 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxConfigReadString()
Read a string parameter from a configuration file

Synopsis:
#include <photon/PxProto.h>

int PxConfigReadString( const char *section,

const char *entry,
char *dflt,
char *value,
short maxlen );

Description:
PxConfigReadString() reads a string parameter from the specified
section and entry of the configuration file. If section is NULL, the
function reads the value from entry in the current section.
PxConfigReadString() copies a maximum of (maxlen-1) characters
(with a ’\0’ terminator appended) in the string into the buffer at
address value. If the required section or entry doesn’t exist, the first
(maxlen-1) characters of the default string dflt are copied into the
buffer at address value (with a ’\0’ terminator appended).

Returns:
Pt TRUE if the required section/entry exists, otherwise Pt FALSE.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 10 ¯ Px — Extended 859

PxConfigReadString()  2005, QNX Software Systems

See also:
PxConfigOpen(), PxConfigReadBool(), PxConfigReadChar(),
PxConfigReadInt(), PxConfigReadLong(), PxConfigReadShort(),
PxConfigWriteBool(), PxConfigWriteChar(), PxConfigWriteInt(),
PxConfigWriteLong(), PxConfigWriteShort(), PxConfigWriteString()

860 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxConfigSection()
Seek the start of a given section in a configuration file

Synopsis:
#include <photon/PxProto.h>

int PxConfigSection( const char *section );

Description:
PxConfigSection() seeks to the start of the requested section, and
returns an indication of whether the section exists within the
configuration file. This function may be used to conditionally process
an optional section block. Photon also uses it internally to locate a
configuration entry; the section is made the internal current section.

☞ Section names must be an exact match — they must not be

abbreviated and the match is case-sensitive.

Returns:
Pt TRUE if the requested section exists, Pt FALSE otherwise

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxConfigDeleteSection(), PxConfigForceEmptySection(),
PxConfigNextSection(), PxConfigNextString(), PxConfigOpen()

September 20, 2005 Chapter 10 ¯ Px — Extended 861

PxConfigWriteBool()  2005, QNX Software Systems
Write a Boolean parameter in a configuration file

Synopsis:
#include <photon/PxProto.h>

int PxConfigWriteBool( const char *section,

const char *entry,
int format,
int value );

Description:
PxConfigWriteBool() writes a Boolean parameter in the specified
section and entry of the configuration file. If section is NULL, the
parameter is written in the specified entry in the current section. If the
parameter value was present in the file, it’s overwritten with its new
value; otherwise, it’s added to the end of the section.

☞ ¯ The configuration file must have been opened by PxConfigOpen()

with a mode of PXCONFIG WRITE.

¯ If the specified section doesn’t exist, it’s created.

¯ To create an empty section, call PxConfigForceEmptySection().

The format parameter determines how the value is formatted:

Format Output
PXCONFIG FMT BOOL ON OFF or ON
PXCONFIG FMT BOOL YES NO or YES
PXCONFIG FMT BOOL TRUE FALSE or TRUE

862 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxConfigWriteBool()

Returns:
Pt TRUE if the entry is written, otherwise Pt FALSE

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxConfigOpen(), PxConfigReadBool(), PxConfigReadChar(),
PxConfigReadInt(), PxConfigReadLong(), PxConfigReadShort(),
PxConfigReadString(), PxConfigWriteChar(), PxConfigWriteInt(),
PxConfigWriteLong(), PxConfigWriteShort(), PxConfigWriteString()

September 20, 2005 Chapter 10 ¯ Px — Extended 863

PxConfigWriteChar()  2005, QNX Software Systems
Write a character parameter in a configuration file

Synopsis:
#include <photon/PxProto.h>

int PxConfigWriteChar( const char *section,

const char *entry,
int format,
char value);

Description:
PxConfigWriteChar() writes a character parameter in the specified
section and entry of the configuration file. If section is NULL, the
parameter is written in the specified entry in the current section. If the
parameter value was present in the file, it’s overwritten with its new
value; otherwise, it’s added to the end of the section.

☞ ¯ The configuration file must have been opened by PxConfigOpen()

with a mode of PXCONFIG WRITE.

¯ If the specified section doesn’t exist, it’s created.

¯ To create an empty section, call PxConfigForceEmptySection().

The format parameter determines how the value is formatted:

PXCONFIG FMT CHAR CHAR

As a single character (letter/digit).

PXCONFIG FMT CHAR HEX

As a 2-digit hex number with leading 0x.

Returns:
Pt TRUE if the entry is written, otherwise Pt FALSE

864 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxConfigWriteChar()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxConfigOpen(), PxConfigReadBool(), PxConfigReadChar(),
PxConfigReadInt(), PxConfigReadLong(), PxConfigReadShort(),
PxConfigReadString(), PxConfigWriteBool(), PxConfigWriteInt(),
PxConfigWriteLong(), PxConfigWriteShort(), PxConfigWriteString()

September 20, 2005 Chapter 10 ¯ Px — Extended 865

PxConfigWriteInt()  2005, QNX Software Systems
Write an integer parameter in a configuration file

Synopsis:
#include <photon/PxProto.h>

int PxConfigWriteInt( const char *section,

const char *entry,
int format,
int value );

Description:
PxConfigWriteInt() writes an integer parameter in the specified
section and entry of the configuration file. If section is NULL, the
parameter is written in the specified entry in the current section. If the
parameter value was present in the file, it’s overwritten with its new
value; otherwise, it’s added to the end of the section.

☞ ¯ The configuration file must have been opened by PxConfigOpen()

with a mode of PXCONFIG WRITE.

¯ If the specified section doesn’t exist, it’s created.

¯ To create an empty section, call PxConfigForceEmptySection().

The format parameter determines how the value is formatted:

PXCONFIG FMT INT DECIMAL

As a decimal number.
PXCONFIG FMT INT HEX
As a hex number with leading 0x.

Returns:
Pt TRUE if the entry is written, otherwise Pt FALSE

866 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxConfigWriteInt()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxConfigOpen(), PxConfigReadBool(), PxConfigReadChar(),
PxConfigReadInt(), PxConfigReadLong(), PxConfigReadShort(),
PxConfigReadString(), PxConfigWriteBool(), PxConfigWriteChar(),
PxConfigWriteLong(), PxConfigWriteShort(), PxConfigWriteString()

September 20, 2005 Chapter 10 ¯ Px — Extended 867

PxConfigWriteLong()  2005, QNX Software Systems
Write a long integer parameter in a configuration file

Synopsis:
#include <photon/PxProto.h>

int PxConfigWriteLong( const char *section,

const char *entry,
int format,
long value );

Description:
PxConfigWriteLong() writes a long integer parameter in the specified
section and entry of the configuration file. If section is NULL, the
parameter is written in the specified entry in the current section. If the
parameter value was present in the file, it’s overwritten with its new
value; otherwise, it’s added to the end of the section.

☞ ¯ The configuration file must have been opened by PxConfigOpen()

with a mode of PXCONFIG WRITE.

¯ If the specified section doesn’t exist, it’s created.

¯ To create an empty section, call PxConfigForceEmptySection().

The format parameter determines how the value is formatted:

PXCONFIG FMT INT DECIMAL

As a decimal number.
PXCONFIG FMT INT HEX
As a hex number with leading 0x.

Returns:
Pt TRUE if the entry is written, otherwise Pt FALSE

868 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxConfigWriteLong()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxConfigOpen(), PxConfigReadBool(), PxConfigReadChar(),
PxConfigReadInt(), PxConfigReadLong(), PxConfigReadShort(),
PxConfigReadString(), PxConfigWriteBool(), PxConfigWriteChar(),
PxConfigWriteInt(), PxConfigWriteShort(), PxConfigWriteString()

September 20, 2005 Chapter 10 ¯ Px — Extended 869

PxConfigWriteShort()  2005, QNX Software Systems
Write a short integer parameter in a configuration file

Synopsis:
#include <photon/PxProto.h>

int PxConfigWriteShort( const char *section,

const char *entry,
int format,
short value );

Description:
PxConfigWriteShort() writes a short integer parameter in the specified
section and entry of the configuration file. If section is NULL, the
parameter is written in the specified entry in the current section. If the
parameter value was present in the file, it’s overwritten with its new
value; otherwise, it’s added to the end of the section.

☞ ¯ The configuration file must have been opened by PxConfigOpen()

with a mode of PXCONFIG WRITE.

¯ If the specified section doesn’t exist, it’s created.

¯ To create an empty section, call PxConfigForceEmptySection().

The format parameter determines how the value is formatted:

PXCONFIG FMT INT DECIMAL

As a decimal number.
PXCONFIG FMT INT HEX
As a hex number with leading 0x.

Returns:
Pt TRUE if the entry is written, otherwise Pt FALSE

870 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxConfigWriteShort()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxConfigOpen(), PxConfigReadBool(), PxConfigReadChar(),
PxConfigReadInt(), PxConfigReadLong(), PxConfigReadShort(),
PxConfigReadString(), PxConfigWriteBool(), PxConfigWriteChar(),
PxConfigWriteInt(), PxConfigWriteLong(), PxConfigWriteString()

September 20, 2005 Chapter 10 ¯ Px — Extended 871

PxConfigWriteString()  2005, QNX Software Systems
Write a string parameter in a configuration file

Synopsis:
#include <photon/PxProto.h>

int PxConfigWriteString( const char *section,

const char *entry,
int format,
const char *value );

Description:
PxConfigWriteString() writes a string parameter in the specified
section and entry of the configuration file. If section is NULL, the
parameter is written in the specified entry in the current section. If the
parameter value was present in the file, it’s overwritten with its new
value; otherwise, it’s added to the end of the section.

☞ ¯ The configuration file must have been opened by PxConfigOpen()

with a mode of PXCONFIG WRITE.

¯ If the specified section doesn’t exist, it’s created.

¯ To create an empty section, call PxConfigForceEmptySection().

The format parameter must be PXCONFIG FMT STRING and the

string must not contain a \n.
You can write a single comment line in the section by specifying "#"
for entry and the comment for value. For example:

PxConfigWriteString( "My section", "#", PXCONFIG FMT STRING,

"This is a comment");

Returns:
Pt TRUE if the entry is written, otherwise Pt FALSE

872 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxConfigWriteString()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxConfigOpen(), PxConfigReadBool(), PxConfigReadChar(),
PxConfigReadInt(), PxConfigReadLong(), PxConfigReadShort(),
PxConfigReadString(), PxConfigWriteBool(), PxConfigWriteChar(),
PxConfigWriteInt(), PxConfigWriteLong(), PxConfigWriteShort()

September 20, 2005 Chapter 10 ¯ Px — Extended 873

PxCRC()  2005, QNX Software Systems
Calculate a CRC for a block of data

Synopsis:
#include <photon/PxProto.h>

long PxCRC( const char *buffer, int nbytes );

Description:
This function generates a cyclic redundancy check or CRC on the
nbytes of data pointed to by buffer.

☞ We recommend that bitmaps and images have a CRC on the image

data and the palette. This CRC is used extensively by phrelay to
cache images.

Returns:
The cyclic redundancy check.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxLoadImage()

874 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxHelpQuit()
Exit the Helpviewer

Synopsis:
#include <photon/PxHelp.h>

void PxHelpQuit( void );

Description:
PxHelpQuit() tells the Helpviewer to exit.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxHelpTopic(), PxHelpTopicRoot(), PxHelpTopicTree(),
PxHelpSearch(), PxHelpUrl(), PxHelpUrlRoot()
Context-Sensitive Help chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 10 ¯ Px — Extended 875

PxHelpSearch()  2005, QNX Software Systems
Search the help information

Synopsis:
#include <photon/PxHelp.h>

int PxHelpSearch( char *string,

int mode,
int scope,
int method );

Description:
Use PxHelpSearch() to search for a string in the online help
information. The arguments are similar to the fields in the
Helpviewer’s Search pane, and are as follows:

string The string you’re looking for.

mode One of the following:
¯ HELP SEARCH MODE TITLE — search for string in
the titles of all the help topics in the given scope.
¯ HELP SEARCH MODE TEXT — search the text of all
the help topics in the current scope.
¯ HELP SEARCH MODE DISPLAYED — search the text
of the displayed topic only.
scope One of the following:
¯ HELP SEARCH SCOPE ALL — search for the text in
all the online help information.
¯ HELP SEARCH SCOPE SELECTED — search for text
in the selected topic only (for example, in a single
book or bookset).
method One of the following:
¯ HELP SEARCH METHOD EXACT — search for an
exact match (including case). For example, if you’re
searching topic titles for Help, match a title Help, but
not Help files.

876 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxHelpSearch()

¯ HELP SEARCH METHOD WORD — search for the

string as a distinct word or words, ignoring case. For
example, if you’re searching for Help, match Help
and help files but not Helpviewer.
¯ HELP SEARCH METHOD SUBSTRING — search for
the string as distinct words or as substrings, ignoring
case. For example, if you’re searching for Help,
match Help, help files, and Helpviewer.

PxHelpSearch() spawns the Helpviewer if it isn’t running, or sends a

message to the Helpviewer if it is.

Returns:
0 on success, or -1 if the Helpviewer couldn’t be found or spawned.

☞ PxHelpSearch() returns immediately, before the search is complete.

Examples:
PxHelpSearch( "console", HELP SEARCH MODE TITLE,
HELP SEARCH SCOPE ALL,
HELP SEARCH METHOD SUBSTRING );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 10 ¯ Px — Extended 877

PxHelpSearch()  2005, QNX Software Systems

See also:
PxHelpQuit(), PxHelpTopic(), PxHelpTopicRoot(),
PxHelpTopicTree(), PxHelpUrl(), PxHelpUrlRoot()
Context-Sensitive Help chapter of the Photon Programmer’s Guide

878 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxHelpTopic()
Display help information identified by a topic path

Synopsis:
#include <photon/PxHelp.h>

int PxHelpTopic( char *topic );

Description:
PxHelpTopic() tells the Helpviewer to display the help text located by
the given topic path.
PxHelpTopic() spawns the Helpviewer if it isn’t running, or sends a
message to the Helpviewer if it is. Using this function, a Photon
application can respond to a help request from the user by telling the
Helpviewer to display the relevant help information.
If the topic path is relative (i.e. it doesn’t start with a /), it’s appended
to the root topic path specified in an earlier call to PxHelpTopicRoot().

Returns:
0 on success, or -1 if the Helpviewer couldn’t be found or spawned.

☞ PxHelpTopic() returns immediately, before the help topic has been

displayed.

Examples:
The following example shows a fragment from a hypothetical
application built using PhAB. This application first sets up a topic
root for all help requests; it then displays help for a particular part of
the application in response to a callback (which could be attached to a
hotkey, for example).
#include <Pt.h>
#include <photon/PxHelp.h>

int main( void )

{
.
.
.

September 20, 2005 Chapter 10 ¯ Px — Extended 879

PxHelpTopic()  2005, QNX Software Systems

PxHelpTopicRoot(
"/Photon microGUI/Installation & Configuration/pdm" );
.
.
.
}

int HelpCallback( PtWidget t * widget, ApInfo t * apinfo,

PtCallbackInfo t * cbinfo )
{
.
.
.
if( widget == ABW PDMConsole )
PxHelpTopic( "Console Switching" );
.
.
.
return( Pt CONTINUE );
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxHelpQuit(), PxHelpSearch(), PxHelpTopicRoot(),
PxHelpTopicTree(), PxHelpUrl(), PxHelpUrlRoot()
Context-Sensitive Help chapter of the Photon Programmer’s Guide

880 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxHelpTopicRoot()
Specify the root of help topic paths

Synopsis:
#include <photon/PxHelp.h>

void PxHelpTopicRoot( char *topic );

Description:
PxHelpTopicRoot() lets you specify a partial root topic path that’s
prefixed to any relative topic paths in subsequent PxHelpTopic() calls.
(Any path that doesn’t start with a / is considered relative.)

☞ PxHelpTopicRoot() doesn’t copy the topic root. Don’t free the string
until you’ve finished using the root topic path.

Examples:
See PxHelpTopic().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxHelpQuit(), PxHelpSearch(), PxHelpTopic(), PxHelpTopicTree(),
PxHelpUrl(), PxHelpUrlRoot()
Context-Sensitive Help chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 10 ¯ Px — Extended 881

PxHelpTopicTree()  2005, QNX Software Systems
Load a new help topic tree

Synopsis:
#include <photon/PxHelp.h>

int PxHelpTopicTree( char *file );

Description:
PxHelpTopicTree() tells the Helpviewer to load a new topic tree. The
argument must be a top-level topic file with the .toc extension. The
format of the topic file is defined in the “Creating topic files” section
of the Helpviewer documentation in the Photon Installation &
Configuration guide.
PxHelpTopicTree() spawns the Helpviewer if it isn’t running, or sends
a message to the Helpviewer if it is.

Returns:
0 on success, or -1 if the Helpviewer couldn’t be found or spawned.

☞ PxHelpTopicTree() returns immediately, before the topic tree has been

displayed.

Examples:
PxHelpTopicTree( "/usr/help/product/photon.toc" );

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

882 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxHelpTopicTree()

See also:
PxHelpQuit(), PxHelpSearch(), PxHelpTopic(), PxHelpTopicRoot(),
PxHelpUrl(), PxHelpUrlRoot()
Context-Sensitive Help chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 10 ¯ Px — Extended 883

PxHelpUrl()  2005, QNX Software Systems
Display help information identified by a URL

Synopsis:
#include <photon/PxHelp.h>

int PxHelpUrl( char *url );

Description:
PxHelpUrl() tells the Helpviewer to display the help text located by
the given Universal Resource Locator. If the URL is relative (i.e. it
doesn’t start with a /), it’s appended to any partial URL root specified
in a previous call to PxHelpUrlRoot().
PxHelpUrl() spawns the Helpviewer if it isn’t running, or sends a
message to the Helpviewer if it is. Using this function, a Photon
application can respond to a help request from the user by telling the
Helpviewer to display the relevant help information.

Returns:
0 on success, or -1 if the Helpviewer couldn’t be found or spawned.

☞ PxHelpUrl() returns immediately, before the help topic has been

displayed.

Examples:
The following example shows a fragment from a hypothetical
application built using PhAB. This application first sets up a URL
root for all help requests; it then displays help for a particular part of
the application in response to a callback (which could be attached to a
hotkey, for example).

#include <Pt.h>
#include <photon/PxHelp.h>

int main( void )

{
.
.
.

884 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxHelpUrl()

PxHelpUrlRoot(
"/usr/help/product/photon/user guide/desktop man.html" );
.
.
.
}

int HelpCallback( PtWidget t * widget, ApInfo t * apinfo,

PtCallbackInfo t * cbinfo )
{
.
.
.
if( widget == ABW PDMConsole )
PxHelpUrl( "#CONSOLESELECTOR" );
.
.
.
return( Pt CONTINUE );
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxHelpQuit(), PxHelpSearch(), PxHelpTopic(), PxHelpTopicRoot(),
PxHelpTopicTree(), PxHelpUrlRoot()
Context-Sensitive Help chapter of the Photon Programmer’s Guide

September 20, 2005 Chapter 10 ¯ Px — Extended 885

PxHelpUrlRoot()  2005, QNX Software Systems
Specify a partial URL for help information

Synopsis:
#include <photon/PxHelp.h>

void PxHelpUrlRoot( char *url );

Description:
PxHelpUrlRoot() lets you specify a partial root URL that’s prefixed to
any relative URLs in subsequent PxHelpUrl() calls. (A relative URL is
one that doesn’t start with a /.)

☞ PxHelpUrlRoot() doesn’t copy the given URL. Don’t free the string
until you’ve finished using the root URL.

Examples:
See PxHelpUrl().

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxHelpQuit(), PxHelpSearch(), PxHelpTopic(), PxHelpTopicRoot(),
PxHelpTopicTree(), PxHelpUrl()
Context-Sensitive Help chapter of the Photon Programmer’s Guide

886 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxLoadImage()
Read or query a graphic file

Synopsis:
#include <photon/PxImage.h>

PhImage t * PxLoadImage( char *filename,

PxMethods t *methods );

Description:
This function reads a graphic file into memory. Photon supports the
BMP, GIF, JPG, PCX, and JPEG file formats, among others. For a
complete list of the currently supported formats, see
<photon/PxImage.h>.
The filename argument specifies the name of the graphic file to load
or query.
The methods argument points to a structure that lets you modify the
behavior of the function. If this argument is NULL, the function loads
the graphic file specified by filename. PxMethods t is defined as:
typedef struct pxmethods
{
int flags;
void *(*px alloc)( long nbytes, int type );
void *(*px free)( void *memory, int type );
void *(*px error)( char *msg );
void *(*px warning)( char *msg );
void *(*px progress)( int percent );
PhDim t scale;
PgColor t transparent;
void *colors;
int ncolors;
} PxMethods t;

The members are as follows:

flags You can OR the following into flags:

¯ PX QUERY — just query the graphic file. A
PhImage t structure is returned on success.

September 20, 2005 Chapter 10 ¯ Px — Extended 887

PxLoadImage()  2005, QNX Software Systems

¯ PX LOAD — read the graphic file into memory

and convert it to a format that Photon can display.
¯ PX SUPPRESS TAG — don’t calculate tag IDs for
the palette and image.
¯ PX DODITHER — this option currently applies to
JPEG images only. Perform FS dithering if the
image loading library for the source type supports
it.
¯ PX DIRECT COLOR — this option currently
applies to JPEG images only. Load the graphic file
as a 24-bit image if the loader library for the
source type supports it.
¯ PX USECOLORS — if loading a JPEG image, use
the palette provided by the application instead of
calculating one. The image will look much better
on palette-based drivers.
¯ PX TRANSPARENT — substitute the color
specified in the transparency member for the
transparent color in the image.
*(*px alloc)( long nbytes, int type );
*(*px free)( void *memory, int type );
Memory allocation/deallocation routines that you
supply. The deallocation routine is called only if the
image can’t be loaded. The type can be one of the
following:
¯ PX NORMAL — the memory allocation is
unspecific.
¯ PX IMAGE — the memory allocation is for the
image data.
¯ PX PALETTE — the memory allocation is for the
palette.
*(*px error)( char *msg );
An error routine that you supply. The loader calls this
function if it encounters a fatal error while loading

888 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxLoadImage()

the graphic file. The msg argument is a pointer to an

error-message string.
Note that all memory allocated by the loader is freed
before this function is called.
*(*px warning)( char *msg );
A warning routine that you supply. The loader calls
this function if it encounters a nonfatal error while
loading the graphic file. The msg argument is a
pointer to a warning-message string.

*(*px progress)( int percent );

A progress routine that you supply. The loader calls
this function after it loads/decodes a scan line. The
percent argument is a fixed point number in the
following format:
####.####
The upper 16 bits are the whole portion; the lower 16
bits are the decimal portion.

scale Not currently used.

transparent This member is used with the PX TRANSPARENT

flag. If this flag is set, the transparent color in the
image is replaced by the color specified by
transparent. You should set transparent to be a color
that isn’t used in the image.
Once the image is loaded, use PhMakeTransBitmap()
to create a transparency mask for this color.
colors, ncolors
Used in conjunction with the PX USECOLORS flag.
The colors argument points to a palette, and ncolors
indicates the number of valid entries in the palette.

To draw an image, call PgDrawPhImagemx().

September 20, 2005 Chapter 10 ¯ Px — Extended 889

PxLoadImage()  2005, QNX Software Systems

The allocated members of the image structure can be freed by calling

PhReleaseImage() after setting the image’s flag member to indicate
which parts of the image should be freed. You can then free the
PhImage t structure. For more information, see PhImage t.

Choosing which file formats to support

When you compile your application, you get to choose which
graphic-file formats the image library supports.

☞ Including support for certain graphic-file formats increases the size of

your application code. To keep your code small, we recommend that
you include only the formats you need.

To choose specific formats, simply define the PX IMAGE MODULES

manifest followed by any number of PX XXX SUPPORT files as
shown below.

☞ The module inclusion flags must be defined before the

<photon/PxImage.h> header file is included.

#define PX IMAGE MODULES

#define PX GIF SUPPORT
#define PX JPG SUPPORT
#define PX PCX SUPPORT
#define PX BMP SUPPORT
#define PX TGA SUPPORT
#define PX PNG SUPPORT
#define PX TIFF SUPPORT

In the example above, the PX IMAGE MODULES manifest tells the

preprocessor that you’re defining an array of supported file formats.
The manifests on the next seven lines initialize the array.

Returns:
A pointer to a PhImage t structure, or NULL if an error occurs.

890 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxLoadImage()

Examples:
This example can use either shared or normal memory. The advantage
of using shared memory is that it takes less time to draw the image. If
you’re not using shared memory, increasing the draw buffer size
causes more drawing to be buffered before being sent to the graphics
driver; this isn’t as important if you’re using shared memory.
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <string.h>
#include <malloc.h>
#include <assert.h>
#include <ctype.h>
#include <signal.h>

#include <Ph.h>
#include <Pt.h>

#define PX IMAGE MODULES // define the modules we want

#define PX GIF SUPPORT
#define PX JPG SUPPORT
#define PX PCX SUPPORT
#define PX BMP SUPPORT

#include <photon/PxImage.h>

void *memory allocate( long nbytes, int type );

void memory free( void *memory, int type );
void warning( char *msg );
void error( char *msg );
void progress( int percent );

int UseShmem = 1;

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

{
int c;
PtArg t arg[5];
PtWidget t *window;
char fname[255] = { 0 };
int Query = 0;
PhImage t *img;
PxMethods t methods;

while( ( c = getopt( argc, argv,

"f:QS" ) ) != -1 ) {
switch( c ) {

September 20, 2005 Chapter 10 ¯ Px — Extended 891

PxLoadImage()  2005, QNX Software Systems

case ’f’: // filename

strncpy(fname, optarg, 200 );
break;

case ’Q’: // query file

Query = 1;
break;

case ’S’:
UseShmemˆ=1;
break;
}
}

memset( &methods, 0, sizeof( PxMethods t ) );

methods.px alloc = memory allocate;
methods.px free = memory free;
methods.px warning = warning;
methods.px error = error;
methods.px progress = progress;

if( Query )
methods.flags |= PX QUERY;
else
methods.flags |= PX LOAD;

if( ( img = PxLoadImage( fname,

&methods ) ) == NULL ) {
fprintf( stderr, "Error loading/query %s\n",
fname );
exit( EXIT FAILURE );
}

/* Make sure PhReleaseImage() releases any allocated

members of the PhImage t structure. */

img->flags |= Ph RELEASE IMAGE ALL;

if( Query ) {
printf( "Image width: %d\n", img->size.w );
printf( "Image height: %d\n", img->size.h );
printf( "Image BPL: %d\n", img->bpl );
printf( "Image colors: %d\n", img->colors );
printf( "Image type: %d\n", img->type );
exit( EXIT SUCCESS );
}

/* initialize widget library and attach to Photon */

if( PtInit( NULL ) )

892 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxLoadImage()

exit( EXIT FAILURE );

/* increase the draw buffer */

PgSetDrawBufferSize( 0x8000 );

/* create a window */
PtSetArg( &arg[0], Pt ARG DIM, &img->size, 0 );
PtSetArg( &arg[1], Pt ARG WINDOW TITLE,
"Photon Image Viewer", 0 );
window = PtCreateWidget( PtWindow, NULL, 2, arg );

/* Create a label widget with the image. Remember that the

widget creates a copy of the PhImage t structure (because
Pt ARG LABEL DATA is an Alloc resource). The widget
doesn’t copy data pointed to by the PhImage t members. */

PtSetArg( &arg[0], Pt ARG LABEL TYPE, Pt IMAGE, 0 );

PtSetArg( &arg[1], Pt ARG LABEL DATA,
img, sizeof( PhImage t ) );
PtCreateWidget( PtLabel, window, 2, arg );

/* Free the PhImage t structure (but not its contents). */

free( img );

PtRealizeWidget( window );

PtMainLoop();
}

void * memory allocate( long nbytes, int type )

{
if( type == PX IMAGE && UseShmem ) {
return( PgShmemCreate( nbytes, NULL ) );
}
else {
return( calloc( 1, nbytes ) );
}
}

void memory free( void *memory, int type )

{
if( type == PX IMAGE && UseShmem ) {
PgShmemDestroy( memory );
}
else {
free( memory );
}
}

September 20, 2005 Chapter 10 ¯ Px — Extended 893

PxLoadImage()  2005, QNX Software Systems

void warning( char *msg )

{
printf( "%s\n", msg );
}

void error( char *msg )

{
printf( "%s\n", msg );
exit( EXIT FAILURE );
}

void progress( int percent )

{
printf( "Load Status: %d.%d percent\n",
percent >> 16, percent & 0xffff );
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PgDrawPhImagemx(), PgSetPalette(), PgSetFillColor(),
PgSetTextColor(), PgShmemCleanup(), PhImage t,
PhMakeGhostBitmap(), PhMakeTransBitmap(), PhReleaseImage()

894 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxTerminalBuildCharsets()
Create character set tables based on translation tables

Synopsis:
#include <photon/PxTerminal.h>

PtTerminalCharsets t *PxTerminalBuildCharsets(
PxTerminalCsNames t const *names );

Description:
This function is an alternative to creating charset tables by hand. It
creates a PtTerminalCharsets t structure (see the Photon Widget
Reference) based on Photon character translation files (see
PxTranslateSet()).
The PxTerminalCsNames t structure is defined as follows:

typedef struct {
char const *AnsiCharsetName;
char const *InternalCharsetName;
char const *FontCharsetName;
...
}
PxTerminalCsNames t;

The AnsiCharsetName and InternalCharsetName members can be

either NULL or the name of a supported character set. A NULL maps
directly to a NULL in the resulting PtTerminalCharsets t
structure.
The FontCharsetName can be one of:

¯ NULL — no font translation

¯ The name of an 8-bit character encoding

¯ The special value Px TERMINAL UNICODE FONT.

This function puts the resulting structure and all the tables in a single
allocated block of memory. After it’s no longer needed, you can
simply free() it.

September 20, 2005 Chapter 10 ¯ Px — Extended 895

PxTerminalBuildCharsets()  2005, QNX Software Systems

Returns:
A pointer to the resulting PtTerminalCharsets t structure.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxTerminalLoadCharsets(), PxTerminalSaveCharsets()
PtTerminal, PtTerminalCharsets t in the Photon Widget
Reference

896 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxTerminalLoadCharsets()
Load character-set information from a file

Synopsis:
#include <photon/PxTerminal.h>

PtTerminalCharsets t *PxTerminalLoadCharsets(
const char *filename,
PxTerminalCsNames t *names );

Description:
PxTerminalLoadCharsets() loads character-set information from the
given file. The names argument, if not NULL, points to a structure that
the names of the character sets will be stored in.
This function puts the resulting structure and all the tables and strings
in a single allocated block of memory. After it’s no longer needed,
you can simply free() it. Note that this invalidates the strings stored in
*names.

Returns:
A pointer to a PtTerminalCharsets t structure ready for use with
a PtTerminal, widget.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 10 ¯ Px — Extended 897

PxTerminalLoadCharsets()  2005, QNX Software Systems

See also:
PxTerminalBuildCharsets(), PxTerminalSaveCharsets()
PtTerminal, PtTerminalCharsets t in the Photon Widget
Reference

898 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxTerminalSaveCharsets()
Save character-set information in a file

Synopsis:
#include <photon/PxTerminal.h>

int PxTerminalSaveCharsets(
PtTerminalCharsets t *charsets,
PxTerminalCsNames t *names,
const char *filename );

Description:
This function saves the character-set information in the given file. It’s
your responsibility to make sure that the information in *charsets is
consistent with the information in *names — generating both with the
same call to PxTerminalBuildCharsets() is a good way to ensure
consistency.

Returns:
0 Success.

-1 An error occurred (errno is set).

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

September 20, 2005 Chapter 10 ¯ Px — Extended 899

PxTerminalSaveCharsets()  2005, QNX Software Systems

See also:
PxTerminalBuildCharsets(), PxTerminalLoadCharsets()
PtTerminal, PtTerminalCharsets t in the Photon Widget
Reference

900 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxTranslateFromUTF()
Translate characters from UTF-8

Synopsis:
#include <photon/PxProto.h>

int PxTranslateFromUTF( struct PxTransCtrl *ctrl,

const char *src,
int maxsrc,
int *srctaken,
char *dst,
int maxdst,
int *dstmade);

Description:
PxTranslateFromUTF() is used to translate a block of characters from
UTF-8 (the internal Photon character set). The ctrl parameter
specifies the encoding of the destination characters and must be the
pointer returned by a previous call to PxTranslateSet() to install this
encoding.
The parameters are as follows:

src a pointer to the buffer containing the source UTF-8

characters. If this is NULL, no translation is performed,
and the function returns the worst-case number of bytes
required to hold a character in the current encoding.

maxsrc the length of the contents in the source buffer (in bytes).
No more than this number of bytes are read.

dst a pointer to the buffer where the encoded characters

should be placed. If this is NULL, no data is copied but
the translation is still performed to calculate the length
required to store the converted data.

maxdst the length of the destination buffer (in bytes). No more

than this number of bytes will be written; if this is 0, the
buffer is assumed to be large enough to hold the entire
encoding.

September 20, 2005 Chapter 10 ¯ Px — Extended 901

PxTranslateFromUTF()  2005, QNX Software Systems

srctaken this must point to an integer, which will be updated to

reflect the number of bytes consumed from the source
buffer src. This value may be smaller than maxsrc (if the
given destination buffer would overflow or if the final
input character of a multibyte UTF-8 sequence is
incomplete).

dstmade this must point to an integer, which will be updated to

reflect the number of bytes produced (or would be
produced) into the destination buffer dst. This value
may be smaller than maxdst (if the given source buffer
is exhausted or if the final output character of a
multibyte sequence would be incomplete).

Returns:
0 Success.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxTranslateList(), PxTranslateSet(), PxTranslateStateFromUTF(),
PxTranslateStateToUTF(), PxTranslateToUTF(),
PxTranslateUnknown()
Unicode Multilingual Support in the Photon Programmer’s Guide

902 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxTranslateFromUTF()

mbtowc(), wctomb() in the Watcom C Library Reference

September 20, 2005 Chapter 10 ¯ Px — Extended 903

PxTranslateList()  2005, QNX Software Systems
Create a list of all supported character translations

Synopsis:
#include <photon/PxProto.h>

int PxTranslateList( PtWidget t *widget,

char const *none );

Description:
This function may be used to create a list or combobox of all
supported character translations. It takes as a parameter a pointer to a
list-type widget and sets its Pt ARG ITEMS resource to be the list of
translations. These translations are read from the file
/usr/photon/translations/charsets, using the
Description entry as the item text.
If non-NULL, the none parameter points to a string to be added to the
top of the list. This allows you to specify an entry such as None or
Default. Your application will need to know how to handle this entry
when it’s chosen.
This list may then be used at run time to alter the current translation
dynamically. The program should call PxTranslateSet() with the
selected description text to install the new encoding.

☞ This function uses the PxConfig... functions. If you call it while a

configuration file is open, the file will be closed.

Returns:
The number of items placed in the list, or -1 on error.

Classification:
Photon

904 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxTranslateList()

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxTranslateFromUTF(), PxTranslateSet(),
PxTranslateStateFromUTF(), PxTranslateStateToUTF(),
PxTranslateToUTF(), PxTranslateUnknown()
Unicode Multilingual Support in the Photon Programmer’s Guide

September 20, 2005 Chapter 10 ¯ Px — Extended 905

PxTranslateSet()  2005, QNX Software Systems
Install a new character set translation

Synopsis:
#include <photon/PxProto.h>

struct PxTransCtrl *PxTranslateSet(

struct PxTransCtrl *ctrl,
const char *charset);

Description:
PxTranslateSet() installs a new character set translation. The ctrl
argument, if non-NULL, is a pointer to the control structure for a
character set translation returned from a previous call to
PxTranslateSet(). The translation it specifies is disabled, and any
resources it uses are released.
PxTranslateSet() searches the
/usr/photon/translations/charsets configuration file for the
translation specified by charset; it may be an entry section name, one
of the Alias entries or the Description entry. The charset name is
usually selected by the user (see PxTranslateList()) or from an
external specification (for example, the charset= field of the
Content-type MIME / HTTP header).
If the specified charset is found, resources are allocated as required,
and any necessary data files are loaded into memory. The following
special values of charset are recognized:

¯ NULL — release any resources used by the existing encoding

scheme without installing a new translation

¯ an empty string ("") — install a simple byte-copy scheme

The translation routines are provided in the Photon library

phexlib3r.lib, with prototypes in <photon/PxProto.h>.

906 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxTranslateSet()

Returns:
A pointer to a translation control structure, which should be passed to
subsequent translation routines and to future calls to PxTranslateSet()

Examples:
This sample program converts characters from stdin (encoded in a
character set specified to the program as its only argument) to
stdout (in UTF-8). Note that a 256-byte buffer is allocated for input
and a MB LEN MAX * 256 bytes (the worst-case UTF-8 encoding for
that number of input bytes) created for output. Alternatively, a call to
PxTranslateToUTF() with a NULL source buffer could be used to
work out the bytes-per-character requirements (we exploit the fact
that we already know this number for UTF-8 encoding).
#include <mbstring.h>
#include <stdio.h>
#include <stdlib.h>
#include <photon/PxProto.h>

#define BUFFER 256

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

{
struct PxTransCtrl *trans;
char *code, *utf;
int srclen, dstlen;

if (argc < 2) {
fprintf(stderr, "specify translation charset\n");
return(1);
}
if ((trans = PxTranslateSet(NULL, argv[1])) == NULL) {
fprintf(stderr, "unknown translation charset ’%s’\n",
argv[1]);
return(1);
}
if ((code = malloc(BUFFER)) == NULL ||
(utf = malloc(BUFFER * MB LEN MAX)) == NULL) {
fprintf(stderr,
"unable to allocate %d-byte translation buffers\n",
BUFFER);
return(1);
}

while ((srclen = fread(code, sizeof(char), BUFFER,

September 20, 2005 Chapter 10 ¯ Px — Extended 907

PxTranslateSet()  2005, QNX Software Systems

stdin))) {
if ((dstlen = PxTranslateStateToUTF(trans, code,,
srclen NULL, utf,
BUFFER * MB LEN MAX)) == -1) {
fprintf(stderr, "invalid encoding sequence\n");
return(1);
}
fwrite(utf, dstlen, sizeof(char), stdout);
}

return(0);
}

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxTranslateList(), PxTranslateFromUTF(),
PxTranslateStateFromUTF(), PxTranslateStateToUTF(),
PxTranslateToUTF(), PxTranslateUnknown()
Unicode Multilingual Support in the Photon Programmer’s Guide
Unicode Multilingual Support in the Installation & Configuration
guide.

908 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxTranslateStateFromUTF()
Translate characters from UTF-8, using an internal state buffer

Synopsis:
#include <photon/PxProto.h>

int PxTranslateStateFromUTF(
struct PxTransCtrl *ctrl,
const char *src,
int maxsrc,
int *consumed,
char *dst,
int maxdst );

Description:
This function is similar to PxTranslateFromUTF() except that it uses
an internal state buffer.
Since many encodings are multibyte, it’s possible (in cases where
input data is being provided from a file or socket) for a conversion to
end in the middle of a multibyte sequence or for the output buffer to
be too small to hold the complete encoding of the final character. This
routine buffers any partial encoding, using those bytes as the start of a
character sequence for the next PxTranslateStateFromUTF() call.
This routine uses an appropriately sized temporary overflow buffer,
allocated by the PxTranslateSet() routine.
The parameters src and maxsrc specify the input UTF-8 buffer; dst
and maxdst specify the output buffer. These have the same meaning
as in the PxTranslateFromUTF() function. The consumed parameter
is updated with the number of bytes converted from the source buffer;
this may be NULL if this information isn’t required ( i.e. if the source
is always correctly encoded and the destination buffer is always
sufficiently large).

Returns:
The number of bytes produced in the destination buffer, or -1 on error.

September 20, 2005 Chapter 10 ¯ Px — Extended 909

PxTranslateStateFromUTF()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxTranslateList(), PxTranslateFromUTF(), PxTranslateSet(),
PxTranslateStateToUTF(), PxTranslateToUTF(),
PxTranslateUnknown()
Unicode Multilingual Support in the Photon Programmer’s Guide

910 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxTranslateStateToUTF()
Translate characters to UTF-8, using an internal state buffer

Synopsis:
#include <photon/PxProto.h>

int PxTranslateStateToUTF( struct PxTransCtrl *ctrl,

const char *src,
int maxsrc,
int *consumed,
char *dst,
int maxdst );

Description:
This function is similar to PxTranslateToUTF() except that it uses an
internal state buffer.
Since many encodings are multibyte, it’s possible (in cases where
input data is being provided from a file or socket) for a conversion to
end in the middle of a multibyte sequence or for the output buffer to
be too small to hold the complete encoding of the final character. This
routine buffers any partial encoding, using those bytes as the start of a
character sequence for the next PxTranslateStateToUTF() call.
This routine uses an appropriately sized temporary overflow buffer,
allocated by the PxTranslateSet() routine.
The parameters src and maxsrc specify the input buffer; the
parameters dst and maxdst specify the output UTF-8 buffer. These
have the same meaning as in the PxTranslateToUTF() function. The
consumed parameter will be updated with the number of bytes
converted from the source buffer; this may be NULL if this
information isn’t required (i.e. if the source is always correctly
encoded and the destination buffer is always sufficiently large).

Returns:
The number of bytes produced in the destination buffer, or -1 on error.

September 20, 2005 Chapter 10 ¯ Px — Extended 911

PxTranslateStateToUTF()  2005, QNX Software Systems

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxTranslateList(), PxTranslateFromUTF(), PxTranslateSet(),
PxTranslateStateFromUTF(), PxTranslateToUTF(),
PxTranslateUnknown()
Unicode Multilingual Support in the Photon Programmer’s Guide

912 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxTranslateToUTF()
Translate characters to UTF-8

Synopsis:
#include <photon/PxProto.h>

int PxTranslateToUTF( struct PxTransCtrl *ctrl,

const char *src,
int maxsrc,
int *srctaken,
char *dst,
int maxdst,
int *dstmade);

Description:
This function translates a block of characters to Unicode UTF-8 (the
internal Photon character set). The ctrl parameter specifies the
encoding of the source characters and must be the pointer returned by
a previous call to PxTranslateSet() to install this encoding.
The parameters are as follows:

src A pointer to the buffer containing the source characters.

If this is NULL, no translation is performed and the
function returns the worst-case number of bytes required
to hold a character in UTF-8 (MB LEN MAX == 3).

maxsrc The length of the contents in the source buffer (in

bytes). No more than this number of bytes are read.

dst A pointer to the buffer where the UTF-8 characters

should be placed. If this is NULL, no data is copied but
the translation is still performed to calculate the length
required to store the converted data

maxdst The length of the destination buffer (in bytes). No more

than this number of bytes will be written; if this is 0, the
buffer is assumed to be large enough to hold the entire
encoding

September 20, 2005 Chapter 10 ¯ Px — Extended 913

PxTranslateToUTF()  2005, QNX Software Systems

srctaken This must point to an integer, which will be updated to

reflect the number of bytes consumed from the source
buffer src. This value may be smaller than maxsrc (if the
given destination buffer would overflow or if the final
input character of a multibyte sequence is incomplete)

dstmade This must point to an integer, which will be updated to

reflect the number of bytes produced (or would be
produced) in the destination buffer dst. This value may
be smaller than maxdst (if the given source buffer is
exhausted or if the final output character of a multibyte
UTF-8 sequence would be incomplete).

Returns:
0 Success.

-1 An error occurred.

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxTranslateList(), PxTranslateFromUTF(), PxTranslateSet(),
PxTranslateStateFromUTF(), PxTranslateStateToUTF(),
PxTranslateUnknown()
Unicode Multilingual Support in the Photon Programmer’s Guide

914 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxTranslateToUTF()

mbtowc(), wctomb() in the Watcom C Library Reference

September 20, 2005 Chapter 10 ¯ Px — Extended 915

PxTranslateUnknown()  2005, QNX Software Systems
Control how unknown encodings are handled

Synopsis:
#include <photon/PxProto.h>

int PxTranslateUnknown( struct PxTransCtrl *ctrl,

uint16 t to,
uint16 t from );

Library:
phexlib

Description:
This function controls the behavior of the encoding routines when
they encounter an invalid byte sequence or a character that can’t be
represented in the current encoding scheme.
The ctrl argument is a pointer to the control structure for a character
set translation returned from a previous call to PxTranslateSet().
The to argument is used when converting to UTF-8 by calling
PxTranslateToUTF() or PxTranslateStateToUTF(). If to is 0 (the
default) and an invalid encoding is encountered, the translation is
halted an returns an error. If to is nonzero, it’s the Unicode character
to insert into the translation instead of the invalid one.
The from argument is similar, but id used when converting from
UTF-8 by calling PxTranslateFromUTF() or
PxTranslateStateFromUTF().

Returns:
0 Success.

-1 An error occurred.

916 Chapter 10 ¯ Px — Extended September 20, 2005

 2005, QNX Software Systems PxTranslateUnknown()

Classification:
Photon

Safety
Interrupt handler No
Signal handler No
Thread No

See also:
PxTranslateFromUTF(), PxTranslateSet(),
PxTranslateStateFromUTF(), PxTranslateStateToUTF(),
PxTranslateToUTF()
Unicode Multilingual Support in the Photon Programmer’s Guide

September 20, 2005 Chapter 10 ¯ Px — Extended 917

 Chapter 11
wc — Wide-Character

September 20, 2005 Chapter 11 ¯ wc — Wide-Character 919

 2005, QNX Software Systems

The Photon libraries provide wide-character functions that are useful

if you’re working with Unicode characters.

September 20, 2005 Chapter 11 ¯ wc — Wide-Character 921

wctolower()  2005, QNX Software Systems
Return the lowercase equivalent of a wide character

Synopsis:
wchar t wctolower( wchar t wc );

Description:
The wctolower() function returns the lowercase equivalent of wc, or
wc itself if there’s no lowercase equivalent. It’s similar to tolower(),
except that it knows about Unicode characters.
This function is optimized for size rather than speed. If speed is
important, use wctolower() to create a full Unicode conversion table
and then index into it directly.

Returns:
The equivalent lowercase character, or the given character itself if
there’s no lowercase equivalent.

Classification:
UNIX

Safety
Interrupt handler No
Signal handler Yes
Thread Yes

922 Chapter 11 ¯ wc — Wide-Character September 20, 2005

 Glossary

September 20, 2005 Glossary 923

 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 925

  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

926 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 927

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

928 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 929

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

930 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 931

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

932 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 933

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

934 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 935

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

936 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 937

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

938 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 939

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

940 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 941

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

942 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 943

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

944 Glossary September 20, 2005

 Index

! dithering 289
summary of functions 14
<photon/PkKeyDef.h> 436 transparency 293
XOR color 295
stroke
caps 308
A color 310
dash 311
ABLPATH 68, 127
dithering 314
applications, initializing 584
joins 316
arcs, drawing 196
summary of functions 14
area
transparency 319
based on widget extent,
width 320
setting 759
XOR color 322
data structure 348
text
widget canvas, setting based
color 323
on 761
dithering 324
widget, getting 787
font 297
argument lists 598, 599, 762
transparency 326
arrows, beveled, drawing 203
underline 330
attributes
XOR color 327
drawing
plane mask, setting 305
summary of functions 14
fill
color 287

September 20, 2005 Index 945

Index  2005, QNX Software Systems

B Pt CB RAW 560, 562

link
Bézier curve, drawing 207 determining the initiator 129
background processing PhAB information
adding 576 structure 106
removing 594 removing
summary of functions 7 general case 741, 743
work procedures, prototype Pt CB HOTKEY 750
for 832 Pt CB RAW 747, 749
balloons, inflating 704 summary of functions 31
beveled arrow, drawing 203 canvas
beveled box, drawing 200 determining
beveled rectangle, drawing 203 basic 604
bitmaps label 711
color 323 widget 790
dithering 324 caps 308
drawing 210 channels
repeatedly 235 Neutrino
PhAB data structure 70 attaching 355
summary of functions 7 use by widget library 610
transparency 326 Photon
widget databases arming for events 400
freeing 91 attaching 349, 706
loading from 93 connection information 417
XOR color 327 detaching 379
blitting events, checking for 409
summary of functions 8 reattaching 461
within a region 353 summary of functions 25
box, beveled, drawing 200 characters
translating
from UTF-8 901, 909
installing 906
C listing supported 904
callbacks summary of functions 8
adding tables, building 895
general case 554, 556 tables, loading 897
Pt CB HOTKEY 563 tables, saving 899

946 Index September 20, 2005

 2005, QNX Software Systems Index

to UTF-8 911, 913 fill 287

unknown 916 gray
wide RGB, converting from 270
converting to lowercase 922 RGB, converting to 268
summary of functions 31 green component 271
class hierarchy HSV
summary of functions 33 data structure 187
widget class, getting 795 RGB, converting from 279
widget, determining 808, 810 RGB, converting to 272, 275
clipboard palette, getting current 267
copying palette, setting current 302
data 357 red component 276
strings 359 RGB
header data structure 370 composite format, converting
pasting to 277
freeing memory 361 data type 185
starting 362 gray, converting from 268
strings 364 gray, converting to 270
searching HSV, converting from 275
by order 368 HSV, converting to 279
by type 366 stroke 310
summary of functions 9 summary of functions 10
clipping text 323
list of rectangles, setting text underline 330
to 300 XOR
setting 281, 332 bitmaps 327
summary of functions 9 fill 295
widget, visible extent 830 stroke 322
colors text 327
best matches 188 configuration files
bitmaps 323 Boolean parameters
blue component 179 reading 849
calculating writing 862
top and bottom shading 178 character parameters
CMY, converting to RGB 183 reading 851
composite writing 864
data type 185 closing 836

September 20, 2005 Index 947

Index  2005, QNX Software Systems

entries decreasing 635

deleting 837 ignoring 674
getting as string 844 increasing 631
integer parameters updates
reading 853 holding off 631
writing 866 permitting 635
long parameters contexts
reading 855 draw
writing 868 getting current 375
opening 846 setting current 376
sections summary of functions 14
creating 840 graphical
deleting 838 attributes, resetting 191
seeking 861 creating 189
seeking next 842 current, getting 266
short parameters current, setting 299
reading 857 destroying 195
writing 870 draw buffer, clearing 180
string parameters draw mode, resetting 192
reading 859 fill, resetting 190
writing 872 plane mask, resetting 192
summary of functions 11 stroke (line) attributes,
connection ID, getting 416 resetting 193
connection information, summary of functions 19
getting 417 text attributes, resetting 194
consoles memory
current, getting coordinates activating 516
of 502 creating 506
switching 615 deactivating 518
containers draw buffer, incremental size
flux, determining if in 709 for 513
focus draw buffer, maximum size
finding 619 for 514
next 620 flushing 510
nullifying 633 releasing 512
previous 622 summary of functions 21
hold count type, setting 515

948 Index September 20, 2005

 2005, QNX Software Systems Index

printing data chains

activating 543 adding to 558, 666, 672
attributes, modifying 537 removing from 745
attributes, querying 528 summary of functions 13
creating 526 unlinking 782
deactivating 524, 546 dialogs
initializing 522, 534 file selection 652
page break 532 question 601
releasing 536 dimensions
summary of functions 27 data structure 381
widgets 547 widget, getting 799
control flags, getting 685 dithering
conventions, typographical xxiii bitmaps 324
coordinates fill 289
translation stroke 314
clearing 182 text 324
rectangles 645, 781 dragging
setting 328 starting 430
summary of functions 12 summary of functions 13
CRC (cyclic redundancy check), draw buffer
generating 874 clearing 180
cursors flushing 264
information about 452 resizing 283
moving draw contexts
absolute position 447 getting current 375
relative position 449 setting current 376
summary of functions 13 summary of functions 14
custom widgets draw events
summary of functions 33 region, emitting 307
cyclic redundancy check (CRC), draw mode
generating 874 resetting 192
setting 285
drawing attributes
plane mask, setting 305
D summary of functions 14
drawing primitives
dash 311 arcs 196

September 20, 2005 Index 949

Index  2005, QNX Software Systems

Bézier curve 207 asynchronous notification 411

beveled arrow 203 buffer size, getting 420
beveled box 200 buffer, resizing 755
beveled rectangle 203 checking for 409
bitmaps 210 data structure 382
bitmaps, repeatedly 235 data, getting 419
ellipses 213 device
grids 216 adding a handler 567
images 218, 223, 239, 257 removing a handler 588
lines 221 emitting 401, 404
pixels 225, 226 forwarding to window
polygons 228 manager 678, 680
rectangles 232 handlers, main loop 713
rectangles, rounded 242 input/output
spans 245 summary of functions 19
summary of functions 25 key
text 250, 255 data structure 434
trend 259 ISO8859-1 value 490
UTF-8 value 438
key, translating
summary of functions 21
E modal processing 724
Photon, processing
ellipses, drawing 213 outstanding 606
environment variables processing 724
ABLPATH 68, 127 rectangle set, getting 422
HOME 522, 537 regions
PATH 769 data structure 414
PHFONTMEM 150 summary of functions 16
PHIG 357, 362, 364, 447, synchronous notification 407
449, 452, 455, 501 timer, arming 488, 780
PHOTON 349, 736 types 382
PHOTON PATH 522 widget, sending to 757
errno 88 widgets involved in 648
error messages, displaying 88 extents
events getting 800
arming the Photon channel 400 querying visible 501

950 Index September 20, 2005

 2005, QNX Software Systems Index

recalculating 649, 650 focus

visible 830 child widget, closest
focusable 669
container
finding 619
F next 620
nullifying 633
family hierarchy previous 622
child of a given class, giving 624
finding 661, 663 global
container parent, finding 665 next after focused widget,
summary of functions 39 giving to 693
fd functions next after given widget, giving
adding 567 to 695
changing modes 596 next before focused widget,
prototype 651 giving to 697
removing 588 next before given widget,
file descriptors, reducing number giving to 699
of 124 next container’s widget,
file-descriptor handlers giving to 694
adding 567 previous container’s widget,
changing modes 596 giving to 698
prototype 651 summary of functions 41
removing 588 widget, determining degree
files of 710
selecting 652 FontDetails 169
fill attributes FontQueryInfo 166
color 287 fonts
dithering 289 characters, obtaining 161
resetting 190 extent, calculating 153, 155,
summary of functions 14 157
transparency 293 fractional scaling
XOR color 295 extent, calculating 157
flags, control, getting 685 rendering 159
flux count glyphs, obtaining 161
decrementing 646 information, querying 166
incrementing 776 list of 168

September 20, 2005 Index 951

Index  2005, QNX Software Systems

metrics current, getting 266

loading 165 current, setting 299
unloading 173 destroying 195
rendering 159, 171 draw buffer, clearing 180
selecting 675 draw mode, resetting 192
server fill, resetting 190
attaching 150 plane mask, resetting 192
detaching 152 stroke (line) attributes,
preloading fonts 163 resetting 193
setting 297 summary of functions 19
summary of functions 17 text attributes, resetting 194
frame size, determining 682 grids, drawing 216

G H
geometry help
area 348 quitting 875
dimensions 381 searching 876
point 451 summary of functions 24
rectangle 463 topic path 879
summary of functions 18 topic path root 881
widgets topic tree 882
area, based on canvas 761 URL 884
area, based on extent 759 URL root 886
area, getting 787 widget with help topic, finding
dimensions, getting 799 first 805
extent, recalculating 649, HELP SEARCH METHOD EXACT 876
650 HELP SEARCH METHOD SUBSTRING
extent, visible 830 877
offset, getting 813 HELP SEARCH METHOD WORD 877
positions, absolute 608 HELP SEARCH MODE DISPLAYED 876
summary of functions 43 HELP SEARCH MODE TEXT 876
graphical contexts HELP SEARCH MODE TITLE 876
attributes, resetting 191 HELP SEARCH SCOPE ALL 876
creating 189 HELP SEARCH SCOPE SELECTED 876

952 Index September 20, 2005

 2005, QNX Software Systems Index

hierarchy ghosting 223, 441

class loading 887
summary of functions 33 supported formats 890
widget, determining 808, memory allocation 888
810 releasing members 483
widget, getting 795 summary of functions 7
family tag 425
child of a given class, transparency mask 442, 889
finding 661, 663 types 426
container parent, finding 665 INITIAL PC 537, 721
summary of functions 39 input handler
hold count adding 570
containers prototype 708
decreasing 635 removing 589
ignoring 674 input/output events
increasing 631 summary of functions 19
global INTERACTIVE PC 537, 721
decreasing 740, 784 internal links 76
increasing 702 interprocess communication (IPC)
HOME 522, 537 channels
hotkey handlers use by widget library 610
adding 563 Neutrino channel,
removing 750 attaching 355
summary of functions 31 process ID, getting from receive
ID 689
summary of functions 20
ionotify() 571
I
images
cyclic redundancy check J
(CRC) 425, 874
data structure 424 joins 316
drawing 223 jump gates
primitive functions 218, 257 application, sending
repeatedly 239 through 736
extracting from databases 96 summary of functions 21

September 20, 2005 Index 953

Index  2005, QNX Software Systems

K deactivating 518
draw buffer
key events incremental size 513
translating maximum size 514
summary of functions 21 flushing 510
UTF-8 value 438 releasing 512
keys, modifier 434 summary of functions 21
type, setting 515
memory, shared
attaching 334
L cleaning up 336
creating 338
libraries
destroying 340
version number 439
detaching 341
widget, initialization 706
summary of functions 29
line attributes
menus
caps 308
items
color 310
getting text 100
dash 311
setting state 110
dithering 314
setting text 112
joins 316
position, setting 720
resetting 193
summary of functions 44
summary of functions 14
messages
transparency 319
displaying 714
width 320
errors, displaying 88
XOR color 322
summary of functions 22
lines, drawing 221
modal processing
link callbacks
ending 715
determining the initiator 129
events 724
starting 716
summary of functions 22
M modifier keys 434
modules
main loop 713 creating 76
memory contexts location, specifying 116
activating 516 parent, specifying 118
creating 506 setup function, specifying 114

954 Index September 20, 2005

 2005, QNX Software Systems Index

setup functions Pg DRAW FILL 242

information structure 106 Pg DRAW FILL STROKE 242
summary of functions 23 Pg DRAW STROKE 242
widget instance pointer, Pg GHOST 223, 441
getting 98 Pg IMAGE CLASS DIRECT 429
widget instance pointer, getting Pg IMAGE CLASS GRADIENT 428
within 104 Pg IMAGE CLASS MASK 428
widgets, determining which Pg IMAGE CLASS PALETTE 428
initiated a link callback Pg IMAGE DIRECT 444 428
129 Pg IMAGE DIRECT 555 427
multibyte-character strings Pg IMAGE DIRECT 565 427
comparing 141 Pg IMAGE DIRECT 888 427, 507
counting 134, 138, 142 Pg IMAGE DIRECT 8888 427
searching 136, 139 Pg IMAGE GRADIENT BYTE 428
searching backwards 144 Pg IMAGE GRADIENT NIBBLE 428
summary of functions 23 Pg IMAGE PALETTE BYTE 426,
442, 507
Pg IMAGE PALETTE NIBBLE 427,
442
N Pg INDEX COLOR 442
Pg MAX PALETTE 267
Neutrino channel, attaching 355 Pg PALSET FORCE EXPOSE 303
NOTIFY ACTION TRANARMC 568 Pg PALSET GLOBAL 303
NOTIFY COND MASK 586 Pg PALSET HARD 302
NOTIFY DATA MASK 571 Pg PALSET HARDINACTIVE 303
Pg PALSET HARDLOCKED 303
Pg PALSET SOFT 303
Pg REPBM ALTERNATE 239
P Pg TEXT BOTTOM 255
palette Pg TEXT CENTER 255
getting current 267 Pg TEXT LEFT 255
setting current 302 Pg TEXT MIDDLE 255
PATH 769 Pg TEXT RIGHT 255
pathname delimiter in QNX Pg TEXT TOP 255
Momentics documentation Pg TEXT WIDECHAR 255
xxiv PhAB
Pg BACK FILL 255 information structure 106

September 20, 2005 Index 955

Index  2005, QNX Software Systems

Ph AUXPTR REGION 456 Ph EV DRAG START 391

Ph BACK EVENT 383 Ph EV DRAW 391, 456
Ph BUTTON ADJUST 387, 436, Ph EVENT ABSOLUTE 384, 468
453 Ph EVENT DIRECT 384
Ph BUTTON MENU 387, 436, 453 Ph EVENT INCLUSIVE 383, 384
Ph BUTTON SELECT 387, 436, Ph EVENT MSG 407, 409
453 Ph EV EXPOSE 385, 391, 456, 467,
Ph CAPTURE EXPOSE 264, 392 470, 492
PhClipHeader 474 Ph EV FEP 393, 396
PhConnectInfo t 417 Ph EV INFO 392, 457
PhCursorDef t 474 Ph EV INVALIDATE SYSINFO 393
Ph CURSOR INHERIT 465 Ph EV KEY 394, 431, 456
Ph CURSOR NO INHERIT 465 Ph EV LB SYSTEM 457
Ph DIRECTED FOCUS 383 Ph EV PTR ENTER 385
Ph DONE DRAW 264 Ph EV PTR LEAVE 386
PhDragEvent t 389 Ph EV PTR MOTION BUTTON 394,
Ph DRAG KEY MOTION 389, 431 431, 456
Ph DRAG NOBUTTON 389, 431 Ph EV PTR MOTION NOBUTTON 394,
Ph DRAG TRACK 389, 430 431, 456
PhDrawEvent t 391 Ph EV PTR STEADY 386
Ph DYNAMIC BUFFER 350, 407, Ph EV PTR UNSTEADY 386
409, 420 Ph EV RAW 457
Ph EMIT TOWARD 384 Ph EV RELEASE ENDCLICK 388
Ph EV AMIN 456 Ph EV RELEASE PHANTOM 388
Ph EV BLIT 456 Ph EV RELEASE REAL 388
Ph EV BOUNDARY 385, 456 Ph EV REMOTE WM 395
Ph EV BUT PRESS 386, 452, 456 Ph EV SERVICE 395, 457
Ph EV BUT RELEASE 388, 456 Ph EV SYSTEM 397, 457
Ph EV BUT REPEAT 388, 457 Ph EV TIMER 398, 457, 780
Ph EV COVERED 388, 456 Ph EV WM 399, 457
Ph EV DRAG 389, 430, 431, 456 Ph EV WM EVENT 399
Ph EV DRAG BOUNDARY 390 Ph EXPOSE FAMILY 470, 492
Ph EV DRAG COMPLETE 390 Ph EXPOSE REGION 470, 492
Ph EV DRAG INIT 390 Ph FAKE EVENT 383
Ph EV DRAG KEY EVENT 390 Ph FEP ACTIVATE 397
Ph EV DRAG MOTION EVENT 391 Ph FEP BROADCAST 393, 396
Ph EV DRAG MOVE 391 Ph FEP CHINESE 393

956 Index September 20, 2005

 2005, QNX Software Systems Index

Ph FEP DEACTIVATE 397 PhKbdRegionData t 474

Ph FEP DEREGISTER 393 Ph LIB VERSION 439
PhFEPInfo t 393 PhLibVersion() 439
Ph FEP JAPANESE 393 PhNO HOLD 350
Ph FEP KOREAN 393 PhNO PROXY 350
Ph FEP NORECT 397 Ph NORMAL DRAW 264
Ph FEP RECT 397 Ph NORMAL EXPOSE 392
Ph FEP REGISTER 393, 396 Ph NOT CUAKEY 394
PhFEPService t 396 Ph NOT HOTKEY 394
Ph FOCUS BRANCH 383 PHOTON 349, 736
PHFONT ALL FONTS 168, 676 Photon Application Builder (PhAB)
PHFONT BITMAP 168, 675 summary of functions 24
PHFONT FIXED 168, 675 Photon channels
PHFONT INFO BLDITC 166, 169 arming for events 400
PHFONT INFO BOLD 166, 169 attaching 706
PHFONT INFO FIXED 166, 169 connection information 417
PHFONT INFO ITALIC 166, 169 events
PHFONT INFO PLAIN 166, 169 checking for 409
PHFONT INFO PROP 166, 169 Photon services
PHFONT LOAD IMAGES 163 attaching 349
PHFONT LOAD METRICS 163 detaching 379
PHFONTMEM 150 reattaching 461
PHFONT PROP 168, 675 summary of functions 25
PHFONT SCALABLE 168, 675 PHOTON PATH 522
Ph FORCE BOUNDARY 385, 456, PhPointerEvent t 386
467 Ph PRINT REGION 456
Ph FORCE FRONT 456, 467 Ph PTR REGION 456, 467
PhGrafxDetail t 474 PhPtrRegionData t 474
Ph GRAFX REGION 456, 467 Ph QUERY EXACT 501
PhGrafxRegionData t 474 Ph QUERY GRAPHICS 501
Ph GRAPHIC EXPOSE 392 Ph QUERY IG POINTER 501
PHIG 357, 362, 364, 447, 449, Ph QUERY IG REGION 502
452, 455, 501 Ph QUERY INPUT GROUP 501
PhIgRegionData t 474 Ph RDATA CLIPBOARD 474
Ph INPUTGROUP REGION 456, Ph RDATA CURSOR 474
467 Ph RDATA GFXDETAIL 474
Ph KBD REGION 456, 467 Ph RDATA GFXINFO 474

September 20, 2005 Index 957

Index  2005, QNX Software Systems

Ph RDATA IG 474 Ph TRACK LEFT 389, 430

Ph RDATA INPMGRINFO 474 Ph TRACK RIGHT 389, 430
Ph RDATA KBDINFO 474 Ph TRACK TOP 390, 430
Ph RDATA PTRINFO 474 Ph TYPE SPECIFIC 383
Ph RDATA USER 474 Ph USER RSRVD BITS 383
Ph RDATA WINDOW 474 PhWindowInfo t 474
Ph RDATA WMCONFIG 474 Ph WINDOW REGION 456, 467
Ph REGION BEHIND 476 Ph WM BACKDROP 496, 497
Ph REGION CURSOR 476 Ph WM CLOSE 495
Ph REGION DATA 476 Ph WM CONSWITCH 496
PhRegionDataHdr t 474 Ph WM EVSTATE FFRONT 497
Ph REGION EV OPAQUE 476 Ph WM EVSTATE FFRONT DISABLE
Ph REGION EV SENSE 476 497
Ph REGION FLAGS 476 Ph WM EVSTATE FOCUS 497
Ph REGION HANDLE 476 Ph WM EVSTATE FOCUSLOST 497
Ph REGION IN FRONT 476 Ph WM EVSTATE HIDE 497
Ph REGION ORIGIN 476 Ph WM EVSTATE INVERSE 497
Ph REGION OWNER 476 Ph WM EVSTATE MENU 497
Ph REGION PARENT 476 Ph WM EVSTATE MENU FINISH 497
Ph REGION RECT 476 Ph WM EVSTATE PERFORM 497
Ph RELEASE GHOST BITMAP 425, Ph WM EVSTATE UNHIDE 497
483 Ph WM FFRONT 496, 497
Ph RELEASE IMAGE 425, 483 Ph WM FOCUS 495, 497
Ph RELEASE IMAGE ALL 425, Ph WM HELP 496
483 Ph WM HIDE 496, 497
Ph RELEASE PALETTE 425, 483 Ph WM MAX 496, 497
Ph RELEASE TRANSPARENCY MASK Ph WM MENU 495, 497
425, 442, 483 Ph WM MOVE 496, 497
PhRemoteWMEvent t 395 Ph WM RESIZE 496, 497
Ph RESIZE MSG 407, 409, 420 Ph WM RESTORE 496, 497
Ph RIDQUERY IG POINTER 455 Ph WM STATE ISBACKDROP 496
Ph RIDQUERY TOWARD 455 Ph WM STATE ISHIDDEN 496
Ph ROOT RID 476 Ph WM STATE ISICONIFIED 496
Ph START DRAW 264 Ph WM STATE ISMAX 496
Ph SYSTEM REGION CHANGE 397 Ph WM STATE ISNORMAL 496
Ph TRACK BOTTOM 390, 430 Ph WM STATE ISTASKBAR 496
Ph TRACK DRAG 390, 430 Ph WM SUPERSELECT 680

958 Index September 20, 2005

 2005, QNX Software Systems Index

Ph WM TOBACK 495 point

Ph WM TOFRONT 495 data structure 451
Ph WND MGR REGION 456, 467 pointers
picture modules information about 452
creating 76 moving
pixels, drawing 225, 226 absolute position 447
PkKeyDef.h 436 relative position 449
Pk KF Cap Valid 435 summary of functions 13
Pk KF Compose 435 polygons, drawing 228
Pk KF Key Down 435 Pp PC COLLATING MODE 528,
Pk KF Key Repeat 435 539
Pk KF Scan Valid 435 Pp PC COLOR MODE 528, 539
Pk KF Sym Valid 435 Pp PC COMMENT 528, 539
Pk KM Alt 434 Pp PC CONTROL 528, 539
Pk KM AltGr 434 Pp PC COPIES 528, 539
Pk KM AltGr Lock 435 Pp PC DATE 528, 539
Pk KM Alt Lock 435 Pp PC DEVICE 528, 534, 539
Pk KM Caps Lock 435 Pp PC DITHERING 528, 539
Pk KM Ctrl 434 Pp PC DO PREVIEW 528, 539
Pk KM Ctrl Lock 434 Pp PC DRIVER 528
Pk KM Mod6 434 Pp PC DUPLEX 528, 539
Pk KM Mod6 Lock 435 Pp PC FILENAME 528, 534, 539
Pk KM Mod7 434 Pp PC INKTYPE 528, 539
Pk KM Mod7 Lock 435 Pp PC INTENSITY 528, 539
Pk KM Mod8 434 Pp PC JOB NAME 528, 539
Pk KM Mod8 Lock 435 Pp PC LOCATION 528, 539
Pk KM Num Lock 435 Pp PC MARGINS 528, 539
Pk KM Scroll Lock 435 Pp PC NAME 528, 534, 539
Pk KM Shift 434 Pp PC NONPRINT MARGINS 528,
Pk KM Shift Lock 434 539
Pk KM Shl3 434 Pp PC ORIENTATION 528, 539
Pk KM Shl3 Lock 435 Pp PC PAGE RANGE 528, 539
plane mask Pp PC PAPER SIZE 528, 539
resetting 192 Pp PC PAPER SOURCE 528, 539
setting 305 Pp PC PAPER TYPE 528, 539
Pm IMAGE CONTEXT 515 Pp PC PREVIEW APP 528, 539
Pm PHS CONTEXT 515

September 20, 2005 Index 959

Index  2005, QNX Software Systems

Pp PC PRINTER RESOLUTION 528, Pt ARG BORDER WIDTH 682

539 Pt ARG FLAGS 483, 620, 622,
Pp PC PROP APP 528, 539 624, 734
Pp PC SCALE 528, 539 Pt ARG POS 720
Pp PC SOURCE COLORS 528, 539 Pt BALLOON BOTTOM 704
Pp PC SOURCE OFFSET 528, 539 Pt BALLOON INPLACE 704
Pp PC SOURCE RESOLUTION 528, Pt BALLOON LEFT 704
539 Pt BALLOON RIGHT 704
Pp PC SOURCE SIZE 528, 539 Pt BALLOON TOP 704
Pp PC USER ID 528, 539 PtBasic
PRINTER GLOBAL 537 canvas, determining 604
PRINTER LOCAL 537 Pt BLOCKED 624, 716
printing Pt CB ACTIVATE 564
completing 524 Pt CB HOTKEY
contexts adding 563
activating 543 removing 750
attributes, modifying 537 Pt CB LOST FOCUS 625
attributes, querying 528 Pt CB RAW
creating 526 adding 560, 562
deactivating 546 removing 747, 749
initializing 522 Pt CLEAN RESOURCES 797
releasing 536 Pt CLEAR 646
initalizing 534 PtComboBox
page break 532 zzzzzzzzzz
summary of functions 27 summary of functions 44
widgets 547 Pt CONTAINER 797
processes Pt DELAY REALIZE 734
ID, getting from receive ID Pt DESTROYED 643
(RCVID) 689 PtDestroyWidget() 643
spawning 769 Pt DISJOINT 667, 797
spawning and waiting 774 Pt FD DRAIN 568
summary of functions 27 Pt FD NOPOLL 568
termination callback Pt FD OBAND 567, 596
adding 773 Pt FD READ 567, 596
deleting 772 Pt FD WRITE 567, 596
prompts Pt FEP PRESENT 685
summary of functions 22 Pt FEP QUERIED 685

960 Index September 20, 2005

 2005, QNX Software Systems Index

PtFileSel Pt PP RESIZE PC 547

summary of functions 45 Pt PP RESIZE WIDGET 547
Pt FORCE UNREALIZE 797 Pt PRINTSEL ALL PANES 721
Pt FREE MEMORY 483 Pt PRINTSEL CANCEL 722
Pt FSDIALOG BTN1 652, 653 Pt PRINTSEL DFLT LOOK 722
Pt FSDIALOG BTN2 653 Pt PRINTSEL NO COLLATE 722
Pt FSDIALOG NO FCHECK 654, Pt PRINTSEL NO COPIES 722
656 Pt PRINTSEL NO PAGE RANGE 722
Pt FSDIALOG NO FSPEC 654 Pt PRINTSEL NO SELECT RANGE
Pt FSDIALOG NO UP BUTTON 654 722
Pt FSDIALOG SHOW HIDDEN 654 Pt PRINTSEL PREVIEW 722
PtGenList Pt PRINTSEL PRINT 722
summary of functions 47 Pt PRINTSEL PROP APP 722
PtGenTree Pt PROCREATED 670
summary of functions 49 Pt RECTANGULAR 798
Pt GETS FOCUS 620, 622, 624 Pt SUBORDINATES CHILD 611
Pt GHOST 223, 441 PtTerminal
Pt HOTKEY IGNORE MODS 563 summary of functions 54
Pt HOTKEY SYM 563 PtText
PtHtml summary of functions 55
summary of functions 52 Pt TRAVERSE BACK 826
Pt IMMEDIATE CHILD 611 Pt TRAVERSE DONE 824
Pt INDEX RESOURCES 797 Pt TRAVERSE FORCE 827
Pt IN EXPOSE 685 Pt TRAVERSE LAST 826
PtLabel Pt TRAVERSE ROOT 826
canvas, determining 711 Pt TRAVERSE START 824, 826
PtList PtTree
summary of functions 52 summary of functions 56
PtMenuButton 720 PtTty
PtMessage summary of functions 58
summary of functions 53 Pt UNCLEAN RESOURCES 798
PtMultiText PtWidget
summary of functions 53 canvas, determining 790
Pt NO INHERITED RESOURCES 797 PtWindow
Pt OBSCURED 646 summary of functions 58
Pt OCCLUSIVE 798 pulses, Photon
Pt PP NO RESIZE 548 arming 725, 727

September 20, 2005 Index 961

Index  2005, QNX Software Systems

creating 580 Q
deleting 582
delivering to a process 729 question dialog 601
delivering to yourself 586
disarming 731
PX XXX SUPPORT 890
PXCONFIG CREATE 846
R
PXCONFIG FMT BOOL ON 862
receive ID (RCVID), getting process
PXCONFIG FMT BOOL TRUE 862
ID (PID) from 689
PXCONFIG FMT BOOL YES 862
rectangles
PXCONFIG FMT CHAR CHAR 864
data structure 463
PXCONFIG FMT CHAR HEX 864
drawing
PXCONFIG FMT INT DECIMAL 866,
beveled 203
868, 870 rounded 242
PXCONFIG FMT INT HEX 866,
intersection of 738
868, 870 union of 739
PXCONFIG FMT STRING 872
rectangles, drawing 232
PXCONFIG READ 846
regions
PXCONFIG WRITE 846
blitting 353
PX DIRECT COLOR 888
closing 472
PX DODITHER 888
console, switching to 831
PX IMAGE 888
data
PxImage.h 890
header 474
PX IMAGE MODULES 890
searching by type 473
PX LOAD 888
data structure 465
PxMethods t 887
disjoint 667, 797
PX NORMAL 888
events 382
PX PALETTE 888
data structure 414
PX QUERY 887
graphical contexts 189
PX SUPPRESS TAG 888
querying 455, 481
PX TRANSPARENT 888, 889
summary of functions 28
PX USECOLORS 888, 889
system information 459
widgets 817
windows
actions, data structure 495
REMOTE FLAG FIXED 396
REMOTE FLAG INITIAL 396

962 Index September 20, 2005

 2005, QNX Software Systems Index

REMOTE FLAG IS ORIGIN 396 summary of functions 29

REMOTE FLAG NO DIM 396 spans, drawing 245
REMOTE WM TITLE 395 strings
REMOTE WM WINDOW 395 drawing 248
resources extent, calculating 153, 155,
argument lists 598, 599, 762 157
flags, getting 804 multibyte-character
getting 691 comparing 141
record file, closing 124 length, calculating 134, 138,
setting 766 142
summary of functions 59 searching 136, 139
rounded rectangles, drawing 242 searching backwards 144
RtTrend summary of functions 23
summary of functions 59 rendering 159, 171
translating
summary of functions 29
stroke attributes
S caps 308
color 310
services, Photon dash 311
attaching 349 dithering 314
detaching 379 joins 316
reattaching 461 resetting 193
summary of functions 25 summary of functions 14
shared memory transparency 319
attaching 334 width 320
cleaning up 336 XOR color 322
creating 338 system information
destroying 340 connection 417
detaching 341 connection ID 416
summary of functions 29 for a region 459
SIGCHLD 770 for a widget 732
SIG DFL 592 summary of functions 30
signal handlers
adding 574
prototype 768
removing 590, 592

September 20, 2005 Index 963

Index  2005, QNX Software Systems

T from UTF-8 901, 909

installing 906
text listing supported 904
attributes, resetting 194 summary of functions 8
drawing 250, 255 tables, building 895
extent, calculating 153, 155, tables, loading 897
157, 262 tables, saving 899
rendering 159, 171 to UTF-8 911, 913
summary of functions 30 unknown 916
text attributes coordinates
color 323 clearing 182
dithering 324 rectangles 645, 781
font 297 setting 328
transparency 326 summary of functions 12
underline 330 key events
XOR color 327 summary of functions 21
tiles strings
clipping one list from summary of functions 29
another 371 translation files
combining 373 appending 68
converting from rectangles 464 changing to another 127
converting to rectangles 487 transparency
copying a list 374 bitmaps 326
data structure 486 fill 293
determining intersection of two images 442, 889
lists 433 stroke 319
freeing 415 text 326
getting 423 trend, drawing 259
merging 446 typographical conventions xxiii
merging two lists, eliminating
overlap 346
sorting 485
summary of functions 30 U
translating 380, 491
timer events, arming 488, 780 UTF-8
translation translating characters
characters from 901, 909

964 Index September 20, 2005

 2005, QNX Software Systems Index

translating characters to 911, backmost 792, 794

913 class
getting 795
class hierarchy
class, determining 808, 810
V summary of functions 33
classes, adding 66
video memory coordinates 684
draw mode, setting 285 creating 637
protecting 305 summary of functions 33
creating from a database 80,
83
custom
W summary of functions 33
wide characters damage
converting to lowercase 922 flux count,
summary of functions 31 decrementing 646
widget databases flux count, incrementing 776
bitmaps, freeing 91 damaging
bitmaps, loading 93 an area 639
closing 72 completely 641
images, extracting 96 container, determining if in
opening 122 flux 709
saving 125 summary of functions 38
summary of functions 38 default parent
text, getting translated 102 creating children 637
widgets getting 688
copying 74 setting 764
deleting 86 destroying 643
widgets all within a container 613
balloons, inflating 704 summary of functions 33
brother determining relationship 611
behind 788 events
in front 789 sending to 757
child extents, getting 800
focusable, finding 669 family hierarchy
children

September 20, 2005 Index 965

Index  2005, QNX Software Systems

child of a given class, extent, recalculating 649,

finding 661, 663 650
container parent, finding 665 extent, visible 830
skipping 818 offset, getting 813
summary of functions 39 positions, absolute 608
traversing, front to back 824, summary of functions 43
826 guardian 670
traversing, top to bottom 802 help topic, finding first
finding with 805
in an area 617 inserting 806
summary of functions 41 instance name, getting 108
the nth in a container 701 instance pointer withing a
the nth in an area 629 module, getting 104
flags library initialization 706
class structure 797 summary of functions 44
focus menus
container 619, 620, 622, 633 position, setting 720
degree of, determining 710 summary of functions 44
giving 624 module instance pointer,
global, giving to next after getting 98
focused widget 693 moving
global, giving to next after to back 820
given widget 695 to front 822
global, giving to next before parents
focused widget 697 getting 815
global, giving to next before nearest of a given class 686
given widget 699 valid, finding 785
global, giving to next PhAB name, getting 120
container’s widget 694 position 684
global, giving to previous printing 547
container’s widget 698 PtComboBox
summary of functions 41 summary of functions 44
geometry PtFileSel
area, based on canvas 761 summary of functions 45
area, based on extent 759 PtGenList
area, getting 787 summary of functions 47
dimensions, getting 799 PtGenTree

966 Index September 20, 2005

 2005, QNX Software Systems Index

summary of functions 49 updates

PtHtml forcing 674
summary of functions 52 hold count, containers 631,
PtList 635
summary of functions 52 holding off 702
PtMessage permitting 740, 784
summary of functions 53 summary of functions 59
PtMultiText synchronizing a widget 779
summary of functions 53 synchronizing Photon 777
PtTerminal window manager
summary of functions 54 consoles, switching 615
PtText forwarding events 678, 680
summary of functions 55 summary of functions 60
PtTree windows
summary of functions 56 actions, data structure 495
PtTty disjoint 667
summary of functions 58 frame size, determining 682
PtWindow regions
summary of functions 58 changing attributes 492
realizing closing 494
determining if 812 opening 499
summary of functions 58 WmConfig t 474
region ID, getting 817 work procedures
reparenting 752 adding 576
rerealizing 734, 754 prototype 832
resources removing 594
argument lists 598, 599, 762
flags, getting 804
getting 691
setting 766 X
summary of functions 59
RtTrend XOR color
summary of functions 59 bitmaps 327
system information 732 fill 295
top-level, finding 719 stroke 322
unrealizing 783 text 327
summary of functions 58

September 20, 2005 Index 967