Working with Modules

Modules are the major pieces of the user interface in a PhAB application. This chapter describes how to work with them, and includes:

• Overview of working with modules
• Using the module selector
• Creating a new module
• Viewing a module
• Opening a module
• Deleting a module
• Window modules
• Dialog modules
• Menu modules
• Picture modules
• Icon modules
• Other modules
• Iconifying modules
• Importing PhAB modules from other applications
• Importing QNX Windows picture files
• Closing a module
• Positioning a module
• Selecting a module
• Finding lost modules and icons

Overview

Modules as containers

Modules serve as containers to hold your application's widgets. Some modules, such as windows and dialogs, are actually Photon container-class widgets and let you place widgets directly inside them. Others, such as icons and menus, have either predefined widgets or a specialized editor for creating the widgets that they contain.

Module types

PhAB provides a number of types of modules, each with a specific usage. Each module type is identified as follows:

• If the module isn't iconified, look at the colored tab in the module's top-right corner.
• If a module is iconified, look at the small swatch of color displayed in the icon.
• When you generate your code, PhAB creates a file for each module. The extension identifies the type of module.

  ---

  These are all binary files. Don't edit them with a text editor or you could damage them.

  ---

Changing module resources

When you select a module within PhAB, the Control Panel changes to display the list of widget resources available for that module's class. Depending on which resources you change, you may see no immediate effect. All changes will take effect, however, when you run the application.

Because PhAB displays all modules as child windows within its work area, you can work with any number of modules at the same time.

Anatomy of a module

PhAB displays each module as a window in its work area. Like windows, modules have a set of controls in their frames.

Anatomy of a typical PhAB module.

Most modules include these elements:

• Work menu button-brings up the module's Work menu so you can iconify the module, move the module behind all other modules, or close the module.
• Title bar-displays the module's instance name. To move a module, point to this bar and drag the pointer.
• Test tab (some modules only)-lets you switch the module into test mode so you can interact with the widgets as you would when your application is running.
• Module-type tab-displays the module type. You'll find that each module type displays a different color in its tab. These colors are used throughout PhAB to make identifying modules easy. For more info, see "Module types" in this chapter.

Note that using the Work menu to close a module doesn't delete the module. It simply removes the module from the work area to give you more space to work with. To get the module back any time, use the module selector, which lets you access, create, and delete any type of module. For more info, see "Using the Module selector" in this chapter.

How modules are saved

When you save your application, PhAB stores all the application's modules as files within the application's wgt directory. Each module is saved in its own file with a file extension based on the module's type. Later, when you "make" your application, PhAB binds all the modules into the binary executable. This makes the application a single free-standing program that you can distribute easily.

For more info, see "How application files are organized" in the Generating, Compiling, & Running Code chapter.

Displaying modules at run time

Your application needs a way to make modules appear when you run it. You can:

• Create a widget that uses a callback to display the module. For example, you can create a PtButton with a module-type link callback that displays the module. For more information, see "Editing callbacks" in the Editing Resources and Callbacks in PhAB chapter.
• Use an internal link to create the module in your application's code. See the Accessing PhAB Modules from Code chapter.

Using the module selector

When you use the Application menu to create or view any of the six PhAB module types (windows, dialogs, menus, etc.), PhAB displays the module selector dialog:

Module Selector dialog.

At the top of the dialog you'll see a set of color-coded toggle buttons. These let you select which type of module you wish to create/open, delete or close. The default type is determined by the menu option you chose to bring up the dialog.

Creating a new module

To create any new module, follow these simple steps:

1. From the Application menu, choose the type of module you want to create. You'll see the module selector.
2. In the Name field, type the instance name of the new module, then press Enter or click on Open.

   ---

   Module names must not be longer than 48 characters.

   ---

3. PhAB asks whether it should create the new module. Press Enter or click on Yes. You'll see the new module in PhAB's work area.
4. Click on Done.

If you choose the "Others" module type, PhAB asks you to select the type of module you want. If you're creating an icon module for your application's main window, you should name the module Icon. This is the name the Photon Desktop Manager (PDM) uses to extract the icon for its quick-launch folders.

For more info on creating specific types of modules, see the sections on each type of module in this chapter.

Viewing a module

To see a sample view of any module:

1. From the Application menu, choose the type of module you want to view. You'll see the module selector.
2. Click on the module's name in the Modules scrolling list.

Opening a module

To display a module in your work area:

1. From the Application menu, choose the type of module you want to open. You'll see the module selector.
2. Do one of the following:
   • double-click on the module's name

     Or

   • click on the module's name, then press Enter or click on Open

     Or

   • type the module's name, then press Enter or click on Open

Deleting a module

To delete a module:

1. From the Application menu, choose the type of module you want to delete. You'll see the module selector.
2. Click on the module's name.
3. Click on the Delete button.

Deleting a module doesn't delete the module's file; it just removes the name from the list. Any callbacks belonging to the module or its children are deleted.

Window modules

Typically, you use window modules for your application's major activities. Since most applications use a window module for their main window, PhAB automatically generates a window module named base when you first create any application. It also presets the application's startup information to make the base window open when the application starts up. (See "Specifying application startup information" in the Working with Applications chapter.)

Window modules can support multiple instances. That is, two or more copies of the same window module can be displayed at the same time. As a result, you should keep track of each window's instance pointer, which is generated when you create the window. That way, you'll always know which window you're dealing with when you process callbacks. For more information, see "Handling multiple instances of a window" in the Working with Code chapter.

Even though your application's base window is a window module, you usually display it only once, at startup. So unless your application needs to display more than one copy of the base window at the same time you won't have to keep track of the base window's instance pointer.

For an example of code for handling multiple instances of window modules, see "Creating Windows" in the Tutorials chapter.

Resizing a window module

When you set a window module's size in PhAB, that's the size it will be when you run the application.

Dialog modules

Dialog modules let you obtain additional information from the user. Typically, you use this information to carry out a particular command or task.

Most dialog modules include the following buttons:

• Done-allows users to indicate that they've finished entering information
• Cancel or Close-allows users to close the dialog without responding

From PhAB's perspective, dialog modules are almost identical to window modules, with one important difference-a dialog module can have only one active instance. So if you invoke a dialog that's already open, the PhAB API simply brings the existing instance of the dialog to the front of the screen. This behavior fits with the nature of a dialog-you rarely want to get the same information twice. If for any reason you need a dialog that can support multiple instances, use a window module.

Limiting a dialog to a single instance makes callback handling simpler since you can use the widget manifests that PhAB generates to access the widgets within the dialog. For more info, see the discussion on instance names in the Creating Widgets in PhAB chapter.

Resizing a dialog module

When you set a dialog module's size in PhAB, that's the size it will be when you run the application.

Menu modules

A menu module provides a multilevel text-only menu. Unlike most other modules, a menu module doesn't let you create widgets directly inside it. Instead, you use PhAB's menu editor to create the menu's items.

Opening the menu editor

To open the menu editor:

1. Select a menu module.
2. Click on Menu Items in the Control Panel. PhAB displays the menu editor:

   ---

   

   ---

   Menu editor.

   In the upper-right corner you'll see buttons that represent the types of menu items you can create:

   • Command-invokes a PhAB callback.
   • Submenu-displays a child menu.
   • Separator-provides lines or spacing between other menu items.
   • Toggle-changes or displays an application state.
   • Function-specifies an application function that can dynamically add menu items to the menu.

At the bottom of the dialog are two buttons:

Specifying instance names

To create any command or toggle menu item (that is, any item that can invoke a callback), you must enter a unique instance name-PhAB enforces this. The instance name lets you access the menu item from within your application code.

When PhAB generates the code for your application, it generates an ABN_... global variable for each menu item that requires it. You use this variable with the menu-item related API functions, ApModifyItemState() and ApModifyItemText().

For example, let's say a menu item isn't available when the user clicks on the widget that brings up the menu. Using the instance name, you can dim that item before displaying the menu. For more information, see "Initializing menus" in the Working with Code chapter.

Creating hotkeys and shortcuts

To help the user select a menu item more quickly, you can:

• provide a keyboard shortcut that selects the item
• provide a hotkey that directly invokes the command that the item represents, even when the menu isn't visible

A keyboard shortcut works only when the menu is currently visible. A hotkey, on the other hand, should work whether the menu is visible or not.

Creating a keyboard shortcut is easy. When you're entering the Item Text, simply place "&" in front of the character that will act as the shortcut. For example, let's say you're creating a "Save As" item. You could enter Save &As, which will underline the "A." When the menu opens, the user can press either A or a to invoke the callback associated with "Save As".

Creating a hotkey takes a bit more work, but it's still easy to do. First, you want to make sure that the hotkey accelerator appears next to the menu item when the menu is displayed. To do this, use the Accel Text field. For example, let's say the hotkey accelerator for a "Save" menu item will be Ctrl -S . In that case, you would type Ctrl-S in the Accel Text field.

Next, you need to create a hotkey callback for Ctrl -S . Since the menu might not be created when the user presses Ctrl -S , you can't attach the hotkey callback to the menu or to the menu item. Rather, you must attach the callback to the application's main module, which is usually the base window module. When you specify the hotkey callback's function, use the same function you defined for the menu item's callback.

If for some reason you need to differentiate between the two methods of invoking the callback, look at the callback's reason code. Hotkeys always have a reason code of Pt_CB_HOTKEY.

For more info on creating hotkey callbacks, see "Hotkey callbacks" in the Editing Resources and Callbacks in PhAB chapter.

Resizing a menu module

Feel free to resize a menu module to make it more readable or take up less space. When you run the application, the actual size of the PtMenu widget will be determined by the menu items.

Creating command items

A command item lets you invoke application code or display a module.

To create a command item:

1. Click on <NEW>.
2. Click on the Command button in the upper-right corner.
3. In the Item Text field, enter the item's text. To create a shortcut key, place "&" in front of the character that will act as the shortcut.

   For example, let's say you enter &File. In that case, the user can select the item by pressing F.

4. In the Inst Name field, enter the instance name you'll use.
5. If you plan to have a hotkey callback for this item, enter the hotkey string (for example, Ctrl-S) in the Accel Text field. This string will appear in the menu as a reminder to the user.
6. Add a PhAB callback by clicking on the Callback icon:

   

   For more info on creating a callback, see "Editing callbacks" in the Editing Resources and Callbacks in PhAB chapter.

7. Click on Apply to add the item to the menu.

Creating submenu items

A submenu item lets you create another menu level.

To create a submenu item:

1. Click on <NEW>.
2. Click on the Submenu button in the upper-right corner.
3. In the Item Text field, type the name of the submenu. To create a keyboard shortcut, place "&" in front of the character that will act as the shortcut (just like command items, above).
4. Click on Apply.
5. You can now add items to the submenu. At the top of the Menu Items list you'll see the Level control:

   

   Click on the down arrow, then add the submenu items you want. You can add any type of menu item to a submenu, including another submenu item.

Creating separator items

A separator item lets you create spacings between menu items. You'll find this item type handy for creating logical groupings of menu items. You can choose from several separator styles.

To create a menu separator:

1. Click on <NEW>.
2. Click on the Separator button in the upper-right corner. You'll see a list of separator styles:

   ---

   

   ---

   Styles of menu separators.

3. Click on the separator style you want, then click on Apply.

Creating toggle items

A toggle item lets you change or display an application state, which can be either on or off.

To create a toggle item:

1. Click on <NEW>, then click on the Toggle button.
2. Follow the same procedure used to create command items.

Creating function items

A function item lets you specify an application function that dynamically adds menu items to the menu at runtime. For example, you could use a function item in a File menu to display the last three files the user worked on.

The PhAB library invokes the specified function as the menu is built. The dynamically created menu items appear where you've positioned the function item in the menu.

To create a function item:

1. Click on <NEW>, then click on the Function button.
2. In the Function field, enter the name of the application function that will dynamically add menu items to the menu.

   If you specify this function name, PhAB will generate 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. You can edit the function right away by clicking on the button to the right of the function name.
4. Click on Apply.

For information on the application function, see "Generating menu items" in the Working with Code chapter.

Moving menu items

The Menu Items scrolling list lets you move a menu item to a new position in the menu.

Let's say you want to move an item named Browse so it appears just before an item named Edit. You would:

1. Drag the Browse item until its outline is directly over Edit.
2. Release the mouse button. The Browse item appears in its new position.

Using a menu module

Once you've created a menu module, you need a way to make your application display it. Typically, you do the following:

1. Create a PtMenuBar widget at the top of a window.
2. Add a PtMenuButton widget to the menu bar, giving it an appropriate instance name and text string.
3. Add a module-link callback to the menu button's Pt_CB_ARM callback list.

   ---

   You could add the callback to the Pt_CB_ACTIVATE list, but adding it to Pt_CB_ARM allows the user to access it in two ways: by pressing the left mouse button on the menu button widget, dragging to highlight a menu item, and releasing to select it. This is known as the press-drag-release (PDR) method. by clicking on the menu, and then clicking on a menu item If you use an Activate callback, the user can only use the second method.

   ---

4. Have the callback display the menu module. See "Module callbacks" in the Editing Resources and Callbacks in PhAB chapter.
5. If you need to initialize the menu whenever it's displayed, specify a setup function for it. See "Initializing menus" in the Working with Code chapter.

If you want your menu to appear when you press the right mouse button while pointing at a widget, you'll need to use an internal link. For more information, see the Accessing PhAB Modules from Code chapter - there's even an example.

Picture modules

Using a picture module, you can change the contents of an existing module or create a convenient database of widgets. You always display a picture inside a container-class widget or another module, such as a window or dialog.

Like windows, picture modules support multiple instances. So you should keep track of the instance pointer of the container that each picture is placed into. That way, you'll always know which picture you're dealing with when you process callbacks.

If you're sure that your application will use only one instance of the picture at any given point, you don't have to keep track of instance pointers. Instead, you can use PhAB-generated manifests to access the picture's widgets.

Displaying a picture

You always access picture modules from within your application code. To access a picture, you must create an internal link to it. This tells PhAB to generate a manifest that you can use with PhAB's API functions-such as ApCreateModule()-to access the picture.

For more info, see "Using internal links to create and access modules" in the Accessing PhAB Modules from Code chapter.

Using pictures as widget databases

You can use a picture module as a widget database. A widget database contains predefined widgets that you can copy at any time into a window, dialog, or container.

When using a widget database, you don't have worry about handling multiple instances since the generated PhAB widget manifests don't apply to widget databases: each widget you create is a new instance. The instance pointer is returned to you when you create the widget using ApCreateWidget(). You'll need to keep track of this pointer manually if you need to access the widget in the future.

For more info, see "Widget databases" in the Accessing PhAB Modules from Code chapter.

Resizing a picture module

It doesn't matter how large or small you make a picture module. That's because it has no associated widget class. Only the widgets inside the module are used.

Icon modules

Icon modules let you design your application's icons. PhAB ensures that these icons are automatically supported by Photon's Desktop and Window Managers.

Icon modules consist of two icon widgets:

• a large one for the Photon Desktop Manager (PDM) quick-launch folders
• a small one for the Photon Window Manager (PWM) taskbar

PhAB automatically supplies samples of these icons when you create the module. At any point, you can use PhAB's pixmap editor, described in the Editing Resources and Callbacks in PhAB chapter, to redraw these samples into something more appropriate for your application. You can even use the pixmap editor to import an existing graphic.

Feel free to resize an icon module as you wish-it isn't used to display the icons.

Naming the icon module

When you create your application's icon module, remember to specify Icon as the module's name. Then, open the base window's Window Icon (Pt_ARG_ICON_WINDOW) resource and specify Icon there as well. This ties the icon module to the application's base window module and makes it possible for PDM to find the icon.

Specifying sizes and instance names

The widgets in an icon module can be of any class, but they must have the following sizes and instance names:

The two sample icon widgets that PhAB provides are PtLabel-class widgets with the Label Type resource set to Pt_IMAGE. These icons are prenamed and presized to match the specification. Unless you have a specific icon requirement, we recommend you use these samples and edit them with the pixmap editor.

When you view the icon module using the Module Tree mode of the Control Panel, LIcon must come before SIcon for Photon to find the icons properly.

Other modules

Other modules are predefined modules that PhAB provides for specific purposes. Currently, you can choose from the following types:

• file selector-to allow the user to open and save files (class = AwFileSelect)
• message-to provide a text-based message, with optional buttons, in a popup window (class = AwMessage)

Since each of these modules is predefined, you can't add any widgets. Nevertheless, you can edit several resources provided for the module itself. Note, however, that changing a resource has no immediate visual effect. That's because the displayed module shows either a sample of the widget class it represents or its current list of resources. If you want to see the effects of any change, run the application.

We strongly recommend that you not use these modules. Instead, use the PtFileSel and PtMessage widgets (see the Photon Widget Reference) or PtFileSelection(), and PtAskQuestion() or PtMessageBox() (see the Photon Library Reference).

Resizing an "other" module

Feel free to resize these modules to take up less space in PhAB. They'll appear in a predefined size when you run your application.

Iconifying modules

PhAB's work area lets you work on several application modules at once. You can iconify modules to organize your work area. The icons are color-coded so you can identify what kind of module each icon represents. See "Module types" in this chapter.

To reduce any module in the work area to an icon:

• double-click on the module's Work menu button (upper-left corner of the module)

  Or

• click on the Work menu button and choose Minimize

Once it's iconified, the module positions itself at the bottom of the work area. You can drag it anywhere in the work area, so (for example) you can group commonly used or related icons.

Rearranging icons

To automatically rearrange module icons into neat rows starting at the bottom-left corner, choose Arrange Icons from the Window menu.

Importing PhAB modules from other applications

To import a PhAB module from another application:

1. Choose Import Files from the File menu, then choose PhAB Module from the Import Files submenu. You'll see a file selector.
2. The file selector may display several modules. To identify the module you want by its file extension, see "Module types" in this chapter.
3. To select the module, do one of the following:
   • double-click on the module
   • click on the module, then press Enter or click on Open
   • type the module's name, then press Enter or click on Open

Callbacks aren't imported, only the module and the widgets themselves. After importing the module, you can attach new application-specific callbacks. 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 QNX Windows picture files

To import a QNX Windows picture (.pict) file:

1. Choose Import Files from the File menu, then choose QNX Windows Picture File from the Import Files submenu. You'll see a file selector.
2. Choose the picture file. You'll be asked to choose the type of module you want to import the picture file into:

   Window

   main base window picture

   Dialog

   popup window picture

   Picture

   database picture (that is, QNX Window links), or pictures that replace other pictures

QNX Windows window files (.wnd) can't be imported, as they have no equivalent in Photon. Only picture files (.pict) can be imported. Not all QNX Windows elements are supported. Photon doesn't currently have a Meter, Dial or Number widget, so the importer converts Numbers into PtText widgets, and ignores Meters and Dials. Not all QNX Windows format options are supported.

Closing a module

If you wish to stop working on a module and remove it from the work area:

1. Click on the module's Work menu button (upper-left corner of the module).
2. Choose the Close item.

   If you simply wish to iconify the module, choose the Minimize item.

To reopen any module that's been closed, see the "Module selector" section in this chapter.

Positioning a module

You can specify where a module will display when you create a link callback from a widget to that module. To do this, you use the location dialog.

Opening the location dialog

To open the Location dialog and select a module's location:

1. When creating or editing a link callback to a module, click on the Location field or on the icon to the right of the field. You'll see a list of locations:

   ---

   

   ---

   Location dialog.

   For windows and dialogs, the default location is Default (0,0), which places the window at the next available position defined by the Window Manager. The default location for a menu module is Below Widget.

2. Click on the location you want.
3. You can also specify x and y offsets. For example, if you set the location to the bottom-right corner and set the x offset to -100, the window will be displayed so that its bottom-right corner is 100 pixels to the left of the bottom-right corner of the screen.

   ---

   If you choose Default as the location, the offsets are ignored.

   ---

4. Click on Done.

Selecting a module

To select a module that's in the PhAB work area:

• Click on the module's titlebar.

  Or

• If the module is iconified, double-click on its icon.

  Or

• Bring up the Window menu and choose the module by name (this works for both iconified and noniconified modules).

Whichever method you choose, you'll see resize handles that indicate the module is selected.

For information on opening a module that's not currently in PhAB's work area, see "Opening a module" in this chapter.

Finding lost modules and icons

To find a lost module or icon:

• Choose Arrange Modules from the Window menu. PhAB cascades all open modules and pulls the Control Panel back into the PhAB work area.
• Choose Arrange Icons from the Window menu. PhAB rearranges all existing icons along the bottom of the work area.

If the above techniques don't work, you may have "closed" the module. (PhAB lets you close a module to remove it from your work area and reduce clutter.) To find how to reopen a closed module, see "Opening a module" in this chapter.