This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

About This Manual

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

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

to find out what has changed in this version.

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:

Notes point out something important or useful.

Cautions tell you about commands or procedures that may have unwanted or undesirable side effects.

Warnings tell you about commands or procedures that could be dangerous to your files, your hardware, or even yourself.

Note to Windows users

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

We also generally follow POSIX/UNIX filesystem conventions.

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:

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:

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.