About This Guide

    What's new in Photon

      Introduction

      PhAB's Environment

      Working with Applications

      Working with Modules

      Creating Widgets in PhAB

      Geometry Management

      Working with Code

      Manipulating Resources in Application Code

      Creating Widgets in Application Code

      Context-Sensitive Help

      Interprocess Communication

      Lengthy Operations

      Raw Drawing and Animation

      Fonts

      Printing

      Drag and Drop

      Events

Introduction

    Overview of the Photon architecture

    Photon Application Builder---PhAB

      Get immediate results

      Concentrate on functionality

      Create prototypes without writing code

      Cut code size

      Create consistent applications

      Create all kinds of applications

    Widget concepts

     Widget life cycle

     Widget geometry

    Programming paradigm

     Text-mode application

     Non-PhAB application

     PhAB application

    Photon libraries

    Building applications with PhAB---an overview

     Step 1: Create modules

     Step 2: Add widgets

     Step 3: Attach callbacks

     Step 4: Generate code

     Step 5: Run your application

     Step 6: Repeat any previous step

    Writing applications without PhAB

Tutorials

    Before you start...

    Tutorial 1 --- Hello World

     Creating the application

     Generating code

     Want more info?

    Tutorial 2 --- Editing Resources

     Adding a button widget

     Changing the bevel width

     Changing the font

     Changing the text alignment

     Setting flags

     Changing the fill color

     Editing a pixmap

     Editing multiline text

     Editing a list of text items

     Creating a template

     Want more info?

    Tutorial 3 --- Creating Menus and Menubars

     About link callbacks

     About instance names

     Creating a menubar

     Creating the File menu module

     Adding menu items

     Creating the Help menu module

     Attaching link callbacks

      Attaching a module-type link callback

      Attaching a code-type link callback

     Setting up the code

     Want more info?

    Tutorial 4 --- Creating Dialogs

     About dialogs

     More on instance names

     Attaching a dialog module

     Adding widgets to the dialog

     Adding a callback to the Done button

     Modifying a generated code function

     Compiling and Running

     Want more info?

    Tutorial 5 --- Creating Windows

     Creating a window

     Attaching callbacks

     Adding widgets

     Generating and modifying the code

      Generating the code

      Modifying the setup function

      Modifying the color-change function

      Modifying the window-close function

     Compiling and running

     Want more info?

PhAB's Environment

    Menus

     File menu

     Edit menu

     View menu

     Options menu

     Application menu

     Window menu

     Help menu

    Toolbars

    Control panels

    Widget palette

     Modes (create vs select)

      Determining the mode

      Switching to create mode

      Switching to select mode

    Resources panel

    Callbacks panel

    Module Tree panel

    Module Links panel

    Search panel

    Customizing your PhAB environment

     General preferences

     Color preferences

     Dragging preferences

    Grid preferences

Working with Applications

    Creating an application

    Opening an application

    Saving an application

     Naming or renaming an application

     Saving an existing application

     Overwriting an existing application

    Closing an application

    Specifying application startup information

     Specifying a global header file

     Initialization function

     Command-line options

     Including instance names

     Startup windows

      Adding a startup window

      Modifying a startup window

      Deleting a startup window

    Importing files

     Importing PhAB modules from other applications

     Importing graphics images

     Importing QNX Windows picture files

Working with Modules

    Module types

    Anatomy of a module

    Selecting a module

    How modules are saved

    Changing module resources

    Using the module selector

    Creating a new module

    Viewing a module

    Opening a module

    Deleting a module

    Iconifying modules

    Closing a module

    Displaying modules at run time

     Positioning a module

    Finding lost modules and icons

    Window modules

     Resizing a window module

    Dialog modules

     Resizing a dialog module

     Predefined dialogs

    Menu modules

     Opening the menu editor

     Specifying instance names

     Creating hotkeys and shortcuts

     Resizing a menu module

     Creating command items

     Creating submenu items

     Creating separator items

     Creating toggle items

     Creating function items

     Moving menu items

     Using a menu module

    Picture modules

     Displaying a picture

     Using pictures as widget databases

     Resizing a picture module

    Icon modules

     Specifying sizes and instance names

Creating Widgets in PhAB

    Types of widgets

    Instance names

     Default instance name

     When to assign a unique name

     Instance names and translations

     Duplicate names

    Creating a widget

     Creating several widgets

     Canceling create mode

    Selecting widgets

     A single widget

      Point-and-click method

      Control-panel methods

     Multiple widgets

      Using a bounding box

      Using Shift and click

      Using the control panels

     Widgets within a group

      Using the Module Tree panel

      Using the Next and Previous buttons

     Hidden widgets

    Aligning widgets

     To another widget

     To a parent container

    Common User Access (CUA) and handling focus

     Changing focus with the keyboard

     Controlling focus

     Focus callbacks

     Focus-handling functions

    Ordering widgets

    Dragging widgets

      Dragging preferences

    Setting a widget's x and y coordinates

    Transferring widgets between containers

    Resizing widgets and modules

    Clipboard

     Cutting and copying

     Pasting

     Viewing the clipboard

     Editing the clipboard

    Duplicating widgets and containers

    Deleting widgets

    Importing graphic files

    Changing a widget's class

    Templates

     Creating templates

     Editing templates

     Deleting templates

Editing Resources and Callbacks in PhAB

    Editing widget resources

    Pixmap editor

     Setting the pixmap's size

     How to draw and erase

     Choosing colors

      Choosing a background color

     Drawing freehand

     Drawing lines, rectangles, and circles

     Filling an enclosed area

     Selecting an area

     Nudging an area

     Using the Pixmap toolbar

     Other pixmap controls

    Color editor

     Full color editor

     Quick color editor

    Flag/option editor

     Flag resources

     Option list resources

    Font editor

    List editor

     Editing existing list items

     Deleting list items

    Number editor

    Text editors

    Function editor

    Callbacks

    Editing callbacks

    Module callbacks

     Prerealize setup function

     Postrealize setup function

     Setup functions are stored in stub files

    Code callbacks

     Callback functions are stored in stub files

    Hotkey callbacks

     Hotkeys --- the basics

     Specifying the hotkey label

     Specifying the callback

      Where you want a module to appear

      What widget you need in the callback function

      Where the user is going to type the hotkey

     Processing hotkeys

     Disabling hotkeys

    Event handlers --- raw and filter callbacks

Geometry Management

    Container widgets

    Geometry negotiation

     Resize policy

      Setting the resize policy in PhAB

      Setting the resize policy in your application's code

    Absolute positioning

    Aligning widgets using groups

     Joining widgets into a group

     Accessing widgets in a group

     Aligning widgets horizontally or vertically

     Aligning widgets in rows and columns

     Using the Group flags

     Splitting apart a group

    Constraint management using anchors

     Anchor resources

      Setting anchor flags in PhAB

      Setting anchor flags in your application's code

    Enforcing position or size constraints without anchors

Generating, Compiling, & Running Code

    Using the Build + Run dialog

    Generating application code

     What PhAB generates

     Version control

      Tips on using CVS

     Function prototypes

      Potential problems with generating proto.h

    How application files are organized

     Multiplatform applications

     Single-platform applications

     Converting to multiplatforms

    Editing source

     Choosing an editor or browser

     Creating a source module

     Changing the file display

    Compiling & linking

     Choosing the libraries

     Running make

      Modifying the make command

    Running the application

    Debugging

     Modifying the debugger command

    Including non-PhAB files in your application

     Multiplatform applications

     Single-platform applications

     Adding libraries

Working with Code

    Variables and manifests

     Widget variables and manifests

     Using the global variable and widget manifest

     Handling multiple instances of a window

     Internal link manifests

     Icon manifests

    Global header file

    Function names and filenames

    Initialization function

     Processing command-line options

    Module setup functions

    Code-callback functions

    Geometry data types

    Timers

     Using PtTimer

     RtTimer* functions

    Initializing menus

     Enabling, disabling, or toggling menu items

     Changing menu-item text

     Generating menu items

      Creating submenus

Manipulating Resources in Application Code

    Argument lists

    Setting resources

     Argument lists for setting resources

      Scalar and color resources

      String resources

      Alloc resources

      Image resources

      Array resources

      Flag resources

      Function resources

      Pointer resources

      Link resources

      Struct resources

      Boolean resources

     Calling PtSetResources

     Setting one resource

    Getting resources

     Not using pointers

      Scalar and flag resources (nonpointer method)

      String resources (nonpointer method)

      Boolean resources (nonpointer method)

     Using pointers

      Scalar and flag resources (pointer method)

      String resources (pointer method)

      Alloc resources (pointer method)

      Image resources (pointer method)

      Array resources (pointer method)

      Pointer resources (pointer method)

      Link resources (pointer method)

      Struct resources (pointer method)

      Boolean resources (pointer method)

     Calling PtGetResources

     Getting one resource

Creating Widgets in Application Code

    Creating widgets

    Ordering widgets

     Working in the widget family

    Manipulating callbacks in your code

     Adding callbacks

     Callback invocation

     Removing callbacks

     Examining callbacks

    Manipulating event handlers in your code

     Adding event handlers

     Removing event handlers

     Event handler invocation

Control Surfaces

    What's a control surface?

     Limitations

     Binding actions to control surfaces

     Referring to control surfaces

    Control-surface API

     Creating and destroying control surfaces

     Finding IDs for control surfaces

     Calculating geometry for control surfaces

     Drawing control surfaces

     Activating control surfaces

     Enabling and disabling control surfaces

     Finding control surfaces

     Hiding and showing control surfaces

     Ordering control surfaces

     Storing user data with control surfaces

    Example

Accessing PhAB Modules from Code

    Creating internal links

    Using internal links in your code

     Manifests

     Internal-link functions

     Example --- displaying a menu

    Using widget databases

     Creating a database

     Preattaching callbacks

     Assigning unique instance names

     Creating a dynamic database

     Widget-database functions

International Language Support

    Application design considerations

     Size of text-based widgets

     Justification

     Font height

     Hard-coded strings

     Use of @ in instance names

     Bilingual applications

     Common strings

    Generating a language database

    Message databases

    Language editor

     Starting the Language Editor within PhAB

     Starting the Language Editor as a stand-alone application

     Creating a new translation file

     Editing an existing translation file

     Translating the text

     Hotkeys

     Help resources

     Translation functions

    Running your application

    Distributing your application

Context-Sensitive Help

    Creating help text

     Help files

     Table-of-content files

    Referring to help topics

     Universal Resource Locator (URL)

     Topic path

    Connecting help to widgets

     Displaying help in the Helpviewer

     Displaying help in a balloon

     Help without the ? icon

    Accessing help from your code

Interprocess Communication

    Connections

     Creating a connector

     Setting up the connection object

     Messages

     Notifications

     Local connections

     Asynchronous client calls

     Naming conventions

     Example

    Sending QNX messages

    Receiving QNX messages

     Adding an input handler

      name_attach and PtAppAddInput

     Removing an input handler

     Message buffer size

     Example --- logging error messages

    Photon pulses

     Photon application that receives a pulse

      Creating a pulse

      Arming a pulse

      Sending the pulse message to the deliverer

      Registering an input handler

      Delivering a pulse to yourself

      Destroying a pulse

      Example --- message queues

     Photon application that delivers a pulse

    Processing signals

     Adding a signal-processing function

     Removing a signal-processing function

    Other I/O mechanisms

Lengthy Operations

    Threads

     Time-consuming work in a callback

     Why not just use a mutex?

     Realtime threads

     Flags to PtEnter and PtLeave

     Modal operations and threads

     Exiting

     Threads and work procedures

    Work procedures

    Modal dialogs

Raw Drawing and Animation

    PtRaw widget

     Raw drawing function

      Determining the raw widget canvas

      Translating coordinates

      Clipping

      Using damage tiles

      Using a model for more complex drawing

      Examples of simple PtRaw drawing functions

    Color

    Drawing attributes

     General attributes

     Text attributes

     Fill attributes

     Stroke (line) attributes

    Arcs, ellipses, polygons, and rectangles

     Rectangles

     Rounded rectangles

     Beveled boxes, rectangles, and arrows

     Polygons

      Overlapping polygons

     Arcs, circles, chords, and pies

     Spans --- complex shapes

    Lines, pixels, and pixel arrays

    Text

    Bitmaps

    Images

     Palette-based images

     Direct-color images

     Gradient-color images

     Creating images

     Caching images

     Transparency in images

      Using chroma

      Using a transparency mask

     Displaying images

     Manipulating images

     Releasing images

    Animation

     Creating a series of snapshots

      Using a widget database

      Using a file

     Cycling through the snapshots

     Flickerless animation

      PtOSContainer

      Memory-context functions

    Direct mode

     Example

    Video memory offscreen

    Alpha blending support

    Chroma key support

    Extended raster operations

    Video modes

    Gradients

     Driver-level gradients

     Application-level gradients

    Video overlay

     Example

Fonts

    Symbol metrics

    Font names

     Querying available fonts

     FontDetails structure

     Generating font names

     Example

    Writing text in a rectangular area

    Repairing damage to proportional text

Printing

    What's in a print context?

      Pp_PC_COLLATING_MODE

      Pp_PC_COLOR_MODE

      Pp_PC_CONTROL (read-only)

      Pp_PC_COPIES

      Pp_PC_DATE

      Pp_PC_DEVICE

      Pp_PC_DITHERING

      Pp_PC_DO_PREVIEW

      Pp_PC_DRIVER

      Pp_PC_DUPLEX

      Pp_PC_FILENAME

      Pp_PC_INKTYPE

      Pp_PC_INTENSITY

      Pp_PC_JOB_NAME

      Pp_PC_MARGINS

      Pp_PC_MAX_DEST_SIZE

      Pp_PC_NAME

      Pp_PC_NONPRINT_MARGINS

      Pp_PC_ORIENTATION

      Pp_PC_PAGE_NUM

      Pp_PC_PAGE_RANGE

      Pp_PC_PAPER_SIZE

      Pp_PC_PAPER_SOURCE

      Pp_PC_PAPER_TYPE

      Pp_PC_PREVIEW_APP

      Pp_PC_PRINTER_RESOLUTION

      Pp_PC_PROP_APP

      Pp_PC_REVERSED

      Pp_PC_SCALE

      Pp_PC_SOURCE_COLORS

      Pp_PC_SOURCE_OFFSET

      Pp_PC_SOURCE_RESOLUTION

      Pp_PC_SOURCE_SIZE

      Pp_PC_USER_ID (read-only)

    Creating a print context

    Modifying a print context

    Starting a print job

    Printing the desired widgets

     Printing a new page

     Printing widgets that scroll

      PtList

      PtMultiText

      PtScrollArea

    Suspending and resuming a print job

    Ending a print job

    Freeing the print context

    Example

Drag and Drop

    Transport mechanism

    Using drag and drop

     Starting drag and drop

      Example

     Receiving drag-and-drop events

      Source widget

      Destination widget

     Canceling drag and drop

    Registering new transport types

     A simple data structure

     A more complicated structure

      Clear-references list

      Endian list

      Fixup list

      Registry entry

     Transport functions

      Both applications

      Source application

      Destination application

Regions

    Photon coordinate space

    Region coordinates

     Region origins

     Initial dimensions and location

      Origin at (0,0) and initial rectangle at (0,0)

      Origin at (0,0) and initial rectangle not at (0,0)

      Origin not at (0,0) and initial rectangle not at (0,0)

     About child regions

    Regions and event clipping

    Placement and hierarchy

     Region hierarchy

     Parent region

     Brother regions

     Default placement

      Ph_FORCE_FRONT flag

     Specific placement

    Using regions

     Opening a region

     Placing regions

      Changing region placement

      Changing the parent

      Specifying brothers

    System information

Events

    Pointer events

      Pressing a button

      Releasing a button

      Multiple clicks

      Modifier keys

    Emitting events

     Targeting specific regions

      Inclusive event

      Direct event

     Targeting specific widgets

     Emitting key events

    Event coordinates

    Event handlers --- raw and filter callbacks

    Collecting events

    Event compression

    Dragging

     Initiating dragging

      Outline dragging

      Opaque dragging

     Handling drag events

      Outline dragging

      Opaque dragging

Window Management

    Window-management flags

     Window-rendering flags

     Window-managed flags

     Window-notify flags

    Notification callback

     Example: verifying window closure

    Getting and setting the window state

    Managing multiple windows

    Window-manager functions

    Running a standalone application

Programming Photon without PhAB

    Basic steps

    Compiling and linking a non-PhAB application

    Sample application

     What's going on

      PtInit

      PtCreateWidget --- first call

      PtSetArg

      PtCreateWidget --- second call

      PtRealizeWidget

      PtMainLoop

    Connecting application code to widgets

     Callbacks

     Event handling

    Complete sample application

Photon Architecture

    Event space

     Regions and events

    Events

     Initial rectangle set

     Collected rectangle set

    Regions

     Sensitivity

     Opacity

     Attribute summary

     Event logging

     Event modification

     Parent/child relationships

     Photon coordinate space

     Root region

    Event types

    How region owners are notified of events

     Polling

     Synchronous notification

     Asynchronous notification

    Device region

     Pointer focus

     Keyboard focus

     Drag events

     Drag-and-drop events

    Photon drivers

     Input drivers

      Mouse driver

      Keyboard driver

     Output drivers

      Graphics driver

      Multiple graphic drivers

      Drivers using separate regions

      Drivers using overlapping regions

      Encapsulation drivers

    Photon window manager

     Window-frame regions

     Focus region

     Workspace region

     Backdrop region

Widgets at a Glance

Unicode Multilingual Support

    Wide and multibyte characters

    Unicode

    UTF-8 encoding

    Other encodings

    Keyboard drivers

     Example: text widgets

     Dead keys and compose sequences

    Photon compose sequences

Photon in Embedded Systems

    Assumptions

    Introduction

      Steps to boot into Photon

    Step 1. Export the PHOTON_PATH environment variable

    Step 2. Start the Photon server

     Files needed

    Step 3. Start the input driver

     Files needed

    Step 4. Start the font manager

     Configuring Fonts

     Starting the font server

    Step 5. Switch into graphics mode

     Getting the card in the right mode

    Step 6. Start the graphics driver

     Files needed

    Step 7. Start the window manager

     Files needed

    Step 8. Start your application

     Files needed

    Caveats

     mkifs

     Flash filesystems

     Graphics

     Misc

    Example

     Required binaries

     Required libraries

     Required fonts

     Font servers

     Putting it all together

     Handy tips

Glossary