QNX Neutrino Realtime Operating Systemfusion.qnx.com/7/9357/Photon_widget_ref.pdf · QNX Neutrino...

QNX Neutrino Realtime

Operating SystemPhoton microGUI

Widget Reference

For QNX Neutrino 6.3

2004, QNX Software Systems Ltd.

QNX Software Systems Ltd.175 Terence Matthews CrescentKanata, OntarioK2M 1W8CanadaVoice: +1 613 591-0931Fax: +1 613 591-3579Email: [email protected]: http://www.qnx.com/

1996 – 2004, QNX Software Systems Ltd. All rights reserved.

Technical support options

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

QNX, Momentics, Neutrino, and Photon microGUI are registered trademarks of QNX Software Systems Ltd. in certain jurisdictions. All other trademarks and

trade names belong to their respective owners.

Contents

About This Reference xviiWhat’s new in Photon for QNX Neutrino 6.3 xix

New widgets xx

Changes xx

What’s new in Photon for QNX Neutrino 6.2.1 xxiv

Changes xxiv

Errata xxiv

What’s new in Photon for QNX Neutrino 6.2.0 xxv

What’s new in Photon for QNX Neutrino 6.1.0 xxvi

What’s new in Photon for QNX Neutrino 6.0 xxvii

New widgets xxvii

Deprecated widgets xxvii

Other changes xxviii

Global Data Structures 11PtBalloonCallback t 5

PtCallback t 7

PtCallbackInfo t 9

PtHotkeyCallback t 11

PtRawCallback t 13

Widgets 152Widget hierarchy 17

Widget icons in PhAB 18

What’s in a widget description? 24

May 31, 2004 Contents iii


PtArc 28

PtBarGraph 34

PtBasic 42

PtBezier 68

PtBkgd 73

PtButton 80

PtCalendar 88

PtClient 102

PtClock 112

PtColorPanel 124

PtColorPatch 129

PtColorSel 135

PtColorSelGroup 143

PtColorWell 148

PtComboBox 154

PtComboBoxListClose() 169

PtComboBoxListOpen() 170

PtCompound 171

PtContainer 175

PtDisjoint 195

PtDivider 200

PtEllipse 208

PtFileSel 212

PtFSAddAfter() 240

PtFSAddFirst() 242

PtFSAllItems() 244

PtFSAllocItem() 245

PtFSClearSelection() 248

PtFSDamageItem() 249

PtFSExpandParents() 250

PtFSFolderCollapse() 251

PtFSFolderExpand() 252

iv Contents May 31, 2004


PtFSFreeAllItems() 253

PtFSFreeItems() 254

PtFSGetCurrent() 255

PtFSGetSelIndexes() 256

PtFSGoto() 257

PtFSItemIndex() 258

PtFSRemoveChildren() 259

PtFSRemoveItem() 261

PtFSRemoveList() 263

PtFSRootItem() 265

PtFSSelect() 266

PtFSSelectedItems() 267

PtFSSetSelIndexes() 268

PtFSShow() 269

PtFSUnselect() 270

PtFSUnselectNonBrothers() 271

PtFlash 272

PtFontSel 276

PtGauge 287

PtGenList 297

PtGenListAddItems() 321

PtGenListAllItems() 323

PtGenListClearSelection() 324

PtGenListCreateTextBalloon() 325

PtGenListDamageItem() 327

PtGenListDrawBackground() 328

PtGenListDrawString() 330

PtGenListFirstItem() 332

PtGenListGetCurrent() 333

PtGenListGetSelIndexes() 334

PtGenListGoto() 335

PtGenListHold() 336

May 31, 2004 Contents v


PtGenListItem t 337

PtGenListItemIndex() 340

PtGenListItemRealloc() 341

PtGenListLastItem() 342

PtGenListLockItem() 343

PtGenListRelease() 344

PtGenListRemoveItems() 345

PtGenListResize() 347

PtGenListSelect() 348

PtGenListSelectedItems() 349

PtGenListSetColumnBalloon() 350

PtGenListSetGflags() 351

PtGenListSetSelIndexes() 352

PtGenListShow() 354

PtGenListUnlockItem() 355

PtGenListUnselect() 356

PtGenTree 357

PtGenTreeAddAfter() 369

PtGenTreeAddFirst() 370

PtGenTreeAllItems() 372

PtGenTreeClearSelection() 373

PtGenTreeCollapse() 374

PtGenTreeDamageItem() 375

PtGenTreeExpand() 376

PtGenTreeExpandParents() 378

PtGenTreeFreeAllItems() 379

PtGenTreeFreeItems() 380

PtGenTreeGetCurrent() 381

PtGenTreeGetSelIndexes() 382

PtGenTreeGoto() 383

PtGenTreeItem t 384

PtGenTreeItemIndex() 387

vi Contents May 31, 2004


PtGenTreeItemRealloc() 388

PtGenTreeItemResize() 389

PtGenTreeRemoveChildren() 390

PtGenTreeRemoveItem() 391

PtGenTreeRemoveList() 392

PtGenTreeResize() 393

PtGenTreeRootItem() 394

PtGenTreeSelect() 395

PtGenTreeSelectedItems() 396

PtGenTreeSetSelIndexes() 397

PtGenTreeShow() 399

PtGenTreeUnselect() 401

PtGenTreeUnselectNonBrothers() 402

PtGraphic 403

PtGrid 417

PtGroup 422

PtLabel 431

PtLine 450

PtList 455

PtListAddItems() 471

PtListDeleteAllItems() 473

PtListDeleteItemPos() 474

PtListDeleteItems() 475

PtListGotoPos() 476

PtListItemExists() 477

PtListItemPos() 478

PtListRemovePositions() 479

PtListReplaceItemPos() 480

PtListReplaceItems() 481

PtListSelectPos() 482

PtListShowPos() 483

PtListUnselectPos() 484

May 31, 2004 Contents vii


PtMenu 485

PtMenuBar 503

PtMenuButton 508

PtMeter 515

PtMTrend 532

PtMTrendAddData(), PtMTrendChangeData() 545

PtMultiText 547

PtMultiLines t 581

PtMultiTextAttributes t 583

PtMultiTextCallback t, PtMultiTextControl t,PtMultiTextInfo t 585

PtMultiTextCreateAttributes() 587

PtMultiTextGetAttributes() 588

PtMultiTextInfo() 592

PtMultiTextLine t 595

PtMultiTextModifyAttributes() 597

PtMultiTextModifyText() 599

PtMultiTextQuery t 601

PtMultiTextSegment t 603

PtNumeric 605

PtNumericFloat 611

PtNumericInteger 619

PtOnOffButton 627

PtOSContainer 633

PtPane 637

PtPanelGroup 641

PtPGCreatePopup() 656

PtPGFindIndexByPanel() 659

PtPGFindIndexByTitle() 660

PtPGFindPanelByIndex() 661

PtPGFindPanelByTitle() 662

PtPGFindTitleByIndex() 663

PtPixel 664

viii Contents May 31, 2004


PtPolygon 668

PtPrintSel 673

PtProgress 687

PtProgressEntireSegment() 694

PtProgressFirstSegment() 696

PtProgressNextSegment() 698

PtProgressTextRect() 700

PtRaw 701

PtRawList 711

PtRawTree 725

PtRect 736

PtRegion 741

PtScrollArea 750

PtScrollAreaCanvas() 761

PtScrollbar 762

PtScrollContainer 773

PtSeparator 780

PtServer 790

PtSlider 799

PtTab 811

PtTerminal 818

PtTerminalCharset t, PtTerminalCharsets t 858

PtTerminalCopy() 861

PtTerminalCreateCsXlat() 862

PtTerminalDefaultCharsets() 864

PtTerminalFontInfo() 865

PtTerminalGetKeys() 867

PtTerminalGetSelection() 869

PtTerminalName() 870

PtTerminalPasteClipboard() 871

PtTerminalPasteSelection() 872

PtTerminalPut(), PtTerminalPutc(), PtTerminalPuts() 873

May 31, 2004 Contents ix


PtTerminalSelectWord() 875

PtText 877

PtTextCallback t, PtTextControl t,PtTextControlInfo t 909

PtTextGetSelection() 911

PtTextModifyText() 912

PtTextSetSelection() 914

PtTimer 916

PtToggleButton 920

PtToolbar 928

PtToolbarGroup 934

PtTree 939

PtTreeAddAfter() 966

PtTreeAddFirst() 968

PtTreeAddImages() 970

PtTreeAllItems() 972

PtTreeAllocItem() 974

PtTreeChangeItem() 976

PtTreeClearSelection() 978

PtTreeCollapse() 979

PtTreeCreateItem() 980

PtTreeExpand() 983

PtTreeFreeAllItems() 985

PtTreeFreeItems() 986

PtTreeGetCurrent() 987

PtTreeGetSelIndexes() 988

PtTreeGoto() 990

PtTreeItem t 991

PtTreeItemAttributes t 993

PtTreeItemIndex() 995

PtTreeModifyItem() 996

PtTreeModifyItemString() 998

PtTreeRemoveChildren() 999

x Contents May 31, 2004


PtTreeRemoveItem() 1001

PtTreeRemoveList() 1003

PtTreeRootItem() 1005

PtTreeSelect() 1006

PtTreeSelectedItems() 1007

PtTreeSetSelIndexes() 1009

PtTreeShow() 1010

PtTreeUnselect() 1012

PtTreeUnselectNonBrothers() 1013

PtTrend 1014

PtTrendChangeData(), PtTrendChangeTrendData() 1027

PtTty 1030

PtTtyShell() 1051

PtWebClient 1052

PtWidget 1148

PtWindow 1181

PtWindowFocus() 1202

PtWindowGetState() 1204

PtWindowToBack() 1206

PtWindowToFront() 1208

Glossary 1211

Index 1233

May 31, 2004 Contents xi

List of Figures

The Photon widget hierarchy. 17

Instances of PtArc: arcs, circles, ellipses, wedges, and chords.28

A PtBarGraph widget. 34

A widget displaying all the border components. 45

A widget displaying a half-round bevel. 45

A Bezier curve created by PtBezier. 68

Several different styles of background widgets. 73

A PtButton widget. 80

A PtCalendar widget. 88

Analog, digital, and LED clocks created by PtClock. 112

A PtColorPanel widget. 124

A PtColorPatch widget. 129

A PtColorSelGroup widget. 143

A PtColorWell widget. 148

A PtComboBox widget provides a text-entry area and a list ofchoices. 154

Two PtDivider widgets: one contains two lists, the othercontains some buttons. 200

A PtEllipse widget. 208

A PtFileSel widget. 212

A single-level file selector. 214

The results of using PtFSAddAfter(). 240

The results of using PtFSAddFirst(). 242

The results of using PtFSRemoveChildren(). 259

The results of using PtFSRemoveItem(). 261

May 31, 2004 List of Figures xiii


The results of using PtFSRemoveList(). 263

A PtFontSel widget. 277

A five-pointed star before clipping. 407

The star after clipping. 408

A PtGrid widget. 417

A group of buttons. 422

A text string in a PtLabel widget. 431

A PtLine widget. 450

A PtList containing text items. 455

A PtMenu widget that contains various menu items. 485

A PtMenuBar that contains several menu buttons. 503

A PtMenuButton widget. 508

A PtMeter widget. 515

A one-arc PtMeter widget. 516

A PtMTrend widget. 533

A PtMultiText widget. 547

A PtNumericFloat widget. 611

A PtNumericInteger widget. 619

A PtOnOffButton widget. 627

A dialog box featuring several PtPane widgets. 637

A PtPanelGroup widget as used in PhAB. 641

Open or closed PtPolygon widgets. 668

A PtPrintSel widget. 674

Two styles of PtProgress bar. 687

Additional Pt ARG TREE FLAGS for a PtRawTree widget.734

A PtRect widget. 736

A PtScrollbar widget. 762

A PtScrollContainer widget acts as a viewport. 773

PtSeparator widgets, as used to organize the items in a menu.780

A PtSlider widget. 799

A PtSlider widget with a custom handle and trough. 800

xiv List of Figures May 31, 2004


A group of PtTab widgets positioned at the top of a PtPane.811

A PtTerminal widget. 818

A PtText widget. 877

Various button styles supported by PtToggleButton. 920

A PtToolbar as used in PhAB. 928

A PtToolbarGroup. 934

A PtTree widget, as used in the Helpviewer. 939

A PtTree without images. 941

A PtTree with images. 943

Additional Pt ARG TREE FLAGS for a PtTree widget. 961

The results of using PtTreeAddAfter(). 966

The results of using PtTreeAddFirst(). 968

The results of using PtTreeRemoveChildren(). 999

The results of using PtTreeRemoveItem(). 1001

The results of using PtTreeRemoveList(). 1003

A PtTrend widget. 1014

Replacing trend samples with PtTrendChangeData() orPtTrendChangeTrendData(). 1028

Output from a terminal device. 1030

A PtWindow widget that contains an editor application. 1181

May 31, 2004 List of Figures xv

About This Reference

May 31, 2004 About This Reference xvii

2004, QNX Software Systems Ltd. What’s new in Photon for QNX Neutrino 6.3

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

If you’re familiar with earlier versions of Photon, you should read:

� “What’s new in Photon for QNX Neutrino 6.3”

� “What’s new in Photon for QNX Neutrino 6.2.1”



� “What’s new in Photon for QNX Neutrino 6.0”

to find out how the widgets have changed in this release.

�

For information about: See:

Data structures Global Data Structures

Widget classes Widgets

Explanations of Photon terms Glossary

Since widgets inherit a lot of behavior from their parent classes, youshould make yourself familiar with the fundamental classes,especially PtWidget, PtBasic, and PtContainer.

This reference doesn’t include contributed widgets. You’ll find thedocumentation for them (if any) in their source files.

�

What’s new in Photon for QNX Neutrino 6.3

May 31, 2004 About This Reference xix

What’s new in Photon for QNX Neutrino 6.3 2004, QNX Software Systems Ltd.

New widgets� PtMTrend

ChangesPtBasic

Changed resources:

� Pt CB GOT FOCUS

� Pt CB LOST FOCUS

PtContainer

PtContainer can now be instantiated in PhAB, and has a PhABicon.

New resources:

� Pt CB CHILD GETTING FOCUS

� Pt CB CHILD LOSING FOCUS

� Pt ARG LAYOUT

� Pt ARG LAYOUT INFO

� Pt ARG LAYOUT TYPE

� Pt ARG FILL LAYOUT INFO

� Pt ARG GRID LAYOUT INFO

� Pt ARG ROW LAYOUT INFO

� Pt CB LAYOUT

PtFontSel

The PtFontSel interface widget is changed. A user can now selecttext and background color, and the style selection method is changed.The changed interface has introduced new resources, and made otherresources unnecessary.

New resources:

xx About This Reference May 31, 2004


� Pt ARG FONT LBL TEXTCOLOR

� Pt ARG FONT LBL BKGDCOLOR

� Pt ARG FONT POINT SIZE MAX

Deprecated resources:

� Pt ARG DIM

� Pt ARG FONT LBL STYLE BOLD

� Pt ARG FONT LBL STYLE BOLDITALIC

� Pt ARG FONT LBL STYLE ITALIC

� Pt ARG FONT LBL STYLE PLAIN

� Pt ARG FONT LBL QUALITY

� Pt ARG FONT LBL QUALITY PLAIN

� Pt ARG FONT LBL QUALITY ANTIALIASED

PtLabel

New resources:

� Pt ARG SECONDARY H ALIGN

� Pt ARG SECONDARY V ALIGN

� Pt ARG BALLOON TEXT

PtSeparator

New resources:

� Pt ARG SEP ARM BITMAP CURSOR

� Pt ARG SEP ARM CURSOR COLOR

� Pt ARG SEP ARM CURSOR TYPE

� Pt ARG SEP DRAG BOUNDS

May 31, 2004 About This Reference xxi


� Pt ARG SEP FLAGS

� Pt ARG SEP IMAGE

� Pt ARG SEP IMAGE H ALIGN

� Pt ARG SEP IMAGE V ALIGN

PtTerminal

PtTerminalFont() is deprecated; use PtTerminalFontInfo() instead.

The length field in PtTerminalInput t is changed fromunsigned short to unsigned, which allows PtTerminal to pastemore than 65535 bytes of data from the clipboard.

PtTree

New convenience functions and attributes structure:

� PtTreeCreateItem()

� PtTreeChangeItem()

� PtTreeItemAttributes t

PtWebClient

New resources:

� Pt CB WEB DOWNLOAD

� Pt CB WEB SSL CLIENT CERT SELECT

Changed resources:

� Pt ARG WEB ENCODING

� Pt ARG WEB COMMAND

� Pt ARG WEB OPTION

� Pt ARG WEB SERVER

� Pt CB WEB ERROR

xxii About This Reference May 31, 2004


� Pt CB WEB SSL CERTNONTRUSTED

� Pt CB WEB SSL ERROR

Flags are renamed from WWW * to Pt WEB * in these resources:

� Pt ARG WEB AUTHENTICATE

� Pt ARG WEB COMMAND

� Pt ARG WEB DATA

� Pt ARG WEB GET URL

� Pt ARG WEB HELPER

� Pt ARG WEB NAVIGATE FRAME

� Pt ARG WEB NAVIGATE LINK

� Pt ARG WEB NAVIGATE PAGE

� Pt ARG WEB PRINT

� Pt CB WEB AUTHENTICATE

� Pt CB WEB DATA REQ

� Pt CB WEB ERROR

� Pt CB WEB NEED SCROLL

� Pt CB WEB SSL CERTNONTRUSTED

� Pt CB WEB SSL ERROR

� Pt CB WEB STATUS

� Pt CB WEB UNKNOWN

May 31, 2004 About This Reference xxiii

What’s new in Photon for QNX Neutrino 6.2.1 2004, QNX Software Systems Ltd.

PtWidget

New resources:

� Pt ARG GRID LAYOUT DATA

� Pt ARG LAYOUT DATA

� Pt ARG ROW LAYOUT DATA

What’s new in Photon for QNX Neutrino 6.2.1ChangesPtGraphics

New resources:

� Pt ARG INSIDE FILL PATTERN

� Pt ARG INSIDE TRANS PATTERN

ErrataPtClock If the clock flickers too much, you can place it in a

PtOSContainer widget, but you must use atransparent fill for the clock, or else it won’t berefreshed properly.

PtPanelGroup

The Pt ARG PG CURRENT INDEX resource is1-based.

The default value for a panel group’sPt ARG RESIZE FLAGS is 0.

Corrected the example of thePt CB PG PANEL SWITCHING callback.

xxiv About This Reference May 31, 2004

2004, QNX Software Systems Ltd. What’s new in Photon for QNX Neutrino 6.2.0

What’s new in Photon for QNX Neutrino 6.2.0PtBasic

New flags for Pt ARG BASIC FLAGS:

� Pt BLANK ETCHES

� Pt OPAQUE ETCHES

PtFontSel

New flags for Pt ARG FONT FLAGS:

� Pt FONTSEL COLORSEL BKGD

� Pt FONTSEL COLORSEL TEXT

New resources:

� Pt ARG FONT TEXT COLOR

� Pt ARG FONT TEXT BKGD COLOR

PtGenList

Pt ARG LIST FLAGS includes a new flag,Pt LIST NO COLUMN LINES, that makes the list not display the linesthat separate the list’s columns.

PtMultiText

This widget now supports drag and drop; see “Drag and drop.”

PtOSContainer

When you unrealize a PtOSContainer widget, its offscreen memoryis automatically released. When you rerealize the widget, theoffscreen memory is reallocated.

May 31, 2004 About This Reference xxv

What’s new in Photon for QNX Neutrino 6.1.0 2004, QNX Software Systems Ltd.

PtSlider

New resources:

� Pt ARG SLIDER TROUGH IMAGE1,Pt ARG SLIDER TROUGH IMAGE2

PtTerminal


PtText


PtTty


What’s new in Photon for QNX Neutrino 6.1.0PtGroup

New resources:

� Pt ARG CELL HORZ ALIGN

� Pt ARG CELL VERT ALIGN

PtMenu

Pt MENU TEXT ALIGN is a new bit for Pt ARG MENU FLAGS. It’sset by default.

PtNumericFloat

This widget exports Pt ARG TEXT FLAGS andPt ARG TEXT FONT from its subordinate PtText widget.

PtNumericInteger

This widget exports Pt ARG TEXT FLAGS andPt ARG TEXT FONT from its subordinate PtText widget.

xxvi About This Reference May 31, 2004


What’s new in Photon for QNX Neutrino 6.0New widgets

� PtClient

� PtColorPanel

� PtColorPatch

� PtColorSel

� PtColorSelGroup

� PtColorWell

� PtDisjoint

� PtFlash

� PtOSContainer

� PtPanelGroup

� PtProgress

� PtRawList

� PtRawTree

� PtScrollContainer — use this instead of PtScrollArea

� PtServer

� PtToolbar

� PtToolbarGroup

� PtWebClient

Deprecated widgets

May 31, 2004 About This Reference xxvii


Instead of: Use:

AwFileSelect PtFileSel

AwMessage PtAlert(), PtNotice(), or PtPrompt() (see thePhoton Library Reference)

PtBitmap PtLabel

PtDBContainer PtOSContainer

PtHtml PtWebClient

PtIcon Define in PhAB

PtMessage PtAlert(), PtNotice(), or PtPrompt() — see thePhoton Library Reference

PtTab PtPanelGroup

PtUpDown PtScrollbar

RtMeter PtMeter

RtProgress PtProgress

RtTrend PtTrend

Other changesPtBasic

New resources:

� Pt ARG BASIC FLAGS

� Pt ARG BEVEL COLOR

� Pt ARG BEVEL CONTRAST

� Pt ARG CONTRAST

� Pt ARG DARK BEVEL COLOR

� Pt ARG DARK FILL COLOR

� Pt ARG INLINE COLOR

xxviii About This Reference May 31, 2004


� Pt ARG LIGHT BEVEL COLOR

� Pt ARG LIGHT FILL COLOR

� Pt ARG OUTLINE COLOR

� Pt ARG STYLE


� Pt ARG BOT BORDER COLOR

� Pt ARG TOP BORDER COLOR

PtBezier

Pg DRAW FILL and Pg DRAW STROKE have been deleted fromPt ARG BEZIER FLAGS. Use Pt ARG INSIDE COLOR (defined byPtGraphic) and Pt ARG COLOR (defined by PtBasic) instead.

PtBkgd

The Pt type of Pt ARG BKGD IMAGE is now Image.

PtButton

New resources:

� Pt ARG ARM IMAGE — replaces Pt ARG ARM DATA.

PtComboBox

Pt COMBOBOX ALT DOWN is a new bit for Pt ARG CBOX FLAGS.

PtContainer

New resources:

� Pt ARG TITLE

� Pt ARG TITLE FONT

� Pt CB CHILD ADDED REMOVED

May 31, 2004 About This Reference xxix


� Pt ARG CURSOR OVERRIDE — replacesPt ARG WINDOW CURSOR OVERRIDE formerly defined byPtWindow.

Resources moved to PtWidget:

� Pt ARG ANCHOR FLAGS

� Pt ARG ANCHOR OFFSETS

� Pt CB FILTER

The Pt AUTO EXTENT bit of Pt ARG CONTAINER FLAGS nowcauses the container to recalculate its preferred size when any of itschildren are realized, unrealized, moved, or resized. (This bitpreviously didn’t apply to unrealizing.)

The PtContainerCallback t structure that’s passed toPt CB RESIZE now includes the old and new dimensions of thecontainer.

PtFileSel

New resources:

� Pt ARG FS LBL NAME

� Pt ARG FS LBL SIZE

� Pt ARG FS LBL DATE

� Pt ARG FS LBL PERMISSIONS

� Pt ARG FS LBL OWNER

� Pt ARG FS LBL GROUP

Pt FS NO ROOT DISPLAY is a new bit for Pt ARG FS FLAGS.

xxx About This Reference May 31, 2004


PtFontSel

New resources:

� Pt ARG FONT LBL FONT

� Pt ARG FONT LBL QUALITY — deprecated

� Pt ARG FONT LBL QUALITY ANTIALIASED — deprecated

� Pt ARG FONT LBL QUALITY PLAIN — deprecated

� Pt ARG FONT LBL SIZE

� Pt ARG FONT LBL STYLE

� Pt ARG FONT LBL STYLE BOLD — deprecated

� Pt ARG FONT LBL STYLE BOLDITALIC — deprecated

� Pt ARG FONT LBL STYLE ITALIC — deprecated

� Pt ARG FONT LBL STYLE PLAIN — deprecated

PtGenList

Pt ARG LIST DNDSEL COLOR is a new resource.

The actions included in the callback data for Pt CB SCROLL MOVEnow include Pt SCROLL JUMP.

Pt ARG LIST SCROLL RATE is now of type unsigned char

instead of short.

Pt LIST COLUMN NO STRING is a new flag forPt ARG LIST COLUMN ATTR

PtGauge

New resources:

May 31, 2004 About This Reference xxxi


Resource Replaces

Pt ARG MAXIMUM Pt ARG GAUGE MAXIMUM

Pt ARG MINIMUM Pt ARG GAUGE MINIMUM

Pt ARG ORIENTATION Pt ARG GAUGE ORIENTATION

Pt CB GAUGE VALUE CHANGED N/A

New bits for Pt ARG GAUGE FLAGS:

� Pt GAUGE INDETERMINATE

� Pt GAUGE INTERACTIVE

� Pt GAUGE LIVE

� Pt GAUGE SHOW VALUE — replaces Pt SHOW VALUE.

� Pt GAUGE VALUE XOR — replaces Pt VALUE XOR.

Deprecated bits for Pt ARG GAUGE FLAGS:

� Pt GAUGE MAX ON RIGHT

� Pt GAUGE MAX ON BOTTOM

PtGenTree

New resources:

� Pt ARG TREE LINE COLOR

� Pt ARG TREE LINE SPACING

� Pt ARG TREE MARGIN COLOR

New bits for Pt ARG TREE FLAGS:

� Pt TREE SHOW LINES

� Pt TREE SHOW MARGIN

� Pt TREE INDENT LINES

xxxii About This Reference May 31, 2004


� Pt TREE INDENT BUTTONS

� Pt TREE SHOW CONNECTORS

Deprecated bits for Pt ARG TREE FLAGS:

� Pt TREE HAS LINES

� Pt TREE ROOT LINES

PtGraphic

New resources:

� Pt ARG INSIDE COLOR

PtGrid

The following resources are no longer relevant, and have been deleted:

� Pt ARG DASH LIST

� Pt ARG DASH SCALE

� Pt ARG LINE CAP

� Pt ARG LINE JOIN

� Pt ARG LINE WIDTH

PtLabel

New resources:

� Pt ARG LABEL IMAGE — replaces Pt ARG LABEL DATA.

� Pt ARG TEXT IMAGE SPACING

PtMenuButton

New resources:

� Pt ARG MODIFIER KEYS

New bits for Pt ARG BUTTON TYPE:

May 31, 2004 About This Reference xxxiii


� Pt MENU UP

� Pt MENU ACCL CTRL

� Pt MENU ACCL ALT

� Pt MENU ACCL SHFT

PtMultiText

The attributes member of the PtMultiTextControl t structure isnow of type PtMultiTextAttributes t const *.

PtNumeric


� Pt ARG NUMERIC TEXT BORDER

� Pt ARG NUMERIC TEXT BOT BORDER COLOR

� Pt ARG NUMERIC TEXT COLOR

� Pt ARG NUMERIC TEXT FILL COLOR

� Pt ARG NUMERIC TEXT FONT

� Pt ARG NUMERIC TEXT TOP BORDER COLOR

� Pt ARG NUMERIC UPDOWN BORDER WIDTH

PtNumericInteger

The default values of Pt ARG NUMERIC MAX andPt ARG NUMERIC MIN are INT MAX and INT MIN.

PtPolygon

Pg POLY FILL and Pg POLY STROKE have been deleted fromPt ARG POLYGON FLAGS. Use Pt ARG INSIDE COLOR (definedby PtGraphic) and Pt ARG COLOR (defined by PtBasic) instead.

xxxiv About This Reference May 31, 2004


PtPrintSel

New resources:

� Pt ARG PS LBL ALL

� Pt ARG PS LBL COLLATED

� Pt ARG PS LBL COPIES

� Pt ARG PS LBL DOUBLE SIDED

� Pt ARG PS LBL FILE

� Pt ARG PS LBL FROM

� Pt ARG PS LBL INSTALL

� Pt ARG PS LBL NAME

� Pt ARG PS LBL NOT COLLATED

� Pt ARG PS LBL PREFERENCES

� Pt ARG PS LBL PRINT ORDER

� Pt ARG PS LBL PRINT PAGES

� Pt ARG PS LBL RANGE

� Pt ARG PS LBL REVERSED

� Pt ARG PS LBL SELECTION

� Pt ARG PS LBL SEND TO FILE

� Pt ARG PS LBL SEND TO PRINTER

� Pt ARG PS LBL TO

The flags for the Pt ARG PRINT FLAGS resource have beenreplaced.

The Pt PRINTSEL ADDNEW and Pt PRINTSEL RETURN subtypes ofthe Pt CB PRINT PROPS callbacks have been deprecated; the

May 31, 2004 About This Reference xxxv


Pt PRINTSEL INSTALLER, Pt PRINTSEL PROPERTIES EXITED,Pt PRINTSEL INSTALLER EXITED, Pt PRINTSEL NOPRINTER, andPt PRINTSEL PRINTER subtypes have been added.

PtRaw

New resource:

� Pt ARG RAW CALC OPAQUE F

PtRegion

You don’t have to set bits in Pt ARG REGION FIELDS to makechanges to the region’s resources take effect. This resource nowindicates which portions of the region were changed the last time thatyou set any resources, including the flags, sensitivity, opacity, origin,and position.

PtScrollArea

This class has become a superclass for widgets that scroll. UsePtScrollContainer as a viewport that contains other widgets.PhAB automatically converts an existing PtScrollArea into aPtScrollContainer.

New resources:

� Pt CB SCROLLAREA SCROLLED — replacesPt CB SCROLLED X and Pt CB SCROLLED Y .

Pt SCROLLAREA ENABLE PAN has been added to, andPt SCROLL AREA TRACK FOCUS removed from,Pt ARG SCROLLAREA FLAGS.

PtScrollAreaCanvas() is a new convenience function.

PtScrollbar

This widget is now a subclass of PtGauge. Hence, it inherits thefollowing resources instead of defining them:

� Pt ARG MAXIMUM

xxxvi About This Reference May 31, 2004


� Pt ARG MINIMUM

� Pt ARG ORIENTATION


� Pt ARG DIRECTION

� Pt ARG SCROLL POSITION — use Pt ARG GAUGE VALUE

Deleted bits for Pt ARG SCROLLBAR FLAGS:

� Pt SCROLLBAR HORIZONTAL

� Pt SCROLLBAR INVERTED

New bits for Pt ARG SCROLLBAR FLAGS:

� Pt SCROLLBAR FIXED SLIDER SIZE

The actions included in the callback data for Pt CB SCROLL MOVEnow include Pt SCROLL JUMP.

PtSlider

The appearance of this widget has changed a lot. Labels are no longerpart of the widget; place PtLabel widgets around the slider ifrequired.

New resources:

� Pt ARG SLIDER HANDLE COLOR

� Pt ARG SLIDER THICKNESS — deprecated; usePt ARG SLIDER HANDLE WIDTH


� Pt ARG SLIDER HANDLE HEIGHT

� Pt ARG SLIDER LABEL BR

� Pt ARG SLIDER LABEL BR COL

� Pt ARG SLIDER LABEL TL

May 31, 2004 About This Reference xxxvii


� Pt ARG SLIDER LABEL TL COL

� Pt ARG SLIDER ORIENTATION

� Pt ARG SLIDER TICK MAJOR COL

� Pt ARG SLIDER TICK MINOR COL

� Pt ARG SLIDER TROUGH COL

� Pt ARG SLIDER TROUGH SIZE

Deleted bits for Pt ARG SLIDER FLAGS:

� Pt TICKS ON TOP

� Pt TICKS ON LEFT

� Pt TICKS ON BOTTOM

� Pt TICKS ON RIGHT

� Pt TICKS TOUCH TROUGH

� Pt TICKS ETCHED OUT

� Pt TICKS ETCHED IN

� Pt SLIDER POINT LEFT

� Pt SLIDER POINT UP

� Pt SLIDER POINT RIGHT

� Pt SLIDER POINT DOWN

The reason subtype for Pt CB SLIDER MOVE is now used and canbe one of the following:

� Pt SLIDER INCREMENT

� Pt SLIDER DECREMENT

� Pt SLIDER MULTIPLE INCREMENT

xxxviii About This Reference May 31, 2004


� Pt SLIDER MULTIPLE DECREMENT

� Pt SLIDER DRAGGED

� Pt SLIDER RELEASED

� Pt SLIDER TO MIN

� Pt SLIDER TO MAX

� Pt SLIDER JUMP

� Pt SLIDER SET

PtTerminal

New resource:

� Pt ARG TERM ANSI PROTOCOL — replacesPt ARG TERM PROTOCOL

The Subst member has been added to PtTerminalCharset t.

PtText

The C type for Pt ARG CURSOR POSITION is int, not short.

PtTimer

Pt ARG TIMER INITIAL and Pt ARG TIMER REPEAT are nowunsigned long instead of long.

PtToggleButton


� Pt ARG INDICATOR DEPTH

� Pt ARG INDICATOR HEIGHT

� Pt ARG INDICATOR WIDTH

� Pt ARG SET COLOR — use Pt ARG ARM COLOR instead (seePtButton).

May 31, 2004 About This Reference xxxix


� Pt ARG SET FILL — use Pt ARG ARM FILL instead (seePtButton).

� Pt ARG SPACING — use Pt ARG TEXT IMAGE SPACINGinstead (see PtLabel).

The types supported by Pt ARG INDICATOR TYPE have completelychanged:

Old New

Pt ONE OF MANY N/A

Pt N OF MANY N/A

Pt ROUND N/A

Pt RADIO Pt TOGGLE RADIO

Pt TICK N/A

Pt CHECK Pt TOGGLE CHECK

N/A Pt TOGGLE OUTLINE

PtTree

New resources:

� Pt ARG TREE COLUMN ATTR

� Pt ARG TREE COLUMN IMGFUN

� Pt CB TREE COLUMN SEL

PtTreeAddAfter() and PtTreeAddFirst() now return 0 on success, or -1if the item is already in a tree.

PtTreeFreeItems() now returns 0 on success, or -1 if the items are stillin a tree.

The expand member of the PtTreeCallback t structure passed toPt CB TREE STATE is now used whether expanding or collapsing an

xl About This Reference May 31, 2004


item. PtTreeCollapse() now returns the value of the expand member(the prototype has changed).

The PtTreeItem t structure has changed to allow for futureenhancements. This:

short set img, unset img;

has been replaced by:

union {struct { short set, unset; } img;} attr;

PtTreeModifyItemString() is a new convenience function that changesthe string for a PtTree item.

PtTty

The way the PtTty uses file descriptors has changed. Instead of twoFDs, it can now have three: one for reading, one for writing, and oneto give to a child process. Each can be set separately. This way, it’spossible to use a PtTty with a pair of pipes instead of a pseudo tty.It’s also possible to close the “slave” end of the pty after giving it to achild process.

New resources:

� Pt ARG TTY FDS

� Pt ARG TTY RFD

� Pt ARG TTY SFD

� Pt ARG TTY WFD


� Pt ARG TTY FD — set Pt ARG TTY FDS instead.

� Pt ARG TTY MFD — get Pt ARG TTY RFD orPt ARG TTY WFD instead.

May 31, 2004 About This Reference xli


PtWidget

New resources:

� Pt ARG ANCHOR FLAGS — moved from PtContainer

� Pt ARG ANCHOR OFFSETS — moved from PtContainer

� Pt ARG BEVEL WIDTH — replaces Pt ARG BORDER WIDTH

� Pt ARG MINIMUM DIM

� Pt ARG POINTER

� Pt CB DND

� Pt CB FILTER — moved from PtContainer

� Pt CB IS DESTROYED

� Pt CB OUTBOUND

The Pt CB RAW callbacks are now invoked even if the widget’s classmethods consume the event. In this case, Ph CONSUMED is set in theevent’s processing flags member.

The Pt ETCH HIGHLIGHT bit of Pt ARG FLAGS is deprecated; usethe Pt ARG BASIC FLAGS defined by PtBasic.

PtWindow


� Pt ARG ICON WINDOW

� Pt ARG WINDOW CURSOR OVERRIDE — replaced by thePt ARG CURSOR OVERRIDE resource defined byPtContainer.

The following bits have been added toPt ARG WINDOW RENDER FLAGS:

� Ph WM RENDER COLLAPSE

xlii About This Reference May 31, 2004


� Ph WM RENDER ASDIALOG

� Ph WM RENDER ASPALETTE

Instead of using Pt ARG MAX HEIGHT , Pt ARG MAX WIDTH,Pt ARG MIN HEIGHT , and Pt ARG MIN WIDTH to set thewindow’s dimensions, you can use the Pt ARG MAXIMUM DIM andPt ARG MINIMUM DIM resources that are defined by PtWidget.

May 31, 2004 About This Reference xliii

Chapter 1

Global Data Structures

May 31, 2004 Chapter 1 � Global Data Structures 1


The Photon API defines various data types and structures:

� If you’re using the Photon Application Builder (PhAB), theappropriate header files are automatically included in yourapplication.

� If you’re not using PhAB, include <Pt.h>.

This chapter describes the data structures listed below:

PtBalloonCallback t

Balloon callback structure

PtCallback t

Regular callback structure

PtCallbackInfo t

Specific callback information

PtHotkeyCallback t

Hotkey handler structure

PtRawCallback t

Event handler structure

The following datatypes are described in the Photon LibraryReference:

ApInfo t PhAB information structure

PgColor t Composite color value

PgColorHSV t Hue-Saturation-Value color value

PhArea t Position and dimensions of a rectangular area

PhClipboardHdr

Clipboard header structure



PhDim t Dimensions of an area

PhEvent t An event

PhEventRegion t

Emitter and collector of an event

PhImage t Data and characteristics of an image

PhPoint t Coordinates of a single point

PhRect t Coordinates of a rectangle

PhRegion t A region

PhRegionDataHdr t

Data that’s attached to a region

PhTile t A list of rectangles

PhWindowEvent t

A window action

PtArg t Argument structure used for getting and settingwidget resources

PtDndFetch t Structure that defines data types a widget acceptsfrom a drag-and-drop event

PtFDProc t Type for defining a file-descriptor function

PtInputCallbackProc t

Type for defining a input callback function

PtSignalProc t

Type for defining a signal-handling function

PtWorkProc t Type for defining a work procedure function

4 Chapter 1 � Global Data Structures May 31, 2004

2004, QNX Software Systems Ltd. PtBalloonCallback tBalloon callback structure

Synopsis:typedef struct Pt balloon callback {

PtWidget t *widget;void (*event f)( PtWidget t *wgt,

void *data,PtCallbackInfo t *cbinfo);

} PtBalloonCallback t;

Description:The PtBalloonCallback t structure lets you attach a ballooncallback to a widget’s container. The container invokes the specifiedfunction whenever a balloon action is warranted. This structurecontains at least:

widget A pointer to the widget the callback is being attached to.

event f A pointer to an inflate/deflate function that’s calledwhenever a balloon action is required for widget. Thearguments passed to this function are:

wgt A pointer to the widget whose balloon is beingaffected.

data NULL.

cbinfo In the cbinfo structure, the reason member isPt CB BALLOONS, and the reason subtypemember is one of the following:

� Pt INFLATE BALLOON — make the balloonvisible.

� Pt POP BALLOON — remove the balloon.

Classification:Photon


PtBalloonCallback t 2004, QNX Software Systems Ltd.

See also:PtCallbackInfo t, PtContainer


2004, QNX Software Systems Ltd. PtCallback tRegular callback structure

Synopsis:typedef struct Pt callback {

int (*event f)( PtWidget t *, void *,PtCallbackInfo t * );

void *data;} PtCallback t;

Description:The PtCallback t structure lets you specify a widget’s callbackswhen you call PtCreateWidget() or PtAddCallbacks().

This structure contains at least:

event f A pointer to the callback function.

data A pointer to data that you want to pass as the secondparameter to the callback function when it’s invoked.

Callback functions

A callback function takes the following arguments:

PtWidget t *widget

A pointer to the widget instance that invoked the callback.

void *client data

The data from the PtCallback t structure.

A PhAB callback takes as its second argument a pointer to anApInfo t structure. For more information, see the Photon LibraryReference.

�

PtCallbackInfo t *cbinfo

A pointer to a common Photon callback structure. The structureprovides information related to the widget callback beinginvoked, the Photon event, and some widget-specific callbackdata. The format of the data varies with the widget class andcallback type. For more information, see PtCallbackInfo t.


PtCallback t 2004, QNX Software Systems Ltd.

Callback functions should return Pt CONTINUE unless the descriptionof the widget’s callback resource tells you to return something else.


See also:PtBalloonCallback t, PtCallbackInfo t,PtHotkeyCallback t, PtRawCallback t

ApInfo t, PtAddCallbacks(), PtCreateWidget() in the PhotonLibrary Reference

“Callbacks” in the Managing Widgets in Application Code chapter ofthe Photon Programmer’s Guide.


2004, QNX Software Systems Ltd. PtCallbackInfo tSpecific callback information

Synopsis:typedef struct Pt callback info {

unsigned long reason;unsigned long reason subtype;PhEvent t *event;void *cbdata;} PtCallbackInfo t;

Description:The PtCallbackInfo t structure is the third argument passed to allcallback functions. You can use this structure to determine whycallbacks occurred and to get the specific callback information.

The structure contains at least the following members:

reason The reason why this callback was invoked. For example, ifyou cause the widget to invoke its Pt CB ACTIVATEcallback, reason is Pt CB ACTIVATE.

reason subtype

If there are different ways to invoke the callback, thismember indicates which one.

event A pointer to a PhEvent t structure that describes theevent that caused this callback to be invoked.

cbdata A pointer to callback-specific data.

For more information about these fields, see the descriptions ofcallbacks for each widget.



PtCallbackInfo t 2004, QNX Software Systems Ltd.

See also:PtBalloonCallback t, PtCallback t, PtHotkeyCallback t,PtRawCallback t

PhEvent t in the Photon Library Reference


2004, QNX Software Systems Ltd. PtHotkeyCallback tHotkey handler structure

Synopsis:typedef struct Pt hotkey callback {

unsigned short key sym cap;short flags;unsigned long key mods;PtWidget t *widget;void *data;int (*event f)(

PtWidget t *, void *,PtCallbackInfo t * );

} PtHotkeyCallback t;

Description:The PtHotkeyCallback t structure lets you specify hotkeys orhotkey handlers, or both, for various widgets. It contains at least thefollowing members:

key sym cap Depending on the specified flags, this membercontains either the symbol or cap of the key to beinterpreted as a hotkey. For valid key sym capvalues, see <photon/PkKeyDef.h>.

flags Determines how key sym cap is interpreted andwhether or not key mods is used. Valid bits include:

Pt HOTKEY SYM

Interpret key sym cap as a key symbol; thedefault is to interpret it as a key cap.

Pt HOTKEY IGNORE MODS

Ignore the key mods argument. This flag istypically used in menus, where you want bothupper- and lowercase letters to be accepted ashotkeys.

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


PtHotkeyCallback t 2004, QNX Software Systems Ltd.

Pt HOTKEY IGNORE MODS flag is set, thismember is ignored.

For valid key modifiers, see<photon/PkKeyDef.h>. All key-modifiermanifests begin with Pk KM .

widget If event f is NULL, the widget member’s activatecallback is invoked with a reason subtype ofPt CB HOTKEY. If the widget member is NULLwhen the hotkey is attached, it’s set to the widgetthat the hotkey is attached to.

data A pointer to any data that you want to pass as thesecond argument to the callback function.

event f A pointer to the hotkey function. If event f is NULLwhen the hotkey is activated, the widget that thehotkey is attached to has its Pt CB ACTIVATEcallback (see PtBasic) invoked with areason subtype of Pt CB HOTKEY.


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


2004, QNX Software Systems Ltd. PtRawCallback tEvent handler structure

Synopsis:typedef struct Pt raw callback {

unsigned long event mask;int (*event f)(

PtWidget t *,void *,PtCallbackInfo t * );

void *data;} PtRawCallback t;

Description:The PtRawCallback t structure lets you specify event handlers(raw and filter callbacks) for your application’s widgets. You use thisstructure when setting the Pt CB RAW or Pt CB FILTER resource ofany widget (see PtWidget) or calling PtAddEventHandler(),PtAddEventHandlers(), PtAddFilterCallback(), orPtAddFilterCallbacks().

This structure contains at least the following members:

event mask A bitmap that specifies which events trigger thefunction specified in event f . See PhEvent t in thePhoton Library Reference.

event f A pointer to the callback function.

data A pointer to data that you want to be passed as thesecond argument to the callback function.


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


PtRawCallback t 2004, QNX Software Systems Ltd.

PtAddEventHandler(), PtAddEventHandlers() PtAddFilterCallback(),PtAddFilterCallbacks() in the Photon Library Reference

“Event handlers” in the Managing Widgets in Application Codechapter of the Photon Programmer’s Guide


Chapter 2

Widgets

May 31, 2004 Chapter 2 � Widgets 15

2004, QNX Software Systems Ltd. Widget hierarchy

Widget hierarchy

PtWidget

PtBasic

PtTimer

PtContainer

PtGauge

PtGraphic

PtLabel

PtRaw

PtSeparator

PtTrend

PtButtonPtMenuLabelPtTab

PtCalendar

PtClock

PtToggleButton

PtOnOffButton

PtBezier

PtEllipsePtGrid

PtLine

PtPixel

PtPolygonPtRect

PtArc

PtScrollbar

PtSlider

PtProgress

PtMeter

PtText

PtCompound

PtGroup

PtMenuBar

PtBkgd

PtScrollArea

PtTerminal PtTty

PtFontSel

PtPrintSel

PtOSContainer

PtPanelGroup

PtDisjoint

PtClient PtWebClient

PtToolbar

PtToolbarGroup

PtMenu

PtRegion

PtWindow

PtServer

PtFlash

PtPane

PtComboBox

PtDivider

PtGenList

PtMenuButton

PtMultiTextPtNumericFloat

PtNumericIntegerPtNumeric

PtColorSelPtColorSelGroup

PtColorPanel

PtColorPatch

PtColorWell

PtTree

PtFileSelPtRawTree

PtList

PtGenTree

PtRawList

PtScrollContainer

PtMTrend

The Photon widget hierarchy.


Widget icons in PhAB 2004, QNX Software Systems Ltd.

The widget hierarchy is important because classes inherit resourcesand behavior from their ancestors. When you’re working with aparticular class, be sure to look at the descriptions of its ancestors,too.

�

Widget icons in PhABThe following table lists the Photon widget classes and the icons usedin PhAB’s widget palette:

PhAB Icon Class Description

PtArc Elliptical arc

PtBasic Superclass of basicresources for mostwidgets

PtBezier Bezier curve

PtBkgd Background of tiledimages, gradients, orbitmaps

PtButton Button for initiating anaction

PtCalendar Calendar

N/A PtClient Superclass for clientwidgets — notnormally instantiated

PtClock Analog, digital, orLED clock

continued. . .

18 Chapter 2 � Widgets May 31, 2004

2004, QNX Software Systems Ltd. Widget icons in PhAB


PtColorPanel Color panel

PtColorPatch Color patch forselecting a hue andshading or tint

N/A PtColorSel Superclass forcolor-selector widgets— not normallyinstantiated

PtColorSelGroup Group of colorselectors

PtColorWell Rectangle that displaysa color and lets youchange it

PtComboBox Text-entry field with alist of choices

N/A PtCompound Superclass forcompound widgets —not normallyinstantiated

N/A PtContainer Superclass forcontainer widgets —not normallyinstantiated

N/A PtDisjoint Superclass for disjointwidgets — notnormally instantiated

continued. . .




PtDivider Widget that divides agiven space among itschild widgets andallows resizing

PtEllipse Ellipse

PtFileSel Tree widget forselecting files anddirectories

PtFlash Container that displaysMacromedia Flash 4animation

PtFontSel Widget for selectingfont attributes

N/A PtGauge Superclass forgauge-like widgets —not normallyinstantiated

N/A PtGenList Superclass for listwidgets — notnormally instantiated

N/A PtGenTree Superclass for treewidgets — notnormally instantiated

N/A PtGraphic Superclass forgraphical widgets —not normallyinstantiated

PtGrid Grid pattern

continued. . .




N/A PtGroup Group — use PhAB’sGroup Together buttonto create this

PtLabel A text, bitmap, orimage label

PtLine Straight line (singlesegment)

PtList List of text items

N/A PtMenu Menu — use a Menumodule instead

PtMenuBar Menubar that’s placedat the top of a window

PtMenuButton Button that pops up amenu, or an item in amenu

PtMeter Meter widget

PtMTrend Medical trend widget

PtMultitext Multiple-line stylizedtext field

N/A PtNumeric Numeric fieldsuperclass — notnormally instantiated

PtNumericFloat Floating-point numericfield

PtNumericInteger Integer field

continued. . .




PtOnOffButton Button that’s either onor off

PtOSContainer Offscreen-contextcontainer, useful fordrawing flicker-freeimages and animations

PtPane Container fororganizing widgets

PtPanelGroup Container that managespanels

PtPixel Set of points

PtPolygon Set of connected linesegments

PtPrintSel Compound widget forchoosing printingoptions

PtProgress Progress bar

PtRaw Widget in which youcan use low-level Pgdrawing functions

PtRawList Raw list

PtRawTree Raw tree

PtRect Rectangle

continued. . .




N/A PtRegion Photon region — mustbe created withPtCreateWidget()

N/A PtScrollArea Superclass for scrollingwidgets — notnormally instantiated

PtScrollBar Scrollbar

PtScrollContainer Viewport for viewing alarge virtual area

PtSeparator Separator fororganizing widgets

N/A PtServer Server widget — mustbe created withPtCreateWidget()

PtSlider Numerical inputmechanism with arange

PtTab Terminal emulator

PtTerminal Terminal emulator

PtText Single-line text field

PtTimer Timer

PtToggleButton Toggle button

PtToolbar Superclass for toolbarwidgets

continued. . .


What’s in a widget description? 2004, QNX Software Systems Ltd.


PtToolbarGroup Group of toolbars

PtTree Hierarchy tree

PtTrend Display of connectedpoints that shift in aspecified direction atthe rate in which data isfed

PtTty Terminal device

PtWebClient Widget for displayingweb pages

N/A PtWidget Widget superclass —not normallyinstantiated

N/A PtWindow Window — use aPhAB window moduleinstead

What’s in a widget description?You’ll find the following sections in a typical widget-classdescription:

Class hierarchy

The classes a widget inherits its resources and behavior from.

PhAB icon

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


2004, QNX Software Systems Ltd. What’s in a widget description?

Public header

The name of the header file containing the resource manifests, datastructures, and #define directives associated with the widget class.

Description

How to use the widget. This section may include sample code as wellas an example of the widget’s appearance.

New resources

The new resources introduced by this widget class. This sectiondescribes the following for each resource:

Resource The resource manifest.

C type The C data type this resource refers to.

Pt type An indication of how you should get or set the resource.These methods are described in the ManipulatingResources in Application Code chapter of the PhotonProgrammer’s Guide.

The Pt types are:

� Alloc — an arbitrarily sized memory object.

� Array — an array. For this type of resource, the Ctype column has two values: the first is the data typethe array is expected to contain; the second is thedata type of the array counter (usually short).

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

� Complex — a resource that needs special handling.There’s usually a convenience function defined tohelp you use a complex resource.

� Flag — a value in which each bit has a differentmeaning.

� Image — a PhImage t structure; see the PhotonLibrary Reference.


What’s in a widget description? 2004, QNX Software Systems Ltd.

� Link — a linked list.

� Pointer — a pointer to arbitrary data.

� Scalar — a value that can be represented within asingle long (that is, a long, a short, or a char).

� String — a NULL-terminated UTF-8 string.

� Struct — an instance of the structure listed in the Ctype column.

Default The default value(s) of a resource.

Inherited resources

This section lists the resources that the widget class inherits from itsancestors, or in the case of a compound widget, from its exportedsubordinate children. The default values that a widget class inheritscan be overridden. The Inherited resources table contains thefollowing columns of information:

Resource The manifest of the inherited resource.

Inherited from The widget class this resource is defined in(default values are defined in the originating class).

Default override The default resources a widget class inherits canbe overridden. If a default value is overridden, thiscolumn contains the new default value. When awidget inherits resources from exportedsubordinate children, new defaults can be assignedby the widget class inheriting those resources.With the exception of resources inherited fromexported subordinate children, modifications toresources affects all subclassed widgets.

The value in the Default override column may start with |=, as in thefollowing example:

|=Pt SELECTABLE | Pt HIGHLIGHTED


2004, QNX Software Systems Ltd. What’s in a widget description?

This symbol indicates that the flags listed are added to the resourcewithout destroying any flags already set in it (i.e. the new flags andthe default value are combined in an OR operation).

A &=˜ symbol means that one or more flags are cleared. In thefollowing example, the Pt SELECTABLE flag is added to the resourceand the Pt HIGHLIGHTED flag is cleared:

|=Pt SELECTABLE &=˜Pt HIGHLIGHTED

If the widget does anything special with an inherited resource, it’sdescribed after the table.

Convenience functions

This section describes the functions you can use to control the widgetonce it has been created.


PtArc 2004, QNX Software Systems Ltd.

An elliptical arc

Class hierarchy:PtWidget → PtBasic → PtGraphic → PtArc

PhAB icon:

Public header:<photon/PtArc.h>

Description:You can use PtArc to create an elliptical arc that’s defined by:

� the origin

� an ellipse

� a start angle

� an end angle.

Instances of PtArc: arcs, circles, ellipses, wedges, and chords.

The ellipse is specified using two control points stored inPt ARG POINTS. These points are relative to the widget’s origin,Pt ARG ORIGIN (see PtGraphic). If the points aren’t set, theellipse is specified by the widget’s dimensions, Pt ARG DIM.

An arc is drawn along the ellipse in a counter-clockwise direction,starting at the start angle and finishing at the end angle. The start and


2004, QNX Software Systems Ltd. PtArc

end angles are specified by two resources: Pt ARG ARC START andPt ARG ARC END.

The arc may be scaled directly by scaling its defining points. Scalinga circular arc by unequal amounts in the x and y directions results inan elliptical arc.

The arc may also be drawn as a closed curve by specifying the arctype with the Pt ARG ARC TYPE resource:

� Pt ARC CURVE — draws the arc inscribed by the points

� Pt ARC PIE — draws the arc inscribed by the points with linesdrawn from the two end points to the centroid of the arc, creating apie-slice

� Pt ARC CHORD — draws the arc inscribed by the points with thechord connecting the two end points closing the curve.

New resources:

Resource C type Pt type Default

Pt ARG ARC END unsigned short Scalar 0

Pt ARG ARC START unsigned short Scalar 0

Pt ARG ARC TYPE unsigned short Scalar Pt ARC CURVE

Pt ARG ARC END

C type Pt type Default

unsigned short Scalar 0

The end angle, in tenths of a degree.



Pt ARG ARC START



The start angle, in tenths of a degree. If this angle is 0, the arc startson the horizon, to the right of the center. Angles increase in acounter-clockwise direction.

Pt ARG ARC TYPE


unsigned short Scalar Pt ARC CURVE

The type of arc; one of:

Pt ARC CHORD

Curve with ends connected by a straight line.

Pt ARC CURVE

Curve only.

Pt ARC PIE Curve with ends connected to the center.

Inherited resources:If the widget modifies an inherited resource, the “Default override”column indicates the new value. This modification affects anysubclasses of the widget.

Resource Inherited from Default override

Pt ARG ANCHOR FLAGS PtWidget

continued. . .




Pt ARG ANCHOR OFFSETS PtWidget

Pt ARG AREA PtWidget

Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by this class.

Pt ARG BASIC FLAGS PtBasic

Pt ARG BEVEL WIDTH PtWidget

Pt ARG BITMAP CURSOR PtWidget

Pt ARG BEVEL COLOR PtBasic

Pt ARG BEVEL CONTRAST PtBasic

Pt ARG COLOR PtBasic

Pt ARG CONTRAST PtBasic

Pt ARG CURSOR COLOR PtWidget

Pt ARG CURSOR TYPE PtWidget

Pt ARG DARK BEVEL COLOR PtBasic

Pt ARG DARK FILL COLOR PtBasic

Pt ARG DASH LIST PtGraphic

Pt ARG DASH SCALE PtGraphic

Pt ARG DATA PtWidget

Pt ARG DIM PtWidget

Pt ARG EFLAGS PtWidget

Pt ARG EXTENT PtWidget

Pt ARG FILL COLOR PtBasic Pg TRANSPARENT

Pt ARG FILL PATTERN PtBasic

Pt ARG FLAGS PtWidget

continued. . .




Pt ARG GRAPHIC FLAGS PtGraphic

Pt ARG HEIGHT PtWidget

Pt ARG HELP TOPIC PtWidget

Pt ARG HIGHLIGHT ROUNDNESS PtBasic

Pt ARG INLINE COLOR PtBasic

Pt ARG INSIDE COLOR PtGraphic

Pt ARG LIGHT BEVEL COLOR PtBasic

Pt ARG LIGHT FILL COLOR PtBasic

Pt ARG LINE CAP PtGraphic

Pt ARG LINE JOIN PtGraphic

Pt ARG LINE WIDTH PtGraphic

Pt ARG MARGIN HEIGHT PtBasic

Pt ARG MARGIN WIDTH PtBasic

Pt ARG MAXIMUM DIM PtWidget

Pt ARG MINIMUM DIM PtWidget

Pt ARG ORIGIN PtGraphic

Pt ARG OUTLINE COLOR PtBasic

Pt ARG POINTER PtWidget

Pt ARG POINTS PtGraphic

Pt ARG POS PtWidget

Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY AS REQUIRED

Pt ARG STYLE PtBasic

Pt ARG TRANS PATTERN PtBasic

continued. . .




Pt ARG USER DATA PtWidget

Pt ARG WIDTH PtWidget

Pt CB ACTIVATE PtBasic

Pt CB ARM PtBasic

Pt CB BLOCKED PtWidget

Pt CB DESTROYED PtWidget

Pt CB DISARM PtBasic

Pt CB DND PtWidget

Pt CB FILTER PtWidget

Pt CB GOT FOCUS PtBasic

Pt CB HOTKEY PtWidget

Pt CB IS DESTROYED PtWidget

Pt CB LOST FOCUS PtBasic

Pt CB MENU PtBasic

Pt CB OUTBOUND PtWidget

Pt CB RAW PtWidget

Pt CB REALIZED PtWidget

Pt CB REPEAT PtBasic

Pt CB RESCALE PtGraphic

Pt CB UNREALIZED PtWidget


PtBarGraph 2004, QNX Software Systems Ltd.

A bar graph

Class hierarchy:PtWidget → PtBasic → PtBarGraph

PhAB icon:

Public header:<photon/PtBarGraph.h>

Description:PtBarGraph draws a horizontal or vertical bar graph, with or withouta grid.

A PtBarGraph widget.

You specify the bars by setting Pt ARG BARGRAPH DATA to anarray of values. The colors of the bars depends on how you set thewidget’s resources:


2004, QNX Software Systems Ltd. PtBarGraph

� To specify the color for each bar, setPt ARG BARGRAPH COLOR to be an array of PgColor t

values.

� If you set Pt ARG BARGRAPH COLOR to NULL, the widget usesthe value of Pt ARG COLOR for all the bars.

The Pt ARG BARGRAPH FLAGS resource controls the direction ofthe graph and whether or not the grid is displayed.

If you set Pt ARG BARGRAPH DEPTH to a positive value, the barsare drawn with a bevel.

New resources:


Pt ARG BARGRAPH BASE short Scalar 0

Pt ARG BARGRAPH COLOR PgColor t, short Array NULL

Pt ARG BARGRAPH DATA short, short Array NULL

Pt ARG BARGRAPH DEPTH short Scalar 0

Pt ARG BARGRAPH FLAGS long Flag Pt BARGRAPH VERTICAL

Pt ARG BARGRAPH GRID COLOR PgColor t Color Pg DGREY

Pt ARG BARGRAPH GRID HORIZ short Scalar 6

Pt ARG BARGRAPH GRID VERT short Scalar 6

Pt ARG BARGRAPH MAX short Scalar SHRT MAX

Pt ARG BARGRAPH MIN short Scalar SHRT MIN

Pt ARG BARGRAPH BASE




short Scalar 0

The value that’s used as the base line for the bars. If the data for a baris greater than this value, the bar is displayed above the base line (fora vertical bar graph) or to the right (for a horizontal graph).

Pt ARG BARGRAPH COLOR


PgColor t, short Array NULL

An array of colors to use for the bars. If this resource is NULL, thewidget uses the value of Pt ARG COLOR (inherited from PtBasic)as the color for all the bars.

You should have at least as many bar colors as entries in thePt ARG BARGRAPH DATA array.

You can’t edit this resource in PhAB.�

Here’s an example of setting this resource:

PgColor t bar colours[7] = {Pg RED, Pg BLUE, Pg CELIDON,Pg GREEN, Pg YELLOW, Pg MAGENTA,Pg DGREEN };

PtSetResource (widget, Pt ARG BARGRAPH COLOR, bar colours, 7);

Pt ARG BARGRAPH DATA


short, short Array NULL



The data to be displayed in the bar graph. When you set this resource,the value is the array of data, and arg is the number of bars.


Here’s an example of setting this resource:

short bar values[7] = {0, 450, 399, 22, 500, 50, 555 };

PtSetResource (widget, Pt ARG BARGRAPH DATA, bar values, 7);

Pt ARG BARGRAPH DEPTH


short Scalar 0

The depth of the bars in the graph, in pixels.

Pt ARG BARGRAPH FLAGS


long Flag Pt BARGRAPH VERTICAL

Flags that affect the appearance and behavior of the bar graph; acombination of:

Pt BARGRAPH GRID

Display a grid.

Pt BARGRAPH VERTICAL

Make the bars vertical.

Pt BARGRAPH HORIZONTAL

Make the bars horizontal.



Pt ARG BARGRAPH GRID COLOR


PgColor t Color Pg DGREY

The color of the grid, if displayed.


Pt ARG BARGRAPH GRID HORIZ


short Scalar 6

The number of horizontal lines in the grid.

Pt ARG BARGRAPH GRID VERT


short Scalar 6

The number of vertical lines in the grid.

Pt ARG BARGRAPH MAX


short Scalar SHRT MAX

The maximum value in the bar graph.

Pt ARG BARGRAPH MIN




short Scalar SHRT MIN

The minimum value in the bar graph.












Pt ARG COLOR PtBasic Pg RED






continued. . .





Pt ARG DIM PtWidget



Pt ARG FILL COLOR PtBasic Pg BLACK















Pt ARG POS PtWidget

Pt ARG RESIZE FLAGS PtWidget



continued. . .







Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget





PtBasic 2004, QNX Software Systems Ltd.

A superclass of basic resources for most widgets

Class hierarchy:PtWidget → PtBasic

Immediate subclasses:

� PtCalendar

� PtClock

� PtContainer

� PtGauge

� PtGraphic

� PtLabel

� PtRaw

� PtSeparator

� PtTrend

PhAB icon:

Public header:<photon/PtBasic.h>

Description:The PtBasic superclass provides basic resources for all widgets. Itprovides the fundamental callbacks for:

� getting/losing focus

� activating

� button press, release, and repeat

Also, PtBasic supports:


2004, QNX Software Systems Ltd. PtBasic

� toggle buttons

� autohighlighting

and provides resources for:

� margins

� bevel colors

� outline and inline colors

� draw color

� fill color

� fill pattern.

Selecting widgets

PtBasic defines some callback resources for actions involving theleft pointer button. These callbacks are invoked only if the widget hasPt SELECTABLE set in its Pt ARG FLAGS (see PtWidget).

When you: The widget becomes: Callback invoked:

Press the leftpointer buttonwhile pointing atthe widget

Armed Pt CB ARM

Release the leftpointer buttonwhile pointing atan armed widget

Activated Pt CB ACTIVATE

Release the leftpointer buttonwhen the pointer isoutside an armedwidget

Disarmed Pt CB DISARM



� Not all widgets change their appearance when armed.

� The callback information for Pt CB ACTIVATE includes thenumber of clicks. The activate callbacks are invoked once for eachclick.

�

If you hold down the left pointer button, the widget’s Pt CB REPEATcallbacks are invoked.

PtBasic also defines an action involving the right pointer button:when you press the right pointer button while pointing at a widget, thewidget’s Pt CB MENU callback list is invoked.

In order for this action to occur, the widget must have must havePt MENUABLE set and Pt ALL BUTTONS cleared in itsPt ARG FLAGS resource; the widget doesn’t have to havePt SELECTABLE set. Pt CB MENU is invoked only when the pointerbutton is pressed, not when the button is released or held down.

If the widget has Pt ALL BUTTONS set in its Pt ARG FLAGSresource, the actions for all pointer buttons are those for the leftbutton.

�

Borders and colors

PtBasic defines resources that give you full control over thewidget’s colors, shadings, and borders.

A widget’s border is made up of various components, all of which areoptional; set the bits in Pt ARG BASIC FLAGS to indicate whichcomponents to display. These components, going from outside toinside, are:

� A one-pixel etch line

� A one-pixel outline, of the color specified byPt ARG OUTLINE COLOR



� A shaded bevel, the width of which is set byPt ARG BEVEL WIDTH (defined by PtWidget)

� A one-pixel inline, of the color specified byPt ARG INLINE COLOR

A widget displaying all the border components.

The color of the bevel is the same as the widget’s fill color unlessoverridden by Pt ARG BEVEL COLOR. The bevel is shadedaccording to Pt ARG BEVEL CONTRAST , which is used to calculatethe default values of Pt ARG DARK BEVEL COLOR andPt ARG LIGHT BEVEL COLOR. You can override the contrast bysetting the light and dark bevel colors explicitly. By default, the upperleft corner of the bevel is a gradient that goes from the light bevelcolor to the light fill color. The lower right bevel goes from the darkfill color to the dark bevel color.

If you set Pt STATIC BEVEL COLORS in Pt ARG BASIC FLAGS, thebevel color doesn’t change when you set Pt ARG FILL COLOR.

You can display a full (i.e. half-round) bevel by settingPt FULL BEVELS in Pt ARG BASIC FLAGS:

A widget displaying a half-round bevel.

You can use Pt ARG FILL COLOR to specify the widget’s fill color.These bits in Pt ARG BASIC FLAGS affect the fill:



Pt FLAT FILL By default, the widget’s fill is a flat color; to use agradient for the fill, clear this bit.

Pt REVERSE GRADIENT

The default gradient goes from the light fill color atthe top to the dark fill color at the bottom. Toreverse the gradient, set this bit.

Pt HORIZONTAL GRADIENT

Make the gradient change color on the horizontalaxis instead of the vertical axis.

You can specify the amount of contrast between the light and dark fillcolors by setting Pt ARG CONTRAST . If this resource doesn’t giveyou the look you want, you can override it by settingPt ARG DARK FILL COLOR and Pt ARG LIGHT FILL COLORexplicitly.

Pt ARG COLOR specifies the foreground or drawing color.

Setting Pt ARG FILL COLOR overrides any previous setting ofPt ARG DARK FILL COLOR, and Pt ARG LIGHT FILL COLOR. IfPt STATIC BEVEL COLORS isn’t set in Pt ARG BASIC FLAGS, thenew fill color also overrides Pt ARG BEVEL COLOR,Pt ARG DARK BEVEL COLOR, andPt ARG LIGHT BEVEL COLOR.

�

New resources:


Pt ARG BANDWIDTH THRESHOLD unsigned long Scalar 0

continued. . .




Pt ARG BASIC FLAGS unsigned long Flags Pt ALL ETCHES

|Pt ALL BEVELS

|Pt ALL OUTLINES

| Pt FLAT FILL

Pt ARG BEVEL COLOR PgColor t Scalar Pg LGREY

Pt ARG BEVEL CONTRAST char Scalar 75

Pt ARG COLOR PgColor t Scalar Pg BLACK

Pt ARG CONTRAST char Scalar 20

Pt ARG DARK BEVEL COLOR PgColor t Scalar Set internally

Pt ARG DARK FILL COLOR PgColor t Scalar Set internally

Pt ARG FILL COLOR PgColor t Scalar Pg GRAY

Pt ARG FILL PATTERN PgPattern t Struct Pg PAT FULL

Pt ARG HIGHLIGHT ROUNDNESS unsigned short Scalar 0

Pt ARG INLINE COLOR PgColor t Scalar Pg DGRAY

Pt ARG LIGHT BEVEL COLOR PgColor t Scalar Set internally

Pt ARG LIGHT FILL COLOR PgColor t Scalar Set internally

Pt ARG MARGIN HEIGHT unsigned short Scalar 0

Pt ARG MARGIN WIDTH unsigned short Scalar 0

Pt ARG OUTLINE COLOR PgColor t Scalar Pg WHITE

Pt ARG STYLE See below Complex

Pt ARG TRANS PATTERN PgPattern t Struct Pg PAT NONE

Pt CB ACTIVATE PtCallback t * Link NULL

Pt CB ARM PtCallback t * Link NULL

continued. . .




Pt CB DISARM PtCallback t * Link NULL

Pt CB GOT FOCUS PtCallback t * Link NULL

Pt CB LOST FOCUS PtCallback t * Link NULL

Pt CB MENU PtCallback t * Link NULL

Pt CB REPEAT PtCallback t * Link NULL

Pt ARG BANDWIDTH THRESHOLD


unsigned long Scalar 0

Defines the “graphics bandwidth” threshold that defines a slowconnection. This resource is used by only a few widgets.

Pt ARG BASIC FLAGS


unsigned long Flags Pt ALL ETCHES | Pt ALL BEVELS| Pt ALL OUTLINES |Pt FLAT FILL

This flag resource controls which “edge decorations” are rendered fora widget when it’s highlighted (see Pt ARG FLAGS, defined byPtWidget). It gives you individual control over the rendering of thetop, bottom, left, and right edges of a widget. It also gives you controlover the fill type (flat or gradient) and several behavior elements withregards to the rendering of a widget’s border.

Valid Pt ARG BASIC FLAGS bits (applied only if the widget is alsohighlighted) control:

� the appearance of the edges

� the fill



� the behavior when the widget’s state changes.

Edge-control

bits Pt TOP ETCHPt BOTTOM ETCHPt LEFT ETCHPt RIGHT ETCH

Render a single alpha line on an edge of the widget. The topand left lines are dark, and the bottom and right lines are light.This can make a widget look like it’s slightly inset.

Pt BLANK ETCHES

Don’t draw the etched lines.

Pt OPAQUE ETCHES

Use a solid line, instead of an alpha line, for the etching. Thecolor is calculated based on the widget’s color and widget’sparent color.

Pt TOP OUTLINEPt BOTTOM OUTLINEPt LEFT OUTLINEPt RIGHT OUTLINE

Render a single-pixel outline on an edge of the widget.

Pt TOP BEVELPt BOTTOM BEVELPt LEFT BEVELPt RIGHT BEVEL

Render a bevel Pt ARG BEVEL WIDTH pixels wide on anedge of the widget.

Pt FULL BEVELS

Render a full bevel (i.e. half-round) instead of a half bevel(quarter-round).



Pt TOP INLINEPt BOTTOM INLINEPt LEFT INLINEPt RIGHT INLINE

Render a single-pixel inline on an edge of the widget.

These convenience manifests make working with these bits easier:

Pt TOP LEFT ETCHPt BOTTOM RIGHT ETCHPt ALL ETCHEDPt ALL ETCHES

Adjust the etching on the top/left, bottom/right, or all edges.

Pt TOP LEFT OUTLINEPt BOTTOM RIGHT OUTLINEPt ALL OUTLINES

Adjust the outline on the top/left, bottom/right, or all edges.

Pt TOP LEFT BEVELPt BOTTOM RIGHT BEVELPt ALL BEVELS

Adjust the bevel on the top/left, bottom/right, or all edges.

Pt TOP LEFT INLINEPt BOTTOM RIGHT INLINEPt ALL INLINES

Adjust the inline on the top/left, bottom/right, or all edges.

Pt ALL TOPPt ALL BOTTOMPt ALL LEFTPt ALL RIGHTPt ALL

Adjust all edge decorations (etch, outline, bevel, and inline) onthe top, left, bottom, right, or all edges.



Fill-controlbits

Pt FLAT FILL If set, the widget is filled with a solid color as givenby Pt ARG FILL COLOR. If clear, the widget isfilled with a gradient.

Pt HORIZONTAL GRADIENT

If set, and Pt FLAT FILL is clear, the fill gradientchanges colors on the horizontal axis. If clear andPt FLAT FILL is clear, the fill gradient changescolors on the vertical axis.

Pt REVERSE GRADIENT

If set and Pt FLAT FILL is clear, the gradientrendered is reversed (i.e. begin with the dark fillcolor on the top or left when the widget isn’tpressed).

Pt STATIC BEVEL COLORS

If set, the bevel color doesn’t change when you setPt ARG FILL COLOR.

These bits affect how the widget behaves when set (depressed) orBehavior onstate

changeunset (raised):

Pt STATIC GRADIENT

If set, the gradient doesn’t reverse when the widget is set orunset.

Pt STATIC BEVELS

If set, the rendered bevels don’t change when the widget is setor unset.

Pt ARG BEVEL COLOR




PgColor t Scalar Pg LGREY

The main color of the bevel. See PgColor t in the Photon LibraryReference.

This value is automatically generated when you setPt ARG FILL COLOR. Setting Pt ARG FILL COLOR overrides anyvalues set previously via this resource.

�

Pt ARG BEVEL CONTRAST


char Scalar 75

This value determines how much the dark and light bevel colors differfrom the base bevel color (Pt ARG BEVEL COLOR). The higher thevalue, the greater the difference:

0 No change.

255 Maximum contrast.

The effect of this resource is visible only if the widget has bevelsdisplayed (see Pt ARG BASIC FLAGS).

Pt ARG COLOR


PgColor t Scalar Pg BLACK

The widget’s foreground or drawing color. See PgColor t in thePhoton Library Reference.



Pt ARG CONTRAST


char Scalar 20

This value determines how much the dark and light fill colors differfrom the base fill color (Pt ARG FILL COLOR). The higher thevalue, the greater the difference:

0 No change.

255 Maximum contrast.

The effect of this resource is visible only if the widget is filled with agradient (see Pt ARG BASIC FLAGS).

�

Pt ARG DARK BEVEL COLOR


PgColor t Scalar Set internally

This resource, with Pt ARG LIGHT BEVEL COLOR, specifies theoutermost colors used when applying a bevel to a widget. SeePt ARG BASIC FLAGS to find out when gradients and borders arerendered for a given widget.

These values are automatically generated when you setPt ARG FILL COLOR. Setting Pt ARG FILL COLOR overrides anyvalues set previously via these resources.

�

Pt ARG DARK FILL COLOR





This resource, with Pt ARG LIGHT FILL COLOR, specifies thecolors with which a gradient (if applied) starts and ends. These valuesare also used as the inner color for the bevels (i.e. the bottom bevelnormally goes through a transition fromPt ARG DARK BEVEL COLOR to Pt ARG DARK FILL COLORwhen a bevel is applied to the widget). See Pt ARG BASIC FLAGS tofind out when gradients and bevels are rendered for a given widget.


�

Pt ARG FILL COLOR


PgColor t Scalar Pg GRAY

The base fill color for the widget. See PgColor t in the PhotonLibrary Reference.

This color is used as the base color when generating thePt ARG BEVEL COLOR, Pt ARG LIGHT BEVEL COLOR,Pt ARG DARK BEVEL COLOR, Pt ARG LIGHT FILL COLOR, andPt ARG DARK FILL COLOR.

Setting this resource effectively overrides all values previously set forthe LIGHT and DARK resources. This is like setting the chroma for awidget.

�

If the widget uses a flat fill, that fill is Pt ARG FILL COLOR. If thewidget uses a gradient fill, the gradient runs fromPt ARG LIGHT FILL COLOR to Pt ARG DARK FILL COLOR. If



the widget uses a bevel, it’s rendered with color ranges as defined byPt ARG LIGHT BEVEL COLOR to Pt ARG LIGHT FILL COLORand Pt ARG DARK BEVEL COLOR toPt ARG DARK FILL COLOR.

See Pt ARG BASIC FLAGS to find out when gradients and bordersare rendered for a given widget.

�

Pt ARG FILL PATTERN


PgPattern t Struct Pg PAT FULL

The widget’s background pattern. You can’t edit this resource inPhAB.

Pt ARG HIGHLIGHT ROUNDNESS



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

If you set this resource to a nonzero value, the widget library has towork with a nonrectangular widget. It might take longer to draw thewidget, and you might notice some flickering. You can reduce theflickering by placing the widget inside a PtOSContainer.

�

Pt ARG INLINE COLOR


PgColor t Scalar Pg DGRAY



The color of the inline of the border. See PgColor t in the PhotonLibrary Reference.

The inline is drawn if any of Pt TOP INLINE, Pt BOTTOM INLINE,Pt LEFT INLINE, and Pt RIGHT INLINE are set inPt ARG BASIC FLAGS.

Pt ARG LIGHT BEVEL COLOR



This resource, with Pt ARG DARK BEVEL COLOR, specifies theoutermost colors used when applying a bevel to a widget. SeePt ARG BASIC FLAGS to find out when gradients and borders arerendered for a given widget.


�

Pt ARG LIGHT FILL COLOR



This resource, with Pt ARG DARK FILL COLOR, specifies thecolors with which a gradient (if applied) starts and ends. These valuesare also used as the inner color for the bevels (i.e. the bottom bevelnormally goes through a transition fromPt ARG DARK BEVEL COLOR to Pt ARG DARK FILL COLORwhen a bevel is applied to the widget). See Pt ARG BASIC FLAGS tofind out when gradients and borders are rendered for a given widget.




�

Pt ARG MARGIN HEIGHT



The amount of vertical space between the widget’s canvas and thewidget’s border. The canvas is the valid drawing area of the widgetand is inside all borders and margins.

Pt ARG MARGIN WIDTH



The amount of horizontal space between the widget’s canvas and thewidget’s border. The canvas is the valid drawing area of the widgetand is inside all borders and margins.

Pt ARG OUTLINE COLOR


PgColor t Scalar Pg WHITE

The color of the outline of the border. See PgColor t in the PhotonLibrary Reference.

The outline is drawn if any of Pt TOP OUTLINE,Pt BOTTOM OUTLINE, Pt LEFT OUTLINE, and Pt RIGHT OUTLINEare set in Pt ARG BASIC FLAGS.



Pt ARG STYLE


See below Complex

The style to use for this widget instance. This resource is a complexone, so it requires special handling, as described below.

A style is a collection of override methods that can change how awidget looks and behaves. Styles can also add widget resources. Formore information, see “Widget Styles” in the Managing Widgets inApplication Code chapter of the Photon Programmer’s Guide.

When setting this resource, the value is a character string that’s thename of the style. For example:

PtSetResource( widget, Pt ARG STYLE, "MyStyle", 0);

Setting this resource has the same effect as calling PtSetWidgetStyle().For more information, see the Photon Library Reference.

When you get the value of this resource, you get a pointer to aPtWidgetClassStyle t structure. For example:

PtWidgetClassStyle t *style = NULL;...PtGetResource( widget, Pt ARG STYLE, &style, 0);

Don’t access the members of the PtWidgetClassStyle t structuredirectly; call PtGetStyleMember() instead.

�

Pt ARG TRANS PATTERN


PgPattern t Struct Pg PAT NONE



The widget’s transparency pattern. You’ll find this handy for“ghosting” widgets. You can’t edit this resource in PhAB.

Pt CB ACTIVATE


PtCallback t * Link NULL

A list of PtCallback t structures that define the callbacks that thewidget calls when it becomes activated. To activate a widget, youtypically release the left pointer button while pointing at an armedwidget.

These callbacks are invoked only if the widget has Pt SELECTABLEset in its Pt ARG FLAGS.

PtText, PtMultiText, and PtComboBox have special versions ofPt CB ACTIVATE.

�

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

reason Pt CB ACTIVATE

reason subtype

Pt CB HOTKEY if the callbacks were invoked because ahotkey was pressed; otherwise 0.

event A pointer to a PhEvent t structure that describes theevent that caused the callback to be invoked, or NULL ifthere isn’t an event.

cbdata A pointer to a PtBasicCallback t structure thatcontains at least the following members:

� long int value —

if the Pt TOGGLE flag in Pt ARG FLAGS is set, valuecontains either 1 (the widget is pushed in) or 0 (the



widget is pushed out). If Pt TOGGLE isn’t set, valuecontains the click count.

These callbacks should return Pt CONTINUE.

If you multi-click on a widget, its Pt CB ACTIVATE callbacks areinvoked once for each click. The callback data includes the clickcount (1 for the first click, 2 for the second, and so on).

If you want to process only the last of a series of clicks, use aPt CB RAW callback to look for a Ph EV BUT RELEASE event with asubtype of Ph EV RELEASE ENDCLICK. For more information, seePhEvent t in the Photon Library Reference.

The Ph EV BUT RELEASE event with a subtype ofPh EV RELEASE ENDCLICK occurs approximately half a secondafter the click, which could be annoying to the user. Most Photonapplications don’t use multiple clicks because of this.

�

Pt CB ARM



A list of PtCallback t structures that define the callbacks that thewidget calls when it becomes armed. To arm a widget, you typicallypress the left pointer button while pointing at the widget.


�


reason Pt CB ARM



reason subtype

0 (not used).


cbdata NULL.


Pt CB DISARM



A list of PtCallback t structures that define the callbacks that thewidget calls when it becomes disarmed. To disarm a widget, youtypically release the left pointer button when not pointing at an armedwidget.


�


reason Pt CB DISARM

reason subtype

0 (not used).


cbdata NULL.




Pt CB GOT FOCUS



A list of PtCallback t structures that define the callbacks invokedwhen a widget gets focus or its focus status changes (e.g. a childwidget gets focus from its parent or the focus switches from a child toits parent). You can call PtIsFocused() to find the current focus stateof any widget.


reason Pt CB GOT FOCUS

reason subtype

0 (not used).

event A pointer to a PhEvent t structure that describes theevent that caused the callback to be invoked.

cbdata NULL, or a pointer to a PtFocusInfo t.PtFocusInfo t contains at least:

PtWidget t *src A pointer to the widget which is losingfocus. This pointer could be NULL.

PtWidget t *dst A pointer to the widget which isintended to get the focus. This pointercould be NULL, for example ifPtContainerNullFocus() was invoked.




Returning Pt END doesn’t make your widget refuse focus; if thewidget doesn’t want focus, it has to give focus to another widget bycalling one of the focus functions described in the Photon LibraryReference.

�

Pt CB LOST FOCUS



A list of PtCallback t structures that define the callbacks that thewidget calls when it loses focus.


reason Pt CB LOST FOCUS

reason subtype

0 (not used).



PtWidget t *src A pointer to the widget which is losingfocus. This pointer could be NULL.

PtWidget t *dst A pointer to the widget which isintended to get the focus. This pointercould be NULL, for example ifPtContainerNullFocus() was invoked.

These callbacks should return:



� Pt CONTINUE to relinquish focus

Or:

� Pt END to keep it (for example, if the user has to type something ina text widget).

Pt CB MENU



A list of PtCallback t structures that define the callbacks that thewidget calls when you press the right button while the pointer is ontop of the widget.

The widget must have Pt MENUABLE set and Pt ALL BUTTONScleared in its Pt ARG FLAGS resource. The widget doesn’t need tohave Pt SELECTABLE set in its Pt ARG FLAGS for these callbacks tobe invoked.

Pt CB MENU is invoked only when the pointer button is pressed, notwhen the button is released or held down.

�


reason Pt CB MENU

reason subtype

0 (not used).


cbdata NULL.




Pt CB REPEAT



A list of PtCallback t structures that define the callbacks that thewidget calls when it receives Ph EV BUT REPEAT events. Theseevents occur when you hold down the left pointer button (or the rightpointer button if the widget has Pt ALL BUTTONS set in itsPt ARG FLAGS resource).


�


reason Pt CB REPEAT

reason subtype

0 (not used).


cbdata NULL.









Pt ARG BEVEL WIDTH PtWidget 0





Pt ARG DIM PtWidget









Pt ARG POS PtWidget






continued. . .




Pt CB DND PtWidget





Pt CB RAW PtWidget




PtBezier 2004, QNX Software Systems Ltd.

A Bezier curve

Class hierarchy:PtWidget → PtBasic → PtGraphic → PtBezier

PhAB icon:

Public header:<photon/PtBezier.h>

Description:The PtBezier class draws a Bezier curve via PgDrawBezier().

A Bezier curve created by PtBezier.

The Pt ARG POINTS resource specifies the points in the Beziercurve. These points are relative to the widget’s Pt ARG ORIGIN. Formore information, see PtGraphic.

New resources:


2004, QNX Software Systems Ltd. PtBezier


Pt ARG BEZIER FLAGS unsigned short Scalar 0

Pt ARG BEZIER FLAGS



Flags that affect the appearance of the curve; any combination of:

Pg CLOSED Connect the last point to the first.

Pg RELATIVE Use relative coordinates to draw the curve. Eachpoint is relative to the previous point.










continued. . .















Pt ARG DIM PtWidget












continued. . .


2004, QNX Software Systems Ltd. PtBezier















Pt ARG POS PtWidget







Pt CB ARM PtBasic



continued. . .





Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






2004, QNX Software Systems Ltd. PtBkgdA color-gradient and image background

Class hierarchy:PtWidget → PtBasic → PtContainer → PtBkgd

PhAB icon:

Public header:<photon/PtBkgd.h>

Description:The PtBkgd widget provides a background of a color gradient withan optional image on top of it. The image can be tiled across thegradient.

Several different styles of background widgets.

A PtBkgd widget is filled with a color gradient that’s based on the


PtBkgd 2004, QNX Software Systems Ltd.

widget’s Pt ARG FILL COLOR and Pt ARG CONTRAST (definedby PtBasic). For example, the background could start from darkblue at the top and gradually fade to light blue at the bottom.

On top of this gradient, you can display an image, defined by thePt ARG BKGD IMAGE resource. If the image is smaller than thePtBkgd widget, you can tile the image in various ways by settingPt ARG BKGD SPACING X, Pt ARG BKGD SPACING Y , andPt ARG BKGD TILE.

New resources:


Pt ARG BKGD IMAGE PhImage t * Image NULL

Pt ARG BKGD SPACING X short Scalar 0

Pt ARG BKGD SPACING Y short Scalar 0

Pt ARG BKGD TILE uint8 t Scalar Pt BKGD GRID

Pt ARG BKGD IMAGE


PhImage t * Image NULL

A pointer to a PhImage t structure that defines the image to bedisplayed. If it’s NULL, no image is displayed. For more information,see PhImage t and PxLoadImage() in the Photon Library Reference.

Set the flags member of the PhImage t structure to:

Ph RELEASE IMAGE | Ph RELEASE PALETTE |Ph RELEASE TRANSPARENCY MASK | Ph RELEASE GHOST BITMAP


2004, QNX Software Systems Ltd. PtBkgd

before providing the image to the widget. If you do this, the memoryused for the image is released when the widget is unrealized ordestroyed.

When you set this resource, the widget copies the PhImage t

structure but not the data pointed to by the members of the structure.After setting this resource, you can free() the PhImage t if you don’tneed it, but don’t free() the members of it.

�

Pt ARG BKGD SPACING X


short Scalar 0

The horizontal spacing between tiles, in pixels.

Pt ARG BKGD SPACING Y


short Scalar 0

The vertical spacing between tiles, in pixels.

Pt ARG BKGD TILE


uint8 t Scalar Pt BKGD GRID

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

Pt BKGD CENTER

Draw the image once and center it within the container.



Pt BKGD CENTER GRID

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

Pt BKGD GRID

Repeat the image in grid fashion.

Pt BKGD NONE

Don’t tile the image; just display it once in the upper left corner.



Pt ARG ANCHOR FLAGS PtWidget Pt LEFT ANCHORED LEFT|Pt RIGHT ANCHORED LEFT|Pt TOP ANCHORED TOP|Pt BOTTOM ANCHORED TOP









continued. . .





Pt ARG CONTAINER FLAGS PtContainer



Pt ARG CURSOR OVERRIDE PtContainer





Pt ARG DIM PtWidget



Pt ARG FILL COLOR PtBasic











continued. . .








Pt ARG POS PtWidget



Pt ARG TITLE PtContainer

Pt ARG TITLE FONT PtContainer





Pt CB ARM PtBasic

Pt CB BALLOONS PtContainer


Pt CB CHILD ADDED REMOVED PtContainer



Pt CB DND PtWidget




continued. . .






Pt CB MENU PtBasic


Pt CB RAW PtWidget



Pt CB RESIZE PtContainer



PtButton 2004, QNX Software Systems Ltd.

A button for initiating an action

Class hierarchy:PtWidget → PtBasic → PtLabel → PtButton


� PtOnOffButton

� PtToggleButton

PhAB icon:

Public header:<photon/PtButton.h>

Description:The PtButton class draws a button. Buttons let you initiate an actionwithin your application; clicking a button invokes an applicationcallback.

A PtButton widget.

Creating pushbuttons

A pushbutton is like a button you might find on a calculator or acontrol panel. The label is displayed within the button. The widgetitself is shaded to appear like a raised button. When you click on thebutton, it becomes “pressed in.”

The label inside the button is usually a text string and/or iconrepresenting the action that’s performed when the button is pressed.You specify a label for the button in the same way as for PtLabelwidgets.


2004, QNX Software Systems Ltd. PtButton

Pushbutton behavior

A pushbutton is usually associated with a command to be performed— when you click on the pushbutton, the command is executed. Formore information, see PtBasic.

Visual feedback

A visual cue is displayed when a pushbutton is armed. Usually thepushbutton appears to be pressed in. The original appearance isrestored once the pushbutton has been disarmed or activated.

You can also configure a pushbutton so that the background of thewidget is filled with a different color to provide more noticeablefeedback when the button is armed. Use the Pt ARG ARM COLORresource to set the fill color for armed pushbuttons. This resource isignored if the Pt ARG ARM FILL resource hasn’t been set toPt TRUE.

When the pushbutton is displaying an image, you may want the imageto change when the pushbutton is armed. This is useful if you want tochange the color of the icon displayed or change the actual image,such as changing a mail box icon from one with the flag up to onewith the flag down. If you wish to change only the color, you can usePt ARG ARM COLOR if the image is a bitmap with backfill turnedon. The arm color is used in place of the widget’s fill color.

To display a different image entirely when the button is armed, usethe Pt ARG ARM IMAGE resource. When the Pt ARG LABEL TYPEresource (see PtLabel) is set to an image type, this resource isconsulted to see if an alternate image is available for displaying whenthe pushbutton is armed. If the data points to an image, that image isdisplayed when the button is armed.

New resources:




Pt ARG ARM COLOR PgColor t Scalar PgGray(170)

Pt ARG ARM FILL unsigned char Scalar Pt FALSE

Pt ARG ARM IMAGE PhImage t * Image NULL

Pt ARG ARM COLOR


PgColor t Scalar PgGray(170)

The background color used when the button is armed (pressed in).See PgColor t in the Photon Library Reference.

This resource is used only if Pt ARG ARM FILL is set to Pt TRUE.

Pt ARG ARM FILL


unsigned char Scalar Pt FALSE

Determines whether or not to use Pt ARG ARM COLOR as thebackground color used when the button is armed (pressed in).Possible values:

Pt TRUE Use the value of Pt ARG ARM COLOR.

Pt FALSE Ignore the value of Pt ARG ARM COLOR.

Pt ARG ARM IMAGE





A pointer to a PhImage t structure (see the Photon LibraryReference) that defines the image to use when the button is armed. It’sused only if the label type (Pt ARG LABEL TYPE — see PtLabel)is Pt IMAGE or Pt TEXT IMAGE.



before providing the image to the widget. If you do this, the memoryused for the image is released when the widget is unrealized ordestroyed.



�



Pt ARG ACCEL KEY PtLabel




Pt ARG BALLOON COLOR PtLabel

Pt ARG BALLOON FILL COLOR PtLabel

continued. . .




Pt ARG BALLOON POSITION PtLabel

Pt ARG BALLOON TEXT PtLabel


Pt ARG BASIC FLAGS PtBasic Pt ALL ETCHES |Pt ALL BEVELS |Pt ALL OUTLINES |Pt STATIC GRADIENT












Pt ARG DIM PtWidget



Pt ARG FILL COLOR PtBasic Pg LGREY


Pt ARG FLAGS PtWidget |=Pt SELECTABLE|Pt HIGHLIGHTED

continued. . .







Pt ARG HORIZONTAL ALIGNMENT PtLabel Pt CENTER


Pt ARG LABEL BALLOON PtLabel

Pt ARG LABEL FLAGS PtLabel

Pt ARG LABEL IMAGE PtLabel

Pt ARG LABEL TYPE PtLabel



Pt ARG LINE SPACING PtLabel

Pt ARG MARGIN BOTTOM PtLabel


Pt ARG MARGIN LEFT PtLabel

Pt ARG MARGIN RIGHT PtLabel

Pt ARG MARGIN TOP PtLabel






Pt ARG POS PtWidget

continued. . .





Pt ARG SECONDARY H ALIGN PtLabel

Pt ARG SECONDARY V ALIGN PtLabel


Pt ARG TEXT FONT PtLabel

Pt ARG TEXT IMAGE SPACING PtLabel

Pt ARG TEXT STRING PtLabel


Pt ARG UNDERLINE TYPE PtLabel

Pt ARG UNDERLINE1 PtLabel



Pt ARG VERTICAL ALIGNMENT PtLabel Pt CENTER



Pt CB ARM PtBasic




Pt CB DND PtWidget




continued. . .






Pt CB MENU PtBasic


Pt CB RAW PtWidget





PtCalendar 2004, QNX Software Systems Ltd.

A calendar

Class hierarchy:PtWidget → PtBasic → PtCalendar

PhAB icon:

Public header:<photon/PtCalendar.h>

Description:PtCalendar draws a calendar showing the day of the week, monthand year. You can interactively change the date and browse othermonths and years. The calendar is drawn on a per-month basis andcan be drawn with or without a grid.

A PtCalendar widget.


2004, QNX Software Systems Ltd. PtCalendar

New resources:


Pt ARG CALENDAR COLOR1 PgColor t Scalar Pg BLACK

Pt ARG CALENDAR COLOR2 PgColor t Scalar Pg DGREY



Pt ARG CALENDAR COLOR5 PgColor t Scalar Pg BLUE

Pt ARG CALENDAR DATE PtCalendarDate t Struct Current date

Pt ARG CALENDAR FLAGS ulong t Flag See below.

Pt ARG CALENDAR FONT1 char * String "TextFont09"

Pt ARG CALENDAR FONT2 char * String "TextFont09i"

Pt ARG CALENDAR FONT3 char * String "TextFont09"

Pt ARG CALENDAR FONT4 char * String "TextFont09b"

Pt ARG CALENDAR FONT5 char * String "TextFont09b"

Pt ARG CALENDAR HIGHLIGHT ulong t Flags 0

Pt ARG CALENDAR MONTH BTN COLOR PgColor t Scalar Pg GREY

Pt ARG CALENDAR MONTH NAMES char **, short Array See below.

Pt ARG CALENDAR SEL COLOR PgColor t Scalar Pg YELLOW

Pt ARG CALENDAR TIME T time t Scalar Current date

Pt ARG CALENDAR WDAY NAMES char **, short Array See below.

Pt ARG CALENDAR YEAR BTN COLOR PgColor t Scalar Pg GREY

Pt CB CALENDAR SELECT PtCallback t * Link NULL



Pt ARG CALENDAR COLOR1



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

in the Photon Library Reference.



PgColor t Scalar Pg DGREY

The color used to display the next and previous month’s days. SeePgColor t in the Photon Library Reference.




The color used for the year and month name. See PgColor t in thePhoton Library Reference.




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





PgColor t Scalar Pg BLUE

The color used for the names of the days of the week (seePt ARG CALENDAR WDAY NAMES). See PgColor t in thePhoton Library Reference.

Pt ARG CALENDAR DATE


PtCalendarDate t Struct Current date

The current date shown on the calendar.

You might find it easier to use Pt ARG CALENDAR TIME T insteadof Pt ARG CALENDAR DATE. They both specify the date, butPt ARG CALENDAR DATE uses a custom data structure.

You can’t set either of these resources in PhAB.

�

This date is stored in a PtCalendarDate t structure that contains:

� year — the current year starting from 0000.

� month — the current month [0-11]; 0 is January.

� day — the current day of the month [0-30].

Pt ARG CALENDAR FLAGS




ulong t Flag Pt CALENDAR YEAR BTNS |Pt CALENDAR MONTH BTNS |Pt CALENDAR SHOW PREV |Pt CALENDAR SHOW NEXT |Pt CALENDAR SHOW GRID

Calendar-specific flags. This can be a combination of:

Pt CALENDAR YEAR BTNS

Show the next/previous year buttons.

Pt CALENDAR MONTH BTNS

Show the next/previous month buttons.

Pt CALENDAR SHOW PREV

Show the last few days of the previous month.

Pt CALENDAR SHOW NEXT

Show the first few days of the following month.

Pt CALENDAR SHOW GRID

Show the calendar in a grid format with lines separating thedays.

Pt ARG CALENDAR FONT1


char * String "TextFont09"

The font used for the current month’s days.





char * String "TextFont09i"

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




The font used for the year and month name.



char * String "TextFont09b"

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




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

Pt ARG CALENDAR HIGHLIGHT


ulong t Flags 0



A set of up to 32 bits that specify the days of the current month tohighlight. For example, 0x1 means that day 1 is highlighted and 0x3

means that days 1 and 2 are highlighted.

The highlighted days are displayed using the values ofPt ARG CALENDAR COLOR4 and Pt ARG CALENDAR FONT4.

You can’t edit Pt ARG CALENDAR HIGHLIGHT in PhAB.�

Pt ARG CALENDAR MONTH BTN COLOR


PgColor t Scalar Pg GREY

The color used for the buttons for moving to the next and previousmonths. See PgColor t in the Photon Library Reference.

Pt ARG CALENDAR MONTH NAMES


char **, short Array See below

An array of names to be used for the months of the year. By defaultthese values are:

Element Value

0 January

1 February

2 March

3 April

4 May

continued. . .



Element Value

5 June

6 July

7 August

8 September

9 October

10 November

11 December

The array should contain 12 elements. If you set more, the extras arediscarded. If you set fewer, the above elements are used for themissing ones.

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

Pt ARG CALENDAR SEL COLOR


PgColor t Scalar Pg YELLOW

The color of the currently selected day of the month. See PgColor t


Pt ARG CALENDAR TIME T


time t Scalar Current date

The current date shown on the calendar. This date is stored in atime t structure.



You can’t edit Pt ARG CALENDAR TIME T in PhAB.�

Pt ARG CALENDAR WDAY NAMES


char **, short Array See below.

An array of names to be used for the days of the week. By defaultthese values are:

Element Value

0 Su

1 Mo

2 Tu

3 We

4 Th

5 Fr

6 Sa

The array should contain 7 elements. If you set more, the extras arediscarded. If you set fewer, the above elements are used for themissing ones.

You can’t edit Pt ARG CALENDAR WDAY NAMES in PhAB.�

Pt ARG CALENDAR YEAR BTN COLOR




PgColor t Scalar Pg GREY

The color used for the buttons for moving to next and previous years.See PgColor t in the Photon Library Reference.

Pt CB CALENDAR SELECT



A list of PtCallback t structures that define the callbacks invokedwhen a date is selected. Each callback is passed aPtCallbackInfo t structure that contains at least the followingmembers:

reason Pt CB CALENDAR SELECT

reason subtype

0 (not used).


cbdata A pointer to a PtCalendarSelectCallback t

structure.

The PtCalendarSelectCallback t structure contains at least:

int type The type of selection made:

� Pt CALENDAR DATE SELECTED

� Pt CALENDAR WDAY SELECTED

� Pt CALENDAR MONTH SELECTED

� Pt CALENDAR YEAR SELECTED



PtCalendarDate t date

The selected date. This structure contains at least:

� signed char day — values in the range 0through 30.

� signed char month — values in the range 0through 11.

� signed short year — values in the range-32767 through +32767.

time t time The selected date, represented as a time t.













continued. . .











Pt ARG DIM PtWidget












Pt ARG MARGIN HEIGHT PtBasic 2

Pt ARG MARGIN WIDTH PtBasic 2



continued. . .






Pt ARG POS PtWidget







Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget


continued. . .


PtClient 2004, QNX Software Systems Ltd.

Client widget

Class hierarchy:PtWidget → PtBasic → PtContainer → PtClient


� PtWebClient

PhAB icon:None — not normally instantiated.

Public header:<photon/PtClient.h>

Description:PtClient and PtServer let one process (the “server”) displaywidgets in a window that belongs to another process (the “client”).

PtClient and PtServer use a Photon connection to communicate(see “Connections” in the Interprocess Communications chapter ofthe Photon Programmer’s Guide), but they have a few resources thatin most cases let applications avoid dealing with connection objectsdirectly.

A PtClient widget creates a parent region for a PtServer widgetand handles the process of connecting to a PtServer. Then, theclient controls the server’s size and notifies it of certain events inorder to make the server look and feel as if it were just anothercontainer in the client’s window. Additionally, PtClient lets yourapplication send arbitrary messages to the server process.

New resources:


2004, QNX Software Systems Ltd. PtClient


Pt ARG CLIENT FLAGS unsigned Flags 0

Pt ARG CLIENT NAME char * String NULL

Pt ARG CLIENT REPLY LEN unsigned Scalar 0

Pt ARG CLIENT SEND char[], unsigned Array NULL,0

Pt ARG CLIENT SERVER PtConnectionClient t * Pointer NULL

Pt CB CLIENT CONNECTED PtCallback t * Link NULL

Pt CB CLIENT ERROR PtCallback t * Link NULL

Pt CB CLIENT EVENT PtCallback t * Link NULL

Pt CB CLIENT NOT FOUND PtCallback t * Link NULL

Pt ARG CLIENT FLAGS


unsigned Flags 0

Flags that control the behavior of the widget:

Pt CLIENT NOEVENTS

Setting this flag tells the widget that the server doesn’t use thePt ARG SERVER SEND resource.

Pt CLIENT NONBLOCK

If this flag is clear, the call to PtSetResources() that setsPt ARG CLIENT NAME doesn’t return until the connecting haseither succeeded or been aborted.

If the flag is set, setting the Pt ARG CLIENT NAME isnonblocking, and the connecting is performed in background,after PtSetResources() has returned.



Pt ARG CLIENT NAME


char * String NULL

The connector name to which to connect. Setting this resourceinitiates the process of connecting to a server.

If the connection isn’t successful, the widget’sPt CB CLIENT NOT FOUND callbacks are invoked.

Pt ARG CLIENT REPLY LEN


unsigned Scalar 0

The maximum length of a reply from the server, in bytes. SeePt ARG CLIENT SEND.

Pt ARG CLIENT SEND


char[], unsigned Array NULL, 0

When you set this resource, the widget sends a message to itsPtServer. The message invokes a Pt CB SERVER RECEIVEcallback in the server that lets the server specify a reply. The reply isthen available in the client by getting the Pt ARG CLIENT SENDresource (the length gives you the actual length of the reply, not thesize of the buffer).

Pt ARG CLIENT SERVER (read only)

continued. . .





PtConnectionClient t * Pointer NULL

A pointer to the connection object used for communicating to thePtServer. Don’t use this pointer for anything other than checking tosee if it’s NULL.

Pt CB CLIENT CONNECTED



A list of PtCallback t structures that define the callbacks that areinvoked when the client connects to the server. Each callback ispassed a PtCallbackInfo t structure that contains at least thefollowing members:

reason Pt CB CLIENT CONNECTED

reason subtype

0 (not used).

event NULL.

cbdata NULL.


Pt CB CLIENT ERROR





A list of PtCallback t structures that define the callbacks that areinvoked when an error occurs.


reason Pt CB CLIENT ERROR

reason subtype

0 (not used).


cbdata A pointer to a PtClientErrorCallback t structurethat contains at least:

� int action — the value that the connection client’serror handler will return. It’s initialized to Pt END. Setit to Pt CONTINUE to retry the failed operation.

Not all operations are retried if an error handler returnsPt CONTINUE. For example, a MsgReply() is never retried.

�

� int errnum — the errno value from the error handler.

� int where — the value (of type enumPtConnectionClientError) that describes whatoperation failed.

If this value is Pt CONNECTION CLIENT BROKEN, the widgetdisconnected from the server and its Pt ARG CLIENT NAMEresource has been reset to NULL.

�




Pt CB CLIENT EVENT



A list of PtCallback t structures that define the callbacks that areinvoked for each message sent by the server’sPt ARG SERVER SEND resource.


reason Pt CB CLIENT EVENT

reason subtype

0 (not used).


cbdata A pointer to a PtClientCallback t structure thatcontains at least:

� void const *message — a pointer to the message.

� unsigned nbytes — its length.


Pt CB CLIENT NOT FOUND



A list of PtCallback t structures that define the callbacks that areinvoked if the widget fails to find the server specified when you setPt ARG CLIENT NAME.




reason Pt CB CLIENT NOT FOUND

reason subtype

0 (not used).

event NULL.

cbdata A pointer to an int initialized to Pt END. Set it toPt CONTINUE if you want the widget to retry after a littlewhile. Typically, the first Pt CB CLIENT NOT FOUNDcallback spawns the server, and any subsequentPt CB CLIENT NOT FOUND callback checks whether ornot the server is still running, and abort the connecting ifthe server has terminated.









continued. . .

















Pt ARG DIM PtWidget










continued. . .












Pt ARG POS PtWidget









Pt CB ARM PtBasic






continued. . .




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






PtClock 2004, QNX Software Systems Ltd.

An analog, digital, or LED clock

Class hierarchy:PtWidget → PtBasic → PtClock

PhAB icon:

Public header:<photon/PtClock.h>

Description:A PtClock draws a clock and can optionally update its displayperiodically (about once a second) to reflect the current time.

Analog, digital, and LED clocks created by PtClock.

PtClock follows the system time, but don’t rely on it to be accurateall the time.

The widget may flicker excessively, particularly if you use atransparent fill color. To reduce flicker, use a nontransparent fill coloror disable the display of seconds.

Alternatively, you can place the clock in a PtOSContainer, but youmust use a transparent fill for the clock, or it won’t be refreshedproperly.

�


2004, QNX Software Systems Ltd. PtClock

New resources:


Pt ARG CLOCK FACE COLOR PgColor t Scalar Pg WHITE

Pt ARG CLOCK FACE OUTLINE COLOR PgColor t Scalar Pg BLACK

Pt ARG CLOCK FLAGS long Flag See below.

Pt ARG CLOCK FONT char * String "TextFont09"

Pt ARG CLOCK HOUR short Scalar Pt CLOCK CURRENT

Pt ARG CLOCK HOUR COLOR PgColor t Scalar Pg BLACK

Pt ARG CLOCK HOUR OFFSET short Scalar 0

Pt ARG CLOCK MINUTE short Scalar Pt CLOCK CURRENT

Pt ARG CLOCK MINUTE COLOR PgColor t Scalar Pg BLACK

Pt ARG CLOCK MINUTE OFFSET short Scalar 0

Pt ARG CLOCK SECOND short Scalar Pt CLOCK CURRENT

Pt ARG CLOCK SECOND COLOR PgColor t Scalar Pg RED

Pt ARG CLOCK SECOND OFFSET short Scalar 0

Pt ARG CLOCK SEP1 char * String ":"

Pt ARG CLOCK SEP1 COLOR PgColor t Scalar Pg BLACK

Pt ARG CLOCK SEP2 char * String ":"

Pt ARG CLOCK SEP2 COLOR PgColor t Scalar Pg BLACK

Pt ARG CLOCK TYPE short Scalar Pt CLOCK ANALOG

Pt CB CLOCK TIME CHANGED PtCallback t * Link NULL



Pt ARG CLOCK FACE COLOR



The fill color of the clock’s face (applicable only for analog clocks).See PgColor t in the Photon Library Reference.

Pt ARG CLOCK FACE OUTLINE COLOR



The color of the line drawn around the clock face (applicable only foranalog clocks). See PgColor t in the Photon Library Reference.

Pt ARG CLOCK FLAGS


long Flag Pt CLOCK TRACK TIME |Pt CLOCK SHOW SECONDS |Pt CLOCK SHOW NUMBERS

Defines the clock’s behavior. Possible values are:

Pt CLOCK 24 HOUR

Use a 24-hour display rather than conventional 12-hour format.This flag overrides Pt CLOCK SHOW AMPM.

Pt CLOCK PAD HOURS

Pad the hour field with a leading zero such that there are always2 digits in the hours field (applicable only for digital or LEDclocks).

Pt CLOCK SHOW AMPM

Display an AM/PM indicator. For digital clocks, this isrendered as an AM or PM suffix. For LED clocks, this is rendered



as a dot in the upper right corner (AM) or lower right corner(PM) of the display. This flag has no effect on analog clocks,and is overridden by the Pt CLOCK 24 HOUR flag.

Pt CLOCK SHOW NUMBERS

Display numbers on the face (applicable only for analogclocks).

Pt CLOCK SHOW SECONDS

Display the seconds component of the time.

Pt CLOCK TRACK TIME

Update the clock every second to reflect the current time. If thisflag isn’t set, the clock holds its current setting until it’schanged programmatically or the flag is reenabled.

Pt ARG CLOCK FONT



The font to use. For analog clocks, this applies to the numbers on theface (if displayed). For digital clocks, this applies to the entire display.

Pt ARG CLOCK HOUR


short Scalar Pt CLOCK CURRENT

The current hour setting for the clock (reflecting the current systemclock setting if Pt CLOCK TRACK TIME is set). This value is in24-hour format.

If you set this resource to Pt CLOCK CURRENT, the clock is set to thecurrent system time.



Pt ARG CLOCK HOUR COLOR



The color to use when drawing the hours component. SeePgColor t in the Photon Library Reference.

Pt ARG CLOCK HOUR OFFSET


short Scalar 0

Offset the clock setting by this amount when displaying the hoursfield.

Pt ARG CLOCK MINUTE



The current minute setting for the clock (reflecting the current systemclock setting if Pt CLOCK TRACK TIME is set). If you set thisresource to Pt CLOCK CURRENT, the clock is set to the currentsystem time.

Pt ARG CLOCK MINUTE COLOR



The color to use when drawing the minutes component. SeePgColor t in the Photon Library Reference.



Pt ARG CLOCK MINUTE OFFSET


short Scalar 0

Offset the clock setting by this amount when displaying the minutesfield.

Pt ARG CLOCK SECOND



The current second setting for the clock (reflecting the current systemclock setting if Pt CLOCK TRACK TIME is set). If you set thisresource to Pt CLOCK CURRENT, the clock is set to the currentsystem time.

Pt ARG CLOCK SECOND COLOR


PgColor t Scalar Pg RED

The color to use when drawing the seconds component. SeePgColor t in the Photon Library Reference.

Pt ARG CLOCK SECOND OFFSET


short Scalar 0

Offset the clock setting by this amount when displaying the secondsfield.



Pt ARG CLOCK SEP1


char * String ":"

The separator to use between the hours and minutes field (applicableonly for digital clocks; LED clocks always use a colon). Only the firstcharacter of the string is used.

Pt ARG CLOCK SEP1 COLOR



The color to use when drawing the separator character between hoursand minutes. See PgColor t in the Photon Library Reference.

Pt ARG CLOCK SEP2


char * String ":"

The separator to use between the minutes and seconds field(applicable only for digital clocks with Pt CLOCK SHOW SECONDSset; LED clocks always use a colon). Only the first character of thestring is used.

Pt ARG CLOCK SEP2 COLOR



The color to use when drawing the separator character betweenminutes and seconds. See PgColor t in the Photon LibraryReference.



Pt ARG CLOCK TYPE


short Scalar Pt CLOCK ANALOG

The clock type:

Pt CLOCK DIGITAL

A numeric display (using system fonts).

Pt CLOCK LED

A scalable display that resembles conventional LED/LCDdigital clocks.

Pt CLOCK ANALOG

An analog clock with hands.

Pt CB CLOCK TIME CHANGED



A list of PtCallback t structures that define the callbacks invokedwhen the time on the clock changes. This occurs once a second ifPt CLOCK SHOW SECONDS is set, otherwise once every minutewhen the minute changes.

If the widget has the Pt CALLBACKS ACTIVE bit set in itsPt ARG FLAGS resource, these callbacks are also invoked when yourapplication changes the time by calling PtSetResource() orPtSetResources().


reason Pt CB CLOCK TIME CHANGED



reason subtype

Why this callback was invoked. This value is a flag thatmay contain any of the following (ORed together):

� Pt CLOCK HOUR CHANGED

� Pt CLOCK MINUTE CHANGED

� Pt CLOCK SECOND CHANGED

event A pointer to a PhEvent t structure that describes theevent that caused the callback to be invoked. If event isNULL, the callback was invoked because your applicationchanged the time setting by calling PtSetResources().

cbdata A pointer to a PtClockTimeCallback t structure thatcontains at least:

� short hour — The new hour displayed on the clock(in 24-hour format). Note that this includes the houroffset, if any.

� short minute — The new minute displayed on theclock.

� short second — The new second displayed on theclock.

� short old hour — The previous hour displayed onthe clock before the change was made (in 24-hourformat). Note that this includes the hour offset, if any.

� short old minute — The previous minute displayedon the clock before the change was made.

� short old second — The previous second displayedon the clock before the change was made.






















Pt ARG DIM PtWidget



continued. . .



















Pt ARG POS PtWidget







Pt CB ARM PtBasic

continued. . .







Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget





PtColorPanel 2004, QNX Software Systems Ltd.

A color panel

Class hierarchy:PtWidget → PtBasic → PtContainer → PtCompound →PtColorSel → PtColorPanel

PhAB icon:

Public header:<photon/PtColorPanel.h>

Description:A composite color selector that provides color selection via acombination of the following optional mechanisms:

� A PtColorWell widget

� textual entry fields that let you type values for the individualchannels.

� A “dropper” button that lets you pick a color from anywhere on thescreen by clicking on it (press Esc to abort the operation).

A PtColorPanel widget.

New resources:


2004, QNX Software Systems Ltd. PtColorPanel


Pt ARG CPANEL FLAGS uint16 t Flags Pt CPANEL SHOW FIELDS |Pt CPANEL SHOW WELL |Pt CPANEL SHOW DROPPER

Pt ARG CPANEL FLAGS


uint16 t Flags Pt CPANEL SHOW FIELDS |Pt CPANEL SHOW WELL |Pt CPANEL SHOW DROPPER

Flags that affect the appearance and behavior of the color panel. Bitsinclude:

Pt CPANEL SHOW DROPPER

Display the dropper button.

Pt CPANEL SHOW FIELDS

Display the textual entry fields.

Pt CPANEL SHOW WELL

Display the color well.




continued. . .















Pt ARG CS COLOR PtColorSel

Pt ARG CS COLOR MODELS PtColorSel

Pt ARG CS CURRENT MODEL PtColorSel

Pt ARG CS FLAGS PtColorSel

Pt ARG CS PALETTE PtColorSel







Pt ARG DIM PtWidget

continued. . .


2004, QNX Software Systems Ltd. PtColorPanel



















Pt ARG POS PtWidget






continued. . .







Pt CB ARM PtBasic




Pt CB CS COLOR CHANGED PtColorSel



Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






2004, QNX Software Systems Ltd. PtColorPatchA widget for selecting a hue and shading or tint

Class hierarchy:PtWidget → PtBasic → PtContainer → PtCompound →PtColorSel → PtColorPatch

PhAB icon:

Public header:<photon/PtColorPatch.h>

Description:A PtColorPatch is a widget that you can use to select a color froma three dimensional color space by means of a 2-dimensional colorspectrum and a slider.

A PtColorPatch widget.

The widget includes:

� An optional combo box used to select the color space (HSB, andso on). It’s displayed if Pt CPATCH SHOW SELECTOR is set inPt ARG CPATCH FLAGS.


PtColorPatch 2004, QNX Software Systems Ltd.

� An optional slider on the left controls one of the variables of thethree-dimensional color space. It’s displayed ifPt CPATCH SHOW SLIDER is set in Pt ARG CPATCH FLAGS.

� An area displaying a “plane of color” defined by the remaining twovariables in the three-dimensional color space. You can use thepointer to select a color from this plane.

New resources:


Pt ARG CPATCH FLAGS ushort t Flags Pt CPATCH SHOW SELECTOR| Pt CPATCH SHOW SLIDER|Pt CPATCH ENABLE MENU

Pt ARG CPATCH FLAGS


ushort t Flags Pt CPATCH SHOW SELECTOR |Pt CPATCH SHOW SLIDER |Pt CPATCH ENABLE MENU

Flags that affect the appearance and behavior of the color patch. Bitsinclude:

Pt CPATCH SHOW SELECTOR

Show a PtComboBox selector that lets you select the colormodels that are supported by the color patch (see thePt ARG CS COLOR MODELS resource defined byPtColorSel).


2004, QNX Software Systems Ltd. PtColorPatch

Pt CPATCH SHOW SLIDER

Show a slider on the left that lets you change the channel notshown in the spectrum. Clear this bit if you want that channel toremain fixed (your application will need to set itprogrammatically).

Pt CPATCH ENABLE MENU

Enable a popup menu that lets you change the patch’sconfiguration. orientation of the palette, and so on.















continued. . .















Pt ARG DIM PtWidget












continued. . .


2004, QNX Software Systems Ltd. PtColorPatch








Pt ARG POS PtWidget









Pt CB ARM PtBasic







Pt CB DND PtWidget

continued. . .









Pt CB MENU PtBasic


Pt CB RAW PtWidget






2004, QNX Software Systems Ltd. PtColorSelSuperclass for color-selector widgets

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


� PtColorPanel

� PtColorPatch

� PtColorSelGroup

� PtColorWell


Public header:<photon/PtColorSel.h>

Description:PtColorSel is a superclass for all color-selection widgets. It definesa common interface to widgets that let you select colors. To maintainconsistency, any widget that implements color selection should be adescendant of PtColorSel.

New resources:


Pt ARG CS COLOR PgColor t Color Pg BLACK

Pt ARG CS COLOR MODELS PgColorModel t **,short

Array {Pg CM RGB}

continued. . .


PtColorSel 2004, QNX Software Systems Ltd.


Pt ARG CS CURRENT MODEL uint8 t Scalar 0

Pt ARG CS FLAGS uint16 t Flags 0

Pt ARG CS PALETTE PgPalette t * Alloc NULL

Pt CB CS COLOR CHANGED PtCallback t * Link NULL

Pt ARG CS COLOR


PgColor t Color Pg BLACK

The currently selected color. See PgColor t in the Photon LibraryReference.

Pt ARG CS COLOR MODELS


PgColorModel t **, short Array {Pg CM RGB}

A list of color models that this color selector supports. When you seta color using a color model that the selector doesn’t support, theactual color can still be calculated; ensuring that the color model issupported can reduce roundoff errors if the color doesn’t cleanly mapbetween RGB and the color model in question.

In addition, this resource is useful for widgets that let you choosefrom the different color models that the widget supports.

The following color models are defined:

Pg CM RGB Red-green-blue.

Pg CM HSB Hue-saturation-brightness.

Pg CM HLS Hue-lightness-saturation. A modified HSB modelthat’s more intuitive for selecting colors in a GUI.


2004, QNX Software Systems Ltd. PtColorSel

Pg CM CMYK Cyan-magenta-yellow-black.

Here’s an example of how to set this resource:

PgColorModel t const *models[]={Pg CM RGB, Pg CM CMYK,Pg CM HSB};

PtSetResource( my widget, Pt ARG CS COLOR MODELS,models, 3 );

Pt ARG CS CURRENT MODEL


uint8 t Scalar 0

An index to the currently active model into the array of color modelsthat this widget supports. Indexes start at 0.

Pt ARG CS FLAGS


uint16 t Flags 0

Flags that control the widget’s behavior:

Pt CS FAST UPDATE

If the selector is undergoing a high-bandwidth change, do anyrendering (if applicable) in a “fast” manner. This is a meta-flagthat doesn’t actually affect the behavior of PtColorSel itself,but may be observed by subclasses (PtColorPatch uses it torender the two-dimensional patch).

Pt CS QUANTIZE COLOR

Ensure Pt ARG CS COLOR is always mapped (quantized) tothe nearest match in the palette if a palette is set. The



PtColorSel widget always does this matching, so subclassesdon’t need to implement it.

Pt ARG CS PALETTE


PgPalette t * Alloc NULL

The color palette supported by this PtColorSel. A palette servesthese main purposes:

� It supplies the needed palette information for a palette-orientedcolor selector.

� It imposes a discrete set of colors within a continuous range thatthis selector must conform to.

Pt CB CS COLOR CHANGED



A list of PtCallback t structures that define the callbacks that areinvoked when the selected color changes.


reason Pt CB CS COLOR CHANGED

reason subtype

A combination of the following:

� Pt CS COLOR CHANGED — a low-bandwidth change(e.g. click, set). If this bit isn’t set, assume that ahigh-bandwidth change is in progress, and there mightbe many subsequent callbacks in a very short time.



� Pt CS COLOR CHANGE COMPLETE — awidget-specific inference that the selection is“complete.” For example, this bit is useful if the colorselector appears in a popup pane that you wish todismiss automatically when the change is complete.


cbdata A pointer to a PtColorSelCallback t structure thatcontains at least these members:

� PgColor t rgb — the selected color, in RGB format.See PgColor t in the Photon Library Reference.

� PgColorChannel t const *channels — theconstituent channel values for the selected color. Youshould interpret these values based on the color model.

� PgColorModel t const *color model — the colormodel, which you should to interpret the values storedin the channels. If this is NULL, the channels should bedisregarded.







continued. . .



















Pt ARG DIM PtWidget








continued. . .














Pt ARG POS PtWidget









Pt CB ARM PtBasic




continued. . .






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






2004, QNX Software Systems Ltd. PtColorSelGroupA group of color selectors

Class hierarchy:PtWidget → PtBasic → PtContainer → PtCompound →PtColorSel → PtColorSelGroup

PhAB icon:

Public header:<photon/PtColorSelGroup.h>

Description:A PtColorSelGroup is a composite color selector that, by default,provides a PtColorPanel for selecting colors and lets you add othercolor selectors to it to augment its functionality.

A PtColorSelGroup widget.

PtColorSelGroup ensures that all its children are synchronizedwhenever one of their values is changed.

New resources:


Pt ARG CSGROUP FLAGS uint16 t Flags 0


PtColorSelGroup 2004, QNX Software Systems Ltd.

Pt ARG CSGROUP FLAGS


uint16 t Flags 0

Flags that affect the appearance and behavior of the color-selectorgroup. Bits include:

Pt CSGROUP ALL AT ONCE

Display all of the children color selectors at once, rather thanshowing one at a time.













continued. . .


2004, QNX Software Systems Ltd. PtColorSelGroup















Pt ARG DIM PtWidget










continued. . .


PtColorSelGroup 2004, QNX Software Systems Ltd.










Pt ARG POS PtWidget









Pt CB ARM PtBasic






continued. . .


2004, QNX Software Systems Ltd. PtColorSelGroup



Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






PtColorWell 2004, QNX Software Systems Ltd.

A rectangle that displays a color and lets you change it

Class hierarchy:PtWidget → PtBasic → PtContainer → PtCompound →PtColorSel → PtColorWell

PhAB icon:

Public header:<photon/PtColorWell.h>

Description:A PtColorWell is a rectangular area that displays a color. Whenyou click on it, a PtColorPatch pops up to let you select a color tobe displayed in the color well.

A PtColorWell widget.

New resources:


2004, QNX Software Systems Ltd. PtColorWell


Pt ARG CWELL FLAGS uint16 t Flags Pt CWELL POPUP ON SELECT|Pt CWELL POPUP ON MENU

Pt ARG CWELL SWATCH DIM PhDim t Struct {220, 120}

Pt ARG CWELL FLAGS


uint16 t Flags Pt CWELL POPUP ON SELECT |Pt CWELL POPUP ON MENU

Flags that affect the appearance and behavior of the color well. Youcan set this resource to any combination of these bits:

Pt CWELL POPUP ON SELECT

Pop up the color patch when you click on the well using theselect (usually left) button.

Pt CWELL POPUP ON MENU

Pop up the color patch when you click on the well using themenu (usually right) button.

Pt ARG CWELL SWATCH DIM


PhDim t Struct {220, 120}

A PhDim t structure (see the Photon Library Reference) that definesthe dimensions of the popup color patch, in pixels.
























continued. . .








Pt ARG DIM PtWidget


















Pt ARG POS PtWidget

continued. . .












Pt CB ARM PtBasic







Pt CB DND PtWidget






Pt CB MENU PtBasic


continued. . .




Pt CB RAW PtWidget






PtComboBox 2004, QNX Software Systems Ltd.

A text field with a list of choices

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

PhAB icon:

Public header:<photon/PtComboBox.h>

Description:The PtComboBox class provides a widget that’s built from twoexported subordinate widgets: PtList and PtText.

A PtComboBox widget provides a text-entry area and a list of choices.

You can type in the text field or choose a predefined entry from thelist. The list can be either:

Static Always present above or below the text field.

Dropping You must click a button to see the list.


2004, QNX Software Systems Ltd. PtComboBox

The widget behaves like a PtList or PtText widget, depending onwhich part has focus.

You can’t specify the selection mode for the list;Pt ARG SELECTION MODE is blocked. The list always usesPt BROWSE MODE.

�

To select an item using the pointer, either click on an item or drag thepointer down the list and release the button when the correct item ishighlighted. You can select only one item. If you drag the pointer, thelist can scroll.

A blocking mechanism lets PtComboBox block the inheritance ofcertain resources from its subordinate widgets. This prevents anyactions that would negatively affect the look and behavior of aPtComboBox widget. For more information, see the “Exportedsubordinate children” section.

Keyboard actions

The keyboard actions depend on which part of the PtComboBox hasfocus. If the text widget has focus, the keyboard actions are:

Key Action

↑ Set the text to the previous item in the list

↓ Set the text to the next item in the list

Alt – ↓ Display the list, highlighting the item corresponding tothe current text

The Alt – ↓ action occurs only if Pt COMBOBOX ALT DOWN is set inthe widget’s Pt ARG CBOX FLAGS.

If the list has focus, the keyboard actions are:



Key Action

Enter Select the current item (see “Current item” in thedescription of PtGenList)

↑ Move to the previous item

↓ Move to the next item

Pg Up Move to the previous page

Pg Dn Move to the next page

Home Move to the first item

End Move to the last item

Callbacks

The following callbacks are associated with the text part of thePtComboBox and are invoked as described for PtText:

� Pt CB ACTIVATE

� Pt CB MODIFY NOTIFY or Pt CB TEXT CHANGED

� Pt CB MODIFY VERIFY

� Pt CB MOTION NOTIFY

� Pt CB MOTION VERIFY

The following callbacks are associated with the list part of thePtComboBox and are invoked as described for PtList:

� Pt CB LIST INPUT

� Pt CB SELECTION

PtComboBox also defines the following callbacks for the list:

� Pt CB CBOX ACTIVATE

� Pt CB CBOX CLOSE



New resources:


Pt ARG CBOX BUTTON WIDTH unsigned short Scalar 17

Pt ARG CBOX FLAGS unsigned long Flag 0

Pt ARG CBOX MAX VISIBLE COUNT unsigned short Scalar 0

Pt ARG CBOX SEL ITEM unsigned short Scalar 0

Pt ARG CBOX TEXT FILL COLOR unsigned long Scalar Pg LGRAY

Pt CB CBOX ACTIVATE PtCallback t * Link NULL

Pt CB CBOX CLOSE PtCallback t * Link NULL

Pt ARG CBOX BUTTON WIDTH



The width of the drop button, in pixels.

Pt ARG CBOX FLAGS


unsigned long Flag 0

Possible values:

Pt COMBOBOX ALT DOWN

Enable the Alt – ↓ keychord, which displays the list andhighlights the item corresponding to the current text.

Pt COMBOBOX MAX WIDTH

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



Pt COMBOBOX OPEN (read-only)

If this bit is set, the list is currently open.

Pt COMBOBOX STATIC

Make the list field static and remove the drop button. If this bitis off, the list field is visible only when the drop button ispressed.

Pt COMBOBOX TOP

Place the list field above the text field. If this bit is off, the listfield is placed below the text field. If there isn’t enough spacebetween the text field and the edge of the screen, the list mayappear on the opposite side of the text field.

Pt ARG CBOX MAX VISIBLE COUNT



The maximum number of list items that may be visible beforescrollbars appear. If this is 0, the entire list is displayed withoutscrollbars.

You can use either this resource or Pt ARG VISIBLE COUNT tocontrol the size of the list, but you shouldn’t use them both.

Pt ARG CBOX SEL ITEM



An index into Pt ARG ITEMS that indicates which list item iscurrently selected.



Pt ARG CBOX TEXT FILL COLOR


unsigned long Scalar Pg LGRAY

The fill color of the text area.

Pt CB CBOX ACTIVATE



A list of PtCallback t structures that define the callbacks that thewidget invokes when the list is activated (i.e opened).


reason Pt CB CBOX ACTIVATE


cbdata NULL


Pt CB CBOX CLOSE



A list of PtCallback t structures that define the callbacks that areinvoked when you close the combobox’s list.




reason Pt CB CBOX CLOSE.


cbdata NULL.


Exported subordinate children:Unless the resources are already defined in PtComboBox, thePtComboBox class uses the resources of its exported subordinatechildren, PtList and PtText.

The PtComboBox class “inherits” all the resources of its exportedsubordinate children, with the exception of the following, which areblocked:

� Pt ARG SELECTION MODE (defined in PtGenList andinherited by PtList) — browse mode is always used.

� Pt ARG SELECTION INDEXES (defined in PtList) —PtComboBox replaces this with Pt ARG CBOX SEL ITEMbecause you can select only one item from the list.

Where PtComboBox and one of its exported subordinate childrenboth define resources having the same name, the resource defined inPtComboBox takes precedence.

Inherited resources:If PtComboBox modifies an inherited resource, the “Default override”column indicates the new value. If PtComboBox inherits a resourcefrom one of its exported subordinate children, the default value



assigned by the subordinate widget is inherited too; the “Defaultoverride” column shows this default value.


Pt ARG ACCEL KEY PtLabel Blocked by this class.














Pt ARG COLUMNS PtText




Pt ARG CURSOR POSITION PtText



continued. . .







Pt ARG DIM PtWidget

Pt ARG EDIT MASK PtText





Pt ARG FLAGS PtWidget |=Pt HIGHLIGHTED |Pt SET&=˜Pt GETS FOCUS




Pt ARG HORIZONTAL ALIGNMENT PtLabel


Pt ARG ITEMS PtList


Pt ARG LABEL FLAGS PtLabel &=˜Pt LABEL SELECT SHIFT


Pt ARG LABEL TYPE PtLabel Blocked by this class.



continued. . .




Pt ARG LINE SPACING PtLabel Blocked by this class.

Pt ARG LIST BALLOON PtList

Pt ARG LIST COLUMN ATTR PtGenList

Pt ARG LIST COLUMN POS PtGenList

Pt ARG LIST FLAGS PtGenList

Pt ARG LIST FONT PtGenList

Pt ARG LIST ITEM COUNT PtGenList

Pt ARG LIST SB RES PtGenList

Pt ARG LIST SCROLL RATE PtGenList

Pt ARG LIST SEL COUNT PtGenList

Pt ARG LIST SPACING PtList

Pt ARG LIST TOTAL HEIGHT PtGenList







Pt ARG MAX LENGTH PtText



Pt ARG MODIFY ITEMS PtList


continued. . .





Pt ARG POS PtWidget

Pt ARG RESIZE FLAGS PtWidget Pt RESIZE XY ALWAYS

Pt ARG SCROLLBAR WIDTH PtGenList 17

Pt ARG SELECTION FILL COLOR PtGenList

Pt ARG SELECTION INDEXES PtList Blocked by this class; seePt ARG CBOX SEL ITEM

Pt ARG SELECTION MODE PtGenList Blocked by this class;browse mode is alwaysused.

Pt ARG SELECTION RANGE PtText

Pt ARG SELECTION TEXT COLOR PtGenList


Pt ARG TEXT CURSOR WIDTH PtText

Pt ARG TEXT FLAGS PtText


Pt ARG TEXT HIGHLIGHT BACKGROUND COLOR PtText

Pt ARG TEXT HIGHLIGHT TEXT COLOR PtText



Pt ARG TEXT SUBSTRING PtText



Pt ARG TOP ITEM POS PtGenList

continued. . .





Pt ARG UNDERLINE TYPE PtLabel Blocked by this class.

Pt ARG UNDERLINE1 PtLabel Blocked by this class.

Pt ARG UNDERLINE2 PtLabel Blocked by this class.


Pt ARG VERTICAL ALIGNMENT PtLabel

Pt ARG VISIBLE COUNT PtGenList See below.


Pt CB ACTIVATE PtBasic Behaves as for PtText.

Pt CB ARM PtBasic






Pt CB DND PtWidget





Pt CB LIST INPUT PtList


Pt CB MENU PtBasic

continued. . .




Pt CB MODIFY NOTIFY PtText

Pt CB MODIFY VERIFY PtText

Pt CB MOTION NOTIFY PtText

Pt CB MOTION VERIFY PtText


Pt CB RAW PtWidget




Pt CB SCROLL MOVE PtGenList

Pt CB SELECTION PtList

Pt CB TEXT CHANGED PtText


Pt ARG VISIBLE COUNT

Set this resource to a nonzero value to resize the list to a multiple ofthe item height. If the number of items is less than this resource,blank items are displayed at the end of the list; if the number of itemsis greater than this resource, a scrollbar is displayed.

You can use either this resource orPt ARG CBOX MAX VISIBLE COUNT to control the size of the list,but you shouldn’t use them both.

Convenience functions:The PtComboBox widget and its exported subordinate PtList andPtText children define various convenience functions that make iteasier to use the combo box once it’s been created. Here’s a briefoverview:



PtComboBoxListOpen()

Open a combobox list.

PtComboBoxListClose()

Close an open combobox list.

PtListAddItems()

Adds one or more items to the list at a specified position.

PtListDeleteAllItems()

Removes all the items from the list.

PtListDeleteItems()

Deletes items in the list by name.

PtListDeleteItemPos()

Deletes a range of items by position.

PtListItemExists()

Determines whether or not an item exists within the list.

PtListItemPos()

Determines the position of an item within the list.

PtListRemovePositions()

Deletes items at specified positions.

PtListReplaceItemPos()

Replaces items by position number.

PtListReplaceItems()

Replaces items by item text.

PtTextGetSelection()

Gets the selected range from a PtText widget.

PtTextModifyText()

Modifies the contents of a PtText widget.



PtTextSetSelection()

Sets the selected range for a PtText widget.


2004, QNX Software Systems Ltd. PtComboBoxListClose()Close an open combobox list

Synopsis:int PtComboBoxListClose( PtWidget t *widget );

Description:This function closes the list in a PtComboBox widget.

Returns:0 Success.

-1 The specified widget isn’t a PtComboBox widget.


Safety

Interrupt handler No

Signal handler No

Thread No

See also:PtComboBoxListOpen()


PtComboBoxListOpen() 2004, QNX Software Systems Ltd.

Open a combobox list

Synopsis:int PtComboBoxListOpen( PtWidget t *widget );

Description:This function opens/drops down the list in a PtComboBox widget.

Returns:0 Success.

-1 The specified widget isn’t a PtComboBox widget.


Safety


Signal handler No

Thread No

See also:PtComboBoxListClose()


2004, QNX Software Systems Ltd. PtCompoundSuperclass for all compound widgets

Class hierarchy:PtWidget → PtBasic → PtContainer → PtCompound


� PtColorSel

� PtComboBox

� PtDivider

� PtGenList

� PtMenuButton

� PtMultitext

� PtNumeric


Public header:<photon/PtCompound.h>

Description:The PtCompound superclass provides the ability to combine widgetsinto a compound. A compound widget can export its subordinatechildren to let you get and set their resources, or it can block access tothem to provide a “canned” appearance.



PtCompound 2004, QNX Software Systems Ltd.




















Pt ARG DIM PtWidget





continued. . .


2004, QNX Software Systems Ltd. PtCompound















Pt ARG POS PtWidget









Pt CB ARM PtBasic

continued. . .


PtCompound 2004, QNX Software Systems Ltd.







Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






2004, QNX Software Systems Ltd. PtContainerLayout and geometry management for all container widgets

Class hierarchy:PtWidget → PtBasic → PtContainer


� PtBkgd

� PtClient

� PtCompound

� PtDisjoint

� PtFlash

� PtFontSel

� PtGroup

� PtOSContainer

� PtPane

� PtPanelGroup

� PtPrintSel

� PtScrollArea

� PtTerminal

� PtToolbar

� PtToolbarGroup

PhAB icon:


PtContainer 2004, QNX Software Systems Ltd.

Public header:<photon/PtContainer.h>

Description:The PtContainer superclass provides layout and geometrymanagement for all container widgets. It also redirects certain events— such as button presses, releases, repeats, and keys — to the childthat has focus.

New resources:


Pt ARG CONTAINER FLAGS long Flag Pt ENABLE CUA

Pt ARG CURSOR OVERRIDE int Boolean Pt FALSE

Pt ARG LAYOUT PtLayoutDefinition t * Struct NULL

Pt ARG LAYOUT INFO void * Struct NULL

Pt ARG LAYOUT TYPE int Scalar NULL

Pt ARG FILL LAYOUT INFO PtFillLayoutInfo t * Struct NULL

Pt ARG GRID LAYOUT INFO PtGridLayoutInfo t * Struct NULL

Pt ARG ROW LAYOUT INFO PtRowLayoutInfo t * Struct NULL

Pt ARG TITLE char * String NULL

Pt ARG TITLE FONT char * String "TextFont09"

Pt CB BALLOONS PtBalloonCallback t * Link NULL

Pt CB CHILD GETTING FOCUS PtCallback t * Link NULL

Pt CB CHILD LOSING FOCUS PtCallback t * Link NULL

Pt CB CHILD ADDED REMOVED PtCallback t * Link NULL

continued. . .


2004, QNX Software Systems Ltd. PtContainer


Pt CB LAYOUT PtCallback t * Link NULL

Pt CB RESIZE PtCallback t * Link NULL

Pt ARG CONTAINER FLAGS


long Flag Pt ENABLE CUA

Flags that control the look and behavior of the container:

Pt AUTO EXTENT

Cause the container to recalculate its preferred size when any ofits children are realized, unrealized, moved, or resized.

Pt BLOCK CUA FOCUS

Prevent Common User Access from moving focus into thiscontainer.

Pt DISABLE BALLOONS

Prevent balloons from being inflated in this or any childcontainer.

Pt ENABLE CUA

Let CUA keys function in this container (and its children).

Pt ENABLE CUA ARROWS

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

Pt ETCH TITLE AREA

Display an etched line below the title given by Pt ARG TITLE,provided that Pt SHOW TITLE is also set.

Pt GRADIENT TITLE AREA

Display a gradient behind the title given by Pt ARG TITLE,provided that Pt SHOW TITLE is also set.



Pt HOTKEYS FIRST

Process key events that reach this container as hotkeys beforepassing them to any children. If the key is a hotkey, the event isconsumed and isn’t passed to any children. Normally the key ispassed to the children and, if not consumed, is processed as ahotkey.

Pt HOTKEY TERMINATOR

Prevent hotkey searches from going to parents of this container.Note that this flag works only if it’s set in a disjointcontainer-class widget.

Pt SHOW TITLE

Display the title given by Pt ARG TITLE, using the fontspecified by Pt ARG TITLE FONT .

Pt ARG CURSOR OVERRIDE


int Boolean Pt FALSE

Let the container’s cursor override its children’s cursors.

Pt ARG LAYOUT


PtLayoutDefinition t * Struct NULL

A generic resource that lets you set the active layout for the container,and the layout info structure at the same time. This is an alternative tosetting Pt ARG LAYOUT TYPE and Pt ARG * LAYOUT INFOseparately.

This resource can be one of:

� PtFillLayout

� PtRowLayout



� PtGridLayout

� NULL (equivalent to PtAnchorLayout, the default layout type)

When you set this resource using PtSetResource() or PtSetArg(), youcan optionally also set the Pt ARG * LAYOUT INFO resource for theappropriate layout type using the len argument. To do this, pass apointer to layout information structure appropriate to the layout typeas len. It can be one of:

� PtFillLayoutInfo t

� PtRowLayoutInfo t

� PtGridLayoutInfo t

For more information about using layouts and layout resources, seeUsing Layouts in Geometry Management in the PhotonProgrammer’s Guide.

Pt ARG LAYOUT INFO


void * Struct NULL

A generic resource that lets you set the information structure forlayouts. When you set this resource, you must set the len argument ofPtSetResource() or PtSetArg() to the layout type, which is one of:

� PtFillLayout

� PtRowLayout

� PtGridLayout




Pt ARG LAYOUT TYPE


int Scalar NULL

An alternative way of setting or getting the active layout and layoutinformation.

When you set this resource, the value argument of PtSetResource() orPtSetArg() can be one of:

� Pt FILL LAYOUT

� Pt ROW LAYOUT

� PT GRID LAYOUT

� Pt ANCHOR LAYOUT

You can optionally also set the information structure with thisresource. To do this, set the len argument of PtSetResource() orPtSetArg() to the layout information structure, Pt*LayoutInfo t.If you set len to NULL, the information structure for the current layoutis set. In this case, make sure that the layout information structure youset matches the current layout type, or your application may crash.


Pt ARG FILL LAYOUT INFO


PtFillLayoutInfo t Struct NULL

The information structure for the PtFillLayout layout type. Youcan set this resource directly, or via Pt ARG LAYOUT INFO.

The PtFillLayoutInfo t contains at least these members:



short type Direction of layout:

� Pt LAYOUT HORIZONTAL — layout children in arow

� Pt LAYOUT VERTICAL — layout children in acolumn

short spacing

Distance between children, in pixels

There is no layout data for children for this layout type.


Pt ARG ROW LAYOUT INFO


PtRowLayoutInfo t Struct NULL

The information structure for the PtRowLayout layout type. You canset this resource directly, or via Pt ARG LAYOUT INFO.

PtRowLayoutInfo t contains at least these members:

short type Direction of layout:

� Pt LAYOUT HORIZONTAL — layout children inrows

� Pt LAYOUT VERTICAL — layout children incolumns

short flags A combination of the following flags:

� Pt ROW JUSTIFY — distribute extra spacebetween children when the container grows

� Pt ROW PACK — leave children widgets theirpreferred size. If this flag is not set, child widgetsare all the same size.



� Pt ROW WRAP — enable wrapping

PhRect t margins

Container margins in pixels, where:

� ul.x is the left

� ul.y is the top

� lr.x is the right

� lr.y is the bottom

short h spacing

Horizontal spacing distance between children, inpixels

short v spacing

Vertical spacing between children, in pixels

You can use PtRowLayoutInfoDflts to initialize your copy ofPtRowLayoutInfo t. It has the following values:

type = Pt LAYOUT HORIZONTAL

flags = Pt ROW PACK | Pt ROW WRAP

margin.ul.x = margin.ul.y = margin.lr.x = margin.lr.y = 3

h spacing = v spacing = 3

�


Pt ARG GRID LAYOUT INFO


PtGridLayoutInfo t Struct NULL



The information structure for the PtGridLayout layout type. Youcan set this resource directly, or via Pt ARG LAYOUT INFO.

PtGridLayoutInfo t contains at least these members:

unsigned n cols

The number of columns in the grid.

unsigned flags

Combination of the following flags:

� Pt EQUAL COLS — Force all columns to be the same width.

� Pt EQUAL ROWS — Force all rows to be the same height.

PhRect t margins

Container margins in pixels, where:


� ul.y is the top



short h spacing

Horizontal spacing between columns, in pixels.

short v spacing

Vertical spacing between rows, in pixels.



You can use PtGridLayoutInfoDflts to initialize your copy ofPtGridLayoutInfo t. It has the following values:

� n cols = 1

� flags = 0

� margin.ul.x = margin.ul.y = margin.lr.x = margin.lr.y = 2

� h spacing = v spacing = 2

�


Pt ARG TITLE


char * String NULL

The title to be displayed if Pt SHOW TITLE is set inPt ARG CONTAINER FLAGS.

Pt ARG TITLE FONT



The font to use for the label’s text string; see PgSetFont() in thePhoton Library Reference.

Pt CB BALLOONS

continued. . .





PtBalloonCallback t * Link NULL

A list of PtBalloonCallback t structures that define ballooncallbacks that the container invokes if the pointer remains motionlessfor 1.25 seconds over the widget specified in the callback structure.


reason Pt CB BALLOONS

reason subtype

Pt INFLATE BALLOON when the balloon should bedisplayed, or Pt POP BALLOON when it should beremoved.


cbdata NULL

These callbacks (unlike other callbacks) return nothing.�

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

� Pt ARG LABEL BALLOON (PtLabel and its subclasses)

� Pt ARG LIST BALLOON (PtList)

� Pt ARG TREE BALLOON (PtTree)

When a container has balloons registered, it becomes sensitive toPh EV BOUNDARY events. When the container sees an enter event, it



enables the balloon mechanism for that container. When a boundaryevent with a subtype of Ph EV PTR STEADY is received and it’s overa widget that has registered a balloon, the balloons are flagged asactive and the widget’s inflate function is called.

While the balloons are active, Ph EV PTR MOTION NOBUTTONevents are used to determine when the cursor leaves a widget with aninflated balloon (its inflate function is called with a Pt POP BALLOONsubtype). While the balloons are active, any widget that has a balloonthat intersects with a Ph EV PTR MOTION NOBUTTON event has itsballoon inflated.

Key events and pointer button events deactivate the balloons. AnotherPh EV PTR STEADY event over a widget with a balloon is required toreactivate the balloons.

If your application has a widget that obscures the container, thewidget must have a region that consumes Ph EV BOUNDARY eventsto prevent the balloon mechanism for the container from becomingenabled and activated.

This can be done by giving the overlapping widget a Pt CB RAWcallback (see PtWidget) that’s sensitive to Ph EV BOUNDARYevents, or by giving the overlapping widget a cursor (whichautomatically sets Ph FORCE BOUNDARY in the flags for thewidget’s region, which means it’s opaque to boundary events).

�

Pt CB CHILD ADDED REMOVED



A list of PtCallback t structures that define the callbacks that areinvoked when a widget is added or removed from a container:

� When a child is being added to the container, these callbacks areinvoked after the child has been completely added to the widgetfamily hierarchy and has been realized (if applicable).



� When a child is being removed from the container, these callbacksare invoked after the child has been unrealized. If the child is beingdestroyed, these callbacks are invoked before the child is freed (i.e.the pointer to the child is still valid, but the child hasPt DESTROYED set in its Pt ARG FLAGS.

These callbacks are invoked only if:

� Pt CALLBACKS ACTIVE is set in the container’s Pt ARG FLAGS.

� Pt PROCREATED isn’t set in the Pt ARG FLAGS of the child beingadded or removed.

�

Each callback is passed a PtCallbackInfo t structure thatcontains at least the following:

reason Pt CB CHILD ADDED REMOVED

reason subtype

Pt CHILD ADDED or Pt CHILD REMOVED.

event Not used (NULL).

cbdata A pointer to the widget being added or removed (i.e. thenew or former child widget).

Pt CB CHILD GETTING FOCUS



A list of PtCallback t structures that define the callbacks invokedwhen a child widget (or child of a child and so on) is getting focus.You can call PtIsFocused() to find the current focus state of anywidget.




reason Pt CB CHILD GETTING FOCUS

reason subtype

0 (not used).



PtWidget t *src

A pointer to the widget which is losing focus. Thispointer could be NULL.

PtWidget t *dst

A pointer to the widget which is intended to get thefocus. This pointer could be NULL, for example ifPtContainerNullFocus() was invoked.

PtWidget t *child

A pointer to the immediate child of the calledcontainer callback.



Or:




Pt CB CHILD LOSING FOCUS



A list of PtCallback t structures that define the callbacks invokedwhen a child widget (or child of a child and so on) is losing focus.You can call PtIsFocused() to find the current focus state of anywidget.


reason Pt CB CHILD LOSING FOCUS

reason subtype

0 (not used).



PtWidget t *src

A pointer to the widget which is losing focus. Thispointer could be NULL.

PtWidget t *dst

A pointer to the widget which is intended to get thefocus. This pointer could be NULL, for example ifPtContainerNullFocus() was invoked.

PtWidget t *child

A pointer to the immediate child of the calledcontainer callback.





Or:


Pt CB LAYOUT



A list of PtCallback t structures that define the callbacks invokedwhen the widget is about to start laying out children, and when thewidget is finished laying out children.


reason Pt CB LAYOUT

reason subtype

� Pt LAYOUT INIT — starting to lay out children.

� Pt LAYOUT DONE — finished laying out children.

event A pointer to a PhEvent t structure filled withNULLs

cbdata NULL


Pt CB RESIZE





A list of PtCallback t structures that define the callbacks that thecontainer invokes when its size changes. Each callback is passed aPtCallbackInfo t structure that contains at least the followingmembers:

reason Pt CB RESIZE

reason subtype

0 (not used).

event Not used (NULL).

cbdata A pointer to a PtContainerCallback t structure thatcontains at least the following members:

PhRect t old size;

A PhRect t structure (see the Photon LibraryReference that contains the extent of the containerbefore the size changed.

PhRect t new size;

A PhRect t structure that contains the new extentof the container after the size changed.

PhDim t old dim

A PhDim t structure that contains the dimensionsof the container before the size changed.

PhDim t new dim

A PhDim t structure that contains the dimensionsof the container after the size changed.






















Pt ARG DIM PtWidget

Pt ARG EFLAGS PtWidget Pt CONSUME EVENTS






continued. . .















Pt ARG POS PtWidget







Pt CB ARM PtBasic




Pt CB DND PtWidget

continued. . .









Pt CB MENU PtBasic


Pt CB RAW PtWidget





2004, QNX Software Systems Ltd. PtDisjointSuperclass for disjoint widgets

Class hierarchy:PtWidget → PtBasic → PtContainer → PtDisjoint


� PtMenu

� PtRegion

� PtWindow


Public header:<photon/PtDisjoint.h>

Description:PtDisjoint is the superclass for the widget classes that are disjoint(i.e. are instantiated without a parent).

New resources:


Pt ARG SYSINFO PhSysInfo t * Pointer See below.

Pt CB SYSINFO PtCallback t * Link NULL

Pt ARG SYSINFO (read only)


PhSysInfo t * Pointer See below.


PtDisjoint 2004, QNX Software Systems Ltd.

If you get the value of this resource, you get a pointer to aPhSysInfo t structure (see the Photon Library Reference) thatindicates the conditions above this widget.

Pt CB SYSINFO



A list of PtCallback t structures that define the callbacks invokedwhen the widget receives a Ph EV INFO event.


reason Pt CB SYSINFO

reason subtype

One of:

� Ph FEP — the information is from a “front-end inputprocessor.” You can get the data with this code:PhFEPInfo t *fep info = PhGetData( event );

� Ph INVALIDATE SYSINFO — the renderingenvironment has changed. No data is included in theevent; if you need it, call PhQuerySystemInfo() orPtQuerySystemInfo(), both of which are described inthe Photon Library Reference.


cbdata NULL.



2004, QNX Software Systems Ltd. PtDisjoint






Pt ARG BANDWIDTH THRESHOLD PtBasic















Pt ARG DIM PtWidget

continued. . .


PtDisjoint 2004, QNX Software Systems Ltd.



















Pt ARG POS PtWidget






continued. . .


2004, QNX Software Systems Ltd. PtDisjoint





Pt CB ARM PtBasic






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






PtDivider 2004, QNX Software Systems Ltd.

A container that divides space among its children

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

PhAB icon:

Public header:<photon/PtDivider.h>

Description:The PtDivider widget is a container that lays out its children like aone-row or one-column PtGroup widget, but lets you resize thechildren by dragging “handles” placed between the children.

Two PtDivider widgets: one contains two lists, the other contains some

buttons.

The PtDivider class inherits resources from the PtGroup class.Access to these resources is controlled through PtDivider’sexporting mechanism.

A blocking mechanism lets PtDivider block the inheritance ofcertain resources from its subordinate PtGroup widget. This preventsany actions that would negatively affect the look and behavior of aPtDivider widget. For more information, see the “Exportedsubordinate children” section.


2004, QNX Software Systems Ltd. PtDivider

New resources:


Pt ARG DIVIDER FLAGS unsigned short Flag Pt DIVIDER RESIZE BOTH

Pt ARG DIVIDER OFFSET short Scalar 0

Pt ARG DIVIDER SIZES PtDividerSizes t, short Array NULL, 0(read-only)

Pt CB DIVIDER DRAG PtCallback t * Link NULL

Pt ARG DIVIDER FLAGS


unsigned short Flag Pt DIVIDER RESIZE BOTH

Possible values:

Pt DIVIDER NORESIZE

Don’t resize the children, just invoke the callback.

Pt DIVIDER RESIZE BOTH

Resize both widgets: the one to the left and to the right (orabove and below) the dragged handle. If this flag isn’t set, onlythe left child is resized and the right child is moved.

Pt DIVIDER INVISIBLE

Never display the drag outline. This flag is useful mainly whenPt DIVIDER NORESIZE is also set.

Pt ARG DIVIDER OFFSET




short Scalar 0

This number is added to positions of child widgets (relative to theposition of the PtDivider widget) when the values for thePt ARG DIVIDER SIZES resource are calculated. By settingPt ARG DIVIDER OFFSET , you can make thePt ARG DIVIDER SIZES relative to any arbitrary point.

Pt ARG DIVIDER SIZES (read-only)


PtDividerSizes t, short Array NULL, 0

The array of positions and sizes of realized children of the divider.Each PtDividerSizes t structure contains:

short from The left side or top of the child, depending on thedivider’s orientation.

short to The right or bottom of the child, depending on thedivider’s orientation.

Pt CB DIVIDER DRAG



A list of PtCallback t structures that define the callbacks that areinvoked when the widget receives a drag event.

If the widget has the Pt CALLBACKS ACTIVE bit set in itsPt ARG FLAGS resource, these callbacks are also invoked when yourapplication changes the size of a child by calling PtSetResource() orPtSetResources().




reason Pt CB DIVIDER DRAG

reason subtype

The subtype of the drag event (see Ph EV DRAG in thedescription of the PhEvent t structure in the PhotonLibrary Reference), or Pt CB DIVIDER SETRESOURCESif a child is being resized through PtSetResources() andthe widget has the Pt CALLBACKS ACTIVE bit set in itsPt ARG FLAGS resource.

event A pointer to a PhEvent t structure that describes thereceived drag event, or NULL if a child is being resizedthrough a call to PtSetResources().

cbdata A pointer to a PtDividerCallback t structure thatcontains at least the following members:

PtWidget t *left, *right;

The two widgets in the group separatedby the divider.

int moved; How far the widget on the right has beenmoved.

int resized; The amount by which the widget on theleft has been resized.

PtDividerSizes t const *sizes;

The new value of thePt ARG DIVIDER SIZES resource.

int nsizes; The number of items in the sizes array.




Exported subordinate children:Unless the resources are already defined in PtDivider, thePtDivider class uses the resources of its exported subordinate child,PtGroup.

Where PtDivider and PtGroup both define resources having thesame name, the resource defined in PtDivider takes precedence.

Inherited resources:If PtDivider modifies an inherited resource, the “Default override”column indicates the new value. If PtDivider inherits a resourcefrom PtGroup, the default value assigned by PtGroup is inheritedtoo; the “Default override” column shows this default value.


Pt ARG ANCHOR FLAGS PtWidget 0 (no anchors)



Pt ARG BANDWIDTH THRESHOLD PtBasic Ph BAUD CONSOLE (seebelow)







Pt ARG CONTAINER FLAGS PtContainer Sets Pt AUTO EXTENT andPt CHILD MOVED RESIZED


continued. . .










Pt ARG DIM PtWidget

Pt ARG EFLAGS PtWidget ClearsPt DAMAGE ON FOCUS, setsPt CONSUME EVENTS





Pt ARG GROUP FLAGS PtGroup Sets Pt GROUP STRETCH flag

Pt ARG GROUP HORZ ALIGN PtGroup

Pt ARG GROUP ORIENTATION PtGroup Pt GROUP HORIZONTAL (seebelow)

Pt ARG GROUP ROWS COLS PtGroup Blocked by this class.

Pt ARG GROUP SPACING PtGroup 0

Pt ARG GROUP SPACING X PtGroup Blocked by this class.

Pt ARG GROUP SPACING Y PtGroup Blocked by this class.

Pt ARG GROUP VERT ALIGN PtGroup 0


continued. . .















Pt ARG POS PtWidget

Pt ARG RESIZE FLAGS PtWidget 0








Pt CB ARM PtBasic



continued. . .







Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






Defines the “graphics bandwidth” threshold that determines whetherthe widget resizes the children after each received drag event or onlyonce, when the drag is completed — see PtQuerySystemInfo().

Pt ARG GROUP ORIENTATION

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


PtEllipse 2004, QNX Software Systems Ltd.

An ellipse

Class hierarchy:PtWidget → PtBasic → PtGraphic → PtEllipse

PhAB icon:

Public header:<photon/PtEllipse.h>

Description:The PtEllipse class draws an ellipse.

A PtEllipse widget.

The bounding box of the ellipse, which determines its height andwidth, is defined by two points that you can specify in thePt ARG POINTS resource. These points are relative to the widget’sPt ARG ORIGIN. For more information, see PtGraphic.

If you don’t set these points, Pt ARG DIM determines the height andwidth (see PtWidget).



2004, QNX Software Systems Ltd. PtEllipse




















Pt ARG DIM PtWidget





continued. . .


PtEllipse 2004, QNX Software Systems Ltd.






















Pt ARG POS PtWidget



continued. . .


2004, QNX Software Systems Ltd. PtEllipse






Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






PtFileSel 2004, QNX Software Systems Ltd.

A tree widget for selecting files and directories

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

PhAB icon:

Public header:<photon/PtFileSel.h>

Description:The PtFileSel widget is a tree where items can be files, directories,links to files or directories, or custom entries.

A PtFileSel widget.

This widget is useful when a program lets you open or save files ordirectories. It reads a directory and displays the contents. You canalso use the widget to navigate a filesystem and choose your own fileand directory.

The items in the PtFileSel widget are displayed with images toshow what type of file they are. Directory items are expandable andcan show the files, directories and links under them. To expand andcollapse items, you can use the pointer or these keys:


2004, QNX Software Systems Ltd. PtFileSel

To: Press one of:

Expand a directory Enter, →, or + on the keypad

Collapse a directory Backspace, ←, or - on the keypad

Each item is stored in a PtFileSelItem t structure that contains atleast:

PtGenTreeItem t gen

Used internally.

short opened

A value that indicates whether the given directories’children have already been allocated or not:

� Pt FS NEW DIR — an unallocated directory

� Pt FS OLD DIR — an allocated directory

short type The type of file the item is:

� Pt FS DIR OP — an open directory, one that hasvisible items

� Pt FS DIR CL — a closed directory, one thatdoesn’t have visible items

� Pt FS DLINK OP — a link to an open directory

� Pt FS DLINK CL — a link to a closed directory

� Pt FS FILE — a file

� Pt FS FLINK — a link to a file

� Pt FS ERROR — a file that had a read error

short root A value that indicates if this is the root item:

� 1 — this is the root directory

� 0 — this isn’t the root directory



char *fullpath

The full pathname of the item

int tag Used internally

The widget has two main modes of operation:

Tree mode (default)

Items are displayed in a tree structure; opening a directorycauses a new branch to be created.

Single-level mode

Items are displayed in a single level or list; the list contains allthe files in the current directory. When a directory is chosen, theexisting items are freed and new ones are created for the newdirectory. You can traverse up the filesystem by using the ..item. To use this mode, set the Pt FS SINGLE LEVEL bit inPt ARG FS FLAGS.

A single-level file selector.

In this mode, you can also turn on the “key seek” flag,Pt FS SEEK KEY, which lets you use the keyboard to search fora file. In this mode, the widget selects the next file or directory



whose name starts with a character that you type. The search iscase-sensitive and wraps to the top of the list if the characterisn’t found. Whenever you press a key, thePt CB FS SELECTION callback is invoked with areason subtype of Pt LIST SELECTION BROWSE.

The widget can also display file information including name, size,date, permissions, owner and group. You can use thePt ARG FS FORMAT resource to set the amount and order ofinformation displayed. A PtDivider widget is automaticallyincluded in the file selector, along with a label for each column yourequest.

If you want to override the default headers, create a PtDivider ofyour own, add appropriate PtLabel widgets to it, and make thedivider a child of the file selector. The information you requested isdisplayed in the proper columns.

For example, if you create a PtDivider with the headings“Filename”, “File size”, and “Modification time” as a child of aPtFileSel widget and set the Pt ARG FS FORMAT to nsd, thePtFileSel items contain the name, size, and date information in theproper columns, but your divider is displayed.

By default, when you expand an item (directory) for the first time, thedirectory is read and items are allocated. After this, when youcollapse and expand the item, the information is stored in memory toremove the delay of reading a directory. You can refresh an item atany time by using the Pt ARG FS REFRESH resource. You can alsoset the Pt FS FREE ON COLLAPSE flag to cause a directory to bereread every time it’s expanded. Every time a new root directory isset, all the previous items are freed.

If you plan to add items to the PtFileSel widget yourself by usingthe PtFSAllocItem(), PtFSAddFirst(), and PtFSAddAfter()convenience functions, you should have a state callback(Pt CB FS STATE, subtype = Pt FS STATE START) that returnsPt END.



If you’re in tree mode and you get a state callback for one of youritems (i.e. not from a filesystem), you should deal with theexpansion/collapse and return Pt END from the callback to preventPtFileSel from trying to find the item in the filesystem.

If you’re in single-level mode and you get a state callback for one ofyour items, you should deal with the expansion; it’s yourresponsibility to free all the previous items. Return Pt END from thecallback as mentioned above.

�

Examples

In the examples below, Pt FS ALL FLAGS is a value containing all theflag bits. It’s used for a mask.

To display only directories, in tree mode:

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

Pt FS ALL FLAGS);PtSetArg(&args[1], Pt ARG FS ROOT DIR, "/", 0);PtSetArg(&args[2], Pt ARG AREA, area, 0);PtCreateWidget(PtFileSel, Pt DEFAULT PARENT, 3, args);...

To display only files in single-level mode, with keyboard seek on:

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

Pt FS SINGLE LEVEL|Pt FS SHOW FILES| \Pt FS KEY SEEK, Pt FS ALL FLAGS);

PtSetArg(&args[1], Pt ARG FS ROOT DIR, "/", 0);PtSetArg(&args[2], Pt ARG AREA, area, 0);PtCreateWidget(PtFileSel, Pt DEFAULT PARENT, 3, args);...

To display a single level of directories with a “..” item to move uplevels:


Pt FS SHOW DIRS|Pt FS SINGLE LEVEL,



Pt FS ALL FLAGS);PtSetArg(&args[1], Pt ARG FS ROOT DIR, "/", 0);PtSetArg(&args[2], Pt ARG AREA, area, 0);PtCreateWidget(PtFileSel, Pt DEFAULT PARENT, 3, args);...

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


Pt FS SHOW DIRS|Pt FS SHOW FILES,Pt FS ALL FLAGS);


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


Pt FS SHOW FILES|Pt FS SHOW HIDDEN,Pt FS ALL FLAGS);


You can show hidden files or directories by combining thePt FS SHOW HIDDEN flag with Pt FS SHOW DIRS orPt FS SHOW FILES.

The PtFileSel widget reads a filesystem, so there could be somedelays on large directories. To help you cope with these delays, thewidget does the following:

� The Pt CB FS STATE callback is invoked when an item isexpanded or collapsed. The expansion may take a long time if thedirectory is large, so the Pt CB FS STATE callback is actuallyinvoked twice, once at the start of the expansion/collapse (reason =Pt FS STATE START) and once at the end (reason =Pt FS STATE END). This lets you block the widget until the



expansion/collapse is done. The code below gives an example ofthis.

� The Pt CB FS BKGD HANDLER callback is invoked each time adirectory entry is read. You can use this callback to call somethinglike PtBkgdHandlerProcess(). By doing this, any pending Photonevents are handled and all the screen damage is fixed. Thisfunction should be small; if not, it will slow down the directoryreading even further.

Here’s a full PtFileSel example:

#include <stdio.h>#include <stdlib.h>#include <Pt.h>#include <photon/PtFileSel.h>

PtWidget t *window, *button, *fs;

/* Quit button callback */intquit( PtWidget t *widget, void *data,

PtCallbackInfo t *info){

PtExit(EXIT SUCCESS);return (Pt CONTINUE);

}

/* Open button callback */intfile open( PtWidget t *widget, void *data,


PtFileSelItem t *item;char buffer[PATH MAX+NAME MAX + 40];char *btns[] = { "&OK" };

item = PtFSGetCurrent(fs);if (item == NULL)

return(Pt CONTINUE);

strcpy(buffer, "The selected file is\n");strcat(buffer, item->fullpath);

PtAlert( window, NULL, "Selected File", NULL,buffer, NULL, 1, btns, NULL, 1, 1, Pt MODAL ) );



return (Pt CONTINUE);}

/* State callback, will use the reason to block thewidget for large directory opens. */

intstate cb( PtWidget t *widget,

struct fs dialog modal *user,PtCallbackInfo t *info)

{PtArg t args[3];PtFileSelCallback t *it;

it = (PtFileSelCallback t *)(info->cbdata);

if (it->reason == Pt FS STATE START){

PtSetArg(&args[0], Pt ARG FLAGS, Pt BLOCKED,Pt BLOCKED);

PtSetArg(&args[1], Pt ARG CURSOR TYPE,Ph CURSOR CLOCK, 0);

}else{

PtSetArg(&args[0], Pt ARG FLAGS, ˜Pt BLOCKED,Pt BLOCKED);

PtSetArg(&args[1], Pt ARG CURSOR TYPE,Ph CURSOR INHERIT, 0);

}PtSetResources(widget, 2, args);return (Pt CONTINUE);

}

/* Function to handle photon draw events and fixscreen damage */

inthandler cb(PtWidget t *widget,

struct fs dialog modal *user,PtCallbackInfo t *info)

{PtBkgdHandlerProcess();


int main(void){

PtArg t args[10];PtCallback t cb, cb2;PhDim t win dim = { 300, 300 };



PhArea t area;PtFileSelItem t *item;

if (PtInit(NULL) == -1)exit(EXIT FAILURE);

/* Make the main window. */PtSetArg( &args[0], Pt ARG WINDOW TITLE,

"PtFileSel Demo", 0 );PtSetArg( &args[1], Pt ARG DIM, &win dim, 0 );

if ((window = PtCreateWidget(PtWindow, Pt NO PARENT,2, args)) == NULL)

PtExit(EXIT FAILURE);

/* Make a file selector. */area.size.w = 200;area.size.h = 200;area.pos.x = 10;area.pos.y = 10;cb.event f = state cb;cb2.event f = handler cb;PtSetArg(&args[0], Pt ARG AREA, &area, 0 );PtSetArg(&args[1], Pt ARG FS FLAGS,

Pt FS SHOW DIRS|Pt FS SHOW FILES,Pt FS ALL FLAGS );

PtSetArg(&args[2], Pt ARG FS ROOT DIR, "/", 0);PtSetArg(&args[3], Pt CB FS STATE, &cb, 0);PtSetArg(&args[4], Pt CB FS BKGD HANDLER, &cb2, 0);fs = PtCreateWidget( PtFileSel, window, 5, args );

/* Make a button for quitting. */area.size.w = 60;area.size.h = 20;area.pos.x = 230;area.pos.y = 250;cb.event f = quit;PtSetArg( &args[0], Pt ARG AREA, &area, 0 );PtSetArg( &args[1], Pt ARG TEXT STRING, "Quit", 0);PtSetArg( &args[2], Pt CB ACTIVATE, &cb, 0);button = PtCreateWidget( PtButton, window, 3, args );

/* Make a open button. */area.size.w = 60;area.size.h = 20;area.pos.x = 160;area.pos.y = 250;cb.event f = file open;PtSetArg( &args[0], Pt ARG AREA, &area, 0 );PtSetArg( &args[1], Pt ARG TEXT STRING, "Open", 0);



PtSetArg( &args[2], Pt CB ACTIVATE, &cb, 0);PtCreateWidget( PtButton, window, 3, args );

PtRealizeWidget( window );

PtMainLoop();return (EXIT SUCCESS);

}

New resources:


Pt ARG FS FILE SPEC char * String "*"

Pt ARG FS FLAGS ulong t Flags Pt FS SHOW DIRS|Pt FS SHOW FILES

Pt ARG FS FORMAT char * String n

Pt ARG FS IMAGES PhImage t **, short Array PFM-styleimages(write-only)

Pt ARG FS LBL DATE char * String "Date"

Pt ARG FS LBL GROUP char * String "Group"

Pt ARG FS LBL NAME char * String "Name"

Pt ARG FS LBL OWNER char * String "Owner"

Pt ARG FS LBL PERMISSIONS char * String "Permissions"

Pt ARG FS LBL SIZE char * String "Size"

Pt ARG FS REFRESH PtFileSelItem t * Pointer NULL

Pt ARG FS ROOT DIR char * String NULL

continued. . .




Pt CB FS BKGD HANDLER PtCallback t * Link NULL

Pt CB FS SELECTION PtCallback t * Link NULL

Pt CB FS STATE PtCallback t * Link NULL

Pt ARG FS FILE SPEC


char * String "*"

A string that you can use to limit the files listed, by specifying apattern that the filenames must match. The default is *, but you canuse values such as *.c, *.[ch] and so on. You can specify multiplepatterns by separating them with a space or a comma (for example,*.gif, *.jpg).

Pt ARG FS FLAGS


ulong t Flags Pt FS SHOW DIRS | Pt FS SHOW FILES

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

Pt FS CASE INSENSITIVE

The file name’s filtering (according to the file spec ) iscase-insensitive.

Pt FS ERROR POPUP

Display an error dialog when the desired root directory isinvalid.

Pt FS FREE ON COLLAPSE

Free items on every collapse. This means that every time anitem expands, all its child items are reread from the disk.



Pt FS NO ROOT DISPLAY

Don’t show the root item.

Pt FS SEEK KEY

Keyboard seek mode, valid only for single-level mode. Typecharacters to seek an item.

Pt FS SHOW DIRS

Show directories.

Pt FS SHOW ERRORS

Show files that had a read error.

Pt FS SHOW FILES

Show files.

Pt FS SHOW HIDDEN

Show hidden files or directories. This flag must be combinedwith Pt FS SHOW FILES and/or Pt FS SHOW DIRS. A hiddenfile or directory is one whose name begins with a period (.).

Pt FS SINGLE LEVEL

Single-level mode, instead of tree mode. Directories andpossibly files are shown in one level with a .. item for movingup directory levels.

Pt ARG FS FORMAT


char * String n

A string that’s used to set the order and amount of file informationdisplayed and optionally the initial size (in pixels) of each columnshown. The following information can be displayed for each item inthe widget by including the corresponding letter in thePt ARG FS FORMAT string:



To display: Specify:

Name n

Size (in bytes) s

Size (in kbytes) k

Date d

Permissions p

Owner o

Group g

These letters must be in lower case.�

The s and k options are mutually exclusive. If you try to set both, thefirst one found in the string is used and the other is ignored. Themaximum number of characters is 6; any extra ones are ignored.

If you wish to display only the filename and no divider at the top, setthis resource to NULL. To set the size of the column, specify a numberof pixels before the corresponding letter. For example, if you want tohave the name (100 pixels wide) and the date (200 pixels wide)displayed, set the Pt ARG FS FORMAT resource as follows:

PtSetArg(&args[0], Pt ARG FS FORMAT, "100n200d", 0);

Pt ARG FS IMAGES (write-only)


PhImage t ** Array PFM-style images

A pointer to an array of image pointers (of type PhImage t — seethe Photon Library Reference) to be used for displaying items. The



following constants are used to index into this array (the order shownis the order the images appear in the array):

� Pt FS DIR OP — open directories

� Pt FS DIR CL — closed directories

� Pt FS DLINK OP — open directory links

� Pt FS DLINK CL — closed directory links

� Pt FS FILE — files

� Pt FS FLINK — file links

� Pt FS ERROR — errors

If you don’t want to change an image, specify NULL for that arrayelement. For example, to change the file image, set the Pt FS FILEentry of the array to the image pointer and set all others to NULL.

For example, to change the Pt FS DIR OP and Pt FS FILE images:

PhImage t *images[7];/* Fill the below image structures */...PhImage t new open image, new file image;...images[Pt FS DIR OP] = &new open image;images[Pt FS DIR CL] = NULL;images[Pt FS DLINK OP] = NULL;images[Pt FS DLINK CL] = NULL;images[Pt FS FILE] = &new file image;images[Pt FS FLINK] = NULL;images[Pt FS ERROR] = NULL;

PtSetArg(&args[0], Pt ARG FS IMAGES, images, 7);...

If you want to save processing time, set the length parameter toPtSetArg() to the index of the last image you changed + 1.



Set the flags member of the PhImage t structures to:


before providing the images to the widget. If you do this, the memoryused for the images is released when the widget is unrealized ordestroyed.

�

Pt ARG FS LBL DATE


char * String "Date"

The label used for the column that displays the files’ modificationdates.

Pt ARG FS LBL GROUP


char * String "Group"

The label used for the column that displays the group for the owner ofthe files.

Pt ARG FS LBL NAME


char * String "Name"

The label used for the column that displays the names of the files.



Pt ARG FS LBL OWNER


char * String "Owner"

The label used for the column that displays the owners of the files.

Pt ARG FS LBL PERMISSIONS


char * String "Permissions"

The label used for the column that displays the permissions for thefiles.

Pt ARG FS LBL SIZE


char * String "Size"

The label used for the column that displays the sizes of the files.

Pt ARG FS REFRESH


PtFileSelItem t * Pointer NULL

A pointer to the PtFileSelItem t structure for an expandable itemthat’s to be refreshed (i.e. reread from the disk). For example, if youhave a large directory displayed and someone adds a file, you maywish to refresh the directory item. To do this, set thePt ARG FS REFRESH resource to point to the root item for thatsubtree.



Pt ARG FS ROOT DIR


char * String NULL

The root directory for the file selector. The default value is NULL ornone.

The widget stores the actual path obtained via the realpath() function(see the QNX Neutrino Library Reference). For example, if you setthis resource to ///home//fred/.././fred/src, the widgetactually sets it to /home/fred/src or/fs/hd0-qnx4/home/fred/src (if home is a link to/fs/hd0-qnx4/home).

Setting Pt ARG FS ROOT DIR to NULL clears the PtFileSeldirectory tree, and setting it to "." loads the current workingdirectory.

Pt CB FS BKGD HANDLER



A list of PtCallback t structures that define the callbacks invokedeach time a directory item is read. For example, if you have 5 files ina directory and expand that directory, this callback is invoked 5 times.It’s useful for handling pending Photon events.


reason Pt CB FS BKGD HANDLER

reason subtype

One of:

� Pt FS NEW ITEM — a new item is being added to thewidget; see below.



� Pt FS OLD ITEM — the PtFileSel widget is doingintensive work and you may want to process events.


cbdata Used only for the Pt FS NEW ITEM subtype of thiscallback

For the Pt FS NEW ITEM reason subtype, cbdata points to a structureof type PtFileSelBkgdCallback t, which contains at least:

char name[] The name of the item being added to the widget.

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

Set the Pt CB FS BKGD HANDLER callback resource before thePt ARG FS ROOT DIR resource in order to translate all thefilenames.

�

Here’s an example of this callback:

inthandler cb( PtWidget t *widget, void *data,


PtArg t args[1];PtFileSelBkgdCallback t *it = (void *) info->cbdata;int srctaken = 0, dstmade = 0;char dst[NAME MAX * 3] = {""};

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

/* ctrl is a PxTransCtrl structure that was set with acall to PxTranslateSet(). The following will convertthe string and copy it back to the original: */



if (PxTranslateToUTF( ctrl, it->name, strlen( it->name),&srctaken, dst, 0, &dstmade) != -1)

strcpy(it->name, dst);

PtBkgdHandlerProcess();

return(Pt CONTINUE);}

Pt CB FS SELECTION



A list of PtCallback t structures that define the callbacks invokedwhen you select an item. Each callback is passed aPtCallbackInfo t structure that contains at least the followingmembers:

reason Pt CB FS SELECTION

reason subtype

Depending on the selection mode, this is one of:

� Pt LIST SELECTION FINAL

� Pt LIST SELECTION BROWSE

� Pt LIST SELECTION CANCEL


cbdata A pointer to a PtFileSelCallback t structure thatcontains:

� unsigned sel mode — the current selection mode:

- Pt BROWSE MODE

- Pt MULTIPLE MODE



- Pt EXTENDED MODE

- Pt SINGLE MODE

- Pt RANGE MODE

� PtFileSelItem t *item — a pointer to the itemthat has been selected

� unsigned nitems — the number of selected items,which depends on the selection mode

� short reason — not valid for this callback


Pt CB FS STATE



A list of PtCallback t structures that define the callbacks invokedwhen an item is expanded or collapsed. Each callback is passed aPtCallbackInfo t structure that contains at least the followingmembers:

reason Pt CB FS STATE

reason subtype

Pt TREE COLLAPSING or Pt TREE EXPANDING.


cbdata A pointer to a PtFileSelCallback t structure thatcontains:

� unsigned sel mode — the current selection mode:

- Pt BROWSE MODE

- Pt MULTIPLE MODE

- Pt EXTENDED MODE



- Pt SINGLE MODE

- Pt RANGE MODE

� PtFileSelItem t *item — if the reason member isPt FS STATE START, this is a pointer to the item beingcollapsed or expanded; if the reason member isPt FS STATE END, this is NULL.

If the Pt FS SINGLE LEVEL flag is set in the Pt ARG FS FLAGSresource, item is always NULL because all the previous items aredestroyed when you select a new directory in single-level mode.

�

� unsigned nitems — not valid for this callback

� short reason —

Pt FS STATE START

The callback is being called before the directoryis read (useful for blocking the widget whenreading a large directory).

Pt FS STATE END

The callback is being called after the directory isread (useful for unblocking the widget).







continued. . .





Pt ARG BALLOON COLOR PtGenList

Pt ARG BALLOON FILL COLOR PtGenList















Pt ARG DIM PtWidget






continued. . .












Pt ARG LIST DNDSEL COLOR PtGenList














Pt ARG POS PtWidget

continued. . .





Pt ARG SCROLLBAR WIDTH PtGenList


Pt ARG SELECTION MODE PtGenList







Pt ARG TREE FLAGS PtGenTree

Pt ARG TREE LINE COLOR PtGenTree

Pt ARG TREE LINE SPACING PtGenTree

Pt ARG TREE MARGIN COLOR PtGenTree


Pt ARG VISIBLE COUNT PtGenList



Pt CB ARM PtBasic

Pt CB BALLOONS PtContainer Not used by this class.




continued. . .





Pt CB DND PtWidget See below.


Pt CB GEN TREE INPUT PtGenTree





Pt CB MENU PtBasic


Pt CB RAW PtWidget






Pt CB DND

For Pt CB DND callbacks for a PtList, the cbinfo->cbdata is apointer to a PtTreeDndCallback t structure, containing at leastthe following members:

PtDndCallbackInfo t dnd info

See the description of Pt CB DND for PtWidget.

PtGenTreeItem t *item

A pointer to the PtGenTreeItem t structure forthe target item involved in the drag-and-drop



operation. You can cast this to be a pointer to aPtFileSelItem t.

int item pos The index of that item.

unsigned long flags

Possible values:

� Pt LIST ITEM DNDSELECTED UP — the dropoccurred above the item.

� Pt LIST ITEM DNDSELECTED DOWN — thedrop occurred below the item.

� Pt LIST ITEM DNDSELECTED IN — the dropoccurred inside the item.

int action This member is initially set toPt LIST ITEM DNDSELECTED UP |Pt LIST ITEM DNDSELECTED DOWN |Pt LIST ITEM DNDSELECTED IN. You can unsetsome of these values to indicate that thedrag-and-drop isn’t accepted in that case. Forexample, if you unsetPt LIST ITEM DNDSELECTED IN, thedrag-and-drop can’t occur inside the item, onlyabove or below.

Convenience functions:The PtFileSel widget defines the following convenience functionsthat make it easier to use the file selector once it’s been created:

PtFileSelection()

Create a file-selector dialog — see the PhotonLibrary Reference

PtFSAddAfter()

Insert an item after the specified item



PtFSAddFirst()

Add a root item to the widget

PtFSAllItems() Fill a buffer with pointers to all items

PtFSAllocItem()

Create an item for a file-selector widget

PtFSClearSelection()

Clear the selection

PtFSDamageItem()

Redraw an item

PtFSExpandParents()

Expand an item’s collapsed ancestors

PtFSFolderCollapse()

Collapse an expandable item (directory)

PtFSFolderExpand()

Expand an expandable item (directory)

PtFSFreeAllItems()

Unlink and frees all items

PtFSFreeItems()

Free an unlinked item

PtFSGetCurrent()

Get the current item (see “Current item” in thedescription of PtGenList)

PtFSGetSelIndexes()

Fill a buffer with indexes

PtFSGoto() Set the current item

PtFSItemIndex()

Calculate the index of the specified item



PtFSRemoveChildren()

Unlink all the children of a given item

PtFSRemoveItem()

Unlink an item

PtFSRemoveList()

Unlink the root item

PtFSRootItem()

Return the first root item of the file selector

PtFSSelect() Select the specified item

PtFSSelectedItems()

Fill a buffer with item pointers

PtFSSetSelIndexes()

Set the selection indexes

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

PtFSUnselect()

Unselect the specified item

PtFSUnselectNonBrothers()

Unselect all items that aren’t siblings of the specifieditem


PtFSAddAfter() 2004, QNX Software Systems Ltd.


Synopsis:void PtFSAddAfter( PtWidget t *fs,

PtFileSelItem t *item,PtFileSelItem t *brother );

Description:This function inserts a list of items linked with the brother field.PtFSAddAfter() assumes that item points to a list of items. The fsvariable points to a PtFileSel widget. The new items are added tothe specified file selector below the specified brother.

A

B 1

2

3

1

2

3

A

B

C

item tree

brother brother

item

tree

C

The results of using PtFSAddAfter().

You can call this function with a NULL fs argument, as long asbrother points to an item that isn’t attached to any file selector widget.


2004, QNX Software Systems Ltd. PtFSAddAfter()


Safety


Signal handler No

Thread No

See also:PtFSAddFirst()


PtFSAddFirst() 2004, QNX Software Systems Ltd.

Add a root item to a file selector tree

Synopsis:void PtFSAddFirst( PtWidget t *fs,

PtFileSelItem t *item,PtFileSelItem t *parent );

Description:This function adds a list of items linked with the brother field. Theparent argument identifies the parent item for the added items. Thenew items are added in front of any existing children of the parentitem.

The parent argument may also be NULL, in which case the item isadded at the root level of the file selector before any existing items atthe root level. This is what happens when the Pt ARG FS ROOT DIRresource is set.

A

B 1

2

3

1

2

A

B

item tree

parent parent

item

tree

3

The results of using PtFSAddFirst().

You can call this function with a NULL fs argument, as long as parentpoints to an item that isn’t attached to any file selector widget.


2004, QNX Software Systems Ltd. PtFSAddFirst()

PtFSAddFirst() automatically sets the Pt TREE ITEM EXPANDABLEflag in the parent item.


Safety


Signal handler No

Thread No

See also:PtFSAddAfter(), PtFSRootItem()


PtFSAllItems() 2004, QNX Software Systems Ltd.

Fill a buffer with pointers to all items

Synopsis:PtFileSelItem t **PtFSAllItems(

PtWidget t *widget,PtFileSelItem t **buffer );

Description:This function fills a buffer with pointers to all items in the widget. Ifbuffer is NULL, the function allocates a buffer using malloc(), andterminates it with a NULL entry. If buffer isn’t NULL, the functiondoesn’t add a NULL to the end of it.

Returns:A pointer to the buffer.


Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtFSAllocItem()Create an item for a PtFileSel widget

Synopsis:PtFileSelItem t * PtFSAllocItem(

PtFileSelWidget t *fs,int type,char const *info );

Description:You can use this function to create a PtFileSelItem t for thePtFileSel widget. It’s useful if your application can display itemsthat aren’t physically part of the filesystem. The parameters are asfollows:

type The type of item you’re creating:

� Pt FS DIR OP — open directory

� Pt FS DIR CL — closed directory

� Pt FS DLINK OP — open directory link

� Pt FS DLINK CL — closed directory link

� Pt FS FILE — file

� Pt FS FLINK — file link

� Pt FS ERROR — file with an error

This must contain a valid file type and is used to display theitem’s image.

info The string that’s displayed in the tree for the item. It shouldcontain all the information required, such as name, size, anddate. The information should be separated by tabs and in thesame order as the format string. For example, if your formatis "nso" (name, size, owner), you should pass somethinglike "bob\t100\towner" as info.

An item pointer is returned. If you wish to store any information inthe item, use the item->fullpath character pointer. It’s used in mostitems to store the full path of the item, but this function initializes it toNULL.


PtFSAllocItem() 2004, QNX Software Systems Ltd.

Returns:The allocated item pointer if successful, or NULL if an error occurred.

Examples:Suppose you wish to add your own item. In the state callback, youcan check the item’s fullpath to see if it’s the one you want to dealwith and if so, add your own items afterwards. Just return Pt ENDfrom the Pt FS STATE START callback to prevent the widget fromdoing the expansion.

/* State callback. Use the reason to block the widget forlarge directory opens. */

int state cb( PtWidget t *widget,struct fs dialog modal *user,PtCallbackInfo t *info)

{PtArg t args[3];PtFileSelCallback t *it;PtFileSelItem t *new item;

it = (PtFileSelCallback t *)(info->cbdata);

if (it->reason == Pt FS STATE START) {PtSetArg(&args[0], Pt ARG FLAGS, Pt BLOCKED,

Pt BLOCKED);PtSetArg(&args[1], Pt ARG CURSOR TYPE,

Ph CURSOR CLOCK, 0);

if ((strcmp(it->item->fullpath, "/Gamma") == 0) &&(info->reason subtype == Pt TREE EXPANDING)) {it->item->type = Pt FS DIR OP;PtFSDamageItem(fs, it->item);new item = PtFSAllocItem(fs, Pt FS FILE,

"Fred Flintstone");PtFSAddFirst(fs, new item, it->item);return (Pt END);

}} else {

PtSetArg(&args[0], Pt ARG FLAGS, ˜Pt BLOCKED,Pt BLOCKED);

PtSetArg(&args[1], Pt ARG CURSOR TYPE,Ph CURSOR INHERIT, 0);

}PtSetResources(widget, 2, args);return (Pt CONTINUE);

}


2004, QNX Software Systems Ltd. PtFSAllocItem()


Safety


Signal handler No

Thread No


PtFSClearSelection() 2004, QNX Software Systems Ltd.

Clear the selection

Synopsis:void PtFSClearSelection( PtWidget t *widget );

Description:This function clears the selection.


Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtFSDamageItem()Redraw an item in the file selector

Synopsis:void PtFSDamageItem( PtWidget t *fs,

PtFileSelItem t *item );

Description:Call this function to redraw an item when its data has changed.


Safety


Signal handler No

Thread No


PtFSExpandParents() 2004, QNX Software Systems Ltd.

Expand an item’s collapsed ancestors

Synopsis:void PtFSExpandParents( PtWidget t *fs,

PtFileSelItem t *item,PhEvent t *event );

Description:This function tries to expand any collapsed ancestors of the givenitem. The event is passed to PtFSFolderExpand().


Safety


Signal handler No

Thread No

See also:PhEvent t in the Photon Library Reference


2004, QNX Software Systems Ltd. PtFSFolderCollapse()Collapse an expandable item (directory)

Synopsis:void PtFSFolderCollapse( PtWidget t *fs,


Description:This function collapses the given item. The item must be expandable,i.e. a directory item. The fs argument must point to the file selectorthat contains the item or be NULL if the item doesn’t belong to anyfile selector.

If fs isn’t NULL, its Pt CB FS STATE callback is invoked. The eventargument is passed to the callback.


Safety


Signal handler No

Thread No



PtFSFolderExpand() 2004, QNX Software Systems Ltd.

Expand an expandable item (directory)

Synopsis:int PtFSFolderExpand( PtWidget t *fs,


Description:This function expands the given item. The fs argument must point tothe file selector that contains the item or be NULL if the item doesn’tbelong to any file selector.

If fs isn’t NULL, its Pt CB FS STATE callback is invoked. The eventargument is to the callback. If the item isn’t expanded, the returnvalue reflects that.

Returns:0 Success.

Pt END The item couldn’t be expanded.


Safety


Signal handler No

Thread No



2004, QNX Software Systems Ltd. PtFSFreeAllItems()Unlink and free all items

Synopsis:void PtFSFreeAllItems( PtWidget t const *fs );

Description:This function unlinks and frees all items in the PtFileSel widget.Note that this function is called automatically when a PtFileSelwidget is destroyed.


Safety


Signal handler No

Thread No


PtFSFreeItems() 2004, QNX Software Systems Ltd.


Synopsis:void PtFSFreeItems( PtFileSelItem t *item );

Description:This function frees the subtree item (the item together with itsbrothers and their children). The function assumes that the itemsdon’t belong to any file selector — use PtFSRemoveChildren(),PtFSRemoveItem(), or PtFSRemoveList() to remove the subtree itemsfrom a file selector widget before freeing the subtree.


Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtFSGetCurrent()Get the current item

Synopsis:PtFileSelItem t *PtFSGetCurrent(

PtWidget t const *widget );

Description:This function returns a pointer to the current item (see “Current item”in the description of PtGenList).


Safety


Signal handler No

Thread No


PtFSGetSelIndexes() 2004, QNX Software Systems Ltd.


Synopsis:unsigned short *PtFSGetSelIndexes(

PtWidget t *widget,unsigned short *buffer );

Description:This function fills a buffer with indexes of all the selected items in thePtFileSel widget. The first item in the widget has an index of 1, not0.

If buffer is NULL, the function allocates a buffer using malloc(), andthe buffer is zero-terminated.

If buffer is non-NULL, the function adds zero to the end only if thereare no selected items in the widget.



Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtFSGoto()Set the current item

Synopsis:void PtFSGoto( PtWidget t *fs,


Description:This function sets the current item and (if necessary) the currentposition so that the new current item is visible (see “Current item” inthe description of PtGenList).

If item is NULL, there will be no current item.


Safety


Signal handler No

Thread No


PtFSItemIndex() 2004, QNX Software Systems Ltd.

Calculate the index of the given item within the file selector

Synopsis:int PtFSItemIndex( PtFileSelWidget t const *fs,

PtFileSelItem t const *item );

Description:This function calculates the index of the given item within the fs. Theindex of the first item is 1.

Returns:The index of the given item.


Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtFSRemoveChildren()Unlink the children of the specified item

Synopsis:PtFileSelItem t *PtFSRemoveChildren(


Description:This function unlinks all the children of the specified item and returnsthe pointer to the first of them. You can then give the pointer to thePtFSFreeItems() function.

B

CAA

D

B

C

returned pointertree

item

tree

D

The results of using PtFSRemoveChildren().

This function doesn’t collapse the item. If the children are visible,NULL is returned. Call PtFSFolderCollapse() beforePtFSRemoveItem() to make sure that the item is collapsed.

Returns:A pointer to the first child removed.


PtFSRemoveChildren() 2004, QNX Software Systems Ltd.


Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtFSRemoveItem()Unlink an item

Synopsis:void PtFSRemoveItem( PtWidget t *fs,


Description:This function unlinks the given item together with its children from itsparent and brothers (if any) and sets the item->parent anditem->brother fields to NULL.

B

C

C

B

itemtree

item

tree

A A

The results of using PtFSRemoveItem().

The fs argument must point to the PtFileSel widget containing theitem, or be NULL if the item doesn’t belong to any file selector.

If fs is NULL and the item has no parent but has a previous brother,the function won’t be able to find the previous brother and thereforecan’t unlink the item from its brother. The function does nothing ifitem->parent and fs are both NULL.

PtFSRemoveItem() never clears the Pt TREE ITEM EXPANDABLEflag in the item’s parent.

�


PtFSRemoveItem() 2004, QNX Software Systems Ltd.


Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtFSRemoveList()Unlink the root item

Synopsis:void PtFSRemoveList( PtWidget t *fs,

PtFileSelItem t *first );

Description:This function unlinks the item first and its brothers (together withtheir children) from their parent (and previous brother) and sets theirparent fields to NULL.

B

C

C

B

firsttree

first

tree

A A

The results of using PtFSRemoveList().

The fs argument must point to the PtFileSel widget that containsthe items, or be NULL if the items don’t belong to any file selector.

If fs is NULL and first has no parent but has a previous brother, thefunction won’t be able to find the previous brother and therefore can’tunlink first from its previous brother.

�



PtFSRemoveList() 2004, QNX Software Systems Ltd.

Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtFSRootItem()Return the first root item of the file selector

Synopsis:PtFileSelItem t *PtFSRootItem(

PtFileSelWidget t const *fs );

Description:This function returns a pointer to the first root item.

Returns:A pointer to the first root item.


Safety


Signal handler No

Thread No


PtFSSelect() 2004, QNX Software Systems Ltd.

Select the specified item

Synopsis:void PtFSSelect( PtWidget t *widget,


Description:This function selects the given item.


Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtFSSelectedItems()Fill a buffer with pointers to the selected items

Synopsis:PtFileSelItem t **PtFSSelectedItems(

PtWidget t *widget,PtFileSelItem t **buffer );

Description:This function fills a buffer with pointers to the currently selecteditems:

� If buffer is NULL, the function allocates a buffer using malloc(),and the buffer is NULL-terminated.

� If buffer is non-NULL, the function adds a NULL at the end only ifthere are no selected items in the widget.



Safety


Signal handler No

Thread No


PtFSSetSelIndexes() 2004, QNX Software Systems Ltd.


Synopsis:int PtFSSetSelIndexes( PtWidget t *widget,

const unsigned short *buffer,int count );

Description:This function sets the selection indexes. The function assumes thatbuffer points to a sorted array of indexes. The first item in the widgethas an index of 1, not 0.

The function returns the number of items that have been actuallyselected, which may be smaller than count if the array isn’t sorted orcontains duplicate indexes or indexes that are out of range.

If the selection mode is Pt RANGE MODE, only the first index and thecount are used.

�

Returns:The number of items selected.


Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtFSShow()Set the position so that the specified item is visible

Synopsis:void PtFSShow( PtWidget t *widget,


Description:This function sets the current position so that the given item is visible.If item is NULL, the function does nothing. This lets you dosomething like this:

PtFSShow( widget, PtFSGetCurrent(widget) );

without checking to see if PtFSGetCurrent() returned NULL.


Safety


Signal handler No

Thread No


PtFSUnselect() 2004, QNX Software Systems Ltd.

Unselect the given item

Synopsis:void PtFSUnselect( PtWidget t *widget,


Description:This function unselects the given item.

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


Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtFSUnselectNonBrothers()Unselect all items that aren’t siblings of the specified item

Synopsis:void PtFSUnselectNonBrothers(

PtWidget t *widget,PtFileSelItem t *item );

Description:This function unselects all the items that aren’t siblings of the givenitem. If item is NULL, the current item (see “Current item” in thedescription of PtGenList) is used.


Safety


Signal handler No

Thread No


PtFlash 2004, QNX Software Systems Ltd.

A container that displays Macromedia Flash 4 animation

Class hierarchy:PtWidget → PtBasic → PtContainer → PtFlash

PhAB icon:

Public header:<photon/PtFlash.h>

Description:PtFlash is a container widget that displays Macromedia Flash 4animation.

New resources:


Pt ARG FLASH FILE char * String NULL

Pt ARG FLASH FILE


char * String NULL

The full path or URL of the Shockwave Flash file (extension .swf or.SWF) to display. The file starts to play as soon as you set thisresource.


2004, QNX Software Systems Ltd. PtFlash




















Pt ARG DIM PtWidget


continued. . .


PtFlash 2004, QNX Software Systems Ltd.





Pt ARG FLAGS PtWidget Pt GETS FOCUS













Pt ARG POS PtWidget







continued. . .


2004, QNX Software Systems Ltd. PtFlash




Pt CB ARM PtBasic






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






PtFontSel 2004, QNX Software Systems Ltd.

A widget for selecting font attributes

Class hierarchy:PtWidget → PtBasic → PtContainer → PtFontSel

PhAB icon:

Public header:<photon/PtFontSel.h>

Description:The PtFontSel widget lets you select font attributes.


2004, QNX Software Systems Ltd. PtFontSel

A PtFontSel widget.

A PtFontSel widget lets you select the:

� font family

� style (italic, bold, underline, double underline, and case)

� font size

� text and background color

The PtFontSel shows sample text that reflects the current fontformat choices.



New resources:


Pt ARG FONT DISPLAY unsigned Flag Pt FONTSEL ALL FONTS

Pt ARG FONT FLAGS unsigned Flag Pt FONTSEL SAMPLE

|

Pt FONTSEL AA CHECK

Pt ARG FONT LBL BKGDCOLOR char * String "Bkgd:"

Pt ARG FONT LBL FONT char * String "Font:"

Pt ARG FONT LBL SIZE char * String "Size:"

Pt ARG FONT LBL STYLE char * String "Style:"

Pt ARG FONT LBL TEXTCOLOR char * String "Text:"

Pt ARG FONT NAME char * String "TextFont09"

Pt ARG FONT POINT SIZE MAX long Scalar 9999

Pt ARG FONT SAMPLE char * String "AaBbCcXxYyZz"

Pt ARG FONT SYMBOL long Scalar ’A’

Pt ARG FONT TEXT COLOR PgColor t Scalar Pg BLACK

Pt ARG FONT TEXT BKGD COLOR PgColor t Scalar Pg WHITE

Pt CB FONT MODIFY PtCallback t * Link NULL

Pt ARG FONT DISPLAY


unsigned Flag Pt FONTSEL ALL FONTS

Flags to filter the inclusion of font families in the selection dialog (seePtFontSelection() in the Photon Library Reference). You can ORthese flags together:



� Pt FONTSEL SCALABLE — Include scalable fonts.

� Pt FONTSEL BITMAP — Include bitmap fonts.

� Pt FONTSEL FIXED — Include fixed-width fonts.

� Pt FONTSEL PROP — Include proportional-width fonts.

You can use Pt FONTSEL ALL FONTS to override this filtering.

Pt ARG FONT FLAGS


unsigned Flag Pt FONTSEL SAMPLE |Pt FONTSEL AA CHECK

Flags to modify the appearance of the widget:

� Pt FONTSEL SAMPLE — show a sample text string in the currentfont.

� Pt FONTSEL AA CHECK — allow the use of the anti-aliasing(A/A) button only for scalable fonts. For normal bitmap fonts, thisbutton is dimmed. However, external font mapping rules maysupplement bitmap fonts with scalable fonts at certain point sizes,allowing this attribute to be applied.

� Pt FONTSEL COLORSEL BKGD — display a sample of thebackground color to be used for the text. If you click on thesample, you can change the color.

� Pt FONTSEL COLORSEL TEXT — display a sample of the color tobe used for the text. If you click on the sample, you can change thecolor.

Pt ARG FONT LBL BKGDCOLOR




char * String "Bkgd:"

The label for the background color.

Pt ARG FONT LBL FONT


char * String "Font:"

The label beside the combo box for choosing the font.

Pt ARG FONT LBL SIZE


char * String "Size:"

The label used beside the font-size field.

Pt ARG FONT LBL STYLE


char * String "Style:"

The label used beside the Style combo box.

Pt ARG FONT LBL TEXTCOLOR


char * String "Text:"

The label for the text color.



Pt ARG FONT NAME



The name of the initial font. This resource also reflects the currentlyselected font, style, quality, and size.

Pt ARG FONT POINT SIZE MAX


long Scalar 9999

The maximum point size the font selector allows, with a maximum of9999. If this resource is set to a size that is smaller than the currentfont size, the current size is set to the new maximum.

Pt ARG FONT SAMPLE


char * String "AaBbCcXxYyZz"

The string to be used as a sample display of the font (if thePt FONTSEL SAMPLE flag is set).

Pt ARG FONT SYMBOL


long Scalar ’A’

A character used to filter the inclusion of font families in the selectiondialog. Only those fonts that define this character are included.

You can use this resource to display only Latin fonts (set it to ’A’) orCyrillic fonts (set it to Pk Cyrillic IO). You can use the valuePt FONTSEL ALL SYMBOLS to override this filtering.



Pt ARG FONT TEXT COLOR



The color of the text. See PgColor t in the Photon LibraryReference.

Pt ARG FONT TEXT BKGD COLOR



The background color of the text. See PgColor t in the PhotonLibrary Reference.

Pt CB FONT MODIFY



A list of PtCallback t structures that define the callbacks invokedwhen the selected font is modified.

If the widget has the Pt CALLBACKS ACTIVE bit set in itsPt ARG FLAGS resource, these callbacks are also invoked when yourapplication changes the selected font by calling PtSetResource() orPtSetResources().


reason Pt CB FONT MODIFY


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
















Pt ARG CONTAINER FLAGS PtContainer &=˜Pt GETS FOCUS








continued. . .




Pt ARG DIM PtWidget





Pt ARG FLAGS PtWidget 0













Pt ARG POS PtWidget





continued. . .








Pt CB ARM PtBasic






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget







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

PtFontSelection()

Display a modal dialog for selecting a font. See the PhotonLibrary Reference.


2004, QNX Software Systems Ltd. PtGaugeCommon resources for gauge-type widgets

Class hierarchy:PtWidget → PtBasic → PtGauge


� PtMeter

� PtProgress

� PtScrollBar

� PtSlider


Public header:<photon/PtGauge.h>

Description:The PtGauge superclass provides common resources for gauge-likewidgets, which are capable of displaying a range of values.

New resources:


Pt ARG GAUGE FLAGS short int Flag 0

Pt ARG GAUGE FONT char * String "TextFont09"

Pt ARG GAUGE H ALIGN unsigned char Scalar Pt CENTER

Pt ARG GAUGE V ALIGN unsigned char Scalar Pt CENTER

Pt ARG GAUGE VALUE long Scalar 0

continued. . .


PtGauge 2004, QNX Software Systems Ltd.


Pt ARG GAUGE VALUE PREFIX char * String NULL

Pt ARG GAUGE VALUE SUFFIX char * String NULL

Pt ARG MAXIMUM long Scalar 100

Pt ARG MINIMUM long Scalar 0

Pt ARG ORIENTATION char Scalar Pt HORIZONTAL

Pt CB GAUGE VALUE CHANGED PtCallback t * Link NULL

Pt ARG GAUGE FLAGS


short int Flag 0

Flags that affect the appearance and behavior of the gauge. Possiblevalues:

Pt GAUGE INDETERMINATE

The current value is “unknown.”

Any subclass of PtGauge may observe this bit, but the onlywidget that currently does is PtProgress.

Pt GAUGE INTERACTIVE

Let the user change the value of the gauge interactively atruntime (e.g. by dragging). When the value is changed in thismanner, the widget’s Pt CB GAUGE VALUE CHANGEDcallbacks are invoked.


Pt GAUGE LIVE

Alter the widget’s appearance as time passes to indicate thatalthough the value may not be changing, the application is stillworking.


2004, QNX Software Systems Ltd. PtGauge


Pt GAUGE MAX ON TOPPt GAUGE MAX ON LEFT

The position of the maximum value.

Pt GAUGE SHOW VALUE

Display the value of the gauge.

Pt GAUGE VALUE XOR

XOR the value display with the background (i.e. invert the fillof the typeface).

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

Pt ARG GAUGE FONT



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

Pt ARG GAUGE H ALIGN


unsigned char Scalar Pt CENTER

Controls horizontal alignment. Possible values are:

Pt LEFT Draw the value aligned to the left edge.

Pt RIGHT Draw the value aligned to the right edge.

Pt CENTER Draw the value centered.



Pt ARG GAUGE V ALIGN



Controls vertical alignment. Possible values are:

Pt TOP Draw the value aligned with the top edge.

Pt BOTTOM Draw the value aligned with the bottom edge.

Pt CENTER Draw the value centered.

Pt ARG GAUGE VALUE


long Scalar 0

The gauge’s current value.

Pt ARG GAUGE VALUE PREFIX


char * String NULL

Text prefixed to the value displayed. For example, a value of Red:results in Red:35.

Pt ARG GAUGE VALUE SUFFIX


char * String NULL

Text appended to the value displayed. For example, a value of %results in 35%.



Pt ARG MAXIMUM


long Scalar 100

The maximum value of the gauge.

Pt ARG MINIMUM


long Scalar 0

The minimum value of the gauge.

Pt ARG ORIENTATION


char Scalar Pt HORIZONTAL

The orientation of the gauge; one of:

� Pt HORIZONTAL

� Pt VERTICAL

Pt CB GAUGE VALUE CHANGED



A list of PtCallback t structures that define the callbacks that areinvoked when the user changes the value of an interactive gauge (i.e.one that has the Pt GAUGE INTERACTIVE bit set in itsPt ARG GAUGE FLAGS).

If the widget has the Pt CALLBACKS ACTIVE bit set in itsPt ARG FLAGS resource, these callbacks are also invoked when your



application changes the value by calling PtSetResource() orPtSetResources().


reason Pt CB GAUGE VALUE CHANGED

reason subtype

One of the following:

� Pt GAUGE DECREMENT, Pt GAUGE INCREMENT —the value decreased or increased by a single unit. Themeaning of a “unit” may be specific to the widget (forexample, Pt ARG INCREMENT) but in the absence ofsuch a binding should be understood to mean 1.

� Pt GAUGE MULTIPLE INCREMENT,Pt GAUGE MULTIPLE DECREMENT — the valuedecreased or increased by a multiple unit. A multipleunit definition is optional (for example,Pt ARG PAGE INCREMENT) and if the widgetdoesn’t define it, callbacks with this subtype don’toccur.

� Pt GAUGE TO MAX, Pt GAUGE TO MIN — the valuehas gone to the maximum or minimum value of thegauge.

� Pt GAUGE DRAGGED — the valued changed becauseof a drag operation. (In the case of low-bandwidthrestrictions, you can disregard callbacks of thissubtype)

� Pt GAUGE RELEASED — signals the end of a drag(good for low-bandwidth restrictions). Since the valueis the same as the last callback of subtypePt GAUGE DRAGGED, you don’t need to handle thissubtype if you’re paying attention to thePt GAUGE DRAGGED subtypes.



� Pt GAUGE JUMP — the gauge has jumped to a newvalue (i.e. none of the criteria for the other subtypeshas been met).

event A pointer to a PhEvent t structure that describes theevent that caused the callback to be invoked, or NULL ifthe callback was invoked because your applicationchanged the value and Pt CALLBACKS ACTIVE is set.

cbdata A pointer to a PtGaugeCallback t structure, whichcontains at least:

� long value — the new value for the gauge.













continued. . .











Pt ARG DIM PtWidget
















continued. . .






Pt ARG POS PtWidget







Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget


continued. . .


2004, QNX Software Systems Ltd. PtGenListGeneric superclass for list and tree widgets

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


� PtGenTree

� PtList

� PtRawList


Public header:<photon/PtGenList.h>

Description:The PtGenList class is a superclass for creating list widgets. It’sdiscussed in more detail in Building Custom Widgets.

PtGenList handles a vertical, left-aligned list of rectangular itemsthat may have different sizes. You can select one or more items,depending on the selection policy (see Pt ARG SELECTION MODE).

PtGenListItem t is the data structure used for the items.

A PtGenList widget can have one child, provided it’s a PtDividerwidget. In this case, PtGenList attaches a callback to the child sothat the columns are set automatically to match the children ofPtDivider; the items are drawn below the divider. Some childclasses of PtGenList, such as PtList and PtTree, use Tabcharacters as column separators.


PtGenList 2004, QNX Software Systems Ltd.

Using scrollbars

PtGenList creates a scrollbar if the list’s area isn’t large enough todisplay all the items in the list. By default, the scrollbar is displayedonly when necessary. You can control this behavior by setting thePt LIST SCROLLBAR ALWAYS or (the default)Pt LIST SCROLLBAR AS REQUIRED bits in Pt ARG LIST FLAGS.

You can set or get a limited number of resources (mainly the colors)for the child PtScrollbar widget by using the list’sPt ARG LIST SB RES resource.

Current item

Most of the time, one of the items in a list widget is the current item.(On rare occasions, a list can have no current item but it can’t havemore than one.)

The concept of the current item is similar to the concept of widgetfocus; typically, the current item is drawn with a blue dotted linearound it when its widget has focus. When you press Enter or Space,it’s the current item that gets selected; depending on the widget’sselection mode, this may also unselect any previously selected itemsand/or unselect the current item if it was already selected. For moreinformation, see the description of Pt ARG SELECTION MODE.

Cursor keys change the current item, scroll the list if necessary tomake the new current item visible, and, depending on the widget’sselection mode, may also select and unselect items. For instance,pressing the ↓ key makes the next item the current item, and mayselect the new current item and unselect any previously selecteditems. Clicking on an item also makes it the current item and alsomay select or unselect items.

Holding down the Ctrl key when you click or press cursor keys willprevent any changes to the selection if you just want to walk the listwithout changing the selection.


2004, QNX Software Systems Ltd. PtGenList

Mouse actions

Mouse actions depend on the current selection mode.

Button action Result

Press Result depends on the value ofPt ARG SELECTION MODE

Release Invokes callbacks.

Keyboard actions

Keyboard actions depend on the current selection mode.

Key Action

Enter Result depends on value of Pt ARG SELECTION MODE

↑ Previous item

↓ Next item

Pg Up Previous page

Pg Dn Next page

Home First item

End Last item

New resources:


Pt ARG BALLOON COLOR PgColor t Scalar Pg BLACK

continued. . .




Pt ARG BALLOON FILL COLOR PgColor t Scalar See below

Pt ARG LIST COLUMN ATTR See below Array NULL

Pt ARG LIST COLUMN POS PtListColumn t *,short

Array NULL

Pt ARG LIST DNDSEL COLOR PgColor t Scalar PgRGB(216, 216,216)

Pt ARG LIST FLAGS unsigned short Flag See below

Pt ARG LIST FONT char * String "TextFont09"

Pt ARG LIST ITEM COUNT unsigned short Scalar 0 (read-only)

Pt ARG LIST SB RES PtArg t, int Array None

Pt ARG LIST SCROLL RATE unsigned char Scalar 2

Pt ARG LIST SEL COUNT unsigned short Scalar 0 (read-only)

Pt ARG LIST TOTAL HEIGHT unsigned Scalar 0 (read-only)

Pt ARG SCROLLBAR WIDTH unsigned short Scalar 0 (see below)

Pt ARG SELECTION FILL COLOR PgColor t Scalar PgRGB(142, 162,155)

Pt ARG SELECTION MODE unsigned short Scalar See below

Pt ARG SELECTION TEXT COLOR PgColor t Scalar Pg WHITE

Pt ARG TOP ITEM POS unsigned short Scalar 1

Pt ARG VISIBLE COUNT unsigned short Scalar 0 (read-only)

Pt CB SCROLL MOVE PtCallback t * Link NULL

Pt ARG BALLOON COLOR





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

Pt ARG BALLOON FILL COLOR


PgColor t Scalar Pg BALLOONCOLOR

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

Pt ARG LIST COLUMN ATTR


PtListColumnAttributes t *, short Array NULL

An array of PtListColumnAttributes t structures, eachcontaining at least the following:

short flags; Flags that define the alignment of the text and otherbehavior:

� Pt LIST COLUMN ELLIPSIS — If the textdoesn’t fit into the column, draw an ellipsis (...)instead of part of the text, in accordance with thecolumn’s alignment. For example, if the columnis left-aligned, draw the ellipsis instead of theend of the text; if the column is right-aligned,draw the ellipsis instead of the beginning.

� Pt LIST COLUMN ELLIPSIS MIDDLE — Drawthe ellipsis in the middle of the string. You mustalso set Pt LIST COLUMN ELLIPSIS.



� Pt LIST COLUMN ELLIPSIS INVERT Invert theellipsis position. You must also setPt LIST COLUMN ELLIPSIS.

� Pt LIST COLUMN LEFT

� Pt LIST COLUMN RIGHT

� Pt LIST COLUMN CENTER

� Pt LIST COLUMN DAMAGE ALWAYS — redrawthe column when the column’s position or sizechanges, even if it doesn’t seem necessary.

For example, if a right-aligned column is madenarrower but its right edge doesn’t move, there’sno need to redraw the column. You can set theflag to force a redraw, which needs to be done ifthe column contains some elements that aren’tright-aligned. This flag is usually set by the childclass of PtGenList that knows what’s drawn inthe columns.

� Pt LIST COLUMN NO STRING — if set,PtGenListDrawString() skips over this column.

Pt ARG LIST COLUMN POS


PtListColumn t *, short Array NULL

An array of PtListColumn t column structures. The structurecontains at least the following:

short from, to;

They define the positions of the left and right edges of thecolumn (relative to the left edge of widget’s canvas).



Pt ARG LIST DNDSEL COLOR


PgColor t Scalar PgRGB(216, 216, 216)

The selection color in a drag-and-drop operation. See PgColor t inthe Photon Library Reference.

Pt ARG LIST FLAGS


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

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

Pt LIST BALLOON AS REQUIRED

Show a balloon if the contents of the list areclipped.

Pt LIST BALLOONS IN COLUMNS (on by default)Display balloons for individual columns, not theentire row.

Pt LIST BOUNDARY KEY EVENTS

If this flag is clear (the default), cursor key events(↑, ↓, Pg Up, Pg Down, Home, and End) arealways consumed by the widget.

If this flag is set, a cursor key event is consumedonly if it actually changes the current item. Forexample, an ↑ or Home event isn’t consumed if thefirst item in the list is already the current item.



Pt LIST HEADER AUTORESIZE

Adjust the width of the PtDivider widget (ifthere is one) when the scrollbar is realized orunrealized.

Pt LIST NO COLUMN LINES

Don’t display the lines that separate the columnsin the list.

Pt LIST NOBLIT Don’t blit when Pt ARG TOP ITEM POS ischanged.

Pt LIST NON SELECT

Make the list read-only.

Pt LIST SCROLLBAR ALWAYS

Always display a scrollbar.

Pt LIST SCROLLBAR AS REQUIRED (on by default)Display a scrollbar only if required.

Pt LIST SCROLLBAR AUTORESIZE

Resize the scrollbar automatically when the size ofthe header changes.

Pt LIST SCROLLBAR GETS FOCUS

Let the scrollbar get focus.

Pt LIST SHOW BALLOON

Show list balloons.

Pt LIST SNAP Make the list snap to fit the number of items. Notethat the Pt LIST SNAP flag is cleared automaticallyif the items in the list don’t have equal heights.



Pt ARG LIST FONT



The font used for the items in the list.

Pt ARG LIST ITEM COUNT (read-only)



The number of items.

Pt ARG LIST SB RES


PtArg t Array None

An array of PtArg t structures (see the Photon Library Reference)that are passed to the list’s child PtScrollbar. Note that you canmodify only a selected set of the scrollbar’s resources:

Scrollbar resource Inherited from






Pt ARG MIN SLIDER SIZE PtScrollbar

continued. . .



Scrollbar resource Inherited from




The PtGenList widget doesn’t let you modify resources that mightaffect the position or size of the scrollbar. The main purpose of thisresource is to change the colors of the scrollbar.

To get the Pt ARG LIST SB RES resource, your application mustsupply a buffer and pass its address and length to the PtSetArg()macro. For example, this code for a PtScrollbar widget:

PtGetResources( scrollbar, N, args );

is equivalent to this when the scrollbar is part of a PtGenList:

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

Pt ARG LIST SCROLL RATE


unsigned char Scalar 2

If you drag in a list and move outside the widget, the list scrolls at arate determined by the number of “button repeats”. This resourcespecifies the number of button repeats that must be received beforescrolling occurs. The default value is 2. To make the scrolling faster,set this resource to 1; to make scrolling slower, set this resource to alarger number.



Pt ARG LIST SEL COUNT (read-only)



The number of selected items.

Pt ARG LIST TOTAL HEIGHT (read-only)


unsigned Scalar 0

The total height (in pixels) of all items.

Pt ARG SCROLLBAR WIDTH


unsigned short Scalar 0 (see below)

The width of the accompanying scrollbar, if displayed. The minimumwidth is 6 pixels. If you set this resource to 0, the default width of 15is used.

Pt ARG SELECTION FILL COLOR


PgColor t Scalar PgRGB(142, 162, 155)

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

Pt ARG SELECTION MODE




unsigned short Scalar See below

The selection mode. PtGenList lets you select items using themouse or the keyboard. The descriptions below assume you’re using amouse. If a mouse isn’t available, you can use the ↑ and ↓ keys on thenumeric keypad to highlight items in a list. The widget accepts thecurrent selection when you press Enter.

Pt BROWSE MODE (default)

To select an item using the mouse, either click on an item ordrag the pointer down the list and release the mouse buttonwhen the correct item is highlighted. You can select only oneitem. If you drag the mouse, the list can scroll.

Pt MULTIPLE MODE

To select multiple items using the mouse, click on more thanone item. When you click on a selected item, the item becomesunselected.

Pt EXTENDED MODE

Support click-Shift-click/drag and Ctrl-click combinations toselect multiple items. To select all items between and includingtwo items in a list, click on the first item, press the Shift key,then click on or drag to any other item in the list.

To select multiple disjoint items, hold down the Ctrl whileclicking on selected items.

Pt SINGLE MODE

To select an item, point to the item, then click the mouse button.You can select only one item; if you select a second one, thefirst becomes unselected.

Pt RANGE MODE

To select a range of items, point to the first item, drag to the lastitem in the range, then release the mouse button. When you’redragging the mouse, the list can scroll.



The PtGenList widget supports several “predefined” selectionmodes, but you can also set “compose selection modes” using specialflag values. To define a compose mode, start with one of the followingvalues, which describe what kind of sets of items can be selected:

Pt SELECTION MODE SINGLE

Select up to one item.

Pt SELECTION MODE NONE

Callback functions take care of selecting items.

Pt SELECTION MODE MULTIPLE

Each item can be selected independently.

Pt SELECTION MODE RANGE

A range of items can be selected.

You can OR one of these values with zero or more of the followingflags, which describe how the mouse and keyboard should work:

Pt SELECTION MODE NOMOVE

Don’t move the current item when you drag the mouse.

Pt SELECTION MODE NOSCROLL

Don’t scroll the widget if you drag the mouse above or belowthe widget.

Pt SELECTION MODE NOREST

Don’t restore the previous state if you release the mouse outsidethe widget.

Pt SELECTION MODE NOCLEAR

If you click on an item, don’t clear the previous selection (usewith Pt SELECTION MODE MULTIPLE mode only).

Pt SELECTION MODE AUTO

The keyboard automatically selects the current item (unlessyou’re pressing Ctrl).



Pt SELECTION MODE NOFOCUS

If the Pt SELECTION MODE AUTO flag is set, don’t select thecurrent item automatically when the widget gets focus.

Pt SELECTION MODE TOGGLE

You can unselect an item by clicking on it(Pt SELECTION MODE SINGLE andPt SELECTION MODE MULTIPLE modes only).

Note that zero isn’t a valid value for the selection mode; neither is amixture of predefined and compose values.

The “predefined” selection modes are equivalent to the followingcompose modes:

For Pt BROWSE MODE:

Pt SELECTION MODE SINGLE | Pt SELECTION MODE AUTO

For Pt MULTIPLE MODE:

Pt SELECTION MODE MULTIPLE |Pt SELECTION MODE NOMOVE |Pt SELECTION MODE NOCLEAR |Pt SELECTION MODE TOGGLE |Pt SELECTION MODE NOSCROLL

For Pt EXTENDED MODE:

Pt SELECTION MODE MULTIPLE |Pt SELECTION MODE AUTO |Pt SELECTION MODE NOMOVE |Pt SELECTION MODE NOFOCUS

For Pt SINGLE MODE:

Pt SELECTION MODE SINGLE |Pt SELECTION MODE NOCLEAR

For Pt RANGE MODE:

Pt SELECTION MODE RANGE | Pt SELECTION MODE AUTO| Pt SELECTION MODE NOFOCUS



Pt ARG SELECTION TEXT COLOR



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

Pt ARG TOP ITEM POS



The item index that appears at the top of the list. (The first item is 1.)

Pt ARG VISIBLE COUNT (read-only)



The number of items currently visible.

Pt CB SCROLL MOVE



A list of PtCallback t structures that define the callbacks that thewidget invokes when the top item position changes.

If the widget has the Pt CALLBACKS ACTIVE bit set in itsPt ARG FLAGS resource, these callbacks are also invoked when yourapplication changes the top item position (Pt ARG TOP ITEM POS)by calling PtSetResource() or PtSetResources().




reason Pt CB SCROLL MOVE

reason subtype

Defines the source of the position change:

Pt LIST SCROLL SCROLLBAR

The scrollbar was used.Pt LIST SCROLL LIST

The list was used directly.


cbdata A pointer to a PtScrollbarCallback t structure thatcontains at least the following members:

unsigned action;

A value indicating what happened — seebelow.

int position; A value corresponding to the handle’slocation.

The action field can be one of the following:

Pt SCROLL DECREMENT

The scrollbar handle position has been decreased by oneincrement.

Pt SCROLL INCREMENT

The handle position has been increased by one increment.

Pt SCROLL PAGE INCREMENT

The handle position has been increased by one page.

Pt SCROLL PAGE DECREMENT

The handle position has been decreased by one page.



Pt SCROLL TO MAX

The handle has been moved to the maximum value.

Pt SCROLL TO MIN

The handle has been moved to the minimum value.

Pt SCROLL DRAGGED

The handle is being dragged.

Pt SCROLL RELEASED

The handle has been released after having been dragged.

Pt SCROLL SET

The change of position is the result of a call to PtSetResources()and the widget has the Pt CALLBACKS ACTIVE bit set in itsPt ARG FLAGS resource.

Pt SCROLL JUMP

You jumped to a specific location by Ctrl-clicking on thescrollbar.








continued. . .
















Pt ARG POS PtWidget









Pt CB ARM PtBasic


continued. . .














Pt CB MENU PtBasic


Pt CB RAW PtWidget





Pt CB DND

For Pt CB DND callbacks for a PtGenList, the cbinfo->cbdata is apointer to a PtListDndCallback t structure, containing at leastthe following members:





PtGenListItem t *item

The target item involved in the drag-and-dropoperation.


unsigned long flags

Possible values:



If neither of these is set, the drop occurred insidethe item.


Convenience functions:The following convenience functions and data structure are usefulwhen working with descendants of PtGenList:



In general, the subclass specifies which of the convenience functionsyou can use. For example, PtList and PtTree don’t let you call anyof the PtGenList convenience functions except the ones that areredefined as their own convenience functions.

�

PtGenListAddItems()

Add items to a list.

PtGenListAllItems()

Get pointers to all the items in a list.

PtGenListClearSelection()

Clear the selection.

PtGenListCreateTextBalloon()

Create a popup balloon for an item in the list.

PtGenListDamageItem()

Redraw an item when its data has been changed.

PtGenListDrawBackground()

Draw the background of a list.

PtGenListDrawString()

Draw a string.

PtGenListFirstItem()

Return a pointer to the first item in a list.

PtGenListGetCurrent()

Return a pointer to the current item in a list.

PtGenListGetSelIndexes()

Get the indexes of the selected items.

PtGenListGoto()

Set the current item so that the new current item is visible.



PtGenListHold()

Prevent visible repair of a list widget.

PtGenListItem t

PtGenList item structure

PtGenListItemIndex()

Find the index of an item.

PtGenListItemRealloc()

Reallocate memory for an item.

PtGenListLastItem()

Return a pointer to the last item in a list.

PtGenListLockItem()

Lock an item so it can be resized.

PtGenListRelease()

Release a hold on visible repairs of a list widget.

PtGenListRemoveItems()

Remove items from a list.

PtGenListResize()

Resize a list widget.

PtGenListSelect()

Select an item in a list.

PtGenListSelectedItems()

Get pointers to the selected items.

PtGenListSetColumnBalloon()

Adjust the balloon text to correspond to a given column.

PtGenListSetGflags()

Modify the gflags field of the widget.



PtGenListSetSelIndexes()

Set the selection indexes.

PtGenListShow()

Set the current position so a given item is visible.

PtGenListUnlockItem()

Unlock an item so it can be updated.

PtGenListUnselect()

Unselect an item in a list.

The following convenience functions are useful only if you’recreating a custom list widget; they’re described in the Creating a ListWidget chapter of Building Custom Widget:

PtSuperClassGenListDraw()

Invoke the Draw List method in a superclass.

PtSuperClassGenListInflate()

Invoke the List Inflate method in a superclass.

PtSuperClassGenListKey()

Invoke the List Key method in a superclass.

PtSuperClassGenListMouse()

Invoke the List Mouse method in a superclass.

PtSuperClassGenListSelect()

Invoke the List Select method in a superclass.


2004, QNX Software Systems Ltd. PtGenListAddItems()Add items to a list

Synopsis:void PtGenListAddItems( PtWidget t *list,

PtGenListItem t *items,PtGenListItem t *after );

Description:This function adds items to the PtGenList widget pointed to by list.The arguments are:

items A pointer to a list of PtGenListItem t structures linkedwith the next field (the prev field is ignored).

after If after is NULL, add the items at the beginning of the list.If after isn’t NULL, it must point to an item in the widgetand items is added after that item.

In all selection modes except Pt SELECTION MODE RANGE, ifthere’s no current item in the widget and some of the added itemshave the Pt LIST ITEM CURRENT flag set, the first of them becomesthe current item (see “Current item” in the description ofPtGenList). In all other items, the flag is cleared.

If no item is currently selected and the mode is set toPt SELECTION MODE SINGLE, the first of the added items havingthe Pt LIST ITEM SELECTED flag set becomes the selected item. Thisflag on all other items is cleared.

In Pt SELECTION MODE MULTIPLE mode andPt SELECTION MODE NONE mode, all items with thePt LIST ITEM SELECTED flag are selected.

In Pt SELECTION MODE RANGE mode, the behavior depends onwhether there’s a selected range in the widget and how the after itemis located relative to the selected range. In particular, if you remove arange of items and then reinsert them in the same place, the selectedrange is restored. However, the “direction” of the range may bereversed.


PtGenListAddItems() 2004, QNX Software Systems Ltd.

If no items are selected in Pt SELECTION MODE RANGE mode but arange of added items has the Pt LIST ITEM SELECTED flag set, theseitems become the selected range. The first or last item in this rangebecomes the current item, depending on the setting of thePt LIST ITEM CURRENT flag of the first selected item.


Safety


Signal handler No

Thread No

See also:PtGenList, PtGenListItem t


2004, QNX Software Systems Ltd. PtGenListAllItems()Get pointers to all the items in a list

Synopsis:PtGenListItem t **PtGenListAllItems(

PtWidget t *widget,PtGenListItem t **buffer );

Description:This function fills the given buffer with pointers to all the list items.

If buffer is NULL, the function allocates a buffer by calling malloc(),and the buffer is NULL-terminated (or zero-terminated). It’s yourapplication’s responsibility to free the buffer when it’s no longerneeded.

If buffer isn’t NULL, the function doesn’t add a NULL or zero to theend.

Returns:A pointer to a buffer containing pointers to all the items in the list, orNULL.


Safety


Signal handler No

Thread No



PtGenListClearSelection() 2004, QNX Software Systems Ltd.

Clear the selection

Synopsis:void PtGenListClearSelection( PtWidget t *widget );

Description:This function clears the selection of the given PtGenList widget.


Safety


Signal handler No

Thread No

See also:PtGenList


2004, QNX Software Systems Ltd. PtGenListCreateTextBalloon()Create a popup balloon for a list item

Synopsis:PtWidget t *PtGenListCreateTextBalloon(

PtWidget t *widget,PtWidget t *parent,const PhArea t *area,const char *string,int column,const char *font);

Description:This function creates a PtLabel widget to be used as a popupballoon for a list item. The arguments are as follows:

widget A pointer to the PtGenList widget.

parent A pointer to the widget’s parent window.

area A pointer to a PhArea t structure to use as thePt ARG AREA resource for the balloon.

string The string to display in the balloon.

column The number of the column to extract from the string (seebelow).

font The font to use for the label. If this is NULL, use the samefont as the PtGenList widget.

The string consists of columns separated by tab characters. Thecolumn argument selects a column, with 0 or a negative numberindicating the column at the beginning of the string, 1 indicating thecharacters after the first tab, and so on. For example, if column is 1and string is "One\tTwo\tThree", the label contains the string"Two".


PtGenListCreateTextBalloon() 2004, QNX Software Systems Ltd.

Returns:A pointer to the PtLabel widget.


Safety


Signal handler No

Thread No

See also:PhArea t in the Photon Library Reference


2004, QNX Software Systems Ltd. PtGenListDamageItem()Redraw an item when its data has been changed

Synopsis:void PtGenListDamageItem( PtWidget t *list,

PtGenListItem t *item );

Description:Call this function to redraw the item when its data has been changed.If the size changes too, use PtGenListLockItem() andPtGenListUnlockItem() instead.

If you’re modifying more than one item, you should usePtGenListHold() and PtGenListRelease() to avoid multiple calls to theDraw method.

�


Safety


Signal handler No

Thread No



PtGenListDrawBackground() 2004, QNX Software Systems Ltd.

Draw the background of a list

Synopsis:void PtGenListDrawBackground(

PtWidget t *list,PtGenListItem t const *items,unsigned nitems,PhRect t const *where,int lmarg,int rmarg,int tmarg,int bmarg );

Description:This function can be used by a child class of PtGenList for drawingthe background. If the Pt GEN LIST SHOW DAMAGED bit is set inlist->gflags, the function draws only the background for damageditems.

The values of the list, items, nitems, and where arguments should bethe same as those used to call the List Draw method. The lmarg,rmarg, tmarg, and bmarg arguments define additional “margins” onthe left, right, top, and bottom — by setting them to a positive value,you can shorten the selection bar.


Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtGenListDrawBackground()


PhRect t in the Photon Library Reference


PtGenListDrawString() 2004, QNX Software Systems Ltd.

Draw a string

Synopsis:void PtGenListDrawString( PtWidget t *list,

const char *string,PhRect t const *where,int lmarg,int rmarg );

Description:This function can be used by a child class of PtGenList for drawingstrings. The list and where arguments should be the same as thoseused to call the List Draw method. The string argument is the stringto display. Any Tab characters in the string are interpreted as columnseparators.

The where argument is a pointer to a PhRect t structure (see thePhoton Library Reference) that defines the rectangle in which the textis positioned. The x values for the rectangle should be the same asthose used in the where argument of the List Draw method. The yvalues define the vertical position of the string to be drawn betweenthe given values.

The lmarg and rmarg arguments define additional margins. The valueof lmarg is added to the from value of the first column, and rmarg issubtracted from the to value of the last column. If the widget doesn’thave columns, the width of the widget’s canvas is used as a column.

Examples:Here’s an excerpt showing the List Draw method of a widget (takenfrom PtList):

static PtGenListDrawF t list draw;

static void list draw(PtWidget t *const widget, PtGenListItem t *items,unsigned index, unsigned nitems, PhRect t *where)

{PtGenListWidget t *const glist =

(PtGenListWidget t*) widget;


2004, QNX Software Systems Ltd. PtGenListDrawString()

PtBasicWidget t *const basic = (PtBasicWidget t*) widget;const item height = items->size.h;

PtGenListDrawBackground( widget, items, nitems, where,0, 0, 0, 0 );

do {short bot;bot = where->ul.y + item height;if ( items->flags & Pt LIST ITEM DAMAGED ) {

where->lr.y = bot - 1;PtGenListDrawString( widget, STRING(items), where,

0, 0 );}

where->ul.y = bot;items = items->next;} while ( --nitems );

}


Safety


Signal handler No

Thread No




PtGenListFirstItem() 2004, QNX Software Systems Ltd.

Return a pointer to the first item in a list

Synopsis:PtGenListItem t *PtGenListFirstItem(

PtWidget t const *list );

Description:This function returns a pointer to the first item in the given list.

Returns:A pointer to the first item.


Safety


Signal handler No

Thread No



2004, QNX Software Systems Ltd. PtGenListGetCurrent()Return a pointer to the current item in a list

Synopsis:PtGenListItem t *PtGenListGetCurrent(

PtWidget t const *widget );

Description:This function returns a pointer to the current item in the given list (see“Current item” in the description of PtGenList).

Returns:A pointer to the current item.


Safety


Signal handler No

Thread No



PtGenListGetSelIndexes() 2004, QNX Software Systems Ltd.

Get the indexes of the selected items

Synopsis:unsigned short *PtGenListGetSelIndexes(


Description:This function fills the given buffer with the indexes of the currentlyselected items. The first item in the list has an index of 1, not 0.

If buffer is NULL, the function allocates a buffer using malloc(), andterminates the buffer with a zero. It’s your application’s responsibilityto free the buffer when it’s no longer needed.

If buffer isn’t NULL, the function adds a 0 to the end only if there areno selected items.



Safety


Signal handler No

Thread No

See also:PtGenList


2004, QNX Software Systems Ltd. PtGenListGoto()Set the current item so that the new current item is visible

Synopsis:void PtGenListGoto( PtWidget t *list,



If you pass item as NULL, there isn’t a current item.


Safety


Signal handler No

Thread No



PtGenListHold() 2004, QNX Software Systems Ltd.

Prevent visible repair of a list widget

Synopsis:void PtGenListHold( PtWidget t *widget );

Description:This function is a list-aware version of the PtHold() function. After acall to PtGenListHold(), the PtGenListDamageItem() function simplysets the Pt LIST ITEM DAMAGED flag in the item instead of callingPtDamageExtent().


Safety


Signal handler No

Thread No

See also:PtGenListRelease()

PtDamageExtent(), PtHold() in the Photon Library Reference


2004, QNX Software Systems Ltd. PtGenListItem tPtGenList item structure

Synopsis:typedef struct Pt genlist item {

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

Description:This data structure describes an item in a PtGenList widget.

Applications should view this as a read-only structure; subclassesusually define ways to modify PtGenListItem t members.

�

The members include at least:

flags The state of the item:

Pt LIST ITEM SELECTED

This item is selected.Pt LIST ITEM CURRENT

This item is the current item (see “Current item”in the description of PtGenList).

Pt LIST ITEM DAMAGED

This item should be redrawn.Pt LIST ITEM ABOVE

This item is above the visible range of items.Use the Pt ARG TOP ITEM POS resource toscroll the list.

Pt LIST ITEM BELOW

This item is below the visible range of items.Use the Pt ARG TOP ITEM POS resource toscroll the list.

Pt LIST ITEM INWIDGET

The item has been added to a widget.


PtGenListItem t 2004, QNX Software Systems Ltd.

Pt LIST ITEM FLAG USER1Pt LIST ITEM FLAG USER2Pt LIST ITEM FLAG USER3Pt LIST ITEM FLAG USER4

Flags that you can use for any purpose in yourapplication. The widgets don’t use these flags.

The Pt LIST ITEM USED FLAGS macro defines theflags used by the PtGenList widget. The remainingbits are available for the child class.

It’s safe to set only the following item flags beforeadding the item to a widget — they’re preserved if theydon’t conflict with the current state of the widget:


Preserved unless the selection mode isPt SINGLE MODE and another item is alreadyselected.

Pt LIST ITEM CURRENT

Preserved unless there’s already a current item inthe widget.

Don’t modify these flags directly after the item is in alist; they’re set and cleared by the conveniencefunctions.

size A PhDim t structure (see the Photon LibraryReference) that defines the width and height of theitem. If the widget has columns, the widths of theitems are ignored.

next, prev The widget uses these links to find the next andprevious items in the list.


2004, QNX Software Systems Ltd. PtGenListItem t


See also:PtGenList, PtGenTree, PtGenTreeItem t, PtList,PtTreeItem t

PhDim t in the Photon Library Reference

Building Custom Widgets


PtGenListItemIndex() 2004, QNX Software Systems Ltd.

Find the index of an item

Synopsis:int PtGenListItemIndex(

PtWidget t const *list,PtGenListItem t const *item );

Description:This function calculates the index of the given item within the list.The index of the first item is 1.

Returns:The index of the given item.


Safety


Signal handler No

Thread No



2004, QNX Software Systems Ltd. PtGenListItemRealloc()Reallocate memory for an item

Synopsis:PtGenListItem t *PtGenListItemRealloc(

PtGenListItem t *item,PtWidget t *list,size t size );

Description:This function isn’t used by the PtGenList widget itself. It may beused to reallocate memory if the item was allocated using malloc().

The given size should include the size of the PtGenListItem t

structure. If the item is moved to a different address by the realloc()function, PtGenListItemRealloc() repairs the list links.

Returns:A pointer to the reallocated item.


Safety


Signal handler No

Thread No



PtGenListLastItem() 2004, QNX Software Systems Ltd.

Return a pointer to the last item in a list

Synopsis:PtGenListItem t *PtGenListLastItem(

PtWidget t const *list );

Description:This function returns a pointer to the last item in the list.

Returns:A pointer to the last item.


Safety


Signal handler No

Thread No



2004, QNX Software Systems Ltd. PtGenListLockItem()Lock an item so it can be resized

Synopsis:void PtGenListLockItem( PtWidget t *list,


Description:Use this function if the size field of a list item must be changed. CallPtGenListLockItem() first to save the old size of the item, then modifythe item. Then, call PtGenListUnlockItem() last to update and resizeor redisplay the widget if necessary.

You can lock only one item per widget at a time. If you resize a largenumber of items, set all the sizes and then call PtGenListResize().

�


Safety


Signal handler No

Thread No



PtGenListRelease() 2004, QNX Software Systems Ltd.

Release a hold on visible repairs of a list widget

Synopsis:void PtGenListRelease( PtWidget t *widget );

Description:This function is a list-aware version of PtRelease().

After a call to PtGenListHold(), PtGenListDamageItem() simply setsthe Pt LIST ITEM DAMAGED flag in the item instead of callingPtDamageExtent(). PtGenListRelease() looks for items that have theflag set and calls PtDamageExtent().


Safety


Signal handler No

Thread No

See also:PtGenListHold()

PtDamageExtent(), PtRelease() in the Photon Library Reference


2004, QNX Software Systems Ltd. PtGenListRemoveItems()Remove items from a list

Synopsis:PtGenListItem t *PtGenListRemoveItems(

PtWidget t *list,PtGenListItem t *first,PtGenListItem t *last );

Description:This function removes the given sublist list from the PtGenListwidget. If first or last is NULL, the first or last item of the entire list isused. Both arguments may point to the same item, but last must notprecede first in the list.

The function returns the first removed item (or NULL if the list wasempty). The function inserts NULL in the next field of the lastremoved item and the prev field of the first removed item. Thisensures the returned value (if not NULL) always points to the firstitem of a NULL-terminated, double-linked list. No other fields in anyof the removed items are modified.

If the current item is removed, there won’t be a current item in the listunless the selection mode is Pt SELECTION MODE RANGE and onlypart of the selected range is removed. In this case, the current item isset to the first or last of the remaining selected items (see “Currentitem” in the description of PtGenList).

Returns:The first removed item, or NULL if the list was empty.


Safety


continued. . .


PtGenListRemoveItems() 2004, QNX Software Systems Ltd.

Safety

Signal handler No

Thread No



2004, QNX Software Systems Ltd. PtGenListResize()Resize a list widget

Synopsis:void PtGenListResize( PtWidget t *widget );

Description:This function causes the given widget to:

� recalculate the total size of all its items

� recalculate the height of the currently displayed items

� apply the widget’s resize policy, if any.


Safety


Signal handler No

Thread No

See also:PtGenListLockItem(), PtGenListUnlockItem()


PtGenListSelect() 2004, QNX Software Systems Ltd.

Select an item in a list

Synopsis:void PtGenListSelect( PtWidget t *widget,


Description:This function selects the given item in the list. If the selection mode isset to Pt SELECTION MODE SINGLE orPt SELECTION MODE RANGE, this may involve selecting orunselecting other items.


Safety


Signal handler No

Thread No



2004, QNX Software Systems Ltd. PtGenListSelectedItems()Get pointers to the selected items

Synopsis:PtGenListItem t **PtGenListSelectedItems(

PtWidget t *widget,PtGenListItem t **buffer );

Description:This function fills the given buffer with pointers to the currentlyselected items.

If buffer is NULL, the function allocates a buffer using malloc(), andterminates the buffer with a NULL. It’s your application’sresponsibility to free the buffer when it’s no longer needed.

If buffer isn’t NULL, the function adds a NULL to the end only if thereare no selected items.



Safety


Signal handler No

Thread No



PtGenListSetColumnBalloon() 2004, QNX Software Systems Ltd.

Adjust the balloon text for a list item to correspond to a column

Synopsis:PhArea t *PtGenListSetColumnBalloon(

PhArea t *area,PtListColumn t const *column );

Description:This function adjusts the PhArea t structure pointed to by area sothat it corresponds to the given column rather than the entire item. Ifcolumn is NULL, area isn’t modified.

Returns:A pointer to the adjusted area.


Safety


Signal handler No

Thread No

See also:PhArea t in the Photon Library Reference


2004, QNX Software Systems Ltd. PtGenListSetGflags()Modify the gflags field of the widget

Synopsis:unsigned PtGenListSetGflags( PtWidget t *widget,

unsigned value,unsigned mask );

Description:This function modifies the gflags field of the widget. The bits definedby mask are set to the value defined by value.

Returns:The old value of gflags.


Safety


Signal handler No

Thread No

See also:PtGenList


PtGenListSetSelIndexes() 2004, QNX Software Systems Ltd.


Synopsis:int PtGenListSetSelIndexes(

PtWidget t *widget,const unsigned short *bufferint count );

Description:This function lets you set the selection indexes for the givenPtGenList. It assumes that buffer points to a sorted array of indexes.The first item in the list widget has an index of 1, not 0.

The function returns the number of items that have been actuallyselected, which may be smaller than count if the array isn’t sorted orcontains duplicate or out-of-range indexes.

In Pt SELECTION MODE RANGE mode, only the first index andcount are used. In Pt SELECTION MODE SINGLE mode, only the firstindex is used; if count is greater than 1, it’s treated as 1.

�

Returns:The number of items actually selected.


Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtGenListSetSelIndexes()

See also:PtGenList


PtGenListShow() 2004, QNX Software Systems Ltd.

Set the current position so a given item is visible

Synopsis:void PtGenListShow( PtWidget t *list,



PtGenListShow( list, item->next );

without having to make sure item->next isn’t NULL.


Safety


Signal handler No

Thread No



2004, QNX Software Systems Ltd. PtGenListUnlockItem()Unlock an item so it can be updated

Synopsis:void PtGenListUnlockItem( PtWidget t *list,


Description:Use this function if the size field of a list item must be changed. First,call PtGenListLockItem() to save the old size of the item, and thenmodify the item. Then, call PtGenListUnlockItem() to update andresize or redisplay the widget if necessary.

Only one item per widget can be locked at a time. If you resize a largenumber of items, set all sizes and then call PtGenListResize().

�


Safety


Signal handler No

Thread No



PtGenListUnselect() 2004, QNX Software Systems Ltd.

Unselect an item in a list

Synopsis:void PtGenListUnselect( PtWidget t *widget,


Description:This function unselects the given item. PtGenListUnselect() has noeffect in the Pt SELECTION MODE RANGE selection mode.


Safety


Signal handler No

Thread No



2004, QNX Software Systems Ltd. PtGenTreeA generic superclass for tree widgets

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


� PtFileSel

� PtRawTree

� PtTree


Public header:<photon/PtGenTree.h>

Description:The PtGenTree widget displays a tree of items. When you expandan item, another list of items drops down from it. Additional itemscan be added to an expandable item when it’s about to be expanded.Expanded items can be collapsed, which results in the exclusion ofitems from the displayed list.

The tree can actually be a “forest” — the widget can contain multipleitems at the root level. The root items are always visible (included onthe displayed list) because they don’t have a parent that could becollapsed.

You can build a tree (or a forest) that isn’t linked to any widget andthen add the whole tree to a widget as a root or subtree. Alternatively,you can add each item to the widget tree separately, but once thewidget is realized, you’ll have to use PtHold() and PtUpdate() toavoid multiple redraws.

PtGenTreeItem t is the data structure used for the items.

For more information about this class, see Building Custom Widgets.


PtGenTree 2004, QNX Software Systems Ltd.

New resources:


Pt ARG TREE FLAGS unsigned int Flag Pt TREE HAS BUTTONS |

Pt TREE TO LEFT |

Pt TREE TO RIGHT |

Pt TREE INDENT BUTTONS

|

Pt TREE SHOW CONNECTORS

Pt ARG TREE LINE COLOR PgColor t Scalar PgRGB(239, 239, 239)

Pt ARG TREE LINE SPACING unsigned short Scalar 3

Pt ARG TREE MARGIN COLOR PgColor t Scalar PgRGB(225, 225, 225)

Pt CB GEN TREE INPUT PtCallback t * Link NULL

Pt ARG TREE FLAGS


unsigned int Flag Pt TREE HAS BUTTONS |Pt TREE TO LEFT |Pt TREE TO RIGHT |Pt TREE INDENT BUTTONS |Pt TREE SHOW CONNECTORS

Possible values are:

Pt TREE HAS BUTTONS

Display the buttons for expanding and collapsing items.

Pt TREE INDENT BUTTONS

Indent the buttons.

Pt TREE INDENT LINES

Indent the lines.


2004, QNX Software Systems Ltd. PtGenTree

Pt TREE SHOW CONNECTORS

Display the connectors.

Pt TREE SHOW LINES

Display the lines.

Pt TREE SHOW MARGIN

Display the margins.

Pt TREE TO RIGHT

Extend the items to the right edge of the widget.

Pt TREE TO LEFT

Extend the item background to the left edge.

The PtTree subclass defines some additional flags.�

Pt ARG TREE LINE COLOR


PgColor t Scalar PgRGB( 239, 239, 239 )

The color of the lines. See PgColor t in the Photon LibraryReference.

Pt ARG TREE LINE SPACING



The spacing between lines, in pixels.



Pt ARG TREE MARGIN COLOR


PgColor t Scalar PgRGB( 225, 225, 225 )

The color of the margins. See PgColor t in the Photon LibraryReference.

Pt CB GEN TREE INPUT



A list of PtCallback t structures that define the callbacks invokedon mouse and key events. Each callback is passed aPtCallbackInfo t structure that contains at least the followingmembers:

reason Pt CB GEN TREE INPUT

reason subtype

The event type (same as event->type). For more info, seethe types described for PhEvent t in the Photon LibraryReference.


cbdata A pointer to a PtGenTreeInput t structure thatcontains at least the following members:

PtGenTreeItem t *item;

For mouse events, the item pointed toby the mouse or NULL if the mousedoesn’t point to an item. For keyevents, the item that is going to be the



current item (see “Current item” in thedescription of PtGenList) after theevent is normally processed by thewidget.

unsigned index;

The index of the item.PhPoint t pos;

The pointer position relative to theitem. See PhPoint t in the PhotonLibrary Reference.

int consumed; Initially set to Pt CONTINUE. Yourcallback function can suppress normalhandling of the event by setting thisfield to another value. In the case of keyevents, set it to Pt END to consume theevent, or to Pt HALT to pass the event tothe parent widget. Mouse events arealways consumed.








continued. . .




















Pt ARG DIM PtWidget







continued. . .

























Pt ARG POS PtWidget


continued. . .

















Pt CB ARM PtBasic










continued. . .






Pt CB MENU PtBasic


Pt CB RAW PtWidget






Pt CB DND

For Pt CB DND callbacks for a PtGenTree, the cbinfo->cbdata is apointer to a PtTreeDndCallback t structure, containing at leastthe following members:




A pointer to the target item involved in thedrag-and-drop operation.


unsigned long flags

Possible values:







Convenience functions:PtGenTree defines the following convenience functions and datastructure:

PtGenTreeAddAfter()

Add items after a given item.

PtGenTreeAddFirst()

Add items in front of any existing items.

PtGenTreeAllItems()

Get pointers to all the items in the tree.

PtGenTreeClearSelection()

Clear the selection.

PtGenTreeCollapse()

Collapse a subtree.

PtGenTreeDamageItem()

Redraw an item when its data has changed.



PtGenTreeExpand()

Expand a given subtree.

PtGenTreeExpandParents()

Expand any collapsed ancestors of a given item.

PtGenTreeFreeAllItems()

Free all the items in a tree.

PtGenTreeFreeItems()

Free the items in a subtree.

PtGenTreeGetCurrent()

Get a pointer to the current item.

PtGenTreeGetSelIndexes()

Get the indexes of the selected items.

PtGenTreeGoto()

Set the current item and position so that a given item is visible.

PtGenTreeItem t

PtGenTree item structure

PtGenTreeItemIndex()

Calculate the index of a given item.

PtGenTreeItemRealloc()

Reallocate an item.

PtGenTreeItemResize()

Resize an item.

PtGenTreeRemoveChildren()

Unlink all the children of a given item.

PtGenTreeRemoveItem()

Remove a given item and its children from its parents andsiblings.



PtGenTreeRemoveList()

Remove a given items and its siblings from their parent.

PtGenTreeResize()

Resize many items.

PtGenTreeRootItem()

Get a pointer to the first root item.

PtGenTreeSelect()

Select a given item.

PtGenTreeSelectedItems()

Get pointers to the selected items.

PtGenTreeSetSelIndexes()

Set the selection indexes.

PtGenTreeShow()

Set the current position so that a given item is visible.

PtGenTreeUnselect()

Unselect a given item.

PtGenTreeUnselectNonBrothers()

Unselect all items that aren’t siblings of a given item.

The following convenience functions are useful only if you’recreating a custom tree widget; they’re described in the Creating a TreeWidget chapter of Building Custom Widget:

PtSuperClassGenTreeDrawItem()

Invoke the Tree Draw Item method of a given superclass.

PtSuperClassGenTreeItemState()

Invoke the Tree Item State method of a superclass.


2004, QNX Software Systems Ltd. PtGenTreeAddAfter()Add items after a given item

Synopsis:int PtGenTreeAddAfter( PtWidget t *tree,

PtGenTreeItem t *items,PtGenTreeItem t *brother );

Description:This function inserts a list of trees linked with the brother field.PtGenTreeAddAfter() assumes that items points to a list of trees. Thetree variable points to a PtGenTree widget. The new items are addedto the specified tree below the specified brother.

This function may be called with a NULL tree argument, as long asbrother points to an item that isn’t attached to any tree widget.

Returns:0 Success.

-1 The item is already in a widget.


Safety


Signal handler No

Thread No

See also:PtGenTree, PtGenTreeItem t


PtGenTreeAddFirst() 2004, QNX Software Systems Ltd.

Add items in front of any existing items

Synopsis:int PtGenTreeAddFirst( PtWidget t *tree,

PtGenTreeItem t *item,PtGenTreeItem t *parent );

Description:This function adds the list of PtGenTreeItem t structures pointedto by item to the given PtGenTree widget. The list of items arelinked with their brother fields. The item argument can be NULL.

The parent argument identifies the parent item for the added items (ifany). The new items are added in front of any existing children of theparent item. If parent is NULL, the items are added at the root level ofthe tree, before any existing items there.

The tree argument can be NULL, provided that parent points to anitem that isn’t attached to any tree widget.

PtGenTreeAddFirst() sets the Pt TREE ITEM EXPANDABLE flag inthe parent item, whether or not the item argument is NULL.

Returns:0 Success.



Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtGenTreeAddFirst()



PtGenTreeAllItems() 2004, QNX Software Systems Ltd.

Get pointers to all the items in the tree

Synopsis:PtGenTreeItem t **PtGenTreeAllItems(

PtWidget t *widget,PtGenTreeItem t **buffer );

Description:This function fills a buffer with pointers to all items in the widget. Ifbuffer is NULL, the function allocates a buffer using malloc() and thebuffer is NULL-terminated. If buffer isn’t NULL, the function doesn’tadd a NULL at the end.



Safety


Signal handler No

Thread No



2004, QNX Software Systems Ltd. PtGenTreeClearSelection()Clear the selection

Synopsis:void PtGenTreeClearSelection( PtWidget t *widget );

Description:This function clears the selection in the given PtGenTree widget.


Safety


Signal handler No

Thread No

See also:PtGenTree


PtGenTreeCollapse() 2004, QNX Software Systems Ltd.

Collapse a subtree

Synopsis:int PtGenTreeCollapse( PtWidget t *tree,

PtGenTreeItem t *item,PhEvent t *event );

Description:This function collapses the given subtree item. The tree argumentmust point to the tree that contains the item or can be NULL if the itemdoesn’t belong to any tree.

If the item belongs to the tree widget, the widget’s Tree Item Statemethod is called.

Returns:The value returned by the Tree Item State method.


Safety


Signal handler No

Thread No




2004, QNX Software Systems Ltd. PtGenTreeDamageItem()Redraw an item when its data has changed

Synopsis:void PtGenTreeDamageItem( PtWidget t *tree,

PtGenTreeItem t *item );

Description:Call this function to redraw the given item when its data has changed.


Safety


Signal handler No

Thread No

See also:PtGenTree


PtGenTreeExpand() 2004, QNX Software Systems Ltd.

Expand a given subtree

Synopsis:int PtGenTreeExpand( PtWidget t *tree,


Description:This function expands the given subtree item. The tree argument mustpoint to the tree that contains the item or can be NULL if the itemdoesn’t belong to any tree.

If tree isn’t NULL, the Tree Item State method of that widget is called.If it returns a nonzero value, the item isn’t expanded; if it returns zero,the expansion proceeds. PtGenTreeExpand() returns the same value.

If the Tree Item State method destroys the item, make sure that itdoesn’t return zero.

�



Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtGenTreeExpand()




PtGenTreeExpandParents() 2004, QNX Software Systems Ltd.

Expand any collapsed ancestors of a given item

Synopsis:int PtGenTreeExpandParents( PtWidget t *tree,


Description:If any ancestors of the given item are collapsed, this function attemptsto expand them.



Safety


Signal handler No

Thread No




2004, QNX Software Systems Ltd. PtGenTreeFreeAllItems()Free all the items in a tree

Synopsis:void PtGenTreeFreeAllItems( PtWidget t *tree );

Description:This function unlinks and frees all items in the tree widget.

This function isn’t called automatically when the PtGenTree widgetis being deleted, because the widget doesn’t assume that its itemshave been allocated.

�


Safety


Signal handler No

Thread No

See also:PtGenTree


PtGenTreeFreeItems() 2004, QNX Software Systems Ltd.

Free the items in a subtree

Synopsis:int PtGenTreeFreeItems( PtGenTreeItem t *item );

Description:This function frees the subtree item, together with its siblings andtheir children. The items must not belong to any tree. (UsePtGenTreeRemoveItem(), PtGenTreeRemoveList(), orPtGenTreeRemoveChildren() to remove the subtree before freeing it.)

Returns:0 Success.

-1 The item is still in a widget.


Safety


Signal handler No

Thread No



2004, QNX Software Systems Ltd. PtGenTreeGetCurrent()Get a pointer to the current item

Synopsis:PtGenTreeItem t *PtGenTreeGetCurrent(

const PtWidget t *widget );

Description:This function returns a pointer to the current item (see “Current item”in the description of PtGenList).

Returns:A pointer to the current item.


Safety


Signal handler No

Thread No



PtGenTreeGetSelIndexes() 2004, QNX Software Systems Ltd.

Get the indexes of the selected items

Synopsis:unsigned short *PtGenTreeGetSelIndexes(


Description:This function fills a buffer with indexes of all the selected items in thewidget. The first item in the widget has an index of 1, not 0.

If buffer is NULL, the function allocates a buffer using malloc(), andterminates the buffer with a zero.

If buffer isn’t NULL, the function adds a 0 to the end only if there areno selected items.

Returns:A pointer to the buffer containing the indexes.


Safety


Signal handler No

Thread No

See also:PtGenTree


2004, QNX Software Systems Ltd. PtGenTreeGoto()Set the current item and position so that a given item is visible

Synopsis:int PtGenTreeGoto( PtWidget t *tree,



If item is NULL, there’s no current item.

You can call PtGenTreeGoto() with an item whose ancestor iscollapsed, in which case the ancestor is expanded.



Safety


Signal handler No

Thread No



PtGenTreeItem t 2004, QNX Software Systems Ltd.

PtGenTree item structure

Synopsis:typedef struct Pt gentree item {

PtGenListItem t list;struct Pt gentree item *father,

*son,*brother;

PhDim t dim;} PtGenTreeItem t;

Description:This data structure describes an item in a PtGenTree widget.

Applications should view this as a read-only structure; subclassesusually define ways to modify PtGenTreeItem t members.

�

The members include at least:

list A structure that describes a generic-list item. This structureincludes state information for the item (whether or not it’sselected, the current item, damaged, out of view, and so on),its size, and links to other generic-list items. For moreinformation, see PtGenListItem t.

The PtGenTree class defines some new flags that can be setin item->list.flags:

Pt TREE ITEM EXPANDABLE

The item can be expanded:

� It has a button for expanding or collapsing the item(unless the widget disables the buttons by clearingPt TREE HAS BUTTONS in itsPt ARG TREE FLAGS resource).

� It reacts to the Right and Left arrow keys byattempting to expand or collapse itself (which,again, can be disabled by a subclass).


2004, QNX Software Systems Ltd. PtGenTreeItem t

The setting of this flag is preserved when the item isadded to a widget. This flag is usually set in the parentitem automatically when you add a branch to an item.

This flag isn’t cleared when all the child items aredeleted. You can clear or set this flag in your code, but:

� Make sure the item is collapsed before clearing theflag.

� Call PtGenTreeDamageItem() afterward to causethe item to be redrawn.

Pt TREE ITEM EXPANDED

The branches of this item are currently on display.

If the Pt TREE ITEM EXPANDABLE flag is set whenthe item is added to a widget, the setting ofPt TREE ITEM EXPANDED flag is preserved; ifPt TREE ITEM EXPANDABLE isn’t set, this flag iscleared.

Once the item is in a widget, don’t set or clear this flag;use the convenience functions instead.

Pt TREE ITEM INWIDGET

The item has been added to a widget.

father, son, brother

Tree links. You can use them to traverse the tree structure, butdon’t modify them directly — use the convenience functionsto modify the tree structure.

dim A PhDim t structure (see the Photon Library Reference) thatdefines the size of the item, excluding the tree ornaments(lines and button).

When an item is added to the widget, the widget calculatesitem->list.size based on the size specified in item->dim, theminimum height of the item, and the item’s position in thetree. The height of an item in a tree widget is always an evennumber of pixels — if you specify an odd number for theheight in the dim field, a gap of at least one pixel is displayedbetween the current item (see “Current item” in the


PtGenTreeItem t 2004, QNX Software Systems Ltd.

description of PtGenList) and any other item directlybelow.


See also:PtGenList, PtGenListItem t, PtGenTree, PtTreeItem t

PhDim t in the Photon Library Reference

Building Custom Widgets


2004, QNX Software Systems Ltd. PtGenTreeItemIndex()Calculate the index of a given item

Synopsis:int PtGenTreeItemIndex(

const PtWidget t *tree,const PtGenTreeTtem t *item );

Description:This function calculates the index of the given item within the tree.The index of the first item is 1.

Returns:The index of the item.


Safety


Signal handler No

Thread No

See also:PtGenTree


PtGenTreeItemRealloc() 2004, QNX Software Systems Ltd.

Reallocate an item

Synopsis:PtGenTreeItem t *PtGenTreeItemRealloc(

PtGenTreeItem t *item,PtWidget t *tree,size t newsize );

Description:Use this function to reallocate an item. It repairs any links damaged ifthe realloc() function moves the item to a different address. The treeargument must point to the tree that contains the item or be NULL ifthe item doesn’t belong to any tree.

Returns:A pointer to the reallocated item.


Safety


Signal handler No

Thread No



2004, QNX Software Systems Ltd. PtGenTreeItemResize()Resize an item

Synopsis:void PtGenTreeItemResize( PtGenTreeItem t *item,

PtWidget t *tree );

Description:This function resizes one item. You should call it after changing thedimensions of an item (item->dim). You don’t need to call thisfunction if item doesn’t belong to any tree or if a subtree containingthe item is collapsed.

If you’re resizing many items, use PtGenTreeResize() instead.�


Safety


Signal handler No

Thread No



PtGenTreeRemoveChildren() 2004, QNX Software Systems Ltd.

Unlink all the children of a given item

Synopsis:PtGenTreeItem t *PtGenTreeRemoveChildren(


Description:This function unlinks all the children of the given item and returns thepointer to the first of them. You can then give the pointer toPtGenTreeFreeItems().

This function doesn’t collapse the item. If the children are visible,NULL is returned. Call PtGenTreeCollapse() beforePtGenTreeRemoveItem() to make sure the item is collapsed.

Returns:A pointer to the first unlinked child.


Safety


Signal handler No

Thread No



2004, QNX Software Systems Ltd. PtGenTreeRemoveItem()Remove a given item and its children from its parents and siblings

Synopsis:void PtGenTreeRemoveItem( PtWidget t *tree,


Description:This function unlinks the given item (together with its children) fromits parent and brothers (if any) and sets item->parent anditem->brother to NULL. The tree argument must point to thePtGenTree widget containing item or can be NULL if item doesn’tbelong to any tree.

If tree is NULL and item has no parent but has a previous sibling, thenPtGenTreeRemoveItem() can’t find the previous sibling and can’tunlink item from its sibling. The function does nothing ifitem->parent and tree are NULL.

PtGenTreeRemoveItem() never clears thePt TREE ITEM EXPANDABLE flag in the item’s parent.


Safety


Signal handler No

Thread No



PtGenTreeRemoveList() 2004, QNX Software Systems Ltd.

Remove a given items and its siblings from their parent

Synopsis:void PtGenTreeRemoveList( PtWidget t *tree,

PtGenTreeItem t *first );

Description:This function unlinks the item first and its siblings (together with theirchildren) from their parent (and previous sibling) and sets their parentfields to NULL. The tree argument must point to the widget thatcontains the items or can be NULL if the items don’t belong to anytree.

If tree is NULL and first has no parent but has a previous sibling,PtGenTreeRemoveList() can’t find the previous sibling and can’tunlink first from its previous sibling.


Safety


Signal handler No

Thread No



2004, QNX Software Systems Ltd. PtGenTreeResize()Resize many items

Synopsis:void PtGenTreeResize( PtWidget t *widget );

Description:Use this function to resize many items. You should call it afterchanging the size field of a number of tree items; modify item->dimdirectly in all items, then call PtGenTreeResize() once.


Safety


Signal handler No

Thread No

See also:PtGenTree


PtGenTreeRootItem() 2004, QNX Software Systems Ltd.

Get a pointer to the first root item

Synopsis:PtGenTreeItem t *PtGenTreeRootItem(

PtWidget t const *tree );

Description:This function returns a pointer to the first root item of the tree.

Returns:A pointer to the first root item.


Safety


Signal handler No

Thread No



2004, QNX Software Systems Ltd. PtGenTreeSelect()Select a given item

Synopsis:void PtGenTreeSelect( PtWidget t *widget,


Description:This function selects the given item. As with other PtGenTree*()functions, the tree argument can be set to NULL if item doesn’t belongto a widget.

If tree isn’t NULL and none of item’s ancestors is collapsed,PtGenListSelect() is called. If tree is NULL or some of the ancestorsof the item are collapsed, PtGenTreeSelect() simply sets thePt LIST ITEM SELECTED flag in the item.


Safety


Signal handler No

Thread No



PtGenTreeSelectedItems() 2004, QNX Software Systems Ltd.

Get pointers to the selected items

Synopsis:PtGenTreeItem t **PtGenTreeSelectedItems(

PtWidget t *widget,PtGenTreeItem t **buffer );

Description:This function fills a buffer with pointers to the currently selecteditems. If buffer is NULL, the function allocates a buffer usingmalloc(), and the buffer is NULL-terminated.

If buffer isn’t NULL, the function adds a NULL to the end only if thereare no selected items.



Safety


Signal handler No

Thread No



2004, QNX Software Systems Ltd. PtGenTreeSetSelIndexes()Set the selection indexes

Synopsis:int PtGenTreeSetSelIndexes(

PtWidget t *widget,unsigned short const *buffer,int count );

Description:This function sets the selection indexes. It assumes that buffer pointsto a sorted array of indexes. The first item in the widget has an indexof 1, not 0.

The function returns the number of items that have been actuallyselected, which may be smaller than count if the array isn’t sorted orcontains duplicate or out-of-range indexes.

When the selection mode is Pt SELECTION MODE RANGE, only thefirst index and the count are used.

Returns:The number of items actually selected.


Safety


Signal handler No

Thread No


PtGenTreeSetSelIndexes() 2004, QNX Software Systems Ltd.

See also:PtGenTree


2004, QNX Software Systems Ltd. PtGenTreeShow()Set the current position so that a given item is visible

Synopsis:int PtGenTreeShow( PtWidget t *widget,



PtGenTreeShow( widget, PtGenTreeGetCurrent(widget) );

without checking whether PtGenTreeGetCurrent() returned a NULLvalue.

PtGenTreeShow() can be called with an item whose ancestor iscollapsed, in which case the ancestor will be expanded.



Safety


Signal handler No

Thread No


PtGenTreeShow() 2004, QNX Software Systems Ltd.



2004, QNX Software Systems Ltd. PtGenTreeUnselect()Unselect a given item

Synopsis:void PtGenTreeUnselect( PtWidget t *widget,


Description:This function unselects the given item.

PtGenTreeUnselect() doesn’t support Pt SELECTION MODE RANGEselection mode.

�


Safety


Signal handler No

Thread No



PtGenTreeUnselectNonBrothers() 2004, QNX Software Systems Ltd.

Deselect all items that aren’t siblings of a given item

Synopsis:void PtGenTreeUnselectNonBrothers(

PtWidget t *wgt,PtGenTreeItem t *item );

Description:This function deselects all the items that aren’t siblings of the givenitem. If item is NULL, the function uses the current item (see “Currentitem” in the description of PtGenList).


Safety


Signal handler No

Thread No



2004, QNX Software Systems Ltd. PtGraphicCommon resources for graphical widgets

Class hierarchy:PtWidget → PtBasic → PtGraphic


� PtArc

� PtBezier

� PtEllipse

� PtGrid

� PtLine

� PtPixel

� PtPolygon

� PtRect


Public header:<photon/PtGraphic.h>

Description:The PtGraphic superclass provides the common resources used byall graphic widgets. Graphical widgets provide attributes for color,fills, patterns, line thickness, joins, and much more.

When you want to incorporate simple, static drawings in yourinterface, use the subclasses of PtGraphic.


PtGraphic 2004, QNX Software Systems Ltd.

Don’t call the Pg... drawing primitives directly, as they aren’t redrawnwhen widgets are damaged and repaired. If you need to drawsomething that can’t be done with these widgets, do your drawinginside a PtRaw widget. For more information, see the Raw Drawingand Animation chapter of the Photon Programmer’s Guide.

�

Each graphical widget draws a single graphical primitive. Theprovided primitives are:

� lines

� rectangles

� ellipses

� arcs

� polylines

� points

You can build up a drawing by creating one widget for each of thegraphical primitives you need. You should create the widgets fromback to front, so that their stacking order is correct and theyconsequently appear correct when drawn to the screen. You shouldalso place the widgets in a container widget (i.e a subclass ofPtContainer).

Origin and coordinates

All the vector graphics widgets are defined by an origin and a set ofcoordinates.

The origin is an offset from the graphic widget’s origin, which is usedas the origin of the coordinate space for the graphics primitive.

The set of coordinates is implemented as an array of PhPoint t

structures (see the Photon Library Reference). Each coordinatespecifies a vertex or control point of the primitive. Here’s a codefragment to illustrate:


2004, QNX Software Systems Ltd. PtGraphic

PhPoint t points[]={ { 0, 0},{40,40},{40, 5},{ 0, 0}};

PtSetArg(&argt[0], Pt ARG POINTS, points, 4 ) ;PtCreateWidget( PtPolygon, parent, 1, argt ) ;

Each of the coordinates defining the primitive is relative to thegraphics widget’s origin.

You can specify the graphics widget’s origin by settingPt ARG ORIGIN. This resource takes a PhPoint t as a value. Thispoint is the origin of the primitive’s coordinate space, in pixels,relative to the widget’s origin.

The set of points is specified using the array resourcePt ARG POINTS. The number of points required in the array — andthe interpretation of those points — depends on the type of graphicsprimitive being defined.

Line attributes

When drawing the points for the primitive, the widget uses itsassociated line drawing attributes to determine the color and drawingstyle to use. These line drawing attributes are specified using thefollowing resources defined by the PtGraphic widget class:

Pt ARG LINE WIDTH

The curve’s width, in pixels.

Pt ARG LINE CAP

The cap style for capping off the curve’s start and end points.

Pt ARG LINE JOIN

The join style for connecting any intermediate vertices in thecurve.



Colors

The graphics primitives use the following resources (defined byPtBasic) to determine their colors and patterns:

Pt ARG COLOR

The widget’s line color.

Pt ARG FILL COLOR

The color of the rectangular area occupied by the widget (i.e. itsextent).

Pt ARG FILL PATTERN

The stipple pattern to use to fill the extent.

The graphics primitives that can draw a closed curve may also usethese resources (defined by PtGraphic) for the inside of the curve:

� Pt ARG INSIDE COLOR

� Pt ARG INSIDE FILL PATTERN

� Pt ARG INSIDE TRANS PATTERN

Creating a drawing

To create a drawing composed of several graphical widgets, youshould first create a container-class widget to place the widgets in. Ifyou wish, set the border width and margins of the container to zero.

At this point, you may create the graphics primitives and positionthem within the container widget. You may choose to position andsize the graphics widgets in one of several ways, but the simplest is toplace them all at position (0,0), which is adequate for most purposes.

The origin resource, Pt ARG ORIGIN, provides a reference point ordatum for all the primitives added to the container-class widget. Thisresource defines a coordinate space for each graphic, allowingmaximum flexibility for positioning and sizing primitives.



For example, the origin lets you create a library of symbols defined intheir own coordinate space. You can then use the origin to place thesymbol anywhere in the drawing, and the widget itself doesn’t need tobe positioned. The only thing you have to do then is scale the symbolitself.

If you know the overall dimensions of the drawing, you may want toSizing theprimitives explicitly set the dimensions of the graphics widgets as you create

them. You might also want to set the dimensions if you want to have astandard symbol clipped to obtain a new shape. The figure belowillustrates how a five-pointed star is drawn when Pt ARG ORIGIN isset to (50,50) and the dimensions of the widget are fixed at 101 x 101pixels. The star is constructed from this set of points:

{(95, -31), (-58, 81), (0, -100), (58, 81), (-95, -31)}

A five-pointed star before clipping.

Note the resulting bounding box of the widget as well as the origin ofthe polygon’s coordinate space, which is fixed at position (50,50) ofthe widget’s canvas.



The star after clipping.

If you don’t need special clipping, however, you should use thegraphics widget’s resize policy or another geometry managementmechanism to determine the widget’s size. The default resize policyfor graphics is Pt RESIZE ...AS REQUIRED for both the width andheight. To fix the dimensions of the widget as shown in the caseabove, you have to override the default resize policy. For moreinformation, see the Pt ARG RESIZE FLAGS resource in thedescription of PtWidget.

Occasionally you’ll want to group together a number of graphicalGroupingelements ofthe drawing

primitives and define them as a group or unit. All the primitiveswithin the group are defined in terms of their common origin, and theunit may be repositioned or resized without affecting the group’scomponents. You can do this simply by creating a container-classwidget and placing the widgets for the graphical primitives within it.



Using this technique, you can create a complex drawing composed ofa number of subdrawings. There’s no limit to the number of drawingsthat can be nested in this way. The only limiting factor here is thenumber of resources consumed. In a system with constrainedmemory, many deeply nested drawings may consume too muchmemory.

�

New resources:


Pt ARG DASH LIST char, short Array NULL

Pt ARG DASH SCALE long Scalar 0

Pt ARG GRAPHIC FLAGS char Flag 0

Pt ARG INSIDE COLOR PgColor t Color Pg TRANSPARENT

Pt ARG INSIDE FILL PATTERN PgPattern t Struct Pg PAT FULL

Pt ARG INSIDE TRANS PATTERN PgPattern t Struct Pg PAT NONE

Pt ARG LINE CAP unsigned short Scalar Pg BUTT CAP

Pt ARG LINE JOIN unsigned short Scalar Pg MITER JOIN

Pt ARG LINE WIDTH long Scalar 0

Pt ARG ORIGIN PhPoint t Struct 0,0

Pt ARG POINTS PhPoint t *, short Array NULL

Pt CB RESCALE PtCallback t * Link NULL

Pt ARG DASH LIST




char, short Array NULL

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

Pt ARG DASH SCALE


long Scalar 0

A scaling factor that’s applied to each of the bits in the dash list todetermine the number of pixels for each dash. For information onsetting this factor, see PgSetStrokeDash() in the Photon LibraryReference.

Pt ARG GRAPHIC FLAGS


char Flag 0

Possible values:

Pt FLOAT POS

Adjust the position and origin of the widget, but leave thegraphic in place relative to the widget’s parent. The upper leftcorner of the widget’s canvas is at the upper left corner of thebounding box described by the point array. Depending on itsresize policy, the widget may resize to fit the rendering.

Pt FLOAT ORIGIN

Adjust the origin of the graphic, but leave the widget in placerelative to its parent. The upper left corner of the bounding boxdescribed by the point array is at the upper left corner of thewidget’s canvas.



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

Pt ARG INSIDE COLOR


PgColor t Color Pg TRANSPARENT

The color of the inside of the graphic. See PgColor t in the PhotonLibrary Reference.

Pt ARG FILL COLOR (inherited from PtBasic) is the color of thewidget’s extent (i.e. the rectangular area that the widget occupies).

Pt ARG INSIDE FILL PATTERN


PgPattern t Struct Pg PAT FULL

The background pattern of the inside of the graphic. You can’t editthis resource in PhAB.

Pt ARG FILL PATTERN (inherited from PtBasic) is the fill patternof the widget’s extent (i.e. the rectangular area that the widgetoccupies).

Pt ARG INSIDE TRANS PATTERN


PgPattern t Struct Pg PAT NONE

The transparency pattern for the inside of the graphic. You can usethis resource for “ghosting” widgets. You can’t edit this resource inPhAB.

Pt ARG TRANS PATTERN (inherited from PtBasic) is thetransparency pattern of the widget’s extent (i.e. the rectangular areathat the widget occupies).



Pt ARG LINE CAP


unsigned short Scalar Pg BUTT CAP

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

� Pg BUTT CAP

� Pg ROUND CAP

� Pg SQUARE CAP

Pt ARG LINE JOIN


unsigned short Scalar Pg MITER JOIN

Defines how thick lines are connected; see PgSetStrokeJoin().Possible values:

� Pg BEVEL JOIN

� Pg BUTT JOIN

� Pg MITER JOIN

� Pg ROUND JOIN

� Pg QROUND JOIN (quick rounded join)

Pt ARG LINE WIDTH


long Scalar 0

The line width for any graphically based widget.



Pt ARG ORIGIN


PhPoint t Struct 0,0

A PhPoint t structure that specifies the offset from the upper leftcorner of the widget’s canvas. The graphic is rendered with its originat:

(widget position) + (Pt ARG ORIGIN)

Pt ARG POINTS


PhPoint t *, short Array NULL

An array of points (PhPoint t structures) describing the graphic.The number of points required in the array and the interpretation ofthose points depend on the type of graphics primitive being defined.

Pt CB RESCALE



A list of PtCallback t structures that define the callbacks that thewidget invokes if its Pt ARG DIM or Pt ARG AREA resource ismodified. You can use this callback to rescale the widget.


reason Pt CB RESCALE



reason subtype

0 (not used).

event NULL (not used).

cbdata A pointer to a PhArea t structure (see the PhotonLibrary Reference) that indicates the old area of thewidget (prior to the area/dimension change). You canretrieve the current area by calling PtGetResources().















continued. . .









Pt ARG DIM PtWidget


















continued. . .




Pt ARG POS PtWidget







Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget





2004, QNX Software Systems Ltd. PtGridA grid pattern

Class hierarchy:PtWidget → PtBasic → PtGraphic → PtGrid

PhAB icon:

Public header:<photon/PtGrid.h>

Description:PtGrid draws a grid pattern via PgDrawGrid() (see the PhotonLibrary Reference).

A PtGrid widget.

New resources:


Pt ARG GRID VERTICAL short Scalar 4

Pt ARG GRID HORIZONTAL short Scalar 4


PtGrid 2004, QNX Software Systems Ltd.

Pt ARG GRID HORIZONTAL


short Scalar 4

The number of horizontal lines in the grid.

Pt ARG GRID VERTICAL


short Scalar 4

The number of vertical lines in the grid.












continued. . .


2004, QNX Software Systems Ltd. PtGrid











Pt ARG DIM PtWidget











Pt ARG INSIDE COLOR PtGraphic Not used by this class.

Pt ARG INSIDE FILL PATTERN PtGraphic Not used by this class.

Pt ARG INSIDE TRANS PATTERN PtGraphic Not used by this class.

continued. . .


PtGrid 2004, QNX Software Systems Ltd.















Pt ARG POS PtWidget







Pt CB ARM PtBasic



continued. . .


2004, QNX Software Systems Ltd. PtGrid



Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






PtGroup 2004, QNX Software Systems Ltd.

A container that can arrange its children in rows and columns

Class hierarchy:PtWidget → PtBasic → PtContainer → PtGroup

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

Public header:<photon/PtGroup.h>

Description:The PtGroup class inherits the functionality of a container andactively manages the geometry of its children: the children arearranged in rows, columns, or a matrix. You can use PtGroup tomake the children mutually exclusive, so that the user can set onlyone child at a time.

A group of buttons.

PhAB has a Group command that creates a PtGroup widget. See“Aligning widgets using groups” in the Geometry Managementchapter of the Programmer’s Guide.

New resources:


2004, QNX Software Systems Ltd. PtGroup


Pt ARG CELL HORZ ALIGN unsigned short Scalar Pt GROUP HORZ LEFT

Pt ARG CELL VERT ALIGN unsigned short Scalar Pt GROUP VERT TOP

Pt ARG GROUP FLAGS unsigned long Flag 0

Pt ARG GROUP HORZ ALIGN unsigned short Scalar Pt GROUP HORZ CENTER

Pt ARG GROUP ORIENTATION unsigned short Scalar Pt GROUP HORIZONTAL

Pt ARG GROUP ROWS COLS unsigned short Scalar 0

Pt ARG GROUP SPACING unsigned short Scalar 0

Pt ARG GROUP SPACING X unsigned short Scalar 0

Pt ARG GROUP SPACING Y unsigned short Scalar 0

Pt ARG GROUP VERT ALIGN unsigned short Scalar Pt GROUP VERT CENTER

Pt ARG CELL HORZ ALIGN


unsigned short Scalar Pt GROUP HORZ LEFT

Determines how the children are aligned horizontally within the cells.Possible values:

� Pt GROUP HORZ LEFT

� Pt GROUP HORZ CENTER

� Pt GROUP HORZ RIGHT

Pt ARG CELL VERT ALIGN


unsigned short Scalar Pt GROUP VERT TOP



Determines how the children are aligned vertically within the cells.Possible values:

� Pt GROUP VERT TOP

� Pt GROUP VERT CENTER

� Pt GROUP VERT BOTTOM

Pt ARG GROUP FLAGS


unsigned long Flag 0

Possible values:

Pt GROUP EQUAL SIZE

Force all children to be the same height and width.

Pt GROUP EXCLUSIVE

Allow only one child to be set at a time.

Pt GROUP NO SELECT ALLOWED

Allow any exclusive group to have no selected item. If this flagis set, you can deselect the currently selected child withouthaving to select another child. To do this, click on the currentlyselected child.

Pt GROUP NO KEYS

Prevent the group from using any keys (e.g. arrows).

Pt GROUP NO KEY WRAP HORIZONTAL

Don’t use keys that would cause horizontal wrap.

Pt GROUP NO KEY WRAP VERTICAL

Don’t use keys that would cause vertical wrap.

Pt GROUP NO KEY WRAP

Don’t use keys that would cause horizontal or vertical wrap.



Pt GROUP EQUAL SIZE HORIZONTAL

Make the children in the group the same width.

Pt GROUP EQUAL SIZE VERTICAL

Make the children in the group the same height.

Pt GROUP STRETCH HORIZONTAL

Stretch the rightmost children in the group horizontally to fill itscanvas.

Pt GROUP STRETCH VERTICAL

Stretch the bottommost children in the group vertically to fill itscanvas.

Pt GROUP STRETCH FILL

Stretch the last widget(s) to fill the available space in thedirection indicated by the orientation.


Don’t set the Pt GROUP EQUAL SIZE ... and Pt GROUP STRETCH ...flags for the same direction — the group will expand every time itsextent is calculated.

�

Pt ARG GROUP HORZ ALIGN


unsigned short Scalar Pt GROUP HORZ CENTER

How the children are aligned horizontally within the group. Thechildren retain their relative positions to each other. Possible values:

� Pt GROUP HORZ LEFT

� Pt GROUP HORZ CENTER

� Pt GROUP HORZ RIGHT



Pt ARG GROUP ORIENTATION


unsigned short Scalar Pt GROUP HORIZONTAL

The orientation of the group; one of:

Pt GROUP ASIS

Don’t align children.

Pt GROUP HORIZONTAL

Align children in a row.

Pt GROUP VERTICAL

Align children in a column.

Pt ARG GROUP ROWS COLS



For a horizontally aligned group, this resource indicates the numberof columns to distribute children into. For a vertically aligned group,this resource indicates the number of rows to distribute children into.Not used for an “as is” group; see Pt ARG GROUP ORIENTATION,above.

Pt ARG GROUP SPACING



If alignment is in effect, this resource defines how many pixelsseparate each child of the group.



If you set this resource, you automatically setPt ARG GROUP SPACING X and Pt ARG GROUP SPACING Y tothe same value.

�

Pt ARG GROUP SPACING X



If alignment is in effect, this resource defines how many pixelsseparate each child of the group horizontally. SettingPt ARG GROUP SPACING automatically sets this resource.

Pt ARG GROUP SPACING Y



If alignment is in effect, this resource defines how many pixelsseparate each child of the group vertically. SettingPt ARG GROUP SPACING automatically sets this resource.

Pt ARG GROUP VERT ALIGN


unsigned short Scalar Pt GROUP VERT CENTER

Determines how the children are aligned within the group. Thechildren retain their relative positions to each other. Possible values:

� Pt GROUP VERT TOP

� Pt GROUP VERT CENTER

� Pt GROUP VERT BOTTOM























Pt ARG DIM PtWidget

continued. . .





















Pt ARG POS PtWidget






continued. . .







Pt CB ARM PtBasic






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






2004, QNX Software Systems Ltd. PtLabelA text, bitmap, or image label

Class hierarchy:PtWidget → PtBasic → PtLabel


� PtButton

� PtMenuLabel — see PtMenuButton

� PtTab

� PtText

PhAB icon:

Public header:<photon/PtLabel.h>

Description:The PtLabel class provides a text string, bitmap, or image forlabeling other widgets. You can have text pop up in a balloon toprovide further meaning to the label.

A text string in a PtLabel widget.

As their name implies, labels are tags attached to objects to identifytheir name or nature. Label widgets are usually positioned beside theother widget they’re describing, although in some cases (e.g. lists),the label appears above the object.

The most frequent use of a label is to identify the name of an inputfield. For example, a mail program must provide input fields forindicating the recipient and the subject of a mail message beingcomposed. The label widget lets you attach “To:” and “Subject:” tagsto those input fields.


PtLabel 2004, QNX Software Systems Ltd.

Creating labels

The default label type is a null-terminated text string. To specify thetype of label, use the Pt ARG LABEL TYPE resource. The possiblevalues for this resource are:

Pt Z STRING The label is a null-terminated ASCII string. This isthe default.

Pt IMAGE The label is an image, typically a small icon.

Pt TEXT IMAGE

The label displays an image and text. To specify thepositioning of these two elements relative to eachother, set Pt ARG BALLOON POSITION. UsePt ARG TEXT IMAGE SPACING to specify thenumber of pixels between the image and text.

Different resources are used for the label data for different label types.This is particularly useful when you wish to switch quickly betweenimage labels and text labels, so you can give the user a choicebetween using icons and textual descriptions of operations.

At the push of a button, the user can switch your interface from aniconic representation of commands to a textual representation of thesame labels. You can switch the label from an icon to text simply bychanging the label type resource.

Text labels

When the label type is textual, the label widget gets the text to bedisplayed from the Pt ARG TEXT STRING resource.

To specify the font for the text, set Pt ARG TEXT FONT .

The label widget defines its own margins in addition to the marginwidth defined by the PtBasic widget class. There are separate left,right, top, and bottom margins, which you can specify using:

� Pt ARG MARGIN LEFT


2004, QNX Software Systems Ltd. PtLabel

� Pt ARG MARGIN RIGHT

� Pt ARG MARGIN TOP

� Pt ARG MARGIN BOTTOM

These margins are cumulative, so that the actual margin of one edgeof the widget is the corresponding resource value added to the marginwidth.

The text label may be aligned independently to the left or rightmargin, or centered horizontally within the margins of the widget.The Pt ARG HORIZONTAL ALIGNMENT resource controls thisbehavior. Pt ARG SECONDARY H ALIGN controls how the text isaligned when the label is smaller than the text (that is, when the text isclipped). If this resource is not set, the value fromPt ARG HORIZONTAL ALIGNMENT is used. The values to specifyfor these horizontal alignment resources are:

� Pt LEFT

� Pt RIGHT

� Pt CENTER

For example, you may want to setPt ARG HORIZONTAL ALIGNMENT to Pt CENTER, but ensure thatthe beginning of the text is readable if the label becomes smaller thanthe text (for example, if the window is resized, and the label’s resizepolicies allow clipping) by setting Pt ARG SECONDARY V ALIGNto Pt LEFT.

You can also control the vertical alignment, i.e. whether the text isaligned to the widget’s top or bottom margin, or centered verticallybetween the two margins. The Pt ARG VERTICAL ALIGNMENTresource controls this behavior. Pt ARG SECONDARY V ALIGNcontrols the alignment of clipped text. The values to specify for thevertical alignment are:

� Pt TOP

� Pt BOTTOM



� Pt CENTER

By default, the text displayed in the label widget is left-alignedhorizontally, and centered vertically. The baseline is calculated byadding the ascender of the label font to the top margin. When text isaligned to the bottom of the widget, the baseline is calculated bysubtracting the descender of the label font from the widget’s bottommargin.

You can align the baselines of labels drawn with different fonts byselecting bottom alignment for each of the widgets and choosingappropriate margins for them. In this case, make sure you specify awidget height large enough to accommodate the height of the largestfont used.

The desired baseline for your aligned widgets is adjusted by the sizeof the maximum descender of all the fonts used. For each label, addthe difference between this descender and the descender of that label’sfont, then add this difference to the widget’s bottom margin. Keeptrack of this value so that you can recalculate the correct marginsetting if you want to change the base margin or the font later on.

Image and bitmap labels

When the label is an image, the label widget gets the image from thePt ARG LABEL IMAGE resource, which contains a pointer to animage structure, of type PhImage t, which is described in thePhoton Library Reference.

The members of the image structure used by the label and buttonwidgets are:

type Specifies the type of image. This determines which othermembers of the image structure are significant and definesthe format of the raw image data.

Images can be palette-based or raw. Palette-based images,including bitmaps, have a color palette that serves as alookup table for determining what color should bedisplayed for each pixel. Each pixel in the image is



encoded as an index into the lookup table, and the pixel isdisplayed using the color contained in the correspondingtable entry.

Raw images have actual RGB color values encoded in theimage data.

More than one pixel may be encoded in each byte of theimage data, so image-scan lines are padded out to a byteboundary.

Bitmaps are encoded with 1 bit-per-pixel, with the mostsignificant bit first. The types are:

� Pg BITMAP BACKFILL — a bitonal image; the twocolors are specified in the color palette.

� Pg BITMAP TRANSPARENT — a monochrome image.The bits in the image data that are set to 1 are drawnusing color palette entry 1; zeros are treated astransparent, so they’re not drawn.

The other types of palette-based images are:

� Pg IMAGE PALETTE BYTE — palette-based imageencoded as 8 bits-per-pixel.

� Pg IMAGE PALETTE NIBBLE — palette-based imageencoded as 4 bits-per-pixel. The most significant nibblein a byte specifies the leftmost pixel.

Raw images are all encoded using 16, 24, or 32bits-per-pixel. The types of raw images are:

� Pg IMAGE DIRECT 8888 — raw image with 8 bits eachfor blue, green, and red (with an additional 8 bitsreserved).

� Pg IMAGE DIRECT 888 — raw image with 8 bits eachfor blue, green, and red.

� Pg IMAGE DIRECT 664 — raw image with 6 bits eachfor green and red, and 4 bits for blue.

� Pg IMAGE DIRECT 555 — raw image with 5 bits eachfor blue, green, and red.



bpl The number of bytes used to encode each scan line. Thisdepends on the image type and size.

size The width and height of the image in pixels.

colors The number of colors used in the image for palette-basedimages. It’s used for determining how many color paletteentries are significant.

palette The color lookup table for determining the color of eachpixel in the image.

image The raw image data.

For more information about manipulating images and image dataformats, see the Raw Drawing and Animation chapter of the PhotonProgrammer’s Guide.

Balloons

Balloons are a very handy feature of the PtLabel widget class. Youcan use a balloon to display a line of text when the pointer pauses ontop of a widget for more than a second.

This can be very useful in an application with a lot of icons.Whenever you pause on an icon, a little text box pops up beside it todisplay the name or action the icon represents.

To use balloons with label class widgets:

1 Set the Pt SHOW BALLOON bit in the Pt ARG LABEL FLAGSresource.

2 Set the Pt ARG BALLOON POSITION resource to define thelocation.

The Pt ARG BALLOON TEXT resource defines the text displayed inthe balloon. If this resource is not set, the Pt ARG TEXT STRING isdisplayed instead. This allows you to choose one of the two main usesof balloons, either to give further information to the user, or to displaythe label text in cases where the label has been truncated.



New resources:


Pt ARG ACCEL KEY char * String NULL

Pt ARG BALLOON COLOR PgColor t Scalar Pg BLACK

Pt ARG BALLOON FILL COLOR PgColor t Scalar Pt BALLOONCOLOR

Pt ARG BALLOON POSITION short Scalar Pt BALLOON RIGHT

Pt ARG BALLOON TEXT char * String NULL

Pt ARG HORIZONTAL ALIGNMENT unsigned char Scalar Pt LEFT

Pt ARG LABEL BALLOON PtWidget t * (*)() Pointer PtInflateBalloon

Pt ARG LABEL FLAGS char Flag Pt LABEL SELECT SHIFT

Pt ARG LABEL IMAGE PhImage t * Image NULL

Pt ARG LABEL TYPE char Scalar Pt Z STRING

Pt ARG LINE SPACING ushort t Scalar 0

Pt ARG MARGIN BOTTOM unsigned short Scalar 0

Pt ARG MARGIN LEFT unsigned short Scalar 0

Pt ARG MARGIN RIGHT unsigned short Scalar 0

Pt ARG MARGIN TOP unsigned short Scalar 0

Pt ARG SECONDARY H ALIGN unsigned char Scalar -1 (Not used)

Pt ARG SECONDARY V ALIGN unsigned char Scalar -1 (Not used)

Pt ARG TEXT FONT char * String "TextFont09"

Pt ARG TEXT IMAGE SPACING int Scalar 2

Pt ARG TEXT STRING char * String NULL

Pt ARG UNDERLINE1 unsigned short Scalar Pg BLACK

continued. . .




Pt ARG UNDERLINE2 unsigned short Scalar Pg TRANSPARENT

Pt ARG UNDERLINE TYPE unsigned short Scalar Pt NO ULINE

Pt ARG VERTICAL ALIGNMENT unsigned char Scalar Pt CENTER

Pt ARG ACCEL KEY


char * String NULL

The accelerator key to underline within the widget’s text string. Youtypically use this resource for hotkeys.

Pt ARG BALLOON COLOR



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

Pt ARG BALLOON FILL COLOR


PgColor t Scalar Pt BALLOONCOLOR

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

Pt ARG BALLOON POSITION




short Scalar Pt BALLOON RIGHT

Indicates where the balloon with the label’s text pops up. IfPt ARG LABEL TYPE is Pt TEXT IMAGE, this resource also controlsthe positioning of the text and image elements relative to each other.Possible values:

� Pt BALLOON INPLACE

� Pt BALLOON TOP

� Pt BALLOON LEFT

� Pt BALLOON RIGHT

� Pt BALLOON BOTTOM

Pt ARG BALLOON TEXT


char * String NULL

The text string to display in the balloon. If left blank, thePt ARG TEXT STRING is used for balloons.

Pt ARG HORIZONTAL ALIGNMENT


unsigned char Scalar Pt LEFT

The horizontal alignment for the text string. Possible values:

� Pt LEFT

� Pt CENTER

� Pt RIGHT



Pt ARG LABEL BALLOON


PtWidget t * (*)() Pointer PtInflateBalloon

By default, when you pause the pointer over this widget, the widgetdisplays a small balloon. If you want to change the look of theballoon, you can use this resource to override the default inflatefunction.

Here’s the prototype of the inflate function:

PtWidget t * InflateBalloon( PtWidget t *window,PtWidget t *widget,int position,char *text,char *font,PgColor t fill color,PgColor t text color );

The arguments are:

window The window widget of the widget that requires theballoon.

widget The widget that requires the balloon.

position Where the balloon is to pop up:

� Pt BITMAP BALLOON BOTTOM

� Pt BITMAP BALLOON INPLACE

� Pt BITMAP BALLOON LEFT

� Pt BITMAP BALLOON RIGHT

� Pt BITMAP BALLOON TOP

text The text to display in the balloon.

font The font for the text.



fill color The balloon’s fill color.

text color The color of text in the balloon.

You can use the supplied values in your inflate function or ignorethem and use your own values.

Pt ARG LABEL FLAGS


char Flag Pt LABEL SELECT SHIFT

Possible values:

Pt BACKFILL TEXT

If this is set, the widget fills the text background with thewidget’s fill color before rendering the text.

Pt LABEL SELECT SHIFT

If this is set, the text shifts down and to the right by one pixelwhen the widget is armed. Otherwise, the text doesn’t shift.

Pt SHOW BALLOON

If the pointer remains motionless for 1.25 seconds over thelabel, a balloon pops up with the label’s text.

Pt BALLOON AS REQUIRED

Same as Pt SHOW BALLOON, except the balloon is inflatedonly if the label is clipped by its parent container.

Pt USE ELLIPSIS

Replace part of the text with an ellipsis (...) if there isn’tenough space to display all of it.

Pt ELLIPSIS MIDDLE

Put the ellipsis into the middle of the text string, instead of at itsend(s). This flag is used only when you’ve setPt USE ELLIPSIS.



Pt ARG LABEL IMAGE



A pointer to a PhImage t structure (see the Photon LibraryReference) that defines the image to be used if the label type (seePt ARG LABEL TYPE, below) is Pt IMAGE or Pt TEXT IMAGE.



�



before providing the image to the widget. If you do this, the memoryused for the image is released when image is replaced or the widget isunrealized or destroyed.

Pt ARG LABEL TYPE


char Scalar Pt Z STRING

The type of information displayed by the label. Possible values:

Pt Z STRING Use Pt ARG TEXT STRING to display the text.

Pt IMAGE Use Pt ARG LABEL IMAGE to display an image.

Pt TEXT IMAGE

Display the image and text of the label. You canspecify the positioning of these two elements



relative to each other by settingPt ARG BALLOON POSITION.

Pt ARG LINE SPACING


ushort t Scalar 0

The space, in pixels, between the lines of text in the label.

Pt ARG MARGIN BOTTOM



The amount of space between the bottom of the label’s canvas and thecanvas defined by the basic widget.

Pt ARG MARGIN LEFT



The amount of space between the left side of the label’s canvas andthe canvas defined by the basic widget.

Pt ARG MARGIN RIGHT



The amount of space between the right side of the label’s canvas andthe canvas defined by the basic widget.



Pt ARG MARGIN TOP



The amount of space between the top of the label’s canvas and thecanvas defined by the basic widget.

Pt ARG SECONDARY H ALIGN


unsigned char Scalar -1

The horizontal alignment for the text string, if the text string isclipped. Possible values:

� Pt LEFT

� Pt CENTER

� Pt RIGHT

Pt ARG SECONDARY V ALIGN


unsigned char Scalar -1

The vertical alignment for the text string, if the text string is clipped.Possible values:

� Pt TOP

� Pt CENTER

� Pt BOTTOM



Pt ARG TEXT FONT



The font used for the label’s text string; see PgSetFont().

Pt ARG TEXT IMAGE SPACING


int Scalar 2

The space, in pixels, between the text and the image in the label.

Pt ARG TEXT STRING


char * String NULL

The text string to be displayed if Pt ARG LABEL TYPE isPt Z STRING or Pt TEXT IMAGE, as well as the text to display in theballoon if Pt ARG BALLOON TEXT is blank.

Pt ARG UNDERLINE1


unsigned short Scalar Pg BLACK

The underline color for the first line.

Pt ARG UNDERLINE2


unsigned short Scalar Pg TRANSPARENT



The underline color for the second line (used to create thick orbeveled underlines).

Pt ARG UNDERLINE TYPE


unsigned short Scalar Pt NO ULINE

The type of underline. Possible values:

� Pt NO ULINE

� Pt DOUBLE ULINE (use with underline color)

� Pt SINGLE ULINE (use with underline color)

� Pt ULINE ETCHED IN (use with border color)

� Pt ULINE ETCHED OUT (use with border color)

Pt ARG VERTICAL ALIGNMENT



The vertical alignment for the text string. Possible values:

� Pt TOP

� Pt CENTER

� Pt BOTTOM





















Pt ARG DIM PtWidget







continued. . .















Pt ARG POS PtWidget







Pt CB ARM PtBasic




Pt CB DND PtWidget

continued. . .









Pt CB MENU PtBasic


Pt CB RAW PtWidget





PtLine 2004, QNX Software Systems Ltd.

A line

Class hierarchy:PtWidget → PtBasic → PtGraphic → PtLine

PhAB icon:

Public header:<photon/PtLine.h>

Description:You can use PtLine to create line primitives.

A PtLine widget.

A line is defined by the origin and two points:

Pt ARG ORIGIN

Origin for the line’s coordinate space.

Pt ARG POINTS

The line’s start and end points. If you don’t set these points, noline is rendered.

For more information, see PtGraphic.


2004, QNX Software Systems Ltd. PtLine





















Pt ARG DIM PtWidget

continued. . .



























continued. . .


2004, QNX Software Systems Ltd. PtLine





Pt ARG POS PtWidget







Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget

continued. . .


2004, QNX Software Systems Ltd. PtListA scrolling list of text items

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

PhAB icon:

Public header:<photon/PtList.h>

Description:The PtList class displays a scrolling list of text items. You canselect one or more items, depending on the selection policy.

A PtList containing text items.

Lists are particularly useful for presenting a large or unknown numberof textual items (e.g. a set of items changing over time). Lists havethe added advantage of displaying the set of items currently selected,and allowing more than one item to be selected at once (see thePt ARG SELECTION MODE resource defined by PtGenList).

If the number of items is too large to display in the area allocated tothe list, the widget can display a vertical scrollbar. You can use theinherited Pt ARG LIST FLAGS resource to control when the scrollbarappears: always, never, or as required.


PtList 2004, QNX Software Systems Ltd.

Limitations

PtList widgets have a few limitations:

� They display only text. If you want to display an image for eachitem, use a PtRawList or PtTree instead.

� All items are in the same font.

� All unselected items are the same color

� All selected items are the same color.

Displaying items in columns

To display items in columns, you can:

� Create a PtDivider widget as a child of the PtList. Put it at thetop of the list, and create (for example) PtButton widgets aschildren of the divider, one for each column. The width of eachbutton is the width of the column.

Or

� Use the inherited Pt ARG LIST COLUMN POS resource.

With both methods, use Tab characters in the item strings to separatethe text for each column.

Even if you use columns, each line in the list remains a single item.When you click on any part of the line, the entire line is selected —having columns doesn’t make the list into a spreadsheet.

�

Creating lists

If you know the list of available choices when you create the list, youcan specify it using the Pt ARG ITEMS resource. This resource takesan array of null-terminated strings.

You should establish the selection policy for the list when it’s created.The resource that controls the selection policy isPt ARG SEL MODE.


2004, QNX Software Systems Ltd. PtList

The default selection policy is browse selection mode, which is themore user-friendly of the two selection modes that allow a singleselection.

If the number of items in a widget is variable, or is known to be large,you should control the size of the widget by explicitly settingdimensions or limiting the number of items displayed.

If you ever need to get the items in a list, you can use some code likethis:

PtArg t args[1];short *num, i;char **items = NULL;

PtSetArg(&args[0], Pt ARG ITEMS, &items, &num);PtGetResources(list wgt, 1, args);

for (i = 0; i < *num; i++)printf("Item %d: %s\n", i, items[i]);

Controlling the number of items displayed

To control the number of visible items in the list widget, use thePt ARG VISIBLE COUNT resource. The number of visible items isthe number of list items displayed in the list at any given time. If thisnumber is less than the total number of items in the list, the list widgetcan add a vertical scrollbar so that you can scroll through the wholelist.

If you specify it, the number of visible items is used to calculate thedimensions of the list (overriding any explicit dimensions specified inPt ARG DIM).

Selection notification

The list widget uses the Pt CB SELECTION callback to notify yourapplication whenever you make a new selection. The cbdata passed tothe callback always contains a pointer to a PtListCallback t

structure. The selection policy in effect for the widget at the time ofthe callback determines which members of the structure are valid.



The mode member of the callback data structure indicates theselection mode that caused the callback to be invoked.

Single selection and browse selection modes let you select only aHandlingsingle

selectionssingle item. In browse mode, the selection isn’t made until yourelease the pointer button after dragging the pointer over the list items.

In either case, the selection callback is invoked when you make theselection. The following members of the callback data structureidentify the item that you selected:

� item — the textual label for the selected item

� item len — the size of the item’s label, in bytes

� item pos — the index of the selected item in the array of itemsmaintained by the Pt ARG ITEMS resource.

Multiple selection modes, including extended selection, let you selectHandlingmultiple

selectionsseveral items at once. When the selection callback is invoked, morethan one item may have been added to the set of selected items.

The data passed to the callback function uses these members toidentify the complete set of selected items:

� sel item count — the number of currently selected items

� sel array — an array of indexes for each currently selected item.

Each index in the array refers to the original array of items maintainedby the Pt ARG ITEMS resource.

New resources:


Pt ARG ITEMS char **, short Array NULL

continued. . .




Pt ARG LIST BALLOON PtListBalloonF t * Pointer Seebelow

Pt ARG LIST SPACING short Scalar 0

Pt ARG MODIFY ITEMS PtListModifyItems t Struct Write-only

Pt ARG SELECTION INDEXES unsigned short *, short Array NULL

Pt CB LIST INPUT PtCallback t * Link NULL

Pt CB SELECTION PtCallback t * Link NULL

Pt ARG ITEMS


char **, short Array NULL

An array of pointers to text items to be displayed in the list.

Pt ARG LIST BALLOON


PtListBalloonF t * Pointer See below

A function that inflates a balloon for the item the pointer is on.PtListBalloonF t is a function type:

typedef PtWidget t *PtListBalloonF t(PtWidget t *widget, PtWidget t *parent,PhArea t *area, PtListColumn t const *col,int coln, const char *item,unsigned index, const char *font);

The arguments are as follows:

widget A pointer to the PtList widget.



parent A pointer to its parent window.

area A pointer to a PhArea t structure (see the Photon LibraryReference) that defines the area that covers the item. Thearea->pos member is relative to the parent window.

col The position of the column the pointer is on.

coln The index of the column the pointer is on.

item The item the pointer is on.

index The index of item.

font The widget’s Pt ARG LIST FONT resource.

The default function does this:

returnPtGenListCreateTextBalloon(widget, parent,PtGenListSetColumnBalloon ( area, col ),item, coln, font);

Pt ARG LIST SPACING


short Scalar 0

The spacing, in pixels, between the items in the list.

Pt ARG MODIFY ITEMS (write only)


PtListModifyItems t Struct

Used internally by the convenience functions.



Pt ARG SELECTION INDEXES


unsigned short *, short Array NULL

An array of indexes indicating which list items given by thePt ARG ITEMS array are currently selected.

Pt CB LIST INPUT



A list of PtCallback t structures that define the callbacks that thewidget invokes on each mouse and key event. Each callback is passeda PtCallbackInfo t structure that contains at least the followingmembers:

reason Pt CB LIST INPUT

reason subtype

The event type (same as event->type). For more info, seethe event types described for the PhEvent t structure inthe Photon Library Reference.


cbdata A pointer to a PtListInput t structure that contains atleast the following members:

PhPoint t pos;

The mouse position relative to the item(valid only for mouse events). SeePhPoint t in the Photon LibraryReference.



char * item; For mouse events, the item under thecursor. For key events, the item thatwill be the current item (see “Currentitem” in the description of PtGenList)after the event is processed normally.

unsigned index;

The index of that item (the first item onthe list has an index of 1).

int consumed; Initially set to Pt CONTINUE. Yourcallback function can suppress normalhandling of the event by setting thisfield to another value. In the case of keyevents, set it to Pt END to consume theevent, or to Pt HALT to pass the event tothe parent widget. Mouse events arealways consumed.


Pt CB SELECTION



A list of PtCallback t structures that define the callbacks that thewidget invokes whenever you select an item from the list. Eachcallback is passed a PtCallbackInfo t structure that contains atleast the following members:

reason Pt CB SELECTION

reason subtype

This value depends on the value ofPt ARG SELECTION MODE. In general, the value ofreason subtype is:



� Pt LIST SELECTION FINAL when the mouse button isreleased inside the widget or the Enter is pressed(selection is accepted).

� Pt LIST SELECTION CANCEL when the mouse buttonis released outside the widget (previous state restored).

� Pt LIST SELECTION BROWSE when the mouse buttonis held down, the space bar is used to select an item, orarrow keys are being used to scroll through the list (aselection is in the process of being made).


cbdata A pointer to a PtListCallback t structure thatcontains at least the following members:

unsigned mode

The selection mode.

char *item The item just selected; see below.

int item len The length of the item, in bytes.

int item pos The position of the item in the array ofitems in the list.

char **sel items

The list of selected items.ushort t *sel array

An array of the selected positions withinthe list.

int sel item count

The number of items in the sel items listand the sel array list.



The item member of the PtListCallback t structure identifies theitem that you just selected (or unselected in modes that let youunselect items by clicking on them). Depending on the selectionmode used by the list, any previously selected items might or mightnot remain selected — check sel items or sel array.

�

















continued. . .











Pt ARG DIM PtWidget
















continued. . .
















Pt ARG POS PtWidget











continued. . .





Pt ARG VISIBLE COUNT PtGenList See below.



Pt CB ARM PtBasic












Pt CB MENU PtBasic


Pt CB RAW PtWidget





continued. . .





Pt ARG VISIBLE COUNT

Although this resource is inherited from PtGenList, it’s used in adifferent way. For PtGenList, Pt ARG VISIBLE COUNT is aread-only resource that tells you the number of visible items. ForPtList, it can be set to number of items you want to display in thelist. If it isn’t specified, or is set to 0, the widget displays as manyitems as its specified dimensions allow.

Pt CB DND

For Pt CB DND callbacks for a PtList, the cbinfo->cbdata is apointer to a PtListDndCallback t structure, containing at leastthe following members:



char *item The target item involved in the drag-and-dropoperation.


unsigned long flags

Possible values:







Convenience functions:The PtList widget defines the following convenience functions thatmake it easier to use the list once it’s been created:

PtListAddItems()

Add one or more items to the list at a specified position.

PtListDeleteAllItems()

Remove all the items from the list.

PtListDeleteItemPos()

Delete a range of items by position.

PtListDeleteItems()

Delete items in the list by name.

PtListGotoPos()

Make the item at the specified position the current item anddisplay it.

PtListItemExists()

Determine whether or not an item exists within the list.

PtListItemPos()

Determine the position of an item within the list.



PtListRemovePositions()

Remove the items at the specified positions.

PtListReplaceItemPos()

Replace items by position number.

PtListReplaceItems()

Replace items by item text.

PtListSelectPos()

Select the item at the specified position.

PtListShowPos()

Display the item at the specified position.

PtListUnselectPos()

Unselect the item at the specified position.


2004, QNX Software Systems Ltd. PtListAddItems()Add items to a list

Synopsis:int PtListAddItems( PtWidget t *widget,

const char **items,int item count,unsigned int position );

Description:This function lets you add one or more items to a list widget at aspecified position. The items argument points to an array of items anditem count indicates the number of strings in the array.

List positions start at 1, not 0. If you specify a position of 0, the itemsare added to the end of the list.

If you add new items in between existing items, the rest of the itemsare moved down the list.

Returns:0 Success.

-1 A memory allocation error occurred, or the specified widgetisn’t a PtList widget.


Safety


Signal handler No

Thread No


PtListAddItems() 2004, QNX Software Systems Ltd.

See also:PtList


2004, QNX Software Systems Ltd. PtListDeleteAllItems()Delete all items from a list

Synopsis:int PtListDeleteAllItems( PtWidget t *widget );

Description:This function deletes all the items from a list.

Returns:0 Success.

-1 The specified widget isn’t a PtList widget.


Safety


Signal handler No

Thread No

See also:PtList, PtListDeleteItems(), PtListDeleteItemPos(),PtListRemovePositions()


PtListDeleteItemPos() 2004, QNX Software Systems Ltd.

Delete a range of items from a list

Synopsis:int PtListDeleteItemPos( PtWidget t *widget,

int item count,int position );

Description:This function deletes item count items from the list, starting fromposition. The first item in the widget has a position of 1, not 0.

Returns:0 Success.



Safety


Signal handler No

Thread No

See also:PtList, PtListDeleteAllItems(), PtListDeleteItems(),PtListRemovePositions()


2004, QNX Software Systems Ltd. PtListDeleteItems()Delete specific items from a list

Synopsis:int PtListDeleteItems( PtWidget t *widget,

const char **items,int item count );

Description:This function deletes each item in the items array from the list. Theitem count argument indicates the number of strings in the array.

Returns:0 Success.



Safety


Signal handler No

Thread No

See also:PtList, PtListDeleteAllItems(), PtListDeleteItemPos(),PtListRemovePositions()


PtListGotoPos() 2004, QNX Software Systems Ltd.

Make an item the current item and display it

Synopsis:void PtListGotoPos( PtWidget t *widget,

int pos );


The first item in the widget has an index of 1. If pos is 0, there will beno current item.


Safety


Signal handler No

Thread No

See also:PtList, PtListShowPos()


2004, QNX Software Systems Ltd. PtListItemExists()Determine whether a list contains a particular item

Synopsis:int PtListItemExists( PtWidget t *widget,

const char *item );

Description:This function performs a linear search on the list for the specifieditem.

Returns:1 The item exists in the list.

0 The item wasn’t found.


Safety


Signal handler No

Thread No

See also:PtList, PtListItemPos()


PtListItemPos() 2004, QNX Software Systems Ltd.

Determine the position of an item in a list

Synopsis:int PtListItemPos( PtWidget t *widget,

const char *item );

Description:This function performs a linear search on the list for the specifieditem.

Returns:The position of the item, or 0 if it wasn’t found.


Safety


Signal handler No

Thread No

See also:PtList, PtListItemExists()


2004, QNX Software Systems Ltd. PtListRemovePositions()Remove items in a list at specific positions

Synopsis:int PtListRemovePositions(

PtWidget t *widget,const unsigned short *pos list,int pos count );

Description:This function deletes the item at each position specified in the arraypos list. The first item in the widget has a position of 1, not 0. Thepos count argument specifies the number of entries in the pos listarray.

Returns:0 Success.



Safety


Signal handler No

Thread No

See also:PtList, PtListDeleteAllItems(), PtListDeleteItemPos(),PtListDeleteItems()


PtListReplaceItemPos() 2004, QNX Software Systems Ltd.

Replace items in a list at a specific position

Synopsis:int PtListReplaceItemPos( PtWidget t *widget,

const char **new items,int item count,int position );

Description:This function replaces item count items in the list with new items.The position argument tells the function where to start. The first itemin the widget has a position of 1, not 0.

Returns:0 Success.

-1 A memory allocation error occurred, or the specified widget isnot a PtList widget.


Safety


Signal handler No

Thread No

See also:PtList, PtListReplaceItems()


2004, QNX Software Systems Ltd. PtListReplaceItems()Replace specific items in a list

Synopsis:int PtListReplaceItems( PtWidget t *widget,

const char **old items,const char **new items,int item count );

Description:This function searches the entire list for each item in old items. Everyoccurrence of each item found is replaced with the correspondingnew item. This operation continues until item count is reached.

Returns:0 Success.

-1 A memory allocation error occurred, or the specified widget isnot a PtList widget.


Safety


Signal handler No

Thread No

See also:PtList, PtListReplaceItemPos()


PtListSelectPos() 2004, QNX Software Systems Ltd.

Select the item at a given position

Synopsis:void PtListSelectPos( PtWidget t *widget,

int pos );

Description:This function selects the item at the given position. The first item inthe widget has a position of 1, not 0.


Safety


Signal handler No

Thread No

See also:PtList, PtListUnselectPos()


2004, QNX Software Systems Ltd. PtListShowPos()Show the item at the given position

Synopsis:void PtListShowPos( PtWidget t *widget,

int pos );

Description:This function scrolls the list pointed to by widget to make the itemwith the position given by pos visible. The first item in the widget hasa position of 1, not 0. If the item is already visible, this function doesnothing.

This function doesn’t affect which items are currently selected.


Safety


Signal handler No

Thread No

See also:PtList, PtListGotoPos()


PtListUnselectPos() 2004, QNX Software Systems Ltd.

Unselect the item at the given position

Synopsis:void PtListUnselectPos( PtWidget t *widget,

int pos );

Description:This function unselects the item at the given position. The first item inthe widget has a position of 1, not 0.

PtListUnselectPos() has no effect if the Pt ARG SELECTION MODEresource is set to Pt SELECTION MODE RANGE.


Safety


Signal handler No

Thread No

See also:PtList, PtListSelectPos()


2004, QNX Software Systems Ltd. PtMenuA popdown or pullup menu

Class hierarchy:PtWidget → PtBasic → PtContainer → PtDisjoint →PtMenu

PhAB icon:None — use PhAB’s Menu module.

Public header:<photon/PtMenu.h>

Description:Menus display a list of possible selections (called items) and let youchoose one of them. The PtMenu class provides popup and pulldownmenus that work in either press-drag-release or click-move-clickmode.

A PtMenu widget that contains various menu items.


PtMenu 2004, QNX Software Systems Ltd.

Use PhAB’s Menu module instead of this widget. See “Menumodules” in the Working with Modules chapter of the PhotonProgrammer’s Guide.

�

The selections displayed in a menu are usually pushbuttons thatactivate application functions, but they may also be toggle buttons,cascaded menu buttons that invoke submenus, or any other selectablewidget. Although menus usually consist of PtMenuButton widgets,you can use any type of widget as a menu item by making it the childof a PtMenu widget.

If PtMenu has any PtLabel-class children that have thePt ARG ACCEL KEY resource defined, the menu attaches hotkeycallbacks on behalf of those children.

A PtMenu widget blocks any nonmenu hotkeys while it’s displayed.�

If you use a nonselectable widget as a menu item, you can make itselectable by setting the Pt SELECTABLE bit in its Pt ARG FLAGS(see PtWidget). PtMenu then sets up callbacks on its children toalter their behavior where necessary, thus ensuring that the childrenoperate as you expect. For example, the children automaticallyhighlight in press-drag-release mode.

If a menu item has a PtMenu widget as a child, and that child has thePt MENU CHILD bit set in its Pt ARG MENU FLAGS resource, thechild behaves as a submenu and is realized when necessary.

Most applications have a menu bar, a horizontal bar (usually aPtMenuBar widget) across the top of the application window. Themenu bar contains a number of menu buttons; when you click on one,the associated pulldown menu appears.

A menu may also be activated or popped up in response to an eventsuch as a button press inside another type of widget. Known as apopup menu, this type of menu normally appears at the currentpointer position.


2004, QNX Software Systems Ltd. PtMenu

A menu is displayed when it’s activated; it may be in one of thesemodes:

Press-drag-release

Press the pointer button and hold it down to keep themenu displayed. Drag the pointer to the desiredselection and release the button over the selection tochoose it. While dragging, the selection underneath thepointer is displayed in a different color.

Click-stay Click the pointer button — that is, press and thenrelease the button without moving the pointer. Themenu is displayed until you click on an item. The itemyou choose is displayed in a different color.

When a selectable widget (such as a button or toggle) is chosen fromthe menu:

� the widget is activated

� the associated action is performed

� any menus displayed disappear.

If the selected item is a cascaded menu button, its menu is activatedand it’s displayed to the right of or below the selection.

Creating menus

You can use PtMenu to create either a pulldown or a popup menu.

The Pt ARG MENU FLAGS resource controls the menu’s behaviorand appearance, including:

� the size

� the lifetime of the menu

� the behavior of a submenu or cascaded menu.



You can set Pt ARG MENU TITLE to specify a title to be displayedat the top of the menu. You can also setPt ARG MENU TITLE FONT to specify the title’s font.

You can use Pt ARG MENU TEXT FONT to specify the font to usefor displaying menu items. This resource overrides the normal defaultfont for text items placed in the menu.

As with other containers, items are placed in a menu by creating themPopulatingthe menu as children of the menu itself. The widgets that you place in the menu

behave according to their type. You can use any widgets that have thePt SELECTABLE flag set in their Pt ARG FLAGS. This includesbuttons, toggle buttons, and menu buttons.

Menu buttons within the menu provide cascaded submenus. For moreinformation on how to create cascaded submenus, see “CascadedMenus.”

Widgets that have the Pt AUTOHIGHLIGHT flag set automaticallyhave the visual cuing provided for you. All the widgets in the Photonwidget library that set the Pt SELECTABLE flag by default set this flagas well. If you explicitly set either of these flags for other widgettypes, be sure to use them appropriately in combination so they’llbehave correctly in a menu.

The menu may also contain other widgets that aren’t menu selections.For example, you can add separators and labels to the menu to make avisual distinction between different sections of the menu and toenhance its appearance.

Normally, the menu is wide enough to hold the widest menu item; allSizing

the menu items are made this size as well. The Pt MENU AUTO bit inthe Pt ARG MENU FLAGS resource controls menu sizing.

If you want to explicitly control the sizes of the menu items, you canclear this flag — it’s then your responsibility to set the dimensions ofeach menu item.



A menu may be created either in advance or dynamically in responseLifetime

to the action that activated it.

If you create the menu in advance, you have to create a callbackfunction to position the menu and realize it in response to the actionthat activates it. When you make a selection, the menu unrealizesitself.

To create the menu dynamically, your callback function must createthe menu first, then position it and realize it. You may also want themenu to be re-created from scratch the next time the callback isinvoked. In this case, you can create the menu as a transient menu bysetting the Pt MENU TRANSIENT bit in Pt ARG MENU FLAGS. Thismenu destroys itself after you select a menu item.

The menu might be destroyed before the selected menu item’scallback is invoked. To make sure that the menu item’s callback iscalled first, attach the menu item callback as follows:

PtCallback t callbacks[] = { { menu item callback, NULL } };

PtSetArg( &arg[0], Pt ARG TEXT STRING, "Open", 0 );PtSetArg( &arg[1], Pt CB ACTIVATE, callbacks, Pt LINK INSERT );item = PtCreateWidget( PtMenuButton, menu, 2, arg );

�

Pulldown menus

To create a pulldown menu, you must create the menu as a child ofthe menu button. You must also attach a callback to the menu buttonthat pulls down the menu in response to a button press.

Attach the callback to the Pt CB ARM or Pt CB MENU callback list(see PtBasic) so that both press-drag-release and click-stay modeswork, then provide the pointer to the menu widget as the client datafor the callback.

Your callback must position the menu beneath the menu button andmake it appear. To do this, call PtPositionMenu() with the menuwidget as the first parameter, and a NULL pointer as the secondparameter. This function determines the correct position for the menu,



knowing that its parent is a menu button. After this, you can make themenu appear by calling PtRealizeWidget(). For more informationabout these functions, see the Photon Library Reference.

For example, to display a pulldown menu:

intpostMenu( PtWidget t *w, void *client data,


if (client data){

PtWidget t *menu = (PtWidget t *)client data;

PtPositionMenu(menu, NULL);PtRealizeWidget(menu);

}return (Pt CONTINUE);

}

To create a pulldown menu invoked by a “File” menu button with thisroutine as the callback function, use the following code:

fileMenu = PtCreateWidget(PtMenu, fileButton, 0, NULL);create file items(fileMenu);

PtAddCallback(fileButton, Pt CB ARM, postMenu, fileMenu);

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

Popup menus

Popup menus are frequently used in an application’s work area. Oftenthis area is not a container widget. In this case, you don’t create themenu as a child of the work area itself; instead, create the menu as achild of the work area’s parent.

As with pulldown menus, you have to provide a callback function orevent handler to activate your popup menu. This callback has toposition the menu and make it appear.

If the widget that you wish to associate with the popup menu doesn’thave a Pt CB ARM or Pt CB MENU callback list, the simplest way



to activate the menu is to associate an event handler with button-pressevents. Provide the menu pointer to the event handler as client data.The event handler should make sure that the appropriate menu buttonwas actually pressed before it activates the menu.

The event handler should position the menu by callingPtPositionMenu(). In this case, pass the Photon event from thePtCallbackInfo t structure as the second parameter to thefunction. This identifies the pointer position where the menu shouldbe placed.

The following function illustrates how you can activate a popup menu:

intpostMenu( PtWidget t *w, void *client data,


PhEvent t *event = info ? info->event : NULL;PhPointerEvent t *ptr = event ? (PhPointerEvent t *)

PhGetData(event) : NULL;

/* post the popup if the right button was pressed */if (event && client data &&

(event->type & Ph EV BUT PRESS) &&(ptr->buttons == 1))

{PtWidget t *menu = (PtWidget t *)client data;

PtPositionMenu(menu, event);PtRealizeWidget(menu);


}

The following code illustrates how you can create a popup menu andactivate it using the above function:

PtSetArg(&arg[0], Pt ARG POS, &offsets.ul, 0);PtSetArg(&arg[1], Pt ARG DIM, &workarea, 0);PtSetArg(&arg[2], Pt ARG ANCHOR FLAGS,

Pt LEFT ANCHORED LEFT|Pt RIGHT ANCHORED RIGHT|Pt TOP ANCHORED TOP|Pt BOTTOM ANCHORED BOTTOM,Pt IS ANCHORED);

PtSetArg(&arg[3], Pt ARG ANCHOR OFFSETS, &offsets, 0);raw = PtCreateWidget(PtRaw, window, 4, arg);



popupMenu = PtCreateWidget(PtMenu, window, 0, NULL );create file items(popupMenu);PtAddEventHandler(raw, Ph EV BUT PRESS, popup menu cb,

popupMenu);

Cascaded menus

If you place a menu button in a menu and create another menu as itschild, you’ll get a cascaded submenu. Unlike pulldown menus orpopup menus, you don’t have to attach any callbacks to activatesubmenus — they’re handled automatically.

You must, however, set the Pt MENU CHILD bit in thePt ARG MENU FLAGS to indicate that the menu is a submenu. Ifyou want the submenu to appear to the right of its parent — theconventional way that submenus cascade — you’ll also have to set thePt MENU RIGHT flag in the PtMenuButton widget’sPt ARG BUTTON TYPE resource.

Here’s the create file items() function from the previous example;notice how it creates a cascaded submenu:

void create file items(PtWidget t *parent){

PtArg t arg[3];PtWidget t *importButton, *importMenu;PtCallback t quit callbacks[] = { {quit cb, NULL} };PtCallback t noop[] = { {nop cb, NULL} };

PtSetArg(&arg[0], Pt ARG TEXT STRING, "Open", 0);PtSetArg(&arg[1], Pt ARG TEXT FONT, Helvetica 14B, 0);PtSetArg(&arg[2], Pt CB ACTIVATE, noop, 1);PtCreateWidget(PtButton, parent, 3, arg);

PtSetArg(&arg[0], Pt ARG TEXT STRING, "New", 0);PtSetArg(&arg[1], Pt ARG TEXT FONT, Helvetica 14B, 0);PtSetArg(&arg[2], Pt CB ACTIVATE, noop, 1);PtCreateWidget(PtButton, parent, 3, arg);

PtSetArg(&arg[0], Pt ARG TEXT STRING, "Import", 0);PtSetArg(&arg[1], Pt ARG TEXT FONT, Helvetica 14B, 0);PtSetArg(&arg[2], Pt ARG BUTTON TYPE, Pt MENU RIGHT,

Pt MENU RIGHT);importButton = PtCreateWidget(PtMenuButton, parent, 3, arg);



PtSetArg(&arg[0], Pt ARG MENU FLAGS,Pt MENU AUTO|Pt MENU CHILD,Pt MENU AUTO|Pt MENU CHILD);

importMenu = PtCreateWidget(PtMenu, importButton, 1, arg );

create import items(importMenu);

PtCreateWidget(PtSeparator, parent, 0, NULL);

PtSetArg(&arg[0], Pt ARG TEXT STRING, "Quit", 0);PtSetArg(&arg[1], Pt ARG TEXT FONT, Helvetica 14B, 0);PtSetArg(&arg[2], Pt CB ACTIVATE, quit callbacks, 1);PtCreateWidget(PtButton, parent, 3, arg);

}

Complete menu example

Here’s a complete example that uses all the techniques describedabove. It includes an application window with a menu bar along thetop, and a work area. The menu bar consists of a File menu and aHelp menu. The work area is a PtRaw widget that has a popup menuassociated with the right pointer button. The popup menu contains thesame selections as the file menu.

#include <Pt.h>

#include <stdlib.h>

/* The name of the font to use in the menus: */

char Helvetica 14B[MAX FONT TAG];

int

post menu cb(PtWidget t *w, void *client data, PtCallbackInfo t *info){

client data = client data; info = info;

if (client data)

{PtWidget t *menu = (PtWidget t *)client data;

PtPositionMenu(menu, NULL);

PtRealizeWidget(menu);


}

int

popup menu cb(PtWidget t *w, void *client data, PtCallbackInfo t *info)

{PhEvent t *event = info ? info->event : NULL;



PhPointerEvent t *ptr = event ? (PhPointerEvent t *)PhGetData

(event) : NULL;

w = w;

/* post the popup if the right button was pressed */if (event && client data &&

(event->type & Ph EV BUT PRESS) &&(ptr->buttons == 1))

{

PtWidget t *menu = (PtWidget t *)client data;

PtPositionMenu(menu, event);

PtRealizeWidget(menu);}

return (Pt CONTINUE);

}

int

nop cb(PtWidget t *w, void *client data,PtCallbackInfo t *info)

{

PtArg t arg[1];char *text;

w = w; client data = client data; info = info;

PtSetArg(&arg[0], Pt ARG TEXT STRING, &text, 0);PtGetResources(w, 1, arg);

if (text)printf("Pushed the %s button\n", text);

return (Pt CONTINUE);

}

int

quit cb(PtWidget t *w, void *client data, PtCallbackInfo t *info){

w = w; client data = client data; info = info;

PtExit( EXIT SUCCESS );


void create import items(PtWidget t *parent){

PtArg t arg[3];

PtCallback t noop[] = { {nop cb, NULL} };

PtSetArg(&arg[0], Pt ARG TEXT STRING, "Image", 0);

PtSetArg(&arg[1], Pt ARG TEXT FONT, Helvetica 14B, 0);PtSetArg(&arg[2], Pt CB ACTIVATE, noop, 1);

PtCreateWidget(PtButton, parent, 3, arg);

PtSetArg(&arg[0], Pt ARG TEXT STRING, "Bitmap", 0);

PtSetArg(&arg[1], Pt ARG TEXT FONT, Helvetica 14B, 0);

PtSetArg(&arg[2], Pt CB ACTIVATE, noop, 1);PtCreateWidget(PtButton, parent, 3, arg);

}



void create file items(PtWidget t *parent)

{

PtArg t arg[3];PtWidget t *importButton, *importMenu;

PtCallback t quit callbacks[] = { {quit cb, NULL} };


PtSetArg(&arg[0], Pt ARG TEXT STRING, "Open", 0);PtSetArg(&arg[1], Pt ARG TEXT FONT, Helvetica 14B, 0);

PtSetArg(&arg[2], Pt CB ACTIVATE, noop, 1);


PtSetArg(&arg[0], Pt ARG TEXT STRING, "New", 0);



PtSetArg(&arg[0], Pt ARG TEXT STRING, "Import", 0);

PtSetArg(&arg[1], Pt ARG TEXT FONT, Helvetica 14B, 0);

PtSetArg(&arg[2], Pt ARG BUTTON TYPE, Pt MENU RIGHT,Pt MENU RIGHT);

importButton = PtCreateWidget(PtMenuButton, parent, 3, arg);

PtSetArg(&arg[0], Pt ARG MENU FLAGS,

Pt MENU AUTO|Pt MENU CHILD,Pt MENU AUTO|Pt MENU CHILD);

importMenu = PtCreateWidget(PtMenu, importButton, 1, arg );

create import items(importMenu);

PtCreateWidget(PtSeparator, parent, 0, NULL);

PtSetArg(&arg[0], Pt ARG TEXT STRING, "Quit", 0);

PtSetArg(&arg[1], Pt ARG TEXT FONT, Helvetica 14B, 0);PtSetArg(&arg[2], Pt CB ACTIVATE, quit callbacks, 1);


}

void create help items(PtWidget t *parent)

{PtArg t arg[3];


PtSetArg(&arg[0], Pt ARG TEXT STRING, "About", 0);


PtCreateWidget(PtMenuButton, parent, 3, arg);

}

int

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

PtAppContext t app;

PhDim t dim, workarea, *group size;PhPoint t pos;

PtArg t arg[5];

PtWidget t *window, *group, *raw;PtWidget t *fileButton, *helpButton;

PtWidget t *fileMenu, *helpMenu, *popupMenu;



if (PtInit(NULL) == -1)


if ((window = PtCreateWidget(PtWindow, Pt NO PARENT,

0, NULL)) == NULL)PtExit(EXIT FAILURE);

/* Generate the name of the font for the menus. */

if(PfGenerateFontName("Helvetica", PF STYLE BOLD, 14,

Helvetica 14B) == NULL) {perror("Unable to generate font name");


}

PtSetArg(&arg[0], Pt ARG ANCHOR FLAGS,

Pt LEFT ANCHORED LEFT|Pt RIGHT ANCHORED RIGHT,Pt IS ANCHORED);

PtSetArg(&arg[1], Pt ARG BEVEL WIDTH, 2, 0);

PtSetArg(&arg[2], Pt ARG FLAGS, Pt HIGHLIGHTED, Pt HIGHLIGHTED);group = PtCreateWidget(PtGroup, window, 3, arg);

PtSetArg(&arg[0], Pt ARG TEXT STRING, "File", 0);PtSetArg(&arg[1], Pt ARG TEXT FONT, Helvetica 14B, 0);

fileButton = PtCreateWidget(PtMenuButton, group, 2, arg);

PtSetArg(&arg[0], Pt ARG TEXT STRING, "Help", 0);

PtSetArg(&arg[1], Pt ARG TEXT FONT, Helvetica 14B, 0);helpButton = PtCreateWidget(PtMenuButton, group, 2, arg);

fileMenu = PtCreateWidget(PtMenu, fileButton, 0, NULL);create file items(fileMenu);

helpMenu = PtCreateWidget(PtMenu, helpButton, 0, NULL);create help items(helpMenu);

PtAddCallback(fileButton, Pt CB ARM, post menu cb, fileMenu);PtAddCallback(helpButton, Pt CB ARM, post menu cb, helpMenu);

PtRealizeWidget(window);

PtSetArg(&arg[0], Pt ARG DIM, &group size, 0);PtGetResources(group, 1, arg);

workarea.w = 300;workarea.h = 200;

pos.x = 0;

pos.y = group size->h + 2 * 2;

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

PtSetArg(&arg[1], Pt ARG DIM, &workarea, 0);raw = PtCreateWidget(PtRaw, window, 2, arg);

popupMenu = PtCreateWidget(PtMenu, window, 0, NULL );create file items(popupMenu);

PtAddEventHandler(raw, Ph EV BUT PRESS, popup menu cb, popupMenu);

PtRealizeWidget(raw);



dim.w = workarea.w;dim.h = workarea.h + group size->h + 2 * 2;

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

PtSetResources(window, 1, arg);

PtMainLoop();

return (EXIT SUCCESS);}

New resources:


Pt ARG MENU FLAGS unsigned long Flag Pt MENU AUTO |Pt MENU TEXT ALIGN

Pt ARG MENU SPACING short Scalar Value ofPt ARG BEVEL WIDTH

Pt ARG MENU TEXT FONT char * String NULL

Pt ARG MENU TITLE char * String NULL

Pt ARG MENU TITLE FONT char * String "MenuFont09"

Pt ARG MENU FLAGS


unsigned long Flag Pt MENU AUTO |Pt MENU TEXT ALIGN

Flags that control the menu’s appearance and behavior. You can setthis resource to any combination of the following bits:

Pt MENU AUTO

Make all items the same width.



Pt MENU CHILD

Let this menu override its parent menu.

Pt MENU GRADIENT

Fill the highlighted item with a gradient.

Pt MENU TEAR OFF

Let the user “tear off” the menu from where it originallyappears and keep it somewhere else.

Pt MENU TEXT ALIGN

Align text horizontally.

Pt MENU TRANSIENT

Destroy the menu on closing. The menu might be destroyedbefore the callback for the selected menu item is invoked.

Pt ARG MENU SPACING


short Scalar Value of Pt ARG BEVEL WIDTH

The amount of space, in pixels, between each menu item. The defaultis the value of the Pt ARG BEVEL WIDTH resource defined byPtWidget.

Pt ARG MENU TEXT FONT


char * String NULL

The font used for PtLabel-based menu items; see PgSetFont() in thePhoton Library Reference. This resource overrides the normal defaultfont for text items placed in the menu.



Pt ARG MENU TITLE


char * String NULL

The menu’s title. If you don’t want a title, set this resource to NULL.

Pt ARG MENU TITLE FONT


char * String "MenuFont09"

The font used for displaying the title.



Pt ARG ANCHOR FLAGS PtWidget Not used by this class.

Pt ARG ANCHOR OFFSETS PtWidget Not used by this class.








continued. . .





Pt ARG CONTAINER FLAGS PtContainer Not used by this class.








Pt ARG DIM PtWidget





Pt ARG FLAGS PtWidget |=Pt DELAY REALIZE|Pt HIGHLIGHTED

Pt ARG GROUP FLAGS PtGroup Not used by this class.

Pt ARG GROUP HORZ ALIGN PtGroup Not used by this class.

Pt ARG GROUP ORIENTATION PtGroup Not used by this class.

Pt ARG GROUP ROWS COLS PtGroup Not used by this class.

Pt ARG GROUP SPACING PtGroup Not used by this class.

Pt ARG GROUP SPACING X PtGroup Not used by this class.

Pt ARG GROUP SPACING Y PtGroup Not used by this class.

Pt ARG GROUP VERT ALIGN PtGroup Not used by this class.

continued. . .
















Pt ARG POS PtWidget



Pt ARG SYSINFO PtDisjoint







Pt CB ARM PtBasic

continued. . .









Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget




Pt CB SYSINFO PtDisjoint



2004, QNX Software Systems Ltd. PtMenuBarA container for managing menu buttons

Class hierarchy:PtWidget → PtBasic → PtContainer → PtToolbar →PtMenuBar

PhAB icon:

Public header:<photon/PtMenuBar.h>

Description:The PtMenuBar class provides alignment of menu buttons, andcursor-key navigation through menus.

A PtMenuBar that contains several menu buttons.

This widget is a container that aligns its children and automaticallyanchors itself to the top and sides of its parent.

A PtMenuBar can have only PtMenuButton widgets as children.�



PtMenuBar 2004, QNX Software Systems Ltd.


Pt ARG ANCHOR FLAGS PtWidget Pt LEFT ANCHORED LEFT |Pt RIGHT ANCHORED RIGHT| Pt TOP ANCHORED TOP


Pt ARG AREA PtWidget height = 29
















Pt ARG DIM PtWidget




continued. . .


2004, QNX Software Systems Ltd. PtMenuBar



Pt ARG FLAGS PtWidget |= Pt HIGHLIGHTED











Pt ARG ORIENTATION PtToolbar



Pt ARG POS PtWidget



Pt ARG TOOLBAR FLAGS PtToolbar &=˜Pt TOOLBAR END SEPARATOR

Pt ARG TOOLBAR LAYOUT FLAGS PtToolbar Pt TOOLBAR FROM LINE START

| Pt TOOLBAR TO LINE END

Pt ARG TOOLBAR SPACING PtToolbar 10


continued. . .


PtMenuBar 2004, QNX Software Systems Ltd.







Pt CB ARM PtBasic






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget




continued. . .


2004, QNX Software Systems Ltd. PtMenuBar




PtMenuButton 2004, QNX Software Systems Ltd.

A button used to display a menu

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

PhAB icon:

Public header:<photon/PtMenuButton.h>

Description:The PtMenuButton class displays text or images with optionalaccelerator key text. Menu buttons are used to present menus fromwithin menu bars or other menus.

A PtMenuButton widget.

If you want an accelerator key, set the Pt ARG ACCEL KEY resourcethat’s inherited from PtLabel. For example:

narg = 0;PtSetArg (&args [narg++], Pt ARG TEXT STRING, "File", 0);PtSetArg (&args [narg++], Pt ARG ACCEL KEY, "F", 0);PtCreateWidget (PtMenuButton, database.menu, narg, args);

New resources:


2004, QNX Software Systems Ltd. PtMenuButton


Pt ARG ACCEL FONT char * String "TextFont09b"

Pt ARG ACCEL TEXT char * String ""

Pt ARG BUTTON TYPE unsigned short Scalar Pt MENU TEXT

Pt ARG MODIFIER KEYS ulong t Scalar 0

Pt ARG OFFSET unsigned short Scalar 0

These resources are actually defined in <photon/PtMenuLabel.h>

for the PtMenuLabel widget, which you’ll never instantiate on itsown.

�

Pt ARG ACCEL FONT



The font used to render the hotkey accelerator text.

Pt ARG ACCEL TEXT


char * String ""

The text that identifies the hotkey that’s bound to this widget.

Pt ARG BUTTON TYPE


unsigned short Scalar Pt MENU TEXT

The type of menu button; one of the following:



Pt MENU TEXT

Display the accelerator text, if it’s defined.

Pt MENU RIGHT

Display the submenu to the right of the button.

Pt MENU DOWN

Display the submenu below the button.

Pt MENU UP Display the submenu above the button.

Pt ARG MODIFIER KEYS


ulong t Scalar 0

The modifier key(s) to be displayed in the menu button, expressed asa bitwise OR of one or more of the Pk KM * flags defined in<photon/PkKeyDef.h>.

Pt ARG OFFSET



The x offset used to render the accelerator text.




























continued. . .




Pt ARG DIM PtWidget

Pt ARG EFLAGS PtWidget &= ˜Pt CONSUME EVENTS




Pt ARG FLAGS PtWidget Pt SELECTABLE|Pt MENU BUTTON|Pt GETS FOCUS|Pt MENUABLE|Pt ALL BUTTONS
















continued. . .











Pt ARG POS PtWidget
















continued. . .






Pt CB ARM PtBasic






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






2004, QNX Software Systems Ltd. PtMeterA meter

Class hierarchy:PtWidget → PtBasic → PtGauge → PtMeter

PhAB icon:

Public header:<photon/PtMeter.h>

Description:The PtMeter widget is drawn as a half circle with divisional ticks at1/4, 1/2, and 3/4 of the arc.

100

A PtMeter widget.

You can move the needle in several ways:

� With the mouse — click once to move the meter to the currentmouse position; drag the mouse with a button held down to makethe needle follow the mouse, through meter values.

� With the keyboard — you can use these resources to set up keys tomove the needle to the left or right:

- Pt ARG METER KEY LEFT

- Pt ARG METER KEY RIGHT

� Programatically — set the Pt ARG METER NEEDLE POSITIONresource.

Your meter can include up to 3 severity arcs, drawn in colors toindicate different levels of the meter:


PtMeter 2004, QNX Software Systems Ltd.

� Arc 1 — Pt ARG METER MIN NEEDLE POSITION toPt ARG METER LEVEL1 POS.

� Arc 2 — Pt ARG METER LEVEL1 POS toPt ARG METER LEVEL2 POS.

� Arc 3 — Pt ARG METER LEVEL2 POS toPt ARG METER MAX NEEDLE POSITION.

The widget bases its size on the text size and the specifieddimensions. If the given dimensions are too small, it sizes itselfappropriately based on the resize policy. The height of the widgetdepends on the radius of the meter, which in turn depends on the Xdimension and text sizes.

Creating a 3-arc meter

To create a 3-arc meter with the default arc colors and positions (asshown above):

...PhArea t area = { { 10, 10 }, { 200, 200 } };...PtSetArg(&args[0], Pt ARG AREA, &area, 0);PtCreateWidget(PtMeter, parent, 1, args)...

Creating a 1-arc meter

This example creates a 1-arc meter that has a minimum value of 0,and a maximum of 1000. You can move its needle by clicking themouse buttons; a callback notifies your application when you movethe needle:

1000

A one-arc PtMeter widget.


2004, QNX Software Systems Ltd. PtMeter

...PhArea t area = { { 10, 10 }, { 200, 200 } };PtCallback t cb[1] = { {moved cb, NULL} };

PtSetArg(&args[0], Pt ARG AREA, &area, 0);PtSetArg(&args[1], Pt ARG METER MAX NEEDLE POSITION,

1000, 0);PtSetArg(&args[2], Pt CB METER MOVED, &cb[0], 0);PtCreateWidget(PtMeter, parent, 3, args)...

int moved cb(PtWidget t *widget, void *data,PtCallbackInfo t *info)

{PtMeterCallback t *mydata;mydata = info->cbdata;

printf("Got the callback. Position was: %d severity: %d\n ",mydata->position, mydata->severity);

}...

Creating a 3-arc meter movable by keys and mouse

This example creates a 3-arc meter whose needle can be moved:

� with the mouse

� to the right with ↑ (Pk Up)

� to the left with ↓ (Pk Down)

with an increment of 10 for each keystroke (for example, the metermoves 0, 10, 20, ... when you press the up-arrow key).

...PhArea t area = { { 10, 10 }, { 200, 200 } };PtCallback t cb[1] = { {moved cb, NULL} };

PtSetArg(&args[0], Pt ARG AREA, &area, 0);PtSetArg(&args[1], Pt ARG METER KEY LEFT, Pk Down, 0);PtSetArg(&args[2], Pt ARG METER KEY RIGHT, Pk Up, 0);PtSetArg(&args[3], Pt ARG METER INCREMENT, 10, 0);PtSetArg(&args[4], Pt CB METER MOVED, &cb[0], 0);PtCreateWidget( PtMeter, parent, 5, args );...



int moved cb( PtWidget t *widget, void *data,PtCallbackInfo t *info)

{PtMeterCallback t *mydata;mydata = info->cbdata;

printf("Got the callback. Position was: %d severity: %d\n",mydata->position, mydata->severity);

}

You’ll notice that as you move the needle on the widget, there’s verylittle flickering. This is because when the needle moves it’s merelyerased and then drawn at the new position. However, if you create ameter with Pg TRANSPARENT as a fill color, you’ll notice moreflickering because the needle can’t merely be erased — thebackground must be drawn as well. In this case, flickering is reducedby calculating a bounding rectangle for the needle and redrawing onlythat rectangle. The most flickering (redraw) occurs when the needle isat 45° or 135°.

For flicker-free performance when using Pg TRANSPARENT as a fillcolor, put the PtMeter inside a PtOSContainer widget.

�

Full meter example

#include <stdio.h>#include <Pt.h>#include <photon/PtMeter.h>

PtWidget t *window, *meter, *quit, *sev lbl, *pos lbl;

/* Callback for when the meter moves */int meter cb( PtWidget t *widget, void *data,


PtMeterCallback t *mydata;char pos[10], sev[5];PtArg t args[2];

mydata = info->cbdata;itoa(mydata->position, pos, 10);itoa(mydata->severity, sev, 10);

/* Set the position label to the current position. */



PtSetArg(&args[0], Pt ARG TEXT STRING, pos, 0);PtSetResources(pos lbl, 1, args);

/* Set the severity label to the current severity. */PtSetArg(&args[0], Pt ARG TEXT STRING, sev, 0);PtSetResources(sev lbl, 1, args);


/* Callback for the quit button */int quit cb( PtWidget t *widget, void *data,


PtExit (EXIT SUCCESS);return (Pt CONTINUE);

}

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

PtArg t args[10];PhDim t win dim = { 300, 300 };PhArea t meter area = { { 10, 20 }, { 280, 280 } };PhArea t sev area = { { 125, 200 }, { 50, 20 } };PhArea t pos area = { { 125, 230 }, { 50, 20} };PhArea t quit area = { { 230, 270 }, { 60, 20 } };PtCallback t callbacks[2] = { {meter cb, NULL},

{quit cb, NULL} };int n = 0;char Helvetica 12[MAX FONT TAG];

if (PtInit(NULL) == -1)PtExit(EXIT FAILURE);

PtSetArg( &args[n++], Pt ARG WINDOW TITLE,"PtMeter Demo", 0 );

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

if ((window = PtCreateWidget(PtWindow, Pt NO PARENT,n, args)) == NULL)


/* Draw the meter with 3 arcs and a callback for whenthe meter is moved. */

n = 0;PtSetArg( &args[n++], Pt ARG AREA, &meter area, 0 );PtSetArg( &args[n++], Pt ARG METER MAX NEEDLE POSITION,

1000, 0 );

/* Generate the name of the font to use for the meter. */



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

perror("Unable to generate font name");} else {PtSetArg( &args[n++], Pt ARG METER TEXT FONT,

Helvetica 12, 0 );}PtSetArg( &args[n++], Pt CB METER MOVED, &callbacks[0], 0 );

/* If you don’t want your meter to be selectable, add* the following:** PtSetArg( &args[n++], Pt ARG METER FLAGS,* PtM NON SELECTABLE, PtM NON SELECTABLE );*/

meter = PtCreateWidget( PtMeter, window, n, args );

/* Draw a label to show the severity changes.The first label is the label to be changed,and the second is the name of the parameter. */

n = 0;PtSetArg( &args[n++], Pt ARG AREA, &sev area, 0 );PtSetArg( &args[n++], Pt ARG FLAGS,

Pt HIGHLIGHTED | Pt ETCH HIGHLIGHT, \Pt HIGHLIGHTED | Pt ETCH HIGHLIGHT);

PtSetArg( &args[n++], Pt ARG BEVEL WIDTH, 1, 0);PtSetArg( &args[n++], Pt ARG TEXT STRING, "1", 0);sev lbl = PtCreateWidget( PtLabel, window, n, args );

n = 0;sev area.pos.x -= 60;PtSetArg( &args[n++], Pt ARG AREA, &sev area, 0 );PtSetArg( &args[n++], Pt ARG TEXT STRING, "Severity:", 0);PtCreateWidget( PtLabel, window, n, args );

/* Draw a label to show the position changes.The first label is the label to be changed,and the second is the name of the parameter. */

n = 0;PtSetArg( &args[n++], Pt ARG AREA, &pos area, 0 );PtSetArg( &args[n++], Pt ARG FLAGS,

Pt HIGHLIGHTED | Pt ETCH HIGHLIGHT, \Pt HIGHLIGHTED | Pt ETCH HIGHLIGHT);

PtSetArg( &args[n++], Pt ARG BEVEL WIDTH, 1, 0);PtSetArg( &args[n++], Pt ARG TEXT STRING, "0", 0);pos lbl = PtCreateWidget( PtLabel, window, n, args );



n = 0;pos area.pos.x -= 60;PtSetArg( &args[n++], Pt ARG AREA, &pos area, 0 );PtSetArg( &args[n++], Pt ARG TEXT STRING, "Position:", 0);PtCreateWidget( PtLabel, window, n, args );

/* Draw a quit button. */n = 0;PtSetArg( &args[n++], Pt ARG AREA, &quit area, 0 );PtSetArg( &args[n++], Pt ARG TEXT STRING, "Quit", 0);PtSetArg( &args[n++], Pt CB ACTIVATE, &callbacks[1], 0);quit = PtCreateWidget( PtButton, window, n, args );


PtMainLoop();return (EXIT SUCCESS);

}

New resources:


Pt ARG METER COLOR PgColor t Scalar Pg BLACK

Pt ARG METER FLAGS unsigned short Flag PtM SELECTABLE

Pt ARG METER FONT COLOR PgColor t Scalar Pg BLACK

Pt ARG METER INCREMENT int Scalar 5

Pt ARG METER KEY LEFT int Scalar Pk Left

Pt ARG METER KEY RIGHT int Scalar Pk Right

Pt ARG METER LEVEL1 COLOR PgColor t Scalar Pg GREEN

Pt ARG METER LEVEL1 POS short Scalar 50

Pt ARG METER LEVEL2 COLOR PgColor t Scalar Pg YELLOW

Pt ARG METER LEVEL2 POS short Scalar 75

continued. . .




Pt ARG METER LEVEL3 COLOR PgColor t Scalar Pg RED

Pt ARG METER MAX NEEDLE POSITION short Scalar 100

Pt ARG METER MIN NEEDLE POSITION short Scalar 0

Pt ARG METER NEEDLE COLOR PgColor t Scalar Pg WHITE

Pt ARG METER NEEDLE POSITION short Scalar 0

Pt ARG METER NUM SEVERITY LEVELS short Scalar 3

Pt ARG METER TEXT FONT char * String "TextFont09"

Pt CB METER MOVED PtCallback t * Link NULL

Pt ARG METER COLOR



The color for the center circle, outline of the meter, and divisionalticks. See PgColor t in the Photon Library Reference.

Pt ARG METER FLAGS


unsigned short Flag PtM SELECTABLE

The valid bits are:

PtM NO TEXT

Don’t display the minimum and maximum text strings.

PtM NON SELECTABLE

Make the meter noninteractive.



PtM SELECTABLE

Make the meter interactive.

Pt ARG METER FONT COLOR



The font color for the minimum and maximum strings. SeePgColor t in the Photon Library Reference.

Pt ARG METER INCREMENT


int Scalar 5

The increment used when the keyboard is used to move the meter’sneedle. Every press of the assigned keys moves the meter thisdistance.

Pt ARG METER KEY LEFT


int Scalar Pk Left

The key, as defined in <photon/PkKeyDef.h>, that you can use tomove the meter’s needle to the left. The default value is the left arrow,Pk Left.

For this key to be useful, you must set Pt GETS FOCUS in the meter’sPt ARG FLAGS.

�



Pt ARG METER KEY RIGHT


int Scalar Pk Right

The key, as defined in <photon/PkKeyDef.h>, that you can use tomove the meter’s needle to the right. The default value is the rightarrow, Pk Right.

For this key to be useful, you must set Pt GETS FOCUS in the meter’sPt ARG FLAGS.

�

Pt ARG METER LEVEL1 COLOR


PgColor t Scalar Pg GREEN

The color of the first severity arc. See PgColor t in the PhotonLibrary Reference.

Pt ARG METER LEVEL1 POS


short Scalar 50

The position of the end of the first severity arc, expressed as apercentage of the whole. If the minimum and/or maximum value(s)change, the location of the arc is updated to remain at this percentage.



PgColor t Scalar Pg YELLOW



The color of the second severity arc. See PgColor t in the PhotonLibrary Reference.

Pt ARG METER LEVEL2 POS


short Scalar 75

The position of the end of the second severity arc, expressed as apercentage of the whole. If the minimum and/or maximum value(s)change, the location of the arc is updated to remain at this percentage.




The color of the third severity arc. See PgColor t in the PhotonLibrary Reference.

Pt ARG METER MAX NEEDLE POSITION


short Scalar 100

The maximum needle position; also the value drawn as the maximum.

Pt ARG METER MIN NEEDLE POSITION


short Scalar 0

The minimum needle position; also the value drawn as the minimum.



Pt ARG METER NEEDLE COLOR



The color of the meter’s needle. See PgColor t in the PhotonLibrary Reference.

Pt ARG METER NEEDLE POSITION


short Scalar 0

The current needle position, somewhere between the minimum andmaximum needle position. If the position is above the maximum, themaximum is used; if the position is below the minimum, theminimum is used.

Pt ARG METER NUM SEVERITY LEVELS


short Scalar 3

The number of severity arcs (levels) that the meter displays. Thismust be 1, 2, or 3. If this resource is set higher than 3, only 3 arcs aredisplayed.

Pt ARG METER TEXT FONT



The font for the minimum and maximum strings.



Pt CB METER MOVED



A list of PtCallback t structures that define the callbacks invokedwhen the needle is moved. Each callback is passed aPtCallbackInfo t structure that contains at least the followingmembers:

reason Pt CB METER MOVED

reason subtype

Why the callback was invoked:

� Pt ARG MOVED — the needle moved becausePt ARG METER NEEDLE POSITION was set; eventis NULL

� Pt KEY MOVED — the needle moved due to a keyevent; event is a Ph EV KEY event

� Pt MOUSE MOVED — the needle moved due to amouse event; event is a Ph EV PTR MOTION BUTTONor Ph EV BUT PRESS event

For more information, see PhEvent t in the PhotonLibrary Reference.

event A pointer to a PhEvent t structure that describes theevent that caused the callback to be invoked. If event isNULL, then the callback was invoked because thePt ARG METER NEEDLE POSITION resource was set.

cbdata A pointer to a PtMeterCallback t structure thatcontains at least:

int position The current position of the needle betweenthe minimum and maximum positions.



int severity The severity arc number that the needlecurrent lies in, between 1 and the numberof arcs.













Pt ARG COLOR PtBasic Not used by this class.






continued. . .





Pt ARG DIM PtWidget




Pt ARG FILL PATTERN PtBasic Not used by this class.

Pt ARG FLAGS PtWidget Pt GETS FOCUS

Pt ARG GAUGE FLAGS PtGauge

Pt ARG GAUGE FONT PtGauge

Pt ARG GAUGE H ALIGN PtGauge

Pt ARG GAUGE V ALIGN PtGauge

Pt ARG GAUGE VALUE PtGauge

Pt ARG GAUGE VALUE PREFIX PtGauge

Pt ARG GAUGE VALUE SUFFIX PtGauge









Pt ARG MAXIMUM PtGauge

continued. . .





Pt ARG MINIMUM PtGauge


Pt ARG ORIENTATION PtGauge



Pt ARG POS PtWidget







Pt CB ARM PtBasic




Pt CB DND PtWidget






continued. . .




Pt CB MENU PtBasic


Pt CB RAW PtWidget





PtMTrend 2004, QNX Software Systems Ltd.

A medical trend widget

Class hierarchy:PtWidget → PtBasic → PtMTrend

PhAB icon:

Public header:<photon/PtMTrend.h>

Description:A PtMTrend widget displays trend graphs intended for medicalapplications. The data is displayed as a set of connected points thatshift in a specified direction and at the rate at which data is fed in, orat a rate specified by the application.

PtMTrend is similar to PtTrend, but with some added capabilities:

� A trace mode that displays a trace line, indicating where new datais being drawn.

� Each graph has its own minimum and maximum values.

� Customizable line thickness and join type for each graph.

� You can provide your own customized functions for drawinggraphs, the grid, and the trace line.


2004, QNX Software Systems Ltd. PtMTrend

A PtMTrend widget.

New resources:


Pt ARG MTREND FLAGS int Flag Pt MTREND ALWAYS SCRO

Pt ARG MTREND N SAMPLES unsigned Scalar 0

Pt ARG MTREND N GRAPHS unsigned Scalar 0

Pt ARG MTREND GRAPH ATTR PtMTrendAttr t Struct N/A

Pt ARG MTREND GRAPH STATE int Scalar N/A

Pt ARG MTREND GRAPH DATA PtMTrendData t Struct N/A

Pt ARG MTREND TRACE WIDTH int Scalar 5

Pt ARG MTREND TRACE COLOR PgColor t Scalar 0xC0C0C0

continued. . .




Pt ARG MTREND TRACE DRAW F See below pointer N/A

Pt ARG MTREND GRID X unsigned Scalar 5

Pt ARG MTREND GRID Y unsigned Scalar 5

Pt ARG MTREND GRID COLOR PgColor t Scalar 0xC0C0C0

Pt ARG MTREND GRID DRAW F See below pointer N/A

Pt ARG MTREND ADVANCE BY N SAMPLES> unsigned Scalar 1

Pt ARG MTREND FLAGS


int Flag 0

Flags that control the way the widget draws data.

Direction flags; one of:

Pt MTREND HORZ L2R

Draw the trend left to right.

Pt MTREND HORZ R2L

Draw the trend right to left.

Pt MTREND VERT T2B

Draw the trend top to bottom.

Pt MTREND VERT B2T

Draw the trend bottom to top.

When setting the direction flag, use Pt MTREND DIRECTION MASKas the len argument for the PtSetArg() or PtSetResource() function.

Grid flags; one of:



Pt MTREND GRID NONE

Do not show a grid.

Pt MTREND GRID ABOVE

Draw the grid over the graphs.

Pt MTREND GRID BELOW

Draw the grid under the graphs.

To set the grid, use Pt MTREND GRID MASK as the len argument forthe PtSetArg() or PtSetResource() function.

Graphs drawing mode; one of:

Pt MTREND TRACE

Draw a trace line indicating where new graph data is beingdrawn on the trend.

Pt MTREND BLIT

Use blit mode — blit the data to reduce CPU use. Blit mode isavailable only if Pt MTREND TRACE isn’t set and no grid isshown.

Pt MTREND ALWAYS SCROLL

When data is first drawn on an empty graph, start drawing fromthe side of the graph that represents the newest data. The sidethat represents new data is dependent on the direction flag. Forexample, if the direction is Pt MTREND HORZ L2R, new data isdrawn on the right hand side of the graph, and older data isscrolled to the left.

If this flag is not set, when data is first drawn in the graph, it isdrawn on the side that represents old data. Once the graph fillswith data, it begins to scroll in the direction indicated by thedirection flag.



Pt ARG MTREND N SAMPLES


unsigned Scalar 0

The maximum number of samples shown in the trend. If you reducethis number when there is sample data in the trend, the oldest samplesare trimmed.

Pt ARG MTREND N GRAPHS


unsigned Scalar 0

The number of graphs drawn in the trend. Note that graphs arenumbered starting at 0, but this resource indicates the actual numberof graphs.

If you add new graphs to a trend widget, they appear with minimumvalues until you set the graph data. If you reduce the number ofgraphs, existing graphs are removed from the trend. For example, ifyou have 5 graphs numbered 0 to 4 in your trend, and you changePt ARG MTREND N GRAPHS from 5 to 3, graphs 3 and 4 areremoved from the trend.

Pt ARG MTREND GRAPH ATTR


PtMTrendAttr t Struct N/A

Set attributes of a graph. PtMTrendAttr t contains the followingmembers, which your application must fill in:

int state The trend state; one ofPt MTREND STATE SHOWN (visible) orPt MTREND STATE HIDDEN (not visible).



PgColor t color

The line color.

int line thickness

The line thickness, in pixels.

int join type The line join type; see PgSetStrokeJoin() in thePhoton Library Reference for more informationabout join types.

int min and max

The minimum and maximum values for sampledata.

void *draw f A pointer to a customized draw function for thegraph. You can set the pointer to your ownfunction (see below).

To set your graph draw function, draw f should be a pointer of type:

void (*draw f)( PtWidget t *widget,PhTile t *damage,struct pt mtrend graph info *attr );

The widget argument is a pointer to the trend widget of typePtMTrend. The damage argument is the damage list for the widget.The attr argument is type pt mtrend graph info, which has atleast the following attributes:

PtMTrendAttr t attr

A structure containing the attribute information for thegraph.

int n samples

The total number of samples in the data buffer.

int *data A pointer to an array of data for the graph, with theoldest data at position 0.



When setting this resource with PtSetArg() or PtSetResource(), passthe graph number as the len argument.

Pt ARG MTREND GRAPH STATE


int Scalar N/A

Enables or disables graph drawing. Values:

Pt MTREND STATE SHOWN

Draw the graph.

Pt MTREND STATE HIDDEN

Don’t draw the graph.

When setting this resource with PtSetArg() or PtSetResource(), passthe graph number as the len argument.

Pt ARG MTREND GRAPH DATA


PtMTrendData t Struct N/A

Use to add or change data for a specified graph. When setting thisresource with PtSetArg() or PtSetResource(), pass the graph numberas the len argument. The PtMTrendData t contains at least thesemembers:

int mode Can be one of Pt MTREND ADD or Pt MTREND PUT

unsigned n samples

The number of data samples in the data array.



unsigned last sample

The sample number where to put new data into thebuffer, if mode is Pt MTREND PUT.

const int *data

The data samples array.

For convenience, the library provides PtMTrendAddData() andPtMTrendChangeData() for working with data in the graphs.

Pt ARG MTREND TRACE WIDTH


int Scalar 5

The width of the trace strip. If positive, this is the number of pixels. Ifnegative, the width is calculated as the absolute value of this resourcemultiplied by the width of one data sample.

Pt ARG MTREND TRACE COLOR


PgColor t Scalar 0xC0C0C0

The trace strip color.

Pt ARG MTREND TRACE DRAW F


See below Pointer N/A

By default, a pointer to the default trace drawing function. You canprovide your own drawing function for the trace line by setting thisresource to a pointer with the following type:

void (*draw f)( PtWidget t *widget, PhTile t *damage );



The arguments are:

widget A pointer to a PtMTrendWidget t structure. Thefunction should use the trace.pos and trace.dim membersof this structure for drawing.

damage The damage list for the draw function.

Pt ARG MTREND GRID X


unsigned Scalar 5

The number of vertical grid lines, if the grid is turned on.

Pt ARG MTREND GRID Y


unsigned Scalar 5

The number of horizontal grid lines, if the grid is turned on.

Pt ARG MTREND GRID COLOR


PgColor t Scalar 0xC0C0C0

The grid line color, if the grid is turned on.

Pt ARG MTREND GRID DRAW F


See below Pointer N/A



A pointer to the default grid drawing function. You can provide yourown customized grid drawing function by setting this resource to apointer to a function of the following type:

void (*draw f)( PtWidget t *widget, PhTile t *damage );

The arguments are:

widget A pointer to a PtMTrendWidget t structure. Thefunction should use the grid.* members for drawing.

damage The damage list for the widget.

Pt ARG MTREND ADVANCE BY N SAMPLES


unsigned Scalar 1

This resource specifies the number of data samples to be shifted whenthe limit (the edge of the trend widget) is reached. If set to 1 (default),the trend appears to be continuously scrolling. That is, for each drawcycle, the trend is scrolled by one sample, then the new sample isdrawn.

If you set this resource to a larger value, the trend scroll behavior isdifferent. For example, if you set the value to 10, each time the trendreaches the end of the widget, the trend is scrolled back by tensamples. Ten more samples are drawn before the trend is scrolledagain.

You can set this resource to a value larger than 1 only for trends thataren’t in trace mode.





















Pt ARG DIM PtWidget







continued. . .















Pt ARG POS PtWidget







Pt CB ARM PtBasic




Pt CB DND PtWidget

continued. . .









Pt CB MENU PtBasic


Pt CB RAW PtWidget




Convenience functions:The PtMTrend defines the following convenience functions thatmake it easier to use the widget once it’s been created:

PtMTrendAddData()

Add data to a trend.

PtMTrendChangeData()

Change existing data in a trend.


2004, QNX Software Systems Ltd. PtMTrendAddData(),PtMTrendChangeData()

Add or change data for a PtMTrend widget

Synopsis:

void PtMTrendAddData( PtWidget t *widget,unsigned graph no,const int *newdata,unsigned nsamples );

void PtMTrendChangeData( PtWidget t *widget,unsigned graph no,int const *newdata,unsigned last sample,unsigned nsamples );

Arguments:widget A pointer to a widget of type PtMTrend.

graph no The number of the graph to be added to or changed, inthe range 0 to trend count - 1, inclusive.

newdata A pointer to an array of the new data (see below).

nsamples The number of samples in the array.

last sample (PtMTrendChangeData() only)

The index of the newest sample to replace, where 0 isconsidered to be the index of the most recently addedsample.

Description:PtMTrendAddData() lets you add data for a PtMtrend, whilePtMTrendChangeData() lets you change existing data.

The newdata array is ordered with the oldest sample at newdata[0],and the newest at newdata[nsamples - 1]. The oldest sample to bereplaced has an index of last sample + nsamples - 1;

The samples in the trend are replaced as follows:


PtMTrendAddData(), PtMTrendChangeData() 2004, QNX

Software Systems Ltd.

� trend sample[last sample] = newdata[nsamples - 1].

� trend sample[last sample + 1] = newdata[nsamples - 2].

� ...

� trend sample[last sample + nsamples - 1] = newdata[0].

If last sample + nsamples - 1 is outside the range of samples for thewidget, some initial portion of the new data is discarded.


Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtMultiTextMultiline stylized text

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

PhAB icon:

Public header:<photon/PtMultiText.h>

Description:The PtMultiText widget class lets you display and edit multilinedstylized text.

A PtMultiText widget.

Lines can be automatically wrapped on character or word boundaries.Optional scrollbars are provided to make it easy to view wide or longdocuments. Multiple colors and fonts are supported on any line.

The text buffer of the PtMultiText widget is a zero-terminatedstring consisting of multibyte (UTF-8) characters. You can setattributes (such as font, color, or style) for any segment of text, butthis information isn’t embedded in the text buffer.

Features

The MultiText widget provides many features that make it ideal formultilined data entry fields or as the basis for an editor:

� optional line- and word- or character-wrapping


PtMultiText 2004, QNX Software Systems Ltd.

� support for multiple text fonts and colors

� support for “tagging” segments of text

� optional automatic scrollbars, both horizontal and vertical

� range selection

� cut, copy, and paste

� multiple tab stops

� tab expansion

� optional automatic indentation

� anchoring

� many useful callbacks

� cursor visibility, editable or read-only options

� overstrike and insert editing modes

You can control all these features via the widget’s resources andconvenience functions. For example, to force the widget to wrap longlines at word boundaries, set the Pt EMT WORD bit of thePt ARG MULTITEXT WRAP FLAGS resource:

PtSetArg( &argt, Pt ARG MULTITEXT WRAP FLAGS, Pt EMT WORD,Pt EMT WORD );

PtSetResources( mtwidget, 1, &argt );

If you set both the word- and character-wrap flags, word wrapping isapplied.

You can also control the amount of space left between lines of textusing Pt ARG LINE SPACING. The value of this resource is thenumber of pixels to leave between the descenders of one line of textand the ascenders of the next.


2004, QNX Software Systems Ltd. PtMultiText

To display a horizontal scrollbar:

� Set the Pt ARG SCROLLBAR X DISPLAY to Pt AS REQUIRED orPt ALWAYS.

� Clear Pt EMT WORD and Pt EMT CHAR in the widget’sPt ARG MULTITEXT WRAP FLAGS resource.

�

Setting text

You can set the contents of the text buffer using thePt ARG TEXT STRING, Pt ARG TEXT SUBSTRING, orPt ARG MULTITEXT SEGMENTS resources, or thePtTextModifyText() or PtMultiTextModifyText() conveniencefunctions. The PtMultiText widget automatically wraps the textaccording to the wrap flags, and displays scrollbars if thePt ARG SCROLLBAR X DISPLAY and/orPt ARG SCROLLBAR Y DISPLAY resources allow for them.

If you set the text using the Pt ARG TEXT STRING resource, the newtext replaces the entire text buffer of the widget, and all the lines oftext are drawn using the same attributes. The font is the one specifiedby the Pt ARG TEXT FONT resource inherited from PtLabel. Thetext foreground and background colors are taken from the values ofthe Pt ARG COLOR and Pt ARG FILL COLOR resources.

If you set the text using Pt ARG TEXT SUBSTRING, only thespecified portion of the text buffer is affected. Text can be deletedand/or inserted. The text inserted is drawn with the same attributes asthe text at the insertion point.

Text attributes

You can control the following attributes of a range of text:

� font

� text color

� background color



� tag ( void * for your own use )

There are several methods for setting the attributes that affect a givenrange of text:

� Delete and/or insert ranges of text with attributes via thePtMultiTextModifyText() convenience function. Specify theattributes in the PtMultiTextAttributes t structure that youpass to this function.

� Change the attributes of a range of text that’s already there byfilling in a PtMultiTextAttributes t structure and using it toset the Pt ARG MULTITEXT RANGE ATTRIBUTES resource or,by calling the PtTextModifyText() convenience function.

� Define the ranges of text in advance (along with the associated setof attributes) and place them in the text buffer by setting thePt ARG MULTITEXT SEGMENTS resource. This is an easy wayto initialize the PtMultiText widget with a catchy message.

When setting the text and attributes via thePt ARG MULTITEXT SEGMENTS resource, you provide theresource with an array of PtMultiLines t structures. Eachelement of the array has a text string and an associated set ofattributes that are used when displaying the text.

Setting text using ranges

The following example shows how to create a multiline text widgetwith two ranges of text with different attributes:

#include <stdio.h>#include <stdlib.h>#include <Pt.h>#include <Ph.h>

char Verdana24[MAX FONT TAG];

PtMultiLines t hello[] = {{ "Hello\n", Pt DEFAULT FONT, Pt DEFAULT COLOR,Pt INHERIT COLOR },

{ "World!", Pt DEFAULT FONT, Pg BLUE, Pt INHERIT COLOR }};



main() {PtWidget t *window;PtArg t args[2];int nargs = 0;PhDim t dim = { 300, 150 };


if ((window = PtCreateWidget(PtWindow, Pt NO PARENT,0, NULL)) == NULL)

PtExit( EXIT FAILURE );

if(PfGenerateFontName("Verdana", 0, 24,Verdana24) == NULL) {

perror("Unable to generate font name");} else {hello[1].font = Verdana24;

}PtSetArg( &args[nargs++], Pt ARG DIM, &dim, 0 );PtSetArg( &args[nargs++], Pt ARG MULTITEXT SEGMENTS,

&hello, sizeof( hello )/sizeof(hello[0]) );PtCreateWidget( PtMultiText, Pt DEFAULT PARENT,

nargs, args );


PtMainLoop();}

Inserting text with assigned attributes

You can insert a new range of text into the text buffer and specify itsattributes using the PtMultiTextModifyText() function. To deleteand/or insert text such that it takes on the attributes in effect at theinsertion point, use PtTextModifyText().

The following shows how our “Hello, world” example could berewritten to insert text into the widget:

#include <stdio.h>#include <stdlib.h>#include <Pt.h>#include <Ph.h>

main()



{PtWidget t *window, *mtext;PtArg t args[2];int nargs = 0;PhDim t dim = { 300, 150 };PtMultiTextAttributes t attr;char Verdana24[MAX FONT TAG];


if ((window = PtCreateWidget(PtWindow, Pt NO PARENT,0, NULL)) == NULL)

PtExit( EXIT FAILURE );

if(PfGenerateFontName("Verdana", 0, 24,Verdana24) == NULL) {

perror("Unable to generate font name");attr.font = Pt DEFAULT FONT;

} else {attr.font = Verdana24;

}

PtSetArg( &args[nargs++], Pt ARG DIM, &dim, 0 );mtext = PtCreateWidget( PtMultiText, Pt DEFAULT PARENT,

nargs, args );PtTextModifyText( mtext, NULL, NULL, 0, "Hello, \n", 8 );PtMultiTextModifyText( mtext, NULL, NULL, -1,

"World! \n", 8, attr, Pt MT FONT );


PtMainLoop();}

Changing the attributes of a range of text

With a WYSIWYG editor, you can select a range of text in the textwidget and change the text attributes of that range. This requires theability to modify the attributes of a range programmatically.Modifying the attributes of a range is also useful for marking blocksof text, as may be done to indicate the results of a search. You canmodify the attributes of a range of text by using thePtMultiTextModifyAttributes() function or by setting thePt ARG MULTITEXT RANGE ATTRIBUTES resource.



The following example shows how to change the font of the textselection to 14-point Helvetica, by usingPtMultiTextModifyAttributes():

PtMultiTextAttributes t attr;int start, end;char Helvetica 14[MAX FONT TAG];

if( PtTextGetSelection( text, &start, &end ) ){


perror("Unable to generate font name");} else {

attr.font = Helvetica 14;PtMultiTextModifyAttributes( text, &start, &end,

&attr, Pt MT FONT );}

}

This code segment first determines the start and end of the textselection by calling PtTextGetSelection(). This gives the start and endpositions to use in a subsequent call to PtMultiTextModifyAttributes().

The following example shows how to change the font of the textselection to 14-point Helvetica, by setting thePt ARG MULTITEXT RANGE ATTRIBUTES resource:

PtMultiTextAttributes t attr;PtMultiTextControl t mtc;char Helvetica 14[MAX FONT TAG];

if( PtTextGetSelection( text, &mtc.tc.start, &mtc.tc.end ) ){


perror("Unable to generate font name");} else {

PtArg t argt;attr.font = Helvetica 14;mtc.attributes = &attr;PtSetArg( &argt, Pt ARG MULTITEXT RANGE ATTRIBUTES,

&mtc, Pt MT FONT );PtSetResources( text, 1, &argt );

}}



The members of the PtMultiTextControl t structure (also knownas PtMultiTextCallback t) used in the example are:

PtTextCallback t tc

Text control structure used to control the modification of text.This is always present in the modification callbacks of PtTextor PtMultiText widgets. The members ofPtTextCallback t (also known as PtTextControl t) are:

int start posint end pos The characters from start pos up to but not

including end pos will be deleted.

int cur insert The position to insert characters if no deletionhas occurred; otherwise, the new characterswill be inserted at start pos.

int new insert Useful only in modify callbacks, this memberindicates the position the cursor will be inafter the modification has occurred.

int length The number of multibyte (UTF-8) charactersto insert.

char *text The multibyte string to insert.

int doit Must be set to nonzero before changes to thecontent of the body of text will be permitted.

PtMultiTextAttributes t *attributes

This structure describes a set of attributes. SeePtMultiTextAttributes t.

PtMultiTextSegment t *seg

Valid only in callbacks from the PtMultiText widget. Itpoints to the segment of text that’s involved in the modificationthat caused the callback. See PtMultiTextSegment t.

If you implement editing functions that allow operations that alter theattributes of fonts in text ranges, you should always obtain the current



attributes in effect at the start of each range and make changes basedon those.

Hyperlinks using cursor-motion callbacks

Since the cursor-motion callback notifies your application wheneverthe cursor is moved, the callback can also notify the application whenthe user presses the pointer button over a “hot-spot” used for ahypertext link.

You can store the data for a hypertext link itself on the pointermaintained in the tag for the text segment. The cursor-motioncallback can then simply:

1 Check the tag’s contents to determine if the cursor has beenpositioned on a hypertext link.

2 Check the event to see if the appropriate event type caused thecallback to be invoked (i.e. a pointer-button press).

3 Take the action associated with the hypertext link.

You can refine this technique further by changing the callback so thatit registers only an event handler that invokes the action associatedwith the hypertext link, then deregisters itself. This lets you definemore complex behavior (e.g. proper “activate” behavior for the link).In this case, the link is followed only if the user releases the pointerbutton when the pointer is over the link.

When dealing with structured text such as hypertext, it’s a good ideato break the text down into nodes. Define a data structure for thesenodes, defining the type of node and any data associated with thenode. Create a range of text for each node, attaching a pointer to thenode as the Pt MT TAG attribute for the range, and add the range tothe widget. The text’s original structure can be obtained in callbacksby looking at the tag in the attributes member of the callback datastructure.

The following illustrates a simple node structure, allowing either plaintext or a hypertext link:

typedef enum text node enum { tnText, tnHyperlink }



TextNodeType t;typedef text node str {

TextNodeType t type;void *data;

} TextNode t;

The following code illustrates how a hypertext link can be activatedwithin a multiline text widget:

struct line str {TextNode t node;char *text;

} lines[] = {{ {tnText, NULL}, "Click " },{ {tnHyper, (void *)"file.html#id"}, "here" },{ {tnText, NULL}, " to follow a hypertext link"}

};

intfollow link(PtWidget t *widget, void *client data,


PtMultiTextCallback t *cbs =(PtTextCallback t *)info->cbdata;

if (info->reason == Pt CB MOTION VERIFY &&info->event != NULL &&(info->event->type & Ph EV BUT PRESS))

{TextNode t *node =

(TextNode t *)cbs->attributes->tag;printf("URL referenced: %s\n", node->data);


}

voidinit text(PtWidget t *text){

PtMultiTextAttributes t reg, hyper;int nlines;

PtMultiTextCreateAttributes(&reg);PtMultiTextCreateAttributes(&hyper);hyper.text color = Pg DGREEN;for (nlines = 0; nlines < sizeof(lines)/

sizeof(lines[0]); nlines++){

PtMultiTextAttributes t *attr =



lines[nlines].node.type == tnHyper ? &hyper: ®

PtMultiTextModifyText (text, 0, 0, -1,lines[nlines].text,&lines[nlines].node,attr,Pt MT TAG|Pt MT FOREGROUND);

}PtAddCallback(text, Pt CB MOTION VERIFY, follow link,

NULL);}

The data member of a hyperlink node is assumed to be a stringindicating what action to take. In this case, it refers to anotherdocument to load by a URL of the form used by the PhotonHelpviewer.

Widget dimensions

As for all widgets, Pt ARG DIM holds the dimensions of aPtMultiText widget. For example, suppose you have a multitextwidget that can show four lines of text. If you type more than fourlines, say six lines, the widget displays a scrollbar to let you knowthere are more lines. Querying Pt ARG DIM gives the dimensions ofthe four lines of text.

If you need to determine the dimensions of the entire text — the sixlines in our example — you’ll need to calculate it as described below:

Use the Pt ARG MULTITEXT QUERY LINE resource to query thefirst line (line 1). This gives you information in the form of aPtMultiTextQuery t structure, which contains a pointer to aPtMultiTextLine t structure. The PtMultiTextLine t

structure contains a PhRect t structure (see the Photon LibraryReference) that specifies the extent for that line. Calculate thedimensions of the line as:

height = extent.lr.y - extent.ul.y + 1;width = extent.lr.x - extent.ul.x + 1;



The lines are organized as a linked list, using the next and previouspointers in the PtMultiTextLine t structure. Traverse all the linesuntil the next pointer is NULL, calculating:

� the sum of the heights

� the maximum width

When you’ve examined all the lines, you’ll have the “virtualdimensions” of the text input area (i.e. the area that the text wouldoccupy if it had enough room to do so)

If you have only one font in the PtMultiText widget, the method offinding the dimensions can be simplified. For example, to find thevirtual height, calculate the height of the first line and multiply it bythe number of lines.

Drag and Drop

If you select some text and hold down the Ctrl key, you can drag theselected text to a PtText, PtMultiText, PtTerminal, or PtTtywidget.

New resources:


Pt ARG MULTITEXT BOTTOM LINE long Scalar None(write-only)

Pt ARG MULTITEXT FLAGS long Flag Seebelow

Pt ARG MULTITEXT NUM LINES long Scalar 1 (read-only)

continued. . .




Pt ARG MULTITEXT NUM LINES VISIBLE short Scalar None(read-only)

Pt ARG MULTITEXT QUERY CHARACTER PtMultiTextQuery t * Complex None(read-only)

Pt ARG MULTITEXT QUERY LINE PtMultiTextQuery t * Complex None(read-only)

Pt ARG MULTITEXT RANGE ATTRIBUTES PtMultiTextControl t * Complex None

Pt ARG MULTITEXT ROWS long Scalar None(write-only —seebelow)

Pt ARG MULTITEXT SEGMENTS PtMultiLines t, short Array None(write-only)

Pt ARG MULTITEXT TABS int, int Array {20}

Pt ARG MULTITEXT TOP LINE long Scalar 1

Pt ARG MULTITEXT WRAP FLAGS short Flag Seebelow

Pt ARG MULTITEXT X SCROLL POS short Scalar 0

Pt ARG MULTITEXT Y SCROLL POS long Scalar 1

Pt ARG SCROLLBAR X DISPLAY unsigned short Scalar Pt NEVER

Pt ARG SCROLLBAR X HEIGHT unsigned short Scalar 0 (usescrollbardefaultof 15)

continued. . .




Pt ARG SCROLLBAR Y DISPLAY unsigned short Scalar Pt NEVER

Pt ARG SCROLLBAR Y WIDTH unsigned short Scalar 0 (usescrollbardefaultof 15)

The convenience functions can make it easier for you to use thecomplex resources. For more information, see “Conveniencefunctions,” below.

�

Pt ARG MULTITEXT BOTTOM LINE (write-only)


long Scalar None

Set the bottom line (top line + number of visible lines -1).

Pt ARG MULTITEXT FLAGS


long Flag Pt EMT SCROLL TO CURSOR

Flags that affect the appearance and behavior of the widget. The validbits are:

Pt EMT AUTOINDENT

Automatically indent a new line (when you press Enter) tomatch the previous line, by duplicating any leading whitespacecharacters.

Pt EMT FULL LINES

Draw a line of text only if there’s enough room for its ascendersand descenders.



Pt EMT FORCED SCROLL

Scroll down automatically if there’s a blank space at the bottomof the widget and lines of text above the top of it.

Pt EMT SCROLL TO CURSOR

Enable cursor tracking.

Pt ARG MULTITEXT NUM LINES (read-only)


long Scalar 1

The line number of the last line in the buffer. The first line is line 1,not 0.

Pt ARG MULTITEXT NUM LINES VISIBLE (read-only)


short Scalar None

The number of lines that are currently visible.

Pt ARG MULTITEXT QUERY CHARACTER (read-only)


PtMultiTextQuery t * Complex None

Use this resource to get information about a certain character. Thisresource is a complex one, so it needs special handling. When getting,set the arguments to PtSetArg() as follows:

value A pointer to an instance of a PtMultiTextQuery t

structure.

len The index of the character you want to be query. The indexof the first character is 0.



Pt ARG MULTITEXT QUERY LINE (read-only)


PtMultiTextQuery t * Complex None

Use this resource to get information about a certain line. Thisresource is a complex one, so it needs special handling. When getting,set the arguments to PtSetArg() as follows:

value A pointer to an instance of a PtMultiTextQuery t

structure.

len The index of the line to be queried. The index of the firstline is 1.

Pt ARG MULTITEXT RANGE ATTRIBUTES


PtMultiTextControl t * Complex None

This resource modifies/queries the attributes of a specified range. Thisresource is a complex one, so it needs special handling.

When setting this resource, set the arguments to PtSetArg() as follows:

value A pointer to an instance of a PtMultiTextControl t

structure.

len A bitmask indicating which attributes to affect in the range.The valid bits for this mask are:

� Pt MT FONT

� Pt MT FOREGROUND

� Pt MT TEXT COLOR

� Pt MT BACKGROUND

� Pt MT BACKGROUND COLOR



� Pt MT TAG

� Pt MT FLAGS

When getting the value of this resource, set the arguments toPtSetArg() as follows:

value The address of a pointer to a PtMultiTextInfo t

structure, which is the same as PtMultiTextControl t.

len A pointer to an instance of a PtTextCallback t structurethat defines the range you want to query.

Pt ARG MULTITEXT ROWS (write-only)


long Scalar None (see below)

Specifies the number of rows. Setting this resource sets the widget’sheight dimension based on the height of the current font and numberof rows specified. There’s no default value for this resource becausethe widget initially uses its dimension to determine the number ofrows.

This is a “one-shot” resource; it changes the size of the widget whenyou set it, based on the widget’s current settings. If you later changethe font, the value of Pt ARG MULTITEXT ROWS isn’t used torecalculate the height of the widget.

�

Pt ARG MULTITEXT SEGMENTS (write-only)


PtMultiLines t, short Array None



This resource provides an easy way for you to define a multisegmentmessage. (A segment is a set of contiguous characters that sharecommon attributes, such as font, color, and so on.)

All the text provided in the PtMultiLines t array is concatenatedand used to replace the text in the Pt ARG TEXT STRING resource.The rest of the information in the array is used to build up an index ofsegments into the text. The array itself isn’t preserved within thewidget. Consequently, you should treatPt ARG MULTITEXT SEGMENTS as a write-only resource. Toretrieve the text, use the Pt ARG TEXT STRING resource.

Pt ARG MULTITEXT TABS


int, int Array {20}

Provides a means of specifying tab stops to the multitext widget. Thearray provided is an array of integers, each of which is a tab spacing,in pixels, relative to the last tab position. The last tab spacing isrepeated; for example, a tab array of {10,20,10} produces tab stops at10, 30, 40, 50, 60, ... pixels.

Pt ARG MULTITEXT TOP LINE


long Scalar 1

Set or get the top line or vertical scroll position, in lines (where thefirst line is line 1).

Pt ARG MULTITEXT WRAP FLAGS


short Flag Pt EMT WORD|Pt EMT NEWLINE



This resource controls how the multitext widget wraps. The possiblevalues are:

Pt EMT WORD

Wrap on word breaks.

Pt EMT CHAR

Wrap at the end of the line.

Pt EMT NEWLINE

Wrap on carriage returns.

If both the word and character wrap flags are on, word wrapping isapplied.

Pt ARG MULTITEXT X SCROLL POS


short Scalar 0

The horizontal scroll position (in pixels).

Pt ARG MULTITEXT Y SCROLL POS


long Scalar 1

Set or get the top line or vertical scroll position in lines, where thefirst line is line 1. This resource is the same asPt ARG MULTITEXT TOP LINE.

Pt ARG SCROLLBAR X DISPLAY




unsigned short Scalar Pt NEVER

This resource indicates when to display the horizontal scrollbar. Thepossible values are:

� Pt NEVER (default)

� Pt AS REQUIRED

� Pt ALWAYS

In order to display a horizontal scrollbar, you need to clearPt EMT WORD and Pt EMT CHAR in the widget’sPt ARG MULTITEXT WRAP FLAGS resource.

�

Pt ARG SCROLLBAR X HEIGHT


unsigned short Scalar 0 (use scrollbar default of 15)

The height of the horizontal scrollbar. If you set this resource to 0,widget uses the default size of 15.

Pt ARG SCROLLBAR Y DISPLAY


unsigned short Scalar Pt NEVER

This resource indicates when to display the vertical scrollbar. Thepossible values are:

� Pt NEVER (default)

� Pt AS REQUIRED

� Pt ALWAYS



Pt ARG SCROLLBAR Y WIDTH


unsigned short Scalar 0 (use scrollbar default of 15)

The width of the vertical scrollbar. If you set this resource to 0,widget uses the default size of 15.



Pt ARG ANCHOR FLAGS PtWidget 0 (no anchors)



Pt ARG BANDWIDTH THRESHOLD PtBasic Not used by thisclass.







Pt ARG COLUMNS PtText


continued. . .






Pt ARG CURSOR POSITION PtText 0


Pt ARG CURSOR TYPE PtWidget Ph CURSOR INSERT




Pt ARG DIM PtWidget

Pt ARG EFLAGS PtWidget &=˜Pt CONSUME EVENTS




Pt ARG FLAGS PtWidget |=Pt SET|Pt HIGHLIGHTED|Pt GETS FOCUS








continued. . .











Pt ARG MAX LENGTH PtText





Pt ARG POS PtWidget


Pt ARG SELECTION RANGE PtText


Pt ARG TEXT CURSOR WIDTH PtText



Pt ARG TEXT HIGHLIGHT BACKGROUND COLOR PtText

Pt ARG TEXT HIGHLIGHT TEXT COLOR PtText



continued. . .




Pt ARG TEXT SUBSTRING PtText







Pt CB ACTIVATE PtBasic See below

Pt CB ARM PtBasic






Pt CB DND PtWidget


Pt CB GOT FOCUS PtBasic See below



Pt CB LOST FOCUS PtBasic See below

Pt CB MENU PtBasic

Pt CB MODIFY NOTIFY PtText See below

Pt CB MODIFY VERIFY PtText See below

continued. . .




Pt CB MOTION NOTIFY PtText See below

Pt CB MOTION VERIFY PtText See below


Pt CB RAW PtWidget




Pt CB TEXT CHANGED PtText See below


Pt CB ACTIVATE

Pt CB ACTIVATE is inherited from PtBasic, but its behavior isdifferent for a PtMultiText widget. Each callback is passed aPtCallbackInfo t structure that contains at least the followingmembers:


reason subtype

Indicates why the callback was invoked:

� 0 — you clicked on the widget and it hasPt SELECTABLE set in its Pt ARG FLAGS.

� Pt EDIT ACTIVATE — you pressed Enter in the textfield.

� Pt CHANGE ACTIVATE — you modified the text, gavefocus to another widget, and Pt CHANGE ACTIVATE isset in the text widget’s Pt ARG TEXT FLAGS(inherited from PtText).




cbdata If reason subtype is 0, the callback data is as describedfor the Pt CB ACTIVATE resource for PtBasic.

If reason subtype is Pt EDIT ACTIVATE orPt CHANGE ACTIVATE, cbdata points to aPtMultiTextCallback t structure that contains atleast the following members:

PtTextCallback t tc;PtMultiTextAttributes t const *attributes;PtMultiTextSegment t *seg;void *extended data;

� The PtTextCallback t tc structure has thefollowing members:

int start pos;int end pos; All characters starting at start pos

up to but not including end pos areto be deleted. If start pos andend pos are equal, no characters areto be deleted.

int cur insert; The position at which text will beinserted. A value of 0 indicates thatthe text will be inserted to the left ofthe first character, 1 to the right ofthe first character, and so on.

int new insert; Where the cursor will be after thechanges are applied.

int length; The number of characters to beinserted. If length is zero, no text isbeing inserted, so the text field isinvalid.



char *text; The text to be inserted at cur insert.Before using text, check the lengthfield to make sure text contains validdata. In addition, note that textmight not be zero-terminated.

int doit; Indicates whether or not thismodification will be applied to thewidget. If doit is zero, the widgetdiscards the modification. If doit isnonzero, the widget uses thecontents of the callback structure tomodify itself.For more information, seePtTextModifyText() orPtMultiTextModifyText().

� PtMultiTextSegment t *seg is the text segmentthat contains the character indicated by cur insert. SeePtMultiTextSegment t.

� PtMultiTextAttributes t *attributes are theattributes associated with seg. SeePtMultiTextAttributes t.


Pt CB GOT FOCUS, Pt CB LOST FOCUS

Pt CB GOT FOCUS and Pt CB LOST FOCUS are inherited fromPtBasic, but the cbdata member of the callback information isdifferent for a PtMultiText widget.


reason The name of the callback resource that caused thiscallback to be invoked.

reason subtype

0 (not used).




cbdata A pointer to a PtMultiTextCallback t structure.

The members of the PtMultiTextCallback t structure are used asfollows:

� The PtTextCallback t tc structure has the following members:

int cur insert;

The position of the cursor along the string. Avalue of 0 indicates that the cursor is to the left ofthe first character, 1 to the right of the firstcharacter, and so on.

char *text; The beginning of the text string.

int length; The length of the text string (not including theNULL).

� PtMultiTextSegment t *seg is the text segment that containsthe character indicated by cur insert. SeePtMultiTextSegment t.

� PtMultiTextAttributes t *attributes are the attributesassociated with seg. See PtMultiTextAttributes t.

The Pt CB GOT FOCUS callbacks should return Pt CONTINUE.

The Pt CB LOST FOCUS callbacks should return:


Or:

� Pt END to keep it (for example, if you have to type something inthe text widget).



Pt CB TEXT CHANGED, Pt CB MODIFY NOTIFY, Pt CB MOTION NOTIFY

Pt CB TEXT CHANGED (Pt CB MODIFY NOTIFY), andPt CB MOTION NOTIFY are inherited from PtText but the cbdatamember of the callback information is different for a PtMultiTextwidget.



reason subtype

0 (not used).





int cur insert;

The position of the cursor along the string. Avalue of 0 indicates that the cursor is to the left ofthe first character, 1 to the right of the firstcharacter, and so on.

char *text; The beginning of the text string.

int length; The length of the text string (not including theNULL).






Pt CB MODIFY VERIFY

Pt CB MODIFY VERIFY is inherited from PtText, but the cbdatamember of the callback information is different for a PtMultiTextwidget.



reason subtype

0 (not used).





int start pos;int end pos; All characters starting at start pos up to but not

including end pos are to be deleted. If start posand end pos are equal, no characters are to bedeleted.

int cur insert; The position at which text will be inserted. Avalue of 0 indicates that the text will be insertedto the left of the first character, 1 to the right ofthe first character, and so on.



int new insert;

Where the cursor will be after the changes areapplied.

int length; The number of characters to be inserted. If lengthis zero, no text is being inserted, so the text fieldis invalid.

char *text; The text to be inserted at cur insert.

Before using text, check the length field to makesure text contains valid data. In addition, note thattext might not be zero-terminated.

int doit; Indicates whether or not this modification will beapplied to the widget. If doit is zero, the widgetdiscards the modification. If doit is nonzero, thewidget uses the contents of the callback structureto modify itself.

For more information, see PtTextModifyText() orPtMultiTextModifyText().




Pt CB MOTION VERIFY

Pt CB MOTION VERIFY (Pt CB MODIFY NOTIFY), is inheritedfrom PtText, but the cbdata member of the callback information isdifferent for a PtMultiText widget.





reason subtype

0 (not used).




int cur insert; The current position of the cursor. A value of 0indicates that the cursor is to the left of the firstcharacter, 1 to the right of the first character, andso on.

int start pos;int end pos;int new insert;

These all indicate the destination of the cursor atthe time the callback is invoked. A value of 0indicates that the cursor will be to the left of thefirst character, 1 to the right of the first character,and so on.

char *text; The string beginning at cur insert.

int length; The number of characters from the selectedcharacter to the end of the segment.

int doit; Indicates whether or not this modification will beapplied to the widget. If doit is zero, the cursorremains at cur insert. If doit is nonzero, thecursor will be repositioned at new insert.





If cbinfo->event is NULL, the cursor motion occurred because:

� Your application set a resource on this widget that affects thecursor position.

Or:

� The application called a function that repositioned the cursor.


Convenience functions:The PtMultiText widget defines several convenience functions anddata structures that make it easier to use the widget once it’s beencreated. Here’s a brief overview:

PtMultiLines t

Structure for setting multiline text and attributes

PtMultiTextAttributes t

Attributes for multiline text

PtMultiTextCallback t, PtMultiTextControl t

Information passed to PtMultiText callbacks

PtMultiTextCreateAttributes()

Initialize a multitext attribute structure.

PtMultiTextGetAttributes()

Get the attributes of a PtMultiText widget.

PtMultiTextInfo()

Get character/line information from a PtMultiText widget.

PtMultiTextInfo t

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


Get the selected range from a PtText widget.

PtTextModifyText()

Modify the contents of a PtText widget.


Set the selected range for a PtText widget.


2004, QNX Software Systems Ltd. PtMultiLines tStructure for setting multiline text and attributes

Synopsis:typedef struct{

char * string;char * font;PgColor t text color;PgColor t background color;

} PtMultiLines t;

Description:This structure is used to specify multiline text and its attributes. Youcan pass an array of these structures to the PtMultiText widget’sPt ARG MULTITEXT SEGMENTS resource.

The members include:

string The UTF-8 text string to display.

font The font used to render text. This must be specified asthe name of an existing font or as one of the followingspecial values:

Pt INHERIT FONT

Use the same font as the previous range.

Pt DEFAULT FONT

Use the value of the Pt ARG TEXT FONTresource.

To make text bold/italic, change the font to a bold/italic typeface.�

text color The color used for the text.

This must be set to a valid color (i.e. a variable of typePgColor t — see the Photon Library Reference) orone of the following special values:


PtMultiLines t 2004, QNX Software Systems Ltd.

Pt INHERIT COLOR

Use the same color as the previous range.

Pt DEFAULT COLOR

Use the value of the Pt ARG COLOR resource.

background color

The color used as a background for the text. This mustbe set to a valid color (i.e. a variable of typePgColor t) or one of the following special values:

Pt INHERIT COLOR


Pt DEFAULT COLOR

Use the value of the Pt ARG FILL COLORresource.


See also:PtMultiText, PtMultiTextAttributes t

PgColor t in the Photon Library Reference


2004, QNX Software Systems Ltd. PtMultiTextAttributes tAttributes for multiline text


char * font;PgColor t text color;PgColor t background color;int flags;void * tag;

} PtMultiTextAttributes t;

Description:This structure describes a set of attributes for multiline text:

font The font used to render text. This must be specified asthe name of an existing font or as one of the followingspecial values:

Pt INHERIT FONT

Use the same font as the previous range.

Pt DEFAULT FONT

Use the value of the Pt ARG TEXT FONTresource.

To make text bold/italic, change the font to a bold/italic typeface.�

text color The color used for the text.

This must be set to a valid color (i.e. a variable of typePgColor t — see the Photon Library Reference) orone of the following special values:

Pt INHERIT COLOR



PtMultiTextAttributes t 2004, QNX Software Systems Ltd.

Pt DEFAULT COLOR

Use the value of the Pt ARG COLOR resource.

background color

The color used as a background for the text. This mustbe set to a valid color (i.e. a variable of typePgColor t) or one of the following special values:

Pt INHERIT COLOR


Pt DEFAULT COLOR

Use the value of the Pt ARG FILL COLORresource.

flags For internal use.

tag To be used at your application’s discretion.


See also:PtMultiText, PtMultiTextInfo()

PgColor t in the Photon Library Reference


2004, QNX Software Systems Ltd. PtMultiTextCallback t,PtMultiTextControl t,

PtMultiTextInfo tInformation passed to PtMultiText callbacksSynopsis:

typedef struct{

PtTextCallback t tc;PtMultiTextAttributes t const *attributes;PtMultiTextSegment t *seg;void *extended data;

} PtMultiTextCallback t;

typedef PtMultiTextCallback t PtMultiTextControl t;typedef PtMultiTextControl t PtMultiTextInfo t;

Description:PtMultiTextCallback t, PtMultiTextControl t, andPtMultiTextInfo t are different names for the same structure.They’re used in callbacks for the PtMultiText widgets as well as tospecify actions or request data. The members of these structures are:

tc A pointer to a PtTextCallback t structure thatdescribes the affected text.

attributes A pointer to a PtMultiTextAttributes t

structure that describes the attributes of theaffected text.

seg A pointer to a PtMultiTextSegment t structurethat describes the segment of text that’s involved inthe modification that invoked the callback.

extended data A pointer to user data.



PtMultiTextCallback t,PtMultiTextControl t,PtMultiTextInfo t 2004, QNX Software Systems Ltd.

See also:PtMultiText, PtMultiTextAttributes t,PtMultiTextSegment t, PtTextCallback t


2004, QNX Software Systems Ltd. PtMultiTextCreateAttributes()Initialize a multitext attribute structure

Synopsis:PtMultiTextAttributes t *

PtMultiTextCreateAttributes(PtMultiTextAttributes t *attrs);

Description:This function initializes the specified PtMultiTextAttributes t

structure to default values. If you don’t specify aPtMultiTextAttributes t structure, one is allocated andinitialized.

Returns:A pointer to the initialized attributes structure, or NULL if no memorywas available.

Examples:See PtMultiTextGetAttributes().


Safety


Signal handler No

Thread No

See also:PtTextGetSelection(), PtTextModifyText(), PtTextSetSelection(),PtMultiTextAttributes t


PtMultiTextGetAttributes() 2004, QNX Software Systems Ltd.

Get the attributes of a PtMultiText widget

Synopsis:PtMultiTextAttributes t *

PtMultiTextGetAttributes(PtWidget t *widget,int char offset,PtMultiTextAttributes t *attributes,int *start,int *end );

Description:This function sets the provided PtMultiTextAttributes t

structure to the attributes found at char offset.

If you provide the integers for start and end, the function sets theseparameters to the character offsets that mark the beginning and end ofthe segment that contains char offset. Both start and end are 0-based.So, for example, if *start is set to 0, it indicates the first character inthe widget’s text buffer.

Returns:A pointer to the provided PtMultiTextAttributes t structure, orNULL if the specified widget is NULL or isn’t a PtMultiTextwidget.

Examples:/* Standard headers */#include <stdio.h>#include <stdlib.h>#include <unistd.h>#include <string.h>

/* Toolkit headers */#include <Ph.h>#include <Pt.h>#include <Ap.h>

/* Local headers */#include "editor.h"#include "abimport.h"#include "proto.h"


2004, QNX Software Systems Ltd. PtMultiTextGetAttributes()

intsave( PtWidget t *widget, ApInfo t *apinfo,

PtCallbackInfo t *cbinfo ){

PtArg t argt;FILE *fp;char *text;PtMultiTextAttributes t attrs;int start = 0, end = 0, len;

if( !(fp = fopen( "notepad", "w" ) ) )return Pt CONTINUE;

PtSetArg( &argt, Pt ARG TEXT STRING, &text, 0 );PtGetResources( ABW text, 1, &argt );len = strlen( text ) + 1;fwrite( &len, sizeof( len ), 1, fp );fwrite( text, len, 1, fp );PtMultiTextGetAttributes( ABW text, start,

&attrs, NULL, &end );while( end > start ){

fwrite( &start, sizeof( start ), 1, fp);fwrite( &end, sizeof( end ), 1, fp);fwrite( &attrs, sizeof( attrs ), 1, fp );if( attrs.font ){ len = strlen( attrs.font ) +1;

fwrite( &len, sizeof( len ), 1, fp );fwrite( attrs.font, len, 1, fp );

}start = end;PtMultiTextGetAttributes( ABW text, start,

&attrs, NULL, &end );}fclose( fp );widget = widget, apinfo = apinfo, cbinfo = cbinfo;return Pt CONTINUE;

}

int load( PtWidget t *widget, ApInfo t *apinfo,PtCallbackInfo t *cbinfo )

{PtArg t argt;FILE *fp;char *text;PtMultiTextAttributes t attrs;int start = -1, end = 0, len;

if( !(fp = fopen( "notepad", "r" ) ) )


PtMultiTextGetAttributes() 2004, QNX Software Systems Ltd.

return Pt CONTINUE;

fread( &len, sizeof( len ), 1, fp );if( !( text = (char *) malloc( len ) ) )

return Pt CONTINUE;

fread( text, len, 1, fp );

PtSetArg( &argt, Pt ARG TEXT STRING, text, 0 );PtSetResources( ABW text, 1, &argt );free( text );

while( fread( &start, sizeof( start ), 1, fp ) ){

fread( &end, sizeof( end ), 1, fp );fread( &attrs, sizeof( attrs ), 1, fp );if( attrs.font ){ fread( &len, sizeof( len ), 1, fp );

attrs.font = (char *) malloc( len );fread( attrs.font, len, 1, fp );

}PtMultiTextModifyAttributes( ABW text, start,

end, &attrs, -1 );if( attrs.font )

free( attrs.font );}fclose( fp );widget = widget, apinfo = apinfo, cbinfo = cbinfo;return Pt CONTINUE;

}


Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtMultiTextGetAttributes()

See also:PtMultiTextCreateAttributes(), PtTextGetSelection(),PtTextModifyText(), PtTextSetSelection(),PtMultiTextAttributes t


PtMultiTextInfo() 2004, QNX Software Systems Ltd.

Get character or line information from a PtMultiText widget

Synopsis:int PtMultiTextInfo( PtWidget t *widget,

int query type,int *char offset,int *line num,PtMultiTextLine t *line,int *start,int *end,int *length,PtMultiTextSegment t *seg,PtMultiTextAttributes t *attrs);

Description:This function gets information about a character or line within aPtMultiText widget.

Using the information returned in the provided integers and in thePtMultiTextLine t, PtMultiTextSegment t, andPtMultiTextAttributes t structures, you can determine:

� which line a character is on

� the start and end offsets of a given line

� the segment and attributes that exist at the beginning of a line

� the segment and attributes that exist at a given character offset.

Any argument representing information that you don’t require can beset to NULL. Any argument representing information you do requiremust point to an instance of the integers or structures of theappropriate type. The data returned is copied from the widget’sinternal structures into the structures provided.

The returned data may not remain valid for very long, so you shoulduse it immediately!

�

If you set query type to Pt MT QUERY LINE, then:


2004, QNX Software Systems Ltd. PtMultiTextInfo()

� line num must point to an instance of an int that specifies the linenumber on which information will be collected (the widget’s firstline is line 1, its second is line 2, and so on)

� line num will be set to the last line if the widget has fewer thanline num lines

� char offset, if provided, will be set to the offset of the firstcharacter of the line

� attrs, if provided, will be filled in with the attributes in effect at thebeginning of the line

If you set query type to Pt MT QUERY CHAR, then:

� char offset must point to an instance of an int that contains acharacter offset (the widget’s first character is 0, its second is 1,and so on)

� char offset will be set to the last character if the widget has fewerthan char offset characters

� attrs, if provided, will be filled in with the attributes in effect at thegiven char offset

Here’s what the function fills in when you provide a pointer to any ofthe following parameters:

line num The number of the line found by the query.

line The line structure for that line.

start The character offset of the first character in the line.

end The character offset of the last character in the line.

Both start and end are 0-based. So, for example, if*start is set to 0, it indicates the first character in thewidget’s text buffer.

length The number of characters in the line.


PtMultiTextInfo() 2004, QNX Software Systems Ltd.

seg The segment that contains char offset.

You could use this function to scroll to a specific line. For example, ifyou set Pt ARG CURSOR POSITION to the offset of a character online 35, the widget will scroll to line 35. (The PtMultiText widgetwill scroll as necessary, horizontally and vertically, to make the cursorvisible).

Returns:0 Success.

1 The provided widget is NULL or isn’t a PtMultiText widget.


Safety


Signal handler No

Thread No

See also:PtTextGetSelection(), PtTextModifyText(), PtTextSetSelection(),PtMultiTextAttributes t, PtMultiTextLine t,PtMultiTextSegment t


2004, QNX Software Systems Ltd. PtMultiTextLine tInformation about a line of text in a PtMultiText

Synopsis:typedef struct Pt emt text line{

unsigned int first char;unsigned int byte offset;ushort t num chars;PhRect t extent;PtMultiTextSegment t *segment;struct Pt emt text line *prev;struct Pt emt text line *next;

} PtMultiTextLine t;

Description:The PtMultiTextLine t structure describes a line of text asdisplayed in a PtMultiText widget.


first char The index into the entire string of the first character onthe line.

byte offset The offset into the entire string of the first character onthe line, in bytes.

num chars The number of characters on the line.

extent The PhRect t that specifies the extent of the line.

segment A pointer to the PtMultiTextSegment t structurethat describes the segment in effect at the start of theline.

prev A pointer to the PtMultiTextLine t structure forthe previous line.

next A pointer to the PtMultiTextLine t structure forthe next line.


PtMultiTextLine t 2004, QNX Software Systems Ltd.


See also:PtMultiText, PtMultiTextInfo(), PtMultiTextSegment t


2004, QNX Software Systems Ltd. PtMultiTextModifyAttributes()Modify the attributes of a PtMultiText widget

Synopsis:void PtMultiTextModifyAttributes(

PtWidget t *widget,int start,int end,PtMultiTextAttributes t const *attrs,int attributes mask );

Description:This function applies attributes to a range of characters within thespecified PtMultiText widget. All characters from start up to, butnot including, end are affected.

The attributes that this function applies are taken from the providedPtMultiTextAttributes t structure. Only the attributes specifiedin attributes mask are applied. The valid bits for this mask are:

� Pt MT FONT

� Pt MT FOREGROUND

� Pt MT TEXT COLOR

� Pt MT BACKGROUND

� Pt MT BACKGROUND COLOR

� Pt MT TAG

� Pt MT FLAGS

This function causes a nondestructive deselect before attempting thechanges.

�


PtMultiTextModifyAttributes() 2004, QNX Software Systems Ltd.

Examples:See PtMultiTextGetAttributes().


Safety


Signal handler No

Thread No



2004, QNX Software Systems Ltd. PtMultiTextModifyText()Modify the contents of a PtMultiText widget

Synopsis:void PtMultiTextModifyText(

PtWidget t *widget,int start,int end,int insert pos,char *text,int length,PtMultiTextAttributes t const *attrs,int attributes mask );

Description:This function modifies the contents and attributes of a PtMultiTextwidget.

If start doesn’t equal end, then:

� all characters from start up to but not including end are deleted

� the widget’s current insert position is set to the lesser of start andend

� insert pos is ignored.

If start does equal end, then:

� no text is deleted

� the widget’s current insert position is set to insert pos; if insert posequals -1, the current insert position is set to the end of thewidget’s text buffer.

Once the current insert position is set, the function inserts lengthcharacters from text. It does this regardless of the widget’s insertionmode. If length is 0, no text is inserted.

Here’s what happens after the function inserts the text into thesegment that contains the current insert position:

� The text inherits the segment’s attributes.


PtMultiTextModifyText() 2004, QNX Software Systems Ltd.

� The text is separated into its own segment, but keeps its inheritedvalues.

� The attributes specified by attributes mask are applied to the newsegment from the attrs structure provided. The valid bits for thismask are:

- Pt MT FONT

- Pt MT FOREGROUND

- Pt MT TEXT COLOR

- Pt MT BACKGROUND

- Pt MT BACKGROUND COLOR

- Pt MT TAG

- Pt MT FLAGS

This function causes a nondestructive deselect before attempting thechanges.

�


Safety


Signal handler No

Thread No



2004, QNX Software Systems Ltd. PtMultiTextQuery tStructure for getting information about a line or character


int character number;int line number;PtMultiTextLine t *line;PtMultiTextSegment t *segment;char *character;

} PtMultiTextQuery t;

Description:This structure is used to get information about a specified line orcharacter in a PtMultiText widget. You’ll use it when getting thevalue of Pt ARG MULTITEXT QUERY CHARACTER orPt ARG MULTITEXT QUERY LINE. When getting these resources,use the len member of the PtArg t structure (see the Photon LibraryReference) to indicate the character or line to be queried. When youget call PtGetResources(), the members of thePtMultiTextQuery t structure are filled in:

character number

The index into the string of the character queried.Characters are numbered from 0.

line number The index of the line queried. Lines are numberedfrom 1.

line A pointer to the PtMultiTextLine t structurethat describes the line queried or the line thatcontains the character queried.

segment A pointer to the PtMultiTextSegment t structurein effect for the character queried or at the beginningof the line queried.

character The character queried or the first character of the linequeried.


PtMultiTextQuery t 2004, QNX Software Systems Ltd.


See also:PtMultiText, PtMultiTextSegment t, PtMultiTextLine t


2004, QNX Software Systems Ltd. PtMultiTextSegment tInformation about a segment of text in a PtMultiText

Synopsis:typedef struct Pt emt text segment{

PtMultiTextAttributes t attrs;int first char;int num chars;struct Pt emt text segment *prev;struct Pt emt text segment *next;

} PtMultiTextSegment t;

Description:This structure that describes a segment of text in a PtMultiTextwidget. A segment is a block of text for which some attributes (suchas color and font) are set. The members of thePtMultiTextSegment t structure are:

attrs The PtMultiTextAttributes t structure thatdescribes the attributes in effect for this segment oftext.

first char The multibyte (UTF-8) offset to the first character inthe segment. This isn’t the byte offset to the firstcharacter in the segment.

num chars The number of multibyte (UTF-8) characters in thesegment.

prev, next Pointers to the previous and next segments in thePtMultiText widget.



PtMultiTextSegment t 2004, QNX Software Systems Ltd.

See also:PtMultiText, PtMultiTextAttributes t


2004, QNX Software Systems Ltd. PtNumericA superclass for numeric widgets

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


� PtNumericFloat

� PtNumericInteger


Public header:<photon/PtNumeric.h>

Description:PtNumeric is a parent class for all numeric widgets. It creates aPtText widget and arrows to let you interact with the widget. It alsocreates some of the base functionality of numeric widgets.

New resources:


Pt ARG NUMERIC FLAGS long Flag See below

Pt ARG NUMERIC PREFIX char * String NULL

Pt ARG NUMERIC SPACING int Scalar 1

Pt ARG NUMERIC SUFFIX char * String NULL

Pt ARG NUMERIC UPDOWN WIDTH int Scalar 17


PtNumeric 2004, QNX Software Systems Ltd.

Pt ARG NUMERIC FLAGS


long Flag Pt NUMERIC ENABLE UPDOWN |Pt NUMERIC WRAP |Pt NUMERIC AUTO HIGHLIGHT

Flags that control the widget’s appearance and behavior; anycombination of:

Pt NUMERIC AUTO HIGHLIGHT

Autohighlight text when selected.

Pt NUMERIC ENABLE UPDOWN

Display the up/down buttons.

Pt NUMERIC HEXADECIMAL

Display the value as a hexadecimal number (applies only toPtNumericInteger).

Pt NUMERIC USE SEPARATORS

Insert comma separators in values (e.g. 1,000).

Pt NUMERIC WRAP

Wrap numbers from minimum to maximum and frommaximum to minimum.

Pt ARG NUMERIC PREFIX


char * String NULL

A prefix string to be added to all entered values.


2004, QNX Software Systems Ltd. PtNumeric

Pt ARG NUMERIC SPACING


int Scalar 1

The spacing, in pixels, between the text field and the up/down buttons.

Pt ARG NUMERIC SUFFIX


char * String NULL

A suffix string to be added to all entered values.

Pt ARG NUMERIC UPDOWN WIDTH


int Scalar 17

The width, in pixels, of the PtScrollbar widget.

Exported subordinate children:Unless the resources are already defined in PtNumeric, thePtNumeric class uses the resources of its exported subordinate child,PtScrollbar.

The PtNumeric class “inherits” all the resources of its exportedsubordinate child. Where PtNumeric and its exported subordinatechild both define resources having the same name, the resourcedefined in PtNumeric takes precedence.








Pt ARG ARM COLOR PtButton

Pt ARG ARM FILL PtButton Pg GRAY

Pt ARG ARM IMAGE PtButton








Pt ARG CONTAINER FLAGS PtContainer Not used by this class.








Pt ARG DIM PtWidget


continued. . .


2004, QNX Software Systems Ltd. PtNumeric


















Pt ARG POS PtWidget

Pt ARG RESIZE FLAGS PtWidget Pt RESIZE Y ALWAYS |Pt RESIZE X AS REQUIRED






continued. . .






Pt CB ARM PtBasic






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






2004, QNX Software Systems Ltd. PtNumericFloatFloating-point numeric widget

Class hierarchy:PtWidget → PtBasic → PtContainer → PtCompound →PtNumeric → PtNumericFloat

PhAB icon:

Public header:<photon/PtNumericFloat.h>

Description:The PtNumericFloat class is a numeric widget that lets you enterfloating-point values between given minimum and maximum values.You can also use an incorporated PtScrollbar to increase ordecrease the value by a set amount.

A PtNumericFloat widget.

In addition, you can use the resources defined by PtNumeric to addprefix and suffix strings, and use comma separators. You can usePt ARG NUMERIC PRECISION to specify the precision of thenumber (i.e. the number of decimal places, for example, 1,000.00).

PtNumericFloat defines several resources with a C type of double* and a Pt type of Struct. Remember that you can’t set and get themas if they were scalar values. Here’s how to set the widget’s value:

double number = 5.55;

PtSetResource (ABW base float, Pt ARG NUMERIC VALUE,&number, 0);

Here’s how to get the value:


PtNumericFloat 2004, QNX Software Systems Ltd.

double *number;

PtGetResource (ABW base float, Pt ARG NUMERIC VALUE,&number, 0);

printf ("Value is %f\n", *number);

PtNumericFloat isn’t included in the shared ph library because ituses floating-point operations. If you use it in a non-PhABapplication, link with the static library. For more information, seeCompiling and linking a non-PhAB application in the ProgrammingPhoton without PhAB chapter of the Photon Programmer’s Guide.

�

New resources:


Pt ARG NUMERIC INCREMENT double * Struct 1.0

Pt ARG NUMERIC MAX double * Struct 1000000.00

Pt ARG NUMERIC MIN double * Struct -1000000.00

Pt ARG NUMERIC PRECISION int Scalar 2

Pt ARG NUMERIC VALUE double * Struct 0.0

Pt CB NUMERIC CHANGED PtCallback t * Link NULL

Pt ARG NUMERIC INCREMENT


double * Struct 1.0

The value by which to increase or decrease the value when theup/down buttons are pressed.


2004, QNX Software Systems Ltd. PtNumericFloat

Pt ARG NUMERIC MAX


double * Struct 1000000.00

The maximum value for the widget.

Pt ARG NUMERIC MIN


double * Struct -1000000.00

The minimum value for the widget.

Pt ARG NUMERIC PRECISION


int Scalar 2

The precision or number of displayed decimal places of the widget’scurrent value.

Pt ARG NUMERIC VALUE


double * Struct 0.0

The current value of the widget.

Pt CB NUMERIC CHANGED





A list of PtCallback t structures that define the callbacks invokedwhen the widget’s value changes.

If the widget has the Pt CALLBACKS ACTIVE bit set in itsPt ARG FLAGS resource, these callbacks are also invoked when yourapplication changes the Pt ARG NUMERIC VALUE with a call toPtSetResource() or PtSetResources(), or if thePt ARG NUMERIC VALUE is changed indirectly by a change toPt ARG NUMERIC MIN or Pt ARG NUMERIC MAX.


reason Pt CB NUMERIC CHANGED

reason subtype

A subtype that indicates why the callback was invoked:

� Pt NUMERIC CHANGED — the text in the numeric’stext field has been changed.

� Pt NUMERIC SET — PtSetResource() orPtSetResources() was called to change the currentvalue.

� Pt NUMERIC UPDOWN ACTIVATE — a button waspressed to change the current value.

� Pt NUMERIC UPDOWN REPEAT — a button was helddown to change the current value.


cbdata A pointer to a PtNumericFloatCallback t structurethat contains at least:

� double numeric value — the current value of thewidget




Exported subordinate children:Unless the resources are already defined in PtNumericFloat, thePtNumericFloat class uses the resources of its exportedsubordinate child, PtScrollbar.

The PtNumericFloat class “inherits” all the resources of itsexported subordinate child. Where PtNumericFloat and itsexported subordinate child both define resources having the samename, the resource defined in PtNumericFloat takes precedence.



Pt ARG ANCHOR FLAGS PtWidget Not used by thisclass.

Pt ARG ANCHOR OFFSETS PtWidget Not used by thisclass.









continued. . .







Pt ARG CONTAINER FLAGS PtContainer Not used by thisclass.








Pt ARG DIM PtWidget












continued. . .








Pt ARG NUMERIC FLAGS PtNumeric

Pt ARG NUMERIC PREFIX PtNumeric

Pt ARG NUMERIC SPACING PtNumeric

Pt ARG NUMERIC SUFFIX PtNumeric

Pt ARG NUMERIC UPDOWN WIDTH PtNumeric



Pt ARG POS PtWidget










Pt CB ACTIVATE PtBasic See below.

Pt CB ARM PtBasic

continued. . .




Pt CB BALLOONS PtContainer Not used by thisclass.





Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget





Pt CB ACTIVATE

If cbinfo->reason subtype is Pt NUMERIC ACTIVATE, the callbackwas invoked because you changed the value and pressed Enter whilein PtNumericFloat’s text field.


2004, QNX Software Systems Ltd. PtNumericIntegerInteger numeric widget

Class hierarchy:PtWidget → PtBasic → PtContainer → PtCompound →PtNumeric → PtNumericInteger

PhAB icon:

Public header:<photon/PtNumericInteger.h>

Description:The PtNumericInteger class lets you specify integer valuesbetween given minimum and maximum values.

A PtNumericInteger widget.

A PtScrollbar widget is included to let you increase or decreasethe value by a set amount. You can use the resources defined byPtNumeric to add prefix and suffix strings, and use commaseparators (e.g. 1,000).

If you want the value to be displayed as a hexadecimal value, setPt NUMERIC HEXADECIMAL in Pt ARG NUMERIC FLAGS.

New resources:


Pt ARG NUMERIC INCREMENT int Scalar 1

continued. . .


PtNumericInteger 2004, QNX Software Systems Ltd.


Pt ARG NUMERIC MAX int Scalar INT MAX

Pt ARG NUMERIC MIN int Scalar INT MIN

Pt ARG NUMERIC VALUE int Scalar 0

Pt CB NUMERIC CHANGED PtCallback t * Link NULL

Pt ARG NUMERIC INCREMENT


int Scalar 1

The amount by which to increase or decrease the value when theup/down buttons are pressed.

Pt ARG NUMERIC MAX


int Scalar INT MAX

The maximum value for the widget.

Pt ARG NUMERIC MIN


int Scalar INT MIN

The minimum value for the widget.

Pt ARG NUMERIC VALUE


2004, QNX Software Systems Ltd. PtNumericInteger


int Scalar 0

The current value of the widget.

Pt CB NUMERIC CHANGED



A list of PtCallback t structures that define the callbacks invokedwhen the widget’s value changes.

If the widget has the Pt CALLBACKS ACTIVE bit set in itsPt ARG FLAGS resource, these callbacks are also invoked when yourapplication changes the Pt ARG NUMERIC VALUE with a call toPtSetResource() or PtSetResources(), or if thePt ARG NUMERIC VALUE is changed indirectly by a change toPt ARG NUMERIC MIN or Pt ARG NUMERIC MAX.


reason Pt CB NUMERIC CHANGED

reason subtype

A subtype that indicates why the callback was invoked:

� Pt NUMERIC CHANGED — the text in the numeric’stext field has been changed.

� Pt NUMERIC SET — PtSetResource() orPtSetResources() was called to change the currentvalue.

� Pt NUMERIC UPDOWN ACTIVATE — a button waspressed to change the current value.

� Pt NUMERIC UPDOWN REPEAT — a button was helddown to change the current value.




cbdata A pointer to a PtNumericIntegerCallback t

structure that contains at least:

� int numeric value — the current value of the widget.


Exported subordinate children:Unless the resources are already defined in PtNumericInteger, thePtNumericInteger class uses the resources of its exportedsubordinate child, PtScrollbar.

The PtNumericInteger class “inherits” all the resources of itsexported subordinate child. Where PtNumericInteger and itsexported subordinate child both define resources having the samename, the resource defined in PtNumericInteger takes precedence.



Pt ARG ANCHOR FLAGS PtWidget Not used by thisclass.

Pt ARG ANCHOR OFFSETS PtWidget Not used by thisclass.



continued. . .













Pt ARG CONTAINER FLAGS PtContainer Not used by thisclass.








Pt ARG DIM PtWidget





continued. . .















Pt ARG NUMERIC FLAGS PtNumeric

Pt ARG NUMERIC PREFIX PtNumeric

Pt ARG NUMERIC SPACING PtNumeric

Pt ARG NUMERIC SUFFIX PtNumeric

Pt ARG NUMERIC UPDOWN WIDTH PtNumeric



Pt ARG POS PtWidget





continued. . .










Pt CB ARM PtBasic

Pt CB BALLOONS PtContainer Not used by thisclass.





Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget



continued. . .






Pt CB ACTIVATE

If cbinfo->reason subtype is Pt NUMERIC ACTIVATE, the callbackwas invoked because you changed the value and pressed Enter whilein PtNumericInteger’s text field.


2004, QNX Software Systems Ltd. PtOnOffButtonAn on/off button that can be set or unset

Class hierarchy:PtWidget -> PtBasic -> PtLabel -> PtButton ->PtOnOffButton

PhAB icon:

Public header:<photon/PtOnOffButton.h>

Description:A PtOnOffButton widget displays an on/off button that can be setor unset. Instances of this class of widget are typically used inexclusive or nonexclusive groups.

A PtOnOffButton widget.

New resources:


Pt ARG ONOFF STATE short Scalar 0 (off)

Pt CB ONOFF NEW VALUE PtCallback t * Link NULL


PtOnOffButton 2004, QNX Software Systems Ltd.

Pt ARG ONOFF STATE


short Scalar 0 (off)

The current state of the on/off button. If the button is off, this resourceis 0; if the button is on, it’s nonzero.

Pt CB ONOFF NEW VALUE



A list of PtCallback t structures that define the callbacks that thewidget invokes when the state of the on/off button changes.

If you’ve set the Pt CALLBACKS ACTIVE bit set in the widget’sPt ARG FLAGS resource, these callbacks are also invoked when yourapplication changes the state of the button by calling PtSetResource()or PtSetResources().


reason Pt CB ONOFF NEW VALUE

reason subtype

0 (not used).


cbdata A pointer to a PtOnOffButtonCallback t structurethat contains at least the following member:

int state; The current state of the on/off button.



2004, QNX Software Systems Ltd. PtOnOffButton









Pt ARG ARM FILL PtButton













continued. . .









Pt ARG DIM PtWidget





Pt ARG FLAGS PtWidget |=Pt SELECTABLE&=˜Pt TOGGLE













continued. . .


2004, QNX Software Systems Ltd. PtOnOffButton












Pt ARG POS PtWidget













continued. . .







Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget





2004, QNX Software Systems Ltd. PtOSContainerOffscreen-context container for flicker-free drawing

Class hierarchy:PtWidget → PtBasic → PtContainer → PtOSContainer

PhAB icon:

Public header:<photon/PtOSContainer.h>

Description:PtOSContainer creates an offscreen context and forces all itschildren’s draws to be directed to that context. The draw stream isrendered into offscreen video memory, taking advantage of anyhardware-acceleration features supported by the graphics driver. Thegraphics hardware can then blit the image directly onto the screen,resulting in flicker-free widgets and/or animation.

When you unrealize a PtOSContainer widget, its offscreen memoryis automatically released. When you rerealize the widget, theoffscreen memory is reallocated.

�





continued. . .


PtOSContainer 2004, QNX Software Systems Ltd.


















Pt ARG DIM PtWidget



Pt ARG FILL COLOR PtBasic See below.




continued. . .


2004, QNX Software Systems Ltd. PtOSContainer













Pt ARG POS PtWidget









Pt CB ARM PtBasic



continued. . .


PtOSContainer 2004, QNX Software Systems Ltd.





Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget





Pt ARG FILL COLOR

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


2004, QNX Software Systems Ltd. PtPaneA container for organizing widgets

Class hierarchy:PtWidget → PtBasic → PtContainer → PtPane

PhAB icon:

Public header:<photon/PtPane.h>

Description:PtPane is a container widget that’s useful for logically or visuallygrouping widgets in an application. Any child widgets that extendbeyond the canvas of the PtPane widget are clipped.

A dialog box featuring several PtPane widgets.



PtPane 2004, QNX Software Systems Ltd.


Pt ARG ANCHOR FLAGS PtWidget Pt LEFT ANCHORED LEFT|Pt RIGHT ANCHORED LEFT|Pt TOP ANCHORED TOP|Pt BOTTOM ANCHORED TOP




Pt ARG BASIC FLAGS PtBasic Pt ALL OUTLINES |Pt ALL BEVELS |Pt FLAT FILL













Pt ARG DIM PtWidget


continued. . .


2004, QNX Software Systems Ltd. PtPane





Pt ARG FLAGS PtWidget Pt HIGHLIGHTED













Pt ARG POS PtWidget







continued. . .


PtPane 2004, QNX Software Systems Ltd.




Pt CB ARM PtBasic






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






2004, QNX Software Systems Ltd. PtPanelGroupA container that manages panels

Class hierarchy:PtWidget → PtBasic → PtContainer → PtPanelGroup

PhAB icon:

Public header:<photon/PtPanelGroup.h>

Description:A PtPanelGroup is a container that manages panels and optionallyprovides a method for you to switch between them.

A PtPanelGroup widget as used in PhAB.

PtPanelGroup provides two modes to switch between panels:

Multiple tabs As shown above, there’s one tab per panel — clickon a tab to select a panel.

Single tab When you click on the tab, a popup menu lets youselect a panel:


PtPanelGroup 2004, QNX Software Systems Ltd.

You can make the PtPanelGroup switch automatically betweenthese two selection modes as necessary, depending on the availablespace — single-tab mode is useful when there isn’t much horizontalspace. For more information, see Pt ARG PG SELECTION MODE.

Populating a panel group

You can populate a PtPanelGroup in the following ways, dependingon your requirements:

� Multiple panels, created at design time

� Single panel, repopulated at runtime.

� A PtPanelGroup can use only one population method; you can’tadd some panels at design time and others at runtime. However,you can add an empty container and populate it at runtime whenyou switch panels.

� If you use the single-panel method to populate the PtPanelGroupat runtime, you can’t drag and drop the panels, to avoid thecomplexity of having different (and possibly conflicting)population methods coexisting in the same panel group.

�


2004, QNX Software Systems Ltd. PtPanelGroup

When you design the UI for your application, you can put containerMultiplepanels widgets (i.e. descendants of PtContainer) into a PtPanelGroup.

PtPanelGroup manages these containers and incorporates them intothe selection mechanism (i.e. it assigns tabs to them).

The panel group extracts the titles for the panels from theirPt ARG TITLE resources.

This method gives you complete control over the layout in anapplication-building environment (for example, PhAB). Thedrawback to this method is that it requires more memory at runtime,since all of the widgets in all of the panels exist for the lifetime of thePtPanelGroup.

To add panels to a PtPanelGroup in PhAB, select a container widgetfrom the palette and click on the PtPanelGroup. The container isautomatically sized to fit the panel group. When you add other panels,click on the top part of the panel group (i.e. above the existing panelsand tabs). Use the Module Tree control panel to verify that the panelsare where you want them (for more information, see the chapter onPhAB’s environment in the Photon Programmer’s Guide).

To flip between existing panels in PhAB, select the PtPanelGroupand change Pt ARG PG CURRENT INDEX to the number of thepanel you wish to edit.

At runtime, your application’s code can clear and repopulate theSingle panel

PtPanelGroup when a new panel is selected. This method mightsave a significant amount of memory at runtime, but it’s lessconvenient than the first method, since it requires some code tointercept the panel switching and to repopulate the panel group’sdisplay.

This method yields slower switches, since your application must clearthe panel group’s display and then reconstruct it each time you selecta different panel. However, you can design the individual panels inPhAB (as picture modules) and then use PtClearWidget() andApCreateModule() whenever you switch panels.



If you choose this method to populate a PtPanelGroup, use thePt ARG PG PANEL TITLES resource to specify number of panelsand their titles.

For an example of using this method, seePt CB PG PANEL SWITCHING.

Panel margins

PtPanelGroup defines its own margins in addition to the marginwidth defined by the PtBasic widget class. There are separate left,right, top, and bottom margins, which are specified using theseresources:





These margins are cumulative, so that the actual margin of one edgeof the widget is the corresponding resource value added to the marginwidth.

Panel indexes

Panels are indexed from 0 through n - 1, where n is the number ofpanels managed by the PtPanelGroup. An index value ofPt PG INVALID may be interpreted as a “NULL” value.

The panel indexes indicate the order of panels in the PtPanelGroup;they change when panels are added, removed, or reordered.

�

New resources:




Pt ARG MARGIN BOTTOM unsigned short Scalar 5

Pt ARG MARGIN LEFT unsigned short Scalar 5

Pt ARG MARGIN RIGHT unsigned short Scalar 5

Pt ARG MARGIN TOP unsigned short Scalar 3

Pt ARG PG CURRENT char * String NULL

Pt ARG PG CURRENT INDEX uint16 t Scalar Pt PG INVALID

Pt ARG PG FLAGS ushort t Flag 0x0

Pt ARG PG OVERLAP THRESHOLD uchar t Scalar 128

Pt ARG PG PANEL TITLES char **, ushort t Array NULL

Pt ARG PG SELECTION MODE uchar t Scalar Pt PG AUTO

Pt CB PG PANEL SWITCHING PtCallback t * Link NULL

Pt ARG MARGIN BOTTOM



The amount of space between the bottom of the panel group’s canvasand the canvas defined by the basic widget.

Pt ARG MARGIN LEFT



The amount of space between the left side of the panel group’s canvasand the canvas defined by the basic widget.



Pt ARG MARGIN RIGHT



The amount of space between the right side of the panel group’scanvas and the canvas defined by the basic widget.

Pt ARG MARGIN TOP



The amount of space between the top of the panel group’s canvas andthe canvas defined by the basic widget.

Pt ARG PG CURRENT


char * String NULL

The name of the currently selected panel.

You can set this resource to switch to another panel. If more than onepanel has the same title, the widget switches to the first one it findswith the specified title.

Pt ARG PG CURRENT INDEX


uint16 t Scalar Pt PG INVALID

The index of the currently selected panel, where 0 indicates the firstpanel. You can set this resource to switch to another panel.



Pt ARG PG FLAGS


ushort t Flag 0x0

This resource controls the behavior of the PtPanelGroup. Possiblevalues are:

Pt PG DND Support drag-and-drop operations of container-typewidgets.

Panels that are dragged away from thePtPanelGroup are reparented to another container ifone is present at the drop site and it also supportsdrag-and-drop operations. Otherwise a popupwindow is created at the drop site with a newPtPanelGroup to display the panel.

If the panel group is populated at runtime,drag-and-drop isn’t supported and this flag is ignored.

Pt PG MULTI CONTAINER MODE (read-only)

The PtPanelGroup was populated with more thanone container. You can’t set or clear this bit; thewidget sets or clears this bit to reflect its state.

Pt PG SELECTOR ALIGN RIGHT

Align the tab or tabs to the right of thePtPanelGroup instead of the left.Pt ARG MARGIN WIDTH controls the amount thatthe selector is inset from the edge.

Pt PG SELECTOR ON BOTTOM

Place the tab or tabs at the bottom of thePtPanelGroup instead of at the top.

Pt PG TABS EQUAL SIZE

Force all tabs to be the same size. If this bit isn’t set,tabs occupy as little space as possible to



accommodate their displayable data, and changing thesize of one tab doesn’t affect the sizes of the others.

Pt PG USE PANEL COLORS

Let each tab specify its own color. This flag worksonly when the panelgroup has multiple containers; thetext and fill color for the tab are retrieved from thePt ARG COLOR and Pt ARG FILL COLORresources of the corresponding panel.

Pt ARG PG OVERLAP THRESHOLD


uchar t Scalar 128

The amount by which tabs can overlap before switching to/fromsingle-tab selection mode (providing the selection type is set toPt PG AUTO).

This quantity is specified as an integer between 0 and 255 andrepresents a fraction of tab width. For example, a value of 0 doesn’tlet tabs overlap at all, while a value of 128 lets tabs overlap by up tohalf their width.

If you set this to too large a value, it might be difficult to use the tabs.�

Pt ARG PG PANEL TITLES


char **, ushort t Array NULL

The titles for the panels managed by this PtPanelGroup.



If the PtPanelGroup is populated with multiple containers,Pt ARG PG PANEL TITLES is a read-only resource.

�

When you get the value of this resource, it gives the titles of thepanels and the number of panels, regardless of how the panel groupwas populated.

Pt ARG PG SELECTION MODE


uchar t Scalar Pt PG AUTO

This resource indicates the method you’ll use to select panels. One of:

Pt PG NONE Don’t use an internal selector. When this mode is inuse, panels must be selected programmatically (bysetting the Pt ARG PG CURRENT orPt ARG PG CURRENT INDEX resource).

Pt PG AUTO Display one tab per panel as long as there’s enoughspace, depending on the sizes of the tabs and thePt ARG PG OVERLAP THRESHOLD resource. Ifthere isn’t enough space, display a single tab that,when selected, provides a popup list of panels.

Pt PG SINGLE TAB

Use single-tab selection mode, regardless of thespace available.

Pt CB PG PANEL SWITCHING





A list of PtCallback t structures that define the callbacks that areinvoked when a new panel is selected. This resource lets you clearand repopulate the display container (if necessary), set up resources ofexisting panels (if applicable), or prevent the switch by returning avalue other than Pt CONTINUE.

If the widget has the Pt CALLBACKS ACTIVE bit set in itsPt ARG FLAGS resource, these callbacks are also invoked when yourapplication changes Pt ARG PG CURRENT orPt ARG PG CURRENT INDEX by calling PtSetResource() orPtSetResources().


reason Pt CB PG PANEL SWITCHING

reason subtype

Not used.

event A pointer to a PhEvent t structure that describes theevent that caused the callback to be invoked. If event isNULL, then the callback was invoked because theselection was changed programmatically.

cbdata A pointer to a PtPanelGroupCallback t structure thatcontains at least:

� char *old panel — the title of the panel that waspreviously selected, or NULL if no panel waspreviously selected.

� char *new panel — the title of the newly selectedpanel, or NULL if no panel is being selected.

� uint16 t old panel index — the index of the panelthat was previously selected, or Pt PG INVALID if nopanel was previously selected

� uint16 t new panel index — the index of the newlyselected panel, or Pt PG INVALID if no panel is beingselected.



The panel indexes indicate the order of panels in the PtPanelGroup;they change when panels are added, removed, or reordered.

�

These callbacks should return Pt CONTINUE to permit the switch tooccur. Returning a value other than Pt CONTINUE prevents the switchfrom taking place. This is useful if you want to “lock” thePtPanelGroup to the currently selected panel.

For example, to clear and repopulate a PtPanelGroup at runtime ina Pt CB PG PANEL SWITCHING callback:

int panelswitch cb( PtWidget t *widget,ApInfo t *apinfo,PtCallbackInfo t *cbinfo)

{PtPanelGroupCallback t *pgcb =(PtPanelGroupCallback t*)(cbinfo->cbdata);

/* We use some arbitrary user function that returnsnonzero if switch is ok */

if(!switch ok(widget))/* Prevent the switch from happening */return(Pt END);

/* Clear the PtPanelGroup display */

PtClearWidget(widget);

/* Here we use the panel indexes rather than titlesto figure out current panel. This is deterministic,provided the Pt ARG PG PANEL TITLES resourceisn’t changed. */

switch(pgcb->new panel index){

case 0:

/* Populate the display. Note that we providewidget (the PtPanelGroup pointer) as theparent. In this case, PtPanelGroup acceptsthe widgets as children. */

ApCreateModule(ABM pic module 0,widget,NULL);PtReRealizeWidget( widget );break;



case 1:

ApCreateModule(ABM pic module 1,widget,NULL);PtReRealizeWidget( widget );break;

...}

return(Pt CONTINUE); /* Let the switch proceed */}







Pt ARG BASIC FLAGS PtBasic Pt ALL OUTLINES








continued. . .










Pt ARG DIM PtWidget

















continued. . .





Pt ARG POS PtWidget









Pt CB ARM PtBasic






Pt CB DND PtWidget






Pt CB MENU PtBasic

continued. . .





Pt CB RAW PtWidget





Convenience functions:The PtPanelGroup widget defines the following conveniencefunctions:

PtPGCreatePopup()

Create an empty copy of a panel group as a popup window

PtPGFindIndexByPanel()

Get the index for a panel, given a pointer to the panel

PtPGFindIndexByTitle()

Get the index of a panel, given its title

PtPGFindPanelByIndex()

Get a pointer to the panel widget with a given index

PtPGFindPanelByTitle()

Get a pointer to the panel widget with a given title

PtPGFindTitleByIndex()

Get the title of the panel with a given index


PtPGCreatePopup() 2004, QNX Software Systems Ltd.

Create an empty copy of a panel group as a popup window

Synopsis:PtWidget t *PtPGCreatePopup( PtWidget t *widget,

PhPoint t const *pos );

Description:This function creates an empty copy of the PtPanelGroup specifiedby widget, in the form of a popup window. The popup window ispositioned at pos, or at (0,0) if pos is NULL.

PtPGCreatePopup() copies the following resources into the new panelgroup:

� Pt ARG ANCHOR FLAGS

� Pt ARG BASIC FLAGS

� Pt ARG BEVEL WIDTH

� Pt ARG BITMAP CURSOR

� Pt ARG COLOR

� Pt ARG CONTAINER FLAGS

� Pt ARG CURSOR COLOR

� Pt ARG CURSOR TYPE

� Pt ARG DIM

� Pt ARG EFLAGS

� Pt ARG FILL COLOR

� Pt ARG FILL PATTERN

� Pt ARG FLAGS

� Pt ARG HELP TOPIC



2004, QNX Software Systems Ltd. PtPGCreatePopup()




� Pt ARG MARGIN HEIGHT

� Pt ARG MARGIN WIDTH

� Pt ARG PG FLAGS

� Pt ARG PG SELECTION MODE

� Pt ARG RESIZE FLAGS

� Pt ARG TRANS PATTERN

� Pt CB BALLOONS

� Pt CB BLOCKED

� Pt CB CHILD ADDED REMOVED

� Pt CB DESTROYED

� Pt CB FILTER

� Pt CB GOT FOCUS

� Pt CB HOTKEY

� Pt CB LOST FOCUS

� Pt CB MENU

� Pt CB PG PANEL SWITCHING

� Pt CB REALIZED

� Pt CB RESIZE

� Pt CB UNREALIZED


PtPGCreatePopup() 2004, QNX Software Systems Ltd.

Returns:A pointer the to new PtPanelGroup widget, or NULL if there wasn’tenough memory.

To realize or otherwise manipulate the popup window, do it to thepanel group’s parent (using the PtWidgetParent() macro).

�


Safety


Signal handler No

Thread No

See also:PtPanelGroup

PhPoint t, PtWidgetParent() in the Photon Library Reference


2004, QNX Software Systems Ltd. PtPGFindIndexByPanel()Get the index of a panel, given a pointer to the panel

Synopsis:int PtPGFindIndexByPanel( PtWidget t *widget,

PtWidget t const *panel );

Description:This function retrieves the index for a specified panel within thePtPanelGroup specified by the widget argument.

Returns:The panel index, or Pt PG INVALID if the panel couldn’t be found, orif the PtPanelGroup isn’t in multiple-container mode.


Safety


Signal handler No

Thread No

See also:PtPanelGroup, PtPGFindIndexByTitle(), PtPGFindPanelByIndex(),PtPGFindPanelByTitle(), PtPGFindTitleByIndex()


PtPGFindIndexByTitle() 2004, QNX Software Systems Ltd.

Get the index of a panel, given its title

Synopsis:int PtPGFindIndexByTitle( PtWidget t *widget,

char const *title );

Description:This function retrieves the index of the panel with the specified titlewithin the PtPanelGroup specified by the widget argument.

Returns:The panel index, or Pt PG INVALID if the panel couldn’t be found.


Safety


Signal handler No

Thread No

See also:PtPanelGroup, PtPGFindIndexByPanel(),PtPGFindPanelByIndex(), PtPGFindPanelByTitle(),PtPGFindTitleByIndex()


2004, QNX Software Systems Ltd. PtPGFindPanelByIndex()Get a pointer to the panel widget with a given index

Synopsis:PtWidget t *PtPGFindPanelByIndex( PtWidget t *widget,

int panel );

Description:This function retrieves the panel associated with the specified panelindex within the PtPanelGroup specified by the widget argument.

Returns:A pointer to the panel widget, or NULL if the specified panel doesn’texist or the PtPanelGroup isn’t in multiple-container mode.


Safety


Signal handler No

Thread No

See also:PtPanelGroup, PtPGFindIndexByPanel(), PtPGFindIndexByTitle(),PtPGFindPanelByTitle(), PtPGFindTitleByIndex()


PtPGFindPanelByTitle() 2004, QNX Software Systems Ltd.

Get a pointer to the panel widget with a given title

Synopsis:PtWidget t *PtPGFindPanelByTitle( PtWidget t *widget,

char const *title );

Description:This function retrieves the panel with the specified title within thePtPanelGroup specified by the widget argument.

Returns:A pointer to the panel widget, or NULL if the panel couldn’t be foundor the PtPanelGroup isn’t in multiple-container mode.


Safety


Signal handler No

Thread No

See also:PtPanelGroup, PtPGFindIndexByPanel(), PtPGFindIndexByTitle(),PtPGFindPanelByIndex(), PtPGFindTitleByIndex()


2004, QNX Software Systems Ltd. PtPGFindTitleByIndex()Get the title of the panel with a given index

Synopsis:char *PtPGFindTitleByIndex( PtWidget t *widget,

int index );

Description:This function retrieves the title of the panel with the specified indexwithin the PtPanelGroup specified by the widget argument.

Returns:A pointer to the title of the specified panel, or NULL if the specifiedpanel doesn’t exist.


Safety


Signal handler No

Thread No

See also:PtPanelGroup, PtPGFindIndexByPanel(), PtPGFindIndexByTitle(),PtPGFindPanelByIndex(), PtPGFindPanelByTitle()


PtPixel 2004, QNX Software Systems Ltd.

A set of points

Class hierarchy:PtWidget → PtBasic → PtGraphic → PtPixel

PhAB icon:

Public header:<photon/PtPixel.h>

Description:You can use the PtPixel widget to draw a set of points. The array ofpoints, Pt ARG POINTS specifies a number of points to be drawnusing the widget’s drawing attributes. These points are relative to thewidget’s Pt ARG ORIGIN. For more information, see PtGraphic.

Each point in the Pt ARG POINTS array is a position at which a pointis to be drawn. The points are drawn independently of each other (i.e.they’re not connected).








continued. . .


2004, QNX Software Systems Ltd. PtPixel






Pt ARG COLOR PtBasic Pg BLACK






Pt ARG DASH LIST PtGraphic Not used by this class.

Pt ARG DASH SCALE PtGraphic Not used by this class.


Pt ARG DIM PtWidget










continued. . .


PtPixel 2004, QNX Software Systems Ltd.








Pt ARG LINE CAP PtGraphic Not used by this class.

Pt ARG LINE JOIN PtGraphic Not used by this class.










Pt ARG POS PtWidget






continued. . .


2004, QNX Software Systems Ltd. PtPixel



Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






PtPolygon 2004, QNX Software Systems Ltd.

A set of connected line segments

Class hierarchy:PtWidget → PtBasic → PtGraphic → PtPolygon

PhAB icon:

Public header:<photon/PtPolygon.h>

Description:You can use the PtPolygon widget to draw a set of connected linesegments, called a polyline, from the vertices of the line segments.

Open or closed PtPolygon widgets.

The points that you specify in the Pt ARG POINTS resource are thevertices of the polyline or polygon. These points are relative to thewidget’s Pt ARG ORIGIN. For more information, see PtGraphic.

For a polygon, the last vertex doesn’t have to be the same as the first;the widget can close the polygon for you.

You can use Pt ARG POLYGON FLAGS to specify:

� whether points in the polygon definition are relative to the previouspoint or in absolute coordinates


2004, QNX Software Systems Ltd. PtPolygon

� whether a polyline (open curve) or polygon (closed curve) is to bedrawn.

New resources:


Pt ARG POLYGON FLAGS unsigned short Flag 0

Pt ARG POLYGON FLAGS


unsigned short Flag 0

This resource defines the type of polygon to be drawn. You can ORthe following flag bits (defined in <photon/Pg.h>):

Pg CLOSED Connect the last point to the first.

Pg POLY RELATIVE

Use relative coordinates to draw the polygon. Eachpoint is relative to the previous point.
























Pt ARG DIM PtWidget





continued. . .


2004, QNX Software Systems Ltd. PtPolygon









Pt ARG INSIDE FILL PATTERN PtGraphic

Pt ARG INSIDE TRANS PATTERN PtGraphic














Pt ARG POS PtWidget

continued. . .










Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






2004, QNX Software Systems Ltd. PtPrintSelA widget for selecting printing properties

Class hierarchy:PtWidget → PtBasic → PtContainer → PtPrintSel

PhAB icon:

Public header:<photon/PtPrintSel.h>

Description:The PtPrintSel widget lets you select a printer, change itsproperties, and optionally select a range of pages and the number ofcopies to print.


PtPrintSel 2004, QNX Software Systems Ltd.

A PtPrintSel widget.

The widget has a resource for a print context,Pt ARG PRINT CONTEXT , that you must set to one you’ve createdwith PpCreatePC():

PtSetArg(&args[0], Pt ARG PRINT CONTEXT, pc, 0);/* Set some other resources... */printsel = PtCreateWidget(PtPrintSel, window, nargs, args);


2004, QNX Software Systems Ltd. PtPrintSel

The widget automatically handles all aspects of selecting a printer andalso runs the properties application to modify elements in the printcontext. When you’re finished selecting the printer, you can get themodified print context by using PtGetResource() or PtGetResources()to get the widget’s print-context resource:

/* The user has finished configuring the print session. */

PtGetResource( printsel, Pt ARG PRINT CONTEXT, &pc, 0);

New resources:


Pt ARG PRINT CONTEXT PpPrintContext t Struct NULL

Pt ARG PRINT FLAGS unsigned short Flag Pt PRINTSEL FILE PANE |

Pt PRINTSEL SETTINGS PANE

| Pt PRINTSEL PREFERENCES

Pt ARG PS LBL ALL char * String Print All Pages

Pt ARG PS LBL COLLATED char * String Print Collated

Pt ARG PS LBL COPIES char * String Copies:

Pt ARG PS LBL DOUBLE SIDED char * String Print DoubleSided

Pt ARG PS LBL FILE char * String File:

Pt ARG PS LBL FROM char * String From:

Pt ARG PS LBL INSTALL char * String Install

Pt ARG PS LBL NAME char * String Name:

Pt ARG PS LBL NOT COLLATED char * String Print NotCollated

continued. . .




Pt ARG PS LBL PREFERENCES char * String Preferences

Pt ARG PS LBL PRINT ORDER char * String Print Order

Pt ARG PS LBL PRINT PAGES char * String Print Pages

Pt ARG PS LBL RANGE char * String Print Range

Pt ARG PS LBL REVERSED char * String Print ReversedOrder

Pt ARG PS LBL SELECTION char * String Print Selection

Pt ARG PS LBL SEND TO FILE char * String Send to file

Pt ARG PS LBL SEND TO PRINTER char * String Send to printer

Pt ARG PS LBL TO char * String To:

Pt CB PRINT PROPS PtCallback t * Link NULL

If you click on the Preferences button, the widget displays the PrinterProperties dialog by PtPrintPropSelect(). You can customize thisdialog by setting some pseudo-resources. They aren’t really widgetresources, but you can set them for PtPrintSel as if they were, andthe widget passes the settings to PtPrintPropSelect(). For detailsabout these resources, see the Photon Library Reference.

�

Pt ARG PRINT CONTEXT


PpPrintContext t Struct NULL

The current Print Context settings. This resource isn’t availablethrough PhAB, but you’ll need a Print Context in order to do anyprinting. Use PpCreatePC() to create a Print Context, and PpSetPC()to change its settings.



When you use PtGetResources() to get this resource, you mustprovide a PpPrintContext t structure, which is filled in directlywith the values of the context. Unlike most calls to PtGetResources(),you aren’t given a pointer into the widget’s internal memory.

�

Pt ARG PRINT FLAGS


unsigned short Flag Pt PRINTSEL FILE PANE |Pt PRINTSEL SETTINGS PANE |Pt PRINTSEL PREFERENCES

Flags that modify the appearance of the widget:

Pt PRINTSEL FILE PANE

Enable the Send to file pane.

Pt PRINTSEL NO COPIES

Disable the Copies widget.

Pt PRINTSEL NO PAGE RANGE

Disable the Print Range toggle button and the From and Tofields.

Pt PRINTSEL NO PRINTSELECT

Disable the printer-name combobox. Physical output goes tothe default physical printer whose name is shown.

Pt PRINTSEL NO SELECT RANGE

Disable the Print Selection toggle button.

Pt PRINTSEL PREFERENCES

Enable the Preferences button.

Pt PRINTSEL SETTINGS PANE

Enable the Print Pages, Print Order and Copies panes.



The following flag macros are defined in <PtPrintSel.h>:

Pt PRINTSEL ALL PANES

Pt PRINTSEL FILE PANE | Pt PRINTSEL SETTINGS PANE

Pt PRINTSEL DFLT LOOK

Pt PRINTSEL FILE PANE | Pt PRINTSEL SETTINGS PANE |Pt PRINTSEL PREFERENCES

Pt ARG PS LBL ALL


char * String Print All Pages

The label used for the button used to print all the pages.

Pt ARG PS LBL COLLATED


char * String Print Collated

The label used for the toggle button used to collate the pages.

Pt ARG PS LBL COPIES


char * String Copies:

The label for the field for specifying the number of copies.

Pt ARG PS LBL DOUBLE SIDED




char * String Print Double Sided

The label for the toggle button used to choose between single- anddouble-sided printing.

Pt ARG PS LBL FILE


char * String File:

The label of the field used to specify the name of the file to print to.

Pt ARG PS LBL FROM


char * String From:

The label used for the lower end of a range of pages to print.

Pt ARG PS LBL INSTALL


char * String Install

The label of the button used to install printers.

Pt ARG PS LBL NAME


char * String Name:

The label for the field that holds the printer’s name.



Pt ARG PS LBL NOT COLLATED


char * String Print Not Collated

The label for the button that requests noncollated printing.

Pt ARG PS LBL PREFERENCES


char * String Preferences

The label for the button for choosing print preferences.

Pt ARG PS LBL PRINT ORDER


char * String Print Order

The title for the pane for selecting the order in which pages areprinted.

Pt ARG PS LBL PRINT PAGES


char * String Print Pages

The title of the pane for choosing which pages to print.

Pt ARG PS LBL RANGE


char * String Print Range



The label of the button and fields used to select a range of pages forprinting.

Pt ARG PS LBL REVERSED


char * String Print Reversed Order

The label for the button to select printing in reverse order.

Pt ARG PS LBL SELECTION


char * String Print Selection

The label for the button for printing just the selected pages.

Pt ARG PS LBL SEND TO FILE


char * String Send to file

The title of the pane used to send the output to a file.

Pt ARG PS LBL SEND TO PRINTER


char * String Send to printer

The title of the pane used to send the output to a printer.

Pt ARG PS LBL TO




char * String To:

The label used for the upper end of a range of pages to print.

Pt CB PRINT PROPS



A list of PtCallback t structures that define the callbacks that areinvoked when you click on the Preferences button. If this resourceisn’t set or is set to NULL, clicking the Preferences button displays thePrint Properties dialog by invoking the PtPrintPropSelect()convenience function; for more information, see the Photon LibraryReference.


reason Pt CB PRINT PROPS

reason subtype

Not used.


cbdata A pointer to a PpPrintContext t structure. For moreinformation, see the Printing chapter of the PhotonProgrammer’s Guide.
















Pt ARG CONTAINER FLAGS PtContainer &=˜Pt GETS FOCUS








Pt ARG DIM PtWidget Read only

continued. . .





















Pt ARG POS PtWidget






continued. . .







Pt CB ARM PtBasic






Pt CB DND PtWidget







Pt CB MENU PtBasic


Pt CB RAW PtWidget







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

PtPrintSelect()

Display a custom modal dialog for selecting print options

PtPrintSelection()

Display a modal dialog for initiating printing

For more information, see the Photon Library Reference.


2004, QNX Software Systems Ltd. PtProgressA progress bar

Class hierarchy:PtWidget → PtBasic → PtGauge → PtProgress

PhAB icon:

Public header:<photon/PtProgress.h>

Description:The PtProgress widget draws a progress bar and (optionally) thecorresponding value.

Two styles of PtProgress bar.

The bar can be either a single bar, growing continuously as the valueis changed, or it can consist of a number of divisions of equal size.

The following bits of the Pt ARG GAUGE FLAGS resource definedby PtGauge are of particular interest to PtProgress:

Pt GAUGE INDETERMINATE

The current value is “unknown.”

Pt GAUGE LIVE

Alter the widget’s appearance as time passes to indicate thatalthough the value may not be changing, the application is stillworking.


PtProgress 2004, QNX Software Systems Ltd.

Pt GAUGE INTERACTIVE

Let the user change the value of the gauge interactively atruntime (e.g. by dragging). When the value is changed in thismanner, the widget’s Pt CB GAUGE VALUE CHANGEDcallbacks are invoked.

New resources:


Pt ARG PROGRESS BAR COLOR PgColor t Scalar Pg RED

Pt ARG PROGRESS DIVISIONS unsigned short Scalar 1

Pt ARG PROGRESS GAP unsigned short Scalar 4

Pt ARG PROGRESS SPACING unsigned short Scalar 0

Pt ARG PROGRESS BAR COLOR



The color of the progress bar. See PgColor t in the Photon LibraryReference.

Pt ARG PROGRESS DIVISIONS



The number of divisions (1 means continuous).

PtProgress doesn’t use this resource, but any subclasses can.


2004, QNX Software Systems Ltd. PtProgress

Pt ARG PROGRESS GAP



The gap (in pixels) between the progress bar and the text (if the textisn’t on top of the bar).

PtProgress doesn’t use this resource, but any subclasses can.

Pt ARG PROGRESS SPACING



The spacing (in pixels) between divisions (seePt ARG PROGRESS DIVISIONS).









continued. . .







Pt ARG COLOR PtBasic Pg BLACK







Pt ARG DIM PtWidget



Pt ARG FILL COLOR PtBasic Pg GRAY



Pt ARG GAUGE FLAGS PtGauge


Pt ARG GAUGE H ALIGN PtGauge

Pt ARG GAUGE V ALIGN PtGauge


Pt ARG GAUGE VALUE PREFIX PtGauge

Pt ARG GAUGE VALUE SUFFIX PtGauge

continued. . .
















Pt ARG ORIENTATION PtGauge



Pt ARG POS PtWidget







Pt CB ARM PtBasic

continued. . .







Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget




Convenience functions:PtProgress defines the following convenience functions:

These functions are useful only if you create subclasses ofPtProgress.

�

PtProgressEntireSegment()

Get the entire segment of a progress bar

PtProgressFirstSegment()

Get the first segment of a progress bar



PtProgressNextSegment()

Get the next segment of a progress bar

PtProgressTextRect()

Get the text area of a progress bar


PtProgressEntireSegment() 2004, QNX Software Systems Ltd.

Get the entire segment of a progress bar

Synopsis:int PtProgressEntireSegment( PtWidget t *widget,

short *start,short *end);

Description:This function gets the coordinates (x for a horizontal bar, y for avertical one) of the entire segment of the PtProgress pointed to bywidget.

The coordinates are stored in the space pointed to by start and end,taking into account whether or not the progress bar is inverted (i.e. thestarting coordinate is always less than or equal to the end coordinate).

Returns:0 Success.

Pt PROGRESS NO MORE SEGMENTS

No segment was found.


Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtProgressEntireSegment()

See also:PtProgress, PtProgressEntireSegment(), PtProgressFirstSegment(),PtProgressNextSegment(), PtProgressTextRect(),


PtProgressFirstSegment() 2004, QNX Software Systems Ltd.

Get the first segment of a progress bar

Synopsis:int PtProgressFirstSegment(PtWidget t *widget,

short *start,short *end );

Description:This function gets the coordinates (x for a horizontal bar, y for avertical one) of the first segment of the PtProgress pointed to bywidget.


After calling this function, you can call PtProgressNextSegment() toget the coordinates of succeeding segments.

Returns:0 Success.




Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtProgressFirstSegment()

See also:PtProgress, PtProgressEntireSegment(), PtProgressNextSegment(),PtProgressTextRect()


PtProgressNextSegment() 2004, QNX Software Systems Ltd.

Get the next segment of a progress bar

Synopsis:int PtProgressNextSegment( PtWidget t *widget,

short *start,short *end);

Description:This function gets the coordinates (x for a horizontal bar, y for avertical one) of the next segment of the PtProgress pointed to bywidget.


You must have called PtProgressFirstSegment() before calling thisfunction.

�

Returns:0 Success.




Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtProgressNextSegment()

See also:PtProgress, PtProgressEntireSegment(), PtProgressFirstSegment(),PtProgressTextRect()


PtProgressTextRect() 2004, QNX Software Systems Ltd.

Get the text area of a progress bar

Synopsis:void PtProgressTextRect( PtWidget t const *widget,

PhRect t *rect );

Description:This function gets the rectangle in which text is drawn on thePtProgress pointed to by widget. The rectangle’s coordinates arestored in the PhRect t structure pointed to by rect.


Safety


Signal handler No

Thread No

See also:PtProgress, PtProgressEntireSegment(), PtProgressFirstSegment(),PtProgressNextSegment()



2004, QNX Software Systems Ltd. PtRawA widget for use with Photon drawing primitives

Class hierarchy:PtWidget → PtBasic → PtRaw

PhAB icon:

Public header:<photon/PtRaw.h>

Description:The PtRaw widget lets you use the Photon graphics drawing functionsin applications that use widgets.

The PtRaw class provides a good starting point for creating customwidgets. However, custom widgets require their own Initialization,Extent, and Connect methods in addition to a Draw method. Since thePtRaw widget is typically used for drawing, the Draw function PtRawsupports is described in detail in this chapter. If you’d like moreinformation about when to use an Initialization, Extent, or Connectfunction, see Building Custom Widgets.

�

With a PtRaw widget, you can draw using raw Photon graphicsprimitives without completely losing what you’ve drawn when thewidget is damaged. If the widget is damaged, your application isnotified so that it may redraw whatever it had previously drawn.

You must refresh the contents of the canvas whenever they becomedamaged. This is necessary because Photon doesn’t keep track of thewidget’s raw contents for you. It’s more efficient to have you, asapplication programmer, maintain the original data structure andredraw the contents of the canvas. If it takes a long time to render thecontents of the canvas, consider rendering them into an image andcopying the image into the canvas when it’s damaged.

The canvas is considered damaged whenever one of the followingsituations occurs:


PtRaw 2004, QNX Software Systems Ltd.

� A Photon expose event arrives at the canvas’s region.

� The widget is realized — the empty region has been drawn and thecontents of the canvas must be drawn.

� The region becomes unobscured — a region that was covering partof the canvas’ region has moved or been destroyed. The contentsof the obscured area were lost, so that area must be redrawn.

Draw function

The PtRaw widget defines a drawing function,Pt ARG RAW DRAW F, which is invoked any time the contents of thecanvas have to be refreshed due to damage.

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

�

The drawing function you provide for the canvas gets two argumentswhen it’s invoked:

� a pointer to the canvas widget

� a list of tiles indicating which parts of the canvas have beendamaged.

For simple situations where the widget’s contents don’t change, youcould put the drawing primitives in the draw function directly. But it’smore likely that the contents change dynamically. In this case, youshould create a data structure, or model, that defines the contents ofthe canvas.

Place a pointer to this data structure in the Pt ARG POINTER orPt ARG USER DATA resource of the PtRaw widget, so that yourdraw function can get it easily. This function should be able to walkthe data structure you’ve provided and to render the contents of thecanvas, based on that information. The draw function must handle itsown clipping and highlighting.


2004, QNX Software Systems Ltd. PtRaw

Before your function begins drawing, it should establish its coordinatespace correctly. First, get the coordinates of the clip rectangle or thewidget canvas, by calling PtCalcCanvas() with the raw widget and theaddress of a rectangle to be filled with the boundaries of the rawwidget’s clip region.

Once you’ve determined the clip region, you should determine a scalefactor, based on:

� the portion of the model you wish to display

� the overall extents of the model

� the current dimensions of the canvas.

The coordinates for the Pg* calls made within the draw function arerelative to the canvas of PtRaw’s parent. You need to translate thecoordinates to compensate for the raw widget’s margins. The edge ofthe margins is given as the rectangle’s upper-left corner given by thePtCalcCanvas() function. Add the rectangle’s upper-left corner to anytranslation you wish to perform on the model and pass this value toPgSetTranslation().

This function takes two parameters. The second parameter should beset to the constant Pg RELATIVE. When rendering your model, scalethe values by your scale factor. The coordinates are automaticallytranslated by the amount you specified in the call toPgSetTranslation().

If your draw function changes the current clipping (PtClipAdd()) ortranslation (PgSetTranslation()), be sure to restore them beforereturning from the draw function.

�

The simple example below shows a drawing function that fills theentire canvas with blue:

void raw draw(PtWidget t *widget, PhTile t *damage){

PhRect t rect;

PtCalcCanvas(widget, &rect);



PgSetFillColor(Pg BLUE);PgDrawRect(&rect, Pg DRAW FILL);

}

If your model doesn’t explicitly represent color information, makesure you set the stroke color to the value contained in thePt ARG COLOR resource and the fill color to the value specified inthe Pt ARG FILL COLOR resource.

Here’s a more detailed example of setting up and using a PtRawwidget:

pos.x = 220;dim.w = 200, dim.h = 200;n=0;PtSetArg( &args[n], Pt ARG DIM, &dim, 0 );n++;PtSetArg( &args[n], Pt ARG POS, &pos, 0 );n++;PtSetArg( &args[n], Pt ARG RAW DRAW F, &draw, 1 );n++;PtSetArg( &args[n], Pt ARG BEVEL WIDTH, 2, 0 );n++;PtSetArg( &args[n], Pt ARG FLAGS, Pt TRUE,

Pt SELECTABLE | Pt HIGHLIGHTED );n++;PtSetArg( &args[n], Pt CB ARM, &aback, 1 );n++;PtCreateWidget(PtRaw, Pt DEFAULT PARENT, n, &args[0] );...

void draw( PtWidget t *widget, PhTile t *damage ){

PhRect t rect;

damage = damage;

PtSuperClassDraw( PtBasic, widget, damage );

/* Find our canvas. */PtCalcCanvas( widget, &rect );

/* Clip to our basic canvas (it’s only polite). */PtClipAdd( widget, &rect );

/* Do our drawing... */PgSetStrokeColor( Pg RED );PgDrawRect( &rect , Pg DRAW STROKE );rect.ul.x++;rect.ul.y++;rect.lr.y--;rect.lr.x--;



PgSetStrokeColor( Pg WHITE );PgDrawRect( &rect , Pg DRAW STROKE );

/* Remove our clipping */PtClipRemove();

}

For more information, see the Raw Drawing and Animation chapterof the Photon Programmer’s Guide.

New resources:


Pt ARG RAW CALC OPAQUE F See below Pointer NULL

Pt ARG RAW CONNECT F See below Pointer NULL

Pt ARG RAW DRAW F See below Pointer NULL

Pt ARG RAW EXTENT F See below Pointer NULL

Pt ARG RAW INIT F See below Pointer NULL

Pt ARG RAW CALC OPAQUE F


See below Pointer NULL

A function that calculates the raw widget’s opacity tile list:

int (*calc opaque f) (PtWidget t *widget)

If this resource isn’t set, the raw widget uses the function defined byPtBasic.



Pt ARG RAW CONNECT F



A function that creates any regions needed by the widget (normallyPtWidget does this for you):

int (*connect f) (PtWidget t *widget)


Pt ARG RAW DRAW F



A function that renders the widget on the screen:

void (*draw f) (PtWidget t *widget, PhTile t *damage)

The damage argument points to a linked list of PhTile t structures(see the Photon Library Reference) that identify which areas of thewidget have been damaged.


For more information, see the Raw Drawing and Animation chapterof the Photon Programmer’s Guide.

Pt ARG RAW EXTENT F





A function that determines the exact size of the widget based ondefault values and/or the widget’s position, size, margins, borders,and highlighting information:

void (*extent f) (PtWidget t *widget)


Pt ARG RAW INIT F



This function is typically used by widgets that create children. Itchecks to ensure that all members used in a subsequent call to theextent function are correctly assigned.

int (*init f) (PtWidget t *widget)







continued. . .

















Pt ARG DIM PtWidget










continued. . .












Pt ARG POS PtWidget







Pt CB ARM PtBasic




Pt CB DND PtWidget




continued. . .






Pt CB MENU PtBasic


Pt CB RAW PtWidget





2004, QNX Software Systems Ltd. PtRawListA raw list

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

PhAB icon:

Public header:<photon/PtRawList.h>

Description:PtRawList is a list that gives you more control than PtList over theappearance and behavior of its items. You can supply variousfunctions to draw items, react to events, and so on. If these functionsaren’t given, the widget uses the default functions defined forPtGenList.

Use PtGenListAddItems() to add items to the raw list.

New resources:


Pt ARG RAWLIST BACKGROUND F See below Pointer NULL

Pt ARG RAWLIST DRAW F See below Pointer NULL

Pt ARG RAWLIST GFLAGS unsigned short Flags 0

Pt ARG RAWLIST INFLATE F See below Pointer NULL

Pt ARG RAWLIST KEY F See below Pointer NULL

Pt ARG RAWLIST MOUSE F See below Pointer NULL

continued. . .


PtRawList 2004, QNX Software Systems Ltd.


Pt ARG RAWLIST SELECT F See below Pointer NULL

Pt ARG RAWLIST BACKGROUND F



A function that draws the background of the list. If this resource isNULL, the widget uses the default function defined for PtGenList.

This function is of type PtRawListDrawBackgroundF t; theprototype is:

void drawbackground( PtWidget t *widget,PhRect t const *canvas,PhRect t const *empty );

The arguments are:

widget A pointer to the raw-list widget.

canvas A pointer to a PhRect t structure (see the PhotonLibrary Reference) that defines the widget’s canvas.

empty A pointer to a PhRect t structure that defines the emptyarea between the last item and the bottom margin, if any.

Pt ARG RAWLIST DRAW F



A function that draws the widget. If this resource is NULL, the widgetuses the default function defined for PtGenList.


2004, QNX Software Systems Ltd. PtRawList

This function is of type PtRawListDrawF t; the prototype is:

void drawf( PtWidget t *widget,PtGenListItem t *item,unsigned index,unsigned nitems,PhRect t *where );

The arguments are:


item A pointer to the PtGenListItem t structure for the firstitem that needs to be redrawn.

index The index of the item to be redrawn. The first item in thelist has an index of 1.

nitems The number of items the function should look at.

where A pointer to a PhRect t structure (see the Photon LibraryReference) that defines the extent of the items. Thefunction can modify the structure pointed to by where, ifneeded.

Pt ARG RAWLIST GFLAGS


unsigned short Flags 0

Flags that affect the behavior of the widget. The bits include:

Pt GEN LIST NO BACKGROUND

If set, the Draw function doesn’t draw the background (underthe items) or margins.

Pt GEN LIST ITEM BACKGROUND

If this bit is set but the Pt GEN LIST NO BACKGROUND bit isclear, the Draw function draws the background beneath each



item and calls the List Draw method once for each item thatneeds to be drawn.

Pt GEN LIST NO CLIPPING

If this bit is clear, the Draw method sets clipping to the widget’scanvas before calling the List Draw method. The clipping isn’tset if no items are wider than the canvas.

Pt GEN LIST SHOW DAMAGED

If this flag is set, the Draw method scans the damage list andsets the Pt LIST ITEM DAMAGE flag in the items that need tobe drawn. The List Draw method isn’t called at all if no itemsare damaged.

Pt GEN LIST FULL WIDTH

If this flag is set, the space to the right of an item is consideredpart of the item — the width stored in the item is treated as asuggested minimum. If that space is damaged, the item ismarked as damaged. If this flag isn’t set, the space to the rightof an item is treated like the margin. Mouse clicks on that spaceare ignored.

Pt GEN LIST NO AUTOFOCUS

If this flag is clear, giving focus to the widget when there’s nocurrent item (see “Current item” in the description ofPtGenList) in that widget automatically sets the current itemto the first displayed item.

Pt LIST BALLOONS IN COLUMNS

If this flag is set and the widget has columns, the widgetdestroys and recreates the balloon when the mouse pointercrosses column boundaries.

Pt ARG RAWLIST INFLATE F





A function that’s called when a balloon widget needs to be created. Itshould create a balloon and returns its widget pointer. If this resourceis NULL, the widget uses the default function defined for PtGenList.

This function is of type PtRawListInflateF t The prototype is:

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

The arguments are:


parent A pointer to the balloon’s parent.

item A pointer to the PtGenListItem t structure for theitem under the mouse pointer.

index The index of the list item. The first item in the list has anindex of 1.

column The index of the column under the mouse pointer, or -1 ifthe pointer isn’t on a column or the list has no columns.

area A pointer to a PhArea t structure (see the PhotonLibrary Reference) that contains the area, relative to theparent widget, corresponding to the entire item, UsePtGenListSetColumnBalloon() to adjust the area to thespecified column if you’re not usingPtGenListCreateTextBalloon().



Pt ARG RAWLIST KEY F



A function that’s called for key events. If this resource is NULL, thewidget uses the default function defined for PtGenList.

This function is of type PtRawListKeyF t; the prototype is:

int keyf( PtWidget t *widget,PhEvent t *ev,PhKeyEvent t *kev,PtGenListItem t *newcur,unsigned newpos );

The arguments are:


ev A pointer to the PhEvent t structure (see the PhotonLibrary Reference) that describes the event.

kev A pointer a PhKeyEvent t structure that describes theevent data, which the function can modify.

newcur A pointer to the PtGenListItem t structure for the newcurrent item (see “Current item” in the description ofPtGenList) in the list, if the event is processed normally.

newpos The index of the new current item. The first item in thelist has an index of 1.

This function must return one of the following values:

Pt CONTINUE The PtGenList class processes the data containedin the PhKeyEvent t structure (see the PhotonLibrary Reference). Note that the class’s rawcallbacks can modify the contents of this structure.



Pt END The widget ignores the event and the class’s rawcallbacks return Pt CONTINUE immediately.

Pt HALT The event is consumed by the widget, butPtGenList itself doesn’t take any further action.The class’s raw callbacks return Pt ENDimmediately.

Pt ARG RAWLIST MOUSE F



A function that’s called to handle mouse events if the mouse points toan item. If this resource is NULL, the widget uses the default functiondefined for PtGenList.

This function is of type PtRawListMouseF t, and the prototype is:

int mousef( PtWidget t *widget,PtGenListItem t *item,unsigned index,PhPoint t *where,int column,PhEvent t *event );

The arguments are:


item A pointer to the PtGenListItem t structure for theitem under the mouse cursor.

index The index of that item. The first item in the list has anindex of 1.

where A pointer to a PhPoint t structure that gives the mouseposition relative to the item. The function can modify thestructure pointed to by where.



column The column number.

event A pointer to the PhEvent t structure (see the PhotonLibrary Reference) that describes the event.

This function must return one of the following values:

Pt CONTINUE The PtGenList class processes the data containedin the PhKeyEvent t structure (see the PhotonLibrary Reference). Note that the class’s rawcallbacks can modify the contents of this structure.

Pt END The widget ignores the event and the class’s rawcallbacks return Pt CONTINUE immediately.

Pt HALT The event is consumed by the widget, butPtGenList itself doesn’t take any further action.The class’s raw callbacks return Pt ENDimmediately.

Pt ARG RAWLIST SELECT F



A function that’s called when an item is selected or unselected. If thisresource is NULL, the widget uses the default function defined forPtGenList.

This function is of type PtRawListSelectF t, with a prototype of:

void selectf( PtWidget t *widget,PtGenListItem t *item,int pos,int column,int nitems,int subtype,PhEvent t *ev );

The arguments are:




item A pointer to a PtGenListItem t structure. InPt SELECTION MODE RANGE selection mode, it’s apointer to the first selected item. In other modes, it’s apointer to the item that’s been selected or unselected.

pos The index of that item. The first item on the list has anindex of 1.


nitems The current number of selected items (the same aslist->sel count).

subtype The selection subtype.

event A pointer to the PhEvent t structure (see the PhotonLibrary Reference) that describes the event.









continued. . .


















Pt ARG DIM PtWidget









continued. . .























Pt ARG POS PtWidget




continued. . .















Pt CB ARM PtBasic












continued. . .




Pt CB MENU PtBasic


Pt CB RAW PtWidget






Pt CB DND

For Pt CB DND callbacks for a PtRawList, the cbinfo->cbdata is apointer to a PtGenListDndCallback t structure, containing atleast the following members:



PtGenListItem t *item

The target item involved in the drag-and-dropoperation.


unsigned long flags

Possible values:







Convenience functions:You can use any of the convenience functions defined for PtGenListwhen working with a PtRawList.


2004, QNX Software Systems Ltd. PtRawTreeA raw tree

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

PhAB icon:

Public header:<photon/PtRawTree.h>

Description:PtRawTree is a tree that gives you more control than PtTree overthe appearance and behavior of its items. You can supply variousfunctions to draw items, react to events, and so on. If these functionsaren’t given, the widget uses the default functions defined forPtGenTree or PtGenList.

New resources:


Pt ARG RAWTREE DRAW F See below Pointer NULL

Pt ARG RAWTREE INFLATE F See below Pointer NULL

Pt ARG RAWTREE SELECT F See below Pointer NULL

Pt ARG RAWTREE STATE F See below Pointer NULL

Pt ARG RAWTREE DRAW F


PtRawTree 2004, QNX Software Systems Ltd.



A function that’s called to draw the widget. If this resource is NULL,the default function for PtGenTree is called.

This function is of type PtRawTreeDrawItemF t, and has thisprototype:

void drawitemf( PtWidget t *widget,PtGenTreeItem t *item,PhRect t const *where,int lmargin,int rmargin );

The arguments are:

widget A pointer to the widget.

item A pointer to the PtGenTreeItem t structure for theitem that needs to be redrawn.

where A pointer to a PhRect t structure (see the PhotonLibrary Reference) that defines the extent of the item.

lmargin If positive, an additional left margin to add to the firstcolumn.

rmargin If positive, an additional right margin to add to the lastcolumn.

The PtGenTree List Draw method is responsible for drawing thelines and boxes representing the tree structure. This function shoulddraw only the item.


2004, QNX Software Systems Ltd. PtRawTree

Pt ARG RAWTREE INFLATE F



A function that’s called when a balloon widget needs to be created. Itshould create a balloon and return its widget pointer. If this resourceis NULL, the default function for PtGenTree is called.

This function is of type PtRawTreeInflateF t, and has thisprototype:

PtWidget t *inflatef( PtWidget t *widget,PtWidget t *parent,PtGenTreeItem t *item,unsigned index,int column,PhArea t *area );

The arguments are:


parent A pointer to the balloon’s parent.

item A pointer to the PtGenTreeItem t structure for theitem under the mouse pointer.

index The index of the list item. The first item in the list has anindex of 1.

column The index of the column under the mouse pointer, or -1 ifthe pointer isn’t on a column or the list has no columns.

area A pointer to a PhArea t structure (see the PhotonLibrary Reference) that contains the area, relative to theparent widget, corresponding to the entire item, UsePtGenListSetColumnBalloon() to adjust the area to thespecified column if you’re not usingPtGenListCreateTextBalloon().



Pt ARG RAWTREE SELECT F



A function that’s called when an item is selected or unselected. If thisresource is NULL, the default function for PtGenTree is called.

This function is of type PtRawTreeSelectF t, and has thisprototype:

void selectf( PtWidget t *widget,PtGenTreeItem t *item,int pos,int column,int nitems,int subtype,PhEvent t *ev );

The arguments are:

widget A pointer to the raw-tree widget.

item A pointer to a PtGenTreeItem t structure. InPt SELECTION MODE RANGE selection mode, it’s apointer to the first selected item. In other modes, it’s apointer to the item that’s been selected or unselected.

pos The index of that item. The first item on the list has anindex of 1.


nitems The current number of selected items (the same aslist->sel count).

subtype The selection subtype.

event A pointer to a PhEvent t structure (see the PhotonLibrary Reference) that describes the event.



Pt ARG RAWTREE STATE F



A function that’s called when an item is expanded or collapsed. If thisresource is NULL, the default function for PtGenTree is called.

This function is of type PtRawTreeItemStateF t, and has thisprototype:

int statef( PtWidget t *widget,PtGenTreeItem t *item,PhEvent t *event,int reason );

The arguments are:

PtWidget t *widget

A pointer to the widget.


A pointer to the PtGenTreeItem t structure for theitem that’s being collapsed or expanded.

PhEvent t *event

A pointer to a PhEvent t structure (see the PhotonLibrary Reference) that describes the event.

int reason Either Pt TREE EXPANDING orPt TREE COLLAPSING.

If reason is Pt TREE EXPANDING, the item is about to be expanded.This function can update the item’s branches before the actualexpansion. After the function returns, the widget displays a list ofitems in the expanded branch.

If an item in the list has its Pt TREE ITEM EXPANDED flag set, theitems below are displayed too. To permit the expansion, return zero;to prevent it, return a nonzero value.



If reason is Pt TREE COLLAPSING, the item has been collapsed. Itsbranches are concealed and this function can free the associated items.




















continued. . .







Pt ARG DIM PtWidget




















continued. . .












Pt ARG POS PtWidget











Pt ARG TREE FLAGS PtGenTree See below.




continued. . .








Pt CB ARM PtBasic













Pt CB MENU PtBasic


Pt CB RAW PtWidget




continued. . .






Pt ARG TREE FLAGS

In addition to the flags defined by PtGenTree, the following flags aredefined:

� Pt TREE BALLOON ON IMAGE — the balloon is permitted tocover the image and the text

� Pt TREE BALLOON ON TREE — the balloon is permitted to coverthe tree, the image, and the text

By default, neither is set. The width and location of the balloondepend on these flags:

Neither Pt_TREE_BALLOON_ON_IMAGE

Pt_TREE_BALLOON_ON_TREE

Additional Pt ARG TREE FLAGS for a PtRawTree widget.

Pt CB DND

For Pt CB DND callbacks for a PtRawTree, the cbinfo->cbdata is apointer to a PtTreeDndCallback t structure, containing at leastthe following members:






A pointer to the PtGenTreeItem t structure forthe target item involved in the drag-and-dropoperation.


unsigned long flags

Possible values:





Convenience functions:You can use any of the convenience functions defined for PtGenTreewhen working with a PtRawTree.


PtRect 2004, QNX Software Systems Ltd.

A rectangle

Class hierarchy:PtWidget → PtBasic → PtGraphic → PtRect

PhAB icon:

Public header:<photon/PtRect.h>

Description:A PtRect widget draws a single rectangle whose bounding box isdefined by two points. To set these points, use the Pt ARG POINTSresource. These points are relative to the widget’s Pt ARG ORIGIN.For more information, see PtGraphic.

If you don’t set Pt ARG POINTS, the rectangle defaults to the sizedefined by Pt ARG POS and Pt ARG DIM (see PtWidget).

A PtRect widget.

The rectangle can have square or rounded corners. For roundedcorners, specify a radius in pixels for the curve at the corners by usingthe Pt ARG RECT ROUNDNESS resource.

New resources:


2004, QNX Software Systems Ltd. PtRect

Resource C Type Pt Type Default

Pt ARG RECT ROUNDNESS unsigned short Scalar 0

Pt ARG RECT ROUNDNESS



Defines the number of pixels used for rounding the corners of therectangle.













continued. . .












Pt ARG DIM PtWidget












Pt ARG INSIDE FILL PATTERN PtGraphic

Pt ARG INSIDE TRANS PATTERN PtGraphic


continued. . .


2004, QNX Software Systems Ltd. PtRect














Pt ARG POS PtWidget







Pt CB ARM PtBasic




continued. . .




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






2004, QNX Software Systems Ltd. PtRegionA Photon region

Class hierarchy:PtWidget → PtBasic → PtContainer → PtDisjoint →PtRegion


� PtServer

PhAB icon:None — instantiate it by calling PtCreateWidget().

Public header:<photon/PtRegion.h>

Description:PtRegion is ideal for controlling a region without foregoing theconvenience of the Photon widget library interface. With PtRegion,you can control a region without having to modify the standard mainloop function.

For more information about regions, see PhRegion t in the PhotonLibrary Reference, and the Regions chapter of the PhotonProgrammer’s Guide.

�

New resources:


Pt ARG REGION DATA PhRegionDataHdr t * Alloc NULL

Pt ARG REGION FIELDS long Flag 0

Pt ARG REGION FLAGS long Flag 0

continued. . .


PtRegion 2004, QNX Software Systems Ltd.


Pt ARG REGION HANDLE long Scalar widget pointer

Pt ARG REGION INFRONT long Scalar 0

Pt ARG REGION INPUT GROUP short Scalar 0

Pt ARG REGION OPAQUE long Flag 0

Pt ARG REGION OWNER PhConnectId t Scalar 0

Pt ARG REGION PARENT long Scalar 0

Pt ARG REGION SENSE long Flag 0

Pt ARG REGION DATA


PhRegionDataHdr t * Alloc NULL

Defines the data to be attached to the region. SeePhRegionDataHdr t in the Photon Library Reference.

Pt ARG REGION FIELDS


long Flag 0

This resource indicates which portions of the region were changed thelast time that you set any resources, including the flags, sensitivity,opacity, origin, and position.

The following bits can be used to define a field in a region change(PhRegionChange()) or open (PhRegionOpen()). For moreinformation, see <PhT.h>.


2004, QNX Software Systems Ltd. PtRegion

The Ph REGION HANDLE, Ph REGION ORIGIN, andPh REGION RECT bits are set up automatically when the widget isinitialized.

�

Bit Corresponding resource

Ph REGION OWNER Pt ARG REGION OWNER

Ph REGION HANDLE Pt ARG REGION HANDLE

Ph REGION FLAGS Pt ARG REGION FLAGS

Ph REGION EV OPAQUE Pt ARG REGION OPAQUE

Ph REGION EV SENSE Pt ARG REGION SENSE

Ph REGION STATE Read-only. Don’t modify.

Ph REGION ORIGIN See below.

Ph REGION PARENT Pt ARG REGION PARENT

Ph REGION IN FRONT Pt ARG REGION INFRONT

Ph REGION BEHIND See below.

Ph REGION RECT See below.

Ph REGION DATA Pt ARG REGION DATA

Ph REGION INPUT GROUP Pt ARG REGION INPUT GROUP

Any time you change PtRegion’s Pt ARG POS or Pt ARG AREAresource, the Ph REGION ORIGIN bit is changed automatically.

The Ph REGION BEHIND bit defines which region this region will beopened in front of. The specified region becomes the brother inbehind. A value of 0 makes the region the rearmost child of its parentwhen created.

Any time you change PtRegion’s Pt ARG AREA or Pt ARG DIMresource, the Ph REGION RECT bit is changed automatically.



Pt ARG REGION FLAGS


long Flag 0

Defines the region type and behavior:

� Ph WINDOW REGION

� Ph WND MGR REGION

� Ph GRAFX REGION

� Ph PTR REGION

� Ph KBD REGION

� Ph PRINT REGION

� Ph INPUTGROUP REGION

� Ph AUXPTR REGION

� Ph FORCE FRONT

� Ph FOLLOW IG SIZE

� Ph FORCE BOUNDARY

� Ph NO COMPRESSION

� Ph CURSOR SET

Pt ARG REGION HANDLE


long Scalar widget pointer

A widget pointer normally used by the widget library to determinewhich widget is associated with a region. You should either set thisresource to 0 or leave it set to its default value.



Pt ARG REGION INFRONT


long Scalar 0

Defines which region (rid) this region will be opened behind. Thespecified region becomes the brother in front. A value of 0 makes theregion the frontmost child of its parent when created.

Pt ARG REGION INPUT GROUP


short Scalar 0

Associates the region with the specified input group.

Pt ARG REGION OPAQUE


long Flag 0

A bitmask that defines which events this region is opaque to. For a listof event types, see PhEvent t in the Photon Library Reference.

Pt ARG REGION OWNER


PhConnectId t Scalar 0

Specifies the owner of the region.

Pt ARG REGION PARENT




long Scalar 0

Specifies the ID (rid) of the region that will be this region’s parent.

Pt ARG REGION SENSE


long Flag 0

A bitmask that defines which events this region is sensitive to. For alist of event types, see PhEvent t in the Photon Library Reference.












continued. . .













Pt ARG DIM PtWidget














continued. . .








Pt ARG POS PtWidget










Pt CB ARM PtBasic






Pt CB DND PtWidget



continued. . .







Pt CB MENU PtBasic


Pt CB RAW PtWidget







PtScrollArea 2004, QNX Software Systems Ltd.

A viewport for viewing a large virtual area

Class hierarchy:PtWidget → PtBasic → PtContainer → PtScrollArea


� PtScrollContainer


Public header:<photon/PtScrollArea.h>

Description:PtScrollArea is a metaclass that supports scrolling and panning forits subclasses. It combines scrollbar widgets and an area that providesa viewport onto a virtual display area. Typically, the virtual area islarger than the viewing area; the scrollbar widgets let you bring anypart of the virtual area into view.

As for other widgets, you can set the physical size of aPtScrollArea with its Pt ARG AREA resource (inherited fromPtWidget). The virtual size depends on itsPt ARG SCROLLAREA MAX X and Pt ARG SCROLLAREA MAX Yresources.

Any anchorable children of a PtScrollArea widget anchor to thevirtual size, not the physical size.

If the virtual area’s size is greater than the viewport’s size, you’ll needhorizontal and/or vertical scrollbars to control the viewport’s position.The dimensions are checked when the widget is realized to determineif scrollbars are necessary. Pt ARG SCROLLBAR X DISPLAY andPt ARG SCROLLBAR Y DISPLAY indicate when the scrollbarsshould be displayed:

� Pt NEVER — never display the scrollbars.

� Pt ALWAYS — display the scrollbars even if they’re not needed.


2004, QNX Software Systems Ltd. PtScrollArea

� Pt AS REQUIRED — display the scrollbars only if they’re needed.

Scrolling notification

When you move either the vertical or horizontal scrollbar to changethe viewport’s position, the Pt CB SCROLLAREA SCROLLEDcallbacks are invoked to notify your application that the viewport hasbeen moved. You may use these callbacks to keep two relatedviewports synchronized with each other by monitoring both viewportsand updating the position of the alternate viewport when one of themscrolls. See “Scrolling control” below.

Scrolling control

The scrollbars provided by the scrollable area let you vary theposition of the viewport between (0,0) and (xmax, ymax), where xmaxand ymax are the maximum positions in x and y. These are equal tothe virtual area’s size in the specified dimension minus the viewport’ssize in that dimension.

The size of the handle used by the scrollbar to represent theviewport’s position within the virtual area is the viewport’s sizerelative to the virtual area’s size.

The handle may be moved by incremental amounts by clicking oneither of the arrow buttons in the scrollbar. You can control theincrement by setting the increment resource corresponding to thescrollbar:

� Pt ARG SCROLLAREA INCREMENT X

� Pt ARG SCROLLAREA INCREMENT Y

These specify the number of pixels to increment the viewport’sposition by when one of the stepper buttons in the scrollbar is pressed.

You can pan the viewport by holding down the Alt key, pointing insidethe viewport, and dragging.

You can also update the viewport’s position under program control.To move the viewport, you simply set a new position using the



Pt ARG SCROLLAREA POS X and Pt ARG SCROLLAREA POS Yresources.

New resources:


Pt ARG SCROLLAREA FLAGS unsigned short Flag See below

Pt ARG SCROLLAREA INCREMENT X unsigned short Scalar 10

Pt ARG SCROLLAREA INCREMENT Y unsigned short Scalar 10

Pt ARG SCROLLAREA MAX X unsigned short Scalar 0

Pt ARG SCROLLAREA MAX Y unsigned short Scalar 0

Pt ARG SCROLLAREA POS X unsigned short Scalar 0

Pt ARG SCROLLAREA POS Y unsigned short Scalar 0

Pt ARG SCROLLBAR X DISPLAY unsigned short Scalar Pt AS REQUIRED

Pt ARG SCROLLBAR X HEIGHT unsigned short Scalar 15

Pt ARG SCROLLBAR Y DISPLAY unsigned short Scalar Pt AS REQUIRED

Pt ARG SCROLLBAR Y WIDTH unsigned short Scalar 15

Pt CB SCROLLAREA SCROLLED PtCallback t * Link NULL

Pt ARG SCROLLAREA FLAGS


unsigned short Flag Pt SCROLLAREA ENABLE PAN

These flags control the behavior of the scroll area. Valid bits include:



Pt SCROLLAREA IGNORE KEYS

Prevent the scroll area from handling and consuming the arrowkeys, Pg Up, Pg Dn, Home, or End.

Pt SCROLLAREA ENABLE PAN

Allow you to pan the scroll area by Alt-clicking and dragginganywhere in the client (viewport) area.

Pt ARG SCROLLAREA INCREMENT X



The number of pixels that the widget scrolls by when you click thehorizontal arrow buttons.

Pt ARG SCROLLAREA INCREMENT Y



The number of pixels that the widget scrolls by when you click thevertical arrow buttons.

Pt ARG SCROLLAREA MAX X



The width (in pixels) of the total scrollable area. This is the widget’svirtual width. To specify the displayed portion of this scrollable area,use Pt ARG AREA.



Pt ARG SCROLLAREA MAX Y



The height (in pixels) of the total scrollable area. This is the widget’svirtual height. To specify the displayed portion of this scrollable area,use Pt ARG AREA.

Pt ARG SCROLLAREA POS X



The horizontal position of the displayed portion of the scrollable area.

Pt ARG SCROLLAREA POS Y



The vertical position of the displayed portion of the scrollable area.

Pt ARG SCROLLBAR X DISPLAY


unsigned short Scalar Pt AS REQUIRED

Controls the visibility of the horizontal scrollbar. Possible values:

Pt NEVER Don’t display.

Pt ALWAYS Always display.



Pt AS REQUIRED

Display if the visible dimension is less than thevirtual dimension.

Pt ARG SCROLLBAR X HEIGHT



The height, in pixels, of the horizontal scrollbar. The minimum heightis 6 pixels.

Pt ARG SCROLLBAR Y DISPLAY


unsigned short Scalar Pt AS REQUIRED

Controls the visibility of the scrollbar. Possible values:

Pt NEVER Don’t display.

Pt ALWAYS Always display.

Pt AS REQUIRED

Display if the visible dimension is less than thevirtual dimension.

Pt ARG SCROLLBAR Y WIDTH



The width, in pixels, of the vertical scrollbar. The minimum width is6 pixels.



Pt CB SCROLLAREA SCROLLED



A list of PtCallback t structures that define the callbacks that thePtScrollArea widget invokes when its scrollbars are moved.

If the widget has the Pt CALLBACKS ACTIVE bit set in itsPt ARG FLAGS resource, these callbacks are also invoked when yourapplication changes the positions of the scrollbars by callingPtSetResource() or PtSetResources().


reason Pt CB SCROLLAREA SCROLLED

reason subtype

One of:

� Pt SCROLLAREA X CHANGED — change in x(horizontal) position.

� Pt SCROLLAREA Y CHANGED — change in y(vertical) position.

� Pt SCROLLAREA XY CHANGED — simultaneouschange in both axes.

event A pointer to a PhEvent t structure that describes theevent that caused the callback to be invoked, or NULL ifthere’s no event.

cbdata A pointer to a PtScrollAreaCallback t structure thatcontains at least:

int32 t old x, old y

The x and y positions before this change.



int32 t new x, new y

The current x and y positions (after the change).




Pt ARG ANCHOR FLAGS PtWidget Pt RIGHT ANCHORED LEFT|Pt BOTTOM ANCHORED TOP




Pt ARG BASIC FLAGS PtBasic Pt ALL ETCHES |Pt ALL OUTLINES |Pt FLAT FILL










continued. . .








Pt ARG DIM PtWidget





Pt ARG FLAGS PtWidget |= Pt GETS FOCUS |Pt HIGHLIGHTED | Pt SET |Pt REGION













continued. . .




Pt ARG POS PtWidget









Pt CB ARM PtBasic






Pt CB DND PtWidget






Pt CB MENU PtBasic


continued. . .




Pt CB RAW PtWidget





Convenience functions:The PtScrollArea widget defines the following conveniencefunction:

PtScrollAreaCanvas()

Get the viewport canvas, as opposed to the widget canvas


2004, QNX Software Systems Ltd. PtScrollAreaCanvas()Get the viewport canvas of a PtScrollArea

Synopsis:PhRect t *PtScrollAreaCanvas( PtWidget t *widget,

PhRect t *rect );

Library:ph

Description:This function determines the canvas rectangle for the specifiedwidget’s viewport. The PtScrollArea canvas rectangle describesthe area inside the widget’s border; the viewport’s canvas is the areainside the scrollbars. The rect argument must point to a PhRect t

structure; if you pass rect as NULL, the function returns NULL.

Returns:A pointer to the viewport’s canvas, or NULL if an error occurs.


Safety


Signal handler No

Thread No

See also:PhRect t in the Photon Library Reference


PtScrollbar 2004, QNX Software Systems Ltd.

A scrollbar

Class hierarchy:PtWidget → PtBasic → PtGauge → PtScrollbar

PhAB icon:

Public header:<photon/PtScrollbar.h>

Description:A PtScrollbar widget provides a scrollbar. It returns values (viacallbacks) that indicate a value within the provided range.

A PtScrollbar widget.

A scrollbar consists of the following parts:

Trough A shaded box, oriented horizontally or vertically, thatrepresents the total range.

Handle A shaded button-like object that moves through thetrough. Its range of motion is limited by the trough.

Stepper arrows

Arrow buttons drawn at either end of the trough that letthe handle slide forward or back by incremental amounts.The width of a stepper arrow in a horizontal scrollbar isautomatically set to be 3/4 of the height of the scrollbar.Similarly, the height of a stepper arrow in a verticalscrollbar is set to 3/4 of the scrollbar’s width.


2004, QNX Software Systems Ltd. PtScrollbar

A scrollbar can return values from minimum to (maximum -size-of-handle + 1). You’ll find the returned values useful forimplementing scrolling areas, text viewers/editors, and so on.

The handle size is determined by the Pt ARG SLIDER SIZE resource.If you don’t set this resource, the handle size is one-tenth of thespecified range.

The handle’s value is represented by its relative position within thetrough. The size of the trough represents the allowable range ofvalues.

Your application can also control the handle’s size. You can change itto indicate an object’s size and the portion viewed when the scrollbaris used for scrolling.

Scrolling is the action of controlling which part of an object isdisplayed when the object is too large to view all at once. By default,the trough’s size visually represents the scroll region — the totallength of the object being viewed; you can use thePt SCROLLBAR FIXED SLIDER SIZE bit in thePt ARG SCROLLBAR FLAGS to override this.

The edge of the handle represents your current relative position withinthe object. The handle’s size represents the proportion of the entireobject that is currently in view.

Sliding the handle within the trough controls which portion of theobject is displayed. Your application is responsible for changing thedisplay of the object in response to any change in the handle’sposition.

Mouse actions

When the mouse button is pressed, the result depends on the locationof the pointer.



If the pointer is: the handle:

On either arrow Moves up or down one increment (holdingdown the mouse button repeats the action)

In the trough Moves up or down one page increment(holding down the mouse button repeats theaction)

On the handle Starts a drag action

If you hold down the Ctrl and click the button while pointing at thetrough, the slider jumps to the pointer’s position.

Keyboard actions

If you press: The handle moves:

↑ Up one increment

↓ Down one increment

→ Right one increment

← Left one increment

Ctrl – ↑ Up one page increment

Ctrl – ↓ Down one page increment

Ctrl – → Right one page increment

Ctrl – ← Left one page increment

Home To the top or left (depending on the orientation)

End To the bottom or right (depending on theorientation)



New resources:


Pt ARG INCREMENT long Scalar 1

Pt ARG MIN SLIDER SIZE ushort t Scalar 10

Pt ARG PAGE INCREMENT int Scalar -1

Pt ARG SCROLLBAR FLAGS short Scalar 0

Pt ARG SLIDER SIZE int Scalar 1/10th of range

Pt CB SCROLL MOVE PtCallback t * Link NULL

Pt ARG INCREMENT


long Scalar 1

The value the widget scrolls by when you click the arrow buttons.

Pt ARG MIN SLIDER SIZE


ushort t Scalar 10

The minimum length of the handle, in pixels.

Pt ARG PAGE INCREMENT


int Scalar -1



The handle increment to be used when the scrollbar is moved by apage. If this value is -1, the value for Pt ARG SLIDER SIZE is used.

Pt ARG SCROLLBAR FLAGS


short Scalar 0

Flags that control the appearance and behavior of the scrollbar. Thevalid bits are:

Pt SCROLLBAR FIXED SLIDER SIZE

Make the scrollbar slider a fixed size, as specified byPt ARG MIN SLIDER SIZE.

Pt SCROLLBAR FOCUSED

Cause the scrollbar to be rendered as if it has focus even if itdoesn’t. This is useful in applications where one widget collectskeystrokes and directs specific keys to other widgets.

Pt SCROLLBAR SHOW ARROWS

Display arrow buttons at the ends of the trough.

Pt ARG SLIDER SIZE


int Scalar 1/10th of range

The length of the handle, in the range of 1 to (Pt ARG MAXIMUM -Pt ARG MINIMUM).

Pt CB SCROLL MOVE





A list of PtCallback t structures that define the callbacks that thescrollbar invokes when the scroll position changes.

If the widget has the Pt CALLBACKS ACTIVE bit set in itsPt ARG FLAGS resource, these callbacks are also invoked when yourapplication changes the position of the scrollbar by callingPtSetResource() or PtSetResources().


reason Pt CB SCROLL MOVE

reason subtype

0 (not used).


cbdata A pointer to a PtScrollbarCallback t structure thatcontains at least the following members:

� unsigned action — one of the following:

Pt SCROLL DECREMENT

The scrollbar has been decreased byone increment.

Pt SCROLL INCREMENT

The scrollbar has been increased byone increment.

Pt SCROLL PAGE INCREMENT

The scrollbar has been increased byone page.



Pt SCROLL PAGE DECREMENT

The scrollbar has been decreased byone page.

Pt SCROLL TO MAX

The handle part of the scrollbar hasbeen moved to the maximum value.

Pt SCROLL TO MIN

The handle has been moved to theminimum value.

Pt SCROLL DRAGGED

The handle is being dragged.Pt SCROLL RELEASED

The handle part has been releasedafter having been dragged.

Pt SCROLL SET The position of the handle waschanged by a call toPtSetResources(), and the widget hasthe Pt CALLBACKS ACTIVE bit set inits Pt ARG FLAGS resource.

Pt SCROLL JUMP

You jumped to a specific location byCtrl-clicking on the scrollbar.

� int position — a value corresponding to the handle’slocation.









Pt ARG BANDWIDTH THRESHOLD PtBasic Ph BAUD SLOW (seebelow)

Pt ARG BASIC FLAGS PtBasic Pt ALL ETCHES |Pt ALL INLINES





Pt ARG COLOR PtBasic Pg GRAY







Pt ARG DIM PtWidget



Pt ARG FILL COLOR PtBasic Pg MGRAY

Pt ARG FILL PATTERN PtBasic Pg PAT DIAGF8

continued. . .




Pt ARG FLAGS PtWidget |=Pt GETS FOCUS|Pt HIGHLIGHTED|Pt SET|Pt SELECTABLE|Pt SELECT NOREDRAW

Pt ARG GAUGE FLAGS PtGauge ˜Pt GAUGE HORIZONTAL

Pt ARG GAUGE FONT PtGauge Not used by this class.

Pt ARG GAUGE H ALIGN PtGauge Not used by this class.

Pt ARG GAUGE V ALIGN PtGauge Not used by this class.


Pt ARG GAUGE VALUE PREFIX PtGauge Not used by this class.

Pt ARG GAUGE VALUE SUFFIX PtGauge Not used by this class.









Pt ARG MAXIMUM PtGauge 19


Pt ARG MINIMUM PtGauge 0


Pt ARG ORIENTATION PtGauge Pt VERTICAL

continued. . .






Pt ARG POS PtWidget







Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget


continued. . .







The threshold value for graphics bandwidth (as reported byPtQuerySystemInfo()) that defines a slow connection.


2004, QNX Software Systems Ltd. PtScrollContainerA viewport for viewing a large virtual container

Class hierarchy:PtWidget → PtBasic → PtContainer → PtScrollArea →PtScrollContainer

PhAB icon:

Public header:<photon/PtScrollContainer.h>

Description:A PtScrollContainer widget combines one or more scrollbarwidgets and an area that provides a viewport onto a virtual displayarea. The virtual display area is a container for other widgets.Typically, the virtual area is larger than the viewing area; the scrollbarwidgets let you bring any part of the virtual area into view.

A PtScrollContainer widget acts as a viewport.

If the virtual area’s size is significantly greater than that of theviewport (such as when a large textual document is being viewed), it’susually impractical in terms of performance and memory to use ascrolling area. This is because the widget for the virtual area keepsthe entire contents of the object in memory and always renders theentire object, most of which gets clipped. In these cases, you should


PtScrollContainer 2004, QNX Software Systems Ltd.

consider creating your own subclass of PtScrollArea to manageonly the portion of the virtual area that’s displayed.

Anchors and resize policy

Anchors between a scrollable area and its parent affect the scrollablearea’s visible area.

Children of the scrollable area are anchored to its virtual area.

The scrollable area’s Pt ARG SCROLLCONT RESIZE FLAGSspecify the resize policy that’s applied to its virtual area. You can setthe virtual area’s size directly by modifying the resources associatedwith it. Otherwise, the area changes only under the followingconditions:

� The Pt AUTO EXTENT flag is set.

OR

� The scrollable area’s resize policy is set to allow it to resize inresponse to a change in its contents (i.e. any of its children change)

AND

� one of its children changes size, as a result of its resize policy or aprogrammatic change

AND

� you call PtExtentWidget() on the scrollable area after the change.

Other layouts are possible by making another container, such as agroup widget, a child of the scrollable area.

New resources:


2004, QNX Software Systems Ltd. PtScrollContainer


Pt ARG SCROLLCONT FLAGS uint16 t Flags Pt SCROLLCONT TRACK FOCUS

Pt ARG SCROLLCONT RESIZE FLAGS long Flags Pt RESIZE XY AS REQUIRED

Pt ARG SCROLLCONT FLAGS


uint16 t Flags Pt SCROLLCONT TRACK FOCUS

Flags that control the appearance and behavior of the widget. Thedefined bits include:

Pt SCROLLCONT TRACK FOCUS

Pan to accommodate the focused child as focus changes.

Pt ARG SCROLLCONT RESIZE FLAGS


long Flags Pt RESIZE XY AS REQUIRED

Flags that control the resizing of the virtual area. The defined bits arethe same as those defined for Pt ARG RESIZE FLAGS:

� Pt RESIZE X AS REQUIRED

� Pt RESIZE X ALWAYS

� Pt RESIZE X INITIAL

� Pt RESIZE X BITS

� Pt RESIZE Y AS REQUIRED

� Pt RESIZE Y ALWAYS

� Pt RESIZE Y INITIAL



� Pt RESIZE Y BITS

� Pt RESIZE XY ALWAYS

� Pt RESIZE XY AS REQUIRED

� Pt RESIZE XY INITIAL

� Pt RESIZE XY BITS



Pt ARG ANCHOR FLAGS PtWidget Pt RIGHT ANCHORED LEFT|Pt BOTTOM ANCHORED TOP













continued. . .









Pt ARG DIM PtWidget





Pt ARG FLAGS PtWidget |=Pt GETS FOCUS|Pt HIGHLIGHTED|Pt SET












continued. . .





Pt ARG POS PtWidget


Pt ARG SCROLLAREA FLAGS PtScrollArea

Pt ARG SCROLLAREA INCREMENT X PtScrollArea

Pt ARG SCROLLAREA INCREMENT Y PtScrollArea

Pt ARG SCROLLAREA MAX X PtScrollArea

Pt ARG SCROLLAREA MAX Y PtScrollArea

Pt ARG SCROLLAREA POS X PtScrollArea

Pt ARG SCROLLAREA POS Y PtScrollArea

Pt ARG SCROLLBAR X DISPLAY PtScrollArea

Pt ARG SCROLLBAR X HEIGHT PtScrollArea

Pt ARG SCROLLBAR Y DISPLAY PtScrollArea

Pt ARG SCROLLBAR Y WIDTH PtScrollArea








Pt CB ARM PtBasic


continued. . .








Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget




Pt CB SCROLLAREA SCROLLED PtScrollArea



PtSeparator 2004, QNX Software Systems Ltd.

Separator for organizing widgets

Class hierarchy:PtWidget → PtBasic → PtSeparator

PhAB icon:

Public header:<photon/PtSeparator.h>

Description:PtSeparator provides a separator line with various styles. Youshould find it handy when creating menus, or for organizing areas thathold a lot of widgets.

PtSeparator widgets, as used to organize the items in a menu.

New resources:


2004, QNX Software Systems Ltd. PtSeparator


Pt ARG SEP ARM BITMAP CURSOR PhBitmapCursorDescription t * Alloc NULL

Pt ARG SEP ARM CURSOR COLOR PgColor t Scalar Ph CURSOR DEFAULT COLOR

Pt ARG SEP ARM CURSOR TYPE unsigned short Scalar Ph CURSOR INHERIT

Pt ARG SEP DRAG BOUNDS PhRect t Struct NULL

Pt ARG SEP FLAGS short Flag Pt SEP HORIZONTAL

Pt ARG SEP IMAGE PhImage t * Image NULL

Pt ARG SEP IMAGE H ALIGN unsigned char Scalar Pt LEFT

Pt ARG SEP IMAGE V ALIGN unsigned char Scalar Pt TOP

Pt ARG SEP TYPE unsigned short Scalar Pt SINGLE LINE

Pt CB SEP DRAG PtCallback t * Link NULL

Pt ARG SEP ARM BITMAP CURSOR


PhBitmapCursorDescription t * Alloc NULL

A pointer to a PhBitmapCursorDescription t, which representsthe cursor which is used when the separator is armed and beingdragged.

You can’t edit this resource in PhAB.

The widget automatically sets the hdr member of thePhBitmapCursorDescription t and PhBitmapCursorData t

structures.

The PhBitmapCursorDescription t contains at least these members:

hdr A PhCursorDescription t structure that isautomatically filled in by the widget.



bmp A PhBitmapCursorData t structure that describes thebitmap.

The PhCharacterCursorDescription t contains at least thesemembers:

hdr A PhCursorDescription t structure.

color A PgColor t structure that describes the backgroundcolour of the bitmap.

The PhBitmapCursorData t contains at least these members:

hdr A pointer to a PhRegionDataHdr t structure thatdefines the region data header.

size1 The dimensions of the first bitmap plane, in pixels.

offset1 The position of the upper-left corner of the firstplane of the bitmap, relative to the hot spot.

color1 The color of the first bitmap plane.

bytesperline1 The number of bytes per line for the first bitmapplane.

size2 The dimensions of the second bitmap plane, inpixels.

offset2 The position of the upper-left corner of the secondplane of the bitmap, relative to the hot spot.

color2 The color of the second bitplane. You can havemore than two bitplanes.

bytesperline2 The number of bytes per line for the second bitmapplane.

images The bitmap image data, as a series of1-bit-per-pixel planes.



Pt ARG SEP ARM CURSOR COLOR


PgColor t Scalar Ph CURSOR DEFAULT COLOR

A PgColor t structure that defines the color for the cursor specifiedby the Pt ARG SEP ARM CURSOR TYPE, which is used when theseparator is armed and being dragged. For more information, seePgColor t in the Photon Library Reference.

Pt ARG SEP ARM CURSOR TYPE


unsigned short Scalar Ph CURSOR INHERIT

The cursor type which is used when the separator is armed and beingdragged. It can be:

Ph CURSOR INHERIT

Inherit the cursor, not from the class hierarchy, but from thefamily hierarchy; that is, from the way your application neststhe widgets. The cursor might even be inherited from thePhoton server itself.

Ph CURSOR BITMAP

Use the bitmap stored inPt ARG SETP ARM BITMAP CURSOR for the cursor.

Pt ARG SEP DRAG BOUNDS


PhRect t Struct NULL

The dragging boundary for the separator. This resource is used whendragging is initiated (see the Pt SEP DRAGGABLE flag). The default



of this resource is the widget’s parent’s canvas. Set the resource toNULL to use the defaults.

Pt ARG SEP FLAGS


short Flag Pt SEP HORIZONTAL

Flags that control the separator’s appearance. Possible values:

Pt SEP ORIENTATION

If this bit is Pt SEP VERTICAL, the separator is vertical. If thisbit is Pt SEP HORIZONTAL, the separator is horizontal.

Pt SEP DRAGGABLE

The separator can be dragged within its parent’s canvas, or bythe bounding rectangle specified by via tthePt SEP DRAG BOUNDS resource.

Pt SEP DRAW DRAG BAND

Enable rubber band drawing while dragging the widget.

Pt ARG SEP IMAGE


PhImage t Image NULL

You can use this resource to create your own style of separator. Itspecifies an image to be used as the separator. Set to NULL to disableimage drawing. For more information about PhImage t, see thePhoton Library Reference.



Pt ARG SEP IMAGE H ALIGN


unsigned char scalar Pt LEFT

The separator’s horizontal image alignment. Can be one of:

� Pt LEFT

� Pt CENTER

� Pt RIGHT

Pt ARG SEP IMAGE V ALIGN


unsigned char scalar Pt TOP

The separator’s vertical image alignment. Can be one of:

� Pt TOP

� Pt CENTER

� Pt BOTTOM

Pt ARG SEP TYPE


unsigned short Scalar Pt SINGLE LINE

The type of separator. Possible values:

� Pt SINGLE LINE

� Pt DOUBLE LINE

� Pt SINGLE DASH LINE

� Pt DOUBLE DASH LINE



� Pt ETCHED IN

� Pt ETCHED OUT

� Pt NOLINE

Pt CB SEP DRAG



A list of PtCallback t structures that define the callbacks involvedwhen you drag the separator widget.

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

reason Pt CB SEP DRAG

reason subtype

One of:

� Pt INIT — the separator was armed

� Pt MOVED — the separator was dragged

� Pt DONE — the separator was disarmed; look thePhDragEvent t structure of the event member tofind out more details.


cbdata A pointer to a PtSeparatorCallback t structurewhich contains at least contains PhRect t, a separatorrectangle relative to its parent.








Pt ARG BANDWIDTH THRESHOLD PtBasic See below.













Pt ARG DIM PtWidget



continued. . .



















Pt ARG POS PtWidget







Pt CB ARM PtBasic

continued. . .







Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget





Pt ARG BANDWIDTH THRESHOLD defines the "graphicsbandwidth" threshold over which the separator drag mode is switchedto drag outline mode, as if the Pt SEP DRAW DRAG BAND flag wasset. This optimizes the number of events in low bandwidth situations,such as when you are using phrelay. Note that this resource onlyapplies when the separator is draggable.

By default this resource is set to Ph BAUD NETWORK.

For more information about the system bandwidth, seePtQuerySystemInfo() and PhSysInfo t.


PtServer 2004, QNX Software Systems Ltd.

Server widget

Class hierarchy:PtWidget → PtBasic → PtContainer → PtDisjoint →PtRegion → PtServer

PhAB icon:None — instantiate it by calling PtCreateWidget().

Public header:<photon/PtServer.h>

Description:PtClient and PtServer allow one process (the “server”) to displaywidgets in a window that belongs to another process (the “client”).

PtClient and PtServer use a Photon connection to communicate(see “Connections” in the Interprocess Communications chapter ofthe Photon Programmer’s Guide), but they have a few resources thatin most cases let applications avoid dealing with connection objectsdirectly.

A PtServer widget displays its contents inside the PtClient it’sattached to. The contents can be any widgets you choose to put inyour PtServer widget. Additionally, PtServer lets yourapplication send arbitrary messages to the client process.

When a PtServer is attached to a PtClient, it’s the client thatdecides what size your server should be and when it should berealized, unrealized, and destroyed.

Don’t try to resize, realize, unrealize, or destroy a PtServer widgetthat’s connected to a client. Don’t exit from an application that hasactive PtServer widgets. If you need to do any of those things, youshould do it by sending a message to ask the client to do theappropriate action on its PtClient widget instead.

�


2004, QNX Software Systems Ltd. PtServer

New resources:


Pt ARG SERVER CONNECTION PtConnectionServer t * Pointer NULL

Pt ARG SERVER NAME char * String NULL

Pt ARG SERVER SEND char[], int Array (writeonly)

Pt CB SERVER CONNECTED PtCallback t * Link NULL

Pt CB SERVER ERROR PtCallback t * Link NULL

Pt CB SERVER RECEIVE PtCallback t * Link NULL

Pt CB SERVER TRANSPORT PtCallback t * Link NULL

Pt ARG SERVER CONNECTION


PtConnectionServer t * Pointer NULL

A pointer to the connection object used for communicating to thePtClient. If you get the value of this resource, don’t use this pointerfor anything other than checking to see if it’s NULL.

You can set this resource, provided that the widget isn’t connected toa client yet. This is useful in a server application that has a connectorthat multiple clients can connect to. This kind of server has aconnector callback that creates a PtServer widget and gives the newconnection object to its Pt ARG SERVER CONNECTION resource(see PtConnectorCreate() in the Photon Library Reference for moredetails about connectors).

In a server that just creates one PtServer widget, thePt ARG SERVER NAME resource is a simpler way of connecting to aclient.



Pt ARG SERVER NAME


char * String NULL

When you set this resource, the widget creates a connector and lets aclient connect to it. After the client has connected, the connector isautomatically destroyed.

Pt ARG SERVER SEND (write only)


char[], int Array

When you set this resource, the widget sends the given message to theclient PtClient that invokes the Pt CB CLIENT EVENT callback.

Pt CB SERVER CONNECTED



A list of PtCallback t structures that define the callbacks invokedwhen a client connects to the widget.


reason Pt CB SERVER CONNECTED

reason subtype

0 (not used).

event NULL (not used).

cbdata NULL.




Pt CB SERVER ERROR



A list of PtCallback t structures that define the callbacks that areinvoked when an error occurs.


reason Pt CB SERVER ERROR

reason subtype

0 (not used).


cbdata A pointer to a PtServerErrorCallback t structurethat contains at least:

� int action — the value that the PtConnectionServererror handler will return. It’s initialized to Pt END. Setit to Pt CONTINUE to retry the failed operation.

Not all operations are retried if an error handler returnsPt CONTINUE. For example, a MsgReply() is never retried.

�

� int errnum — the errno value from the error handler.

� int where — the value (of type enumPtConnectionServerError) that describes whatoperation failed.

If this value is Pt CONNECTION SERVER BROKEN, the widget isdestroyed after the callback returns.

�




Pt CB SERVER RECEIVE



A list of PtCallback t structures that define the callbacks that areinvoked when the server receives a message sent by the client’sPt ARG CLIENT SEND resource.


reason Pt CB SERVER RECEIVE

reason subtype

0 (not used).


cbdata A pointer to a PtServerCallback t structure thatcontains at least:

� void const *message — the message from theclient.

� unsigned msg len — its length, in bytes.

� void *reply — set this to point to your reply buffer.

� unsigned reply len — put its length here.


Pt CB SERVER TRANSPORT





A list of PtCallback t structures that define the callbacks that areinvoked when the PtClient that the PtServer is attached to isrealized in a Photon session different from the one that the server isconnected to. This can happen when the client is being transported toa different Photon.


reason Pt CB SERVER TRANSPORT

reason subtype

0 (not used).


cbdata A pointer to the pathname of the new Photon device.









continued. . .

















Pt ARG DIM PtWidget










continued. . .












Pt ARG POS PtWidget










Pt CB ARM PtBasic





continued. . .





Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget







2004, QNX Software Systems Ltd. PtSliderA widget for choosing a value from a range

Class hierarchy:PtWidget → PtBasic → PtGauge → PtSlider

PhAB icon:

Public header:<photon/PtSlider.h>

Description:A PtSlider widget lets you choose numerical values within aspecified range from minimum to maximum.

A PtSlider widget.

A slider consists of a narrow trough (representing the total range), amovable handle, and optional tick marks. The handle — whichappears on top of the trough — represents the current position withinthe range. You can specify the size of the handle by settingPt ARG SLIDER HANDLE WIDTH.

If you want to create your own style of slider, you can specify:

� Pt ARG SLIDER IMAGE to replace the default handle

� Pt ARG SLIDER TROUGH IMAGE1 andPt ARG SLIDER TROUGH IMAGE2 to replace the defaulttrough.


PtSlider 2004, QNX Software Systems Ltd.

A PtSlider widget with a custom handle and trough.

You need to set Pt ARG SLIDER FLAGS appropriately to use theseimages.

Mouse actions

When you press the mouse button, the result depends on the locationof the pointer.

If the pointer is: Then:

In the trough The handle moves up or down one slidermultiple

On the handle A drag is started

If you hold down the Ctrl key and click in the trough, the handlejumps to the position of the pointer.

Keyboard actions


↑ Up one increment

↓ Down one increment

→ Right one increment

← Left one increment

Pg Up Up/right one “page”

continued. . .


2004, QNX Software Systems Ltd. PtSlider


Pg Down Down/left one “page”

Home To the minimum value

End To the maximum value

where:

� The size of a “page” is determined by thePt ARG SLIDER MULTIPLE resource.

� The locations of the minimum and maximum value depend on thePt ARG ORIENTATION and Pt ARG GAUGE FLAGS resourcesinherited from PtGauge.

New resources:


Pt ARG SLIDER FLAGS short int Flag 0

Pt ARG SLIDER HANDLE COLOR PgColor t Scalar PgGrey(217)

Pt ARG SLIDER HANDLE WIDTH short int Scalar 15

Pt ARG SLIDER IMAGE PhImage t * Image NULL

Pt ARG SLIDER INCREMENT ushort t Scalar 1

Pt ARG SLIDER MULTIPLE ushort t Scalar 10

Pt ARG SLIDER TICK MAJOR DIV short int Scalar 10

Pt ARG SLIDER TICK MAJOR LEN short int Scalar 10

Pt ARG SLIDER TICK MINOR DIV short int Scalar 0

Pt ARG SLIDER TICK MINOR LEN short int Scalar 0

continued. . .




Pt ARG SLIDER TROUGH IMAGE1 PhImage t * Image NULL

Pt ARG SLIDER TROUGH IMAGE2 PhImage t * Image NULL

Pt CB SLIDER MOVE PtCallback t * Link NULL

Pt ARG SLIDER FLAGS


short int Flag 0

Valid flags:

Pt SLIDER IMAGE

Use the image specified by Pt ARG SLIDER IMAGE as theslider handle.

Pt SLIDER TROUGH IMAGE

Use the images specified byPt ARG SLIDER TROUGH IMAGE1 andPt ARG SLIDER TROUGH IMAGE2 as the trough.

Pt ARG SLIDER HANDLE COLOR


PgColor t Scalar PgGrey(217)

The color of the slider handle. See PgColor t in the Photon LibraryReference.

Pt ARG SLIDER HANDLE WIDTH




short int Scalar 15

The width of the slider handle.

Pt ARG SLIDER IMAGE



You can use this resource to create your own style of slider. Itspecifies an image to be used as the slider’s handle. For moreinformation about the PhImage t structure, see the Photon LibraryReference.

The widget ignores this resource unless you set Pt SLIDER IMAGE inPt ARG SLIDER FLAGS.

�

Pt ARG SLIDER INCREMENT


ushort t Scalar 1

The slider increment when you press the cursor keys.

Pt ARG SLIDER MULTIPLE


ushort t Scalar 10

The slider increment when you click the pointer button in the trough,or you press Pg Up or Pg Down.



Pt ARG SLIDER TICK MAJOR DIV


short int Scalar 10

The number of major divisions.

Pt ARG SLIDER TICK MAJOR LEN


short int Scalar 10

The length of the major ticks, in pixels.

Pt ARG SLIDER TICK MINOR DIV


short int Scalar 0

The number of minor divisions per major division.

Pt ARG SLIDER TICK MINOR LEN


short int Scalar 0

The length of the minor ticks, in pixels.

Pt ARG SLIDER TROUGH IMAGE1, Pt ARG SLIDER TROUGH IMAGE2





You can use these resources to create your own style of slider. Usethem to specify the images to be displayed as the trough. The sliderbecomes the same size as Pt ARG SLIDER TROUGH IMAGE1.

The widget ignores these resources unless you setPt SLIDER TROUGH IMAGE in Pt ARG SLIDER FLAGS.

�

If you specify just Pt ARG SLIDER TROUGH IMAGE1, it’s used asthe background for the entire slider.

If you specify both images:

� Pt ARG SLIDER TROUGH IMAGE1 is displayed from theminimum value of the slider to the current handle position.

� Pt ARG SLIDER TROUGH IMAGE2 is displayed from thecurrent handle position to the maximum value.

If the image specified by Pt ARG SLIDER TROUGH IMAGE2 is adifferent size than the one specified byPt ARG SLIDER TROUGH IMAGE1, you should use anon-transparent color to avoid drawing artifacts when the handleposition changes.

�

By default, the maximum value is on the right side of a horizontalslider. The widget displays the first image to the left of the handle,and the second image to the right. If you setPt GAUGE MAX ON LEFT in the Pt ARG GAUGE FLAGS resource(inherited from PtGauge), the widget displays the first image to theright of the handle, and the second image to the left.

You get similar results with a vertical slider if you setPt GAUGE MAX ON TOP.



The images aren’t rotated if you change the slider’sPt ARG ORIENTATION resource (inherited from PtGauge). Youshould create horizontal images for a horizontal slider, and verticalimages for a vertical slider.

�

For more information about the PhImage t structure, see the PhotonLibrary Reference.

Pt CB SLIDER MOVE



A list of PtCallback t structures that define the callbacks that theslider invokes when the handle position changes.

If you’ve set the Pt CALLBACKS ACTIVE bit set in the widget’sPt ARG FLAGS resource, these callbacks are also invoked when yourapplication changes the handle position by calling PtSetResource() orPtSetResources().


reason Pt CB SLIDER MOVE

reason subtype

One of the following:

� Pt SLIDER INCREMENT

� Pt SLIDER DECREMENT

� Pt SLIDER MULTIPLE INCREMENT

� Pt SLIDER MULTIPLE DECREMENT

� Pt SLIDER DRAGGED

� Pt SLIDER RELEASED

� Pt SLIDER TO MIN



� Pt SLIDER TO MAX

� Pt SLIDER JUMP

� Pt SLIDER SET


cbdata A pointer to a PtSliderCallback t structure thatcontains at least the following member:

int position; A value corresponding to the sliderhandle’s location.












continued. . .





Pt ARG COLOR PtBasic Pg GRAY







Pt ARG DIM PtWidget





Pt ARG FLAGS PtWidget |=Pt GETS FOCUS

Pt ARG GAUGE FLAGS PtGauge |=Pt GAUGE MAX ON TOP


Pt ARG GAUGE H ALIGN PtGauge Not used by this class.

Pt ARG GAUGE V ALIGN PtGauge Not used by this class.


Pt ARG GAUGE VALUE PREFIX PtGauge Not used by this class.

Pt ARG GAUGE VALUE SUFFIX PtGauge Not used by this class.



continued. . .














Pt ARG ORIENTATION PtGauge Pt HORIZONTAL



Pt ARG POS PtWidget







Pt CB ARM PtBasic



continued. . .





Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget





2004, QNX Software Systems Ltd. PtTabA tab button for initiating an action

Class hierarchy:PtWidget → PtBasic → PtLabel → PtTab

PhAB icon:

Public header:<photon/PtTab.h>

Description:The PtTab class draws a tab such as is found on a file folder.Clicking the tab invokes an application callback.

A group of PtTab widgets positioned at the top of a PtPane.

Instead of using a PtTab, you should use a PtPanelGroup. This isthe preferred method, since PtPanelGroup manages all aspects of atabbed panel for you.

If you insist on using PtTab widgets, you typically:

� Group the tabs together and set the Pt GROUP EXCLUSIVE bit inthe PtGroup widget’s Pt ARG GROUP FLAGS resource. Thisflag allows only one of the tabs to be set at a time.

� Use other PtGroup flags and resources to make the tabs the samesize, aligned horizontally, and so on. For more information, see“Aligning widgets using groups” in the Geometry Managementchapter of the Photon Programmer’s Guide.

� Place the tabs at the top of a PtPane or some other container. Usethe same border width for the tabs and the container, and line up


PtTab 2004, QNX Software Systems Ltd.

the top of the container’s border with the top of the bevel on thetab.

� Use PhAB’s Picture module and internal links to change thecontents of the container widget for the tabs. For moreinformation, see the Photon Programmer’s Guide.

New resources:


Pt ARG TAB FLAGS unsigned int Flag 0

Pt TAB UNSELECTED COLOR PgColor t Scalar PgGray(0xc0)

Pt ARG TAB FLAGS


unsigned int Flag 0

Flags that affect how the widget appears. The defined bits are:

Pt TAB UPSIDE DOWN

Vertically invert the tab; display the rounded corners on thebottom of the widget instead of the top.

Pt TAB RIGHTSIDE LEFT

Horizontally invert the tab.

Pt TAB DRAG HANDLE

Show a textured drag handle within the tab, visually indicatingthat the associated panel can be pulled away. You need to writesome code to support the dragging (PtPanelGroup supports italready).


2004, QNX Software Systems Ltd. PtTab

Pt TAB MULTI

Indicate that this tab produces a popup panel of some sort whenpressed (the term “multi” is used since, in this case, the tabgenerally represents multiple choices). You need to write somecode to this (PtPanelGroup supports it already).

Pt TAB UNSELECTED COLOR


PgColor t Scalar PgGray(0xc0)

The color of the tab when it isn’t selected (i.e. not set). SeePgColor t in the Photon Library Reference.

When the tab is set, it gets its color from Pt ARG FILL COLOR (seePtBasic).










continued. . .
















Pt ARG DIM PtWidget



Pt ARG FILL COLOR PtBasic PgGray(170)


Pt ARG FLAGS PtWidget |=Pt CLIP HIGHLIGHT|Pt TOGGLE



Pt ARG HIGHLIGHT ROUNDNESS PtBasic 3



continued. . .





















Pt ARG POS PtWidget






continued. . .













Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget


continued. . .






Convenience functions:The PtTab widget defines the following macros that make it easier touse the tab once it’s been created:

PtTabIsUpsideDown()

Return a nonzero value if the tab is upside down, 0otherwise

PtTabIsRightsideUp()

Return a nonzero value if the tab is rightside up, 0otherwise

PtTabIsRightsideLeft()

Return a nonzero value if the tab is flippedleft-to-right, 0 otherwise

PtTabIsRightsideRight()

Return a nonzero value if the tab isn’t flippedleft-to-right, 0 otherwise

PtTabIsDraggable()

Return a nonzero value if the panel can be draggedaway, 0 otherwise

PtTabIsMulti() Return a nonzero value if the tab produces a popuppanel of some sort when pressed, 0 otherwise

PtTabDragHandleRect()

Retrieve the rectangle that encompasses the dragarea of the tab


PtTerminal 2004, QNX Software Systems Ltd.

A window that emulates a character-mode terminal

Class hierarchy:PtWidget → PtBasic → PtContainer → PtTerminal


� PtTty

PhAB icon:

Public header:<photon/PtTerm.h>

Description:The PtTerminal class provides a text window emulating a characterterminal.

A PtTerminal widget.

You can send characters to the terminal by calling PtTerminalPutc(),PtTerminalPut() and PtTerminalPuts(). If you type in the terminal, the


2004, QNX Software Systems Ltd. PtTerminal

keyboard input is passed to the widget via the Pt CB TERM INPUTcallback.

Other convenience functions and callbacks support the followingkinds of user interaction:

� resizing the terminal window

� changing the displayed font

� scrolling

� other activities permitted through escape sequences. Forinformation about specific escape sequences, see devc-con in theQNX Neutrino Utilities Reference.

PtTerminal uses some Ctrl – Alt combinations for cutting andpasting, changing font sizes, and so on, but all Alt-key combinationsthat are defined for text mode are passed to your text-modeapplication, provided that the window manager lets PtTerminal seethem.

The window manager intercepts certain Alt-key combinations unlessyou set Ph WM STATE ISALTKEY in the Pt ARG WINDOW STATEresource of the PtWindow that contains the PtTerminal.

�

PtTerminal and PtTty

The main difference between PtTerminal and PtTty is thatPtTerminal doesn’t do any I/O for you. The only way to displaycharacters in a PtTerminal is by giving them to one of thePtTerminalPut*() functions. Similarly, the only thing PtTerminaldoes with Photon input is translate function keys into text-modecompatible escape sequences and give the result to yourPt CB TERM INPUT callback.

PtTty adds device I/O to that. The code that opens a pty, readscharacters from it, and gives those characters to PtTerminalPut() ispart of PtTty. Similarly, PtTty attaches a Pt CB TERM INPUT



callback that writes Photon keyboard input (translated byPtTerminal to text-mode compatible format) to the pty.

Another responsibility of PtTty is spawning a command for you andinvoking the Pt CB TTY TERMINATED callbacks when thecommand terminates.

Fonts

Your application program can use Pt ARG TERM FONT to set anexplicit font name, or Pt ARG TERM FONT INDEX to choose a fontfrom the list of supported fonts, Pt ARG TERM FONT LIST .

If you set the Pt TERM KBFONT bit in Pt ARG TERM RESIZE FL,you can select a font using the keyboard:

� Press Ctrl – Alt – < or Ctrl – Alt – [ to decrement the value ofPt ARG TERM FONT INDEX by one (unless it’s already at 0) orset it to the maximum value (if the current value is -1).

� Press Ctrl – Alt – > or Ctrl – Alt – ] to increment the value ofPt ARG TERM FONT INDEX by one (unless it’s already at themaximum value).

The Pt TERM KBFORCE flag affects any resizing that occurs whenthe above keychords are used:

� If this flag isn’t set, the above keystrokes simply set thePt ARG TERM FONT INDEX resource.

� If the flag is set, the [ and ] keys adjust the window size to keep theterminal size (rows/columns) while the < and > keys attempt toadjust the terminal size within the current window size.

If you’ve set the Pt TERM OPFONT flag, you can use escapesequences to set the font:

� If you use Pt ARG TERM FONT to set the font, and the new fontname is equal to one of the names on the current font list,Pt ARG TERM FONT INDEX is set to the index of that list item.When the Pt ARG TERM FONT LIST resource is set, the widget



also attempts to find the current font name on the list and set theindex.

� If the font list contains an invalid font name, you can setPt ARG TERM FONT INDEX to its index, but the current fontisn’t changed.

Character sets

PtTerminal uses two 8-bit character sets:

Internal character set

What the widget uses to store characters internally. Thischaracter set is also used in QNX mode as the “text-modecharacter set” (i.e. anything that you pass to PtTerminalPut() isassumed to use this character set, and Photon key events gettranslated to this character set before being passed to thePt CB TERM INPUT callback).

In ANSI mode, the internal character set can be used for thedisplay by setting one of the G0...G3 character sets to “the PCcharacter set.” The escape sequences that do it are:

ESC ( UESC ) UESC * UESC + U

See the documentation for devc-con in the QNX NeutrinoUtilities Reference.

ANSI character set

What’s used in ANSI mode. It’s the default setting for the G2character set (which is used by default for characters above0x9F). It’s also the character set to which Photon key events gettranslated in the ANSI mode.

By default, the internal character set is the PC character set (“IBMcode page 437”) and the ANSI character set is ISO 8859-1.



PtTerminal lets you choose any 8-bit character sets — the onlyrequirement is that they must be supersets of ASCII: PtTerminaltranslates only codes above 0x7F.

By default, PtTerminal assumes that the Photon font used for thedisplay is encoded using the internal character set (in particular, allthe terminal fonts shipped with Photon use the PC character set ratherthan Unicode). Your application can define an additional mapping; forexample, you can use a Unicode font to display any character sets inPtTerminal.

The Pt ARG TERM CHARSETS resource stores the current charactersets.

Resource changes and function reentrancy

When the PtTerminalPut*() functions parse the output stream, certainescape sequences contained in the stream may cause resource changesthat invoke callback functions. The callback functions shouldn’t callany of the PtTerminalPut*() functions to output text to the sameterminal widget that invoked the callback because the protocol enginefunction isn’t reentrant. Recursion is allowed, but only when each ofthe nested calls outputs data to a different terminal widget. Otherwise,the PtTerminalPut*() functions return -1 to indicate an illegal call.

Geometry

The groups of resources that affect a terminal widget’s geometry are:

Dimensions Pt ARG DIM and Pt ARG AREA (see PtWidget)

Margins Pt ARG MARGIN HEIGHT ,Pt ARG MARGIN WIDTH (see PtBasic), andPt ARG TERM MARGINS

Terminal size Pt ARG TERM SIZE, Pt ARG TERM ROWS, andPt ARG TERM COLS

Font Pt ARG TERM FONT andPt ARG TERM FONT INDEX



A widget’s dimensions can be calculated as long as terminal size, fontResizing

size, and margins are known. Thus, whenever one of these resourcesis changed, another resource — or sometimes even two resources —must be adjusted too.

The return value of the function attached to thePt ARG TERM RESIZE FUN resource (known as the resize function)determines how the widget is resized. The function is called with twooutput arguments: the first is a pointer to a string that describes whichresource is changing and how, and the second is the value of widget’sPt ARG TERM RESIZE STR resource.

Each character in the string has a specific meaning. The first characteris a resource identifier that describes which resource is changing:

D (dimension) Change Pt ARG DIM and Pt ARG AREA.

M (margin) Change Pt ARG MARGIN WIDTH andPt ARG MARGIN HEIGHT .

S (size) Change Pt ARG TERM SIZE,Pt ARG TERM ROWS, and Pt ARG TERM COLS.

F (font) Change Pt ARG TERM FONT .

The next series of characters provide the details, starting with thecharacter x or y to specify direction (horizontal or vertical). The nextcharacter can be one of the following:

Character Meaning

- The value is decreasing.

+ The value is increasing.

= The value didn’t change (used only when the size ormargin is changing).



Additional characters can be given to indicate resources that aren’tsufficient alone to adjust the widget because these resources havelimited values. An m means that the adjustment must involve aresource other than the margins, and an s means that the adjustmentmust involve a resource other than the terminal size.

The result of the “resize function” is a string specifying the order ofAdjustingafter aresize

the resources used in the adjustment process. The adjustment can beperformed in both directions, but if the original resource changedoesn’t affect horizontal or vertical dimensions, only the affecteddirection is adjusted.

The resize function may either return a static string or use the bufferpassed in the first argument. The buffer size is at least 10 bytes. ANULL pointer is equivalent to an empty string.

Each character in the adjustment string has a specific meaning:

x Perform a horizontal adjustment on the following characters.

y Perform a vertical adjustment on the following characters.

d Adjust the Pt ARG DIM resource.

s Adjust the Pt ARG TERM SIZE resource.

m Adjust the Pt ARG MARGIN WIDTH and/orPt ARG MARGIN HEIGHT resource and copy the new valueto the Pt ARG TERM MARGINS resource.

M Adjust the Pt ARG TERM MARGINS resource.

For example, xsym adjusts the number of columns (xs) and themargin height (ym).

Before any adjustments specified by the string are done,Pt ARG TERM MARGINS is reset to the values ofPt ARG MARGIN HEIGHT and/or Pt ARG MARGIN WIDTH.

Adjusting the dimension is always successful, while adjusting the sizeor margin isn’t always sufficient — size is limited and must be amultiple of the font size, and margin must be nonnegative.



After the adjustments specified by the string are done, the dimensionis adjusted to make sure that the new values are coherent. Thus,specifying a d is always superfluous and specifying anything after a dhas no effect unless it specifies a different direction.

The default function uses only the resource identifier (i.e. D, M, S or F)The defaultresize

functiongiven in the first argument. The function assumes that thePt ARG TERM RESIZE STR resource string given in the secondargument consists of segments delimited by colons.

Each of the segments consists of a list of letters that define resources,an equality symbol (=), and the string that’s returned if the resourceidentifier matches one of the letters in the list.

The default value of the Pt ARG TERM RESIZE STR resource isD=sM:M=s, which means:

� If the dimension has changed (D), sM is returned. The size andmargin of the widget are adjusted. If the sizes couldn’t be matched(that is, the new dimensions are smaller than the minimum size),the dimension is readjusted.

� If a margin is changed (M), s is returned, and the widget attemptsto adjust the appropriate size component (rows or columns), afterwhich the dimension is adjusted to fit the exact margin width orheight.

� If font (F) or size (S) is changed, the corresponding resourceidentifier isn’t found on the default list and an empty string isreturned. The terminal’s margin is set according to the marginwidth and height resources, and then the dimension is recalculated.

Size limits

Other resources that may affect geometry are the size limits:

� Pt ARG TERM MINSIZE

� Pt ARG TERM MINROWS

� Pt ARG TERM MINCOLS



� Pt ARG TERM MAXSIZE

� Pt ARG TERM MAXROWS

� Pt ARG TERM MAXCOLS

When a limit is being set to a value that makes the current sizeinvalid, the current size is adjusted. If a minimum is set to a valuelarger than the corresponding maximum, then both the maximum andthe current size are also set to this value.

The opposite is also true: if a maximum is changed, thecorresponding minimum may be adjusted. This means that if youwant to set the limits and size to arbitrary values regardless of theircurrent values, you should set the limits before the size.

The minimum size (together with font and margins) determines alsominimal values for the Pt ARG DIM resource. There’s no upper limitfor the dimensions because there’s no upper limit forPt ARG TERM MARGINS.

Console emulation

A PtSetResources() call for the Pt ARG TERM CONSOLE writesdata directly to the widget’s screen buffer.

First, your application should fill a PtTerminalConsoleWrite t

structure:

void const *buffer

A pointer to the data to be written.

unsigned short offset

The offset into the widget’s screen buffer at which to write thedata.

unsigned short nbytes

The number of bytes to write.

Pass a pointer to the structure as the second argument to PtSetArg().When you call PtSetResources(), the widget transfers the actual



screen data from the buffer given by the application to the widget’sscreen buffer. Then the corresponding area of the widget is damagedin order to display the new data. PtSetResources() doesn’t check tosee if the offset and length given by your application exceed the sizeof the buffer.

If you call PtGetResources() to get Pt ARG TERM CONSOLE,you’re given a pointer to the buffer. If your application wishes to getthe contents of a specific fragment of the screen, it must calculate theoffset to the desired position in the buffer and copy the data.

Color coding

The Pt ARG TERM COLOR TABLE resource is an array used by thewidget for mapping color numbers into Photon PgColor t colorvalues (see the Photon Library Reference). Color numbers are indexesinto this array. The default array has 16 elements corresponding to 16standard CGA colors.

Pt ARG FILL COLOR (see PtBasic) defines the color of themargins.

The background color of the terminal defaults to black — or whateverthe Pt ARG TERM COLOR TABLE resource defines as entry 0. Ifyou want a different background color, you can either change thecolor table or set the background color by sending appropriate escapesequences to the terminal using PtTerminalPut(). The latter isprobably safer if the widget is a PtTty that will be running arbitraryprograms in it; programs that use color might look odd if the colors inthe color table differ too much from the default values.

Drawing and scrolling

The Pt ARG TERM DRAW MODES resource defines the widget’sscrolling capability.

If your application gives characters to PtTerminalPut() in a largeScrollingoptimization portion that consists of many lines that scroll through the terminal, the

widget may attempt to optimize drawing speed.



Instead of blitting h-1 lines (where h is the height of the terminal inlines) and drawing the bottom line on each scroll, the widget blits h-nlines (if h-n is positive) and draws min(h,n) lines every n scrolls.

The limit for the actual value of n is determined byPt ARG BANDWIDTH THRESHOLD (see PtBasic),Pt ARG TERM SCROLL, and Pt ARG TERM DRAW MODES, andby the current graphics bandwidth (see PhQuerySystemInfo() in thePhoton Library Reference). If the connection is slow and thePt TERM SCROLL NOSPEEDCHK bit inPt ARG TERM CURSOR FLAGS is clear, there’s no limit for n.Otherwise, the maximal value of n is the value of thePt ARG TERM SCROLL resource.

Drag and Drop


New resources:


Pt ARG TERM ANSI PROTOCOL int Boolean 1

Pt ARG TERM APP PtTerminalAppState t Struct See below

Pt ARG TERM CHARSETS PtTerminalCsXlatData t * Pointer See below

Pt ARG TERM COLOR MODE PtTerminalColorMode t Struct Pt TERM COLOR MODE

Pt ARG TERM COLOR TABLE PgColor t[], short Array CGA colors, 16

Pt ARG TERM COLS short Scalar 80

Pt ARG TERM CONSOLE PtTerminalConsoleWrite t Complex N/A

Pt ARG TERM CUR COL short Scalar 0

continued. . .




Pt ARG TERM CUR POS PtTerminalRowCol t Struct 0, 0

Pt ARG TERM CUR ROW short Scalar 0

Pt ARG TERM CURSOR FLAGS short Flag Pt TERM CURSOR ON FOCUS

Pt ARG TERM DRAW MODES unsigned char Flag Pt TERM SCROLL RFSH

Pt ARG TERM FONT char * String "pcterm14"

Pt ARG TERM FONT INDEX short Scalar -1

Pt ARG TERM FONT LIST char **, short Array NULL, 0

Pt ARG TERM FONT SIZE PhDim t Struct Size of defaultfont (read-only)

Pt ARG TERM MARGINS PhRect t Struct 0, 0, 0, 0(read-only)

Pt ARG TERM MAXCOLS short Scalar 1000

Pt ARG TERM MAXROWS short Scalar 1000

Pt ARG TERM MAXSIZE PtTerminalRowCol t Struct 1000, 1000

Pt ARG TERM MINCOLS short Scalar 1

Pt ARG TERM MINROWS short Scalar 1

Pt ARG TERM MINSIZE PtTerminalRowCol t Struct 1, 1

Pt ARG TERM OPTIONS unsigned long Flag 0x84380

Pt ARG TERM OPTMASK unsigned long Flag ˜0uL

Pt ARG TERM RESIZE FL unsigned short Flag All defined flags

Pt ARG TERM RESIZE FUN See below Pointer Pointer to staticfunction

Pt ARG TERM RESIZE STR char * String "DF=sM:M=s"

Pt ARG TERM ROWS short Scalar 25

continued. . .




Pt ARG TERM SCRLBK COUNT short Scalar 0

Pt ARG TERM SCRLBK LIMIT short Scalar 0

Pt ARG TERM SCRLBK POS short Scalar 0

Pt ARG TERM SCROLL short Scalar Pt TERM MAX ROWS

Pt ARG TERM SELECTION PtTerminalSelection t Struct 0

Pt ARG TERM SIZE PtTerminalRowCol t Struct 25, 80

Pt ARG TERM VISUAL BELL short Scalar 20

Pt CB TERM APP PtCallback t * Link NULL

Pt CB TERM FONT PtCallback t * Link NULL

Pt CB TERM INPUT PtCallback t * Link NULL

Pt CB TERM OPTIONS PtCallback t * Link NULL

Pt CB TERM RESIZE PtCallback t * Link NULL

Pt CB TERM RESIZED PtCallback t * Link NULL

Pt CB TERM SCRLBK PtCallback t * Link NULL

Pt ARG TERM ANSI PROTOCOL


short Boolean 1

The protocol to use for the terminal:

0 QNX4

1 ANSI



Pt ARG TERM APP


PtTerminalAppState t Struct See below

A structure containing the application window’s state, which theprotocol engine needs (see the Pt CB TERM APP callback). Thisstructure also contains some other information that a terminalemulator can use, such as the window title, size, and position.

The PtTerminalAppState t structure is defined as:

typedef struct Pt terminal app state {struct PtTerminal app state bins {

/* Binary part - memcmp can be used for comparing */unsigned version;PhArea t area;PtTerminalRowCol t size;unsigned iconic: 1, infront: 1;}

b;/* Strings - guaranteed to never contain garbage after ’\0’ */char title[ Pt TERM WSTRING MAX + 1 ];char l msg[ Pt TERM WSTRING MAX + 1 ];char icon[ Pt TERM WSTRING MAX + 1 ];char reserved;}

PtTerminalAppState t;

Most of the members of this structure are present mainly forcompatibility with terminal emulators other than pterm, A text-modeprogram might use certain special escape sequences to set thosevalues, and other special escape sequences to query those values. Inpterm, the values are preserved (so your text-mode program sees theexpected responses to escape sequences), but are otherwise ignored.The only exception is title — pterm uses it to set its window title.

If you have a text-mode program that needs a terminal emulator otherthan pterm, you’ll need to use the Pt ARG TERM APP resource andthe Pt CB TERM APP callback.

The members are:



b.version The version number, which is initialized to 100, can bequeried by an escape sequence. It’s useful if you want towrite a terminal emulator that recognizes additionalescape sequences and you want your text-modeprograms to be able to detect whether they’re running ina pterm (version=100) or in your emulator(version=something else).

b.area The area of the PtTerminal widget.

b.size The terminal’s size, in rows and columns.

b.iconic A bit that indicates whether or not the application isiconified (minimized).

b.infront A bit that indicates whether or not the application is infront of all other windows.

title The first part of the window’s title.

l msg The second part of the window’s title.

icon The string to display on the icon instead of the windowtitle.

Pt ARG TERM CHARSETS


PtTerminalCsXlatData t * Pointer See below

This resource handles the character set translation. It’s a pointer totranslation tables stored in a PtTerminalCsXlatData t structure.The contents of the structure aren’t defined in a public header — theonly way to create a PtTerminalCsXlatData t structure is bycalling PtTerminalCreateCsXlat().

If you set Pt ARG TERM CHARSETS to NULL, the widget callsPtTerminalCreateCsXlat() to create its own copy of the default



translation tables. This copy is freed when you destroy the widget orset its Pt ARG TERM CHARSETS resource to a non-NULL value.

PtTerminalCreateCsXlat() doesn’t make a copy of thePtTerminalCharsets t structure passed to it, and PtTerminal

doesn’t make a copy of the PtTerminalCsXlatData t structurewhen you set Pt ARG TERM CHARSETS. Don’t free or modify thesestructures until they’re no longer needed by any widget.

The PtTerminalCsXlatData t structure created byPtTerminalCreateCsXlat() is placed in a single allocated block ofmemory. When it’s no longer needed, you can simply free() it.

�

Pt ARG TERM COLOR MODE


PtTerminalColorMode t Struct Pt TERM COLOR MODE

A set of pointers to conversion functions, used internally by thewidget.

Pt ARG TERM COLOR TABLE


PgColor t[], short Array CGA colors, 16

The color table used for the display. See PgColor t in the PhotonLibrary Reference.

This resource is used to convert color numbers used internally toactual Photon color values. Color numbers are indexes into this array.The default array has 16 elements corresponding to 16 standard CGAcolors:



Index Color

0 BLACK

1 BLUE

2 GREEN

3 CYAN

4 RED

5 MAGENTA

6 BROWN

7 WHITE (light grey)

8 BRIGHT BLACK (dark grey)

9 BRIGHT BLUE

10 BRIGHT GREEN

11 BRIGHT CYAN

12 BRIGHT RED

13 BRIGHT MAGENTA

14 BRIGHT BROWN (yellow)

15 BRIGHT WHITE

Pt ARG TERM COLS


short Scalar 80

The number of character columns.



Pt ARG TERM CONSOLE


PtTerminalConsoleWrite t Complex N/A

You can use this resource to access the widget’s “video memory” Formore information, see “Console emulation,” above.

Pt ARG TERM CUR COL


short Scalar 0

The column number of the cursor’s position.

Pt ARG TERM CUR POS


PtTerminalRowCol t Struct 0, 0

The cursor position. The PtTerminalRowCol t structure containsthe following members:

� short r

� short c

Pt ARG TERM CUR ROW


short Scalar 0

The line number of the cursor’s position.



Pt ARG TERM CURSOR FLAGS


short Flag Pt TERM CURSOR ON FOCUS

Flags affecting the cursor timer. Possible values are:

� Pt TERM CURSOR ON FOCUS — the cursor blinks when thewidget has focus.

� Pt TERM CURSOR ALWAYS — the cursor always blinks.

� Pt TERM CURSOR NEVER (zero) — the cursor never blinks.

� Pt TERM CURSOR TIMER — the timer is activated even if notneeded. This may be useful for getting a raw callback periodically.Note that this timer runs only when the widget is realized.

� Pt TERM CURSOR NOSPEEDCHK — if this flag isn’t set, thecursor won’t blink if the connection to Photon is slow. See alsoPt ARG BANDWIDTH THRESHOLD.

Pt ARG TERM DRAW MODES


unsigned char Flag Pt TERM SCROLL RFSH

Flags that determine scrolling optimization:

� Pt TERM SCROLL NOBLIT — always redraw instead of blitting.

� Pt TERM SCROLL NOHWCHK — attempt to blit even if blittingisn’t supported by hardware.

� Pt TERM SCROLL RFSH — redraw the screen on the first scrolleven if PhBlit() won’t be used.

� Pt TERM SCROLL NOVISCHK — always assume that the widgetisn’t clipped or obscured by other widgets. (Normally, the widget



checks to see if it it’s obscured or clipped by other widgets in sucha way that using PhBlit() would move parts of another widget.)

� Pt TERM SCROLL NOSPEEDCHK — don’t check the bandwidth.If this flag isn’t set and the bandwidth isn’t greater than the valueof the Pt ARG BANDWIDTH THRESHOLD resource, the widgetbehaves as if the Pt TERM SCROLL NOBLIT,Pt TERM SCROLL NOHWCHK, and Pt TERM SCROLL RFSH flagsare clear and the Pt ARG TERM SCROLL resource has a hugevalue.

For more information, see the “Drawing and scrolling” part of the“Description” section above.

Pt ARG TERM FONT


char * String "pcterm14"

The name of the font used for the display. For more information, see“Fonts,” above.

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

�

Pt ARG TERM FONT INDEX


short Scalar -1

The position of the current font in the font list, or -1 if the current fontisn’t in the list. You can use this resource to choose a font from thelist, but you can’t explicitly set it to -1.



Pt ARG TERM FONT LIST


char **, short Array NULL, 0

The list of fonts (an array of pointers to strings).

When you set this resource, the meaning of the value argument of thePtSetArg() macro depends on whether the len argument is zero ornonzero:

� If len is nonzero, value should be a pointer to an array of pointersto font names, and len should be the number of pointers in thearray. The widget replaces the current font list with a copy of thegiven list.

� If len is zero, value should be either NULL or a pointer to string. Ifvalue is NULL, the font list is removed. Otherwise, the given stringis appended to the current list. For more information, see “Fonts,”above.

Pt ARG TERM FONT SIZE (read-only)


PhDim t Struct Size of default font

A PhDim t structure (see the Photon Library Reference) that definesthe dimensions of the font used for the display.

Pt ARG TERM MARGINS (read-only)


PhRect t Struct 0, 0, 0, 0

A PhRect t structure (see the Photon Library Reference) thatcontains the actual width and height of the widget’s margins. Thesevalues are equal to or greater than values of



Pt ARG MARGIN WIDTH and Pt ARG MARGIN HEIGHTresources. For more information, see “Geometry,” above.

Pt ARG TERM MAXCOLS


short Scalar 1000

The maximum number of character columns.

Pt ARG TERM MAXROWS


short Scalar 1000

The maximum number of character rows.

Pt ARG TERM MAXSIZE



The maximum screen size, in character rows and columns. ThePtTerminalRowCol t structure contains the following members:

� short r

� short c

Pt ARG TERM MINCOLS


short Scalar 1

The minimum number of character columns.



Pt ARG TERM MINROWS


short Scalar 1

The minimum number of character rows.

Pt ARG TERM MINSIZE



The minimum screen size, in character rows and columns. ThePtTerminalRowCol t structure contains the following members:

� short r

� short c

Pt ARG TERM OPTIONS


unsigned long Flag 0x84380

A set of flags that can be set or cleared by escape sequences. The flagsare numbered from 1 to 32 (see <photon/PtTerm.h>). The widgethandles some of them, and your application can handle some others.

Pt ARG TERM OPTMASK


unsigned long Flag ˜0uL

A set of bits that correspond to those in Pt ARG TERM OPTIONS.Clearing a bit in Pt ARG TERM OPTMASK disables the escapesequence for the corresponding bit in Pt ARG TERM OPTIONS



Pt ARG TERM RESIZE FL


unsigned short Flag All defined flags

Flags that affect the resizing of the terminal widget. Any combinationof:

� Pt TERM OPFONT — FONT can be set with escape sequences.

� Pt TERM KBFONT — FONT can be set with keyboard.

� Pt TERM KBFORCE — when FONT is set with keyboard, keep thewidget’s SIZE or DIM (depending on the key sequence).

� Pt TERM ANCHOR PARENT WIDTH — resize the parent widget’swidth if the terminal’s right edge is anchored to the parent’s rightedge.

� Pt TERM ANCHOR PARENT HEIGHT — resize the parentwidget’s height if the terminal’s bottom edge is anchored to theparent’s bottom edge.

� Pt TERM ANCHOR WINDOWS ONLY — don’t resize the parentunless it’s a window.

Pt ARG TERM RESIZE FUN


See below Pointer Pointer to static function

A pointer to a function to be used in geometry adjustments. Theprototype is:

const char*(*)(char*, const char*)

For more information, see “Geometry,” above.



Pt ARG TERM RESIZE STR


char * String "DF=sM:M=s"

A hint for the function used in geometry adjustments. For moreinformation, see “Geometry,” above.

Pt ARG TERM ROWS


short Scalar 25

The number of character rows.

Pt ARG TERM SCRLBK COUNT


short Scalar 0

The current number of lines saved in the scrollback buffer.

Pt ARG TERM SCRLBK LIMIT


short Scalar 0

The maximum of number of lines saved in the scrollback buffer.

Pt ARG TERM SCRLBK POS


short Scalar 0



The current position in the scrollback buffer (reset to zero on anyoutput, including the Pt ARG TERM CONSOLE resource).

Pt ARG TERM SCROLL


short Scalar Pt TERM MAX ROWS

The maximum number of scrolls that will be delayed. For moreinformation, see “Scrolling optimization,” above.

Pt ARG TERM SELECTION


PtTerminalSelection t Struct 0

The PtTerminalSelection t structure contains at least thefollowing members:

unsigned char type;unsigned char old type;unsigned short flags;PtTerminalRowCol t first, last;

where:

type Can be one of:

� Pt TERM SELECTION NONE — no selection.

� Pt TERM SELECTION BLOCK — a block is selected.

� Pt TERM SELECTION STREAM — a stream isselected.

old type The last value of type that differed fromPt TERM SELECTION NONE.

flags Valid flags are:



� Pt TERM SELECTION ALWAYS — the pointeralways selects text.

� Pt TERM SELECTION NEVER — the pointer neverselects text.

� Pt TERM SELECTING (read only) — something isbeing selected.

The following flags aren’t stored in the widget but theytell the widget that the corresponding member of thestructure shouldn’t be modified:

� Pt TERM SELECTION TYPE KEEP — don’t modifytype.

� Pt TERM SELECTION FIRST KEEP — don’t modifyfirst.

� Pt TERM SELECTION LAST KEEP — don’t modifylast.

� Pt TERM SELECTION FLAGS KEEP — don’t modifyflags.

first, last Two positions that define the selected area. If selectedby the mouse, first is the position of the press and last isthe position of the release. The PtTerminalRowCol t

structure contains the following members:

� short r

� short c

Pt ARG TERM SIZE



The screen size, in characters. The PtTerminalRowCol t structurecontains the following members:

� short r



� short c

Pt ARG TERM VISUAL BELL


short Scalar 20

The time, in milliseconds, of the screen flash when the ASCII BELcharacter (Ctrl – G) is received.

Pt CB TERM APP



A list of PtCallback t structures that define the callbacks invokedwhenever the Pt ARG TERM APP resource changes, or a privateescape sequence is received.


reason Pt CB TERM APP

reason subtype

The character or number defining the type of escapesequence.

event NULL

cbdata Either a NULL pointer, or the string contained in theescape sequence.

There are four general sources of the Pt CB TERM APP callback.They can be recognized by the values of the reason subtype andcbdata fields:



reason subtype=0, cbdata=NULL

A change of terminal’s size or font. Before issuing thiscallback, the widget sets the area and size fields of thePt ARG TERM APP resource to the values of the widget’sPt ARG AREA and Pt ARG TERM SIZE resources so that evenif a terminal emulator program doesn’t modify thePt ARG TERM APP resource, the terminal responds properlyto escape sequences that query terminal parameters.

reason subtype=0, cbdata=""

An explicit change of the Pt ARG TERM APP resource.

reason subtype=nonzero, cbdata=NULL

An escape sequence that set some of the data stored in the“binary” part of the Pt ARG TERM APP resource. Thereason subtype field indicates the first parameter of the escapesequence.

reason subtype=nonzero, cbdata=string

An escape sequence that changed one of the strings stored inthe Pt ARG TERM APP resource.

The value of the reason subtype field is the ASCII code of thecharacter that indicates the escape sequence type, and the cbdata fieldpoints to the <string>.


Pt CB TERM FONT



A list of PtCallback t structures that define the callbacks invokedafter the font is changed. Each callback is passed aPtCallbackInfo t structure that contains at least the followingmembers:



reason Pt CB TERM FONT

event NULL

cbdata A pointer to a PtTerminalFontChange t structurethat contains at least the following members:

const char * old font;

Defines the previous font.

const char * new font;

Defines the new font.


Pt CB TERM INPUT



A list of PtCallback t structures that define the callbacks invokedwhen keyboard or mouse input is delivered to the widget. Eachcallback is passed a PtCallbackInfo t structure that contains atleast the following members:

reason Pt CB TERM INPUT

reason subtype

Can be one of:

� Pt TERM KEYBOARD INPUT — for key events otherthan the Break key.

� Pt TERM MOUSE INPUT — for mouse events.

� Pt TERM CTRLBRK INPUT — for the Break key.

� Pt TERM PROTOCOL INPUT — for responses to anescape sequence.



� Pt TERM PASTE INPUT — for pasting from theclipboard.

� Pt TERM PASTE NF INPUT — for pasting from theclipboard.

event A pointer to a PhEvent t structure that describes theevent that caused the callback to be invoked, or NULL ifthe characters are a reply to an escape sequence ratherthan reaction to a keyboard or mouse event.

cbdata A pointer to a PtTerminalInput t structure thatcontains at least the following members:

unsigned length;

The number of characters the key generates (maybe zero if a key was pressed that doesn’t generatecharacters).

const char * string;

A pointer to the buffer containing the characters.

PtTerminalRowCol t position;

In the case of a pointer event, the current mouseposition. In all other cases, the current cursorposition. The PtTerminalRowCol t structurecontains the following members:

� short r

� short c

The widget issues this callback on every keystroke unless both Ctrland Alt modifiers are pressed.

When text is being pasted from the clipboard, the callback subtype isset to Pt TERM PASTE INPUT if the buffer has been allocated with themalloc() function. A callback function can take over the responsibilityfor freeing the buffer by changing the subtype toPt TERM PASTE NF INPUT.




Pt CB TERM OPTIONS



A list of PtCallback t structures that define the callbacks invokedwhenever the Pt ARG TERM OPTIONS resource changes. Eachcallback is passed a PtCallbackInfo t structure that contains atleast the following members:

reason Pt CB TERM OPTIONS

reason subtype

0 if options have been changed via widget resources, or 1if options have been changed by an escape sequence.

event NULL

cbdata A pointer to a PtTerminalOptionChange t structurethat contains at least the following members:

unsigned long old opts;

The previous value of the options.

unsigned long new opts;

The new value of the options.


Pt CB TERM RESIZE





A list of PtCallback t structures that define the callbacks invokedwhen the terminal is about to change its size (i.e the number of rowsand/or columns).


reason Pt CB TERM RESIZE

event NULL

cbdata A pointer to a PtTerminalSizeChange t structurethat contains at least the following members:

PtTerminalRowCol t old size;

The current size of the terminal.PtTerminalRowCol t new size;

The new size.

The PtTerminalRowCol t structure contains thefollowing members:

� short r

� short c

This callback is issued whenever one of the Pt ARG TERM SIZE,Pt ARG TERM ROWS, or Pt ARG TERM COLS resources is set,even if the new value is equal to the old value.

However, if your application calls PtSetResources() with invalid sizevalues (outside of limits defined by Pt ARG TERM MINSIZE andPt ARG TERM MAXSIZE resources), the new size is validated beforeissuing the callback.




Pt CB TERM RESIZED



A list of PtCallback t structures that define the callbacks invokedafter the size is changed.


reason Pt CB TERM RESIZED

event NULL

cbdata A pointer to a PtTerminalSizeChange t structurethat contains at least the following members:


The previous size of the terminal.

PtTerminalRowCol t new size;

The current size.


� short r

� short c

This callback is issued whenever one of the Pt ARG TERM SIZE,Pt ARG TERM ROWS, or Pt ARG TERM COLS resources is set,even if the new value is equal to the old value.

After an unsuccessful attempt to resize the terminal, the callback isissued with cbdata set to NULL.




Pt CB TERM SCRLBK



A list of PtCallback t structures that define the callbacks invokedwhenever the Pt ARG TERM SCRLBK POS resource or the numberof saved lines in the widget’s buffer changes. Each callback is passeda PtCallbackInfo t structure that contains at least the followingmembers:

reason Pt CB TERM SCRLBK

reason subtype

0

event NULL

cbdata A pointer to a PtTerminalScrlbkCb t structure thatcontains at least the following members:

short old count;

The previous value of the line count

short old pos; The previous value of the line position.

short new count;

The new line count.short new pos;

The new line position.

Functions invoked by this callback shouldn’t set any of the widget’sresources.

�
























Pt ARG DIM PtWidget

continued. . .






Pt ARG FILL COLOR PtBasic Pt INHERIT COLOR(see below)















Pt ARG POS PtWidget






continued. . .







Pt CB ARM PtBasic






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget








The threshold value for graphics bandwidth (as reported byPhQuerySystemInfo()) that defines a slow connection. For moreinformation, see Pt ARG TERM CURSOR FLAGS and “Scrollingoptimization,” above.

Pt ARG FILL COLOR

The color of widget’s margins. When set to Pt INHERIT COLOR, thewidget draws margins using the “saved” fill color, which can be set tothe current fill color using an escape sequence:

In QNX mode:

ESC S

In ANSI mode:

ESC [ 8 ]

Convenience functions:The PtTerminal widget defines the following convenience functionsand data structures that make it easier to use the terminal once it’sbeen created:

PtTerminalCharset t, PtTerminalCharsets t

Character sets used by PtTerminal

PtTerminalCopy()

Copy the current selection to the clipboard.

PtTerminalCreateCsXlat().

Create a translation table for PtTerminal’s character sets.

PtTerminalDefaultCharsets():

Get the default character sets used by PtTerminal.

PtTerminalFontInfo()

Examine a font.



PtTerminalGetKeys()

Get the terminal line-editing keys.

PtTerminalGetSelection()

Get a copy of the current selection.

PtTerminalName()

Get the terminal’s termcap/terminfo name.

PtTerminalPasteClipboard()

Paste the contents of the clipboard into the terminal.

PtTerminalPasteSelection()

Paste the current selection into the terminal.

PtTerminalPut(), PtTerminalPutc(), PtTerminalPuts()

Output text to the terminal.

PtTerminalSelectWord()

Select a word.


PtTerminalCharset t,PtTerminalCharsets t 2004, QNX Software Systems Ltd.

Character sets used by PtTerminal

Synopsis:typedef struct {

const unsigned short *table;unsigned char first, last;...} PtTerminalCharset t;

typedef struct {unsigned short from, to;} PtTerminalCharSubst t;

typedef struct {PtTerminalCharset t const *AnsiCharset;PtTerminalCharset t const *InternalCharset;PtTerminalCharset t const *FontTranslation;PtTerminalCharSubst t const *Subst;unsigned short NumSubst;...} PtTerminalCharsets t;

Description:The PtTerminalCharset t and PtTerminalCharsets t

structures define character sets used internally and externally byPtTerminal.

Both structures have some undocumented members at the end,reserved for future extensions. To be safe, make sure that they’refilled with zeros. The order of the documented members will stay thesame — it’s safe to initialize these structures statically.

�

A PtTerminalCharset t structure defines an 8-bit character set bydefining its mapping to Unicode. This is how this mapping can beexpressed in C:

wchar t unicode value( unsigned char ch,PtTerminalCharset t const *cs ) {

wchar t result;


2004, QNX Software Systems Ltd. PtTerminalCharset t,PtTerminalCharsets t

if ( ch < 0x80 )return ch; /* ch is an ASCII character */

else {if ( ch >= cs->first && ch <= cs->last

&& ( result = cs->table[ cs - cs->first ] ) != L’\0’ )/* ch is mapped to a Unicode value */return result;

else/* ch is an illegal value */return NO MAPPING DEFINED;

}}

If a character set contains “illegal values”, they’re displayed as blanksand are never generated from a key event. But in general, it’s a goodidea to avoid having illegal values in a character set — preferably, theinternal character set should define all values from 0x80 to 0xFF andthe ANSI character set should define all values from 0xA0 to 0xFF.

You can set AnsiCharset or InternalCharset (or both) to NULL; thefunction then uses the defaults (8859-1 for AnsiCharset and PCcharacter set for InternalCharset). It’s also possible to get to theactual tables that define the defaults by callingPtTerminalDefaultCharsets():

const PtTerminalCharsets t *PtTerminalDefaultCharsets( void );

The FontTranslation defines the mapping from the internal characterset to whatever character set your Photon font is using. In otherwords, if FontTranslation isn’t NULL, PtTerminal uses the 16-bitcode returned by:

unicode value( internal char, FontTranslation )

to display the 8-bit internal code internal char. Note that if you wantthe widget to use Unicode, FontTranslation should point to the samecharacter set as InternalCharset.

If FontTranslation is NULL, the font is assumed to be compatible withthe internal character set, and no mapping is used.

The Subst field points to an array that lists character substitutions thatthe widget uses when a character is missing from the character set that


PtTerminalCharset t,PtTerminalCharsets t 2004, QNX Software Systems Ltd.

it needs to be translated to. The array must be sorted with the respectto the from field. NumSubst defines the length of the array.

The situations where the substitutions are performed are:

� When the widget receives a key event containing a Unicodesymbol that doesn’t exist in the current text-mode character set(i.e. either the ANSI character set or the internal character set,depending on the current terminal emulation), the widget searchesthe Subst array for an entry where from is the character in the eventand to is a character that exists in the text-mode character set. Ifsuch an entry exists, the to character is used instead of the symbolin the event. If multiple matching entries exist in the table, the firstone is used. If none exists, the event doesn’t generate any terminalinput.

� In the ANSI mode, characters written to the terminal must beconverted from the ANSI character set to the internal character setbefore they can be displayed. If the ANSI character set containscharacters that the internal character set doesn’t contain, the Substarray is searched for a replacement character. If none is found, thecharacter is displayed as a space.


See also:PtTerminal, PtTerminalDefaultCharsets()


2004, QNX Software Systems Ltd. PtTerminalCopy()Copy the current selection to the clipboard

Synopsis:void PtTerminalCopy( PtWidget t *widget,

PhEvent t *event );

Description:This function copies the current selection in the given PtTerminal

widget to the clipboard. The event parameter is used to select theinput group; see PhClipboardCopyString() in the Photon LibraryReference.


Safety


Signal handler No

Thread No

See also:PtTerminal



PtTerminalCreateCsXlat() 2004, QNX Software Systems Ltd.

Create a translation table for PtTerminal’s character sets

Synopsis:PtTerminalCsXlatData t *PtTerminalCreateCsXlat(

PtTerminalCharsets t const *csets );

Description:This function creates a translation table for the character sets used byPtTerminal. The PtTerminalCsXlatData t structure is forinternal use only; you must use this function to create it.

The csets argument is a pointer to a PtTerminalCharsets t

structure that defines the character sets and their translation.

Returns:A pointer to a PtTerminalCsXlatData t structure that you canuse to set the Pt ARG TERM CHARSETS resource of a PtTerminalwidget.

PtTerminalCreateCsXlat() doesn’t make a copy of thePtTerminalCharsets t structure pointed to by csets, andPtTerminal doesn’t make a copy of thePtTerminalCsXlatData t structure when you setPt ARG TERM CHARSETS. Don’t free these structures until they’reno longer needed by any widget.

The PtTerminalCsXlatData t structure created byPtTerminalCreateCsXlat() is placed in a single allocated block ofmemory. When it’s no longer needed, you can simply free() it.

�


Safety


continued. . .


2004, QNX Software Systems Ltd. PtTerminalCreateCsXlat()

Safety

Signal handler No

Thread No

See also:PtTerminal, Pt ARG TERM CHARSETS,PtTerminalCharsets t


PtTerminalDefaultCharsets() 2004, QNX Software Systems Ltd.

Get the default character sets used by PtTerminal

Synopsis:const PtTerminalCharsets t *

PtTerminalDefaultCharsets( void );

Description:This function returns a pointer to the tables that define the defaultcharacter sets used by PtTerminal.

Returns:A pointer to the tables.


Safety


Signal handler No

Thread No

See also:PtTerminal, PtTerminalCharsets t


2004, QNX Software Systems Ltd. PtTerminalFontInfo()Convert the font name to a fixed-width font name

Synopsis:int PtTerminalFontInfo( const char *font,

PhDim t *size,PhPoint t *offs );

Description:This function makes sure that the given font exists and is afixed-width font. It returns an allocated copy of the name. If theappropriate font doesn’t exist, PtTerminalFontInfo() returns NULL.

This function stores information about the font’s geometry atlocations pointed to by size and offs:

� If size isn’t NULL, the width and height of the character cell arestored in the PhDim t structure (see the Photon LibraryReference) it points to.

� If offs isn’t NULL, the function stores, in the PhPoint t structurethat it points to, the position that should be given to a drawingfunction in order to draw the character cell starting at position (0,0).

Returns:0 if the font name exists and is a fixed-width font, and -1 if not.


Safety


Signal handler No

Thread No


PtTerminalFontInfo() 2004, QNX Software Systems Ltd.

See also:PtTerminal


2004, QNX Software Systems Ltd. PtTerminalGetKeys()Get the terminal line-editing keys

Synopsis:void PtTerminalGetKeys( int protocol,

struct termios *buf );

Description:This function fills the following items of the buf ->c cc array withvalues appropriate for the given protocol:

� VPREFIX

� VSUFFIX

� VLEFT

� VRIGHT

� VUP

� VDOWN

� VINS

� VDEL

� VHOME

� VEND

The other fields of the structure aren’t modified. For moreinformation, see the Pt ARG TERM ANSI PROTOCOL resourceassociated with the PtTerminal widget.



PtTerminalGetKeys() 2004, QNX Software Systems Ltd.

Safety


Signal handler No

Thread No

See also:PtTerminal


2004, QNX Software Systems Ltd. PtTerminalGetSelection()Get a copy of the current selection

Synopsis:char *PtTerminalGetSelection( PtWidget t *widget );

Description:This function returns a copy of the current selection (or NULL ifthere’s no selection).

It’s your application’s responsibility to free() the buffer when it’s nolonger needed.

�


Safety


Signal handler No

Thread No

See also:PtTerminal


PtTerminalName() 2004, QNX Software Systems Ltd.

Get the terminal termcap or terminfo name

Synopsis:const char *PtTerminalName( int protocol );

Description:This function returns a terminal name (one of qnxm or qansi-m),based on the given protocol.

For more information, see the Pt ARG TERM ANSI PROTOCOLresource associated with the PtTerminal widget.


Safety


Signal handler No

Thread No

See also:PtTerminal


2004, QNX Software Systems Ltd. PtTerminalPasteClipboard()Paste the contents of the clipboard into the terminal

Synopsis:void PtTerminalPasteClipboard( PtWidget t *widget,

PhEvent t *event );

Description:This function pastes the contents of the clipboard into the terminal’s“keyboard” by invoking the widget’s Pt CB TERM INPUT callback.The given event is passed to the callback functions. If event isn’tNULL, event->input group also selects the clipboard; seePhClipboardPasteString() in the Photon Library Reference.


Safety


Signal handler No

Thread No

See also:PtTerminal



PtTerminalPasteSelection() 2004, QNX Software Systems Ltd.

Paste the current selection into the terminal

Synopsis:void PtTerminalPasteSelection( PtWidget t *widget,

PhEvent t *event );

Description:This function pastes the current selection into the terminal’s“keyboard” by invoking the widget’s Pt CB TERM INPUT callback.The given event is passed to the callback functions.


Safety


Signal handler No

Thread No

See also:PtTerminal



2004, QNX Software Systems Ltd. PtTerminalPut(),PtTerminalPutc(), PtTerminalPuts()

Output text to the terminal

Synopsis:int PtTerminalPut( PtWidget t *widget,

const char *buffer,size t nchars );

int PtTerminalPutc( PtWidget t *widget,char character );

int PtTerminalPuts( PtWidget t *widget,const char *string );

Description:These functions output characters to the terminal widget.

Returns:0 Success.

-1 An error occurred (errno is set).

Errors:EINVAL The widget isn’t a terminal widget.

EBUSY Invalid recursion.


Safety


Signal handler No

Thread No


PtTerminalPut(), PtTerminalPutc(),PtTerminalPuts() 2004, QNX Software Systems Ltd.

See also:PtTerminal


2004, QNX Software Systems Ltd. PtTerminalSelectWord()Select a word

Synopsis:int PtTerminalSelectWord(

PtWidget t *widget,PtTerminalRowCol t const *pos );

Description:This function selects a word containing the character at the specifiedposition (or at the cursor position if pos is NULL).

The PtTerminalRowCol t structure contains the followingmembers:

� short r

� short c

Returns:1 Done.

0 There’s no word at the specified position (neither the characterat the specified position nor the character to the left is a letter,digit or underscore).

-1 The pos argument is invalid (i.e. beyond the screen size).


Safety


Signal handler No

Thread No


PtTerminalSelectWord() 2004, QNX Software Systems Ltd.

See also:PtTerminal


2004, QNX Software Systems Ltd. PtTextSingle-line text

Class hierarchy:PtWidget → PtBasic → PtLabel → PtText

PhAB icon:

Public header:<photon/PtText.h>

Description:The Photon text widgets let you type textual information into atext-entry box. The widgets provide basic editing features, so you canalter text that’s entered. They also support a point-and-click model ofediting, so that you can operate on blocks of text as a unit.

A PtText widget.

Photon provides two different text widgets:

� PtText — a small, simple widget that provides a single-linedata-entry field. You can’t change the attributes of the text in thefield — the same font and color are used throughout the text string.

� PtMultiText — a full-featured text editor that handles multiplelines of text. You can select blocks of text and assign to themdifferent text attributes (e.g. you can display the text in severaldifferent fonts and colors).

Interaction model

The text that you enter in the text widget is either inserted into oroverwrites the existing text, depending on the insertion mode. Thelocation where text is inserted or replaced is visually represented by acursor.


PtText 2004, QNX Software Systems Ltd.

In insert mode, the cursor appears as a vertical bar or pipe (|)between two characters. When you enter a character, it appears at thecursor location, and the cursor is moved to the right of that character.

In replace mode, the cursor appears as an underline ( ) beneath acharacter. When you enter a new character, it replaces the character atthe cursor location, and the cursor is moved to the next character inthe text.

Selecting text

Clicking the mouse button once changes the cursor location to thecharacter position nearest the pointer location. Dragging the pointerwith the button pressed selects a range of text as the object of asubsequent operation. The selected range of text, which begins at thecursor position and ends at the pointer location, is highlighted byinverting the foreground and background colors used to display thetext. Releasing the button completes the range selection.

You can extend the range of text selected by dragging with the Shiftkey pressed. The selected range of text is changed to the text betweenthe current cursor position and the pointer location. The extension ofthe range of text is completed when the button is released.

Any character you type after selecting a range of text replaces theselected range. Your application can also specify a string to replacethe selected range.

The widget’s text

To modify the text widget’s contents within a program, you must beable to access the text widget’s internal storage. The primary meansof access to this text is through the Pt ARG TEXT STRING resource(inherited from PtLabel).

When you set the widget’s text using Pt ARG TEXT STRING, youSetting text

must give a null-terminated C string as a value.

The following short program creates a text widget whose initialcontents are the string “hello, world...”:

#include <Pt.h>


2004, QNX Software Systems Ltd. PtText

PhArea t area = { {0, 0}, {200,40} };

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

PtAppContext t app;int nargs = 0;PtArg t args[4];PtWidget t *window;


PtSetArg(&args[nargs++], Pt ARG POS, &area.pos, 0);PtSetArg(&args[nargs++], Pt ARG DIM, &area.size, 0);PtSetArg(&args[nargs++], Pt ARG WINDOW TITLE, "hello", 0);if ((window = PtCreateWidget(PtWindow, Pt NO PARENT,

nargs, args)) == NULL)PtExit(EXIT FAILURE);

nargs = 0;area.pos.y = 15;PtSetArg(&args[nargs++], Pt ARG POS, &area.pos, 0);PtSetArg(&args[nargs++], Pt ARG DIM, &area.size, 0);PtSetArg(&args[nargs++], Pt ARG TEXT STRING,

"hello, world...", 0);PtCreateWidget(PtText, window, nargs, args);

PtRealizeWidget(window);PtMainLoop();

}

You can retrieve the widget’s text as a null-terminated C string byGetting text

getting the value of the Pt ARG TEXT STRING resource with thePtGetResources() function.

For more information, see “Getting resources” in the ManipulatingResources in Application Code chapter of the Photon Programmer’sGuide.

You can obtain the range of characters in the current selection byGetting thecurrent

selectionusing the PtTextGetSelection() function. This function takes thewidget as the first parameter and returns the start and end position inthe remaining two parameters. You can pass the range to otherconvenience functions to modify the selected text.



Your application can change any block of text in the widget by callingReplacingtext PtTextModifyText(). The arguments are:

widget A pointer to the text widget.

start pos The start position of the range of text to be replaced.

end pos The end position of the range of text to be replaced.

cur insert The position to place the cursor before the change.

text The UTF-8 string to replace the block of text.

length The number of multibyte characters in the string.

Text-modification callbacks

Your application can monitor and control changes made to thewidget’s text using the text-modification callbacks. These callbacksare invoked when you type new text. If the widget has thePt CALLBACKS ACTIVE bit set in its Pt ARG FLAGS resource, thesecallbacks are also invoked when your application changes the text ischanged by calling PtSetResource(), PtSetResources(), or aconvenience function such as PtTextModifyText(). Thetext-modification callbacks are:

Pt CB MODIFY VERIFY

Called before any changes are made to the text.

Pt CB MODIFY NOTIFY (also known as Pt CB TEXT CHANGED)Called after a change.

The Pt CB MODIFY VERIFY callback is useful for validatingValidation

changes before they’re made to the widget. You can use this callbackto alter the text modification or prevent it entirely.

This callback can manipulate the text modification via the cbdatamember of the PtCallbackInfo t structure passed to it. Thecbdata member is a pointer to a text-callback structure. This is a



PtTextCallback t structure if the widget is a PtText, and aPtMultiTextCallback t structure if the widget is aPtMultiText widget.

The following example shows how the text member of the abovestructure can be modified to alter the text inserted into the widget. Theexample uses the allcaps() callback function to convert any lowercasecharacters to uppercase before they’re inserted into the widget.

#include <Pt.h>#include <stdlib.h>#include <ctype.h>

int allcaps(PtWidget t *, void *, PtCallbackInfo t *);

main(int argc, char *argv[]){PtAppContext t app;PhRect t extent;PhPoint t pos;PhPoint t dim;PtArg t args[6];int nargs;PtWidget t *window, *text, *label;


/* Labels work with UTF-8 (multibyte character) strings.International characters can be entered only from aneditor that supports UTF-8 */

nargs = 0;PtSetArg(&args[nargs], Pt ARG MARGIN HEIGHT, 4, 0);nargs++;

if ((window = PtCreateWidget(PtWindow, Pt NO PARENT,nargs, args)) == NULL)


nargs = 0;PtSetArg(&args[nargs], Pt ARG TEXT STRING, "Enter Text:", 0);nargs++;label = PtCreateWidget(PtLabel, window, nargs, args);

PtExtentWidget(label);PtWidgetExtent(label, &extent);pos.x = extent.lr.x + 4;pos.y = 0;



nargs = 0;PtSetArg(&args[nargs], Pt ARG COLUMNS, 20, 0); nargs++;PtSetArg(&args[nargs], Pt ARG POS, &pos, 0); nargs++;text = PtCreateWidget(PtText, window, nargs, args);PtAddCallback(text, Pt CB MODIFY VERIFY, allcaps, NULL);


PtMainLoop();}

int allcaps( PtWidget t *w, void *client data,PtCallbackInfo t *info)

{int len;PtTextCallback t *cbs = (PtTextCallback t

*)info->cbdata;

if (cbs->text == NULL)return Pt CONTINUE;

for ( len = 0; len < cbs->length; len++ )if (islower(cbs->text[len]))

cbs->text[len] = toupper(cbs->text[len]);

return Pt CONTINUE;}

You can prevent the text from being added to the widget by setting thePreventingthe

modificationdoit member of the PtTextCallback t structure to zero or bysetting the length member to zero.

Setting the length to 0 stops the widget from inserting the text; itdoesn’t prevent any deletion included in the modification.

�

You can determine if a modification is replacing or deleting a block ofHandlingdeletions text by checking start pos and end pos. If these values differ, then a

block of text is being removed from the widget and may potentiallybe replaced by new text contained in the text member.

Be sure to handle backspaces correctly. As well as checking for adifferent start and end position, an application can determine which of



Backspace or Delete was pressed by checking the length, cur insert,and new insert:

� If length is zero, then no text replaces the deleted range — youmost likely pressed the Delete key or the destructive backspacekey.

� If new insert is less than cur insert, you pressed the destructivebackspace key.

� If new insert equals cur insert, you pressed the Delete key.

The following simple example of accepting a password as inputExample:entering apassword

illustrates how to handle all editing operations (including pasting)correctly:

/* This program creates two text widgets for enteringa password:

- one offscreen to collect the password- one onscreen in which to type.

All characters are displayed as stars in the onscreenwidget but are saved in the offscreen widget. This isdone by making the displayed widget’s callbacksmanipulate the offscreen widget’s text.

*/

#include <Pt.h>#include <stdio.h>#include <stdlib.h>

int check passwd(PtWidget t *, void *, PtCallbackInfo t *);int update passwd(PtWidget t *, void *, PtCallbackInfo t *);

PtWidget t *displayed text, *offscreen text;

main(int argc, char *argv[]){PhRect t extent;PhPoint t pos;PtArg t args[2];int nargs;PtWidget t *window, *label;




nargs = 0;PtSetArg(&args[nargs++], Pt ARG MARGIN HEIGHT, 4, 0);

if ((window = PtCreateWidget(PtWindow, Pt NO PARENT,nargs, args)) == NULL)


nargs = 0;PtSetArg( &args[nargs++], Pt ARG TEXT STRING,

"Enter Text:", 0);label = PtCreateWidget( PtLabel, Pt DEFAULT PARENT,

nargs, args);

PtExtentWidget(label);PtWidgetExtent(label, &extent);pos = extent.lr;pos.x += 4;pos.y = 0;

/* Create the displayed text widget: */

nargs = 0;PtSetArg(&args[nargs++], Pt ARG POS, &pos, 0);PtSetArg(&args[nargs++], Pt ARG COLUMNS, 20, 0);displayed text = PtCreateWidget( PtText, Pt DEFAULT PARENT,

nargs, args);PtAddCallback(displayed text, Pt CB MODIFY VERIFY,

update passwd, NULL);PtAddCallback(displayed text, Pt CB ACTIVATE,

check passwd, NULL);

/* Create an offscreen text widget: */

pos.x = -1000;nargs = 0;PtSetArg(&args[nargs++], Pt ARG POS, &pos, 0);offscreen text = PtCreateWidget( PtText, Pt DEFAULT PARENT,

nargs, args);


PtMainLoop();}

int check passwd( PtWidget t *widget, void *client data,PtCallbackInfo t *info )

{

/* This callback gets the password out of the offscreenwidget. It’s invoked when you activate the displayed



widget (e.g. by pressing Enter). */

PtTextCallback t *cbs = (PtTextCallback t*)info->cbdata;

char *passwd;PtGetResource( offscreen text, Pt ARG TEXT STRING,

&passwd, 0 );if (info->reason subtype == Pt EDIT ACTIVATE)

printf("Password: %s\n", passwd);


int update passwd( PtWidget t *widget, void *client data,PtCallbackInfo t *info )

{

/* This callback is invoked when you type in the displayedwidget, but it passes the typing to the offscreen widget.The characters are replaced by the same number of starsin the displayed widget.

You need as many stars in the string below as charactersthat you allow in the password. */

PtTextCallback t *tcb = (PtTextCallback t *)info->cbdata;static const char stars[] = "********************";

PtSetResource( offscreen text, Pt ARG TEXT SUBSTRING, tcb, 0 );tcb->text = stars;


After you’ve entered the new text into the widget, theStringchanges Pt CB TEXT CHANGED or Pt CB MODIFY NOTIFY callback list

is invoked. You can use this callback to keep track of changes afterthey’ve been made. This is useful in form-filling applications and texteditors to determine if the contents of the text buffer are “dirty” (i.e.the user modified them).

This callback uses the same text-modification callback structure as thePt CB MODIFY VERIFY callback. The text member of this structurecontains a UTF-8 string indicating the current contents of the textwidget (i.e. the entire text buffer).



As an example, you can use this callback in form-filling applicationsto provide a visual cue to indicate that one or more fields within theform have changed. The user then knows that the pending changeswon’t take effect until they’re applied, usually by pressing an Applyor OK button.

To use this callback in this way:

1 Create the form, including the Apply and Cancel buttons. TheApply button should have the Pt GHOST and Pt BLOCKED bitsset in its Pt ARG FLAGS resource (see PtWidget) to give it aninactive or disabled appearance.

2 Attach a callback function to the Pt CB TEXT CHANGEDcallback list. Make sure this callback turns off the Pt GHOSTand Pt BLOCKED bits for the Apply button.

Another possibility is to create a check button beside each field in theform when the user alters the field’s contents. Activating the checkbutton causes the new value to take effect.

Focus callbacks

The text widget inherits callbacks from PtBasic that tell yourapplication either that the text widget has gained or lost focus.

The text widget gains focus when the user either clicks on the textwidget or presses the Tab key to move from another widget into thisone.

When the text widget obtains the focus by either of these two means,any callbacks defined in its Pt CB GOT FOCUS callback list arecalled. This is useful if your application wishes to alter theappearance of a text widget that the user is entering text into, or totrigger the update of a status field providing hints to a user using a“novice” mode of the interface.

The Pt CB LOST FOCUS callback is invoked any time the userswitches focus away from the text widget, either by tabbing to orclicking within another widget. You can use this callback to undo anychange in the text widget’s appearance that the application made to



indicate that the widget had focus. The callback can also be useful inchecking any syntax in the fields within a form.

Cursor-movement callbacks

You can track changes to the text cursor position representing thecurrent insertion point by adding a cursor movement callback to thePt CB MOTION VERIFY callback list. The callback is invoked everytime:

� You move the cursor by using the arrow keys.

Or:

� You click the SELECT pointer button.

Or:

� Your application calls a widget convenience function that modifiesthe text buffer, causing the cursor to be moved.

The reason member given in the callback info for this callback isPt CB MOTION VERIFY. The event member indicates the type ofaction that caused the callback to be invoked.

You can determine the type of action that caused the callback to beinvoked by making a comparison on the event member. If it’s set toNULL, the callback was invoked as a result of an application functioncall. Otherwise, the callback was invoked as a result of a user action(such as a pointer button press or keypress event).

The event member is a pointer to a PhEvent t structure (see thePhoton Library Reference) that describes the user’s action. Todifferentiate between a pointer event and a keypress event, look at thetype of that event.

The cbdata member of info is a pointer to the same type oftext-modification callback structure used by the other text widgetcallbacks. This callback uses the cur insert, new insert, and doitmembers of the structure. Your application can set the doit member tozero to prevent the cursor movement from taking place.



Activate callback

The PtText widget inherits an activate callback from PtBasic,Pt CB ACTIVATE, that’s invoked when one of the following occurs:

� You press the Enter key within the widget. This signals that anychanges to the field are complete and your application can use thenew value.

The reason subtype in the callback information isPt EDIT ACTIVATE. The callback data is a pointer to the sametext-modification callback structure as used by thetext-modification callbacks. The text member of that structurecontains a UTF-8 string indicating the contents of the buffer.

� You click on the widget and Pt SELECTABLE is set in itsPt ARG FLAGS. In this case, the reason subtype in the callbackinformation is 0, and the callback is as described for PtBasic.

� You modified the text, moved focus to another widget, andPt CHANGE ACTIVATE is set in the text widget’sPt ARG TEXT FLAGS.

The reason subtype in the callback information isPt CHANGE ACTIVATE. The callback data is a pointer to the sametext-modification callback structure as used by thetext-modification callbacks. The text member of that structurecontains a UTF-8 string indicating the contents of the buffer.

The reason code in the callback information is alwaysPt CB ACTIVATE.

When only one text field is contained within a container widget (e.g. adialog), the activate callback is often chained to the activate action onthe dialog. In other words, for a prompt dialog, typing a new value inthe text field and pressing the Enter key has the same effect aspressing the dialog’s OK button after entering the new value.



Edit masks

The PtText widget provides an edit mask that lets you specify apattern for the text entered into the text field. Any characters that youtype must conform to this pattern or they’re rejected.

Edit masks can be difficult to use and aren’t very flexible; use aPt CB MODIFY VERIFY callback instead.

�

The string entered into a data-entry field often conforms to someformat. The text widget can use an edit mask to ensure that theinformation is in the correct format.

You can provide a single edit mask for the text widget by setting thePt ARG EDIT MASK resource. This resource is a null-terminatedtext string that acts as a template for text entered in the text field.Each character that you type must match the corresponding characterin the edit mask.

Here are the characters that you can specify in the edit mask, alongwith the characters they match:

This character: Matches:

# Any single numeric digit

X Any character (don’t care)

A Any alphabetic character (the letters A-Z)

n Any alphanumeric character (the letters A-Z orany numeric digit). All alphabetic charactersare converted to lowercase.

N Any alphanumeric character (the letters A-Z orany numeric digit). All alphabetic charactersare converted to uppercase.

continued. . .



This character: Matches:

c Any alphabetic character (the letters A-Z). Allcharacters are converted to lowercase.

C Any alphabetic character (the letters A-Z). Allcharacters are converted to uppercase.

d Any alphanumeric character (the letters A-Z orany numeric digit), but without case conversion.

Any other character that appears in the edit mask is assumed to be aconstant character that must appear at that position in the text field.When you’ve typed enough characters to reach that position, thecharacter is automatically inserted. After that, you can’t delete or alterit.

As an example, Canadian postal codes must consist of uppercasealphabetic characters and numbers in the following order: character,digit, character, space, digit, character, digit. For example, QNXSoftware System’s postal code is K2M 1W8. So, a text field forentering a postal code might specify C#C #C# as the edit mask. Thetext field widget enforces the constraints on the characters you typeand automatically adds the space character.

Mouse actions

If you: The widget:

Press the mouse button Gets input focus

Press the mouse button and drag themouse

Extends the text selection

Release the mouse button Ends the text selection



Keyboard actions

If you press: The widget:

Any character Inserts the typed character

→ Moves the cursor to the right

← Moves the cursor to the left

Home Moves the cursor to the beginning of the line

End Moves the cursor to the end of the line

Shift – → Extends the text selection to the right

Shift – ← Extends the text selection to the left

Shift – Home Extends the text selection to the beginning of theline

Shift – End Extends the text selection to the end of the line

Backspace Deletes the previous character

Delete Deletes the current character

Enter Processes the text

Tab Moves the cursor to the next text field

Shift – Tab Moves the cursor to the previous text field

Ctrl – → Moves the cursor to the next word

Ctrl – ← Moves the cursor to the previous word

Ins Toggles between insert and replace modes

Drag and Drop




New resources:


Pt ARG COLUMNS short Scalar 0

Pt ARG CURSOR POSITION int Scalar -1

Pt ARG EDIT MASK char * Scalar NULL

Pt ARG MAX LENGTH short Scalar SHRT MAX

Pt ARG SELECTION RANGE See below Complex See below

Pt ARG TEXT CURSOR WIDTH char Scalar 1

Pt ARG TEXT FLAGS unsigned long Flag Pt CURSOR VISIBLE

| Pt EDITABLE |

Pt INSERT MODE

Pt ARG TEXT HIGHLIGHT BACKGROUND COLOR PgColor t Scalar Pt DEFAULT COLOR

Pt ARG TEXT HIGHLIGHT TEXT COLOR PgColor t Scalar Pt DEFAULT COLOR

Pt ARG TEXT SUBSTRING See below Complex See below

Pt CB MODIFY NOTIFY PtCallback t * Link NULL

Pt CB MODIFY VERIFY PtCallback t * Link NULL

Pt CB MOTION NOTIFY PtCallback t * Link NULL

Pt CB MOTION VERIFY PtCallback t * Link NULL

Pt CB TEXT CHANGED PtCallback t * Link NULL

Pt ARG COLUMNS


short Scalar 0



The number of “M” characters that fit in the field horizontally. Thewidget uses this resource only if the width component of thePt ARG DIM resource is 0.

Pt ARG CURSOR POSITION


int Scalar -1

The cursor position. A value of 0 indicates that the cursor is placedbefore the first character, 1 before the second character, and so on.

Pt ARG EDIT MASK


char * Scalar NULL

A string that serves as an input filter for the text field. Each characterin the string determines the acceptable input for the correspondingcharacter position in the text field. The edit mask can contain thefollowing:

X Any character.

A Alphabetic characters only.

# Numeric characters only.

d Alphanumeric characters.

N Alphanumeric characters. All alphabeticcharacters are converted to uppercase.

n Alphanumeric characters. All alphabeticcharacters are converted to lowercase.

C Alphabetic characters only. All alphabeticcharacters are converted to uppercase.



c Alphabetic characters only. All alphabeticcharacters are converted to lowercase.

Anything else Treated as a place holder, and appears as is,without alteration, in the text field. The cursor“steps over” place holders.

See “Edit masks,” above.

Edit masks can be difficult to use and aren’t very flexible; use aPt CB MODIFY VERIFY callback instead.

�

Pt ARG MAX LENGTH


short Scalar SHRT MAX

The maximum text length that the widget accepts.

Pt ARG SELECTION RANGE


See below Complex See below

You can use this resource to select a range of text or determine whattext is currently selected. This resource is complex, and requiresspecial handling:

� When setting, set the value argument to PtSetArg() to the addressof a PtTextControl t structure. Use the start pos and end posmembers of the structure to indicate the range of text to behighlighted (selected). If end pos is -1 or beyond the end of thestring, the widget sets the end of the range to the last characterposition of its text. Always set the doit member to 1.

� When getting, set the value to the address of a pointer to aPtTextControl t structure. The widget sets the start pos and



end pos members to hold the currently highlighted selected range.If no range is currently selected, start pos is -1. Don’t free() thisstructure.

The len isn’t used when setting or getting this resource.

You can call PtTextGetSelection() or PtTextSetSelection() instead ofusing this resource.

Pt ARG TEXT CURSOR WIDTH


char Scalar 1

The width, in pixels, of the cursor.

Pt ARG TEXT FLAGS


unsigned long Flag Pt CURSOR VISIBLE |Pt EDITABLE | Pt INSERT MODE

Valid flags:

Pt CHANGE ACTIVATE

If the text is changed and the widget loses focus,invoke the Pt CB ACTIVATE callback with thePt CHANGE ACTIVATE subtype.

For more information, see the description ofPt CB ACTIVATE in “Inherited resources,” below.

Pt CURSOR VISIBLE

Display the cursor. Default is on.

Pt EDITABLE Make the text editable. Default is on.

Pt INSERT MODE

Toggle insert/replace mode. Default is insert (on).



Pt TEXT AUTO HIGHLIGHT

Highlight the text when the widget is given focus.Default is off.

Pt ARG TEXT HIGHLIGHT BACKGROUND COLOR


PgColor t Scalar Pt DEFAULT COLOR

The background color for highlighting. See PgColor t in the PhotonLibrary Reference.

If you set this resource to Pt DEFAULT COLOR, the widget uses thedefault background color.

Pt ARG TEXT HIGHLIGHT TEXT COLOR


PgColor t Scalar Pt DEFAULT COLOR

The text color for highlighting. See PgColor t in the PhotonLibrary Reference.

If you set this resource to Pt DEFAULT COLOR, the widget uses thedefault text color.

Pt ARG TEXT SUBSTRING


See below Complex See below

You can use this resource to get or set a substring of the widget’s text.It’s a complex resource, so it needs special handling:

� When setting, set the value argument to PtSetArg() to the addressof an instance of a PtTextControl t structure that defines



which characters are to be deleted and which are to be inserted. Setthe members as follows:

- start pos — the beginning of the range to delete, or -1 if youdon’t want delete any text.

- end pos — the end of the range to delete, or -1 if you don’twant delete any text.

- cur insert — the position at which to insert the new text.

- length — the number of multibyte characters to add.

- text — a pointer to the text to add.

Instead of setting this resource, you can call PtTextModifyText().

� When getting, set the value to the address of a pointer to aPtTextControl t structure. Set the start pos and end pos to thebeginning and end of the substring you want. When you get theresource, the length member is the number of multibyte charactersin the substring, and text points to the range in the widget’s internalmemory.

You don’t use the len argument to PtSetArg() when setting or gettingthis resource.

Pt CB MODIFY NOTIFY or Pt CB TEXT CHANGED



A list of PtCallback t structures that define the callbacks that thewidget invokes after the value of the text string changes.

It doesn’t matter which name you use for this resource.�

If you’ve set the Pt CALLBACKS ACTIVE bit in the widget’sPt ARG FLAGS resource, these callbacks are also invoked when yourapplication changes the text is changed by calling PtSetResource(),



PtSetResources(), or a convenience function such asPtTextModifyText().


reason Pt CB MODIFY NOTIFY

reason subtype

0 (not used).


cbdata A pointer to a PtTextCallback t structure thatcontains at least the following members:

int cur insert; The position of the cursor along thestring. A value of 0 indicates that thecursor is to the left of the first character,1 to the right of the first character, andso on.

char *text; The text string.

int length; The length of the text string (notincluding the NULL).

For more information, see “Text-modification callbacks,” above.


Pt CB MODIFY VERIFY





A list of PtCallback t structures that define the callbacks that thewidget invokes before the value of the text string changes. To alter theinput to the widget, you can modify the members of the callbackstructure.

If you’ve set the Pt CALLBACKS ACTIVE bit set in the widget’sPt ARG FLAGS resource, these callbacks are also invoked when yourapplication changes the text is changed by calling PtSetResource(),PtSetResources(), or a convenience function such asPtTextModifyText().


reason Pt CB MODIFY VERIFY

reason subtype

0 (not used).



unsigned int start pos;unsigned int end pos;

All characters starting at start pos upto but not including end pos are beingdeleted. If start pos and end pos areequal, no characters are being deleted.

int cur insert; The position at which text is beinginserted. A value of 0 indicates that thetext is being inserted to the left of thefirst character, 1 to the right of the firstcharacter, and so on.

int new insert; Where the cursor will be after thechanges are applied.



char *text; The text to be inserted at cur insert.

int length; The number of characters to beinserted. If length is zero, no text isbeing inserted.

int doit; Indicates whether or not thismodification will be applied to thewidget. If doit is zero, the widgetdiscards the modification. If doit isnonzero, the widget uses the contentsof the callback structure to modifyitself.

For more information, seePtTextModifyText().


Pt CB MOTION NOTIFY



A list of PtCallback t structures that define the callbacks that thewidget invokes after it repositions the cursor.

If you’ve set the Pt CALLBACKS ACTIVE bit set in the widget’sPt ARG FLAGS resource, these callbacks are also invoked when yourapplication repositions the cursor by calling PtSetResource() orPtSetResources().


reason Pt CB MOTION NOTIFY

reason subtype

0 (not used).




cbdata A pointer to a PtTextCallback t structure.

Pt CB MOTION VERIFY



A list of PtCallback t structures that define the callbacks that thewidget invokes before it repositions the cursor. You can use thiscallback resource to modify or even disallow cursor repositioning.

If you’ve set the Pt CALLBACKS ACTIVE bit set in the widget’sPt ARG FLAGS resource, these callbacks are also invoked when yourapplication repositions the cursor by calling PtSetResource() orPtSetResources().


reason Pt CB MOTION VERIFY

reason subtype

0 (not used).



int cur insert; The current position of the cursor. Avalue of 0 indicates that the cursor is tothe left of the first character, 1 to theright of the first character, and so on.



int start pos;int end pos;int new insert; All these indicate the destination of the

cursor. A value of 0 indicates that thecursor will be to the left of the firstcharacter, 1 to the right of the firstcharacter, and so on.

char *text; The string beginning at cur insert.

int length; The number of characters from theselected character to the end of thesegment.

int doit; Indicates whether or not thismodification will be applied to thewidget. If doit is zero, the cursorremains at cur insert. If doit isnonzero, the cursor will berepositioned at new insert.




Pt ARG ACCEL KEY PtLabel Not used by this class.





continued. . .
















Pt ARG CURSOR TYPE PtWidget Ph CURSOR INSERT




Pt ARG DIM PtWidget

Pt ARG EFLAGS PtWidget |= Pt CONSUME EVENTS


Pt ARG FILL COLOR PtBasic Pg GRAY


Pt ARG FLAGS PtWidget |=Pt SET|Pt HIGHLIGHTED|Pt GETS FOCUS

continued. . .











Pt ARG LABEL IMAGE PtLabel Not used by this class.

Pt ARG LABEL TYPE PtLabel Not used by this class.



Pt ARG LINE SPACING PtLabel Not used by this class.











Pt ARG POS PtWidget

continued. . .




Pt ARG RESIZE FLAGS PtWidget Pt RESIZE Y AS REQUIRED|Pt RESIZE Y INITIAL








Pt ARG UNDERLINE TYPE PtLabel Not used by this class.

Pt ARG UNDERLINE1 PtLabel Not used by this class.

Pt ARG UNDERLINE2 PtLabel Not used by this class.


Pt ARG VERTICAL ALIGNMENT PtLabel Pt CENTER



Pt CB ARM PtBasic




Pt CB DND PtWidget


Pt CB GOT FOCUS PtBasic See below.


continued. . .





Pt CB LOST FOCUS PtBasic See below.

Pt CB MENU PtBasic


Pt CB RAW PtWidget




Pt CB ACTIVATE

Pt CB ACTIVATE is inherited from PtBasic, but its behavior isdifferent for a PtText widget. Each callback is passed aPtCallbackInfo t structure that contains at least the followingmembers:


reason subtype

Indicates why the callback was invoked:

� 0 — you clicked on the widget and it hasPt SELECTABLE set in its Pt ARG FLAGS.

� Pt EDIT ACTIVATE — you pressed Enter in the textfield.

� Pt CHANGE ACTIVATE — you modified the text, gavefocus to another widget, and Pt CHANGE ACTIVATE isset in the widget’s Pt ARG TEXT FLAGS.




cbdata If reason subtype is 0, the callback data is as describedfor the Pt CB ACTIVATE resource for PtBasic.

If reason subtype is Pt EDIT ACTIVATE orPt CHANGE ACTIVATE, cbdata points to aPtTextCallback t structure that contains at least thefollowing members:

� int cur insert — the position of the cursor along thestring at the time the user pressed Enter. A value of 0indicates that the cursor is to the left of the firstcharacter, 1 to the right of the first character, and so on.

� char *text — the text string.

� int length — the length of the text string (notincluding the \0).


Pt CB GOT FOCUS, Pt CB LOST FOCUS

Pt CB GOT FOCUS and Pt CB LOST FOCUS are inherited fromPtBasic, but the callback data is different for a PtText widget.Each callback is passed a PtCallbackInfo t structure thatcontains at least the following members:

reason Pt CB GOT FOCUS or Pt CB LOST FOCUS

reason subtype

0 (not used).



� int cur insert — the position of the cursor along thestring at the time the user pressed Enter. A value of 0indicates that the cursor is to the left of the firstcharacter, 1 to the right of the first character, and so on.



� char *text — the text string.

� int length — the length of the text string (notincluding the \0).

The Pt CB GOT FOCUS callbacks should return Pt CONTINUE.

The Pt CB LOST FOCUS callbacks should return:


Or:


Convenience functions:The PtText widget defines the following convenience functions anddata structures that make it easier to use the widget once it’s beencreated:

PtTextCallback t, PtTextControl t,PtTextControlInfo t

Information passed to PtText callbacks


Get the selected range from a PtText widget.

PtTextModifyText()

Modify the contents of a PtText widget.


Set the selected range for a PtText widget.


2004, QNX Software Systems Ltd. PtTextCallback t,PtTextControl t, PtTextControlInfo t

Information passed to PtText callbacks

Synopsis:typedef struct Pt text callback {

int start pos;int end pos;int cur insert;int new insert;int length;short reserved;char *text;int doit;

} PtTextCallback t;typedef PtTextCallback t PtTextControl t;typedef PtTextControl t PtTextControlInfo t;

Description:PtTextCallback t, PtTextControl t, andPtTextControlInfo t are different names for the same structure.They’re used in callbacks for PtText widgets as well as to specifyactions or request data. The members of these structures are:

start pos The start position of the affected range of text.

end pos The end position of the affected range of text.

cur insert The character position where the cursor was located atthe time of the change.

new insert The character position where the cursor will be locatedafter the change.

length The number of multibyte characters in the text stringthat’s about to be added to the widget.

text A pointer to length characters to be added to thewidget.

doit Indicates whether or not the change should be made tothe widget’s text. In a Pt CB MODIFY VERIFY


PtTextCallback t, PtTextControl t,PtTextControlInfo t 2004, QNX Software Systems Ltd.

callback, you can prevent the text from being added tothe widget by setting doit or length to zero.


See also:PtMultiTextCallback t


2004, QNX Software Systems Ltd. PtTextGetSelection()Get the selected range from a PtText widget

Synopsis:int PtTextGetSelection( PtWidget t *widget,

int *start,int *end );

Description:This function gets the currently selected range from a PtText widget.It returns the number of characters currently selected and sets theprovided integers to the actual range. All characters from start up tobut not including end are currently selected.

Both start and end are 0-based. So, for example, if start returns as 0,it indicates the first character in the widget’s text buffer.

Returns:The number of characters currently selected, or -1 if the specifiedwidget isn’t a PtText widget.


Safety


Signal handler No

Thread No

See also:PtText, PtTextSetSelection()


PtTextModifyText() 2004, QNX Software Systems Ltd.

Modify the contents of a PtText widget

Synopsis:int PtTextModifyText( PtWidget t *widget,

int start,int end,int insert pos,char const *text,int length );

Description:This function modifies the contents of a PtText widget.

If start doesn’t equal end, then:

� All characters from start up to, but not including, end are deleted.

� The widget’s current insert position is set to the lesser of start andend.

� The insert pos argument is ignored.

If start does equal end, then:

� No text is deleted.

� The widget’s current insert position is set to insert pos; ifinsert pos equals -1, the current insert position is set to the end ofthe widget’s text buffer.

Both start and end are 0-based. So, for example, if start is 0, itindicates the first character in the widget’s text buffer.

Once the current insert position is set, the function inserts lengthcharacters from text. It does this regardless of the widget’s insertmode. If length is zero, no text is inserted.

This function causes a nondestructive deselect before attempting thechanges. If the widget has the Pt CALLBACKS ACTIVE bit set in itsPt ARG FLAGS resource, it then invokes itsPt CB MODIFY VERIFY callbacks, if any. These callbacks might doone of the following:


2004, QNX Software Systems Ltd. PtTextModifyText()

� Cause the changes to be discarded.

Or:

� Modify the text to be inserted and/or deleted before this functionapplies the changes.

If this call results in a change to the widget’s text (andPt CALLBACKS ACTIVE is set), the widget invokes itsPt CB MODIFY NOTIFY or Pt CB TEXT CHANGED callbacks, ifany.

Returns:1 The widget’s text was changed.

0 No change occurred.

-1 The widget is NULL or isn’t a PtText widget.


Safety


Signal handler No

Thread No


PtTextSetSelection() 2004, QNX Software Systems Ltd.

Set the selected range for a PtText widget

Synopsis:int PtTextSetSelection( PtWidget t *widget,

int *start,int *end );

Description:This function sets the selected range for a PtText. When thefunction completes successfully, start and end contain the rangeactually selected (start < end). These values may differ from theoriginal values you specified if:

� The start value you specified was greater than end.

Or:

� The range you specified exceeded the bounds of the widget’s text.

Both start and end are 0-based. So, for example, if start is 0, itindicates the first character in the widget’s text buffer.

This function causes a nondestructive deselect of the currentlyselected range, if there is one.

Here’s how a selected range behaves:

� If you move the text cursor (via arrow keys or a mouse click), therange is deselected nondestructively.

� If you perform an action that would modify the widget’s text inany way, the range is deleted and replaced by your input. If thatinput is Del or a delete backspace (DBS on many keyboards), therange is simply deleted.

Returns:The number of characters successfully selected (which may be 0 if*start equals *end or if *start and *end are both greater than thenumber of characters in the widget), or -1 if the specified widget isn’ta PtText widget.


2004, QNX Software Systems Ltd. PtTextSetSelection()


Safety


Signal handler No

Thread No

See also:PtText, PtTextGetSelection()


PtTimer 2004, QNX Software Systems Ltd.

A widget that invokes a callback after a given length of time

Class hierarchy:PtWidget → PtTimer

PhAB icon:

Public header:<photon/PtTimer.h>

Description:A PtTimer widget invokes a callback after an initial and repeatedtime period, given in milliseconds. This widget is intended to providea non-accurate, resourceless time base for your application. To disablethe timer, set Pt ARG TIMER INITIAL to 0 or unrealize the widget.

When you create a PtTimer widget in PhAB, it appears as a blackbox. The box doesn’t appear when you run the application; it’s just aplaceholder.

PtTimer is easy to use, but doesn’t give accurate timer events. Inparticular, it doesn’t guarantee a constant repeat rate; since therepetition is handled by rearming the timer for each event, any delaysin handling the events accumulate. Kernel timers guarantee anaccurate repeat rate even if your application can’t keep up with them.For more information, see “Timers” in the Working with Codechapter of the Photon Programmer’s Guide.

�

New resources:


2004, QNX Software Systems Ltd. PtTimer


Pt ARG TIMER INITIAL unsigned long Scalar 0

Pt ARG TIMER REPEAT unsigned long Scalar 0

Pt CB TIMER ACTIVATE PtCallback t * Link NULL

Pt ARG TIMER INITIAL



The time, in milliseconds, before the first timer callback is activated.

Pt ARG TIMER REPEAT



The time, in milliseconds, for the repeat rate of the timer once theinitial time period has expired.

Pt CB TIMER ACTIVATE



A list of PtCallback t structures that define the callbacks that thewidget invokes when the timer has expired.


reason Pt CB TIMER ACTIVATE


PtTimer 2004, QNX Software Systems Ltd.

reason subtype

One of:

� Pt TIMER INITIAL

� Pt TIMER REPEAT


cbdata NULL.






Pt ARG AREA PtWidget Not used by this class.

Pt ARG BITMAP CURSOR PtWidget Not used by this class.

Pt ARG BEVEL WIDTH PtWidget Not used by this class.

Pt ARG CURSOR COLOR PtWidget Not used by this class.

Pt ARG CURSOR TYPE PtWidget Not used by this class.


Pt ARG DIM PtWidget Not used by this class.

Pt ARG EFLAGS PtWidget Not used by this class.

Pt ARG EXTENT PtWidget Not used by this class.

continued. . .


2004, QNX Software Systems Ltd. PtTimer



Pt ARG HEIGHT PtWidget Not used by this class.

Pt ARG HELP TOPIC PtWidget Not used by this class.

Pt ARG MAXIMUM DIM PtWidget Not used by this class.

Pt ARG MINIMUM DIM PtWidget Not used by this class.


Pt ARG POS PtWidget Not used by this class.

Pt ARG RESIZE FLAGS PtWidget Not used by this class.


Pt ARG WIDTH PtWidget Not used by this class.

Pt CB BLOCKED PtWidget Not used by this class.


Pt CB DND PtWidget

Pt CB FILTER PtWidget Not used by this class.

Pt CB HOTKEY PtWidget Not used by this class.


Pt CB OUTBOUND PtWidget Not used by this class.

Pt CB RAW PtWidget Not used by this class.




PtToggleButton 2004, QNX Software Systems Ltd.

A toggle switch that’s either off or on

Class hierarchy:PtWidget → PtBasic → PtLabel → PtButton →PtToggleButton

PhAB icon:

Public header:<photon/PtToggleButton.h>

Description:A PtToggleButton widget is like a toggle switch, although itbehaves like a button. It has on and off states, and pressing the buttoninverts the current state of the button.

Various button styles supported by PtToggleButton.

Creating toggle buttons

Toggle buttons inherit resources from PtLabel and PtButton;specify the label for toggle buttons the way you do for these classes.

A toggle button is displayed as a button with a label beside it. Thebutton is either set or unset, and you can control its appearance withthe Pt ARG INDICATOR COLOR and Pt ARG INDICATOR TYPEresources.


2004, QNX Software Systems Ltd. PtToggleButton

You can also set Pt ARG ARM COLOR, which specifies the fill colorfor the button’s interior when the button is set. This resource is usedonly if the value of Pt ARG ARM FILL is Pt TRUE. These resourcesare inherited from PtButton.

To determine whether or not the button is set, check the:

� Pt SET bit in the Pt ARG FLAGS resource — see PtWidget

� Callback data passed to the Pt CB ACTIVATE callbacks — seePtBasic.

Grouping toggle buttons

A group can control how several toggle buttons behave together. Ifyou place the toggle buttons in a group and make them mutuallyexclusive, they behave like the channel-selector buttons on a carradio: only one of the buttons can be set at any given time, and settingany button automatically unsets the button that’s currently set.

To make a group of toggle buttons mutually exclusive, set thePt GROUP EXCLUSIVE bit in the group’s Pt ARG GROUP FLAGSresource. For example:

PtSetArg (&argt[n], Pt ARG GROUP FLAGS, Pt TRUE,Pt GROUP EXCLUSIVE );

n++;PtSetArg (&argt[n], Pt ARG GROUP ORIENTATION,

Pt GROUP VERTICAL, 0 ) ;n++;group = PtCreateWidget (PtGroup, parent, n, argt );

PtSetArg (&argt[0], Pt ARG TEXT STRING,"Button 1", 0 ) ;

button1 = PtCreateWidget (PtToggleButton, group,1, argt ) ;







PtRealizeWidget ( group ) ;

You can use the same callback for all the buttons, but how do youdetermine which one is selected? There are several ways:

� Specify a Pt CB ACTIVATE callback (see PtBasic) for thegroup. The PtGroup adds its callback to each of its children;when the callback is invoked, the widget argument is a pointer tothe selected button, not the group. You can compare the pointer topreviously saved pointers to the buttons.

Or:

� Store a unique value in each button’s Pt ARG USER DATAresource (see PtWidget). In the callback, get this resource anduse its value to determine which button was pressed.

Or:

� If you create the buttons in code (instead of in PhAB), you can passa unique value in the client data argument to the callback routine.

New resources:


Pt ARG INDICATOR COLOR PgColor t Scalar Pg WHITE

Pt ARG INDICATOR TYPE unsigned char Scalar Pt TOGGLE CHECK

Pt ARG INDICATOR COLOR





The fill color for the toggle button’s indicator. See PgColor t in thePhoton Library Reference.

Pt ARG INDICATOR TYPE


unsigned char Scalar Pt TOGGLE CHECK

Determines how the indicator is drawn. Possible values:

� Pt TOGGLE RADIO

� Pt TOGGLE CHECK

� Pt TOGGLE OUTLINE

Here’s how these types look, both set and unset:





continued. . .








Pt ARG ARM FILL PtButton


















Pt ARG DIM PtWidget

continued. . .








Pt ARG FLAGS PtWidget |=Pt SELECTABLE|Pt TOGGLE








Pt ARG LABEL IMAGE PtLabel Not used by this class.

Pt ARG LABEL TYPE PtLabel Not used by this class.










continued. . .








Pt ARG POS PtWidget
















Pt CB ARM PtBasic



continued. . .





Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget





PtToolbar 2004, QNX Software Systems Ltd.

Superclass for toolbar widgets

Class hierarchy:PtWidget → PtBasic → PtContainer → PtToolbar


� PtMenuBar

PhAB icon:

Public header:<photon/PtToolbar.h>

Description:A PtToolbar is a container that organizes its children as a horizontal(by default) or vertical toolbar.

A PtToolbar as used in PhAB.

The children of a PtToolbar can be any type of widget. They’recenter-aligned within the toolbar, and can optionally be separatedfrom each other with etched lines:

New resources:


2004, QNX Software Systems Ltd. PtToolbar



Pt ARG TOOLBAR FLAGS uint16 t Flags Pt TOOLBAR DRAGGABLE |

Pt TOOLBAR END SEPARATOR |

Pt TOOLBAR FOLLOW FOCUS

Pt ARG TOOLBAR LAYOUT FLAGS uint8 t Flags 0

Pt ARG TOOLBAR SPACING uint8 t Scalar 2

Pt ARG ORIENTATION



Indicates whether the toolbar is to be drawn vertically or horizontally.Possible values:

� Pt HORIZONTAL

� Pt VERTICAL

Pt ARG TOOLBAR FLAGS


uint16 t Flags Pt TOOLBAR DRAGGABLE |Pt TOOLBAR END SEPARATOR |Pt TOOLBAR FOLLOW FOCUS

Flags that control the behavior of the widget. Any combination of:

Pt TOOLBAR DRAGGABLE

Enable dragging operations.

Pt TOOLBAR REVERSE LAST ITEM

Right- or bottom-align the frontmost (i.e. last) item.



Pt TOOLBAR FOLLOW FOCUS

Pan the toolbar as focus changes within it.

Pt TOOLBAR LOCK ORIENTATION

Don’t let the orientation change.

Pt TOOLBAR ITEM SEPARATORS

Render separators between all items.

Pt TOOLBAR END SEPARATOR

Render a separator after the last item.

Pt ARG TOOLBAR LAYOUT FLAGS


uint8 t Flags 0

Flags that PtToolbarGroup uses to record the toolbar’s layout:

Pt TOOLBAR FROM LINE START

Start the toolbar on a new line.

Pt TOOLBAR TO LINE END

Run the toolbar to the end of the line.

Pt ARG TOOLBAR SPACING


uint8 t Scalar 2

The spacing, in pixels, between items in the toolbar.









Pt ARG BASIC FLAGS PtBasic (& ˜Pt FLAT FILL) |Pt REVERSE GRADIENT




Pt ARG BEVEL CONTRAST PtBasic 65


Pt ARG CONTAINER FLAGS PtContainer |= Pt AUTO EXTENT

Pt ARG CONTRAST PtBasic 10







Pt ARG DIM PtWidget

continued. . .





















Pt ARG POS PtWidget






continued. . .







Pt CB ARM PtBasic






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






PtToolbarGroup 2004, QNX Software Systems Ltd.

A group of toolbars

Class hierarchy:PtWidget → PtBasic → PtContainer → PtToolbarGroup

PhAB icon:

Public header:<photon/PtToolbarGroup.h>

Description:A PtToolbarGroup is a container that manages its children, whichmust be of the PtToolbar class or one of its subclasses.

A PtToolbarGroup.

You can drag the toolbars in the group to expand or shrink them.

New resources:



Pt ARG TG FLAGS uint16 t Flags 0

Pt ARG ORIENTATION




2004, QNX Software Systems Ltd. PtToolbarGroup

Indicates whether the toolbar group is to be drawn vertically orhorizontally. Possible values:

� Pt HORIZONTAL

� Pt VERTICAL

This resource overrides the orientation specified for the toolbargroup’s children.

�

Pt ARG TG FLAGS


uint16 t Flags 0

Flags that control the behavior of the widget:

Pt TG COLLAPSIBLE

Toolbars are collapsible. If this bit is set, you can click on atoolbar’s drag handle to minimize the toolbar to a thin bar.






continued. . .





Pt ARG BASIC FLAGS PtBasic &= ˜Pt ALL BEVELS,|= Pt ALL OUTLINES






Pt ARG CONTAINER FLAGS PtContainer |= Pt AUTO EXTENT








Pt ARG DIM PtWidget








continued. . .


2004, QNX Software Systems Ltd. PtToolbarGroup












Pt ARG POS PtWidget









Pt CB ARM PtBasic




continued. . .






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






2004, QNX Software Systems Ltd. PtTreeA tree of items that collapse and expand as requested

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

PhAB icon:

Public header:<photon/PtTree.h>

Description:The PtTree widget displays a tree of items that collapse or expandaccording to your selections. PtTree assumes that each tree itemcontains two images and a string.

A PtTree widget, as used in the Helpviewer.


PtTree 2004, QNX Software Systems Ltd.

Allocating items and building a tree

The items in a PtTree are stored in structures of typePtTreeItem t, which you should allocate by callingPtTreeAllocItem() or PtTreeCreateItem(). The PtTree widget freesall its items automatically when it’s destroyed.

The item structure contains a “user data” pointer that you can use tostore any data you want to associate with the item; the widget ignoresthis pointer. There are some functions that free items, but none ofthem attempts to free the user data.

�

PtTreeAllocItem() takes as arguments:

� a pointer to the tree widget — this must be the same widget thatthe item will be added to

� the text to display for the item

� indexes of images to use when the item is “set” and “unset” —we’ll look at these later.

This function uses the font and image list stored in the tree widget todetermine the item’s dimensions. This means that between creating anitem and adding it to the widget, you mustn’t change the widget’s fontor images.

PtTreeCreateItem() is similar to PtTreeAllocItem(), except instead ofthe set and unset image indexes, it takes a pointer to aPtTreeItemAttributes t structure which defines the set andunset images, as well as font and color attributes for the item’s text.

Use PtTreeAddFirst() and PtTreeAddAfter() to build a tree. Forexample, suppose you wanted to build the following tree:


2004, QNX Software Systems Ltd. PtTree

A PtTree without images.

Assuming your tree widget is referenced by tree wgt, use thefollowing code:

PtTreeItem t *item, *brother;char *text;

/* Add "Item 1" as first root item */

text = "Item 1";item = PtTreeAllocItem(tree wgt, text, -1, -1);PtTreeAddFirst(tree wgt, item, NULL);brother = item;

/* Add "Item 2" as root item after "Item 1" */

text = "Item 2";item = PtTreeAllocItem(tree wgt, text, -1, -1);PtTreeAddAfter(tree wgt, item, brother);brother = item;

/* Add "Item 2a" as first child of "Item 2" */

text = "Item 2a";item = PtTreeAllocItem(tree wgt, text, -1, -1);PtTreeAddFirst(tree wgt, item, brother);

/* Add "Item 3" as root item after "Item 2" */

text = "Item 3";item = PtTreeAllocItem(tree wgt, text, -1, -1);PtTreeAddAfter(tree wgt, item, brother);



Using images in tree items

The array of all available images is stored in the widget’sPt ARG TREE IMAGES resource; the items contain indexes into thisarray.

Before allocating the tree items, set up the array of images;PtTreeAddImages() provides a convenient way to do this.

When you call PtTreeAllocItem() to allocate the tree items, specifythe index of the icons to use when the item is set or unset. To specifythe meaning of “set” and “unset”, use the Pt ARG TREE IMGMASKresource.

Alternatively, you can use PtTreeCreateItem() or PtTreeChangeItem()to assign images not in the Pt ARG TREE IMGMASK resource to atree item.

Here’s some code that sets up a tree with images:

PtTreeItem t *item, *brother;char *text;int closed dir, closed file, open dir, open file;

/* Extract the images from a widget database and add themto the tree’s array of images: */

closed dir = PtTreeAddImages (tree wgt,ApGetImageRes (database, "dir closed"), 1);

closed file = PtTreeAddImages (tree wgt,ApGetImageRes (database, "file closed"), 1);

open dir = PtTreeAddImages (tree wgt,ApGetImageRes (database, "dir open"), 1);

open file = PtTreeAddImages (tree wgt,ApGetImageRes (database, "file open"), 1);

/* Add "Directory 1" as first root item */

text = "Directory 1";item = PtTreeAllocItem(tree wgt, text, open dir, closed dir);PtTreeAddFirst(tree wgt, item, NULL);brother = item;

/* Add "Directory 2" as root item after "Directory 1" */

text = "Directory 2";item = PtTreeAllocItem(tree wgt, text, open dir, closed dir);PtTreeAddAfter(tree wgt, item, brother);



brother = item;

/* Add "My File" as first child of "Directory 2" */

text = "My File";item = PtTreeAllocItem(tree wgt, text, open file, closed file);PtTreeAddFirst(tree wgt, item, brother);

/* Add "Directory 3" as root item after "Directory 2" */

text = "Directory 3";item = PtTreeAllocItem(tree wgt, text, open dir, closed dir);PtTreeAddAfter(tree wgt, item, brother);

The tree’s Pt ARG TREE IMGMASK is set toPt TREE ITEM EXPANDED so that the “open” icon is displayed whenthe tree item is expanded. The tree looks like this:

A PtTree with images.

Displaying text in columns

To display items in columns, you can:

� Create a PtDivider widget as a child of the PtTree. Put it at thetop of the tree, and create (for example) PtButton widgets aschildren of the divider, one for each column. The width of eachbutton is the width of the column.

Or



� Use the Pt ARG LIST COLUMN POS resource inherited fromPtGenList.

With both methods, use the Tab character in the item strings as acolumn separator.

Even if you use columns, each line in the tree remains a single item.When you select any part of the line, the entire line is selected —having columns doesn’t make the tree into a spreadsheet.

�

Displaying images in columns

You can make your PtTree display clickable images instead of textin selected columns. Here’s how:

Set the Pt LIST COLUMN NO STRING flag in the PtGenListcolumn attributes (Pt ARG LIST COLUMN ATTR) for each columnthat you want to display images. This prevents text from being drawnon top of images. For example:

static const PtListColumnAttributes t latrs[] = {{ Pt LIST COLUMN LEFT },{ Pt LIST COLUMN CENTER | Pt LIST COLUMN NO STRING }};

PtSetResource( ABW tree, Pt ARG LIST COLUMN ATTR, latrs,sizeof(latrs) / sizeof(latrs[0]) );

A tab character in an item’s string skips over a column flagged asPt LIST COLUMN NO STRING. For example, if the second columnhas the flag set, you need only one tab character between the stringsfor the first and the third column.

�

Set up an array of image pointers for each column and an array of treecolumn attributes (Pt ARG TREE COLUMN ATTR):

static const PhImage t *images[3] = { &image1, &image2,&image3 };

static const PtTreeColumnAttributes t tatrs[] = {



/* The first column has no images: */{ NULL, 0, Pt TREE COLUMN NOCB },{ images, sizeof(images) / sizeof(images[0]),

Pt TREE COLUMN NOSELECT,Pt LIST ITEM FLAG USER1 | Pt LIST ITEM FLAG USER2}

};

PtSetResource( ABW tree, Pt ARG LIST COLUMN ATTR, tatrs,sizeof(tatrs) / sizeof(tatrs[0]) );

Optionally, write an image-selector function and attach it to thePt ARG TREE COLUMN IMGFUN resource.

This function takes as arguments a tree item, a column index, and acolumn attributes structure, and returns an index into the column’simage array (or -1 for no image). You need this function only if:

� You need more than two states per column (i.e. either two imagesto choose from or one image that can be either present or absent)

Or:

� You want to use something other than an item flag to distinguishbetween these two states.

For example:

static int image selector(PtWidget t *widget,PtTreeItem t *item,PtTreeColumnAttributes t const *cattr,unsigned cindex )

{unsigned const flags = item->gen.list.flags;int result = -1;

/* We don’t really need to check if cindex is onebecause we only have one column that displays images.But for the sake of example... */

if ( cindex == 1 ) {/* This column has three images and four possible

states (no image is the fourth state).The function should return -1 for no image and0...3 to pick an image. */



if ( flags & Pt LIST ITEM FLAG USER2 )result += 2;

if ( flags & Pt LIST ITEM FLAG USER1 )result += 1;

}return result;

}...PtSetResource( ABW tree, Pt ARG TREE COLUMN IMGFUN,

image selector, 0 );

Optionally, attach a Pt CB TREE COLUMN SEL callback that bothnotifies your application when you click on a column, and lets youcontrol how the item’s state changes.

For instance, the following callback makes your items cycle throughthe four possible states:

static int column cb( PtWidget t *widget, void *data,PtCallbackInfo t *cbinfo ) {

PtTreeCallback t *tcb = cbinfo->cbdata;if ( tcb->column == 1 ) {

if ( tcb->new flags & Pt LIST ITEM FLAG USER1 )tcb->new flags ˆ= Pt LIST ITEM FLAG USER2;

}return Pt CONTINUE;}

New resources:


Pt ARG TREE BALLOON PtTreeBalloonF t * Pointer See below

Pt ARG TREE COLUMN ATTR See below Array NULL

Pt ARG TREE COLUMN IMGFUN See below Pointer See below

continued. . .




Pt ARG TREE IMAGES PhImage t *, short Array NULL

Pt ARG TREE IMGMASK unsigned Scalar Pt LIST ITEM SELECTED

Pt CB TREE COLUMN SEL PtCallback t * Link NULL

Pt CB TREE SELECTION PtCallback t * Link NULL

Pt CB TREE STATE PtCallback t * Link NULL

Pt ARG TREE BALLOON


PtTreeBalloonF t * Pointer See below

A function that inflates a balloon for the item the pointer is on.PtTreeBalloonF t is a function type:

typedef PtWidget t *PtTreeBalloonF t( PtWidget t *widget,PtWidget t *parent,PhArea t *area,PtListColumn t *column,PtTreeItem t *item,int coln,const char *font );

The parameters are as follows:

widget A pointer to the PtTree widget.

parent A pointer to its parent window.

area A pointer to a PhArea t structure (see the PhotonLibrary Reference) that covers the item. The area->posmember is relative to the parent window.

column A pointer to a PtListColumn t structure that indicatesthe position of the column the pointer is on. For



information about this structure, see thePt ARG LIST COLUMN POS resource inherited fromPtGenList.

item A pointer to the item the pointer is on.

coln The index of the column the pointer is on.

font The value of the widget’s Pt ARG LIST FONT resource.

The default function does this:

returnPtGenListCreateTextBalloon(widget, parent,PtGenListSetColumnBalloon ( area, column ),item->string, coln, font);

Pt ARG TREE COLUMN ATTR


PtTreeColumnAttributes t, short Array NULL

Attributes for the tree’s columns. This resource is an array ofPtTreeColumnAttributes t structures. The structure contains atleast the following members (in the following order — staticinitialization is OK):

PhImage t const **images

An array of image pointers. When you set the resource, thisarray is copied, but the PhImage t structures pointed to by itaren’t.

unsigned short nimages

The number of entries in the images array.



unsigned short cflags

Column flags; any combination of:

� Pt TREE COLUMN NOSELECT — when set, clicking on thiscolumn doesn’t cause selection.

� Pt TREE COLUMN NOCURRENT — when set, clicking onthis column doesn’t even set the current item (see “Currentitem” in the description of PtGenList).

� Pt TREE COLUMN NOCB — when set, clicking on thiscolumn doesn’t change the item’s flags or invoke thePt CB TREE COLUMN SEL callback.

unsigned iflags

Item flags that are used to select this column’s image. SeePt ARG TREE COLUMN IMGFUN andPt CB TREE COLUMN SEL

Pt ARG TREE COLUMN IMGFUN


PtTreeColumnImageF t * Pointer See below

This function is called by the draw function for each item and eachcolumn that has the Pt LIST COLUMN NO STRING flag in thePt ARG LIST COLUMN ATTR resource (see PtGenList) and anonempty image array defined in the Pt ARG TREE COLUMN ATTRresource.

The function must be of the following type:

typedef int PtTreeColumnImageF t(PtWidget t *widget,PtTreeItem t *item,PtTreeColumnAttributes t const *cattr,unsigned cindex );

The arguments are:

widget A pointer to the PtTree widget.



item A pointer to the item being drawn.

cattr A pointer to a PtTreeColumnAttributes t structurethat describes the column attributes. For information aboutthis structure, see Pt ARG TREE COLUMN ATTR.

cindex The column index.

The function should return an index into the image array, or -1 if noimage should be drawn. If you return a value that’s equal to or greaterthan the column’s nimages, no image is drawn.

The default function returns 0 or 1, depending on whether thecolumn’s iflags ANDed with the item’s flags gives a nonzero result.

The function attached to this resource isn’t allowed to modifyanything and should be quick, since it’s called a lot.

�

For an example, see “Displaying images in columns,” above.

Pt ARG TREE IMAGES


PhImage t *, short Array NULL

A list of images that can be displayed with tree items. For moreinformation about the image structure, see PhImage t in the PhotonLibrary Reference.



Set the flags member of the PhImage t structures to:


before providing the images to the widget. If you do this, the memoryused for the images is released when the widget is destroyed orPt ARG TREE IMAGES is set.

�

For a convenient way to add images, see PtTreeAddImages(); for anexample, see “Using images in tree items,” above.

Pt ARG TREE IMGMASK


unsigned Scalar Pt LIST ITEM SELECTED

Defines the mask for selecting an item’s image.

When you create an item by calling PtTreeAllocItem(), you specifythe images to be used when the item is set or unset. An item isconsidered set if its flags masked with the tree’sPt ARG TREE IMGMASK resource give a nonzero value. The flagsinclude:


The item is selected.

Pt LIST ITEM CURRENT

The item is the current item (see “Current item” in thedescription of PtGenList).

Pt TREE ITEM EXPANDABLE

The item can be expanded.

Pt TREE ITEM EXPANDED

The branches of this item are currently displayed.



Pt CB TREE COLUMN SEL



A list of PtCallback t structures that define the callbacks that areinvoked when you click on a column that has an entry in thePt ARG TREE COLUMN ATTR array but thePt TREE COLUMN NOCB flag in that entry isn’t set.


reason Pt CB TREE COLUMN SEL

reason subtype

0 (not used).


cbdata A pointer to a PtTreeCallback t structure thatincludes:

unsigned sel mode;

The current selection mode(Pt ARG SELECTION MODE).

PtTreeItem t *item;

If the selection mode isn’t set toPt RANGE MODE, item is a pointer tothe item you clicked on. If theselection mode is set toPt RANGE MODE, item is a pointer tothe first of the selected items.

unsigned nitems;

This contains the number of selecteditems, excluding collapsed subtrees.



int click count; The number of mouse clicks (0 forkeyboard events or if event is NULL).

unsigned old iflags

The current value of the item’s flags.

unsigned new iflags

The value of the item’s flags, to be setafter the callback functions return.

Only the “user flags”(Pt LIST ITEM FLAG USER[1234]defined in PtGenList.h) andPt LIST ITEM DAMAGED are lookedat. The initial value of new flags iscalculated as follows:

� Set new iflags to old iflags;

� If the column attributes entry hasany of the user flags set in iflags,flip those flags in new iflags and setPt LIST ITEM DAMAGED.

After the callback functions return, theuser flags are copied back fromnew iflags and if thePt LIST ITEM DAMAGED flag is set innew iflags, the item is damaged. Makesure that you set thePt LIST ITEM DAMAGED flag if youmodify new iflags in a way thatrequires the item to be redrawn,particularly if you have your ownfunction attached to thePt ARG TREE COLUMN IMGFUNresource.

int column The column number, or -1 if none.

PtTreeColumnAttributes t const *cattrA pointer to the attributes of thatcolumn, if any. For information about



this structure, seePt ARG TREE COLUMN ATTR.


For an example, see “Displaying images in columns,” above.

Pt CB TREE SELECTION



A list of PtCallback t structures that define the callbacks invokedwhen you select an item from the tree.


reason Pt CB TREE SELECTION

reason subtype

This value depends on the selection mode. One of:

� Pt LIST SELECTION FINAL

� Pt LIST SELECTION BROWSE

� Pt LIST SELECTION CANCEL


cbdata A pointer to a PtTreeCallback t structure thatcontains at least the following members:

unsigned sel mode;




PtTreeItem t *item;

If the selection mode isn’t set toPt RANGE MODE, item is a pointer tothe item you clicked on. If theselection mode is set toPt RANGE MODE, item is a pointer tothe first of the selected items.

unsigned nitems;

This contains the number of selecteditems, excluding collapsed subtrees.

int click count; The number of mouse clicks (0 forkeyboard events).


If you multi-click on a tree, its Pt CB TREE SELECTION callbacksare invoked once for each click. The callback data includes the clickcount (1 for the first click, 2 for the second, and so on).

If you want to process only the last of a series of clicks, use aPt CB RAW callback to look for a Ph EV BUT RELEASE event with asubtype of Ph EV RELEASE ENDCLICK. For more information, seePhEvent t in the Photon Library Reference.

The Ph EV BUT RELEASE event with a subtype ofPh EV RELEASE ENDCLICK occurs approximately half a secondafter the click, which could be annoying to the user. Most Photonapplications don’t use multiple clicks because of this.

�

Pt CB TREE STATE



A list of PtCallback t structures that define the callbacks that arecalled before an item is expanded and after an item is collapsed. Each



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

reason Pt CB TREE STATE

reason subtype

Pt TREE COLLAPSING or Pt TREE EXPANDING.


cbdata A pointer to a PtTreeCallback t structure thatcontains at least the following members:

unsigned sel mode;


PtTreeItem t *item;

A pointer to the item that’s beingcollapsed or expanded.

int expand; This field is initially set to 0. If thereason subtype is Pt TREE EXPANDING,set expand to a nonzero value to suppressexpansion.


























Pt ARG DIM PtWidget



continued. . .



























continued. . .






Pt ARG POS PtWidget











Pt ARG TREE FLAGS PtGenTree See below.








Pt CB ARM PtBasic


continued. . .















Pt CB MENU PtBasic


Pt CB RAW PtWidget






Pt ARG TREE FLAGS

In addition to the flags defined by PtGenTree, the following flags aredefined:

� Pt TREE BALLOON ON IMAGE — the balloon is permitted tocover the image and the text



� Pt TREE BALLOON ON TREE — the balloon is permitted to coverthe tree, the image, and the text

By default, neither is set. The width and location of the balloondepend on these flags:

Neither Pt_TREE_BALLOON_ON_IMAGE

Pt_TREE_BALLOON_ON_TREE

Additional Pt ARG TREE FLAGS for a PtTree widget.

To make the balloons appear, set one of the balloon bits (e.g.Pt LIST BALLOON AS REQUIRED) in the Pt ARG LIST FLAGSresource inherited from PtGenList.

�

Pt CB DND

For Pt CB DND callbacks for a PtTree, the cbinfo->cbdata is apointer to a PtTreeDndCallback t structure, containing at leastthe following members:




A pointer to the PtGenTreeItem t structure forthe target item involved in the drag-and-drop



operation. You can cast this to be a pointer to aPtTreeItem t.


unsigned long flags

Possible values:





Convenience functions:The PtTree widget defines the following structures and conveniencefunctions that make it easier to use the tree once it’s been created:

PtTreeAddAfter()


PtTreeAddFirst()

Add a root item to the widget, or add an item as thefirst child of a specified item



PtTreeAddImages()

Add images to the PtTree widget’s image list

PtTreeAllItems() Fill a buffer with pointers to all items

PtTreeAllocItem()

Allocate a new item

PtTreeClearSelection()

Clear the selection

PtTreeCollapse()

Collapse an expandable item

PtTreeChangeItem()

Change the text string and attributes of thespecified item

PtTreeCreateItem()

Allocate a new item with attributes

PtTreeExpand() Expand an expandable item

PtTreeFreeAllItems()

Unlink and free all items

PtTreeFreeItems()


PtTreeGetCurrent()

Get the current item

PtTreeGetSelIndexes()

Fill a buffer with indexes of selected items

PtTreeGoto() Set the current item

PtTreeItem t PtTree item structure



PtTreeItemAttributes t

PtTree item attributes structure, used byPtTreeCreateItem() and PtTreeChangeItem().

PtTreeItemIndex()

Calculate the index of the specified item

PtTreeModifyItem()

Change item resources

PtTreeModifyItemString()

Change the string for a PtTree item

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()


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 thespecified item


PtTreeAddAfter() 2004, QNX Software Systems Ltd.


Synopsis:int PtTreeAddAfter( PtWidget t *tree,

PtTreeItem t *item,PtTreeItem t *brother );

Description:This function inserts a list of trees linked with the brother member ofthe PtTreeItem t structure.

PtTreeAddAfter() assumes that item points to a list of trees. The treevariable points to a PtTree widget. The new items are added to thespecified tree below the specified brother:

A

B 1

2

3

1

2

3

A

B

C

item tree

brother brother

item

tree

C

The results of using PtTreeAddAfter().

You can call this function with a NULL tree argument, as long asbrother points to an item that isn’t attached to any tree widget.


2004, QNX Software Systems Ltd. PtTreeAddAfter()

Returns:0 Success.


Examples:See “Allocating items and building a tree” in the description ofPtTree.


Safety


Signal handler No

Thread No

See also:PtTree, PtTreeAddFirst(), PtTreeAllocItem(), PtTreeFreeAllItems(),PtTreeFreeItems(), PtTreeItem t


PtTreeAddFirst() 2004, QNX Software Systems Ltd.

Add a root item to a tree list

Synopsis:int PtTreeAddFirst( PtWidget t *tree,

PtTreeItem t *item,PtTreeItem t *parent );

Description:This function adds the list of PtTreeItem t structures pointed to byitem to the given PtTree widget. The list of items are linked withtheir brother fields. The item argument can be NULL.

The parent argument identifies the parent item for the added items.The new items are added in front of any existing children of theparent item:

A

B 1

2

3

1

2

A

B

item tree

parent parent

item

tree

3

The results of using PtTreeAddFirst().

If parent is NULL, the items are added at the root level of the tree,before any existing items there.

The tree argument can be NULL, provided that parent points to anitem that isn’t attached to any tree widget.


2004, QNX Software Systems Ltd. PtTreeAddFirst()

PtTreeAddFirst() automatically sets the Pt TREE ITEM EXPANDABLEflag in the parent item, whether or not the item argument is NULL.

Returns:0 Success.




Safety


Signal handler No

Thread No

See also:PtTree, PtTreeAddAfter(), PtTreeAllocItem(), PtTreeFreeAllItems(),PtTreeFreeItems(), PtTreeItem t, PtTreeRootItem()


PtTreeAddImages() 2004, QNX Software Systems Ltd.

Add images to the PtTree widget’s image list

Synopsis:int PtTreeAddImages( PtWidget t *widget,

PhImage t const *images,int n );

Description:This function adds n images to the widget’s image list. The functionreturns the index of the first of the added items, which is the same asthe number of images on the list (before the new ones were added).The widget makes its own copy of the PhImage t structures, but itdoesn’t copy the palettes or image data pointed to by members of thestructures.

Returns:The index of the first of the added items.

Examples:See “Using images in tree items” in the description of PtTree.


Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtTreeAddImages()

See also:PtTree

PhImage t in the Photon Library Reference


PtTreeAllItems() 2004, QNX Software Systems Ltd.

Fill a buffer with pointers to all items

Synopsis:PtTreeItem t **PtTreeAllItems(

PtWidget t *widget,PtTreeItem t **buffer );

Description:This function fills a buffer with pointers to all items in the widget. Ifbuffer is NULL, the function allocates a buffer using malloc(), and thebuffer is NULL-terminated. If buffer isn’t NULL, the function doesn’tadd a NULL at the end.

Items that belong to collapsed subtrees aren’t included in the buffer. Ifyou need a list of all the items, traverse the father, son, and brotherpointers in the PtGenTreeItem t structure that’s part ofPtTreeItem t.

�


Examples:PtTreeItem t *item, **buf;

buf = PtTreeAllItems( widget, NULL );for ( i=0; ( item = buf[i] ) != NULL; ++i ) {

printf( "%s\n", item->string );}

free( buf );



2004, QNX Software Systems Ltd. PtTreeAllItems()

Safety


Signal handler No

Thread No

See also:PtTree, PtTreeGetCurrent(), PtTreeGetSelIndexes(),PtTreeItem t, PtTreeSelectedItems(), PtTreeSetSelIndexes()


PtTreeAllocItem() 2004, QNX Software Systems Ltd.

Allocate a new item

Synopsis:PtTreeItem t *PtTreeAllocItem(

PtWidget t const *tree,const char *string,short set img,short unset img );

Description:This function allocates a new item. The item’s string is copied fromstring.

The set img argument is the index of the image to be displayed whenthe item is set, and unset img is the image to be displayed when itisn’t set. An item is considered set if its flags masked with thePt ARG TREE IMGMASK resource of the widget give a nonzerovalue.

The image must be already present in the widget: if you specify anindex that’s larger than the current image count, it’s changed to -1. Avalue of -1 means “no image.”

Use PtTreeAddFirst() and PtTreeAddAfter() to add the new item to atree structure.

�



Safety


continued. . .


2004, QNX Software Systems Ltd. PtTreeAllocItem()

Safety

Signal handler No

Thread No

See also:PtTree, PtTreeAddAfter(), PtTreeAddFirst(), PtTreeAddImages(),PtTreeFreeAllItems(), PtTreeFreeItems(), PtTreeItem t,PtTreeModifyItem(), PtTreeModifyItemString()


PtTreeChangeItem() 2004, QNX Software Systems Ltd.

Create a tree item with attributes

Synopsis:PtTreeItem t *PtTreeChangeItem(PtWidget t *tree,PtTreeItem t *item,const char *string,PtTreeItemAttributes t const *attr);

Arguments:tree A pointer to the PtTree widget which contains the item

you want to change.

item A pointer to the PtTreeItem t you wish to change.

string The tree item text string. Set to NULL to leave the item’stext string unchanged.

attr A pointer to the new PtTreeItemAttributes t

structure you want to set for this item. Set to NULL todisplay no images, and use the widget-defined font andcolors. The Pt TREE ITEM HAS ATTRS flag bit is still setfor the item.

Description:This function changes an existing tree item, created withPtTreeCreateItem() or PtTreeAllocItem(). The string and attrparameters will override the existing item text string and attributes.

Returns:A pointer to a PtTreeItem t

Success.

NULL Error


2004, QNX Software Systems Ltd. PtTreeChangeItem()



Safety


Signal handler No

Thread No

See also:PtTree, PtTreeAddAfter(), PtTreeAllocItem(), PtTreeCreateItem(),PtTreeFreeAllItems(), PtTreeFreeItems(), PtTreeItem t,PtTreeItemAttributes t, PtTreeRootItem()


PtTreeClearSelection() 2004, QNX Software Systems Ltd.

Clear the selection

Synopsis:void PtTreeClearSelection( PtWidget t *widget );

Description:This function clears the selection.


Safety


Signal handler No

Thread No

See also:PtTree, PtTreeGetCurrent(), PtTreeGetSelIndexes(), PtTreeGoto(),PtTreeSelect(), PtTreeSelectedItems(), PtTreeSetSelIndexes(),PtTreeUnselect(), PtTreeUnselectNonBrothers()


2004, QNX Software Systems Ltd. PtTreeCollapse()Collapse an expandable item

Synopsis:int PtTreeCollapse( PtWidget t *tree,

PtTreeItem t *item,PhEvent t *event );

Description:This function collapses the given subtree item. The tree argumentmust point to the tree that contains the item, or it can be NULL if theitem doesn’t belong to any tree.

If the item is in the tree, the tree’s Pt CB TREE STATE callback isinvoked after the item has been collapsed. The event argument to thisfunction is the event that’s passed to the callback.

Returns:The value assigned to the expand field in the callback structure, orzero if the item isn’t in a tree or there’s no Pt CB TREE STATEcallback that modifies the expand field.


Safety


Signal handler No

Thread No

See also:PtTree, PtTreeExpand(), PtTreeGetCurrent(), PtTreeGoto(),PtTreeItem t, PtTreeShow()



PtTreeCreateItem() 2004, QNX Software Systems Ltd.

Create a tree item with attributes

Synopsis:PtTreeItem t *PtTreeCreateItem(PtWidget t const *tree,const char *string,PtTreeItemAttributes t const *attr);

Arguments:tree A pointer to the PtTree widget that this item will be added

to.

string The text to display for the item.

attr A pointer to a PtTreeItemAttributes t structurewhich defines the attributes for the item. Set to NULL to setno images for the item, and to use the widget-defined fontand colors.

Description:This function creates a new tree item. The item’s string is copied fromstring.

Attributes are set with a PtTreeItemAttributes t structure,passed as attr. The item’s Pt TREE ITEM HAS ATTRS is set whetherattr is passed as a pointer or NULL.

Both PtTreeAllocItem() and PtTreeCreateItem() create a tree item.PtTreeCreateItem() lets you specify set and unset images that are notalready present in the widget’s Pt ARG TREE IMAGES array. Ingeneral, if you want to use images in this array, you should usePtTreeAllocItem().


2004, QNX Software Systems Ltd. PtTreeCreateItem()

An item created with PtTreeCreateItem(widget,string,NULL) behavesidentically to an item created withPtTreeAllocItem(widgetmstring,-1,-1), except it has thePt TREE ITEM HAS ATTRS flag set, whereas the latter does not.

�

Using PtTreeCreateItem() you can also specify text and fill colorattributes for selected and unselected items.

Use PtTreeAddFirst() and PtTreeAddAfter() to add the new item to atree structure.

�

Returns:A pointer to a PtTreeItem t

Success.

NULL Error



Safety


Signal handler No

Thread No


PtTreeCreateItem() 2004, QNX Software Systems Ltd.

See also:PtTree, PtTreeAddAfter(), PtTreeAllocItem(), PtTreeChangeItem(),PtTreeFreeAllItems(), PtTreeFreeItems(), PtTreeItem t,PtTreeItemAttributes t, PtTreeRootItem()


2004, QNX Software Systems Ltd. PtTreeExpand()Expand an expandable item

Synopsis:int PtTreeExpand( PtWidget t *tree,

PtTreeItem t *item,PhEvent t *event );

Description:This function expands the given subtree item. The tree argument mustpoint to the tree that contains the item or can be NULL if the itemdoesn’t belong to any tree.

If the item is in the tree, the tree’s Pt CB TREE STATE callback isinvoked before the item is expanded. The event argument to thisfunction is the event that’s passed to the callback. Your callbackfunction can prevent the expansion by setting the expand field in thecallback structure to a nonzero value; zero means successfulexpansion.

Returns:The value assigned to the expand field in the callback structure, orzero if the item isn’t in a tree or there’s no Pt CB TREE STATEcallback that modifies the expand field.


Safety


Signal handler No

Thread No


PtTreeExpand() 2004, QNX Software Systems Ltd.

See also:PtTree, PtTreeCollapse(), PtTreeGetCurrent(), PtTreeGoto(),PtTreeItem t, PtTreeShow()



2004, QNX Software Systems Ltd. PtTreeFreeAllItems()Unlink and free all items

Synopsis:void PtTreeFreeAllItems( PtWidget t *tree );

Description:This function unlinks and frees all items in the tree widget. Note thatthis function is called automatically when the PtTree widget is beingdestroyed.


Safety


Signal handler No

Thread No

See also:PtTree, PtTreeAllocItem(), PtTreeFreeItems(),PtTreeRemoveChildren(), PtTreeRemoveItem(), PtTreeRemoveList()


PtTreeFreeItems() 2004, QNX Software Systems Ltd.


Synopsis:int PtTreeFreeItems( PtTreeItem t *item );

Description:This function frees the given subtrees (the item together with itsbrothers and their children). The items must not belong to any tree —use PtTreeRemoveChildren(), PtTreeRemoveItem(), orPtTreeRemoveList() to remove the subtree from a tree widget beforefreeing the subtrees.

Returns:0 Success.

-1 The item is still in a widget.


Safety


Signal handler No

Thread No

See also:PtTree, PtTreeAllocItem(), PtTreeFreeAllItems(), PtTreeItem t,PtTreeRemoveChildren(), PtTreeRemoveItem(), PtTreeRemoveList()


2004, QNX Software Systems Ltd. PtTreeGetCurrent()Get the current item

Synopsis:PtTreeItem t *PtTreeGetCurrent(

const PtWidget t *widget );

Description:This function returns a pointer to the current item in the given PtTreewidget (see “Current item” in the description of PtGenList).


Safety


Signal handler No

Thread No

See also:PtTree, PtTreeClearSelection(), PtTreeGetSelIndexes(),PtTreeGoto(), PtTreeItem t, PtTreeRootItem(), PtTreeSelect(),PtTreeSelectedItems(), PtTreeSetSelIndexes(), PtTreeShow(),PtTreeUnselect(), PtTreeUnselectNonBrothers()


PtTreeGetSelIndexes() 2004, QNX Software Systems Ltd.


Synopsis:unsigned short *PtTreeGetSelIndexes(


Description:This function fills a buffer with indexes of all the selected items in thePtTree widget. The first item in the widget has an index of 1, not 0.

� If buffer is NULL, the function allocates a buffer using malloc(),and the buffer is zero-terminated.

� If buffer is non-NULL, the function adds zero to the end only ifthere are no selected items in the widget.

Items that belong to collapsed subtrees aren’t included in the buffer.�



Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtTreeGetSelIndexes()

See also:PtTree, PtTreeClearSelection(), PtTreeGetCurrent(), PtTreeGoto(),PtTreeItem t, PtTreeRootItem(), PtTreeSelect(),PtTreeSelectedItems(), PtTreeSetSelIndexes(), PtTreeShow(),PtTreeUnselect(), PtTreeUnselectNonBrothers()


PtTreeGoto() 2004, QNX Software Systems Ltd.

Set the current item

Synopsis:int PtTreeGoto( PtWidget t *list,

PtTreeItem t *item );


If you pass item as NULL, there will be no current item.

Returns:0 Success.

Nonzero item belongs to a collapsed subtree, and a callbackfunction prevented the subtree from being expanded.


Safety


Signal handler No

Thread No

See also:PtTree, PtTreeClearSelection(), PtTreeGetCurrent(), PtTreeGoto(),PtTreeItem t, PtTreeRootItem(), PtTreeSelect(),PtTreeSelectedItems(), PtTreeSetSelIndexes(), PtTreeShow(),PtTreeUnselect(), PtTreeUnselectNonBrothers()


2004, QNX Software Systems Ltd. PtTreeItem tPtTree item structure

Synopsis:typedef struct Pt tree item {

PtGenTreeItem t gen;union {

struct { short set, unset; } img;PtTreeItemAttributes t const *ptr;} attr;

void *data;char string[1];} PtTreeItem t;

Description:This data structure describes an item in a PtTree. The membersinclude at least:

gen A structure that describes a generic-tree item. Thisstructure includes state information for the item(whether or not it’s selected, the current item,damaged, out of view, expandable, expanded, andso on), its size, and links to other generic-treeitems. For more information, seePtGenTreeItem t.

attr.img.set The index into the tree’s Pt ARG TREE IMAGESresource of the image that’s displayed when theitem is set. An item is considered set if its flagsmasked with the tree’s Pt ARG TREE IMGMASKresource give a nonzero value.

attr.img.unset The index of the image displayed when the itemisn’t set.

attr.ptr A pointer to the item’sPtTreeItemAttributes t attribute structure.

data A pointer to arbitrary user data. The widget doesn’tuse this member.


PtTreeItem t 2004, QNX Software Systems Ltd.

string The string to be displayed for the item. This field isallocated the appropriate amount of space when it’sset.

Use PtTreeAllocItem() or PtTreeCreateItem() to allocate and fill inthis structure.

Once the tree item has been created or changed, item->gen.list.flagsindicates which half of the PtTreeItem t’s attr union is valid.When this flag is Pt TREE ITEM HAS ATTRS, attr.ptr is a pointer toan attributes structure (or NULL). When this flag is clear, attr.img.setand attr.img.unset are indexes into the Pt ARG TREE IMAGES array(or -1).


See also:PtGenList, PtGenTree, PtGenTreeItem t, PtTree,PtTreeAddAfter(), PtTreeAddFirst(), PtTreeAllItems(),PtTreeAllocItem(), PtTreeChangeItem(), PtTreeCreateItem(),PtTreeFreeItems(), PtTreeGetCurrent(),PtTreeItemAttributes t, PtTreeItemIndex(),PtTreeModifyItem(), PtTreeModifyItemString(), PtTreeRemoveItem(),PtTreeRootItem(), PtTreeSelectedItems()


2004, QNX Software Systems Ltd. PtTreeItemAttributes tPtTree item attributes structure

Synopsis:typedef struct Pt tree item attributes {

PtGenListItemAttrs t list;PhImage t const *set image, *unset image;}

PtTreeItemAttributes t;

Description:This data structure describes the attributes for a PtTreeItem t. Themembers include at least:

list A PtGenListItemsAttrs t structure thatrepresents a list of generic item attributes. See thedescription below.

set image A pointer to the set image for the item.

unset image A pointer for the unset image for the item.

It’s your responsibility to allocate and deallocate the members of thisstructure, and to ensure that their contents don’t change while thestructure is in use.

Use this structure as a parameter to PtTreeCreateItem() to create atree item with attributes (as opposed to PtTreeAllocItem()), and toPtTreeChangeItem() to change an existing tree item.

The list member is a PtGenListItemAttrs t with this structure:

typedef struct Pt genlist item attrs {const char *font;PtGenListColorSet t unselected colors;PtGenListColorSet t selected colors;unsigned flags;} PtGenListItemAttrs t;

The members are:


PtTreeItemAttributes t 2004, QNX Software Systems Ltd.

font The font name for the item text. If this item is set to NULL,the widget-defined font it used.

unselected colors, selected colors

The text and fill color for the list item. Set toPg TRANSPARENT to use the widget-defined color.

This member is a PtGenListColorSet t, with thisstructure:

typedef struct Pt gen list color set {PgColor t text, fill;} PtGenListColorSet t;

flags Used internally. Must be set to zero.


See also:PtTree, PtTreeChangeItem(), PtTreeCreateItem(), PtTreeItem t


2004, QNX Software Systems Ltd. PtTreeItemIndex()Calculate the index of the given item within the tree

Synopsis:int PtTreeItemIndex( const PtTreeWidget t *tree,

const PtTreeItem t *item );

Description:This function calculates the index of the given item within the tree.The index of the first item is 1.

Returns:The index of the item, or 0 if it belongs to a collapsed subtree.


Safety


Signal handler No

Thread No

See also:PtTree, PtTreeAllItems(), PtTreeGetSelIndexes(), PtTreeItem t


PtTreeModifyItem() 2004, QNX Software Systems Ltd.

Change item resources

Synopsis:PtTreeItem t *PtTreeModifyItem( PtWidget t *tree,

PtTreeItem t *item,const char *string,short set img,short unset img );

Description:This function changes item resources:

� The item’s string is changed to be a copy of string. If string isNULL, the item’s string isn’t changed.

� The set img argument is the index of the image that’s displayedwhen the item is set, and unset img is the image displayed when itisn’t set. An item is considered set if its flags masked with thePt ARG TREE IMGMASK resource of the widget give a nonzerovalue.

The tree is a pointer to the PtTree that the item belongs to, or NULL.If the item is in a tree, it must be in the one pointed to by tree.

Returns:The new address of the item.

This address may differ from the old one if the new string is longer.�


Safety


continued. . .


2004, QNX Software Systems Ltd. PtTreeModifyItem()

Safety

Signal handler No

Thread No

See also:PtTree, PtTreeAllocItem(), PtTreeItem t, PtTreeItemIndex(),PtTreeModifyItemString()


PtTreeModifyItemString() 2004, QNX Software Systems Ltd.

Change the string for a PtTree item

Synopsis:PtTreeItem t *PtTreeModifyItemString(

PtWidget t *tree,PtTreeItem t *item,const char *string );

Description:This function changes the string for the given item, making a copy ofstring. The tree is a pointer to the PtTree that the item is in, orNULL. If the item is in a tree, it must be in the one pointed to by tree.

Returns:The new address of the item.

This address may differ from the old one if the new string is longer.�


Safety


Signal handler No

Thread No

See also:PtTree, PtTreeAllocItem(), PtTreeItem t, PtTreeItemIndex(),PtTreeModifyItem()


2004, QNX Software Systems Ltd. PtTreeRemoveChildren()Unlink the children of the specified item

Synopsis:PtTreeItem t *PtTreeRemoveChildren(


Description:This function unlinks all the children of the specified item and returnsthe pointer to the first of them:

B

CAA

D

B

C

returned pointertree

item

tree

D

The results of using PtTreeRemoveChildren().

You can then give the pointer to the PtTreeFreeItems() function.

This function doesn’t collapse the item. If the children are visible,PtTreeRemoveChildren() returns NULL. Call PtTreeCollapse() beforePtTreeRemoveItem() to make sure that the item is collapsed.

Returns:A pointer to the first of the removed children, or NULL if the childrenare visible.


PtTreeRemoveChildren() 2004, QNX Software Systems Ltd.


Safety


Signal handler No

Thread No

See also:PtTree, PtTreeAddAfter(), PtTreeAddFirst(), PtTreeAllocItem(),PtTreeFreeAllItems(), PtTreeFreeItems(), PtTreeItem t,PtTreeRemoveItem(), PtTreeRemoveList()


2004, QNX Software Systems Ltd. PtTreeRemoveItem()Unlink an item

Synopsis:void PtTreeRemoveItem( PtWidget t *tree,


Description:This function unlinks the given item together with its children from itsparent and brothers (if any) and sets the item->gen.father anditem->gen.brother fields to NULL:

B

C

C

B

itemtree

item

tree

A A

The results of using PtTreeRemoveItem().

The tree argument must point to the PtTree widget containing theitem, or can be NULL if the item doesn’t belong to any tree.

Note that if tree is NULL and the item has no parent but has a previousbrother, then the function can’t find the previous brother, andtherefore can’t unlink the item from its brother. The function doesnothing if item->gen.father and tree are NULL.

PtTreeRemoveItem() never clears the Pt TREE ITEM EXPANDABLEflag in the item’s parent.



PtTreeRemoveItem() 2004, QNX Software Systems Ltd.

Safety


Signal handler No

Thread No

See also:PtTree, PtTreeAddAfter(), PtTreeAddFirst(), PtTreeAllocItem(),PtTreeFreeAllItems(), PtTreeFreeItems(), PtTreeItem t,PtTreeRemoveChildren(), PtTreeRemoveList()


2004, QNX Software Systems Ltd. PtTreeRemoveList()Unlink the root item

Synopsis:void PtTreeRemoveList( PtWidget t *tree,

PtTreeItem t *first );

Description:This function unlinks the item first and its brothers (together withtheir children) from their parent (and previous brother) and sets theirgen.father fields to NULL:

B

C

C

B

firsttree

first

tree

A A

The results of using PtTreeRemoveList().

The tree argument must point to the PtTree widget that contains theitems, or can be NULL if the items don’t belong to any tree.

Note that if tree is NULL and first has no parent but has a previousbrother, then the function won’t be able to find the previous brotherand therefore can’t unlink first from its previous brother.


Safety


continued. . .


PtTreeRemoveList() 2004, QNX Software Systems Ltd.

Safety

Signal handler No

Thread No

See also:PtTree, PtTreeAddAfter(), PtTreeAddFirst(), PtTreeAllocItem(),PtTreeFreeAllItems(), PtTreeFreeItems(), PtTreeItem t,PtTreeRemoveChildren(), PtTreeRemoveItem()


2004, QNX Software Systems Ltd. PtTreeRootItem()Return the first root item of the tree

Synopsis:PtTreeItem t *PtTreeRootItem(

PtTreeWidget t const *tree );

Description:This function returns a pointer to the first root item in the givenPtTree widget.


Safety


Signal handler No

Thread No

See also:PtTree, PtTreeAddAfter(), PtTreeAddFirst(), PtTreeAllItems(),PtTreeFreeAllItems(), PtTreeFreeItems(), PtTreeGetCurrent(),PtTreeGoto(), PtTreeItem t, PtTreeSelect(), PtTreeShow()


PtTreeSelect() 2004, QNX Software Systems Ltd.

Select the specified item

Synopsis:void PtTreeSelect( PtWidget t *widget,


Description:This function selects the given item belonging to the given PtTree

widget. You can pass NULL for widget if the item doesn’t belong to awidget.


Safety


Signal handler No

Thread No

See also:PtTree, PtTreeClearSelection(), PtTreeGetCurrent(),PtTreeGetSelIndexes(), PtTreeGoto(), PtTreeItem t,PtTreeSelectedItems(), PtTreeSetSelIndexes(), PtTreeUnselect(),PtTreeUnselectNonBrothers()


2004, QNX Software Systems Ltd. PtTreeSelectedItems()Fill a buffer with item pointers

Synopsis:PtTreeItem t **PtTreeSelectedItems(

PtWidget t *widget,PtTreeItem t **buffer );

Description:This function fills a buffer with pointers to the tree’s selected items:

� If buffer is NULL, the function allocates a buffer using malloc(),and the buffer is NULL-terminated.

� If buffer is non-NULL, the function adds a NULL at the end only ifthere are no selected items in the widget.

Items that belong to collapsed subtrees aren’t included in the buffer.�



Safety


Signal handler No

Thread No


PtTreeSelectedItems() 2004, QNX Software Systems Ltd.

See also:PtTree, PtTreeClearSelection(), PtTreeGetCurrent(),PtTreeGetSelIndexes(), PtTreeGoto(), PtTreeItem t,PtTreeSelect(), PtTreeSetSelIndexes(), PtTreeUnselect(),PtTreeUnselectNonBrothers()


2004, QNX Software Systems Ltd. PtTreeSetSelIndexes()Set the selection indexes

Synopsis:int PtTreeSetSelIndexes(

PtWidget t *widget,const unsigned short *buffer,int count );

Description:This function sets the selection indexes. The function assumes thatbuffer points to a sorted array of indexes. The first item in the widgethas an index of 1, not 0.

The function returns the number of items that have been actuallyselected, which may be smaller than count if the array isn’t sorted orcontains duplicate indexes or indexes out of range.

Note that if the selection mode is Pt RANGE MODE, only the firstindex and the count are used.


Safety


Signal handler No

Thread No

See also:PtTree, PtTreeClearSelection(), PtTreeGetCurrent(),PtTreeGetSelIndexes(), PtTreeGoto(), PtTreeItem t,PtTreeSelect(), PtTreeSelectedItems(), PtTreeUnselect(),PtTreeUnselectNonBrothers()


PtTreeShow() 2004, QNX Software Systems Ltd.

Set the position so that the specified item is visible

Synopsis:int PtTreeShow( PtWidget t *widget,


Description:This function sets the current position so that the given item is visible.If you pass item as NULL, the function does nothing. This lets you dosomething like this:

PtTreeShow( widget, PtTreeGetCurrent(widget) );

without checking to see if PtTreeGetCurrent() returned NULL.

Returns:0 Success.

Nonzero item belongs to a collapsed subtree, and a callbackfunction prevented the subtree from being expanded


Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtTreeShow()

See also:PtTree, PtTreeClearSelection(), PtTreeCollapse(), PtTreeExpand(),PtTreeGetCurrent(), PtTreeGetSelIndexes(), PtTreeGoto(),PtTreeItem t, PtTreeRootItem(), PtTreeSelect()


PtTreeUnselect() 2004, QNX Software Systems Ltd.

Unselect the given item

Synopsis:void PtTreeUnselect( PtWidget t *widget,


Description:This function unselects the given item belonging to the given PtTree

widget.

Note that PtTreeUnselect() doesn’t support the Pt RANGE MODEselection mode.


Safety


Signal handler No

Thread No

See also:PtTree, PtTreeClearSelection(), PtTreeGetCurrent(),PtTreeGetSelIndexes(), PtTreeGoto(), PtTreeItem t,PtTreeSelect(), PtTreeSelectedItems(), PtTreeSetSelIndexes(),PtTreeUnselectNonBrothers()


2004, QNX Software Systems Ltd. PtTreeUnselectNonBrothers()Unselect all items that aren’t siblings of the specified item

Synopsis:void PtTreeUnselectNonBrothers(

PtWidget t *widget,PtTreeItem t *item );

Description:This function unselects all the items that aren’t siblings of the givenitem. If you pass item as NULL, the current item is used (see “Currentitem” in the description of PtGenList).


Safety


Signal handler No

Thread No

See also:PtTree, PtTreeClearSelection(), PtTreeGetCurrent(),PtTreeGetSelIndexes(), PtTreeGoto(), PtTreeItem t,PtTreeSelect(), PtTreeSelectedItems(), PtTreeSetSelIndexes(),PtTreeUnselect()


PtTrend 2004, QNX Software Systems Ltd.

A trend graph

Class hierarchy:PtWidget → PtBasic → PtTrend

PhAB icon:

Public header:<photon/PtTrend.h>

Description:A PtTrend widget displays a trend graph. The data is displayed as aset of connected points that shift in a specified direction and at therate at which data is fed in.

A PtTrend widget.


2004, QNX Software Systems Ltd. PtTrend

New resources:


Pt ARG TREND ATTRIBUTES PtTrendAttr t *, short Array 1 or(1,1,1,1..)

Pt ARG TREND COLOR LIST PgColor t *, short Array NULL

Pt ARG TREND COUNT int Scalar 1

Pt ARG TREND DATA short *, int Array None(write-only)

Pt ARG TREND FLAGS long Flag Seebelow

Pt ARG TREND GRID COLOR PgColor t Scalar Pg GRAY

Pt ARG TREND GRID X short int Scalar 5

Pt ARG TREND GRID Y short int Scalar 5

Pt ARG TREND INC short int Scalar 1

Pt ARG TREND MAX short int Scalar SHRT MAX

Pt ARG TREND MIN short int Scalar SHRT MIN

Pt ARG TREND PALETTE END unsigned short Scalar 256

Pt ARG TREND ATTRIBUTES


PtTrendAttr t *, short Array 1 or (1,1,1,1..)

The attributes that the trend may have. This resource is an array ofstructures of type PtTrendAttr t, which contains at least thefollowing member:



int map An index into Pt ARG TREND COLOR LIST toindicate the color that the trend uses. This index is usedas follows:

Index Color used

0 Pt ARG FILL COLOR (that is, the background color forthe widget)

1 the first color in Pt ARG TREND COLOR LIST (which isthe same as Pt ARG COLOR)

2 the second color in Pt ARG TREND COLOR LIST

3 etc.

In order to set this resource, you must use the arguments to PtSetArg()in an unusual way; the value argument points to the value of theresource, as usual, but len is used for the trend number, not the size ofvalue.

To set the colors for all the trends at once, specify a list of mappingsof trends onto colors, and use 0 for the trend number. That is, the lenargument to 0 and have the value argument point to an array ofPtTrendAttr t structures.

For example, the following code fragment sets up the color list, andsets the colors to be used for three trends.

int trend color array[4] = {Pg GREEN, Pg RED,Pg YELLOW, Pg BLUE};

PtTrendAttr t one attr, several attr[3];PtArg t args[2];PtWidget t trend widget;

...

/* Set up the color list. */PtSetArg (&args[0], Pt ARG TREND COLOR LIST,

trend color array, 4);PtSetResources (trend widget, 1, args);



/* Map the trends to colors. */several attr[0].map = 3; /* Trend 0 is Pg YELLOW */several attr[1].map = 2; /* Trend 1 is Pg RED */several attr[2].map = 4; /* trend 2 is Pg BLUE */

PtSetArg (&args[0], Pt ARG TREND ATTRIBUTES,several attr, 0);

PtSetResources (trend widget, 1, args);

To set an attribute for a given trend, set PtSetArg’s len argument to thenumber of that trend, and have the value argument point to a singlestructure of type PtTrendAttr t. For example, the followingchanges the color of trend 2 to Pg GREEN:

one attr.map = 1;PtSetArg (&args[0], Pt ARG TREND ATTRIBUTES,

&one attr, 2);PtSetResources (trend widget, 1, args);

It isn’t possible to set the color of trend 0 alone, as setting the lenargument of PtSetArg() to 0 specifies that you want to set the colorindex for all the trends.

�

Pt ARG TREND COLOR LIST


PgColor t *, short Array NULL

The list of colors that the trend may use. See PgColor t in thePhoton Library Reference.

To assign one of these colors to a trend, use thePt ARG TREND ATTRIBUTES resource.

The first color in this list is always the same as Pt ARG COLOR.�



Pt ARG TREND COUNT


int Scalar 1

The number of trends that the widget displays.

Pt ARG TREND DATA (write-only)


short *, int Array None

The data displayed by the trends. You can use this resource to set thedata; you can’t use it to extract the data from the trends.

When you want to add data to a trend, your application should set thevalue argument to PtSetArg() with a pointer to a data buffer thatcontains the new data points. The application must also set the lenparameter to the number of new data points being added to the trend.

If the widget is displaying multiple trends, the data buffer mustcontain the new data for each trend: data for the first trend is followedby data for the second trend, and so on. The application must set lento be the total number of points being added, not the number of pointsper trend.

If you set the value parameter to NULL, the trend’s display is cleared.

If you wish to replace some of the data for one trend, callPtTrendChangeData(). To replace data in all trends, callPtTrendChangeTrendData().

Pt ARG TREND FLAGS




long Flag Pt TREND HORIZONTAL | Pt GRID |Pt TREND RIGHT TO LEFT |Pt GRID IS TRANSLUCENT

Flags that control the appearance of the widget. The bits include:

Pt GRID Draw a grid.

If this flag is set, you must also setPt GRID IS TRANSLUCENT,Pt GRID ABOVE TRENDS, orPt TRENDS ABOVE GRID.

Pt GRID ABOVE TRENDS

Make the grid opaque, appearing over the trends.

The grid is displayed only if Pt GRID is set.

Pt GRID FORCE

Draw a grid even if the graphics device doesn’t supportplanar hardware blitting. Some flickering may occur.

Pt GRID IS TRANSLUCENT

Make the grid translucent, appearing over the trends.


Pt PIXEL Draw the trend with PgDrawPixelArray() instead ofPgDrawPolygon().

Pt TREND HORIZONTAL

Make the trends horizontal.

If this is set, you must also setPt TREND LEFT TO RIGHT orPt TREND RIGHT TO LEFT.



Pt TREND BOTTOM TO TOP

Make the trends move from the bottom to the top of thewidget. You can use this only withPt TREND VERTICAL.

Pt TREND LEFT TO RIGHT

Make the trends move from left to right. You can usethis only with Pt TREND HORIZONTAL.

Pt TREND RIGHT TO LEFT

Make the trends move from right to left. You can usethis only with Pt TREND HORIZONTAL.

Pt TREND TOP TO BOTTOM

Make the trends move from the top to the bottom of thewidget. You can use this only withPt TREND VERTICAL.

Pt TREND VERTICAL

Make the trends vertical.

If this is set, you must also setPt TREND TOP TO BOTTOM orPt TREND BOTTOM TO TOP.

Pt TRENDS ABOVE GRID

Make the grid opaque, appearing under the trends.


If you set Pt ARG TREND FLAGS to an invalid value, the widgetdraws only the background.

�

Pt ARG TREND GRID COLOR




PgColor t Scalar Pg GRAY

The color of the grid, specified as an RGB value. See PgColor t inthe Photon Library Reference.

The grid is displayed only if Pt GRID is set inPt ARG TREND FLAGS.

Pt ARG TREND GRID X


short int Scalar 5

The number of grid lines along the x axis; in other words, the numberof vertical lines. The grid is displayed only if Pt GRID is set inPt ARG TREND FLAGS.

Pt ARG TREND GRID Y


short int Scalar 5

The number of grid lines along the y axis; in other words, the numberof horizontal lines. The grid is displayed only if Pt GRID is set inPt ARG TREND FLAGS.

Pt ARG TREND INC


short int Scalar 1

The distance between data points displayed on the screen. The defaultis 1. Note that if the increment is too large, the data won’t be plotted



correctly. Generally, you should use this resource only if you need acoarse-grained display.

Pt ARG TREND MAX


short int Scalar SHRT MAX

The maximum data value for all the trends.

Pt ARG TREND MIN


short int Scalar SHRT MIN

The minimum data value for all the trends.

Pt ARG TREND PALETTE END



Defines the range of palette entries the widget uses for drawing if thegrid is displayed. This is useful if you have more than one PtTrendwidget and you want to make sure their palette entries don’t overlap.

Each PtTrend widget uses:

� two palette entries for each entry in thePt ARG TREND COLOR LIST — one for the trend, and one forwhere the trend overlaps the grid

� one palette entry for the background

� one palette entry for the grid.

If E is the value of the Pt ARG TREND PALETTE END resource andN is the number of palette entries used for the widget (rounded up to



the next power of 2), the widget uses palette entries from E - N to E -1.

The value of Pt ARG TREND PALETTE END should be a multipleof N. If it isn’t, it’s rounded down to a multiple of N.


















continued. . .





Pt ARG DIM PtWidget


















Pt ARG POS PtWidget




continued. . .







Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget




Convenience functions:The PtTrend widget defines the following convenience functionsthat make it easier to use the widget once it’s been created:

PtTrendChangeData()

Replace some samples for all trends



PtTrendChangeTrendData()

Replace some samples for one trend


2004, QNX Software Systems Ltd. PtTrendChangeData(),PtTrendChangeTrendData()

Replace some samples for one or all trends

Synopsis:void PtTrendChangeData( PtWidget t *widget,

short const *newdata,unsigned last sample,unsigned nsamples);

void PtTrendChangeTrendData( PtWidget t *widget,unsigned tn,short const *newdata,unsigned last sample,unsigned nsamples);

Description:These functions let you replace some samples in one or more trends,without touching other data or other trends in the widget.

These functions are used to replace data that’s already in a trend, notto add data to the end of the trends.

�

PtTrendChangeTrendData() lets you change data for a single trend.The widget argument must be a widget of type PtTrend. The tnargument is the number of the trend to be changed, in the range 0 totrend count - 1, inclusive.

The newdata argument is a pointer to an array of the new data.last sample is the index of the newest sample to replace, where 0 isconsidered to be the index of the most recently added sample.nsamples is the number of samples to be replaced. The diagram belowshows how the samples are replaced.


PtTrendChangeData(), PtTrendChangeTrendData() 2004, QNX Software Systems Ltd.

last_sample + nsamples -1 last_sample

newdata[0] newdata nsamples-1][

Old samples New samplesMovement

Replacing trend samples with PtTrendChangeData() or

PtTrendChangeTrendData().

The newdata array is ordered with the oldest sample at newdata[0],and the newest at newdata[nsamples - 1]. The oldest sample to bereplaced will have an index of last sample + nsamples - 1;

The samples in the trend are replaced as follows:

� trend sample[last sample] = newdata[nsamples - 1].

� trend sample[last sample + 1] = newdata[nsamples - 2].

� ...


2004, QNX Software Systems Ltd. PtTrendChangeData(),PtTrendChangeTrendData()

� trend sample[last sample + nsamples - 1] = newdata[0].

If last sample + nsamples - 1 is outside the range of samples for thewidget, some initial portion of the new data is discarded.

PtTrendChangeData() lets you change the data for all the trends. Itsarguments are similar to those of PtTrendChangeTrendData() with thefollowing exceptions:

� The tn argument isn’t passed to PtTrendChangeData().

� The data for the first trend is put into the first nsamples places ofnewdata, followed by those for trend 2, 3 and so on.

Calling PtTrendChangeData() is similar to callingPtTrendChangeTrendData() in the following loop:

for (i=0; i<TREND COUNT; ++i) {PtTrendChangeTrendData (widget, i, newdata, last sample,

nsamples);newdata += nsamples;

}

The only difference is that PtTrendChangeData() redraws the widgetonce; the loop redraws it once per iteration.


Safety


Signal handler No

Thread No


PtTty 2004, QNX Software Systems Ltd.

A PtTerminal widget attached to a device

Class hierarchy:PtWidget → PtBasic → PtContainer → PtTerminal →PtTty

PhAB icon:

Public header:<photon/PtTty.h>

Description:A PtTty widget is a PtTerminal attached to a device. The deviceoutput is passed to the terminal, but also can be caught with thePt CB TTY OUTPUT callback.

Output from a terminal device.

If the widget has the Pt GETS FOCUS flag set in its Pt ARG FLAGSresource, keyboard input to the widget (as well as mouse events) areredirected to the device. You can also use the Pt ARG TTY INPUTresource to simulate keyboard input.

PtTerminal and PtTty

The main difference between PtTerminal and PtTty is thatPtTerminal doesn’t do any I/O for you. The only way to displaycharacters in a PtTerminal is by giving them to one of the


2004, QNX Software Systems Ltd. PtTty

PtTerminalPut*() functions. Similarly, the only thing PtTerminaldoes with Photon input is translate function keys into text-modecompatible escape sequences and give the result to yourPt CB TERM INPUT callback.

PtTty adds device I/O to that. The code that opens a pty, readscharacters from it, and gives those characters to PtTerminalPut() ispart of PtTty. Similarly, PtTty attaches a Pt CB TERM INPUTcallback that writes Photon keyboard input (translated byPtTerminal to text-mode compatible format) to the pty.

Another responsibility of PtTty is spawning a command for you andinvoking the Pt CB TTY TERMINATED callbacks when thecommand terminates.

Setting PtTty resources

Some of the resources for PtTty aren’t just data stored in the widget,they’re “action resources” that define an action to be performed whenyou set the resource. This includes all the resources flagged aswrite-only.

Some of those actions are order-dependent. For example, you can’tspawn a program on a device (by setting Pt ARG TTY CMD orPt ARG TTY ARGV) before defining which device it’s to be spawnedon (by setting Pt ARG TTY SFD, Pt ARG TTY PATH, orPt ARG TTY PSEUDO).

The widget opens its pty and starts its command as soon as you setPt ARG TTY CMD or Pt ARG TTY ARGV , even if the widget hasn’tyet been realized. By default, the command continues to run if youunrealize the widget.

�

Additionally, the following resources are order-dependent eventhough they’re not action resources:

� Pt ARG TERM ANSI PROTOCOL

� Pt ARG TTY FDSET

� Pt ARG TTY FLAGS (Pt TTY SETENV and Pt TTY ARGV0)



� Pt ARG TTY SPAWN OPTIONS

Since the widget looks at the current value of these resources whenspawning the command, changing their values after a command hasbeen spawned doesn’t affect the command that’s already running.Make sure that those resources have correct values before you setPt ARG TTY CMD or Pt ARG TTY ARGV .

Here’s an example:

/* Open a pseudo tty -- NULL is a shortcut for "/dev";* the widget will add something like "ttyp3" to it*/

PtSetArg( &arg, Pt ARG TTY PSEUDO, NULL, 0 );PtSetResources( ABW tty, 1, &arg );

/* Have we succeeded? */PtSetArg( &arg, Pt ARG TTY SFD, 0, 0 );PtGetResources( ABW tty, 1, &arg );if ( arg.value == -1 )

PtTerminalPuts( ABW tty, "Unable to find a pty\r\n" );else {

/* Run a program on the pseudo tty.* NULL is more or less a shortcut for* "char *argv[] = { "/bin/sh", NULL };",* except it runs *your* shell rather than always /bin/sh.*/

PtSetArg( &arg, Pt ARG TTY ARGV, NULL, 0 );PtSetResources( ABW tty, 1, &arg );

/* Have we succeeded? */PtSetArg( &arg, Pt ARG TTY PID, NULL, 0 );PtGetResources( ABW tty, 1, &arg );if ( arg.value == 0 )

PtTerminalPuts( ABW tty, "Unable to spawn the shell\r\n" );}

PhAB doesn’t know that these resources are order-dependent. Set theresources in the correct order. If you suspect that the order isn’tcorrect, set all the order-dependent resources to their default values,and then set them again in the correct order.

�



File descriptors

PtTty uses three file descriptors, but they don’t have to be different.The following resources are involved:

Pt ARG TTY RFD

The file descriptor that the widget uses for reading. Any inputfrom this fd is displayed in the widget.

Pt ARG TTY WFD

The fd to which the widget writes keyboard input.

Pt ARG TTY SFD

The fd that the widget maps stdin, stdout, and stderr to whenyou set Pt ARG TTY CMD or Pt ARG TTY ARGV .

Pt ARG TTY SFD overrides the entries in the iov array of thePt ARG TTY SPAWN OPTIONS resource that correspond to the setbits in Pt ARG TTY FDSET .

�

Pt ARG TTY FDS

A shortcut for setting Pt ARG TTY RFD, Pt ARG TTY WFD,and Pt ARG TTY SFD to the same value. SettingPt ARG TTY FDS to -1 closes any previously open filedescriptors and sets Pt ARG TTY PATH to NULL.

When you set Pt ARG TTY RFD or Pt ARG TTY WFD to a filedescriptor, the widget sets the O NONBLOCK flag on that fd if it isn’talready set.

When the widget is later destroyed, or its resources are changed insuch a way that neither Pt ARG TTY RFD nor Pt ARG TTY WFDreferences that fd any more, the widget unsets the O NONBLOCK flag.If the Pt ARG TTY SFD resource doesn’t reference that fd either, thefd is then closed.

In short, if you give an fd to a PtTty widget, it’s the widget’sresponsibility to close it when it’s no longer used. If you want to keep



the fd, make a copy using dup() (see the QNX Neutrino LibraryReference) and give that copy to the widget. Either way, don’t useeither the copy or the original fd for any I/O while the widget is usingit.

Drag and Drop


New resources:


Pt ARG TTY ARGV char ** Pointer (write-only)

Pt ARG TTY BUFFER char *, unsigned short Array allocated

Pt ARG TTY BUFLEN unsigned short Scalar 1024

Pt ARG TTY CMD char * String (write-only)

Pt ARG TTY DEVSIZE PtTerminalRowCol t Struct 0, 0

Pt ARG TTY EXIT STATUS int Scalar 0 (read-only)

Pt ARG TTY FDS int Scalar -1

Pt ARG TTY FDSET unsigned short Scalar 7

Pt ARG TTY FLAGS unsigned short Flag Seebelow

Pt ARG TTY INPUT char *, unsigned short Array NULL

continued. . .




Pt ARG TTY INPUT WRITTEN unsigned short Scalar 0 (read-only)

Pt ARG TTY PATH char * String NULL

Pt ARG TTY PID pid t Scalar 0

Pt ARG TTY PRI int Scalar -1

Pt ARG TTY PSEUDO char * String NULL

Pt ARG TTY RFD int Scalar -1

Pt ARG TTY SFD int Scalar -1

Pt ARG TTY SPAWN OPTIONS PtSpawnOptions t const * Pointer NULL

Pt ARG TTY WFD int Scalar -1

Pt CB TTY DEVSIZE PtCallback t * Link NULL

Pt CB TTY OUTPUT PtCallback t * Link NULL

Pt CB TTY TERMINATED PtCallback t * Link NULL

Pt ARG TTY ARGV (write-only)


char ** Pointer

When you set this resource, the widget spawns a process on thedevice. The resource value must be the pointer to a NULL-terminatedarray of pointers to strings. These strings are used for the programname and arguments.

The first string in the array specifies the program to execute. If itdoesn’t contain a slash character, the PATH environment variable isused to search for the program.

If the Pt TTY ARGV0 flag is set (which is the default), the first stringis also used as the first argument to the new process (argv[0]). If the



flag is clear, the argument list is assumed to start from the second itemof the array passed as the resource value. This lets you run a programwhose argv[0] entry is different from the actual name of the program.

If the list is NULL or contains too few non-NULL elements (theminimum is one when the Pt TTY ARGV0 flag is set and two whenit’s clear), the user’s shell is spawned. If the Pt TTY ARGV0 flag isclear and the list is NULL or empty, this is a login shell.

All the flags and resources described under Pt ARG TTY CMD,except the Pt TTY ARGV0 flag, have the same effect when thisresource is set.

Pt ARG TTY BUFFER


char *, unsigned short Array allocated

The buffer that’s used by the widget for reading data from the deviceand passing them to the PtTerminalPut() function. If you set thisresource, you must give both the address and the length of a buffer forthe widget to use. Several widgets may share a common buffer,provided that none of them attaches a callback that could cause arecursive invocation of PtTerminalPut().

Pt ARG TTY BUFLEN



The length of the buffer used by the widget for reading data from thedevice. If you set this resource, the widget allocates a buffer.

Pt ARG TTY CMD (write-only)




char * String

When you set this resource, the widget spawns a process on thedevice.

If the resource value is a NULL or points to an empty string, the user’sshell is spawned. If the resource is a nonempty string, the widgetspawns the user’s shell with two arguments: -c and the resourcestring. In either case, if the Pt TTY ARGV0 flag is clear, the shell isstarted as a login shell.

If another process has been spawned previously and is still running,and the Pt ARG TTY PID resource hasn’t been set to zero, aSIGTERM signal is sent to the process group of that process beforestarting the new program.

If the Pt TTY SETENV flag is set (which is the default), the TERMenvironment variable of the new process is set to a valuecorresponding to the current terminal protocol (using thePtTerminalName() function). The environment variables LINES andCOLUMNS are also removed if they exist.

Pt ARG TTY DEVSIZE



The current device size. It can differ from the terminal widget’s size,depending on the Pt ARG TTY FLAGS resource. ThePtTerminalRowCol t structure contains the following members:

� short r

� short c



Pt ARG TTY EXIT STATUS (read-only)


int Scalar 0

The exit status of the process spawned on the device. You canexamine the value using the POSIX macros described for waitpid() inthe QNX Neutrino Library Reference. The value is valid only afterthe child process has terminated.

Pt ARG TTY FDS


int Scalar -1

A shortcut for setting Pt ARG TTY RFD, Pt ARG TTY WFD, andPt ARG TTY SFD to the same value. Setting Pt ARG TTY FDS to -1closes any previously open file descriptors and sets thePt ARG TTY PATH to NULL.

For more details, see “File descriptors,” above.

Pt ARG TTY FDSET



This number defines (as a bitmask) the set of file descriptors that thewidget sets for a new process started when the Pt ARG TTY CMD orPt ARG TTY ARGV resource is set. The default value of 7 means thatthe PtTty widget’s device is available as descriptors 0, 1 and 2. Onlythe ten low-order bits are used because the redirection is done usingthe iov[] member of the PtSpawnOptions t structure, which hasten elements.



Pt ARG TTY FLAGS


unsigned short Flag See below

Flags that affect the widget’s behavior. Any combination of:

� Pt TTY DEVRESIZE — when the terminal’s size changes, thedevice is resized.

� Pt TTY TERMRESIZE — when the device size changes, theterminal widget’s size is set (but the operation may fail if thedevice size is beyond terminal’s size limit).

� Pt TTY DEVLIMIT — when the device size changes beyond theterminal’s size limit, the device is resized.

� Pt TTY DEVFORCE — when the device size changes, it’s resizedback to the terminal’s size.

� Pt TTY SETENV — modify environment variables (seePt ARG TTY CMD).

� Pt TTY ARGV0 — use the program name as argv[0] (seePt ARG TTY CMD).

� Pt TTY BUF PRIVATE (read-only) — the widget is using anallocated buffer.

By default, all bits are set except Pt TTY DEVFORCE.

If both Pt TTY TERMRESIZE and Pt TTY DEVRESIZE flags are set,changes of sizes are propagated in both directions. However, if thesizes differ at the moment when the flags are set or when the device isbeing opened, the device size is adjusted.

If the Pt TTY DEVFORCE flag is set, the Pt TTY DEVLIMIT flag isignored.



Pt ARG TTY INPUT


char *, unsigned short Array NULL

Characters to be written to the device.

Since the device is opened with the O NONBLOCK flag, the numberof bytes that are actually written may be less than the specified length.You can use the Pt ARG TTY INPUT WRITTEN resource to find outhow many bytes the widget managed to read.

Pt ARG TTY INPUT WRITTEN (read-only)



The number of characters successfully written by thePt ARG TTY INPUT resource.

Pt ARG TTY PATH


char * String NULL

When you set this resource, the widget closes all its file descriptors,then attempts to open the given pathname and stores the new fd (or -1on error) in Pt ARG TTY RFD, Pt ARG TTY WFD, andPt ARG TTY SFD.

The descriptor is guaranteed to be greater than 2 and have theFD CLOEXEC flag set.

Pt ARG TTY PID




pid t Scalar 0

Zero or the process ID of the process that has been spawned on thedevice. The only value to which you can explicitly set this resource iszero, meaning “Forget about that process.” If this resource is nonzerowhen the device is closed (e.g. when the widget is being destroyed), aSIGHUP signal is sent to the process group of the child process.

Pt ARG TTY PRI


int Scalar -1

The priority of Photon pulses attached to the device — seePtAppAddFdPri() in the Photon Library Reference.

Pt ARG TTY PSEUDO


char * String NULL

When you set this resource, the widget closes all its file descriptors,then attempts to find and open a pseudo-tty.

The “master” fd is stored in both Pt ARG TTY RFD andPt ARG TTY WFD, and the “slave” fd in Pt ARG TTY SFD.

Also, the pathname of the slave device is stored inPt ARG TTY PATH.

You should set this resource to NULL or to the name of a directorythat contains some ptys.

After opening the pseudo tty, the stty entry of the “slave” device is setto default modes. The editing keys are set according to the currentvalue of the Pt ARG TERM ANSI PROTOCOL resource (see



PtTerminal). If the protocol is changed with the same call toPtSetResources() that opens the pseudo tty, the order of the argumentlist is significant.

Both descriptors opened in this mode are guaranteed to be greaterthan 2 and have the FD CLOEXEC flag set.

Pt ARG TTY RFD


int Scalar -1

The file descriptor that the widget uses for reading. Any input fromthis FD is displayed in the widget.


Pt ARG TTY SFD


int Scalar -1

The file descriptor to which the widget maps stdin, stdout, and stderrwhen you set Pt ARG TTY CMD or Pt ARG TTY ARGV .



�

Pt ARG TTY SPAWN OPTIONS


PtSpawnOptions t const * Pointer NULL



A pointer to a PtSpawnOptions t structure that’s used forspawning the child process.

If you leave this resource set to NULL, the widget uses the defaultvalues in:

extern const PtSpawnOptions t PtTtyDefaultSpawnOptions

For more information about this structure, see PtSpawn() in thePhoton Library Reference.


�

Pt ARG TTY WFD


int Scalar -1

The file descriptor to which the widget writes keyboard input.

When you set this resource, the widget attaches itself to the given filedescriptor. The descriptor must be open in a mode that allows writing.To force the widget to detach from any file descriptor it’s attached to,set this resource to -1.


Pt CB TTY DEVSIZE



A list of PtCallback t structures that define the callbacks invokedwhen a resize event is received from the device (and before theterminal widget is resized according to the new size).




reason Pt CB TTY DEVSIZE

event NULL

cbdata A pointer to a PtTerminalSizeChange t structurethat has at least following members:


Previous size of the device.PtTerminalRowCol t new size;

Current size.


� short r

� short c


Pt CB TTY OUTPUT



A list of PtCallback t structures that define the callbacks invokedwhen any output from the device is received (and before the output ispassed to the terminal widget)


reason Pt CB TTY OUTPUT

event NULL



cbdata A pointer to a PtTtyOutput t structure that has at leastfollowing members defined:

int length; The number of characters received.

const char * buffer;

A pointer to buffer containing thecharacters.


Pt CB TTY TERMINATED



A list of PtCallback t structures that define the callbacks invokedafter the child process has terminated. Each callback is passed aPtCallbackInfo t structure that contains at least the followingmembers:

reason Pt CB TTY TERMINATED

event NULL

cbdata A pointer to an int containing thePt ARG TTY EXIT STATUS resource.
























Pt ARG DIM PtWidget




continued. . .


















Pt ARG POS PtWidget



Pt ARG TERM APP PtTerminal

Pt ARG TERM COLOR MODE PtTerminal

Pt ARG TERM COLOR TABLE PtTerminal

Pt ARG TERM COLS PtTerminal

Pt ARG TERM CONSOLE PtTerminal

Pt ARG TERM CUR COL PtTerminal

continued. . .




Pt ARG TERM CUR POS PtTerminal

Pt ARG TERM CUR ROW PtTerminal

Pt ARG TERM CURSOR FLAGS PtTerminal

Pt ARG TERM DRAW MODES PtTerminal

Pt ARG TERM FONT PtTerminal

Pt ARG TERM FONT LIST PtTerminal

Pt ARG TERM FONT INDEX PtTerminal

Pt ARG TERM FONT SIZE PtTerminal

Pt ARG TERM MARGINS PtTerminal

Pt ARG TERM MAXCOLS PtTerminal

Pt ARG TERM MAXROWS PtTerminal

Pt ARG TERM MAXSIZE PtTerminal

Pt ARG TERM MINCOLS PtTerminal

Pt ARG TERM MINROWS PtTerminal

Pt ARG TERM MINSIZE PtTerminal

Pt ARG TERM OPTIONS PtTerminal

Pt ARG TERM OPTMASK PtTerminal

Pt ARG TERM ANSI PROTOCOL PtTerminal

Pt ARG TERM RESIZE FL PtTerminal

Pt ARG TERM RESIZE FUN PtTerminal

Pt ARG TERM RESIZE STR PtTerminal

Pt ARG TERM ROWS PtTerminal

Pt ARG TERM SCRLBK COUNT PtTerminal

continued. . .




Pt ARG TERM SCRLBK LIMIT PtTerminal

Pt ARG TERM SCRLBK POS PtTerminal

Pt ARG TERM SCROLL PtTerminal

Pt ARG TERM SELECTION PtTerminal

Pt ARG TERM SIZE PtTerminal

Pt ARG TERM VISUAL BELL PtTerminal







Pt CB ARM PtBasic






Pt CB DND PtWidget





continued. . .





Pt CB MENU PtBasic


Pt CB RAW PtWidget




Pt CB TERM APP PtTerminal

Pt CB TERM FONT PtTerminal

Pt CB TERM INPUT PtTerminal

Pt CB TERM OPTIONS PtTerminal

Pt CB TERM RESIZE PtTerminal

Pt CB TERM RESIZED PtTerminal

Pt CB TERM SCRLBK PtTerminal



The threshold value for graphics bandwidth, as reported byPhQuerySystemInfo(), that defines a slow connection. For moreinformation, see Pt ARG TERM CURSOR FLAGS and “Scrollingoptimization” in the description of PtTerminal.

Convenience functions:The PtTty widget defines the following convenience function:

PtTtyShell() Return the user’s default shell.


2004, QNX Software Systems Ltd. PtTtyShell()Return the user’s default shell

Synopsis:const char PtTtyShell( void );

Description:The PtTtyShell() function returns either the value of the SHELLenvironment variable or, if SHELL is undefined, the user’s defaultshell defined in the passwd file.

This string is used by the PtTty widget to start the user’s shell (seePt ARG TTY CMD and Pt ARG TTY ARGV resources to PtTty).


Safety


Signal handler No

Thread No


PtWebClient 2004, QNX Software Systems Ltd.

Widget for displaying web pages

Class hierarchy:PtWidget → PtBasic → PtContainer → PtClient →PtWebClient

PhAB icon:

Public header:<photon/PtWebClient.h>

Description:You can use the PtWebClient widget to start, interact, and control aweb server, such as Voyager or NetFront. PtWebClient alsoprovides a user-defined area within your application for the server toformat and display web pages. Your application controls the server bysetting widget resources. The server communicates status informationand user interaction back to the application using the widgetcallbacks.

PtWebClient transparently supports the version of HTML that theserver supports. For more information about the Voyager andNetFront web servers, see vserver and netfront in the QNXNeutrino Utilities Reference.

Starting the server

Start the server initially by setting the Pt ARG WEB SERVERresource.

Typically, the PtWebClient widget is in a PhAB application, and itsPt ARG WEB SERVER resource is NULL.

You can set the Pt ARG WEB SERVER resource to either:

� the name of a web server profile

� a web server command and command line options


2004, QNX Software Systems Ltd. PtWebClient

If you set this resource to a profile name (for example, online), thewidget searches the web server profile files for a match. If a match isfound, the widget starts the web server and client name found in theprofile; the Pt ARG CLIENT NAME is ignored (since it is already inthe profile). If the profile is not found, the widget assumes theresource is the command, including path if required, for the webserver executable.

If you start the profile name with the @ character, there is no profilelookup. Instead, the web client widget discards the @, and uses theremaining string as the command line (including path and options) forstarting the server.

To start the current online web server, do the following in theprerealize setup function for the module containing the widget:

PtSetArg( &args[0], Pt ARG WEB SERVER, "online", 0 );PtSetResources( ABW web pane, 1, args );

To use the default off-line web server profile, do the following in theprerealize setup function for the module containing the widget:

PtSetArg( &args[0], Pt ARG WEB SERVER, "offline", 0 );PtSetResources( ABW web pane, 1, args );

Once the server is started, you can check that it was successful bygetting the value of Pt ARG WEB STARTUP ERRNO. For example:

int *error;

PtSetArg( &args[0], Pt ARG WEB STARTUP ERRNO, &error, 0 );PtGetResources( ABW web pane, 1, args );

if ( *error != EOK ) {/* error occurred - use errno to display message */

}

After successfully starting the server, you can access URLs by settingthe Pt ARG WEB GET URL resources.



Migrating from libPtWeb.so.2 to libPtWeb.so.3

If your browser application has been designed to work with thePtWebClient widget from libPtWeb.so.2, when migrating to thenew PtWebClient API in libPtWeb.so.3, you should be aware ofa couple of changes that are required in your code.

1 All the macros starting with WWW are renamed to start withPt WEB now. You should change your code accordingly. Forexample: WWW RESPONSE OK is nowPt WEB RESPONSE OK. The compiler will probably make youaware of this if you try to compile code that uses the old macronames.

2 In all the structures that are passed either from the server toPtWebClient or from PtWebClient to the server, membersthat were char member[] are now pointers to char, char*member.

This change is particularly important in the structures that arefilled in by the user. Therefore the following structures havebeen renamed to make the compiler aware:

� PtWebClientAuthenticationData t — renamed toPtWebClient2AuthenticationData t

� PtWebClientHelperData t — renamed toPtWebClient2HelperData t

� PtWebClientUnknownData t — renamed toPtWebClient2UnknownData t

� PtWebClientData t — renamed toPtWebClient2Data t

� PtWebCommand t — renamed toPtWebClient2Command t

� PtWebClientSSLResponse t — renamed toPtWebClient2SSLResponse t

For example, PtWebClientAuthenticationData t used tobe defined as:



typedef struct {short response;short type;char userid[255];char password[255];char url[MAX URL LENGTH];

} PtWebClientAuthenticationData t;

It is now defined as:typedef struct {short response;short type;char *userid;char *password;char *url;

} PtWebClient2AuthenticationData t;

The userid, password and url members should be allocated bythe user, and it is user’s responsibility to free them.

New resources:


Pt ARG WEB ACTIVATE LINK int Scalar 0 (write-only)

Pt ARG WEB AUTHENTICATE See below Pointer NULL(write-only)

Pt ARG WEB BUILD DATE char * String NULL(read-only)

Pt ARG WEB COMMAND PtWebCommand t *Pointer NULL(write-only)

Pt ARG WEB DATA PtWebClientData t *Pointer NULL(write-only)

continued. . .




Pt ARG WEB DOWNLOAD char *, char*

String N/A(write-only)

Pt ARG WEB ENCODING char * String NULL

Pt ARG WEB GET CERTIFICATES See below Pointer NULL(read-only)

Pt ARG WEB GET CONTEXT char * String NULL(read-only)

Pt ARG WEB GET HISTORY See below Pointer None(read-only)

Pt ARG WEB GET URL char * String N/A(write-only)

Pt ARG WEB HELPER See below Pointer NULL(write-only)

Pt ARG WEB H ERRNO int Scalar 0

Pt ARG WEB IMPORT CERTIFICATE See below pointer N/A(write-only)

Pt ARG WEB NAVIGATE FRAME int Scalar 0

Pt ARG WEB NAVIGATE LINK int Scalar 0

Pt ARG WEB NAVIGATE PAGE int Scalar 0

Pt ARG WEB OPTION char *, char* String NULL

Pt ARG WEB PRINT PpPrintContext t *,

int

Pointer NULL(write-only)

Pt ARG WEB RELOAD N/A N/A N/A(write-only)

Pt ARG WEB SERVER char * String NULL

Pt ARG WEB SERVER PID pid t Scalar read-only

continued. . .




Pt ARG WEB SSL RESPONSE See below Pointer NULL

Pt ARG WEB STARTUP ERRNO int Scalar 0

Pt ARG WEB STOP N/A N/A N/A(write-only)

Pt ARG WEB UNKNOWN RESP See below Pointer NULL(write-only)

Pt ARG WEB VERSION char * String NULL(read-only)

Pt CB WEB AUTHENTICATE PtCallback t*

Link NULL

Pt CB WEB CLOSE WINDOW PtCallback t*

Link NULL

Pt CB WEB COMPLETE PtCallback t*

Link NULL

Pt CB WEB CONTEXT PtCallback t*

Link NULL

Pt CB WEB DATA REQ PtCallback t*

Link NULL

Pt CB WEB DOWNLOAD PtCallback t*

Link NULL

Pt CB WEB ERROR PtCallback t*

Link NULL

Pt CB WEB IMPORT CERTIFICATE PtCallback t*

Link NULL

Pt CB WEB METADATA PtCallback t*

Link NULL

Pt CB WEB NEED SCROLL PtCallback t*

Link NULL

continued. . .




Pt CB WEB NEW WINDOW PtCallback t*

Link NULL

Pt CB WEB PAGE INFO PtCallback t*

Link NULL

Pt CB WEB SSL CERTINFO PtCallback t*

Link NULL

Pt CB WEB SSL CERTNONTRUSTED PtCallback t*

Link NULL

Pt CB WEB SSL CLIENT CERT SELECT PtCallback t*

Link NULL

Pt CB WEB SSL ERROR PtCallback t*

Link NULL

Pt CB WEB START PtCallback t*

Link NULL

Pt CB WEB STATUS PtCallback t*

Link NULL

Pt CB WEB UNKNOWN PtCallback t*

Link NULL

Pt CB WEB URL PtCallback t*

Link NULL

Pt ARG WEB ACTIVATE LINK (key mode only)


int Scalar 0 (write-only)

This resource activates and deactivates the current link.

� If the current link is an image map and it’s activated, a cursorappears at the top-left corner of the image and thePt ARG WEB NAVIGATE LINK resource moves the cursor in the



appropriate direction. If you then setPt ARG WEB ACTIVATE LINK to 0, the link in the imagemap isactivated; if you set this resource to 1, the image map selection iscanceled.

� If a form type of TEXTAREA or TEXT is active, setting thisresource to 0 gives focus, and a value of 1 removes focus.

Pt ARG WEB AUTHENTICATE


PtWebClientAuthenticationData t * Pointer NULL(write-only)

Set this resource to give authentication information to the server whenthe Pt CB WEB AUTHENTICATE callbacks have been invoked. Thedata structure used is as follows:

typedef struct {short response;short type;char *userid;char *password;char *url;

} PtWebClientAuthenticationData t;


response The type of response:

� Pt WEB RESPONSE OK — the information is valid.

� Pt WEB RESPONSE CANCEL — cancel theauthentication request.

type The type of authentication:

� Pt WEB BASIC AUTHENTICATION

� Pt WEB DIGEST AUTHENTICATION



� Pt WEB PROXY AUTHENTICATION

userid A pointer to the user’s login string.

password A pointer to the user’s password string.

url A pointer to the URL of the request that invoked thecallback.

Pt ARG WEB BUILD DATE (read only)


char * String NULL (read-only)

The Build date of the connected web server.

Pt ARG WEB COMMAND (write only)


PtWebCommand t * Pointer NULL

Tell the server to perform a specific command. The command isspecified in the len argument to PtSetArg(). If a pointer to thePtWebCommand t data structure is required with the command, passit as the value argument to PtSetArg().

The PtWebCommand t data structure is as follows:

typedef struct {union {

struct {char *filename;

} SaveasInfo;struct {

char *String;unsigned long flags;

} FindInfo;char *scroll to;int reset type;int num purge;

};} PtWebCommand t;



The commands are:

Pt WEB COMMAND FIND

Find and highlight a word in the current document. The part ofthe PtWebCommand t data structure used is:

struct {char *String;unsigned long flags;

} FindInfo;

where:

� String — a pointer to the word to find in the document.

� flags — possible values:

- Pt WEB FIND START AT TOP — start the search at thetop of the document.

- Pt WEB FIND MATCH CASE — match the character casein the word.

- Pt WEB FIND GO BACKWARDS — search backward.- Pt WEB FIND MATCH WHOLE WORDS — match whole

words.

Pt WEB COMMAND LOADMISSING

Load any missing images.

Pt WEB COMMAND SAVEAS

Save the current document to disk. The part of thePtWebCommand t data structure used is:

struct {char *filename;

} SaveasInfo;

where filename is a pointer to the name of the file in which tosave the document.

Pt WEB COMMAND RESET OPT

Cause any changed options that may change the current visiblepage to take effect.



Pt WEB COMMAND PURGE CACHE

Purge the in-memory image and page cache.

Pt WEB COMMAND LOADMISSING CONTEXT

Load a missing image whose context is valid (the context isvalid after a Pt CB WEB CONTEXT callback).

Pt ARG WEB DATA (write only)


PtWebClientData t * Pointer NULL

Voyager server only.

This resource is set in response to a Pt CB WEB DATA REQcallback. It provides the header and data of the client protocol datastream to the browser.

The data structure used is as follows:

typedef struct {int type;char *url;int length;char *data;

} PtWebClientData t;

The members are:

type Possible values:

� Pt WEB DATA HEADER — the data is the header of therequest.

� Pt WEB DATA BODY — the data is the body of therequest.

� Pt WEB DATA CLOSE — this flag closes (aborts) therequest.

url A pointer to the URL of this client data stream.



length The number of bytes (no more than what was asked for inthe Pt CB WEB DATA REQ callback).

data A pointer to the data.

Here’s an example of using the client protocol:

int web data( PtWidget t *widget, ApInfo t *apinfo,PtCallbackInfo t *cbinfo )

{PtArg t args[1];PtWebClientData t webdata;PtWebDataReqCallback t *web data req = cbinfo->cbdata;const char *html =

"<html><body bgcolor=\"#ffffff\"><p>\<center><table border=1 bgcolor=\"#f8f7d9\"><tr>\<td>This is a simple test of the client protocol</td>\<td><font size=4>Voyager Client: Version 2.01\<br>Built on: %s<br><hr>\<font size=4>Voyager Server: %s<br>Built on: %s\</font></center></td></tr></table></center><p>\</body></html>\n";

char about[512];static int about sent;

/* eliminate ’unreferenced’ warnings */apinfo = apinfo;

if ( !strcmp( web data req->url, "client:about" ) ) {if( cbinfo->reason subtype == Pt WEB DATA HEADER ) {

const char *data = "Content-Type: text/html\n";webdata.type = Pt WEB DATA HEADER;webdata.length = strlen(data);strcpy( webdata.url, web data req->url );PtSetArg( &args[0], Pt ARG WEB DATA, data,

&webdata );PtSetResources( widget, 1, args );

} else if( cbinfo->reason subtype == Pt WEB DATA BODY ) {/** Since no content length was given, you need* to signal EOF with a zero length data packet*/

if ( about sent ) {webdata.type = Pt WEB DATA BODY;strcpy( webdata.url, web data req->url );webdata.length = 0;PtSetArg( &args[0], Pt ARG WEB DATA, "",




about sent = 0;} else {

char *version, *build date;

PtSetArg( &args[0], Pt ARG WEB VERSION,&version, 0 );

PtSetArg( &args[1], Pt ARG WEB BUILD DATE,&build date, 0 );

PtGetResources(widget, 2, args );sprintf( about, html, DATE , version,

build date );webdata.type = Pt WEB DATA BODY;strcpy( webdata.url, web data req->url );webdata.length = strlen(about);PtSetArg( &args[0], Pt ARG WEB DATA, about,

&webdata );PtSetResources( widget, 1, args );about sent = 1;

}}

} else {if( cbinfo->reason subtype == Pt WEB DATA HEADER ) {

/** If I give a content length then I don’t need* provide a zero byte data packet*/

const char *data ="Content-Type: text/plain\nContent-Length: 20\n";

webdata.type = Pt WEB DATA HEADER;webdata.length = strlen(data);strcpy( webdata.url, web data req->url );PtSetArg( &args[0], Pt ARG WEB DATA, data,


} else if( cbinfo->reason subtype == Pt WEB DATA BODY ) {const char *data = "Unknown client type\n";webdata.type = Pt WEB DATA BODY;strcpy( webdata.url, web data req->url );webdata.length = strlen( data );PtSetArg( &args[0], Pt ARG WEB DATA, data,&webdata );PtSetResources( widget, 1, args );

}}return( Pt CONTINUE );

}



Pt ARG WEB DOWNLOAD (write only)


char *, char * String N/A

This resource lets you download a file without having to wait for thePt CB WEB UNKNOWN callback to provide a file. The valueargument of PtSetArg() should contain the URL of the file todownload and the len argument should contain the filename to save itas.

Pt ARG WEB DOWNLOAD does GET requests only.�

Pt ARG WEB ENCODING


char * String NULL

The current document encoding. See PxTranslateSet() in the PhotonLibrary Reference.

For the netfront server, you can set this resource to Autodetect

Encoding (the default setting). When this value is set, the netfrontserver will try to auto detect the encoding.

Pt ARG WEB GET CERTIFICATES (read only)


PtWebSSLClientCertificates t * Pointer NULL

This resource gets information about current client certificates.


typedef struct {int ncert;char *url;



int reserved1;int reserved2;PtWebSSLCertInfo t info[1];} PtWebSSLClientCertificates t;

The members are:

ncert The number of certificates.

url Not used.

info A PtWebSSLCertInfo t structure which containsinformation about the certificate. See thePt CB WEB SSL CERTNONTRUSTED resource for adescription of the PtWebSSLCertInfo t structure.

Pt ARG WEB GET CONTEXT (read only)


char * String NULL

This resource gets the context information, which is valid after aPt CB WEB CONTEXT callback. To get context information, specifythe type in the len argument of PtSetArg().

The possible context types are:

Pt WEB CONTEXT ANCHOR

The URL of a link.

Pt WEB CONTEXT OBJECT

The URL of a image or embedded object.

Pt WEB CONTEXT BKGD

The URL of a background image.



Pt ARG WEB GET HISTORY (read only)


PtWebClientHistory t * Pointer None

Use this resource to get the site history list from the browser. This is alist of titles and URLs of all the sites visited in the timeframespecified in the History Expire option (default 4 days).

The data structures used with this resource are:

typedef struct {short num;short offset;

} PtWebClientHistory t;

where:

� num — the number of history entries to return

� offset — the offset into the history site list at which to begin.

and:

typedef struct {char *title;char *url;time t lastvisited;

} PtWebClientHistoryData t;

Here’s an example of how to get the history:

PtArg t args[1];PtWebClientHistoryData t list[HISTORY REQUEST SIZE];PtWebClientHistory t list info;char *description[HI MAX LIST SIZE];int i, item count = 0, loop = TRUE;

list info.num = HISTORY REQUEST SIZE;list info.offset = 0;



/* retrieve history list from voyager server */while (loop) {

/* get the next 10 history entries */PtSetArg(&args[0], Pt ARG WEB GET HISTORY,

&list, &list info);PtGetResources( w, 1, args);

for (i=0; i < 10; i++, item count++) {if (list[i].url[0] == NULL ||

list[i].url[0] == 0 ||item count >= HI MAX LIST SIZE) {loop = FALSE;break;

}if ( description[item count] =

malloc(strlen(list[i].url) +strlen(list[i].title) + 4) )

sprintf(description[item count], "%s\t%s\t",list[i].title, list[i].url);

}list info.offset += HISTORY REQUEST SIZE;

}

Pt ARG WEB GET URL (write only)


char * String N/A

The URL that you want the browser to display or save. Set the lenargument of PtSetArg() to one of:

Pt WEB ACTION DISPLAY

Display the URL in the browser.

Pt WEB ACTION SAVEAS

Download and save the URL.

You can OR the following flags into the action to control the cachingof the page and the recording of history:



Pt WEB NO MEMORY CACHE

Don’t cache the page in memory.

Pt WEB NO DISK CACHE

Don’t cache the page on disk.

Pt WEB NO SITE HISTORY

Don’t record the site in the site history.

Pt WEB NO PAGE HISTORY

Don’t record the site in the page history.

� When saving a URL, the browser responds with aPt CB WEB UNKNOWN to obtain a filename to save the file onceit has determined that it can get the URL or seePt ARG WEB DOWNLOAD.

� The maximum length of a URL string is 1024 bytes orMAX URL LENGTH.

�

Pt ARG WEB HELPER (write only)


PtWebClientHelperData t * Pointer NULL

Setting this resource tells the server which external helperapplications are available. The data structure used is as follows:

typedef struct {short action;char *mimetype;char *suffixes;char *encoding;char *helperapp;

} PtWebClientHelperData t;

The members of this structure are:



action The action to take:

� Pt WEB ACTION ADD — add the external helper.

� Pt WEB ACTION DELETE — delete the externalhelper (if added previously).

mimetype A pointer to the mimetype of the data that the helperapplication can handle.

suffixes A pointer to the file suffixes of the helper applicationdata files (e.g. “mpeg mpg”).

encoding Currently not used.

helperapp A pointer to the complete filename to the helperapplication; use %s to indicate where the data fileshould appear on the command line.

If you wish to control the running of the helper application yourself,add the helper with no help application (i.e. helperapp=""). APt CB WEB UNKNOWN callback is called if an HTML pagecontains an <embed> tag to a file with the mimetype or suffixprovided. (Normally these files are ignored.)

�

Pt ARG WEB H ERRNO


int Scalar 0

The value of h errno after a DNS failure. The possible values are:

HOST NOT FOUND

No such host is known.

NO DATA The name is known to the name server, but has no IPaddress associated with it — this isn’t a temporaryerror. Another type of request to the name server



using this domain name results in an answer (e.g. amail-forwarder may be registered for this domain).

NO RECOVERY

Some unexpected server failure was encountered.This is a nonrecoverable error.

TRY AGAIN This is usually a temporary error and means that thelocal server didn’t receive a response from anauthoritative server. A retry at some later time maysucceed.

Pt ARG WEB IMPORT CERTIFICATE


PtWebImportCertificate t Pointer 0

Netfront server only.

Set this resource when you want a client certificate to be imported.


typedef struct {int type;char *path;} PtWebImportCertificate t;


type The type of certificate to be imported. It can be one of:

� Pt WEB CERT TYPE DER — x509 certificate

� Pt WEB CERT TYPE PKCS7

� Pt WEB CERT TYPE PKCS12

path The full path to the file that contains the certificate data.



After you set this resource, the netfront server starts importing thecertificate. If the certificate is password protected, netfront issues aPt CB WEB AUTHENTICATE withtype=Pt WEB IMPORT CERT AUTHENTICATION. (In this caseaction, realm, and url are not used.) The client responds by setting thepassword member of the Pt ARG WEB AUTHENTICATE resource.The netfront server then continues importing the certificate. If anerror or a warning needs to be displayed, thePt CB WEB SSL ERROR andPt CB WEB SSL CERTNONTRUSTED are invoked with reason setto Pt WEB SSL IMPORT CERT.

At the end of the import process aPt CB WEB IMPORT CERTIFICATE is invoked indicating whetherthe process was successful or not.

Pt ARG WEB NAVIGATE FRAME


int Scalar 0


Controls focus navigation of FRAMES pages when the browser is inkey mode. Set the value argument of PtSetArg() to one of:

Pt WEB DIRECTION UP

Focus the frame above the current one.

Pt WEB DIRECTION DOWN

Focus the frame below the current one.

Pt WEB DIRECTION LEFT

Focus the frame to the left of the current one.

Pt WEB DIRECTION RIGHT

Focus the frame to the right of the current one.



Pt WEB DIRECTION FWD

Focus the next frame.

Pt WEB DIRECTION BACK

Focus the previous frame.

The next and previous directions are defined by the order of the<FRAME> tag in each <FRAMESET> tag.

�

Pt ARG WEB NAVIGATE LINK


int Scalar 0

This resource controls focus navigation of links on the current pagewhen the browser is in key mode. Set the value argument toPtSetArg() to one of the following:

Pt WEB DIRECTION UP

Focus the link above the current one.


Focus the link below the current one.


Focus the link to the left of the current one.


Focus the link to the right of the current one.


Focus the next link.


Focus the previous link.



When an IMAGE-MAP type link has been activated, this resource isused to navigate the “ImageMap Cursor” over the image map in thespecified direction. The len argument is then used to specify thenumber of pixels to move the cursor.

When a FORM type object has been activated (given focus), thesecommands are turned into cursor-key directions and given to the formobject.

The next and previous directions are defined by the order of the linksin the HTML page.

�

Pt ARG WEB NAVIGATE PAGE


int Scalar 0

This resource controls the scrolling of the displayed page and theability to navigate back and forward through pages in the pagehistory. Set the value argument to a direction and the len argument tothe amount to scroll, in percentage of the visible page (e.g. 100 ==scroll one full page). The direction must be one of:

Pt WEB DIRECTION UP

Scroll the page up.


Scroll the page down.


Scroll the page to the left.


Scroll the page to the right.


Go to the previous page in the page history.




Go to the next page in the page history.

The len argument has no effect when using Pt WEB DIRECTION FWDor Pt WEB DIRECTION BACK.

�

Getting the value of this resource indicates whether or not you canperform a given operation. Currently, only Pt WEB DIRECTION FWDand Pt WEB DIRECTION BACK are supported.

The format of the data returned is 1 << Pt WEB DIRECTION xx.For example:

int *nav dir;

PtSetArg( &arg, Pt ARG WEB NAVIGATE PAGE, &nav dir, 0 );PtGetResources( webclient, 1, args );

if ( *nav dir & (1 << Pt WEB DIRECTION FWD ) ) {

/* I can go forward in the page history */

} else if ( *nav dir & (1 << Pt WEB DIRECTION BACK ) ) {

/* I can go backward in the page history */

}

Pt ARG WEB OPTION


char *, char* String NULL

Set this resource to set options on the web server. This resource takestwo parameters:

� value — the setting of the options.

� len — the string that describes the option.



For example, to change the scrollbar size:

PtArg t args[1];

PtSetArg( &args[0], Pt ARG WEB OPTION, "10","iScrollbarSize" );

PtSetResources( webclient wgt, 1, args );

You can read the options from the server by getting the value of thisresource. The following piece of code increases the font size by onelevel:

char *size;

PtSetArg( &args[0], Pt ARG WEB OPTION, &size,"iUserTextSize" );

PtGetResources( ABW web pane, 1, args );

if ( size ) {fontsize = atoi( size );if ( fontsize < 3 ) {

sprintf( buf, "%d", fontsize + 1 );PtSetArg( &args[0], Pt ARG WEB OPTION,

buf, "iUserTextSize" );PtSetResources( ABW web pane, 1, args );

}}

If you’re changing options that have visual effects after thePtWebClient widget is realized, then you must issue a resetcommand in order for the changes to be seen. The command is asfollows:

PtSetArg( &args[0], Pt ARG WEB COMMAND, 0,Pt WEB COMMAND RESET OPT );

PtSetResources( ABW web pane, 1, args );

�

The following sections list the options and their defaults:

� HTML Options



� HTTP cookie options

� Authentication options

� FTP options

� Gopher options

� HTTP options

� File options

� Image options

� Print options

� SOCKS options

� TCP/IP options

� Disk Cache options

� Miscellaneous options

� NetFront-specfic options

The HTML options are:HTMLOptions

A:active color

The color of a link when you click on it with themouse.

Default: "#ff0000"

A:link color The normal color of a link.

Default: "#0000ff"

A:visited color

The color of a link after it’s been visited.

Default: "#008080"



bAutoLoadImages


If "TRUE", images are loaded as they’reencountered in the page. If "FALSE", images areloaded only if thePt WEB COMMAND LOADMISSING command isissued.

Default: "TRUE"

bDisableHighlight


Don’t highlight text while dragging over it.

Default: "FALSE"

bDisableImagePlaceHolders


Disable drawing on the missing/error imageplaceholders.

Default: "FALSE"

bIgnoreDocumentAttributes


If "TRUE", color attributes override what’sspecified in the page.

Default: "FALSE"

bkey mode Voyager server only.

If set to "TRUE", key navigation is enabled.

Default: "FALSE"

BODY background

The color of the page background.

Default: "#ffffff"



BODY color The color of text inside the body on the HTMLpage.

Default: "#000000"

BODY font-family

The font family name of the text in the bodyportion of the page.

BODY margin-right

The margin, in pixels, between right side of displayarea and the first visible element in the page (Note:page tags may override this).

Default: "10"

BODY margin-top

The margin, in pixels, between top of display areaand the first visible element in the page (Note: pagetags may override this).

Default: "20"

bot border color


The bottom color of borders in frame pages.

Default: "#606060"

bot focus color


The bottom color of the focus box in key mode.

Default: "#7f7f00"

bUnderlineLinks

If "TRUE", the link on a page is underlined.

Default: "TRUE"

bview source

Allow page source to be viewed (setting this optionto "FALSE" saves memory).



Default: "TRUE"

disable exception dlg

Don’t allow the Javascript exception dialog to bedisplayed.

Default: "FALSE"

disable new windows

Don’t allow Javascript windows to open.

Default: "FALSE"

enable link arm


Activate links on arm (useful for touch screens).

Default: "FALSE"

enable print bgcolor


Print background colors.

Default: "FALSE"

form font Voyager server only.

The font used for lists, comboboxes, submit buttonsand reset buttons.

frame spacing


The spacing between frames, in pixels.

Default: "2"

H* font-family


The font family name of the text used in headingson the page.



iReformatHandling


Reformat handling

Default: "2"

Possible values:

� "0" — no progressive formatting or display.Subviews can be progressively requested, butnothing formats or displays until the documentreaches a totally stable state. This mode iscommonly used for kiosk browsers and is alsouseful for devices.

� "1" — reformat once after all subviews areloaded. Text is displayed immediately as itcomes in, and subviews that have size hints aredisplayed as they arrive without reformatting.Reformatting isn’t done until the entiredocument is complete. However, any otherreformatting, such as resizing the window,brings those subviews with size hints onto thescreen.

� "2" — the GUI is reformatted after eachsubview is loaded. Any subviews with size hintsare displayed without reformatting. However,subviews without hints trigger a partial reformatas soon as their size is known so they can bedisplayed immediately.

iScrollbarSize

The scrollbar width, in pixels.

Default: "16"

iUserTextSize

The base logical font size of text size used in thepage.

Defaults:



voyager — "2"

netfront — "100"

Possible values:voyager uses values between "0" and "4" forsmall to large text, with "2" being average size.netfront uses values larger than "5", whichrepresent the percent of original size of the text,with "100" being the original size.

java disable Voyager server only.

Disable Java applet tag parsing (forced "TRUE" ifvgr javanpl.so isn’t found).

Default: "FALSE"

mono form font


The font used for editable form fields.

PRE font-family


The font family name used for preformatted text (this should be a fixed-width font).

top border color


The top color of borders in frame pages.

Default: "#ffffff"

top focus color


The top color of the focus box in key mode.

Default: "#ffff00"

underline width




The line thickness, in pixels, of the underline usedon links.

Default: "1"

The HTTP cookie options are:HTTPcookie

optionscookiejar name

The name of file to store cookie information in.

Default: "cookie.jar"

cookiejar path

The directory used to write the cookie file in.

Default: "$(HOME)"

cookiejar save always


Always keep the cookie-jar file on disk up-to-date.

Default: "FALSE"

cookiejar size

The maximum size, in bytes, that the cookie-jar file is allowedto grow. A value of "-1" means no limit.

Default: "-1"

The authentication options are:Authentication

optionsmax password guesses


The maximum number of guesses allowed when performingauthentication.

Default: "3"



The FTP options are:FTP options

email address


The email address used for the password on anonymous loginsof FTP server.

Default: "80"

ftp proxy host


The host name or IP address of proxy server for FTP requests.

Default: none

ftp proxy port


The port number on FTP proxy server to use.

Default: "80"

proxy overrides

A comma-separated list of host names or IP addresses to bypassthe FTP proxy server when accessed.

Default: "80"

The Gopher options are:Gopheroptions

gopher proxy host


The host name or IP address of the proxy server for gopherrequests.

Default: none

gopher proxy port


The port number on the gopher proxy server to use.

Default: "80"



proxy overrides

A comma-separated list of host names or IP addresses to bypassthe gopher proxy server when accessed

Default: none

The HTTP options are:HTTPoptions

http proxy host

The host name or IP address of proxy server for HTTP requests.

Default: none

http proxy port

The port number on the HTTP proxy server to use.

Default: "80"

proxy overrides

A comma-separated list of host names or IP addresses to bypassthe HTTP proxy server when accessed.

Default: none

The file options are:File options

file display dir


Display directory listings as HTML pages. For example,file:/ produces an HTML page with the content of the rootdirectory.

Default: "TRUE"

file strict access


Enable strict file access (file: URLs must have thePt WEB STRICT FILE ACCESS flag set when requested viaPt ARG WEB GET URL or Pt ARG WEB DOWNLOAD).

Default: "FALSE"



The image options are:Imageoptions

bProgressiveImageDisplay

Display images progressively as they’re being loaded.

Default: "TRUE"

concurrent decodes

The number of concurrent JPEG decodings that should be done.This option can save significant memory when decoding JPEGSto 256 colors.

Default: "4"

quantize jpegs


Always convert JPEGS to a 256-color palette. (The default isbased on current graphics mode; if running on a high-color ordirect-color graphics driver, JPEGS are converted to the defaultcolor mode, usually 24-bit. If a palette-based graphics driver isrunning, the JPEGS are always converted to 256 colors usingthe current hardware palette, and setting this option has noeffect.)

Default: "FALSE"

The print options are:Printoptions

Print Left Footer String

The left footer used when printing.

Default: "Page &"

Print Left Header String

The left header string used when printing.

Default: "&w"

Print Header Font

The font used in the header and footer.

Default: "helv"



Print Header Font Size

The font size used in the header and footer.

Default: "8"

Print Right Footer String

The right footer used when printing.

Default: "&d &t"

Print Right Header String

The right header string used when printing.

Default: "&u"

You can use these special characters in the header and footer strings:

"&w" Page title

"&u" URL

"&p" Page number

"&d" Date — American style (“mmm dd yyyy”)

"&D" Date — European style (“dd mmm yyyy”)

"&t" Time — 12-hour format (“HH:MM am”)

"&T" Time — 24-hour format (“HH:MM”)

"&&" The ampersand ("&") character

These options are for the Voyager server only. The SOCKS optionsSOCKSoptions are:

socks app The application name to pass to the SOCKS server.

Default: none

socks port The port number on the SOCKS server to use.

Default: none



socks server The host name or IP address of the SOCKS serverfor any requests.

Default: none

socks user The userid to pass to the SOCKS server.

Default: none

The TCP/IP options are:TCP/IPoptions

file buckets


Fill network buffers before processing them.

Default: "TRUE"

max connections

Default: "4"

socket timeout


Default: "2400"

The disk-cache options are:Disk-cacheoptions

clear main cache on exit

Clear the on-disk cache when the browser exits.

Default: "FALSE"

dcache verify policy

0 means never verify if document has changed; 1 means verifyif document has changed once per session; 2 means alwaysverify if document has changed.

Default: "0"

Note: Verifying is done by using the “If-Modified-Since”request-header.



enable disk cache

Enable on-disk caching.

Default: "TRUE"

keep index file updated


Keep the disk cache index file updated on disk when it changesinstead of once on exiting.

Default: "FALSE"

main cache dir

The directory used to store cache files.

Default: "/tmp"

main cache kb size

The maximum size of the on-disk cache.

Default: "5000"

main index file


The name of the cache index file.

Default: "main.ndx"

The miscellaneous options are:Miscellaneous

optionsPage History Length

The maximum number of pages allowed in the page history(back/forward history).

Default: "50"

Use Anti Alias

Use anti-aliased fonts.

Default: "TRUE"



Use Double Buffer

Enable double-buffered rendering.

Default: "TRUE"

Visitation Horizon

The number of days after which to expire the visited linksdisplay (i.e. VLINK -> LINK).

Default: "4"

Voyager server only miscellaneous options:

Accept Charset Header

The value string to pass with the Accept-Charset header (seethe HTTP specification).

Default: "TRUE"

Accept Language Header

The value string to pass with the Accept-Language header(see the HTTP specification).

Default: "TRUE"

Global History File

The full pathname of the file to store the site history list in.(Note: this page is an HTML-formatted page.)

Default: none

History Expire

The number of days used to expire entries in the site history list.(Note: set to "0" to remove the history when the client is shutdown and restarted.)

Default: "4"

IBeam Cursor

See /usr/include/photon/PhCursor.h

Default: "e90e" (the insert cursor)



Image Cache Size KB

The size of image cache, in kilobytes.

Default: "1024"

ImageMap Cursor


Default: "e90c" (the finger cursor)

ImageMap Cursor NoLink


Default: "e900" (the pointer cursor)

Link Cursor


Default: "e90c" (the finger cursor)

LinkWait Cursor


Default: "e918" (the point wait cursor)

Normal Cursor


Default: "e900" (the pointer cursor)

NormalWait Cursor


Default: "e918" (the point wait cursor)

Page Cache Size

The number of pages kept in memory.

Default: "4"

Safe Memory Free

The minimum amount of memory, in kilobytes, to leave for thesystem. If the system has less than this amount available,Voyager’s requests to allocate memory fail.



Default: "0"

Show Server Errors

Display the HTML-formatted error pages received from theremote HTTP servers. Otherwise generate aPt CB WEB ERROR callback.

Default: "FALSE"

Site History Length

The maximum number of sites allowed in the site history (thelist is obtained from server).

Default: "500"

Use Explicit Accept Headers

Send an explicit Accept: content-type header requestfield in the HTTP header; otherwise send Accept: */*.

Default: "TRUE"

Wait Cursor


Default: "e908" (the wait cursor)

These options are specific to the netfront server.NetFront-specificoptions

ServerId (Read only) The string identifier for the server.You can use this string if your client can be usedwith both the vserver and netfront servers,and you want to do specific things when connectedto a certain server. The string returned arevserver and Netfront, respectively.

iUserZoom A numeric value for the global (text and image)zoom factor, in percent. A value of "100" meansoriginal size.

fNavigatorUserAgent

The user agent string.



memory cache kb size

The amount of in-cache memory. The default 0.

fEnableWML Enables Wireless Markup Language (WML/WAP)support. The default is "FALSE".

These options are write-only:

fRunJavaScript

If "TRUE", JavaScript is enabled.

Default: "TRUE"

fScriptDisables

Validates/invalidates external script files. Possiblevalues are:

� "DISABLE SCRIPT SRC" — Invalidates the srcattribute of the <script> element. The externalscript isn’t read.

� "DISABLE SCRIPT EXECUTE" — Invalidatesscripts in newly generated Windows.

� "DISABLES NONE" — No disabling.

Default: "DISABLES NONE"

fCSSDisables

Options used to configure CSS. Possible values are:

� "DISABLE CSS DEFAULT" — Default stylesheet is invalid.

� "DISABLE CSS LINK" — External filedefinition (LINK REL) style sheet is invalid.

� "DISABLE CSS IMPORT" — Import (@import)style sheet is invalid.

� "DISABLE CSS STYLETAG" — <style> tag isinvalid.



� "DISABLE CSS STYLEATTR" — style attributeis invalid.

Set to "FLAG NONE" to clear all flags.

Default: all flags enabled.

fSSLVersion The version of SSL to use. Can be a combination ofvalues:

� "V2" — use SSL version 2

� "V3" — use SSL version 3

� "TLS" — use TLS version 1

Set to "FLAG NONE" for none.

Default: all flags enabled.

fDisplayTable

Sets whether the browser displays <table>elements described in content by table style or not.

Default: "TRUE"

fDisplayImage

Sets whether the browser displays images.

Default: "TRUE"

fAnimateImage

Sets whether the browser animates images.

Default: "TRUE"

fWaitDecodeImage

Sets whether the browser waits until an image isdisplayed to decode it.

Default: "FALSE"

fAnimationImageMaxLoops

The maximum number of animation loops forimages. No limit if set to -1.

Default: "-1"



fMaxImageDelayTime

The maximum delay time for animations, inmilliseconds. No limit if less than 0.

Default: "-1"

fMinImageDelayTime

The minimum delay time for animations, inmilliseconds. No limit if less than 0.

Default: "-1"

fMaxImageWidth

The maximum display width size of images, inpixels. Possible values are:

� greater than "0" — if the width of the image islarger than this, the image is scaled so its widthequals fMaxImageWidth.

� equal to "0" — the image is displayed at its realsize.

� less than "0" — specifies the maximum size of aviewport. If the width of an image is larger thanthat of the viewport, it is resized to the width ofthe viewport. If the image size to be displayed islarger than the specified value, the reductiondecode is attempted. If the reduction decode isimpossible, the image is resized again when it isdisplayed.

Default: "0"

fMaxImageHeight similar

The maximum display height size of image (inpixels). Possible values are:

� greater than "0" — if the height of the image islarger than this, the image is scaled so its heightequals fMaxImageHeight.



� equal to "0" — the image is displayed at its realsize.

� less than "0" — specifies the maximum size of aviewport. If the height of an image is larger thanthat of the viewport, it is resized to the height ofthe viewport. If the image size to be displayed islarger than the specified value, the reductiondecode is attempted. If the reduction decode isimpossible, the image is resized again when it isdisplayed.

Default: "0"

fMaxPixelsPerImage

The maximum image size, which is the width �height, in pixels. No limit if set to "-1".

This sets the maximum image file size that can bedisplayed. The size is determined by the width andheight recorded in the image file before the browserengine converts the size. It is not related to theattribute values specified by the image’s HTML tag.If the image size is larger than the specified value orthe image header is damaged, the browser cancelsdecoding and it displays the image data damagedicon. This prevents a memory shortage when thebrowser attempts to reserve memory for anabnormally large image.

Default: "-1"

fKeepResizedImage

Sets whether the browser retains a temporary imageor not when it scales an image up or down.

Default: "FALSE"

fMaxPixelsPerDecodedPixelMap

Sets the maximum pixel map size. Possible valuesare:



� > "0" — the maximum pixel map size whendecoding an image, in pixels.

� = "-1" — no limitation on the pixel map size.

Default: "-1"

If a large image causes a lack of memory when it’sdecoded, nothing can be displayed. Setting theappropriate value forfMaxPixelsPerDecodedPixelMap enlarges thereduced image again, and enables the browser todisplay the rough image with a resolution lower thanits original.

If the pixel map size is larger than the specifiedmaximum size, a reduction decode is attempted sothat the image is the specified size or smaller. If thedecoder is unable to reduce the image to thespecified size, the image data damaged icon isdisplayed.

fDeleteImageBound


� "INT MIN" — release all the pixelmaps thathave been already decoded.

� "-1" — keep all the pixelmaps that have beenalready decoded.

� ≥ "0" — the margin outside the visible displayarea where pixelmaps are not released. Thepixelmaps in the range of the visible display areaplus the specified margin (in pixels) are notreleased, and the browser decodes images thathave not been decoded yet. Pixelmaps outsidethe visible display area are released.

� "INT MAX" — decode all the images that havenot been decoded yet. Pixelmaps are notreleased.



Default: "-1"

fImageResizeAlgorithm

The algorithm to use to reduce images. Possiblevalues are:

� "IMAGERESIZE SIMPLE"

� "IMAGERESIZE BILINEAR"

Default: "IMAGERESIZE SIMPLE"

fPixelMapProtectInMemoryCrisis

Sets whether to protect (by releasing) the pixel mapor not when a memory error occurs, except whenprocessing images.

Default: "TRUE"

fMaxActiveDecoders

The maximum number of image decoders that canoperate at the same time (except the image decoderoperating on animation). No limit when set to -1.

Default: "-1"

fIncrementalReflow


� "TRUE" — Execute incremental re-flow. Thebrowser displays elements one by one even if thelayout information is not calculated. It lays outagain if the element is changed when the layoutinformation is decided.

� "FALSE" — Don’t execute incremental re-flow.

Default: "FALSE"

fTextareaRows

Default value for the rows attribute of the<textarea> element.

Default: "4"



fTextareaCols

Default value for the cols attribute of the<textarea> element.

Default: "20"

fBlinkOnPeriod

On time for the <blink> element, in milliseconds.

Default: "1500"

fBlinkOffPeriod

Off time for the <blink> element, in milliseconds.

Default: "800"

fBlinkLimitTime

The time limit for blinking of the <blink> element,in milliseconds. Set to "-1" for no limit.

Default: "-1"

fWapMarqueeSpeedFast

The fast speed of a <marquee> element, inmilliseconds.

Default: "60"

fWapMarqueeSpeedNormal

The normal speed of a <marquee> element, inmilliseconds

Default: "82"

fWapMarqueeSpeedSlow

The slow speed of a <marquee> element, inmilliseconds

Default: "100"

fWaitStartMarquee

Specifies whether to delay scrolling a <marquee>element until the marquee is displayed.

Default: "FALSE"



fMaxTotalContentsSize

The maximum size, in bytes, of the contentdisplayed in one page. This setting requires a restartto take effect. Set to "-1" for no limit.

Default: "-1"

fFitIntoPane

Turns Smart-Fit mode on or off. Smart-Fit fits adisplay to the window width.

Default: "FALSE"

fProgressiveOnlyDisplayed

Sets how progressive display works:

� "TRUE" — The browser formats the visiblecontent progressively, and then formats the restof the content. This shortens the time to display apage.

� "FALSE" — Formats all content progressively.

Default: "TRUE"

fDisplayCompact

Sets the behavior if content protrudes off the screen:

� "TRUE" — Ignore all margin and paddingsettings.

� "FALSE" — Don’t ignore margin and padding.

Default: "FALSE"

fTabWidth Sets the width of the tab character in the <pre>element.

Default: "8"

fEnableFrameSet

Enables the <frameset> tag.

Default: "TRUE"



fEnableIFrame

Enables the <iframe> tag.

Default: "TRUE"

fInhibitLineOverlap

Prevents lines of text from overlapping in thesituation where a small value is set for line-height ina style sheet, but there’s no small font.

Default: "FALSE"

fCanvasMarginWidth

The margin width of the drawing content area. Thisis the default value of the <body> tag.

Default: "2"

fCanvasMarginHeight

The margin height of the drawing content area. Thisis the default value of the <body> tag.

Default: "2"

fRememberFormValue

Sets whether the browser saves the content enteredin a form to its history (excluding <input> where"type"=“password”).

Default: "TRUE"

fEnableClientPull

Allows the browser to attempt a connection due to aclient pull when it is browsing off-line.

Default: "TRUE"

fNotifyInclError

Indicates whether the browser notifies you of anerror occurs when loading embedded content, suchas images.

Default: "FALSE"



fPDConfig Specifies when mouse events are generated. Can beone of these values:

� "NO MOUSE MOVE" — generate mouse over atthe time of mouse down, and generate mouse outat the time of mouse up.

� "NO POINTING DEVICE" — generate mouseover at the time of on focus, and generate mouseout at the time of on blur.

Or: "FLAG NONE" — none of the above.

Default: "FLAG NONE"

fAutoSetFocus

Specifies whether focus is set if there is a focustarget on screen:

� "TRUE" — set a focus automatically.

� "FALSE" — don’t set focus automatically.

Default: "FALSE"

fAccesskeyFocusOnlySubmitReset

Specifies the behavior of pressing the access keyspecified by the accesskey attribute of form<input> elements:

� "TRUE" — don’t execute a send/reset when theaccess key is pressed, but only move the focus.

� "FALSE" — execute a send/reset when theaccess key is pressed.

Default: "FALSE"

fEnableTabIndex

Specifies whether a tab index is enabled:

� "TRUE" — tab index is valid.

� "FALSE" — tab index is invalid.



Default: "TRUE"

fTabOrder Specifies the tab order:

� "TABORDER DOCTREE" — tab order isdetermined by the description in the document,set by the tabindex attribute.

� "TABORDER DISPLAY" — tab order starts fromthe y coordinate of the upper edge of thefocusable elements in the focus area.

� "TABORDER BASELINE" — tab order startsfrom the y coordinate of the lower edge of thefocusable elements in the focus area.

Default: "TABORDER DISPLAY"

fFocusOutlineWidth

Specifies the border for image maps or buttons withfocus, in pixels. Must be ≥1.

Default: "1"

fFocusOutlineWidthForControl

Specifies the border for controls with focus, inpixels:

� ≥"0" — the border width of the focus frame.

� "-1" — do not draw the focus frame eventhough the focus was retrieved.

Default: "1"

fFocusOutlineWidthForIFrame

The border width of the focus frame, in pixels, forthe inline frame.

Default: "1"

fContentParserMaxStayTime

The maximum time for the “content parserprogress”, before it can be interrupted, in



milliseconds. This process analyzes the text data andbuilds the internal DOM tree. Set to "0" or more.

Default: "100"

Higher values for “progress stay” times can result in faster pagerendering times. Lower values means the process is interrupted moreoften, possibly resulting in slower rendering times, but also allowingprocesses other than the browser engine more processor time.

�

fPageMakerMaxStayTime

The maximum time for the “page maker progress”,before it can be interrupted, in milliseconds. Set to"0" or more.

Default: "100"


�

fEditorMaxStayTimeFG

The maximum time for the “editor progress” for thevisible display area, in milliseconds. In this process,the rendering engine calculates the layoutinformation and draws the content to the currentlydisplayed area. Set to "0" or more.

Default: "100"


�

fEditorMaxStayTimeBG

The maximum time for the “editor progress” for theundisplayed area, in milliseconds. In this process,



the rendering engine calculates the layoutinformation for the area that isn’t currentlydisplayed. Set to "0" or more.

Default: "100"


�

fUseHTTP11PipeLine

Sets whether the browser uses pipelining inHTTP/1.1.

Default: "FALSE"

fCookieMode Cookie processing mode:

� "COOKIE NOTIFY BEFORE SET" — notifybefore setting a cookie.

� "COOKIE ALWAYS SET" — always set.

� "COOKIE NEVER SET" — never set.

Default: "COOKIE NOTIFY BEFORE SET"

fMaxStreams Maximum number of simultaneous TCPconnections.

Default: "4"

fMaxRequestHeader

The maximum HTTP request line size, in bytes.

Default: "-1" (no limit)

fMaxRequestBody

The maximum HTTP request body size, in bytes.




fMaxTotalCookies

The maximum number of cookies.

Default: "300"

fMaxCookiesPerDomain

The maximum number of cookies for each domain.

Default: "20"

fMaxLenPerCookie

The maximum size per cookie, in bytes.

Default: "4096"

fMaxRedirect

The maximum number of redirects.

Default: "30"

fMaxPageAuth

The maximum number of authentications per page.


fMaxProxyAuth

The maximum time for authentication per proxy.


fSendProxyKeepAlive

Transmit Proxy-Connection: KeepAlive header atHTTP.

Default: "TRUE"

fSendReferer

Transmit Referer header at HTTP.

Default: "TRUE"

fSendCookie Transmit cookies.

Default: "TRUE"



fDisableFilep

Disable file protocol.

Default: "FALSE"

fAllowHTTPandHTTPS

Display HTTPS content in HTTP content, or displayHTTP content in HTTPS content.

Default: "TRUE"

fBlockquoteMargin left

The left margin when drawing a <blockquote>element.

Default: "30"

fBlockquoteMargin right

The right margin when drawing a <blockquote>element

Default: "30"

fBlockquoteMargin top

The top margin when drawing a <blockquote>element

Default: "19"

fBlockquoteMargin bottom

The bottom margin when drawing a<blockquote> element

Default: "19"

Pt ARG WEB PRINT (write-only)


PpPrintContext t *, int Pointer



Set this resource to print the page. You can use the len argument ofPtSetArg() to specify a combination of the following flags:

Pt WEB PRINT FROM CACHE

When printing, let the print filters read images from the imagecache, to reduce the size of intermediate file.

Use this option only if the filter is run locally. It’s up to the clientapplication to prevent any activation in the server while printing.

�

Pt WEB PRINT ALL FRAMES

Print all frames as shown on the current page.

Pt ARG WEB RELOAD (write only)


N/A N/A N/A

This is a write-only resource without any specified type. Set it to anyvalue to reload the current page:

PtSetArg (&args[0], Pt ARG WEB RELOAD, 0, 0);PtSetResources (widget, 1, args);

Pt ARG WEB SERVER


char * String NULL

The name of a web server profile to use, or the path and any options tothe web server to start. Setting this resource starts the server; if there’sa server already attached to the client, it’s shut down and the new oneis started.



Web server profiles are stored in $HOME/.ph/webservers (the userprofile) and /etc/photon/webservers (the global profile). Theuser profile is searched first. The format of this file is:

profile=server,name

In this format, server is the server executable, including path andcommand-line options if required, and name is the named connectionthat the client must use to establish a connection to the server. Profilenames are not rigidly defined, so you can use any name that suits yourapplication if you create a custom profile. The file can containwhitespace, and lines that start with # are comments. If you need touse a comma in a command line option, use quotation marks aroundthe command line.

Here’s an example file:

# default server for "online" browsing (ie www)online = vserver,VoyagerServer-2

#default server for "offline" browsing (ie files on disk)offline = vserver.file -l -nVoyagerOffline,VoyagerOffline

# server profile for using Mozilla enginemozilla = mozilla -sshared,MozillaServer

# my own webserver - an example of using ’,’myserver = "/foo/bar/mywebserver -oOpt1,Opt2",MyServer

If no matching profile is found, then the string is taken literally as theserver to spawn, and the setting for Pt ARG CLIENT NAME is usedto connect to the spawned server.



You can bypass the profile lookup by beginning thePt ARG WEB SERVER string with the @ character. PtWebClientdiscards the @ and uses the remainder as the command to start the webserver. In this scenario, the setting for Pt ARG CLIENT NAME isused to connect to the server.

�

You can use web server profiles to override the web server used byexisting applications. For example, if an application tries to start thevserver server, you can cause it to use mozilla instead with thefollowing profile:

# default server for old Voyager clientvserver = mozilla -sshared,MozillaServer

Any options set prior to setting the resource are set back to theirdefaults.

�

For an example of using this resource, see “Starting the server,” above.

Pt ARG WEB SERVER PID (read only)


pid t Scalar

A read-only resource that returns the PID of the web server. The valueis 0 if the widget has connected to an existing server, or -1 if spawn()has failed.

Pt ARG WEB SSL RESPONSE


PtWebClientSSLResponse t * Pointer NULL

A resource that’s used only if you’re using the SSL (Secure SocketsLayer) version on the web server. This resource is used in response to



the Pt CB WEB SSL CERTNONTRUSTED andPt CB WEB SSL ERROR callbacks. The data structure used is asfollows:

typedef struct {char *url;int response;

} PtWebClientSSLResponse t;


url A pointer to the URL obtained from thePt CB WEB SSL ERROR callback.


� Pt WEB RESPONSE OK — override the error andcontinue.

� Pt WEB RESPONSE CANCEL — abort thetransaction.

Pt ARG WEB STARTUP ERRNO (read only)


int Scalar 0

A read-only resource that you can use to determine if the serverstarted successfully. If the value isn’t EOK, use errno to determinewhat went wrong. For more information, see “Starting the server,”above.

Pt ARG WEB STOP (write only)


N/A N/A N/A



This is a write-only resource without any specified type. Set it to anyvalue to stop the loading of the current page:

PtSetArg (&args[0], Pt ARG WEB STOP, 0, 0);PtSetResources (widget, 1, args);

Pt ARG WEB UNKNOWN RESP (write-only)


PtWebClientUnknownData t * Pointer

Set this resource to give a response to the server after aPt CB WEB UNKNOWN callback. When the download begins, thebrowser engine calls your Pt CB WEB DOWNLOAD callback.


typedef struct {short response;short zero;int download ticket;char *filename;char *url;

} PtWebClientUnknownData t;



� Pt WEB RESPONSE OK — the filename file is valid;continue with the disk download.Pt CB WEB DOWNLOAD is called.

� Pt WEB RESPONSE CANCEL — cancel thedownload of the unknown file.

download ticket

Arbitrary data. You can set this to unique data to helpyou keep track of downloads, for example if severaldownloads happen concurrently.



filename A pointer to the name of the file in which to saveunknown data.

url A pointer to the URL obtained from thePt CB WEB UNKNOWN callback.

Pt ARG WEB VERSION (read only)


char * String

Get the value of this resource to obtain the version of the connectedweb server.

Pt CB WEB AUTHENTICATE



A list of PtCallback t structures that define the callbacks invokedwhen the server requires authentication information or whencanceling a previous authentication request. To return theinformation, set the Pt ARG WEB AUTHENTICATE resource.


reason Pt CB WEB AUTHENTICATE

reason subtype

Not used.

event NULL

cbdata A pointer to a PtWebAuthenticateCallback t

structure:

typedef struct {



short type;short action;char *realm;char *url;

} PtWebAuthenticateCallback t;

The members of the PtWebAuthenticateCallback t structureare:

type The type of authentication used:

� Pt WEB BASIC AUTHENTICATION

� Pt WEB DIGEST AUTHENTICATION

� Pt WEB PROXY AUTHENTICATION

� Pt WEB IMPORT CERT AUTHENTICATION

action The action to take:

� Pt WEB ACTION OK — the server is requesting basicauthentication information.

� Pt WEB ACTION ABORT — the server is canceling aprevious request for basic authentication information.

realm A pointer to the realm name.

url A pointer to the URL that requires the authentication.

Pt CB WEB CLOSE WINDOW



A list of PtCallback t structures that define the callbacks invokedwhen a web page with Javascript requests that its window be closed.




reason Pt CB WEB CLOSE WINDOW

reason subtype

Not used.

event NULL

cbdata NULL

Pt CB WEB COMPLETE



A list of PtCallback t structures that define the callbacks invokedwhen the page has completed loading. Each callback is passed aPtCallbackInfo t structure that contains at least the followingmembers:

reason Pt CB WEB COMPLETE

reason subtype

Not used.

event NULL

cbdata A pointer to a PtWebCompleteCallback t structure:

typedef struct {char *url;

} PtWebCompleteCallback t;

The url member points to the URL of the page that hasjust completed.



Pt CB WEB CONTEXT



A list of PtCallback t structures that define the callbacks invokedwhen the user has right-clicked on the current page with the mouse.


reason Pt CB WEB CONTEXT

reason subtype

Not used.

event NULL

cbdata A pointer to a PtWebContextCallback t structure:

typedef struct {long context;PhPoint t pos;

} PtWebContextCallback t;

The members of the PtWebContextCallback t structure are:

context The context, which is one of:

� Pt WEB CONTEXT ANCHOR — the URL of a link isavailable.

� Pt WEB CONTEXT OBJECT — the URL of an imageor embedded object is available.

� Pt WEB CONTEXT BKGD — the URL of abackground image is available.

pos A PhPoint t structure (see the Photon LibraryReference) that contains the (x, y) coordinates of thelocation where the right mouse button was pressed.



Pt CB WEB DATA REQ




A list of PtCallback t structures that define the callbacks invokedwhen a file has been requested using the client protocol in the URL(e.g. client:about). The callback notifies the client that the serveris waiting for data; to return the data, set the Pt ARG WEB DATAresource.


reason Pt CB WEB DATA REQ

reason subtype

The same as the type member in the callback data.

event NULL

cbdata A pointer to a PtWebDataReqCallback t structure:

typedef struct {int type;int length;char *url;

} PtWebDataReqCallback t;

The members of the PtWebDataReqCallback t structure are:

type The type of request:

� Pt WEB DATA HEADER — the server is requesting theheader portion of the data. The header is of the sameform present in an HTTP request header.



� Pt WEB DATA BODY — the server is requesting thebody portion of the data.

� Pt WEB DATA CLOSE — the server has closed the datastream, and no more data should be given to the server.

length The maximum amount of data the server can accept.

url A pointer to the URL of the request.

For an example of using the client protocol, seePt ARG WEB DATA.

Pt CB WEB DOWNLOAD



A list of PtCallback t structures that define the callbacks invokedwhen the browser begins a file download.


reason Pt CB WEB DOWNLOAD

reason subtype

Not used.

event NULL

cbdata A pointer to a PtWebDownloadCallback t structure:

typedef struct {int download ticket;int type;int current;int total;char *url;char *message;

} PtWebDownloadCallback t;



The members of the PtWebDownloadCallback t structure are:

download ticket

This is the download ticket assigned to the downloadwhen you set the PtWebClientUnknownData t

structure for the Pt ARG WEB UNKNOWN RESPresource. This ticket allows you to keep track ofmultiple downloads.

type Can be one of:

� Pt WEB DOWNLOAD ERROR — an error occurred,display a dialog with some error text (see message).

� Pt WEB DOWNLOAD DONE — the download iscomplete.

� Pt WEB DOWNLOAD PROGRESS — the downloadis in progress.

current The current number of bytes that have beendownloaded.

total The total expected number of bytes.

url The url of the downloaded file.

message A descriptive message of the error that has occurred.The message is used only whentype=Pt WEB DOWNLOAD ERROR.

Pt CB WEB ERROR





A list of PtCallback t structures that define the callbacks invokedif an error occurs while loading a page. This includes unknown URLprotocols such as mailto:, allowing the client to handle them.

The mailto links are handled by the client. This is done by watchingfor the mailto URL in the Pt CB WEB ERROR callback.

�


reason Pt CB WEB ERROR

reason subtype

Not used.

event NULL

cbdata A pointer to a PtWebErrorCallback t structure:

typedef struct {short type;short reason;char *url;char *description;

} PtWebErrorCallback t;

The members of the PtWebErrorCallback t structure are:

type The type of error:

� Pt WEB ERROR SERVER EXIT — the server hasterminated.

� Pt WEB ERROR TOPVIEW — an error occurredwhen loading the requested page.

� Pt WEB ERROR SUBVIEW — an error occurredwhen loading a subdocument of the requested page(e.g. images in an HTML page).



� Pt WEB ERROR FILE — an error occurred whensaving a document to disk.

� Pt WEB ERROR WML — an error occurred whenloading the requested WML page.

reason If type is Pt WEB ERROR SERVER EXIT, the reasonmember contains the terminating status of the server(see waitpid() for more information on determiningwhy the server terminated).

If type is Pt WEB ERROR WML, an error occurred inWML content, and the reason member contains oneof:

Pt WEB ERROR WML AccessDenied

Access rejection error caused by specifying anaccess element.

Pt WEB ERROR WML InvalidVariableReference

Incorrect variable name error.Pt WEB ERROR WML InfiniteLoop

The WML parser has detected an infinite loop.

Pt WEB ERROR WML Unknown

An unknown WML error has occurred.Pt WEB ERROR WML SAX

The WML parser has detected syntax error.

For other values of type, the possible values of reasonare:

-1 Unspecified or unknown error.

-2 Parameter check / consistency check failed.

-3 Low memory.

-4 Low image cache memory.

-5 The operation was aborted.

-6 Bad header.



-8 The document contains no data.

-9 Missing service API.

-10 Missing request API.

-11 Multiple init.

-12 DNS failure.

-13 Connection failure.

-14 Network failure.

-15 Bad input stream.

-16 Request for data sink failed.

-17 New data sink failed.

-18 Invalid redirect.

-19 Unknown server error.

-21 Unknown document character set encoding.

-31 Corrupt data.

-39 Helper failed.

-40 SSL not supported.

-41 Unknown URL (No URL handler could befound to process the given URL).

-400 HTTP — Bad request.

-401 HTTP — Unauthorized.

-402 HTTP — Payment required.

-403 HTTP — Forbidden.

-404 HTTP — Not found.

-405 HTTP — Method not allowed.

-406 HTTP — Not acceptable.

-407 HTTP — Proxy authentication required.

-408 HTTP — Request time-out.

-409 HTTP — Conflict.

-410 HTTP — Gone.



-411 HTTP — Length required.

-412 HTTP — Precondition required.

-413 HTTP — Request entity too large.

-414 HTTP — Request URL too large.

-415 HTTP — Unsupported media type.

-500 HTTP — Internal server error.

-501 HTTP — Not implemented.

-502 HTTP — Bad gateway.

-503 HTTP — Service unavailable.

-504 HTTP — Gateway time-out.

-505 HTTP — HTTP version not supported.

-1200 FTP — Server error.

-1202 FTP — Error 332.

-1203 FTP — Error 530.

description The netfront server sets this member to a stringcontaining a description of the error.Voyager server does not use this member, and sets itto NULL.

Pt CB WEB IMPORT CERTIFICATE



A list of PtCallback t structures that define the callbacks invokedto inform the client whether a client certificate import operation issuccessful. The client initiates the import by settingPt ARG WEB IMPORT CERTIFICATE




reason Not used.

reason subtype

Not used.

event NULL

cbdata A pointer to a PtWebImportCertificateCallback t

structure:

typedef struct {int reason;char *description;} PtWebImportCertificateCallback t;

The reason is one of:

� Pt WEB IMPORT CERTIFICATE OK

� Pt WEB IMPORT CERTIFICATE ERROR

If reason is Pt WEB IMPORT CERTIFICATE ERROR,description is a text explanation for the error.

Pt CB WEB METADATA



A list of PtCallback t structures that define the callbacks invokedto inform the client of meta data that was read from the page. Themost common meta data returned is the web page title.


reason Pt CB WEB METADATA

reason subtype

Not used.



event NULL

cbdata A pointer to a PtWebMetaDataCallback t structure:

typedef struct {char *url;char *name;char *value;

} PtWebMetaDataCallback t;

The name member for the web page title is title.

Pt CB WEB NEED SCROLL (key mode only)




A list of PtCallback t structures that define the callbacks invokedwhen the server requires the client to scroll the page.


reason Pt CB WEB NEED SCROLL

reason subtype

Not used.

event NULL

cbdata A pointer to a PtWebNeedScrollCallback t structure:

typedef struct {short dir;

} PtWebNeedScrollCallback t;

where dir indicates the direction to scroll:



� Pt WEB DIRECTION UP

� Pt WEB DIRECTION DOWN

� Pt WEB DIRECTION LEFT

� Pt WEB DIRECTION RIGHT

Pt CB WEB NEW WINDOW



A list of PtCallback t structures that define the callbacks invokedwhen the browser requests that a new PtWebClient widget beconnected to the server so that it can display a page.

If no callback is attached, then the requested page appears in thewindow that the request was made (i.e. user clicked in). This doesn’tapply to Javascript open windows.


reason Pt CB WEB NEW WINDOW

reason subtype

Not used.

event NULL

cbdata A pointer to a PtWebWindowCallback t structure:

typedef struct {PhDim t size;long flags;

} PtWebWindowCallback t;

The members of the PtWebWindowCallback t structure are:



size A PhDim t structure (see the Photon Library Reference)that defines the dimensions of the new window.

flags A combination of the following bits:

� Pt WEB SHOW TOOLBAR — if the client contains atoolbar, it should be visible.

� Pt WEB SHOW MENUBAR — if the client contains amenubar, it should be visible.

� Pt WEB RESIZEABLE — the new window should beresizable.

� Pt WEB SHOW STATUS — the status field should bevisible.

� Pt WEB SHOW LOCATION — the URL location textfield should be visible.

Pt CB WEB PAGE INFO



A list of PtCallback t structures that define the callbacks invokedwhen the page size or position has changed. Each callback is passed aPtCallbackInfo t structure that contains at least:

reason Pt CB WEB PAGE INFO

reason subtype

Not used.

event NULL

cbdata A pointer to a PtWebPageInfoCallback t structure:

typedef struct {long vheight;long vwidth;long height;



long width;long ypos;long xpos;

} PtWebPageInfoCallback t;

The members of the PtWebPageInfoCallback t structure are:

vheight The height of the visible portion, in pixels.

vwidth The width of the visible portion, in pixels.

height The height of the page, in pixels.

width The width of the page, in pixels.

ypos The position of the right side of the page, in pixels.

xpos The position of the top of the page, in pixels.

Pt CB WEB SSL CERTINFO



A list of PtCallback t structures that define the callbacks that areinvoked when the web server has discovered an SSL connection;invoked after the handshake phase has determined the other party’sidentity.

This callback list is invoked only if you’re using the SSL version ofthe Voyager server (Spyrus Terisa version).

�


reason Pt CB WEB SSL CERTINFO



reason subtype

Not used.

event NULL

cbdata A pointer to a PtWebSSLCertInfoCallback t

structure:

typedef struct PtWebSSLCertInfoCallback t {char *url;char *cipher kind;int is sgc;int version;unsigned int flags;struct {

char *serial;char *subject;char *issuer;

} certinfo;time t valid begin, valid end;char *status;char *extensions;

} PtWebSSLCertInfoCallback t;

The members of the PtWebSSLCertInfoCallback t structure are:

url A pointer to the URL associated with the error.

cipher kind A pointer to the cipher suite used for theconnection (SSL 3 RSA WITH RC4-128 MD5,SSL 3 RSA WITH RC4 40 MD5, etc.)

is sgc Nonzero if the connection is using the “ServerGated Cryptography” (also called “Step-UpEncryption”).

version The version number: 2 for SSL 2.0, 0x0300 (768)for SSL 3.0, 0x0301 for TLS 1.0.

flags Flags for future extensions (always zero in thecurrent implementation).



certinfo.serial A pointer to the serial number for the certificate (ahexadecimal number).

certinfo.subject, certinfo.issuer

A pointer to distinguished names of the public keybeing certified.

valid begin, valid end

The time (in seconds since 01/01/1970 0h GMT) atwhich the certificates became valid and invalid.

status A pointer to the status of the certificate, representedas a string (Valid, Pending, Expired, Trustedroot, Unverified, and so on).

extensions A pointer to some additional information about theSSL connections (string).

When this callback is invoked, typically the client saves thisinformation relative to the current SSL connection, in order to be ableto display it on a subsequent user’s request (usually when the userclicks on the lock).

This callback returns only Pt CONTINUE; there’s no need to fill up aspecial structure as response.

Pt CB WEB SSL CERTNONTRUSTED



A list of PtCallback t structures that define the callbacks that areinvoked when the web server has discovered that the current SSLconnection is made with nontrusted certificate. Note that Voyagersupports only server certificate, and not Client certificates.




�


reason Pt CB WEB SSL CERTNONTRUSTED

reason subtype

Not used.

event NULL

cbdata A pointer to a PtWebSSLCertNonTrustedCallback t

structure:

typedef struct {short action;short ncert;char *url;char *status;int reason;PtWebSSLCertInfo t info[1];} PtWebSSLCertNonTrustedCallback t;

The members of the PtWebSSLCertNonTrustedCallback t

structure are:

action One of the following:

� Pt WEB ACTION OK — The callback was invoked asa warning; The non-trusted certificate did not make theconnection to be aborted.

� Pt WEB ACTION ABORT — The connection wasaborted.

ncert The number of items in the info array.



url A pointer to the URL associated with the error.

status A pointer to the status of the certificate, represented as astring (Valid, Pending, Expired, Trusted root,Unverified, and so on).

info An array of PtWebSSLCertInfo t structures (seebelow).

reason The reason the callback was invoked. Can be one of:

� Pt WEB SSL AUTHENTICATE — the callback wasinvoked during an authentication.

� Pt WEB SSL IMPORT CERT — the callback wasinvoked during an import certificate operation.

typedef struct {char *name;char *subject;char *issuer;char *cert serial;char *version;char *signature algorithm;char *basic constraints;char *extended key usage;int rsa public key bits;time t valid begin, valid end;} PtWebSSLCertInfo t;

PtWebSSLCertInfo t has these members:

name A pointer to the certificate’s name.

subject, issuer A pointer to distinguished names of the public keybeing certified.

cert serial A pointer to the serial number for the certificate(hexadecimal number).



version The version of X.509 applied to the certificate (1,2, or 3).

signature algorithm

The signature algorithm, which can be one of:

� CRL SIGN ALGO RSA — RSA Encryption

� CRL SIGN ALGO MD2 WITH RSA — MD2with RSA Encryption

� CRL SIGN ALGO MD5 WITH RSA — MD5with RSA Encryption

� CRL SIGN ALGO SHA1 WITH RSA — SHA-1with RSA Encryption

� CRL SIGN ALGO SHA1 WITH RSA SIGN —SHA-1 with RSA Signature

basic constraints

Basic constraints for the certificate.

extended key usage

The extended key usage, which specifies the usesfor which a certificate is valid.

rsa public key bits

The number of bits in the public RSA key.

valid begin, valid end

The time (in seconds since 01/01/1970 0h GMT) atwhich the certificates became valid and invalid.

When this callback is invoked, typically the client displays a dialoggiving three choices to the user:

� Abort

� Continue

� Accept



The transaction is halted until you set thePt ARG WEB SSL RESPONSE resource. You need to fill in aPtWebClientSSLResponse t structure with the URL found in thecallback structure and one of these response codes:

SSL CERTNONTRUSTED ABORT

Abort the connection to the site.

SSL CERTNONTRUSTED CONTINUE

Connect to the site, don’t save the certificate.

SSL CERTNONTRUSTED ACCEPT

Connect to the site, save the certificate.

Pt CB WEB SSL CLIENT CERT SELECT



A list of PtCallback t structures that define the callbacks that areinvoked when the netfront server wants the browser client todisplay a client certificate selection dialog. The dialog should list theavailable client certificates and the user should select one certificate tobe used for the current url that requested it.

The transaction is halted until you set thePt ARG WEB SSL RESPONSE resource. You need to fill in aPtWebClientSSLResponse t structure with the url found in thecallback structure and you have to set the response field to the index(starting at 0) of the selected certificate.


reason Pt CB WEB SSL CLIENT CERT SELECT

reason subtype

Not used.



event NULL

cbdata A pointer to a PtWebSSLClientCertCallback t

structure:

typedef struct {int ncert;char *url;int reserved1;int reserved2;PtWebSSLCertInfo t *info;} PtWebSSLClientCertCallback t;

The members of the PtWebSSLClientCertCallback t structureinclude:

ncert the number of certificates to be displayed (the number ofitems in the info array).

url the current url that have requested the client certificatesselection dialog to be displayed.

info array contains information about the certificates. See thePt CB WEB SSL CERTNONTRUSTED resource for adescription of the PtWebSSLCertInfo t structure.

Pt CB WEB SSL ERROR



A list of PtCallback t structures that define the callbacks that areinvoked when the Voyager server has discovered an error orinconsistency with the current SSL transaction.




�


reason Pt CB WEB SSL ERROR

reason subtype

Not used.

event NULL

cbdata A pointer to a PtWebSSLErrorCallback t structure:

typedef struct {short certerr;short trusted;char *url;int reason;

} PtWebSSLErrorCallback t;

The members of the PtWebSSLErrorCallback t structure are:

� trusted — indicates whether the current certificate is trusted.

� url — a pointer to the URL associated with the error.

� reason — can be one of:

- Pt WEB SSL AUTHENTICATE — the callback is invokedduring an authentication.

- Pt WEB SSL IMPORT CERT — the callback is invoked duringan import certificate operation.

� certerr — one of the following:

Pt WEB ERROR CertNoError

You don’t have a trusted certification on your end.



Pt WEB ERROR CertChainInvalid

No correct server should provide a certificate chain thatcauses this error. Any chain that creates this error is entirelyinsecure. Therefore, this error can’t be overridden.

Pt WEB ERROR CertExpired

The certificate provided by the remote server has expired.

Pt WEB ERROR CertNamesNotEqual

The name in the certificate isn’t the same as its DNS name.Pt WEB ERROR CertChainIncomplete

This error can be overridden and is equivalent to receiving acertificate with an unknown and untrusted root certificate. Ifyou choose to override this error, you abandon any protectionfrom active attacks, but because this error can be caused by aserver with a valid certificate (albeit one issued by anunknown party), letting users override this error may let themconnect to a valid site they would otherwise be unable toaccess.

Pt WEB ERROR InvalidSignature

Like Pt WEB ERROR CertChainInvalid, this error can’t beoverridden.

Pt WEB ERROR BasicConstraints

Violates basic constraints.Pt WEB ERROR FailedVerify

Cannot verify signature.

Pt WEB ERROR IncorrectKeyUsage

Key use and extension key use are invalid.

Pt WEB ERROR RootCertificateNotValid

The browser’s root CA certificate is expired.

The transaction is halted until you set thePt ARG WEB SSL RESPONSE resource. You need to fill in aPtWebClientSSLResponse t structure with the URL found in thecallback structure and one of the following response codes:



� Pt WEB RESPONSE OK — override the error and continue.

� Pt WEB RESPONSE CANCEL — abort the transaction.

Pt CB WEB START



A list of PtCallback t structures that define the callbacks invokedwhen a page starts loading. Each callback is passed aPtCallbackInfo t structure that contains at least the followingmembers:

reason Pt CB WEB START

reason subtype

Not used.

event NULL

cbdata NULL

Pt CB WEB STATUS



A list of PtCallback t structures that define the callbacks that areinvoked when the browser’s status changes. These callbacks give youmany different types of information.


reason Pt CB WEB STATUS



reason subtype

Not used.

event NULL

cbdata A pointer to a PtWebStatusCallback t structure:

typedef struct {short type;short zero;char *desc;char *url;

} PtWebStatusCallback t;

This callback gives you many different types of information. Beforeperforming any actions, you should first check the type and then actaccordingly.

The types are:

Pt WEB STATUS MOUSE

Reports when the mouse moved over links, images, etc.

Pt WEB STATUS CONNECT

Reports connection-related messages.

Pt WEB STATUS DEFAULT

Reported when Javascript requests the default status bar text bechanged (i.e. window.defaultStatus=". . ."). The defaultStatusmessage appears when nothing else is in the status bar.

Pt WEB STATUS PROGRESS

A progress message (e.g. the number of bytes downloaded).

Pt WEB STATUS INFO

Reports various information. Valid INFO types are:

FORM-EDIT Single-line text field has focus.



FORM-PASS The password field has focus.

FORM-LIST Single select list has focus.

FORM-MULTILIST

Multi-select list has focus.

FORM-COMBO Combo box has focus.

FORM-TEXTAREA

Multi-line text field has focus.FORM-CHECKBOX

Check box has focus.

FORM-RADIO Radio button has focus.

FORM-SUBMIT Submit button has focus.

FORM-RESET Reset button has focus.

LINK-IMAGE-MAP

Image map has focus.

LINK-IMAGE Image link has focus.

LINK-TEXT Text link has focus.

FRAMESET-DOC

Frames document has been loaded.FORM-CURSOR-LEFT

The cursor inside a FORM control or imagemap has reached the leftmost position.

FORM-CURSOR-RIGHT

The cursor inside a FORM control or imagemap has reached the rightmost cursorposition.

FORM-CURSOR-TOP

The cursor inside a FORM control or imagemap has reached the topmost position.

FORM-CURSOR-BOTTOM

The cursor inside a FORM control or imagemap has reached the bottommost cursorposition.



PAGE-TOP The page has scrolled to its topmost position.

PAGE-BOTTOM The page has scrolled to its bottommostposition.

PAGE-LEFT The page has scrolled to its leftmost position.

PAGE-RIGHT The page has scrolled to its rightmostposition.

Pt WEB STATUS PRINT

Reports print-related status (pages printed):

� "Print Error %d" — an error occurred. The %dparameter can be:

-600 No printer was set.

-601 The page wasn’t printable.

-602 A general print error occurred.

� "Print Done"

� "Print Done - More" — more pages can be printed.

Pt CB WEB UNKNOWN



A list of PtCallback t structures that define the callbacks invokedwhen the server has received a file that it can’t display or has noexternal helpers that match its mimetype or file suffix. SetPt ARG WEB UNKNOWN RESP to provide a filename or cancel thedownload anytime after this callback.


reason Pt CB WEB UNKNOWN



reason subtype

Not used.

event NULL

cbdata A pointer to a PtWebUnknownCallback t structure:

typedef struct {short action;short flags;char *content type;int content length;char *url;

} PtWebUnknownCallback t;

The members of the PtWebUnknownCallback t structure are:

action The action taking place:

� Pt WEB ACTION OK — the server is requestinga the name of a file in which to save the data.

� Pt WEB ACTION ABORT — the server iscanceling a previous request for a filename.

flags Not currently used.

content type A pointer to the mime content type of the file (ifavailable).

content length The length of the file (-1 if unknown).

url A pointer to the URL of the file.

Pt CB WEB URL





A list of PtCallback t structures that define the callbacks that areinvoked when the browser has a complete URL to be loaded. This isuseful for saving internal history lists or saving URLs in hotlists.


reason Pt CB WEB URL

reason subtype

Not used.

event NULL

cbdata A pointer to a PtWebUrlCallback t structure:

typedef struct {char *url;

} PtWebUrlCallback t;





continued. . .











Pt ARG CLIENT FLAGS PtClient

Pt ARG CLIENT NAME PtClient "VoyagerServer-2"

Pt ARG CLIENT REPLY LEN PtClient

Pt ARG CLIENT SEND PtClient

Pt ARG CLIENT SERVER PtClient










Pt ARG DIM PtWidget


continued. . .




















Pt ARG POS PtWidget







continued. . .






Pt CB ARM PtBasic




Pt CB CLIENT CONNECTED PtClient

Pt CB CLIENT EVENT PtClient

Pt CB CLIENT NOT FOUND PtClient



Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget




continued. . .


PtWidget 2004, QNX Software Systems Ltd.

Superclass for all widgets

Class hierarchy:PtWidget


� PtBasic

� PtTimer


Public header:<photon/PtWidget.h>

Description:PtWidget is the fundamental superclass. All widgets belong to asubclass of PtWidget.

Geometry

Geometry refers to the size and location of the widget. The followingresources let you set and get the widget’s geometry in various ways:

Pt ARG AREA The (x, y) coordinates of the widget’s upper leftcorner, and the widget’s height and width.

Pt ARG DIM The widget’s width and height.

Pt ARG EXTENT

A rectangle giving the coordinates of the upper-leftand lower-right corners of the widget.

Pt ARG GRID LAYOUT DATA

The grid layout data structure, which containslayout hints and settings for the widget when itscontainer has a layout type of PtGridLayout.


2004, QNX Software Systems Ltd. PtWidget

Pt ARG HEIGHT

The overall height.

Pt ARG LAYOUT DATA

A generic resource to set the layout data structure,which contains layout hints and settings for thewidget.

Pt ARG MAXIMUM DIM

The maximum size of the widget.

Pt ARG MINIMUM DIM

The minimum size of the widget.

Pt ARG POS The coordinates of the upper left corner of thewidget.

Pt ARG ROW LAYOUT DATA

The row layout data structure, which containslayout hints and settings for the widget when itscontainer has a layout type of PtRowLayout.

Pt ARG WIDTH

The overall width of the widget.

These resources aren’t displayed in PhAB’s control panel; you canuse the pointer to change a widget’s size and location, or you can editthe values in PhAB’s toolbar. Setting one of these resources causesthe others to be updated automatically.

Storing arbitrary user data

You can store arbitrary data in a widget by using these resources:

Pt ARG POINTER

When you set this resource, the widget copies the value of thepointer into its internal memory.



If you use Pt ARG POINTER, you can have several widgetspointing at the same data. If you free the data, you’ll need tomake sure that no widgets still refer to it.

Pt ARG USER DATA

When you set this resource, the widget copies a block of data ofa given size into its internal memory.

There’s another resource, Pt ARG DATA, that sounds like it can beused for storing user data, but it can’t. It’s used internally by PhABapplications and compound widgets.

�

New resources:


Pt ARG ANCHOR FLAGS unsigned Flag 0

Pt ARG ANCHOR OFFSETS PhRect t Struct 0, 0, 0, 0

Pt ARG AREA PhArea t Struct 0,0,0,0

Pt ARG BEVEL WIDTH unsigned short Scalar 2

Pt ARG BITMAP CURSOR PhCursorDef t * Alloc NULL

Pt ARG CURSOR COLOR PgColor t Scalar Ph CURSOR DEFAULT COLOR

Pt ARG CURSOR TYPE unsigned short Scalar Ph CURSOR INHERIT

Pt ARG DATA void * Alloc NULL

Pt ARG DIM PhDim t Struct 0,0

Pt ARG EFLAGS unsigned short Flag 0

Pt ARG EXTENT PhRect t Struct 0,0,0,0

continued. . .




Pt ARG FLAGS long Flag 0

Pt ARG GRID LAYOUT DATA PtGridLayoutData t * Struct NULL

Pt ARG HEIGHT unsigned short Scalar 0

Pt ARG HELP TOPIC char * String NULL

Pt ARG LAYOUT DATA void * Struct NULL

Pt ARG MAXIMUM DIM PhDim t Struct 0,0

Pt ARG MINIMUM DIM PhDim t Struct 0,0

Pt ARG POINTER void Pointer NULL

Pt ARG POS PhPoint t Struct 0,0

Pt ARG RESIZE FLAGS long Flag 0

Pt ARG ROW LAYOUT DATA PtRowLayoutData t * Struct NULL

Pt ARG USER DATA void * Alloc NULL

Pt ARG WIDTH unsigned short Scalar 0

Pt CB BLOCKED PtCallback t * Link NULL

Pt CB DESTROYED PtCallback t * Link NULL

Pt CB DND PtCallback t * Link NULL

Pt CB FILTER PtRawCallback t * Link NULL

Pt CB HOTKEY PtHotkeyCallback t * Link NULL

Pt CB IS DESTROYED PtCallback t * Link NULL

Pt CB OUTBOUND PtCallback t * Link NULL

Pt CB RAW PtRawCallback t * Link NULL

Pt CB REALIZED PtCallback t * Link NULL

Pt CB UNREALIZED PtCallback t * Link NULL



Pt ARG ANCHOR FLAGS


unsigned Flag 0

This resource specifies how the widget is anchored to its parent. Thepossible values are:

Pt LEFT ANCHORED RIGHT

Anchor the widget’s left extent to the right edge of its parent’scanvas.

Pt RIGHT ANCHORED RIGHT

Anchor the widget’s right extent to the right edge of its parent’scanvas.

Pt TOP ANCHORED BOTTOM

Anchor the widget’s top extent to the bottom edge of its parent’scanvas.

Pt BOTTOM ANCHORED BOTTOM

Anchor the widget’s bottom extent to the bottom edge of itsparent’s canvas.

Pt LEFT ANCHORED LEFT

Anchor the widget’s left extent to the left edge of its parent’scanvas.

Pt RIGHT ANCHORED LEFT

Anchor the widget’s right extent to the left edge of its parent’scanvas.

Pt TOP ANCHORED TOP

Anchor the widget’s top extent to the top edge of its parent’scanvas.

Pt BOTTOM ANCHORED TOP

Anchor the widget’s bottom extent to the top edge of its parent’scanvas.



Pt BALLOONS ON

If a child widget has been assigned a balloon, pop up theballoon as soon as the pointer passes over the child widget;otherwise delay the pop up for 1.25 seconds.

If the resize policy conflicts with the anchors, thePt ARG RESIZE FLAGS override Pt ARG ANCHOR OFFSETS andPt ARG ANCHOR FLAGS.

�

For more information about anchors, see the Geometry Managementchapter of the Photon Programmer’s Guide.

Pt ARG ANCHOR OFFSETS


PhRect t Struct 0, 0, 0, 0

The four values in this PhRect t structure (see the Photon LibraryReference) determine the anchor offsets of each of the widget’s sides.(An anchor offset is the distance between the anchoring side of theparent and corresponding side of the child.)

The Pt ARG ANCHOR OFFSETS resource isn’t displayed in PhABbecause PhAB sets it automatically.

�

If a side is anchored, its anchor offsets, if explicitly specified, overridePt ARG AREA and Pt ARG DIM.

Only offsets that have a corresponding bit set in thePt ARG ANCHOR FLAGS resource are applied. For example, let’ssay you have a Pt ARG ANCHOR OFFSETS resource of (5,10,20,25)with absolute anchoring and a Pt ARG ANCHOR FLAGS resource ofPt LEFT ANCHORED LEFT | Pt RIGHT ANCHORED RIGHT |

Pt TOP ANCHORED TOP | Pt BOTTOM ANCHORED BOTTOM. Inthat case, the pane’s extent will be:



� 5 pixels from its parent’s left canvas edge

� 10 pixels from its parent’s top canvas edge

� 20 pixels from its parent’s right canvas edge

� and 25 pixels from its parent’s bottom canvas edge

This remains true even as the parent is resized.


�

Pt ARG AREA


PhArea t Struct 0,0,0,0

A PhArea t structure (see the Photon Library Reference) thatcontains the x, y, height, and width values for the widget. For relatedresources, see the “Geometry” section, above.

You can edit this resource in PhAB’s toolbar, not the control panel;PhAB also sets it automatically when you move or size the widget.

Pt ARG BEVEL WIDTH



The width of the widget’s bevel if the widget is highlighted and is todraw a bevel (see Pt ARG FLAGS, below, and thePt ARG BASIC FLAGS resource defined for PtBasic).



Pt ARG BITMAP CURSOR


PhCursorDef t * Alloc NULL

Defines bitmaps for the cursor when the cursor type(Pt ARG CURSOR TYPE) is set to Ph CURSOR BITMAP. You can’tedit this resource in PhAB.

The widget automatically sets the hdr member of thePhCursorDef t structure. For information, see the Photon LibraryReference.

Pt ARG CURSOR COLOR


PgColor t Scalar Ph CURSOR DEFAULT COLOR

The color of the pointer when it’s inside the widget. See PgColor t


Pt ARG CURSOR TYPE


unsigned short Scalar Ph CURSOR INHERIT

The type of cursor:

Ph CURSOR INHERIT

Inherit the cursor, not from the class hierarchy, but from thefamily hierarchy; that is, from the way your application neststhe widgets. The cursor might even be inherited from thePhoton server itself.

Ph CURSOR BITMAP

Use the bitmap stored in Pt ARG BITMAP CURSOR for thecursor.



By default, bitmap cursors aren’t inherited by a widget’s childregions. To change this, set Pt ARG CURSOR TYPE to:

Ph CURSOR BITMAP & ˜Ph CURSOR NO INHERIT

�

For other cursor definitions, see the cursor type table inPhCharacterCursorDescription t.

Pt ARG DATA


void * Alloc NULL

This resource is used internally by PhAB applications as well as bycompound widgets. It isn’t displayed in PhAB. For more information,see Building Custom Widgets.

If you want to store arbitrary data in a widget, use itsPt ARG POINTER or Pt ARG USER DATA resource. See “Storingarbitrary user data,” above.

�

Pt ARG DIM


PhDim t Struct 0,0

A PhDim t structure (see the Photon Library Reference) that definesthe height and width values for the widget. For related resources, seethe “Geometry” section, above.

You can edit this resource in PhAB’s toolbar, not the control panel;PhAB also sets it automatically when you size the widget.



Pt ARG EFLAGS


unsigned short Flag 0

Extended flags inherited by all widgets:

Pt CONSUME EVENTS

Consume any event encountered, whether or not an action wasperformed as a result of that event. (When a widget hasprocessed an event and prevents another widget frominteracting with the event, the first widget is said to haveconsumed the event.)

Pt INTERNAL HELP

Display help information for the widget in a balloon, not in theHelpviewer. See the chapter on Context-Sensitive Help in thePhoton Programmer’s Guide.

Pt DAMAGE PARENT (read-only)

If the widget is damaged for any reason, damage its parentinstead (internal use only).

Pt SKIP LAYOUT

Skip this widget when performing a layout. See Using layoutsin the Geometry Management chapter of the PhotonProgrammer’s Guide.

Pt ARG EXTENT


PhRect t Struct 0,0,0,0

A PhRect t structure (see the Photon Library Reference) thatcontains the extent of the widget, a rectangle that specifies the



upper-left and lower-right corners of the widget. For relatedresources, see the “Geometry” section, above.

A widget’s extent isn’t normally calculated until the widget isrealized. You can force a widget to calculate its extent by callingPtExtentWidget() — see the Photon Library Reference.

�

Pt ARG FLAGS


long Flag 0

Common flags used by all widgets. Except for those indicated asread-only, these flags are all read/write.

PtWidgetFlags() is a convenience function that retrieves the value ofthis resource.

�

The flags include:

Pt ALL BUTTONS

Any pointer button can activate the widget. Defaultis the left button only.

Pt AUTOHIGHLIGHT

Highlight and give focus to the widget when thecursor enters its extent, and unhighlight andremove focus when the cursor leaves.

Pt BLOCKED Prevent the widget and all its non-window-classchildren from interacting with Photon events.

Pt CALLBACKS ACTIVE

If certain widgets have this bit set, and yourapplication sets their resources, the relevantcallbacks are invoked. Otherwise callbacks aren’t



invoked when your application sets resources. If acallback refers to this flag, its description says soexplicitly.

For example, if this bit is set for a PtDivider andyou use PtSetResources() to change the size of oneof its children, the Pt CB DIVIDER DRAGcallback is invoked.

Pt CLEAR (read-only)

The widget’s brothers-in-front don’t intersect withits extent.

Pt CLIP HIGHLIGHT

Clip the corners of the highlighting rectangle.

Pt DAMAGED (read-only)

The widget requires repair.

Pt DAMAGE FAMILY (read-only)

The widget and all its children need to be repaired.

Pt DELAY REALIZE

Prevent the widget from becoming realized unlessit’s explicitly realized with PtRealizeWidget().

Pt DESTROYED (read-only)

The widget has been marked for destruction.

Pt FOCUS RENDER

Render a focus indicator when the widget when itgets focus.

Pt GETS FOCUS

Allow the widget to be granted focus. The widgetneeds to have this bit set if it’s to receive keyevents.

Pt GHOST Dim the widget. Setting this flag doesn’t affect thewidget’s behavior, just its appearance. The



simplest way to disable the widget is to set thePt BLOCKED flag in this resource.

Pt HIGHLIGHTED

Allow the widget to be highlighted as defined bythe Pt ARG BEVEL WIDTH, and thePt ARG BASIC FLAGS resource defined byPtBasic.

Pt IN FLUX (read-only)

A call to PtContainerHold() has been made on thewidget.

Pt MENUABLE Respond to clicks on the pointer’s right button (i.e.enable the Pt CB MENU callback defined byPtBasic).

Pt MENU BUTTON

The widget is a menu item.

Pt OBSCURED (read-only)

The widget is completely covered by one otherwidget, or it’s completely outside its parentcontainer’s canvas.

Pt OPAQUE (read-only)

This widget obscures everything directly behind it(i.e. it isn’t transparent).

Pt PROCREATED (read-only)

The widget was created by another widget (asopposed to an application), such as the PtListand PtText created by a PtComboBox.

Pt REALIZED (read-only)

The widget is realized.

Pt REALIZING (read-only)

The widget is in the process of being realized.



Pt REGION Force the widget to have a region.

Pt SELECTABLE

You can select (repeat, arm, disarm, and activate)the widget. Widgets usually provide visualfeedback when selected.

Pt SELECT NOREDRAW

The widget doesn’t change its appearance when setor unset. This is meaningful only when the widgetis selectable.

Pt SET The widget is in a “set” state. Generally, thisindicates that the widget has been selected.

Pt TOGGLE Pressing the pointer button on this widget causes itto toggle between being set and unset. Normally,selectable widgets act as push buttons — theybecome set when you press the pointer button, andunset when you release the button.

Pt WIDGET REBUILD (read-only)

The widget will be rebuilt (rerealized) when thewidget engine is finished applying resourcechanges.

Pt WIDGET RESIZE (read-only)

The widget will be resized when the widget engineis finished applying resource changes.


Pt ARG GRID LAYOUT DATA


PtGridLayoutData t * Struct NULL



A PtGridLayoutData t structure that defines additional layoutdata for the widget when its container widget uses a PtGridLayouttype layout.

PtGridLayoutData t has at least these members:

short flags Combination of the following flags:

� Pt H GRAB — If the parent grows horizontally,this child’s cell gets some or all of the extraspace, depending on the setting of the h weightmember, and whether or not other cells are alsograbbing extra space.

� Pt V GRAB — If the parent grows vertically,this child’s cell gets some or all of the extraspace, depending on the setting of the v weightmember, and whether or not other cells are alsograbbing extra space .

� Pt GRAB BOTH — Pt V GRAB | Pt V GRAB

� Pt H ALIGN BEGINNING — Left align thewidget in its cell

� Pt H ALIGN CENTER — Center the widgethorizontally in its cell

� Pt H ALIGN END — Right align the widget inits cell

� Pt H ALIGN FILL — Horizontally stretch (or“fill”) the widget in its cell

� Pt V ALIGN BEGINNING — Top align thewidget in its cell

� Pt V ALIGN CENTER — Center the widgetvertically in its cell

� Pt V ALIGN END — Bottom align the widgetin its cell

� Pt V ALIGN FILL — Vertically stretch (or“fill”) the widget in its cell



� Pt ALIGN BEGINNING BOTH —Pt H ALIGN BEGINNING |Pt V ALIGN BEGINNING

� Pt ALIGN CENTER BOTH —Pt H ALIGN CENTER | Pt V ALIGN CENTER

� Pt ALIGN END BOTH — Pt H ALIGN END |Pt V ALIGN END

� Pt ALIGN FILL BOTH — Pt H ALIGN FILL |Pt V ALIGN FILL

short h span Horizontal span of this child in a number ofcolumns.

short v span Vertical span of this child in a number of rows.

PhDim t hint The w (width) and h (height) hints for this childwidget. Think of these hints as a user definedminimum size, even if the widget could be smaller.Set w and h to 0 if you just want to apply flags tothis child.

short h weight The portion of the extra space the widget’s cellgets if its parent grows, and the widget has thePt H GRAB flag set.

short v weight The portion of the extra space the widget’s cellgets if its parent grows, and the widget has thePt V GRAB flag set.

PhRect t margins

cell margins in pixels, where:


� ul.y is the top





You can use PtGridLayoutDataDflts to initialize your copy ofPtGridLayoutData t. It has the following values:

� flags = Pt H ALIGN BEGINNING | Pt V ALIGN BEGINNING

� h span = v span = 1

� hint.w = hint.h = 0

� h weigth = v weight = 0

� margin.ul.x = margin.ul.y = margin.lr.x = margin.lr.y = 0

�


Pt ARG HEIGHT



The height of the widget. For related resources, see the “Geometry”section, above.


Pt ARG HELP TOPIC


char * String NULL

The meaning of this resource depends on the bits set inPt ARG EFLAGS:

� If Pt INTERNAL HELP isn’t set, Pt ARG HELP TOPIC is used toset the topic position within the HTML help file.



� If Pt INTERNAL HELP is set, Pt ARG HELP TOPIC is the helpinformation to be displayed.

For more information, see the PtHelp*() functions and the chapter onContext-Sensitive Help in the Photon Programmer’s Guide.

Pt ARG LAYOUT DATA


void * Struct NULL

This resource provides a convenient method to get or set either of thePt ARG * LAYOUT DATA resources.

When you set this resource using PtSetResource() or PtSetArg(), setthe value argument to a pointer to the layout data structure you wantto use. This can be one of:

� PtRowLayoutData t

� PtGridLayoutData t

You can optionally set the len argument to a pointer to the layout typethat corresponds to the data structure (that is, PtRowLayout orPtGridLayout). If you set len to NULL, the layout data structure forthe current layout is set. In this case, make sure that the data structurecorresponds to the correct layout type, or your application mightcrash.


Pt ARG MAXIMUM DIM


PhDim t Struct 0,0



A PhDim t structure (see the Photon Library Reference) that definesthe maximum size that a widget can be. For related resources, see the“Geometry” section, above.

Pt ARG MINIMUM DIM


PhDim t Struct 0,0

A PhDim t structure (see the Photon Library Reference) that definesthe minimum size that a widget can be. For related resources, see the“Geometry” section, above.

Pt ARG POINTER


void Pointer NULL

A pointer to any data that you want to associate with the widget.

For a comparison between this resource and Pt ARG USER DATA,see “Storing arbitrary user data,” above.

Pt ARG POS


PhPoint t Struct 0,0

A PhPoint t structure that stores the x and y coordinates for thewidget. For related resources, see the “Geometry” section, above.

You can edit this resource in PhAB’s toolbar, not the control panel;PhAB also sets it automatically when you move the widget.



Pt ARG RESIZE FLAGS


long Flag 0

Controls a widget’s resize policy in both the x and y directions.Possible values:

� Pt RESIZE X AS REQUIRED

� Pt RESIZE X ALWAYS

� Pt RESIZE X INITIAL

� Pt RESIZE X BITS

� Pt RESIZE Y AS REQUIRED

� Pt RESIZE Y ALWAYS

� Pt RESIZE Y INITIAL

� Pt RESIZE Y BITS

� Pt RESIZE XY ALWAYS

� Pt RESIZE XY AS REQUIRED

� Pt RESIZE XY INITIAL

� Pt RESIZE XY BITS

Note that each ...BITS flag is a mask that represents all the bits of thattype.

The default setting of this resource is 0; that is, no resize policy is ineffect.

A widget’s resize policy deals solely with the widget’s renderabledata. For a button, the data is its text; for a container, the data is itschildren. Any rendered data that doesn’t fit within the widget’s canvasis clipped.



If no resize policy is in effect, the widget’s size is unbounded; it maybe made as large or small as specified via Pt ARG DIM orPt ARG AREA.

If a resize policy is in effect, the widget grows or shrinks to honor thatpolicy. If the policy is ...ALWAYS, the widget resizes itself to fit itsdata — the dimensions specified via Pt ARG DIM or Pt ARG AREAdon’t apply. If the policy is ...AS REQUIRED, the widget resizes itselfto fit its data only if its current canvas size is inadequate to containthat data. In other words, it grows, but doesn’t shrink, to fit its data.

If the widget has the ...INITIAL bit set, the resize policy is appliedonly once each time the widget is realized. This bit is meaningfulonly in concert with ...ALWAYS or ...AS REQUIRED.


�

For more information about resize policies, see the GeometryManagement chapter of the Photon Programmer’s Guide.

Pt ARG ROW LAYOUT DATA


PtRowLayoutData t * Struct NULL

A PtRowLayoutData t structure that defines additional layout datafor the widget when its container widget uses a PtRowLayout typelayout.

PtRowLayoutData t has at least these members:

PhDim t hint Contains w (width) and h (height) hints for thischild widget. Think of these hints as a user definedminimum size, even if the widget could be smaller.Set w and h to 0 if you just want to apply flags tothis child.



short flags Combination of the following flags:

� Pt ROW WRAP AFTER — Unconditionallywrap after this child. Pt ROW WRAP should beset in the flags member of thePtRowLayoutInfo t of the parent.

� Pt ROW WRAP BEFORE — Unconditionallywrap this child. Pt ROW WRAP should be set inthe flags member of the PtRowLayoutInfo t

of the parent.

� Pt ROW FILL — If this child is the last one inits row or column, stretch or shrink it to occupyall the available space.

You can use PtRowLayoutDataDflts to initialize your copy ofPtRowLayoutData t. It has the following values:

� flags = NULL

� hint.w = hint.h = 0

�


Pt ARG USER DATA


void * Alloc NULL

Data that you want to store in the widget’s internal memory.

For a comparison between this resource and Pt ARG POINTER, see“Storing arbitrary user data,” above.



Pt ARG WIDTH



The width of the widget. For related resources, see the “Geometry”section, above.


Pt CB BLOCKED



A list of PtCallback t structures that define the callbacks that thewidget invokes whenever it must ignore an event due to beingblocked.


reason Pt CB BLOCKED

event A pointer to a PhEvent t structure that describes theevent that was blocked for this widget.

cbdata NULL


Pt CB DESTROYED





A list of PtCallback t structures that define the callbacks invokedwhen the widget is marked for destruction and is no longer visible.You can use these callbacks, for example, to adjust the appearance ofthe widgets around the one being destroyed.

In contrast, the Pt CB IS DESTROYED callbacks are invoked whenthe widget’s resources are actually being released.

�


reason Pt CB DESTROYED

event A pointer to a PhEvent t structure filled with NULLs.

cbdata NULL


Pt CB DND



A list of PtCallback t structures that define the callbacks calledwhen a drag-and-drop (Ph EV DNDROP) event is received. For moreinformation, see the Drag and Drop chapter of the PhotonProgrammer’s Guide.

A widget doesn’t have to have Pt SELECTABLE set in itsPt ARG FLAGS for its Pt CB DND callbacks to be invoked.

�


reason Pt CB DND



reason subtype

One of:

� Ph EV DND ENTER — the pointer has moved into thewidget during a drag-and-drop operation.

� Ph EV DND LEAVE — the pointer has left the widget.

� Ph EV DND CANCEL — the drag-and-drop operationhas been canceled.

� Ph EV DND COMPLETE — the drag-and-dropoperation has been completed.

� Ph EV DND MOTION — the pointer is moving.

� Ph EV DND DROP — the user is dropping the draggeditem on this widget.


cbdata A pointer to a PtDndCallbackInfo t structure thatcontains at least the following members:

� PtTransportCtrl t *trans ctrl — a pointer to thePtTransportCtrl t structure (see the PhotonLibrary Reference) controlling the drag-and-dropoperation if this application is the originator of it.NULL otherwise.

The following members are valid only when thereason subtype is Ph EV DND DROP:

int unsigned fetch index

This contains the index of the elementdefined in the “fetch array” that describesthe data contained in the data member ofthis structure.

PhTransportHdr t *trans hdr

A pointer to the transport header for theunpacked data. See <PhTransport.h>.



void *data A pointer to the data extracted from thedrag-and-drop event. The type of data isgiven by examining the fetch indexmember.

The following member is meaningful only when thereason subtype is Ph EV DND ENTER:

int unsigned flags

If set to Ph DND DELAY ACK in the callback, thelibrary doesn’t automatically acknowledge theENTER event. This results in a clock cursor overthis drop zone until the drag-and-drop operation iscanceled.Otherwise the library automatically acknowledgesthe ENTER event based on the number of dataitems selected from the drag-and-drop event viaPtDndSelect().

The PtTransportCtrl t structure also includes:

int unsigned handle

A variable for the your convenience. The valueplaced here will be found in handle in subsequentcallbacks related to the ENTER event where thehandle was set.



Additional data is passed to Pt CB DND callbacks for these widgetclasses:

� PtFileSel

� PtGenList

� PtGenTree

� PtList

� PtRawList

� PtRawTree

� PtTree

�

A drag-and-drop recipient typically calls PtDndSelect() when thereason subtype is Ph EV DND ENTER, and handles the data when thereason subtype is Ph EV DND DROP. The other subtypes can begenerally ignored.

For more information, see the Drag and Drop chapter of the PhotonProgrammer’s Guide.

Pt CB FILTER


PtRawCallback t * Link NULL

A list of raw callbacks invoked when an event that matches theprovided event mask is to be passed to the widget.

These callbacks are invoked before the event is processed by thewidget. Contrast this resource with Pt CB RAW.

�

Because the Pt CB FILTER callback is called before the widgetprocesses the event, it gives you the opportunity to decide if the event



should be ignored, discarded, or processed by the widget. The returncode from the callback indicates what is to happen to the event.

You can add a Pt CB FILTER callback to a widget in yourapplication’s code by calling PtAddFilterCallback() orPtAddFilterCallbacks(). For more information about this callback,see “Event handlers” in the Events chapter of the PhotonProgrammer’s Guide.


reason Pt CB FILTER

reason subtype

0 (not used).


cbdata NULL

These callbacks should return one of:

Pt CONSUME Consume the event and prevent further propagationof it.

Pt IGNORE Ignore the event. The event is still consumed if thewidget has Pt CONSUME EVENTS set in itsPt ARG EFLAGS. If Pt CONSUME EVENTS isn’tset, the event continues through the widgethierarchy as if the current widget didn’t exist.

Pt PROCESS Allow the event to be processed by the widget asusual.



Pt CB HOTKEY


PtHotkeyCallback t * Link NULL

A list of PtHotkeyCallback t structures. If the widget receives akey event that matches a structure’s key cap and key modifiers, thewidget calls the function specified in that structure. If a function isn’tspecified, the widget invokes its Pt CB ACTIVATE callback list with areason subtype of Pt CB HOTKEY.

A hotkey isn’t invoked if any ancestor of the widget that owns it isblocked.

�

You can add a Pt CB HOTKEY callback to a widget in yourapplication’s code by calling PtAddHotkeyHandler(). For moreinformation about this callback, see “Hotkey callbacks” in the EditingResources and Callbacks in PhAB chapter of the PhotonProgrammer’s Guide.


reason Pt CB HOTKEY


cbdata A pointer to a PtHotkeyCallback t structure.


Pt CB IS DESTROYED





A list of PtCallback t structures that define the callbacks invokedwhen the widget’s resources are being released. You’ll find thisresource useful for cleaning up variables or memory associated withthe widget.

In contrast, the Pt CB DESTROYED callbacks are invoked when thewidget is marked for destruction and is no longer visible.

�


reason Pt CB IS DESTROYED


cbdata NULL


Pt CB OUTBOUND



A list of PtCallback t structures that define the callbacks invokedwhen you press the pointer button on the widget and then move out ofthe “hot spot” with the button still depressed.

This callback is particularly useful for initiating drag ordrag-and-drop operations. For more information, see the Drag andDrop chapter of the Photon Programmer’s Guide.




reason Pt CB OUTBOUND

reason subtype

The button state (the same as ptr->button state if the codegiven below is included in your callback).

event A pointer to a PhEvent t structure that describes theevent that caused the callback to be invoked. The eventdata is a PhPointerEvent t structure (see the PhotonLibrary Reference) that can be fetched in the followingmanner:

PhPointerEvent t *ptr =(PhPointerEvent t *)PhGetData( cbinfo->event );

cbdata NULL


Pt CB RAW


PtRawCallback t * Link NULL

A list of PtRawCallback t structures that defines the raw callbacksthat the widget invokes if the event it receives matches the event maskprovided in the PtRawCallback t structure.



These callbacks are invoked after the widget has processed the event,even if the widget’s class methods consume it. Contrast this with thePt CB FILTER resource, which is invoked before the widgetprocesses the event.

�

You can add a Pt CB RAW callback to a widget in your application’scode by calling PtAddEventHandler() or PtAddEventHandlers(). Formore information about this callback, see “Event handlers” in theEvents chapter of the Photon Programmer’s Guide.


reason Pt CB RAW

event A pointer to a PhEvent t structure that describes theevent that caused the callback to be invoked. If thewidget’s class methods consumed the event,Ph CONSUMED is set in the event’s processing flagsmember.

cbdata NULL

These callbacks should return one of:

Pt CONSUME Consume the event and prevent furtherpropagation of it.

Pt CONTINUE Allow the event to be passed up to the widget’sparent.

Pt CB REALIZED





A list of PtCallback t structures that define the callbacks that thewidget invokes whenever it is realized.


reason Pt CB REALIZED


cbdata NULL


Pt CB UNREALIZED



A list of PtCallback t structures that define the callbacks that thewidget invokes whenever it’s unrealized.


reason Pt CB UNREALIZED


cbdata NULL



2004, QNX Software Systems Ltd. PtWindowAn application window that’s managed by the Photon Window Manager

Class hierarchy:PtWidget → PtBasic → PtContainer → PtDisjoint →PtWindow

PhAB icon:None — use PhAB’s Window or Dialog module.

Public header:<photon/PtWindow.h>

Description:The PtWindow class provides a top-level container for yourapplications’ widgets. It also provides a standard appearance for allwindows. Windows are managed by the Photon Window Manager ifit’s present (PtForwardWindowEvent() sends window events to theWindow Manager — see the Photon Library Reference).

A PtWindow widget that contains an editor application.

The frame and title bar aren’t part of the PtWindow widget; thewindow manager adds them. The value of the widget’s Pt ARG DIMresource doesn’t include the frame, but you can callPtWindowGetFrameSize() to determine the size of the frame.


PtWindow 2004, QNX Software Systems Ltd.

� Use PhAB’s Window module instead of using this widget directly.See “Window modules” in the Working with Modules chapter ofthe Photon Programmer’s Guide.

� A PtWindow is the top-level widget of the application. If you tryto use another class for the top-level widget (aside from aPtRegion), the behavior is undefined — you’ll likely get a fatalerror.

� In addition to the sections below, see the Window Managementchapter of the Photon Programmer’s Guide.

�

The PtWindow class handles the details of opening a Photon windowand displaying the widget hierarchy in it. It also tells the WindowManager what controls to place in the frame around the applicationwindow. This gives a standard appearance to the windows of allapplications using the Photon widget library.

Interacting with the Window Manager

Using resources, you can choose which elements of the windowframe will be displayed. You can control which window managementfunctions the Window Manager will perform, and whether they’reinvoked from the window menu or from one of the window controls.You can also have your application notified when the user hasrequested a window management function, regardless of whether ornot the Window Manager will perform that function.

You can specify the string displayed in the window’s title bar bySetting thewindow’s

titlesetting the Pt ARG WINDOW TITLE resource.

You control the elements displayed in the window frame using theControllingthe

decorationsPt ARG WINDOW RENDER FLAGS resource. Enable or disable awindow-frame element by setting or clearing the appropriate bit.

The Pt ARG WINDOW RENDER FLAGS resource also has one ofthe following bits set to specify how the window and its frame aredisplayed and behave:


2004, QNX Software Systems Ltd. PtWindow

� Ph WM RENDER ASAPP

� Ph WM RENDER ASDIALOG

� Ph WM RENDER ASICON

� Ph WM RENDER ASPALETTE

If you need to control the maximum and minimum possible sizes forControllingwindowresizing

the window, use the Pt ARG MAXIMUM DIM andPt ARG MINIMUM DIM resources defined by PtWidget.

The following resources also control the window’s size:

� Pt ARG MAX HEIGHT

� Pt ARG MAX WIDTH

� Pt ARG MIN HEIGHT

� Pt ARG MIN WIDTH

You can control how the Window Manager operates on your windowEnablingWindow

Managerfunctions

by setting Pt ARG WINDOW MANAGED FLAGS.

Every flag in the resource corresponds to an operation the WindowManager can perform on the window. If the flag is set, the WindowManager lets you perform that operation. If a flag isn’t set, theWindow Manager disables the operation.

Each operation is identified by the name of the flag thatenables/disables it. Here are the operations the Window Manager letsyou perform on a window:

Ph WM BACKDROP

Use the window as the backdrop for theworkspace.

Ph WM CLOSE Close the window. If the window is the mainwindow for the application, the application itselfis terminated.



Ph WM COLLAPSE

You can collapse the window to just the title bar.

Ph WM CONSWITCH

Move the window within the Photon coordinatespace so that it remains in the same position on thescreen when the workspace is moved in responseto a console-switch request.

Ph WM FOCUS Give focus to the window.

Ph WM HIDE Minimize/hide the window. You can restore thewindow by clicking on its button in therunning-tasks part of the shelf.

Ph WM MAX Maximize the window (i.e. make it fill the entirescreen).

Ph WM MOVE Move the window to a new location.

Ph WM NO FOCUS LIST

Prevent you from cycling focus to the window bypressing Alt – Esc, Alt – Shift – Esc, or Alt – Tab.

Ph WM RESIZE Change the size of the window.

Ph WM RESTORE

Restore the window to its state prior to an iconifyor maximize operation.

Ph WM TASKBAR

Taskbar applications should include this window.

Ph WM TERMINATE

Terminate the application. This operation is usedfor graceful shutdown of the windowing system.

Ph WM TOBACK Move the window to the back of the windowstacking order.



Ph WM TOFRONT

Move the window to the front of the windowstacking order.

You may also tell the Window Manager to notify the application afterNotifyingthe

applicationit has done a Window Manager operation. This behavior is controlledby the Pt ARG WINDOW NOTIFY FLAGS resource. This resourceconsists of the same set of flags as thePt ARG WINDOW MANAGED FLAGS resource.

Setting a flag in this resource tells the Window Manager that it shouldsend an event to the application whenever the correspondingoperation is performed on the window widget. The event sent to theapplication is handled by the window’s Pt CB WINDOW callbacks.

The callback data for these callbacks consists of a pointer to awindow event structure, PhWindowEvent t (described in the PhotonLibrary Reference).

Creating subwindows

Some parts of the UI, such as toolbars, palettes, or dialogs, may resideoutside the main application window in windows of their own. Thesewindows are usually subwindows of the main application window.

A subwindow is obtained by creating a window widget as the child ofanother window widget. A subwindow can’t be placed behind itsparent. The subwindows associated with a window are also iconifiedas a group whenever the window itself is iconified.

New resources:


Pt ARG MAX HEIGHT short Scalar 0 (See below)

continued. . .




Pt ARG MAX WIDTH short Scalar 0 (See below)

Pt ARG MIN HEIGHT short Scalar 0 (See below)

Pt ARG MIN WIDTH short Scalar 0 (See below)

Pt ARG WINDOW ACTIVE COLOR PgColor t Scalar See below

Pt ARG WINDOW FRONT WINDOW PhRid t Scalar 0

Pt ARG WINDOW HELP ROOT char * String NULL

Pt ARG WINDOW INACTIVE COLOR PgColor t Scalar See below.

Pt ARG WINDOW MANAGED FLAGS unsigned short Flag See below.

Pt ARG WINDOW NOTIFY FLAGS unsigned short Flag See below.

Pt ARG WINDOW RENDER FLAGS unsigned short Flag See below.

Pt ARG WINDOW STATE unsigned short Flag See below.

Pt ARG WINDOW TITLE char * String "Untitled"

Pt ARG WINDOW TITLE COLOR PgColor t Scalar See below.

Pt CB WINDOW PtCallback t * Link NULL

Pt CB WINDOW CLOSING PtCallback t * Link NULL

Pt CB WINDOW OPENING PtCallback t * Link NULL

Pt CB WINDOW TRANSPORT PtCallback t * Link NULL

Pt ARG MAX HEIGHT


short Scalar 0 (See below)

The maximum height of the window. If you set this resource to 0, thedefault value specified by the window manager is used.



You should use Pt ARG MAXIMUM DIM instead of this resource.�

Pt ARG MAX WIDTH


short Scalar 0 (see below)

The maximum width of the widget. If you set this resource to 0, thedefault value specified by the window manager is used.

You should use Pt ARG MAXIMUM DIM instead of this resource.�

Pt ARG MIN HEIGHT



The minimum height of the widget. If you set this resource to 0, thedefault value specified by the window manager is used.

You should use Pt ARG MINIMUM DIM instead of this resource.�

Pt ARG MIN WIDTH



The minimum width of the widget. If you set this resource to 0, thedefault value specified by the window manager is used.



You should use Pt ARG MINIMUM DIM instead of this resource.�

Pt ARG WINDOW ACTIVE COLOR


PgColor t Scalar Pg DEFAULT WM COLOR

The color of the window’s frame when the window has focus. Thisoverrides the color specified by the window manager.

Pt ARG WINDOW FRONT WINDOW


PhRid t Scalar 0

Specifies the region ID of the window that this window is to bepositioned behind.

Pt ARG WINDOW HELP ROOT


char * String NULL

Defines the root topic path for the window. For more information, seethe PtHelp*() functions in the Photon Library Reference and theContext-Sensitive Help chapter of the Photon Programmer’s Guide.

Pt ARG WINDOW INACTIVE COLOR



The color of the window’s frame when the window doesn’t havefocus. This overrides the color specified by the window manager.



Pt ARG WINDOW MANAGED FLAGS


unsigned short Flag Ph WM APP DEF MANAGED

Controls which actions the Window Manager performs for theapplication, but doesn’t affect whether or not the Window Managernotifies the application of those actions (for that, usePt ARG WINDOW NOTIFY FLAGS). You can set the following bits:

If you set this bit: the Window Manager:

Ph WM BACKDROP Allows the window to be theworkspace backdrop

Ph WM CLOSE Closes the application

Ph WM COLLAPSE Collapses the window to just the titlebar

Ph WM CONSWITCH Moves the window to keep it on thevisible display whenever the virtualPhoton console is switched

Ph WM FFRONT Allows the window to become forcefront. To make the base window forcefront, set Ph WM STATE ISFRONT inthe Pt ARG WINDOW STATEresource.

Ph WM FOCUS Handles gaining and losing focus forthis window

Ph WM HELP Provides context-sensitive help

Ph WM MAX Maximizes the window

Ph WM MENU Pops up the window menu

Ph WM MOVE Moves the window

continued. . .



If you set this bit: the Window Manager:

Ph WM NO FOCUS LIST Doesn’t let you cycle focus to thewindow when you press Alt – Esc, Alt –Shift – Esc, or Alt – Tab

Ph WM RESIZE Resizes the application

Ph WM RESTORE Restores the window after it has beeniconified, maximized, or hidden

Ph WM TASKBAR Includes the window in its taskbar

Ph WM TOBACK Sends the window to the back

Ph WM TOFRONT Sends the window to the front

Ph WM HIDE Hides the window

The default is Ph WM APP DEF MANAGED, a convenience manifestthat’s defined in <PhWm.h> as:

#define Ph WM APP DEF MANAGED ( Ph WM CLOSE | \Ph WM FOCUS | \Ph WM MENU | \Ph WM TOFRONT | \Ph WM TOBACK | \Ph WM RESIZE | \Ph WM MOVE | \Ph WM HIDE | \Ph WM MAX | \Ph WM RESTORE | \Ph WM TASKBAR | \Ph WM COLLAPSE)

Pt ARG WINDOW NOTIFY FLAGS


unsigned short Flag Ph WM RESIZE|Ph WM CLOSE|Ph WM HELP



This resource controls which events the Pt CB WINDOW callbacksare invoked for. This resource doesn’t cause the window manager toperform actions (for that, usePt ARG WINDOW MANAGED FLAGS).Pt ARG WINDOW NOTIFY FLAGS uses the same set of bits asPt ARG WINDOW MANAGED FLAGS, but the following bits haveno notification associated with them:

� Ph WM FFRONT

� Ph WM NO FOCUS LIST

� Ph WM TASKBAR

Pt ARG WINDOW RENDER FLAGS


unsigned short Flag Ph WM APP DEF RENDER

Controls how the Window Manager renders components of thewindow. The value of this resource is one of the following bits, whichdetermine how the window and its frame look and feel:

Ph WM RENDER ASAPP

Render the window as an application.

Ph WM RENDER ASDIALOG

Render it as a dialog.

Ph WM RENDER ASICON

Render it as an icon.

Ph WM RENDER ASPALETTE

Render it as a palette.

as well as any combination of the following bits:

Ph WM RENDER BORDER

Put a border around the window.



Ph WM RENDER CLOSE

If the window has a title bar, include a close button.

Ph WM RENDER COLLAPSE

If the window has a title bar, add a collapse button.

Ph WM RENDER HELP

If the window has a title bar, include a help button.

Ph WM RENDER INLINE

Add a black line just inside the standard borders.

Ph WM RENDER MAX

If the window has a title bar, include a maximize button.

Ph WM RENDER MENU

If the window has a title bar, include a menu button.

Ph WM RENDER MIN

If the window has a title bar, include a minimize button.

Ph WM RENDER RESIZE

If the window has a border, add resize handles.

Ph WM RENDER TITLE

If the window has a border, add a title bar.

The default value is Ph WM APP DEF RENDER, a conveniencemanifest that’s defined in <PhWm.h> as:

#define Ph WM APP DEF RENDER ( Ph WM RENDER ASAPP | \Ph WM RENDER BORDER | \Ph WM RENDER RESIZE | \Ph WM RENDER MOVE | \Ph WM RENDER CLOSE | \Ph WM RENDER TITLE | \Ph WM RENDER MENU | \Ph WM RENDER MIN | \Ph WM RENDER MAX | \Ph WM RENDER COLLAPSE)



Pt ARG WINDOW STATE


unsigned short Flag Ph WM STATE ISFOCUS

This resource controls the window’s state. You can set one of thefollowing:

Ph WM STATE ISALTKEY

Pass Alt function-key combinations to the application.

Ph WM STATE ISBACKDROP

Open as the workspace backdrop. SeePt ARG WINDOW MANAGED FLAGS.

Ph WM STATE ISBLOCKED

Block input to the window.

Ph WM STATE ISCOLLAPSE

Display just the window’s title bar.

Ph WM STATE ISFOCUS

Grant focus to the window when it’s opened if the cursor focusoption to the Window Manager is disabled (default is enabled).

Ph WM STATE ISFRONT

Open the base window in front of the windows of allapplications. Child windows will open behind the last forcedfront window in the family. SeePt ARG WINDOW MANAGED FLAGS.

Ph WM STATE ISHIDDEN

Open as a normal window but don’t display it.

Ph WM STATE ISICONIFIED

Open the window and iconify it.



Ph WM STATE ISMAX

Open as a maximized window.

You can get and set the state of the window at any time by using thisresource, but you might get unexpected results if the user is changingthe window state at the same time.

�

The safest time to use this resource to set the window state is beforethe window is realized. For example, you could set it when creatingthe PtWindow widget or in the window’sPt CB WINDOW OPENING callback. The setting will be in effectwhen the window is realized.

You can set Pt ARG WINDOW STATE after the window has beenrealized, basing your changes on what you think the current windowstate is, but it’s safer to tell the window manager how you want tochange the state, by calling:

PtForwardWindowEvent()

Change the state for the window associated with a given regionID

PtForwardWindowTaskEvent()

Change the state for a window associated with a given Photonconnection ID

Pt ARG WINDOW TITLE


char * String "Untitled"

The string that the Window Manager displays in the title bar.



Pt ARG WINDOW TITLE COLOR



The color of the window’s title (i.e. the text). This overrides the colorspecified by the window manager.

Pt CB WINDOW



A list of PtCallback t structures that define the callbacks that thewidget invokes when it receives an event from the Window Manager.See Pt ARG WINDOW NOTIFY FLAGS.


reason Pt CB WINDOW

reason subtype

0 (not used).


cbdata A pointer to a PhWindowEvent t (described in thePhoton Library Reference).


For an example of using this callback to verify that the user reallywants to exit the application, see “Notification callback” in theWindow Management chapter of the Photon Programmer’s Guide.



Pt CB WINDOW CLOSING



A list of PtCallback t structures that define the callbacks that thewidget invokes when the window is being closed. It’s invoked beforethe window’s region is removed. These callbacks are invoked whenthe window is about to unrealize for any reason. This includestransporting to another Photon and explicit calls to PtDestroyWidget()or PtUnrealizeWidget(). If you want to make sure in a WindowClosing callback that the window is actually being destroyed, checkthe Pt DESTROYED flag in Pt ARG FLAGS. You can also use thePt CB DESTROYED callback to know when a window is marked fordestruction, or Pt CB IS DESTROYED to know when it is beingdestroyed.

The Pt CB WINDOW CLOSING callbacks are invoked when thewindow is already closing. To be notified before the window is closed,use the Ph WM CLOSE bit in Pt ARG WINDOW NOTIFY FLAGSand the Pt CB WINDOW callback.

�


reason Pt CB WINDOW CLOSING

reason subtype

0 (not used).

event NULL (not supplied).

cbdata NULL (not supplied).




Pt CB WINDOW OPENING



A list of PtCallback t structures that define the callbacks that thewidget invokes when the window is being opened. If you want toresize the window and want anchoring to be in effect, do it in this typeof callback.

The window hasn’t been completely realized when thePt CB WINDOW OPENING callbacks are invoked; don’t change thewindow’s widget family hierarchy in these callbacks. If you need toadjust the widgets’ stacking order, do it in the Pt CB REALIZEDcallbacks.

�


reason Pt CB WINDOW OPENING

reason subtype

0 (not used)


cbdata NULL


Pt CB WINDOW TRANSPORT





A list of PtCallback t structures that define the callbacks that thewidget invokes when the window is being transported through a JumpGate.


reason Pt CB WINDOW TRANSPORT

reason subtype

0 (not used)

event A pointer to a PhEvent t structure that describes thePh EV WM event that caused the callback to be invoked.

cbdata Internal use only









Pt ARG BEVEL WIDTH PtWidget Not used by this class.


continued. . .















Pt ARG DIM PtWidget












continued. . .




Pt ARG MARGIN HEIGHT PtBasic Not used by this class.

Pt ARG MARGIN WIDTH PtBasic Not used by this class.





Pt ARG POS PtWidget

Pt ARG RESIZE FLAGS PtWidget |=Pt RESIZE XY AS REQUIRED









Pt CB ARM PtBasic






Pt CB DND PtWidget

continued. . .









Pt CB MENU PtBasic


Pt CB RAW PtWidget






Convenience functions:The PtWindow widget defines the following convenience functions:

PtWindowFocus()

Give a window focus.

PtWindowGetState()

Return the current state of a window.

PtWindowToBack()

Move a window to the back of the workspace.

PtWindowToFront()

Bring a window to the front and give it focus.


PtWindowFocus() 2004, QNX Software Systems Ltd.

Give a window focus

Synopsis:int PtWindowFocus( PtWidget t *widget );

Description:This function lets your application give focus to the specified windowwidget. To do this, the function sends a message to the WindowManager, telling it to give the window focus. The Window Managermay change consoles if the specified window isn’t in the currentconsole.

Returns:0 Successful completion.

-1 The window wasn’t found or an error occurred.

Examples:PtWidget t *my window;

/* give my window focus */if ( 0 == PtWindowFocus( my window ) ) {

/* focus related processing */}


Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtWindowFocus()

See also:PtWindowToBack(), PtWindowToFront()

PtForwardWindowEvent() in the Photon Library Reference


PtWindowGetState() 2004, QNX Software Systems Ltd.

Return the current state of a window

Synopsis:long PtWindowGetState( PtWidget t *widget )

Description:This function returns the current state of the window pointed to by thewidget variable:

State Description

Ph WM STATE ISHIDDEN The window is hidden.

Ph WM STATE ISMAX The window is maximized.

Ph WM STATE ISBACKDROP The window is a backdrop.

Ph WM STATE ISTASKBAR The window is a taskbar.

Ph WM STATE ISICONIFIED The window is iconified.

Ph WM STATE ISFRONT The window is the frontmost inthe family.

Ph WM STATE ISFOCUS The window has focus.

Returns:The current state of the window, or -1 if the widget isn’t a PtWindowor wasn’t realized.


Safety


Signal handler No

continued. . .


2004, QNX Software Systems Ltd. PtWindowGetState()

Safety

Thread No


PtWindowToBack() 2004, QNX Software Systems Ltd.

Move a window to the back of the workspace

Synopsis:void PtWindowToBack( PtWidget t *widget );

Description:This function moves the specified window widget and all its childwindows to the back of the workspace. To do this, the function sendsa message to the Window Manager.

There’s no way to move a window behind its parent window. If youwant to be able to move one window behind another in yourapplication, they must be siblings. For example, to make a window asibling rather than a child of the base window, set the window’s parentto NULL.

�


/* move my window to the back */PtWindowToBack( my window );


Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtWindowToBack()

See also:PtWindowFocus(), PtWindowToFront()

PtForwardWindowEvent(), PtWidgetToBack(), PtWidgetToFront() inthe Photon Library Reference


PtWindowToFront() 2004, QNX Software Systems Ltd.

Bring a window to the front and give it focus

Synopsis:void PtWindowToFront( PtWidget t *widget );

Description:This function brings the specified window widget and all its childwindows to the front of the workspace and gives the front windowfocus. To do this, the function sends a message to the WindowManager. The Window Manager may switch consoles if the specifiedwindow isn’t within the current workspace.

There’s no way to move a parent window in front of its child. If youwant to be able to move one window in front of another in yourapplication, they must be siblings. For example, to make a window asibling rather than a child of the base window, set the window’s parentto NULL.

�


/* bring my window to the front */PtWindowToFront( my window );


Safety


Signal handler No

Thread No


2004, QNX Software Systems Ltd. PtWindowToFront()

See also:PtWindowToBack(), PtWindowFocus()

PtForwardWindowEvent(), PtWidgetToBack(), PtWidgetToFront() inthe Photon Library Reference


Glossary

May 31, 2004 Glossary 1211


accelerator

See hotkey.

activate

A widget is usually activated when you release a mouse button whilepointing at an armed widget.

active window

The window that currently has focus.

anchor offset

The distance between the edges of a widget and the parent widget it’sanchored to.

anchor

A constraint mechanism used to manage what happens to a widgetwhen its parent is expanded or contracted. For example, a pane that’sanchored to the sides of a window expands or contracts as thewindow’s size is changed.

application region

A region that belongs to a Photon application (as opposed to a Photonsystem 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 widgetresources.

arm

A widget is usually armed when you press a mouse button whilepointing at it.



backdrop

An image that’s displayed as a background on your screen.

backdrop region

A region placed behind all windows to display a background image.

balloon

A small box that pops up to define or explain part of the user interface.A balloon is displayed when the pointer pauses over a widget.

bitmap

A color picture consisting of one or more bitplanes.

bitplane

An array of bits representing pixels of a single color in a bitmap.

blit

An operation that moves an area of a graphics context (e.g. thescreen) to another area on the same or a different context.

callback

A callback function or a callback resource.

callback function

Code connecting an application’s user interface to its code. Forexample, a callback is invoked when you press a button.

callback resource

A resource that specifies a list of functions and their client data to becalled when a certain action occurs.

canvas

The part of a widget that’s used for drawing. For PtWidget, this isthe area inside the widget’s borders. For PtBasic and itsdescendants, the canvas is the area inside the widget’s border and

1214 Glossary May 31, 2004


margins. Other widgets, such as PtLabel, may define additionalmargins.

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

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 awidget’s callback list is invoked.

color depth

The number of bits per pixel for a screen or pixmap.



Common User Access

See CUA.

compose sequence

A sequence of key presses that can be used to type a character thatmight 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 widgetfrom interacting with the event, the first widget is said to haveconsumed the event.

container

A widget that can have other widgets as children. For example,PtWindow, PtGroup, and PtOSContainer.

cooked event

A key or pointer event that has been assigned a location in the Photonevent space. Also called a focused event.

CUA

Common User Access — a standard that defines how you can changefocus by using the keyboard.

current item

The item in a list or tree widget that will be selected (or perhapsunselected) when you press Enter or Space. It’s typically drawn witha blue dotted line around it when its widget has focus.



cursor

An indicator of a position on a screen, such as a pointer or aninsertion point in a text field.

damaged

Whenever a widget needs to be redisplayed due to a change in thewindow (e.g. the widget is changed, moved, or realized), it’s said tobe damaged.

dead key

A key that, when pressed, doesn’t produce a symbol, but initiates acompose sequence.

default placement

The placement of a region when no siblings are specified. Theopposite of specific placement.

desktop

The virtual screen, consisting of nine consoles or workspaces.

device region

The region located in the middle of the event space, with applicationregions behind it and driver regions in front of it (from the user’spoint of view).

dialog module

A PhAB module similar to a window module, except that a dialogmodule can have only one instance per process.

direct-color

A color scheme in which each pixel is represented by an RGB value.Contrast palette-based.



disjoint parent

A disjoint widget that’s the ancestor of another widget.

disjoint widget

A widget that can exist without a parent. If a disjoint widget has aparent, it can exist outside its parent’s canvas. For example,PtWindow, PtMenu, and PtRegion are disjoint widgets, butPtButton, PtBkgd, and PtRect aren’t.

A disjoint widget owns regions that aren’t children of its parent’sregions. Any clipping set by the parent of a disjoint widget isn’tapplied to the disjoint widget. The regions of disjoint widgets aresensitive and opaque to expose events.

dithering

A process whereby pixels of two colors are combined to create atexture or a blended color.

draw context

A structure that defines the flow of the draw stream. The default drawcontext emits draw events to graphics drivers. Print contexts andmemory contexts are types of draw contexts.

draw stream

A series of tokens that are dispatched via draw events and can becollected by a rendering engine such as a graphics driver.

driver region

A region created by a driver, usually placed in front of the deviceregion.

encapsulation driver

A program that displays Photon graphical output inside anotherwindowing system such as the X Window System.



event

A data structure that represents an interaction between you and anapplication or between applications. Events travel through the eventspace either toward you or away (i.e. toward the root region).

event compression

The merging of events such that the application sees only their latestvalues. The application doesn’t have to process many unnecessaryevents.

event handler

A callback function that lets an application respond directly to Photonevents, such as dragging events.

event mask

A set of event types that are of interest to an event handler. Whenone of these events occurs, the event handler is invoked.

event space

An abstract, three-dimensional space that contains regions — fromthe root region at the back to the graphics region at the front. You sitoutside the event space, looking in from the front. Events travelthrough the event space either toward the root region or toward you.

exported subordinate child

A widget created by a container widget (as opposed to an application)whose resources you can access only through the parent.

exposure

Typically occurs when a region is destroyed, resized, or moved.Expose events are sent to applications to inform them when thecontents of their regions need to be redisplayed.



extent

A rectangle that describes the outermost edges of a widget.

File Manager

The Photon File Manager (PFM), an application used to maintain andorganize files and directories.

focus

A widget that has focus will receive any key events collected by itswindow.

focus region

A region placed just behind the device region by the PhotonWindow Manager that lets it intercept key events and direct them tothe active window.

focused event

A key or pointer event that has been assigned a location in the Photonevent 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 itsdescendants, which depends on the widget’s layout policy, any sizeset for the widget, and the dimensions and desired positions of each ofthe widget’s children.



global header file

A header file that’s included in all code generated by PhAB for anapplication. The global header file is specified in PhAB’s ApplicationStartup Information dialog.

graphics driver

A program that places a region that’s sensitive to draw events on theuser’s side of the device region, collects draw events, and renders thegraphical 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 menuitem) without actually selecting a widget. Also called an accelerator.Contrast keyboard shortcut.

hotspot

The part of the pointer that corresponds to the coordinates reportedfor the pointer (e.g. the intersection of crosshairs, or the tip of thearrow of the basic pointer).

HSB

Hue-Saturation-Brightness color model.

HSV

Hue-Saturation-Value color model.



icon module

A PhAB module that associates icons with an application.

image

A rectangular array of color values, where each element represents asingle pixel. See also direct-color and palette-based.

initialization function

In a PhAB application, a function that’s called before any widgets arecreated.

input driver

A program that emits, and is the source of, key and/or pointer events.

input group

A set of input and output devices. There’s typically one input groupper user.

input handler (or input-handling function)

A function that’s hooked into Photon’s main event-processing loop tohandle messages and pulses sent to the application by other processes.

instance

A concrete example of an abstract class; for example, “Lassie” is aninstance of the class “dog.” In Photon, an instance is usually a widgetinstance; for example, a pushbutton is an instance of the PtButtonwidget class. When an instance of a widget is created, the initialvalues of its resources are assigned.

instance name

In PhAB, a string that identifies a particular instance of a widget sothat you can access the instance in your application’s code.



instantiation

The action of creating an instance of a widget class in an application.

internal link

A PhAB mechanism that lets a developer access a PhAB moduledirectly from an application’s code.

Image Viewer

A Photon application (pv) that displays images.

key modifier

A flag in a key event that indicates the state of the correspondingmodifier key when another key was pressed.

keyboard driver

A program that gets information from the keyboard hardware, buildsPhoton key events, and emits them towards the root region.

keyboard shortcut

A key that selects a menu item. The shortcut works only if the menuis displayed. Contrast hotkey.

language database

A file that contains the text strings used in a PhAB application; alanguage database makes it easier to create multilingual applicationswith PhAB’s language editor.

link callback

A mechanism that connects different parts of a PhAB application. Forexample, a link callback can be invoked to display a dialog when abutton is pressed.



margin

The area between a widget’s border and canvas.

memory context

A draw context in which Photon draw events are directed to memoryfor future displaying on the screen, as opposed to a printer (printcontext) or to the screen directly (the default draw context).

menu module

A PhAB module used to create a menu.

method

A function that’s internal to a widget class and invoked under specificconditions (e.g. to draw the widget). Methods are provided aspointers to functions in widget class records.

modifier key

A key (such as Shift, Alt, or Ctrl) used to change the meaning ofanother key.

module

An object in PhAB that holds an application’s widgets. PhABmodules 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, buildsPhoton raw pointer events, and emits them towards the root region.

opaque

The state of a region with regard to events. If a region is opaque to anevent type, any event of that type that intersects with the region has its



rectangle set adjusted to clip out the intersecting area. The regionprevents the event from passing through.

palette

An array of colors. A hard palette is in hardware; a soft palette is insoftware.

palette-based

A color scheme in which each pixel is represented by an index into apalette. Contrast direct-color.

PDR

See Press-drag-release.

PFM

See Photon File Manager.

PhAB

Photon Application Builder. Visual design tool that generates thecode required to implement a user interface.

phditto

A utility that accesses the Photon workspace on a remote node. Seealso ditto.

Phindows

Photon in Windows. An application that accesses a Photon sessionfrom a Microsoft Windows environment.

Photon File Manager (PFM)

An application used to maintain and organize files and directories.



Photon Manager or server

The program that maintains the Photon event space by managingregions and events.

Photon Terminal

An application (pterm) that emulates a character-mode terminal in aPhoton window.

Photon Window Manager (PWM)

An application that manages the appearance of window frames andother objects on the screen. For example, the window manager addsthe resize bars, title bar, and various buttons to an application’swindow. The window manager also provides a method of focusingkeyboard events.

picture module

A PhAB module that contains an arrangement of widgets that can bedisplayed in another widget or used as a widget database.

pixmap

A bitmap or image.

plane mask

A mask used to restrict graphics operations to affect only a subset ofcolor 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 severalpointers 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 buttonwhile pointing to a menu button, dragging until the desired item ishighlighted, and releasing the mouse button.

print context

A draw context in which Photon draw events are directed to a file, asopposed to the screen (the default draw context) or to memory(memory context).

printer driver

A program that converts Photon draw stream format into a formatsuitable for a printer, including PostScript, Hewlett-Packard PCL, andCanon.

procreated widget

A widget created by another widget (as opposed to an application),such as the PtList and PtText created by a PtComboBox. Alsoknown as a subordinate child.

pterm

A Photon Terminal; an application that emulates a character-modeterminal in a Photon window.

pulse

A small message that doesn’t require a reply; used for asynchronouscommunication 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 Photonevent space. Also called an unfocused event.

raw callback

A function that lets an application respond directly to Photon eventssuch as dragging events. Also called an event handler.

realize

To display a widget and its descendants, possibly making theminteractive.

rectangle set

An array of nonoverlapping rectangles associated with an event.

region

A rectangular area within the Photon event space that’s used by anapplication for collecting and emitting events.

resize policy

A rule that governs how a widget resizes itself when its contentschange.

resource

An attribute of a widget, such as fill color, dimensions, or a callbacklist.

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 aparticular type of event, the region’s owner collects a copy of anysuch event that intersects with the region.



setup function

A function that’s called after a PhAB module is created.

shelf

An application that attaches areas to the outside edge of the screen.You can add plugins to customize these areas, such as a taskbar,launcher, clock, and magnifier.

Snapshot

A Photon application for capturing images of the screen.

specific placement

The placement of a region when one or more siblings are specified.The opposite of default placement.

subordinate child

A widget created by another widget (as opposed to an application),such as the PtList and PtText created by a PtComboBox. Alsoknown as a procreated widget.

table-of-contents (TOC) file

In the Photon Helpviewer, a file that describes a hierarchy of helptopics.

taskbar

A shelf plugin that displays icons representing the applications thatare currently running.

tile

A data structure used to build linked lists of rectangles, such as a listof the damaged parts of an interface.



topic path

Help information identified by a string of titles that are separated byslashes.

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’sone translation file per language supported by the application.

unfocused event

See raw event.

Unicode

The ISO/IEC 10646 16-bit encoding scheme for representing thecharacters used in most languages.

UTF-8

The encoding for Unicode characters, where each character isrepresented by one, two, or three bytes.

widget

A component (e.g. a pushbutton) in a graphical user interface.

widget class

A template for widgets that perform similar functions and provide thesame public interface. For example, PtButton is a widget class.



widget database

In PhAB, a module containing widgets that can be copied at any timeinto a window, dialog, or other container.

widget family

A hierarchy of widget instances. For example, a window and thewidgets it contains.

widget instance

See instance.

window frame region

A region that PWM adds to a window. It lets you move, resize,iconify, and close the window.

Window Manager

See Photon Window Manager.

window module

A PhAB module that’s instantiated as a PtWindow widget.

window region

A region that belongs to an application window.

work procedure

A function that’s invoked when there are no Photon events pendingfor an application.

workspace

See console.

workspace menu

A configurable menu that’s displayed when you press or click theright mouse button while pointing at the background of the desktop.


Index

!

“set” state 1161Pt CB ACTIVATE 59

A

accelerators 438menu items 486

activationany mouse button 1158defined 43Pt CB ACTIVATE 59, 922

anchor flags 1152, 1153anchor offsets 1152, 1153animation See PtFlasharc widget See PtArcarea 1148, 1154arming

defined 43Pt CB ARM 60

arrow keysdisablingPtGroup 424

PtScrollArea 752enablingPtContainer 177

PtMeter 523, 524PtText 887PtTextSetSelection() 914

autohighlighting 1158

B

Bezier curve widget SeePtBezier

backgroundcolor 54pattern 55, 411widget See PtBkgd

balloonscallback 185customizing 440disabling 177fill color 438popping up immediately 1153position 436, 439PtBalloonCallback t 5

May 31, 2004 Index 1233

Index 2004, QNX Software Systems Ltd.

text 439text color 438

bandwidth, graphics threshold 48bar graph widget See PtBarGraphbasic widget See PtBasicbevel

colormain 52

full 49rendering 49width 49, 1154

bevel color 53, 56bevels

static 51bitmap widget

label See PtLabelblocking 1158

hotkeys 1176Pt CB BLOCKED 1170

bordercolor

inline 55outline 57

roundness 55browse mode 308browser

see PtWebClient 1052button widget

menu See PtMenuButtonon/off See PtOnOffButtonpushbutton See PtButtontoggle See PtToggleButton

C

calendar widget See PtCalendarcallbacks

activate 59, 922arguments 7arm 60balloon 185blocked 1170child added/removed 186destroyed 1170, 1177disarm 61drag and drop 1171filter 1174getting focus 187got focus 62, 886hotkey 1176invoking when resources are

set 1158losing focus 189lost focus 63, 886menu 44, 64outbound 1177PtBalloonCallback t 5PtCallback t 7PtCallbackInfo t 9PtHotkeyCallback t 11PtRawCallback t 13raw 1178realized 1180repeat 44, 65resizing 190return value 8right mouse button 44, 64unrealized 1180

canvasdetermining

1234 Index May 31, 2004

2004, QNX Software Systems Ltd. Index

PtScrollArea 761child added/removed callback 186chord 30circle widget See PtEllipseclass hierarchy 17clipped highlighting rectangle 1159clock widget See PtClockcolor

background 54bevel 53, 56

main 52border

inline 55outline 57

fill 54, 56font selector

text 282text background 282

foreground 52models 136

color selectors SeePtColorPanel, SeePtColorPatch, SeePtColorSelGroup, SeePtColorSel, SeePtColorWell

color-gradient widget See PtBkgdcolumn widget See PtGroupcombobox widget See

PtComboBox

compound widget See alsoPtCompound

procreated child 1160container widget

flags 177, 184general purpose See

PtContainer

offscreen-context SeePtOSContainer

contrast 53contrast, bevel 52contributed widgets xixcreating a drawing 406Ctrl-click selection 308CUA (Common User Access)

enabling 177enabling arrow keys 177preventing focusing 177

cursorbitmap 1155color 1155type 1155

D

damagefamily 1159parent 1157widget 1159

dashed lines 410data, user-defined 922, 1149, 1166,

1169PtRaw 702

destructionmarking for 1159Pt CB DESTROYED 1170Pt CB IS DESTROYED 1177

device emulator widget See PtTtydimensions 1148, 1154, 1156,

1164, 1170maximum 1149, 1165minimum 1149, 1166

May 31, 2004 Index 1235


dimming 58, 411, 1159disarming

defined 43Pt CB DISARM 61

disjoint widget See PtDisjointdivider widget See PtDividerdrag and drop

Pt CB DND 1171Pt CB OUTBOUND 1177

draggingPt CB OUTBOUND 1177

drawingcolor 52flicker-free See

PtOSContainer

using graphical widgets 404,406

using primitive graphicsfunctions 701

E

edgesalpha line 49bevel 49inline 50, 55outline 49, 57

edit masks 889ellipse widget See PtEllipseelliptical arc widget See PtArcevents

blocking 1158, 1170consuming 1157, 1179filter callbacks 1174PtRawCallback t 13

hotkeyscallback 1176PtHotkeyCallback t 11terminating searches for 178

keyconsuming 303processing as hotkeys

first 178pendingPtFileSel 228

Ph EV BUT REPEAT 65raw callbacks 1178PtRawCallback t 13

repeat callback 65window manager 1185, 1190,

1195extended flags 1157extended-selection mode 308extent 1148, 1157. See also

resizingno intersections with 1159recalculating

automatically 177

F

FD CLOEXEC 1040, 1042file folder widget See PtTabfile selector widget See

PtFileSel

fillcolor 54flat 51gradient 51pattern 55, 411

1236 Index May 31, 2004


reverse gradient 51fill color 54, 56filter callback 1174filter callbacks 13flags

anchor 1152, 1153container 177, 184extended 1157generic list 303generic list column 301generic tree 358, 384graphic 410group 424

alignment in cells 423menu 497PtColorPanel 125PtColorPatch 130PtColorSelGroup 144PtColorWell 149PtRawList 713region 744resize 1167widget 1158

flicker-free drawing SeePtOSContainer

floating-point number widget SeePtNumericFloat

flux 1160focus

getting 1158granting 1159Pt CB CHILD GETTING FOCUS

187Pt CB CHILD LOSING FOCUS

189Pt CB GOT FOCUS 62, 886Pt CB LOST FOCUS 63, 886

Pt GEN LIST NO AUTOFOCUS714

rendering 1159font selector widget See

PtFontSel

force front 1189, 1193foreground color 52FORM-CHECKBOX 1140FORM-COMBO 1140FORM-CURSOR-BOTTOM 1140FORM-CURSOR-LEFT 1140FORM-CURSOR-RIGHT 1140FORM-CURSOR-TOP 1140FORM-EDIT 1139FORM-LIST 1140FORM-MULTILIST 1140FORM-PASS 1140FORM-RADIO 1140FORM-RESET 1140FORM-SUBMIT 1140FORM-TEXTAREA 1140FRAMESET-DOC 1140

G

gauge widget See PtGaugegeneric list widget See

PtGenList

generic tree widget SeePtGenTree

ghosting 58, 411, 1159gradient

fill 51static 51

graphics

May 31, 2004 Index 1237


bandwidth threshold 48vector 404

graphics primitives functions 701graphics primitives widget

arc See PtArcBezier curve See PtBeziercircle, ellipse See PtEllipseflags 410line See PtLinepixels See PtPixelpolygon See PtPolygonrectangle See PtRectsuperclass See PtGraphic

grid widget See PtGridgroup widget See PtGroup

H

height 1148, 1154, 1156, 1164maximum 1149, 1165minimum 1149, 1166

helpbutton 1192in a balloon 1157information 1165root 1188topic path 1164

highlightingautomatically 1158clipping corners 1159requesting 1160

HOST NOT FOUND 1070hotkeys

accelerator key 438blocking 1176

callback 1176menu items 486PtHotkeyCallback t 11terminating searches for 178

hyperlinks 555

I

image widgetbackground See PtBkgdlabel See PtLabel

insert mode 877integer widget See

PtNumericInteger

J

Jump Gate 1197

K

key eventsconsuming 303processing as hotkeys first 178

L

label widget See PtLabellayouts

PtWidget 1157line widget See PtLine

1238 Index May 31, 2004


lines, dashed 410LINK-IMAGE 1140LINK-IMAGE-MAP 1140LINK-TEXT 1140List Draw method

PtList 330list widget

superclass See PtGenListtext items See PtListwith text-entry field See

PtComboBox

list, raw See PtRawList

M

Macromedia Flash 4 See PtFlashmargins

height 57width 57

matrix widget See PtGroupMAX URL LENGTH 1069memory context 633memory, freeing

when destroying awidget 1177

menuenabling mouse button 1160item, indicating 1160Pt CB MENU 44, 64

menu bar widget See PtMenuBarmenu button widget See

PtMenuButton

menu widget See PtMenumeter widget See PtMetermethods

List DrawPtList 330

Tree Item Statetree widgets 374, 376

mouseleft button actions 43

click count 60Pt CB ACTIVATE 59, 922Pt CB ARM 60Pt CB DISARM 61

making actions the same for allbuttons 44, 1158

right button action 44, 1160Pt CB MENU 44, 64

multiline text widget SeePtMultiText

multiple choice widget SeePtComboBox

multiple-select mode 308

N

navigation See CUA (CommonUser Access)

NO DATA 1071NO RECOVERY 1071numeric widget

floating-point SeePtNumericFloat

integer SeePtNumericInteger

range of values SeePtSlider

superclass See PtNumeric

May 31, 2004 Index 1239


O

obscuring 1160offscreen-context container widget

See PtOSContaineron/off button widget See

PtOnOffButton

opacity 1160

P

PAGE-BOTTOM 1141PAGE-LEFT 1141PAGE-RIGHT 1141PAGE-TOP 1141pane widget See PtFlash, See

PtPane

panels See PtPanelGrouppasswords, entering into a

PtText 883pattern

background 55, 411fill 55, 411transparency 58, 411

Pg BEVEL JOIN 412Pg BITMAP BACKFILL 435Pg BITMAP TRANSPARENT 435Pg BUTT CAP 412Pg BUTT JOIN 412Pg CLOSED 69, 669Pg CM CMYK 137Pg CM HLS 136Pg CM HSB 136Pg CM RGB 136PgColor t 581, 583Pg IMAGE DIRECT 555 435

Pg IMAGE DIRECT 664 435Pg IMAGE DIRECT 888 435Pg IMAGE DIRECT 8888 435Pg IMAGE PALETTE BYTE 435Pg IMAGE PALETTE NIBBLE 435Pg MITER JOIN 412Pg POLY RELATIVE 669Pg QROUND JOIN 412Pg RELATIVE 69Pg ROUND CAP 412Pg ROUND JOIN 412Pg SQUARE CAP 412Ph AUXPTR REGION 744Ph BAUD SLOW 768Ph CONSUMED 1179Ph CURSOR BITMAP 1155PhCursorDef t 1155Ph CURSOR INHERIT 1155Ph CURSOR NO INHERIT 1156Ph CURSOR SET 744Ph EV BOUNDARY 185, 186Ph EV DND CANCEL 1172Ph EV DND COMPLETE 1172Ph EV DND DROP 1172Ph EV DND ENTER 1172Ph EV DND LEAVE 1172Ph EV DND MOTION 1172Ph EV PTR MOTION NOBUTTON 186Ph EV PTR STEADY 185Ph FOLLOW IG SIZE 744Ph FORCE BOUNDARY 186, 744Ph FORCE FRONT 744Ph GRAFX REGION 744Ph INPUTGROUP REGION 744Ph KBD REGION 744Ph NO COMPRESSION 744Ph PRINT REGION 744

1240 Index May 31, 2004


Ph PTR REGION 744Ph WINDOW REGION 744Ph WM APP DEF MANAGED 1190Ph WM BACKDROP 1189Ph WM CLOSE 1189Ph WM COLLAPSE 1189Ph WM CONSWITCH 1189Ph WM FFRONT 1189, 1191Ph WM FOCUS 1189Ph WM HELP 1189Ph WM HIDE 1189Ph WM MAX 1189Ph WM MENU 1189Ph WM MOVE 1189Ph WM NO FOCUS LIST 1189,

1191Ph WM RENDER ASAPP 1183,

1191Ph WM RENDER ASDIALOG 1183,

1191Ph WM RENDER ASICON 1183,

1191Ph WM RENDER ASPALETTE 1183,

1191Ph WM RENDER BORDER 1191Ph WM RENDER CLOSE 1192Ph WM RENDER COLLAPSE 1192Ph WM RENDER HELP 1192Ph WM RENDER INLINE 1192Ph WM RENDER MAX 1192Ph WM RENDER MENU 1192Ph WM RENDER MIN 1192Ph WM RENDER RESIZE 1192Ph WM RENDER TITLE 1192Ph WM RESIZE 1189Ph WM RESTORE 1189Ph WM STATE ISALTKEY 1193

Ph WM STATE ISBACKDROP 1193Ph WM STATE ISBLOCKED 1193Ph WM STATE ISCOLLAPSE 1193Ph WM STATE ISFOCUS 1193Ph WM STATE ISFRONT 1193Ph WM STATE ISHIDDEN 1193Ph WM STATE ISICONIFIED 1193Ph WM STATE ISMAX 1194Ph WM TASKBAR 1189, 1191Ph WM TOBACK 1189Ph WM TOFRONT 1189Ph WND MGR REGION 744pie wedge 30pixel widget See PtPixelPk Cyrillic IO 281pointer

left button actions 43click count 60Pt CB ACTIVATE 59, 922Pt CB ARM 60Pt CB DISARM 61

making actions the same for allbuttons 44, 1158

right button action 44, 1160Pt CB MENU 44, 64

points widget See PtPixelpolygon widget See PtPolygonposition 1148, 1154, 1166PpPrintContext t 677primitive graphics functions 701print selector widget See

PtPrintSel

procreated child 1160progress widget See PtProgressPt ALL 50Pt ALL BEVELS 50Pt ALL BOTTOM 50

May 31, 2004 Index 1241


Pt ALL BUTTONS 44, 65, 1158Pt ALL ETCHED 50Pt ALL ETCHES 50Pt ALL INLINES 50Pt ALL LEFT 50Pt ALL OUTLINES 50Pt ALL RIGHT 50Pt ALL TOP 50PtArc 28

control points 28end angle 29Pt ARG ARC END 29Pt ARG ARC START 30Pt ARG ARC TYPE 30Pt ARG DIM 28Pt ARG ORIGIN 28Pt ARG POINTS 28start angle 30type 30

Pt ARC CHORD 30Pt ARC CURVE 30Pt ARC PIE 30Pt ARG ACCEL FONT 509Pt ARG ACCEL KEY

PtLabel 438PtMenuButton 508

Pt ARG ACCEL TEXT 509Pt ARG ANCHOR FLAGS 1152,

1153Pt ARG ANCHOR OFFSETS

1152, 1153Pt ARG ARC END 29Pt ARG ARC START 30Pt ARG ARC TYPE 30Pt ARG AREA

PtScrollArea 750, 753, 754PtTerminal 822, 823

PtWidget 1148, 1153, 1154Pt ARG ARM COLOR 81, 82Pt ARG ARM FILL 81, 82Pt ARG ARM IMAGE 81, 82Pt ARG BALLOON COLOR

PtGenList 301PtLabel 438

Pt ARG BALLOON FILL COLORPtGenList 301PtLabel 438

Pt ARG BALLOON POSITION432, 436, 439

Pt ARG BALLOON TEXT 439Pt ARG BANDWIDTH THRESHOLD

PtBasic 48PtDivider 207PtScrollbar 772PtTerminal 828, 856PtTty 1050

Pt ARG BARGRAPH BASEPtBarGraph 36

Pt ARG BARGRAPH COLORPtBarGraph 35, 36

Pt ARG BARGRAPH DATAPtBarGraph 34, 36

Pt ARG BARGRAPH DEPTHPtBarGraph 37

Pt ARG BARGRAPH FLAGSPtBarGraph 37

Pt ARG BARGRAPH GRID COLORPtBarGraph 38

Pt ARG BARGRAPH GRID HORIZPtBarGraph 38

Pt ARG BARGRAPH GRID VERTPtBarGraph 38

Pt ARG BARGRAPH MAXPtBarGraph 38

1242 Index May 31, 2004


Pt ARG BARGRAPH MINPtBarGraph 39

Pt ARG BEVEL COLOR 52Pt ARG BEVEL CONTRAST

PtBasic 52Pt ARG BEVEL WIDTH

PtBasic 49PtMenu 498PtWidget 1154

Pt ARG BEZIER FLAGS 69Pt ARG BITMAP CURSOR 1155Pt ARG BKGD IMAGE 74Pt ARG BKGD SPACING X 75Pt ARG BKGD SPACING Y 75Pt ARG BKGD TILE 75Pt ARG BUTTON TYPE 492, 509Pt ARG CALENDAR COLOR1 90Pt ARG CALENDAR COLOR2 90Pt ARG CALENDAR COLOR3 90Pt ARG CALENDAR COLOR4 90Pt ARG CALENDAR COLOR5 91Pt ARG CALENDAR DATE 91Pt ARG CALENDAR FLAGS 92Pt ARG CALENDAR FONT1 92Pt ARG CALENDAR FONT2 93Pt ARG CALENDAR FONT3 93Pt ARG CALENDAR FONT4 93Pt ARG CALENDAR FONT5 93Pt ARG CALENDAR HIGHLIGHT

93Pt ARG CALENDAR MONTH BTN COLOR

94Pt ARG CALENDAR MONTH NAMES

94Pt ARG CALENDAR SEL COLOR

95Pt ARG CALENDAR TIME T 95

Pt ARG CALENDAR WDAY NAMES96

Pt ARG CALENDAR YEAR BTN COLOR97

Pt ARG CBOX BUTTON WIDTH157

Pt ARG CBOX FLAGS 155, 157Pt ARG CBOX MAX VISIBLE COUNT

158Pt ARG CBOX SEL ITEM 158Pt ARG CBOX TEXT FILL COLOR

159Pt ARG CELL HORZ ALIGN 423Pt ARG CELL VERT ALIGN 423Pt ARG CLIENT FLAGS

PtClient 103Pt ARG CLIENT NAME 103, 104,

106Pt ARG CLIENT REPLY LEN

PtClient 104Pt ARG CLIENT SEND

PtClient 104Pt ARG CLIENT SERVER

PtClient 105Pt ARG CLOCK FACE COLOR

114Pt ARG CLOCK FACE OUTLINE COLOR

114Pt ARG CLOCK FLAGS 114Pt ARG CLOCK FONT 115Pt ARG CLOCK HOUR 115Pt ARG CLOCK HOUR COLOR

116Pt ARG CLOCK HOUR OFFSET

116Pt ARG CLOCK MINUTE 116

May 31, 2004 Index 1243


Pt ARG CLOCK MINUTE COLOR116

Pt ARG CLOCK MINUTE OFFSET117

Pt ARG CLOCK SECOND 117Pt ARG CLOCK SECOND COLOR

117Pt ARG CLOCK SECOND OFFSET

117Pt ARG CLOCK SEP1 118Pt ARG CLOCK SEP1 COLOR


118Pt ARG CLOCK TYPE 119Pt ARG COLOR

PtBarGraph 35, 36PtBasic 52PtMultiText 549, 582, 584PtRaw 704PtTrend 1017

Pt ARG COLUMNS 892Pt ARG CONTAINER FLAGS

177, 184Pt ARG CONTRAST

PtBasic 53Pt ARG CPANEL FLAGS

PtColorPanel 125Pt ARG CPATCH FLAGS

PtColorPatch 130Pt ARG CS COLOR

PtColorSel 136Pt ARG CS CURRENT MODEL

PtColorSel 137Pt ARG CS FLAGS

PtColorSel 137

Pt ARG CSGROUP FLAGSPtColorSelGroup 144

Pt ARG CS PALETTEPtColorSel 138

Pt ARG CURSOR COLOR 1155Pt ARG CURSOR OVERRIDE

178Pt ARG CURSOR POSITION 893Pt ARG CURSOR TYPE 1155Pt ARG CWELL FLAGS

PtColorWell 149Pt ARG CWELL SWATCH DIM

PtColorWell 149Pt ARG DARK BEVEL COLOR

PtBasic 53Pt ARG DARK FILL COLOR

PtBasic 54Pt ARG DASH LIST

PtGraphic 410Pt ARG DASH SCALE

PtGraphic 410Pt ARG DATA 1156Pt ARG DIM

PtArc 28PtEllipse 208PtMultiText 557PtRect 736PtTerminal 822–824, 826PtText 892PtWidget 1148, 1156

Pt ARG DIVIDER FLAGS 201Pt ARG DIVIDER OFFSET 202Pt ARG DIVIDER SIZES 202Pt ARG EDIT MASK 889, 893Pt ARG EFLAGS 1157, 1164Pt ARG EXTENT

PtWidget 1148, 1157

1244 Index May 31, 2004


Pt ARG FILL COLORPtBasic 54PtMultiText 549, 582, 584PtOSContainer 636PtRaw 704PtTerminal 856PtTrend 1016

Pt ARG FILL LAYOUT INFO180

Pt ARG FILL PATTERN 55Pt ARG FLAGS 1171

menu items 486PtBasic 43, 44, 59, 65PtClock 119PtContainer 187PtDivider 202PtFontSel 282PtGauge 291PtGenList 311PtMenu 488PtMeter 523, 524PtMultiText 571PtOnOffButton 628PtPanelGroup 650PtScrollArea 756PtScrollbar 767PtSlider 806PtText 880, 888, 897,

899–901, 906, 912PtToggleButton 921PtTty 1030PtWidget 1158

Pt ARG FLASH FILE 272Pt ARG FONT DISPLAY 278Pt ARG FONT FLAGS 279Pt ARG FONT LBL BKGDCOLOR

280

Pt ARG FONT LBL FONT 280Pt ARG FONT LBL SIZE 280Pt ARG FONT LBL STYLE 280Pt ARG FONT LBL TEXTCOLOR

280Pt ARG FONT NAME 281Pt ARG FONT POINT SIZE MAX

281Pt ARG FONT SAMPLE 281Pt ARG FONT SYMBOL 281Pt ARG FONT TEXT BKGD COLOR

282Pt ARG FONT TEXT COLOR

282Pt ARG FS FILE SPEC 222Pt ARG FS FLAGS 214, 222Pt ARG FS FORMAT 223Pt ARG FS IMAGES 224Pt ARG FS LBL DATE 226Pt ARG FS LBL GROUP 226Pt ARG FS LBL NAME 226Pt ARG FS LBL OWNER 227Pt ARG FS LBL PERMISSIONS

227Pt ARG FS LBL SIZE 227Pt ARG FS REFRESH 227Pt ARG FS ROOT DIR 228Pt ARG GAUGE FLAGS

PtGauge 288PtProgress 687PtSlider 805

Pt ARG GAUGE FONT 289Pt ARG GAUGE H ALIGN 289Pt ARG GAUGE V ALIGN 290Pt ARG GAUGE VALUE 290Pt ARG GAUGE VALUE PREFIX

290

May 31, 2004 Index 1245


Pt ARG GAUGE VALUE SUFFIX290

Pt ARG GRAPHIC FLAGS 410Pt ARG GRID HORIZONTAL 418Pt ARG GRID LAYOUT DATA

1161PtWidget 1148

Pt ARG GRID LAYOUT INFO182

Pt ARG GRID VERTICAL 418Pt ARG GROUP FLAGS 424

toggle buttons 921Pt ARG GROUP HORZ ALIGN

425Pt ARG GROUP ORIENTATION

PtDivider 207PtGroup 426

Pt ARG GROUP ROWS COLS426

Pt ARG GROUP SPACING 426Pt ARG GROUP SPACING X 427Pt ARG GROUP SPACING Y 427Pt ARG GROUP VERT ALIGN

427Pt ARG HEIGHT

PtWidget 1149, 1164Pt ARG HELP TOPIC 1164Pt ARG HIGHLIGHT ROUNDNESS

55Pt ARG HORIZONTAL ALIGNMENT

433, 439Pt ARG INCREMENT 765Pt ARG INDICATOR COLOR

922Pt ARG INDICATOR TYPE 923Pt ARG INLINE COLOR 55Pt ARG INSIDE COLOR

PtGraphic 411Pt ARG INSIDE FILL PATTERN

411Pt ARG INSIDE TRANS PATTERN

411Pt ARG ITEMS 458, 459Pt ARG LABEL BALLOON 440Pt ARG LABEL FLAGS 436, 441Pt ARG LABEL IMAGE 434, 442Pt ARG LABEL TYPE

PtButton 81PtLabel 432, 442

Pt ARG LAYOUT 178Pt ARG LAYOUT DATA 1165

PtWidget 1149Pt ARG LAYOUT INFO 179Pt ARG LAYOUT TYPE 180Pt ARG LIGHT BEVEL COLOR

PtBasic 56Pt ARG LIGHT FILL COLOR

PtBasic 56Pt ARG LINE CAP

PtGraphic 412Pt ARG LINE JOIN

PtGraphic 412Pt ARG LINE SPACING

PtLabel 432, 443PtMultiText 548

Pt ARG LINE WIDTHPtGraphic 412

Pt ARG LIST BALLOON 459Pt ARG LIST COLUMN ATTR

PtGenList 301PtTree 944

Pt ARG LIST COLUMN POSPtGenList 302PtList 456

1246 Index May 31, 2004


PtTree 943Pt ARG LIST DNDSEL COLOR

303Pt ARG LIST FLAGS

PtGenList 298, 303Pt ARG LIST FONT 305Pt ARG LIST ITEM COUNT 305Pt ARG LIST SB RES 298, 305Pt ARG LIST SCROLL RATE 306Pt ARG LIST SEL COUNT 307Pt ARG LIST SPACING 460Pt ARG LIST TOTAL HEIGHT

307Pt ARG MARGIN BOTTOM

PtLabel 433, 443PtPanelGroup 644, 645

Pt ARG MARGIN HEIGHTPtBasic 57PtTerminal 822–824, 838

Pt ARG MARGIN LEFTPtLabel 432, 443PtPanelGroup 644, 645

Pt ARG MARGIN RIGHTPtLabel 433, 443PtPanelGroup 644, 646

Pt ARG MARGIN TOPPtLabel 433, 444PtPanelGroup 644, 646

Pt ARG MARGIN WIDTHPtBasic 57PtTerminal 822–824, 838

Pt ARG MAX HEIGHT 1186Pt ARG MAXIMUM 291Pt ARG MAXIMUM DIM

PtWidget 1149, 1165Pt ARG MAX LENGTH 894Pt ARG MAX WIDTH 1187

Pt ARG MENU FLAGS 486–489,492, 497

Pt ARG MENU SPACING 498Pt ARG MENU TEXT FONT

488, 498Pt ARG MENU TITLE 488, 499Pt ARG MENU TITLE FONT

488, 499Pt ARG METER COLOR 522Pt ARG METER FLAGS 522Pt ARG METER FONT COLOR

523Pt ARG METER INCREMENT

523Pt ARG METER KEY LEFT 515,

523Pt ARG METER KEY RIGHT

515, 524Pt ARG METER LEVEL1 COLOR

524Pt ARG METER LEVEL1 POS

524Pt ARG METER LEVEL2 COLOR



525Pt ARG METER MAX NEEDLE POSITION

525Pt ARG METER MIN NEEDLE POSITION

525Pt ARG METER NEEDLE COLOR

526Pt ARG METER NEEDLE POSITION

515, 526, 527

May 31, 2004 Index 1247


Pt ARG METER NUM SEVERITY LEVELS526

Pt ARG METER TEXT FONT526

Pt ARG MIN HEIGHT 1187Pt ARG MINIMUM 291Pt ARG MINIMUM DIM

PtWidget 1149, 1166Pt ARG MIN SLIDER SIZE 765Pt ARG MIN WIDTH 1187Pt ARG MODIFIER KEYS 510Pt ARG MODIFY ITEMS 460Pt ARG MOVED 527Pt ARG MTREND ADVANCE BY N SAMPLES

541Pt ARG MTREND ATTRIBUTES

534Pt ARG MTREND GRAPH ATTR

536Pt ARG MTREND GRAPH DATA

538Pt ARG MTREND GRAPH STATE

538Pt ARG MTREND GRID COLOR

540Pt ARG MTREND GRID DRAW F

540Pt ARG MTREND GRID X 540Pt ARG MTREND GRID Y 540Pt ARG MTREND N GRAPHS

536Pt ARG MTREND N SAMPLES

536Pt ARG MTREND TRACE DRAW F

539Pt ARG MTREND TRACE WIDTH

539

Pt ARG MULTITEXT BOTTOM LINE560

Pt ARG MULTITEXT FLAGS 560Pt ARG MULTITEXT NUM LINES

561Pt ARG MULTITEXT NUM LINES VISIBLE

561Pt ARG MULTITEXT QUERY CHARACTER

561Pt ARG MULTITEXT QUERY LINE

557, 562Pt ARG MULTITEXT RANGE ATTRIBUTES

550, 552, 562Pt ARG MULTITEXT ROWS 563Pt ARG MULTITEXT SEGMENTS

549, 550, 563Pt ARG MULTITEXT TABS 564Pt ARG MULTITEXT TOP LINE

564Pt ARG MULTITEXT WRAP FLAGS

548, 564Pt ARG MULTITEXT X SCROLL POS

565Pt ARG MULTITEXT Y SCROLL POS

565Pt ARG NUMERIC FLAGS 606Pt ARG NUMERIC INCREMENT

PtNumericFloat 612PtNumericInteger 620

Pt ARG NUMERIC MAXPtNumericFloat 613PtNumericInteger 620

Pt ARG NUMERIC MINPtNumericFloat 613PtNumericInteger 620

Pt ARG NUMERIC PRECISION613

1248 Index May 31, 2004


Pt ARG NUMERIC PREFIX 606Pt ARG NUMERIC SPACING

607Pt ARG NUMERIC SUFFIX 607Pt ARG NUMERIC UPDOWN WIDTH

607Pt ARG NUMERIC VALUE

PtNumericFloat 613PtNumericInteger 621

Pt ARG OFFSET 510Pt ARG ONOFF STATE 628Pt ARG ORIENTATION

PtGauge 291PtToolbar 929PtToolbarGroup 934

Pt ARG ORIGIN 405, 406, 413PtArc 28PtBezier 68PtEllipse 208PtLine 450PtPolygon 668

Pt ARG OUTLINE COLOR 57Pt ARG PAGE INCREMENT 765Pt ARG PG CURRENT

PtPanelGroup 646Pt ARG PG CURRENT INDEX

PtPanelGroup 646Pt ARG PG FLAGS

PtPanelGroup 647Pt ARG PG OVERLAP THRESHOLD

PtPanelGroup 648Pt ARG PG PANEL TITLES

PtPanelGroup 648Pt ARG PG SELECTION MODE

PtPanelGroup 649Pt ARG POINTER

PtRaw 702

PtWidget 1149, 1166Pt ARG POINTS

PtArc 28PtBezier 68PtEllipse 208PtGraphic 405, 413PtLine 450PtPixel 664PtPolygon 668PtRect 736

Pt ARG POLYGON FLAGS 668,669

Pt ARG POSPtRect 736PtWidget 1149, 1166

Pt ARG PRINT CONTEXT 674,676

Pt ARG PRINT FLAGS 677Pt ARG PROGRESS BAR COLOR

688Pt ARG PROGRESS DIVISIONS

688Pt ARG PROGRESS GAP 689Pt ARG PROGRESS SPACING

689Pt ARG PS LBL ALL 678Pt ARG PS LBL COLLATED 678Pt ARG PS LBL COPIES 678Pt ARG PS LBL DOUBLE SIDED

679Pt ARG PS LBL FILE 679Pt ARG PS LBL FROM 679Pt ARG PS LBL INSTALL 679Pt ARG PS LBL NAME 679Pt ARG PS LBL NOT COLLATED

680

May 31, 2004 Index 1249


Pt ARG PS LBL PREFERENCES680

Pt ARG PS LBL PRINT ORDER680

Pt ARG PS LBL PRINT PAGES680

Pt ARG PS LBL RANGE 680Pt ARG PS LBL REVERSED 681Pt ARG PS LBL SELECTION

681Pt ARG PS LBL SEND TO FILE

681Pt ARG PS LBL SEND TO PRINTER

681Pt ARG PS LBL TO 682Pt ARG RAW CALC OPAQUE F

705Pt ARG RAW CONNECT F 706Pt ARG RAW DRAW F 702, 706Pt ARG RAW EXTENT F 706Pt ARG RAW INIT F 707Pt ARG RAWLIST BACKGROUND F

PtRawList 712Pt ARG RAWLIST DRAW F

PtRawList 712Pt ARG RAWLIST GFLAGS

PtRawList 713Pt ARG RAWLIST INFLATE F

PtRawList 715Pt ARG RAWLIST KEY F

PtRawList 716Pt ARG RAWLIST MOUSE F

PtRawList 717Pt ARG RAWLIST SELECT F

PtRawList 718Pt ARG RAWTREE DRAW F

PtRawTree 726

Pt ARG RAWTREE INFLATE FPtRawTree 727

Pt ARG RAWTREE SELECT FPtRawTree 728

Pt ARG RAWTREE STATE FPtRawTree 729

Pt ARG RECT ROUNDNESS 736,737

Pt ARG REGION DATA 742Pt ARG REGION FIELDS 742Pt ARG REGION FLAGS 744Pt ARG REGION HANDLE 744Pt ARG REGION INFRONT 745Pt ARG REGION INPUT GROUP

745Pt ARG REGION OPAQUE 745Pt ARG REGION OWNER 745Pt ARG REGION PARENT 746Pt ARG REGION SENSE 746Pt ARG RESIZE FLAGS

PtWidget 1167Pt ARG ROW LAYOUT DATA

1168PtWidget 1149

Pt ARG ROW LAYOUT INFO181

Pt ARG SCROLLAREA FLAGS752

Pt ARG SCROLLAREA INCREMENT X753

Pt ARG SCROLLAREA INCREMENT Y753

Pt ARG SCROLLAREA MAX X750, 753

Pt ARG SCROLLAREA MAX Y750, 754

1250 Index May 31, 2004


Pt ARG SCROLLAREA POS X754

Pt ARG SCROLLAREA POS Y754

Pt ARG SCROLLBAR FLAGS 766Pt ARG SCROLLBAR WIDTH

307Pt ARG SCROLLBAR X DISPLAY

PtMultiText 549, 566PtScrollArea 750, 754

Pt ARG SCROLLBAR X HEIGHTPtMultiText 566PtScrollArea 755

Pt ARG SCROLLBAR Y DISPLAYPtMultiText 549, 566PtScrollArea 750, 755

Pt ARG SCROLLBAR Y WIDTHPtMultiText 567PtScrollArea 755

Pt ARG SCROLLCONT FLAGSPtScrollContainer 775

Pt ARG SCROLLCONT RESIZE FLAGSPtScrollContainer 775

Pt ARG SECONDARY H ALIGN433, 444

Pt ARG SECONDARY V ALIGN433, 444

Pt ARG SELECTION FILL COLOR307

Pt ARG SELECTION INDEXES461

Pt ARG SELECTION MODEPtGenList 308PtTree 952, 954, 956

Pt ARG SELECTION RANGE894

Pt ARG SELECTION TEXT COLOR311

Pt ARG SEP ARM BITMAP CURSOR781

Pt ARG SEP ARM CURSOR COLOR783

Pt ARG SEP ARM CURSOR TYPE783

Pt ARG SEP DRAG BOUNDS783

Pt ARG SEP FLAGS 784Pt ARG SEP IMAGE 784Pt ARG SEP IMAGE H ALIGN

785Pt ARG SEP IMAGE V ALIGN

785Pt ARG SEP TYPE 785Pt ARG SERVER CONNECTION

PtServer 791Pt ARG SERVER NAME

PtServer 792Pt ARG SERVER SEND

PtServer 792Pt ARG SLIDER FLAGS 802Pt ARG SLIDER HANDLE COLOR

802Pt ARG SLIDER HANDLE WIDTH

803Pt ARG SLIDER IMAGE 803Pt ARG SLIDER INCREMENT

803Pt ARG SLIDER MULTIPLE 803Pt ARG SLIDER SIZE 765, 766Pt ARG SLIDER TICK MAJOR DIV

804Pt ARG SLIDER TICK MAJOR LEN

804

May 31, 2004 Index 1251


Pt ARG SLIDER TICK MINOR DIV804

Pt ARG SLIDER TICK MINOR LEN804

Pt ARG SLIDER TROUGH IMAGE1804

Pt ARG SLIDER TROUGH IMAGE2804

Pt ARG STYLE 58Pt ARG SYSINFO

PtDisjoint 195Pt ARG TAB FLAGS 812Pt ARG TERM ANSI PROTOCOL

830Pt ARG TERM APP 831Pt ARG TERM CHARSETS 822,

832Pt ARG TERM COLOR MODE

833Pt ARG TERM COLOR TABLE

827, 833Pt ARG TERM COLS 822, 823,

834, 850, 851Pt ARG TERM CONSOLE 826,

835Pt ARG TERM CUR COL 835Pt ARG TERM CUR POS 835Pt ARG TERM CUR ROW 835Pt ARG TERM CURSOR FLAGS

836Pt ARG TERM DRAW MODES

828, 836Pt ARG TERM FONT 820, 822,

823, 837Pt ARG TERM FONT INDEX

820, 822, 837

Pt ARG TERM FONT LIST 820,838

Pt ARG TERM FONT SIZE 838Pt ARG TERM MARGINS 822,

824, 826, 838Pt ARG TERM MAXCOLS 826,

839Pt ARG TERM MAXROWS 826,

839Pt ARG TERM MAXSIZE 826,

839, 850Pt ARG TERM MINCOLS 825,

839Pt ARG TERM MINROWS 825,

840Pt ARG TERM MINSIZE 825,

840, 850Pt ARG TERM OPTIONS 840Pt ARG TERM OPTMASK 840Pt ARG TERM RESIZE FL 841Pt ARG TERM RESIZE FUN

823, 841Pt ARG TERM RESIZE STR 823,

825, 842Pt ARG TERM ROWS 822, 823,

842, 850, 851Pt ARG TERM SCRLBK COUNT

842Pt ARG TERM SCRLBK LIMIT

842Pt ARG TERM SCRLBK POS

842Pt ARG TERM SCROLL 828, 843Pt ARG TERM SELECTION 843Pt ARG TERM SIZE 822–824,

844, 850, 851

1252 Index May 31, 2004


Pt ARG TERM VISUAL BELL845

Pt ARG TEXT CURSOR WIDTH895

Pt ARG TEXT FLAGS 571, 888,895, 906

Pt ARG TEXT FONTPtLabel 432, 445PtMultiText 549, 581, 583


896Pt ARG TEXT HIGHLIGHT TEXT COLOR

896Pt ARG TEXT IMAGE SPACING

PtLabel 445Pt ARG TEXT STRING

PtLabel 432, 436, 445PtMultiText 549, 564PtText 878

Pt ARG TEXT SUBSTRINGPtMultiText 549PtText 896

Pt ARG TG FLAGSPtToolbarGroup 935

Pt ARG TIMER INITIAL 917Pt ARG TIMER REPEAT 917Pt ARG TITLE

PtContainer 178, 184Pt ARG TITLE FONT

PtContainer 184Pt ARG TOOLBAR FLAGS

PtToolbar 929Pt ARG TOOLBAR LAYOUT FLAGS

PtToolbar 930Pt ARG TOOLBAR SPACING

PtToolbar 930Pt ARG TOP ITEM POS 311, 337

Pt ARG TRANS PATTERN 58Pt ARG TREE BALLOON 947Pt ARG TREE COLUMN ATTR

944, 948Pt ARG TREE COLUMN IMGFUN

945, 949Pt ARG TREE FLAGS

PtGenTree 358, 384PtRawTree 734PtTree 960

Pt ARG TREE IMAGES 942, 950Pt ARG TREE IMGMASK 942,

951Pt ARG TREE LINE COLOR 359Pt ARG TREE LINE SPACING

359Pt ARG TREE MARGIN COLOR

360Pt ARG TREND ATTRIBUTES

1015, 1017Pt ARG TREND COLOR LIST

1015, 1017, 1022Pt ARG TREND COUNT 1018Pt ARG TREND DATA 1018Pt ARG TREND FLAGS 1019Pt ARG TREND GRID COLOR

1021Pt ARG TREND GRID X 1021Pt ARG TREND GRID Y 1021Pt ARG TREND INC 1021Pt ARG TREND MAX 1022Pt ARG TREND MIN 1022Pt ARG TREND PALETTE END

1022Pt ARG TTY ARGV 1035Pt ARG TTY BUFFER 1036Pt ARG TTY BUFLEN 1036

May 31, 2004 Index 1253


Pt ARG TTY CMD 1036, 1037Pt ARG TTY DEVSIZE 1037Pt ARG TTY EXIT STATUS 1038,

1045Pt ARG TTY FDS 1038Pt ARG TTY FDSET 1038Pt ARG TTY FLAGS 1039Pt ARG TTY INPUT 1040Pt ARG TTY INPUT WRITTEN

1040Pt ARG TTY PATH 1040Pt ARG TTY PID 1037, 1041Pt ARG TTY PRI 1041Pt ARG TTY PSEUDO 1041Pt ARG TTY RFD 1042Pt ARG TTY SFD 1042Pt ARG TTY SPAWN OPTIONS

1042Pt ARG TTY WFD 1043Pt ARG UNDERLINE1 445Pt ARG UNDERLINE2 445Pt ARG UNDERLINE TYPE 446Pt ARG USER DATA

PtRaw 702PtToggleButton 922PtWidget 1150, 1169

Pt ARG VERTICAL ALIGNMENT433, 446

Pt ARG VISIBLE COUNTPtComboBox 166PtGenList 311PtList 457, 468

Pt ARG WEB ACTIVATE LINK1058

Pt ARG WEB AUTHENTICATE1059

Pt ARG WEB BUILD DATE 1060

Pt ARG WEB COMMAND 1060Pt ARG WEB DATA 1062Pt ARG WEB DOWNLOAD 1065Pt ARG WEB ENCODING 1065Pt ARG WEB GET CERTIFICATES

1065Pt ARG WEB GET CONTEXT

1066Pt ARG WEB GET HISTORY

1067Pt ARG WEB GET URL 1053,

1068Pt ARG WEB HELPER 1069Pt ARG WEB H ERRNO 1070Pt ARG WEB IMPORT CERTIFICATE

1071Pt ARG WEB NAVIGATE FRAME

1072Pt ARG WEB NAVIGATE LINK

1073Pt ARG WEB NAVIGATE PAGE

1074Pt ARG WEB OPTION 1075Pt ARG WEB PRINT 1107Pt ARG WEB RELOAD 1108Pt ARG WEB SERVER 1052, 1108Pt ARG WEB SERVER PID 1110Pt ARG WEB SSL RESPONSE

1110Pt ARG WEB STARTUP ERRNO

1053, 1111Pt ARG WEB STOP 1111Pt ARG WEB UNKNOWN RESP

1112Pt ARG WEB VERSION 1113Pt ARG WIDTH

PtWidget 1149, 1170

1254 Index May 31, 2004


Pt ARG WINDOW ACTIVE COLOR1188

Pt ARG WINDOW FRONT WINDOW1188

Pt ARG WINDOW HELP ROOT1188

Pt ARG WINDOW INACTIVE COLOR1188

Pt ARG WINDOW MANAGED FLAGS1183, 1189

Pt ARG WINDOW NOTIFY FLAGS1185, 1190

Pt ARG WINDOW RENDER FLAGS1182, 1191

Pt ARG WINDOW STATE 1193Pt ARG WINDOW TITLE 1194Pt ARG WINDOW TITLE COLOR

1195Pt AUTO EXTENT 177Pt AUTOHIGHLIGHT 488, 1158Pt BACKFILL TEXT 441Pt BALLOON AS REQUIRED 441Pt BALLOON BOTTOM 439PtBalloonCallback t 5Pt BALLOONCOLOR 438Pt BALLOON INPLACE 439Pt BALLOON LEFT 439Pt BALLOON RIGHT 439Pt BALLOONS ON 1153Pt BALLOON TOP 439PtBarGraph 34

barsvertical 37

base 36color 35, 36data 34, 36depth 37

flags 37grid

color 38displaying 37horizontal lines 38vertical lines 38

maximum value 38minimum value 39Pt ARG BARGRAPH BASE

36Pt ARG BARGRAPH COLOR

35, 36Pt ARG BARGRAPH DATA

34, 36Pt ARG BARGRAPH DEPTH

37Pt ARG BARGRAPH FLAGS

37Pt ARG BARGRAPH GRID COLOR

38Pt ARG BARGRAPH GRID HORIZ

38Pt ARG BARGRAPH GRID VERT

38Pt ARG BARGRAPH MAX

38Pt ARG BARGRAPH MIN 39Pt ARG COLOR 35, 36

Pt BARGRAPH GRID 37Pt BARGRAPH HORIZONTAL 37Pt BARGRAPH VERTICAL 37PtBasic 42

behavior 43bevel color 53, 56

main 52bevel width 49border color

May 31, 2004 Index 1255


inline 55outline 57

border roundness 55callbacks

activate 59arm 60disarm 61got focus 62lost focus 63menu 44, 64repeat 44, 65right mouse button 44, 64

contrast 53contrast, bevel 52fill color 54, 56fill pattern 55, 411foreground color 52graphics bandwidth

threshold 48margins

height 57width 57

Pt ARG BANDWIDTH THRESHOLD48

Pt ARG BEVEL COLOR 52Pt ARG BEVEL CONTRAST

52Pt ARG BEVEL WIDTH 49Pt ARG COLOR 52Pt ARG CONTRAST 53Pt ARG DARK BEVEL COLOR

53Pt ARG DARK FILL COLOR

54Pt ARG FILL COLOR 54Pt ARG FILL PATTERN 55Pt ARG FLAGS 43, 44, 59, 65

Pt ARG HIGHLIGHT ROUNDNESS55

Pt ARG INLINE COLOR 55Pt ARG INSIDE FILL PATTERN

411Pt ARG INSIDE TRANS PATTERN

411Pt ARG LIGHT BEVEL COLOR

56Pt ARG LIGHT FILL COLOR

56Pt ARG MARGIN HEIGHT

57Pt ARG MARGIN WIDTH 57Pt ARG OUTLINE COLOR

57Pt ARG STYLE 58Pt ARG TRANS PATTERN

58Pt CB ACTIVATE 43, 59Pt CB ARM 43, 60Pt CB DISARM 43, 61Pt CB GOT FOCUS 62Pt CB LOST FOCUS 63Pt CB MENU 44, 64

enabling 1160Pt CB REPEAT 44, 65selectable 43style 58transparency pattern 58, 411

PtBezier 68Pt ARG BEZIER FLAGS 69Pt ARG ORIGIN 68Pt ARG POINTS 68

Pt BITMAP BALLOON BOTTOM 440Pt BITMAP BALLOON INPLACE 440Pt BITMAP BALLOON LEFT 440

1256 Index May 31, 2004


Pt BITMAP BALLOON RIGHT 440Pt BITMAP BALLOON TOP 440PtBkgd 73

image 74Pt ARG BKGD IMAGE 74Pt ARG BKGD SPACING X

75Pt ARG BKGD SPACING Y

75Pt ARG BKGD TILE 75tiling

spacing 75type 75

Pt BKGD CENTER 75Pt BKGD CENTER GRID 76Pt BKGD GRID 76Pt BKGD NONE 76Pt BLANK ETCHES 49Pt BLOCK CUA FOCUS 177Pt BLOCKED 1158, 1159Pt BOTTOM ANCHORED BOTTOM 1152Pt BOTTOM ANCHORED TOP 1152Pt BOTTOM BEVEL 49Pt BOTTOM ETCH 49Pt BOTTOM INLINE 50, 55Pt BOTTOM OUTLINE 49, 57Pt BOTTOM RIGHT BEVEL 50Pt BOTTOM RIGHT ETCH 50Pt BOTTOM RIGHT INLINE 50Pt BOTTOM RIGHT OUTLINE 50Pt BROWSE MODE 155, 230, 308PtButton 80

armedcolor 81, 82data 81, 82fill 81, 82

behavior 81

creating 80label type 81Pt ARG ARM COLOR 81, 82Pt ARG ARM FILL 81, 82Pt ARG ARM IMAGE 81, 82Pt ARG LABEL TYPE 81visual feedback 81

PtCalendar 88callbacks

date selection 97date

current 91, 95days

highlighted 93highlighted, color 90highlighted, font 93name, color 91name, font 93names 96selected, color 95

flags 92grid, displaying 92month

current, day color 90current, day font 92name, color 90name, font 93names 94next/previous buttons,

color 94next/previous buttons,

displaying 92next/previous days,

displaying 92next/previous, day color 90next/previous, font 93

May 31, 2004 Index 1257







Pt ARG CALENDAR DATE91

Pt ARG CALENDAR FLAGS92






Pt ARG CALENDAR HIGHLIGHT93

Pt ARG CALENDAR MONTH BTN COLOR94

Pt ARG CALENDAR MONTH NAMES94

Pt ARG CALENDAR SEL COLOR95

Pt ARG CALENDAR TIME T95

Pt ARG CALENDAR WDAY NAMES96

Pt ARG CALENDAR YEAR BTN COLOR97

Pt CB CALENDAR SELECT97

yearcolor 90font 93next/previous buttons,

color 97next/previous buttons,

displaying 92Pt CALENDAR DATE SELECTED 97Pt CALENDAR MONTH BTNS 92Pt CALENDAR MONTH SELECTED 97PtCalendarSelectCallback t

97Pt CALENDAR SHOW GRID 92Pt CALENDAR SHOW NEXT 92Pt CALENDAR SHOW PREV 92Pt CALENDAR WDAY SELECTED 97Pt CALENDAR YEAR BTNS 92Pt CALENDAR YEAR SELECTED 97PtCallback t 7PtCallbackInfo t 9Pt CALLBACKS ACTIVE 613, 1158

Pt CB CHILD ADDED REMOVED187

Pt CB CLOCK TIME CHANGED119

Pt CB DIVIDER DRAG 202Pt CB FONT MODIFY 282Pt CB GAUGE VALUE CHANGED

291Pt CB MODIFY NOTIFY

880, 897, 913Pt CB MODIFY VERIFY

899, 912

1258 Index May 31, 2004


Pt CB MOTION NOTIFY900

Pt CB MOTION VERIFY 901Pt CB ONOFF NEW VALUE

628Pt CB PG PANEL SWITCHING

650Pt CB SCROLLAREA SCROLLED

756Pt CB SCROLL MOVE 311,

767Pt CB SLIDER MOVE 806Pt CB TEXT CHANGED

880, 897, 913PtTextModifyText() 912

Pt CB ACTIVATEhotkeys 1176PtBasic 43, 59, 59PtGroup 922PtMultiText 571PtNumericFloat 618PtNumericInteger 626PtText 888, 906PtToggleButton 921

Pt CB ARMPtBasic 43, 60PtMenuButton 489

Pt CB BALLOONS 185Pt CB BLOCKED 1170Pt CB CALENDAR SELECT 97Pt CB CBOX ACTIVATE 159Pt CB CBOX CLOSE 159Pt CB CHILD ADDED REMOVED

186Pt CB CHILD GETTING FOCUS

PtContainer 187Pt CB CHILD LOSING FOCUS

PtContainer 189Pt CB CLIENT CONNECTED

PtClient 105Pt CB CLIENT ERROR 106Pt CB CLIENT EVENT

PtClient 107Pt CB CLIENT NOT FOUND

PtClient 107Pt CB CLOCK TIME CHANGED

119Pt CB CS COLOR CHANGED

PtColorSel 138Pt CB DESTROYED 1170Pt CB DISARM

PtBasic 43, 61Pt CB DIVIDER DRAG 202Pt CB DND

PtFileSel 236PtGenList 316PtGenTree 365PtList 468PtRawList 723PtRawTree 734PtTree 961PtWidget 1171

Pt CB FILTER 1174Pt CB FONT MODIFY 282Pt CB FS BKGD HANDLER 228Pt CB FS SELECTION 230Pt CB FS STATE 231Pt CB GAUGE VALUE CHANGED

PtGauge 291PtProgress 688

Pt CB GEN TREE INPUT 360Pt CB GOT FOCUS

PtBasic 62PtMultiText 573

May 31, 2004 Index 1259


PtText 886, 907Pt CB HOTKEY 1176Pt CB IS DESTROYED 1177Pt CB LAYOUT 190Pt CB LIST INPUT 461Pt CB LOST FOCUS

PtBasic 63PtMultiText 573PtText 886, 907

Pt CB MENUenabling 1160PtBasic 44, 64PtMenuButton 489

Pt CB METER MOVED 527Pt CB MODIFY NOTIFY

PtMultiText 575PtText 880, 885, 897, 913

Pt CB MODIFY VERIFYPtMultiText 576PtText 880, 898, 912

Pt CB MOTION NOTIFYPtMultiText 575PtText 900

Pt CB MOTION VERIFYPtMultiText 577PtText 887, 901

Pt CB NUMERIC CHANGEDPtNumericFloat 613PtNumericInteger 621

Pt CB ONOFF NEW VALUE 628Pt CB OUTBOUND 1177Pt CB PG PANEL SWITCHING

PtPanelGroup 649Pt CB PRINT PROPS 682Pt CB RAW 1178Pt CB REALIZED 1180Pt CB REPEAT 44, 65

Pt CB RESCALE 413Pt CB RESIZE 190Pt CB SCROLLAREA SCROLLED

751, 756Pt CB SCROLL MOVE

PtGenList 311PtScrollbar 767

Pt CB SELECTION 457, 462Pt CB SEP DRAG 786Pt CB SERVER CONNECTED

PtServer 792Pt CB SERVER ERROR 793Pt CB SERVER RECEIVE

PtServer 794Pt CB SERVER TRANSPORT

PtServer 794Pt CB SLIDER MOVE 806Pt CB SYSINFO

PtDisjoint 196Pt CB TERM APP 845Pt CB TERM FONT 846Pt CB TERM INPUT 847, 871,

872Pt CB TERM OPTIONS 849Pt CB TERM RESIZE 849Pt CB TERM RESIZED 851Pt CB TERM SCRLBK 852Pt CB TEXT CHANGED

PtMultiText 575PtText 880, 885, 897, 913

Pt CB TIMER ACTIVATE 917Pt CB TREE COLUMN SEL

PtTree 946, 952Pt CB TREE SELECTION 954Pt CB TREE STATE 955, 979, 983Pt CB TTY DEVSIZE 1043Pt CB TTY OUTPUT 1044

1260 Index May 31, 2004


Pt CB TTY TERMINATED 1045Pt CB UNREALIZED 1180Pt CB WEB AUTHENTICATE

1113Pt CB WEB CLOSE WINDOW

1114Pt CB WEB COMPLETE 1115Pt CB WEB CONTEXT 1116Pt CB WEB DATA REQ 1117Pt CB WEB DOWNLOAD 1118Pt CB WEB ERROR 1119Pt CB WEB IMPORT CERTIFICATE

1123Pt CB WEB METADATA 1124Pt CB WEB NEED SCROLL

1125Pt CB WEB NEW WINDOW

1126Pt CB WEB PAGE INFO 1127Pt CB WEB SSL CERTINFO

1128Pt CB WEB SSL CERTNONTRUSTED

1130Pt CB WEB SSL CLIENT CERT SELECT

1134Pt CB WEB SSL ERROR 1135Pt CB WEB START 1138Pt CB WEB STATUS 1138Pt CB WEB UNKNOWN 1141Pt CB WEB URL 1143Pt CB WINDOW 1195Pt CB WINDOW CLOSING 1196Pt CB WINDOW OPENING 1197Pt CB WINDOW TRANSPORT

1197Pt CHANGE ACTIVATE 571, 888,

895, 906

Pt CHILD ADDED 187Pt CHILD REMOVED 187Pt CLEAR 1159PtClient 102

callbacksconnected 105error 106not connected 107zzzzzzzzzz 107

connection object 105connector name 103, 104, 106flags 103messages, sending to

server 104Pt ARG CLIENT FLAGS 103Pt ARG CLIENT NAME 103,

104, 106Pt ARG CLIENT REPLY LEN

104Pt ARG CLIENT SEND 104Pt ARG CLIENT SERVER

105Pt CB CLIENT CONNECTED

105Pt CB CLIENT ERROR 106Pt CB CLIENT EVENT 107Pt CB CLIENT NOT FOUND

107reply length 104

PtClientCallback t 107Pt CLIENT NOEVENTS 103Pt CLIENT NONBLOCK 103Pt CLIP HIGHLIGHT 1159PtClock 112

24-hour display 114AM/PM indicator 114analog 119

May 31, 2004 Index 1261


callbackstime changed 119

digital 119face

color 114numbers, displaying 115outline color 114

flags 114flicker, reducing 112font 115hour

color 116current setting 115leading zero, adding 114offset 116

LED/LCD 119minute

color 116current setting 116offset 117

Pt ARG CLOCK FACE COLOR114

Pt ARG CLOCK FACE OUTLINE COLOR114

Pt ARG CLOCK FLAGS 114Pt ARG CLOCK FONT 115Pt ARG CLOCK HOUR 115Pt ARG CLOCK HOUR COLOR

116Pt ARG CLOCK HOUR OFFSET

116Pt ARG CLOCK MINUTE

116Pt ARG CLOCK MINUTE COLOR

116Pt ARG CLOCK MINUTE OFFSET

117

Pt ARG CLOCK SECOND117

Pt ARG CLOCK SECOND COLOR117

Pt ARG CLOCK SECOND OFFSET117

Pt ARG CLOCK SEP1 118Pt ARG CLOCK SEP1 COLOR


118Pt ARG CLOCK TYPE 119Pt ARG FLAGS 119Pt CB CLOCK TIME CHANGED

119second

color 117current setting 117displaying 115offset 117

separatorcharacter 118color 118

timeupdating every second 115

type 119Pt CLOCK 24 HOUR 114Pt CLOCK ANALOG 119Pt CLOCK DIGITAL 119Pt CLOCK HOUR CHANGED 120Pt CLOCK LED 119Pt CLOCK MINUTE CHANGED 120Pt CLOCK PAD HOURS 114Pt CLOCK SECOND CHANGED 120Pt CLOCK SHOW AMPM 114Pt CLOCK SHOW NUMBERS 115

1262 Index May 31, 2004


Pt CLOCK SHOW SECONDS 115PtClockTimeCallback t 120Pt CLOCK TRACK TIME 115PtColorPanel 124

flags 125Pt ARG CPANEL FLAGS

125PtColorPatch 129

flags 130Pt ARG CPATCH FLAGS

130PtColorSel 135

callbackscolor changed 138

color 136flags 137models 136models, current 137palette 138Pt ARG CS COLOR 136Pt ARG CS COLOR MODELS

136Pt ARG CS CURRENT MODEL

137Pt ARG CS FLAGS 137Pt ARG CS PALETTE 138Pt CB CS COLOR CHANGED

138PtColorSelGroup 143

flags 144Pt ARG CSGROUP FLAGS

144PtColorWell 148

color-swatch dimensions 149flags 149Pt ARG CWELL FLAGS 149

Pt ARG CWELL SWATCH DIM149

PtComboBox 154behavior 155callbacks

drop button activation 159list close 159

convenience functions 166drop button

suppressing 158width 157

flags 155, 157keyboard actions 155list

closing from code 169determining if open 158item, selected 158items, maximum visible 158items, number visible 166opening from code 170opening via keyboard 155,

157placing above text 158static 158types 154

maximizing width 157Pt ARG CBOX BUTTON WIDTH

157Pt ARG CBOX FLAGS 155,

157Pt ARG CBOX MAX VISIBLE COUNT

158Pt ARG CBOX SEL ITEM

158Pt ARG CBOX TEXT FILL COLOR

159

May 31, 2004 Index 1263


Pt ARG VISIBLE COUNT166

Pt CB CBOX ACTIVATE 159Pt CB CBOX CLOSE 159text area, fill color 159

Pt COMBOBOX ALT DOWN 155,157

PtComboBoxListClose() 169PtComboBoxListOpen() 170Pt COMBOBOX MAX WIDTH 157Pt COMBOBOX OPEN 158Pt COMBOBOX STATIC 158Pt COMBOBOX TOP 158PtCompound 171Pt CONNECTION CLIENT BROKEN 106Pt CONNECTION SERVER BROKEN 793Pt CONSUME 1175Pt CONSUME EVENTS 1157PtContainer 175

balloonscallback 185disabling 177

callbackschild added/removed 186child getting focus 187child losing focus 189resize 190

CUAenabling 177enabling arrow keys 177preventing focusing 177

flags 177, 184hotkeys, terminating searches

for 178key events, processing as

hotkeys first 178

Pt ARG CONTAINER FLAGS177, 184

Pt ARG FILL LAYOUT INFO180

Pt ARG FLAGS 187Pt ARG GRID LAYOUT INFO

182Pt ARG LAYOUT 178Pt ARG LAYOUT INFO 179Pt ARG LAYOUT TYPE 180Pt ARG ROW LAYOUT INFO

181Pt ARG TITLE 178, 184Pt ARG TITLE FONT 184Pt CB BALLOONS 185Pt CB CHILD ADDED REMOVED

186Pt CB CHILD GETTING FOCUS

187Pt CB CHILD LOSING FOCUS

189Pt CB LAYOUT 190Pt CB RESIZE 190reextent, forcing 177title

etching 177font 184gradient 177showing 178text 184

PtContainerCallback t 191PtContainerHold() 311, 1160Pt CONTINUE 8Pt CPANEL SHOW DROPPER 125Pt CPANEL SHOW FIELDS 125Pt CPANEL SHOW WELL 125Pt CPATCH ENABLE MENU 131

1264 Index May 31, 2004


Pt CPATCH SHOW SELECTOR 130Pt CPATCH SHOW SLIDER 131Pt CS COLOR CHANGE COMPLETE

139Pt CS COLOR CHANGED 138Pt CS FAST UPDATE 137Pt CSGROUP ALL AT ONCE 144Pt CS QUANTIZE COLOR 138Pt CURSOR VISIBLE 895Pt CWELL POPUP ON MENU 149Pt CWELL POPUP ON SELECT 149Pt DAMAGED 1159PtDamageExtent() 336, 344Pt DAMAGE FAMILY 1159Pt DAMAGE PARENT 1157Pt DEFAULT COLOR 582, 584Pt DEFAULT FONT 581, 583Pt DELAY REALIZE 1159Pt DESTROYED 187, 1159Pt DISABLE BALLOONS 177PtDisjoint 195

callbacks, systeminformation 196

Pt ARG SYSINFO 195Pt CB SYSINFO 196system information 195

PtDivider 200bandwidth threshold 207callbacks

dragging 202drag outline, suppressing 201flags 201group orientation 207in a list 303offset 202Pt ARG BANDWIDTH THRESHOLD

207

Pt ARG DIVIDER FLAGS201

Pt ARG DIVIDER OFFSET202

Pt ARG DIVIDER SIZES 202Pt ARG FLAGS 202Pt ARG GROUP ORIENTATION

207Pt CB DIVIDER DRAG 202resizing

both children 201preventing 201

sizes of realized children 202PtDividerCallback t 203Pt DIVIDER INVISIBLE 201Pt DIVIDER NORESIZE 201Pt DIVIDER RESIZE BOTH 201PtDndCallbackInfo t 1172Pt DOUBLE DASH LINE 785Pt DOUBLE LINE 785Pt DOUBLE ULINE 446Pt EDITABLE 895Pt EDIT ACTIVATE 571, 906PtEllipse 208

height 208Pt ARG DIM 208Pt ARG ORIGIN 208Pt ARG POINTS 208width 208

Pt ELLIPSIS MIDDLE 441Pt EMT AUTOINDENT 560Pt EMT CHAR 565Pt EMT FORCED SCROLL 561Pt EMT FULL LINES 560Pt EMT NEWLINE 565Pt EMT SCROLL TO CURSOR 561Pt EMT WORD 548, 565

May 31, 2004 Index 1265


Pt ENABLE CUA 177Pt ENABLE CUA ARROWS 177Pt ETCHED IN 786Pt ETCHED OUT 786Pt ETCH TITLE AREA 177Pt EXTENDED MODE 231, 308PtFileSel 212

background handler 228callbacks

drag and drop 236item selection 230

case insensitivity 222convenience functions 237custom headers 215directories, listing 223error dialog 222events, processing

pending 228files

hidden 223information 215, 223listing 223names, pattern for 222

flags 214, 222items

adding 240, 242allocating 245collapsing 212, 231, 251damaging 249expanding 212, 231, 252expanding parents 250freeing 253, 254freeing when collapsing 222getting all 244getting current 255getting selected 256, 267images for 224

index of 258redrawing 249removing 259, 261, 263rereading 227root 265scrolling to 269selecting 266, 268selection, clearing 248setting current 257unselecting 270, 271

keyboard seek mode 223labels

date 226group 226name 226owner 227permissions 227size 227

Pt ARG FS FILE SPEC 222Pt ARG FS FLAGS 214, 222Pt ARG FS FORMAT 223Pt ARG FS IMAGES 224Pt ARG FS LBL DATE 226Pt ARG FS LBL GROUP 226Pt ARG FS LBL NAME 226Pt ARG FS LBL OWNER

227Pt ARG FS LBL PERMISSIONS

227Pt ARG FS LBL SIZE 227Pt ARG FS REFRESH 227Pt ARG FS ROOT DIR 228Pt CB DND 236Pt CB FS BKGD HANDLER

228Pt CB FS SELECTION 230Pt CB FS STATE 231

1266 Index May 31, 2004


read error 223reading directories 215root directory 228sample code 216seeking files 223single-level mode 214, 223,

232tree mode 214

PtFileSelBkgdCallback t

229PtFileSelCallback t 231PtFileSelItem t 213PtFlash 272

Pt ARG FLASH FILE 272URL 272

Pt FLAT FILL 51Pt FLOAT ORIGIN 410Pt FLOAT POS 410Pt FOCUS RENDER 1159PtFontSel 276

callbacksfont modified 282

colorstext 282text background 282

convenience functions 286flags 279font

currently selected 281families, filtering 278initial 281

labelbackground color 280font name 280size 280style 280text color 280

maximum point size 281Pt ARG FLAGS 282Pt ARG FONT DISPLAY 278Pt ARG FONT FLAGS 279Pt ARG FONT LBL BKGDCOLOR

280Pt ARG FONT LBL FONT

280Pt ARG FONT LBL SIZE

280Pt ARG FONT LBL STYLE

280Pt ARG FONT LBL TEXTCOLOR

280Pt ARG FONT NAME 281Pt ARG FONT POINT SIZE MAX

281Pt ARG FONT SAMPLE 281Pt ARG FONT SYMBOL 281Pt ARG FONT TEXT BKGD COLOR

282Pt ARG FONT TEXT COLOR

282Pt CB FONT MODIFY 282required symbol 281sample text 281

Pt FONTSEL AA CHECK 279Pt FONTSEL ALL FONTS 279Pt FONTSEL ALL SYMBOLS 281Pt FONTSEL BITMAP 279Pt FONTSEL COLORSEL BKGD 279Pt FONTSEL COLORSEL TEXT 279Pt FONTSEL FIXED 279Pt FONTSEL PROP 279Pt FONTSEL SAMPLE 279Pt FONTSEL SCALABLE 279PtForwardWindowEvent() 1194

May 31, 2004 Index 1267


PtForwardWindowTaskEvent() 1194PtFSAddAfter() 240PtFSAddFirst() 242PtFSAllItems() 244PtFSAllocItem() 245Pt FS CASE INSENSITIVE 222PtFSClearSelection() 248PtFSDamageItem() 249Pt FS DIR CL 213, 225Pt FS DIR OP 213, 225Pt FS DLINK CL 213, 225Pt FS DLINK OP 213, 225Pt FS ERROR 213, 225Pt FS ERROR POPUP 222PtFSExpandParents() 250Pt FS FILE 213, 225Pt FS FLINK 213, 225PtFSFolderCollapse() 251PtFSFolderExpand() 252PtFSFreeAllItems() 253PtFSFreeItems() 254Pt FS FREE ON COLLAPSE 222PtFSGetCurrent() 255PtFSGetSelIndexes() 256PtFSGoto() 257PtFSItemIndex() 258Pt FS NEW DIR 213Pt FS NEW ITEM 228Pt FS NO ROOT DISPLAY 223Pt FS OLD DIR 213Pt FS OLD ITEM 229PtFSRemoveChildren() 259PtFSRemoveItem() 261PtFSRemoveList() 263PtFSRootItem() 265Pt FS SEEK KEY 214, 223PtFSSelect() 266

PtFSSelectedItems() 267PtFSSetSelIndexes() 268PtFSShow() 269Pt FS SHOW DIRS 223Pt FS SHOW ERRORS 223Pt FS SHOW FILES 223Pt FS SHOW HIDDEN 223Pt FS SINGLE LEVEL 214, 223,

232Pt FS STATE END 232Pt FS STATE START 232PtFSUnselect() 270PtFSUnselectNonBrothers() 271Pt FULL BEVELS 49PtGauge 287

callbacksvalue changed 291

flags 288font 289horizontal alignment 289interactive 288, 291live 288orientation 291Pt ARG FLAGS 291Pt ARG GAUGE FLAGS 288Pt ARG GAUGE FONT 289Pt ARG GAUGE H ALIGN

289Pt ARG GAUGE V ALIGN

290Pt ARG GAUGE VALUE 290Pt ARG GAUGE VALUE PREFIX

290Pt ARG GAUGE VALUE SUFFIX

290Pt ARG MAXIMUM 291Pt ARG MINIMUM 291

1268 Index May 31, 2004


Pt ARG ORIENTATION 291Pt CB GAUGE VALUE CHANGED

291value

current 290displaying 289indeterminate 288inverting fill color 289maximum 291maximum, position of 289minimum 291prefix 290suffix 290

vertical alignment 290PtGaugeCallback t 293Pt GAUGE DECREMENT 292Pt GAUGE DRAGGED 292Pt GAUGE INCREMENT 292Pt GAUGE INDETERMINATE 288,

687Pt GAUGE INTERACTIVE 288,

291, 688Pt GAUGE JUMP 293Pt GAUGE LIVE 288, 687Pt GAUGE MAX ON LEFT 289,

805Pt GAUGE MAX ON TOP 289, 805Pt GAUGE MULTIPLE DECREMENT 292Pt GAUGE MULTIPLE INCREMENT 292Pt GAUGE RELEASED 292Pt GAUGE SHOW VALUE 289Pt GAUGE TO MAX 292Pt GAUGE TO MIN 292Pt GAUGE VALUE XOR 289PtGenList 297

background, drawing 328balloon

adjusting for a column 350creating 325fill color 301for individual columns 303showing 304text color 301when clipping occurs 303

blitting, disabling 304browse mode 308callbacks

drag and drop 316scroll 311

column flags 301column positions 302compose selection modes,

defining 309convenience functions 317drag and drop, selection

color 303events, consuming 303extended mode 308flags 303font 305gflags, getting 351items

adding 321browsing 308Ctrl-click 308current 298damaging 327getting all 323getting current 333getting first 332getting last 342getting selected 334, 349index 340locking 343

May 31, 2004 Index 1269


number of 305number selected 307number visible 311reallocating 341removing 345selected, color of 307selected, text color 311selecting 348selecting a range 308selecting many 308selecting one 308setting current 335setting selected 352Shift-click 308showing 354top one displayed 311total height 307unlocking 355unselecting 356

keyboard actions 299mouse actions 299multiple mode 308Pt ARG BALLOON COLOR

301Pt ARG BALLOON FILL COLOR

301Pt ARG FLAGS 311Pt ARG LIST COLUMN ATTR

301Pt ARG LIST COLUMN POS

302Pt ARG LIST DNDSEL COLOR

303Pt ARG LIST FLAGS 298,

303Pt ARG LIST FONT 305

Pt ARG LIST ITEM COUNT305

Pt ARG LIST SB RES 298,305

Pt ARG LIST SCROLL RATE306

Pt ARG LIST SEL COUNT307

Pt ARG LIST TOTAL HEIGHT307

Pt ARG SCROLLBAR WIDTH307

Pt ARG SELECTION FILL COLOR307

Pt ARG SELECTION MODE308

Pt ARG SELECTION TEXT COLOR311

Pt ARG TOP ITEM POS 311Pt ARG VISIBLE COUNT

311Pt CB DND 316Pt CB SCROLL MOVE 311PtDivider as child 297

adjusting size 303range-select mode 308read-only 304repairs

holding 336releasing hold on 344

resizing 347scroll rate 306scrollbar

always 304as required 304color 298, 305granting focus to 304

1270 Index May 31, 2004


resizing 304resources 298, 305width 307

scrollbars 298selection

clearing 324selection mode 308single-select mode 308snapping to the number of

items 304strings, drawing 330text alignment 301

PtGenListAddItems() 321PtGenListAllItems() 323PtGenListClearSelection() 324PtGenListCreateTextBalloon() 325,

715, 727PtGenListDamageItem() 327, 336,

344PtGenListDndCallback t 723PtGenListDrawBackground() 328PtGenListDrawString() 330PtGenListFirstItem() 332Pt GEN LIST FULL WIDTH 714PtGenListGetCurrent() 333PtGenListGetSelIndexes() 334PtGenListGoto() 335PtGenListHold() 327, 336, 344PtGenListItem t 337Pt GEN LIST ITEM BACKGROUND

714PtGenListItemIndex() 340PtGenListItemRealloc() 341PtGenListLastItem() 342PtGenListLockItem() 327, 343, 355Pt GEN LIST NO AUTOFOCUS 714Pt GEN LIST NO BACKGROUND 713

Pt GEN LIST NO CLIPPING 714PtGenListRelease() 327, 344PtGenListRemoveItems() 345PtGenListResize() 343, 347, 355PtGenListSelect() 348PtGenListSelectedItems() 349PtGenListSetColumnBalloon() 350,

715, 727PtGenListSetGflags() 351PtGenListSetSelIndexes() 352PtGenListShow() 354Pt GEN LIST SHOW DAMAGED 328,

714PtGenListUnlockItem() 327, 343,

355PtGenListUnselect() 356PtGenTree 357

buttonsdisplaying 358, 384indenting 358

callbacksdrag and drop 365mouse and key event 360

connectorsdisplaying 359

convenience functions 366flags 358, 384items

adding 369, 370collapsing 374damaging 375expanding 376expanding parents 378extending background to the

left 359extending to the right 359freeing 380

May 31, 2004 Index 1271


freeing all 379getting all 372getting current 381getting root 394getting selected 382, 396,

397index 387reallocating 388removing 391, 392removing children 390resizing 389, 393selecting 395setting current 383showing 399unselecting 401, 402

linescolor 359displaying 359indenting 358spacing 359

marginsdisplaying 359

margins, color 360Pt ARG TREE FLAGS 358,

384Pt ARG TREE LINE COLOR

359Pt ARG TREE LINE SPACING

359Pt ARG TREE MARGIN COLOR

360Pt CB DND 365Pt CB GEN TREE INPUT

360selection

clearing 373PtGenTreeAddAfter() 369

PtGenTreeAddFirst() 370PtGenTreeAllItems() 372PtGenTreeClearSelection() 373PtGenTreeCollapse() 374PtGenTreeDamageItem() 375PtGenTreeExpand() 376, 729PtGenTreeExpandParents() 378PtGenTreeFreeAllItems() 379PtGenTreeFreeItems() 380PtGenTreeGetCurrent() 381PtGenTreeGetSelIndexes() 382PtGenTreeGoto() 383PtGenTreeInput t 360PtGenTreeItem t 384PtGenTreeItemIndex() 387PtGenTreeItemRealloc() 388PtGenTreeItemResize() 389PtGenTreeRemoveChildren() 390PtGenTreeRemoveItem() 391PtGenTreeRemoveList() 392PtGenTreeResize() 393PtGenTreeRootItem() 394PtGenTreeSelect() 395PtGenTreeSelectedItems() 396PtGenTreeSetSelIndexes() 397PtGenTreeShow() 399PtGenTreeUnselect() 401PtGenTreeUnselectNonBrothers() 402Pt GETS FOCUS 523, 524, 1030,

1159PtGetStyleMember() 58Pt GHOST 1159Pt GRADIENT TITLE AREA 177PtGraphic 403

callbacksrescale 413

colors

1272 Index May 31, 2004


fill 411inside 411

dashscaling 410style 410

flags 410lines

cap style 412join style 412width 412

origin 405, 413floating 410

points 405, 413position, floating 410Pt ARG DASH LIST 410Pt ARG DASH SCALE 410Pt ARG GRAPHIC FLAGS

410Pt ARG INSIDE COLOR 411Pt ARG LINE CAP 412Pt ARG LINE JOIN 412Pt ARG LINE WIDTH 412Pt ARG ORIGIN 405, 406,

413Pt ARG POINTS 405, 413Pt CB RESCALE 413

PtGrid 417lines

horizontal, number of 418vertical, number of 418

Pt ARG GRID HORIZONTAL418

Pt ARG GRID VERTICAL418

Pt GRID 1019Pt GRID ABOVE TRENDS 1019Pt GRID FORCE 1019

Pt GRID IS TRANSLUCENT 1019PtGroup 422

callbacksactivate 922

cellshorizontal alignment 423vertical alignment 423

childrenaligning 426exclusive choice 424forcing equal height 425forcing equal size 424forcing equal width 425horizontal alignment 425no choice 424spacing between 426, 427stretching horizontally 425stretching vertically 425vertical alignment 427

flags 424horizontal wrapping,

preventing 424keys, preventing use of 424number of rows and

columns 426orientation 426Pt ARG CELL HORZ ALIGN

423Pt ARG CELL VERT ALIGN

423Pt ARG GROUP FLAGS

424, 921Pt ARG GROUP HORZ ALIGN

425Pt ARG GROUP ORIENTATION

426

May 31, 2004 Index 1273


Pt ARG GROUP ROWS COLS426

Pt ARG GROUP SPACING426

Pt ARG GROUP SPACING X427

Pt ARG GROUP SPACING Y427

Pt ARG GROUP VERT ALIGN427

Pt CB ACTIVATE 922vertical wrapping,

preventing 424Pt GROUP ASIS 426Pt GROUP EQUAL SIZE 424Pt GROUP EQUAL SIZE HORIZONTAL

425Pt GROUP EQUAL SIZE VERTICAL

425Pt GROUP EXCLUSIVE 424, 921Pt GROUP HORIZONTAL 426Pt GROUP HORZ CENTER 423,

425Pt GROUP HORZ LEFT 423, 425Pt GROUP HORZ RIGHT 423, 425Pt GROUP NO KEYS 424Pt GROUP NO KEY WRAP 424Pt GROUP NO KEY WRAP HORIZONTAL

424Pt GROUP NO KEY WRAP VERTICAL

424Pt GROUP NO SELECT ALLOWED 424Pt GROUP STRETCH FILL 425Pt GROUP STRETCH HORIZONTAL 425Pt GROUP STRETCH VERTICAL 425Pt GROUP VERT BOTTOM 424,

427

Pt GROUP VERT CENTER 424,427

Pt GROUP VERTICAL 426Pt GROUP VERT TOP 424, 427Pt HIGHLIGHTED 1160PtHold() 336Pt HORIZONTAL GRADIENT 51PtHotkeyCallback t 11, 1176Pt HOTKEY IGNORE MODS 11Pt HOTKEYS FIRST 178Pt HOTKEY SYM 11Pt HOTKEY TERMINATOR 178Pt IGNORE 1175Pt IMAGE 82, 432, 442Pt INFLATE BALLOON 5, 185, 440Pt IN FLUX 1160Pt INHERIT COLOR 582–584Pt INHERIT FONT 581, 583Pt INSERT MODE 895Pt INTERNAL HELP 1157, 1164Pt KEY MOVED 527PtLabel 431

accelerator key 438backfilling text 441balloons

customizing 440enabling 441enabling if clipped 441fill color 438position 436, 439text 436, 439text color 438

creating 432flags 436, 441font 432, 445horizontal alignment 433, 439,

444

1274 Index May 31, 2004


imagedata 434, 442position 432, 439spacing relative to text 432,

445line spacing 443margins

bottom 433, 443left 432, 443right 433, 443top 433, 444

Pt ARG ACCEL KEY 438Pt ARG BALLOON COLOR

438Pt ARG BALLOON FILL COLOR

438Pt ARG BALLOON POSITION

432, 436, 439Pt ARG BALLOON TEXT

439Pt ARG HORIZONTAL ALIGNMENT

433, 439Pt ARG LABEL BALLOON

440Pt ARG LABEL FLAGS 436,

441Pt ARG LABEL IMAGE 434,

442Pt ARG LABEL TYPE 432,

442Pt ARG LINE SPACING 432,

443Pt ARG MARGIN BOTTOM

433, 443Pt ARG MARGIN LEFT 432,

443

Pt ARG MARGIN RIGHT433, 443

Pt ARG MARGIN TOP 433,444

Pt ARG SECONDARY H ALIGN433, 444

Pt ARG SECONDARY V ALIGN444

Pt ARG TEXT FONT 432,445

Pt ARG TEXT IMAGE SPACING445

Pt ARG TEXT STRING 432,436, 445

Pt ARG UNDERLINE1 445Pt ARG UNDERLINE2 445Pt ARG UNDERLINE TYPE

446Pt ARG VERTICAL ALIGNMENT

433, 446shifting when selected 441text 432, 445

position 432, 439spacing relative to

image 432, 445using ellipsis 441

type 432, 442underline color 445underline type 446vertical alignment 433, 444,

446Pt LABEL SELECT SHIFT 441Pt LEFT ANCHORED LEFT 1152Pt LEFT ANCHORED RIGHT 1152Pt LEFT BEVEL 49Pt LEFT ETCH 49Pt LEFT INLINE 50, 55

May 31, 2004 Index 1275


Pt LEFT OUTLINE 49, 57PtLine 450

Pt ARG ORIGIN 450Pt ARG POINTS 450

PtList 455balloon function 459callbacks

drag and drop 468mouse and key event 461selection 457, 462

convenience functions 469creating 456items

adding 471array of 458, 459checking existence of 477deleting a range 474deleting all 473deleting specific 475determining position of 478displaying in columns 456getting 457number displayed 457removing by position 479replacing 481replacing by position 480selected 461selecting by position 482setting the current 476showing by position 483spacing between 460unselecting 484

methodsList Draw 330

Pt ARG ITEMS 458, 459Pt ARG LIST BALLOON 459

Pt ARG LIST COLUMN POS456

Pt ARG LIST SPACING 460Pt ARG MODIFY ITEMS

460Pt ARG SELECTION INDEXES

461Pt ARG VISIBLE COUNT

457, 468Pt CB DND 468Pt CB LIST INPUT 461Pt CB SELECTION 457, 462PtDivider as child 456selection policy

browse 458extended 458multiple 458single 458

PtListAddItems() 471Pt LIST BALLOON AS REQUIRED

303, 961Pt LIST BALLOONS IN COLUMNS

303, 714Pt LIST BOUNDARY KEY EVENTS

303PtListCallback t 457, 463PtListColumn t 302PtListColumnAttributes t

301Pt LIST COLUMN CENTER 302Pt LIST COLUMN DAMAGE ALWAYS

302Pt LIST COLUMN ELLIPSIS 301Pt LIST COLUMN ELLIPSIS INVERT

302Pt LIST COLUMN ELLIPSIS MIDDLE

301

1276 Index May 31, 2004


Pt LIST COLUMN LEFT 302Pt LIST COLUMN NO STRING 302,

944Pt LIST COLUMN RIGHT 302PtListDeleteAllItems() 473PtListDeleteItemPos() 474PtListDeleteItems() 475PtListDndCallback t 316,

468PtListGotoPos() 476Pt LIST HEADER AUTORESIZE 303PtListInput t 461Pt LIST ITEM ABOVE 337Pt LIST ITEM BELOW 337Pt LIST ITEM CURRENT 321, 337,

338, 951Pt LIST ITEM DAMAGED 336,

337, 344, 953Pt LIST ITEM DNDSELECTED DOWN

237, 317, 366, 468, 723,735, 962

Pt LIST ITEM DNDSELECTED IN237, 317, 366, 469, 723,735, 962

Pt LIST ITEM DNDSELECTED UP237, 317, 365, 468, 723,735, 962

PtListItemExists() 477Pt LIST ITEM FLAG USER[1234]

953Pt LIST ITEM FLAG USER* 338Pt LIST ITEM INWIDGET 337PtListItemPos() 478Pt LIST ITEM SELECTED 321,

337, 338, 395, 951Pt LIST ITEM USED FLAGS 338Pt LIST NOBLIT 304

Pt LIST NO COLUMN LINES 304Pt LIST NON SELECT 304PtListRemovePositions() 479PtListReplaceItemPos() 480PtListReplaceItems() 481Pt LIST SCROLLBAR ALWAYS 298,

304Pt LIST SCROLLBAR AS REQUIRED

298, 304Pt LIST SCROLLBAR AUTORESIZE

304Pt LIST SCROLLBAR GETS FOCUS

304Pt LIST SCROLL LIST 312Pt LIST SCROLL SCROLLBAR 312Pt LIST SELECTION BROWSE 230,

954Pt LIST SELECTION CANCEL 230,

954Pt LIST SELECTION FINAL 230,

954PtListSelectPos() 482Pt LIST SHOW BALLOON 304PtListShowPos() 483Pt LIST SNAP 304PtListUnselectPos() 484PtMenu 485

activating via an eventhandler 490

appearance, controlling 487cascaded menus 492click-stay mode 487creating 487destroying 489destroying on closing 498example 493flags 486, 488, 489, 492, 497

May 31, 2004 Index 1277


gradient fill 498items

accelerators 486font 488, 498forcing equal widths 497hotkeys 486making selectable 486selecting 487spacing between 498widget types 486

labels 488lifetime 489menu bar 486overriding parent menu 498PhAB’s Menu module, using

instead 486populating 488popup 486, 490positioning 489press-drag-release mode 487Pt ARG BEVEL WIDTH 498Pt ARG FLAGS 488Pt ARG MENU FLAGS

486–489, 492, 497Pt ARG MENU SPACING

498Pt ARG MENU TEXT FONT

488, 498Pt ARG MENU TITLE 488,

499Pt ARG MENU TITLE FONT

488, 499pulldown 489separators 488sizing 488submenus 486tear off 498

text alignment 498title 488, 499title font 488, 499

Pt MENUABLE 44, 1160Pt MENU AUTO 488, 497PtMenuBar 503. See also PtMenu

anchoring 503children 503

PtMenuButton 508accelerator

displaying 510font 509key 508modifier keys 510text 509x offset 510

callbacksarm 489menu 489

menu position 510Pt ARG ACCEL FONT 509Pt ARG ACCEL KEY 508Pt ARG ACCEL TEXT 509Pt ARG BUTTON TYPE 492,

509Pt ARG MODIFIER KEYS

510Pt ARG OFFSET 510Pt CB ARM 489Pt CB MENU 489type 509

Pt MENU BUTTON 1160Pt MENU CHILD 486, 492, 498Pt MENU DOWN 510Pt MENU GRADIENT 498Pt MENU RIGHT 492, 510Pt MENU TEAR OFF 498

1278 Index May 31, 2004


Pt MENU TEXT 510Pt MENU TEXT ALIGN 498Pt MENU TRANSIENT 489, 498Pt MENU UP 510PtMeter 515

callbacksneedle movement 527

colorcenter 522font 523level 1 524level 2 524level 3 525needle 526outline 522ticks 522

examples 516flags 522flickering 518font 526interactive 522key

increment 523left 515, 523movement with 515right 515, 524

levels, number of 526maximum 525minimum 525mouse movement 515no text 522noninteractive 522position

level 1 524level 2 525maximum 525minimum 525

needle 515, 526Pt ARG FLAGS 523, 524Pt ARG METER COLOR 522Pt ARG METER FLAGS 522Pt ARG METER FONT COLOR

523Pt ARG METER INCREMENT

523Pt ARG METER KEY LEFT

515, 523Pt ARG METER KEY RIGHT

515, 524Pt ARG METER LEVEL1 COLOR





525Pt ARG METER MAX NEEDLE POSITION

525Pt ARG METER MIN NEEDLE POSITION

525Pt ARG METER NEEDLE COLOR



526, 527Pt ARG METER NUM SEVERITY LEVELS

526Pt ARG METER TEXT FONT

526Pt CB METER MOVED 527

May 31, 2004 Index 1279


severity arcs 515size 516

PtM NON SELECTABLE 522PtM NO TEXT 522Pt MOUSE MOVED 527PtM SELECTABLE 522Pt MT BACKGROUND 562, 597,

600Pt MT BACKGROUND COLOR 562,

597, 600Pt MT FLAGS 563, 597, 600Pt MT FONT 562, 597, 600Pt MT FOREGROUND 562, 597,

600Pt MT QUERY CHAR 593PtMTrend 532

adding or changing graphdata 538

attributes 534graph attributes 536graph drawing state 538grid color 540grid draw function 540grid lines 540number of graphs 536number of samples 536Pt ARG MTREND ADVANCE BY N SAMPLES

541Pt ARG MTREND ATTRIBUTES

534Pt ARG MTREND GRAPH ATTR

536Pt ARG MTREND GRAPH DATA

538Pt ARG MTREND GRAPH STATE

538

Pt ARG MTREND GRID COLOR540

Pt ARG MTREND GRID DRAW F540

Pt ARG MTREND GRID X540

Pt ARG MTREND GRID Y540

Pt ARG MTREND N GRAPHS536

Pt ARG MTREND N SAMPLES536

Pt ARG MTREND TRACE DRAW F539

Pt ARG MTREND TRACE WIDTH539

scrolling 541trace line drawing

function 539trace line width 539trends

data, replacing 545PtMTrendAddData() 545PtMTrendChangeData() 545Pt MT TAG 555, 563, 597, 600Pt MT TEXT COLOR 562, 597, 600PtMultiLines t 550, 564, 581Pt MULTIPLE MODE 230, 308PtMultiText 547

attributescreating 587getting 562, 588modifying 552, 562, 597,

599callbacks

activate 571got focus 573

1280 Index May 31, 2004


lost focus 573modify notify 575modify verify 576motion notify 575motion verify 577text changed 575

character information,getting 561, 592

color 581, 583convenience functions 579cursor tracking, enabling 561dimensions 557features 547flags 560, 571flags, wrapping 564font 552, 581, 583hyperlinks 555indentation, automatic 560lines

bottom 560displaying if there’s

room 560getting information 562, 592number of 561number visible 561spacing 548top 564, 565

Pt ARG COLOR 549, 582,584

Pt ARG DIM 557Pt ARG FILL COLOR 549,

582, 584Pt ARG FLAGS 571Pt ARG LINE SPACING 548Pt ARG MULTITEXT BOTTOM LINE

560

Pt ARG MULTITEXT FLAGS560

Pt ARG MULTITEXT NUM LINES561

Pt ARG MULTITEXT NUM LINES VISIBLE

561Pt ARG MULTITEXT QUERY CHARACTER

561Pt ARG MULTITEXT QUERY LINE

557, 562Pt ARG MULTITEXT RANGE ATTRIBUTES

550, 552, 562Pt ARG MULTITEXT ROWS

563Pt ARG MULTITEXT SEGMENTS

549, 550, 563Pt ARG MULTITEXT TABS

564Pt ARG MULTITEXT TOP LINE

564Pt ARG MULTITEXT WRAP FLAGS

548, 564Pt ARG MULTITEXT X SCROLL POS

565Pt ARG MULTITEXT Y SCROLL POS


549, 566Pt ARG SCROLLBAR X HEIGHT

566Pt ARG SCROLLBAR Y DISPLAY

549, 566Pt ARG SCROLLBAR Y WIDTH

567Pt ARG TEXT FLAGS 571Pt ARG TEXT FONT 549,

581, 583

May 31, 2004 Index 1281


Pt ARG TEXT STRING 549,564

Pt ARG TEXT SUBSTRING549

Pt CB ACTIVATE 571Pt CB GOT FOCUS 573Pt CB LOST FOCUS 573Pt CB MODIFY NOTIFY

575Pt CB MODIFY VERIFY 576Pt CB MOTION NOTIFY

575Pt CB MOTION VERIFY 577Pt CB TEXT CHANGED 575rows, number of 563scrollbars

displaying 566height 566position 565width 567

scrolling, automatic 561tab stops 564text

inserting 551modifying 599multisegment 563ranges of 550setting 549setting attributes 550

wrapping 548carriage return 565end of line 565word break 565

PtMultiTextAttributes t

583PtMultiTextCallback t 554,

585, 880

PtMultiTextControl t 554,562, 585

PtMultiTextCreateAttributes() 587PtMultiTextGetAttributes() 588PtMultiTextInfo t 585PtMultiTextInfo() 592PtMultiTextLine t 557, 595PtMultiTextModifyAttributes() 552,

597PtMultiTextModifyText() 549–551,

599PtMultiTextQuery t 557, 561,

562, 601PtMultiTextSegment t 603Pt NOLINE 786Pt NO ULINE 446PtNumeric 605

buttonsdisplaying 606width 607

flags 606Pt ARG NUMERIC FLAGS

606Pt ARG NUMERIC PREFIX

606Pt ARG NUMERIC SPACING

607Pt ARG NUMERIC SUFFIX

607Pt ARG NUMERIC UPDOWN WIDTH

607spacing 607text

autohighlighting 606hexadecimal 606inserting commas 606prefix 606

1282 Index May 31, 2004


suffix 607wrapping 606

Pt NUMERIC AUTO HIGHLIGHT 606Pt NUMERIC CHANGED 614, 621Pt NUMERIC ENABLE UPDOWN 606PtNumericFloat 611

callbacksactivate 618value changed 613

increment 612precision 613Pt ARG NUMERIC INCREMENT

612Pt ARG NUMERIC MAX 613Pt ARG NUMERIC MIN 613Pt ARG NUMERIC PRECISION

613Pt ARG NUMERIC VALUE

613Pt CB ACTIVATE 618Pt CB NUMERIC CHANGED

613value

current 613maximum 613minimum 613

PtNumericFloatCallback t

614Pt NUMERIC HEXADECIMAL 606PtNumericInteger 619

callbacksactivate 626value changed 621

increment 620Pt ARG NUMERIC INCREMENT

620Pt ARG NUMERIC MAX 620

Pt ARG NUMERIC MIN 620Pt ARG NUMERIC VALUE

621Pt CB ACTIVATE 626Pt CB NUMERIC CHANGED

621value

current 621hexadecimal 619maximum 620minimum 620

PtNumericIntegerCallback t

622Pt NUMERIC SET 614, 621Pt NUMERIC UPDOWN ACTIVATE 614,

621Pt NUMERIC UPDOWN REPEAT 614,

621Pt NUMERIC USE SEPARATORS 606Pt NUMERIC WRAP 606Pt OBSCURED 1160PtOnOffButton 627

Pt ARG FLAGS 628Pt ARG ONOFF STATE 628Pt CB ONOFF NEW VALUE

628Pt OPAQUE 1160Pt OPAQUE ETCHES 49PtOSContainer 633

fill color 636Pt ARG FILL COLOR 636

PtPane 637PtPanelGroup 641

convenience functions 655copying as popup window 656drag and drop 647flags 647

May 31, 2004 Index 1283


marginsbottom 644, 645left 644, 645right 644, 646top 644, 646

panel index, finding 659, 660panel pointer, finding 661, 662panel title, finding 663panel titles 648panels

current 646switching 649

Pt ARG FLAGS 650Pt ARG MARGIN BOTTOM

644, 645Pt ARG MARGIN LEFT 644,

645Pt ARG MARGIN RIGHT

644, 646Pt ARG MARGIN TOP 644,

646Pt ARG PG CURRENT 646Pt ARG PG CURRENT INDEX

646Pt ARG PG FLAGS 647Pt ARG PG OVERLAP THRESHOLD

648Pt ARG PG PANEL TITLES

648Pt ARG PG SELECTION MODE

649Pt CB PG PANEL SWITCHING

649selection mechanism

location 647selection mode 649selector

none 649tabs

color 648displaying one per panel 649displaying only one 649forcing equal size 647overlap 648

Pt PG AUTO 649Pt PG DND 647Pt PG MULTI CONTAINER MODE 647Pt PG NONE 649Pt PG SELECTOR ALIGN RIGHT 647Pt PG SELECTOR ON BOTTOM 647Pt PG SINGLE TAB 649Pt PG TABS EQUAL SIZE 647Pt PG USE PANEL COLORS 648PtPixel 664

Pt ARG POINTS 664Pt PIXEL 1019PtPolygon 668

closed 669flags 668, 669Pt ARG ORIGIN 668Pt ARG POINTS 668Pt ARG POLYGON FLAGS

668, 669relative coordinates 669

Pt POP BALLOON 5, 185PtPositionMenu() 489PtPrintSel 673

callbacksprint properties 682

convenience functions 686flags 677labels

all pages 678collate pages 678

1284 Index May 31, 2004


double sided 679file name 679install button 679not collated 680number of copies 678pages from 679pages to 682preferences 680print order 680print pages 680print range 680print selected 681printer name 679reverse order 681send to file 681send to printer 681

print context 674, 676Pt ARG PRINT CONTEXT

674, 676Pt ARG PRINT FLAGS 677Pt ARG PS LBL ALL 678Pt ARG PS LBL COLLATED

678Pt ARG PS LBL COPIES

678Pt ARG PS LBL DOUBLE SIDED

679Pt ARG PS LBL FILE 679Pt ARG PS LBL FROM 679Pt ARG PS LBL INSTALL

679Pt ARG PS LBL NAME 679Pt ARG PS LBL NOT COLLATED

680Pt ARG PS LBL PREFERENCES

680

Pt ARG PS LBL PRINT ORDER680

Pt ARG PS LBL PRINT PAGES680

Pt ARG PS LBL RANGE 680Pt ARG PS LBL REVERSED

681Pt ARG PS LBL SELECTION

681Pt ARG PS LBL SEND TO FILE

681Pt ARG PS LBL SEND TO PRINTER

681Pt ARG PS LBL TO 682Pt CB PRINT PROPS 682

Pt PRINTSEL ALL PANES 678Pt PRINTSEL DFLT LOOK 678Pt PRINTSEL FILE PANE 677Pt PRINTSEL NO COPIES 677Pt PRINTSEL NO PAGE RANGE 677Pt PRINTSEL NO PRINTSELECT 677Pt PRINTSEL NO SELECT RANGE

677Pt PRINTSEL PREFERENCES 677Pt PRINTSEL SETTINGS PANE 677Pt PROCESS 1175Pt PROCREATED 187, 1160PtProgress 687

callbacksvalue changed 688

color 688convenience functions 692flags 687number of divisions 688Pt ARG GAUGE FLAGS 687Pt ARG PROGRESS BAR COLOR

688

May 31, 2004 Index 1285


Pt ARG PROGRESS DIVISIONS688

Pt ARG PROGRESS GAP689

Pt ARG PROGRESS SPACING689

Pt CB GAUGE VALUE CHANGED688

segments, gettingnext 698zzzzzzzzzz 694, 696

spacingbar and text 689divisions 689

text area, getting 700PtProgressEntireSegment() 694PtProgressFirstSegment() 696PtProgressNextSegment() 698Pt PROGRESS NO MORE SEGMENTS

694, 696, 698PtProgressTextRect() 700Pt RANGE MODE 231, 308, 952,

955not supported

byPtTreeUnselect() 1012PtRaw 701

clippingrestoring 703setting 702

color 704connect function 706custom widgets 701damage 701data model 702data, user-defined 702drawing

function 702

drawing function 706example 704extent function 706fill color 704initialization function 707opacity-calculation

function 705Pt ARG COLOR 704Pt ARG FILL COLOR 704Pt ARG POINTER 702Pt ARG RAW CALC OPAQUE F

705Pt ARG RAW CONNECT F

706Pt ARG RAW DRAW F 702,

706Pt ARG RAW EXTENT F

706Pt ARG RAW INIT F 707Pt ARG USER DATA 702redrawing 701scaling 703translation

restoring 703setting 703

PtRawCallback t 13, 1178PtRawList 711

callbacksdrag and drop 723

convenience functions 724flags 713functions

background 712draw 712inflate balloon 715key event 716mouse event 717

1286 Index May 31, 2004


selection 718Pt ARG RAWLIST BACKGROUND F

712Pt ARG RAWLIST DRAW F

712Pt ARG RAWLIST GFLAGS

713Pt ARG RAWLIST INFLATE F

715Pt ARG RAWLIST KEY F

716Pt ARG RAWLIST MOUSE F

717Pt ARG RAWLIST SELECT F

718Pt CB DND 723

PtRawListDrawBackgroundF t

712PtRawListInflateF t 715PtRawListMouseF t 717PtRawListSelectF t 718PtRawTree 725

balloonlocation 734

callbacksdrag and drop 734

convenience functions 735flags 734functions

draw 726inflate balloon 727selection 728state 729

Pt ARG RAWTREE DRAW F726

Pt ARG RAWTREE INFLATE F727

Pt ARG RAWTREE SELECT F728

Pt ARG RAWTREE STATE F729

Pt ARG TREE FLAGS 734Pt CB DND 734

PtRawTreeDrawItemF t 726PtRawTreeInflateF t 727PtRawTreeItemStateF t 729PtRawTreeSelectF t 728Pt REALIZED 1160Pt REALIZING 1160PtRect 736

dimensions 736points 736position 736Pt ARG DIM 736Pt ARG POINTS 736Pt ARG POS 736Pt ARG RECT ROUNDNESS

736, 737rounding corners 736, 737

PtRegion 741data 742flags 744handle 744input group 745instantiation 741opacity 745owner 745Pt ARG REGION DATA 742Pt ARG REGION FIELDS

742Pt ARG REGION FLAGS

744Pt ARG REGION HANDLE

744

May 31, 2004 Index 1287


Pt ARG REGION INFRONT745

Pt ARG REGION INPUT GROUP745

Pt ARG REGION OPAQUE745

Pt ARG REGION OWNER745

Pt ARG REGION PARENT746

Pt ARG REGION SENSE746

regionin front 745parent 746

resources, changing 742sensitivity 746

Pt REGION 1161PtRelease() 344Pt RESIZE X ALWAYS 775, 1167Pt RESIZE X AS REQUIRED 775,

1167Pt RESIZE X BITS 775, 1167Pt RESIZE X INITIAL 775, 1167Pt RESIZE XY ALWAYS 776, 1167Pt RESIZE XY AS REQUIRED 776,

1167Pt RESIZE XY BITS 776, 1167Pt RESIZE XY INITIAL 776, 1167Pt RESIZE Y ALWAYS 775, 1167Pt RESIZE Y AS REQUIRED 775,

1167Pt RESIZE Y BITS 776, 1167Pt RESIZE Y INITIAL 775, 1167Pt REVERSE GRADIENT 51Pt RIGHT ANCHORED LEFT 1152Pt RIGHT ANCHORED RIGHT 1152

Pt RIGHT BEVEL 49Pt RIGHT ETCH 49Pt RIGHT INLINE 50, 55Pt RIGHT OUTLINE 49, 57PtScrollArea 750

arrow keys, ignoring 752callbacks

scrollbars moved 751, 756canvas, determining 761convenience functions 760displayed portion, position 754flags 752Pt ARG AREA 750, 753, 754Pt ARG FLAGS 756Pt ARG SCROLLAREA FLAGS

752Pt ARG SCROLLAREA INCREMENT X

753Pt ARG SCROLLAREA INCREMENT Y

753Pt ARG SCROLLAREA MAX X

750, 753Pt ARG SCROLLAREA MAX Y

750, 754Pt ARG SCROLLAREA POS X

754Pt ARG SCROLLAREA POS Y


750, 754Pt ARG SCROLLBAR X HEIGHT

755Pt ARG SCROLLBAR Y DISPLAY

750, 755Pt ARG SCROLLBAR Y WIDTH

755

1288 Index May 31, 2004


Pt CB SCROLLAREA SCROLLED751, 756

scrollbarsdisplaying 750, 754, 755height 755increment 753width 755

scrollingcontrol 751notification 751

sizephysical 750virtual 750, 753, 754

PtScrollAreaCanvas() 761Pt SCROLLAREA ENABLE PAN 753Pt SCROLLAREA IGNORE KEYS 752PtScrollbar 762

arrow buttons, displaying 766bandwidth threshold 772callbacks

scrolled 767flags 766handle length

current 766minimum 765

incrementpage 765step 765

keyboard actions 764mouse actions 763Pt ARG BANDWIDTH THRESHOLD

772Pt ARG FLAGS 767Pt ARG INCREMENT 765Pt ARG MIN SLIDER SIZE

765

Pt ARG PAGE INCREMENT765

Pt ARG SCROLLBAR FLAGS766

Pt ARG SLIDER SIZE 765,766

Pt CB SCROLL MOVE 767rendering as if focused 766slider, fixed size 766

Pt SCROLLBAR FIXED SLIDER SIZE766

Pt SCROLLBAR FOCUSED 766Pt SCROLLBAR SHOW ARROWS 766PtScrollContainer 773

anchors 774flags 775Pt ARG SCROLLCONT FLAGS

775Pt ARG SCROLLCONT RESIZE FLAGS

775resize flags 775resize policy 774

Pt SCROLLCONT TRACK FOCUS 775Pt SCROLL DECREMENT 312, 767Pt SCROLL DRAGGED 313, 768Pt SCROLL INCREMENT 312, 767Pt SCROLL JUMP 313, 768Pt SCROLL PAGE DECREMENT 312,

768Pt SCROLL PAGE INCREMENT 312,

767Pt SCROLL RELEASED 313, 768Pt SCROLL SET 313, 768Pt SCROLL TO MAX 313, 768Pt SCROLL TO MIN 313, 768Pt SELECTABLE 43, 486, 488, 571,

888, 906, 1161, 1171

May 31, 2004 Index 1289


Pt SELECTION MODE AUTO 309Pt SELECTION MODE MULTIPLE 309,

321Pt SELECTION MODE NOCLEAR 309Pt SELECTION MODE NOFOCUS 310Pt SELECTION MODE NOMOVE 309Pt SELECTION MODE NONE 309,

321Pt SELECTION MODE NOREST 309Pt SELECTION MODE NOSCROLL 309Pt SELECTION MODE RANGE 309,

321, 345, 348, 352, 401,719, 728

Pt SELECTION MODE SINGLE 309,321, 348

Pt SELECTION MODE TOGGLE 310Pt SELECT NOREDRAW 1161PtSeparator 780

flags 784orientation 784Pt ARG SEP ARM BITMAP CURSOR

781Pt ARG SEP ARM CURSOR COLOR

783Pt ARG SEP ARM CURSOR TYPE

783Pt ARG SEP DRAG BOUNDS

783Pt ARG SEP FLAGS 784Pt ARG SEP IMAGE 784Pt ARG SEP IMAGE H ALIGN

785Pt ARG SEP IMAGE V ALIGN

785Pt ARG SEP TYPE 785Pt CB SEP DRAG 786type 785

PtServer 790callbacks

connected 792error 793receive 794transport 794

connection object 791instantiation 790messages, sending to

client 792name 792Pt ARG SERVER CONNECTION

791Pt ARG SERVER NAME 792Pt ARG SERVER SEND 792Pt CB SERVER CONNECTED

792Pt CB SERVER ERROR 793Pt CB SERVER RECEIVE

794Pt CB SERVER TRANSPORT

794PtServerCallback t 794Pt SET 921, 1161PtSetWidgetStyle() 58Pt SHOW BALLOON 436, 441Pt SHOW TITLE 178, 184Pt SINGLE DASH LINE 785Pt SINGLE LINE 785Pt SINGLE MODE 231, 308Pt SINGLE ULINE 446Pt SKIP LAYOUT 1157PtSlider

callbacksmovement 806

flags 802gauge flags 805

1290 Index May 31, 2004


handlecolor 802image 802, 803width 803

increment 803increment, multiple 803keyboard actions 800mouse actions 800Pt ARG FLAGS 806Pt ARG GAUGE FLAGS 805Pt ARG SLIDER FLAGS 802Pt ARG SLIDER HANDLE COLOR

802Pt ARG SLIDER HANDLE WIDTH

803Pt ARG SLIDER IMAGE 803Pt ARG SLIDER INCREMENT

803Pt ARG SLIDER MULTIPLE

803Pt ARG SLIDER TICK MAJOR DIV

804Pt ARG SLIDER TICK MAJOR LEN

804Pt ARG SLIDER TICK MINOR DIV

804Pt ARG SLIDER TICK MINOR LEN

804Pt ARG SLIDER TROUGH IMAGE1

804Pt ARG SLIDER TROUGH IMAGE2

804Pt CB SLIDER MOVE 806ticks, major

length 804number of 804

ticks, minor

length 804number of 804

troughimage 804

PtSliderCallback t 807Pt SLIDER DECREMENT 806Pt SLIDER DRAGGED 806Pt SLIDER IMAGE 802Pt SLIDER INCREMENT 806Pt SLIDER JUMP 807Pt SLIDER MULTIPLE DECREMENT

806Pt SLIDER MULTIPLE INCREMENT

806Pt SLIDER RELEASED 806Pt SLIDER SET 807Pt SLIDER TO MAX 807Pt SLIDER TO MIN 806Pt SLIDER TROUGH IMAGE 802Pt STATIC BEVELS 51Pt STATIC GRADIENT 51PtTab 811

convenience functions 817displaying upside down 812flags 812Pt ARG TAB FLAGS 812Pt TAB UNSELECTED COLOR

813typical usage 811unselected color 813

Pt TAB DRAG HANDLE 812Pt TAB MULTI 813Pt TAB RIGHTSIDE LEFT 812Pt TAB UNSELECTED COLOR

813Pt TAB UPSIDE DOWN 812

May 31, 2004 Index 1291


Pt TERM ANCHOR PARENT HEIGHT841

Pt TERM ANCHOR PARENT WIDTH841

Pt TERM ANCHOR WINDOWS ONLY841

Pt TERM COLOR MODE 833Pt TERM CTRLBRK INPUT 847Pt TERM CURSOR ALWAYS 836Pt TERM CURSOR NEVER 836Pt TERM CURSOR NOSPEEDCHK 836Pt TERM CURSOR ON FOCUS 836Pt TERM CURSOR TIMER 836PtTerminal 818

ANSI protocol 830application window state 831

callback 845bandwidth, not checking 837blitting 836callbacks

font changed 846input 847options changed 849resizing, after 851resizing, before 849

character sets 821, 832creating translation

tables 862characters, outputting 873clipboard

copying to 861pasting from 871

clipped, assuming widgetisn’t 837

colorcoding 827mode 833

table 833columns

current 835maximum number of 839minimum number of 839number of 834

console emulation 826convenience functions 856cursor

blinking 836not checking for speed 836position 835timer 836

escape sequences 840flags 836font

enabling escapesequences 841

index 820, 837list of 820, 838maintaining widget size 841name 820, 837setting via keyboard 841size 838verifying 865

function reentrancy 822geometry 822line-editing keys, getting 867margins 838name, getting 870options 840

disabling 840protocol 830Pt ARG AREA 822, 823Pt ARG BANDWIDTH THRESHOLD

828, 856Pt ARG DIM 822–824, 826

1292 Index May 31, 2004


Pt ARG FILL COLOR 856Pt ARG MARGIN HEIGHT

822–824, 838Pt ARG MARGIN WIDTH

822–824, 838Pt ARG TERM ANSI PROTOCOL

830Pt ARG TERM APP 831Pt ARG TERM CHARSETS

822, 832Pt ARG TERM COLOR MODE

833Pt ARG TERM COLOR TABLE

827, 833Pt ARG TERM COLS 822,

823, 834, 850, 851Pt ARG TERM CONSOLE

826, 835Pt ARG TERM CUR COL

835Pt ARG TERM CUR POS

835Pt ARG TERM CUR ROW

835Pt ARG TERM CURSOR FLAGS

836Pt ARG TERM DRAW MODES

828, 836Pt ARG TERM FONT 820,

822, 823, 837Pt ARG TERM FONT INDEX

820, 822, 837Pt ARG TERM FONT LIST

820, 838Pt ARG TERM FONT SIZE

838

Pt ARG TERM MARGINS822, 824, 826, 838

Pt ARG TERM MAXCOLS826, 839

Pt ARG TERM MAXROWS826, 839

Pt ARG TERM MAXSIZE826, 839, 850

Pt ARG TERM MINCOLS825, 839

Pt ARG TERM MINROWS825, 840

Pt ARG TERM MINSIZE825, 840, 850

Pt ARG TERM OPTIONS840

Pt ARG TERM OPTMASK840

Pt ARG TERM RESIZE FL841

Pt ARG TERM RESIZE FUN823, 841

Pt ARG TERM RESIZE STR823, 825, 842

Pt ARG TERM ROWS 822,823, 842, 850, 851

Pt ARG TERM SCRLBK COUNT842

Pt ARG TERM SCRLBK LIMIT842

Pt ARG TERM SCRLBK POS842

Pt ARG TERM SCROLL 828,843

Pt ARG TERM SELECTION843

May 31, 2004 Index 1293


Pt ARG TERM SIZE822–824, 844, 850, 851

Pt ARG TERM VISUAL BELL845

Pt CB TERM APP 845Pt CB TERM FONT 846Pt CB TERM INPUT 847,

871, 872Pt CB TERM OPTIONS 849Pt CB TERM RESIZE 849Pt CB TERM RESIZED 851Pt CB TERM SCRLBK 852QNX 4 protocol 830redrawing

always 836on first scroll 836

resizing 823adjusting after 824flags 841hint 842parent widget 841resize function 841resize function, default 825

rowscurrent 835maximum number of 839minimum number of 840number of 842

screen size 844maximum 839minimum 840

scrollback buffercallback 852maximum number of

lines 842number of lines saved 842position in 842

scrolling optimization 827,836

scrolls, maximum numberdelayed 843

selectioncurrent 843getting current 869pasting current 872

size limits 825video memory 826, 835visual bell 845word, selecting 875

PtTerminalAppState t 831PtTerminalCharset t 858PtTerminalCharsets t 858PtTerminalCopy() 861PtTerminalCreateCsXlat() 862PtTerminalDefaultCharsets() 864PtTerminalFontChange t 847PtTerminalFontInfo() 865PtTerminalGetKeys() 867PtTerminalGetSelection() 869PtTerminalInput t 848PtTerminalName() 870PtTerminalOptionChange t

849PtTerminalPasteClipboard() 871PtTerminalPasteSelection() 872PtTerminalPut() 873PtTerminalPutc() 873PtTerminalPuts() 873PtTerminalRowCol t 835PtTerminalScrlbkCb t 852PtTerminalSelectWord() 875PtTerminalSizeChange t 850,

851, 1044Pt TERM KBFONT 820, 841

1294 Index May 31, 2004


Pt TERM KBFORCE 820, 841Pt TERM KEYBOARD INPUT 847Pt TERM MOUSE INPUT 847Pt TERM OPFONT 820, 841Pt TERM PASTE INPUT 848Pt TERM PASTE NF INPUT 848Pt TERM PROTOCOL INPUT 847Pt TERM SCROLL NOBLIT 836Pt TERM SCROLL NOHWCHK 836Pt TERM SCROLL NOSPEEDCHK 828,

837Pt TERM SCROLL NOVISCHK 837Pt TERM SCROLL RFSH 836Pt TERM SELECTING 844Pt TERM SELECTION ALWAYS 844Pt TERM SELECTION BLOCK 843Pt TERM SELECTION FIRST KEEP

844Pt TERM SELECTION FLAGS KEEP

844Pt TERM SELECTION LAST KEEP

844Pt TERM SELECTION NEVER 844Pt TERM SELECTION NONE 843Pt TERM SELECTION STREAM 843Pt TERM SELECTION TYPE KEEP

844PtText 877

arrow keys 887callbacks

activate 906activate, invoking when losing

focus 895changed 880, 885, 897got focus 886lost focus 886modify-notify 880, 885, 897

modify-verify 880, 898motion-notify 900motion-verify 887, 901

columns, number of 892convenience functions 908cursor position 893cursor width 895cursor, displaying 895edit mask 889, 893editable 895flags 888, 895, 906focus 886highlighting

background color 896text color 896when given focus 896

input filter 889, 893insert mode 877, 895interaction model 877keyboard actions 891maximum length 894mouse actions 890passwords, entering 883Pt ARG COLUMNS 892Pt ARG CURSOR POSITION

893Pt ARG DIM 892Pt ARG EDIT MASK 889,

893Pt ARG FLAGS 880, 888,

897, 899–901, 906, 912Pt ARG MAX LENGTH 894Pt ARG SELECTION RANGE

894Pt ARG TEXT CURSOR WIDTH

895

May 31, 2004 Index 1295


Pt ARG TEXT FLAGS 888,895, 906


896Pt ARG TEXT HIGHLIGHT TEXT COLOR

896Pt ARG TEXT STRING 878Pt ARG TEXT SUBSTRING

896Pt CB ACTIVATE 888, 906Pt CB GOT FOCUS 886, 907Pt CB LOST FOCUS 886,

907Pt CB MODIFY NOTIFY

880, 885, 897, 913Pt CB MODIFY VERIFY

880, 898, 912Pt CB MOTION NOTIFY

900Pt CB MOTION VERIFY

887, 901Pt CB TEXT CHANGED

880, 885, 897, 913replace mode 878, 895selection 878

getting current 911range 894setting 914

substring, getting orsetting 896

text 878getting 879modifying 878, 880, 912

Pt TEXT AUTO HIGHLIGHT 896PtTextCallback t 554, 572,

574–576, 578, 880, 898,899, 901, 907, 909

PtTextControl t 554, 909PtTextControlInfo t 909PtTextGetSelection() 553, 911Pt TEXT IMAGE 432, 442PtTextModifyText() 549–551, 880,

912PtTextSetSelection() 914Pt TG COLLAPSIBLE 935PtTimer 916

callbacksexpiration 917

initial time 917Pt ARG TIMER INITIAL 917Pt ARG TIMER REPEAT

917Pt CB TIMER ACTIVATE

917repetition time 917

Pt TIMER INITIAL 918Pt TIMER REPEAT 918Pt TOGGLE 1161

Pt CB ACTIVATE 59PtToggleButton 920

“set”checking to see if 921

callbacksactivate 921

creating 920exclusive choice 921grouping 921indicator

fill color 922types 920, 923

Pt ARG FLAGS 921Pt ARG INDICATOR COLOR

922

1296 Index May 31, 2004


Pt ARG INDICATOR TYPE923

Pt ARG USER DATA 922Pt CB ACTIVATE 921user-defined data 922

Pt TOGGLE CHECK 923Pt TOGGLE OUTLINE 923Pt TOGGLE RADIO 923PtToolbar 928

flags 929layout flags 930orientation 929Pt ARG ORIENTATION 929Pt ARG TOOLBAR FLAGS

929Pt ARG TOOLBAR LAYOUT FLAGS

930Pt ARG TOOLBAR SPACING

930spacing 930

Pt TOOLBAR DRAGGABLE 929Pt TOOLBAR END SEPARATOR 930Pt TOOLBAR FOLLOW FOCUS 930Pt TOOLBAR FROM LINE START 930PtToolbarGroup 934

flags 935orientation 934Pt ARG ORIENTATION 934Pt ARG TG FLAGS 935

Pt TOOLBAR ITEM SEPARATORS 930Pt TOOLBAR LOCK ORIENTATION 930Pt TOOLBAR REVERSE LAST ITEM

929Pt TOOLBAR TO LINE END 930Pt TOP ANCHORED BOTTOM 1152Pt TOP ANCHORED TOP 1152Pt TOP BEVEL 49

Pt TOP ETCH 49Pt TOP INLINE 50, 55Pt TOP LEFT BEVEL 50Pt TOP LEFT ETCH 50Pt TOP LEFT INLINE 50Pt TOP LEFT OUTLINE 50Pt TOP OUTLINE 49, 57PtTree 939

balloonenabling 961function 947location 961

callbackscolumn-selection 946, 952drag and drop 961selection 954state-change 955

column attributes 944, 948column flags 944column function 945, 949columns 943convenience functions 962flags 960images 942, 950

adding 942, 970mask 942, 951selecting 942, 951

itemsadding after 966adding first 968allocating 940, 974collapsing 979current, getting 987current, setting 990expanding 983freeing 986freeing all 985

May 31, 2004 Index 1297


getting all 972index, getting 995modifying 996, 998removing 1001, 1003removing children 999root item, getting 1005scrolling to 990selecting 1006selection, clearing 978selection, getting 988, 1007selection, setting 1009showing 1010unselecting 1012unselecting

nonbrothers 1013Pt ARG LIST COLUMN ATTR

944Pt ARG LIST COLUMN POS

943Pt ARG SELECTION MODE

952, 954, 956Pt ARG TREE BALLOON

947Pt ARG TREE COLUMN ATTR

944, 948Pt ARG TREE COLUMN IMGFUN

945, 949Pt ARG TREE FLAGS 960Pt ARG TREE IMAGES 942,

950Pt ARG TREE IMGMASK

942, 951Pt CB DND 961Pt CB TREE COLUMN SEL

946, 952Pt CB TREE SELECTION

954

Pt CB TREE STATE 955PtDivider as child 943selection mode 952, 954, 956

PtTreeitems

changing 976creating 980

PtTreeAddAfter() 966PtTreeAddFirst() 968PtTreeAddImages() 942, 970PtTreeAllItems() 972PtTreeAllocItem() 974Pt TREE BALLOON ON IMAGE 734,

960Pt TREE BALLOON ON TREE 734,

961PtTreeCallback t 952, 954PtTreeChangetem() 976PtTreeClearSelection() 978PtTreeCollapse() 979Pt TREE COLLAPSING 231, 729,

956PtTreeColumnAttributes t

948Pt TREE COLUMN NOCB 949Pt TREE COLUMN NOCURRENT 949Pt TREE COLUMN NOSELECT 949PtTreeCreateItem() 980PtTreeDndCallback t 236,

365, 734, 961PtTreeExpand() 983Pt TREE EXPANDING 231, 729,

956PtTreeFreeAllItems() 985PtTreeFreeItems() 986PtTreeGetCurrent() 987PtTreeGetSelIndexes() 988

1298 Index May 31, 2004


PtTreeGoto() 990Pt TREE HAS BUTTONS 358, 384Pt TREE INDENT BUTTONS 358Pt TREE INDENT LINES 358PtTreeItem t 940, 991PtTreeItemAttributes t 993Pt TREE ITEM EXPANDABLE 242,

370, 384, 391, 951, 968Pt TREE ITEM EXPANDED 385,

729, 943, 951PtTreeItemIndex() 995Pt TREE ITEM INWIDGET 385PtTreeModifyItem() 996PtTreeModifyItemString() 998PtTreeRemoveChildren() 999PtTreeRemoveItem() 1001PtTreeRemoveList() 1003PtTreeRootItem() 1005PtTreeSelect() 1006PtTreeSelectedItems() 1007PtTreeSetSelIndexes() 1009PtTreeShow() 1010Pt TREE SHOW CONNECTORS 359Pt TREE SHOW LINES 359Pt TREE SHOW MARGIN 359Pt TREE TO LEFT 359Pt TREE TO RIGHT 359PtTreeUnselect() 1012PtTreeUnselectNonBrothers() 1013PtTrend 1014

attributes 1015color list 1017convenience functions 1025flags 1019grid

color 1021drawing 1019

forcing display of 1019horizontal lines, number

of 1021opaque, over trends 1019translucent 1019vertical lines, number

of 1021palette entries, range of 1022Pt ARG COLOR 1017Pt ARG FILL COLOR 1016Pt ARG TREND ATTRIBUTES

1015, 1017Pt ARG TREND COLOR LIST

1015, 1017, 1022Pt ARG TREND COUNT

1018Pt ARG TREND DATA 1018Pt ARG TREND FLAGS

1019Pt ARG TREND GRID COLOR

1021Pt ARG TREND GRID X

1021Pt ARG TREND GRID Y

1021Pt ARG TREND INC 1021Pt ARG TREND MAX 1022Pt ARG TREND MIN 1022Pt ARG TREND PALETTE END

1022trends

data 1018data, replacing 1027direction of movement 1020distance between

points 1021drawing as pixels 1019

May 31, 2004 Index 1299


drawing over grid 1020horizontal 1019maximum value 1022minimum value 1022number of 1018vertical 1020

Pt TREND BOTTOM TO TOP 1020PtTrendChangeData() 1027PtTrendChangeTrendData() 1027Pt TREND HORIZONTAL 1019Pt TREND LEFT TO RIGHT 1020Pt TREND RIGHT TO LEFT 1020Pt TRENDS ABOVE GRID 1020Pt TREND TOP TO BOTTOM 1020Pt TREND VERTICAL 1020PtTty 1030

argv[0], using program nameas 1039

bandwidth threshold 1050buffer 1036

size 1036using 1039

callbacksdevice resized 1043output 1044process terminated 1045

charactersnumber written to

device 1040to be written to device 1040

COLUMNS 1037command 1037convenience functions 1050device

pathname 1040resizing automatically 1039size 1037

size, limiting toterminal 1039

size, same as terminal 1039environment variables,

modifying 1037, 1039exit status 1038file descriptor

all 1038read 1042resources 1033set 1038standard input, output, and

error 1042write 1043

flags 1039LINES 1037Photon pulses, priority 1041process

arguments 1035ID 1041

program name, using asargv[0]1039

pseudo-tty device 1041Pt ARG BANDWIDTH THRESHOLD

1050Pt ARG FLAGS 1030Pt ARG TTY ARGV 1035Pt ARG TTY BUFFER 1036Pt ARG TTY BUFLEN 1036Pt ARG TTY CMD 1036,

1037Pt ARG TTY DEVSIZE 1037Pt ARG TTY EXIT STATUS

1038, 1045Pt ARG TTY FDS 1038Pt ARG TTY FDSET 1038Pt ARG TTY FLAGS 1039

1300 Index May 31, 2004


Pt ARG TTY INPUT 1040Pt ARG TTY INPUT WRITTEN

1040Pt ARG TTY PATH 1040Pt ARG TTY PID 1037, 1041Pt ARG TTY PRI 1041Pt ARG TTY PSEUDO 1041Pt ARG TTY RFD 1042Pt ARG TTY SFD 1042Pt ARG TTY SPAWN OPTIONS

1042Pt ARG TTY WFD 1043Pt CB TTY DEVSIZE 1043Pt CB TTY OUTPUT 1044Pt CB TTY TERMINATED

1045shell, returning name of 1051spawn options 1042TERM 1037widget, resizing

automatically 1039Pt TTY ARGV0 1035, 1037, 1039Pt TTY BUF PRIVATE 1039Pt TTY DEVFORCE 1039Pt TTY DEVLIMIT 1039Pt TTY DEVRESIZE 1039PtTtyOutput t 1045Pt TTY SETENV 1037, 1039PtTtyShell() 1051Pt TTY TERMRESIZE 1039Pt ULINE ETCHED IN 446Pt ULINE ETCHED OUT 446Pt USE ELLIPSIS 441Pt WEB ACTION ABORT 1114,

1142Pt WEB ACTION ADD 1070Pt WEB ACTION DELETE 1070

Pt WEB ACTION DISPLAY 1068Pt WEB ACTION OK 1114, 1142Pt WEB ACTION SAVEAS 1068PtWebAuthenticateCallback t

1113Pt WEB BASIC AUTHENTICATION

1059, 1114PtWebClient 1052

callbacksauthentication 1113certificates 1123closing window 1114file requested 1117file, unknown 1141loading complete 1115loading error 1119meta data 1124new window 1126page information 1127right-click 1116scrolling 1125SSL certification 1128SSL client error 1134SSL error 1135SSL nontrusted 1130start loading 1138status 1138URL being loaded 1143

certificate information 1071certificates 1065client protocol data

stream 1062context information 1066DNS errors 1070downloads 1118encoding 1065external helpers 1069

May 31, 2004 Index 1301


file, downloading 1065frame navigation 1072link

deactivating 1058navigation 1073

optionsauthentication 1083disk-cache 1088file 1085FTP 1084Gopher 1084HTML 1077HTTP 1085HTTP cookie 1083image 1086miscellaneous 1089print 1086SOCKS 1087TCP/IP 1088

pageloading, stopping 1111navigation 1074printing 1107reloading 1108

Pt ARG WEB ACTIVATE LINK1058

Pt ARG WEB AUTHENTICATE1059

Pt ARG WEB BUILD DATE1060

Pt ARG WEB COMMAND1060

Pt ARG WEB DATA 1062Pt ARG WEB DOWNLOAD

1065Pt ARG WEB ENCODING

1065

Pt ARG WEB GET CERTIFICATES1065

Pt ARG WEB GET CONTEXT1066

Pt ARG WEB GET HISTORY1067

Pt ARG WEB GET URL1053, 1068

Pt ARG WEB HELPER 1069Pt ARG WEB H ERRNO

1070Pt ARG WEB IMPORT CERTIFICATE

1071Pt ARG WEB NAVIGATE FRAME

1072Pt ARG WEB NAVIGATE LINK

1073Pt ARG WEB NAVIGATE PAGE

1074Pt ARG WEB OPTION 1075Pt ARG WEB PRINT 1107Pt ARG WEB RELOAD 1108Pt ARG WEB SERVER 1052,

1108Pt ARG WEB SERVER PID

1110Pt ARG WEB SSL RESPONSE

1110Pt ARG WEB STARTUP ERRNO

1053, 1111Pt ARG WEB STOP 1111Pt ARG WEB UNKNOWN RESP

1112Pt ARG WEB VERSION

1113Pt CB WEB AUTHENTICATE

1113

1302 Index May 31, 2004


Pt CB WEB CLOSE WINDOW1114

Pt CB WEB COMPLETE1115

Pt CB WEB CONTEXT 1116Pt CB WEB DATA REQ 1117Pt CB WEB DOWNLOAD

1118Pt CB WEB ERROR 1119Pt CB WEB IMPORT CERTIFICATE

1123Pt CB WEB METADATA

1124Pt CB WEB NEED SCROLL

1125Pt CB WEB NEW WINDOW

1126Pt CB WEB PAGE INFO

1127Pt CB WEB SSL CERTINFO

1128Pt CB WEB SSL CERTNONTRUSTED

1130Pt CB WEB SSL CLIENT CERT SELECT

1134Pt CB WEB SSL ERROR

1135Pt CB WEB START 1138Pt CB WEB STATUS 1138Pt CB WEB UNKNOWN

1141Pt CB WEB URL 1143scrolling 1074server

authenticationinformation 1059

build date 1060

command 1060options 1075path 1052, 1108process ID 1110unknown response 1112version 1113

site history list 1067SSL (Secure Sockets Layer)

response 1110starting 1052startup errors 1053, 1111URL 1053, 1068

PtWebClientAuthenticationData t

1059PtWebClientData t * 1062PtWebClientHelperData t

1069PtWebClientHistory t 1067PtWebClientHistoryData t

1067PtWebClientSSLResponse t

1134, 1137PtWebClientSSLResponse t *

1110PtWebClientUnknownData t

1112PtWebCommand t 1060Pt WEB COMMAND FIND 1061Pt WEB COMMAND LOADMISSING 1061Pt WEB COMMAND LOADMISSING CONTEXT

1062Pt WEB COMMAND PURGE CACHE

1062Pt WEB COMMAND RESET OPT 1061Pt WEB COMMAND SAVEAS 1061PtWebCompleteCallback t

1115

May 31, 2004 Index 1303


Pt WEB CONTEXT ANCHOR 1066,1116

Pt WEB CONTEXT BKGD 1066,1116

PtWebContextCallback t

1116Pt WEB CONTEXT OBJECT 1066,

1116Pt WEB DATA BODY 1062, 1118Pt WEB DATA CLOSE 1062, 1118Pt WEB DATA HEADER 1062,

1117PtWebDataReqCallback t

1117Pt WEB DIGEST AUTHENTICATION

1059, 1114Pt WEB DIRECTION BACK 1073,

1075Pt WEB DIRECTION DOWN

1072–1074, 1126Pt WEB DIRECTION FWD 1073,

1074Pt WEB DIRECTION LEFT

1072–1074, 1126Pt WEB DIRECTION RIGHT

1072–1074, 1126Pt WEB DIRECTION UP 1072–

1074,1126

PtWebDownloadCallback t

1118Pt WEB ERROR BasicConstraints

1137PtWebErrorCallback t 1120Pt WEB ERROR CertChainIncomplete

1137

Pt WEB ERROR CertChainInvalid1137

Pt WEB ERROR CertExpired 1137Pt WEB ERROR CertNamesNotEqual

1137Pt WEB ERROR CertNoError 1136Pt WEB ERROR FailedVerify 1137Pt WEB ERROR FILE 1121Pt WEB ERROR IncorrectKeyUsage

1137Pt WEB ERROR InvalidSignature

1137Pt WEB ERROR RootCertificateNotValid

1137Pt WEB ERROR SERVER EXIT 1120Pt WEB ERROR SUBVIEW 1120Pt WEB ERROR TOPVIEW 1120Pt WEB ERROR WML 1121Pt WEB FIND GO BACKWARDS 1061Pt WEB FIND MATCH CASE 1061Pt WEB FIND MATCH WHOLE WORDS

1061Pt WEB FIND START AT TOP 1061Pt WEB IMPORT CERT AUTHENTICATION

1114PtWebImportCertificateCallback t

1124PtWebMetaDataCallback t

1125PtWebNeedScrollCallback t

1125Pt WEB NO DISK CACHE 1069Pt WEB NO MEMORY CACHE 1069Pt WEB NO PAGE HISTORY 1069Pt WEB NO SITE HISTORY 1069PtWebPageInfoCallback t

1127

1304 Index May 31, 2004


Pt WEB PRINT ALL FRAMES 1108Pt WEB PRINT FROM CACHE 1108Pt WEB PROXY AUTHENTICATION

1060, 1114Pt WEB RESIZEABLE 1127Pt WEB RESPONSE CANCEL 1059,

1111, 1112, 1138Pt WEB RESPONSE OK 1059,

1111, 1112, 1138Pt WEB SHOW LOCATION 1127Pt WEB SHOW MENUBAR 1127Pt WEB SHOW STATUS 1127Pt WEB SHOW TOOLBAR 1127PtWebSSLCertInfoCallback t

1129PtWebSSLCertNonTrustedCallback t

1131PtWebSSLClientCertCallback t

1135PtWebSSLErrorCallback t

1136PtWebStatusCallback t 1139Pt WEB STATUS CONNECT 1139Pt WEB STATUS DEFAULT 1139Pt WEB STATUS INFO 1139Pt WEB STATUS MOUSE 1139Pt WEB STATUS PRINT 1141Pt WEB STATUS PROGRESS 1139PtWebUnknownCallback t

1142PtWebUrlCallback t 1143PtWebWindowCallback t 1126PtWidget 1148

“set” state 1161activation by any mouse

button 1158anchor flags 1152, 1153

anchor offsets 1152, 1153area 1148, 1154autohighlighting 1158balloons

popping upimmediately 1153

bevel width 1154blocking 1158callbacks

blocked 1170destroyed 1170, 1177drag-and-drop 1171filter 1174hotkey 1176outbound 1177raw event 1178unrealized 1180

callbacks, invoking whenresources are set 1158

cursorbitmap 1155color 1155type 1155

damageindicating for family 1159indicating for widget 1159propagating to parent 1157

destruction, marked for 1159dimensions 1148, 1154, 1156

maximum 1165minimum 1166

events, consuming 1157extended flags 1157extent 1148, 1157extent, no intersections

with 1159flags 1158

May 31, 2004 Index 1305


flux 1160focus, granting 1159ghosting 1159height 1148, 1154, 1156, 1164


help information 1157, 1164highlighting

automatically 1158clipping corners 1159requesting 1160

layoutsskipping 1157

menu button 1160menuable 1160obscured 1160opaque 1160position 1148, 1154, 1166procreated child 1160Pt ARG ANCHOR FLAGS

1152, 1153Pt ARG ANCHOR OFFSETS

1152, 1153Pt ARG AREA 1148, 1153,

1154Pt ARG BEVEL WIDTH

1154Pt ARG BITMAP CURSOR

1155Pt ARG CURSOR COLOR

1155Pt ARG CURSOR TYPE

1155Pt ARG DATA 1156Pt ARG DIM 1148, 1153,

1156Pt ARG EFLAGS 1157, 1164

Pt ARG EXTENT 1148, 1157Pt ARG FLAGS 1158Pt ARG GRID LAYOUT DATA

1148, 1161Pt ARG HEIGHT 1149, 1164Pt ARG HELP TOPIC 1164Pt ARG LAYOUT DATA

1149, 1165Pt ARG MAXIMUM DIM

1149, 1165Pt ARG MINIMUM DIM

1149, 1166Pt ARG POINTER 1149, 1166Pt ARG POS 1149, 1166Pt ARG RESIZE FLAGS

1167Pt ARG ROW LAYOUT DATA

1149, 1168Pt ARG USER DATA 1150,

1169Pt ARG WIDTH 1149, 1170Pt CB BLOCKED 1170Pt CB DESTROYED 1170Pt CB DND 1171Pt CB FILTER 1174Pt CB HOTKEY 1176Pt CB IS DESTROYED 1177Pt CB OUTBOUND 1177Pt CB RAW 1178Pt CB REALIZED 1180Pt CB UNREALIZED 1180realizing

callback 1180delaying 1159indicating completion 1160indicating in progress 1160

1306 Index May 31, 2004


whenever resources areset 1161

redrawing, preventing 1161region, forcing to have 1161render focus 1159resizing

flags 1167whenever resources are

set 1161selectable 1161toggling, enabling 1161user-defined data 1149, 1166,

1169width 1148, 1154, 1156, 1170


x, y coordinates 1148, 1154,1166

PtWidgetClassStyle t 58PtWidgetFlags() 1158Pt WIDGET REBUILD 1161Pt WIDGET RESIZE 1161PtWindow 1181

active color 1188Alt function key combinations

1193application 1191backdrop 1189, 1193block input 1193border 1191callbacks

opening 1197transport 1197window event 1195

close button 1192closing 1189

callback 1196

collapse button 1192collapsing to title bar 1189,

1193convenience functions 1201cursors, overriding

children’s 178cycling focus 1189dialog 1191flags

managed 1183, 1189notify 1185, 1190render 1182, 1191

focusgaining and losing 1189giving 1202giving when opened 1193

force front 1189, 1193height


helpbutton 1192context-sensitive 1189root 1188

hiding 1189, 1193icon 1191iconifying 1193in front 1193inactive color 1188inline 1192maximize button 1192maximizing 1189, 1194menu button 1192minimize button 1192moving 1189palette 1191

May 31, 2004 Index 1307


Pt ARG CURSOR OVERRIDE178

Pt ARG MAX HEIGHT 1186Pt ARG MAX WIDTH 1187Pt ARG MIN HEIGHT 1187Pt ARG MIN WIDTH 1187Pt ARG WINDOW ACTIVE COLOR

1188Pt ARG WINDOW FRONT WINDOW

1188Pt ARG WINDOW HELP ROOT

1188Pt ARG WINDOW INACTIVE COLOR

1188Pt ARG WINDOW MANAGED FLAGS

1183, 1189Pt ARG WINDOW NOTIFY FLAGS

1185, 1190Pt ARG WINDOW RENDER FLAGS

1182, 1191Pt ARG WINDOW STATE

1193Pt ARG WINDOW TITLE

1194Pt ARG WINDOW TITLE COLOR

1195Pt CB WINDOW 1195Pt CB WINDOW CLOSING

1196Pt CB WINDOW OPENING

1197Pt CB WINDOW TRANSPORT

1197resizing 1183, 1189

handles 1192restoring 1189sending to back 1189, 1206

sending to front 1189, 1208state 1193

getting 1204subwindows 1185switching consoles

automatically 1189taskbar, including in 1189title

bar 1192color 1195text 1194

widthmaximum 1187minimum 1187

window in front 1188window manager 1182window menu 1189

PtWindowFocus() 1202PtWindowGetState() 1204PtWindowToBack() 1206PtWindowToFront() 1208Pt Z STRING 82, 432, 442pushbutton widget See PtButtonPWM 1181

R

range-select mode 308raw callbacks 13, 1178raw drawing widget See PtRawraw list See PtRawListraw tree See PtRawTreerealizing

delaying 1159done 1160

1308 Index May 31, 2004


in progress 1160Pt CB REALIZED 1180whenever resources are

set 1161rebuilding 1161rectangle widget See PtRectredrawing, preventing 1161region

forcing a widget to have 1161region widget See PtRegionrender shared library 633replace mode 878resizing

callback 190flags 1167

and anchor flags 1168policy 408, 1167whenever resources are

set 1161resources

inheritance of 18types 25

reverse gradientfill 51

row widget See PtGroup

S

scroll area widget SeePtScrollArea

scrollable container widget SeePtScrollContainer

scrollbar widget SeePtScrollbar

selecting

enabling 1161widgets 43

selection mode 308separator widget See

PtSeparator

servers See PtServershared memory 633Shift-click selection 308single-select mode 308slider widget See PtSliderspace, sharing among widgets See

PtDivider

SSL CERTNONTRUSTED ABORT 1134SSL CERTNONTRUSTED ACCEPT 1134SSL CERTNONTRUSTED CONTINUE 1134style 58superclass widget See PtWidget

T

Tab character, use as columnseparator 456, 944

tab widget See PtTabterminal emulator widget See

PtTerminal

attached to a device SeePtTty

TEXT 1059text widget

label See PtLabelmultiline See PtMultiTextsingle-line See PtTextwith list of choices See

PtComboBox

TEXTAREA 1059

May 31, 2004 Index 1309


threshold, graphics bandwidth 48time widget See PtClocktimer widget See PtTimertoggle button widget See

PtToggleButton

togglingenabling 1161Pt CB ACTIVATE 59state, checking 59

toolbars See PtToolbarGroup,See PtToolbar

transparency pattern 58, 411Tree Item State method

tree widgets 374, 376tree widget

general purpose See PtTreesuperclass See also

PtGenTree

tree widgetsmethods

Tree Item State 374, 376tree, raw See PtRawTreetrend widget See PtMTrend, See

PtTrend

TRY AGAIN 1071

U

unrealizingPt CB UNREALIZED 1180

user-defined data 922, 1149, 1166,1169

PtRaw 702

V

vector graphics 404viewport widget See

PtScrollArea, SeePtScrollContainer

Voyager Web Server 1052

W

web browsersee PtWebClient 1052

web server 1052wedge 30widget See also PtWidget

contributed xixdescription, contents of 24hierarchy 17

widgetsicon in PhAB 18

width 1148, 1154, 1156, 1170maximum 1149, 1165minimum 1149, 1166

window manager 1181window widget See PtWindow

X

x, y coordinates 1148, 1154, 1166

1310 Index May 31, 2004

QNX Neutrino Realtime Operating Systemfusion.qnx.com/7/9357/Photon_widget_ref.pdf · QNX Neutrino...

Documents

Transcript of QNX Neutrino Realtime Operating Systemfusion.qnx.com/7/9357/Photon_widget_ref.pdf · QNX Neutrino...