About This Guide

The Photon Programmer's Guide is intended for developers of Photon applications. It describes how to create applications and the widgets that make up their user interfaces, with and without using the Photon Application Builder (PhAB).

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

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
What's new in Photon for QNX Neutrino 6.0

to find out how Photon and its widgets have changed in this release.

This table may help you find what you need in this book:

For information about:	See:
Photon, widgets, and PhAB	Introduction
Getting started with PhAB	Tutorials
PhAB's user interface	PhAB's Environment
Creating, opening, and saving applications in PhAB	Working with Applications
PhAB modules, such as windows, dialogs, and menus	Working with Modules
Adding, deleting, and modifying widgets in PhAB	Creating Widgets in PhAB
Initializing a widget's resources and callbacks	Editing Resources and Callbacks in PhAB
Setting the sizes of a widget and its children	Geometry Management
Getting PhAB to generate code	Generating, Compiling, and Running Code
Editing code generated by PhAB	Working with Code
Getting and setting widget resources	Manipulating Resources in Application Code
Adding or modifying widgets "on the fly" at runtime	Managing Widgets in Application Code
Building special areas into a widget	Control Surfaces
Using internal links to refer to PhAB modules	Accessing PhAB Modules from Code
Developing a multilingual application	International Language Support
Adding help information to your application	Context-Sensitive Help
Communicating with a Photon application	Interprocess Communication
Threads, work procedures, and background processing	Parallel Operations
Using `PtRaw` and Photon's low-level drawing routines	Raw Drawing and Animation
Photon's fonts	Fonts
Printing in a Photon application	Printing
Transferring data from one widget or application to another	Drag and Drop
Photon's regions	Regions
Interaction between applications, users, and the Photon server	Events
Working with windows and modal dialogs	Window Management
Developing applications "by hand" without PhAB	Programming Photon without PhAB
Photon's implementation	Photon Architecture
PhAB's widget icons	Widgets at a Glance
Handling international characters	Unicode Multilingual Support
Building an embedded system	Photon in Embedded Systems
Differences between the Windows and native QNX Neutrino versions of PhAB	Using PhAB under Microsoft Windows
Photon terminology	Glossary

What's new in Photon for QNX Neutrino 6.3

New content

The PhAB's Environment -- PhAB's interface has changed, including an updated menu and simplified toolbar.
The Geometry Management chapter now describes how to use layouts to manage widget placement.
The directory structure for PhAB projects has changed, and is described in How application files are organized.
The Generating, Compiling and Running Code chapter now describes how you can Manage targets.
The Raw Drawing and Animation chapter now describes how you can use layers.
The Fonts chapter is updated with information about the new font library.
The Photon in Embedded Systems appendix has a new example of creating a floppy containing Photon and some applications, and is updated with new font library information pertinent to embedded systems.

What's new in Photon for QNX Neutrino 6.2.1

New content

Listed the supported platforms; see "Versions and platforms" in the Introduction.
The Interprocess Communication chapter has a better description of how to use Photon connections.
There's a new section, "Layers," in the Raw Drawing and Animation chapter.
Added a description of the PHINDOWSOPTS environment variable to the Using PhAB under Microsoft Windows appendix.

Errata

The libraries in /usr/photon/lib are provided for runtime compatibility with Photon for QNX Neutrino 6.0 (x86 only). The current libraries are in /usr/lib. For more information about the libraries, see "Photon libraries" in the Introduction.
Corrected the call to ionotify() in "Sending the pulse message to the deliverer" in the Interprocess Communication chapter.
The instructions for printing a PtMultiText widget have been corrected.
The order of the options to the on command have been corrected in "Putting it all together" in the Photon in Embedded Systems appendix.
If you want to use a graphical debugger when developing in Windows, use the IDE.

What's new in Photon for QNX Neutrino 6.2.0

New content

The Edit menu now includes Undo and Redo commands. For more information, see the chapter on PhAB's Environment.
PhAB can't import QNX Windows picture files any more.
You can now specify a list of library callback functions when you start PhAB. For more information, see appbuilder in the QNX Neutrino Utilities Reference.
"Making a DLL out of a PhAB application" in the Generating, Compiling, and Running Code chapter
"Widget styles" in the Managing Widgets in Application Code chapter
"Offscreen locks" in the Raw Drawing and Animation chapter.
Using PhAB under Microsoft Windows appendix

What's new in Photon for QNX Neutrino 6.0

This section doesn't try to describe all the changes to PhAB's user interface; most you'll discover by trying it yourself or by scanning this manual. Instead, this section lists only the major changes.

The changes are listed below by chapter:

Introduction
PhAB's Environment
Working with Applications
Working with Modules
Creating Widgets in PhAB
Geometry Management
Working with Code
Manipulating Resources in Application Code
Managing Widgets in Application Code
Context-Sensitive Help
Interprocess Communication
Parallel Operations
Raw Drawing and Animation
Fonts
Printing
Drag and Drop
Events

Introduction

The geometry of a widget has changed slightly; it now includes the widget's border. For more information, see "Widget geometry."

PhAB's Environment

You no longer need to press Enter after giving an instance name to a widget.

Working with Applications

It's no longer possible to override the standard Photon mainloop function.

Working with Modules

PtWindow widgets (which are used to instantiate Window modules) no longer include an icon resource. You must now use PhAB to associate an icon with the window.
You can no longer create "other" modules (file selectors or messages) in PhAB, although they're still supported for existing applications. Instead of the file selector, use one of:
- PtFileSel
- PtFileSelection()
Instead of the message module, use one of:
For more information, see the Photon Library Reference.

Creating Widgets in PhAB

You can now create templates, or customized widgets, to use as the basis when creating other widgets.

Geometry Management

In the current version of the Photon microGUI, widgets are anchored immediately upon creation. In earlier versions, anchoring is done when the widgets are realized.
If the resize policy conflicts with the anchors, the Pt_ARG_RESIZE_FLAGS override Pt_ARG_ANCHOR_OFFSETS and Pt_ARG_ANCHOR_FLAGS.

Working with Code

New sections:

Timers

Manipulating Resources in Application Code

New sections:

Other changes:

When setting string resources, the fourth argument to PtSetArg() is the number of bytes to copy; if it's 0, strlen() is used to determine the length of the string.
Changes to the widget's state may invalidate the pointers returned by PtGetResources(); use them promptly.

Managing Widgets in Application Code

New sections:

Ordering widgets

Context-Sensitive Help

The PxHelp* functions are now named PtHelp* and are in the main Photon library, ph.

Interprocess Communication

New sections:

Connections -- the best method of IPC for Photon applications.

Other changes:

As described in "Adding an input handler," an input handler must return one of the following:

Pt_CONTINUE

The input handler doesn't recognize the message. If there are other input handlers attached to the same process ID, they're called. If there are no input handlers attached specifically to this process ID, or if all input handlers attached specifically to this process ID return Pt_CONTINUE, the library looks for input handlers attached to pid 0. If all the input handlers return Pt_CONTINUE, the library replies to the message with an ENOSYS.

Pt_END

The message has been recognized and processed and the input handler needs to be removed from the list. No other input handlers are called for this message.

Pt_HALT

The message has been recognized and processed but the input handler needs to stay on the list. No other input handlers are called for this message.

This creates several incompatibilities with earlier versions of the Photon microGUI:
- If an input handler replies to the message and returns Pt_CONTINUE (or if the message is from a proxy/pulse), everything should be OK. The current library tries and fails to reply again, but that's harmless. Still, it's a good idea to change the code to return Pt_HALT; this prevents the library from calling other input handlers or replying.
- If an input handler returns Pt_CONTINUE without replying to the message, the old library doesn't reply either, but the current one does. You need to change the code to return Pt_HALT.
- If an input handler returns Pt_END (which is the most obvious value other than Pt_CONTINUE), the only situation that can cause a problem is when you have multiple input handlers attached to the same process ID.
- If an input handler returns a value other than Pt_CONTINUE or Pt_END, the old library removes it from the list but the new library doesn't. You need to change the code to return Pt_END.

Parallel Operations

New sections:

Threads

Raw Drawing and Animation

New sections:

Other changes:

If you use PxLoadImage() to load an transparent image, set PX_TRANSPARENT in the flags member of the PxMethods_t structure. If you do this, the function automatically makes the image transparent; you don't need to create a transparency mask. See "Transparency in images."

Fonts

New chapter.

Printing

The entire API has been made simpler. Applications that call the old routines should still work, but you should reread this chapter.

Drag and Drop

New chapter.

Events

New sections:

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.