About This Guide

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

     Introduction

     PhAB's Environment

     Working with Applications

     Working with Modules

     Editing Resources and Callbacks in PhAB

     Generating, Compiling, & Running Code

     Working with Code

     Manipulating Resources in Application Code

     Creating Widgets in Application Code

     Accessing PhAB Modules from Code

     International Language Support

     Context-Sensitive Help

     Interprocess Communication and Lengthy Operations

     Raw Drawing and Animation

     Printing

     Regions

     Events

     Window Management

     Programming Photon without PhAB

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 border 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

     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

     What you'll learn

     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

     What you'll learn

     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

    Menubar

    Speedbar

     Detaching the speedbar

     Reattaching the speedbar

     Hiding the speedbar

    Widget bar

     Modes (create vs select)

      Determining the mode

      Switching to create mode

      Switching to select mode

     Customizing the widget bar

    Control Panel

     Resources mode

     Callbacks mode

     Module Tree mode

     Module Links mode

    Customizing your PhAB environment

     General preferences

     Color preferences

     Dragging preferences

    Help

    Exiting PhAB

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

     Mainloop function

     Including instance names

     Startup windows

      Adding a startup window

      Modifying a startup window

      Deleting a startup window

      Link to Window Module Info

Working with Modules

    Overview

     Modules as containers

     Module types

     Changing module resources

     Anatomy of a module

     How modules are saved

     Displaying modules at run time

    Using the module selector

    Creating a new module

    Viewing a module

    Opening a module

    Deleting a module

    Window modules

     Resizing a window module

    Dialog modules

     Resizing a dialog module

    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

     Naming the icon module

     Specifying sizes and instance names

    Other modules

     Resizing an other module

    Iconifying modules

     Rearranging icons

    Importing PhAB modules from other applications

    Importing QNX Windows picture files

    Closing a module

    Positioning a module

     Opening the location dialog

    Selecting a module

    Finding lost modules and icons

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 Panel

     Widgets within a group

      Selecting a single widget

      Selecting multiple widgets

     Hidden widgets

    Positioning widgets with a grid

    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

    Moving and resizing widgets with the nudge tool

    Clipboard

     Cutting and copying

     Pasting

     Viewing the clipboard

     Editing the clipboard

    Duplicating widgets and containers

    Deleting widgets

    Importing graphic files

Editing Resources and Callbacks in PhAB

    Editing widget resources

    Pixmap editor

     Setting the pixmap's size

     Choosing colors

      Choosing a background color

     How to draw and erase

     Drawing freehand

     Drawing lines, rectangles, and circles

     Filling an enclosed area

     Selecting an area

     Nudging an area

     Using the Pixmap Tools window

      Rotating an area

      Flipping an area

      Inserting or deleting a row or column

      Cutting, copying, and pasting

     Other pixmap controls

    Color editor

     Ensuring color consistency

    Flag/option editor

     Flag resources

     Option list resources

    Font editor

    List editor

     Editing existing list items

     Deleting list items

    Number editor

    Text editor

    Multiline text editor

    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

    Raw-event 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

    Multithreaded programs

    Initialization function

     Processing command-line options

    Mainloop function

    Module setup functions

    Code-callback 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 resources

      String resources

      Alloc resources

      Array resources

      Flag resources

      Pointer resources

      Link resources

      Struct resources

      Boolean resources

     Calling PtSetResources

    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)

      Array resources (pointer method)

      Pointer resources (pointer method)

      Link resources (pointer method)

      Struct resources (pointer method)

      Boolean resources (pointer method)

       Version 1.13 and earlier

       Version 1.14 and later

     Calling PtGetResources

Creating Widgets in Application Code

    Creating widgets

    Ordering widgets

     All 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

Accessing PhAB Modules from Code

    Creating internal links

    Using internal links in your code

     Manifests

     API

     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

    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

    Running your application

    Distributing your application

Context-Sensitive Help

    Creating help text

     Help files

     Table-of-content files

    Referring to help topics

    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 and Lengthy Operations

    Sending QNX messages

    Receiving QNX messages

     Adding an input handler

     Removing an input handler

     Message buffer size

     Example --- logging error messages

     Example --- replying to sin ver commands

    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

      Disarming a pulse

      Destroying a pulse

      Example

     Photon application that delivers a pulse

      Registering an input handler

      Delivering the pulse

      Example

     Non-Photon application that delivers a pulse

    Processing signals

     Adding a signal-processing function

     Removing a signal-processing function

    Other I/O mechanisms

    Lengthy operations

     Work procedures

     Timers

     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

    Arcs, ellipses, polygons, and rectangles

     Rectangles

     Rounded rectangles

     Beveled boxes

     Polygons

      Overlapping polygons

     Arcs, circles, chords, and pies

    Lines, pixels, and pixel arrays

    Text

    Bitmaps

    Images

     Palette-based images

     Direct-color images

     Gradient-color images

     Creating images

     Caching images

     Transparency in images

     Displaying images

     Releasing images

    Animation

     Creating a series of snapshots

      Using a widget database

      Using a file

     Cycling through the snapshots

     Flickerless animation

      PtDBContainer

      PmMem... functions

Fonts

    Font names

     Using PfQueryFonts

     FontDetails structure

     Example

Printing

    Overview

    What's in a print context?

     Pp_PC_CONTROL control structure

    Creating a print context

    Modifying a print context

     Calling PtPrintSelection

     Using the PtPrintSel widget

     Calling PpPrintSetPC

    Starting printing

    Drawing the desired widgets

     Printing by damaging widgets

     Printing by calling PpPrintWidget

     Printing a new page

     Printing scrolling widgets

      PtList

      PtMultiText

      PtScrollArea

    Suspending and resuming printing

    Closing printing

    Multiple print sessions

    Freeing the print context

    Example

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

    Emitting events

     Targeting specific regions

      Inclusive event

      Direct event

     Targeting specific widgets

     Emitting key events

    Event coordinates

    Collecting events

    Event compression

    Dragging

     Initiating dragging

      Outline dragging

      Opaque dragging

     Handling drag events

      Outline dragging

      Opaque dragging

Window Management

    Window-management flags

     Window render 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

     Linking under QNX 4

     Linking under QNX Neutrino

    Sample application

     What's going on

      PtAppInit

      PtSetArg

      PtCreateWidget

      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

    Photon drivers

     Input drivers

      Mouse driver

      Keyboard driver

     Output drivers

      Graphics driver

      Multiple graphic drivers

      Drivers using separate regions

      Drivers using overlapping regions

      Printer driver

      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

Glossary