Using the Editors


Chapter 25 . Menu Bar Editor

With Panther's menu bar editor, you can create menus with pulldowns and submenus and attach them to your screens as menu bars. You can optionally specify items in a menu bar to appear simultaneously on a toolbar. Menus can also be invoked as popups from a screen or field, or as external submenus used by other menus at runtime.

After you define a menu, you can attach it to a screen or widget through its Properties window in the screen editor. Alternatively, you can load and install a menu at runtime through Panther's library functions. The library functions also let you change a menu's runtime behavior and appearance.

This chapter shows how to create menus with the menu bar editor. For information about Panther's menu system and runtime options, refer to Chapter 15, "Including Menus and Toolbars," in Application Development Guide.


Starting the Menu Bar Editor

How to Invoke the Menu Bar Editor

Do any one of the following:

To invoke the menu bar editor and open a specific menu file, use this command:

mbedit [menuFile]

menuFile must be a binary menu file, either created with the menu bar editor or converted from an ASCII menu script with m2asc. If you specify a file in an open library, the menu bar editor opens it; otherwise, it opens with a new untitled menu:

Figure 25-1 The menu bar editor workspace, with the editor menu, toolbar, a new untitled menu, and the menu item's Properties window.

The menu bar editor workspace contains up to six components:

Editor menu bar
The menu bar editor has its own menu bar with five pulldown menus: File, Edit, View, Windows, and Help. Use these menus to open and create menus and libraries, save menu files in libraries, connect to the middleware, maintain menu files under source control, add or remove items from the menu you are creating, and manipulate the workspace.

Editor toolbar
The menu bar editor has its own toolbar with buttons that execute often-used operations such as Open, Save, Cut, and Paste.

Design window
The design window is the area in which you build menus. The window title shows the file in which the menu is stored—in the case of a new unsaved menu, Untitled. You can edit only one menu bar at a time.

When you are in edit mode, a menu appears in its popup format—that is, the top-level menu items are displayed vertically. Test mode shows the menu in its menu bar format.

Item Properties window
The Item Properties window allows access to different sets of properties, according to the item's type. Some properties are valid for most items: the item type, its label, and so on. Other properties are dependent on the type you specify for the item.

This window automatically opens when you start the menu bar editor. You can close and open it through ViewItem Properties.

Menu Properties window
The Menu Properties window displays the properties set for the current menu. Each menu in the menu file—for example, the main menu and its submenus—has its own set of properties.

You can open and close this window through ViewMenu Properties.

Menu List window
The Menu List window lists all menus that are defined in the current file. Refer to "Using the Menu List Window" on page 25-17 for a detailed discussion of this window.

Creating Menus

When you enter the menu bar editor, it displays a new untitled menu.

How to Create A New Menu

  1. Choose FileNew (or the New button on the toolbar).
  2. The menu bar editor displays a new menu with an end-of-menu marker (>).
  3. In the Label property, enter the text of the first menu label and select which type of menu item it is.

How to Insert New Menu Items

  1. Select the item that is to be under the new item. To place an item at the bottom of the menu, select the end-of-menu marker (>).
  2. Choose EditInsert. The editor places the new item above the previous selection with the label UNTITLED.

Creating Submenus

A menu item can invoke a submenu if its Type property is set to Submenu. Items in a submenu can themselves invoke other submenus.

When you set a menu item's type to Submenu, the menu bar editor displays a submenu indicator (->) on the item; it also creates an empty menu—named and incrementally numbered (Submenu_1, Submenu_2, and so on)—and sets this name in the Submenu property of the parent item. You can accept this name or change it. If you enter a name that is currently undefined in this file, the newly created menu is assigned this name.

After you create a Submenu item, you can define its submenu in one of three ways:

How to Attach An Existing Menu

Set the item's Submenu property. The property is set through a combo box, whose drop-down menu contains the names of all menus defined in the current file. Select one of these menus or enter the name directly; Panther attaches it to the submenu item.

How to Edit The New Menu

Add items to the newly created submenu; select the submenu item and either click on it or press right arrow. An empty menu displays to the right and below the parent item. Edit this menu by inserting items and changing their properties.

Figure 25-2 After the File menu item is defined as a Submenu item type, the editor attaches a new empty submenu to it.

How to Specify An External Menu

Set the Submenu property to the name of a menu that is not defined in the current file. At runtime, Panther assumes that an undefined submenu is an external menu and searches for it among all menu files that are loaded into memory. This option is useful for invoking the same submenu in different menus, for example, a generic Edit menu.


Menu Properties

Menus have their own properties, some of which apply to the menu, while others set default values for new items in that menu.

The following menu properties apply to menu items; refer to "Item Properties" for their descriptions:

Accelerator
Show Accelerator
Separator Style
Indicator State
Accelerator Active
Active

The following properties identify the menu and define its behavior:

Menu Name
The name of this menu, up to 252 characters. If you rename a menu, Panther posts a warning message that this menu might be referenced by other items' Submenu property and asks for confirmation. Panther leaves references to the previous name unchanged; either change each reference to the new name, or make sure that the reference is resolved at runtime as an external menu.

Menu Title
A title to display with the menu when displayed as a popup.

Tear-Off
A check box that specifies whether to allow users to tear this menu off, valid only for Motif.

Note: Menu properties are accessible at runtime through Panther library functions. For more information on these, refer to Chapter 15, "Including Menus and Toolbars," in Application Development Guide.


Item Properties

All menu items have a set of properties. Some of these are valid for all menu items; others are type-specific. At runtime, you can use Panther library functions to access menu item properties. For more information, refer to "Changing Menus at Runtime" in Application Development Guide.

Label
Enter the text of this menu item. Labels can contain up to 255 characters. You can specify any letter within the label text as the item's mnemonic by prefixing that letter with an ampersand (&)—for example, Fi&le and &Open. Users can select the menu item from the keyboard by typing this character. To include an ampersand character in the label, precede it with another ampersand.

You can specify a label for all item types except separators and those types whose labels are system-defined—for example, Edit or Cut.

Note: Motif only receives the character of the mnemonic, not its position, and underlines the first occurrence of that character. For example, Col&or will underline the first occurrence of the letter o in Motif applications.

Type
Choose the item type that determines this item's purpose—for example, whether it invokes an action, a submenu, or acts as a separator. Refer to "Item Types" for descriptions of menu item types.

Name
Enter the name of this menu item, up to 255 characters.

Ctrl
For action and toggle items, enter a control string that specifies the action that occurs when this item is selected.

Accel
For action and toggle items, optionally enter an accelerator string. This string specifies the keyboard equivalent for selecting this menu item and has the following syntax:
keyboard-modifier -key

where keyboard-modifier can be Ctrl or Alt, and key can be any alphanumeric or Panther function key—for example, Ctrl-P or Alt-PF1

Accelerator keys for edit-type items such as Edit Cut or Edit Paste are set by the GUI platform—for example, in Windows, through the Panther initialization file; on Motif, in the Panther file. To change edit item accelerators, modify the appropriate GUI file.

If you specify an accelerator string, two check box subproperties become available:

Indicator
Use this check box to set a toggle item's initial state to on. This property is valid only for toggle item types.

Menu
Use this check box to display the item in the menu bar. Set this property to off in order to omit this item from the menu bar's initial display—for example, if you want the item to appear only in the toolbar, or display the item programmatically only in certain contexts.

Toolbar
Use this check box to display the item in one of the toolbars. This property is valid only for action, toggle, and edit item types.

If you set this property, all toolbar subproperties become available:

Is Help
Use this check box to display the item as the rightmost item on the menu bar. You can specify this display option for only one menu item and only if it appears on a menu bar. To designate another item as the help item, first set the previous help item's Is Help property to No; otherwise, Panther posts an error message.

The position of the corresponding toolbar item is unaffected by this property.

Note: Panther always shows the help item in its correct position during test mode. When you exit test mode, Panther automatically repositions the help item as the last item.

Active
Use this check box to allow or disallow user access to the menu item. If unchecked, the menu item is initially greyed out; nothing happens when users click on the item.

Submenu
Identify the menu to display when users select this item. This property displays only for submenu item types.

The drop-down menu of this property's combo box lists the menus that are defined in the current file. Choose one to use an existing menu. To define a new menu or specify an external menu, enter its name. In either case,

Panther creates an empty menu. You can add items to this menu or leave it empty.

Note: If you leave a menu empty, Panther discards it when you save. At runtime, Panther assumes that the referenced menu exists in another file and looks for it accordingly.

Separator
Choose the style used by a separator item. This property displays only for separator item types. Choose a style from the option menu. For more information, refer to "Separator Styles."

Status Text
Enter the text to display on the screen's status line when this item has focus. On Motif, inactive items cannot get focus and therefore display no status line text.

Help Screen
Enter the name of a Panther screen to invoke as a help screen.

Ext Help Tag
Enter a help context identifier that specifies the help to invoke from an external help program.

Memo Text
Enter a string expression. You can use the contents of this field programmatically.

TM Class
Enter a transaction manager property. Refer to "Setting Classes for Menu Items and Push Buttons" for valid arguments.

Item Types

A menu item's type determines the action that occurs when users select the item. Each type is described in the following sections.

Separator
Draws a separator between the previous and next menu items, according to the specified separator style. Refer to "Separator Styles" for descriptions of different separator display options.

Action
Invokes an action through a control string.

Toggle
Changes an item's state through a control string and indicates whether the state is on or off with a toggle indicator. If the item is included on the toolbar, Panther uses the item's Armed Pixmap and Active Pixmap properties to show its on and off states.

You set the indicator's initial state through the item's Indicator State property. The indicator's state can be determined and reset through sm_mnitem_get and sm_mnitem_change, respectively. Refer to "Changing the State of Toggle Items" in Application Development Guide for details on controlling the item's state at runtime.

In character mode, toggle items reserve a single space to the left of a label for the toggle indicator. To change the mark character for character mode applications—typically an X or check mark—assign a new value to MARKCHAR in the video file.

Motif ignores this setting for top-level items in a menu bar.

The menu items under View on the screen editor's menu bar are all toggle items. For example, when the Widget List is open, the menu item indicates that it is on, or open. When the item is toggled, the Widget List window closes.

Submenu
Specifies that this menu item invokes another menu. You enter the name of the menu name in the Submenu property.

Windows Ops
Invokes the platform-specific windows submenu:

Windows List
Lists all accessible windows, with the last-opened window listed first. When users select a screen from this menu, Panther brings it to the top of the display. Windows applications omit this listing from popup menus.

Edit Types

The menu bar editor provides standard editing types for menu items. These item types are valid only on GUI platforms:

Edit Cut
Cuts selected text to the clipboard.

Edit Copy
Copies selected text to the clipboard.

Edit Paste
Pastes the clipboard contents.

Edit Delete
Deletes the selected text.

Edit Sel All
Selects the current widget's contents.

Edit Clear
Replaces the selected text with blank spaces.

The following restrictions apply to edit item types:

Separator Styles

You can separate menu items with separator items—that is, items whose Item Type property is set to Separator. You can specify the display characteristics of the separator item by setting the Separator Style property to one of these values:

Single
Double
Double Dashed
Etched In
Etched Out
Dashed
Etched In Dashed
Etched Out Dashed
None

In character-based applications, single and double can use characters defined in the video file. If no definition exists in the video file, Panther uses its own default values: _ and = for vertical menus, | and || for horizontal menus.

On GUI platforms, each GUI determines which separator options are valid and how to display them. For information about GUI display of menu separator styles, refer to Table 45-10 in Application Development Guide.


Displaying Pictures on Toolbar Items

The menu item Properties window contains properties that let you specify the name of a pixmapped or bitmapped image to display on a toolbar item:

Windows
Windows controls display of toolbars. Panther Windows applications support three pixmap states: Active, Inactive, and Hot. For Armed Pixmaps, Windows uses the pixmap specified in the Active Pixmap property. For Inactive Pixmaps, if inactive pixmaps are not specified for any of the toolbar items, a grayed version of the Active Pixmap property is used.

For each toolbar state that you want to indicate in your application—active, inactive and hot—you must supply a pixmap for each toolbar item.

Motif
If you leave the Armed Pixmap or Inactive Pixmap properties blank, Motif uses the Active Pixmap image to display the push button in its armed (pressed) and inactive states. If the Active Pixmap property is blank, the menu item text is displayed.

Image Size

Under Motif, bitmaps and pixmaps display at the size at which they were created. If you use different-sized images for an item's active, armed, and inactive states, Motif uses the largest of the three for the item's frame. In Windows, bitmapped images need to be the same size. Panther uses a size of 16 x 15 pixels.

Image File Types

Panther supports several file formats for pixmap properties. Table 25-1 shows which file types are valid on each platform:

Table 25-1 Supported file formats for pixmap properties.

File format File extension Windows Motif

Windows bitmap

.bmp

l

l

Motif bitmap

.xbm

l

Motif pixmaps

.xpm

l

Graphics Interchange Format

.gif

l

l

Joint Photographic Experts Group

.jpg

.jpeg

l

l

Portable Network Graphics

.png

l

l

Filename Extensions

Pixmap properties can optionally contain filename extensions. To facilitate portability and provide maximum flexibility, you can omit the filename extension.

If you omit the file extension, Panther searches for files in all open libraries using all possible image extensions supported on the local platform.

Keep the extension if you have multiple images that use the same name but different types. For example, dog.bmp might be a bitmapped image while dog.jpg is a photograph. In this case, include the extension to ensure that the correct image displays at runtime.

Note: Under Windows, if you compile the image into your resource-definition file, the resource id must match the pixmap property setting exactly.

Panther looks for the file according to the following platform-specific search procedures:


Using the Menu List Window

The Menu List window lists the names of all menus defined in the current file. It provides a hierarchical view of the menu in outline form, where the topmost menu is the first entry, and its submenus are listed directly below it:

Figure 25-3 Hierarchical listing of menus defined in a menu file. The last menu is flush left and outside the hierarchy, indicating that it is unused.

The Menu List window also lists all menus that are defined in the current file but are unattached to a submenu item type. These names appear flush left at the bottom of the window. Unused menus are always accessible for later usage, either through the editor or at runtime through Panther library functions. For information about runtime menu installation, refer to the library function sm_menu_install in the Programming Guide.

Three push buttons let you create and delete menus, and manipulate the menu hierarchy:

New
Creates a menu and adds its name to the group of unused menus. You can attach this menu to a submenu item and add items to it.

Delete
Removes the selected menu's definition from the menu file. If the deleted menu has submenus nested within it, they join the group of unused menus.

Top Menu
Moves the selected menu to the top of the menu hierarchy; all of its submenus move up with it. Parent and sibling menus in the previous hierarchy join the list of unused menus.

Testing Menus

You can test a menu and its toolbar in one of two ways:


Saving Menus

The menu bar editor has two save options available on the File menu:

Save
Saves the menu (in binary format) to its source file in a library. If the menu is new, the Save As Library Member dialog box opens where you can provide a name and specify a library. If no changes occurred since the last save, this menu item is greyed out.

Save As
Opens the Save As Library Member dialog box where you can save the menu (in binary format) with a new name to a different library. This menu becomes the current one for this editing session.

You can convert binary menus to ASCII files and vice versa through the utility m2asc. The menu bar editor can only read binary files; in order to modify an ASCII menu file through the editor, first convert it to binary with m2asc and then use formlib to put it in a library.

Information about m2ascis in Application Development Guide. Information about formlib is in Application Development Guide. For information about ASCII menu format, refer to "Outputting Menu Definitions to ASCII" in Application Development Guide.