Working with Applications

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

• creating an application
• opening an existing application
• saving an application
• closing an application
• specifying application startup information

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

Creating an application

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. PhAB creates a new unnamed application that consists of a single main window, named base.

After creating an application, you should:

• save it, giving it a name
• use the Application Startup Information dialog to:
  • specify a global header file
  • specify an initialization function
  • enable or disable command-line options

A naming convention for all the widgets, modules, functions, and so on will make managing your application easier.

Opening an application

To open an existing application:

1. Choose Open from the File menu or press Ctrl -O . You'll see the application selector:

   ---

   

   ---

   Application Selector dialog.

2. If the application you want is in another directory, type the directory name in the Application Directory field, then press Enter.
3. To choose the application, do one of the following:
   • double-click on the application
   • click on the application, then press Enter or click on Open Application
   • type the application's name, then press Enter or click on Open Application

If the application has already been opened (whether by you or someone else), 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.

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, & Running Code chapter.

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, type the directory name in the Application Directory field, then press Enter.

   ---

   If you type a new directory name, it's saved. The next time you want to look in that directory, click on 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 on Save Application.

If you rename an application, you'll find that the name of the executable isn't changed. This is because PhAB doesn't change the Makefile. 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, & Running Code chapter.

Saving an existing application

To save an existing application, choose Save from the File menu or press Ctrl -S .

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 on the existing application
   • click on the existing application, then press Enter or click on Save Application

Closing an application

To close an application, choose Close from the File menu.

Specifying application startup information

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

• enable or disable command-line options
• define a global header
• define an initialization function
• include instance names in widgets
• define a mainloop function
• indicate whether or not proto.h is to be generated - see "Generating function prototypes" in the Generating, Compiling, & Running Code chapter
• define which windows appear when the application runs.

To open this dialog:

• Choose Startup Info/Modules from the Application menu.

  Or

• Press F2.

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

Application Startup Information dialog.

Once you've made your changes, click on Done.

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 Startup Info/Modules from the Application menu. You'll see the Application Startup Information 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 on 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 could initialize data, open widget databases, set up signal handlers, and so on. To set up an initialization function:

1. Press F2 or choose StartUp Info/Modules from the Application menu. You'll see the Application Startup Information 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 on 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.

Command-line options

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_number	//node_number/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 Application menu, choose Startup Info/Modules to open the Application Startup Information dialog.
2. To disable the size options, click on No Dim Arg. To disable the position options, click on No Pos Arg. To disable the state option, click on No State Arg.

Mainloop function

PhAB lets you take over the standard Photon mainloop function.

This option is provided for very advanced Photon developers, and requires an excellent understanding of how Photon processes events. It can also make your application incompatible with future versions of Photon. Don't use it unless absolutely necessary.

To specify an application-based mainloop function:

1. Press F2 or from the Application menu, choose Startup Info/Modules to open the Application Startup Information dialog.
2. In the Main Loop Function field, enter the name of your own mainloop function. PhAB will generate a mainline stub that contains the standard Photon mainline code; you can modify this code as needed.

Including instance names

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

1. Press F2 or from the Application menu, choose Startup Info/Modules to open the Application Startup Information dialog.
2. Click on the Include Names toggle button.

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

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

Startup windows

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.

Adding a startup window

To add a new window to the startup window list:

1. Press F2 or choose Startup Info/Modules from the Application menu. You'll see the Application Startup Information dialog.
2. Click on <NEW> and fill in the "Link to Window Module Info" fields. For example:

   

   To use these fields, see "Link to Window Module Info," below.

3. Click on Apply.

Modifying a startup window

To modify an existing startup window:

1. Select the window from the "Windows Opened/Startup" list.
2. Enter whatever changes are needed in the "Link to Window Module Info" fields (see below).
3. Click on Apply.

Deleting a startup window

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

Link to Window Module Info

To add or modify a startup window, you use the following controls:

Name

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

Location

Determines where the window will appear; see the "Location dialog" section in the Working with Modules chapter.

Setup Function

Specifies the function that will be called when the window is realized (optional). To edit the function, click on the icon next to this field.

Called

Determines whether the setup function is called before the window is realized, after the window is realized, or both.

Apply

Applies any changes.

Reset

Restores the window information to its original state.

Remove

Deletes the selected window from the startup list.