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

Developing Photon Applications

In this chapter:

What is PhAB?

The Photon microGUI includes a powerful development tool called PhAB (Photon Application Builder), a visual design tool that generates the underlying C/C++ code to implement your program's UI.

With PhAB, you can dramatically reduce the amount of programming required to build a Photon application. You can save time not only in writing the UI portion of your code, but also in debugging and testing. PhAB helps you get your applications to market sooner and with more professional results.

PhAB lets you rapidly prototype your applications. You simply select widgets, arrange them as you like, specify their behavior, and interact with them as you design your interface.

PhAB's opening screen looks like this:

PhAB screen shot

Photon Application Builder.

PhAB and the IDE

The IDE frequently runs command-line tools such as gdb and mkefs “behind the scenes,” but PhAB and the IDE are separate applications; each runs in its own window. You can create files, generate code snippets, edit callbacks, test your UI components, etc. in PhAB, while you continue to use the IDE to manage your project as well as debug your code, run diagnostics, etc.

PhAB was originally designed to run under the Photon microGUI on a QNX Neutrino host, but the phindows (“Photon in Windows”) utility lets you run PhAB on a Windows host as well. The IDE lets you see, debug, and interact with your target Photon application right from your host machine as if you were sitting in front of your target machine.

Using PhAB

In most respects, using PhAB inside the IDE is the same as running PhAB as a standalone application.

Note: For a full description of PhAB's functionality, see the Photon Programmer's Guide.

Creating a QNX Photon Appbuilder project

In order to use PhAB with the IDE, you must create a QNX Photon Appbuilder project to contain your code. This type of project contains tags and other information that let you run PhAB from within the IDE.

To create a PhAB Project:

  1. From the workbench menu, select File-->New-->Project….
  2. In the list, expand QNX.
  3. Select Photon Appbuilder Project, and then click Next.
  4. Name your project. If you don't want to use the default location for the project, specify a different one.
  5. Click Next.
  6. Select your target architecture.

    Note: If you wish to set any other options for this project, click the remaining tabs and fill in the fields. For details on the tabs in this wizard, see “New C/C++ Project wizard tabs” in the Common Wizards Reference chapter.

  7. Click Finish.

    The IDE creates your project, then launches PhAB. (In Windows, the IDE also creates a Console for PhAB window.)

Closing PhAB

To end a PhAB session, do one of the following:

Reopening PhAB

To reopen your QNX Photon Appbuilder project, select it in the C/C++ Projects view, open the Project menu, and then click Open Appbuilder.

Editing code

You can edit the code in your QNX Photon Appbuilder project using both PhAB and the IDE. Using PhAB, you can control the widgets and the overall layout of your program; using either PhAB or the IDE, you can edit the code that PhAB generates and specify the behavior of your callbacks.

To use PhAB to edit the code in a QNX Photon Appbuilder project:

  1. In the C/C++ Projects view, select a QNX Photon Appbuilder project.
  2. Click the Open Appbuilder button in the toolbar (Icon: PhAB). PhAB starts, then opens your project.

Note: If for some reason the Open Appbuilder button isn't in the C/C++ perspective's toolbar:
  1. From the main menu, select Window-->Customize Perspective.
  2. Select the Commands tab.
  3. Check Photon Appbuilder Actions.
  4. Click OK. The Open Appbuilder button appears in the toolbar.

To use the IDE to edit the code in a QNX Photon Appbuilder project:
In the C/C++ Projects view, double-click the file you want to edit. The file opens in an editor.

If a file that you created with PhAB doesn't appear in the C/C++ Projects view, right-click your project and select Refresh.

Note: Editing files using two applications can increase the risk of accidentally overwriting your changes. To minimize this risk, close the file in one application before editing the file in the other.

Building a QNX Photon Appbuilder project

You build a QNX Photon Appbuilder project in exactly the same way as other projects. (For information on building projects, see the “Building projects” section in the Developing C/C++ Programs chapter.)

To build a QNX Photon Appbuilder project:
In the C/C++ Projects view, right-click your QNX Photon Appbuilder project and select Build. The IDE builds your project.

Importing an existing standalone QNX Photon Appbuilder project

If you have an application written in the standalone version of QNX Photon Appbuilder, you can import it into an empty IDE-based PhAB project. Once the project is imported, you can edit the source and build the project in the IDE. To import a standalone PhAB project:

  1. Open the project in standalone PhAB and make sure it uses an Eclipse Project directory structure. To do this, select Project-->Convert to Eclipse Project.

    Note: If this option is grayed out, the project already uses an Eclipse Project directory structure.

  2. Save the project.
  3. Run the IDE and create a new Photon Appbuilder Project. This will run PhAB automatically, but for now cancel and exit out of PhAB. This creates a new, empty PhAB project in your workspace.
  4. Select File-->Import…, and choose File system to import resources from the local filesystem. Browse to the project saved earlier by standalone PhAB, and import the following items:
  5. At this point you can rebuild the project using the IDE, and launch PhAB from the IDE to edit the project.

Checking out an existing PhAB project from CVS

To check out an existing PhAB project from CVS:

  1. Select an import source from CVS-->Projects.
  2. Click Next.
  3. In the Checkout Project from CVS Repository window, select an existing repository location, or create a new location.

    If you choose an existing location, select Use existing repository location.

  4. Click Next.
  5. In the Select Module window, enter a module name, or choose an existing module by selecting Use an existing module, and then browse the modules in the repository.
  6. Click Next.
  7. In the Check Out As window, select Check out as a project in the workspace.
  8. Click Next.
  9. In the Check Out As window, if not already checked, select Use default workspace location.
  10. Click Next.
  11. In the Select tag window, click Finish.

Note: If you check a project out from CVS by using the New Project wizard, and you choose only one CPU with both debug and release versions, then when the wizard is done, the debug variant is always unchecked for SH, PPC, and x86. In addition, while the project is being checked out, a message shows indicating “The file has been changed on the file system, do you want to load the changes?”, but it doesn't indicate which file was changed.

Starting Photon applications

You can connect to a Photon session from a Windows or QNX Neutrino host machine and run your Photon program as if you were sitting in front of the target machine. Photon appears in a phindows window on your Windows host or in a phditto window on your QNX Neutrino host.

The remote Photon session runs independently of your host. For example, the clipboards don't interact, and you can't drag-and-drop files between the two machines. The phindows and phditto utilities transmit your mouse and keyboard input to Photon and show the resulting state of your Photon session as a bitmap on your host machine.

Before you run a remote Photon session on a Windows host, you must first prepare your target machine. For details, see the “Connecting with Phindows” section in the Preparing Your Target chapter.

To start a remote Photon session:
In the Target Navigator view, right-click a target and select Launch Remote Photon.

Photon appears in a Phindows window.

You can start a Photon application you created in PhAB in exactly the same way that you launch any other program in the IDE. By default, the program opens in the target machine's main Photon session. (For more on launching, see the Launch Configurations Reference chapter in this guide.)

To run your Photon program in a remote Photon session window:

  1. In the remote Photon session, open a command window (e.g. a terminal from the shelf).
  2. In the command window, enter:
    echo $PHOTON


    The target returns the session, such as /dev/ph1470499. The number after ph is the process ID (PID).

  3. In the IDE, edit the launch configuration for your QNX Photon Appbuilder project.
  4. Select the Arguments tab.
  5. In the C/C++ Program Arguments field, enter -s followed by the value of $PHOTON. For example, enter -s /dev/ph1470499.
  6. Click Apply, then Run or Debug. Your remote Photon program opens in the phindows or phditto window on your host machine.

    Note: If you close and reopen a remote Photon session, you must update your launch configuration to reflect the new PID of the new session.