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
MenuBarType Struct
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
Menu Constants
Command Button Location Constants
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
Menu Activation Constants
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
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
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
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
menuCloseEvent
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
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. Iffalse
, 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
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
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
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
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
sysNotifyMenuCmdBarOpenEvent
Purpose
Broadcast when the menu command tool bar is about to be displayed at the bottom of the screen.
Declared In
NotifyMgr.h
Prototype
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
MenuAddItem Function
Purpose
Adds an item to the currently active menu.
Declared In
Menu.h
Prototype
status_t MenuAddItem ( uint16_tpositionId
, uint16_tid
, charcmd
, 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 isNULL
. -
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
Purpose
Defines a button to be displayed on the command tool bar.
Declared In
Menu.h
Prototype
status_t MenuCmdBarAddButton ( uint8_twhere
, DmOpenRefdatabase
, uint16_tbitmapId
, MenuCmdBarResultTyperesultType
, uint32_tresult
, 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. SeeMenuCmdBarResultType
. -
→ 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 inresult
, 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
Purpose
Displays the command tool bar.
Declared In
Menu.h
Prototype
void MenuCmdBarDisplay ( void )
Parameters
Returns
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
Purpose
Gets the data for a given command button.
Declared In
Menu.h
Prototype
Boolean MenuCmdBarGetButtonData ( int16_tbuttonIndex
, 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.
-
← databas
eP
- Open resource database that contains
bitmapId
. PassNULL
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 notNULL
,nameP
must point to a string ofmenuCmdBarMaxTextLength
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
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
Returns
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
MenuDrawMenu Function
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
Returns
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
MenuEraseStatus Function
Purpose
Erases the menu command status.
Declared In
Menu.h
Prototype
void MenuEraseStatus (
MenuBarType *menuP
)
Parameters
Returns
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
MenuGetActiveMenu Function
Purpose
Returns a pointer to the currently active menu.
Declared In
Menu.h
Prototype
MenuBarType *MenuGetActiveMenu ( void )
Parameters
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
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 setserror
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
orpenMoveEvent
. 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 amenuEvent
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
containingvChrCommand
orvchrMenu
. If the menu is being activated and initialized for the first time, this function enqueues amenuOpenEvent
containing the reason the menu was initialized (menuButtonCause
for avchrMenu
ormenuCommandCause
for avchrCommand
), and then the current event is added after it.For
vchrCommand
, this function sends amenuCmdBarOpenEvent
. -
winUpdateEvent
. Redraws the currently displayed menu bar and pull-down menu.
MenuHideItem Function
Purpose
Hides the specified menu item.
Declared In
Menu.h
Prototype
Boolean MenuHideItem (
uint16_t id
)
Parameters
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
MenuInit Function
Purpose
Loads a menu resource from a resource file.
Declared In
Menu.h
Prototype
MenuBarType *MenuInit ( DmOpenRefdatabase
, uint16_tresourceId
)
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
Purpose
Declared In
Menu.h
Prototype
MenuBarType *MenuSetActiveMenu (
MenuBarType *menuP
)
Parameters
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
MenuSetActiveMenuRscID Function
Purpose
Sets the current menu by resource ID.
Declared In
Menu.h
Prototype
void MenuSetActiveMenuRscID ( DmOpenRefdatabase
, uint16_tresourceId
)
Parameters
-
→ database
- Open resource database containing the menu.
-
→ resourceId
- Resource ID of the menu to be made active.
Returns
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
Purpose
Makes the specified menu item visible.
Declared In
Menu.h
Prototype
Boolean MenuShowItem (
uint16_t id
)
Parameters
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.