Caution: This version of this document is no longer maintained. For the latest documentation, see

About This Manual

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

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

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:

Note: Notes point out something important or useful.

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

WARNING: 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:
Previous To the previous part of the document.
Contents "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.
Keyword index To the keyword index.
Next 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 ( 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


Corrected the description.

What's new in Photon for QNX Neutrino 6.2.0

This section summarizes the changes to these chapters:


Anatomy of a Widget

Creating a List Widget

Creating a Tree Widget

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:

Miscellaneous Widget-Building Tips

Various tips have been added.

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