Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

23    Menu Reference

User Interface

Exploring Palm OS®

This chapter describes the menu API as declared in the header file Menu.h. It discusses the following topics:

Menu Structures and Types
Menu Constants
Menu Events
Menu Notifications
Menu Functions and Macros

For more information on menus, see the section Chapter 4, "Working with Menus."

Menu Structures and Types ^TOP^

MenuBarType Struct ^TOP^

Purpose

Internal structure that defines a menu bar. The MenuBarPtr function defines a pointer to a menu bar.

Declared In

Menu.h

Prototype

typedef struct MenuBarType MenuBarType;
typedef MenuBarType *MenuBarPtr

Fields

None.

Menu Constants ^TOP^

Command Button Location Constants ^TOP^

Purpose

Specifies where to place a new button within the menu command tool bar.

Declared In

Menu.h

Constants

#define menuCmdBarOnLeft 0xff
Add the button to the left of the other buttons on the command tool bar.
#define menuCmdBarOnRight 0
Add the button to the right of the other buttons.

See Also

MenuCmdBarAddButton()

Menu Activation Constants ^TOP^

Purpose

Indicates how a menu has been activated. These constants are sent as part of the menuOpenEvent.

Declared In

Menu.h

Constants

#define menuButtonCause 0
The menu is going to be displayed because the user tapped the Menu icon or tapped the form's title bar.
#define menuCommandCause 1
The user drew the menu command shortcut character in the input area, so the menu is becoming active without being displayed.

Menu Error Constants ^TOP^

Purpose

Errors returned by menu functions.

Declared In

Menu.h

Constants

#define menuErrNoMenu (menuErrorClass | 1)
There is currently no active menu.
#define menuErrNotFound (menuErrorClass | 2)
Could not locate the specified item.
#define menuErrOutOfMemory (menuErrorClass | 5)
There is not enough memory available to perform the operation.
#define menuErrSameId (menuErrorClass | 3)
The menu already contains an item with the specified ID.
#define menuErrTooManyItems (menuErrorClass | 4)
The command tool bar already has the maximum number of buttons allowed (currently 8).

Miscellaneous Constants ^TOP^

Purpose

Other constants defined in Menu.h.

Declared In

Menu.h

Constants

#define MenuSeparatorChar '-'
Special character indicating that the menu item is a bar used to separate groups of related menu items.
#define noMenuItemSelection -1
There is currently no item selected within a menu.
#define noMenuSelection -1
There is currently no pull-down menu selected.
#define separatorItemSelection -2
The currently selected item within a menu is the bar used to separate groups of related menu items.
#define menuCmdBarMaxTextLength 20
The maximum length of the text that is briefly displayed as a status message when a button in the menu command tool bar is tapped.

MenuCmdBarResultType Typedef ^TOP^

Purpose

Specifies what the result of a user tapping a specific button in the menu command tool bar is.

Declared In

Menu.h

Prototype

typedef Enum8 MenuCmdBarResultType

Constants

menuCmdBarResultNone
No result.
menuCmdBarResultChar
The result is a character to send in a keyDownEvent.
menuCmdBarResultMenuItem
The result is the ID of the menu item to send in a menuEvent.
menuCmdBarResultNotify
The result is a notification constant to be broadcast using SysNotifyBroadcastDeferred().

See Also

MenuCmdBarAddButton(), MenuCmdBarGetButtonData()

Menu Events ^TOP^

menuCloseEvent ^TOP^

Purpose

This event is not currently used. If you need to perform some cleanup (such as closing a resource) after the menu item you added is no longer needed, do so in response to frmCloseEvent.

menuCmdBarOpenEvent ^TOP^

Purpose

Sent when the menu command tool bar is about to be displayed.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct menuCmdBarOpen {
   Boolean preventFieldButtons;
   uint8_t reserved;
} menuCmdBarOpen;

Fields

preventFieldButtons
If true, the UI Library does not add the standard cut, copy, paste, and undo buttons when the focus is on a field. If false, the UI Library adds the buttons.
reserved
Unused.

Comments

Applications might respond to this event by calling MenuCmdBarAddButton() to add custom buttons to the command tool bar. Return false to allow the default system behavior to take place.

Shared libraries or other non-application code resources can add buttons to the tool bar by registering to receive the sysNotifyMenuCmdBarOpenEvent notification.

To prevent the command tool bar from being displayed, respond to this event and return true. Returning true prevents the UI Library from displaying the tool bar.

menuCmdBarTimeoutEvent ^TOP^

Purpose

Sent when the menu command tool bar has reached its timeout limit for activity and is about to be erased.

Declared In

EventCodes.h

Prototype

No data is passed with this event.

Comments

Applications do not need to send or handle this event. It is used internally by the menu command tool bar.

menuEvent ^TOP^

Purpose

Sent when one of the following occurs:

  • When the user selects an item from a pull-down menu
  • When the user draws the menu command stroke followed by a character; for example, Command-C for copy
  • When the user taps one of the buttons on the command tool bar and the button is set up to generate a menuEvent.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct menu {
  uint16_t itemID;
} menu;

Fields

itemID
Item ID of the selected menu command.

Comments

Applications respond to this event to perform the action that the user requested. Return true to indicate that you've handled the event.

menuOpenEvent ^TOP^

Purpose

Sent when a new active menu has been initialized.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct menuOpen {
   uint16_t menuRscID;
   int16_t cause;
} menuOpen;

Fields

menuRscID
Resource ID of the menu.
cause
Reason for opening the menu. This value is one of the Menu Activation Constants.

Comments

A menu becomes active the first time the user taps the Menu icon or taps the form's title bar, and a menu might need to be re-initialized and reactivated several times during the life of an application.

A menu remains active until one of the following happens:

  • A FrmSetMenu() call changes the active menu on the form.
  • 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, it must be initialized again, so menuOpenEvent is sent again.

Applications might respond to this event by adding, hiding, or unhiding menu items using the functions MenuAddItem(), MenuHideItem(), or MenuShowItem(). Return false to allow the default system behavior to take place.

Menu Notifications ^TOP^

sysNotifyMenuCmdBarOpenEvent ^TOP^

Purpose

Broadcast when the menu command tool bar is about to be displayed at the bottom of the screen.

Declared In

NotifyMgr.h

Prototype

None.

Comments

Register for this notification if you are writing a shared library or system resource that needs to add a button to the menu command bar or to suppress the menu command tool bar. To add a button, call MenuCmdBarAddButton(). To suppress the command tool bar, set the handled field to true.

Applications that need to add their own buttons to the menu command tool bar should do so in response to a menuCmdBarOpenEvent. They should not register for this notification because an application should only add buttons if it is already the active application. The notification is sent after the event has been received, immediately before the command tool bar is displayed.

Menu Functions and Macros ^TOP^

MenuAddItem Function ^TOP^

Purpose

Adds an item to the currently active menu.

Declared In

Menu.h

Prototype

status_t MenuAddItem (
   uint16_t positionId,
   uint16_t id,
   char cmd,
   const char *textP
)

Parameters

positionId
ID of an existing menu item. The new menu item is added after this menu item.
id
ID value to use for the new menu item.
cmd
Menu command shortcut key. If you provide menu shortcuts, make sure that each shortcut is unique among all commands available at that time.
textP
Pointer to the text to display for this menu item, including the menu shortcut key. To include a shortcut key, begin the string with the item's text, then type a tab character, and then the item's shortcut key.
To create a separator bar, create a one-character string containing the MenuSeparatorChar constant.

Returns

errNone upon success or one of the following if an error occurs:

menuErrNoMenu
The textP parameter is NULL.
menuErrSameId
The menu already contains an item with the ID id.
menuErrNotFound
The menu doesn't contain an item with the ID positionId.

Comments

You should call this function only in response to a menuOpenEvent. This event is generated when the menu is first made active. In general, a form's menu becomes active the first time a keyDownEvent with a vchrMenu or vchrCommand is generated, and it remains active until a new form (including a modal form or alert panel) is displayed or until FrmSetMenu() is called to change the form's menu. Palm OS® user interface guidelines discourage adding or hiding menu items at any time other than when the menu is first made active.


WARNING! The system may need to resize and move the menu's memory block as a result of this function, invalidating any pointer to the menu. Call MenuGetActiveMenu() after calling this function to obtain a pointer to the menu's new location.

This function may display a fatal error message if there is no current menu.

MenuCmdBarAddButton Function ^TOP^

Purpose

Defines a button to be displayed on the command tool bar.

Declared In

Menu.h

Prototype

status_t MenuCmdBarAddButton (
   uint8_t where,
   DmOpenRef database,
   uint16_t bitmapId,
   MenuCmdBarResultType resultType,
   uint32_t result,
   char *nameP
)

Parameters

where
Either menuCmdBarOnLeft to add the button to the left of the other buttons on the command tool bar, menuCmdBarOnRight to add it to the right of the other buttons, or a number indicating the exact position of the button. Button positions are numbered from right to left, and the rightmost position is number 1.
It is best to add buttons on the left side. If you add buttons to the right, this function moves all existing buttons over one position to the left.
If you specify an exact position, this function adds buttons to the first open slot if you don't specify buttons in order. That is, if you add a button at position 3 and there are no buttons at positions 1 and 2, this function adds the button at position 1.
database
Open resource database containing bitmapId.
bitmapId
Resource ID of the bitmap to display on the button. The bitmap's dimensions should be 13 standard coordinates high by 16 standard coordinates wide.
resultType
The type of data contained in the result parameter. See MenuCmdBarResultType.
result
The data to send when the user taps this button. This can be a character, a menu item ID, or a notification constant.
nameP
Pointer to the text to display in the status message if the user taps the button. If NULL, the text is taken from the menu item that matches the ID or shortcut character contained in result, if a match is found.
If you supply a text buffer for this parameter, MenuCmdBarAddButton() makes a copy of the buffer.

Returns

errNone upon success, or one of the following error codes:

menuErrOutOfMemory
There is not enough memory available to perform the operation.
menuErrTooManyItems
The command tool bar already has the maximum number of buttons allowed (currently 8).

Comments

Call this function in response to a menuCmdBarOpenEvent or to the notification sysNotifyMenuCmdBarOpenEvent. Both of these signal that the user has written the menu command stroke in the input area and the command tool bar is about to open. Your response should be to add buttons to the tool bar and to return false, indicating that you have not completely handled the event.

The sysNotifyMenuCmdBarOpenEvent notification is intended to be used only by shared libraries, system extensions, and other code resources that do not use an event loop. If you're writing an application, always respond to the event instead of the notification; an application should only add buttons to the tool bar if it is the current application. If you register for the notification, you receive it each time the command tool bar is displayed, whether your application is active or not.

Note that the command tool bar is allocated each time it is opened and is deallocated when it is erased from the screen.

The result and resultType parameters specify what the result should be if the user taps the button. result contains the actual data, and resultType contains a constant that specifies the type of data in result. Typically, the result is to enqueue a menuEvent. In this case, resultType is menuCmdBarResultMenuItem and the result is the ID of the menu item that should included in the event.

You may also specify the shortcut character instead of the menu ID; however, doing so is inefficient. When result is a shortcut character, the MenuHandleEvent() function enqueues a keyDownEvent with the character in result. During the next cycle of the event loop, MenuHandleEvent() enqueues a menuEvent in response to the keyDownEvent. Thus, it is better to have your button enqueue the menuEvent directly.

If you call MenuCmdBarAddButton() outside of an application, you might not know of any menu items in the active menu (unless your code has added one using MenuAddItem()). In this case, specify a notification to be broadcast. The notification is broadcast at the top of the next event loop, and it must contain no custom data. (Applications may also use the notification result type.)

See Also

MenuCmdBarDisplay(), MenuCmdBarGetButtonData()

MenuCmdBarDisplay Function ^TOP^

Purpose

Displays the command tool bar.

Declared In

Menu.h

Prototype

void MenuCmdBarDisplay (
   void
)

Parameters

None.

Returns

Nothing.

Comments

This function displays the command tool bar when the user enters the command keystroke. You normally do not call this function in your own code. FrmHandleEvent() calls it at the end of its handling of menuCmdBarOpenEvent.

See Also

MenuCmdBarAddButton(), MenuCmdBarGetButtonData()

MenuCmdBarGetButtonData Function ^TOP^

Purpose

Gets the data for a given command button.

Declared In

Menu.h

Prototype

Boolean MenuCmdBarGetButtonData (
   int16_t buttonIndex,
   DmOpenRef *databaseP,
   uint16_t *bitmapIdP,
   MenuCmdBarResultType *resultTypeP,
   uint32_t *resultP,
   char *nameP
)

Parameters

buttonIndex
Index of the button for which you want to obtain information. Buttons are ordered from right to left, with the rightmost button at index 0.
databaseP
Open resource database that contains bitmapId. Pass NULL if you don't want to retrieve this value.
bitmapIdP
The resource ID of the bitmap displayed on the button. Pass NULL if you don't want to retrieve this value.
resultTypeP
The type of action this button takes. Pass NULL if you don't want to retrieve this value.
resultP
The result of tapping the button. Pass NULL if you don't want to retrieve this information.
nameP
The text displayed in the status message when this button is tapped. Pass NULL if you don't want to retrieve this information. If not NULL, nameP must point to a string of menuCmdBarMaxTextLength size.

Returns

true if the information was retrieved successfully, false if there is no command tool bar or if there is no button at buttonIndex.

Comments

You can use this function to retrieve information about the buttons that are displayed on the command tool bar. If the command tool bar has not yet been initialized, this function returns false.

Note that the command tool bar is allocated when the user enters the command keystroke and deallocated when MenuEraseStatus() is called. Thus, the only logical place to call MenuCmdBarGetButtonData() is in response to a menuCmdBarOpenEvent or a sysNotifyMenuCmdBarOpenEvent notification.

See Also

MenuCmdBarDisplay(), MenuCmdBarAddButton()

MenuDispose Function ^TOP^

Purpose

Releases any memory allocated to the menu and the command status and restore any saved bits to the screen.

Declared In

Menu.h

Prototype

void MenuDispose (
   MenuBarType *menuP
)

Parameters

menuP
Pointer to the menu to dispose. If NULL, this function returns immediately.

Returns

Nothing.

Comments

Most applications do not need to call this function directly. MenuDispose() is called by the system when the form that contains the menu is no longer the active form, when the form that contains the menu is freed, and when FrmSetMenu() is called to change the form's menu bar.

See Also

MenuInit(), MenuDrawMenu()

MenuDrawMenu Function ^TOP^

Purpose

Requests that the current menu bar and the last pull-down that was visible be drawn or redrawn.

Declared In

Menu.h

Prototype

void MenuDrawMenu (
   MenuBarType *menuP
)

Parameters

menuP
Pointer to a menu bar.

Returns

Nothing.

Comments

Invalidates the windows for the menu bar and the pull-down menu that was last visible so that they are later redrawn.

Most applications do not need to call this function directly. MenuHandleEvent() calls MenuDrawMenu() when the user taps the Menu icon or the form's title bar.

The menu bar and the pull-down menu are drawn in front of all the application windows.

A menu keeps track of the last pull-down menu displayed for as long as the menu 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 MenuDrawMenu() is called (that is, the next time the user taps the Menu silk-screen button), the menu bar is displayed as it was before, and the first pull-down menu listed in the menu bar is displayed instead of the Options pull-down menu.

See Also

MenuInit(), MenuDispose()

MenuEraseStatus Function ^TOP^

Purpose

Erases the menu command status.

Declared In

Menu.h

Prototype

void MenuEraseStatus (
   MenuBarType *menuP
)

Parameters

menuP
Pointer to a menu bar, or NULL for the current menu.

Returns

Nothing.

Comments

When the user selects a menu command using the command keystroke, the command tool bar is displayed at the bottom of the screen. MenuEraseStatus() erases the tool bar.

You do not need to call this function explicitly. Let the current menu command status remove itself automatically. Otherwise, you may cause text to be erased before the user has a chance to see it. In Palm OS Cobalt, the menu command bar draws in its own window and does not interfere with your application's drawing.

See Also

MenuInit()

MenuGetActiveMenu Function ^TOP^

Purpose

Returns a pointer to the currently active menu.

Declared In

Menu.h

Prototype

MenuBarType *MenuGetActiveMenu (
   void
)

Parameters

None.

Returns

A pointer to the currently active menu, or NULL if there is none.

Comments

An active menu is not necessarily visible on the screen. A menu might be active but not visible, for example, if a menu command shortcut has been entered. In general, a form's menu becomes active the first time a keyDownEvent with a vchrMenu or vchrCommand is generated, and it remains active until a new form (including a modal form or alert panel) is displayed or until FrmSetMenu() is called to change the form's menu.

See Also

MenuHandleEvent(), MenuSetActiveMenu()

MenuHandleEvent Function ^TOP^

Purpose

Handles events in the current menu.

Declared In

Menu.h

Prototype

Boolean MenuHandleEvent (
   MenuBarType *menuP,
   EventType *event,
   status_t *error
)

Parameters

menuP
Pointer to a menu bar.
event
Pointer to an EventType structure.
error
Error (or errNone if no error). Currently this function always sets error to zero.

Returns

true if the event is handled; false otherwise.

Comments

The following cases will result in a return value of true:

  • A penDownEvent or penMoveEvent. If the pen is within the bounds of the menu bar, the selected menu title is inverted and the appropriate pull-down menu is drawn. Any previous pull-down menu is erased. If the pen is within the bounds of a pull-down menu, inverts the selected menu item and removes the selection from any previously selected menu item. If a pull-down menu is currently displayed and the pen is down outside the bounds of the menu, the menu is dismissed.
  • A penUpEvent. If the pen is up within the bounds of the menu bar, erases the current pull-down menu. If the pen is within the bounds of a menu item in a pull-down menu, sends a menuEvent containing the resource ID of the selected menu item. If the pen is up outside the bounds of the menu bar and menu resources, they are both erased and no item is selected.
  • keyDownEvent containing vChrCommand or vchrMenu. If the menu is being activated and initialized for the first time, this function enqueues a menuOpenEvent containing the reason the menu was initialized (menuButtonCause for a vchrMenu or menuCommandCause for a vchrCommand), and then the current event is added after it.

    For vchrCommand, this function sends a menuCmdBarOpenEvent.

  • winUpdateEvent. Redraws the currently displayed menu bar and pull-down menu.

MenuHideItem Function ^TOP^

Purpose

Hides the specified menu item.

Declared In

Menu.h

Prototype

Boolean MenuHideItem (
   uint16_t id
)

Parameters

id
ID of the menu item to hide.

Returns

true if the item was successfully hidden, false otherwise.

Comments

You should call this function only in response to a menuOpenEvent. This event is generated when the menu is first made active. In general, a form's menu becomes active the first time a keyDownEvent with a vchrMenu or vchrCommand is generated, and it remains active until a new form (including a modal form or alert panel) is displayed or until FrmSetMenu() is called to change the form's menu. Palm OS user interface guidelines discourage adding or hiding menu items at any time other than when the menu is first made active.

See Also

MenuShowItem()

MenuInit Function ^TOP^

Purpose

Loads a menu resource from a resource file.

Declared In

Menu.h

Prototype

MenuBarType *MenuInit (
   DmOpenRef database,
   uint16_t resourceId
)

Parameters

database
Open resource database containing the menu.
resourceId
ID that identifies the menu resource.

Returns

A pointer to a MenuBarType structure.

Comments

The menu is not usable until MenuSetActiveMenu() is called.

Typically, you do not need to call this function directly. A form stores the resource ID of the menu associated with it and initializes that menu as necessary. If you want to change the form's menu, call FrmSetMenu(), which handles disposing of the form's current menu, associating the new menu with the form, and initializing when needed.

See Also

MenuSetActiveMenu(), MenuDispose()

MenuSetActiveMenu Function ^TOP^

Purpose

Sets the current menu.

Declared In

Menu.h

Prototype

MenuBarType *MenuSetActiveMenu (
   MenuBarType *menuP
)

Parameters

menuP
Pointer to the structure that contains the new menu, or NULL for none.

Returns

A pointer to the menu that was active before the new menu was set, or NULL if no menu was active.

Comments

This function sets the active menu but does not associate it with a form. It's recommended that you call FrmSetMenu() instead of MenuSetActiveMenu(). FrmSetMenu() sets the active menu, frees the old menu, and associates the newly active menu with the form, which means the menu will be freed when the form is freed.

See Also

MenuGetActiveMenu()

MenuSetActiveMenuRscID Function ^TOP^

Purpose

Sets the current menu by resource ID.

Declared In

Menu.h

Prototype

void MenuSetActiveMenuRscID (
   DmOpenRef database,
   uint16_t resourceId
)

Parameters

database
Open resource database containing the menu.
resourceId
Resource ID of the menu to be made active.

Returns

Nothing.

Comments

This function is similar to MenuSetActiveMenu() except that you pass the menu's resource ID instead of a pointer to a menu structure. It is used as an optimization; with MenuSetActiveMenu(), you must initialize the menu before making it active. Potentially, the application may exit before the menu is needed, making this memory allocation unnecessary. MenuSetActiveMenuRscID() simply stores the resource ID. The next time a menu is requested, the menu is initialized from this resource.

It's recommended that you call FrmSetMenu() instead of calling this function for the reasons given in MenuSetActiveMenu().

MenuShowItem Function ^TOP^

Purpose

Makes the specified menu item visible.

Declared In

Menu.h

Prototype

Boolean MenuShowItem (
   uint16_t id
)

Parameters

id
ID of the menu item to display.

Returns

true if the hidden attribute of the specified item was successfully disabled, false otherwise.

Comments

You should call this function only in response to a menuOpenEvent. This event is generated when the menu is first made active. In general, a form's menu becomes active the first time a keyDownEvent with a vchrMenu or vchrCommand is generated, and it remains active until a new form (including a modal form or alert panel) is displayed or until FrmSetMenu() is called to change the form's menu. Palm OS user interface guidelines discourage adding or hiding menu items at any time other than when the menu is first made active.

See Also

MenuHideItem()