Menu bars and their associated pulldown menus are defined within the resource script file, using the MENU and SUBMENU keywords. A sample menu bar and pulldown menu definition is shown in Figure "Menu Bar Resource Definition".
The symbolic name (MAIN in the example above) identifies the resource. This name is passed as a parameter to the WinCreateWindow() and WinCreateStdWindow() functions and identifies the menu bar resource when the FCF_MENU style frame control flag is specified for the frame window. The PRELOAD option specifies that the resource will be incorporated into the application's main .EXE file, and is to be loaded immediately into memory, rather than being loaded when called by the application.
The SUBMENU statement defines a menu bar entry that will be associated with a pulldown menu. MENUITEM statements that are enclosed within the BEGIN and END markers of a SUBMENU statement define the pulldown menu items. MENUITEM statements that are not enclosed within the bounds of a SUBMENU statement define menu bar entries that do not have an associated pulldown menu.
The text strings within quotation marks define the text for each menu bar or pulldown menu item. The symbolic name following the text identifies the value (placed in the first message parameter) of the WM_COMMAND message generated when the item is selected. The symbolic names following the message identifier define the style of the item. In the example above, all items are simple text items and are defined with the style MIS_TEXT. The sole exception is the final "Help" menu bar item, which is defined with the style attributes of MIS_HELP, which causes the item to generate a WM_HELP message rather than a WM_COMMAND message, and MIS_BUTTONSEPARATOR, which causes the item to be displayed on the right-hand side of the menu bar separated by a vertical bar, in accordance with SAA CUA guidelines. The various item styles and attributes are documented in the IBM OS/2 Version 2.0 Presentation Manager Reference.
When groups of items within a single pulldown menu are logically separate, they should be visually separated by a horizontal bar within the pulldown menu. This may be achieved using the SEPARATOR keyword in the MENUITEM statement, as follows:
MENUITEM SEPARATORThe use of a separator bar in pulldown menus is particularly important when the pulldown menu is used to display a list of entries, comprised of multiple sets of mutually exclusive options, from which the user must select one option from each set. In such a case, the separator bar is used to group the items within each set, and to visually separate the sets from one another.
As already mentioned, menu bar resources are typically incorporated into a window by specifying their resource identifier in a WinCreateWindow() or WinCreateStdWindow() call, with the FCF_MENU frame creation flag set for the frame window. A submenu within a menu bar resource may also be dynamically created using the WinCreateMenu() function, which is described in The Menu Bar.
Mnemonics
Mnemonics may be specified for menu bar and pulldown menu items. A mnemonic is a key which, when combined with the F10 key, results in selection of the item. The character for the mnemonic must be part of the text for the item. For example, the conventional mnemonic key for the "Exit" menu bar item is "x"; when the F10 key is pressed followed by the "x" key, a WM_COMMAND message with value MI_EXIT is generated.
Mnemonics are indicated to the user by the appropriate character within the item text being underlined. This is achieved by placing a tilde character (~) within the item text, immediately prior to the required character; for example:
MENUITEM "E~xit", MI_EXIT, MIS_TEXT
When the resource script file is compiled using the resource compiler, the menu bar item is created with the appropriate mnemonic.
Accelerator Keys
Accelerator keys or key sequences may be used to represent a pulldown menu item and provide a "fast path" to a particular command. Note that accelerator keys are not used to represent menu bar entries, since the use of an accelerator key sequence is typically more complex than the use of a mouse or an F10 + single character operation. The definition of accelerator keys is described in Accelerator Tables. It is conventional to display an accelerator key sequence, along with the command represented by that sequence, in the pulldown menu, thus providing the user with a visual indication of the accelerator key sequence. This may be achieved by the use of the "\t" or "\a" control codes within the item text. The "\t" code causes text to the right of the code to be left-justified in a new column, whereas the "\a" code causes text to the right of the code to be right-justified in a new column.
To display an accelerator key sequence in a pulldown menu, it is conventional to use the "\t" control code. For example:
MENUITEM "~Tile\tShift+F5", MI_TILE, MIS_TEXT
This would result in the item text "Tile" (with the "T" underscored to represent the mnemonic) being displayed in the left of the pulldown menu with the text "Shift+F5" being left-justified in a second column to the right of the item text.