Working with Applications

This chapter describes working with an application as a whole in PhAB.

• Creating an application
• Opening an application
• Saving an application
• Closing an application
• Specifying your project properties
• Importing files

For information on running an application, see the Generating, Compiling, and Running Code chapter.

Creating an application

The way you create a new application depends on whether you're using PhAB from the IDE or standalone.

From the IDE:

To create a new PhAB project, see “Creating a QNX Photon Appbuilder project” in the Developing Photon Applications chapter of the IDE User's Guide. When you create a new project, the IDE opens PhAB, and you see the New Window Style dialog where you can select the type of base window for your application.

Standalone PhAB:

To create a new application, choose New from the File menu or press Ctrl-N. If you're already working on an application, PhAB asks if you want to save any changes to that application before closing it.

Choosing a main window style

PhAB creates a new unnamed application that consists of a single main window named base. PhAB displays a dialog where you must choose the style of the base window:

Choosing the style of the base window.

After creating an application, you should:

• if you're using standalone PhAB, save it, giving it a name
• use the Project Properties dialog to:
  • specify a global header file
  • specify an initialization function
  • enable or disable command-line options
  • specify an icon for your application
  • specify your startup window, and other startup options

---

You should develop a naming convention for all the widgets, modules, functions, and so on. This will make managing your application easier.

---

Opening an application

The way you open an existing application depends on whether you're using PhAB in the IDE or standalone.

From the IDE

To open an existing PhAB project, see “Reopening PhAB” in the Developing Photon Applications chapter of the IDE User's Guide.

Standalone PhAB

To open an existing application, choose Open from the File menu, press Ctrl-O, or choose Open from PhAB's toolbar:

The Open button on PhAB's toolbar.

You'll see the application selector:

Application Selector dialog.

If the application you want is in another directory, type the directory name in the Application Directory field, then press Enter, or browse to the directory. To enter a directory, double-click it. To go one level up in the directory structure, click the up arrow directory in the top-right corner of the dialog, or double-click the .. folder in the file list.

To choose the application, do one of the following:

• Double-click the application.

  Or:

• Click the application, then press Enter or click Open Application.

  Or:

• Type the application's name, then press Enter or click Open Application.

---

If someone already has the application open, PhAB won't open it unless you started PhAB with the -n option. If you're using NFS or SMB, you should start PhAB with the -n option because you can't lock files with either. For more information, see appbuilder in the QNX Neutrino Utilities Reference.

---

Saving an application

You can save your application in several ways, as described in the sections below.

---

To ensure the latest changes to your application are in effect, PhAB automatically saves your application whenever you regenerate or make your application code.

---

For information on using version-control software with PhAB applications, see “Version control” in the Generating, Compiling, and Running Code chapter.

How you save your application depends on whether you're running PhAB from the IDE or standalone.

From the IDE

When you run PhAB from the IDE, all file management is handled by the IDE. However, you can save the PhAB portion of the project by choosing Save from the File menu in PhAB. For information on managing projects in the IDE, see Developing C/C++ Programs in the IDE User's Guide.

From standalone PhAB

Naming or renaming an application

To save a new unnamed application or to save an application under another name or in a different directory:

1. Choose Save As from the File menu. You'll see the application selector dialog.

   

2. The dialog lists the contents of a directory. If you want to save your application in another directory, browse to the desired directory, or type the directory name in the Application Directory field and press Enter.

   ---

   If you type a new directory name, it's saved. The next time you want to look in that directory, click the button to the right of the directory field and select the directory from the list.

   ---

3. Type the name of the application in the Application Name field.
4. Press Enter or click Save Application.

---

If you rename an application, you'll find that the name of the executable is also renamed if the project is an Eclipse-style project. However, if it's an older-style project, the application name isn't changed. This is because PhAB doesn't change the Makefile. In this case, to change the name of the executable: Edit the Makefile manually and change every occurrence of the executable's name. Or: If you haven't changed the Makefile since it was first generated, delete it and regenerate the application. See the Generating, Compiling, and Running Code chapter.

---

Saving an existing application

To save an existing application, choose Save from the File menu, press Ctrl-S, or select the Save button on PhAB's toolbar:

The Save button on PhAB's toolbar.

Overwriting an existing application

To overwrite an existing application:

1. Choose Save As from the File menu.
2. Do one of the following:
   • Double-click the existing application.

     Or:

   • Click the existing application, then press Enter or click Save Application.

Closing an application

When using PhAB from the IDE:

1. Close PhAB first using Exit from the File menu.
2. Close the project in the IDE.

To close an application in standalone PhAB, choose Close from the File menu. If you've made any changes but haven't saved your application, PhAB asks if you want to save it.

Specifying project properties

The Project Properties dialog lets you set up the typical operations that are performed when an application starts. You can:

• define startup windows and other initialization features
• set various project generation options
• define run options, such as command line arguments and language
• define build and debug options

To open this dialog:

• Choose Project Properties from the Project menu.

  Or

• Press F2.

Here's the dialog, with some sample information filled in:

The Project Properties dialog.

Once you've made your changes, click Done.

Startup Windows tab

Here's the Startup Windows tab, with some sample information filled in:

The Project Properties dialog—Startup Windows tab.

You can use this tab to define:

• a startup window
• a global header
• an initialization function.

Define a startup window

When you first create an application, the mandatory base window is preset as the initial and only startup window. Using the Application Startup Information dialog, you can tell your application to:

• use another window as the initial startup window
• display several windows at startup
• use no startup windows.

The window that appears first in the Windows Opened/Startup list is the initial startup window:

• It's the first window to be displayed.
• It acts as the default parent window for all other windows and dialogs.
• Closing it causes the application to end.

Typically, the application's main window is the first created.

For each window in the startup list, you can specify information that's identical to the information used to create a module-type link callback, as described in the Editing Resources and Callbacks in PhAB chapter.

The information for each window includes:

Window Name

The name of the window module. To select from a list of existing windows, click the icon next to this field. If you specify the name of a module that doesn't exist, PhAB asks whether it should create that module.

Window Location

Where the window will appear; see “Positioning a module” in the Working with Modules chapter.

Setup Function

The function that's called when the window is realized (optional). To edit the function, click the icon next to this field.

The buttons below the function name determine whether the setup function is called before the window is realized, after the window is realized, or both.

Apply

Applies any changes.

Revert

Restores the window information to its original state.

Remove

Deletes the selected window from the startup list.

Adding a startup window

To add a new window to the startup window list, click <NEW>, fill in the window information, and click Apply.

Modifying a startup window

To modify an existing startup window, select the window from the “Windows Opened/Startup” list, enter whatever changes are needed in the window information fields, and then click Apply.

Deleting a startup window

To delete an existing startup window, select the window from the “Windows Opened/Startup” list and click Remove.

Specifying a global header file

Most applications have a global header that's included in all source code files. If you plan to use a global header in your application, you should set up the header before PhAB generates any code. This lets PhAB automatically include the header in each file it generates.

To set up a global header:

1. Press F2 or choose Properties from the Project menu. You'll see the Project Properties dialog.
2. In the Global Header field, type the name of the header file you plan to use. You don't have to include the .h extension.

   For example, to set up a globals.h header file, you can simply enter: globals

3. To edit the header immediately, click the icon next to the Global Header field. You can edit the header only if you've named the application by saving it. The format of the header file is discussed in the Working with Code chapter.

---

If you specify the header after some code has been generated, you'll have to go back and manually add the header to the stub files that were previously generated.

---

Initialization function

Your application can include an initialization function that's called before any modules or widgets are created. In it you can initialize data, open widget databases, set up signal handlers, and so on. To set up an initialization function:

1. Press F2 or choose Properties from the Project menu. You'll see the Project Properties dialog.
2. In the Initialization Function field, type the name of the initialization function.

   When you specify a setup function, PhAB generates a stub function; for information on specifying the language (C or C++) and the filename, see “Function names and filenames” in the Working with Code chapter.

3. To edit the function immediately, click the icon next to the Initialization Function field. You can edit the function only if you've named the application by saving it. The prototype of this function is discussed in the Working with Code chapter.

Generate Options tab

The Generate Options tab lets you:

• set window arguments
• include instance names.

Here's an example of this tab:

Build and Debug Options tab of the Project Properties dialog.

By default, all PhAB-generated applications have the following command-line options:

-h height[%]

The height of the window, in pixels, or as a percentage of the screen height if % is specified.

-s server_name

The name of the Photon server:

If server_name is:	This server is used:
node_path	node_path/dev/photon
fullpath	fullpath
relative_path	/dev/relative_path

-w width[%]

The width of the window, in pixels, or as a percentage of the screen width if % is specified.

-x position[%][r]

The x coordinate of the upper-left corner of the window, in pixels, or as a percentage of screen width if % is specified. If r is specified, the coordinate is relative to the current console.

-y position[%][r]

The y coordinate of the upper-left corner of the window, in pixels, or as a percentage of screen height if % is specified. If r is specified, the coordinate is relative to the current console.

-Si|m|n

The initial state of the main window (iconified, maximized, or normal).

By default, all these options are enabled so that users can dynamically move or resize the application, or specify its initial state. For example, to start an application in console 4 (the center of the workspace), specify the command-line options:

-x100% -y100%

The PhAB API processes these options before it calls the initialization function; if you plan to add your own command-line options to an application, make sure you pick options that don't conflict with these. You should also code your option processing to handle and ignore these options. If you don't, you'll see errors on the console when you run the application. See the discussion on the initialization function in the Working with Code chapter.

If you don't want users to move or resize the application:

1. Press F2 or from the Project menu, choose Properties to open the Project Properties dialog.
2. Select the Generate Options tab.
3. Unset the toggle buttons for these options as required:
   • Enable Window State Arguments
   • Enable Window Dimension Arguments
   • Enable Window Position Arguments.

Other Generate options

You can set project-generation options for storing widget instance names, generating proto.h, and generating release-quality code.

Store Names for ApInstanceName()

PhAB converts your widgets' instance names into ABN_... manifests that you can use in your code to refer to your widgets by name. Check this option to include the instance-name text string in the widgets' memory.

---

Including instance names increases the amount of memory required to run your application.

---

Use ApInstanceName() to find this string for a widget—see the Photon Library Reference for more information.

Scan source files for prototypes

Indicates whether or not proto.h is to be generated — see “Generating function prototypes” in the Generating, Compiling, and Running Code chapter.

Generate release quality code

When your application has passed the development/debuging cycle and is ready for release, you can turn on this option and rebuild your executable. This will build an executable that requires less memory to run. The memory savings depend on the number of named widgets you have in your application, as PhAB optimizes the compiled code by turning ABN_ constants into macros.

Run options

Here's an example of the Run Options tab:

Run Options tab on the Project Properties dialog.

Use the Run Options tab to specify:

Run Arguments

Command line arguments used when PhAB runs your application

Language

The language PhAB uses when it runs your application

Project Large Icon
Project Small Icon

The large and small icons used for your project. Click the icon or the edit button to edit the icon in the pixmap editor. See the pixmap editor,as described in the Editing Resources and Callbacks in PhAB chapter.

Build and Debug options

This tab of the Project Properties dialog lets you specify options related to the build and debug process. Here is an example of this tab:

Build and Debug Options tab of the Project Properties dialog.

Build version

Set to Release to generate the executable without debug information, or Debug if you plan to debug your application.

Link Libraries

Use to specify additional libraries to be used when your application is linked. The -l is optional.

You can't specify link options in this field, except for the -B option, which specifies static or dynamic linking. For example, you could enter: -Bstatic -lphexlib -Bdynamic.

An exception to this rule is pre-6.3 projects which are not yet converted using Project-->Convert to Eclipse Project. Those projects require the -l option, and take any linker command in this field.

---

The content of Link Libraries is saved in the indLfiles file and is included in the Makefile in the target directory.

---

Make command

Use to specify the command to build your application. The default is “make”.

Debug Command

Use to specify the command to debug your application. The default is “pterm gdb”, which launches a gdb session inside a new terminal window.

Targets

Use to select one or more targets for the current application. When you select Build or Rebuild All from the Build menu, only the selected targets are built. To add or delete targets, click Manage Targets.

Importing files

PhAB lets you import several types of files by using the Import Files item in the file menu:

• PhAB modules
• XBM Header File
• Graphics image files

The steps are the same for all types:

1. Choose Import Files from the File menu, then choose the appropriate type from the Import Files submenu. You'll see a file selector.
2. The file selector displays the available files of the specified type in the current directory.
3. To select a file, do one of the following:
   • double-click the file
   • click the file, then press Enter or click Open
   • type the file's name, then press Enter or click Open

Importing PhAB modules from other applications

When importing a PhAB module from another application, the file selector may display several modules. Each type of module has a different file extension; see “Module types” in the Working with Modules chapter.

---

Callbacks aren't imported, only the module and the widgets themselves. After importing the module, you can attach new application-specific callbacks. You can copy and paste widgets or modules between two phab sessions in order to preserve the callbacks (you have to make sure the Clipboard Operations: Save/Restore callbacks option is set in the Preferences dialog). Or you can save the modules or widgets as templates, and choose to save the callbacks with the templates. Normally, PhAB retains the instance name of each imported widget. However, if it detects a duplicate name, it changes that name to the widget-class name to avoid code-generation errors.

---

Importing XBM images

You can import X bitmap (XBM) files using the Import menu item. XBM image data is mostly found in header files (with a .h file extension) and in separate XBM bitmap files (with no file extension). To import an XBM image, use the Import menu item to open the header file containing the image data.

Importing graphics images

When importing graphics images, the file selector displays all files with the following extensions:

• .bmp
• .gif
• .jpg
• .pcx

PhAB imports the graphic as a PtLabel into the currently selected module, and sets the widget's Pt_ARG_LABEL_TYPE resource to Pt_IMAGE. If you wish to edit the imported image, use the pixmap editor, as described in the Editing Resources and Callbacks in PhAB chapter.

Exporting files

You can export the code used to create a module. To do this, select File-->Export. A fragment of C code that creates the widgets in the currently selected module is written to the home directory in a file called module.code.