WIDGET REFERENCE

WIDGET REFERENCE

Q N X ® P H O T O N ® M I C R O G U I ® V 6 .3

QNX Neutrino Realtime

Operating SystemPhoton microGUI

Widget Reference

For QNX Neutrino 6.3.0

2005, 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/

1995 – 2005, QNX Software Systems Ltd. All rights reserved.

Publishing history

November 1995 First edition

December 1996 Second edition

April 1998 Third edition

July 2004 Fourth edition

Electronic version published January 2005.

Technical support options

To obtain technical support for any QNX product, visit theTechnical Support section in theServices area on our website(www.qnx.com). You’ll find a wide range of support options, including our free web-basedDeveloper 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.

Printed in Canada.

Part Number: 002524

Contents

About This Reference xviiWhat’s new in Photon for QNX Neutrino 6.3.1 xx

New widgets xx

Changes xx

What’s new in Photon for QNX Neutrino 6.3 xxi

New widgets xxi

Changes xxi

What’s new in Photon for QNX Neutrino 6.2.1 xxv

Changes xxv

Errata xxv

What’s new in Photon for QNX Neutrino 6.2.0 xxvi

What’s new in Photon for QNX Neutrino 6.1.0 xxvii

What’s new in Photon for QNX Neutrino 6.0 xxviii

New widgets xxviii

Deprecated widgets xxix

Other changes xxix

Global Data Structures 11PtBalloonCallback t 5

PtCallback t 7

PtCallbackInfo t 9

PtHotkeyCallback t 11

PtRawCallback t 13

Widgets 152

January 31, 2005 Contents iii


Widget hierarchy 17

Widget icons in PhAB 18

What’s in a widget description? 25

Photon Widgets — PtA to PtN 29PtArc 32

PtBarGraph 38

PtBasic 46

PtBezier 73

PtBkgd 78

PtButton 85

PtCalendar 93

PtClient 107

PtClock 117

PtColorPanel 129

PtColorPatch 135

PtColorSel 141

PtColorSelGroup 149

PtColorWell 154

PtComboBox 160

PtComboBoxListClose() 175

PtComboBoxListOpen() 176

PtCompound 177

PtContainer 181

PtDisjoint 201

PtDivider 206

PtEllipse 215

PtFileSel 219

PtFSAddAfter() 247

PtFSAddFirst() 249

PtFSAllItems() 251

PtFSAllocItem() 252

PtFSClearSelection() 255

iv Contents January 31, 2005


PtFSDamageItem() 256

PtFSExpandParents() 257

PtFSFolderCollapse() 258

PtFSFolderExpand() 259

PtFSFreeAllItems() 260

PtFSFreeItems() 261

PtFSGetCurrent() 262

PtFSGetSelIndexes() 263

PtFSGoto() 264

PtFSItemIndex() 265

PtFSRemoveChildren() 266

PtFSRemoveItem() 268

PtFSRemoveList() 270

PtFSRootItem() 272

PtFSSelect() 273

PtFSSelectedItems() 274

PtFSSetSelIndexes() 275

PtFSShow() 276

PtFSUnselect() 277

PtFSUnselectNonBrothers() 278

PtFlash 279

PtFontSel 283

PtGauge 293

PtGenList 303

PtGenListAddItems() 327

PtGenListAllItems() 329

PtGenListClearSelection() 330

PtGenListCreateTextBalloon() 331

PtGenListDamageItem() 333

PtGenListDrawBackground() 334

PtGenListDrawString() 336

PtGenListFirstItem() 338

January 31, 2005 Contents v


PtGenListGetCurrent() 339

PtGenListGetSelIndexes() 340

PtGenListGoto() 341

PtGenListHold() 342

PtGenListItem t 343

PtGenListItemIndex() 346

PtGenListItemRealloc() 347

PtGenListLastItem() 348

PtGenListLockItem() 349

PtGenListRelease() 350

PtGenListRemoveItems() 351

PtGenListResize() 353

PtGenListSelect() 354

PtGenListSelectedItems() 355

PtGenListSetColumnBalloon() 356

PtGenListSetGflags() 357

PtGenListSetSelIndexes() 358

PtGenListShow() 360

PtGenListUnlockItem() 361

PtGenListUnselect() 362

PtGenTree 363

PtGenTreeAddAfter() 375

PtGenTreeAddFirst() 376

PtGenTreeAllItems() 378

PtGenTreeClearSelection() 379

PtGenTreeCollapse() 380

PtGenTreeDamageItem() 381

PtGenTreeExpand() 382

PtGenTreeExpandParents() 384

PtGenTreeFreeAllItems() 385

PtGenTreeFreeItems() 386

PtGenTreeGetCurrent() 387

vi Contents January 31, 2005


PtGenTreeGetSelIndexes() 388

PtGenTreeGoto() 389

PtGenTreeItem t 390

PtGenTreeItemIndex() 393

PtGenTreeItemRealloc() 394

PtGenTreeItemResize() 395

PtGenTreeRemoveChildren() 396

PtGenTreeRemoveItem() 397

PtGenTreeRemoveList() 398

PtGenTreeResize() 399

PtGenTreeRootItem() 400

PtGenTreeSelect() 401

PtGenTreeSelectedItems() 402

PtGenTreeSetSelIndexes() 403

PtGenTreeShow() 405

PtGenTreeUnselect() 407

PtGenTreeUnselectNonBrothers() 408

PtGraphic 409

PtGrid 424

PtGroup 429

PtImageArea 439

PtLabel 450

PtLine 469

PtList 474

PtListAddItems() 490

PtListDeleteAllItems() 492

PtListDeleteItemPos() 493

PtListDeleteItems() 494

PtListGotoPos() 495

PtListItemExists() 496

PtListItemPos() 497

PtListRemovePositions() 498

January 31, 2005 Contents vii


PtListReplaceItemPos() 499

PtListReplaceItems() 500

PtListSelectPos() 501

PtListShowPos() 502

PtListUnselectPos() 503

PtMenu 504

PtMenuBar 525

PtMenuButton 530

PtMeter 538

PtMTrend 554

PtMTrendAddData(), PtMTrendChangeData() 567

PtMultiText 569

PtMultiLines t 603

PtMultiTextAttributes t 605

PtMultiTextCallback t, PtMultiTextControl t,PtMultiTextInfo t 607

PtMultiTextCreateAttributes() 609

PtMultiTextGetAttributes() 610

PtMultiTextInfo() 614

PtMultiTextLine t 617

PtMultiTextModifyAttributes() 619

PtMultiTextModifyText() 621

PtMultiTextQuery t 623

PtMultiTextSegment t 625

PtNumeric 627

PtNumericFloat 633

PtNumericInteger 642

Photon Widgets — PtO to PtW 651PtOnOffButton 654

PtOSContainer 660

PtPane 665

PtPanelGroup 670

viii Contents January 31, 2005


PtPGCreatePopup() 685

PtPGFindIndexByPanel() 688

PtPGFindIndexByTitle() 689

PtPGFindPanelByIndex() 690

PtPGFindPanelByTitle() 691

PtPGFindTitleByIndex() 692

PtPixel 693

PtPolygon 697

PtPrintSel 702

PtProgress 716

PtProgressEntireSegment() 723

PtProgressFirstSegment() 725

PtProgressNextSegment() 727

PtProgressTextRect() 729

PtRaw 730

PtRawList 740

PtRawTree 754

PtRect 766

PtRegion 771

PtScrollArea 780

PtScrollAreaCanvas() 791

PtScrollbar 792

PtScrollContainer 803

PtSeparator 811

PtServer 822

PtSlider 832

PtTab 844

PtTerminal 852

PtTerminalCharset t, PtTerminalCharsets t 892

PtTerminalCopy() 895

PtTerminalCreateCsXlat() 896

PtTerminalDefaultCharsets() 898

January 31, 2005 Contents ix


PtTerminalFontInfo() 899

PtTerminalGetKeys() 901

PtTerminalGetSelection() 903

PtTerminalName() 904

PtTerminalPasteClipboard() 905

PtTerminalPasteSelection() 906

PtTerminalPut(), PtTerminalPutc(), PtTerminalPuts() 907

PtTerminalSelectWord() 909

PtText 911

PtTextCallback t, PtTextControl t,PtTextControlInfo t 944

PtTextGetSelection() 946

PtTextModifyText() 947

PtTextSetSelection() 949

PtTimer 951

PtToggleButton 955

PtToolbar 963

PtToolbarGroup 970

PtTree 975

PtTreeAddAfter() 1002

PtTreeAddFirst() 1004

PtTreeAddImages() 1006

PtTreeAllItems() 1008

PtTreeAllocItem() 1010

PtTreeChangeItem() 1012

PtTreeClearSelection() 1014

PtTreeCollapse() 1015

PtTreeCreateItem() 1016

PtTreeExpand() 1019

PtTreeFreeAllItems() 1021

PtTreeFreeItems() 1022

PtTreeGetCurrent() 1023

PtTreeGetSelIndexes() 1024

x Contents January 31, 2005


PtTreeGoto() 1026

PtTreeItem t 1027

PtTreeItemAttributes t 1029

PtTreeItemIndex() 1031

PtTreeModifyItem() 1032

PtTreeModifyItemString() 1034

PtTreeRemoveChildren() 1035

PtTreeRemoveItem() 1037

PtTreeRemoveList() 1039

PtTreeRootItem() 1041

PtTreeSelect() 1042

PtTreeSelectedItems() 1043

PtTreeSetSelIndexes() 1045

PtTreeShow() 1046

PtTreeUnselect() 1048

PtTreeUnselectNonBrothers() 1049

PtTrend 1050

PtTrendChangeData(), PtTrendChangeTrendData() 1063

PtTty 1066

PtTtyShell() 1088

PtUpDown 1089

PtWebClient 1097

PtWidget 1193

PtWindow 1226

PtWindowFocus() 1249

PtWindowGetState() 1251

PtWindowToBack() 1253

PtWindowToFront() 1255

Glossary 1257

Index 1279

January 31, 2005 Contents xi

List of Figures

The Photon widget hierarchy. 17

Instances ofPtArc: arcs, circles, ellipses, wedges, and chords.32

A PtBarGraph widget. 38

A widget displaying all the border components. 49

A widget displaying a half-round bevel. 50

A Bezier curve created byPtBezier. 73

Several different styles of background widgets. 78

A PtButton widget. 85

A PtCalendar widget. 93

Analog, digital, and LED clocks created byPtClock. 117

A PtColorPanel widget. 129

A PtColorPatch widget. 135

A PtColorSelGroup widget. 149

A PtColorWell widget. 154

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

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

A PtEllipse widget. 215

A PtFileSel widget. 219

A single-level file selector. 221

The results of usingPtFSAddAfter(). 247

The results of usingPtFSAddFirst(). 249

The results of usingPtFSRemoveChildren(). 266

The results of usingPtFSRemoveItem(). 268

January 31, 2005 List of Figures xiii


The results of usingPtFSRemoveList(). 270

A PtFontSel widget. 283

A five-pointed star before clipping. 413

The star after clipping. 414

A PtGrid widget. 424

A group of buttons. 429

A text string in aPtLabel widget. 450

A PtLine widget. 469

A PtList containing text items. 474

A PtMenu widget that contains various menu items. 504

A PtMenuBar that contains several menu buttons. 525

A PtMenuButton widget. 530

A PtMeter widget. 538

A one-arcPtMeter widget. 539

A PtMTrend widget. 555

A PtMultiText widget. 569

A PtNumericFloat widget. 633

A PtNumericInteger widget. 642

A PtOnOffButton widget. 654

A dialog box featuring severalPtPane widgets. 665

A PtPanelGroup widget as used in PhAB. 670

Open or closedPtPolygon widgets. 697

A PtPrintSel widget. 703

Two styles ofPtProgress bar. 716

Additional Pt ARG TREE FLAGS for aPtRawTree widget.763

A PtRect widget. 766

A PtScrollbar widget. 792

A PtScrollContainer widget acts as a viewport. 803

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

A PtSlider widget. 832

A PtSlider widget with a custom handle and trough. 833

xiv List of Figures January 31, 2005


A group ofPtTab widgets positioned at the top of aPtPane.844

A PtTerminal widget. 852

A PtText widget. 911

Various button styles supported byPtToggleButton. 955

A PtToolbar as used in PhAB. 963

A PtToolbarGroup. 970

A PtTree widget, as used in the Helpviewer. 975

A PtTree without images. 977

A PtTree with images. 979

Additional Pt ARG TREE FLAGS for aPtTree widget. 997

The results of usingPtTreeAddAfter(). 1002

The results of usingPtTreeAddFirst(). 1004

The results of usingPtTreeRemoveChildren(). 1035

The results of usingPtTreeRemoveItem(). 1037

The results of usingPtTreeRemoveList(). 1039

A PtTrend widget. 1050

Replacing trend samples withPtTrendChangeData() orPtTrendChangeTrendData(). 1064

Output from a terminal device. 1066

A PtUpDown widget. 1089

A PtWindow widget that contains an editor application. 1226

January 31, 2005 List of Figures xv

About This Reference

January 31, 2005 About This Reference xvii


The PhotonWidget 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.0 Service Pack 1”

� “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,especiallyPtWidget, PtBasic, andPtContainer.

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

☞

January 31, 2005 About This Reference xix

What’s new in Photon for QNX Neutrino 6.3.1 2005, QNX Software Systems Ltd.

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

� PtImageArea

ChangesPtGenList

Changes toPt ARG LIST FLAGS:

New flags:

� Pt LIST VSCROLLBAR ALWAYS

� Pt LIST SCROLLBAR AS REQUIRED

� Pt LIST VSCROLLBAR AS REQUIRED

� Pt LIST VSCROLLBAR NEVER

� Pt LIST HSCROLLBAR ALWAYS

� Pt LIST HSCROLLBAR AS REQUIRED

� Pt LIST HSCROLLBAR NEVER

� Pt LIST STRETCHHEADER

Deprecated flags:

� Pt LIST SCROLLBAR ALWAYS

� Pt LIST SCROLLBAR NEVER

� Pt LIST SCROLLBAR AS REQUIRED

Removed flags:

� Pt LIST NOBLIT

xx About This Reference January 31, 2005

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

PtBasic

Changed resources:

� Pt ARG BASIC FLAGS — new flag:Pt BASIC PREVENT FILL.

PtWindow

New resources:

� Pt ARG WINDOW FLAGS.

What’s new in Photon for QNX Neutrino 6.3New 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

January 31, 2005 About This Reference xxi

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

� Pt ARG FILL LAYOUT INFO

� Pt ARG GRID LAYOUT INFO

� Pt ARG ROW LAYOUT INFO

� Pt CB LAYOUT

PtFontSel

ThePtFontSel 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:

� 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

xxii About This Reference January 31, 2005


PtLabel

New resources:

� Pt ARG SECONDARY H ALIGN

� Pt ARG SECONDARY V ALIGN

� Pt ARG BALLOON TEXT

PtSeparator

New resources:

� Pt ARG SEP ARM BITMAP CURSOR

� Pt ARG SEP ARM CURSOR COLOR

� Pt ARG SEP ARM CURSOR TYPE

� Pt ARG SEP DRAG BOUNDS

� Pt ARG SEP FLAGS

� Pt ARG SEP IMAGE

� Pt ARG SEP IMAGE H ALIGN

� Pt ARG SEP IMAGE V ALIGN

PtTerminal

PtTerminalFont() is deprecated; usePtTerminalFontInfo() instead.

Thelength field in PtTerminalInput t is changed fromunsigned short to unsigned, which allowsPtTerminal to pastemore than 65535 bytes of data from the clipboard.

PtTree

New convenience functions and attributes structure:

� PtTreeCreateItem()

� PtTreeChangeItem()

� PtTreeItemAttributes t

January 31, 2005 About This Reference xxiii


PtWebClient

New resources:

� Pt CB WEB DOWNLOAD

� Pt CB WEB SSL CLIENT CERT SELECT

Changed resources:

� Pt ARG WEB ENCODING

� Pt ARG WEB COMMAND

� Pt ARG WEB OPTION

� Pt ARG WEB SERVER

� Pt CB WEB ERROR

� Pt CB WEB SSL CERTNONTRUSTED

� Pt CB WEB SSL ERROR

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

� Pt ARG WEB AUTHENTICATE

� Pt ARG WEB COMMAND

� Pt ARG WEB DATA

� Pt ARG WEB GET URL

� Pt ARG WEB HELPER

� Pt ARG WEB NAVIGATE FRAME

� Pt ARG WEB NAVIGATE LINK

� Pt ARG WEB NAVIGATE PAGE

� Pt ARG WEB PRINT

� Pt CB WEB AUTHENTICATE

xxiv About This Reference January 31, 2005

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

� Pt CB WEB DATA REQ

� Pt CB WEB ERROR

� Pt CB WEB NEED SCROLL

� Pt CB WEB SSL CERTNONTRUSTED

� Pt CB WEB SSL ERROR

� Pt CB WEB STATUS

� Pt CB WEB UNKNOWN

PtWidget

New resources:

� Pt ARG GRID LAYOUT DATA

� Pt ARG LAYOUT DATA

� Pt ARG ROW LAYOUT DATA

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.

January 31, 2005 About This Reference xxv

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

PtPanelGroup

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

What’s new in Photon for QNX Neutrino 6.2.0PtBasic

New flags forPt ARG BASIC FLAGS:

� Pt BLANK ETCHES

� Pt OPAQUE ETCHES

PtFontSel

New flags forPt ARG FONT FLAGS:

� Pt FONTSELCOLORSELBKGD

� Pt FONTSELCOLORSELTEXT

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.

xxvi About This Reference January 31, 2005

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

PtMultiText

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

PtOSContainer

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

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 forPt ARG MENU FLAGS. It’sset by default.

January 31, 2005 About This Reference xxvii


PtNumericFloat

This widget exportsPt ARG TEXT FLAGS andPt ARG TEXT FONT from its subordinatePtText widget.

PtNumericInteger

This widget exportsPt ARG TEXT FLAGS andPt ARG TEXT FONT from its subordinatePtText widget.

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 ofPtScrollArea

� PtServer

� PtToolbar

xxviii About This Reference January 31, 2005


� PtToolbarGroup

� PtWebClient

Deprecated widgetsInstead of: Use:

AwFileSelect PtFileSel

AwMessage PtAlert(), PtNotice(), or PtPrompt() (see thePhotonLibrary Reference)

PtBitmap PtLabel

PtDBContainer PtOSContainer

PtHtml PtWebClient

PtIcon Define in PhAB

PtMessage PtAlert(), PtNotice(), or PtPrompt() — see thePhotonLibrary Reference

PtTab PtPanelGroup

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

January 31, 2005 About This Reference xxix


� Pt ARG DARK BEVEL COLOR

� Pt ARG DARK FILL COLOR

� Pt ARG INLINE COLOR

� Pt ARG LIGHT BEVEL COLOR

� Pt ARG LIGHT FILL COLOR

� Pt ARG OUTLINE COLOR

� Pt ARG STYLE


� Pt ARG BOT BORDER COLOR

� Pt ARG TOP BORDER COLOR

PtBezier

Pg DRAW FILL andPg DRAW STROKEhave been deleted fromPt ARG BEZIER FLAGS. UsePt ARG INSIDE COLOR (defined byPtGraphic) andPt ARG COLOR (defined byPtBasic) instead.

PtBkgd

The Pt type ofPt ARG BKGD IMAGE is now Image.

PtButton

New resources:

� Pt ARG ARM IMAGE — replacesPt ARG ARM DATA.

PtComboBox

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

xxx About This Reference January 31, 2005


PtContainer

New resources:

� Pt ARG TITLE

� Pt ARG TITLE FONT

� Pt CB CHILD ADDED REMOVED

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

Resources moved toPtWidget:

� Pt ARG ANCHOR FLAGS

� Pt ARG ANCHOR OFFSETS

� Pt CB FILTER

ThePt 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.)

ThePtContainerCallback 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

January 31, 2005 About This Reference xxxi


� Pt ARG FS LBL GROUP

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

PtFontSel

New resources:

� Pt ARG FONT LBL FONT

� Pt ARG FONT LBL QUALITY — deprecated

� Pt ARG FONT LBL QUALITY ANTIALIASED — deprecated

� Pt ARG FONT LBL QUALITY PLAIN — deprecated

� Pt ARG FONT LBL SIZE

� Pt ARG FONT LBL STYLE

� Pt ARG FONT LBL STYLE BOLD — deprecated

� Pt ARG FONT LBL STYLE BOLDITALIC — deprecated

� Pt ARG FONT LBL STYLE ITALIC — deprecated

� Pt ARG FONT LBL STYLE PLAIN — deprecated

PtGenList

Pt ARG LIST DNDSEL COLOR is a new resource.

The actions included in the callback data forPt CB SCROLL MOVEnow includePt SCROLL JUMP.

Pt ARG LIST SCROLL RATE is now of typeunsigned char

instead ofshort.

Pt LIST COLUMN NO STRINGis a new flag forPt ARG LIST COLUMN ATTR

xxxii About This Reference January 31, 2005


PtGauge

New resources:

Resource Replaces

Pt ARG MAXIMUM Pt ARG GAUGE MAXIMUM

Pt ARG MINIMUM Pt ARG GAUGE MINIMUM

Pt ARG ORIENTATION Pt ARG GAUGE ORIENTATION

Pt CB GAUGE VALUE CHANGED N/A

New bits forPt ARG GAUGE FLAGS:

� Pt GAUGE INDETERMINATE

� Pt GAUGE INTERACTIVE

� Pt GAUGE LIVE

� Pt GAUGE SHOW VALUE — replacesPt SHOW VALUE.

� Pt GAUGE VALUE XOR — replacesPt VALUE XOR.

Deprecated bits forPt 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 forPt ARG TREE FLAGS:

January 31, 2005 About This Reference xxxiii


� Pt TREE SHOW LINES

� Pt TREE SHOW MARGIN

� Pt TREE INDENT LINES

� Pt TREE INDENT BUTTONS

� Pt TREE SHOW CONNECTORS

Deprecated bits forPt 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 — replacesPt ARG LABEL DATA.

� Pt ARG TEXT IMAGE SPACING

xxxiv About This Reference January 31, 2005


PtMenuButton

New resources:

� Pt ARG MODIFIER KEYS

New bits forPt ARG BUTTON TYPE:

� Pt MENU UP

� Pt MENU ACCL CTRL

� Pt MENU ACCL ALT

� Pt MENU ACCL SHFT

PtMultiText

Theattributes member of thePtMultiTextControl t structure isnow of typePtMultiTextAttributes 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 ofPt ARG NUMERIC MAX andPt ARG NUMERIC MIN areINT MAX andINT MIN.

January 31, 2005 About This Reference xxxv


PtPolygon

Pg POLY FILL andPg POLY STROKEhave been deleted fromPt ARG POLYGON FLAGS. UsePt ARG INSIDE COLOR (definedby PtGraphic) andPt ARG COLOR (defined byPtBasic) instead.

PtPrintSel

New resources:

� Pt ARG PS LBL ALL

� Pt ARG PS LBL COLLATED

� Pt ARG PS LBL COPIES

� Pt ARG PS LBL DOUBLE SIDED

� Pt ARG PS LBL FILE

� Pt ARG PS LBL FROM

� Pt ARG PS LBL 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

xxxvi About This Reference January 31, 2005


The flags for thePt ARG PRINT FLAGS resource have beenreplaced.

ThePt PRINTSEL ADDNEW andPt PRINTSELRETURNsubtypes ofthePt CB PRINT PROPS callbacks have been deprecated; thePt PRINTSEL INSTALLER, Pt PRINTSEL PROPERTIESEXITED,Pt PRINTSEL INSTALLER EXITED, Pt PRINTSELNOPRINTER, andPt PRINTSEL PRINTERsubtypes have been added.

PtRaw

New resource:

� Pt ARG RAW CALC OPAQUE F

PtRegion

You don’t have to set bits inPt 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 existingPtScrollArea into aPtScrollContainer.

New resources:

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

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

PtScrollAreaCanvas() is a new convenience function.

January 31, 2005 About This Reference xxxvii


PtScrollbar

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

� Pt ARG MAXIMUM

� Pt ARG MINIMUM

� Pt ARG ORIENTATION


� Pt ARG DIRECTION

� Pt ARG SCROLL POSITION — usePt ARG GAUGE VALUE

Deleted bits forPt ARG SCROLLBAR FLAGS:

� Pt SCROLLBAR HORIZONTAL

� Pt SCROLLBAR INVERTED

New bits forPt ARG SCROLLBAR FLAGS:

� Pt SCROLLBAR FIXED SLIDER SIZE

The actions included in the callback data forPt CB SCROLL MOVEnow includePt SCROLL JUMP.

PtSlider

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

New resources:

� Pt ARG SLIDER HANDLE COLOR

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


xxxviii About This Reference January 31, 2005


� Pt ARG SLIDER HANDLE HEIGHT

� Pt ARG SLIDER LABEL BR

� Pt ARG SLIDER LABEL BR COL

� Pt ARG SLIDER LABEL TL

� Pt ARG SLIDER LABEL TL COL

� Pt ARG SLIDER ORIENTATION

� Pt ARG SLIDER TICK MAJOR COL

� Pt ARG SLIDER TICK MINOR COL

� Pt ARG SLIDER TROUGH COL

� Pt ARG SLIDER TROUGH SIZE

Deleted bits forPt 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

January 31, 2005 About This Reference xxxix


Thereason 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

� 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

TheSubst member has been added toPtTerminalCharset t.

PtText

The C type forPt ARG CURSOR POSITION is int, notshort.

PtTimer

Pt ARG TIMER INITIAL andPt ARG TIMER REPEAT are nowunsigned long instead oflong.

xl About This Reference January 31, 2005


PtToggleButton


� Pt ARG INDICATOR DEPTH

� Pt ARG INDICATOR HEIGHT

� Pt ARG INDICATOR WIDTH

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

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

� Pt ARG SPACING — usePt ARG TEXT IMAGE SPACINGinstead (seePtLabel).

The types supported byPt 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

January 31, 2005 About This Reference xli


� Pt ARG TREE COLUMN IMGFUN

� Pt CB TREE COLUMN SEL

PtTreeAddAfter() andPtTreeAddFirst() 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.

Theexpand member of thePtTreeCallback t structure passed toPt CB TREE STATE is now used whether expanding or collapsing anitem. PtTreeCollapse() now returns the value of theexpand member(the prototype has changed).

ThePtTreeItem 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 aPtTree item.

PtTty

The way thePtTty 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 aPtTty 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

xlii About This Reference January 31, 2005


� Pt ARG TTY RFD

� Pt ARG TTY SFD

� Pt ARG TTY WFD


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

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

PtWidget

New resources:

� Pt ARG ANCHOR FLAGS — moved fromPtContainer

� Pt ARG ANCHOR OFFSETS — moved fromPtContainer

� Pt ARG BEVEL WIDTH — replacesPt ARG BORDER WIDTH

� Pt ARG MINIMUM DIM

� Pt ARG POINTER

� Pt CB DND

� Pt CB FILTER — moved fromPtContainer

� Pt CB IS DESTROYED

� Pt CB OUTBOUND

ThePt CB RAW callbacks are now invoked even if the widget’s classmethods consume the event. In this case,Ph CONSUMEDis set in theevent’sprocessing flags member.

ThePt ETCH HIGHLIGHT bit of Pt ARG FLAGS is deprecated; usethePt ARG BASIC FLAGS defined byPtBasic.

January 31, 2005 About This Reference xliii


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

� Ph WM RENDER ASDIALOG

� Ph WM RENDER ASPALETTE

Instead of usingPt ARG MAX HEIGHT, Pt ARG MAX WIDTH,Pt ARG MIN HEIGHT, andPt ARG MIN WIDTH to set thewindow’s dimensions, you can use thePt ARG MAXIMUM DIM andPt ARG MINIMUM DIM resources that are defined byPtWidget.

xliv About This Reference January 31, 2005

Chapter 1

Global Data Structures

January 31, 2005 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 PhotonLibraryReference:

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 January 31, 2005

2005, 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:ThePtBalloonCallback 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 forwidget. Thearguments passed to this function are:

wgt A pointer to the widget whose balloon is beingaffected.

data NULL.

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

� Pt INFLATE BALLOON — make the balloonvisible.

� Pt POPBALLOON — remove the balloon.

Classification:Photon


PtBalloonCallback t 2005, QNX Software Systems Ltd.

See also:PtCallbackInfo t, PtContainer


2005, 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:ThePtCallback t structure lets you specify a widget’s callbackswhen you callPtCreateWidget() 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

Thedata from thePtCallback t structure.

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

☞

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, seePtCallbackInfo t.


PtCallback t 2005, QNX Software Systems Ltd.

Callback functions should returnPt 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 PhotonProgrammer’s Guide.


2005, 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:ThePtCallbackInfo 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 itsPt 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 aPhEvent 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 2005, QNX Software Systems Ltd.

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

PhEvent t in the PhotonLibrary Reference


2005, 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:ThePtHotkeyCallback 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 specifiedflags, this membercontains either the symbol or cap of the key to beinterpreted as a hotkey. For validkey sym capvalues, see<photon/PkKeyDef.h>.

flags Determines howkey sym cap is interpreted andwhether or notkey mods is used. Valid bits include:

Pt HOTKEY SYM

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

Pt HOTKEY IGNORE MODS

Ignore thekey 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 2005, 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 withPk KM .

widget If event f is NULL, thewidget member’s activatecallback is invoked with areason subtype ofPt CB HOTKEY. If the widget member isNULLwhen 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. Ifevent f is NULLwhen the hotkey is activated, the widget that thehotkey is attached to has itsPt CB ACTIVATEcallback (seePtBasic) 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


2005, 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:ThePtRawCallback t structure lets you specify event handlers(raw and filter callbacks) for your application’s widgets. You use thisstructure when setting thePt CB RAW or Pt CB FILTER resource ofany widget (seePtWidget) or callingPtAddEventHandler(),PtAddEventHandlers(), PtAddFilterCallback(), orPtAddFilterCallbacks().

This structure contains at least the following members:

event mask A bitmap that specifies which events trigger thefunction specified inevent f . SeePhEvent t in thePhotonLibrary 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 2005, QNX Software Systems Ltd.

PtAddEventHandler(), PtAddEventHandlers() PtAddFilterCallback(),PtAddFilterCallbacks() in the PhotonLibrary Reference

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


Chapter 2

Widgets

January 31, 2005 Chapter 2 � Widgets 15

2005, 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

PtMeter

PtScrollbar

PtSlider

PtProgress

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

PtBarGraph

PtMTrend

PtUpDown

PtImageArea

The Photon widget hierarchy.


Widget icons in PhAB 2005, 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

PtBarGraph Bar graph

PtBasic Superclass of basicresources for mostwidgets

PtBezier Bezier curve

PtBkgd Background of tiledimages, gradients,or bitmaps

PtButton Button for initiatingan action

PtCalendar Calendar

N/A PtClient Superclass for clientwidgets — notnormallyinstantiated

continued. . .

18 Chapter 2 � Widgets January 31, 2005

2005, QNX Software Systems Ltd. Widget icons in PhAB


PtClock Analog, digital, orLED clock

PtColorPanel Color panel

PtColorPatch Color patch forselecting a hue andshading or tint

N/A PtColorSel Superclass forcolor-selectorwidgets — notnormallyinstantiated

PtColorSelGroup Group of colorselectors

PtColorWell Rectangle thatdisplays a color andlets you change it

PtComboBox Text-entry field witha list of choices

N/A PtCompound Superclass forcompound widgets— not normallyinstantiated

PtContainer Superclass forcontainer widgets

N/A PtDisjoint Superclass fordisjoint widgets —not normallyinstantiated

continued. . .




PtDivider Widget that dividesa given spaceamong its childwidgets and allowsresizing

PtEllipse Ellipse

PtFileSel Tree widget forselecting files anddirectories

PtFlash Container thatdisplaysMacromedia Flash 4animation

PtFontSel Widget for selectingfont attributes

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

N/A PtGenList Superclass for listwidgets — notnormallyinstantiated

N/A PtGenTree Superclass for treewidgets — notnormallyinstantiated

continued. . .




N/A PtGraphic Superclass forgraphical widgets— not normallyinstantiated

PtGrid Grid pattern

N/A PtGroup Group — usePhAB’s GroupTogether button tocreate this

PtImageArea An area for viewingan image

PtLabel A text, bitmap, orimage label

PtLine Straight line (singlesegment)

PtList List of text items

N/A PtMenu Menu — use aMenu moduleinstead

PtMenuBar Menubar that’splaced at the top ofa window

PtMenuButton Button that pops upa menu, or an itemin a menu

PtMeter Meter widget

continued. . .




PtMTrend Medical trendwidget

PtMultitext Multiple-linestylized text field

N/A PtNumeric Numeric fieldsuperclass — notnormallyinstantiated

PtNumericFloat Floating-pointnumeric field

PtNumericInteger Integer field

PtOnOffButton Button that’s eitheron or off

PtOSContainer Offscreen-contextcontainer, useful fordrawing flicker-freeimages andanimations

PtPane Container fororganizing widgets

PtPanelGroup Container thatmanages panels

PtPixel Set of points

PtPolygon Set of connectedline segments

continued. . .




PtPrintSel Compound widgetfor choosingprinting options

PtProgress Progress bar

PtRaw Widget in whichyou can uselow-level Pgdrawing functions

PtRawList Raw list

PtRawTree Raw tree

PtRect Rectangle

N/A PtRegion Photon region —must be createdwithPtCreateWidget()

N/A PtScrollArea Superclass forscrolling widgets —not normallyinstantiated

PtScrollBar Scrollbar

PtScrollContainer Viewport forviewing a largevirtual area

PtSeparator Separator fororganizing widgets

continued. . .




N/A PtServer Server widget —must be createdwithPtCreateWidget()

PtSlider Numerical inputmechanism with arange

PtTab Terminal emulator

PtTerminal Terminal emulator

PtText Single-line text field

PtTimer Timer

PtToggleButton Toggle button

PtToolbar Superclass fortoolbar widgets

PtToolbarGroup Group of toolbars

PtTree Hierarchy tree

PtTrend Display ofconnected pointsthat shift in aspecified directionat the rate in whichdata is fed

PtTty Terminal device

PtUpDown Up/Down button

continued. . .


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


PtWebClient Widget fordisplaying webpages

N/A PtWidget Widget superclass— not normallyinstantiated

N/A PtWindow Window — use aPhAB windowmodule instead

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.

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.


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

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 (usuallyshort).

� 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 — aPhImage t structure; see the PhotonLibrary Reference.

� Link — a linked list.

� Pointer — a pointer to arbitrary data.

� Scalar — a value that can be represented within asinglelong (that is, along, ashort, or achar).

� String — aNULL-terminated UTF-8 string.

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

Default The default value(s) of a resource.


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

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

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, thePt SELECTABLEflag is added to the resourceand thePt HIGHLIGHTED flag is cleared:

|=Pt SELECTABLE &=˜Pt HIGHLIGHTED

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


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

Convenience functions

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


Photon Widgets — PtA to PtN

January 31, 2005 Photon Widgets — PtA to PtN 29


The Photon Widgets, data structures, and widget-related functions aredescribed here in order:

Volume Range Entries

1 PtA to PtN PtArc to PtNumericInteger

2 PtO to PtW PtOnOffButton to PtWindowToFront()


PtArc 2005, QNX Software Systems Ltd.

An elliptical arc

Class hierarchy:PtWidget → PtBasic → PtGraphic → PtArc

PhAB icon:

Public header:<photon/PtArc.h>

Description:You can usePtArc 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 (seePtGraphic). 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

32 Photon Widgets — PtA to PtN January 31, 2005

2005, 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 thePt 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 RESIZEXY 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 2005, 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 settingPt ARG BARGRAPH DATA to anarray of values. The colors of the bars depends on how you set thewidget’s resources:


2005, QNX Software Systems Ltd. PtBarGraph

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

values.

� If you setPt ARG BARGRAPH COLOR to NULL, the widget usesthe value ofPt ARG COLOR for all the bars.

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

If you setPt 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 isNULL, thewidget uses the value ofPt ARG COLOR (inherited fromPtBasic)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,thevalue is the array of data, andarg 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 2005, QNX Software Systems Ltd.

A superclass of basic resources for most widgets

Class hierarchy:PtWidget → PtBasic

Immediate subclasses:

� PtBarGraph –>

� PtCalendar

� PtClock

� PtContainer

� PtGauge

� PtGraphic

� PtLabel

� PtRaw

� PtSeparator

� PtTrend

PhAB icon:

Public header:<photon/PtBasic.h>

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

� getting/losing focus

� activating

� button press, release, and repeat


2005, QNX Software Systems Ltd. PtBasic

Also,PtBasic supports:

� 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 SELECTABLEset in itsPt ARG FLAGS (seePtWidget).

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

continued. . .



When you: The widget becomes: Callback invoked:

Release the leftpointer buttonwhen the pointer isoutside an armedwidget

Disarmed Pt CB DISARM

� Not all widgets change their appearance when armed.

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

☞

If you hold down the left pointer button, the widget’sPt 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’sPt CB MENU callback list is invoked.

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

If the widget hasPt ALL BUTTONSset in itsPt 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 inPt ARG BASIC FLAGS to indicate which



components 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 byPtWidget)

� 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 byPt ARG BEVEL COLOR. The bevel is shadedaccording toPt ARG BEVEL CONTRAST, which is used to calculatethe default values ofPt 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 setPt STATIC BEVEL COLORSin Pt ARG BASIC FLAGS, thebevel color doesn’t change when you setPt 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 usePt ARG FILL COLOR to specify the widget’s fill color.These bits inPt 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 REVERSEGRADIENT

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 settingPt ARG CONTRAST. If this resource doesn’t giveyou the look you want, you can override it by settingPt ARG DARK FILL COLOR andPt ARG LIGHT FILL COLORexplicitly.

Pt ARG COLOR specifies the foreground or drawing color.



SettingPt ARG FILL COLOR overrides any previous setting ofPt ARG DARK FILL COLOR, andPt ARG LIGHT FILL COLOR. IfPt STATIC BEVEL COLORSisn’t set inPt ARG BASIC FLAGS, thenew fill color also overridesPt ARG BEVEL COLOR,Pt ARG DARK BEVEL COLOR, andPt ARG LIGHT BEVEL COLOR.

☞

New resources:


Pt ARG BANDWIDTH THRESHOLD unsigned long Scalar 0

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

continued. . .




Pt ARG INLINE COLOR PgColor t Scalar Pg DGRAY

Pt ARG LIGHT BEVEL COLOR PgColor t Scalar Set internally

Pt ARG LIGHT FILL COLOR PgColor t Scalar Set internally

Pt ARG MARGIN HEIGHT unsigned short Scalar 0

Pt ARG MARGIN WIDTH unsigned short Scalar 0

Pt ARG OUTLINE COLOR PgColor t Scalar Pg WHITE

Pt ARG STYLE See below Complex

Pt ARG TRANS PATTERN PgPattern t Struct Pg PAT NONE

Pt CB ACTIVATE PtCallback t * Link NULL

Pt CB ARM PtCallback t * Link NULL

Pt CB DISARM PtCallback t * Link NULL

Pt CB GOT FOCUS PtCallback t * Link NULL

Pt CB LOST FOCUS PtCallback t * Link NULL

Pt CB MENU PtCallback t * Link NULL

Pt CB REPEAT PtCallback t * Link NULL

Pt ARG BANDWIDTH THRESHOLD


unsigned long Scalar 0

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 (seePt 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 bevelPt 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

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

Fill-control bits

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, andPt 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 REVERSEGRADIENT

If set andPt 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.



Pt BASIC PREVENT FILL

If set, the widget isn’t filled. This is useful whenyou want to set the base color for borders andetches without actually rendering a fill.

Behavior on state change

These bits affect how the widget behaves when set (depressed) orunset (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. SeePgColor t in the PhotonLibraryReference.

This value is automatically generated when you setPt ARG FILL COLOR. SettingPt 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 (seePt ARG BASIC FLAGS).

Pt ARG COLOR


PgColor t Scalar Pg BLACK

The widget’s foreground or drawing color. SeePgColor t in thePhotonLibrary 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 (seePt ARG BASIC FLAGS).

☞

Pt ARG DARK BEVEL COLOR


PgColor t Scalar Set internally

This resource, withPt 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. SettingPt ARG FILL COLOR overrides anyvalues set previously via these resources.

☞

Pt ARG DARK FILL COLOR



This resource, withPt 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). SeePt 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. SeePgColor 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 isPt ARG FILL COLOR. If thewidget uses a gradient fill, the gradient runs fromPt ARG LIGHT FILL COLOR to Pt ARG DARK FILL COLOR. Ifthe widget uses a bevel, it’s rendered with color ranges as defined byPt ARG LIGHT BEVEL COLOR to Pt ARG LIGHT FILL COLORandPt ARG DARK BEVEL COLOR toPt ARG DARK FILL COLOR.

SeePt 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 aPtOSContainer.

☞

Pt ARG INLINE COLOR


PgColor t Scalar Pg DGRAY

The color of the inline of the border. SeePgColor t in the PhotonLibrary Reference.

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



Pt ARG LIGHT BEVEL COLOR



This resource, withPt 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, withPt 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). SeePt 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. SeePgColor t in the PhotonLibrary Reference.

The outline is drawn if any ofPt TOP OUTLINE,Pt BOTTOM OUTLINE, Pt LEFT OUTLINE, andPt RIGHT OUTLINEare set inPt 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 PhotonProgrammer’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 callingPtSetWidgetStyle().For more information, see the PhotonLibrary 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 thePtWidgetClassStyle t structuredirectly; callPtGetStyleMember() 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 hasPt SELECTABLEset in itsPt ARG FLAGS.

PtText, PtMultiText, andPtComboBox have special versions ofPt CB ACTIVATE.

☞

Each callback is passed aPtCallbackInfo 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 aPhEvent t structure that describes theevent that caused the callback to be invoked, orNULL ifthere isn’t an event.

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

� long int value —

if the Pt TOGGLEflag in Pt ARG FLAGS is set,valuecontains either 1 (the widget is pushed in) or 0 (thewidget is pushed out). IfPt TOGGLEisn’t set,valuecontains the click count.



These callbacks should returnPt CONTINUE.

If you multi-click on a widget, itsPt 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 aPh EV BUT RELEASEevent with asubtype ofPh EV RELEASEENDCLICK. For more information, seePhEvent t in the PhotonLibrary Reference.

ThePh EV BUT RELEASEevent with a subtype ofPh EV RELEASEENDCLICK 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 callPtIsFocused() to find the current focus stateof any widget.


reason Pt CB GOT FOCUS

reason subtype

0 (not used).

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

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

PtWidget t *src

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

PtWidget t *dst

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




ReturningPt 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 PhotonLibraryReference.

☞

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


PtWidget t *dst


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 havePt MENUABLE set andPt ALL BUTTONScleared in its Pt ARG FLAGS resource. The widget doesn’t need tohavePt SELECTABLEset in itsPt 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 receivesPh EV BUT REPEATevents. Theseevents occur when you hold down the left pointer button (or the rightpointer button if the widget hasPt ALL BUTTONSset 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 GRID LAYOUT DATA PtWidget



Pt ARG LAYOUT DATA PtWidget




Pt ARG POS PtWidget


Pt ARG ROW LAYOUT DATA PtWidget


continued. . .







Pt CB DND PtWidget





Pt CB RAW PtWidget




2005, QNX Software Systems Ltd. PtBezierA Bezier curve

Class hierarchy:PtWidget → PtBasic → PtGraphic → PtBezier

PhAB icon:

Public header:<photon/PtBezier.h>

Description:ThePtBezier class draws a Bezier curve viaPgDrawBezier().

A Bezier curve created by PtBezier.

ThePt ARG POINTS resource specifies the points in the Beziercurve. These points are relative to the widget’sPt ARG ORIGIN. Formore information, seePtGraphic.

New resources:


PtBezier 2005, QNX Software Systems Ltd.


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


2005, QNX Software Systems Ltd. PtBezier













Pt ARG DIM PtWidget












continued. . .


PtBezier 2005, QNX Software Systems Ltd.















Pt ARG POS PtWidget







Pt CB ARM PtBasic



continued. . .


2005, QNX Software Systems Ltd. PtBezier



Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






PtBkgd 2005, QNX Software Systems Ltd.

A color-gradient and image background

Class hierarchy:PtWidget → PtBasic → PtContainer → PtBkgd

PhAB icon:

Public header:<photon/PtBkgd.h>

Description:ThePtBkgd 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


2005, QNX Software Systems Ltd. PtBkgd

widget’sPt ARG FILL COLOR andPt 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 aPhImage t structure that defines the image to bedisplayed. If it’sNULL, no image is displayed. For more information,seePhImage t andPxLoadImage() in the PhotonLibrary Reference.

Set theflags member of thePhImage t structure to:

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



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

When you set this resource, the widget copies thePhImage t

structure but not the data pointed to by the members of the structure.After setting this resource, you canfree() thePhImage t if you don’tneed it, but don’tfree() 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

Pt ARG FILL LAYOUT INFO PtContainer




Pt ARG GRID LAYOUT INFO PtContainer






continued. . .




Pt ARG LAYOUT INFO PtContainer









Pt ARG POS PtWidget



Pt ARG ROW LAYOUT INFO PtContainer


Pt ARG TITLE PtContainer

Pt ARG TITLE FONT PtContainer





Pt CB ARM PtBasic

Pt CB BALLOONS PtContainer


continued. . .




Pt CB CHILD ADDED REMOVED PtContainer



Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget



Pt CB RESIZE PtContainer



2005, QNX Software Systems Ltd. PtButtonA button for initiating an action

Class hierarchy:PtWidget → PtBasic → PtLabel → PtButton


� PtOnOffButton

� PtToggleButton

PhAB icon:

Public header:<photon/PtButton.h>

Description:ThePtButton 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 forPtLabel

widgets.


PtButton 2005, QNX Software Systems Ltd.

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, seePtBasic.

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 thePt ARG ARM COLORresource to set the fill color for armed pushbuttons. This resource isignored if thePt 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, usethePt ARG ARM IMAGE resource. When thePt ARG LABEL TYPEresource (seePtLabel) 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:


2005, QNX Software Systems Ltd. PtButton


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).SeePgColor t in the PhotonLibrary Reference.

This resource is used only ifPt ARG ARM FILL is set toPt TRUE.

Pt ARG ARM FILL


unsigned char Scalar Pt FALSE

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

Pt TRUE Use the value ofPt ARG ARM COLOR.

Pt FALSE Ignore the value ofPt ARG ARM COLOR.

Pt ARG ARM IMAGE





A pointer to aPhImage t structure (see the PhotonLibraryReference) that defines the image to use when the button is armed. It’sused only if the label type (Pt ARG LABEL TYPE — seePtLabel)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





continued. . .





Pt ARG POS PtWidget



Pt ARG SECONDARY H ALIGN PtLabel

Pt ARG SECONDARY V ALIGN PtLabel


Pt ARG TEXT FONT PtLabel

Pt ARG TEXT IMAGE SPACING PtLabel

Pt ARG TEXT STRING PtLabel


Pt ARG UNDERLINE TYPE PtLabel

Pt ARG UNDERLINE1 PtLabel



Pt ARG VERTICAL ALIGNMENT PtLabel Pt CENTER



Pt CB ARM PtBasic




Pt CB DND PtWidget

continued. . .









Pt CB MENU PtBasic


Pt CB RAW PtWidget





2005, QNX Software Systems Ltd. PtCalendarA 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.


PtCalendar 2005, QNX Software Systems Ltd.

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


2005, QNX Software Systems Ltd. PtCalendar

Pt ARG CALENDAR COLOR1



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

in the PhotonLibrary Reference.



PgColor t Scalar Pg DGREY

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




The color used for the year and month name. SeePgColor t in thePhotonLibrary 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). SeePgColor t in thePhotonLibrary Reference.

Pt ARG CALENDAR DATE


PtCalendarDate t Struct Current date

The current date shown on the calendar.

You might find it easier to usePt 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 aPtCalendarDate 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 and0x3means that days 1 and 2 are highlighted.

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

You can’t editPt 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. SeePgColor t in the PhotonLibrary 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 editPt 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. SeePgColor 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 editPt 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 editPt 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.SeePgColor t in the PhotonLibrary 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 aPtCalendarSelectCallback t

structure.

ThePtCalendarSelectCallback 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 atime 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

continued. . .





Pt CB RAW PtWidget





2005, QNX Software Systems Ltd. PtClientClient widget

Class hierarchy:PtWidget → PtBasic → PtContainer → PtClient


� PtWebClient

PhAB icon:None — not normally instantiated.

Public header:<photon/PtClient.h>

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

PtClient andPtServer use a Photon connection to communicate(see “Connections” in the Interprocess Communications chapter ofthe PhotonProgrammer’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 aPtServer widgetand handles the process of connecting to aPtServer. 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:


PtClient 2005, QNX Software Systems Ltd.


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 toPtSetResources() that setsPt ARG CLIENT NAME doesn’t return until the connecting haseither succeeded or been aborted.

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


2005, QNX Software Systems Ltd. PtClient

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 aPt CB SERVER RECEIVEcallback in the server that lets the server specify a reply. The reply isthen available in the client by getting thePt 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’sNULL.

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 aPtCallbackInfo 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 aPtClientErrorCallback t structurethat contains at least:

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

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

☞

� int errnum — theerrno value from the error handler.

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



If this value isPt CONNECTION CLIENT BROKEN, the widgetdisconnected from the server and itsPt ARG CLIENT NAMEresource has been reset toNULL.

☞


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 aPtClientCallback 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 anint initialized toPt END. Set it toPt CONTINUE if you want the widget to retry after a littlewhile. Typically, the firstPt 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.
























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






2005, QNX Software Systems Ltd. PtClockAn 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 aPtOSContainer, but youmust use a transparent fill for the clock, or it won’t be refreshedproperly.

☞


PtClock 2005, QNX Software Systems Ltd.

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


2005, QNX Software Systems Ltd. PtClock

Pt ARG CLOCK FACE COLOR



The fill color of the clock’s face (applicable only for analog clocks).SeePgColor t in the PhotonLibrary Reference.

Pt ARG CLOCK FACE OUTLINE COLOR



The color of the line drawn around the clock face (applicable only foranalog clocks). SeePgColor t in the PhotonLibrary 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 overridesPt 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 anAM 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 thePt 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 ifPt CLOCK TRACK TIME is set). This value is in24-hour format.

If you set this resource toPt 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 PhotonLibrary 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 ifPt CLOCK TRACK TIME is set). If you set thisresource toPt 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 PhotonLibrary 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 ifPt CLOCK TRACK TIME is set). If you set thisresource toPt 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 PhotonLibrary 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. SeePgColor t in the PhotonLibrary Reference.

Pt ARG CLOCK SEP2


char * String ":"

The separator to use between the minutes and seconds field(applicable only for digital clocks withPt 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. SeePgColor t in the PhotonLibraryReference.



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 SECONDSis set, otherwise once every minutewhen the minute changes.

If the widget has thePt CALLBACKS ACTIVE bit set in itsPt ARG FLAGS resource, these callbacks are also invoked when yourapplication changes the time by callingPtSetResource() 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 SECONDCHANGED

event A pointer to aPhEvent t structure that describes theevent that caused the callback to be invoked. Ifevent isNULL, the callback was invoked because your applicationchanged the time setting by callingPtSetResources().

cbdata A pointer to aPtClockTimeCallback 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






continued. . .






Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget





2005, QNX Software Systems Ltd. PtColorPanelA 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 (pressEsc to abort the operation).

A PtColorPanel widget.

New resources:


PtColorPanel 2005, QNX Software Systems Ltd.


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


2005, QNX Software Systems Ltd. PtColorPanel













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























Pt ARG POS PtWidget




continued. . .


2005, QNX Software Systems Ltd. PtColorPanel








Pt CB ARM PtBasic




Pt CB CS COLOR CHANGED PtColorSel



Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget


continued. . .








2005, 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 ifPt CPATCH SHOW SELECTORis set inPt ARG CPATCH FLAGS.


PtColorPatch 2005, 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 inPt 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 aPtComboBox selector that lets you select the colormodels that are supported by the color patch (see thePt ARG CS COLOR MODELS resource defined byPtColorSel).


2005, 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. . .


2005, QNX Software Systems Ltd. PtColorPatch










Pt ARG POS PtWidget










Pt CB ARM PtBasic





continued. . .






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






2005, 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 ofPtColorSel.

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 2005, 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. SeePgColor t in the PhotonLibraryReference.

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.


2005, 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 ofPtColorSel itself,but may be observed by subclasses (PtColorPatch uses it torender the two-dimensional patch).

Pt CS QUANTIZE COLOR

EnsurePt 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 thisPtColorSel. 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 aPtColorSelCallback t structure thatcontains at least these members:

� PgColor t rgb — the selected color, in RGB format.SeePgColor t in the PhotonLibrary Reference.

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

� PgColorModel t const *color model — the colormodel, which you should to interpret the values storedin thechannels. If this is NULL, thechannels 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






2005, 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 aPtColorPanel 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 2005, 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 CSGROUPALL AT ONCE

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













continued. . .


2005, QNX Software Systems Ltd. PtColorSelGroup















Pt ARG DIM PtWidget










continued. . .


PtColorSelGroup 2005, QNX Software Systems Ltd.












Pt ARG POS PtWidget










Pt CB ARM PtBasic



continued. . .


2005, QNX Software Systems Ltd. PtColorSelGroup






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






PtColorWell 2005, 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, aPtColorPatch pops up to let you select a color tobe displayed in the color well.

A PtColorWell widget.

New resources:


2005, QNX Software Systems Ltd. PtColorWell


Pt ARG CWELL FLAGS uint16 t Flags Pt CWELL POPUPON SELECT|Pt CWELL POPUPON MENU

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

Pt ARG CWELL FLAGS


uint16 t Flags Pt CWELL POPUPON SELECT|Pt CWELL POPUPON MENU

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

Pt CWELL POPUPON SELECT

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

Pt CWELL POPUPON 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 PhotonLibrary Reference) that definesthe dimensions of the popup color patch, in pixels.
























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






PtComboBox 2005, 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:ThePtComboBox class provides a widget that’s built from twoexported subordinate widgets:PtList andPtText.

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.


2005, QNX Software Systems Ltd. PtComboBox

The widget behaves like aPtList 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 BROWSEMODE.

☞

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 letsPtComboBox 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 thePtComboBox 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

TheAlt – ↓ action occurs only ifPt COMBOBOX ALT DOWN is set inthe widget’sPt ARG CBOX FLAGS.

If the list has focus, the keyboard actions are:



Key Action

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

↑ 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 forPtText:

� 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 forPtList:

� 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 theAlt – ↓ 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 orPt ARG VISIBLE COUNT tocontrol the size of the list, but you shouldn’t use them both.

Pt ARG CBOX SEL ITEM



An index intoPt 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 inPtComboBox, thePtComboBox class uses the resources of its exported subordinatechildren,PtList andPtText.

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

� Pt ARG SELECTION MODE (defined inPtGenList andinherited byPtList) — browse mode is always used.

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

WherePtComboBox 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. IfPtComboBox 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 SELECTSHIFT


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



continued. . .




Pt ARG MODIFY ITEMS PtList



Pt ARG POS PtWidget

Pt ARG RESIZE FLAGS PtWidget Pt RESIZEXY 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

continued. . .






Pt ARG TOP ITEM POS PtGenList


Pt ARG UNDERLINE TYPE PtLabel Blocked by this class.

Pt ARG UNDERLINE1 PtLabel Blocked by this class.

Pt ARG UNDERLINE2 PtLabel Blocked by this class.


Pt ARG VERTICAL ALIGNMENT PtLabel

Pt ARG VISIBLE COUNT PtGenList See below.


Pt CB ACTIVATE PtBasic Behaves as forPtText.

Pt CB ARM PtBasic






Pt CB DND PtWidget





continued. . .




Pt CB LIST INPUT PtList


Pt CB MENU PtBasic

Pt CB MODIFY NOTIFY PtText

Pt CB MODIFY VERIFY PtText

Pt CB MOTION NOTIFY PtText

Pt CB MOTION VERIFY PtText


Pt CB RAW PtWidget




Pt CB SCROLL MOVE PtGenList

Pt CB SELECTION PtList

Pt CB TEXT CHANGED PtText


Pt ARG VISIBLE COUNT

Set this resource to a nonzero value to resize the list to a multiple 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:ThePtComboBox widget and its exported subordinatePtList 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 aPtText widget.

PtTextModifyText()

Modifies the contents of aPtText widget.

PtTextSetSelection()

Sets the selected range for aPtText widget.


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

Synopsis:int PtComboBoxListClose( PtWidget t *widget );

Description:This function closes the list in aPtComboBox widget.

Returns:0 Success.

-1 The specified widget isn’t aPtComboBox widget.


Safety

Interrupt handler No

Signal handler No

Thread No

See also:PtComboBoxListOpen()


PtComboBoxListOpen() 2005, QNX Software Systems Ltd.

Open a combobox list

Synopsis:int PtComboBoxListOpen( PtWidget t *widget );

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

Returns:0 Success.

-1 The specified widget isn’t aPtComboBox widget.


Safety


Signal handler No

Thread No

See also:PtComboBoxListClose()


2005, 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:ThePtCompound superclass provides the ability to combine widgetsinto a compound. A compound widget canexport its subordinatechildren to let you get and set their resources, or it can block access tothem to provide a “canned” appearance.



PtCompound 2005, QNX Software Systems Ltd.




















Pt ARG DIM PtWidget





continued. . .


2005, QNX Software Systems Ltd. PtCompound















Pt ARG POS PtWidget









Pt CB ARM PtBasic

continued. . .


PtCompound 2005, QNX Software Systems Ltd.







Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






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

Class hierarchy:PtWidget → PtBasic → PtContainer


� PtBkgd

� PtClient

� PtCompound

� PtDisjoint

� PtFlash

� PtFontSel

� PtGroup

� PtImageArea

� PtOSContainer

� PtPane

� PtPanelGroup

� PtPrintSel

� PtScrollArea

� PtTerminal

� PtToolbar

� PtToolbarGroup

PhAB icon:


PtContainer 2005, QNX Software Systems Ltd.

Public header:<photon/PtContainer.h>

Description:ThePtContainer 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 ENABLE CUA ARROWS

Pt ARG CURSOR OVERRIDE int Boolean Pt FALSE

Pt ARG FILL LAYOUT INFO PtFillLayoutInfo t * Struct NULL

Pt ARG GRID LAYOUT INFO PtGridLayoutInfo t * Struct NULL

Pt ARG LAYOUT PtLayoutDefinition t * Struct NULL

Pt ARG LAYOUT INFO void * Struct NULL

Pt ARG LAYOUT TYPE int Scalar NULL

Pt ARG ROW LAYOUT INFO PtRowLayoutInfo t * Struct NULL

Pt ARG TITLE char * String NULL

Pt ARG TITLE FONT char * String "TextFont09"

Pt CB BALLOONS PtBalloonCallback t * Link NULL

Pt CB CHILD ADDED REMOVED PtCallback t * Link NULL

Pt CB CHILD GETTING FOCUS PtCallback t * Link NULL

continued. . .


2005, QNX Software Systems Ltd. PtContainer


Pt CB CHILD LOSING FOCUS PtCallback t * Link NULL

Pt CB LAYOUT PtCallback t * Link NULL

Pt CB RESIZE PtCallback t * Link NULL

Pt ARG CONTAINER FLAGS


long Flag Pt ENABLE CUA | Pt ENABLE CUA ARROWS

Flags that control the look and behavior of the container:

Pt AUTO EXTENT

Cause the container to recalculate its preferred size when any 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 byPt ARG TITLE,provided thatPt SHOW TITLE is also set.



Pt GRADIENT TITLE AREA

Display a gradient behind the title given byPt ARG TITLE,provided thatPt 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 adisjointcontainer-class widget.

Pt SHOW TITLE

Display the title given byPt ARG TITLE, using the fontspecified byPt 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 tosettingPt ARG LAYOUT TYPE andPt ARG * LAYOUT INFOseparately.



This resource can be one of:

� PtFillLayout

� PtRowLayout

� PtGridLayout

� NULL (equivalent toPtAnchorLayout, the default layout type)

When you set this resource usingPtSetResource() or PtSetArg(), youcan optionally also set thePt ARG * LAYOUT INFO resource for theappropriate layout type using thelen argument. To do this, pass apointer to layout information structure appropriate to the layout typeaslen. 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 thePhotonProgrammer’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 thelen 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, thevalue argument ofPtSetResource() 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 thelen argument ofPtSetResource() orPtSetArg() to the layout information structure,Pt*LayoutInfo t.If you setlen 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 thePtFillLayout layout type. Youcan set this resource directly, or viaPt ARG LAYOUT INFO.

ThePtFillLayoutInfo 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 thePtRowLayout layout type. You canset this resource directly, or viaPt 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 usePtRowLayoutInfoDflts 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 thePtGridLayout layout type. Youcan set this resource directly, or viaPt 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 usePtGridLayoutInfoDflts 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 ifPt SHOW TITLE is set inPt ARG CONTAINER FLAGS.

Pt ARG TITLE FONT



The font to use for the label’s text string; seePgSetFont() in thePhotonLibrary Reference.



Pt CB BALLOONS


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, orPt POPBALLOON 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, itenables the balloon mechanism for that container. When a boundary



event with a subtype ofPh 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 aPt POPBALLOONsubtype). While the balloons are active, any widget that has a balloonthat intersects with aPh 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 consumesPh EV BOUNDARY eventsto prevent the balloon mechanism for the container from becomingenabled and activated.

This can be done by giving the overlapping widget aPt CB RAWcallback (seePtWidget) that’s sensitive toPh EV BOUNDARYevents, or by giving the overlapping widget a cursor (whichautomatically setsPh FORCEBOUNDARY 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 DESTROYEDset in itsPt ARG FLAGS.

These callbacks are invoked only if:

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

� Pt PROCREATEDisn’t set in thePt ARG FLAGS of the child beingadded or removed.

☞

Each callback is passed aPtCallbackInfo 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 callPtIsFocused() to find the current focus state of anywidget.




reason Pt CB CHILD GETTING FOCUS

reason subtype

0 (not used).



PtWidget t *src


PtWidget t *dst


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 callPtIsFocused() to find the current focus state of anywidget.


reason Pt CB CHILD LOSING FOCUS

reason subtype

0 (not used).



PtWidget t *src


PtWidget t *dst


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 aPhEvent t structure filled withNULLs

cbdata NULL

These callbacks should return PtCONTINUE.

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 aPtContainerCallback t structure thatcontains at least the following members:

PhRect t old size;

A PhRect t structure (see the PhotonLibraryReference 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


continued. . .






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget





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

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

Pt CB SYSINFO



A list of PtCallback t structures that define the callbacks invokedwhen the widget receives aPh 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, callPhQuerySystemInfo() orPtQuerySystemInfo(), both of which are described inthe PhotonLibrary Reference.


cbdata NULL.



2005, QNX Software Systems Ltd. PtDisjoint






Pt ARG BANDWIDTH THRESHOLD PtBasic















Pt ARG DIM PtWidget

continued. . .


PtDisjoint 2005, QNX Software Systems Ltd.



















Pt ARG POS PtWidget






continued. . .


2005, QNX Software Systems Ltd. PtDisjoint





Pt CB ARM PtBasic






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






PtDivider 2005, 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:ThePtDivider widget is a container that lays out its children like aone-row or one-columnPtGroup 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.

ThePtDivider class inherits resources from thePtGroup class.Access to these resources is controlled throughPtDivider’sexporting mechanism.

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


2005, QNX Software Systems Ltd. PtDivider

New resources:


Pt ARG DIVIDER FLAGS unsigned short Flag Pt DIVIDER RESIZEBOTH

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 RESIZEBOTH

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 NORESIZEis also set.

Pt ARG DIVIDER OFFSET




short Scalar 0

This number is added to positions of child widgets (relative to theposition of thePtDivider 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 ofrealized children of the divider.EachPtDividerSizes 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 thePt CALLBACKS ACTIVE bit set in itsPt ARG FLAGS resource, these callbacks are also invoked when yourapplication changes the size of a child by callingPtSetResource() orPtSetResources().




reason Pt CB DIVIDER DRAG

reason subtype

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

event A pointer to aPhEvent t structure that describes thereceived drag event, orNULL if a child is being resizedthrough a call toPtSetResources().

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

PtWidget t *left, *right;

The two widgets in the group separated bythe 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 thesizes array.




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

WherePtDivider andPtGroup both define resources having thesame name, the resource defined inPtDivider takes precedence.

Inherited resources:If PtDivider modifies an inherited resource, the “Default override”column indicates the new value. IfPtDivider inherits a resourcefrom PtGroup, the default value assigned byPtGroup 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 SetsPt 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 SetsPt GROUPSTRETCHflag

Pt ARG GROUP HORZ ALIGN PtGroup

Pt ARG GROUP ORIENTATION PtGroup Pt GROUPHORIZONTAL (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









continued. . .




Pt CB ARM PtBasic






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 — seePtQuerySystemInfo().



Pt ARG GROUP ORIENTATION

The value of this resource can be onlyPt GROUPHORIZONTAL orPt GROUPVERTICAL.


2005, QNX Software Systems Ltd. PtEllipseAn ellipse

Class hierarchy:PtWidget → PtBasic → PtGraphic → PtEllipse

PhAB icon:

Public header:<photon/PtEllipse.h>

Description:ThePtEllipse 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, seePtGraphic.

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



PtEllipse 2005, QNX Software Systems Ltd.




















Pt ARG DIM PtWidget





continued. . .


2005, QNX Software Systems Ltd. PtEllipse






















Pt ARG POS PtWidget



continued. . .


PtEllipse 2005, QNX Software Systems Ltd.






Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






2005, QNX Software Systems Ltd. PtFileSelA tree widget for selecting files and directories

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

PhAB icon:

Public header:<photon/PtFileSel.h>

Description:ThePtFileSel 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 thePtFileSel 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:


PtFileSel 2005, QNX Software Systems Ltd.

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 aPtFileSelItem 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


2005, QNX Software Systems Ltd. PtFileSel

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 thePt 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. APtDivider widget is automaticallyincluded in the file selector, along with a label for each column yourequest.

If you want to override the default headers, create aPtDivider ofyour own, add appropriatePtLabel 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 aPtDivider with the headings“Filename”, “File size”, and “Modification time” as a child of aPtFileSel widget and set thePt 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 thePt ARG FS REFRESH resource. You can alsoset thePt FS FREEON COLLAPSEflag 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 thePtFileSel widget yourself by usingthePtFSAllocItem(), PtFSAddFirst(), andPtFSAddAfter()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 returnPt 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. ReturnPt 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.

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

� ThePt CB FS STATE callback is invoked when an item isexpanded or collapsed. The expansion may take a long time if thedirectory is large, so thePt 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.

� ThePt 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 fullPtFileSel 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 thefile spec ) iscase-insensitive.

Pt FS ERRORPOPUP

Display an error dialog when the desired root directory isinvalid.

Pt FS FREEON 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/orPt 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.☞

Thes andk 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 toNULL. 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 thePt 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 typePhImage t — seethe PhotonLibrary 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, specifyNULL for that arrayelement. For example, to change the file image, set thePt FS FILEentry of the array to the image pointer and set all others toNULL.

For example, to change thePt FS DIR OPandPt 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 theflags member of thePhImage 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 thePtFileSelItem 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 isNULL ornone.

The widget stores the actual path obtained via therealpath() function(see the QNX NeutrinoLibrary 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).

SettingPt ARG FS ROOT DIR to NULL clears thePtFileSeldirectory 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 — thePtFileSel widget is doingintensive work and you may want to process events.


cbdata Used only for thePt FS NEW ITEM subtype of thiscallback

For thePt FS NEW ITEM reason subtype,cbdata points to a structureof typePtFileSelBkgdCallback t, which contains at least:

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

If this callback returnsPt END, the item isn’t added. If you wish totranslate an item to another encoding, you should usePxTranslate...functions to do so, copy the new string intoname, and returnPt CONTINUE. You may also wish to process events.

Set thePt CB FS BKGD HANDLER callback resourcebefore 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 aPtFileSelCallback t structure thatcontains:

� unsigned sel mode — the current selection mode:

- Pt BROWSEMODE

- 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 COLLAPSINGor Pt TREE EXPANDING.


cbdata A pointer to aPtFileSelCallback t structure thatcontains:

� unsigned sel mode — the current selection mode:

- Pt BROWSEMODE

- 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 thereason member isPt FS STATE END, this isNULL.

If the Pt FS SINGLE LEVEL flag is set in thePt ARG FS FLAGSresource,item is alwaysNULL 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














continued. . .




Pt ARG POS PtWidget


Pt ARG SCROLLBAR WIDTH PtGenList


Pt ARG SELECTION MODE PtGenList







Pt ARG TREE FLAGS PtGenTree

Pt ARG TREE LINE COLOR PtGenTree

Pt ARG TREE LINE SPACING PtGenTree

Pt ARG TREE MARGIN COLOR PtGenTree


Pt ARG VISIBLE COUNT PtGenList



Pt CB ARM PtBasic

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 aPtList, thecbinfo->cbdata is apointer to aPtTreeDndCallback t structure, containing at leastthe following members:

PtDndCallbackInfo t dnd info

See the description ofPt CB DND for PtWidget.



PtGenTreeItem t *item

A pointer to thePtGenTreeItem t structure forthe target item involved in the drag-and-dropoperation. 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 DNDSELECTEDUP — the dropoccurred above the item.

� Pt LIST ITEM DNDSELECTEDDOWN — thedrop occurred below the item.

� Pt LIST ITEM DNDSELECTEDIN — the dropoccurred inside the item.

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

Convenience functions:ThePtFileSel 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 ofPtGenList)

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


2005, QNX Software Systems Ltd. PtFSAddAfter()Insert an item after the specified item

Synopsis:void PtFSAddAfter( PtWidget t *fs,

PtFileSelItem t *item,PtFileSelItem t *brother );

Description:This function inserts a list of items linked with the brother field.PtFSAddAfter() assumes thatitem points to a list of items. Thefsvariable points to aPtFileSel widget. The new items are added tothe specified file selector below the specifiedbrother.

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 aNULL fs argument, as long asbrother points to an item that isn’t attached to any file selector widget.


PtFSAddAfter() 2005, QNX Software Systems Ltd.


Safety


Signal handler No

Thread No

See also:PtFSAddFirst()


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

Synopsis:void PtFSAddFirst( PtWidget t *fs,

PtFileSelItem t *item,PtFileSelItem t *parent );

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

Theparent argument may also beNULL, in which case theitem isadded at the root level of the file selector before any existing items atthe root level. This is what happens when thePt 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 aNULL fs argument, as long asparentpoints to an item that isn’t attached to any file selector widget.


PtFSAddFirst() 2005, QNX Software Systems Ltd.

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


Safety


Signal handler No

Thread No

See also:PtFSAddAfter(), PtFSRootItem()


2005, QNX Software Systems Ltd. PtFSAllItems()Fill a buffer with pointers to all items

Synopsis:PtFileSelItem t **PtFSAllItems(

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

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

Returns:A pointer to the buffer.


Safety


Signal handler No

Thread No


PtFSAllocItem() 2005, QNX Software Systems Ltd.

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 aPtFileSelItem 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" asinfo.

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


2005, QNX Software Systems Ltd. PtFSAllocItem()

Returns:The allocated item pointer if successful, orNULL 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 returnPt ENDfrom thePt 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);

}


PtFSAllocItem() 2005, QNX Software Systems Ltd.


Safety


Signal handler No

Thread No


2005, QNX Software Systems Ltd. PtFSClearSelection()Clear the selection

Synopsis:void PtFSClearSelection( PtWidget t *widget );

Description:This function clears the selection.


Safety


Signal handler No

Thread No


PtFSDamageItem() 2005, QNX Software Systems Ltd.

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


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

Synopsis:void PtFSExpandParents( PtWidget t *fs,

PtFileSelItem t *item,PhEvent t *event );

Description:This function tries to expand any collapsed ancestors of the givenitem. Theevent is passed toPtFSFolderExpand().


Safety


Signal handler No

Thread No

See also:PhEvent t in the PhotonLibrary Reference


PtFSFolderCollapse() 2005, QNX Software Systems Ltd.

Collapse an expandable item (directory)

Synopsis:void PtFSFolderCollapse( PtWidget t *fs,


Description:This function collapses the givenitem. The item must be expandable,i.e. a directory item. Thefs argument must point to the file selectorthat contains the item or beNULL if the item doesn’t belong to anyfile selector.

If fs isn’t NULL, its Pt CB FS STATE callback is invoked. Theeventargument is passed to the callback.


Safety


Signal handler No

Thread No



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

Synopsis:int PtFSFolderExpand( PtWidget t *fs,


Description:This function expands the givenitem. Thefs argument must point tothe file selector that contains the item or beNULL if the item doesn’tbelong to any file selector.

If fs isn’t NULL, its Pt CB FS STATE callback is invoked. Theeventargument 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



PtFSFreeAllItems() 2005, QNX Software Systems Ltd.

Unlink and free all items

Synopsis:void PtFSFreeAllItems( PtWidget t const *fs );

Description:This function unlinks and frees all items in thePtFileSel widget.Note that this function is called automatically when aPtFileSel

widget is destroyed.


Safety


Signal handler No

Thread No


2005, QNX Software Systems Ltd. PtFSFreeItems()Free an unlinked item

Synopsis:void PtFSFreeItems( PtFileSelItem t *item );

Description:This function frees the subtreeitem (the item together with itsbrothers and their children). The function assumes that the itemsdon’t belong to any file selector — usePtFSRemoveChildren(),PtFSRemoveItem(), or PtFSRemoveList() to remove the subtree itemsfrom a file selector widget before freeing the subtree.


Safety


Signal handler No

Thread No


PtFSGetCurrent() 2005, QNX Software Systems Ltd.

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 ofPtGenList).


Safety


Signal handler No

Thread No


2005, QNX Software Systems Ltd. PtFSGetSelIndexes()Fill a buffer with indexes

Synopsis:unsigned short *PtFSGetSelIndexes(

PtWidget t *widget,unsigned short *buffer );

Description:This function fills a buffer with indexes of all the selected items in thePtFileSel widget. The first item in the widget has an index of 1, not0.

If buffer is NULL, the function allocates a buffer usingmalloc(), 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


PtFSGoto() 2005, QNX Software Systems Ltd.

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 ofPtGenList).

If item is NULL, there will be no current item.


Safety


Signal handler No

Thread No


2005, QNX Software Systems Ltd. PtFSItemIndex()Calculate the index of the given item within the file selector

Synopsis:int PtFSItemIndex( PtFileSelWidget t const *fs,

PtFileSelItem t const *item );

Description:This function calculates the index of the givenitem within thefs. Theindex of the first item is 1.

Returns:The index of the given item.


Safety


Signal handler No

Thread No


PtFSRemoveChildren() 2005, QNX Software Systems Ltd.

Unlink the children of the specified item

Synopsis:PtFileSelItem t *PtFSRemoveChildren(


Description:This function unlinks all the children of the specifieditem 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. CallPtFSFolderCollapse() beforePtFSRemoveItem() to make sure that the item is collapsed.

Returns:A pointer to the first child removed.


2005, QNX Software Systems Ltd. PtFSRemoveChildren()


Safety


Signal handler No

Thread No


PtFSRemoveItem() 2005, QNX Software Systems Ltd.

Unlink an item

Synopsis:void PtFSRemoveItem( PtWidget t *fs,


Description:This function unlinks the givenitem together with its children from itsparent and brothers (if any) and sets theitem->parent anditem->brother fields toNULL.

B

C

C

B

itemtree

item

tree

A A

The results of using PtFSRemoveItem().

Thefs argument must point to thePtFileSel widget containing theitem, or beNULL 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 andfs are bothNULL.

PtFSRemoveItem() never clears thePt TREE ITEM EXPANDABLEflag in the item’s parent.

☞


2005, QNX Software Systems Ltd. PtFSRemoveItem()


Safety


Signal handler No

Thread No


PtFSRemoveList() 2005, QNX Software Systems Ltd.

Unlink the root item

Synopsis:void PtFSRemoveList( PtWidget t *fs,

PtFileSelItem t *first );

Description:This function unlinks the itemfirst and its brothers (together withtheir children) from their parent (and previous brother) and sets theirparent fields toNULL.

B

C

C

B

firsttree

first

tree

A A

The results of using PtFSRemoveList().

Thefs argument must point to thePtFileSel widget that containsthe items, or beNULL if the items don’t belong to any file selector.

If fs is NULL andfirst 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.

☞



2005, QNX Software Systems Ltd. PtFSRemoveList()

Safety


Signal handler No

Thread No


PtFSRootItem() 2005, QNX Software Systems Ltd.

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


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

Synopsis:void PtFSSelect( PtWidget t *widget,


Description:This function selects the givenitem.


Safety


Signal handler No

Thread No


PtFSSelectedItems() 2005, QNX Software Systems Ltd.

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 usingmalloc(),and the buffer isNULL-terminated.

� If buffer is non-NULL, the function adds aNULL at the end only ifthere are no selected items in the widget.



Safety


Signal handler No

Thread No


2005, QNX Software Systems Ltd. PtFSSetSelIndexes()Set the selection indexes

Synopsis:int PtFSSetSelIndexes( PtWidget t *widget,

const unsigned short *buffer,int count );

Description:This function sets the selection indexes. The function assumes 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 thancount if the array isn’t sorted orcontains duplicate indexes or indexes that are out of range.

If the selection mode isPt RANGE MODE, only the first index and thecount are used.

☞

Returns:The number of items selected.


Safety


Signal handler No

Thread No


PtFSShow() 2005, QNX Software Systems Ltd.

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 givenitem is visible.If item is NULL, the function does nothing. This lets you dosomething like this:

PtFSShow( widget, PtFSGetCurrent(widget) );

without checking to see ifPtFSGetCurrent() returnedNULL.


Safety


Signal handler No

Thread No


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

Synopsis:void PtFSUnselect( PtWidget t *widget,


Description:This function unselects the givenitem.

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


Safety


Signal handler No

Thread No


PtFSUnselectNonBrothers() 2005, QNX Software Systems Ltd.

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 ofPtGenList) is used.


Safety


Signal handler No

Thread No


2005, QNX Software Systems Ltd. PtFlashA 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.

PtFlash is provided for evaluation only.☞

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.


PtFlash 2005, QNX Software Systems Ltd.




















Pt ARG DIM PtWidget


continued. . .


2005, QNX Software Systems Ltd. PtFlash





Pt ARG FLAGS PtWidget Pt GETS FOCUS













Pt ARG POS PtWidget







continued. . .


PtFlash 2005, QNX Software Systems Ltd.




Pt CB ARM PtBasic






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






2005, QNX Software Systems Ltd. PtFontSelA widget for selecting font attributes

Class hierarchy:PtWidget → PtBasic → PtContainer → PtFontSel

PhAB icon:

Public header:<photon/PtFontSel.h>

Description:ThePtFontSel widget lets you select font attributes.

A PtFontSel widget.

A PtFontSel widget lets you select the:

� font family

� style (italic, bold, underline, double underline, and case)

� font size


PtFontSel 2005, QNX Software Systems Ltd.

� text and background color

ThePtFontSel 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


2005, QNX Software Systems Ltd. PtFontSel

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 PhotonLibrary Reference). You can ORthese flags together:

� Pt FONTSELSCALABLE — Include scalable fonts.

� Pt FONTSELBITMAP — Include bitmap fonts.

� Pt FONTSELFIXED — Include fixed-width fonts.

� Pt FONTSELPROP— Include proportional-width fonts.

You can usePt FONTSEL ALL FONTSto 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 FONTSELSAMPLE — show a sample text string in the currentfont.

� Pt FONTSELAA 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 FONTSELCOLORSELBKGD — display a sample of thebackground color to be used for the text. If you click on thesample, you can change the color.



� Pt FONTSELCOLORSELTEXT — 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 toPk Cyrillic IO). You can use the valuePt FONTSEL ALL SYMBOLS to override this filtering.

Pt ARG FONT TEXT COLOR



The color of the text. SeePgColor t in the PhotonLibraryReference.

Pt ARG FONT TEXT BKGD COLOR



The background color of the text. SeePgColor 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 thePt CALLBACKS ACTIVE bit set in itsPt ARG FLAGS resource, these callbacks are also invoked when your



application changes the selected font by callingPtSetResource() orPtSetResources().


reason Pt CB FONT MODIFY


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













continued. . .





Pt ARG CONTAINER FLAGS PtContainer &=˜Pt GETSFOCUS








Pt ARG DIM PtWidget





Pt ARG FLAGS PtWidget 0









continued. . .










Pt ARG POS PtWidget










Pt CB ARM PtBasic






Pt CB DND PtWidget

continued. . .









Pt CB MENU PtBasic


Pt CB RAW PtWidget





Convenience functions:ThePtFontSel class defines the following convenience function:

PtFontSelection()

Display a modal dialog for selecting a font. See the PhotonLibrary Reference.


2005, 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:ThePtGauge 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 2005, 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 ofPtGauge may observe this bit, but the onlywidget that currently does isPtProgress.

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’sPt 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.


2005, 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 ofRed:

results inRed:35.

Pt ARG GAUGE VALUE SUFFIX


char * String NULL

Text appended to the value displayed. For example, a value of%

results in35%.



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 thePt GAUGE INTERACTIVE bit set in itsPt ARG GAUGE FLAGS).

If the widget has thePt CALLBACKS ACTIVE bit set in itsPt ARG FLAGS resource, these callbacks are also invoked when your



application changes the value by callingPtSetResource() 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 DRAGGEDsubtypes.



� 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 aPhEvent t structure that describes theevent that caused the callback to be invoked, orNULL ifthe callback was invoked because your applicationchanged the value andPt CALLBACKS ACTIVE is set.

cbdata A pointer to aPtGaugeCallback 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. . .







2005, 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:ThePtGenList class is a superclass for creating list widgets. It’sdiscussed in more detail inBuilding 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 (seePt ARG SELECTION MODE).

PtGenListItem t is the data structure used for the items.

A PtGenList widget can have one child, provided it’s aPtDividerwidget. 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 ofPtGenList, such asPtList andPtTree, use Tabcharacters as column separators.


PtGenList 2005, 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 REQUIREDbits in Pt ARG LIST FLAGS.

You can set or get a limited number of resources (mainly the colors)for the childPtScrollbar 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 thecurrent 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 pressEnter 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 ofPt 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 theCtrl 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.


2005, 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 ofPt 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. SeePgColor t in the PhotonLibraryReference.

Pt ARG BALLOON FILL COLOR


PgColor t Scalar Pg BALLOONCOLOR

The balloon’s fill color. SeePgColor t in the PhotonLibraryReference.

Pt ARG LIST COLUMN ATTR


PtListColumnAttributes t *, short Array NULL

An array ofPtListColumnAttributes 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 setPt 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 ofPtGenList 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 ofPtListColumn 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. SeePgColor t inthe PhotonLibrary 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, andEnd) 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 thePtDivider 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 whenPt 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 thePt LIST SNAPflag 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 ofPtArg t structures (see the PhotonLibrary Reference)that are passed to the list’s childPtScrollbar. 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




ThePtGenList 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 thePt ARG LIST SB RES resource, your application mustsupply a buffer and pass its address and length to thePtSetArg()macro. For example, this code for aPtScrollbar widget:

PtGetResources( scrollbar, N, args );

is equivalent to this when the scrollbar is part of aPtGenList:

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. SeePgColor 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 pressEnter.

Pt BROWSEMODE (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 andCtrl-click combinations toselect multiple items. To select all items between and includingtwo items in a list, click on the first item, press theShift key,then click on or drag to any other item in the list.

To select multiple disjoint items, hold down theCtrl 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.



ThePtGenList 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 pressingCtrl).



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 SELECTIONMODE 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 BROWSEMODE:

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 SELECTIONMODE NOFOCUS



Pt ARG SELECTION TEXT COLOR



The text color for selected items. SeePgColor 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 thePt 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 callingPtSetResource() 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 aPtScrollbarCallback 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.

Theaction 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 toPtSetResources()and the widget has thePt CALLBACKS ACTIVE bit set in itsPt ARG FLAGS resource.

Pt SCROLL JUMP

You jumped to a specific location byCtrl-clicking on thescrollbar.








continued. . .


















Pt ARG DIM PtWidget





Pt ARG FLAGS PtWidget |= Pt HIGHLIGHTED|Pt ETCH HIGHLIGHT| Pt SET|Pt GETS FOCUS|Pt FOCUSRENDER

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 aPtGenList, thecbinfo->cbdata is apointer to aPtListDndCallback 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 ofPtGenList:



In general, the subclass specifies which of the convenience functionsyou can use. For example,PtList andPtTree don’t let you call anyof thePtGenList 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 thegflags 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 ofBuilding 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.


2005, 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 thePtGenList widget pointed to bylist.The arguments are:

items A pointer to a list ofPtGenListItem t structures linkedwith thenext field (theprev 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 widgetanditems is added after that item.

In all selection modes exceptPt SELECTION MODE RANGE, ifthere’s no current item in the widget and some of the added itemshave thePt LIST ITEM CURRENTflag set, thefirst 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, thefirst of the added items havingthePt LIST ITEM SELECTEDflag 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 SELECTEDflag are selected.

In Pt SELECTION MODE RANGE mode, the behavior depends onwhether there’s a selected range in the widget and how theafter 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() 2005, QNX Software Systems Ltd.

If no items are selected inPt SELECTION MODE RANGE mode but arange of added items has thePt LIST ITEM SELECTEDflag 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 CURRENTflag of the first selected item.


Safety


Signal handler No

Thread No

See also:PtGenList, PtGenListItem t


2005, 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 callingmalloc(),and the buffer isNULL-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 aNULL 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() 2005, QNX Software Systems Ltd.

Clear the selection

Synopsis:void PtGenListClearSelection( PtWidget t *widget );

Description:This function clears the selection of the givenPtGenList widget.


Safety


Signal handler No

Thread No

See also:PtGenList


2005, 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 aPtLabel widget to be used as a popupballoon for a list item. The arguments are as follows:

widget A pointer to thePtGenList widget.

parent A pointer to the widget’s parent window.

area A pointer to aPhArea 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 isNULL, use the samefont as thePtGenList widget.

Thestring 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, ifcolumn is 1andstring is "One\tTwo\tThree", the label contains the string"Two".


PtGenListCreateTextBalloon() 2005, QNX Software Systems Ltd.

Returns:A pointer to thePtLabel widget.


Safety


Signal handler No

Thread No

See also:PhArea t in the PhotonLibrary Reference


2005, 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, usePtGenListLockItem() andPtGenListUnlockItem() instead.

If you’re modifying more than one item, you should usePtGenListHold() andPtGenListRelease() to avoid multiple calls to theDraw method.

☞


Safety


Signal handler No

Thread No



PtGenListDrawBackground() 2005, 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 ofPtGenList for drawingthe background. If thePt GEN LIST SHOW DAMAGED bit is set inlist->gflags, the function draws only the background for damageditems.

The values of thelist, items, nitems, andwhere arguments should bethe same as those used to call the List Draw method. Thelmarg,rmarg, tmarg, andbmarg 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


2005, QNX Software Systems Ltd. PtGenListDrawBackground()


PhRect t in the PhotonLibrary Reference


PtGenListDrawString() 2005, 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 ofPtGenList for drawingstrings. Thelist andwhere arguments should be the same as thoseused to call the List Draw method. Thestring argument is the stringto display. Any Tab characters in the string are interpreted as columnseparators.

Thewhere argument is a pointer to aPhRect t structure (see thePhotonLibrary Reference) that defines the rectangle in which the textis positioned. Thex values for the rectangle should be the same asthose used in thewhere argument of the List Draw method. Theyvalues define the vertical position of the string to be drawn betweenthe given values.

Thelmarg andrmarg arguments define additional margins. The valueof lmarg is added to thefrom value of the first column, andrmarg issubtracted from theto 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;


2005, 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() 2005, 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



2005, 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 ofPtGenList).

Returns:A pointer to the current item.


Safety


Signal handler No

Thread No



PtGenListGetSelIndexes() 2005, 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 usingmalloc(), 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 endonly if there areno selected items.



Safety


Signal handler No

Thread No

See also:PtGenList


2005, 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 passitem asNULL, there isn’t a current item.


Safety


Signal handler No

Thread No



PtGenListHold() 2005, 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 thePtHold() function. After acall to PtGenListHold(), thePtGenListDamageItem() function simplysets thePt LIST ITEM DAMAGED flag in the item instead of callingPtDamageExtent().


Safety


Signal handler No

Thread No

See also:PtGenListRelease()

PtDamageExtent(), PtHold() in the PhotonLibrary Reference


2005, 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 aPtGenList widget.

Applications should view this as a read-only structure; subclassesusually define ways to modifyPtGenListItem 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 ofPtGenList).

Pt LIST ITEM DAMAGED

This item should be redrawn.Pt LIST ITEM ABOVE

This item is above the visible range of items.Use thePt ARG TOP ITEM POS resource toscroll the list.

Pt LIST ITEM BELOW

This item is below the visible range of items.Use thePt ARG TOP ITEM POS resource toscroll the list.

Pt LIST ITEM INWIDGET

The item has been added to a widget.


PtGenListItem t 2005, 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.

ThePt LIST ITEM USED FLAGS macro defines theflags used by thePtGenList 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 PhotonLibraryReference) 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.


2005, QNX Software Systems Ltd. PtGenListItem t


See also:PtGenList, PtGenTree, PtGenTreeItem t, PtList,PtTreeItem t

PhDim t in the PhotonLibrary Reference

Building Custom Widgets


PtGenListItemIndex() 2005, 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 givenitem within thelist.The index of the first item is 1.

Returns:The index of the given item.


Safety


Signal handler No

Thread No



2005, 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 thePtGenList widget itself. It may beused to reallocate memory if the item was allocated usingmalloc().

The givensize should include the size of thePtGenListItem t

structure. If the item is moved to a different address by therealloc()function,PtGenListItemRealloc() repairs the list links.

Returns:A pointer to the reallocated item.


Safety


Signal handler No

Thread No



PtGenListLastItem() 2005, 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



2005, QNX Software Systems Ltd. PtGenListLockItem()Lock an item so it can be resized

Synopsis:void PtGenListLockItem( PtWidget t *list,


Description:Use this function if thesize field of a list item must be changed. CallPtGenListLockItem() first to save the old size of the item, then modifythe item. Then, callPtGenListUnlockItem() 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 callPtGenListResize().

☞


Safety


Signal handler No

Thread No



PtGenListRelease() 2005, 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 ofPtRelease().

After a call toPtGenListHold(), PtGenListDamageItem() simply setsthePt LIST ITEM DAMAGED flag in the item instead of callingPtDamageExtent(). PtGenListRelease() looks for items that have theflag set and callsPtDamageExtent().


Safety


Signal handler No

Thread No

See also:PtGenListHold()

PtDamageExtent(), PtRelease() in the PhotonLibrary Reference


2005, 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 sublistlist from thePtGenListwidget. If first or last is NULL, the first or last item of the entire list isused. Both arguments may point to the same item, butlast must notprecedefirst in the list.

The function returns the first removed item (orNULL if the list wasempty). The function insertsNULL in thenext field of the lastremoved item and theprev field of the first removed item. Thisensures the returned value (if notNULL) always points to the firstitem of aNULL-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 isPt 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 ofPtGenList).

Returns:The first removed item, orNULL if the list was empty.


Safety


continued. . .


PtGenListRemoveItems() 2005, QNX Software Systems Ltd.

Safety

Signal handler No

Thread No



2005, 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() 2005, 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 toPt SELECTION MODE SINGLE orPt SELECTION MODE RANGE, this may involve selecting orunselecting other items.


Safety


Signal handler No

Thread No



2005, 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 usingmalloc(), andterminates the buffer with aNULL. It’s your application’sresponsibility to free the buffer when it’s no longer needed.

If buffer isn’t NULL, the function adds aNULL to the endonly if thereare no selected items.



Safety


Signal handler No

Thread No



PtGenListSetColumnBalloon() 2005, 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 thePhArea t structure pointed to byarea sothat it corresponds to the givencolumn 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 PhotonLibrary Reference


2005, 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 thegflags field of the widget. The bits definedby mask are set to the value defined byvalue.

Returns:The old value ofgflags.


Safety


Signal handler No

Thread No

See also:PtGenList


PtGenListSetSelIndexes() 2005, 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 thatbuffer 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 thancount 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. InPt SELECTION MODE SINGLE mode, only the firstindex is used; ifcount is greater than 1, it’s treated as 1.

☞

Returns:The number of items actually selected.


Safety


Signal handler No

Thread No


2005, QNX Software Systems Ltd. PtGenListSetSelIndexes()

See also:PtGenList


PtGenListShow() 2005, 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 sureitem->next isn’t NULL.


Safety


Signal handler No

Thread No



2005, QNX Software Systems Ltd. PtGenListUnlockItem()Unlock an item so it can be updated

Synopsis:void PtGenListUnlockItem( PtWidget t *list,


Description:Use this function if thesize field of a list item must be changed. First,call PtGenListLockItem() to save the old size of the item, and thenmodify the item. Then, callPtGenListUnlockItem() 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 callPtGenListResize().

☞


Safety


Signal handler No

Thread No



PtGenListUnselect() 2005, 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 thePt SELECTIONMODE RANGE selection mode.


Safety


Signal handler No

Thread No



2005, 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:ThePtGenTree 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 usePtHold() andPtUpdate() toavoid multiple redraws.

PtGenTreeItem t is the data structure used for the items.

For more information about this class, seeBuilding Custom Widgets.


PtGenTree 2005, 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.


2005, 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.

ThePtTree subclass defines some additional flags.☞

Pt ARG TREE LINE COLOR


PgColor t Scalar PgRGB( 239, 239, 239 )

The color of the lines. SeePgColor t in the PhotonLibraryReference.

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. SeePgColor t in the PhotonLibraryReference.

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 asevent->type). For more info, seethe types described forPhEvent t in the PhotonLibraryReference.


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

PtGenTreeItem t *item;

For mouse events, the item pointed toby the mouse orNULL 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 ofPtGenList) after theevent is normally processed by thewidget.

unsigned index;

The index of the item.PhPoint t pos;

The pointer position relative to theitem. SeePhPoint t in the PhotonLibrary Reference.

int consumed; Initially set toPt CONTINUE. Yourcallback function can suppress normalhandling of the event by setting thisfield to another value. In the case of keyevents, set it toPt END to consume theevent, or toPt 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 aPtGenTree, thecbinfo->cbdata is apointer to aPtTreeDndCallback 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 ofBuilding Custom Widget:

PtSuperClassGenTreeDrawItem()

Invoke the Tree Draw Item method of a given superclass.

PtSuperClassGenTreeItemState()

Invoke the Tree Item State method of a superclass.


2005, 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 thebrother field.PtGenTreeAddAfter() assumes thatitems points to a list of trees. Thetree variable points to aPtGenTree widget. The new items are addedto the specifiedtree below the specifiedbrother.

This function may be called with aNULL tree argument, as long asbrother points to an item that isn’t attached to any tree widget.

Returns:0 Success.

-1 Theitem is already in a widget.


Safety


Signal handler No

Thread No

See also:PtGenTree, PtGenTreeItem t


PtGenTreeAddFirst() 2005, 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 ofPtGenTreeItem t structures pointedto by item to the givenPtGenTree widget. The list of items arelinked with theirbrother fields. Theitem argument can beNULL.

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

Thetree argument can beNULL, provided thatparent points to anitem that isn’t attached to any tree widget.

PtGenTreeAddFirst() sets thePt TREE ITEM EXPANDABLE flag intheparent item, whether or not theitem argument isNULL.

Returns:0 Success.



Safety


Signal handler No

Thread No


2005, QNX Software Systems Ltd. PtGenTreeAddFirst()



PtGenTreeAllItems() 2005, 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 usingmalloc() and thebuffer isNULL-terminated. Ifbuffer isn’t NULL, the function doesn’tadd aNULL at the end.



Safety


Signal handler No

Thread No



2005, QNX Software Systems Ltd. PtGenTreeClearSelection()Clear the selection

Synopsis:void PtGenTreeClearSelection( PtWidget t *widget );

Description:This function clears the selection in the givenPtGenTree widget.


Safety


Signal handler No

Thread No

See also:PtGenTree


PtGenTreeCollapse() 2005, 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 subtreeitem. Thetree argumentmust point to the tree that contains theitem or can beNULL 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




2005, 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 givenitem when its data has changed.


Safety


Signal handler No

Thread No

See also:PtGenTree


PtGenTreeExpand() 2005, QNX Software Systems Ltd.

Expand a given subtree

Synopsis:int PtGenTreeExpand( PtWidget t *tree,


Description:This function expands the given subtreeitem. Thetree argument mustpoint to the tree that contains theitem or can beNULL 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


2005, QNX Software Systems Ltd. PtGenTreeExpand()




PtGenTreeExpandParents() 2005, QNX Software Systems Ltd.

Expand any collapsed ancestors of a given item

Synopsis:int PtGenTreeExpandParents( PtWidget t *tree,


Description:If any ancestors of the givenitem are collapsed, this function attemptsto expand them.



Safety


Signal handler No

Thread No




2005, 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 thePtGenTree widgetis being deleted, because the widget doesn’t assume that its itemshave been allocated.

☞


Safety


Signal handler No

Thread No

See also:PtGenTree


PtGenTreeFreeItems() 2005, QNX Software Systems Ltd.

Free the items in a subtree

Synopsis:int PtGenTreeFreeItems( PtGenTreeItem t *item );

Description:This function frees the subtreeitem, 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 Theitem is still in a widget.


Safety


Signal handler No

Thread No



2005, 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 ofPtGenList).

Returns:A pointer to the current item.


Safety


Signal handler No

Thread No



PtGenTreeGetSelIndexes() 2005, 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 usingmalloc(), andterminates the buffer with a zero.

If buffer isn’t NULL, the function adds a 0 to the endonly if there areno selected items.

Returns:A pointer to the buffer containing the indexes.


Safety


Signal handler No

Thread No

See also:PtGenTree


2005, 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 callPtGenTreeGoto() with an item whose ancestor iscollapsed, in which case the ancestor is expanded.



Safety


Signal handler No

Thread No



PtGenTreeItem t 2005, 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 aPtGenTree widget.

Applications should view this as a read-only structure; subclassesusually define ways to modifyPtGenTreeItem 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, seePtGenListItem t.

ThePtGenTree 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 BUTTONSin 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).


2005, 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 PhotonLibrary 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 initem->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 thedim field, a gap of at least one pixel is displayedbetween the current item (see “Current item” in the


PtGenTreeItem t 2005, QNX Software Systems Ltd.

description ofPtGenList) and any other item directlybelow.


See also:PtGenList, PtGenListItem t, PtGenTree, PtTreeItem t

PhDim t in the PhotonLibrary Reference

Building Custom Widgets


2005, 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 givenitem within thetree.The index of the first item is 1.

Returns:The index of the item.


Safety


Signal handler No

Thread No

See also:PtGenTree


PtGenTreeItemRealloc() 2005, 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 iftherealloc() function moves the item to a different address. Thetreeargument must point to the tree that contains the item or beNULL ifthe item doesn’t belong to any tree.

Returns:A pointer to the reallocated item.


Safety


Signal handler No

Thread No



2005, 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, usePtGenTreeResize() instead.☞


Safety


Signal handler No

Thread No



PtGenTreeRemoveChildren() 2005, 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 givenitem 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. CallPtGenTreeCollapse() beforePtGenTreeRemoveItem() to make sure the item is collapsed.

Returns:A pointer to the first unlinked child.


Safety


Signal handler No

Thread No



2005, 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 givenitem (together with its children) fromits parent and brothers (if any) and setsitem->parent anditem->brother to NULL. Thetree argument must point to thePtGenTree widget containingitem or can beNULL if item doesn’tbelong to any tree.

If tree is NULL anditem 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 andtree areNULL.

PtGenTreeRemoveItem() never clears thePt TREE ITEM EXPANDABLE flag in theitem’s parent.


Safety


Signal handler No

Thread No



PtGenTreeRemoveList() 2005, 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 itemfirst and its siblings (together with theirchildren) from their parent (and previous sibling) and sets theirparentfields toNULL. Thetree argument must point to the widget thatcontains the items or can beNULL if the items don’t belong to anytree.

If tree is NULL andfirst 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



2005, 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 thesize field of a number of tree items; modifyitem->dimdirectly in all items, then callPtGenTreeResize() once.


Safety


Signal handler No

Thread No

See also:PtGenTree


PtGenTreeRootItem() 2005, 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



2005, QNX Software Systems Ltd. PtGenTreeSelect()Select a given item

Synopsis:void PtGenTreeSelect( PtWidget t *widget,


Description:This function selects the givenitem. As with otherPtGenTree*()functions, thetree argument can be set toNULL if item doesn’t belongto a widget.

If tree isn’t NULL and none ofitem’s ancestors is collapsed,PtGenListSelect() is called. Iftree is NULL or some of the ancestorsof the item are collapsed,PtGenTreeSelect() simply sets thePt LIST ITEM SELECTEDflag in the item.


Safety


Signal handler No

Thread No



PtGenTreeSelectedItems() 2005, 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. Ifbuffer is NULL, the function allocates a buffer usingmalloc(), and the buffer isNULL-terminated.

If buffer isn’t NULL, the function adds aNULL to the endonly if thereare no selected items.



Safety


Signal handler No

Thread No



2005, 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 thatbuffer 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 thancount if the array isn’t sorted orcontains duplicate or out-of-range indexes.

When the selection mode isPt SELECTIONMODE RANGE, only thefirst index and the count are used.

Returns:The number of items actually selected.


Safety


Signal handler No

Thread No


PtGenTreeSetSelIndexes() 2005, QNX Software Systems Ltd.

See also:PtGenTree


2005, 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 whetherPtGenTreeGetCurrent() returned aNULLvalue.

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



2005, 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 supportPt SELECTION MODE RANGEselection mode.

☞


Safety


Signal handler No

Thread No



PtGenTreeUnselectNonBrothers() 2005, 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 ofPtGenList).


Safety


Signal handler No

Thread No



2005, 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:ThePtGraphic 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 ofPtGraphic.


PtGraphic 2005, QNX Software Systems Ltd.

Don’t call thePg... 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 aPtRaw widget. For more information, see the Raw Drawingand Animation chapter of the PhotonProgrammer’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 ofPhPoint t

structures (see the PhotonLibrary Reference). Each coordinatespecifies a vertex or control point of the primitive. Here’s a codefragment to illustrate:


2005, 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 aPhPoint 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 thePtGraphic widget class:

Pt ARG LINE WIDTH

The curve’s width, in pixels.

Pt ARG LINE CAP

Thecap style for capping off the curve’s start and end points.

Pt ARG LINE JOIN

Thejoin 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 byPtGraphic) 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.

Sizing the primitives

If you know the overall dimensions of the drawing, you may want toexplicitly set the dimensions of the graphics widgets as you createthem. 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 whenPt 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 isPt RESIZE ...AS REQUIREDfor 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 thePt ARG RESIZE FLAGS resource in thedescription ofPtWidget.

Grouping elements of the drawing

Occasionally you’ll want to group together a number of graphicalprimitives 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 unsignedshort

Scalar Pg BUTT CAP

Pt ARG LINE JOIN unsignedshort

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, seePgSetStrokeDash() in the PhotonLibraryReference.

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 box



described 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. SeePgColor t in the PhotonLibrary Reference.

Pt ARG FILL COLOR (inherited fromPtBasic) 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 fromPtBasic) 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 fromPtBasic) 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; seePgSetStrokeCap().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; seePgSetStrokeJoin().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 itsPt 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 aPhArea 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 callingPtGetResources().









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





PtGrid 2005, QNX Software Systems Ltd.

A grid pattern

Class hierarchy:PtWidget → PtBasic → PtGraphic → PtGrid

PhAB icon:

Public header:<photon/PtGrid.h>

Description:PtGrid draws a grid pattern viaPgDrawGrid() (see the PhotonLibrary Reference).

A PtGrid widget.

New resources:


Pt ARG GRID VERTICAL short Scalar 4

Pt ARG GRID HORIZONTAL short Scalar 4


2005, QNX Software Systems Ltd. PtGrid

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













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.

continued. . .


2005, QNX Software Systems Ltd. PtGrid


Pt ARG INSIDE TRANS PATTERN PtGraphic Not used by this class.















Pt ARG POS PtWidget








continued. . .




Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






2005, QNX Software Systems Ltd. PtGroupA 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:ThePtGroup 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 usePtGroup 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 aPtGroup widget. See“Aligning widgets using groups” in the Geometry Managementchapter of theProgrammer’s Guide.

New resources:


PtGroup 2005, QNX Software Systems Ltd.


Pt ARG CELL HORZ ALIGN unsigned short Scalar Pt GROUPHORZ LEFT

Pt ARG CELL VERT ALIGN unsigned short Scalar Pt GROUPVERT TOP

Pt ARG GROUP FLAGS unsigned long Flag 0

Pt ARG GROUP HORZ ALIGN unsigned short Scalar Pt GROUPHORZ CENTER

Pt ARG GROUP ORIENTATION unsigned short Scalar Pt GROUPHORIZONTAL

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 GROUPVERT CENTER

Pt ARG CELL HORZ ALIGN


unsigned short Scalar Pt GROUPHORZ LEFT

Determines how the children are aligned horizontally within the cells.Possible values:

� Pt GROUPHORZ LEFT

� Pt GROUPHORZ CENTER

� Pt GROUPHORZ RIGHT

Pt ARG CELL VERT ALIGN


unsigned short Scalar Pt GROUPVERT TOP


2005, QNX Software Systems Ltd. PtGroup

Determines how the children are aligned vertically within the cells.Possible values:

� Pt GROUPVERT TOP

� Pt GROUPVERT CENTER

� Pt GROUPVERT BOTTOM

Pt ARG GROUP FLAGS


unsigned long Flag 0

Possible values:

Pt GROUPEQUAL SIZE

Force all children to be the same height and width.

Pt GROUPEXCLUSIVE

Allow only one child to be set at a time.

Pt GROUPNO 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 GROUPNO KEYS

Prevent the group from using any keys (e.g. arrows).

Pt GROUPNO KEY WRAP HORIZONTAL

Don’t use keys that would cause horizontal wrap.

Pt GROUPNO KEY WRAP VERTICAL

Don’t use keys that would cause vertical wrap.

Pt GROUPNO KEY WRAP

Don’t use keys that would cause horizontal or vertical wrap.



Pt GROUPEQUAL SIZE HORIZONTAL

Make the children in the group the same width.

Pt GROUPEQUAL SIZE VERTICAL

Make the children in the group the same height.

Pt GROUPSTRETCHHORIZONTAL

Stretch the rightmost children in the group horizontally to fill itscanvas.

Pt GROUPSTRETCHVERTICAL

Stretch the bottommost children in the group vertically to fill itscanvas.

Pt GROUPSTRETCHFILL

Stretch the last widget(s) to fill the available space in thedirection indicated by the orientation.


Don’t set thePt GROUPEQUAL SIZE ... andPt GROUPSTRETCH...flags for the same direction — the group will expand every time itsextent is calculated.

☞

Pt ARG GROUP HORZ ALIGN


unsigned short Scalar Pt GROUPHORZ CENTER

How the children are aligned horizontally within the group. Thechildren retain their relative positions to each other. Possible values:

� Pt GROUPHORZ LEFT

� Pt GROUPHORZ CENTER

� Pt GROUPHORZ RIGHT



Pt ARG GROUP ORIENTATION


unsigned short Scalar Pt GROUPHORIZONTAL

The orientation of the group; one of:

Pt GROUPASIS

Don’t align children.

Pt GROUPHORIZONTAL

Align children in a row.

Pt GROUPVERTICAL

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; seePt 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 andPt 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 GROUPVERT CENTER

Determines how the children are aligned within the group. Thechildren retain their relative positions to each other. Possible values:

� Pt GROUPVERT TOP

� Pt GROUPVERT CENTER

� Pt GROUPVERT 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



continued. . .







2005, QNX Software Systems Ltd. PtImageAreaAn area for viewing an image

Class hierarchy:PtWidget → PtBasic → PtContainer → PtImageArea

PhAB icon:

Public header:<photon/PtImageArea.h>

Description:PtImageArea is an area in which you can display an image. You canselect an area, zoom in and out, and scroll if the image is too large tofit in the area. You can optionally display a grid when you’ve zoomedin past a specified amount.

New resources:


Pt ARG IMAGEAREA FLAGS short Flags 0

Pt ARG IMAGEAREA GRID COLOR PgColor t Scalar Pg BLACK

Pt ARG IMAGEAREA GRID THRESHOLD long Scalar 0

Pt ARG IMAGEAREA IMAGE PhImage t * Image NULL

Pt ARG IMAGEAREA LEFT short Scalar 0

Pt ARG IMAGEAREA SELECTION PhRect t Struct 0, 0, 0, 0

Pt ARG IMAGEAREA TOP short Scalar 0

Pt ARG IMAGEAREA ZOOM long Scalar 0

Pt CB IMAGEAREA DRAG PtCallback t * Link NULL

continued. . .


PtImageArea 2005, QNX Software Systems Ltd.


Pt CB IMAGEAREA MOVEMENT PtCallback t * Link NULL

Pt CB IMAGEAREA SCROLLED PtCallback t * Link NULL

Pt CB IMAGEAREA SELECTION PtCallback t * Link NULL

Pt ARG IMAGEAREA FLAGS


short Flags 0

Flags that control the behavior of the image area:

Pt IMAGEAREA AUTOSCALE

Automatically scale the image to fit the size of the widget.

Pt IMAGEAREA ENABLE SELECTION

Allow the user to select part of the image.

Pt IMAGEAREA EDITABLE SELECTION

Allow the user to modify a selection.

Pt ARG IMAGEAREA GRID COLOR



The color of the grid, if displayed. SeePgColor t in the PhotonLibrary Reference.

Pt ARG IMAGEAREA GRID THRESHOLD


2005, QNX Software Systems Ltd. PtImageArea


long Scalar 0

The grid threshold, expressed as a fixed-point 16.16 number. If thezooming factor (Pt ARG IMAGEAREA ZOOM) is greater than thisthreshold, the grid is displayed.

Pt ARG IMAGEAREA IMAGE



A pointer to aPhImage t structure (see the PhotonLibraryReference) that defines the image to be displayed in the image area.

Pt ARG IMAGEAREA LEFT


short Scalar 0

The coordinate, in image pixels, of the left side of the image viewport.This only applies when the image is larger than the widget.

Pt ARG IMAGEAREA SELECTION


PhRect t Struct 0, 0, 0, 0

A PhRect t structure (see the PhotonLibrary Reference) thatcontains the selected area of the image, in image coordinates (pixels).

Pt ARG IMAGEAREA TOP




short Scalar 0

The coordinate, in image pixels, of the top side of the image viewport.This only applies when the image is larger than the widget.

Pt ARG IMAGEAREA ZOOM


long Scalar 0

The zooming factor, expressed as a fixed-point 16.16 number.

Pt CB IMAGEAREA DRAG



A list of PtCallback t structures that define the callbacks invokedwhen the image area is dragged.


reason Pt CB IMAGEAREA DRAG

reason subtype

One of:

� Pt IMAGEAREA INIT

� Pt IMAGEAREA DRAG

� Pt IMAGEAREA COMPLETE




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

� PhRect t rect — aPhRect t structure (see thePhotonLibrary Reference) that defines the areadragged in image coordinates (pixels).


Pt CB IMAGEAREA MOVEMENT



A list of PtCallback t structures that define the callbacks that areinvoked when the mouse cursor is moved over the image area.


reason Pt CB IMAGEAREA MOVEMENT

reason subtype

0 (not used).



� PhRect t rect — aPhRect t structure (see thePhotonLibrary Reference) that defines the area themouse moved over in image coordinates (pixels).




Pt CB IMAGEAREA SCROLLED



A list of PtCallback t structures that define the callbacks that areinvoked when the image area is scrolled.


reason Pt CB IMAGEAREA SCROLLED

reason subtype

The direction in which the image area scrolled:

� Pt IMAGEAREA SCROLLED X

� Pt IMAGEAREA SCROLLED Y



� PhRect t rect — aPhRect t structure (see thePhotonLibrary Reference) that defines the newviewport area of the image.


Pt CB IMAGEAREA SELECTION





A list of PtCallback t structures that define the callbacks invokedwhen the image area is selected.


reason Pt CB IMAGEAREA SELECTION

reason subtype

One of:

� Pt IMAGEAREA INIT

� Pt IMAGEAREA DRAG

� Pt IMAGEAREA COMPLETE



� PhRect t rect — aPhRect t structure (see thePhotonLibrary Reference) that defines the areaselected.





continued. . .




















Pt ARG DIM PtWidget







continued. . .













Pt ARG LAYOUT TYPE PtContainer









Pt ARG POS PtWidget




Pt ARG SCROLLBAR X DISPLAY PtScrollArea

continued. . .




Pt ARG SCROLLBAR X HEIGHT PtScrollArea

Pt ARG SCROLLBAR Y DISPLAY PtScrollArea

Pt ARG SCROLLBAR Y WIDTH PtScrollArea




Pt ARG TEXT STRING PtLabel InsufficientMemory






Pt CB ARM PtBasic




Pt CB CHILD GETTING FOCUS PtContainer

Pt CB CHILD LOSING FOCUS PtContainer



Pt CB DND PtWidget



continued. . .






Pt CB LAYOUT PtContainer


Pt CB MENU PtBasic


Pt CB RAW PtWidget






PtLabel 2005, QNX Software Systems Ltd.

A text, bitmap, or image label

Class hierarchy:PtWidget → PtBasic → PtLabel


� PtButton

� PtMenuLabel — seePtMenuButton

� PtTab

� PtText

PhAB icon:

Public header:<photon/PtLabel.h>

Description:ThePtLabel 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.


2005, QNX Software Systems Ltd. PtLabel

Creating labels

The default label type is a null-terminated text string. To specify thetype of label, use thePt 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, setPt 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 thePt ARG TEXT STRING resource.

To specify the font for the text, setPt ARG TEXT FONT.

The label widget defines its own margins in addition to the marginwidth defined by thePtBasic widget class. There are separate left,right, top, and bottom margins, which you can specify using:

� Pt ARG MARGIN LEFT



� Pt ARG MARGIN RIGHT

� Pt ARG MARGIN TOP

� Pt ARG MARGIN BOTTOM

These margins are cumulative, so that the actual margin of one 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.ThePt 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 settingPt 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. ThePt 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 theascender 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 typePhImage t, which is described in thePhotonLibrary 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 thePtLabel 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 thePt SHOW BALLOON bit in thePt ARG LABEL FLAGSresource.

2 Set thePt ARG BALLOON POSITION resource to define thelocation.

ThePt ARG BALLOON TEXT resource defines the text displayed inthe balloon. If this resource is not set, thePt 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 SELECTSHIFT

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. SeePgColor t in the PhotonLibraryReference.

Pt ARG BALLOON FILL COLOR


PgColor t Scalar Pt BALLOONCOLOR

The balloon’s fill color. SeePgColor t in the PhotonLibraryReference.

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 asPt 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 aPhImage t structure (see the PhotonLibraryReference) that defines the image to be used if the label type (seePt ARG LABEL TYPE, below) isPt 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 UsePt ARG TEXT STRING to display the text.

Pt IMAGE UsePt 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; seePgSetFont().

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 ifPt ARG LABEL TYPE isPt Z STRINGor Pt TEXT IMAGE, as well as the text to display in theballoon ifPt 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


continued. . .






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget





2005, QNX Software Systems Ltd. PtLineA line

Class hierarchy:PtWidget → PtBasic → PtGraphic → PtLine

PhAB icon:

Public header:<photon/PtLine.h>

Description:You can usePtLine 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, seePtGraphic.


PtLine 2005, QNX Software Systems Ltd.





















Pt ARG DIM PtWidget

continued. . .


2005, QNX Software Systems Ltd. PtLine

























continued. . .


PtLine 2005, QNX Software Systems Ltd.





Pt ARG POS PtWidget







Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget

continued. . .


2005, QNX Software Systems Ltd. PtLine







PtList 2005, QNX Software Systems Ltd.

A scrolling list of text items

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

PhAB icon:

Public header:<photon/PtList.h>

Description:ThePtList 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 byPtGenList).

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 theinheritedPt ARG LIST FLAGS resource to control when the scrollbarappears: always, never, or as required.


2005, QNX Software Systems Ltd. PtList

Limitations

PtList widgets have a few limitations:

� They display only text. If you want to display an image for eachitem, use aPtRawList 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 aPtDivider widget as a child of thePtList. 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 inheritedPt 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 thePt 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.



The default selection policy isbrowse 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 thePt CB SELECTION callback to notify yourapplication whenever you make a new selection. Thecbdata passed tothe callback always contains a pointer to aPtListCallback t

structure. The selection policy in effect for the widget at the time ofthe callback determines which members of the structure are valid.



Themode member of the callback data structure indicates theselection mode that caused the callback to be invoked.

Handling single selections

Single selection and browse selection modes let you select only asingle 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 thePt ARG ITEMS resource.

Handling multiple selections

Multiple selection modes, including extended selection, let you selectseveral 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 thePt ARG ITEMS resource.

New resources:




Pt ARG ITEMS char **, short Array NULL

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 thePtList widget.

parent A pointer to its parent window.

area A pointer to aPhArea t structure (see the PhotonLibraryReference) 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 ofitem.

font The widget’sPt 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 passedaPtCallbackInfo t structure that contains at least the followingmembers:

reason Pt CB LIST INPUT

reason subtype

The event type (same asevent->type). For more info, seethe event types described for thePhEvent t structure inthe PhotonLibrary Reference.


cbdata A pointer to aPtListInput 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 PhotonLibraryReference.

char * item; For mouse events, the item under thecursor. For key events, the item that willbe the current item (see “Current item”in the description ofPtGenList) afterthe 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 toPt CONTINUE. Yourcallback function can suppress normalhandling of the event by setting thisfield to another value. In the case of keyevents, set it toPt END to consume theevent, or toPt 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 aPtCallbackInfo 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 theEnter is pressed(selection is accepted).

� Pt LIST SELECTION CANCEL when the mouse buttonis released outside the widget (previous state restored).

� Pt LIST SELECTION BROWSEwhen 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 aPtListCallback 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 thesel items listand thesel array list.



Theitem member of thePtListCallback 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 — checksel 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 fromPtGenList, it’s used in adifferent way. ForPtGenList, 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 aPtList, thecbinfo->cbdata is apointer to aPtListDndCallback 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:ThePtList 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.


PtListAddItems() 2005, QNX Software Systems Ltd.

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. Theitems 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 aPtList widget.


Safety


Signal handler No

Thread No


2005, QNX Software Systems Ltd. PtListAddItems()

See also:PtList


PtListDeleteAllItems() 2005, QNX Software Systems Ltd.

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 aPtList widget.


Safety


Signal handler No

Thread No

See also:PtList, PtListDeleteItems(), PtListDeleteItemPos(),PtListRemovePositions()


2005, QNX Software Systems Ltd. PtListDeleteItemPos()Delete a range of items from a list

Synopsis:int PtListDeleteItemPos( PtWidget t *widget,

int item count,int position );

Description:This function deletesitem 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()


PtListDeleteItems() 2005, QNX Software Systems Ltd.

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 theitems 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()


2005, QNX Software Systems Ltd. PtListGotoPos()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. Ifpos is 0, there will beno current item.


Safety


Signal handler No

Thread No

See also:PtList, PtListShowPos()


PtListItemExists() 2005, QNX Software Systems Ltd.

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()


2005, QNX Software Systems Ltd. PtListItemPos()Determine the position of an item in a list

Synopsis:int PtListItemPos( PtWidget t *widget,

const char *item );

Description:This function performs a linear search on the list for the specifieditem.

Returns:The position of the item, or 0 if it wasn’t found.


Safety


Signal handler No

Thread No

See also:PtList, PtListItemExists()


PtListRemovePositions() 2005, QNX Software Systems Ltd.

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 thepos listarray.

Returns:0 Success.



Safety


Signal handler No

Thread No

See also:PtList, PtListDeleteAllItems(), PtListDeleteItemPos(),PtListDeleteItems()


2005, QNX Software Systems Ltd. PtListReplaceItemPos()Replace items in a list at a specific position

Synopsis:int PtListReplaceItemPos( PtWidget t *widget,

const char **new items,int item count,int position );

Description:This function replacesitem count items in the list withnew items.Theposition 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 aPtList widget.


Safety


Signal handler No

Thread No

See also:PtList, PtListReplaceItems()


PtListReplaceItems() 2005, QNX Software Systems Ltd.

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 inold items. Everyoccurrence of each item found is replaced with the correspondingnew item. This operation continues untilitem count is reached.

Returns:0 Success.

-1 A memory allocation error occurred, or the specified widget isnot aPtList widget.


Safety


Signal handler No

Thread No

See also:PtList, PtListReplaceItemPos()


2005, QNX Software Systems Ltd. PtListSelectPos()Select the item at a given position

Synopsis:void PtListSelectPos( PtWidget t *widget,

int pos );

Description:This function selects the item at the given position. The first item inthe widget has a position of 1, not 0.


Safety


Signal handler No

Thread No

See also:PtList, PtListUnselectPos()


PtListShowPos() 2005, QNX Software Systems Ltd.

Show the item at the given position

Synopsis:void PtListShowPos( PtWidget t *widget,

int pos );

Description:This function scrolls the list pointed to bywidget to make the itemwith the position given bypos 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()


2005, QNX Software Systems Ltd. PtListUnselectPos()Unselect the item at the given position

Synopsis:void PtListUnselectPos( PtWidget t *widget,

int pos );

Description:This function unselects the item at the given position. The first item inthe widget has a position of 1, not 0.

PtListUnselectPos() has no effect if thePt ARG SELECTION MODEresource is set toPt SELECTION MODE RANGE.


Safety


Signal handler No

Thread No

See also:PtList, PtListSelectPos()


PtMenu 2005, QNX Software Systems Ltd.

A popdown or pullup menu

Class hierarchy:PtWidget → PtBasic → PtContainer → PtGroup → PtMenu

PhAB icon:None — use PhAB’s Menu module.

Public header:<photon/PtMenu.h>

Description:Menus display a list of possible selections (calleditems) and let youchoose one of them. ThePtMenu class provides popup and pulldownmenus that work in either press-drag-release or click-move-clickmode.

A PtMenu widget that contains various menu items.


2005, QNX Software Systems Ltd. PtMenu

You can use PhAB’s Menu module instead of this widget, whichmakes it easier to add menus to your project. See “Menu modules” inthe Working with Modules chapter of the PhotonProgrammer’sGuide.

☞

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 ofPtMenuButton widgets,you can use any type of widget as a menu item by making it the childof aPtMenu widget.

If PtMenu has anyPtLabel-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 thePt SELECTABLEbit in its Pt ARG FLAGS(seePtWidget). 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 aPtMenu widget as a child, and that child has thePt MENU CHILD bit set in itsPt ARG MENU FLAGS resource, thechild behaves as a submenu and is realized when necessary.

Most applications have amenu 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.



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 buttonwithout 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 usePtMenu to create either a pulldown or a popup menu.

ThePt 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 setPt 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 usePt 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.

Populating the menu

As with other containers, items are placed in a menu by creating themas children of the menu itself. The widgets that you place in the menubehave according to their type. You can use any widgets that have thePt SELECTABLEflag set in theirPt 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 thePt AUTOHIGHLIGHT flag set automaticallyhave the visual cuing provided for you. All the widgets in the Photonwidget library that set thePt SELECTABLEflag 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.

Sizing

Normally, the menu is wide enough to hold the widest menu item; allthe menu items are made this size as well. ThePt MENU AUTO bit inthePt 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.



Lifetime

A menu may be created either in advance or dynamically in responseto 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 atransient menu bysetting thePt 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 thePt CB ARM or Pt CB MENU callback list(seePtBasic) so that both press-drag-release and click-stay modeswork, then provide the pointer to the menu widget as theclient datafor the callback.

Your callback must position the menu beneath the menu button andmake it appear. To do this, callPtPositionMenu() with the menu



widget as the first parameter, and aNULL 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 callingPtRealizeWidget(). For more informationabout these functions, see the PhotonLibrary 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, thecreate 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 isnot 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 aPt CB ARM or Pt CB MENU callback list, the simplest wayto activate the menu is to associate an event handler with button-pressevents. Provide the menu pointer to the event handler asclient 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 thePt 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 thePtMenuButton widget’sPt ARG BUTTON TYPE resource.

Here’s thecreate 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 aPtRaw 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);


}

int

nop cb(PtWidget t *w, void *client data,


PtArg t arg[1];char *text;

w = w; client data = client data; info = info;

PtSetArg(&arg[0], Pt ARG TEXT STRING, &text, 0);

PtGetResources(w, 1, arg);

if (text)

printf("Pushed the %s button\n", text);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 );

return (Pt CONTINUE);

}

void create import items(PtWidget t *parent)

{PtArg t arg[3];

PtCallback t noop[] = { {nop cb, NULL} };

PtSetArg(&arg[0], Pt ARG TEXT STRING, "Image", 0);

PtSetArg(&arg[1], Pt ARG TEXT FONT, 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);

PtCreateWidget(PtButton, parent, 3, arg);

PtSetArg(&arg[0], Pt ARG TEXT STRING, "New", 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[2], Pt CB ACTIVATE, quit callbacks, 1);PtCreateWidget(PtButton, parent, 3, arg);

}

void create help items(PtWidget t *parent)

{PtArg t arg[3];


PtSetArg(&arg[0], Pt ARG TEXT STRING, "About", 0);


PtSetArg(&arg[2], Pt CB ACTIVATE, noop, 1);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");PtExit(EXIT FAILURE);

}

PtSetArg(&arg[0], Pt ARG ANCHOR FLAGS,

Pt LEFT ANCHORED LEFT|Pt RIGHT ANCHORED RIGHT,

Pt IS ANCHORED);PtSetArg(&arg[1], Pt ARG 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);


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 INPUT GROUP short Scalar 0

Pt ARG MENU ITEM FILL COLOR PgColor t Scalar 0xCCCCCC

Pt ARG MENU ITEM HIGHLIGHT COLOR PgColor t Scalar 0xA6B1CE

Pt ARG MENU SPACING short Scalar ValueofPt ARG BEVEL WIDTH

Pt ARG MENU TEXT FONT char * String NULL

Pt ARG MENU TITLE char * String NULL

Pt ARG MENU TITLE FONT char * String "MenuFont09"

Pt ARG SUBMENU PARENT HIGHLIGHT COLOR PgColor t Scalar 0xB0B0B0

Pt ARG MENU FLAGS




unsigned long Flag Pt MENU AUTO |Pt MENU TEXT ALIGN

Flags that control the menu’s appearance and behavior. You can 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 INPUT GROUP


short Scalar 0

The input group for the menu. When this resource is set to a non-zerovalue, the menu uses that input group’s rectangle to position itself on



the screen. A mouse-click outside of the menu in any other inputgroup does not dismiss the menu.

If this resource is0, and you have more than one input group, themenu picks a random group to position itself. Mouse-clicks from anyinput group will dismiss the menu.

☞

Pt ARG MENU ITEM FILL COLOR


PgColor t Scalar 0xCCCCCC

Menu items normally inherit their fill color from the menu, whichinherits its color from the parent widget. If you set this resource, thiscolor is used as the fill color for all menu items, except the itemswhich have a non-transparent fill color.

Pt ARG MENU ITEM HIGHLIGHT COLOR


PgColor t Scalar 0xA6B1CE

The highlight fill color for menu items.

Pt ARG MENU SPACING


short Scalar Value ofPt ARG BEVEL WIDTH

The amount of space, in pixels, between each menu item. The defaultis the value of thePt ARG BEVEL WIDTH resource defined byPtWidget.



Pt ARG MENU TEXT FONT


char * String NULL

The font used forPtLabel-based menu items; seePgSetFont() in thePhotonLibrary 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 toNULL.

Pt ARG MENU TITLE FONT


char * String "MenuFont09"

The font used for displaying the title.

Pt ARG SUBMENU PARENT HIGHLIGHT COLOR


PgColor t Scalar 0xB0B0B0

The highlight fill color for a menu item when an item in its submenuis selected.





Pt ARG ANCHOR FLAGS PtWidget Not used by this class.

Pt ARG ANCHOR OFFSETS PtWidget Not used by this class.



Pt ARG BASIC FLAGS PtBasic SetsPt TOP OUTLINE |Pt BOTTOM OUTLINE |Pt LEFT OUTLINE |Pt RIGHT OUTLINE |Pt TOP BEVEL |Pt BOTTOM BEVEL |Pt LEFT BEVEL |Pt RIGHT BEVEL |Pt FLAT FILL |Pt TOP LEFT OUTLINE |Pt BOTTOM RIGHT OUTLINE| Pt ALL OUTLINES|Pt TOP LEFT BEVEL |Pt BOTTOM RIGHT BEVEL |Pt ALL BEVELS


Pt ARG BEVEL CONTRAST PtBasic 25



Pt ARG CELL HORZ ALIGN PtGroup

Pt ARG CELL VERT ALIGN PtGroup


Pt ARG CONTAINER FLAGS PtContainer Not used by this class.

continued. . .











Pt ARG DIM PtWidget





Pt ARG FLAGS PtWidget SetsPt DELAY ACTIVATION| Pt DELAY REALIZE|Pt HIGHLIGHTED

Pt ARG GROUP FLAGS PtGroup

Pt ARG GROUP HORZ ALIGN PtGroup

Pt ARG GROUP ORIENTATION PtGroup 1

Pt ARG GROUP ROWS COLS PtGroup

Pt ARG GROUP SPACING PtGroup

Pt ARG GROUP SPACING X PtGroup

Pt ARG GROUP SPACING Y PtGroup

Pt ARG GROUP VERT ALIGN PtGroup

Pt ARG HEIGHT PtWidget 8

continued. . .







Pt ARG LAYOUT PtContainer












Pt ARG POS PtWidget








continued. . .





Pt ARG WIDTH PtWidget 9


Pt CB ARM PtBasic








Pt CB DND PtWidget







Pt CB MENU PtBasic


Pt CB RAW PtWidget



continued. . .







2005, 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:ThePtMenuBar 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 onlyPtMenuButton widgets as children.☞



PtMenuBar 2005, 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. . .


2005, 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

continued. . .


PtMenuBar 2005, QNX Software Systems Ltd.


Pt ARG TOOLBAR LAYOUT FLAGS PtToolbar Pt TOOLBAR FROM LINE START

| Pt TOOLBAR TO LINE END

Pt ARG TOOLBAR SPACING PtToolbar 10







Pt CB ARM PtBasic






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget

continued. . .


2005, QNX Software Systems Ltd. PtMenuBar







PtMenuButton 2005, 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:ThePtMenuButton 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 thePt ARG ACCEL KEY resourcethat’s inherited fromPtLabel. 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:


2005, 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 thePtMenuLabel 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 thePk 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




continued. . .






PtMeter 2005, QNX Software Systems Ltd.

A meter

Class hierarchy:PtWidget → PtBasic → PtMeter

PhAB icon:

Public header:<photon/PtMeter.h>

Description:ThePtMeter 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 thePt ARG METER NEEDLE POSITIONresource.

Your meter can include up to 3 severity arcs, drawn in colors toindicate different levels of the meter:


2005, QNX Software Systems Ltd. PtMeter

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



...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 withPg TRANSPARENTas 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 usingPg TRANSPARENTas a fillcolor, put thePtMeter inside aPtOSContainer 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. SeePgColor t in the PhotonLibrary 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 PhotonLibrary 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 setPt GETS FOCUSin 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 setPt GETS FOCUSin the meter’sPt ARG FLAGS.

☞

Pt ARG METER LEVEL1 COLOR


PgColor t Scalar Pg GREEN

The color of the first severity arc. SeePgColor 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. SeePgColor 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. SeePgColor 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. SeePgColor 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 aPh EV KEY event

� Pt MOUSE MOVED — the needle moved due to amouse event;event is aPh EV PTR MOTION BUTTONor Ph EV BUT PRESSevent

For more information, seePhEvent t in the PhotonLibrary Reference.

event A pointer to aPhEvent t structure that describes theevent that caused the callback to be invoked. Ifevent isNULL, then the callback was invoked because thePt ARG METER NEEDLE POSITION resource was set.

cbdata A pointer to aPtMeterCallback 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 GETSFOCUS














Pt ARG POS PtWidget


continued. . .










Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget





PtMTrend 2005, 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 toPtTrend, 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.


2005, QNX Software Systems Ltd. PtMTrend

A PtMTrend widget.

New resources:


Pt ARG MTREND FLAGS int Flag Pt MTREND ALWAYS SCROLL

Pt ARG MTREND N SAMPLES unsigned Scalar 0

Pt ARG MTREND N GRAPHS unsigned Scalar 0

Pt ARG MTREND GRAPH ATTR PtMTrendAttr t Struct N/A

Pt ARG MTREND GRAPH STATE int Scalar N/A

Pt ARG MTREND GRAPH DATA PtMTrendData t Struct N/A

Pt ARG MTREND TRACE WIDTH int Scalar 5

Pt ARG MTREND TRACE COLOR PgColor t Scalar 0xC0C0C0

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, usePt MTREND DIRECTION MASKas thelen argument for thePtSetArg() 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, usePt MTREND GRID MASK as thelen argument forthePtSetArg() 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 ifPt 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 isPt 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; seePgSetStrokeJoin() in thePhotonLibrary Reference for more informationabout join types.

int min andmax

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 );

Thewidget argument is a pointer to the trend widget of typePtMTrend. Thedamage argument is the damage list for the widget.Theattr argument is typept 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 withPtSetArg() or PtSetResource(), passthe graph number as thelen 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 withPtSetArg() or PtSetResource(), passthe graph number as thelen argument.

Pt ARG MTREND GRAPH DATA


PtMTrendData t Struct N/A

Use to add or change data for a specified graph. When setting thisresource withPtSetArg() or PtSetResource(), pass the graph numberas thelen argument. ThePtMTrendData t contains at least thesemembers:

int mode Can be one ofPt 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 providesPtMTrendAddData() 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 aPtMTrendWidget t structure. Thefunction should use thetrace.pos andtrace.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 aPtMTrendWidget t structure. Thefunction should use thegrid.* 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:ThePtMTrend 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.


2005, 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 typePtMTrend.

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 aPtMtrend, whilePtMTrendChangeData() lets you change existing data.

Thenewdata array is ordered with the oldest sample atnewdata[0],and the newest atnewdata[nsamples - 1]. The oldest sample to bereplaced has an index oflast sample + nsamples - 1;

The samples in the trend are replaced as follows:


PtMTrendAddData() , PtMTrendChangeData() 2005, 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


2005, QNX Software Systems Ltd. PtMultiTextMultiline stylized text

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

PhAB icon:

Public header:<photon/PtMultiText.h>

Description:ThePtMultiText 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 thePtMultiText 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

TheMultiText 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 2005, 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 thePt 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 textusingPt 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.


2005, QNX Software Systems Ltd. PtMultiText

To display a horizontal scrollbar:

� Set thePt ARG SCROLLBAR X DISPLAY to Pt AS REQUIREDorPt ALWAYS.

� ClearPt EMT WORD andPt 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. ThePtMultiText 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 thePt 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 thePt ARG TEXT FONT resource inherited fromPtLabel. Thetext foreground and background colors are taken from the values ofthePt ARG COLOR andPt ARG FILL COLOR resources.

If you set the text usingPt 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 thePtMultiTextAttributes 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 thePt ARG MULTITEXT RANGE ATTRIBUTES resource or,by calling thePtTextModifyText() 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 thePtMultiText widget with a catchy message.

When setting the text and attributes via thePt ARG MULTITEXT SEGMENTS resource, you provide theresource with an array ofPtMultiLines 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 thePtMultiTextModifyText() function. To deleteand/or insert text such that it takes on the attributes in effect at theinsertion point, usePtTextModifyText().

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 callingPtTextGetSelection(). This gives the start and endpositions to use in a subsequent call toPtMultiTextModifyAttributes().

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 thePtMultiTextControl t structure (also knownasPtMultiTextCallback 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 ofPtText

or PtMultiText widgets. The members ofPtTextCallback t (also known asPtTextControl t) are:

int start posint end pos The characters fromstart pos up to but not

includingend pos will be deleted.

int cur insert The position to insert characters if no deletionhas occurred; otherwise, the new characterswill be inserted atstart 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 thePtMultiText widget. Itpoints to the segment of text that’s involved in the modificationthat caused the callback. SeePtMultiTextSegment 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 thePt MT TAG attribute for the range, and add the range tothe widget. The text’s original structure can be obtained in callbacksby looking at thetag in theattributes 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);}

Thedata 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. QueryingPt 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 thePt 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. ThePtMultiTextLine t

structure contains aPhRect t structure (see the PhotonLibraryReference) 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 thenext andpreviouspointers in thePtMultiTextLine t structure. Traverse all the linesuntil thenext pointer isNULL, 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 thePtMultiText 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 theCtrl key, you can drag theselected text to aPtText, PtMultiText, PtTerminal, orPtTtywidget.

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 pressEnter) 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 FORCEDSCROLL

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 toPtSetArg() as follows:

value A pointer to an instance of aPtMultiTextQuery 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 toPtSetArg() as follows:

value A pointer to an instance of aPtMultiTextQuery 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 toPtSetArg() as follows:

value A pointer to an instance of aPtMultiTextControl 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 aPtMultiTextInfo t

structure, which is the same asPtMultiTextControl t.

len A pointer to an instance of aPtTextCallback 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 ofPt 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 thePtMultiLines t array is concatenatedand used to replace the text in thePt 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 thePt 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 andPt 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 CURSORINSERT




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

continued. . .




Pt ARG TEXT HIGHLIGHT TEXT COLOR PtText



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

continued. . .




Pt CB MENU PtBasic

Pt CB MODIFY NOTIFY PtText See below

Pt CB MODIFY VERIFY PtText See below

Pt CB MOTION NOTIFY PtText See below

Pt CB MOTION VERIFY PtText See below


Pt CB RAW PtWidget




Pt CB TEXT CHANGED PtText See below


Pt CB ACTIVATE

Pt CB ACTIVATE is inherited fromPtBasic, but its behavior isdifferent for aPtMultiText 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 SELECTABLEset in itsPt ARG FLAGS.

� Pt EDIT ACTIVATE — you pressedEnter in the textfield.



� Pt CHANGE ACTIVATE — you modified the text, gavefocus to another widget, andPt CHANGE ACTIVATE isset in the text widget’sPt ARG TEXT FLAGS(inherited fromPtText).


cbdata If reason subtype is 0, the callback data is as describedfor thePt CB ACTIVATE resource forPtBasic.

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;

� ThePtTextCallback t tc structure has thefollowing members:

int start pos;int end pos; All characters starting atstart pos

up to but not includingend pos areto be deleted. Ifstart 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. Iflength is zero, no text isbeing inserted, so thetext field isinvalid.

char *text; The text to be inserted atcur insert.Before usingtext, check thelengthfield to make suretext contains validdata. In addition, note thattextmight not be zero-terminated.

int doit; Indicates whether or not thismodification will be applied to thewidget. If doit is zero, the widgetdiscards the modification. Ifdoit 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 bycur insert. SeePtMultiTextSegment t.

� PtMultiTextAttributes t *attributes are theattributes associated withseg. SeePtMultiTextAttributes t.


Pt CB GOT FOCUS, Pt CB LOST FOCUS

Pt CB GOT FOCUS andPt CB LOST FOCUS are inherited fromPtBasic, but thecbdata member of the callback information isdifferent for aPtMultiText widget.




reason The name of the callback resource that caused thiscallback to be invoked.

reason subtype

0 (not used).


cbdata A pointer to aPtMultiTextCallback t structure.

The members of thePtMultiTextCallback t structure are used asfollows:

� ThePtTextCallback 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 bycur insert. SeePtMultiTextSegment t.

� PtMultiTextAttributes t *attributes are the attributesassociated withseg. SeePtMultiTextAttributes t.

ThePt CB GOT FOCUS callbacks should returnPt CONTINUE.

ThePt 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 fromPtText but thecbdatamember of the callback information is different for aPtMultiTextwidget.



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 fromPtText, but thecbdatamember of the callback information is different for aPtMultiTextwidget.



reason subtype

0 (not used).





int start pos;int end pos; All characters starting atstart pos up to but not

includingend pos are to be deleted. Ifstart posandend 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. Iflengthis zero, no text is being inserted, so thetext fieldis invalid.

char *text; The text to be inserted atcur insert.

Before usingtext, check thelength field to makesuretext 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. Ifdoit is zero, the widgetdiscards the modification. Ifdoit is nonzero, thewidget uses the contents of the callback structureto modify itself.

For more information, seePtTextModifyText() orPtMultiTextModifyText().




Pt CB MOTION VERIFY

Pt CB MOTION VERIFY (Pt CB MODIFY NOTIFY), is inheritedfrom PtText, but thecbdata member of the callback information isdifferent for aPtMultiText 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 atcur 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. Ifdoit is zero, the cursorremains atcur insert. If doit is nonzero, thecursor will be repositioned atnew 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:ThePtMultiText 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 toPtMultiText callbacks

PtMultiTextCreateAttributes()

Initialize a multitext attribute structure.

PtMultiTextGetAttributes()

Get the attributes of aPtMultiText widget.

PtMultiTextInfo()

Get character/line information from aPtMultiText widget.

PtMultiTextInfo t

Information passed toPtMultiText callbacks

PtMultiTextLine t

Information about a line of text in aPtMultiText



PtMultiTextModifyAttributes()

Modify the attributes of aPtMultiText widget.

PtMultiTextModifyText()

Modify the contents of aPtMultiText widget.

PtMultiTextQuery t

Structure for getting information about a line or character

PtMultiTextSegment t

Information about a segment of text in aPtMultiText


Get the selected range from aPtText widget.

PtTextModifyText()

Modify the contents of aPtText widget.


Set the selected range for aPtText widget.


2005, 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 thePtMultiText 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 thePt 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 PhotonLibrary Reference) orone of the following special values:


PtMultiLines t 2005, QNX Software Systems Ltd.

Pt INHERIT COLOR

Use the same color as the previous range.

Pt DEFAULT COLOR

Use the value of thePt 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 thePt ARG FILL COLORresource.


See also:PtMultiText, PtMultiTextAttributes t

PgColor t in the PhotonLibrary Reference


2005, 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 thePt 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 PhotonLibrary Reference) orone of the following special values:

Pt INHERIT COLOR



PtMultiTextAttributes t 2005, QNX Software Systems Ltd.

Pt DEFAULT COLOR

Use the value of thePt 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 thePt ARG FILL COLORresource.

flags For internal use.

tag To be used at your application’s discretion.


See also:PtMultiText, PtMultiTextInfo()

PgColor t in the PhotonLibrary Reference


2005, 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 thePtMultiText widgets as well as tospecify actions or request data. The members of these structures are:

tc A pointer to aPtTextCallback t structure thatdescribes the affected text.

attributes A pointer to aPtMultiTextAttributes t

structure that describes the attributes of theaffected text.

seg A pointer to aPtMultiTextSegment 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 2005, QNX Software Systems Ltd.

See also:PtMultiText, PtMultiTextAttributes t,PtMultiTextSegment t, PtTextCallback t


2005, QNX Software Systems Ltd. PtMultiTextCreateAttributes()Initialize a multitext attribute structure

Synopsis:PtMultiTextAttributes t *

PtMultiTextCreateAttributes(PtMultiTextAttributes t *attrs);

Description:This function initializes the specifiedPtMultiTextAttributes 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, orNULL if no memorywas available.

Examples:SeePtMultiTextGetAttributes().


Safety


Signal handler No

Thread No

See also:PtTextGetSelection(), PtTextModifyText(), PtTextSetSelection(),PtMultiTextAttributes t


PtMultiTextGetAttributes() 2005, 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 providedPtMultiTextAttributes t

structure to the attributes found atchar offset.

If you provide the integers forstart andend, the function sets theseparameters to the character offsets that mark the beginning and end ofthe segment that containschar offset. Bothstart andend 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 providedPtMultiTextAttributes t structure, orNULL if the specified widget isNULL or isn’t aPtMultiTextwidget.

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"


2005, 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() 2005, 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


2005, QNX Software Systems Ltd. PtMultiTextGetAttributes()

See also:PtMultiTextCreateAttributes(), PtTextGetSelection(),PtTextModifyText(), PtTextSetSelection(),PtMultiTextAttributes t


PtMultiTextInfo() 2005, 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 youdon’t require can beset toNULL. Any argument representing information youdo 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 setquery type to Pt MT QUERY LINE, then:


2005, QNX Software Systems Ltd. PtMultiTextInfo()

� line num must point to an instance of anint 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 setquery 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 fewerthanchar offset characters

� attrs, if provided, will be filled in with the attributes in effect at thegivenchar 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 andend 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() 2005, QNX Software Systems Ltd.

seg The segment that containschar offset.

You could use this function to scroll to a specific line. For example, ifyou setPt ARG CURSOR POSITION to the offset of a character online 35, the widget will scroll to line 35. (ThePtMultiText widgetwill scroll as necessary, horizontally and vertically, to make the cursorvisible).

Returns:0 Success.

1 The provided widget isNULL or isn’t aPtMultiText widget.


Safety


Signal handler No

Thread No

See also:PtTextGetSelection(), PtTextModifyText(), PtTextSetSelection(),PtMultiTextAttributes t, PtMultiTextLine t,PtMultiTextSegment t


2005, 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:ThePtMultiTextLine t structure describes a line of text asdisplayed in aPtMultiText 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 ThePhRect t that specifies the extent of the line.

segment A pointer to thePtMultiTextSegment t structurethat describes the segment in effect at the start of theline.

prev A pointer to thePtMultiTextLine t structure forthe previous line.

next A pointer to thePtMultiTextLine t structure forthe next line.


PtMultiTextLine t 2005, QNX Software Systems Ltd.


See also:PtMultiText, PtMultiTextInfo(), PtMultiTextSegment t


2005, 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 thespecifiedPtMultiText widget. All characters fromstart 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() 2005, QNX Software Systems Ltd.

Examples:SeePtMultiTextGetAttributes().


Safety


Signal handler No

Thread No



2005, 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 aPtMultiText

widget.

If start doesn’t equalend, then:

� all characters fromstart up to but not includingend are deleted

� the widget’s current insert position is set to the lesser ofstart andend

� insert pos is ignored.

If start does equalend, then:

� no text is deleted

� the widget’s current insert position is set toinsert 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 insertslengthcharacters fromtext. It does this regardless of the widget’s insertionmode. Iflength 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() 2005, QNX Software Systems Ltd.

� The text is separated into its own segment, but keeps its inheritedvalues.

� The attributes specified byattributes mask are applied to the newsegment from theattrs 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



2005, 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 aPtMultiText widget. You’ll use it when getting thevalue ofPt ARG MULTITEXT QUERY CHARACTER orPt ARG MULTITEXT QUERY LINE. When getting these resources,use thelen member of thePtArg t structure (see the PhotonLibraryReference) to indicate the character or line to be queried. When youget callPtGetResources(), 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 thePtMultiTextLine t structurethat describes the line queried or the line thatcontains the character queried.

segment A pointer to thePtMultiTextSegment 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 2005, QNX Software Systems Ltd.


See also:PtMultiText, PtMultiTextSegment t, PtMultiTextLine t


2005, 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 asegment of text in aPtMultiTextwidget. 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 ThePtMultiTextAttributes 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 2005, QNX Software Systems Ltd.

See also:PtMultiText, PtMultiTextAttributes t


2005, 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 2005, 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.


2005, 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 thePtScrollbar widget.

Exported subordinate children:Unless the resources are already defined inPtNumeric, thePtNumeric class uses the resources of its exported subordinate child,PtScrollbar.

ThePtNumeric class “inherits” all the resources of its exportedsubordinate child. WherePtNumeric and its exported subordinatechild both define resources having the same name, the resourcedefined inPtNumeric 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. . .


2005, QNX Software Systems Ltd. PtNumeric


















Pt ARG POS PtWidget

Pt ARG RESIZE FLAGS PtWidget Pt RESIZEY ALWAYS |Pt RESIZEX AS REQUIRED






continued. . .






Pt CB ARM PtBasic






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






2005, QNX Software Systems Ltd. PtNumericFloatFloating-point numeric widget

Class hierarchy:PtWidget → PtBasic → PtContainer → PtCompound →PtNumeric → PtNumericFloat

PhAB icon:

Public header:<photon/PtNumericFloat.h>

Description:ThePtNumericFloat class is a numeric widget that lets you enterfloating-point values between given minimum and maximum values.You can also use an incorporatedPtScrollbar to increase ordecrease the value by a set amount.

A PtNumericFloat widget.

In addition, you can use the resources defined byPtNumeric 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 ofdouble* 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 2005, 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 sharedph 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 PhotonProgrammer’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.


2005, 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 thePt CALLBACKS ACTIVE bit set in itsPt ARG FLAGS resource, these callbacks are also invoked when yourapplication changes thePt 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 aPtNumericFloatCallback t structurethat contains at least:

� double numeric value — the current value of thewidget




Exported subordinate children:Unless the resources are already defined inPtNumericFloat, thePtNumericFloat class uses the resources of its exportedsubordinate child,PtScrollbar.

ThePtNumericFloat class “inherits” all the resources of itsexported subordinate child. WherePtNumericFloat and itsexported subordinate child both define resources having the samename, the resource defined inPtNumericFloat 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 ACTIVATE PtBasic See below.

Pt CB ARM PtBasic

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 pressedEnter whilein PtNumericFloat’s text field.


PtNumericInteger 2005, QNX Software Systems Ltd.

Integer numeric widget

Class hierarchy:PtWidget → PtBasic → PtContainer → PtCompound →PtNumeric → PtNumericInteger

PhAB icon:

Public header:<photon/PtNumericInteger.h>

Description:ThePtNumericInteger 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. . .


2005, QNX Software Systems Ltd. PtNumericInteger


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




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 thePt CALLBACKS ACTIVE bit set in itsPt ARG FLAGS resource, these callbacks are also invoked when yourapplication changes thePt 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 aPtNumericIntegerCallback t

structure that contains at least:

� int numeric value — the current value of the widget.


Exported subordinate children:Unless the resources are already defined inPtNumericInteger, thePtNumericInteger class uses the resources of its exportedsubordinate child,PtScrollbar.

ThePtNumericInteger class “inherits” all the resources of itsexported subordinate child. WherePtNumericInteger and itsexported subordinate child both define resources having the samename, the resource defined inPtNumericInteger 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


continued. . .




Pt CB RAW PtWidget





Pt CB ACTIVATE

If cbinfo->reason subtype is Pt NUMERIC ACTIVATE, the callbackwas invoked because you changed the value and pressedEnter whilein PtNumericInteger’s text field.


Photon Widgets — PtO to PtW

January 31, 2005 Photon Widgets — PtO to PtW 651


The Photon Widgets, data structures, and widget-related functions aredescribed here in order:

Volume Range Entries

1 PtA to PtN PtArc to PtNumericInteger

2 PtO to PtW PtOnOffButton to PtWindowToFront()


PtOnOffButton 2005, QNX Software Systems Ltd.

An on/off button that can be set or unset

Class hierarchy:PtWidget -> PtBasic -> PtLabel -> PtButton ->PtOnOffButton

PhAB icon:

Public header:<photon/PtOnOffButton.h>

Description:A PtOnOffButton widget displays an on/off button that can be 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

654 Photon Widgets — PtO to PtW January 31, 2005

2005, QNX Software Systems Ltd. PtOnOffButton

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 thePt 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 callingPtSetResource()or PtSetResources().


reason Pt CB ONOFF NEW VALUE

reason subtype

0 (not used).


cbdata A pointer to aPtOnOffButtonCallback t structurethat contains at least the following member:

int state; The current state of the on/off button.












Pt ARG ARM FILL PtButton













continued. . .









Pt ARG DIM PtWidget





Pt ARG FLAGS PtWidget |=Pt SELECTABLE&=˜Pt TOGGLE













continued. . .
















Pt ARG POS PtWidget











continued. . .










Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget





PtOSContainer 2005, QNX Software Systems Ltd.

Offscreen-context container for flicker-free drawing

Class hierarchy:PtWidget → PtBasic → PtContainer → PtOSContainer

PhAB icon:

Public header:<photon/PtOSContainer.h>

Description:PtOSContainer creates an offscreen context and forces all 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 aPtOSContainer widget, its offscreen memoryis automatically released. When you rerealize the widget, theoffscreen memory is reallocated.

☞





continued. . .


2005, QNX Software Systems Ltd. PtOSContainer


















Pt ARG DIM PtWidget



Pt ARG FILL COLOR PtBasic See below.




continued. . .




















Pt ARG POS PtWidget







continued. . .


2005, QNX Software Systems Ltd. PtOSContainer






Pt CB ARM PtBasic






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget







Pt ARG FILL COLOR

You can’t set this resource toPg TRANSPARENT. The widget ignoresany attempt to do so.


2005, 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 thePtPane widget are clipped.

A dialog box featuring several PtPane widgets.



PtPane 2005, 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. . .


2005, QNX Software Systems Ltd. PtPane






Pt ARG FLAGS PtWidget Pt HIGHLIGHTED

















Pt ARG POS PtWidget


continued. . .


PtPane 2005, QNX Software Systems Ltd.











Pt CB ARM PtBasic






Pt CB DND PtWidget






Pt CB MENU PtBasic


continued. . .


2005, QNX Software Systems Ltd. PtPane


Pt CB RAW PtWidget






PtPanelGroup 2005, QNX Software Systems Ltd.

A container that manages panels

Class hierarchy:PtWidget → PtBasic → PtContainer → PtPanelGroup

PhAB icon:

Public header:<photon/PtPanelGroup.h>

Description:A PtPanelGroup is a container that manages panels and 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:


2005, QNX Software Systems Ltd. PtPanelGroup

You can make thePtPanelGroup 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, seePt ARG PG SELECTION MODE.

Populating a panel group

You can populate aPtPanelGroup 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 thePtPanelGroup

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

☞



Multiple panels

When you design the UI for your application, you can put containerwidgets (i.e. descendants ofPtContainer) into aPtPanelGroup.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 aPtPanelGroup in PhAB, select a container widgetfrom the palette and click on thePtPanelGroup. 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 PhotonProgrammer’s Guide).

To flip between existing panels in PhAB, select thePtPanelGroup

and changePt ARG PG CURRENT INDEX to the number of thepanel you wish to edit.

Single panel

At runtime, your application’s code can clear and repopulate thePtPanelGroup 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 in



PhAB (as picture modules) and then usePtClearWidget() andApCreateModule() whenever you switch panels.

If you choose this method to populate aPtPanelGroup, 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 thePtBasic 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 throughn - 1, wheren is the number ofpanels managed by thePtPanelGroup. An index value ofPt PG INVALID may be interpreted as a “NULL” value.

The panel indexes indicate the order of panels in thePtPanelGroup;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 thePtPanelGroup. 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)

ThePtPanelGroup 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 SELECTORALIGN 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 SELECTORON 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 toaccommodate 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 andPt 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 thisPtPanelGroup.



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 thePt 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 thanPt CONTINUE.

If the widget has thePt CALLBACKS ACTIVE bit set in itsPt ARG FLAGS resource, these callbacks are also invoked when yourapplication changesPt ARG PG CURRENT orPt ARG PG CURRENT INDEX by callingPtSetResource() orPtSetResources().


reason Pt CB PG PANEL SWITCHING

reason subtype

Not used.

event A pointer to aPhEvent t structure that describes theevent that caused the callback to be invoked. Ifevent isNULL, then the callback was invoked because theselection was changed programmatically.

cbdata A pointer to aPtPanelGroupCallback t structure thatcontains at least:

� char *old panel — the title of the panel that waspreviously selected, orNULL if no panel waspreviously selected.

� char *new panel — the title of the newly selectedpanel, orNULL if no panel is being selected.

� uint16 t old panel index — the index of the panelthat was previously selected, orPt PG INVALID if nopanel was previously selected

� uint16 t new panel index — the index of the newlyselected panel, orPt PG INVALID if no panel is beingselected.



The panel indexes indicate the order of panels in thePtPanelGroup;they change when panels are added, removed, or reordered.

☞

These callbacks should returnPt CONTINUE to permit the switch tooccur. Returning a value other thanPt 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 aPtPanelGroup 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




continued. . .






Pt CB MENU PtBasic


Pt CB RAW PtWidget





Convenience functions:ThePtPanelGroup 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


2005, QNX Software Systems Ltd. PtPGCreatePopup()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 thePtPanelGroup specifiedby widget, in the form of a popup window. The popup window ispositioned atpos, or at (0,0) ifpos 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



PtPGCreatePopup() 2005, QNX Software Systems Ltd.




� 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


2005, QNX Software Systems Ltd. PtPGCreatePopup()

Returns:A pointer the to newPtPanelGroup widget, orNULL if there wasn’tenough memory.

To realize or otherwise manipulate the popup window, do it to thepanel group’s parent (using thePtWidgetParent() macro).

☞


Safety


Signal handler No

Thread No

See also:PtPanelGroup

PhPoint t, PtWidgetParent() in the PhotonLibrary Reference


PtPGFindIndexByPanel() 2005, QNX Software Systems Ltd.

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 thewidget argument.

Returns:The panel index, orPt 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()


2005, QNX Software Systems Ltd. PtPGFindIndexByTitle()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 specifiedtitlewithin thePtPanelGroup specified by thewidget argument.

Returns:The panel index, orPt PG INVALID if the panel couldn’t be found.


Safety


Signal handler No

Thread No

See also:PtPanelGroup, PtPGFindIndexByPanel(),PtPGFindPanelByIndex(), PtPGFindPanelByTitle(),PtPGFindTitleByIndex()


PtPGFindPanelByIndex() 2005, QNX Software Systems Ltd.

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 thePtPanelGroup specified by thewidget argument.

Returns:A pointer to the panel widget, orNULL if the specified panel doesn’texist or thePtPanelGroup isn’t in multiple-container mode.


Safety


Signal handler No

Thread No

See also:PtPanelGroup, PtPGFindIndexByPanel(), PtPGFindIndexByTitle(),PtPGFindPanelByTitle(), PtPGFindTitleByIndex()


2005, QNX Software Systems Ltd. PtPGFindPanelByTitle()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 thewidget argument.

Returns:A pointer to the panel widget, orNULL if the panel couldn’t be foundor thePtPanelGroup isn’t in multiple-container mode.


Safety


Signal handler No

Thread No

See also:PtPanelGroup, PtPGFindIndexByPanel(), PtPGFindIndexByTitle(),PtPGFindPanelByIndex(), PtPGFindTitleByIndex()


PtPGFindTitleByIndex() 2005, QNX Software Systems Ltd.

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 specifiedindexwithin thePtPanelGroup specified by thewidget argument.

Returns:A pointer to the title of the specified panel, orNULL if the specifiedpanel doesn’t exist.


Safety


Signal handler No

Thread No

See also:PtPanelGroup, PtPGFindIndexByPanel(), PtPGFindIndexByTitle(),PtPGFindPanelByIndex(), PtPGFindPanelByTitle()


2005, QNX Software Systems Ltd. PtPixelA set of points

Class hierarchy:PtWidget → PtBasic → PtGraphic → PtPixel

PhAB icon:

Public header:<photon/PtPixel.h>

Description:You can use thePtPixel 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’sPt ARG ORIGIN. For more information, seePtGraphic.

Each point in thePt 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. . .


PtPixel 2005, QNX Software Systems Ltd.






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


2005, QNX Software Systems Ltd. PtPixel








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


PtPixel 2005, QNX Software Systems Ltd.



Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






2005, QNX Software Systems Ltd. PtPolygonA set of connected line segments

Class hierarchy:PtWidget → PtBasic → PtGraphic → PtPolygon

PhAB icon:

Public header:<photon/PtPolygon.h>

Description:You can use thePtPolygon widget to draw a set of connected linesegments, called apolyline, from the vertices of the line segments.

Open or closed PtPolygon widgets.

The points that you specify in thePt ARG POINTS resource are thevertices of the polyline or polygon. These points are relative to thewidget’sPt ARG ORIGIN. For more information, seePtGraphic.

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 usePt ARG POLYGON FLAGS to specify:

� whether points in the polygon definition are relative to the previouspoint or in absolute coordinates


PtPolygon 2005, QNX Software Systems Ltd.

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




2005, QNX Software Systems Ltd. PtPolygon




















Pt ARG DIM PtWidget





continued. . .


PtPolygon 2005, QNX Software Systems Ltd.









Pt ARG INSIDE FILL PATTERN PtGraphic

Pt ARG INSIDE TRANS PATTERN PtGraphic














Pt ARG POS PtWidget

continued. . .


2005, QNX Software Systems Ltd. PtPolygon








Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






PtPrintSel 2005, QNX Software Systems Ltd.

A widget for selecting printing properties

Class hierarchy:PtWidget → PtBasic → PtContainer → PtPrintSel

PhAB icon:

Public header:<photon/PtPrintSel.h>

Description:ThePtPrintSel widget lets you select a printer, change itsproperties, and optionally select a range of pages and the number ofcopies to print.


2005, QNX Software Systems Ltd. PtPrintSel

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);



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 usingPtGetResource() 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 PRINTSELFILE PANE|

Pt PRINTSELSETTINGSPANE

| Pt PRINTSELPREFERENCES

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 byPtPrintPropSelect(). You can customize thisdialog by setting some pseudo-resources. They aren’t really widgetresources, but you can set them forPtPrintSel as if they were, andthe widget passes the settings toPtPrintPropSelect(). For detailsabout these resources, see the PhotonLibrary 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. UsePpCreatePC() to create a Print Context, andPpSetPC()to change its settings.



When you usePtGetResources() to get this resource, you mustprovide aPpPrintContext t structure, which is filled in directlywith the values of the context. Unlike most calls toPtGetResources(),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 SETTINGSPANE|Pt PRINTSEL PREFERENCES

Flags that modify the appearance of the widget:

Pt PRINTSELFILE PANE

Enable the Send to file pane.

Pt PRINTSELNO COPIES

Disable the Copies widget.

Pt PRINTSELNO PAGE RANGE

Disable the Print Range toggle button and the From and Tofields.

Pt PRINTSELNO PRINTSELECT

Disable the printer-name combobox. Physical output goes tothe default physical printer whose name is shown.

Pt PRINTSELNO SELECT RANGE

Disable the Print Selection toggle button.

Pt PRINTSELPREFERENCES

Enable the Preferences button.

Pt PRINTSELSETTINGSPANE

Enable the Print Pages, Print Order and Copies panes.



The following flag macros are defined in<PtPrintSel.h>:

Pt PRINTSELALL PANES

Pt PRINTSEL FILE PANE| Pt PRINTSEL SETTINGSPANE

Pt PRINTSELDFLT LOOK

Pt PRINTSEL FILE PANE| Pt PRINTSEL SETTINGSPANE|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 toNULL, clicking the Preferences button displays thePrint Properties dialog by invoking thePtPrintPropSelect()convenience function; for more information, see the PhotonLibraryReference.


reason Pt CB PRINT PROPS

reason subtype

Not used.


cbdata A pointer to aPpPrintContext t structure. For moreinformation, see the Printing chapter of the PhotonProgrammer’s Guide.
















Pt ARG CONTAINER FLAGS PtContainer &=˜Pt GETSFOCUS








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:ThePtPrintSel 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 PhotonLibrary Reference.


PtProgress 2005, QNX Software Systems Ltd.

A progress bar

Class hierarchy:PtWidget → PtBasic → PtGauge → PtProgress

PhAB icon:

Public header:<photon/PtProgress.h>

Description:ThePtProgress 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 thePt ARG GAUGE FLAGS resource definedby PtGauge are of particular interest toPtProgress:

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.


2005, QNX Software Systems Ltd. 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’sPt 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. SeePgColor t in the PhotonLibraryReference.

Pt ARG PROGRESS DIVISIONS



The number of divisions (1 means continuous).

PtProgress doesn’t use this resource, but any subclasses can.



Pt ARG PROGRESS GAP



The gap (in pixels) between the progress bar and the text (if the 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 FONT PtGauge

Pt ARG GAUGE H ALIGN PtGauge

Pt ARG GAUGE V ALIGN PtGauge

Pt ARG GAUGE VALUE PtGauge

Pt ARG GAUGE VALUE PREFIX PtGauge

Pt ARG GAUGE VALUE SUFFIX PtGauge

continued. . .














Pt ARG MAXIMUM PtGauge


Pt ARG MINIMUM PtGauge


Pt ARG ORIENTATION PtGauge



Pt ARG POS PtWidget






continued. . .






Pt CB ARM PtBasic




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


2005, QNX Software Systems Ltd. PtProgressEntireSegment()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 thePtProgress pointed to bywidget.

The coordinates are stored in the space pointed to bystart andend,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 PROGRESSNO MORE SEGMENTS

No segment was found.


Safety


Signal handler No

Thread No


PtProgressEntireSegment() 2005, QNX Software Systems Ltd.

See also:PtProgress, PtProgressEntireSegment(), PtProgressFirstSegment(),PtProgressNextSegment(), PtProgressTextRect(),


2005, QNX Software Systems Ltd. PtProgressFirstSegment()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 thePtProgress pointed to bywidget.


After calling this function, you can callPtProgressNextSegment() toget the coordinates of succeeding segments.

Returns:0 Success.




Safety


Signal handler No

Thread No


PtProgressFirstSegment() 2005, QNX Software Systems Ltd.

See also:PtProgress, PtProgressEntireSegment(), PtProgressNextSegment(),PtProgressTextRect()


2005, QNX Software Systems Ltd. PtProgressNextSegment()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 thePtProgress pointed to bywidget.


You must have calledPtProgressFirstSegment() before calling thisfunction.

☞

Returns:0 Success.




Safety


Signal handler No

Thread No


PtProgressNextSegment() 2005, QNX Software Systems Ltd.

See also:PtProgress, PtProgressEntireSegment(), PtProgressFirstSegment(),PtProgressTextRect()


2005, QNX Software Systems Ltd. PtProgressTextRect()Get the text area of a progress bar

Synopsis:void PtProgressTextRect( PtWidget t const *widget,

PhRect t *rect );

Description:This function gets the rectangle in which text is drawn on thePtProgress pointed to bywidget. The rectangle’s coordinates arestored in thePhRect t structure pointed to byrect.


Safety


Signal handler No

Thread No

See also:PtProgress, PtProgressEntireSegment(), PtProgressFirstSegment(),PtProgressNextSegment()



PtRaw 2005, QNX Software Systems Ltd.

A widget for use with Photon drawing primitives

Class hierarchy:PtWidget → PtBasic → PtRaw

PhAB icon:

Public header:<photon/PtRaw.h>

Description:ThePtRaw widget lets you use the Photon graphics drawing functionsin applications that use widgets.

ThePtRaw 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 functionPtRawsupports is described in detail in this chapter. If you’d like moreinformation about when to use an Initialization, Extent, or Connectfunction, seeBuilding Custom Widgets.

☞

With aPtRaw 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:


2005, QNX Software Systems Ltd. PtRaw

� 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

ThePtRaw 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 callingPtDamageWidget(), 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, ormodel, that defines the contents ofthe canvas.

Place a pointer to this data structure in thePt ARG POINTER orPt ARG USER DATA resource of thePtRaw 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.



Before your function begins drawing, it should establish its coordinatespace correctly. First, get the coordinates of the clip rectangle or thewidget canvas, by callingPtCalcCanvas() 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 thePg* calls made within the draw function arerelative to the canvas ofPtRaw’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 constantPg 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 inthePt ARG FILL COLOR resource.

Here’s a more detailed example of setting up and using aPtRaw

widget:

pos.x = 220;dim.w = 200, dim.h = 200;n=0;PtSetArg( &args[n], Pt ARG DIM, &dim, 0 );n++;PtSetArg( &args[n], Pt ARG POS, &pos, 0 );n++;PtSetArg( &args[n], Pt ARG RAW DRAW F, &draw, 1 );n++;PtSetArg( &args[n], Pt ARG BEVEL WIDTH, 2, 0 );n++;PtSetArg( &args[n], Pt ARG FLAGS, Pt TRUE,

Pt SELECTABLE | Pt HIGHLIGHTED );n++;PtSetArg( &args[n], Pt CB ARM, &aback, 1 );n++;PtCreateWidget(PtRaw, Pt DEFAULT PARENT, n, &args[0] );...

void draw( PtWidget t *widget, PhTile t *damage ){

PhRect t rect;

damage = damage;

PtSuperClassDraw( PtBasic, widget, damage );

/* Find our canvas. */PtCalcCanvas( widget, &rect );

/* Clip to our basic canvas (it’s only polite). */PtClipAdd( widget, &rect );

/* Do our drawing... */PgSetStrokeColor( Pg RED );PgDrawRect( &rect , Pg DRAW STROKE );rect.ul.x++;rect.ul.y++;rect.lr.y--;rect.lr.x--;



PgSetStrokeColor( Pg WHITE );PgDrawRect( &rect , Pg DRAW STROKE );

/* Remove our clipping */PtClipRemove();

}

For more information, see the Raw Drawing and Animation chapterof the PhotonProgrammer’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)

Thedamage argument points to a linked list ofPhTile t structures(see the PhotonLibrary Reference) that identify which areas of thewidget have been damaged.


For more information, see the Raw Drawing and Animation chapterof the PhotonProgrammer’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





PtRawList 2005, QNX Software Systems Ltd.

A 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 thanPtList 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.

UsePtGenListAddItems() 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. . .


2005, QNX Software Systems Ltd. PtRawList


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

This function is of typePtRawListDrawBackgroundF 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 aPhRect t structure (see the PhotonLibrary Reference) that defines the widget’s canvas.

empty A pointer to aPhRect 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 isNULL, the widgetuses the default function defined forPtGenList.



This function is of typePtRawListDrawF 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 thePtGenListItem 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 aPhRect t structure (see the PhotonLibraryReference) that defines the extent of the items. Thefunction can modify the structure pointed to bywhere, 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 thePt 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 thePt 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 forPtGenList.

This function is of typePtRawListInflateF 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 thePtGenListItem 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 aPhArea 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 isNULL, thewidget uses the default function defined forPtGenList.

This function is of typePtRawListKeyF 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 thePhEvent t structure (see the PhotonLibrary Reference) that describes the event.

kev A pointer aPhKeyEvent t structure that describes theevent data, which the function can modify.

newcur A pointer to thePtGenListItem 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 ThePtGenList class processes the data containedin thePhKeyEvent 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 returnPt CONTINUE immediately.

Pt HALT The event is consumed by the widget, butPtGenList itself doesn’t take any further action.The class’s raw callbacks returnPt ENDimmediately.

Pt ARG RAWLIST MOUSE F



A function that’s called to handle mouse events if the mouse points toan item. If this resource isNULL, the widget uses the default functiondefined forPtGenList.

This function is of typePtRawListMouseF 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 thePtGenListItem 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 aPhPoint t structure that gives the mouseposition relative to the item. The function can modify thestructure pointed to bywhere.



column The column number.

event A pointer to thePhEvent t structure (see the PhotonLibrary Reference) that describes the event.

This function must return one of the following values:

Pt CONTINUE ThePtGenList class processes the data containedin thePhKeyEvent 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 returnPt CONTINUE immediately.

Pt HALT The event is consumed by the widget, butPtGenList itself doesn’t take any further action.The class’s raw callbacks returnPt ENDimmediately.

Pt ARG RAWLIST SELECT F



A function that’s called when an item is selected or unselected. If thisresource isNULL, the widget uses the default function defined forPtGenList.

This function is of typePtRawListSelectF 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 aPtGenListItem 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 thePhEvent 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 aPtRawList, thecbinfo->cbdata is apointer to aPtGenListDndCallback 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 forPtGenList

when working with aPtRawList.


PtRawTree 2005, QNX Software Systems Ltd.

A 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 thanPtTree 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


2005, QNX Software Systems Ltd. PtRawTree



A function that’s called to draw the widget. If this resource isNULL,the default function forPtGenTree is called.

This function is of typePtRawTreeDrawItemF 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 thePtGenTreeItem t structure for theitem that needs to be redrawn.

where A pointer to aPhRect 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.

ThePtGenTree List Draw method is responsible for drawing thelines and boxes representing the tree structure. This function shoulddraw only the item.



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 forPtGenTree is called.

This function is of typePtRawTreeInflateF 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 thePtGenTreeItem 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 aPhArea 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 isNULL, the default function forPtGenTree is called.

This function is of typePtRawTreeSelectF 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 aPtGenTreeItem 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 aPhEvent 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 isNULL, the default function forPtGenTree is called.

This function is of typePtRawTreeItemStateF 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 thePtGenTreeItem t structure for theitem that’s being collapsed or expanded.

PhEvent t *event

A pointer to aPhEvent t structure (see the PhotonLibrary Reference) that describes the event.

int reason EitherPt 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 itsPt 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 byPtGenTree, 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 aPtRawTree, thecbinfo->cbdata is apointer to aPtTreeDndCallback t structure, containing at leastthe following members:




A pointer to thePtGenTreeItem 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 forPtGenTree

when working with aPtRawTree.


PtRect 2005, 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 thePt ARG POINTSresource. These points are relative to the widget’sPt ARG ORIGIN.For more information, seePtGraphic.

If you don’t setPt ARG POINTS, the rectangle defaults to the sizedefined byPt ARG POS andPt ARG DIM (seePtWidget).

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 usingthePt ARG RECT ROUNDNESS resource.

New resources:


2005, 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. . .


2005, 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






2005, QNX Software Systems Ltd. PtRegionA Photon region

Class hierarchy:PtWidget → PtBasic → PtContainer → PtRegion


� PtServer

PhAB icon:None — instantiate it by callingPtCreateWidget().

Public header:<photon/PtRegion.h>

Description:PtRegion is ideal for controlling a region without foregoing theconvenience of the Photon widget library interface. WithPtRegion,you can control a region without having to modify the standard mainloop function.

For more information about regions, seePhRegion 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 2005, 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 PhotonLibrary 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>.


2005, QNX Software Systems Ltd. PtRegion

ThePh REGION HANDLE, Ph REGION ORIGIN, andPh REGION RECTbits 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 changePtRegion’s Pt ARG POS or Pt ARG AREAresource, thePh REGION ORIGIN bit is changed automatically.

ThePh 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 changePtRegion’s Pt ARG AREA or Pt ARG DIMresource, thePh REGION RECTbit 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 INPUTGROUPREGION

� Ph AUXPTR REGION

� Ph FORCEFRONT

� Ph FOLLOW IG SIZE

� Ph FORCEBOUNDARY

� Ph NO COMPRESSION

� Ph CURSORSET

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 openedbehind. 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, seePhEvent t in the PhotonLibrary 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, seePhEvent t in the PhotonLibrary Reference.












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






PtScrollArea 2005, 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 andPt ARG SCROLLAREA MAX Yresources.

Any anchorable children of aPtScrollArea 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.


2005, 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, thePt 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), wherexmaxandymax 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 theAlt 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 andPt 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 byAlt-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,usePt 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,usePt 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 thePt 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 aPhEvent t structure that describes theevent that caused the callback to be invoked, orNULL ifthere’s no event.

cbdata A pointer to aPtScrollAreaCallback 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 GETSFOCUS|Pt HIGHLIGHTED | Pt SET|Pt REGION












continued. . .









Pt ARG POS PtWidget











Pt CB ARM PtBasic






Pt CB DND PtWidget

continued. . .









Pt CB MENU PtBasic


Pt CB RAW PtWidget





Convenience functions:ThePtScrollArea widget defines the following conveniencefunction:

PtScrollAreaCanvas()

Get the viewport canvas, as opposed to the widget canvas


2005, 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. ThePtScrollArea canvas rectangle describesthe areainside the widget’s border; the viewport’s canvas is the areainside the scrollbars. Therect argument must point to aPhRect t

structure; if you passrect asNULL, the function returnsNULL.

Returns:A pointer to the viewport’s canvas, orNULL if an error occurs.


Safety


Signal handler No

Thread No

See also:PhRect t in the PhotonLibrary Reference


PtScrollbar 2005, 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.


2005, 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 thePt 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 theCtrl 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 forPt 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 thePt 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 aPtScrollbarCallback 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 hasthePt 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 GETSFOCUS|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

continued. . .





Pt ARG ORIENTATION PtGauge Pt VERTICAL



Pt ARG POS PtWidget








Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic

continued. . .





Pt CB RAW PtWidget





The threshold value for graphics bandwidth (as reported byPtQuerySystemInfo()) that defines a slow connection.


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

consider creating your own subclass ofPtScrollArea 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’svisible area.

Children of the scrollable area are anchored to itsvirtual area.

The scrollable area’sPt ARG SCROLLCONT RESIZE FLAGSspecify the resize policy that’s applied to itsvirtual area. You can setthe virtual area’s size directly by modifying the resources associatedwith it. Otherwise, the area changes only under the followingconditions:

� ThePt 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 callPtExtentWidget() on the scrollable areaafter the change.

Other layouts are possible by making another container, such as agroup widget, a child of the scrollable area.

New resources:


2005, QNX Software Systems Ltd. PtScrollContainer


Pt ARG SCROLLCONT FLAGS uint16 t Flags Pt SCROLLCONTTRACK FOCUS

Pt ARG SCROLLCONT RESIZE FLAGS long Flags Pt RESIZEXY AS REQUIRED

Pt ARG SCROLLCONT FLAGS


uint16 t Flags Pt SCROLLCONTTRACK FOCUS

Flags that control the appearance and behavior of the widget. Thedefined bits include:

Pt SCROLLCONTTRACK FOCUS

Pan to accommodate the focused child as focus changes.

Pt ARG SCROLLCONT RESIZE FLAGS


long Flags Pt RESIZEXY AS REQUIRED

Flags that control the resizing of the virtual area. The defined bits arethe same as those defined forPt ARG RESIZE FLAGS:

� Pt RESIZEX AS REQUIRED

� Pt RESIZEX ALWAYS

� Pt RESIZEX INITIAL

� Pt RESIZEX BITS

� Pt RESIZEY AS REQUIRED

� Pt RESIZEY ALWAYS

� Pt RESIZEY INITIAL



� Pt RESIZEY BITS

� Pt RESIZEXY ALWAYS

� Pt RESIZEXY AS REQUIRED

� Pt RESIZEXY INITIAL

� Pt RESIZEXY BITS



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













continued. . .









Pt ARG DIM PtWidget






Pt ARG FLAGS PtWidget |=Pt GETSFOCUS|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



continued. . .









Pt CB ARM PtBasic






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget




continued. . .




Pt CB SCROLLAREA SCROLLED PtScrollArea



2005, QNX Software Systems Ltd. PtSeparatorSeparator 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:


PtSeparator 2005, QNX Software Systems Ltd.


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 aPhBitmapCursorDescription 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 thehdr member of thePhBitmapCursorDescription t andPhBitmapCursorData t

structures.

The PhBitmapCursorDescriptiont contains at least these members:


2005, QNX Software Systems Ltd. PtSeparator

hdr A PhCursorDescription t structure that isautomatically filled in by the widget.

bmp A PhBitmapCursorData t structure that describes thebitmap.

ThePhCharacterCursorDescription t contains at least thesemembers:

hdr A PhCursorDescription t structure.

color A PgColor t structure that describes the backgroundcolour of the bitmap.

ThePhBitmapCursorData t contains at least these members:

hdr A pointer to aPhRegionDataHdr 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 CURSORDEFAULT COLOR

A PgColor t structure that defines the color for the cursor specifiedby thePt ARG SEP ARM CURSOR TYPE, which is used when theseparator is armed and being dragged. For more information, seePgColor t in the PhotonLibrary Reference.

Pt ARG SEP ARM CURSOR TYPE


unsigned short Scalar Ph CURSORINHERIT

The cursor type which is used when the separator is armed and beingdragged. It can be:

Ph CURSORINHERIT

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 CURSORBITMAP

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 thePt SEPDRAGGABLE 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 SEPHORIZONTAL

Flags that control the separator’s appearance. Possible values:

Pt SEPORIENTATION

If this bit is Pt SEPVERTICAL, the separator is vertical. If thisbit is Pt SEPHORIZONTAL, the separator is horizontal.

Pt SEPDRAGGABLE

The separator can be dragged within its parent’s canvas, or bythe bounding rectangle specified by via tthePt SEP DRAG BOUNDS resource.

Pt SEPDRAW 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 toNULL to disableimage drawing. For more information aboutPhImage t, see thePhotonLibrary 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 PtCallbackt structures that define the callbacks involvedwhen you drag the separator widget.

Each callback is passed a PtCallbackInfot structure that contains atleast the following members:

reason Pt CB SEPDRAG

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 theevent member tofind out more details.


cbdata A pointer to aPtSeparatorCallback t structurewhich contains at least containsPhRect t, a separatorrectangle relative to its parent.








Pt ARG BANDWIDTH THRESHOLD PtBasic See below.













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





Pt ARG BANDWIDTH THRESHOLD defines the"graphicsbandwidth" threshold over which the separator drag mode is switchedto drag outline mode, as if thePt SEPDRAW DRAG BAND flag wasset. This optimizes the number of events in low bandwidth situations,such as when you are usingphrelay. Note that this resource onlyapplies when the separator is draggable.

By default this resource is set toPh BAUD NETWORK.



For more information about the system bandwidth, seePtQuerySystemInfo() andPhSysInfo t in the PhotonLibraryReference.


PtServer 2005, QNX Software Systems Ltd.

Server widget

Class hierarchy:PtWidget → PtBasic → PtContainer → PtRegion →PtServer

PhAB icon:None — instantiate it by callingPtCreateWidget().

Public header:<photon/PtServer.h>

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

PtClient andPtServer use a Photon connection to communicate(see “Connections” in the Interprocess Communications chapter ofthe PhotonProgrammer’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 thePtClient it’sattached to. The contents can be any widgets you choose to put inyourPtServer widget. Additionally,PtServer lets yourapplication send arbitrary messages to the client process.

When aPtServer is attached to aPtClient, 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 aPtServer widgetthat’s connected to a client. Don’t exit from an application that hasactivePtServer 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 itsPtClient widget instead.

☞


2005, 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’sNULL.

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 aPtServer widget and gives the newconnection object to itsPt ARG SERVER CONNECTION resource(seePtConnectorCreate() in the PhotonLibrary Reference for moredetails about connectors).

In a server that just creates onePtServer 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 theclientPtClient that invokes thePt 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 SERVERCONNECTED

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 SERVERERROR

reason subtype

0 (not used).


cbdata A pointer to aPtServerErrorCallback t structurethat contains at least:

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

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

☞

� int errnum — theerrno value from the error handler.

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



If this value isPt CONNECTION SERVERBROKEN, 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 SERVERRECEIVE

reason subtype

0 (not used).


cbdata A pointer to aPtServerCallback 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 thePtClient that thePtServer 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 SERVERTRANSPORT

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 ARG REGION FIELDS PtRegion 0x00000018

Pt ARG REGION FLAGS PtRegion

Pt ARG REGION INFRONT PtRegion

continued. . .




Pt ARG REGION INPUT GROUP PtRegion

Pt ARG REGION OPAQUE PtRegion 0x00210EF8

Pt ARG REGION PARENT PtRegion

Pt ARG REGION SENSE PtRegion 0x00290240











Pt CB ARM PtBasic








Pt CB DND PtWidget

continued. . .










Pt CB MENU PtBasic


Pt CB RAW PtWidget






PtSlider 2005, QNX Software Systems Ltd.

A widget for choosing a value from a range

Class hierarchy:PtWidget → PtBasic → PtGauge → PtSlider

PhAB icon:

Public header:<photon/PtSlider.h>

Description:A PtSlider widget lets you choose numerical values within 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.


2005, QNX Software Systems Ltd. PtSlider

A PtSlider widget with a custom handle and trough.

You need to setPt 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 theCtrl 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. . .




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 andPt ARG GAUGE FLAGS resourcesinherited fromPtGauge.

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 byPt 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. SeePgColor t in the PhotonLibraryReference.

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 thePhImage t structure, see the PhotonLibraryReference.

The widget ignores this resource unless you setPt 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 pressPg 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 asPt ARG SLIDER TROUGH IMAGE1.

The widget ignores these resources unless you setPt SLIDER TROUGH IMAGE in Pt ARG SLIDER FLAGS.

☞

If you specify justPt 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 byPt 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 thePt ARG GAUGE FLAGS resource(inherited fromPtGauge), 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 fromPtGauge). Youshould create horizontal images for a horizontal slider, and verticalimages for a vertical slider.

☞

For more information about thePhImage 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 thePt CALLBACKS ACTIVE bit set in the widget’sPt ARG FLAGS resource, these callbacks are also invoked when yourapplication changes the handle position by callingPtSetResource() 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 aPtSliderCallback 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 GETSFOCUS

Pt ARG GAUGE FLAGS PtGauge |=Pt GAUGE MAX ON TOP

Pt ARG GAUGE FONT PtGauge

Pt ARG GAUGE H ALIGN PtGauge Not used by this class.

Pt ARG GAUGE V ALIGN PtGauge Not used by this class.


Pt ARG GAUGE VALUE PREFIX PtGauge Not used by this class.

Pt ARG GAUGE VALUE SUFFIX PtGauge Not used by this class.



continued. . .












Pt ARG MAXIMUM PtGauge


Pt ARG MINIMUM PtGauge


Pt ARG ORIENTATION PtGauge Pt HORIZONTAL



Pt ARG POS PtWidget








continued. . .




Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget





PtTab 2005, QNX Software Systems Ltd.

A tab button for initiating an action

Class hierarchy:PtWidget → PtBasic → PtLabel → PtTab

PhAB icon:

Public header:<photon/PtTab.h>

Description:ThePtTab 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 aPtTab, you should use aPtPanelGroup. This isthe preferred method, sincePtPanelGroup manages all aspects of atabbed panel for you.

If you insist on usingPtTab widgets, you typically:

� Group the tabs together and set thePt GROUPEXCLUSIVE bit inthePtGroup widget’sPt ARG GROUP FLAGS resource. Thisflag allows only one of the tabs to be set at a time.

� Use otherPtGroup 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 PhotonProgrammer’s Guide.

� Place the tabs at the top of aPtPane or some other container. Usethe same border width for the tabs and the container, and line up


2005, QNX Software Systems Ltd. PtTab

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 PhotonProgrammer’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).



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 PhotonLibrary Reference.

When the tab is set, it gets its color fromPt 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 LABEL FLAGS PtLabel &=˜Pt LABEL SELECT SHIFT
















Pt ARG POS PtWidget




continued. . .
















Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic

continued. . .





Pt CB RAW PtWidget




Convenience functions:ThePtTab 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 2005, 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:ThePtTerminal class provides a text window emulating a characterterminal.

A PtTerminal widget.

You can send characters to the terminal by callingPtTerminalPutc(),PtTerminalPut() andPtTerminalPuts(). If you type in the terminal, the


2005, QNX Software Systems Ltd. PtTerminal

keyboard input is passed to the widget via thePt 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, seedevc-con in theQNX NeutrinoUtilities Reference.

PtTerminal uses someCtrl – Alt combinations for cutting andpasting, changing font sizes, and so on, but allAlt-key combinationsthat are defined for text mode are passed to your text-modeapplication, provided that the window manager letsPtTerminal seethem.

The window manager intercepts certainAlt-key combinations unlessyou setPh WM STATE ISALTKEY in thePt ARG WINDOW STATEresource of thePtWindow that contains thePtTerminal.

☞

PtTerminal and PtTty

The main difference betweenPtTerminal andPtTty is thatPtTerminal doesn’t do any I/O for you. The only way to displaycharacters in aPtTerminal is by giving them to one of thePtTerminalPut*() functions. Similarly, the only thingPtTerminaldoes 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 toPtTerminalPut() ispart ofPtTty. Similarly,PtTty attaches aPt CB TERM INPUT



callback that writes Photon keyboard input (translated byPtTerminal to text-mode compatible format) to the pty.

Another responsibility ofPtTty is spawning a command for you andinvoking thePt CB TTY TERMINATED callbacks when thecommand terminates.

Fonts

Your application program can usePt ARG TERM FONT to set anexplicit font name, orPt ARG TERM FONT INDEX to choose a fontfrom the list of supported fonts,Pt ARG TERM FONT LIST.

If you set thePt TERM KBFONT bit in Pt ARG TERM RESIZE FL,you can select a font using the keyboard:

� PressCtrl – 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).

� PressCtrl – Alt – > or Ctrl – Alt – ] to increment the value ofPt ARG TERM FONT INDEX by one (unless it’s already at themaximum value).

ThePt TERM KBFORCEflag 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 thePt TERM OPFONTflag, you can use escapesequences to set the font:

� If you usePt 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 thePt 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 toPtTerminalPut() 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 fordevc-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:PtTerminal

translates only codes above0x7F.

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.

ThePt ARG TERM CHARSETS resource stores the current charactersets.

Resource changes and function reentrancy

When thePtTerminalPut*() 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 thePtTerminalPut*() 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,thePtTerminalPut*() 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 andPt ARG AREA (seePtWidget)

Margins Pt ARG MARGIN HEIGHT,Pt ARG MARGIN WIDTH (seePtBasic), 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



Resizing

A widget’s dimensions can be calculated as long as terminal size, fontsize, 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 theresize function)determines how the widget is resized. The function is called with twooutput arguments: the first is a pointer to astring that describes whichresource is changing and how, and the second is the value of widget’sPt ARG TERM RESIZE STR resource.

Each character in thestring has a specific meaning. The first characteris a resource identifier that describes which resource is changing:

D (dimension) ChangePt ARG DIM andPt ARG AREA.

M (margin) ChangePt ARG MARGIN WIDTH andPt ARG MARGIN HEIGHT.

S (size) ChangePt ARG TERM SIZE,Pt ARG TERM ROWS, andPt ARG TERM COLS.

F (font) ChangePt ARG TERM FONT.

The next series of characters provide the details, starting with thecharacterx 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.

continued. . .



Character Meaning

= 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. Anm means that the adjustment must involve aresource other than the margins, and ans means that the adjustmentmust involve a resource other than the terminal size.

Adjusting after a resize

The result of the “resize function” is a string specifying the order ofthe 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 thePt ARG DIM resource.

s Adjust thePt ARG TERM SIZE resource.

m Adjust thePt ARG MARGIN WIDTH and/orPt ARG MARGIN HEIGHT resource and copy the new valueto thePt ARG TERM MARGINS resource.

M Adjust thePt 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/orPt 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 ad is always superfluous and specifying anything after ad

has no effect unless it specifies a different direction.

The default resize function

The default function uses only the resource identifier (i.e.D, M, S or F)given in the first argument. The function assumes that 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 thePt 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 thePt 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 thePt ARG TERM CONSOLE writesdata directly to the widget’s screen buffer.

First, your application should fill aPtTerminalConsoleWrite 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 toPtSetArg().When you callPtSetResources(), the widget transfers the actualscreen 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 getPt 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

ThePt ARG TERM COLOR TABLE resource is an array used by thewidget for mapping color numbers into PhotonPgColor t colorvalues (see the PhotonLibrary Reference). Color numbers are indexesinto this array. The default array has 16 elements corresponding to 16standard CGA colors.

Pt ARG FILL COLOR (seePtBasic) defines the color of themargins.

The background color of the terminal defaults to black — or whateverthePt 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 usingPtTerminalPut(). The latter isprobably safer if the widget is aPtTty 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

ThePt ARG TERM DRAW MODES resource defines the widget’sscrolling capability.

Scrolling optimization

If your application gives characters toPtTerminalPut() in a largeportion that consists of many lines that scroll through the terminal, thewidget may attempt to optimize drawing speed.

Instead of blittingh-1 lines (whereh is the height of the terminal inlines) and drawing the bottom line on each scroll, the widget blitsh-nlines (if h-n is positive) and drawsmin(h,n) lines everyn scrolls.

The limit for the actual value ofn is determined byPt ARG BANDWIDTH THRESHOLD (seePtBasic),Pt ARG TERM SCROLL, andPt ARG TERM DRAW MODES, andby the current graphics bandwidth (seePhQuerySystemInfo() in thePhotonLibrary Reference). If the connection is slow and thePt TERM SCROLL NOSPEEDCHKbit inPt ARG TERM CURSOR FLAGS is clear, there’s no limit forn.Otherwise, the maximal value ofn is the value of thePt ARG TERM SCROLL resource.

Drag and Drop


New resources:


Pt ARG TERM ANSI PROTOCOL int Boolean 1

continued. . .




Pt ARG TERM APP PtTerminalAppState t Struct See below

Pt ARG TERM CHARSETS PtTerminalCsXlatData t * Pointer See below

Pt ARG TERM COLOR MODE PtTerminalColorMode t Struct Pt TERM COLOR MODE

Pt ARG TERM COLOR TABLE PgColor t[], short Array CGA colors, 16

Pt ARG TERM COLS short Scalar 80

Pt ARG TERM CONSOLE PtTerminalConsoleWrite t Complex N/A

Pt ARG TERM CUR COL short Scalar 0

Pt ARG TERM CUR POS PtTerminalRowCol t Struct 0, 0

Pt ARG TERM CUR ROW short Scalar 0

Pt ARG TERM CURSOR FLAGS short Flag Pt TERM CURSORON 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

continued. . .




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

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 thePt CB TERM APP callback). Thisstructure also contains some other information that a terminalemulator can use, such as the window title, size, and position.

ThePtTerminalAppState 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 thanpterm, A text-mode



program 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 istitle — pterm uses it to set its window title.

If you have a text-mode program that needs a terminal emulator otherthanpterm, you’ll need to use thePt ARG TERM APP resource andthePt 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 inapterm (version=100) or in your emulator(version=something else).

b.area The area of thePtTerminal 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 aPtTerminalCsXlatData t structure.The contents of the structure aren’t defined in a public header — theonly way to create aPtTerminalCsXlatData t structure is bycallingPtTerminalCreateCsXlat().

If you setPt ARG TERM CHARSETS to NULL, the widget callsPtTerminalCreateCsXlat() to create its own copy of the defaulttranslation tables. This copy is freed when you destroy the widget orset itsPt ARG TERM CHARSETS resource to a non-NULL value.

PtTerminalCreateCsXlat() doesn’t make a copy of thePtTerminalCharsets t structure passed to it, andPtTerminaldoesn’t make a copy of thePtTerminalCsXlatData t structurewhen you setPt ARG TERM CHARSETS. Don’t free or modify thesestructures until they’re no longer needed by any widget.

ThePtTerminalCsXlatData t structure created byPtTerminalCreateCsXlat() is placed in a single allocated block ofmemory. When it’s no longer needed, you can simplyfree() 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. SeePgColor 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

continued. . .



Index Color

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. ThePtTerminalRowCol 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 CURSORON FOCUS

Flags affecting the cursor timer. Possible values are:

� Pt TERM CURSORON FOCUS— the cursor blinks when thewidget has focus.

� Pt TERM CURSORALWAYS — the cursor always blinks.

� Pt TERM CURSORNEVER (zero) — the cursor never blinks.

� Pt TERM CURSORTIMER — 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 CURSORNOSPEEDCHK— 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 ifPhBlit() won’t be used.

� Pt TERM SCROLL NOVISCHK — always assume that the widgetisn’t clipped or obscured by other widgets. (Normally, the widgetchecks to see if it it’s obscured or clipped by other widgets in sucha way that usingPhBlit() 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 thePt ARG BANDWIDTH THRESHOLD resource, the widgetbehaves as if thePt TERM SCROLL NOBLIT,Pt TERM SCROLL NOHWCHK, andPt TERM SCROLL RFSHflagsare clear and thePt 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 thevalue argument of thePtSetArg() macro depends on whether thelen argument is zero ornonzero:

� If len is nonzero,value should be a pointer to an array of pointersto font names, andlen 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 eitherNULL 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 PhotonLibrary Reference) that definesthe dimensions of the font used for the display.



Pt ARG TERM MARGINS (read-only)



A PhRect t structure (see the PhotonLibrary Reference) thatcontains the actual width and height of the widget’s margins. Thesevalues are equal to or greater than values ofPt ARG MARGIN WIDTH andPt 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 inPt ARG TERM OPTIONS.Clearing a bit inPt ARG TERM OPTMASK disables the escapesequence for the corresponding bit inPt 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 thePt 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

ThePtTerminalSelection 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 oftype 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(readonly) — 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 andlast isthe position of the release. ThePtTerminalRowCol t

structure contains the following members:

� short r

� short c



Pt ARG TERM SIZE



The screen size, in characters. ThePtTerminalRowCol 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 thePt ARG TERM APP resource changes, or a privateescape sequence is received.


reason Pt CB TERM APP

reason subtype

The character or number defining thetype of escapesequence.



event NULL

cbdata Either aNULL pointer, or the string contained in theescape sequence.

There are four general sources of thePt CB TERM APP callback.They can be recognized by the values of thereason subtype andcbdata fields:

reason subtype=0, cbdata=NULL

A change of terminal’s size or font. Before issuing thiscallback, the widget sets thearea andsize fields of thePt ARG TERM APP resource to the values of the widget’sPt ARG AREA andPt 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 thePt ARG TERM APP resource.

reason subtype=nonzero,cbdata=NULL

An escape sequence that set some of the data stored in the“binary” part of thePt 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 inthePt ARG TERM APP resource.

The value of thereason subtype field is the ASCII code of thecharacter that indicates the escape sequence type, and thecbdata 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 aPtTerminalFontChange 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 aPtCallbackInfo 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 theBreak key.

� Pt TERM MOUSE INPUT — for mouse events.

� Pt TERM CTRLBRK INPUT — for theBreak key.

� Pt TERM PROTOCOLINPUT — for responses to anescape sequence.

� Pt TERM PASTEINPUT — for pasting from theclipboard.

� Pt TERM PASTENF INPUT — for pasting from theclipboard.

event A pointer to aPhEvent t structure that describes theevent that caused the callback to be invoked, orNULL ifthe characters are a reply to an escape sequence ratherthan reaction to a keyboard or mouse event.

cbdata A pointer to aPtTerminalInput 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. ThePtTerminalRowCol t structurecontains the following members:

� short r

� short c



The widget issues this callback on every keystroke unless bothCtrlandAlt modifiers are pressed.

When text is being pasted from the clipboard, the callback subtype isset toPt TERM PASTEINPUT 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 PASTENF INPUT.


Pt CB TERM OPTIONS



A list of PtCallback t structures that define the callbacks invokedwhenever thePt ARG TERM OPTIONS resource changes. Eachcallback is passed aPtCallbackInfo 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 aPtTerminalOptionChange 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 aPtTerminalSizeChange 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.

ThePtTerminalRowCol t structure contains thefollowing members:

� short r

� short c

This callback is issued whenever one of thePt 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 callsPtSetResources() with invalid sizevalues (outside of limits defined byPt 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 aPtTerminalSizeChange 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 thePt 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 withcbdata set toNULL.




Pt CB TERM SCRLBK



A list of PtCallback t structures that define the callbacks invokedwhenever thePt ARG TERM SCRLBK POS resource or the numberof saved lines in the widget’s buffer changes. Each callback is passedaPtCallbackInfo t structure that contains at least the followingmembers:

reason Pt CB TERM SCRLBK

reason subtype

0

event NULL

cbdata A pointer to aPtTerminalScrlbkCb 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



continued. . .







The threshold value for graphics bandwidth (as reported byPhQuerySystemInfo()) that defines a slow connection. For moreinformation, seePt ARG TERM CURSOR FLAGS and “Scrollingoptimization,” above.

Pt ARG FILL COLOR

The color of widget’s margins. When set toPt 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:ThePtTerminal 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 byPtTerminal

PtTerminalCopy()

Copy the current selection to the clipboard.

PtTerminalCreateCsXlat().

Create a translation table forPtTerminal’s character sets.



PtTerminalDefaultCharsets():

Get the default character sets used byPtTerminal.

PtTerminalFontInfo()

Examine a font.

PtTerminalGetKeys()

Get the terminal line-editing keys.

PtTerminalGetSelection()

Get a copy of the current selection.

PtTerminalName()

Get the terminal’stermcap/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 2005, 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:ThePtTerminalCharset t andPtTerminalCharsets 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;


2005, 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 from0x80 to 0xFF andthe ANSI character set should define all values from0xA0 to 0xFF.

You can setAnsiCharset or InternalCharset (or both) toNULL; thefunction then uses the defaults (8859-1 forAnsiCharset and PCcharacter set forInternalCharset). It’s also possible to get to theactual tables that define the defaults by callingPtTerminalDefaultCharsets():

const PtTerminalCharsets t *PtTerminalDefaultCharsets( void );

TheFontTranslation defines the mapping from the internal characterset to whatever character set your Photon font is using. In otherwords, ifFontTranslation isn’t NULL, PtTerminal uses the 16-bitcode returned by:

unicode value( internal char, FontTranslation )

to display the 8-bit internal codeinternal char. Note that if you wantthe widget to use Unicode,FontTranslation should point to the samecharacter set asInternalCharset.

If FontTranslation is NULL, the font is assumed to be compatible withthe internal character set, and no mapping is used.

TheSubst 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 2005, QNX Software Systems Ltd.

it needs to be translated to. The array must be sorted with the respectto thefrom 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 searchestheSubst array for an entry wherefrom is the character in the eventandto is a character that exists in the text-mode character set. Ifsuch an entry exists, theto 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, theSubstarray is searched for a replacement character. If none is found, thecharacter is displayed as a space.


See also:PtTerminal, PtTerminalDefaultCharsets()


2005, 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 givenPtTerminal

widget to the clipboard. Theevent parameter is used to select theinput group; seePhClipboardCopyString() in the PhotonLibraryReference.


Safety


Signal handler No

Thread No

See also:PtTerminal



PtTerminalCreateCsXlat() 2005, 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. ThePtTerminalCsXlatData t structure is forinternal use only; you must use this function to create it.

Thecsets argument is a pointer to aPtTerminalCharsets t

structure that defines the character sets and their translation.

Returns:A pointer to aPtTerminalCsXlatData t structure that you canuse to set thePt ARG TERM CHARSETS resource of aPtTerminalwidget.

PtTerminalCreateCsXlat() doesn’t make a copy of thePtTerminalCharsets t structure pointed to bycsets, 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.

ThePtTerminalCsXlatData t structure created byPtTerminalCreateCsXlat() is placed in a single allocated block ofmemory. When it’s no longer needed, you can simplyfree() it.

☞


Safety


continued. . .


2005, QNX Software Systems Ltd. PtTerminalCreateCsXlat()

Safety

Signal handler No

Thread No

See also:PtTerminal, Pt ARG TERM CHARSETS,PtTerminalCharsets t


PtTerminalDefaultCharsets() 2005, 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 byPtTerminal.

Returns:A pointer to the tables.


Safety


Signal handler No

Thread No

See also:PtTerminal, PtTerminalCharsets t


2005, 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() returnsNULL.

This function stores information about the font’s geometry atlocations pointed to bysize andoffs:

� If size isn’t NULL, the width and height of the character cell arestored in thePhDim t structure (see the PhotonLibraryReference) it points to.

� If offs isn’t NULL, the function stores, in thePhPoint 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() 2005, QNX Software Systems Ltd.

See also:PtTerminal


2005, 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 thebuf ->c cc array withvalues appropriate for the givenprotocol:

� VPREFIX

� VSUFFIX

� VLEFT

� VRIGHT

� VUP

� VDOWN

� VINS

� VDEL

� VHOME

� VEND

The other fields of the structure aren’t modified. For moreinformation, see thePt ARG TERM ANSI PROTOCOL resourceassociated with thePtTerminal widget.



PtTerminalGetKeys() 2005, QNX Software Systems Ltd.

Safety


Signal handler No

Thread No

See also:PtTerminal


2005, 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 (orNULL ifthere’s no selection).

It’s your application’s responsibility tofree() the buffer when it’s nolonger needed.

☞


Safety


Signal handler No

Thread No

See also:PtTerminal


PtTerminalName() 2005, 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 ofqnxm or qansi-m),based on the givenprotocol.

For more information, see thePt ARG TERM ANSI PROTOCOLresource associated with thePtTerminal widget.


Safety


Signal handler No

Thread No

See also:PtTerminal


2005, 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’sPt CB TERM INPUT callback.The given event is passed to the callback functions. Ifevent isn’tNULL, event->input group also selects the clipboard; seePhClipboardPasteString() in the PhotonLibrary Reference.


Safety


Signal handler No

Thread No

See also:PtTerminal



PtTerminalPasteSelection() 2005, 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’sPt CB TERM INPUT callback.The givenevent is passed to the callback functions.


Safety


Signal handler No

Thread No

See also:PtTerminal



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

See also:PtTerminal


2005, 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 ifpos is NULL).

ThePtTerminalRowCol 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 Thepos argument is invalid (i.e. beyond the screen size).


Safety


Signal handler No

Thread No


PtTerminalSelectWord() 2005, QNX Software Systems Ltd.

See also:PtTerminal


2005, 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 2005, 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 theShiftkey 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 thePt ARG TEXT STRING resource(inherited fromPtLabel).

Setting text

When you set the widget’s text usingPt ARG TEXT STRING, youmust give a null-terminated C string as a value.


2005, QNX Software Systems Ltd. PtText

The following short program creates a text widget whose initialcontents are the string “hello, world...”:

#include <Pt.h>

PhArea t area = { {0, 0}, {200,40} };

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

PtAppContext t app;int nargs = 0;PtArg t args[4];PtWidget t *window;


PtSetArg(&args[nargs++], Pt ARG POS, &area.pos, 0);PtSetArg(&args[nargs++], Pt ARG DIM, &area.size, 0);PtSetArg(&args[nargs++], Pt ARG WINDOW TITLE, "hello", 0);if ((window = 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();

}

Getting text

You can retrieve the widget’s text as a null-terminated C string bygetting the value of thePt ARG TEXT STRING resource with thePtGetResources() function.

For more information, see “Getting resources” in the ManipulatingResources in Application Code chapter of the PhotonProgrammer’sGuide.



Getting the current selection

You can obtain the range of characters in the current selection byusing thePtTextGetSelection() 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.

Replacing text

Your application can change any block of text in the widget by callingPtTextModifyText(). 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 itsPt ARG FLAGS resource, thesecallbacks are also invoked when your application changes the text ischanged by callingPtSetResource(), PtSetResources(), or aconvenience function such asPtTextModifyText(). Thetext-modification callbacks are:

Pt CB MODIFY VERIFY

Called before any changes are made to the text.

Pt CB MODIFY NOTIFY (also known asPt CB TEXT CHANGED)Called after a change.



Validation

ThePt CB MODIFY VERIFY callback is useful for validatingchanges 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 thecbdatamember of thePtCallbackInfo t structure passed to it. Thecbdata member is a pointer to a text-callback structure. This is aPtTextCallback t structure if the widget is aPtText, and aPtMultiTextCallback t structure if the widget is aPtMultiText widget.

The following example shows how thetext member of the abovestructure can be modified to alter the text inserted into the widget. Theexample uses theallcaps() 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;}

Preventing the modification

You can prevent the text from being added to the widget by setting thedoit member of thePtTextCallback t structure to zero or bysetting thelength member to zero.



Setting the length to 0 stops the widget from inserting the text; itdoesn’t prevent any deletion included in the modification.

☞

Handling deletions

You can determine if a modification is replacing or deleting a block oftext by checkingstart pos andend pos. If these values differ, then ablock of text is being removed from the widget and may potentiallybe replaced by new text contained in thetext member.

Be sure to handle backspaces correctly. As well as checking for adifferent start and end position, an application can determine which ofBackspace or Delete was pressed by checking thelength, cur insert,andnew insert:

� If length is zero, then no text replaces the deleted range — youmost likely pressed theDelete key or the destructive backspacekey.

� If new insert is less thancur insert, you pressed the destructivebackspace key.

� If new insert equalscur insert, you pressed theDelete key.

Example: entering a password

The following simple example of accepting a password as inputillustrates 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 displayedwidget (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;




String changes

After you’ve entered the new text into the widget, thePt CB TEXT CHANGED or Pt CB MODIFY NOTIFY callback listis 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. Thetext 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 thePt GHOSTandPt BLOCKED bitsset in itsPt ARG FLAGS resource (seePtWidget) to give it aninactive or disabled appearance.

2 Attach a callback function to thePt CB TEXT CHANGEDcallback list. Make sure this callback turns off thePt GHOSTandPt 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 fromPtBasic 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 theTab 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 itsPt 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.

ThePt 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 toindicate 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.



Thereason member given in the callback info for this callback isPt CB MOTION VERIFY. Theevent 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 theevent 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).

Theevent member is a pointer to aPhEvent t structure (see thePhotonLibrary Reference) that describes the user’s action. Todifferentiate between a pointer event and a keypress event, look at thetype of that event.

Thecbdata member ofinfo is a pointer to the same type oftext-modification callback structure used by the other text widgetcallbacks. This callback uses thecur insert, new insert, anddoitmembers of the structure. Your application can set thedoit member tozero to prevent the cursor movement from taking place.

Activate callback

ThePtText widget inherits an activate callback fromPtBasic,Pt CB ACTIVATE, that’s invoked when one of the following occurs:

� You press theEnter key within the widget. This signals that anychanges to the field are complete and your application can use thenew value.

Thereason 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. Thetext member of that structurecontains a UTF-8 string indicating the contents of the buffer.

� You click on the widget andPt SELECTABLEis set in itsPt ARG FLAGS. In this case, thereason subtype in the callbackinformation is 0, and the callback is as described forPtBasic.



� You modified the text, moved focus to another widget, andPt CHANGE ACTIVATE is set in the text widget’sPt ARG TEXT FLAGS.

Thereason 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. Thetext member of that structurecontains a UTF-8 string indicating the contents of the buffer.

Thereason 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 theEnter key has the same effect aspressing the dialog’s OK button after entering the new value.

Edit masks

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

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 specifyC#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

continued. . .



If you press: The widget:

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 CURSORVISIBLE

| 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

continued. . .




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 thevalue argument toPtSetArg() to the addressof aPtTextControl t structure. Use thestart pos andend posmembers of the structure to indicate the range of text to behighlighted (selected). Ifend 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 thedoit member to 1.

� When getting, set thevalue to the address of a pointer to aPtTextControl t structure. The widget sets thestart pos andend pos members to hold the currently highlighted selected range.If no range is currently selected,start pos is -1. Don’t free() thisstructure.

Thelen isn’t used when setting or getting this resource.

You can callPtTextGetSelection() 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 CURSORVISIBLE |Pt EDITABLE | Pt INSERT MODE

Valid flags:

Pt CHANGE ACTIVATE

If the text is changed and the widget loses focus,invoke thePt CB ACTIVATE callback with thePt CHANGE ACTIVATE subtype.

For more information, see the description ofPt CB ACTIVATE in “Inherited resources,” below.

Pt CURSORVISIBLE

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. SeePgColor t in the PhotonLibrary Reference.



If you set this resource toPt 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. SeePgColor t in the PhotonLibrary Reference.

If you set this resource toPt 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 thevalue argument toPtSetArg() to the addressof an instance of aPtTextControl t structure that defineswhich 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 callPtTextModifyText().



� When getting, set thevalue to the address of a pointer to aPtTextControl t structure. Set thestart pos andend pos to thebeginning and end of the substring you want. When you get theresource, thelength member is the number of multibyte charactersin the substring, andtext points to the range in the widget’s internalmemory.

You don’t use thelen argument toPtSetArg() 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 thePt CALLBACKS ACTIVE bit in the widget’sPt ARG FLAGS resource, these callbacks are also invoked when yourapplication changes the text is changed by callingPtSetResource(),PtSetResources(), or a convenience function such asPtTextModifyText().


reason Pt CB MODIFY NOTIFY

reason subtype

0 (not used).




cbdata A pointer to aPtTextCallback 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 theNULL).

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 thePt CALLBACKS ACTIVE bit set in the widget’sPt ARG FLAGS resource, these callbacks are also invoked when yourapplication changes the text is changed by callingPtSetResource(),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 atstart pos upto but not includingend pos are beingdeleted. Ifstart pos andend pos areequal, no characters are being deleted.

int cur insert; The position at whichtext 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 atcur insert.

int length; The number of characters to beinserted. Iflength 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. Ifdoit 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 thePt CALLBACKS ACTIVE bit set in the widget’sPt ARG FLAGS resource, these callbacks are also invoked when yourapplication repositions the cursor by callingPtSetResource() orPtSetResources().


reason Pt CB MOTION NOTIFY

reason subtype

0 (not used).


cbdata A pointer to aPtTextCallback 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 thePt CALLBACKS ACTIVE bit set in the widget’sPt ARG FLAGS resource, these callbacks are also invoked when yourapplication repositions the cursor by callingPtSetResource() 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 atcur 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 the



widget. If doit is zero, the cursorremains atcur insert. If doit isnonzero, the cursor will berepositioned atnew insert.




Pt ARG ACCEL KEY PtLabel Not used by this class.














continued. . .







Pt ARG CURSOR TYPE PtWidget Ph CURSORINSERT




Pt ARG DIM PtWidget

Pt ARG EFLAGS PtWidget |= Pt CONSUME EVENTS


Pt ARG FILL COLOR PtBasic Pg GRAY


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








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

Pt ARG LABEL IMAGE PtLabel Not used by this class.

continued. . .




Pt ARG LABEL TYPE PtLabel Not used by this class.




Pt ARG LINE SPACING PtLabel Not used by this class.











Pt ARG POS PtWidget

Pt ARG RESIZE FLAGS PtWidget Pt RESIZEY AS REQUIRED|Pt RESIZEY INITIAL







continued. . .






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.



Pt CB LOST FOCUS PtBasic See below.

Pt CB MENU PtBasic


Pt CB RAW PtWidget


continued. . .






Pt CB ACTIVATE

Pt CB ACTIVATE is inherited fromPtBasic, but its behavior isdifferent for aPtText 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 SELECTABLEset in itsPt ARG FLAGS.

� Pt EDIT ACTIVATE — you pressedEnter in the textfield.

� Pt CHANGE ACTIVATE — you modified the text, gavefocus to another widget, andPt CHANGE ACTIVATE isset in the widget’sPt ARG TEXT FLAGS.


cbdata If reason subtype is 0, the callback data is as describedfor thePt CB ACTIVATE resource forPtBasic.

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 pressedEnter. 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 andPt CB LOST FOCUS are inherited fromPtBasic, but the callback data is different for aPtText widget.Each callback is passed aPtCallbackInfo t structure thatcontains at least the following members:

reason Pt CB GOT FOCUSor Pt CB LOST FOCUS

reason subtype

0 (not used).



� int cur insert — the position of the cursor along thestring at the time the user pressedEnter. 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).

ThePt CB GOT FOCUS callbacks should returnPt CONTINUE.

ThePt CB LOST FOCUS callbacks should return:




Or:


Convenience functions:ThePtText 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 toPtText callbacks


Get the selected range from aPtText widget.

PtTextModifyText()

Modify the contents of aPtText widget.


Set the selected range for aPtText widget.


PtTextCallback t, PtTextControl t,PtTextControlInfo t 2005, QNX Software Systems Ltd.

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 forPtText 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 tolength characters to be added to thewidget.

doit Indicates whether or not the change should be made tothe widget’s text. In aPt CB MODIFY VERIFY


2005, QNX Software Systems Ltd. PtTextCallback t,PtTextControl t, PtTextControlInfo t

callback, you can prevent the text from being added tothe widget by settingdoit or length to zero.


See also:PtMultiTextCallback t


PtTextGetSelection() 2005, QNX Software Systems Ltd.

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 aPtText widget.It returns the number of characters currently selected and sets theprovided integers to the actual range. All characters fromstart up tobut not includingend are currently selected.

Both start andend are 0-based. So, for example, ifstart 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 aPtText widget.


Safety


Signal handler No

Thread No

See also:PtText, PtTextSetSelection()


2005, QNX Software Systems Ltd. PtTextModifyText()Modify the contents of a PtText widget

Synopsis:int PtTextModifyText( PtWidget t *widget,

int start,int end,int insert pos,char const *text,int length );

Description:This function modifies the contents of aPtText widget.

If start doesn’t equalend, then:

� All characters fromstart up to, but not including,end are deleted.

� The widget’s current insert position is set to the lesser ofstart andend.

� Theinsert pos argument is ignored.

If start does equalend, then:

� No text is deleted.

� The widget’s current insert position is set toinsert pos; ifinsert pos equals -1, the current insert position is set to the end ofthe widget’s text buffer.

Both start andend are 0-based. So, for example, ifstart is 0, itindicates the first character in the widget’s text buffer.

Once the current insert position is set, the function insertslengthcharacters fromtext. It does this regardless of the widget’s insertmode. Iflength is zero, no text is inserted.

This function causes a nondestructive deselect before attempting thechanges. If the widget has thePt 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:


PtTextModifyText() 2005, QNX Software Systems Ltd.

� 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 isNULL or isn’t aPtText widget.


Safety


Signal handler No

Thread No


2005, QNX Software Systems Ltd. PtTextSetSelection()Set the selected range for a PtText widget

Synopsis:int PtTextSetSelection( PtWidget t *widget,

int *start,int *end );

Description:This function sets the selected range for aPtText. When thefunction completes successfully,start andend contain the rangeactually selected (start < end). These values may differ from theoriginal values you specified if:

� Thestart value you specified was greater thanend.

Or:

� The range you specified exceeded the bounds of the widget’s text.

Both start andend are 0-based. So, for example, ifstart 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 isDel 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’taPtText widget.


PtTextSetSelection() 2005, QNX Software Systems Ltd.


Safety


Signal handler No

Thread No

See also:PtText, PtTextGetSelection()


2005, QNX Software Systems Ltd. PtTimerA 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, setPt ARG TIMER INITIAL to 0 or unrealize the widget.

When you create aPtTimer 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 PhotonProgrammer’s Guide.

☞

New resources:


PtTimer 2005, QNX Software Systems Ltd.


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


2005, QNX Software Systems Ltd. PtTimer

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


PtTimer 2005, QNX Software Systems Ltd.



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.




2005, QNX Software Systems Ltd. PtToggleButtonA 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 fromPtLabel andPtButton;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 withthePt ARG INDICATOR COLOR andPt ARG INDICATOR TYPEresources.


PtToggleButton 2005, QNX Software Systems Ltd.

You can also setPt ARG ARM COLOR, which specifies the fill colorfor the button’s interior when the button is set. This resource is usedonly if the value ofPt ARG ARM FILL is Pt TRUE. These resourcesare inherited fromPtButton.

To determine whether or not the button is set, check the:

� Pt SETbit in thePt ARG FLAGS resource — seePtWidget

� Callback data passed to thePt 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 GROUPEXCLUSIVE bit in the group’sPt 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 ) ;






2005, QNX Software Systems Ltd. PtToggleButton

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 aPt CB ACTIVATE callback (seePtBasic) for thegroup. ThePtGroup adds its callback to each of its children;when the callback is invoked, thewidget 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’sPt ARG USER DATAresource (seePtWidget). 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 theclient 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. SeePgColor t in thePhotonLibrary 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

















continued. . .




Pt CB ARM PtBasic




Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget





2005, QNX Software Systems Ltd. PtToolbarSuperclass 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 aPtToolbar can be any type of widget. They’recenter-aligned within the toolbar, and can optionally be separatedfrom each other with etched lines:

New resources:


PtToolbar 2005, QNX Software Systems Ltd.



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 REVERSELAST ITEM

Right- or bottom-align the frontmost (i.e. last) item.


2005, QNX Software Systems Ltd. PtToolbar

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 thatPtToolbarGroup 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 REVERSEGRADIENT




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



continued. . .







PtToolbarGroup 2005, 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 thePtToolbar 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




2005, 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. . .


2005, 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






2005, 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:ThePtTree 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 2005, QNX Software Systems Ltd.

Allocating items and building a tree

The items in aPtTree are stored in structures of typePtTreeItem t, which you should allocate by callingPtTreeAllocItem() or PtTreeCreateItem(). ThePtTree 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 toPtTreeAllocItem(), 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.

UsePtTreeAddFirst() andPtTreeAddAfter() to build a tree. Forexample, suppose you wanted to build the following tree:


2005, QNX Software Systems Ltd. PtTree

A PtTree without images.

Assuming your tree widget is referenced bytree 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 callPtTreeAllocItem() 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 thePt ARG TREE IMGMASKresource.

Alternatively, you can usePtTreeCreateItem() or PtTreeChangeItem()to assign images not in thePt 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’sPt 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 aPtDivider widget as a child of thePtTree. 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 thePt 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 yourPtTree display clickable images instead of textin selected columns. Here’s how:

Set thePt LIST COLUMN NO STRINGflag in thePtGenListcolumn 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 aPt 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 thePtTree widget.

parent A pointer to its parent window.

area A pointer to aPhArea t structure (see the PhotonLibrary Reference) that covers the item. Thearea->posmember is relative to the parent window.

column A pointer to aPtListColumn 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’sPt 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 thePhImage t structures pointed to by itaren’t.

unsigned short nimages

The number of entries in theimages 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 ofPtGenList).

� 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 thePt LIST COLUMN NO STRINGflag in thePt ARG LIST COLUMN ATTR resource (seePtGenList) and anonempty image array defined in thePt 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 thePtTree widget.



item A pointer to the item being drawn.

cattr A pointer to aPtTreeColumnAttributes t structurethat describes the column attributes. For information aboutthis structure, seePt 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’snimages, no image is drawn.

The default function returns 0 or 1, depending on whether thecolumn’siflags 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, seePhImage t in the PhotonLibrary Reference.



Set theflags member of thePhImage 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, seePtTreeAddImages(); 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 callingPtTreeAllocItem(), you specifythe images to be used when the item isset 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 ofPtGenList).

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 aPtTreeCallback 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 ifevent 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 inPtGenList.h) andPt LIST ITEM DAMAGED are lookedat. The initial value ofnew flags iscalculated as follows:

� Setnew iflags to old iflags;

� If the column attributes entry hasany of the user flags set iniflags,flip those flags innew 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 aPtTreeCallback 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, itsPt 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 aPh EV BUT RELEASEevent with asubtype ofPh EV RELEASEENDCLICK. For more information, seePhEvent t in the PhotonLibrary Reference.

ThePh EV BUT RELEASEevent with a subtype ofPh EV RELEASEENDCLICK 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 aPtCallbackInfo t structure that contains atleast the following members:

reason Pt CB TREE STATE

reason subtype

Pt TREE COLLAPSINGor Pt TREE EXPANDING.


cbdata A pointer to aPtTreeCallback 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,setexpand to a nonzero value to suppressexpansion.


























Pt ARG DIM PtWidget



continued. . .



























continued. . .








Pt ARG POS PtWidget












Pt ARG TREE FLAGS PtGenTree See below.







continued. . .





Pt CB ARM PtBasic













Pt CB MENU PtBasic


Pt CB RAW PtWidget








Pt ARG TREE FLAGS

In addition to the flags defined byPtGenTree, 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 thePt ARG LIST FLAGSresource inherited fromPtGenList.

☞

Pt CB DND

For Pt CB DND callbacks for aPtTree, thecbinfo->cbdata is apointer to aPtTreeDndCallback t structure, containing at leastthe following members:






A pointer to thePtGenTreeItem t structure forthe target item involved in the drag-and-dropoperation. You can cast this to be a pointer to aPtTreeItem t.


unsigned long flags

Possible values:





Convenience functions:ThePtTree 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 thePtTree 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() andPtTreeChangeItem().

PtTreeItemIndex()

Calculate the index of the specified item

PtTreeModifyItem()

Change item resources

PtTreeModifyItemString()

Change the string for aPtTree 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() 2005, 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 thebrother member ofthePtTreeItem t structure.

PtTreeAddAfter() assumes thatitem points to a list of trees. Thetreevariable points to aPtTree widget. The new items are added to thespecifiedtree below the specifiedbrother:

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 aNULL tree argument, as long asbrother points to an item that isn’t attached to any tree widget.


2005, 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() 2005, 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 ofPtTreeItem t structures pointed to byitem to the givenPtTree widget. The list of items are linked withtheirbrother fields. Theitem argument can beNULL.

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

Thetree argument can beNULL, provided thatparent points to anitem that isn’t attached to any tree widget.


2005, QNX Software Systems Ltd. PtTreeAddFirst()

PtTreeAddFirst() automatically sets thePt TREE ITEM EXPANDABLEflag in theparent item, whether or not theitem argument isNULL.

Returns:0 Success.




Safety


Signal handler No

Thread No

See also:PtTree, PtTreeAddAfter(), PtTreeAllocItem(), PtTreeFreeAllItems(),PtTreeFreeItems(), PtTreeItem t, PtTreeRootItem()


PtTreeAddImages() 2005, 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 addsn 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 thePhImage 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 ofPtTree.


Safety


Signal handler No

Thread No


2005, QNX Software Systems Ltd. PtTreeAddImages()

See also:PtTree

PhImage t in the PhotonLibrary Reference


PtTreeAllItems() 2005, 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 usingmalloc(), and thebuffer isNULL-terminated. Ifbuffer isn’t NULL, the function doesn’tadd aNULL at the end.

Items that belong to collapsed subtrees aren’t included in the buffer. Ifyou need a list of all the items, traverse thefather, son, andbrotherpointers in thePtGenTreeItem 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 );



2005, QNX Software Systems Ltd. PtTreeAllItems()

Safety


Signal handler No

Thread No

See also:PtTree, PtTreeGetCurrent(), PtTreeGetSelIndexes(),PtTreeItem t, PtTreeSelectedItems(), PtTreeSetSelIndexes()


PtTreeAllocItem() 2005, 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.

Theset img argument is the index of the image to be displayed whenthe item is set, andunset 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.”

UsePtTreeAddFirst() andPtTreeAddAfter() to add the new item to atree structure.

☞



Safety


continued. . .


2005, QNX Software Systems Ltd. PtTreeAllocItem()

Safety

Signal handler No

Thread No

See also:PtTree, PtTreeAddAfter(), PtTreeAddFirst(), PtTreeAddImages(),PtTreeFreeAllItems(), PtTreeFreeItems(), PtTreeItem t,PtTreeModifyItem(), PtTreeModifyItemString()


PtTreeChangeItem() 2005, 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 thePtTree widget which contains the item

you want to change.

item A pointer to thePtTreeItem t you wish to change.

string The tree item text string. Set toNULL to leave the item’stext string unchanged.

attr A pointer to the newPtTreeItemAttributes t

structure you want to set for this item. Set toNULL todisplay no images, and use the widget-defined font andcolors. ThePt TREE ITEM HAS ATTRS flag bit is still setfor the item.

Description:This function changes an existing tree item, created withPtTreeCreateItem() or PtTreeAllocItem(). Thestring andattrparameters will override the existing item text string and attributes.

Returns:A pointer to aPtTreeItem t

Success.

NULL Error


2005, 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() 2005, 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()


2005, 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 subtreeitem. Thetree argumentmust point to the tree that contains theitem, or it can beNULL if theitem doesn’t belong to any tree.

If the item is in the tree, the tree’sPt CB TREE STATE callback isinvoked after the item has been collapsed. Theevent argument to thisfunction is the event that’s passed to the callback.

Returns:The value assigned to theexpand field in the callback structure, orzero if the item isn’t in a tree or there’s noPt CB TREE STATEcallback that modifies theexpand field.


Safety


Signal handler No

Thread No

See also:PtTree, PtTreeExpand(), PtTreeGetCurrent(), PtTreeGoto(),PtTreeItem t, PtTreeShow()



PtTreeCreateItem() 2005, 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 thePtTree widget that this item will be added

to.

string The text to display for the item.

attr A pointer to aPtTreeItemAttributes t structurewhich defines the attributes for the item. Set toNULL 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 aPtTreeItemAttributes t structure,passed asattr. The item’sPt TREE ITEM HAS ATTRS is set whetherattr is passed as a pointer orNULL.

Both PtTreeAllocItem() andPtTreeCreateItem() create a tree item.PtTreeCreateItem() lets you specify set and unset images that are notalready present in the widget’sPt ARG TREE IMAGES array. Ingeneral, if you want to use images in this array, you should usePtTreeAllocItem().


2005, QNX Software Systems Ltd. PtTreeCreateItem()

An item created withPtTreeCreateItem(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.

☞

UsingPtTreeCreateItem() you can also specify text and fill colorattributes for selected and unselected items.

UsePtTreeAddFirst() andPtTreeAddAfter() to add the new item to atree structure.

☞

Returns:A pointer to a PtTreeItemt

Success.

NULL Error



Safety


Signal handler No

Thread No


PtTreeCreateItem() 2005, QNX Software Systems Ltd.

See also:PtTree, PtTreeAddAfter(), PtTreeAllocItem(), PtTreeChangeItem(),PtTreeFreeAllItems(), PtTreeFreeItems(), PtTreeItem t,PtTreeItemAttributes t, PtTreeRootItem()


2005, 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 subtreeitem. Thetree argument mustpoint to the tree that contains theitem or can beNULL if the itemdoesn’t belong to any tree.

If the item is in the tree, the tree’sPt CB TREE STATE callback isinvoked before the item is expanded. Theevent argument to thisfunction is the event that’s passed to the callback. Your callbackfunction can prevent the expansion by setting theexpand field in thecallback structure to a nonzero value; zero means successfulexpansion.

Returns:The value assigned to theexpand field in the callback structure, orzero if the item isn’t in a tree or there’s noPt CB TREE STATEcallback that modifies theexpand field.


Safety


Signal handler No

Thread No


PtTreeExpand() 2005, QNX Software Systems Ltd.

See also:PtTree, PtTreeCollapse(), PtTreeGetCurrent(), PtTreeGoto(),PtTreeItem t, PtTreeShow()



2005, 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 thetree widget. Note thatthis function is called automatically when thePtTree widget is beingdestroyed.


Safety


Signal handler No

Thread No

See also:PtTree, PtTreeAllocItem(), PtTreeFreeItems(),PtTreeRemoveChildren(), PtTreeRemoveItem(), PtTreeRemoveList()


PtTreeFreeItems() 2005, QNX Software Systems Ltd.


Synopsis:int PtTreeFreeItems( PtTreeItem t *item );

Description:This function frees the given subtrees (theitem together with itsbrothers and their children). The items must not belong to any tree —usePtTreeRemoveChildren(), PtTreeRemoveItem(), orPtTreeRemoveList() to remove the subtree from a tree widget beforefreeing the subtrees.

Returns:0 Success.

-1 Theitem is still in a widget.


Safety


Signal handler No

Thread No

See also:PtTree, PtTreeAllocItem(), PtTreeFreeAllItems(), PtTreeItem t,PtTreeRemoveChildren(), PtTreeRemoveItem(), PtTreeRemoveList()


2005, 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 givenPtTree

widget (see “Current item” in the description ofPtGenList).


Safety


Signal handler No

Thread No

See also:PtTree, PtTreeClearSelection(), PtTreeGetSelIndexes(),PtTreeGoto(), PtTreeItem t, PtTreeRootItem(), PtTreeSelect(),PtTreeSelectedItems(), PtTreeSetSelIndexes(), PtTreeShow(),PtTreeUnselect(), PtTreeUnselectNonBrothers()


PtTreeGetSelIndexes() 2005, QNX Software Systems Ltd.

Fill a buffer with indexes

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 usingmalloc(),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 thewidget.

Items that belong to collapsed subtrees aren’t included in the buffer.☞



Safety


Signal handler No

Thread No


2005, QNX Software Systems Ltd. PtTreeGetSelIndexes()

See also:PtTree, PtTreeClearSelection(), PtTreeGetCurrent(), PtTreeGoto(),PtTreeItem t, PtTreeRootItem(), PtTreeSelect(),PtTreeSelectedItems(), PtTreeSetSelIndexes(), PtTreeShow(),PtTreeUnselect(), PtTreeUnselectNonBrothers()


PtTreeGoto() 2005, QNX Software Systems Ltd.

Set the current item

Synopsis:int PtTreeGoto( PtWidget t *list,

PtTreeItem t *item );


If you passitem asNULL, 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()


2005, 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 aPtTree. 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’sPt ARG TREE IMAGESresource of the image that’s displayed when theitem is set. An item is considered set if its flagsmasked with the tree’sPt 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 2005, QNX Software Systems Ltd.

string The string to be displayed for the item. This field isallocated the appropriate amount of space when it’sset.

UsePtTreeAllocItem() or PtTreeCreateItem() to allocate and fill inthis structure.

Once the tree item has been created or changed,item->gen.list.flagsindicates which half of thePtTreeItem t’s attr union is valid.When this flag isPt TREE ITEM HAS ATTRS, attr.ptr is a pointer toan attributes structure (orNULL). When this flag is clear,attr.img.setandattr.img.unset are indexes into thePt 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()


2005, 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 aPtTreeItem 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 toPtTreeCreateItem() to create atree item with attributes (as opposed toPtTreeAllocItem()), and toPtTreeChangeItem() to change an existing tree item.

Thelist member is aPtGenListItemAttrs 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 2005, QNX Software Systems Ltd.

font The font name for the item text. If this item is set toNULL,the widget-defined font it used.

unselected colors, selected colors

The text and fill color for the list item. Set toPg TRANSPARENTto use the widget-defined color.

This member is aPtGenListColorSet 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


2005, 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 givenitem within thetree.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() 2005, 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 ofstring. If string isNULL, the item’s string isn’t changed.

� Theset img argument is the index of the image that’s displayedwhen the item is set, andunset 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.

Thetree is a pointer to thePtTree that the item belongs to, orNULL.If the item is in a tree, it must be in the one pointed to bytree.

Returns:The new address of the item.

This address may differ from the old one if the new string is longer.☞


Safety


continued. . .


2005, QNX Software Systems Ltd. PtTreeModifyItem()

Safety

Signal handler No

Thread No

See also:PtTree, PtTreeAllocItem(), PtTreeItem t, PtTreeItemIndex(),PtTreeModifyItemString()


PtTreeModifyItemString() 2005, 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 givenitem, making a copy ofstring. Thetree is a pointer to thePtTree that the item is in, orNULL. If the item is in a tree, it must be in the one pointed to bytree.

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()


2005, 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 specifieditem 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 thePtTreeFreeItems() function.

This function doesn’t collapse the item. If the children are visible,PtTreeRemoveChildren() returnsNULL. Call PtTreeCollapse() beforePtTreeRemoveItem() to make sure that the item is collapsed.

Returns:A pointer to the first of the removed children, orNULL if the childrenare visible.


PtTreeRemoveChildren() 2005, QNX Software Systems Ltd.


Safety


Signal handler No

Thread No

See also:PtTree, PtTreeAddAfter(), PtTreeAddFirst(), PtTreeAllocItem(),PtTreeFreeAllItems(), PtTreeFreeItems(), PtTreeItem t,PtTreeRemoveItem(), PtTreeRemoveList()


2005, QNX Software Systems Ltd. PtTreeRemoveItem()Unlink an item

Synopsis:void PtTreeRemoveItem( PtWidget t *tree,


Description:This function unlinks the givenitem together with its children from itsparent and brothers (if any) and sets theitem->gen.father anditem->gen.brother fields toNULL:

B

C

C

B

itemtree

item

tree

A A

The results of using PtTreeRemoveItem().

Thetree argument must point to thePtTree widget containing theitem, or can beNULL if the item doesn’t belong to anytree.

Note that iftree is NULL and theitem has no parent but has a previousbrother, then the function can’t find the previous brother, andtherefore can’t unlink theitem from its brother. The function doesnothing if item->gen.father andtree areNULL.

PtTreeRemoveItem() never clears thePt TREE ITEM EXPANDABLEflag in the item’s parent.



PtTreeRemoveItem() 2005, QNX Software Systems Ltd.

Safety


Signal handler No

Thread No

See also:PtTree, PtTreeAddAfter(), PtTreeAddFirst(), PtTreeAllocItem(),PtTreeFreeAllItems(), PtTreeFreeItems(), PtTreeItem t,PtTreeRemoveChildren(), PtTreeRemoveList()


2005, QNX Software Systems Ltd. PtTreeRemoveList()Unlink the root item

Synopsis:void PtTreeRemoveList( PtWidget t *tree,

PtTreeItem t *first );

Description:This function unlinks the itemfirst and its brothers (together withtheir children) from their parent (and previous brother) and sets theirgen.father fields toNULL:

B

C

C

B

firsttree

first

tree

A A

The results of using PtTreeRemoveList().

Thetree argument must point to thePtTree widget that contains theitems, or can beNULL if the items don’t belong to any tree.

Note that iftree is NULL andfirst has no parent but has a previousbrother, then the function won’t be able to find the previous brotherand therefore can’t unlinkfirst from its previous brother.


Safety


continued. . .


PtTreeRemoveList() 2005, QNX Software Systems Ltd.

Safety

Signal handler No

Thread No

See also:PtTree, PtTreeAddAfter(), PtTreeAddFirst(), PtTreeAllocItem(),PtTreeFreeAllItems(), PtTreeFreeItems(), PtTreeItem t,PtTreeRemoveChildren(), PtTreeRemoveItem()


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

Select the specified item

Synopsis:void PtTreeSelect( PtWidget t *widget,


Description:This function selects the givenitem belonging to the givenPtTreewidget. You can passNULL 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()


2005, 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 usingmalloc(),and the buffer isNULL-terminated.

� If buffer is non-NULL, the function adds aNULL at the end only ifthere are no selected items in thewidget.

Items that belong to collapsed subtrees aren’t included in the buffer.☞



Safety


Signal handler No

Thread No


PtTreeSelectedItems() 2005, QNX Software Systems Ltd.

See also:PtTree, PtTreeClearSelection(), PtTreeGetCurrent(),PtTreeGetSelIndexes(), PtTreeGoto(), PtTreeItem t,PtTreeSelect(), PtTreeSetSelIndexes(), PtTreeUnselect(),PtTreeUnselectNonBrothers()


2005, 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 thancount if the array isn’t sorted orcontains duplicate indexes or indexes out of range.

Note that if the selection mode isPt 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() 2005, 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 givenitem is visible.If you passitem asNULL, the function does nothing. This lets you dosomething like this:

PtTreeShow( widget, PtTreeGetCurrent(widget) );

without checking to see ifPtTreeGetCurrent() returnedNULL.

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


2005, QNX Software Systems Ltd. PtTreeShow()

See also:PtTree, PtTreeClearSelection(), PtTreeCollapse(), PtTreeExpand(),PtTreeGetCurrent(), PtTreeGetSelIndexes(), PtTreeGoto(),PtTreeItem t, PtTreeRootItem(), PtTreeSelect()


PtTreeUnselect() 2005, QNX Software Systems Ltd.

Unselect the given item

Synopsis:void PtTreeUnselect( PtWidget t *widget,


Description:This function unselects the given item belonging to the givenPtTree

widget.

Note thatPtTreeUnselect() doesn’t support thePt RANGE MODEselection mode.


Safety


Signal handler No

Thread No

See also:PtTree, PtTreeClearSelection(), PtTreeGetCurrent(),PtTreeGetSelIndexes(), PtTreeGoto(), PtTreeItem t,PtTreeSelect(), PtTreeSelectedItems(), PtTreeSetSelIndexes(),PtTreeUnselectNonBrothers()


2005, 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 passitem asNULL, the current item is used (see “Currentitem” in the description ofPtGenList).


Safety


Signal handler No

Thread No

See also:PtTree, PtTreeClearSelection(), PtTreeGetCurrent(),PtTreeGetSelIndexes(), PtTreeGoto(), PtTreeItem t,PtTreeSelect(), PtTreeSelectedItems(), PtTreeSetSelIndexes(),PtTreeUnselect()


PtTrend 2005, 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.


2005, 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 typePtTrendAttr t, which contains at least thefollowing member:



int map An index intoPt 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 inPt ARG TREND COLOR LIST (which isthe same asPt ARG COLOR)

2 the second color inPt ARG TREND COLOR LIST

3 etc.

In order to set this resource, you must use the arguments toPtSetArg()in an unusual way; thevalue argument points to the value of theresource, as usual, butlen 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, thelenargument to 0 and have thevalue 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, setPtSetArg’s len argument to thenumber of that trend, and have thevalue argument point to a singlestructure of typePtTrendAttr t. For example, the followingchanges the color of trend 2 toPg 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 thelenargument ofPtSetArg() to 0 specifies that you want to set the colorindex forall the trends.

☞

Pt ARG TREND COLOR LIST


PgColor t *, short Array NULL

The list of colors that the trend may use. SeePgColor t in thePhotonLibrary 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 asPt 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 toPtSetArg() with a pointer to a data buffer thatcontains the new data points. The application must also set thelenparameter 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 setlento be the total number of points being added, not the number of pointsper trend.

If you set thevalue parameter toNULL, the trend’s display is cleared.

If you wish toreplace 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 ifPt 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 withPgDrawPixelArray() 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 withPt TREND HORIZONTAL.

Pt TREND RIGHT TO LEFT

Make the trends move from right to left. You can usethis only withPt 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 setPt ARG TREND FLAGS to an invalid value, the widgetdraws only the background.

☞

Pt ARG TREND GRID COLOR





The color of the grid, specified as an RGB value. SeePgColor t inthe PhotonLibrary Reference.

The grid is displayed only ifPt 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 ifPt 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 ifPt 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 onePtTrend

widget and you want to make sure their palette entries don’t overlap.

EachPtTrend 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 thePt 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 fromE - N to E -1.

The value ofPt ARG TREND PALETTE END should be a multipleof N. If it isn’t, it’s rounded down to a multiple ofN.


















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:ThePtTrend 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


2005, 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.Thewidget argument must be a widget of typePtTrend. Thetnargument is the number of the trend to be changed, in the range 0 totrend count - 1, inclusive.

Thenewdata 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() 2005, 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().

Thenewdata array is ordered with the oldest sample atnewdata[0],and the newest atnewdata[nsamples - 1]. The oldest sample to bereplaced will have an index oflast 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].

� ...


2005, 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 ofPtTrendChangeTrendData() with thefollowing exceptions:

� Thetn argument isn’t passed toPtTrendChangeData().

� The data for the first trend is put into the firstnsamples places ofnewdata, followed by those for trend 2, 3 and so on.

CallingPtTrendChangeData() 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 thatPtTrendChangeData() redraws the widgetonce; the loop redraws it once per iteration.


Safety


Signal handler No

Thread No


PtTty 2005, 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 aPtTerminal 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 thePt GETS FOCUSflag set in itsPt ARG FLAGSresource, keyboard input to the widget (as well as mouse events) areredirected to the device. You can also use thePt ARG TTY INPUTresource to simulate keyboard input.

PtTerminal and PtTty

The main difference betweenPtTerminal andPtTty is thatPtTerminal doesn’t do any I/O for you. The only way to displaycharacters in aPtTerminal is by giving them to one of the


2005, QNX Software Systems Ltd. PtTty

PtTerminalPut*() functions. Similarly, the only thingPtTerminaldoes 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 toPtTerminalPut() ispart ofPtTty. Similarly,PtTty attaches aPt CB TERM INPUTcallback that writes Photon keyboard input (translated byPtTerminal to text-mode compatible format) to the pty.

Another responsibility ofPtTty is spawning a command for you andinvoking thePt CB TTY TERMINATED callbacks when thecommand terminates.

Setting PtTty resources

Some of the resources forPtTty 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 settingPt ARG TTY CMD orPt ARG TTY ARGV) before defining which device it’s to be spawnedon (by settingPt 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 SETENVandPt 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 valuesbefore 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 mapsstdin, stdout, andstderr to whenyou setPt ARG TTY CMD or Pt ARG TTY ARGV.

Pt ARG TTY SFD overrides the entries in theiov 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 settingPt ARG TTY RFD, Pt ARG TTY WFD,andPt ARG TTY SFD to the same value. SettingPt ARG TTY FDS to -1 closes any previously open filedescriptors and setsPt ARG TTY PATH to NULL.

When you setPt ARG TTY RFD or Pt ARG TTY WFD to a filedescriptor, the widget sets theO 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 neitherPt ARG TTY RFD norPt ARG TTY WFDreferences that fd any more, the widget unsets theO 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 aPtTty 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 usingdup() (see the QNX NeutrinoLibraryReference) 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 aNULL-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, thePATH 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 programwhoseargv[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 thePt TTY ARGV0 flag is set and two whenit’s clear), the user’s shell is spawned. If thePt TTY ARGV0 flag isclear and the list isNULL or empty, this is a login shell.

All the flags and resources described underPt ARG TTY CMD,except thePt 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 thePtTerminalPut() 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 ofPtTerminalPut().

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 aNULL 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 thePt TTY ARGV0 flag is clear, the shell isstarted as a login shell.

If another process has been spawned previously and is still running,and thePt ARG TTY PID resource hasn’t been set to zero, aSIGTERMsignal is sent to the process group of that process beforestarting the new program.

If the Pt TTY SETENVflag is set (which is the default), theTERMenvironment variable of the new process is set to a valuecorresponding to the current terminal protocol (using thePtTerminalName() function). The environment variablesLINES 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 thePt 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 forwaitpid() inthe QNX NeutrinoLibrary Reference. The value is valid only afterthe child process has terminated.

Pt ARG TTY FDS


int Scalar -1

A shortcut for settingPt ARG TTY RFD, Pt ARG TTY WFD, andPt ARG TTY SFD to the same value. SettingPt 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 thePt ARG TTY CMD orPt ARG TTY ARGV resource is set. The default value of 7 means thatthePtTty widget’s device is available as descriptors 0, 1 and 2. Onlythe ten low-order bits are used because the redirection is done usingtheiov[] member of thePtSpawnOptions 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 asargv[0] (seePt ARG TTY CMD).

� Pt TTY BUF PRIVATE (read-only) — the widget is using anallocated buffer.

By default, all bits are set exceptPt TTY DEVFORCE.

If both Pt TTY TERMRESIZEandPt TTY DEVRESIZEflags 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 DEVFORCEflag is set, thePt 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 theO NONBLOCK flag, the numberof bytes that are actually written may be less than the specified length.You can use thePt 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) inPt ARG TTY RFD, Pt ARG TTY WFD, andPt ARG TTY SFD.

The descriptor is guaranteed to be greater than 2 and have theFD CLOEXECflag 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), aSIGHUPsignal 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 PhotonLibrary 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 bothPt ARG TTY RFD andPt ARG TTY WFD, and the “slave” fd inPt ARG TTY SFD.

Also, the pathname of the slave device is stored inPt ARG TTY PATH.

You should set this resource toNULL 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 thePt 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 theFD CLOEXECflag 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 mapsstdin, stdout, andstderrwhen you setPt ARG TTY CMD or Pt ARG TTY ARGV.



☞

Pt ARG TTY SPAWN OPTIONS


PtSpawnOptions t const * Pointer NULL



A pointer to aPtSpawnOptions t structure that’s used forspawning the child process.

If you leave this resource set toNULL, the widget uses the defaultvalues in:

extern const PtSpawnOptions t PtTtyDefaultSpawnOptions

For more information about this structure, seePtSpawn() in thePhotonLibrary 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 aPtTerminalSizeChange 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 aPtTtyOutput 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 anint 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

continued. . .




Pt ARG TERM COLS PtTerminal

Pt ARG TERM CONSOLE PtTerminal

Pt ARG TERM CUR COL PtTerminal

Pt ARG TERM CUR POS PtTerminal

Pt ARG TERM CUR ROW PtTerminal

Pt ARG TERM CURSOR FLAGS PtTerminal

Pt ARG TERM DRAW MODES PtTerminal

Pt ARG TERM FONT PtTerminal

Pt ARG TERM FONT LIST PtTerminal

Pt ARG TERM FONT INDEX PtTerminal

Pt ARG TERM FONT SIZE PtTerminal

Pt ARG TERM MARGINS PtTerminal

Pt ARG TERM MAXCOLS PtTerminal

Pt ARG TERM MAXROWS PtTerminal

Pt ARG TERM MAXSIZE PtTerminal

Pt ARG TERM MINCOLS PtTerminal

Pt ARG TERM MINROWS PtTerminal

Pt ARG TERM MINSIZE PtTerminal

Pt ARG TERM OPTIONS PtTerminal

Pt ARG TERM OPTMASK PtTerminal

Pt ARG TERM ANSI PROTOCOL PtTerminal

Pt ARG TERM RESIZE FL PtTerminal

Pt ARG TERM RESIZE FUN PtTerminal

continued. . .




Pt ARG TERM RESIZE STR PtTerminal

Pt ARG TERM ROWS PtTerminal

Pt ARG TERM SCRLBK COUNT PtTerminal

Pt ARG TERM SCRLBK LIMIT PtTerminal

Pt ARG TERM SCRLBK POS PtTerminal

Pt ARG TERM SCROLL PtTerminal

Pt ARG TERM SELECTION PtTerminal

Pt ARG TERM SIZE PtTerminal

Pt ARG TERM VISUAL BELL PtTerminal







Pt 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, seePt ARG TERM CURSOR FLAGS and “Scrollingoptimization” in the description ofPtTerminal.



Convenience functions:ThePtTty widget defines the following convenience function:

PtTtyShell() Return the user’s default shell.


PtTtyShell() 2005, QNX Software Systems Ltd.

Return the user’s default shell

Synopsis:const char PtTtyShell( void );

Description:ThePtTtyShell() function returns either the value of theSHELLenvironment variable or, ifSHELL is undefined, the user’s defaultshell defined in thepasswd file.

This string is used by thePtTty widget to start the user’s shell (seePt ARG TTY CMD andPt ARG TTY ARGV resources toPtTty).


Safety


Signal handler No

Thread No


2005, QNX Software Systems Ltd. PtUpDownVertical or horizontal increment/decrement buttons

Class hierarchy:PtWidget → PtBasic → PtUpDown

PhAB icon:

Public header:<photon/PtUpDown.h>

Description:ThePtUpDown widget creates vertical or horizontalincrement/decrement buttons. It lets you increase or decrease a value.

A PtUpDown widget.

By default, the buttons display images of arrows, but you can useother images if necessary. You can also specify thearmed data, theimage displayed when the user presses one of the buttons.

ThePt CB ACTIVATE,Pt CB ARM, Pt CB DISARM, andPt CB REPEAT callbacks for the buttons have a subtype thatindicates which button was pressed.

New resources:


Pt ARG ARM COLOR PgColor t Scalar PgGray(170)

Pt ARG ORIENTATION int Scalar Pt VERTICAL

continued. . .


PtUpDown 2005, QNX Software Systems Ltd.


Pt ARG SPACING unsignedshort

Scalar 0

Pt ARG UPDOWN ARM DATA DECREMENT PhImage t*

Image NULL

Pt ARG UPDOWN ARM DATA INCREMENT PhImage t*

Image NULL

Pt ARG UPDOWN BORDER WIDTH unsignedshort

Scalar 1

Pt ARG UPDOWN DATA DECREMENT PhImage t*

Image NULL

Pt ARG UPDOWN DATA INCREMENT PhImage t*

Image NULL

Pt ARG UPDOWN FLAGS long Scalar See below

Pt ARG UPDOWN INDICATOR MARGIN unsignedshort

Scalar 0

Pt ARG ARM COLOR



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

This resource is used only ifPt ARG UPDOWN FLAGS hasPt UPDOWN FILL ON ARM set.

Pt ARG ORIENTATION


2005, QNX Software Systems Ltd. PtUpDown


int Scalar Pt VERTICAL

The direction the arrows are pointing:

� Pt VERTICAL

� Pt HORIZONTAL

Pt ARG SPACING



The spacing between the increment and decrement buttons, in pixels.

Pt ARG UPDOWN ARM DATA DECREMENT



The image for the armed decrement button. This resource is used onlyif Pt UPDOWN ARM DECREMENTis set inPt ARG UPDOWN FLAGS.

Pt ARG UPDOWN ARM DATA INCREMENT



The image for the armed increment button. This resource is used onlyif Pt UPDOWN ARM INCREMENT is set inPt ARG UPDOWN FLAGS.



Pt ARG UPDOWN BORDER WIDTH



The width of the widget’s border, in pixels.

Pt ARG UPDOWN DATA DECREMENT



The image for the unarmed decrement button. This resource is usedonly if Pt UPDOWN DECREMENTis set inPt ARG UPDOWN FLAGS.

Pt ARG UPDOWN DATA INCREMENT



The image for the unarmed increment button. This resource is usedonly if Pt UPDOWN INCREMENT is set inPt ARG UPDOWN FLAGS.

Pt ARG UPDOWN FLAGS


long Scalar Pt FILL ON ARM

Pt UPDOWN INCREMENT IMAGE

Use thePt ARG UPDOWN DATA INCREMENT resource asthe image for the unarmed increment button.



Pt UPDOWN DECREMENT IMAGE

Use thePt ARG UPDOWN DATA DECREMENT resource asthe image for the unarmed decrement button.

Pt UPDOWN INCREMENT ARM IMAGE

Use thePt ARG UPDOWN ARM DATA INCREMENTresource as the image for the armed increment button.

Pt UPDOWN DECREMENT ARM IMAGE

Use thePt ARG UPDOWN ARM DATA DECREMENTresource as the image for the armed decrement button.

Pt UPDOWN ROTATE INDICATORS

Rotate the arrow indicators on the increment and decrementbuttons by ninety degrees. This flag only applies to arrowindicators; it doesn’t rotate images when images are used.

Pt UPDOWN FILL ON ARM

Not currently used.

Pt ARG UPDOWN INDICATOR MARGIN


unsigned Scalar 0

The distance, in pixels, around the button image.













Pt ARG COLOR PtBasic Not used by this class.







Pt ARG DIM PtWidget



Pt ARG FILL COLOR PtBasic Not used by this class.

Pt ARG FILL PATTERN PtBasic Not used by this class.




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 WIDTH PtWidget 5

Pt CB ACTIVATE PtBasic See below

Pt CB ARM PtBasic See below



Pt CB DISARM PtBasic See below

continued. . .




Pt CB DND PtWidget

Pt CB FILTER PtWidget Not used by this class.





Pt CB MENU PtBasic


Pt CB RAW PtWidget


Pt CB REPEAT PtBasic See below


Pt CB ACTIVATE, Pt CB ARM, Pt CB DISARM, Pt CB REPEAT

These callbacks are passed aPtCallbackInfo t structure thatcontains at least the following members:

ulong t reason;ulong t reason subtype;PhEvent t *event;void *cbdata;

The callbacks are similar to those forPtButton, except thereason subtype indicates which button was pressed:

� UPDOWN TOP

� UPDOWN BOTTOM

� UPDOWN LEFT

� UPDOWN RIGHT


2005, QNX Software Systems Ltd. PtWebClientWidget for displaying web pages

Class hierarchy:PtWidget → PtBasic → PtContainer → PtClient →PtWebClient

PhAB icon:

Public header:<photon/PtWebClient.h>

Description:You can use thePtWebClient 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, seevserver andnetfront in the QNXNeutrinoUtilities Reference.

Starting the server

Start the server initially by setting thePt ARG WEB SERVERresource.

Typically, thePtWebClient widget is in a PhAB application, and itsPt ARG WEB SERVER resource isNULL.

You can set thePt ARG WEB SERVER resource to either:

� the name of a web server profileOr:

� a web server command and any command-line options


PtWebClient 2005, QNX Software Systems Ltd.

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; thePt 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’s 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 ofPt 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 settingthePt ARG WEB GET URL resources.


2005, QNX Software Systems Ltd. PtWebClient

Migrating from libPtWeb.so.2 to libPtWeb.so.3

If your browser application has been designed to work with thePtWebClient widget fromlibPtWeb.so.2, and you want tomigrate to the newPtWebClient API in libPtWeb.so.3, youshould be aware of some changes that are required in your code:

1 All the macros starting withWWW are renamed to start withPt WEB now. You should change your code accordingly. Forexample: WWW RESPONSEOK is nowPt WEB RESPONSEOK. 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 fromPtWebClient to the server, membersthat werechar member[] are now pointers tochar, 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 — renamedPtWebClient2AuthenticationData t

� PtWebClientHelperData t — renamedPtWebClient2HelperData t

� PtWebClientUnknownData t — renamedPtWebClient2UnknownData t

� PtWebClientData t — renamedPtWebClient2Data t

� PtWebCommand t — renamedPtWebClient2Command t

� PtWebClientSSLResponse t — renamedPtWebClient2SSLResponse 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’s now defined as:typedef struct {short response;short type;char *userid;char *password;char *url;

} PtWebClient2AuthenticationData t;

You should allocate theuserid, password andurl members ,and it’s your responsibility to free them.

New resources:


Pt ARG WEB ACTIVATE LINK int Scalar 0(write-only)

Pt ARG WEB AUTHENTICATE See below Pointer NULL (write-only)

Pt ARG WEB BUILD DATE char * String NULL (read-only)

Pt ARG WEB COMMAND PtWebCommand t * Pointer NULL (write-only)

Pt ARG WEB DATA PtWebClientData t * Pointer NULL (write-only)

Pt ARG WEB DOWNLOAD char *, char * String N/A (write-only)

Pt ARG WEB ENCODING char * String NULL

Pt ARG WEB GET CERTIFICATES See below Pointer NULL (read-only)

Pt ARG WEB GET CONTEXT char * String NULL (read-only)

continued. . .




Pt ARG WEB GET HISTORY See below Pointer None (read-only)

Pt ARG WEB GET URL char * String N/A (write-only)

Pt ARG WEB HELPER See below Pointer NULL (write-only)

Pt ARG WEB H ERRNO int Scalar 0

Pt ARG WEB IMPORT CERTIFICATE See below Pointer N/A (write-only)

Pt ARG WEB NAVIGATE FRAME int Scalar 0

Pt ARG WEB NAVIGATE LINK int Scalar 0

Pt ARG WEB NAVIGATE PAGE int Scalar 0

Pt ARG WEB OPTION char *, char* String NULL

Pt ARG WEB PRINT PpPrintContext t *,

int

Pointer NULL (write-only)

Pt ARG WEB RELOAD N/A N/A N/A (write-only)

Pt ARG WEB SERVER char * String NULL

Pt ARG WEB SERVER PID pid t Scalar read-only

Pt ARG WEB SSL RESPONSE See below Pointer NULL

Pt ARG WEB STARTUP ERRNO int Scalar 0

Pt ARG WEB STOP N/A N/A N/A (write-only)

Pt ARG WEB UNKNOWN RESP See below Pointer NULL (write-only)

Pt ARG WEB VERSION char * String NULL (read-only)

Pt CB WEB AUTHENTICATE PtCallback t*

Link NULL

Pt CB WEB CLOSE WINDOW PtCallback t*

Link NULL

Pt CB WEB COMPLETE PtCallback t*

Link NULL

continued. . .




Pt CB WEB CONTEXT PtCallback t*

Link NULL

Pt CB WEB DATA REQ PtCallback t*

Link NULL

Pt CB WEB DOWNLOAD PtCallback t*

Link NULL

Pt CB WEB ERROR PtCallback t*

Link NULL

Pt CB WEB IMPORT CERTIFICATE PtCallback t*

Link NULL

Pt CB WEB METADATA PtCallback t*

Link NULL

Pt CB WEB NEED SCROLL PtCallback t*

Link NULL

Pt CB WEB NEW WINDOW PtCallback t*

Link NULL

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

continued. . .




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 theappropriate 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 ofTEXTAREA 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 whenthePt 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 RESPONSEOK — the information is valid.

� Pt WEB RESPONSECANCEL — 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 thelen argument toPtSetArg(). If a pointer to thePtWebCommand t data structure is required with the command, passit as thevalue argument toPtSetArg().

ThePtWebCommand 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 ofthePtWebCommand t data structure used is:

struct {char *String;unsigned long flags;

} FindInfo;

where:

� String — a pointer to the word to find in the document.



� flags — a combination of:

- Pt WEB FIND START AT TOP— start the search at 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 wholewords.

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;

wherefilename is a pointer to the name of the file in which tosave the document.

Pt WEB COMMAND RESETOPT

Cause any changed options that may change the current visiblepage to take effect.

Pt WEB COMMAND PURGECACHE

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 aPt CB WEB CONTEXT callback).

Pt ARG WEB DATA (write only)




PtWebClientData t * Pointer NULL

Voyager server only.

This resource is set in response to aPt CB WEB DATA REQcallback. It provides the header and data of theclient 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 of data (no more than what was askedfor in thePt CB WEB DATA REQ callback).

data A pointer to the data.

Here’s an example of using theclient 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, "",

&webdata );PtSetResources( widget, 1, args );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,

&webdata );PtSetResources( widget, 1, args );

} 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. Thevalueargument ofPtSetArg() should contain the URL of the file todownload and thelen 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. SeePxTranslateSet() in the PhotonLibrary Reference.

For thenetfront server, you can set this resource toAutodetect

Encoding (the default setting). When this value is set, thenetfront

server will try to auto detect the encoding.

Pt ARG WEB GET CERTIFICATES (read only)


PtWebSSLClientCertificates t * Pointer NULL

This resource gets information about current client certificates.


typedef struct {int ncert;char *url;int reserved1;int reserved2;PtWebSSLCertInfo t info[1];} PtWebSSLClientCertificates t;

The members are:



ncert The number of certificates.

url Not used.

info A PtWebSSLCertInfo t structure that containsinformation about the certificate. See thePt CB WEB SSL CERTNONTRUSTED resource for adescription of thePtWebSSLCertInfo 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 thelen argument ofPtSetArg().

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 theHistory Expire option (default 4 days).



The data structures used with this resource are:

typedef struct {short num;short offset;

} PtWebClientHistory t;

where:

� num — the number of history entries to return

� offset — the offset into the history site list at which to begin.

and:

typedef struct {char *title;char *url;time t lastvisited;

} PtWebClientHistoryData t;

When you use these structures, you passPtWebClientHistory t

as thevalue argument toPtSetArg(), andPtWebClientHistory t

as thelen argument.

Here’s an example of how to get the history:

PtArg t args[1];PtWebClientHistoryData t list[HISTORY REQUEST SIZE];PtWebClientHistory t list info;char *description[HI MAX LIST SIZE];int i, item count = 0, loop = TRUE;

list info.num = HISTORY REQUEST SIZE;list info.offset = 0;

/* retrieve history list from voyager server */while (loop) {

/* get the next 10 history entries */PtSetArg(&args[0], Pt ARG WEB GET HISTORY,

&list, &list info);PtGetResources( w, 1, args);



for (i=0; i < 10; i++, item count++) {if (list[i].url[0] == NULL ||

list[i].url[0] == 0 ||item count >= HI MAX LIST SIZE) {loop = FALSE;break;

}if ( description[item count] =

malloc(strlen(list[i].url) +strlen(list[i].title) + 4) )

sprintf(description[item count], "%s\t%s\t",list[i].title, list[i].url);

}list info.offset += HISTORY REQUEST SIZE;

}

Pt ARG WEB GET URL (write only)


char * String N/A

The URL that you want the browser to display or save. Set thelenargument ofPtSetArg() 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 ofh 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 serverusing 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, thenetfront 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, andurl aren’t used.) The client responds by setting thepassword member of thePt ARG WEB AUTHENTICATE resource.



Thenetfront 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 withreason 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 thevalue argument ofPtSetArg() to one of:

Pt WEB DIRECTION UP

Focus the frame above the current one.

Pt WEB DIRECTION DOWN

Focus the frame below the current one.

Pt WEB DIRECTION LEFT

Focus the frame to the left of the current one.

Pt WEB DIRECTION RIGHT

Focus the frame to the right of the current one.

Pt WEB DIRECTION FWD

Focus the next frame.

Pt WEB DIRECTION BACK

Focus the previous frame.



The next and previous directions are defined by the order of the<FRAME> tags in each<FRAMESET> tag.

☞

Pt ARG WEB NAVIGATE LINK


int Scalar 0

This resource controls focus navigation of links on the current pagewhen the browser is in key mode. Set thevalue 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 “ImageMapCursor” over the image map in thespecified direction. Thelen 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 thevalue argument to a direction and thelen argument tothe amount to scroll, in percentage of the visible page (e.g. 100 toscroll 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.



Thelen argument has no effect when usingPt WEB DIRECTION FWDor Pt WEB DIRECTION BACK.

☞

Getting the value of this resource indicates whether or not you canperform a given operation. Currently, onlyPt WEB DIRECTION FWDandPt WEB DIRECTION BACK are supported.

The format of the data returned is1 << 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-specific options

HTML Options

The HTML options are:

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 image placeholders for missing orinvalid images.

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 arming (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" — reformat the GUI after each subview isloaded. Any subviews with size hints aredisplayed 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"

HTTP cookie options

The HTTP cookie options are:

cookiejar name

The name of file to store cookie information in.

Default:"cookie.jar"

cookiejar path

The directory used to write the cookie file in.

Default:"$(HOME)"

cookiejar save always


Always keep the cookie-jar file on disk up-to-date.

Default:"FALSE"

cookiejar size

The maximum size, in bytes, that the cookie-jar file is allowedto grow. A value of"-1" means no limit.

Default:"-1"

Authentication options

The authentication options are:

max password guesses


The maximum number of guesses allowed when performingauthentication.

Default:"3"



FTP options

The FTP options are:

email address


The email address used for the password on anonymous loginson the 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 the 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"

Gopher options

The Gopher options are:

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

HTTP options

The HTTP options are:

http proxy host

The host name or IP address of the proxy server for HTTPrequests.

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

File options

The file options are:

file display dir




Display directory listings as HTML pages. For example,file:/ produces an HTML page with the content of the rootdirectory.

Default:"TRUE"

file strict access


Enable strict file access (file: URLs must have thePt WEB STRICT FILE ACCESSflag set when requested viaPt ARG WEB GET URL or Pt ARG WEB DOWNLOAD).

Default:"FALSE"

Image options

The image options are:

bProgressiveImageDisplay

Display images progressively as they’re being loaded.

Default:"TRUE"

concurrent decodes

The number of concurrent JPEG decodings that should be done.This option 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 the current graphics mode; if running on a high-coloror direct-color graphics driver, JPEGs are converted to thedefault color mode, usually 24-bit. If a palette-based graphicsdriver is running, the JPEGs are always converted to 256 colorsusing the current hardware palette, and setting this option hasno effect.)

Default:"FALSE"



Print options

The print options are:

Print Left Footer String

The left footer used when printing.

Default:"Page &"

Print Left Header String

The left header string used when printing.

Default:"&w"

Print Header Font

The font used in the header and footer.

Default:"helv"

Print Header Font Size

The font size used in the header and footer.

Default:"8"

Print Right Footer String

The right footer used when printing.

Default:"&d &t"

Print Right Header String

The right header string used when printing.

Default:"&u"

You can use these special characters in the header and footer strings:

"&w" Page title.

"&u" URL.

"&p" Page number.

"&d" Date — American style (“mmm dd yyyy”).



"&D" Date — European style (“dd mmm yyyy”).

"&t" Time — 12-hour format (“HH:MM am”).

"&T" Time — 24-hour format (“HH:MM”).

"&&" The ampersand ("&") character.

SOCKS options

These options are for the Voyager server only. The SOCKS optionsare:

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 user ID to pass to the SOCKS server.

Default: none

TCP/IP options

The TCP/IP options are:

file buckets


Fill network buffers before processing them.

Default:"TRUE"

max connections

Default:"4"



socket timeout


Default:"2400"

Disk-cache options

The disk-cache options are:

clear main cache on exit

Clear the on-disk cache when the browser exits.

Default:"FALSE"

dcache verify policy

0 means never verify if the document has changed;1 means verify if the document has changed once per session;2 means always verify if the document has changed.

Default:"0"

Note: Verifying is done by using the “If-Modified-Since”request-header.

enable disk cache

Enable on-disk caching.

Default:"TRUE"

keep index file updated


Keep the disk-cache index file updated on disk when it changes,instead of updating it once on exiting.

Default:"FALSE"

main cache dir

The directory used to store cache files.

Default:"/tmp"



main cache kb size

The maximum size of the on-disk cache.

Default:"5000"

main index file


The name of the cache index file.

Default:"main.ndx"

Miscellaneous options

The miscellaneous options are:

Page History Length

The maximum number of pages allowed in the page history(back/forward history).

Default:"50"

Use Anti Alias

Use anti-aliased fonts.

Default:"TRUE"

Use Double Buffer

Enable double-buffered rendering.

Default:"TRUE"

Visitation Horizon

The number of days after which to expire the visited linksdisplay (i.e. VLINK -> LINK).

Default:"4"

Voyager-server-only miscellaneous options:

Accept Charset Header

The value string to pass with theAccept-Charset header (seethe HTTP specification).



Default:"TRUE"

Accept Language Header

The value string to pass with theAccept-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 explicitAccept: content-type header requestfield in the HTTP header; otherwise sendAccept: */*.

Default:"TRUE"



Wait Cursor


Default:"e908" (the wait cursor)

NetFront-specific options

These options are specific to thenetfront server.

ServerId (Read only) The string identifier for the server.You can use this string if your client can be usedwith both thevserver andnetfront servers,and you want to do specific things when connectedto a certain server. The strings returned arevserver andNetfront, 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 is0.

fEnableWML Enable Wireless Markup Language (WML/WAP)support. The default is"FALSE".

fDisableSelection

Disable text slection. When"TRUE", a user can’tselect HTML text in the netfront canvas. Thedefault 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 thesrcattribute 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 widthequalsfMaxImageWidth.

� equal to"0" — the image is displayed at its realsize.

� less than"0" — specifies the negative of themaximum size of a viewport. If the width of animage is larger than that of the viewport, it isresized to the width of the viewport. If the imagesize to be displayed is larger than the specifiedvalue, the reduction decode is attempted. If thereduction decode is impossible, the image isresized again when it is displayed.

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

� equal to"0" — the image is displayed at its realsize.

� less than"0" — specifies the negative of themaximum size of a viewport. If the height of animage is larger than that of the viewport, it isresized to the height of the viewport. If the imagesize to be displayed is larger than the specifiedvalue, the reduction decode is attempted. If thereduction decode is impossible, the image isresized again when it is displayed.



Default:"0"

fMaxPixelsPerImage

The maximum image size, which is the width�height, in pixels. No limit if set to"-1".

This sets the maximum image file size that can bedisplayed. The size is determined by the width andheight recorded in the image file before the browserengine converts the size. It isn’t 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 to



display 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 thathaven’t been decoded yet. Pixelmaps outside thevisible display area are released.

� "INT MAX" — decode all the images thathaven’t been decoded yet. Pixelmaps aren’treleased.

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 pixelmapor 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 reflow. Thebrowser displays elements one by one, even if thelayout information isn’t calculated. It lays outagain if the element is changed when the layoutinformation is decided.

� "FALSE" — Don’t execute incremental reflow.

Default:"FALSE"

fTextareaRows

Default value for therows attribute of the<textarea> element.

Default:"4"

fTextareaCols

Default value for thecols attribute of the<textarea> element.

Default:"20"

fBlinkOnPeriod

The “on” time for the<blink> element, inmilliseconds.

Default:"1500"



fBlinkOffPeriod

The “off” time for the<blink> element, inmilliseconds.

Default:"800"

fBlinkLimitTime

The time limit for blinking of the<blink> element,in milliseconds. Set to"-1" for no limit.

Default:"-1"

fWapMarqueeSpeedFast

Thefast speed of a<marquee> element, inmilliseconds.

Default:"60"

fWapMarqueeSpeedNormal

Thenormal speed of a<marquee> element, inmilliseconds.

Default:"82"

fWapMarqueeSpeedSlow

Theslow 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 it 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 required todisplay a page.

� "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" is 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 if 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 theaccesskey 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 thetabindex 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" — don’t 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, inmilliseconds. 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 fasterpage-rendering times. Lower values means the process is interruptedmore often, possibly resulting in slower rendering times, but alsoallowing processes other than the browser engine more processortime.

☞

fPageMakerMaxStayTime

The maximum time for the “page maker progress”,before it can be interrupted, in milliseconds. Set to"0" or more.

Default:"100"

Higher values for “progress stay” times can result in faster 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.

☞

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

TransmitProxy-Connection: KeepAlive header atHTTP.

Default:"TRUE"

fSendReferer

TransmitReferer 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, in pixels.

Default:"30"

fBlockquoteMargin right

The right margin when drawing a<blockquote>element, in pixels.

Default:"30"

fBlockquoteMargin top

The top margin when drawing a<blockquote>element, in pixels.

Default:"19"

fBlockquoteMargin bottom

The bottom margin when drawing a<blockquote> element, in pixels.

Default:"19"

Pt ARG WEB PRINT (write-only)


PpPrintContext t *, int Pointer

Set this resource to print the page. You can use thelen 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 optionsto the web server to start. Setting this resource starts the server; ifthere’s a server already attached to the client, it’s shut down and thenew one is 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, andname is the named connectionthat the client must use to establish a connection to the server. Profilenames aren’t 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:

# default server for "online" browsing (i.e. www)online = vserver,VoyagerServer-2

#default server for "offline" browsing (i.e. files on disk)offline = vserver.file -l -nVoyagerOffline,VoyagerOffline

# server profile for using Mozilla 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 forPt 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 forPt 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 usemozilla 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 ifspawn()has failed.

Pt ARG WEB SSL RESPONSE


PtWebClient2SSLResponse 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 tothePt CB WEB SSL CERTNONTRUSTED andPt CB WEB SSL ERROR callbacks. The data structure used is asfollows:

typedef struct {char *url;int response;

} PtWebClient2SSLResponse t;


url A pointer to the URL obtained from thePt CB WEB SSL ERROR callback.




� Pt WEB RESPONSEOK — override the error andcontinue.

� Pt WEB RESPONSECANCEL — 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’tEOK, useerrno 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 downloading begins,the browser engine calls yourPt CB WEB DOWNLOAD callback.




typedef struct {short response;short zero;int download ticket;char *filename;char *url;

} PtWebClientUnknownData t;



� Pt WEB RESPONSEOK — thefilename file is valid;continue with the disk download.Pt CB WEB DOWNLOAD is called.

� Pt WEB RESPONSECANCEL — cancel thedownloading 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 thePt ARG WEB AUTHENTICATE resource.


reason Pt CB WEB AUTHENTICATE

reason subtype

Not used.

event NULL

cbdata A pointer to aPtWebAuthenticateCallback t

structure:

typedef struct {short type;short action;char *realm;char *url;

} PtWebAuthenticateCallback t;

The members of thePtWebAuthenticateCallback 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 CLOSEWINDOW

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 aPtWebCompleteCallback t structure:

typedef struct {char *url;

} PtWebCompleteCallback t;

Theurl 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 right-clicks on the current page with the mouse.


reason Pt CB WEB CONTEXT



reason subtype

Not used.

event NULL

cbdata A pointer to aPtWebContextCallback t structure:

typedef struct {long context;PhPoint t pos;

} PtWebContextCallback t;

The members of thePtWebContextCallback 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 PhotonLibraryReference) 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 theclient protocol in the URL



(e.g.client:about). The callback notifies the client that the serveris waiting for data; to return the data, set thePt ARG WEB DATAresource.


reason Pt CB WEB DATA REQ

reason subtype

The same as thetype member in the callback data.

event NULL

cbdata A pointer to aPtWebDataReqCallback t structure:

typedef struct {int type;int length;char *url;

} PtWebDataReqCallback t;

The members of thePtWebDataReqCallback 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, inbytes.

url A pointer to the URL of the request.

For an example of using theclient 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 aPtWebDownloadCallback t structure:

typedef struct {int download ticket;int type;int current;int total;char *url;char *message;

} PtWebDownloadCallback t;

The members of thePtWebDownloadCallback t structure are:

download ticket

This is thedownload ticket assigned to the downloadwhen you set thePtWebClientUnknownData t

structure for thePt 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 (seemessage).

� 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.Themessage is used only whentype isPt 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 asmailto:, allowing the client to handle them.

Themailto links are handled by the client. This is done by watchingfor themailto URL in thePt CB WEB ERROR callback.

☞


reason Pt CB WEB ERROR



reason subtype

Not used.

event NULL

cbdata A pointer to aPtWebErrorCallback t structure:

typedef struct {short type;short reason;char *url;char *description;

} PtWebErrorCallback t;

The members of thePtWebErrorCallback t structure are:

type The type of error:

� Pt WEB ERRORSERVEREXIT — the server hasterminated.

� Pt WEB ERRORTOPVIEW — an error occurredwhen loading the requested page.

� Pt WEB ERRORSUBVIEW — an error occurredwhen loading a subdocument of the requested page(e.g. images in an HTML page).

� Pt WEB ERRORFILE — an error occurred whensaving a document to disk.

� Pt WEB ERRORWML — an error occurred whenloading the requested WML page.

reason If type is Pt WEB ERRORSERVEREXIT, thereasonmember contains the terminating status of the server(usewaitpid () to determine why the serverterminated).

If type is Pt WEB ERRORWML, an error occurred inWML content, and thereason member contains oneof:



Pt WEB ERRORWML AccessDenied

Access rejection error caused by specifying anaccess element.

Pt WEB ERRORWML InvalidVariableReference

Incorrect variable name error.Pt WEB ERRORWML InfiniteLoop

The WML parser has detected an infinite loop.

Pt WEB ERRORWML Unknown

An unknown WML error has occurred.Pt WEB ERRORWML SAX

The WML parser has detected a syntax error.

For other values oftype, the possible values ofreasonare:

-1 Unspecified or unknown error.

-2 Parameter check / consistency check failed.

-3 Low memory.

-4 Low image-cache memory.

-5 The operation was aborted.

-6 Bad header.

-8 The document contains no data.

-9 Missing service API.

-10 Missing request API.

-11 Multiple initialization.

-12 DNS failure.

-13 Connection failure.

-14 Network failure.

-15 Bad input stream.

-16 Request for data sink failed.

-17 New data sink failed.



-18 Invalid redirect.

-19 Unknown server error.

-21 Unknown document character-set encoding.

-31 Corrupt data.

-39 Helper failed.

-40 SSL not supported.

-41 Unknown URL (No URL handler could 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 is too large.

-414 HTTP — Request URL too is large.

-415 HTTP — Unsupported media type.

-500 HTTP — Internal server error.

-501 HTTP — Not implemented.

-502 HTTP — Bad gateway.

-503 HTTP — Service unavailable.



-504 HTTP — Gateway time-out.

-505 HTTP — HTTP version not supported.

-1200 FTP — Server error.

-1202 FTP — Error 332.

-1203 FTP — Error 530.

description Thenetfront 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 Pt CB WEB IMPORT CERTIFICATE.

reason subtype

Not used.

event NULL

cbdata A pointer to aPtWebImportCertificateCallback t

structure:

typedef struct {int reason;char *description;} PtWebImportCertificateCallback t;



Thereason is one of:

� Pt WEB IMPORT CERTIFICATE OK

� Pt WEB IMPORT CERTIFICATE ERROR

If reason is Pt WEB IMPORT CERTIFICATE ERROR,description is a textual explanation for the error.

Pt CB WEB METADATA



A list of PtCallback t structures that define the callbacks 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 aPtWebMetaDataCallback t structure:

typedef struct {char *url;char *name;char *value;

} PtWebMetaDataCallback t;

Thename member for the web page title istitle.



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 aPtWebNeedScrollCallback t structure:

typedef struct {short dir;

} PtWebNeedScrollCallback t;

wheredir 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 newPtWebClient 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. the one the user clicked in).This doesn’t apply to Javascript open windows.


reason Pt CB WEB NEW WINDOW

reason subtype

Not used.

event NULL

cbdata A pointer to aPtWebWindowCallback t structure:

typedef struct {PhDim t size;long flags;

} PtWebWindowCallback t;

The members of thePtWebWindowCallback t structure are:

size A PhDim t structure (see the PhotonLibrary 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 aPtWebPageInfoCallback t structure:

typedef struct {long vheight;long vwidth;long height;long width;long ypos;long xpos;

} PtWebPageInfoCallback t;

The members of thePtWebPageInfoCallback 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 aPtWebSSLCertInfoCallback 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 thePtWebSSLCertInfoCallback t structure are:

url A pointer to the URL associated with the error.

cipher kind A pointer to the cipher suite used for theconnection (SSL3 RSA WITH RC4-128MD5,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 UTC) 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).

these callbacks should return onlyPt CONTINUE; there’s no need tofill up a special 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 a nontrusted certificate. Note that Voyagersupports only server certificates, and not Client certificates.


☞


reason Pt CB WEB SSL CERTNONTRUSTED



reason subtype

Not used.

event NULL

cbdata A pointer to aPtWebSSLCertNonTrustedCallback t

structure:

typedef struct {short action;short ncert;char *url;char *status;int reason;PtWebSSLCertInfo t info[1];} PtWebSSLCertNonTrustedCallback t;

The members of thePtWebSSLCertNonTrustedCallback t

structure are:

action One of the following:

� Pt WEB ACTION OK — the callback was invoked asa warning; The nontrusted certificate didn’t make theconnection to be aborted.

� Pt WEB ACTION ABORT — the connection wasaborted.

ncert The number of items in theinfo 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 ofPtWebSSLCertInfo 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 times (in seconds since 01/01/1970 0h UTC)at which the certificates became valid and invalid.

When this callback is invoked, typically the client displays a 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 aPtWebClient2SSLResponse t structure with the URL found inthe callback structure and one of these response codes:

Pt WEB RESPONSECANCEL

Abort the connection to the site.

Pt WEB RESPONSECONTINUE

Connect to the site, but don’t save the certificate.



Pt WEB RESPONSEOK

Connect to the site, and save the certificate.

Pt CB WEB SSL CLIENT CERT SELECT



A list of PtCallback t structures that define the callbacks that areinvoked when thenetfront 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 aPtWebClient2SSLResponse t structure with theurl 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 aPtWebSSLClientCertCallback t

structure:

typedef struct {int ncert;char *url;int reserved1;int reserved2;PtWebSSLCertInfo t *info;} PtWebSSLClientCertCallback t;



The members of thePtWebSSLClientCertCallback t structureinclude:

ncert The number of certificates to be displayed (the number ofitems in theinfo array).

url The current URL that have requested the client certificatesselection dialog to be displayed.

info An array of information about the certificates. See thePt CB WEB SSL CERTNONTRUSTED resource for adescription of thePtWebSSLCertInfo 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 aPtWebSSLErrorCallback t structure:

typedef struct {short certerr;short trusted;char *url;int reason;

} PtWebSSLErrorCallback t;

The members of thePtWebSSLErrorCallback t structure are:

� trusted — indicates whether the current certificate is trusted.

� url — a pointer to the URL associated with the error.

� reason — one of:

- Pt WEB SSL AUTHENTICATE — the callback is invokedduring an authentication.

- Pt WEB SSL IMPORT CERT— the callback is invoked duringan import certificate operation.

� certerr — one of the following:

Pt WEB ERRORCertNoError

You don’t have a trusted certification on your end.

Pt WEB ERRORCertChainInvalid

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 ERRORCertExpired

The certificate provided by the remote server has expired.

Pt WEB ERRORCertNamesNotEqual

The name in the certificate isn’t the same as its DNS name.Pt WEB ERRORCertChainIncomplete

This error can be overridden and is equivalent to receiving acertificate with an unknown and untrusted root certificate. If



you 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 ERRORInvalidSignature

Like Pt WEB ERRORCertChainInvalid, this error can’t beoverridden.

Pt WEB ERRORBasicConstraints

Violates basic constraints.Pt WEB ERRORFailedVerify

Cannot verify the signature.

Pt WEB ERRORIncorrectKeyUsage

Key use and extension key use are invalid.

Pt WEB ERRORRootCertificateNotValid

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 aPtWebClient2SSLResponse t structure with the URL found inthe callback structure and one of the following response codes:

� Pt WEB RESPONSEOK — override the error and continue.

� Pt WEB RESPONSECANCEL — 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 a



PtCallbackInfo 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 aPtWebStatusCallback 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 thetype 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="..."). ThedefaultStatus message appears when nothing else is in the statusbar.

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 printing 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 aPtWebUnknownCallback t structure:

typedef struct {short action;short flags;



char *content type;int content length;char *url;

} PtWebUnknownCallback t;

The members of thePtWebUnknownCallback 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 aPtWebUrlCallback t structure:

typedef struct {char *url;

} PtWebUrlCallback t;












Pt ARG CLIENT FLAGS PtClient

Pt ARG CLIENT NAME PtClient "VoyagerServer-2"

continued. . .




Pt ARG CLIENT REPLY LEN PtClient

Pt ARG CLIENT SEND PtClient

Pt ARG CLIENT SERVER PtClient










Pt ARG DIM PtWidget











continued. . .











Pt ARG POS PtWidget









Pt CB ARM PtBasic




Pt CB CLIENT CONNECTED PtClient

Pt CB CLIENT EVENT PtClient

Pt CB CLIENT NOT FOUND PtClient

continued. . .






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget






2005, QNX Software Systems Ltd. PtWidgetSuperclass for all widgets

Class hierarchy:PtWidget


� PtBasic

� PtTimer


Public header:<photon/PtWidget.h>

Description:PtWidget is the fundamental superclass. All widgets belong to asubclass ofPtWidget.

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.


PtWidget 2005, QNX Software Systems Ltd.

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.


2005, QNX Software Systems Ltd. PtWidget

If you usePt 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 CURSORDEFAULT COLOR

Pt ARG CURSOR TYPE unsigned short Scalar Ph CURSORINHERIT

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 overridePt ARG ANCHOR OFFSETS andPt ARG ANCHOR FLAGS.

☞

For more information about anchors, see the Geometry Managementchapter of the PhotonProgrammer’s Guide.

Pt ARG ANCHOR OFFSETS



The four values in thisPhRect t structure (see the PhotonLibraryReference) 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.)

ThePt 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 andPt ARG DIM.

Only offsets that have a corresponding bit set in thePt ARG ANCHOR FLAGS resource are applied. For example, let’ssay you have aPt ARG ANCHOR OFFSETS resource of (5,10,20,25)with absolute anchoring and aPt 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 PhotonLibrary 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 (seePt ARG FLAGS, below, and thePt ARG BASIC FLAGS resource defined forPtBasic).



Pt ARG BITMAP CURSOR


PhCursorDef t * Alloc NULL

Defines bitmaps for the cursor when the cursor type(Pt ARG CURSOR TYPE) is set toPh CURSORBITMAP. You can’tedit this resource in PhAB.

The widget automatically sets thehdr member of thePhCursorDef t structure. For information, see the PhotonLibraryReference.

Pt ARG CURSOR COLOR


PgColor t Scalar Ph CURSORDEFAULT COLOR

The color of the pointer when it’s inside the widget. SeePgColor t


Pt ARG CURSOR TYPE


unsigned short Scalar Ph CURSORINHERIT

The type of cursor:

Ph CURSORINHERIT

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 CURSORBITMAP

Use the bitmap stored inPt ARG BITMAP CURSOR for thecursor.



By default, bitmap cursors aren’t inherited by a widget’s childregions. To change this, setPt 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,seeBuilding 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 PhotonLibrary 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 thePhotonProgrammer’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 PhotonLibrary Reference) thatcontains theextent 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 PhotonLibrary 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 aPtDivider andyou usePtSetResources() to change the size of oneof its children, thePt 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 withPtRealizeWidget().

Pt DESTROYED(read-only)

The widget has been marked for destruction.

Pt FOCUSRENDER

Render a focus indicator when the widget when itgets focus.

Pt GETSFOCUS

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 bythePt 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 thePt 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 thePtList

andPtText created by aPtComboBox.

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 SELECTNOREDRAW

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 theh 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 thev 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 Thew (width) andh (height) hints for this childwidget. Think of these hints as a user definedminimum size, even if the widget could be smaller.Setw andh 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 usePtGridLayoutDataDfltsto 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 thePtHelp*() functions and the chapter onContext-Sensitive Help in the PhotonProgrammer’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 usingPtSetResource() or PtSetArg(), setthevalue 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 thelen argument to a pointer to the layout typethat corresponds to the data structure (that is,PtRowLayout orPtGridLayout). If you setlen 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 PhotonLibrary 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 PhotonLibrary 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 andPt 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 RESIZEX AS REQUIRED

� Pt RESIZEX ALWAYS

� Pt RESIZEX INITIAL

� Pt RESIZEX BITS

� Pt RESIZEY AS REQUIRED

� Pt RESIZEY ALWAYS

� Pt RESIZEY INITIAL

� Pt RESIZEY BITS

� Pt RESIZEXY ALWAYS

� Pt RESIZEXY AS REQUIRED

� Pt RESIZEXY INITIAL

� Pt RESIZEXY BITS

Note that each...BITSflag 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 viaPt ARG DIM orPt ARG AREA.

If a resize policyis 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 viaPt 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 PhotonProgrammer’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 Containsw (width) andh (height) hints for thischild widget. Think of these hints as a user definedminimum size, even if the widget could be smaller.Setw andh 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 theflags member of thePtRowLayoutInfo t of the parent.

� Pt ROW WRAP BEFORE— Unconditionallywrap this child.Pt ROW WRAP should be set intheflags member of thePtRowLayoutInfo 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 usePtRowLayoutDataDfltsto 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 andPt 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 aPhEvent 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, thePt CB IS DESTROYED callbacks are invoked whenthe widget’s resources are actually being released.

☞


reason Pt CB DESTROYED

event A pointer to aPhEvent t structure filled withNULLs.

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 havePt SELECTABLEset 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 aPtDndCallbackInfo 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 thedata 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 thefetch indexmember.

The following member is meaningful only when thereason subtype is Ph EV DND ENTER:

int unsigned flags

If set toPh 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().

ThePtTransportCtrl t structure also includes:

int unsigned handle

A variable for the your convenience. The valueplaced here will be found inhandle in subsequentcallbacks related to the ENTER event where thehandle was set.



Additional data is passed toPt CB DND callbacks for these widgetclasses:

� PtFileSel

� PtGenList

� PtGenTree

� PtList

� PtRawList

� PtRawTree

� PtTree

☞

A drag-and-drop recipient typically callsPtDndSelect() 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 invokedbefore the event is processed by thewidget. Contrast this resource withPt CB RAW.

☞

Because thePt 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 aPt CB FILTER callback to a widget in yourapplication’s code by callingPtAddFilterCallback() 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 hasPt CONSUME EVENTSset in itsPt ARG EFLAGS. If Pt CONSUME EVENTSisn’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 itsPt 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 aPt CB HOTKEY callback to a widget in yourapplication’s code by callingPtAddHotkeyHandler(). 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 aPtHotkeyCallback 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, thePt 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 PhotonProgrammer’s Guide.




reason Pt CB OUTBOUND

reason subtype

The button state (the same asptr->button state if the codegiven below is included in your callback).

event A pointer to aPhEvent t structure that describes theevent that caused the callback to be invoked. The eventdata is aPhPointerEvent 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 thePtRawCallback 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 invokedbefore the widgetprocesses the event.

☞

You can add aPt CB RAW callback to a widget in your application’scode by callingPtAddEventHandler() or PtAddEventHandlers(). Formore information about this callback, see “Event handlers” in theEvents chapter of the PhotonProgrammer’s Guide.


reason Pt CB RAW

event A pointer to aPhEvent t structure that describes theevent that caused the callback to be invoked. If thewidget’s class methods consumed the event,Ph CONSUMEDis set in the event’sprocessing 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



PtWindow 2005, QNX Software Systems Ltd.

An application window that’s managed by the Photon Window Manager

Class hierarchy:PtWidget → PtBasic → PtContainer → PtDisjoint →PtWindow

PhAB icon:None — use PhAB’s Window or Dialog module.

Public header:<photon/PtWindow.h>

Description:ThePtWindow 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 PhotonLibrary Reference).

A PtWindow widget that contains an editor application.

The frame and title bar aren’t part of thePtWindow widget; thewindow manager adds them. The value of the widget’sPt ARG DIMresource doesn’t include the frame, but you can callPtWindowGetFrameSize() to determine the size of the frame.


2005, QNX Software Systems Ltd. PtWindow

� Use PhAB’s Window module instead of using this widget directly.See “Window modules” in the Working with Modules chapter ofthe PhotonProgrammer’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 PhotonProgrammer’s Guide.

☞

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

Setting the window’s title

You can specify the string displayed in the window’s title bar bysetting thePt ARG WINDOW TITLE resource.

Controlling the decorations

You control the elements displayed in the window frame using thePt ARG WINDOW RENDER FLAGS resource. Enable or disable awindow-frame element by setting or clearing the appropriate bit.



ThePt ARG WINDOW RENDER FLAGS resource also has one ofthe following bits set to specify how the window and its frame aredisplayed and behave:

� Ph WM RENDER ASAPP

� Ph WM RENDER ASDIALOG

� Ph WM RENDER ASICON

� Ph WM RENDER ASPALETTE

Controlling window resizing

If you need to control the maximum and minimum possible sizes forthe window, use thePt ARG MAXIMUM DIM andPt ARG MINIMUM DIM resources defined byPtWidget.

The following resources also control the window’s size:

� Pt ARG MAX HEIGHT

� Pt ARG MAX WIDTH

� Pt ARG MIN HEIGHT

� Pt ARG MIN WIDTH

Enabling Window Manager functions

You can control how the Window Manager operates on your windowby settingPt 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 FOCUSLIST

Prevent you from cycling focus to the window bypressingAlt – 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.

Notifying the application

You may also tell the Window Manager to notify the application afterit has done a Window Manager operation. This behavior is controlledby thePt 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’sPt 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)

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 FLAGS unsigned short Flag See below

Pt ARG WINDOW FRONT WINDOW PhRid t Scalar 0

Pt ARG WINDOW HELP ROOT char * String NULL

Pt ARG WINDOW INACTIVE COLOR PgColor t Scalar See below

Pt ARG WINDOW MANAGED FLAGS unsigned long Flag See below

Pt ARG WINDOW NOTIFY FLAGS unsigned long Flag See below

Pt ARG WINDOW RENDER FLAGS unsigned long Flag See below

Pt ARG WINDOW STATE unsigned long Flag See below

Pt ARG WINDOW TITLE char * String "Untitled"

Pt ARG WINDOW TITLE COLOR PgColor t Scalar See below

Pt CB WINDOW PtCallback t * Link NULL

Pt CB WINDOW CLOSING PtCallback t * Link NULL

Pt CB WINDOW OPENING PtCallback t * Link NULL

Pt CB WINDOW TRANSPORT PtCallback t * Link NULL



Pt ARG MAX HEIGHT


short Scalar 0 (See below)

The maximum height of the window. If you set this resource to 0, thedefault value specified by the window manager is used.

You should usePt 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 usePt 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 usePt 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 usePt 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 FLAGS


unsigned short Flag Pt WINDOW FRAME BLOCKABLE

This resource has a single bit,Pt WINDOW FRAME BLOCKABLE. Itcontrols whether the Window Manager knows that the window widgetis blocked with thePt BLOCKED flag in Pt ARG FLAGS. If this bit isnot set, a user can give the window focus and resize it, even if it’sblocked.

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, seethePtHelp*() functions in the PhotonLibrary Reference and theContext-Sensitive Help chapter of the PhotonProgrammer’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 long 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

continued. . .



If you set this bit: the Window Manager:

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, setPh WM STATE ISFRONTinthePt 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

Ph WM NO FOCUSLIST Doesn’t let you cycle focus to thewindow when you pressAlt – 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 isPh 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 long Flag Ph WM RESIZE|Ph WM CLOSE|Ph WM HELP

This resource controls which events thePt 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 FOCUSLIST

� Ph WM TASKBAR



Pt ARG WINDOW RENDER FLAGS


unsigned long 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 isPh 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 long Flag Ph WM STATE ISFOCUS

This resource controls the window’s state. You can set one of thefollowing:



Ph WM STATE ISALTKEY

PassAlt 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 creatingthePtWindow widget or in the window’sPt CB WINDOW OPENING callback. The setting will be in effectwhen the window is realized.

You can setPt 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.SeePt ARG WINDOW NOTIFY FLAGS.


reason Pt CB WINDOW

reason subtype

0 (not used).


cbdata A pointer to aPhWindowEvent t (described in thePhotonLibrary 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 PhotonProgrammer’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 toPtDestroyWidget()or PtUnrealizeWidget(). If you want to make sure in a WindowClosing callback that the window is actually being destroyed, checkthePt DESTROYEDflag in Pt ARG FLAGS. You can also use thePt CB DESTROYED callback to know when a window is marked fordestruction, orPt CB IS DESTROYED to know when it is beingdestroyed.

ThePt CB WINDOW CLOSING callbacks are invoked when thewindow is already closing. To be notified before the window is closed,use thePh WM CLOSEbit in Pt ARG WINDOW NOTIFY FLAGSand thePt 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 thePt 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 aPhEvent 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 ARG SYSINFO PtDisjoint







continued. . .




Pt CB ARM PtBasic






Pt CB DND PtWidget






Pt CB MENU PtBasic


Pt CB RAW PtWidget




Pt CB SYSINFO PtDisjoint


Convenience functions:ThePtWindow 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.


2005, QNX Software Systems Ltd. PtWindowFocus()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


PtWindowFocus() 2005, QNX Software Systems Ltd.

See also:PtWindowToBack(), PtWindowToFront()

PtForwardWindowEvent() in the PhotonLibrary Reference


2005, QNX Software Systems Ltd. PtWindowGetState()Return the current state of a window

Synopsis:long PtWindowGetState( PtWidget t *widget )

Description:This function returns the current state of the window pointed to by 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 aPtWindowor wasn’t realized.


Safety


Signal handler No

continued. . .


PtWindowGetState() 2005, QNX Software Systems Ltd.

Safety

Thread No


2005, QNX Software Systems Ltd. PtWindowToBack()Move a window to the back of the workspace

Synopsis:void PtWindowToBack( PtWidget t *widget );

Description:This function moves the specified window widgetand 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


PtWindowToBack() 2005, QNX Software Systems Ltd.

See also:PtWindowFocus(), PtWindowToFront()

PtForwardWindowEvent(), PtWidgetToBack(), PtWidgetToFront() inthe PhotonLibrary Reference


2005, QNX Software Systems Ltd. PtWindowToFront()Bring a window to the front and give it focus

Synopsis:void PtWindowToFront( PtWidget t *widget );

Description:This function brings the specified window widgetand 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


PtWindowToFront() 2005, QNX Software Systems Ltd.

See also:PtWindowToBack(), PtWindowFocus()

PtForwardWindowEvent(), PtWidgetToBack(), PtWidgetToFront() inthe PhotonLibrary Reference


Glossary

January 31, 2005 Glossary 1257


accelerator

Seehotkey.

activate

A widget is usuallyactivated when you release a mouse button whilepointing at anarmed widget.

active window

The window that currently hasfocus.

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 thedevice region.Also called awindow region.

argument list

An array of typePtArg t used when setting and getting widgetresources.

arm

A widget is usuallyarmed 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 morebitplanes.

bitplane

An array of bits representing pixels of a single color in abitmap.

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 acallback 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. ForPtWidget, this isthe area inside the widget’s borders. ForPtBasic and itsdescendants, the canvas is the area inside the widget’s border and

1260 Glossary January 31, 2005


margins. Other widgets, such asPtLabel, may define additionalmargins.

class

Seewidget 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

SeeCUA.

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 thedesktop. Also called aworkspace.

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, andPtOSContainer.

cooked event

A key or pointer event that has been assigned a location in the Photonevent space. Also called afocused 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 pressEnter 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 apointer 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, orrealized), it’s said tobedamaged.

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 ofspecific placement.

desktop

The virtual screen, consisting of nineconsoles or workspaces.

device region

Theregion located in the middle of theevent space, with applicationregions behind it anddriver regions in front of it (from the user’spoint of view).

dialog module

A PhAB module similar to awindow 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.Contrastpalette-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, andPtRegion are disjoint widgets, butPtButton, PtBkgd, andPtRect 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 thedeviceregion.

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 theroot 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 anevent 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 aregion 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 hasfocus will receive any key events collected by itswindow.

focus region

A region placed just behind thedevice region by thePhotonWindow Manager that lets it intercept key events and direct them totheactive window.

focused event

A key or pointer event that has been assigned a location in the Photonevent space. Also called acooked event.

folder

In the Photon File Manager, a metaphor for a directory.

GC

Seegraphics 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 anaccelerator.Contrastkeyboard 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 alsodirect-color andpalette-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 andpulses 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 thePtButton

widget class. When an instance of a widget is created, the initialvalues of itsresources 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 aninstance 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. Contrasthotkey.

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

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 asShift, 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 isopaque 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. Ahard palette is in hardware; asoft palette is insoftware.

palette-based

A color scheme in which each pixel is represented by an index into apalette. Contrastdirect-color.

PDR

SeePress-drag-release.

PFM

SeePhoton 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. Seealsoditto.

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-pointrectangle 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 thePtList andPtText created by aPtComboBox. Alsoknown as asubordinate 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

SeeImage Viewer.

PWM

SeePhoton Window Manager.



raw event

An input event that hasn’t been assigned a location in the Photonevent space. Also called anunfocused event.

raw callback

A function that lets an application respond directly to Photon eventssuch as dragging events. Also called anevent 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 issensitive 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 ofdefault placement.

subordinate child

A widget created by another widget (as opposed to an application),such as thePtList andPtText created by aPtComboBox. Alsoknown as aprocreated widget.

table-of-contents (TOC) file

In the PhotonHelpviewer, 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 oftitles 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

Seeraw event.

Unicode

The ISO/IEC 10646 16-bit encoding scheme for representing thecharacters used in most languages.

UTF-8

The encoding forUnicode 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 widgetinstances. For example, a window and thewidgets it contains.

widget instance

Seeinstance.

window frame region

A region that PWM adds to a window. It lets you move, resize,iconify, and close the window.

Window Manager

SeePhoton Window Manager.

window module

A PhAB module that’s instantiated as aPtWindow 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

Seeconsole.

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 1206

A

accelerators 457menu items 505

activationany mouse button 1203defined 47Pt CB ACTIVATE 64, 957

anchor flags 1197, 1198anchor offsets 1197, 1198animation See PtFlasharc widget See PtArcarea 1193, 1199arming

defined 47Pt CB ARM 65

arrow keysdisablingPtGroup 431PtScrollArea 782

enablingPtContainer 183

PtMeter 546, 547PtText 921PtTextSetSelection() 949

autohighlighting 1203

B

Bezier curve widget SeePtBezier

backgroundcolor 59pattern 60, 417widget See PtBkgd

balloonscallback 191customizing 459disabling 183fill color 457popping up immediately 1198position 455, 458PtBalloonCallback t 5text 458

January 31, 2005 Index 1279

Index 2005, QNX Software Systems Ltd.

text color 457bandwidth, graphics threshold 52bar graph widget See PtBarGraphbasic widget See PtBasicbevel

colormain 56

full 54rendering 54width 54, 1199

bevel color 58, 61bevels

static 56bitmap widget

label See PtLabelblocking 1203

hotkeys 1221Pt CB BLOCKED 1215

bordercolor

inline 60outline 62

roundness 60browse mode 314browser

seePtWebClient 1097button widget

menu See PtMenuButtonon/off See PtOnOffButtonpushbutton See PtButtontoggle See PtToggleButtonup/down See PtUpDown

C

calendar widget See PtCalendarcallbacks

activate 64, 957arguments 7arm 65balloon 191blocked 1215child added/removed 192destroyed 1215, 1222disarm 66drag and drop 1216filter 1219getting focus 193got focus 67, 921hotkey 1221invoking when resources are

set 1203losing focus 195lost focus 68, 921menu 48, 69outbound 1222PtBalloonCallback t 5PtCallback t 7PtCallbackInfo t 9PtHotkeyCallback t 11PtRawCallback t 13raw 1223realized 1225repeat 48, 70resizing 196return value 8right mouse button 48, 69unrealized 1225

canvasdetermining

1280 Index January 31, 2005

2005, QNX Software Systems Ltd. Index

PtScrollArea 791child added/removed callback 192chord 34circle widget See PtEllipseclass hierarchy 17clipped highlighting rectangle 1204clock widget See PtClockcolor

background 59bevel 58, 61

main 56border

inline 60outline 62

fill 58, 59, 61font selector

text 288text background 288

foreground 57models 142

color selectors SeePtColorPanel, SeePtColorPatch, SeePtColorSelGroup, SeePtColorSel, SeePtColorWell

color-gradient widget See PtBkgdcolumn widget See PtGroupcombobox widget See

PtComboBox

compound widget See alsoPtCompound

procreated child 1205container widget

flags 183, 190general purpose See

PtContainer

offscreen-context SeePtOSContainer

contrast 57contrast, bevel 57contributed widgets xixcreating a drawing 412Ctrl-click selection 314CUA (Common User Access)

enabling 183enabling arrow keys 183preventing focusing 183

cursorbitmap 1200color 1200type 1200

D

damagefamily 1204parent 1202widget 1204

dashed lines 416data, user-defined 957, 1194, 1211,

1214PtRaw 731

destructionmarking for 1204Pt CB DESTROYED 1215Pt CB IS DESTROYED 1222

device emulator widget See PtTtydimensions 1193, 1199, 1201,

1209, 1215maximum 1194, 1210minimum 1194, 1211



dimming 63, 417, 1204disarming

defined 47Pt CB DISARM 66

disjoint widget See PtDisjointdivider widget See PtDividerdrag and drop

Pt CB DND 1216Pt CB OUTBOUND 1222

draggingPt CB OUTBOUND 1222

drawingcolor 57flicker-free See

PtOSContainer

using graphical widgets 410,412

using primitive graphicsfunctions 730

E

edgesalpha line 53bevel 54inline 54, 60outline 54, 62

edit masks 923ellipse widget See PtEllipseelliptical arc widget See PtArcevents

blocking 1203, 1215consuming 1202, 1224filter callbacks 1219PtRawCallback t 13

hotkeyscallback 1221PtHotkeyCallback t 11terminating searches for 184

keyconsuming 309processing as hotkeys

first 184pendingPtFileSel 235

Ph EV BUT REPEAT 70raw callbacks 1223PtRawCallback t 13

repeat callback 70window manager 1230, 1236,

1241extended flags 1202extended-selection mode 314extent 1193, 1202.See also

resizingno intersections with 1204recalculating

automatically 183

F

FD CLOEXEC 1076, 1078file folder widget See PtTabfile selector widget See

PtFileSel

fillcolor 59flat 55gradient 55pattern 60, 417



reverse gradient 55fill color 58, 61filter callback 1219filter callbacks 13flags

anchor 1197, 1198container 183, 190extended 1202generic list 309generic list column 307generic tree 364, 390graphic 416group 431

alignment in cells 430menu 517PtColorPanel 130PtColorPatch 136PtColorSelGroup 150PtColorWell 155PtRawList 742region 774resize 1212widget 1203

flicker-free drawing SeePtOSContainer

floating-point number widget SeePtNumericFloat

flux 1205focus

getting 1203granting 1204Pt CB CHILD GETTING FOCUS

193Pt CB CHILD LOSING FOCUS

195Pt CB GOT FOCUS 67, 921Pt CB LOST FOCUS 68, 921

Pt GEN LIST NO AUTOFOCUS743

rendering 1204font selector widget See

PtFontSel

force front 1234, 1239foreground color 57FORM-CHECKBOX 1185FORM-COMBO 1185FORM-CURSOR-BOTTOM 1186FORM-CURSOR-LEFT 1186FORM-CURSOR-RIGHT 1186FORM-CURSOR-TOP 1186FORM-EDIT 1185FORM-LIST 1185FORM-MULTILIST 1185FORM-PASS 1185FORM-RADIO 1186FORM-RESET 1186FORM-SUBMIT 1186FORM-TEXTAREA 1185FRAMESET-DOC 1186

G

gauge widget See PtGaugegeneric list widget See

PtGenList

generic tree widget SeePtGenTree

ghosting 63, 417, 1204gradient

fill 55static 56

graphics



bandwidth threshold 52vector 410

graphics primitives functions 730graphics primitives widget

arc See PtArcBezier curve See PtBeziercircle, ellipse See PtEllipseflags 416line See PtLinepixels See PtPixelpolygon See PtPolygonrectangle See PtRectsuperclass See PtGraphic

grid widget See PtGridgroup widget See PtGroup

H

height 1193, 1199, 1201, 1209maximum 1194, 1210minimum 1194, 1211

helpbutton 1237in a balloon 1202information 1210root 1234topic path 1209

highlightingautomatically 1203clipping corners 1204requesting 1205

HOST NOT FOUND 1115hotkeys

accelerator key 457blocking 1221

callback 1221menu items 505PtHotkeyCallback t 11terminating searches for 184

hyperlinks 577

I

image widgetbackground See PtBkgdlabel See PtLabel

imagesviewing See PtImageArea

increment/decrement button widgetSee PtUpDown

insert mode 911integer widget See

PtNumericInteger

J

Jump Gate 1243

K

key eventsconsuming 309processing as hotkeys first 184



L

label widget See PtLabellayouts

PtWidget 1202line widget See PtLinelines, dashed 416LINK-IMAGE 1186LINK-IMAGE-MAP 1186LINK-TEXT 1186List Draw method

PtList 336list widget

superclass See PtGenListtext items See PtListwith text-entry field See

PtComboBox

list, raw See PtRawList

M

Macromedia Flash 4 See PtFlashmargins

height 62width 62

matrix widget See PtGroupMAX URL LENGTH 1114memory context 660memory, freeing

when destroying awidget 1222

menuenabling mouse button 1205item, indicating 1205Pt CB MENU 48, 69

menu bar widget See PtMenuBar

menu button widget SeePtMenuButton

menu widget See PtMenumeter widget See PtMetermethods

List DrawPtList 336

Tree Item Statetree widgets 380, 382

mouseleft button actions 47

click count 64Pt CB ACTIVATE 64, 957Pt CB ARM 65Pt CB DISARM 66

making actions the same for allbuttons 48, 1203

right button action 48, 1205Pt CB MENU 48, 69

multiline text widget SeePtMultiText

multiple choice widget SeePtComboBox

multiple-select mode 314

N

navigation See CUA (CommonUser Access)

NO DATA 1115NO RECOVERY 1115numeric widget

floating-point SeePtNumericFloat



integer SeePtNumericInteger

range of values SeePtSlider

superclass See PtNumeric

O

obscuring 1205offscreen-context container widget

See PtOSContaineron/off button widget See

PtOnOffButton

opacity 1205

P

PAGE-BOTTOM 1186PAGE-LEFT 1186PAGE-RIGHT 1186PAGE-TOP 1186pane widget See PtFlash, See

PtPane

panels See PtPanelGrouppasswords, entering into a

PtText 917pattern

background 60, 417fill 60, 417transparency 63, 417

Pg BEVEL JOIN 418Pg BITMAP BACKFILL 454Pg BITMAP TRANSPARENT 454Pg BUTT CAP 418

Pg BUTT JOIN 418Pg CLOSED 74, 698Pg CM CMYK 143Pg CM HLS 142Pg CM HSB 142Pg CM RGB 142PgColor t 603, 605Pg IMAGE DIRECT 555 454Pg IMAGE DIRECT 664 454Pg IMAGE DIRECT 888 454Pg IMAGE DIRECT 8888 454Pg IMAGE PALETTE BYTE 454Pg IMAGE PALETTE NIBBLE 454Pg MITER JOIN 418Pg POLY RELATIVE 698Pg QROUND JOIN 418Pg RELATIVE 74Pg ROUND CAP 418Pg ROUND JOIN 418Pg SQUARE CAP 418Ph AUXPTR REGION 774Ph BAUD SLOW 798Ph CONSUMED 1224Ph CURSORBITMAP 1200PhCursorDef t 1200Ph CURSORINHERIT 1200Ph CURSORNO INHERIT 1201Ph CURSORSET 774Ph EV BOUNDARY 191, 192Ph EV DND CANCEL 1217Ph EV DND COMPLETE 1217Ph EV DND DROP 1217Ph EV DND ENTER 1217Ph EV DND LEAVE 1217Ph EV DND MOTION 1217Ph EV PTR MOTION NOBUTTON 192Ph EV PTR STEADY 191



Ph FOLLOW IG SIZE 774Ph FORCEBOUNDARY 192, 774Ph FORCEFRONT 774Ph GRAFX REGION 774Ph INPUTGROUPREGION 774Ph KBD REGION 774Ph NO COMPRESSION 774Ph PRINT REGION 774Ph PTR REGION 774Ph WINDOW REGION 774Ph WM APP DEF MANAGED 1235Ph WM BACKDROP 1234Ph WM CLOSE 1234Ph WM COLLAPSE 1234Ph WM CONSWITCH 1234Ph WM FFRONT 1234, 1236Ph WM FOCUS 1234Ph WM HELP 1234Ph WM HIDE 1234Ph WM MAX 1234Ph WM MENU 1234Ph WM MOVE 1234Ph WM NO FOCUSLIST 1234,

1236Ph WM RENDER ASAPP 1228,

1237Ph WM RENDER ASDIALOG 1228,

1237Ph WM RENDER ASICON 1228,

1237Ph WM RENDER ASPALETTE 1228,

1237Ph WM RENDER BORDER 1237Ph WM RENDER CLOSE 1237Ph WM RENDER COLLAPSE 1237Ph WM RENDER HELP 1237Ph WM RENDER INLINE 1237

Ph WM RENDER MAX 1238Ph WM RENDER MENU 1238Ph WM RENDER MIN 1238Ph WM RENDER RESIZE 1238Ph WM RENDER TITLE 1238Ph WM RESIZE 1234Ph WM RESTORE 1234Ph WM STATE ISALTKEY 1239Ph WM STATE ISBACKDROP 1239Ph WM STATE ISBLOCKED 1239Ph WM STATE ISCOLLAPSE 1239Ph WM STATE ISFOCUS 1239Ph WM STATE ISFRONT 1239Ph WM STATE ISHIDDEN 1239Ph WM STATE ISICONIFIED 1239Ph WM STATE ISMAX 1239Ph WM TASKBAR 1234, 1236Ph WM TOBACK 1234Ph WM TOFRONT 1234Ph WND MGR REGION 774pie wedge 34pixel widget See PtPixelPk Cyrillic IO 288pointer

left button actions 47click count 64Pt CB ACTIVATE 64, 957Pt CB ARM 65Pt CB DISARM 66

making actions the same for allbuttons 48, 1203

right button action 48, 1205Pt CB MENU 48, 69

points widget See PtPixelpolygon widget See PtPolygonposition 1193, 1199, 1211PpPrintContext t 706



primitive graphics functions 730print selector widget See

PtPrintSel

procreated child 1205progress widget See PtProgressPt ALL 55Pt ALL BEVELS 55Pt ALL BOTTOM 55Pt ALL BUTTONS 48, 70, 1203Pt ALL ETCHED 54Pt ALL ETCHES 54Pt ALL INLINES 55Pt ALL LEFT 55Pt ALL OUTLINES 54Pt ALL RIGHT 55Pt ALL TOP 55PtArc 32

control points 32end angle 33Pt ARG ARC END 33Pt ARG ARC START 34Pt ARG ARC TYPE 34Pt ARG DIM 32Pt ARG ORIGIN 32Pt ARG POINTS 32start angle 34type 34

Pt ARC CHORD 34Pt ARC CURVE 34Pt ARC PIE 34Pt ARG ACCEL FONT 531Pt ARG ACCEL KEY

PtLabel 457PtMenuButton 530

Pt ARG ACCEL TEXT 531Pt ARG ANCHOR FLAGS 1197,

1198

Pt ARG ANCHOR OFFSETS1197, 1198

Pt ARG ARC END 33Pt ARG ARC START 34Pt ARG ARC TYPE 34Pt ARG AREA

PtScrollArea 780, 783, 784PtTerminal 856, 857PtWidget 1193, 1198,1199

Pt ARG ARM COLOR 86, 87,1090

Pt ARG ARM FILL 86, 87Pt ARG ARM IMAGE 86, 87Pt ARG BALLOON COLOR

PtGenList 307PtLabel 457

Pt ARG BALLOON FILL COLORPtGenList 307PtLabel 457

Pt ARG BALLOON POSITION451, 455, 458

Pt ARG BALLOON TEXT 458Pt ARG BANDWIDTH THRESHOLD

PtBasic 52PtDivider 213PtScrollbar 802PtTerminal 862, 890PtTty 1086

Pt ARG BARGRAPH BASEPtBarGraph 40

Pt ARG BARGRAPH COLORPtBarGraph 39, 40

Pt ARG BARGRAPH DATAPtBarGraph 38, 40

Pt ARG BARGRAPH DEPTHPtBarGraph 41

Pt ARG BARGRAPH FLAGS



PtBarGraph 41Pt ARG BARGRAPH GRID COLOR

PtBarGraph 42Pt ARG BARGRAPH GRID HORIZ

PtBarGraph 42Pt ARG BARGRAPH GRID VERT

PtBarGraph 42Pt ARG BARGRAPH MAX

PtBarGraph 42Pt ARG BARGRAPH MIN

PtBarGraph 43Pt ARG BEVEL COLOR 56Pt ARG BEVEL CONTRAST

PtBasic 57Pt ARG BEVEL WIDTH

PtBasic 54PtMenu 518PtWidget 1199

Pt ARG BEZIER FLAGS 74Pt ARG BITMAP CURSOR 1200Pt ARG BKGD IMAGE 79Pt ARG BKGD SPACING X 80Pt ARG BKGD SPACING Y 80Pt ARG BKGD TILE 80Pt ARG BUTTON TYPE 511,531Pt ARG CALENDAR COLOR1 95Pt ARG CALENDAR COLOR2 95Pt ARG CALENDAR COLOR3 95Pt ARG CALENDAR COLOR4 95Pt ARG CALENDAR COLOR5 96Pt ARG CALENDAR DATE 96Pt ARG CALENDAR FLAGS 97Pt ARG CALENDAR FONT1 97Pt ARG CALENDAR FONT2 98Pt ARG CALENDAR FONT3 98Pt ARG CALENDAR FONT4 98Pt ARG CALENDAR FONT5 98

Pt ARG CALENDAR HIGHLIGHT98

Pt ARG CALENDAR MONTH BTN COLOR99

Pt ARG CALENDAR MONTH NAMES99

Pt ARG CALENDAR SEL COLOR100

Pt ARG CALENDAR TIME T 100Pt ARG CALENDAR WDAY NAMES

101Pt ARG CALENDAR YEAR BTN COLOR

102Pt ARG CBOX BUTTON WIDTH

163Pt ARG CBOX FLAGS 161, 163Pt ARG CBOX MAX VISIBLE COUNT

164Pt ARG CBOX SEL ITEM 164Pt ARG CBOX TEXT FILL COLOR

165Pt ARG CELL HORZ ALIGN 430Pt ARG CELL VERT ALIGN 430Pt ARG CLIENT FLAGS

PtClient 108Pt ARG CLIENT NAME 108, 109,

112Pt ARG CLIENT REPLY LEN

PtClient 109Pt ARG CLIENT SEND

PtClient 109Pt ARG CLIENT SERVER

PtClient 110Pt ARG CLOCK FACE COLOR

119Pt ARG CLOCK FACE OUTLINE COLOR

119



Pt ARG CLOCK FLAGS 119Pt ARG CLOCK FONT 120Pt ARG CLOCK HOUR 120Pt ARG CLOCK HOUR COLOR

121Pt ARG CLOCK HOUR OFFSET

121Pt ARG CLOCK MINUTE 121Pt ARG CLOCK MINUTE COLOR

121Pt ARG CLOCK MINUTE OFFSET

122Pt ARG CLOCK SECOND 122Pt ARG CLOCK SECOND COLOR

122Pt ARG CLOCK SECOND OFFSET

122Pt ARG CLOCK SEP1 123Pt ARG CLOCK SEP1 COLOR


123Pt ARG CLOCK TYPE 124Pt ARG COLOR

PtBarGraph 39, 40PtBasic 57PtMultiText 571, 604, 606PtRaw 733PtTrend 1053

Pt ARG COLUMNS 927Pt ARG CONTAINER FLAGS

183, 190Pt ARG CONTRAST

PtBasic 57Pt ARG CPANEL FLAGS

PtColorPanel 130

Pt ARG CPATCH FLAGSPtColorPatch 136

Pt ARG CS COLORPtColorSel 142

Pt ARG CS CURRENT MODELPtColorSel 143

Pt ARG CS FLAGSPtColorSel 143

Pt ARG CSGROUP FLAGSPtColorSelGroup 150

Pt ARG CS PALETTEPtColorSel 144

Pt ARG CURSOR COLOR 1200Pt ARG CURSOR OVERRIDE

184Pt ARG CURSOR POSITION 927Pt ARG CURSOR TYPE 1200Pt ARG CWELL FLAGS

PtColorWell 155Pt ARG CWELL SWATCH DIM

PtColorWell 155Pt ARG DARK BEVEL COLOR

PtBasic 58Pt ARG DARK FILL COLOR

PtBasic 58Pt ARG DASH LIST

PtGraphic 416Pt ARG DASH SCALE

PtGraphic 416Pt ARG DATA 1201Pt ARG DIM

PtArc 32PtEllipse 215PtMultiText 579PtRect 766PtTerminal 856–858, 860PtText 927



PtWidget 1193,1201Pt ARG DIVIDER FLAGS 207Pt ARG DIVIDER OFFSET 208Pt ARG DIVIDER SIZES 208Pt ARG EDIT MASK 923, 927Pt ARG EFLAGS 1202, 1209Pt ARG EXTENT

PtWidget 1193,1202Pt ARG FILL COLOR

PtBasic 59PtMultiText 571, 604, 606PtOSContainer 664PtRaw 733PtTerminal 890PtTrend 1052

Pt ARG FILL LAYOUT INFO186

Pt ARG FILL PATTERN 60Pt ARG FLAGS 1216

menu items 505PtBasic 47, 48, 64, 70PtClock 124PtContainer 193PtDivider 208PtFontSel 288PtGauge 297PtGenList 317PtMenu 507PtMeter 546, 547PtMultiText 593PtOnOffButton 655PtPanelGroup 679PtScrollArea 786PtScrollbar 797PtSlider 839PtText 914, 922, 932, 933,

935, 941, 947

PtToggleButton 956PtTty 1066PtWidget 1203

Pt ARG FLASH FILE 279Pt ARG FONT DISPLAY 285Pt ARG FONT FLAGS 285Pt ARG FONT LBL BKGDCOLOR

286Pt ARG FONT LBL FONT 286Pt ARG FONT LBL SIZE 286Pt ARG FONT LBL STYLE 286Pt ARG FONT LBL TEXTCOLOR

287Pt ARG FONT NAME 287Pt ARG FONT POINT SIZE MAX

287Pt ARG FONT SAMPLE 287Pt ARG FONT SYMBOL 288Pt ARG FONT TEXT BKGD COLOR

288Pt ARG FONT TEXT COLOR

288Pt ARG FS FILE SPEC 229Pt ARG FS FLAGS 221, 229Pt ARG FS FORMAT 230Pt ARG FS IMAGES 231Pt ARG FS LBL DATE 233Pt ARG FS LBL GROUP 233Pt ARG FS LBL NAME 233Pt ARG FS LBL OWNER 234Pt ARG FS LBL PERMISSIONS

234Pt ARG FS LBL SIZE 234Pt ARG FS REFRESH 234Pt ARG FS ROOT DIR 235Pt ARG GAUGE FLAGS

PtGauge 294



PtProgress 716PtSlider 838

Pt ARG GAUGE FONT 295Pt ARG GAUGE H ALIGN 295Pt ARG GAUGE V ALIGN 296Pt ARG GAUGE VALUE 296Pt ARG GAUGE VALUE PREFIX

296Pt ARG GAUGE VALUE SUFFIX

296Pt ARG GRAPHIC FLAGS 416Pt ARG GRID HORIZONTAL 425Pt ARG GRID LAYOUT DATA

1206PtWidget 1193

Pt ARG GRID LAYOUT INFO189

Pt ARG GRID VERTICAL 425Pt ARG GROUP FLAGS 431

toggle buttons 956Pt ARG GROUP HORZ ALIGN

432Pt ARG GROUP ORIENTATION

PtDivider 214PtGroup 433

Pt ARG GROUP ROWS COLS433

Pt ARG GROUP SPACING 433Pt ARG GROUP SPACING X 434Pt ARG GROUP SPACING Y 434Pt ARG GROUP VERT ALIGN

434Pt ARG HEIGHT

PtWidget 1194,1209Pt ARG HELP TOPIC 1209Pt ARG HIGHLIGHT ROUNDNESS

60

Pt ARG HORIZONTAL ALIGNMENT452, 458

Pt ARG IMAGEAREA FLAGSPtImageArea 440

Pt ARG IMAGEAREA GRID COLORPtImageArea 440

Pt ARG IMAGEAREA GRID THRESHOLDPtImageArea 441

Pt ARG IMAGEAREA IMAGEPtImageArea 441

Pt ARG IMAGEAREA LEFTPtImageArea 441

Pt ARG IMAGEAREA SELECTIONPtImageArea 441

Pt ARG IMAGEAREA TOPPtImageArea 442

Pt ARG IMAGEAREA ZOOMPtImageArea 442

Pt ARG INCREMENT 795Pt ARG INDICATOR COLOR

957Pt ARG INDICATOR TYPE 958Pt ARG INLINE COLOR 60Pt ARG INSIDE COLOR

PtGraphic 417Pt ARG INSIDE FILL PATTERN

417Pt ARG INSIDE TRANS PATTERN

417Pt ARG ITEMS 477,478Pt ARG LABEL BALLOON 459Pt ARG LABEL FLAGS 455, 460Pt ARG LABEL IMAGE 453, 461Pt ARG LABEL TYPE

PtButton 86PtLabel 451,461

Pt ARG LAYOUT 184



Pt ARG LAYOUT DATA 1210PtWidget 1194

Pt ARG LAYOUT INFO 185Pt ARG LAYOUT TYPE 186Pt ARG LIGHT BEVEL COLOR

PtBasic 61Pt ARG LIGHT FILL COLOR

PtBasic 61Pt ARG LINE CAP

PtGraphic 418Pt ARG LINE JOIN

PtGraphic 418Pt ARG LINE SPACING

PtLabel 451,462PtMultiText 570

Pt ARG LINE WIDTHPtGraphic 419

Pt ARG LIST BALLOON 478Pt ARG LIST COLUMN ATTR

PtGenList 307PtTree 980

Pt ARG LIST COLUMN POSPtGenList 308PtList 475PtTree 979

Pt ARG LIST DNDSEL COLOR309

Pt ARG LIST FLAGSPtGenList 304,309

Pt ARG LIST FONT 311Pt ARG LIST ITEM COUNT 311Pt ARG LIST SB RES 304, 311Pt ARG LIST SCROLL RATE 312Pt ARG LIST SEL COUNT 313Pt ARG LIST SPACING 479Pt ARG LIST TOTAL HEIGHT

313

Pt ARG MARGIN BOTTOMPtLabel 452,462PtPanelGroup 673,674

Pt ARG MARGIN HEIGHTPtBasic 62PtTerminal 856–858, 873

Pt ARG MARGIN LEFTPtLabel 451,462PtPanelGroup 673,674

Pt ARG MARGIN RIGHTPtLabel 452,462PtPanelGroup 673,675

Pt ARG MARGIN TOPPtLabel 452,463PtPanelGroup 673,675

Pt ARG MARGIN WIDTHPtBasic 62PtTerminal 856–858, 873

Pt ARG MAX HEIGHT 1232Pt ARG MAXIMUM 297Pt ARG MAXIMUM DIM

PtWidget 1194,1210Pt ARG MAX LENGTH 928Pt ARG MAX WIDTH 1232Pt ARG MENU FLAGS 505–508,

511,517Pt ARG MENU INPUT GROUP

517Pt ARG MENU ITEM FILL COLOR

518Pt ARG MENU ITEM HIGHLIGHT COLOR

518Pt ARG MENU SPACING 518Pt ARG MENU TEXT FONT

507,519Pt ARG MENU TITLE 507,519



Pt ARG MENU TITLE FONT507,519

Pt ARG METER COLOR 545Pt ARG METER FLAGS 545Pt ARG METER FONT COLOR

546Pt ARG METER INCREMENT

546Pt ARG METER KEY LEFT 538,

546Pt ARG METER KEY RIGHT

538,547Pt ARG METER LEVEL1 COLOR

547Pt ARG METER LEVEL1 POS

547Pt ARG METER LEVEL2 COLOR



548Pt ARG METER MAX NEEDLE POSITION

548Pt ARG METER MIN NEEDLE POSITION

548Pt ARG METER NEEDLE COLOR

549Pt ARG METER NEEDLE POSITION

538,549, 550Pt ARG METER NUM SEVERITY LEVELS

549Pt ARG METER TEXT FONT

549Pt ARG MIN HEIGHT 1232Pt ARG MINIMUM 297Pt ARG MINIMUM DIM

PtWidget 1194,1211Pt ARG MIN SLIDER SIZE 795Pt ARG MIN WIDTH 1233Pt ARG MODIFIER KEYS 532Pt ARG MODIFY ITEMS 480Pt ARG MOVED 550Pt ARG MTREND ADVANCE BY N SAMPLES

563Pt ARG MTREND ATTRIBUTES

556Pt ARG MTREND GRAPH ATTR

558Pt ARG MTREND GRAPH DATA

560Pt ARG MTREND GRAPH STATE

560Pt ARG MTREND GRID COLOR

562Pt ARG MTREND GRID DRAW F

562Pt ARG MTREND GRID X 562Pt ARG MTREND GRID Y 562Pt ARG MTREND N GRAPHS

558Pt ARG MTREND N SAMPLES

558Pt ARG MTREND TRACE DRAW F

561Pt ARG MTREND TRACE WIDTH

561Pt ARG MULTITEXT BOTTOM LINE

582Pt ARG MULTITEXT FLAGS 582Pt ARG MULTITEXT NUM LINES

583Pt ARG MULTITEXT NUM LINES VISIBLE

583



Pt ARG MULTITEXT QUERY CHARACTER583

Pt ARG MULTITEXT QUERY LINE579, 584

Pt ARG MULTITEXT RANGE ATTRIBUTES572, 574,584

Pt ARG MULTITEXT ROWS 585Pt ARG MULTITEXT SEGMENTS

571, 572,585Pt ARG MULTITEXT TABS 586Pt ARG MULTITEXT TOP LINE

586Pt ARG MULTITEXT WRAP FLAGS

570,586Pt ARG MULTITEXT X SCROLL POS

587Pt ARG MULTITEXT Y SCROLL POS

587Pt ARG NUMERIC FLAGS 628Pt ARG NUMERIC INCREMENT

PtNumericFloat 634PtNumericInteger 643

Pt ARG NUMERIC MAXPtNumericFloat 635PtNumericInteger 643

Pt ARG NUMERIC MINPtNumericFloat 635PtNumericInteger 643

Pt ARG NUMERIC PRECISION635

Pt ARG NUMERIC PREFIX 628Pt ARG NUMERIC SPACING

629Pt ARG NUMERIC SUFFIX 629Pt ARG NUMERIC UPDOWN WIDTH

629Pt ARG NUMERIC VALUE

PtNumericFloat 635PtNumericInteger 644

Pt ARG OFFSET 532Pt ARG ONOFF STATE 655Pt ARG ORIENTATION 1091

PtGauge 297PtToolbar 964PtToolbarGroup 970

Pt ARG ORIGIN 411, 412,419PtArc 32PtBezier 73PtEllipse 215PtLine 469PtPolygon 697

Pt ARG OUTLINE COLOR 62Pt ARG PAGE INCREMENT 795Pt ARG PG CURRENT

PtPanelGroup 675Pt ARG PG CURRENT INDEX

PtPanelGroup 675Pt ARG PG FLAGS

PtPanelGroup 676Pt ARG PG OVERLAP THRESHOLD

PtPanelGroup 677Pt ARG PG PANEL TITLES

PtPanelGroup 677Pt ARG PG SELECTION MODE

PtPanelGroup 678Pt ARG POINTER

PtRaw 731PtWidget 1194, 1211

Pt ARG POINTSPtArc 32PtBezier 73PtEllipse 215PtGraphic 411,419PtLine 469



PtPixel 693PtPolygon 697PtRect 766

Pt ARG POLYGON FLAGS 697,698

Pt ARG POSPtRect 766PtWidget 1194,1211

Pt ARG PRINT CONTEXT 703,705

Pt ARG PRINT FLAGS 706Pt ARG PROGRESS BAR COLOR

717Pt ARG PROGRESS DIVISIONS

717Pt ARG PROGRESS GAP 718Pt ARG PROGRESS SPACING

718Pt ARG PS LBL ALL 707Pt ARG PS LBL COLLATED 707Pt ARG PS LBL COPIES 707Pt ARG PS LBL DOUBLE SIDED

708Pt ARG PS LBL FILE 708Pt ARG PS LBL FROM 708Pt ARG PS LBL INSTALL 708Pt ARG PS LBL NAME 708Pt ARG PS LBL NOT COLLATED

709Pt ARG PS LBL PREFERENCES

709Pt ARG PS LBL PRINT ORDER

709Pt ARG PS LBL PRINT PAGES

709Pt ARG PS LBL RANGE 709Pt ARG PS LBL REVERSED 710

Pt ARG PS LBL SELECTION710

Pt ARG PS LBL SEND TO FILE710

Pt ARG PS LBL SEND TO PRINTER710

Pt ARG PS LBL TO 711Pt ARG RAW CALC OPAQUE F

734Pt ARG RAW CONNECT F 735Pt ARG RAW DRAW F 731,735Pt ARG RAW EXTENT F 735Pt ARG RAW INIT F 736Pt ARG RAWLIST BACKGROUND F

PtRawList 741Pt ARG RAWLIST DRAW F

PtRawList 741Pt ARG RAWLIST GFLAGS

PtRawList 742Pt ARG RAWLIST INFLATE F

PtRawList 744Pt ARG RAWLIST KEY F

PtRawList 745Pt ARG RAWLIST MOUSE F

PtRawList 746Pt ARG RAWLIST SELECT F

PtRawList 747Pt ARG RAWTREE DRAW F

PtRawTree 755Pt ARG RAWTREE INFLATE F

PtRawTree 756Pt ARG RAWTREE SELECT F

PtRawTree 757Pt ARG RAWTREE STATE F

PtRawTree 758Pt ARG RECT ROUNDNESS 766,

767



Pt ARG REGION DATA 772Pt ARG REGION FIELDS 772Pt ARG REGION FLAGS 774Pt ARG REGION HANDLE 774Pt ARG REGION INFRONT 775Pt ARG REGION INPUT GROUP

775Pt ARG REGION OPAQUE 775Pt ARG REGION OWNER 775Pt ARG REGION PARENT 776Pt ARG REGION SENSE 776Pt ARG RESIZE FLAGS

PtWidget 1212Pt ARG ROW LAYOUT DATA

1213PtWidget 1194

Pt ARG ROW LAYOUT INFO187

Pt ARG SCROLLAREA FLAGS782

Pt ARG SCROLLAREA INCREMENT X783

Pt ARG SCROLLAREA INCREMENT Y783

Pt ARG SCROLLAREA MAX X780,783

Pt ARG SCROLLAREA MAX Y780,784

Pt ARG SCROLLAREA POS X784

Pt ARG SCROLLAREA POS Y784

Pt ARG SCROLLBAR FLAGS 796Pt ARG SCROLLBAR WIDTH

313Pt ARG SCROLLBAR X DISPLAY

PtMultiText 571,588

PtScrollArea 780,784Pt ARG SCROLLBAR X HEIGHT

PtMultiText 588PtScrollArea 785

Pt ARG SCROLLBAR Y DISPLAYPtMultiText 571,588PtScrollArea 780,785

Pt ARG SCROLLBAR Y WIDTHPtMultiText 589PtScrollArea 785

Pt ARG SCROLLCONT FLAGSPtScrollContainer 805

Pt ARG SCROLLCONT RESIZE FLAGSPtScrollContainer 805

Pt ARG SECONDARY H ALIGN452, 463

Pt ARG SECONDARY V ALIGN452, 463

Pt ARG SELECTION FILL COLOR313

Pt ARG SELECTION INDEXES480

Pt ARG SELECTION MODEPtGenList 314PtTree 988, 990, 992

Pt ARG SELECTION RANGE929

Pt ARG SELECTION TEXT COLOR317

Pt ARG SEP ARM BITMAP CURSOR812

Pt ARG SEP ARM CURSOR COLOR814

Pt ARG SEP ARM CURSOR TYPE814

Pt ARG SEP DRAG BOUNDS814



Pt ARG SEP FLAGS 815Pt ARG SEP IMAGE 815Pt ARG SEP IMAGE H ALIGN

816Pt ARG SEP IMAGE V ALIGN

816Pt ARG SEP TYPE 816Pt ARG SERVER CONNECTION

PtServer 823Pt ARG SERVER NAME

PtServer 824Pt ARG SERVER SEND

PtServer 824Pt ARG SLIDER FLAGS 835Pt ARG SLIDER HANDLE COLOR

835Pt ARG SLIDER HANDLE WIDTH

836Pt ARG SLIDER IMAGE 836Pt ARG SLIDER INCREMENT

836Pt ARG SLIDER MULTIPLE 836Pt ARG SLIDER SIZE 795,796Pt ARG SLIDER TICK MAJOR DIV

837Pt ARG SLIDER TICK MAJOR LEN

837Pt ARG SLIDER TICK MINOR DIV

837Pt ARG SLIDER TICK MINOR LEN

837Pt ARG SLIDER TROUGH IMAGE1


837Pt ARG STYLE 62

Pt ARG SUBMENU PARENT HIGHLIGHT COLOR519

Pt ARG SYSINFOPtDisjoint 201

Pt ARG TAB FLAGS 845Pt ARG TERM ANSI PROTOCOL

865Pt ARG TERM APP 865Pt ARG TERM CHARSETS 856,

867Pt ARG TERM COLOR MODE

867Pt ARG TERM COLOR TABLE

861,868Pt ARG TERM COLS 856, 857,

869, 884, 885Pt ARG TERM CONSOLE 860,

869Pt ARG TERM CUR COL 869Pt ARG TERM CUR POS 869Pt ARG TERM CUR ROW 870Pt ARG TERM CURSOR FLAGS

870Pt ARG TERM DRAW MODES

862,870Pt ARG TERM FONT 854, 856,

857,871Pt ARG TERM FONT INDEX

854, 856,872Pt ARG TERM FONT LIST 854,

872Pt ARG TERM FONT SIZE 872Pt ARG TERM MARGINS 856,

858, 860,873Pt ARG TERM MAXCOLS 860,

873



Pt ARG TERM MAXROWS 860,873

Pt ARG TERM MAXSIZE 860,873, 884

Pt ARG TERM MINCOLS 860,874

Pt ARG TERM MINROWS 860,874

Pt ARG TERM MINSIZE 860,874, 884

Pt ARG TERM OPTIONS 874Pt ARG TERM OPTMASK 875Pt ARG TERM RESIZE FL 875Pt ARG TERM RESIZE FUN

857,876Pt ARG TERM RESIZE STR 857,

859,876Pt ARG TERM ROWS 856, 857,

876, 884, 885Pt ARG TERM SCRLBK COUNT

876Pt ARG TERM SCRLBK LIMIT

877Pt ARG TERM SCRLBK POS

877Pt ARG TERM SCROLL 862, 877Pt ARG TERM SELECTION 877Pt ARG TERM SIZE 856–858,

879, 884, 885Pt ARG TERM VISUAL BELL

879Pt ARG TEXT CURSOR WIDTH

929Pt ARG TEXT FLAGS 594, 923,

930, 941Pt ARG TEXT FONT

PtLabel 451, 464

PtMultiText 571, 603, 605Pt ARG TEXT HIGHLIGHT BACKGROUND COLOR

930Pt ARG TEXT HIGHLIGHT TEXT COLOR

931Pt ARG TEXT IMAGE SPACING

PtLabel 464Pt ARG TEXT STRING

PtLabel 451, 455,464PtMultiText 571, 586PtText 912

Pt ARG TEXT SUBSTRINGPtMultiText 571PtText 931

Pt ARG TG FLAGSPtToolbarGroup 971

Pt ARG TIMER INITIAL 952Pt ARG TIMER REPEAT 952Pt ARG TITLE

PtContainer 184, 190Pt ARG TITLE FONT

PtContainer 190Pt ARG TOOLBAR FLAGS

PtToolbar 964Pt ARG TOOLBAR LAYOUT FLAGS

PtToolbar 965Pt ARG TOOLBAR SPACING

PtToolbar 965Pt ARG TOP ITEM POS 317, 343Pt ARG TRANS PATTERN 63Pt ARG TREE BALLOON 983Pt ARG TREE COLUMN ATTR

980, 984Pt ARG TREE COLUMN IMGFUN

981, 985Pt ARG TREE FLAGS

PtGenTree 364, 390



PtRawTree 763PtTree 997

Pt ARG TREE IMAGES 978, 986Pt ARG TREE IMGMASK 978,

987Pt ARG TREE LINE COLOR 365Pt ARG TREE LINE SPACING

365Pt ARG TREE MARGIN COLOR

366Pt ARG TREND ATTRIBUTES

1051, 1053Pt ARG TREND COLOR LIST

1051,1053, 1058Pt ARG TREND COUNT 1054Pt ARG TREND DATA 1054Pt ARG TREND FLAGS 1055Pt ARG TREND GRID COLOR

1057Pt ARG TREND GRID X 1057Pt ARG TREND GRID Y 1057Pt ARG TREND INC 1057Pt ARG TREND MAX 1058Pt ARG TREND MIN 1058Pt ARG TREND PALETTE END

1058Pt ARG TTY ARGV 1071Pt ARG TTY BUFFER 1072Pt ARG TTY BUFLEN 1072Pt ARG TTY CMD 1072,1073Pt ARG TTY DEVSIZE 1073Pt ARG TTY EXIT STATUS 1074,

1081Pt ARG TTY FDS 1074Pt ARG TTY FDSET 1074Pt ARG TTY FLAGS 1075Pt ARG TTY INPUT 1076

Pt ARG TTY INPUT WRITTEN1076

Pt ARG TTY PATH 1076Pt ARG TTY PID 1073,1077Pt ARG TTY PRI 1077Pt ARG TTY PSEUDO 1077Pt ARG TTY RFD 1078Pt ARG TTY SFD 1078Pt ARG TTY SPAWN OPTIONS

1078Pt ARG TTY WFD 1079Pt ARG UNDERLINE1 464Pt ARG UNDERLINE2 464Pt ARG UNDERLINE TYPE 465Pt ARG UPDOWN ARM DATA DECREMENT

1091Pt ARG UPDOWN ARM DATA INCREMENT

1091Pt ARG UPDOWN BORDER WIDTH

1092Pt ARG UPDOWN DATA DECREMENT

1092Pt ARG UPDOWN DATA INCREMENT

1092Pt ARG UPDOWN FLAGS 1092Pt ARG UPDOWN INDICATOR MARGIN

1093Pt ARG USER DATA

PtRaw 731PtToggleButton 957PtWidget 1195, 1214

Pt ARG VERTICAL ALIGNMENT452, 465

Pt ARG VISIBLE COUNTPtComboBox 172PtGenList 317PtList 476, 487



Pt ARG WEB ACTIVATE LINK1103

Pt ARG WEB AUTHENTICATE1103

Pt ARG WEB BUILD DATE 1104Pt ARG WEB COMMAND 1105Pt ARG WEB DATA 1107Pt ARG WEB DOWNLOAD 1109Pt ARG WEB ENCODING 1110Pt ARG WEB GET CERTIFICATES

1110Pt ARG WEB GET CONTEXT

1111Pt ARG WEB GET HISTORY

1111Pt ARG WEB GET URL 1098,

1113Pt ARG WEB HELPER 1114Pt ARG WEB H ERRNO 1115Pt ARG WEB IMPORT CERTIFICATE

1116Pt ARG WEB NAVIGATE FRAME

1117Pt ARG WEB NAVIGATE LINK

1118Pt ARG WEB NAVIGATE PAGE

1119Pt ARG WEB OPTION 1120Pt ARG WEB PRINT 1153Pt ARG WEB RELOAD 1154Pt ARG WEB SERVER 1097, 1154Pt ARG WEB SERVER PID 1156Pt ARG WEB SSL RESPONSE

1156Pt ARG WEB STARTUP ERRNO

1098, 1157Pt ARG WEB STOP 1157

Pt ARG WEB UNKNOWN RESP1157

Pt ARG WEB VERSION 1158Pt ARG WIDTH

PtWidget 1194,1215Pt ARG WINDOW ACTIVE COLOR

1233Pt ARG WINDOW FLAGS 1233Pt ARG WINDOW FRONT WINDOW

1233Pt ARG WINDOW HELP ROOT

1234Pt ARG WINDOW INACTIVE COLOR

1234Pt ARG WINDOW MANAGED FLAGS

1228,1234Pt ARG WINDOW NOTIFY FLAGS

1230,1236Pt ARG WINDOW RENDER FLAGS

1227,1237Pt ARG WINDOW STATE 1238Pt ARG WINDOW TITLE 1240Pt ARG WINDOW TITLE COLOR

1241Pt AUTO EXTENT 183Pt AUTOHIGHLIGHT 507, 1203Pt BACKFILL TEXT 460Pt BALLOON AS REQUIRED 460Pt BALLOON BOTTOM 458PtBalloonCallback t 5Pt BALLOONCOLOR 457Pt BALLOON INPLACE 458Pt BALLOON LEFT 458Pt BALLOON RIGHT 458Pt BALLOONS ON 1198Pt BALLOON TOP 458PtBarGraph 38



barsvertical 41

base 40color 39, 40data 38, 40depth 41flags 41grid

color 42displaying 41horizontal lines 42vertical lines 42

maximum value 42minimum value 43Pt ARG BARGRAPH BASE

40Pt ARG BARGRAPH COLOR

39, 40Pt ARG BARGRAPH DATA

38, 40Pt ARG BARGRAPH DEPTH

41Pt ARG BARGRAPH FLAGS

41Pt ARG BARGRAPH GRID COLOR

42Pt ARG BARGRAPH GRID HORIZ

42Pt ARG BARGRAPH GRID VERT

42Pt ARG BARGRAPH MAX

42Pt ARG BARGRAPH MIN 43Pt ARG COLOR 39, 40

Pt BARGRAPH GRID 41Pt BARGRAPH HORIZONTAL 41Pt BARGRAPH VERTICAL 41

PtBasic 46behavior 47bevel color 58, 61

main 56bevel width 54border color

inline 60outline 62

border roundness 60callbacks

activate 64arm 65disarm 66got focus 67lost focus 68menu 48, 69repeat 48, 70right mouse button 48, 69

contrast 57contrast, bevel 57fill color 58, 59, 61fill pattern 60, 417foreground color 57graphics bandwidth

threshold 52margins

height 62width 62

Pt ARG BANDWIDTH THRESHOLD52

Pt ARG BEVEL COLOR 56Pt ARG BEVEL CONTRAST

57Pt ARG BEVEL WIDTH 54Pt ARG COLOR 57Pt ARG CONTRAST 57



Pt ARG DARK BEVEL COLOR58

Pt ARG DARK FILL COLOR58

Pt ARG FILL COLOR 59Pt ARG FILL PATTERN 60Pt ARG FLAGS 47, 48, 64, 70Pt ARG HIGHLIGHT ROUNDNESS

60Pt ARG INLINE COLOR 60Pt ARG INSIDE FILL PATTERN

417Pt ARG INSIDE TRANS PATTERN

417Pt ARG LIGHT BEVEL COLOR

61Pt ARG LIGHT FILL COLOR

61Pt ARG MARGIN HEIGHT

62Pt ARG MARGIN WIDTH 62Pt ARG OUTLINE COLOR

62Pt ARG STYLE 62Pt ARG TRANS PATTERN

63Pt CB ACTIVATE 47, 64Pt CB ARM 47, 65Pt CB DISARM 47, 66Pt CB GOT FOCUS 67Pt CB LOST FOCUS 68Pt CB MENU 48, 69

enabling 1205Pt CB REPEAT 48, 70selectable 47style 62transparency pattern 63, 417

Pt BASIC PREVENT FILL 56PtBezier 73

Pt ARG BEZIER FLAGS 74Pt ARG ORIGIN 73Pt ARG POINTS 73

Pt BITMAP BALLOON BOTTOM 459Pt BITMAP BALLOON INPLACE 459Pt BITMAP BALLOON LEFT 459Pt BITMAP BALLOON RIGHT 459Pt BITMAP BALLOON TOP 459PtBkgd 78

image 79Pt ARG BKGD IMAGE 79Pt ARG BKGD SPACING X

80Pt ARG BKGD SPACING Y

80Pt ARG BKGD TILE 80tiling

spacing 80type 80

Pt BKGD CENTER 80Pt BKGD CENTER GRID 81Pt BKGD GRID 81Pt BKGD NONE 81Pt BLANK ETCHES 53Pt BLOCK CUA FOCUS 183Pt BLOCKED 1203, 1204Pt BOTTOM ANCHORED BOTTOM

1197Pt BOTTOM ANCHORED TOP 1197Pt BOTTOM BEVEL 54Pt BOTTOM ETCH 53Pt BOTTOM INLINE 54, 60Pt BOTTOM OUTLINE 54, 62Pt BOTTOM RIGHT BEVEL 55Pt BOTTOM RIGHT ETCH 54



Pt BOTTOM RIGHT INLINE 55Pt BOTTOM RIGHT OUTLINE 54Pt BROWSEMODE 161, 237, 314PtButton 85

armedcolor 86, 87data 86, 87fill 86, 87

behavior 86creating 85label type 86Pt ARG ARM COLOR 86, 87Pt ARG ARM FILL 86, 87Pt ARG ARM IMAGE 86, 87Pt ARG LABEL TYPE 86visual feedback 86

PtCalendar 93callbacks

date selection 102date

current 96, 100days

highlighted 98highlighted, color 95highlighted, font 98name, color 96name, font 98names 101selected, color 100

flags 97grid, displaying 97month

current, day color 95current, day font 97name, color 95name, font 98names 99

next/previous buttons,color 99

next/previous buttons,displaying 97

next/previous days,displaying 97

next/previous, day color 95next/previous, font 98






Pt ARG CALENDAR DATE96

Pt ARG CALENDAR FLAGS97






Pt ARG CALENDAR HIGHLIGHT98

Pt ARG CALENDAR MONTH BTN COLOR99



Pt ARG CALENDAR MONTH NAMES99

Pt ARG CALENDAR SEL COLOR100

Pt ARG CALENDAR TIME T100

Pt ARG CALENDAR WDAY NAMES101

Pt ARG CALENDAR YEAR BTN COLOR102

Pt CB CALENDAR SELECT102

yearcolor 95font 98next/previous buttons,

color 102next/previous buttons,

displaying 97Pt CALENDAR DATE SELECTED 102Pt CALENDAR MONTH BTNS 97Pt CALENDAR MONTH SELECTED 102PtCalendarSelectCallback t

102Pt CALENDAR SHOW GRID 97Pt CALENDAR SHOW NEXT 97Pt CALENDAR SHOW PREV 97Pt CALENDAR WDAY SELECTED 102Pt CALENDAR YEAR BTNS 97Pt CALENDAR YEAR SELECTED 102PtCallback t 7PtCallbackInfo t 9Pt CALLBACKS ACTIVE 635, 1203

Pt CB CHILD ADDED REMOVED193

Pt CB CLOCK TIME CHANGED124

Pt CB DIVIDER DRAG 208Pt CB FONT MODIFY 288Pt CB GAUGE VALUE CHANGED

297Pt CB MODIFY NOTIFY

914, 932, 948Pt CB MODIFY VERIFY

933, 947Pt CB MOTION NOTIFY

935Pt CB MOTION VERIFY 935Pt CB ONOFF NEW VALUE

655Pt CB PG PANEL SWITCHING

679Pt CB SCROLLAREA SCROLLED

786Pt CB SCROLL MOVE 317,

797Pt CB SLIDER MOVE 839Pt CB TEXT CHANGED

914, 932, 948PtTextModifyText() 947

Pt CB ACTIVATEhotkeys 1221PtBasic 47, 64,64PtGroup 957PtMultiText 593PtNumericFloat 641PtNumericInteger 649PtText 922, 941PtToggleButton 956PtUpDown 1096

Pt CB ARMPtBasic 47,65PtMenuButton 508PtUpDown 1096



Pt CB BALLOONS 191Pt CB BLOCKED 1215Pt CB CALENDAR SELECT 102Pt CB CBOX ACTIVATE 165Pt CB CBOX CLOSE 165Pt CB CHILD ADDED REMOVED

192Pt CB CHILD GETTING FOCUS

PtContainer 193Pt CB CHILD LOSING FOCUS

PtContainer 195Pt CB CLIENT CONNECTED

PtClient 110Pt CB CLIENT ERROR 111Pt CB CLIENT EVENT

PtClient 112Pt CB CLIENT NOT FOUND

PtClient 113Pt CB CLOCK TIME CHANGED

124Pt CB CS COLOR CHANGED

PtColorSel 144Pt CB DESTROYED 1215Pt CB DISARM

PtBasic 47,66PtUpDown 1096

Pt CB DIVIDER DRAG 208Pt CB DND

PtFileSel 243PtGenList 322PtGenTree 371PtList 487PtRawList 752PtRawTree 764PtTree 997PtWidget 1216

Pt CB FILTER 1219

Pt CB FONT MODIFY 288Pt CB FS BKGD HANDLER 235Pt CB FS SELECTION 237Pt CB FS STATE 238Pt CB GAUGE VALUE CHANGED

PtGauge 297PtProgress 717

Pt CB GEN TREE INPUT 366Pt CB GOT FOCUS

PtBasic 67PtMultiText 595PtText 921, 942

Pt CB HOTKEY 1221Pt CB IMAGEAREA DRAG

PtImageArea 442Pt CB IMAGEAREA MOVEMENT

PtImageArea 443Pt CB IMAGEAREA SCROLLED

PtImageArea 444Pt CB IMAGEAREA SELECTION

PtImageArea 444Pt CB IS DESTROYED 1222Pt CB LAYOUT 196Pt CB LIST INPUT 480Pt CB LOST FOCUS

PtBasic 68PtMultiText 595PtText 921, 942

Pt CB MENUenabling 1205PtBasic 48,69PtMenuButton 508

Pt CB METER MOVED 550Pt CB MODIFY NOTIFY

PtMultiText 597PtText 914, 920,932, 948

Pt CB MODIFY VERIFY



PtMultiText 598PtText 914,933, 947

Pt CB MOTION NOTIFYPtMultiText 597PtText 935

Pt CB MOTION VERIFYPtMultiText 599PtText 921,935

Pt CB NUMERIC CHANGEDPtNumericFloat 635PtNumericInteger 644

Pt CB ONOFF NEW VALUE 655Pt CB OUTBOUND 1222Pt CB PG PANEL SWITCHING

PtPanelGroup 678Pt CB PRINT PROPS 711Pt CB RAW 1223Pt CB REALIZED 1225Pt CB REPEAT 48, 70Pt CB RESCALE 419Pt CB RESIZE 196Pt CB SCROLLAREA SCROLLED

781, 786Pt CB SCROLL MOVE

PtGenList 317PtScrollbar 797

Pt CB SELECTION 476,481Pt CB SEP DRAG 817Pt CB SERVER CONNECTED

PtServer 824Pt CB SERVER ERROR 825Pt CB SERVER RECEIVE

PtServer 826Pt CB SERVER TRANSPORT

PtServer 827Pt CB SLIDER MOVE 839Pt CB SYSINFO

PtDisjoint 202Pt CB TERM APP 879Pt CB TERM FONT 881Pt CB TERM INPUT 881, 905,

906Pt CB TERM OPTIONS 883Pt CB TERM RESIZE 884Pt CB TERM RESIZED 885Pt CB TERM SCRLBK 886Pt CB TEXT CHANGED

PtMultiText 597PtText 914, 920,932, 948

Pt CB TIMER ACTIVATE 952Pt CB TREE COLUMN SEL

PtTree 982, 988Pt CB TREE SELECTION 990Pt CB TREE STATE 991, 1015,

1019Pt CB TTY DEVSIZE 1079Pt CB TTY OUTPUT 1080Pt CB TTY TERMINATED 1081Pt CB UNREALIZED 1225Pt CB WEB AUTHENTICATE

1159Pt CB WEB CLOSE WINDOW

1160Pt CB WEB COMPLETE 1161Pt CB WEB CONTEXT 1161Pt CB WEB DATA REQ 1162Pt CB WEB DOWNLOAD 1164Pt CB WEB ERROR 1165Pt CB WEB IMPORT CERTIFICATE

1169Pt CB WEB METADATA 1170Pt CB WEB NEED SCROLL

1171



Pt CB WEB NEW WINDOW1172

Pt CB WEB PAGE INFO 1173Pt CB WEB SSL CERTINFO

1174Pt CB WEB SSL CERTNONTRUSTED

1176Pt CB WEB SSL CLIENT CERT SELECT

1180Pt CB WEB SSL ERROR 1181Pt CB WEB START 1183Pt CB WEB STATUS 1184Pt CB WEB UNKNOWN 1187Pt CB WEB URL 1188Pt CB WINDOW 1241Pt CB WINDOW CLOSING 1242Pt CB WINDOW OPENING 1243Pt CB WINDOW TRANSPORT

1243Pt CHANGE ACTIVATE 594, 923,

930, 941Pt CHILD ADDED 193Pt CHILD REMOVED 193Pt CLEAR 1204PtClient 107

callbacksconnected 110error 111not connected 113Pt CB CLIENT EVENT

112connection object 110connector name 108, 109, 112flags 108messages, sending to

server 109Pt ARG CLIENT FLAGS 108

Pt ARG CLIENT NAME 108,109, 112

Pt ARG CLIENT REPLY LEN109

Pt ARG CLIENT SEND 109Pt ARG CLIENT SERVER

110Pt CB CLIENT CONNECTED

110Pt CB CLIENT ERROR 111Pt CB CLIENT EVENT 112Pt CB CLIENT NOT FOUND

113reply length 109

PtClientCallback t 112Pt CLIENT NOEVENTS 108Pt CLIENT NONBLOCK 108Pt CLIP HIGHLIGHT 1204PtClock 117

24-hour display 119AM/PM indicator 119analog 124callbacks

time changed 124digital 124face

color 119numbers, displaying 120outline color 119

flags 119flicker, reducing 117font 120hour

color 121current setting 120leading zero, adding 119offset 121



LED/LCD 124minute

color 121current setting 121offset 122

Pt ARG CLOCK FACE COLOR119

Pt ARG CLOCK FACE OUTLINE COLOR119

Pt ARG CLOCK FLAGS 119Pt ARG CLOCK FONT 120Pt ARG CLOCK HOUR 120Pt ARG CLOCK HOUR COLOR

121Pt ARG CLOCK HOUR OFFSET

121Pt ARG CLOCK MINUTE

121Pt ARG CLOCK MINUTE COLOR

121Pt ARG CLOCK MINUTE OFFSET

122Pt ARG CLOCK SECOND

122Pt ARG CLOCK SECOND COLOR

122Pt ARG CLOCK SECOND OFFSET



123Pt ARG CLOCK TYPE 124Pt ARG FLAGS 124

Pt CB CLOCK TIME CHANGED124

secondcolor 122current setting 122displaying 120offset 122

separatorcharacter 123color 123

timeupdating every second 120

type 124Pt CLOCK 24 HOUR 119Pt CLOCK ANALOG 124Pt CLOCK DIGITAL 124Pt CLOCK HOUR CHANGED 125Pt CLOCK LED 124Pt CLOCK MINUTE CHANGED 125Pt CLOCK PAD HOURS 119Pt CLOCK SECONDCHANGED 125Pt CLOCK SHOW AMPM 119Pt CLOCK SHOW NUMBERS 120Pt CLOCK SHOW SECONDS 120PtClockTimeCallback t 125Pt CLOCK TRACK TIME 120PtColorPanel 129

flags 130Pt ARG CPANEL FLAGS

130PtColorPatch 135

flags 136Pt ARG CPATCH FLAGS

136PtColorSel 141

callbackscolor changed 144



color 142flags 143models 142models, current 143palette 144Pt ARG CS COLOR 142Pt ARG CS COLOR MODELS

142Pt ARG CS CURRENT MODEL

143Pt ARG CS FLAGS 143Pt ARG CS PALETTE 144Pt CB CS COLOR CHANGED

144PtColorSelGroup 149

flags 150Pt ARG CSGROUP FLAGS

150PtColorWell 154

color-swatch dimensions 155flags 155Pt ARG CWELL FLAGS 155Pt ARG CWELL SWATCH DIM

155PtComboBox 160

behavior 161callbacks

drop button activation 165list close 165

convenience functions 173drop button

suppressing 164width 163

flags 161, 163keyboard actions 161list

closing from code 175

determining if open 164item, selected 164items, maximum visible 164items, number visible 172opening from code 176opening via keyboard 161,

163placing above text 164static 164types 160

maximizing width 163Pt ARG CBOX BUTTON WIDTH

163Pt ARG CBOX FLAGS 161,

163Pt ARG CBOX MAX VISIBLE COUNT

164Pt ARG CBOX SEL ITEM

164Pt ARG CBOX TEXT FILL COLOR

165Pt ARG VISIBLE COUNT

172Pt CB CBOX ACTIVATE 165Pt CB CBOX CLOSE 165text area, fill color 165

Pt COMBOBOX ALT DOWN 161,163

PtComboBoxListClose() 175PtComboBoxListOpen() 176Pt COMBOBOX MAX WIDTH 163Pt COMBOBOX OPEN 164Pt COMBOBOX STATIC 164Pt COMBOBOX TOP 164PtCompound 177Pt CONNECTION CLIENT BROKEN 112Pt CONNECTION SERVERBROKEN 826



Pt CONSUME 1220Pt CONSUME EVENTS 1202PtContainer 181

balloonscallback 191disabling 183

callbackschild added/removed 192child getting focus 193child losing focus 195resize 196

CUAenabling 183enabling arrow keys 183preventing focusing 183

flags 183, 190hotkeys, terminating searches

for 184key events, processing as

hotkeys first 184Pt ARG CONTAINER FLAGS

183, 190Pt ARG FILL LAYOUT INFO

186Pt ARG FLAGS 193Pt ARG GRID LAYOUT INFO

189Pt ARG LAYOUT 184Pt ARG LAYOUT INFO 185Pt ARG LAYOUT TYPE 186Pt ARG ROW LAYOUT INFO

187Pt ARG TITLE 184, 190Pt ARG TITLE FONT 190Pt CB BALLOONS 191Pt CB CHILD ADDED REMOVED

192

Pt CB CHILD GETTING FOCUS193

Pt CB CHILD LOSING FOCUS195

Pt CB LAYOUT 196Pt CB RESIZE 196reextent, forcing 183title

etching 183font 190gradient 184showing 184text 190

PtContainerCallback t 197PtContainerHold() 317, 1205Pt CONTINUE 8Pt CPANEL SHOW DROPPER 130Pt CPANEL SHOW FIELDS 130Pt CPANEL SHOW WELL 130Pt CPATCH ENABLE MENU 137Pt CPATCH SHOW SELECTOR 136Pt CPATCH SHOW SLIDER 137Pt CS COLOR CHANGE COMPLETE

145Pt CS COLOR CHANGED 144Pt CS FAST UPDATE 143Pt CSGROUPALL AT ONCE 150Pt CS QUANTIZE COLOR 144Pt CURSORVISIBLE 930Pt CWELL POPUPON MENU 155Pt CWELL POPUPON SELECT 155Pt DAMAGED 1204PtDamageExtent() 342, 350Pt DAMAGE FAMILY 1204Pt DAMAGE PARENT 1202Pt DEFAULT COLOR 604, 606Pt DEFAULT FONT 603, 605



Pt DELAY REALIZE 1204Pt DESTROYED 193, 1204Pt DISABLE BALLOONS 183PtDisjoint 201

callbacks, systeminformation 202

Pt ARG SYSINFO 201Pt CB SYSINFO 202system information 201

PtDivider 206bandwidth threshold 213callbacks

dragging 208drag outline, suppressing 207flags 207group orientation 214in a list 309offset 208Pt ARG BANDWIDTH THRESHOLD

213Pt ARG DIVIDER FLAGS

207Pt ARG DIVIDER OFFSET

208Pt ARG DIVIDER SIZES 208Pt ARG FLAGS 208Pt ARG GROUP ORIENTATION

214Pt CB DIVIDER DRAG 208resizing

both children 207preventing 207

sizes of realized children 208PtDividerCallback t 209Pt DIVIDER INVISIBLE 207Pt DIVIDER NORESIZE 207Pt DIVIDER RESIZEBOTH 207

PtDndCallbackInfo t 1217Pt DOUBLE DASH LINE 816Pt DOUBLE LINE 816Pt DOUBLE ULINE 465Pt EDITABLE 930Pt EDIT ACTIVATE 593, 941PtEllipse 215

height 215Pt ARG DIM 215Pt ARG ORIGIN 215Pt ARG POINTS 215width 215

Pt ELLIPSIS MIDDLE 460Pt EMT AUTOINDENT 582Pt EMT CHAR 587Pt EMT FORCEDSCROLL 583Pt EMT FULL LINES 582Pt EMT NEWLINE 587Pt EMT SCROLL TO CURSOR 583Pt EMT WORD 570, 587Pt ENABLE CUA 183Pt ENABLE CUA ARROWS 183Pt ETCHED IN 817Pt ETCHED OUT 817Pt ETCH TITLE AREA 183Pt EXTENDED MODE 238, 314PtFileSel 219

background handler 235callbacks

drag and drop 243item selection 237

case insensitivity 229convenience functions 244custom headers 222directories, listing 230error dialog 229



events, processingpending 235

fileshidden 230information 222, 230listing 230names, pattern for 229

flags 221, 229items

adding 247, 249allocating 252collapsing 219, 238, 258damaging 256expanding 219, 238, 259expanding parents 257freeing 260, 261freeing when collapsing 229getting all 251getting current 262getting selected 263, 274images for 231index of 265redrawing 256removing 266, 268, 270rereading 234root 272scrolling to 276selecting 273, 275selection, clearing 255setting current 264unselecting 277, 278

keyboard seek mode 230labels

date 233group 233name 233owner 234

permissions 234size 234

Pt ARG FS FILE SPEC 229Pt ARG FS FLAGS 221, 229Pt ARG FS FORMAT 230Pt ARG FS IMAGES 231Pt ARG FS LBL DATE 233Pt ARG FS LBL GROUP 233Pt ARG FS LBL NAME 233Pt ARG FS LBL OWNER

234Pt ARG FS LBL PERMISSIONS

234Pt ARG FS LBL SIZE 234Pt ARG FS REFRESH 234Pt ARG FS ROOT DIR 235Pt CB DND 243Pt CB FS BKGD HANDLER

235Pt CB FS SELECTION 237Pt CB FS STATE 238read error 230reading directories 222root directory 235sample code 223seeking files 230single-level mode 221, 230,

239tree mode 221

PtFileSelBkgdCallback t

236PtFileSelCallback t 238PtFileSelItem t 220PtFlash 279

Pt ARG FLASH FILE 279URL 279

Pt FLAT FILL 55



Pt FLOAT ORIGIN 416Pt FLOAT POS 416Pt FOCUSRENDER 1204PtFontSel 283

callbacksfont modified 288

colorstext 288text background 288

convenience functions 292flags 285font

currently selected 287families, filtering 285initial 287

labelbackground color 286font name 286size 286style 286text color 287

maximum point size 287Pt ARG FLAGS 288Pt ARG FONT DISPLAY 285Pt ARG FONT FLAGS 285Pt ARG FONT LBL BKGDCOLOR

286Pt ARG FONT LBL FONT

286Pt ARG FONT LBL SIZE

286Pt ARG FONT LBL STYLE

286Pt ARG FONT LBL TEXTCOLOR

287Pt ARG FONT NAME 287

Pt ARG FONT POINT SIZE MAX287

Pt ARG FONT SAMPLE 287Pt ARG FONT SYMBOL 288Pt ARG FONT TEXT BKGD COLOR

288Pt ARG FONT TEXT COLOR

288Pt CB FONT MODIFY 288required symbol 288sample text 287

Pt FONTSEL AA CHECK 285Pt FONTSEL ALL FONTS 285Pt FONTSEL ALL SYMBOLS 288Pt FONTSEL BITMAP 285Pt FONTSEL COLORSELBKGD 285Pt FONTSEL COLORSELTEXT 286Pt FONTSEL FIXED 285Pt FONTSEL PROP 285Pt FONTSEL SAMPLE 285Pt FONTSEL SCALABLE 285PtForwardWindowEvent() 1240PtForwardWindowTaskEvent() 1240PtFSAddAfter() 247PtFSAddFirst() 249PtFSAllItems() 251PtFSAllocItem() 252Pt FS CASE INSENSITIVE 229PtFSClearSelection() 255PtFSDamageItem() 256Pt FS DIR CL 220, 232Pt FS DIR OP 220, 232Pt FS DLINK CL 220, 232Pt FS DLINK OP 220, 232Pt FS ERROR 220, 232Pt FS ERRORPOPUP 229PtFSExpandParents() 257



Pt FS FILE 220, 232Pt FS FLINK 220, 232PtFSFolderCollapse() 258PtFSFolderExpand() 259PtFSFreeAllItems() 260PtFSFreeItems() 261Pt FS FREE ON COLLAPSE 229PtFSGetCurrent() 262PtFSGetSelIndexes() 263PtFSGoto() 264PtFSItemIndex() 265Pt FS NEW DIR 220Pt FS NEW ITEM 235Pt FS NO ROOT DISPLAY 230Pt FS OLD DIR 220Pt FS OLD ITEM 236PtFSRemoveChildren() 266PtFSRemoveItem() 268PtFSRemoveList() 270PtFSRootItem() 272Pt FS SEEK KEY 221, 230PtFSSelect() 273PtFSSelectedItems() 274PtFSSetSelIndexes() 275PtFSShow() 276Pt FS SHOW DIRS 230Pt FS SHOW ERRORS 230Pt FS SHOW FILES 230Pt FS SHOW HIDDEN 230Pt FS SINGLE LEVEL 221, 230,

239Pt FS STATE END 239Pt FS STATE START 239PtFSUnselect() 277PtFSUnselectNonBrothers() 278Pt FULL BEVELS 54PtGauge 293

callbacksvalue changed 297

flags 294font 295horizontal alignment 295interactive 294, 297live 294orientation 297Pt ARG FLAGS 297Pt ARG GAUGE FLAGS 294Pt ARG GAUGE FONT 295Pt ARG GAUGE H ALIGN

295Pt ARG GAUGE V ALIGN

296Pt ARG GAUGE VALUE 296Pt ARG GAUGE VALUE PREFIX

296Pt ARG GAUGE VALUE SUFFIX

296Pt ARG MAXIMUM 297Pt ARG MINIMUM 297Pt ARG ORIENTATION 297Pt CB GAUGE VALUE CHANGED

297value

current 296displaying 295indeterminate 294inverting fill color 295maximum 297maximum, position of 295minimum 297prefix 296suffix 296

vertical alignment 296PtGaugeCallback t 299



Pt GAUGE DECREMENT 298Pt GAUGE DRAGGED 298Pt GAUGE INCREMENT 298Pt GAUGE INDETERMINATE 294,

716Pt GAUGE INTERACTIVE 294,

297, 717Pt GAUGE JUMP 299Pt GAUGE LIVE 294, 716Pt GAUGE MAX ON LEFT 295,

838Pt GAUGE MAX ON TOP 295, 838Pt GAUGE MULTIPLE DECREMENT

298Pt GAUGE MULTIPLE INCREMENT

298Pt GAUGE RELEASED 298Pt GAUGE SHOW VALUE 295Pt GAUGE TO MAX 298Pt GAUGE TO MIN 298Pt GAUGE VALUE XOR 295PtGenList 303

background, drawing 334balloon

adjusting for a column 356creating 331fill color 307for individual columns 309showing 310text color 307when clipping occurs 309

blitting, disabling 310browse mode 314callbacks

drag and drop 322scroll 317

column flags 307

column positions 308compose selection modes,

defining 315convenience functions 323drag and drop, selection

color 309events, consuming 309extended mode 314flags 309font 311gflags, getting 357items

adding 327browsing 314Ctrl-click 314current 304damaging 333getting all 329getting current 339getting first 338getting last 348getting selected 340, 355index 346locking 349number of 311number selected 313number visible 317reallocating 347removing 351selected, color of 313selected, text color 317selecting 354selecting a range 314selecting many 314selecting one 314setting current 341setting selected 358



Shift-click 314showing 360top one displayed 317total height 313unlocking 361unselecting 362

keyboard actions 305mouse actions 305multiple mode 314Pt ARG BALLOON COLOR

307Pt ARG BALLOON FILL COLOR

307Pt ARG FLAGS 317Pt ARG LIST COLUMN ATTR

307Pt ARG LIST COLUMN POS

308Pt ARG LIST DNDSEL COLOR

309Pt ARG LIST FLAGS 304,

309Pt ARG LIST FONT 311Pt ARG LIST ITEM COUNT

311Pt ARG LIST SB RES 304,

311Pt ARG LIST SCROLL RATE

312Pt ARG LIST SEL COUNT

313Pt ARG LIST TOTAL HEIGHT

313Pt ARG SCROLLBAR WIDTH

313Pt ARG SELECTION FILL COLOR

313

Pt ARG SELECTION MODE314

Pt ARG SELECTION TEXT COLOR317

Pt ARG TOP ITEM POS 317Pt ARG VISIBLE COUNT

317Pt CB DND 322Pt CB SCROLL MOVE 317PtDivider as child 303

adjusting size 309range-select mode 314read-only 310repairs

holding 342releasing hold on 350

resizing 353scroll rate 312scrollbar

always 310as required 310color 304, 311granting focus to 310resizing 310resources 304, 311width 313

scrollbars 304selection

clearing 330selection mode 314single-select mode 314snapping to the number of

items 310strings, drawing 336text alignment 307

PtGenListAddItems() 327PtGenListAllItems() 329



PtGenListClearSelection() 330PtGenListCreateTextBalloon() 331,

744, 756PtGenListDamageItem() 333, 342,

350PtGenListDndCallback t 752PtGenListDrawBackground() 334PtGenListDrawString() 336PtGenListFirstItem() 338Pt GEN LIST FULL WIDTH 743PtGenListGetCurrent() 339PtGenListGetSelIndexes() 340PtGenListGoto() 341PtGenListHold() 333, 342, 350PtGenListItem t 343Pt GEN LIST ITEM BACKGROUND

743PtGenListItemIndex() 346PtGenListItemRealloc() 347PtGenListLastItem() 348PtGenListLockItem() 333, 349, 361Pt GEN LIST NO AUTOFOCUS 743Pt GEN LIST NO BACKGROUND 742Pt GEN LIST NO CLIPPING 743PtGenListRelease() 333, 350PtGenListRemoveItems() 351PtGenListResize() 349, 353, 361PtGenListSelect() 354PtGenListSelectedItems() 355PtGenListSetColumnBalloon() 356,

744, 756PtGenListSetGflags() 357PtGenListSetSelIndexes() 358PtGenListShow() 360Pt GEN LIST SHOW DAMAGED 334,

743

PtGenListUnlockItem() 333, 349,361

PtGenListUnselect() 362PtGenTree 363

buttonsdisplaying 364, 390indenting 364

callbacksdrag and drop 371mouse and key event 366

connectorsdisplaying 365

convenience functions 372flags 364, 390items

adding 375, 376collapsing 380damaging 381expanding 382expanding parents 384extending background to the

left 365extending to the right 365freeing 386freeing all 385getting all 378getting current 387getting root 400getting selected 388, 402,

403index 393reallocating 394removing 397, 398removing children 396resizing 395, 399selecting 401setting current 389



showing 405unselecting 407, 408

linescolor 365displaying 365indenting 364spacing 365

marginsdisplaying 365

margins, color 366Pt ARG TREE FLAGS 364,

390Pt ARG TREE LINE COLOR

365Pt ARG TREE LINE SPACING

365Pt ARG TREE MARGIN COLOR

366Pt CB DND 371Pt CB GEN TREE INPUT

366selection

clearing 379PtGenTreeAddAfter() 375PtGenTreeAddFirst() 376PtGenTreeAllItems() 378PtGenTreeClearSelection() 379PtGenTreeCollapse() 380PtGenTreeDamageItem() 381PtGenTreeExpand() 382, 758PtGenTreeExpandParents() 384PtGenTreeFreeAllItems() 385PtGenTreeFreeItems() 386PtGenTreeGetCurrent() 387PtGenTreeGetSelIndexes() 388PtGenTreeGoto() 389PtGenTreeInput t 366

PtGenTreeItem t 390PtGenTreeItemIndex() 393PtGenTreeItemRealloc() 394PtGenTreeItemResize() 395PtGenTreeRemoveChildren() 396PtGenTreeRemoveItem() 397PtGenTreeRemoveList() 398PtGenTreeResize() 399PtGenTreeRootItem() 400PtGenTreeSelect() 401PtGenTreeSelectedItems() 402PtGenTreeSetSelIndexes() 403PtGenTreeShow() 405PtGenTreeUnselect() 407PtGenTreeUnselectNonBrothers() 408Pt GETS FOCUS 546, 547, 1066,

1204PtGetStyleMember() 63Pt GHOST 1204Pt GRADIENT TITLE AREA 184PtGraphic 409

callbacksrescale 419

colorsfill 417inside 417

dashscaling 416style 416

flags 416lines

cap style 418join style 418width 419

origin 411, 419floating 416

points 411, 419



position, floating 416Pt ARG DASH LIST 416Pt ARG DASH SCALE 416Pt ARG GRAPHIC FLAGS

416Pt ARG INSIDE COLOR 417Pt ARG LINE CAP 418Pt ARG LINE JOIN 418Pt ARG LINE WIDTH 419Pt ARG ORIGIN 411, 412,

419Pt ARG POINTS 411, 419Pt CB RESCALE 419

PtGrid 424lines

horizontal, number of 425vertical, number of 425

Pt ARG GRID HORIZONTAL425

Pt ARG GRID VERTICAL425

Pt GRID 1055Pt GRID ABOVE TRENDS 1055Pt GRID FORCE 1055Pt GRID IS TRANSLUCENT 1055PtGroup 429

callbacksactivate 957

cellshorizontal alignment 430vertical alignment 430

childrenaligning 433exclusive choice 431forcing equal height 432forcing equal size 431forcing equal width 432

horizontal alignment 432no choice 431spacing between 433, 434stretching horizontally 432stretching vertically 432vertical alignment 434

flags 431horizontal wrapping,

preventing 431keys, preventing use of 431number of rows and

columns 433orientation 433Pt ARG CELL HORZ ALIGN

430Pt ARG CELL VERT ALIGN

430Pt ARG GROUP FLAGS

431, 956Pt ARG GROUP HORZ ALIGN

432Pt ARG GROUP ORIENTATION

433Pt ARG GROUP ROWS COLS

433Pt ARG GROUP SPACING

433Pt ARG GROUP SPACING X

434Pt ARG GROUP SPACING Y

434Pt ARG GROUP VERT ALIGN

434Pt CB ACTIVATE 957vertical wrapping,

preventing 431Pt GROUPASIS 433



Pt GROUPEQUAL SIZE 431Pt GROUPEQUAL SIZE HORIZONTAL

432Pt GROUPEQUAL SIZE VERTICAL

432Pt GROUPEXCLUSIVE 431, 956Pt GROUPHORIZONTAL 433Pt GROUPHORZ CENTER 430,

432Pt GROUPHORZ LEFT 430, 432Pt GROUPHORZ RIGHT 430, 432Pt GROUPNO KEYS 431Pt GROUPNO KEY WRAP 431Pt GROUPNO KEY WRAP HORIZONTAL

431Pt GROUPNO KEY WRAP VERTICAL

431Pt GROUPNO SELECTALLOWED 431Pt GROUPSTRETCHFILL 432Pt GROUPSTRETCHHORIZONTAL 432Pt GROUPSTRETCHVERTICAL 432Pt GROUPVERT BOTTOM 431,

434Pt GROUPVERT CENTER 431,

434Pt GROUPVERTICAL 433Pt GROUPVERT TOP 431, 434Pt HIGHLIGHTED 1205PtHold() 342Pt HORIZONTAL GRADIENT 55PtHotkeyCallback t 11, 1221Pt HOTKEY IGNORE MODS 11Pt HOTKEYS FIRST 184Pt HOTKEY SYM 11Pt HOTKEY TERMINATOR 184Pt IGNORE 1220Pt IMAGE 87, 451, 461

PtImageArea 439callbacks

dragging 442movement 443scrolled 444selection 444

flags 440grid color 440grid threshold 441image 441left 441Pt ARG IMAGEAREA FLAGS

440Pt ARG IMAGEAREA GRID COLOR

440Pt ARG IMAGEAREA GRID THRESHOLD

441Pt ARG IMAGEAREA IMAGE

441Pt ARG IMAGEAREA LEFT

441Pt ARG IMAGEAREA SELECTION

441Pt ARG IMAGEAREA TOP

442Pt ARG IMAGEAREA ZOOM

442Pt CB IMAGEAREA DRAG

442Pt CB IMAGEAREA MOVEMENT

443Pt CB IMAGEAREA SCROLLED

444Pt CB IMAGEAREA SELECTION

444selected area 441top 442



zooming factor 442Pt IMAGEAREA AUTOSCALE 440Pt IMAGEAREA COMPLETE 442,

445Pt IMAGEAREA DRAG 442, 445Pt IMAGEAREA EDITABLE SELECTION

440Pt IMAGEAREA ENABLE SELECTION

440Pt IMAGEAREA INIT 442, 445Pt INFLATE BALLOON 5, 191, 459Pt IN FLUX 1205Pt INHERIT COLOR 604–606Pt INHERIT FONT 603, 605Pt INSERT MODE 930Pt INTERNAL HELP 1202, 1209Pt KEY MOVED 550PtLabel 450

accelerator key 457backfilling text 460balloons

customizing 459enabling 460enabling if clipped 460fill color 457position 455, 458text 455, 458text color 457

creating 451flags 455, 460font 451, 464horizontal alignment 452, 458,

463image

data 453, 461position 451, 458

spacing relative to text 451,464

line spacing 462margins

bottom 452, 462left 451, 462right 452, 462top 452, 463

Pt ARG ACCEL KEY 457Pt ARG BALLOON COLOR

457Pt ARG BALLOON FILL COLOR

457Pt ARG BALLOON POSITION

451, 455, 458Pt ARG BALLOON TEXT

458Pt ARG HORIZONTAL ALIGNMENT

452, 458Pt ARG LABEL BALLOON

459Pt ARG LABEL FLAGS 455,

460Pt ARG LABEL IMAGE 453,

461Pt ARG LABEL TYPE 451,

461Pt ARG LINE SPACING 451,

462Pt ARG MARGIN BOTTOM

452, 462Pt ARG MARGIN LEFT 451,

462Pt ARG MARGIN RIGHT

452, 462Pt ARG MARGIN TOP 452,

463



Pt ARG SECONDARY H ALIGN452, 463

Pt ARG SECONDARY V ALIGN463

Pt ARG TEXT FONT 451,464

Pt ARG TEXT IMAGE SPACING464

Pt ARG TEXT STRING 451,455, 464

Pt ARG UNDERLINE1 464Pt ARG UNDERLINE2 464Pt ARG UNDERLINE TYPE

465Pt ARG VERTICAL ALIGNMENT

452, 465shifting when selected 460text 451, 464

position 451, 458spacing relative to

image 451, 464using ellipsis 460

type 451, 461underline color 464underline type 465vertical alignment 452, 463,

465Pt LABEL SELECTSHIFT 460Pt LEFT ANCHORED LEFT 1197Pt LEFT ANCHORED RIGHT 1197Pt LEFT BEVEL 54Pt LEFT ETCH 53Pt LEFT INLINE 54, 60Pt LEFT OUTLINE 54, 62PtLine 469

Pt ARG ORIGIN 469Pt ARG POINTS 469

PtList 474balloon function 478callbacks

drag and drop 487mouse and key event 480selection 476, 481

convenience functions 488creating 475items

adding 490array of 477, 478checking existence of 496deleting a range 493deleting all 492deleting specific 494determining position of 497displaying in columns 475getting 476number displayed 476removing by position 498replacing 500replacing by position 499selected 480selecting by position 501setting the current 495showing by position 502spacing between 479unselecting 503

methodsList Draw 336

Pt ARG ITEMS 477, 478Pt ARG LIST BALLOON 478Pt ARG LIST COLUMN POS

475Pt ARG LIST SPACING 479Pt ARG MODIFY ITEMS

480



Pt ARG SELECTION INDEXES480

Pt ARG VISIBLE COUNT476, 487

Pt CB DND 487Pt CB LIST INPUT 480Pt CB SELECTION 476, 481PtDivider as child 475selection policy

browse 477extended 477multiple 477single 477

PtListAddItems() 490Pt LIST BALLOON AS REQUIRED

309, 997Pt LIST BALLOONS IN COLUMNS

309, 743Pt LIST BOUNDARY KEY EVENTS

309PtListCallback t 476, 482PtListColumn t 308PtListColumnAttributes t

307Pt LIST COLUMN CENTER 308Pt LIST COLUMN DAMAGE ALWAYS

308Pt LIST COLUMN ELLIPSIS 307Pt LIST COLUMN ELLIPSIS INVERT

308Pt LIST COLUMN ELLIPSIS MIDDLE

307Pt LIST COLUMN LEFT 308Pt LIST COLUMN NO STRING 308,

980Pt LIST COLUMN RIGHT 308PtListDeleteAllItems() 492

PtListDeleteItemPos() 493PtListDeleteItems() 494PtListDndCallback t 322,

487PtListGotoPos() 495Pt LIST HEADER AUTORESIZE 309PtListInput t 480Pt LIST ITEM ABOVE 343Pt LIST ITEM BELOW 343Pt LIST ITEM CURRENT 327, 343,

344, 987Pt LIST ITEM DAMAGED 342,

343, 350, 989Pt LIST ITEM DNDSELECTEDDOWN

244, 323, 372, 487, 753,764, 998

Pt LIST ITEM DNDSELECTEDIN244, 323, 372, 488, 753,764, 998

Pt LIST ITEM DNDSELECTEDUP244, 323, 371, 487, 752,764, 998

PtListItemExists() 496Pt LIST ITEM FLAG USER[1234]

989Pt LIST ITEM FLAG USER* 344Pt LIST ITEM INWIDGET 343PtListItemPos() 497Pt LIST ITEM SELECTED 327,

343, 344, 401, 987Pt LIST ITEM USED FLAGS 344Pt LIST NOBLIT 310Pt LIST NO COLUMN LINES 310Pt LIST NON SELECT 310PtListRemovePositions() 498PtListReplaceItemPos() 499PtListReplaceItems() 500



Pt LIST SCROLLBAR ALWAYS 304,310

Pt LIST SCROLLBAR AS REQUIRED304, 310

Pt LIST SCROLLBAR AUTORESIZE310

Pt LIST SCROLLBAR GETSFOCUS310

Pt LIST SCROLL LIST 318Pt LIST SCROLL SCROLLBAR 318Pt LIST SELECTIONBROWSE 237,

990Pt LIST SELECTIONCANCEL 237,

990Pt LIST SELECTIONFINAL 237,

990PtListSelectPos() 501Pt LIST SHOW BALLOON 310PtListShowPos() 502Pt LIST SNAP 310PtListUnselectPos() 503PtMenu 504

activating via an eventhandler 509

appearance, controlling 506cascaded menus 511click-stay mode 506creating 506destroying 508destroying on closing 517example 512flags 505, 507, 508, 511, 517gradient fill 517input group 517items

accelerators 505fill color 518

font 507, 519forcing equal widths 517highlight color 518hotkeys 505making selectable 505selecting 506spacing between 518widget types 505

labels 507lifetime 508menu bar 505overriding parent menu 517PhAB’s Menu module, using

instead 505populating 507popup 505, 509positioning 508press-drag-release mode 506Pt ARG BEVEL WIDTH 518Pt ARG FLAGS 507Pt ARG MENU FLAGS

505–508, 511, 517Pt ARG MENU INPUT GROUP

517Pt ARG MENU ITEM FILL COLOR

518Pt ARG MENU ITEM HIGHLIGHT COLOR

518Pt ARG MENU SPACING

518Pt ARG MENU TEXT FONT

507, 519Pt ARG MENU TITLE 507,

519Pt ARG MENU TITLE FONT

507, 519



Pt ARG SUBMENU PARENT HIGHLIGHT COLOR519

pulldown 508separators 507sizing 507submenu 519submenus 505tear off 517text alignment 517title 507, 519title font 507, 519

Pt MENUABLE 48, 1205Pt MENU AUTO 507, 517PtMenuBar 525.See also PtMenu

anchoring 525children 525

PtMenuButton 530accelerator

displaying 532font 531key 530modifier keys 532text 531x offset 532

callbacksarm 508menu 508

menu position 532Pt ARG ACCEL FONT 531Pt ARG ACCEL KEY 530Pt ARG ACCEL TEXT 531Pt ARG BUTTON TYPE 511,

531Pt ARG MODIFIER KEYS

532Pt ARG OFFSET 532Pt CB ARM 508

Pt CB MENU 508type 531

Pt MENU BUTTON 1205Pt MENU CHILD 505, 511, 517Pt MENU DOWN 532Pt MENU GRADIENT 517Pt MENU RIGHT 511, 532Pt MENU TEAR OFF 517Pt MENU TEXT 532Pt MENU TEXT ALIGN 517Pt MENU TRANSIENT 508, 517Pt MENU UP 532PtMeter 538

callbacksneedle movement 550

colorcenter 545font 546level 1 547level 2 547level 3 548needle 549outline 545ticks 545

examples 539flags 545flickering 541font 549interactive 545key

increment 546left 538, 546movement with 538right 538, 547

levels, number of 549maximum 548minimum 548



mouse movement 538no text 545noninteractive 545position

level 1 547level 2 548maximum 548minimum 548needle 538, 549

Pt ARG FLAGS 546, 547Pt ARG METER COLOR 545Pt ARG METER FLAGS 545Pt ARG METER FONT COLOR

546Pt ARG METER INCREMENT

546Pt ARG METER KEY LEFT

538, 546Pt ARG METER KEY RIGHT

538, 547Pt ARG METER LEVEL1 COLOR





548Pt ARG METER MAX NEEDLE POSITION

548Pt ARG METER MIN NEEDLE POSITION

548Pt ARG METER NEEDLE COLOR

549

Pt ARG METER NEEDLE POSITION538

Pt ARG METER NEEDLE POSITION549, 550

Pt ARG METER NUM SEVERITY LEVELS

549Pt ARG METER TEXT FONT

549Pt CB METER MOVED 550severity arcs 538size 539

PtM NON SELECTABLE 545PtM NO TEXT 545Pt MOUSE MOVED 550PtM SELECTABLE 545Pt MT BACKGROUND 584, 619,

622Pt MT BACKGROUND COLOR 584,

619, 622Pt MT FLAGS 585, 619, 622Pt MT FONT 584, 619, 622Pt MT FOREGROUND 584, 619,

622Pt MT QUERY CHAR 615PtMTrend 554

adding or changing graphdata 560

attributes 556graph attributes 558graph drawing state 560grid color 562grid draw function 562grid lines 562number of graphs 558number of samples 558Pt ARG MTREND ADVANCE BY N SAMPLES

563



Pt ARG MTREND ATTRIBUTES556

Pt ARG MTREND GRAPH ATTR558

Pt ARG MTREND GRAPH DATA560

Pt ARG MTREND GRAPH STATE560

Pt ARG MTREND GRID COLOR562

Pt ARG MTREND GRID DRAW F562

Pt ARG MTREND GRID X562

Pt ARG MTREND GRID Y562

Pt ARG MTREND N GRAPHS558

Pt ARG MTREND N SAMPLES558

Pt ARG MTREND TRACE DRAW F561

Pt ARG MTREND TRACE WIDTH561

scrolling 563trace line drawing

function 561trace line width 561trends

data, replacing 567PtMTrendAddData() 567PtMTrendChangeData() 567Pt MT TAG 577, 585, 619, 622Pt MT TEXT COLOR 584, 619, 622PtMultiLines t 572, 586, 603Pt MULTIPLE MODE 237, 314PtMultiText 569

attributescreating 609getting 584, 610modifying 574, 584, 619,

621callbacks

activate 593got focus 595lost focus 595modify notify 597modify verify 598motion notify 597motion verify 599text changed 597

character information,getting 583, 614

color 603, 605convenience functions 601cursor tracking, enabling 583dimensions 579features 569flags 582, 594flags, wrapping 586font 574, 603, 605hyperlinks 577indentation, automatic 582lines

bottom 582displaying if there’s

room 582getting information 584, 614number of 583number visible 583spacing 570top 586, 587

Pt ARG COLOR 571, 604,606



Pt ARG DIM 579Pt ARG FILL COLOR 571,

604, 606Pt ARG FLAGS 593Pt ARG LINE SPACING 570Pt ARG MULTITEXT BOTTOM LINE

582Pt ARG MULTITEXT FLAGS

582Pt ARG MULTITEXT NUM LINES

583Pt ARG MULTITEXT NUM LINES VISIBLE

583Pt ARG MULTITEXT QUERY CHARACTER

583Pt ARG MULTITEXT QUERY LINE

579, 584Pt ARG MULTITEXT RANGE ATTRIBUTES

572, 574, 584Pt ARG MULTITEXT ROWS

585Pt ARG MULTITEXT SEGMENTS

571, 572, 585Pt ARG MULTITEXT TABS

586Pt ARG MULTITEXT TOP LINE

586Pt ARG MULTITEXT WRAP FLAGS

570, 586Pt ARG MULTITEXT X SCROLL POS

587Pt ARG MULTITEXT Y SCROLL POS


571, 588Pt ARG SCROLLBAR X HEIGHT

588

Pt ARG SCROLLBAR Y DISPLAY571, 588

Pt ARG SCROLLBAR Y WIDTH589

Pt ARG TEXT FLAGS 594Pt ARG TEXT FONT 571,

603, 605Pt ARG TEXT STRING 571,

586Pt ARG TEXT SUBSTRING

571Pt CB ACTIVATE 593Pt CB GOT FOCUS 595Pt CB LOST FOCUS 595Pt CB MODIFY NOTIFY

597Pt CB MODIFY VERIFY 598Pt CB MOTION NOTIFY

597Pt CB MOTION VERIFY 599Pt CB TEXT CHANGED 597rows, number of 585scrollbars

displaying 588height 588position 587width 589

scrolling, automatic 583tab stops 586text

inserting 573modifying 621multisegment 585ranges of 572setting 571setting attributes 572

wrapping 570



carriage return 587end of line 587word break 587

PtMultiTextAttributes t

605PtMultiTextCallback t 576,

607, 915PtMultiTextControl t 576,

584, 607PtMultiTextCreateAttributes() 609PtMultiTextGetAttributes() 610PtMultiTextInfo t 607PtMultiTextInfo() 614PtMultiTextLine t 579, 617PtMultiTextModifyAttributes() 574,

619PtMultiTextModifyText() 571–573,

621PtMultiTextQuery t 579, 583,

584, 623PtMultiTextSegment t 625Pt NOLINE 817Pt NO ULINE 465PtNumeric 627

buttonsdisplaying 628width 629

flags 628Pt ARG NUMERIC FLAGS

628Pt ARG NUMERIC PREFIX

628Pt ARG NUMERIC SPACING

629Pt ARG NUMERIC SUFFIX

629

Pt ARG NUMERIC UPDOWN WIDTH629

spacing 629text

autohighlighting 628hexadecimal 628inserting commas 628prefix 628suffix 629wrapping 628

Pt NUMERIC AUTO HIGHLIGHT 628Pt NUMERIC CHANGED 636, 644Pt NUMERIC ENABLE UPDOWN 628PtNumericFloat 633

callbacksactivate 641value changed 635

increment 634precision 635Pt ARG NUMERIC INCREMENT

634Pt ARG NUMERIC MAX 635Pt ARG NUMERIC MIN 635Pt ARG NUMERIC PRECISION

635Pt ARG NUMERIC VALUE

635Pt CB ACTIVATE 641Pt CB NUMERIC CHANGED

635value

current 635maximum 635minimum 635

PtNumericFloatCallback t

636Pt NUMERIC HEXADECIMAL 628



PtNumericInteger 642callbacks

activate 649value changed 644

increment 643Pt ARG NUMERIC INCREMENT

643Pt ARG NUMERIC MAX 643Pt ARG NUMERIC MIN 643Pt ARG NUMERIC VALUE

644Pt CB ACTIVATE 649Pt CB NUMERIC CHANGED

644value

current 644hexadecimal 642maximum 643minimum 643

PtNumericIntegerCallback t

645Pt NUMERIC SET 636, 644Pt NUMERIC UPDOWN ACTIVATE 636,

644Pt NUMERIC UPDOWN REPEAT 636,

644Pt NUMERIC USE SEPARATORS 628Pt NUMERIC WRAP 628Pt OBSCURED 1205PtOnOffButton 654

Pt ARG FLAGS 655Pt ARG ONOFF STATE 655Pt CB ONOFF NEW VALUE

655Pt OPAQUE 1205Pt OPAQUE ETCHES 53PtOSContainer 660

fill color 664Pt ARG FILL COLOR 664

PtPane 665PtPanelGroup 670

convenience functions 684copying as popup window 685drag and drop 676flags 676margins

bottom 673, 674left 673, 674right 673, 675top 673, 675

panel index, finding 688, 689panel pointer, finding 690, 691panel title, finding 692panel titles 677panels

current 675switching 678

Pt ARG FLAGS 679Pt ARG MARGIN BOTTOM

673, 674Pt ARG MARGIN LEFT 673,

674Pt ARG MARGIN RIGHT

673, 675Pt ARG MARGIN TOP 673,

675Pt ARG PG CURRENT 675Pt ARG PG CURRENT INDEX

675Pt ARG PG FLAGS 676Pt ARG PG OVERLAP THRESHOLD

677Pt ARG PG PANEL TITLES

677



Pt ARG PG SELECTION MODE678

Pt CB PG PANEL SWITCHING678

selection mechanismlocation 676

selection mode 678selector

none 678tabs

color 677displaying one per panel 678displaying only one 678forcing equal size 677overlap 677

Pt PG AUTO 678Pt PG DND 676Pt PG MULTI CONTAINER MODE 676Pt PG NONE 678Pt PG SELECTORALIGN RIGHT 676Pt PG SELECTORON BOTTOM 676Pt PG SINGLE TAB 678Pt PG TABS EQUAL SIZE 677Pt PG USE PANEL COLORS 677PtPixel 693

Pt ARG POINTS 693Pt PIXEL 1055PtPolygon 697

closed 698flags 697, 698Pt ARG ORIGIN 697Pt ARG POINTS 697Pt ARG POLYGON FLAGS

697, 698relative coordinates 698

Pt POPBALLOON 5, 191PtPositionMenu() 508

PtPrintSel 702callbacks

print properties 711convenience functions 715flags 706labels

all pages 707collate pages 707double sided 708file name 708install button 708not collated 709number of copies 707pages from 708pages to 711preferences 709print order 709print pages 709print range 709print selected 710printer name 708reverse order 710send to file 710send to printer 710

print context 703, 705Pt ARG PRINT CONTEXT

703, 705Pt ARG PRINT FLAGS 706Pt ARG PS LBL ALL 707Pt ARG PS LBL COLLATED

707Pt ARG PS LBL COPIES

707Pt ARG PS LBL DOUBLE SIDED

708Pt ARG PS LBL FILE 708Pt ARG PS LBL FROM 708



Pt ARG PS LBL INSTALL708

Pt ARG PS LBL NAME 708Pt ARG PS LBL NOT COLLATED

709Pt ARG PS LBL PREFERENCES

709Pt ARG PS LBL PRINT ORDER

709Pt ARG PS LBL PRINT PAGES

709Pt ARG PS LBL RANGE 709Pt ARG PS LBL REVERSED

710Pt ARG PS LBL SELECTION

710Pt ARG PS LBL SEND TO FILE

710Pt ARG PS LBL SEND TO PRINTER

710Pt ARG PS LBL TO 711Pt CB PRINT PROPS 711

Pt PRINTSEL ALL PANES 707Pt PRINTSEL DFLT LOOK 707Pt PRINTSEL FILE PANE 706Pt PRINTSEL NO COPIES 706Pt PRINTSEL NO PAGE RANGE 706Pt PRINTSEL NO PRINTSELECT 706Pt PRINTSEL NO SELECTRANGE

706Pt PRINTSEL PREFERENCES 706Pt PRINTSEL SETTINGSPANE 706Pt PROCESS 1220Pt PROCREATED 193, 1205PtProgress 716

callbacksvalue changed 717

color 717convenience functions 721flags 716number of divisions 717Pt ARG GAUGE FLAGS 716Pt ARG PROGRESS BAR COLOR

717Pt ARG PROGRESS DIVISIONS

717Pt ARG PROGRESS GAP

718Pt ARG PROGRESS SPACING

718Pt CB GAUGE VALUE CHANGED

717segments, getting 723, 725

next 727spacing

bar and text 718divisions 718

text area, getting 729PtProgressEntireSegment() 723PtProgressFirstSegment() 725PtProgressNextSegment() 727Pt PROGRESSNO MORE SEGMENTS

723, 725, 727PtProgressTextRect() 729Pt RANGE MODE 238, 314, 988,

991not supported

byPtTreeUnselect() 1048PtRaw 730

clippingrestoring 732setting 731

color 733connect function 735



custom widgets 730damage 730data model 731data, user-defined 731drawing

function 731drawing function 735example 733extent function 735fill color 733initialization function 736opacity-calculation

function 734Pt ARG COLOR 733Pt ARG FILL COLOR 733Pt ARG POINTER 731Pt ARG RAW CALC OPAQUE F

734Pt ARG RAW CONNECT F

735Pt ARG RAW DRAW F 731,

735Pt ARG RAW EXTENT F

735Pt ARG RAW INIT F 736Pt ARG USER DATA 731redrawing 730scaling 732translation

restoring 732setting 732

PtRawCallback t 13, 1223PtRawList 740

callbacksdrag and drop 752

convenience functions 753flags 742

functionsbackground 741draw 741inflate balloon 744key event 745mouse event 746selection 747

Pt ARG RAWLIST BACKGROUND F741

Pt ARG RAWLIST DRAW F741

Pt ARG RAWLIST GFLAGS742

Pt ARG RAWLIST INFLATE F744

Pt ARG RAWLIST KEY F745

Pt ARG RAWLIST MOUSE F746

Pt ARG RAWLIST SELECT F747

Pt CB DND 752PtRawListDrawBackgroundF t

741PtRawListInflateF t 744PtRawListMouseF t 746PtRawListSelectF t 747PtRawTree 754

balloonlocation 763

callbacksdrag and drop 764

convenience functions 765flags 763functions

draw 755inflate balloon 756



selection 757state 758

Pt ARG RAWTREE DRAW F755

Pt ARG RAWTREE INFLATE F756

Pt ARG RAWTREE SELECT F757

Pt ARG RAWTREE STATE F758

Pt ARG TREE FLAGS 763Pt CB DND 764

PtRawTreeDrawItemF t 755PtRawTreeInflateF t 756PtRawTreeItemStateF t 758PtRawTreeSelectF t 757Pt REALIZED 1205Pt REALIZING 1205PtRect 766

dimensions 766points 766position 766Pt ARG DIM 766Pt ARG POINTS 766Pt ARG POS 766Pt ARG RECT ROUNDNESS

766, 767rounding corners 766, 767

PtRegion 771data 772flags 774handle 774input group 775instantiation 771opacity 775owner 775Pt ARG REGION DATA 772

Pt ARG REGION FIELDS772

Pt ARG REGION FLAGS774

Pt ARG REGION HANDLE774

Pt ARG REGION INFRONT775

Pt ARG REGION INPUT GROUP775

Pt ARG REGION OPAQUE775

Pt ARG REGION OWNER775

Pt ARG REGION PARENT776

Pt ARG REGION SENSE776

regionin front 775parent 776

resources, changing 772sensitivity 776

Pt REGION 1206PtRelease() 350Pt RESIZE X ALWAYS 805, 1212Pt RESIZE X AS REQUIRED 805,

1212Pt RESIZE X BITS 805, 1212Pt RESIZE X INITIAL 805, 1212Pt RESIZE XY ALWAYS 806, 1212Pt RESIZE XY AS REQUIRED 806,

1212Pt RESIZE XY BITS 806, 1212Pt RESIZE XY INITIAL 806, 1212Pt RESIZE Y ALWAYS 805, 1212



Pt RESIZE Y AS REQUIRED 805,1212

Pt RESIZE Y BITS 806, 1212Pt RESIZE Y INITIAL 805, 1212Pt REVERSEGRADIENT 55Pt RIGHT ANCHORED LEFT 1197Pt RIGHT ANCHORED RIGHT 1197Pt RIGHT BEVEL 54Pt RIGHT ETCH 53Pt RIGHT INLINE 54, 60Pt RIGHT OUTLINE 54, 62PtScrollArea 780

arrow keys, ignoring 782callbacks

scrollbars moved 781, 786canvas, determining 791convenience functions 790displayed portion, position 784flags 782Pt ARG AREA 780, 783, 784Pt ARG FLAGS 786Pt ARG SCROLLAREA FLAGS

782Pt ARG SCROLLAREA INCREMENT X

783Pt ARG SCROLLAREA INCREMENT Y

783Pt ARG SCROLLAREA MAX X

780, 783Pt ARG SCROLLAREA MAX Y

780, 784Pt ARG SCROLLAREA POS X

784Pt ARG SCROLLAREA POS Y


780, 784

Pt ARG SCROLLBAR X HEIGHT785

Pt ARG SCROLLBAR Y DISPLAY780, 785

Pt ARG SCROLLBAR Y WIDTH785

Pt CB SCROLLAREA SCROLLED781, 786

scrollbarsdisplaying 780, 784, 785height 785increment 783width 785

scrollingcontrol 781notification 781

sizephysical 780virtual 780, 783, 784

PtScrollAreaCanvas() 791Pt SCROLLAREA ENABLE PAN 783Pt SCROLLAREA IGNORE KEYS 782PtScrollbar 792

arrow buttons, displaying 796bandwidth threshold 802callbacks

scrolled 797flags 796handle length

current 796minimum 795

incrementpage 795step 795

keyboard actions 794mouse actions 793



Pt ARG BANDWIDTH THRESHOLD802

Pt ARG FLAGS 797Pt ARG INCREMENT 795Pt ARG MIN SLIDER SIZE

795Pt ARG PAGE INCREMENT

795Pt ARG SCROLLBAR FLAGS

796Pt ARG SLIDER SIZE 795,

796Pt CB SCROLL MOVE 797rendering as if focused 796slider, fixed size 796

Pt SCROLLBAR FIXED SLIDER SIZE796

Pt SCROLLBAR FOCUSED 796Pt SCROLLBAR SHOW ARROWS 796PtScrollContainer 803

anchors 804flags 805Pt ARG SCROLLCONT FLAGS

805Pt ARG SCROLLCONT RESIZE FLAGS

805resize flags 805resize policy 804

Pt SCROLLCONTTRACK FOCUS 805Pt SCROLL DECREMENT 318, 797Pt SCROLL DRAGGED 319, 798Pt SCROLL INCREMENT 318, 797Pt SCROLL JUMP 319, 798Pt SCROLL PAGE DECREMENT 318,

798Pt SCROLL PAGE INCREMENT 318,

797

Pt SCROLL RELEASED 319, 798Pt SCROLL SET 319, 798Pt SCROLL TO MAX 319, 798Pt SCROLL TO MIN 319, 798Pt SELECTABLE 47, 505, 507, 593,

922, 941, 1206, 1216Pt SELECTION MODE AUTO 315Pt SELECTION MODE MULTIPLE 315,

327Pt SELECTION MODE NOCLEAR 315Pt SELECTION MODE NOFOCUS 316Pt SELECTION MODE NOMOVE 315Pt SELECTION MODE NONE 315,

327Pt SELECTION MODE NOREST 315Pt SELECTION MODE NOSCROLL 315Pt SELECTION MODE RANGE 315,

327, 351, 354, 358, 407,748, 757

Pt SELECTION MODE SINGLE 315,327, 354

Pt SELECTION MODE TOGGLE 316Pt SELECT NOREDRAW 1206PtSeparator 811

flags 815orientation 815Pt ARG SEP ARM BITMAP CURSOR

812Pt ARG SEP ARM CURSOR COLOR

814Pt ARG SEP ARM CURSOR TYPE

814Pt ARG SEP DRAG BOUNDS

814Pt ARG SEP FLAGS 815Pt ARG SEP IMAGE 815



Pt ARG SEP IMAGE H ALIGN816

Pt ARG SEP IMAGE V ALIGN816

Pt ARG SEP TYPE 816Pt CB SEP DRAG 817type 816

PtServer 822callbacks

connected 824error 825receive 826transport 827

connection object 823instantiation 822messages, sending to

client 824name 824Pt ARG SERVER CONNECTION

823Pt ARG SERVER NAME 824Pt ARG SERVER SEND 824Pt CB SERVER CONNECTED

824Pt CB SERVER ERROR 825Pt CB SERVER RECEIVE

826Pt CB SERVER TRANSPORT

827PtServerCallback t 826Pt SET 956, 1206PtSetWidgetStyle() 63Pt SHOW BALLOON 455, 460Pt SHOW TITLE 184, 190Pt SINGLE DASH LINE 816Pt SINGLE LINE 816Pt SINGLE MODE 238, 314

Pt SINGLE ULINE 465Pt SKIP LAYOUT 1202PtSlider

callbacksmovement 839

flags 835gauge flags 838handle

color 835image 835, 836width 836

increment 836increment, multiple 836keyboard actions 833mouse actions 833Pt ARG FLAGS 839Pt ARG GAUGE FLAGS 838Pt ARG SLIDER FLAGS 835Pt ARG SLIDER HANDLE COLOR

835Pt ARG SLIDER HANDLE WIDTH

836Pt ARG SLIDER IMAGE 836Pt ARG SLIDER INCREMENT

836Pt ARG SLIDER MULTIPLE

836Pt ARG SLIDER TICK MAJOR DIV

837Pt ARG SLIDER TICK MAJOR LEN

837Pt ARG SLIDER TICK MINOR DIV

837Pt ARG SLIDER TICK MINOR LEN


837



Pt ARG SLIDER TROUGH IMAGE2837

Pt CB SLIDER MOVE 839ticks, major

length 837number of 837

ticks, minorlength 837number of 837

troughimage 837

PtSliderCallback t 840Pt SLIDER DECREMENT 839Pt SLIDER DRAGGED 839Pt SLIDER IMAGE 835Pt SLIDER INCREMENT 839Pt SLIDER JUMP 840Pt SLIDER MULTIPLE DECREMENT

839Pt SLIDER MULTIPLE INCREMENT

839Pt SLIDER RELEASED 839Pt SLIDER SET 840Pt SLIDER TO MAX 840Pt SLIDER TO MIN 839Pt SLIDER TROUGH IMAGE 835Pt STATIC BEVELS 56Pt STATIC GRADIENT 56PtTab 844

convenience functions 850displaying upside down 845flags 845Pt ARG TAB FLAGS 845Pt TAB UNSELECTED COLOR

846typical usage 844unselected color 846

Pt TAB DRAG HANDLE 845Pt TAB MULTI 846Pt TAB RIGHTSIDE LEFT 845Pt TAB UNSELECTED COLOR

846Pt TAB UPSIDE DOWN 845Pt TERM ANCHOR PARENT HEIGHT

875Pt TERM ANCHOR PARENT WIDTH

875Pt TERM ANCHOR WINDOWS ONLY

875Pt TERM COLOR MODE 867Pt TERM CTRLBRK INPUT 882Pt TERM CURSORALWAYS 870Pt TERM CURSORNEVER 870Pt TERM CURSORNOSPEEDCHK 870Pt TERM CURSORON FOCUS 870Pt TERM CURSORTIMER 870PtTerminal 852

ANSI protocol 865application window state 865

callback 879bandwidth, not checking 871blitting 871callbacks

font changed 881input 881options changed 883resizing, after 885resizing, before 884

character sets 855, 867creating translation

tables 896characters, outputting 907clipboard

copying to 895



pasting from 905clipped, assuming widget

isn’t 871color

coding 861mode 867table 868

columnscurrent 869maximum number of 873minimum number of 874number of 869

console emulation 860convenience functions 890cursor

blinking 870not checking for speed 870position 869timer 870

escape sequences 874, 875flags 870font

enabling escapesequences 875

index 854, 872list of 854, 872maintaining widget size 875name 854, 871setting via keyboard 875size 872verifying 899

function reentrancy 856geometry 856line-editing keys, getting 901margins 873name, getting 904options 874

disabling 875protocol 865Pt ARG AREA 856, 857Pt ARG BANDWIDTH THRESHOLD

862, 890Pt ARG DIM 856–858, 860Pt ARG FILL COLOR 890Pt ARG MARGIN HEIGHT

856–858, 873Pt ARG MARGIN WIDTH

856–858, 873Pt ARG TERM ANSI PROTOCOL

865Pt ARG TERM APP 865Pt ARG TERM CHARSETS

856, 867Pt ARG TERM COLOR MODE

867Pt ARG TERM COLOR TABLE

861, 868Pt ARG TERM COLS 856,

857, 869, 884, 885Pt ARG TERM CONSOLE

860, 869Pt ARG TERM CUR COL

869Pt ARG TERM CUR POS

869Pt ARG TERM CUR ROW

870Pt ARG TERM CURSOR FLAGS

870Pt ARG TERM DRAW MODES

862, 870Pt ARG TERM FONT 854,

856, 857, 871



Pt ARG TERM FONT INDEX854, 856, 872

Pt ARG TERM FONT LIST854, 872

Pt ARG TERM FONT SIZE872

Pt ARG TERM MARGINS856, 858, 860, 873

Pt ARG TERM MAXCOLS860, 873

Pt ARG TERM MAXROWS860, 873

Pt ARG TERM MAXSIZE860, 873, 884

Pt ARG TERM MINCOLS860, 874

Pt ARG TERM MINROWS860, 874

Pt ARG TERM MINSIZE860, 874, 884

Pt ARG TERM OPTIONS874

Pt ARG TERM OPTMASK875

Pt ARG TERM RESIZE FL875

Pt ARG TERM RESIZE FUN857, 876

Pt ARG TERM RESIZE STR857, 859, 876

Pt ARG TERM ROWS 856,857, 876, 884, 885

Pt ARG TERM SCRLBK COUNT876

Pt ARG TERM SCRLBK LIMIT877

Pt ARG TERM SCRLBK POS877

Pt ARG TERM SCROLL 862,877

Pt ARG TERM SELECTION877

Pt ARG TERM SIZE856–858, 879, 884, 885

Pt ARG TERM VISUAL BELL879

Pt CB TERM APP 879Pt CB TERM FONT 881Pt CB TERM INPUT 881,

905, 906Pt CB TERM OPTIONS 883Pt CB TERM RESIZE 884Pt CB TERM RESIZED 885Pt CB TERM SCRLBK 886QNX 4 protocol 865redrawing

always 871on first scroll 871

resizing 857adjusting after 858flags 875hint 876parent widget 875resize function 876resize function, default 859

rowscurrent 870maximum number of 873minimum number of 874number of 876

screen size 879maximum 873minimum 874



scrollback buffercallback 886maximum number of

lines 877number of lines saved 876position in 877

scrolling optimization 862,870

scrolls, maximum numberdelayed 877

selectioncurrent 877getting current 903pasting current 906

size limits 860video memory 860, 869visual bell 879word, selecting 909

PtTerminalAppState t 865PtTerminalCharset t 892PtTerminalCharsets t 892PtTerminalCopy() 895PtTerminalCreateCsXlat() 896PtTerminalDefaultCharsets() 898PtTerminalFontChange t 881PtTerminalFontInfo() 899PtTerminalGetKeys() 901PtTerminalGetSelection() 903PtTerminalInput t 882PtTerminalName() 904PtTerminalOptionChange t

883PtTerminalPasteClipboard() 905PtTerminalPasteSelection() 906PtTerminalPut() 907PtTerminalPutc() 907PtTerminalPuts() 907

PtTerminalRowCol t 869PtTerminalScrlbkCb t 886PtTerminalSelectWord() 909PtTerminalSizeChange t 884,

885, 1080Pt TERM KBFONT 854, 875Pt TERM KBFORCE 854, 875Pt TERM KEYBOARD INPUT 882Pt TERM MOUSE INPUT 882Pt TERM OPFONT 854, 875Pt TERM PASTEINPUT 882Pt TERM PASTENF INPUT 882Pt TERM PROTOCOLINPUT 882Pt TERM SCROLL NOBLIT 871Pt TERM SCROLL NOHWCHK 871Pt TERM SCROLL NOSPEEDCHK 862,

871Pt TERM SCROLL NOVISCHK 871Pt TERM SCROLL RFSH 871Pt TERM SELECTING 878Pt TERM SELECTION ALWAYS 878Pt TERM SELECTION BLOCK 878Pt TERM SELECTION FIRST KEEP

878Pt TERM SELECTION FLAGS KEEP

878Pt TERM SELECTION LAST KEEP

878Pt TERM SELECTION NEVER 878Pt TERM SELECTION NONE 878Pt TERM SELECTION STREAM 878Pt TERM SELECTION TYPE KEEP

878PtText 911

arrow keys 921callbacks

activate 941



activate, invoking when losingfocus 930

changed 914, 920, 932got focus 921lost focus 921modify-notify 914, 920, 932modify-verify 914, 933motion-notify 935motion-verify 921, 935

columns, number of 927convenience functions 943cursor position 927cursor width 929cursor, displaying 930edit mask 923, 927editable 930flags 923, 930, 941focus 921highlighting

background color 930text color 931when given focus 930

input filter 923, 927insert mode 911, 930interaction model 911keyboard actions 925maximum length 928mouse actions 925passwords, entering 917Pt ARG COLUMNS 927Pt ARG CURSOR POSITION

927Pt ARG DIM 927Pt ARG EDIT MASK 923,

927Pt ARG FLAGS 914, 922,

932, 933, 935, 941, 947

Pt ARG MAX LENGTH 928Pt ARG SELECTION RANGE

929Pt ARG TEXT CURSOR WIDTH

929Pt ARG TEXT FLAGS 923,

930, 941Pt ARG TEXT HIGHLIGHT BACKGROUND COLOR

930Pt ARG TEXT HIGHLIGHT TEXT COLOR

931Pt ARG TEXT STRING 912Pt ARG TEXT SUBSTRING

931Pt CB ACTIVATE 922, 941Pt CB GOT FOCUS 921, 942Pt CB LOST FOCUS 921,

942Pt CB MODIFY NOTIFY

914, 920, 932, 948Pt CB MODIFY VERIFY

914, 933, 947Pt CB MOTION NOTIFY

935Pt CB MOTION VERIFY

921, 935Pt CB TEXT CHANGED

914, 920, 932, 948replace mode 912, 930selection 912

getting current 946range 929setting 949

substring, getting orsetting 931

text 912getting 913



modifying 912, 914, 947Pt TEXT AUTO HIGHLIGHT 930PtTextCallback t 576, 594,

596–598, 600, 915,933–936, 941, 942, 944

PtTextControl t 576, 944PtTextControlInfo t 944PtTextGetSelection() 575, 946Pt TEXT IMAGE 451, 461PtTextModifyText() 571–573, 914,

947PtTextSetSelection() 949Pt TG COLLAPSIBLE 971PtTimer 951

callbacksexpiration 952

initial time 952Pt ARG TIMER INITIAL 952Pt ARG TIMER REPEAT

952Pt CB TIMER ACTIVATE

952repetition time 952

Pt TIMER INITIAL 953Pt TIMER REPEAT 953Pt TOGGLE 1206

Pt CB ACTIVATE 64PtToggleButton 955

“set”checking to see if 956

callbacksactivate 956

creating 955exclusive choice 956grouping 956indicator

fill color 957

types 955, 958Pt ARG FLAGS 956Pt ARG INDICATOR COLOR

957Pt ARG INDICATOR TYPE

958Pt ARG USER DATA 957Pt CB ACTIVATE 956user-defined data 957

Pt TOGGLE CHECK 958Pt TOGGLE OUTLINE 958Pt TOGGLE RADIO 958PtToolbar 963

flags 964layout flags 965orientation 964Pt ARG ORIENTATION 964Pt ARG TOOLBAR FLAGS

964Pt ARG TOOLBAR LAYOUT FLAGS

965Pt ARG TOOLBAR SPACING

965spacing 965

Pt TOOLBAR DRAGGABLE 964Pt TOOLBAR END SEPARATOR 965Pt TOOLBAR FOLLOW FOCUS 965Pt TOOLBAR FROM LINE START 965PtToolbarGroup 970

flags 971orientation 970Pt ARG ORIENTATION 970Pt ARG TG FLAGS 971

Pt TOOLBAR ITEM SEPARATORS 965Pt TOOLBAR LOCK ORIENTATION

965



Pt TOOLBAR REVERSELAST ITEM964

Pt TOOLBAR TO LINE END 965Pt TOP ANCHORED BOTTOM 1197Pt TOP ANCHORED TOP 1197Pt TOP BEVEL 54Pt TOP ETCH 53Pt TOP INLINE 54, 60Pt TOP LEFT BEVEL 55Pt TOP LEFT ETCH 54Pt TOP LEFT INLINE 55Pt TOP LEFT OUTLINE 54Pt TOP OUTLINE 54, 62PtTree 975

balloonenabling 997function 983location 997

callbackscolumn-selection 982, 988drag and drop 997selection 990state-change 991

column attributes 980, 984column flags 980column function 981, 985columns 979convenience functions 998flags 997images 978, 986

adding 978, 1006mask 978, 987selecting 978, 987

itemsadding after 1002adding first 1004allocating 976, 1010

collapsing 1015current, getting 1023current, setting 1026expanding 1019freeing 1022freeing all 1021getting all 1008index, getting 1031modifying 1032, 1034removing 1037, 1039removing children 1035root item, getting 1041scrolling to 1026selecting 1042selection, clearing 1014selection, getting 1024, 1043selection, setting 1045showing 1046unselecting 1048unselecting

nonbrothers 1049Pt ARG LIST COLUMN ATTR

980Pt ARG LIST COLUMN POS

979Pt ARG SELECTION MODE

988, 990, 992Pt ARG TREE BALLOON

983Pt ARG TREE COLUMN ATTR

980, 984Pt ARG TREE COLUMN IMGFUN

981, 985Pt ARG TREE FLAGS 997Pt ARG TREE IMAGES 978,

986



Pt ARG TREE IMGMASK978, 987

Pt CB DND 997Pt CB TREE COLUMN SEL

982, 988Pt CB TREE SELECTION

990Pt CB TREE STATE 991PtDivider as child 979selection mode 988, 990, 992

PtTreeitems

changing 1012creating 1016

PtTreeAddAfter() 1002PtTreeAddFirst() 1004PtTreeAddImages() 978, 1006PtTreeAllItems() 1008PtTreeAllocItem() 1010Pt TREE BALLOON ON IMAGE 763,

997Pt TREE BALLOON ON TREE 763,

997PtTreeCallback t 988, 990PtTreeChangetem() 1012PtTreeClearSelection() 1014PtTreeCollapse() 1015Pt TREE COLLAPSING 238, 758,

992PtTreeColumnAttributes t

984Pt TREE COLUMN NOCB 985Pt TREE COLUMN NOCURRENT 985Pt TREE COLUMN NOSELECT 985PtTreeCreateItem() 1016PtTreeDndCallback t 243,

371, 764, 997

PtTreeExpand() 1019Pt TREE EXPANDING 238, 758,

992PtTreeFreeAllItems() 1021PtTreeFreeItems() 1022PtTreeGetCurrent() 1023PtTreeGetSelIndexes() 1024PtTreeGoto() 1026Pt TREE HAS BUTTONS 364, 390Pt TREE INDENT BUTTONS 364Pt TREE INDENT LINES 364PtTreeItem t 976, 1027PtTreeItemAttributes t

1029Pt TREE ITEM EXPANDABLE 249,

376, 390, 397, 987, 1004Pt TREE ITEM EXPANDED 391,

758, 979, 987PtTreeItemIndex() 1031Pt TREE ITEM INWIDGET 391PtTreeModifyItem() 1032PtTreeModifyItemString() 1034PtTreeRemoveChildren() 1035PtTreeRemoveItem() 1037PtTreeRemoveList() 1039PtTreeRootItem() 1041PtTreeSelect() 1042PtTreeSelectedItems() 1043PtTreeSetSelIndexes() 1045PtTreeShow() 1046Pt TREE SHOW CONNECTORS 365Pt TREE SHOW LINES 365Pt TREE SHOW MARGIN 365Pt TREE TO LEFT 365Pt TREE TO RIGHT 365PtTreeUnselect() 1048PtTreeUnselectNonBrothers() 1049



PtTrend 1050attributes 1051color list 1053convenience functions 1061flags 1055grid

color 1057drawing 1055forcing display of 1055horizontal lines, number

of 1057opaque, over trends 1055translucent 1055vertical lines, number

of 1057palette entries, range of 1058Pt ARG COLOR 1053Pt ARG FILL COLOR 1052Pt ARG TREND ATTRIBUTES

1051, 1053Pt ARG TREND COLOR LIST

1051, 1053, 1058Pt ARG TREND COUNT

1054Pt ARG TREND DATA 1054Pt ARG TREND FLAGS

1055Pt ARG TREND GRID COLOR

1057Pt ARG TREND GRID X

1057Pt ARG TREND GRID Y

1057Pt ARG TREND INC 1057Pt ARG TREND MAX 1058Pt ARG TREND MIN 1058

Pt ARG TREND PALETTE END1058

trendsdata 1054data, replacing 1063direction of movement 1056distance between

points 1057drawing as pixels 1055drawing over grid 1056horizontal 1055maximum value 1058minimum value 1058number of 1054vertical 1056

Pt TREND BOTTOM TO TOP 1056PtTrendChangeData() 1063PtTrendChangeTrendData() 1063Pt TREND HORIZONTAL 1055Pt TREND LEFT TO RIGHT 1056Pt TREND RIGHT TO LEFT 1056Pt TRENDS ABOVE GRID 1056Pt TREND TOP TO BOTTOM 1056Pt TREND VERTICAL 1056PtTty 1066

argv[0], using program nameas 1075

bandwidth threshold 1086buffer 1072

size 1072using 1075

callbacksdevice resized 1079output 1080process terminated 1081

characters



number written todevice 1076

to be written to device 1076COLUMNS 1073command 1073convenience functions 1087device

pathname 1076resizing automatically 1075size 1073size, limiting to

terminal 1075size, same as terminal 1075

environment variables,modifying 1073, 1075

exit status 1074file descriptor

all 1074read 1078resources 1069set 1074standard input, output, and

error 1078write 1079

flags 1075LINES 1073Photon pulses, priority 1077process

arguments 1071ID 1077

program name, using asargv[0]1075

pseudo-tty device 1077Pt ARG BANDWIDTH THRESHOLD

1086Pt ARG FLAGS 1066Pt ARG TTY ARGV 1071

Pt ARG TTY BUFFER 1072Pt ARG TTY BUFLEN 1072Pt ARG TTY CMD 1072,

1073Pt ARG TTY DEVSIZE 1073Pt ARG TTY EXIT STATUS

1074, 1081Pt ARG TTY FDS 1074Pt ARG TTY FDSET 1074Pt ARG TTY FLAGS 1075Pt ARG TTY INPUT 1076Pt ARG TTY INPUT WRITTEN

1076Pt ARG TTY PATH 1076Pt ARG TTY PID 1073, 1077Pt ARG TTY PRI 1077Pt ARG TTY PSEUDO 1077Pt ARG TTY RFD 1078Pt ARG TTY SFD 1078Pt ARG TTY SPAWN OPTIONS

1078Pt ARG TTY WFD 1079Pt CB TTY DEVSIZE 1079Pt CB TTY OUTPUT 1080Pt CB TTY TERMINATED

1081shell, returning name of 1088spawn options 1078TERM 1073widget, resizing

automatically 1075Pt TTY ARGV0 1071, 1073, 1075Pt TTY BUF PRIVATE 1075Pt TTY DEVFORCE 1075Pt TTY DEVLIMIT 1075Pt TTY DEVRESIZE 1075PtTtyOutput t 1081



Pt TTY SETENV 1073, 1075PtTtyShell() 1088Pt TTY TERMRESIZE 1075Pt ULINE ETCHED IN 465Pt ULINE ETCHED OUT 465PtUpDown 1089

arm color 1090borders

width 1092decrement

image 1091, 1092flags 1092increment

image 1091, 1092indicator

spacing between 1093orientation 1091Pt ARG ARM COLOR 1090Pt ARG ORIENTATION 1091Pt ARG UPDOWN ARM DATA DECREMENT

1091Pt ARG UPDOWN ARM DATA INCREMENT

1091Pt ARG UPDOWN BORDER WIDTH

1092Pt ARG UPDOWN DATA DECREMENT

1092Pt ARG UPDOWN DATA INCREMENT

1092Pt ARG UPDOWN FLAGS

1092Pt ARG UPDOWN INDICATOR MARGIN

1093Pt CB ACTIVATE 1096Pt CB ARM 1096Pt CB DISARM 1096zzzzzzzzzz 1092, 1093

Pt UPDOWN DECREMENT ARM IMAGE1093

Pt UPDOWN DECREMENT IMAGE1092

Pt UPDOWN FILL ON ARM 1093Pt UPDOWN INCREMENT ARM IMAGE

1093Pt UPDOWN INCREMENT IMAGE

1092Pt UPDOWN ROTATE INDICATORS

1093Pt USE ELLIPSIS 460Pt WEB ACTION ABORT 1160,

1188Pt WEB ACTION ADD 1114Pt WEB ACTION DELETE 1114Pt WEB ACTION DISPLAY 1113Pt WEB ACTION OK 1160, 1188Pt WEB ACTION SAVEAS 1113PtWebAuthenticateCallback t

1159Pt WEB BASIC AUTHENTICATION

1104, 1159PtWebClient 1097

callbacksauthentication 1159certificates 1169closing window 1160file requested 1162file, unknown 1187loading complete 1161loading error 1165meta data 1170new window 1172page information 1173right-click 1161scrolling 1171



SSL certification 1174SSL client error 1180SSL error 1181SSL nontrusted 1176start loading 1183status 1184URL being loaded 1188

certificate information 1116certificates 1110client protocol data

stream 1107context information 1111DNS errors 1115downloads 1164encoding 1110external helpers 1114file, downloading 1109frame navigation 1117link

deactivating 1103navigation 1118

optionsauthentication 1128disk-cache 1134file 1130FTP 1129Gopher 1129HTML 1122HTTP 1130HTTP cookie 1128image 1131miscellaneous 1135print 1132SOCKS 1133TCP/IP 1133

pageloading, stopping 1157

navigation 1119printing 1153reloading 1154

Pt ARG WEB ACTIVATE LINK1103

Pt ARG WEB AUTHENTICATE1103

Pt ARG WEB BUILD DATE1104

Pt ARG WEB COMMAND1105

Pt ARG WEB DATA 1107Pt ARG WEB DOWNLOAD

1109Pt ARG WEB ENCODING

1110Pt ARG WEB GET CERTIFICATES

1110Pt ARG WEB GET CONTEXT

1111Pt ARG WEB GET HISTORY

1111Pt ARG WEB GET URL

1098, 1113Pt ARG WEB HELPER 1114Pt ARG WEB H ERRNO

1115Pt ARG WEB IMPORT CERTIFICATE

1116Pt ARG WEB NAVIGATE FRAME

1117Pt ARG WEB NAVIGATE LINK

1118Pt ARG WEB NAVIGATE PAGE

1119Pt ARG WEB OPTION 1120Pt ARG WEB PRINT 1153



Pt ARG WEB RELOAD 1154Pt ARG WEB SERVER 1097,

1154Pt ARG WEB SERVER PID

1156Pt ARG WEB SSL RESPONSE

1156Pt ARG WEB STARTUP ERRNO

1098, 1157Pt ARG WEB STOP 1157Pt ARG WEB UNKNOWN RESP

1157Pt ARG WEB VERSION

1158Pt CB WEB AUTHENTICATE

1159Pt CB WEB CLOSE WINDOW

1160Pt CB WEB COMPLETE

1161Pt CB WEB CONTEXT 1161Pt CB WEB DATA REQ 1162Pt CB WEB DOWNLOAD

1164Pt CB WEB ERROR 1165Pt CB WEB IMPORT CERTIFICATE

1169Pt CB WEB METADATA

1170Pt CB WEB NEED SCROLL

1171Pt CB WEB NEW WINDOW

1172Pt CB WEB PAGE INFO

1173Pt CB WEB SSL CERTINFO

1174

Pt CB WEB SSL CERTNONTRUSTED1176

Pt CB WEB SSL CLIENT CERT SELECT1180

Pt CB WEB SSL ERROR1181

Pt CB WEB START 1183Pt CB WEB STATUS 1184Pt CB WEB UNKNOWN

1187Pt CB WEB URL 1188scrolling 1119server

authenticationinformation 1103

build date 1104command 1105options 1120path 1097, 1154process ID 1156unknown response 1157version 1158

site history list 1111SSL (Secure Sockets Layer)

response 1156starting 1097startup errors 1098, 1157URL 1098, 1113

PtWebClient2SSLResponse t

1179, 1183PtWebClient2SSLResponse t

* 1156PtWebClientAuthenticationData t

1103PtWebClientData t * 1107PtWebClientHelperData t

1114



PtWebClientHistory t 1111PtWebClientHistoryData t

1112PtWebClientUnknownData t

1157PtWebCommand t 1105Pt WEB COMMAND FIND 1105Pt WEB COMMAND LOADMISSING 1106Pt WEB COMMAND LOADMISSING CONTEXT

1106Pt WEB COMMAND PURGECACHE

1106Pt WEB COMMAND RESETOPT 1106Pt WEB COMMAND SAVEAS 1106PtWebCompleteCallback t

1161Pt WEB CONTEXT ANCHOR 1111,

1162Pt WEB CONTEXT BKGD 1111,

1162PtWebContextCallback t

1162Pt WEB CONTEXT OBJECT 1111,

1162Pt WEB DATA BODY 1107, 1163Pt WEB DATA CLOSE 1107, 1163Pt WEB DATA HEADER 1107,

1163PtWebDataReqCallback t

1163Pt WEB DIGEST AUTHENTICATION

1104, 1159Pt WEB DIRECTION BACK

1117–1119Pt WEB DIRECTION DOWN

1117–1119, 1171

Pt WEB DIRECTION FWD 1117–1119

Pt WEB DIRECTION LEFT1117–1119, 1171

Pt WEB DIRECTION RIGHT1117–1119, 1171

Pt WEB DIRECTION UP 1117–1119,1171

PtWebDownloadCallback t

1164Pt WEB ERRORBasicConstraints

1183PtWebErrorCallback t 1166Pt WEB ERRORCertChainIncomplete

1183Pt WEB ERRORCertChainInvalid

1182Pt WEB ERRORCertExpired 1182Pt WEB ERRORCertNamesNotEqual

1182Pt WEB ERRORCertNoError 1182Pt WEB ERRORFailedVerify 1183Pt WEB ERRORFILE 1166Pt WEB ERRORIncorrectKeyUsage

1183Pt WEB ERRORInvalidSignature

1183Pt WEB ERRORRootCertificateNotValid

1183Pt WEB ERRORSERVEREXIT 1166Pt WEB ERRORSUBVIEW 1166Pt WEB ERRORTOPVIEW 1166Pt WEB ERRORWML 1166Pt WEB FIND GO BACKWARDS 1106Pt WEB FIND MATCH CASE 1106



Pt WEB FIND MATCH WHOLE WORDS1106

Pt WEB FIND START AT TOP 1106Pt WEB IMPORT CERT AUTHENTICATION

1160PtWebImportCertificateCallback t

1169PtWebMetaDataCallback t

1170PtWebNeedScrollCallback t

1171Pt WEB NO DISK CACHE 1113Pt WEB NO MEMORY CACHE 1113Pt WEB NO PAGE HISTORY 1114Pt WEB NO SITE HISTORY 1114PtWebPageInfoCallback t

1173Pt WEB PRINT ALL FRAMES 1154Pt WEB PRINT FROM CACHE 1154Pt WEB PROXY AUTHENTICATION

1104, 1160Pt WEB RESIZEABLE 1173Pt WEB RESPONSECANCEL 1104,

1157, 1158, 1179, 1183Pt WEB RESPONSECONTINUE 1179Pt WEB RESPONSEOK 1104,

1157, 1158, 1180, 1183Pt WEB SHOW LOCATION 1173Pt WEB SHOW MENUBAR 1173Pt WEB SHOW STATUS 1173Pt WEB SHOW TOOLBAR 1172PtWebSSLCertInfoCallback t

1174PtWebSSLCertNonTrustedCallback t

1177PtWebSSLClientCertCallback t

1180

PtWebSSLErrorCallback t

1182PtWebStatusCallback t 1184Pt WEB STATUS CONNECT 1185Pt WEB STATUS DEFAULT 1185Pt WEB STATUS INFO 1185Pt WEB STATUS MOUSE 1185Pt WEB STATUS PRINT 1187Pt WEB STATUS PROGRESS 1185PtWebUnknownCallback t

1187PtWebUrlCallback t 1189PtWebWindowCallback t 1172PtWidget 1193

activation by any mousebutton 1203

anchor flags 1197, 1198anchor offsets 1197, 1198area 1193, 1199autohighlighting 1203balloons

popping upimmediately 1198

bevel width 1199blocking 1203callbacks

blocked 1215destroyed 1215, 1222drag-and-drop 1216filter 1219hotkey 1221outbound 1222raw event 1223unrealized 1225

callbacks, invoking whenresources are set 1203

cursor



bitmap 1200color 1200type 1200

damageindicating for family 1204indicating for widget 1204propagating to parent 1202

destruction, marked for 1204dimensions 1193, 1199, 1201

maximum 1210minimum 1211

events, consuming 1202extended flags 1202extent 1193, 1202extent, no intersections

with 1204flags 1203flux 1205focus, granting 1204ghosting 1204height 1193, 1199, 1201, 1209


help information 1202, 1209highlighting

automatically 1203clipping corners 1204requesting 1205

layoutsskipping 1202

menu button 1205menuable 1205obscured 1205opaque 1205position 1193, 1199, 1211procreated child 1205

Pt ARG ANCHOR FLAGS1197, 1198

Pt ARG ANCHOR OFFSETS1197, 1198

Pt ARG AREA 1193, 1198,1199

Pt ARG BEVEL WIDTH1199

Pt ARG BITMAP CURSOR1200

Pt ARG CURSOR COLOR1200

Pt ARG CURSOR TYPE1200

Pt ARG DATA 1201Pt ARG DIM 1193, 1198,

1201Pt ARG EFLAGS 1202, 1209Pt ARG EXTENT 1193, 1202Pt ARG FLAGS 1203Pt ARG GRID LAYOUT DATA

1193, 1206Pt ARG HEIGHT 1194, 1209Pt ARG HELP TOPIC 1209Pt ARG LAYOUT DATA

1194, 1210Pt ARG MAXIMUM DIM

1194, 1210Pt ARG MINIMUM DIM

1194, 1211Pt ARG POINTER 1194, 1211Pt ARG POS 1194, 1211Pt ARG RESIZE FLAGS

1212Pt ARG ROW LAYOUT DATA

1194, 1213



Pt ARG USER DATA 1195,1214

Pt ARG WIDTH 1194, 1215Pt CB BLOCKED 1215Pt CB DESTROYED 1215Pt CB DND 1216Pt CB FILTER 1219Pt CB HOTKEY 1221Pt CB IS DESTROYED 1222Pt CB OUTBOUND 1222Pt CB RAW 1223Pt CB REALIZED 1225Pt CB UNREALIZED 1225realizing

callback 1225delaying 1204indicating completion 1205indicating in progress 1205whenever resources are

set 1206redrawing, preventing 1206region, forcing to have 1206render focus 1204resizing

flags 1212whenever resources are

set 1206selectable 1206set state 1206toggling, enabling 1206user-defined data 1194, 1211,

1214width 1193, 1199, 1201, 1215


x, y coordinates 1193, 1199,1211

PtWidgetClassStyle t 63PtWidgetFlags() 1203Pt WIDGET REBUILD 1206Pt WIDGET RESIZE 1206PtWindow 1226

active color 1233Alt function key combinations

1239application 1237backdrop 1234, 1239block input 1239border 1237callbacks

opening 1243transport 1243window event 1241

close button 1237closing 1234

callback 1242collapse button 1237collapsing to title bar 1234,

1239convenience functions 1247cursors, overriding

children’s 184cycling focus 1234dialog 1237flags 1233

managed 1228, 1234notify 1230, 1236render 1227, 1237

focusgaining and losing 1234giving 1249giving when opened 1239

force front 1234, 1239height




helpbutton 1237context-sensitive 1234root 1234

hiding 1234, 1239icon 1237iconifying 1239in front 1239inactive color 1234inline 1237maximize button 1238maximizing 1234, 1239menu button 1238minimize button 1238moving 1234palette 1237Pt ARG CURSOR OVERRIDE

184Pt ARG MAX HEIGHT 1232Pt ARG MAX WIDTH 1232Pt ARG MIN HEIGHT 1232Pt ARG MIN WIDTH 1233Pt ARG WINDOW ACTIVE COLOR

1233Pt ARG WINDOW FLAGS

1233Pt ARG WINDOW FRONT WINDOW

1233Pt ARG WINDOW HELP ROOT

1234Pt ARG WINDOW INACTIVE COLOR

1234Pt ARG WINDOW MANAGED FLAGS

1228, 1234

Pt ARG WINDOW NOTIFY FLAGS1230, 1236

Pt ARG WINDOW RENDER FLAGS1227, 1237

Pt ARG WINDOW STATE1238

Pt ARG WINDOW TITLE1240

Pt ARG WINDOW TITLE COLOR1241

Pt CB WINDOW 1241Pt CB WINDOW CLOSING

1242Pt CB WINDOW OPENING

1243Pt CB WINDOW TRANSPORT

1243resizing 1228, 1234

handles 1238restoring 1234sending to back 1234, 1253sending to front 1234, 1255state 1238

getting 1251subwindows 1230switching consoles

automatically 1234taskbar, including in 1234title

bar 1238color 1241text 1240

widthmaximum 1232minimum 1233

window in front 1233window manager 1227



window menu 1234PtWindowFocus() 1249PtWindowGetState() 1251PtWindowToBack() 1253PtWindowToFront() 1255Pt Z STRING 87, 451, 461pushbutton widget See PtButtonPWM 1226

R

range-select mode 314raw callbacks 13, 1223raw drawing widget See PtRawraw list See PtRawListraw tree See PtRawTreerealizing

delaying 1204done 1205in progress 1205Pt CB REALIZED 1225whenever resources are

set 1206rebuilding 1206rectangle widget See PtRectredrawing, preventing 1206region

forcing a widget to have 1206region widget See PtRegionrender shared library 660replace mode 912resizing

callback 196flags 1212

and anchor flags 1213

policy 414, 1212whenever resources are

set 1206resources

inheritance of 18types 26

reverse gradientfill 55

row widget See PtGroup

S

scroll area widget SeePtScrollArea

scrollable container widget SeePtScrollContainer

scrollbar widget SeePtScrollbar

selectingenabling 1206widgets 47

selection mode 314separator widget See

PtSeparator

servers See PtServerset state

Pt CB ACTIVATE 64shared memory 660Shift-click selection 314single-select mode 314slider widget See PtSliderspace, sharing among widgetsSee

PtDivider

style 62superclass widget See PtWidget



T

Tab character, use as columnseparator 475, 980

tab widget See PtTabterminal emulator widget See

PtTerminal

attached to a device SeePtTty

TEXT 1103text widget

label See PtLabelmultiline See PtMultiTextsingle-line See PtTextwith list of choices See

PtComboBox

TEXTAREA 1103threshold, graphics bandwidth 52time widget See PtClocktimer widget See PtTimertoggle button widget See

PtToggleButton

togglingenabling 1206Pt CB ACTIVATE 64state, checking 64

toolbars See PtToolbarGroup,See PtToolbar

transparency pattern 63, 417Tree Item State method

tree widgets 380, 382tree widget

general purpose See PtTreesuperclass See also

PtGenTree

tree widgetsmethods

Tree Item State 380, 382tree, raw See PtRawTreetrend widget See PtMTrend, See

PtTrend

TRY AGAIN 1116

U

unrealizingPt CB UNREALIZED 1225

up/down button widget SeePtUpDown

UPDOWN BOTTOM 1096UPDOWN LEFT 1096UPDOWN RIGHT 1096UPDOWN TOP 1096user-defined data 957, 1194, 1211,

1214PtRaw 731

V

vector graphics 410viewport widget See

PtScrollArea, SeePtScrollContainer

Voyager Web Server 1097

W

web browserseePtWebClient 1097



web server 1097wedge 34widget See also PtWidget

contributed xixdescription, contents of 25hierarchy 17

widgetsicon in PhAB 18

width 1193, 1199, 1201, 1215maximum 1194, 1210minimum 1194, 1211

window manager 1226window widget See PtWindow

X

x, y coordinates 1193, 1199, 1211


Documents

WIDGET REFERENCE