About This Guide

For an overview of the changes to the software and docs, see "What's new in Photon 1.14 (as of June 02, 2000)."

The Photon Programmer's Guide is intended for developers of Photon applications. It includes the following:

• an introduction to Photon and the Photon Application Builder (PhAB)
• a set of tutorials to get you started using PhAB
• a description of PhAB's environment
• how to develop PhAB applications:
  • working with an application as a whole
  • working with an application's modules
  • creating widgets in PhAB
  • editing a widget's resources and callbacks in PhAB
  • managing widget geometry
  • generating, compiling, and running code
  • writing code for a PhAB application
  • manipulating widget resources in application code
  • creating widgets in application code for a dynamic user interface
• advanced programming techniques:
  • accessing PhAB modules from your application's code
  • international language support
  • context-sensitive help
  • interprocess communication (IPC) and lengthy operations
  • raw drawing and animation
  • fonts
  • printing
  • working with regions
  • handling events
  • window management
• developing Photon applications without PhAB (for those who insist on doing everything "by hand")
• additional topics, each in an appendix:
  • Photon architecture
  • widgets at a glance
  • Unicode multilingual support
• a glossary

If you'd like to see some sample Photon applications, look in the /usr/free/qnx4/photon/examples directory in QUICS.

What's new in Photon 1.14 (as of June 02, 2000)

Introduction

• The definition of a widget's canvas has been corrected in "Widget geometry."
• You can choose to have the application notified when the widget is actually destroyed by registering a function with the destroy callback (Pt_CB_DESTROYED) for the widget. See "Widget life cycle" in the Introduction chapter.

PhAB's Environment

• The control panel doesn't display all the resources for a widget. PhAB sets Pt_ARG_AREA, Pt_ARG_DIM, and Pt_ARG_POS automatically when you move or resize a widget. Some other resources are too complex to edit in PhAB.

Working with Applications

• You should develop a naming convention for all the widgets in your application - it will make large applications more manageable.

Working with Modules

• We strongly recommend that you not use the Other modules. Instead, use the PtFileSel and PtMessage widgets (see the Photon Widget Reference) or PtFileSelection() and PtAskQuestion() (see the Photon Library Reference).

Editing Resources and Callbacks in PhAB

• As described in "Attaching callbacks," a Done callback in the base window exits the application. A Cancel callback in the base window closes the application's windows but doesn't exit the application.
• A section on hotkeys - the basics has been added.
• As described in "Processing hotkeys," setting the Pt_HOTKEYS_FIRST flag for container-class widgets makes them process key events that reach the container as hotkeys before passing them to their children. If the event is a hotkey, it's consumed, so it isn't passed to the children.

  When adding raw-event callbacks, note that the Pt_CB_RAW callbacks defined for PtWidget are invoked after the widget has processed the event, and then only for events that the widget doesn't consume. In contrast, the Pt_CB_FILTER callbacks defined for PtContainer are invoked before the event is passed to the child widget.

Generating, Compiling, & Running Code

• A section on version control has been added.
• A section on adding libraries to your application's Makefile has been added.

Working with Code

• The value of a widget's ABN_... variable is unique only in the module that contains the widget. The variables for widgets in other modules might have the same value. See "Variables and manifests."
• PhAB doesn't create ABW_... manifests for menu modules or menu items. Menus typically don't exist for very long, so manifests for them aren't very useful. If you need to change the resources of the PtMenu, create a setup function for the menu module and do the work there. See "Module setup functions."
• A section on handling multiple instances of a window has been added.
• For an internal link, the widget pointer in the module setup function's apinfo is a copy of the widget pointer passed to ApCreateModule(). It's useful for positioning the module.

Manipulating Resources in Application Code

• When setting link resources, the widget copies the data into its internal memory.
• The pointer method of getting a Boolean resource has been simplified; the type is always an int.
• Changes to the widget's state may invalidate the pointers returned by PtGetResources(); use them promptly.

Creating Widgets in Application Code

• A section on ordering widgets has been added.
• The datatypes used for event handlers in "Adding event handlers" have been corrected.

Accessing PhAB Modules from Code

• An example of using an internal link to display a popup menu has been added.

International Language Support

• If the key used in a hotkey isn't a function key (i.e. the key code is less than 0xF000), PhAB automatically changes the hotkey to match the accelerator key. See "Hotkeys."
• When running, the application looks for the best match to the language extension. See "Running your application."

Context-Sensitive Help

• The helpviewer supports only GIF and BMP images.
• A section called "Help without the ? icon" has been added.

Interprocess Communication and Lengthy Operations

• The section on receiving QNX messages now discusses the message-buffer size.
• There's now an example of an input handler that replies to messages sent by the sin ver command.
• PtAppRemoveSignalProc() will remove any handlers for the given signals used internally by the libraries. You should use PtAppRemoveSignal() instead to remove signal handlers.
• It's safe to call PtBkgdHandlerProcess() in callbacks, work procedures, and input procedures, but not in a widget's Draw method or a PtRaw widget's drawing function.
• If your fd handler changes the display, it should call PtFlush() to make sure the display is updated.
• PtTimer is easy to use, but doesn't give accurate timer events. In particular, it doesn't guarantee a constant repeat rate; since the repetition is handled by rearming the timer for each event, any delays in handling the events accumulate. Kernel timers guarantee an accurate repeat rate even if your application can't keep up with them.
• The example in "Modal dialogs" has been replaced.

Raw Drawing and Animation

• Don't change any other widget in any way (creating, destroying, setting resources, and so on) in a raw widget's drawing function. It's safe to get resources from other widgets.
• Don't call the drawing function for a PtRaw directly from your program. Instead, damage the widget by calling PtDamageWidget(), and let the library call the drawing function.
• To close a polygon, use Pg_CLOSED as part of the flags. See "Polygons."
• The mask_bpl member of a PhImage_t structure doesn't need to be a multiple of 4. The leftmost pixel of the image corresponds to the top bit of the first byte in the transparency mask.

Printing

• The page range, Pp_PC_PAGE_RANGE, is just a string. The application must parse it to determine which pages should be printed. See "What's in a print context?."
• Don't set Pp_PC_DEVICE or Pp_PC_DRIVER for either method described in "Calling PpPrintSetPC()". They're set for you.
• The instructions for printing a PtMultiText widget have been corrected.

Regions

• Use the Ph_FORCE_FRONT flag to keep a region in front of its brothers. See "Ph_FORCE_FRONT flag."
• To see if shared memory can be used for drawing, check the system information. The Ph_GCAP_SHMEM flag is set in gfx.capabilities if all the graphics drivers support the ...mx() functions and they're all running on your node.

Events

• The timestamp member of the PhEvent_t is in milliseconds, not seconds.
• The section "Emitting events" has been corrected.
• The following sections have been added:
  • Targeting specific widgets
  • Emitting key events

Window Management

• A list of window-manager functions has been added.
• A section on running a standalone application has been added.
• The Pt_CB_WINDOW callbacks are invoked for only those events specified in the Pt_ARG_WINDOW_NOTIFY_FLAGS.
• The section on the notification callback now explains the difference between the notification of a window's closing and its actual closing.

Programming Photon without PhAB

• The section on compiling and linking a non-PhAB application now describes linking under Neutrino.
• The Pt_DELAY_ACTIVATION bit in the Pt_ARG_FLAGS resource is now called Pt_DELAY_REALIZE. This flag is discussed in the section on PtRealizeWidget() following the sample application.