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

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.