PhAB's Environment

This chapter describes PhAB's environment in more detail, and how you can customize it.

It includes:

Menus
Toolbars
Control panels
Widget palette
Resources panel
Callbacks panel
Module Tree panel
Module Links panel
Search panel
Customizing your PhAB environment
Grid preferences

Menus

Across the top of PhAB's workspace you'll see the following menubar:

PhAB's menubar.

The menus include:

File
Edit
View
Options
Application
Window
Help

File menu

Commands that deal with your application and its files:

New: Create a new application; see "Creating an application" in the Working with Applications chapter.
Open: Open an existing application; see "Opening an application" in the Working with Applications chapter. This command is also available through PhAB's toolbars.
Save Save As: Save the current application, under the same or a different name; see "Saving an application" in the Working with Applications chapter. The Save command is also available through PhAB's toolbars.
Close: Close the current application; see "Closing an application" in the Working with Applications chapter.
Import Files: Import files created by other applications; see "Importing PhAB modules from other applications" in the Working with Applications chapter.
Exit: End your current PhAB session. PhAB prompts you if there are any changes that you haven't yet saved.

This menu also lists the last few applications that you edited.

Edit menu

Commands for editing widgets:

Undo Redo

Undo and redo an operation, including:

creating, deleting, moving, resizing, aligning, and selecting a widget
changing the order of widgets
selecting an area
creating, deleting, opening, closing, and iconifying a module
changing a callback resource -- PhAB can't undo/redo any changes you make to a callback function's code
pasting
joining and splitting a group
editing a resource
importing images, XBMs, and modules.

Cut Copy Paste

Delete and copy widgets to the clipboard, and paste them from it; see "Clipboard" in the Creating Widgets in PhAB chapter.

Transfer

Move a widget from one container to another; see "Transferring widgets between containers" in the Creating Widgets in PhAB chapter.

Delete

Delete a widget without saving it on the clipboard; see "Deleting widgets" in the Creating Widgets in PhAB chapter.

To Front To Back

Move the selected widgets to the front or back of the widgets in the container; see "Ordering widgets" in the Creating Widgets in PhAB chapter.

Group Together Split Apart

Combine selected widgets into a group, or break up a selected group; see "Aligning widgets using groups" in the Geometry Management chapter.

Alignment

Align the selected widgets; see "Aligning widgets" in the Creating Widgets in PhAB chapter.

Change Class

Change the class of the selected widgets; see "Changing a widget's class" in the Creating Widgets in PhAB chapter.

Save as template Edit Templates

A template is a customized widget that you want to use as the basis for other widgets. These commands let you create or edit a template; see "Templates" in the Creating Widgets in PhAB chapter.

Many of these commands also appear in PhAB's toolbars.

View menu

Commands that display PhAB's optional windows:

Clipboard: The destination of widgets when you cut or copy them; see "Clipboard" in the Creating Widgets in PhAB chapter.
Resources Callbacks Module Tree Module Links Search Panel: Control panels for editing resources, callbacks, and so on; see "Control panels."

At the end of the View menu is a list of palettes, including the Widget palette and any templates you've created; see "Control panels."

Options menu

Commands that display dialogs for specifying options:

Preferences: PhAB preferences, such as colors, editing commands, and styles of resource names.
Grid: An optional grid that can be used to position widgets.
Generate Report: Generate a report on the application's widgets and modules.

For more information, see "Customizing your PhAB environment."

Application menu

Commands dealing with the application as a whole:

Startup Info/Modules: Information used for the application as a whole, including global headers, initialization function, and which modules to display at startup. For more information, see "Specifying application startup information" in the Working with Applications chapter.
Languages: A menu of commands used to create multilingual versions of your application; see the International Language Support chapter.
Windows Dialogs Menus Pictures Icons: Dialogs that list the modules in your application and let you create new ones. For more information, see the Working with Modules chapter.
Internal Links: An internal link is a PhAB mechanism that lets you access a PhAB module directly from your application's code; see the Accessing PhAB Modules from Code chapter.
Build + Run: The "control center" for compiling and running your application; see the Generating, Compiling, and Running Code chapter.
Generate: Generate the code for your application; see the Generating, Compiling, and Running Code chapter.
Convert to Multiplatform: This command is useful only for old applications that were generated under version 4 of the QNX OS for a single target platform. For more information, see the Generating, Compiling, and Running Code chapter.

Window menu

Commands that manipulate PhAB's windows:

Arrange Modules: Arrange your application's modules so that they're stacked from the upper left to lower right in PhAB's workspace.
Arrange Icons: Arrange the iconified modules in PhAB's workspace so that they're arranged alphabetically in rows.

This menu also lists all the modules in your application. Selecting one of these menu items restores the module if it's minimized, and selects the module.

Help menu

Get online help information:

Welcome to PhAB Tutorials PhAB Concepts Tools + Techniques: Links to the appropriate section of this programmer's guide.
PhAB Library API: A link to the Photon Library Reference.
About PhAB: The version number and copyright information for PhAB.

There are other forms of help available in PhAB:

Context-sensitive help -- To get help on a part of PhAB's user interface, click on the question mark button, then click on the item in question. The Helpviewer displays the information on the selected item.
Balloon help -- To find out what a button in the widget palette or toolbars is for, pause the pointer over it. A descriptive balloon appears.

Toolbars

The toolbars give you quick access to frequently used commands from the menu bar:

PhAB toolbars

PhAB's toolbars.

Open

Open an existing application; see "Opening an application" in the Working with Applications chapter. This command is also available through the File menu.

Save

Save the current application; see "Saving an application" in the Working with Applications chapter. The Save command is also available through the File menu.

Print

Not implemented.

Cut Copy Paste

Delete and copy widgets to the clipboard, and paste them from it; see "Clipboard" in the Creating Widgets in PhAB chapter. These commands are also available through the Edit menu.

Group Split

Combine selected widgets into a group, or break up a selected group; see "Aligning widgets using groups" in the Geometry Management chapter. These commands are also available through the Edit menu.

Move Into

Move a widget from one container to another; see "Transferring widgets between containers" in the Creating Widgets in PhAB chapter. This command corresponds to the Transfer command in the Edit menu.

Test

Switch to test mode so you can interact with the widgets as you would when your application is running.

You can also use a module's Work menu or Test button to switch into and out of test mode. For more information, see "Anatomy of a module" in the Working with Modules chapter.

Raise Lower To Front To Back

Move the selected widgets forward or backward in, or to the front or back of the widgets in the container; see "Ordering widgets" in the Creating Widgets in PhAB chapter. The To Front and To Back commands are also available through the Edit menu.

Align

The most frequently used commands for aligning the selected widgets; see "Aligning widgets" in the Creating Widgets in PhAB chapter. For more choices of alignment, see the Alignment item in the Edit menu.

X Y W H

The coordinates and size of the currently selected widget. To change them, type the new values and press Enter.

To avoid changing a coordinate or dimension for the current widget, lock it by clicking on the padlock so that it closes. You can't change the field (either by typing or dragging) until you unlock it. The locks are saved with your application.

Nudge tool

This tool lets you move, expand, or shrink a widget. Click on the button for the desired mode, and then click on the frame buttons above:

Nudge tool components

The nudge tool's components.

Every click on the frame buttons nudges, stretches, or shrinks the selected widget by one pixel. To nudge by multiple pixels, hold down the mouse button.

You can also use the Ctrl key and the numeric keypad to nudge, stretch, or shrink a widget. Each key corresponds to one of the nudge buttons. Pressing Ctrl -5 switches between modes, and Ctrl -/\ works like the tool's top frame button.

Control panels

PhAB includes a set of control panels that display information about the currently selected widget or widgets. They're displayed by default in PhAB, and you can move them anywhere you like. If you close a control panel, you can reopen it by choosing the appropriate item from the View menu.

The control panels include:

Widget palette
Resources panel
Callbacks panel
Module Tree panel
Module Links panel
Search panel

They're described in the sections that follow.

The control panels are originally displayed as a stack in a PtPanelGroup widget. If you click on the panel tab, a menu of the panels appears. If you expand the window enough, all the tabs are displayed in a line.

You can drag panels away from this group to customize the display. If you drop it on the background of PhAB's work area, it becomes a new panel group. If you drop it on another panel group, the panel joins that group. You're then free to resize the panel groups are you see fit. Depending on your choices in the AppBuilder Preferences Settings dialog, the arrangement of panels is saved with your application or for all your PhAB sessions.

Widget palette

The widget palette lets you add widgets to your application.

PhAB widget palette

PhAB's widget palette.

If you close this panel, you can reopen it by choosing Widgets from the View menu.

The widgets are arranged and color-coded by type. The names are optional; to hide or display them, right-click on the palette and choose the appropriate item from the pop-up menu.

To find out what widget a button represents if the widget names aren't displayed:

Pause the pointer over it until a help balloon pops up.
Or
See the Widgets at a Glance appendix.

For information on using specific widget classes, see the Photon Widget Reference.

Modes (create vs select)

The widget palette has two modes:

Select mode: Lets you select existing widgets and modules in the work area.
Create mode: Lets you create new widgets.

Determining the mode

To find out which mode you're in:

Look at the widget palette -- If an icon button is pushed in, you're in create mode.
Look at the pointer -- If the pointer is a single-headed arrow when you move it into the work area, you're in select mode. If the pointer is anything else, you're in create mode.

Switching to create mode

To switch to create mode, click on any widget icon in the widget palette. You can now create one or more instances of that widget. For more information, see "Creating a widget" in the Creating Widgets in PhAB chapter.

Switching to select mode

To switch from create mode to select mode, do one of the following:

Click on the background of PhAB's work area.
Or:
Click the right mouse button in a module.
Or:
Click on the selected widget in the widget palette.

By default, PhAB returns to select mode as soon as you've created a widget.

Resources panel

The Resources panel displays a list of resources for the selected widget or widgets. (If more than one widget is selected, this panel displays only the resources they have in common.) Here's an example:

Resources mode

The Resources panel.

If you close this panel, you can reopen it by choosing Resources from the View menu.

It includes the following:

Widget class: The class of the selected widget.
Next and previous buttons: Let you navigate sequentially through widgets in the current module. These buttons also let you select multiple widgets or select widgets within a group. For more info, see the "Selecting widgets" section in the Creating Widgets in PhAB chapter.
Instance name: Lets you enter a unique instance name for the widget. For more information, see "Instance names" in the Creating Widgets in PhAB chapter.

You can change the value of a resource right in the control panel, or you can use the full-featured editor by clicking on the resource name. For more information, see the Editing Resources and Callbacks in PhAB chapter.

By default, the Resources and Callbacks control panels display resource labels descriptively. If you pause the pointer over a resource, the header manifest is displayed in a popup balloon.

To have the labels displayed as the actual header manifests (convenient when writing code), open the Preferences dialog and change the setting in the Resource Names field. To open this dialog, choose the Preferences item from the Options menu. Now if you pause the pointer over a resource, the popup balloon displays the descriptive label.

The control panel doesn't display all the resources for a widget. PhAB sets Pt_ARG_AREA, Pt_ARG_DIM, Pt_ARG_EXTENT, and Pt_ARG_POS automatically when you move or resize a widget. Some other resources are too complex to edit in PhAB.

Callbacks panel

The Callbacks panel displays a list of callback resources for the selected widget. You can use this panel only when you've selected a single widget. The widget must have a unique instance name. Here's an example:

Callbacks panel

The Callbacks panel.

If you close this panel, you can reopen it by choosing Callbacks from the View menu.

This panel, like the Resources panel, displays the widget class and instance names, and the next and previous buttons.

The left side of the list indicates the callback type. The right side displays:

"None" if there are no callbacks
the callback type and name if there's one callback
the number of callbacks if there's more than one.

To create a callback or to edit an existing one, click on the appropriate resource (for example, Pt_CB_ACTIVATE).

Module Tree panel

The Module Tree panel displays a hierarchical tree of the widgets in the current module. Here's an example:

Module Tree panel

The Module Tree panel.

If you close this panel, you can reopen it by choosing Module Tree from the View menu.

This panel makes it easy to:

See the parent/child relationships of the module's widgets.
Select a widget inside a group.
Find a widget by name.
Select a widget hidden underneath another widget.

To select a widget from the tree, click on the widget's name.

If you right-click on this panel, a menu appears:

Module Tree panel

The menu for the Module Tree panel.

Module Links panel

The Module Links panel displays a list of all link callbacks both to and from the current module. As you can see from the following example, the callbacks are displayed in a two-line format:

Module Links panel

The Module Links panel.

To do this:	Click on the:
Select a widget	Instance name (e.g. `base_file`) in line 1
Edit a widget callback	Appropriate callback type (e.g. Arm) in line 2

If you close this panel, you can reopen it by choosing Module Links from the View menu.

Search panel

The Search panel lets you search your application for widgets of a specified type, name, text resource, and so on.

Search panel

The Search panel.

If you close this panel, you can reopen it by choosing Search Panel from the View menu.

Just choose the category you want to find from the combo box and specify the pattern (which is case-sensitive) as appropriate:

Widget Name: In the text field, type the exact name of the widget or a regular expression. For example, a value of my_button* matches all the widgets whose names begin with my_button.
Widget Type: Type a class name or a regular expression (e.g. PtScroll*), or use the combobox to select a widget class.
Widget Text: Type specific text or a regular expression to look for in the widgets' text resources.
Callback Type: Search for the widgets that have attached a callback of the type (Code, Done, and so on) selected from the pattern combo box.
Callback Function Name: Type a function name or a regular expression.
Callback Module Name: Type a module name or a regular expression. All the widgets that have a callback pointing to a module whose name matches the pattern are selected.

Next, press the Go button. The matching widgets are displayed in a list. Select entries from the list to select the actual widgets; the PhAB modules they're in are opened or made visible.

Customizing your PhAB environment

To customize PhAB to your preferences:

Choose Preferences from the Options menu. You'll see the Preference Settings dialog:

Setting PhAB preferences.
Click on the button that represents the kind of settings you wish to change: General, Colors, or Dragging.
When you're finished, click on Done.

General preferences

You can set the following general preferences:

Workspace: Lets you decide whether to save your preferences on a per-application or per-user basis, or not at all.
Resource Names: By default, the Resources and Callbacks panels display resource labels descriptively. This field lets you display the labels as the actual header manifests, which you may find helpful when writing code. Note, however, that manifests are long and take up more screen space.
If you pause the pointer over a resource, the label not displayed in the control panel is displayed in a popup balloon.
Icon Descriptions: By default, when you leave the pointer on any icon, descriptive text pops up in a balloon. To disable this feature, click on None.
Edit Command: Lets you specify the editor to use with the Build + Run dialog.
View Command: Lets you specify the file viewer to use with the Build + Run dialog.
Print Command: Lets you specify the print command used to print a selected file (in the Build + Run dialog, for example).
Debug Command: Lets you specify the command used to debug your application in the Build + Run dialog.
Automatically save: Whether or not to save the application automatically, and how often.
Warnings on exiting: Whether or not to warn you when you exit PhAB without generating or saving your application.

Color preferences

You can set the following color preferences:

Resize Handle Non-Resizable Handle: If you choose a window background that makes it difficult to see resize handles, use these options to customize the color. (If you select a widget and the resize handles appear in the nonresize color, the widget can't be resized.)

Dragging preferences

You can set the following dragging preferences:

Widget Module: Drag widgets and modules as outlines rather than as full objects.
Drag Damping Factor: The amount you must drag a widget or module before it moves. This factor helps avoid the annoyance of moving a widget when you really mean to select it.

Grid preferences

You can use a grid to position and size widgets. To change the grid, choose Grid from the Options menu. The following dialog appears:

Grid Settings dialog

Grid Settings dialog.

This dialog lets you:

Snap the position of new widgets to the grid.
Make the grid visible.
Choose the color of the grid.
Specify the origin and spacing of the grid.

Grid settings remain for the current session only. They aren't saved.