A menu bar is displayed whenever the user taps a Menu icon or whenever the user taps in a form's title bar. The menu bar, a horizontal list of menu titles, appears at the top of the screen in its own window, above all application windows. Pressing a menu title highlights the title and "pulls down" the menu below the title (see Figure 4.1).

User actions have the following effect on a menu:
A menu has the following features:
- Item separators, which are lines to group menu items.
- Menu shortcuts; the shortcut labels are right justified in menu items.
- A menu remembers its last selection; the next time a menu is displayed the prior selection appears highlighted.
Menu Events
All applications that support menus should handle the menuEvent
. This event is sent when the user selects a menu command from a menu. The application should respond by performing the requested action.
General event handling for menus is performed by MenuHandleEvent()
. Table 4.1 describes how user actions get translated into events and what MenuHandleEvent()
does in response.
Table 4.1 Event flow for menus
|
Tracks the pen without blocking. Responds to If this is the first time the menu has been opened, adds a |
|
|
Edit Menu
Forms that display editable text fields should provide the system default Edit menu. This menu is shown in Figure 4.1. To provide the system default edit menu, do the following:
- Create a menu resource in your application's resource file and give it the ID 10000.
- Add the menu commands to the menu in the order shown in Figure 4.1.
- Associate the menu resource with the form's menu bar resource.
As long as you have given your Edit menu the ID 10000 and have the commands listed in the same order, Palm OS® handles all of the menuEvent
s for your Edit menu. You do not have to write any code.
Menu Command Shortcuts
As an alternative to selecting a menu command through the user interface, users can instead write a menu shortcut in the input area if the current handwriting recognition engine supports it.
IMPORTANT: Only use a single character from A to Z (case-insensitive) to define a shortcut. Do not use accented characters.
The user can draw a menu command stroke followed by another character. If the next character matches one of the shortcut characters for an item on the active menu, a menuEvent
with that menu item is generated. To support this behavior, you simply specify a shortcut character when you create a menu item resource. The default behavior of Palm OS handles this shortcut appropriately.
Drawing the menu command stroke displays the command tool bar (see Figure 4.2). This tool bar is the width of the screen. The command tool bar displays a status message on the left and buttons on the right. After drawing the command stroke, the user has the choice of writing a character or of tapping one of the buttons on the command tool bar. Both of these actions cause the status message to be briefly displayed and (in most cases) a menuEvent
to be added to the event queue.

The buttons displayed on the tool bar depend on the user context. If the focus is in an editable field, the UI Library displays buttons for cut, copy, and paste on the command tool bar. If there is an action to undo, the UI Library also displays a button for undo.
The active application may also add its own buttons to the tool bar. To do so, respond to the menuCmdBarOpenEvent
and use MenuCmdBarAddButton()
to add the button. Listing 4.1 shows some code from the Memo Pad application that adds to the command tool bar a button that displays the security dialog and then prevents the UI Library from adding other buttons.
Listing 4.1 Responding to menuCmdBarOpenEvent
else if (event->eType == menuCmdBarOpenEvent) { MenuCmdBarAddButton(menuCmdBarOnLeft, myAppDB, BarSecureBitmap, menuCmdBarResultMenuItem, ListOptionsSecurityCmd, 0); // Tell the field package to not add buttons // automatically; we've done it all ourselves. event->data.menuCmdBarOpen.preventFieldButtons = true; // Don't set handled to true; this event must // fall through to the system. }
The system contains bitmaps that represent such commands as beaming and deleting records. If your application performs any of these actions, it should use the system bitmap. Table 4.2 shows the system bitmaps and the commands they represent. If you use any of these, you should use them in the order shown, from right to left. That is, BarDeleteBitmap
should always be the rightmost of these bitmaps, and BarInfoBitmap
should always be the leftmost.
Table 4.2 System command tool bar bitmaps
You should limit the buttons displayed on the command tool bar to 4 or 5. There are two reasons to limit the number of buttons. You must leave room for the status message to be displayed before the action is performed. Also, consider that the tool bar is displayed only briefly. Users must be able to instantly understand the meaning of each of the buttons on the tool bar. If there are too many buttons, it reduces the chance that users can find what they need.
Note that the UI Library already potentially displays 4 buttons by itself. If you want to suppress this behavior and display your own buttons when a field has focus, set the preventFieldButtons
flag of the menuCmdBarOpenEvent
to true
as is shown in Listing 4.1.
Dynamic Menus
You can add, hide, or unhide menu items while the menu resource is being loaded.
A menuOpenEvent
is sent when the menu resource is loaded. In response to this event, you can call MenuAddItem()
to add a menu item to one of the pull-down menus, MenuHideItem()
to hide a menu item, or MenuShowItem()
to display a menu item.
You might receive menuOpenEvent
several times during an application session. The menu resource is loaded each time the menu is made the active menu. A menu becomes active the first time the user either requests that the menu be displayed or enters the command keystroke on the current form. That menu remains active as long as the form with which it is associated is active. A menu loses its active status under these conditions:
- When
FrmSetMenu()
is called to change the active menu on the form. - When a new form, even a modal form or alert panel, becomes active.
Suppose a user selects your application's About item from the Options menu then clicks the OK button to return to the main form. When the About dialog is displayed, it becomes the active form, which causes the main form's menu state to be erased. This menu state is not restored when the main form becomes active again. The next time the user requests the menu, the menu resource is reloaded, and a new menuOpenEvent
is queued.
You should only make changes to a menu the first time it is loaded after a form becomes active. You should not add, hide, or show items based on user context. Such practice is discouraged in the Palm OS user interface guidelines.