---

About This Manual

The Building Custom Widgets guide is intended for Photon programmers who want to create custom widgets.

This manual contains everything you need to know about building your own Photon widgets. Sample code is used throughout this manual to demonstrate new concepts.

When you want to:	Go to:
Learn about widget concepts, attributes, and behavior	Overview
Initialize a widget class, set up a widget instance structure, or set application resources	Life Cycle of a Widget
Define a widget class, its resources, methods, or actions	Anatomy of a Widget
Choose a widget superclass to base your custom widget on	Using Widget Superclasses
Customize a list widget	Creating a List Widget
Customize a tree widget	Creating a Tree Widget
Add a custom widget to the PhAB widget palette	Binding Widgets into PhAB
Manage widgets using the supplied convenience functions	Widget Building Library API
Create a custom PhAB resource editor for your widget's resources	Creating custom resource editors
Read about the resource editor plugin API	The resource editor API
See an example of a resource editor plugin	Resource editor plugin example
Read widget-building tips	Miscellaneous Widget-Building Tips
Look up Photon terms	Glossary

Typographical conventions

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

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

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

You'll find the Other... menu item under Perspective-->Show View.

We use notes, cautions, and warnings to highlight important messages:

Note to Windows users

In our documentation, we use a forward slash (/) as a delimiter in all pathnames, including those pointing to Windows files.

We also generally follow POSIX/UNIX filesystem conventions.

Navigation buttons

At the top and bottom of our HTML docs, you'll see some or all of these buttons:

Use this button:	To move:
	To the previous part of the document.
	"Up" in the document: In a prose book, this typically takes you to About This Guide. In a reference book, it takes you to the listing of items that start with a given letter. For example, if you're looking at the docs for abs(), this button takes you to the listing of the functions that start with A.
	To the keyword index.
	To the next part of the document.

Technical support

To obtain technical support for any QNX product, visit the Support + Services area on our website (www.qnx.com). You'll find a wide range of support options, including community forums.

What's new in Photon for QNX Neutrino 6.3.0 Service Pack 1

Two new functions:

• PtGetCallbackList()
• PtInvokeCallbackType()

What's new in Photon for QNX Neutrino 6.3

Resource editor plugin API

The chapters dealing with the resource editor plugin API are new. These chapters are:

• Creating custom resource editors
• The resource editor API
• Resource editor plugin example

The new function PtFindResouce() replaces PtFindResourceRecord(), which is deprecated.

Binding Widgets into PhAB -- There is a new ushort resource type.

What's new in Photon for QNX Neutrino 6.2.1

Errata

PtWidgetAbove()

Corrected the description.

What's new in Photon for QNX Neutrino 6.2.0

This section summarizes the changes to these chapters:

• Overview
• Anatomy of a Widget
• Creating a List Widget
• Creating a Tree Widget
• Widget Building Library API
• Binding Widgets into PhAB
• Miscellaneous Widget-Building Tips

Overview

• Anchoring is now done by PtWidget instead of PtContainer.

Anatomy of a Widget

• The section on PtResourceRec_t resource records includes new mod_f special values (Pt_CHANGE_CANVAS and Pt_CHANGE_CANVAS_REDRAW) and a new arg_value type (Pt_ARG_IS_IMAGE).
• Widget classes now include a textual description. See "Widget class resource table."
• PtContainerChildRedirect() no longer exists; use the Pt_SET_CHILD_REDIRECT_F manifest in your widget's class-creation function instead. See "Container widget anatomy."

Creating a List Widget

• The prototypes have changed for PtSuperClassGenListMouse() and PtSuperClassGenListSelect().

Creating a Tree Widget

• When expanding an item, the Tree Item State method returns zero to permit the expansion, or a nonzero value to prevent it -- PtGenTreeExpand() returns this value. When collapsing an item, the Tree Item State method returns a nonzero value if the item is destroyed, or zero if the item still exists -- PtGenTreeCollapse() returns this value (the prototype has changed).
• PtGenTreeAddAfter() and PtGenTreeAddFirst() now return 0 on success, or -1 if the item is already in a tree.
• PtGenTreeFreeItems() now returns 0 on success, or -1 if the items are still in a tree.

Binding Widgets into PhAB

The method for binding widgets into PhAB has changed. If PhAB can open the shared object for your widget, it can display your widget correctly, and you can work with them "live."

Widget Building Library API

New functions:

• PtAnchorDeregister() -- replaces PtContainerDeregister().
• PtAnchorRegister() -- replaces PtContainerRegister().
• PtResizeCanvas() -- similar to PtAttemptResize(), but easier to use.

• PtContainerChildRedirect() no longer exists; use the Pt_SET_CHILD_REDIRECT_F manifest in your widget's class-creation function instead. See "Container widget anatomy" in the Anatomy of a Widget chapter.
• PtGetAnchoredExtent() no longer exists; anchors are handled by the widget library.
• PtInvokeResizeCallbacks() is now a void function. It assumes that the widget passed to it is a container.

Miscellaneous Widget-Building Tips

Various tips have been added.

Copyright ©1996-2007, QNX Software Systems. All rights reserved.

---