This chapter describes the menu API as declared in the header file Menu.h. It discusses the following topics:
Menu Data Structures
Menu Constants
Menu Resources
Menu Functions
For more information on menus, see the section "Menus" in the Palm OS Programmer's Companion, vol. I.
Menu Data Structures

MenuBarAttrType

The MenuBarAttrType bit field defines some characteristics of the menu bar.
WARNING! Palm, Inc. does not support or provide backward compatibility for the MenuBarAttrType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
typedef struct {
UInt16 visible : 1;
UInt16 commandPending : 1;
UInt16 insPtEnabled : 1;
UInt16 needsRecalc : 1;
} MenuBarAttrType;
Your code should treat the MenuBarAttrType structure as opaque. Use the functions specified in the descriptions below to retrieve and set each value. Do not attempt to change structure member values directly.
Field Descriptions
visible |
If set, the menu bar is drawn and visible on the screen. This attribute is set as part of MenuDrawMenu, which is called when the menu is drawn. |
commandPending |
If set, a menu command shortcut is in progress. This bit is set during MenuHandleEvent if the menu shortcut keystroke is received. If the next key is received before the timeout value is reached, the key is examined to see if it is a valid menu command. |
insPtEnabled |
Stores the state of the insertion point at the time the menu was drawn so that it can be restored when the menu is erased. |
needsRecalc |
If set, recalculate menu dimensions. |
Compatibility
The needsRecalc constant is present only if 3.5 New Feature Set is present.
MenuCmdBarButtonType

The MenuCmdBarButtonType structure defines a button to be displayed on the command toolbar. The buttonsData field of the MenuCmdBarType structure contains an array of structures of this type.
WARNING! Palm, Inc. does not support or provide backward compatibility for the MenuCmdBarButtonType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
typedef struct {
UInt16 bitmapId;
Char name[menuCmdBarMaxTextLength];
MenuCmdBarResultType resultType;
UInt8 reserved;
UInt32 result;
} MenuCmdBarButtonType;
Your code should treat the MenuCmdBarButtonType structure as opaque. Do not attempt to change structure member values directly. Instead, use MenuCmdBarAddButton to add a button to the display. For the most part, the parameters to MenuCmdBarAddButton are the same as the fields in the MenuCmdBarButtonType, so there should be no need to alter these fields directly.
MenuCmdBarGetButtonData can be called to access information about command bar buttons.
Field Descriptions
bitmapId |
Resource ID of the bitmap to display on the button. This bitmap should be 13 pixels high by 16 pixels wide. |
name |
Text to display in the status message when the user taps the button. |
resultType |
Specifies what type of data is contained in the result field. See MenuCmdBarResultType. |
reserved |
Reserved for future use. |
result |
Specifies the data to send when the user clicks the button. The data is interpreted as specified by the resultType field. The result can be a shortcut character to enqueue in a keyDownEvent, a menu item ID to enqueue in a menuEvent, or a notification to be broadcast. |
Compatibility
This structure is defined only if 3.5 New Feature Set is present.
MenuCmdBarResultType

The MenuCmdBarResultType enum specifies how the result field in the MenuCmdBarButtonType structure should be interpreted.
typedef enum {
menuCmdBarResultNone,
menuCmdBarResultChar,
menuCmdBarResultMenuItem,
menuCmdBarResultNotify
} MenuCmdBarResultType;
Value Descriptions
menuCmdBarResultNone |
Send nothing. |
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 |
Compatibility
This enum is defined only if 3.5 New Feature Set is present.
MenuCmdBarType

The MenuCmdBarType structure defines the command toolbar. This command toolbar is allocated and displayed when the user draws the shortcut stroke in the Graffiti® area. It is deallocated when MenuEraseStatus is called, which occurs most frequently when the timeout value has elapsed.
WARNING! Palm, Inc. does not support or provide backward compatibility for the MenuCmdBarType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
typedef struct MenuCmdBarType {
WinHandle bitsBehind;
Int32 timeoutTick;
Coord top;
Int16 numButtons;
Boolean insPtWasEnabled;
Boolean gsiWasEnabled;
Boolean feedbackMode;
MenuCmdBarButtonType *buttonsData;
} MenuCmdBarType;
Your code should treat the MenuCmdBarType structure as opaque. Do not attempt to change structure member values directly.
Field Descriptions
bitsBehind |
Handle for the window that contains the region obscured by the command toolbar. |
timeoutTick |
Timeout value given in system ticks. If the user hasn't specified a command after this many ticks, the command toolbar is erased from the screen and deallocated from memory. This value also specifies how long the status message is displayed after the user successfully enters a command. |
top |
The top bound of the command toolbar given in display-relative coordinates. The command toolbar is as wide as the screen and displays at the bottom of the screen. |
numButtons |
Number of buttons displayed on the command toolbar. |
insPtWasEnabled |
If true, the insertion point was enabled before the command toolbar was displayed and should be re-enabled when the command toolbar is erased. If false, the insertion point was disabled. |
gsiWasEnabled |
If true, the Graffiti shift indicator was enabled before the command toolbar was displayed and should be re-enabled when the command toolbar is erased. If false, the Graffiti shift indicator was disabled. |
feedbackMode |
If true, the command toolbar is currently displaying a status message. The status message is displayed to tell the user what command is being performed. If false, the command toolbar is awaiting input. |
buttonsData |
The list of buttons to display on the command toolbar. See MenuCmdBarButtonType. Buttons are stored in this list sequentially with the rightmost button at index 0. Access with MenuCmdBarGetButtonData. |
Compatibility
This structure is defined only if 3.5 New Feature Set is present.
MenuBarPtr

The MenuBarPtr type defines a pointer to a MenuBarType.
typedef MenuBarType *MenuBarPtr;
MenuBarType

The MenuBarType structure defines the menu bar. There is one menu bar per form.
WARNING! Palm, Inc. does not support or provide backward compatibility for the MenuBarType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
typedef struct {
WinHandle barWin;
WinHandle bitsBehind;
WinHandle savedActiveWin;
WinHandle bitsBehindStatus;
MenuBarAttrType attr;
Int16 curMenu;
Int16 curItem;
Int32 commandTick;
Int16 numMenus;
MenuPullDownPtr menus;
} MenuBarType;
Your code should treat the MenuBarType structure as opaque. Do not attempt to change structure member values directly.
Field Descriptions
barWin |
Handle for the window that contains the menu bar. |
bitsBehind |
Handle for the window that contains the region obscured by the menu bar. |
savedActiveWin |
Handle where the currently active window is saved so that it can be restored when the menu is erased. |
bitsBehindStatus |
Handle where the bits behind the status message are saved so that when the message display terminates, the bits can be restored. |
|
The status message is displayed when the user activates the menu through the use of the command keystroke. |
attr |
Menu bar attributes. See MenuBarAttrType. |
curMenu |
Menu number for the currently visible menu. Menus are numbered sequentially starting with 0. The value is preserved when the menu bar is dismissed. A value of noMenuSelection indicates that there is no current pull-down menu. |
curItem |
Item number of the currently highlighted menu item. The items in each menu are numbered sequentially, starting with zero. |
|
A value of noMenuItemSelection indicates that there is no current item selected. |
commandTick |
Tick count at which the status message should be erased. |
numMenus |
Number of pull-down menus on the menu bar. |
menus |
Array of MenuPullDownType structures. |
Compatibility
If 3.5 New Feature Set is present, the bitsBehindStatus and commandTick fields are defined but are not used. Instead, the bitsBehind and timeoutTick fields in MenuCmdBarType define the save-behind window and the timeout value for the command toolbar.
MenuItemType

The MenuItemType structure defines a specific item within a menu. The items array in the MenuPullDownType structure contains one MenuItemType structure for each menu item in the pull-down menu.
If 3.5 New Feature Set is present, you can add a menu item to a pull-down menu programmatically using MenuAddItem.
WARNING! Palm, Inc. does not support or provide backward compatibility for the MenuItemType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
typedef struct {
UInt16 id;
Char command;
UInt8 hidden: 1;
UInt8 reserved: 7;
Char *itemStr;
} MenuItemType;
Field Descriptions
id |
ID value you specified when you created the menu item. This ID value is included as part of the event data of a menuEvent. |
command |
Shortcut key. If you provide shortcuts, make sure that each shortcut is unique among all commands available at that time. |
hidden |
If true, the menu item is hidden. If false, it is displayed. You can set and clear this value using MenuHideItem and MenuShowItem. |
reserved |
Reserved for future use. |
itemStr |
Pointer to the text to display for this menu item, including the 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. |
Compatibility
The hidden and reserved fields are defined only if 3.5 New Feature Set is present.
MenuPullDownPtr

The MenuPullDownPtr type defines a pointer to a MenuPullDownType.
typedef MenuPullDownType *MenuPullDownPtr;
MenuPullDownType

The MenuPullDownType structure defines a specific menu accessed from the menu bar. The menus array in the MenuBarType structure contains one MenuPullDownType structure for each pull-down menu associated with the menu bar.
WARNING! Palm, Inc. does not support or provide backward compatibility for the MenuPullDownType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.
typedef struct {
WinHandle menuWin;
RectangleType bounds;
WinHandle bitsBehind;
RectangleType titleBounds;
Char *title;
UInt16 hidden : 1;
UInt16 numItems : 15;
MenuItemType *items;
} MenuPullDownType;
Field Descriptions
menuWin |
Handle for the window that contains the menu. |
bounds |
Position and size, in pixels, of the pull-down menu. |
bitsBehind |
Handle of a window that contains the region obscured by the menu. |
title |
The menu title (null-terminated string) displayed in the menu bar. |
titleBounds |
Position and size, in pixels, of the title in the menu bar. |
hidden |
If true, the menu is hidden; if false, it is displayed. This field is not currently used. |
numItems |
Number of items in the menu. Separators count as items. |
items |
Array of MenuItemType structures. |
Compatibility
The hidden field is defined only if 3.5 New Feature Set is present.
Menu Constants

Constant |
Value |
Description |
noMenuSelection |
-1 |
The curMenu field of MenuBarType is set to this when there is no currently selected menu. |
noMenuItemSelection |
-1 |
The curItem field of MenuBarType is set to this when there is no currently selected menu item. |
separatorItemSelection |
-2 |
The curItem field of MenuBarType is set to this when a menu separator item is selected. |
MenuSeparatorChar |
'-' |
Special character indicating that the menu item is a bar used to separate groups of related menu items. The first character of the itemStr string in MenuItemType is set to this. |
Menu Resources

The menu bar (MBAR) and pull-down menu (MENU) resources are used jointly to represent a menu object on screen. See "Menus and Menu Bars" in Chapter 2, "Palm OS Resources."
Menu Functions

MenuAddItem

Purpose
Adds an item to the currently active menu.
Prototype
Err MenuAddItem (UInt16 positionId, UInt16 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 | Shortcut key. If you provide 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 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. |
Result
Returns 0 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. |
May display a fatal error message if there is no current menu.
Comments
This function creates a new MenuItemType structure and adds it to the MenuBarType's item list.
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.
Compatibility
Implemented only if 3.5 New Feature Set is present.
MenuCmdBarAddButton

Purpose
Defines a button to be displayed on the command toolbar.
Prototype
Err MenuCmdBarAddButton (UInt8 where, UInt16 bitmapId, MenuCmdBarResultType resultType, UInt32 result, Char *nameP)
Parameters
-> where | Either menuCmdBarOnLeft to add the button to the left of the other buttons on the command toolbar, 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. |
-> bitmapId | Resource ID of the bitmap to display on the button. The bitmap's dimensions should be 13 pixels high by 16 pixels wide. |
-> 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. |
Result
Returns 0 upon success, or one of the following error codes:
menuErrOutOfMemory | There is not enough memory available to perform the operation. |
menuErrTooManyItems | The command toolbar 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 entered the command keystroke and the command toolbar is about to open. Your response should be to add buttons to the toolbar 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 toolbar if it is the current application. If you register for the notification, you receive it each time the command toolbar is displayed, whether your application is active or not.
Note that the command toolbar is allocated each time it is opened and is deallocated when it is erased from the screen.
There is a limited amount of space in which to display buttons on the command toolbar. You should limit the number of buttons to four or five. The maximum allowed by the system is eight, but you should leave space for the status message that appears after the user chooses an action. Buttons should be contextual; for example, the field code only displays a paste button if there is text on the clipboard. Bitmaps for the buttons should be 16 X 13 pixels.
If a field has focus when the command toolbar is opened, the field manager adds buttons for cut, copy, paste, and undo. If your application does not want this default behavior, set the preventFieldButtons field in the menuCmdBarOpenEvent structure to true. (Note that there is no way to prevent the field buttons from being drawn from within a notification handler.)
The following bitmaps for command toolbar buttons are defined in UIResources.h. The system and the built-in applications use these bitmaps to represent the commands listed in the table. Your application should also use them if it performs the same actions. If you use any of these buttons, add them in the order shown from right to left. (For example, BarDeleteBitmap, if used, should always be the rightmost button.)
Bitmap |
Command |
BarDeleteBitmap |
Delete record. |
BarPasteBitmap |
Paste clipboard contents at insertion point. |
BarCopyBitmap |
Copy selection. |
BarCutBitmap |
Cut selection. |
BarUndoBitmap |
Undo previous action. |
BarSecureBitmap |
Show Security dialog. |
BarBeamBitmap |
Beam current record. |
BarInfoBitmap |
Show Info dialog (Launcher). |
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. You can also specify an exact position for the where parameter. The positions are numbered from right to left with the rightmost position being 1. If you specify an exact position, the function leaves space for the other buttons. For example, if you specify position 3 and there are no buttons displayed at positions 1 and 2, there will be blank spots to the right of your button.
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.)
Compatibility
Implemented only if 3.5 New Feature Set is present.
See Also
MenuCmdBarDisplay, MenuCmdBarGetButtonData
MenuCmdBarDisplay

Purpose
Displays the command toolbar.
Prototype
void MenuCmdBarDisplay (void)
Parameters
Result
Returns nothing.
Comments
This function displays the command toolbar when the user enters the command keystroke. You normally do not call this function in your own code. The form manager calls it at the end of its handling of menuCmdBarOpenEvent.
Compatibility
Implemented only if 3.5 New Feature Set is present.
See Also
MenuCmdBarAddButton, MenuCmdBarGetButtonData
MenuCmdBarGetButtonData

Purpose
Gets the data for a given command button.
Prototype
Boolean MenuCmdBarGetButtonData (Int16 buttonIndex, UInt16 *bitmapIdP, MenuCmdBarResultType *resultTypeP, UInt32 *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. |
<- 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. |
Result
Returns true if the information was retrieved successfully, false if there is no command toolbar 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 toolbar. If the command toolbar has not yet been initialized, this function returns false.
Note that the command toolbar 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 sysNotifyMenuCmdBarOpenEvent notification.
Compatibility
Implemented only if 3.5 New Feature Set is present.
See Also
MenuCmdBarDisplay, MenuCmdBarAddButton
MenuDispose

Purpose
Releases any memory allocated to the menu and the command status and restore any saved bits to the screen.
Prototype
void MenuDispose (MenuBarType *menuP)
Parameters
-> menuP | Pointer to the menu object to dispose. (See MenuBarType.) If NULL, this function returns immediately. |
Result
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

Purpose
Draws the current menu bar and the last pull-down that was visible.
Prototype
void MenuDrawMenu (MenuBarType *menuP)
Parameters
Result
Returns nothing.
Comments
Most applications do not need to call this function directly. MenuHandleEvent calls MenuDrawMenu when the user taps the Menu silk-screen button (or taps the form's title on Palm OS 3.5 and higher).
The menu bar and the pull-down menu are drawn in front of all the application windows. The state of the insertion point, the bits that are obscured by the menu bar and the pull-down menu, and the currently active window are saved before the menu is drawn. These are all restored when the menu is erased.
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

Purpose
Erases the menu command status.
Prototype
void MenuEraseStatus (MenuBarType *menuP)
Parameters
-> menuP | Pointer to a MenuBarType, or NULL for the current menu. |
Result
Returns nothing.
Comments
When the user selects a menu command using the command keystroke, the command toolbar or status message is displayed at the bottom of the screen. MenuEraseStatus erases the toolbar or status message.
Under most circumstances, you do not need to call this function explicitly-just 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.
You need to call MenuEraseStatus explicitly only if the command toolbar covers something that is going to be changed by the menu command the user has selected. For example, if the user selects a command that displays a new form, call MenuEraseStatus before executing the command. Also, if the command performs some drawing in the lower portion of the window, call MenuEraseStatus before performing the drawing function.
Compatibility
The exact behavior when a menu shortcut character is entered depends on which version of the operating system is running. In versions prior to release 3.5, the system displays the string "Command:" in the lower-left portion of the screen when the user enters the Graffiti command keystroke.
In Palm OS 3.5 and higher, entering the Graffiti command keystroke displays the command toolbar. This toolbar is the entire width of the screen and it displays buttons that the user can tap instead of entering another keystroke. If the user taps a button or enters a character that matches a shortcut character for an item on the active menu, a status message is displayed in the toolbar while the command is executed. Calling MenuEraseStatus on Palm OS 3.5 and higher deallocates the command toolbar data structure as well as erasing the command toolbar from the screen.
Because the command toolbar takes up more of the display than the pre-Palm OS 3.5 status message, you may find you need to call MenuEraseStatus more frequently in Palm OS 3.5 than in earlier versions.
See Also
MenuInit
MenuGetActiveMenu

Purpose
Returns a pointer to the currently active menu.
Prototype
MenuBarType *MenuGetActiveMenu (void)
Parameters
Result
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 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.
If you want to know if the menu is visible rather than merely active, there are two options:
You can check the visible attribute. For example:
myMenu = MenuGetActiveMenu();
if (myMenu && myMenu->attr.visible) {
// menu is visible
}
You can check for winEnterEvent and winExitEvent.
When the system draws a menu, the menu's window becomes the active drawing window. The system generates a winExitEvent for the previous active drawing window and a winEnterEvent for the menu's window. When the menu is erased, the system generates a winExitEvent for the menu's window and a winEnterEvent for the window that was active before the menu was drawn.
It's common to want to check if the menu is visible in applications that perform custom drawing to a window. Such applications want to make sure that they don't draw on top of the menu. The recommended way to do this is to stop drawing when you receive a winExitEvent matching your drawing window and resume drawing when you receive the corresponding winEnterEvent. For example, the following code is excerpted from the Reptoids example application's main event loop:
EvtGetEvent (&event, TimeUntillNextPeriod());
if (event.eType == winExitEvent) {
if (event.data.winExit.exitWindow ==
(WinHandle) FrmGetFormPtr(MainView)) {
// stop drawing.
}
}
else if (event.eType == winEnterEvent) {
if (event.data.winEnter.enterWindow ==
(WinHandle) FrmGetFormPtr(MainView) &&
event.data.winEnter.enterWindow ==
(WinHandle) FrmGetFirstForm ()) {
// start drawing
}
}
Note that the second method of checking to see if a menu is visible is preferred because it is not specific to menus-your application should stop drawing if any window obscures your drawing window, and it will do so if you check for winEnterEvent and winExitEvent.
See Also
MenuHandleEvent, MenuSetActiveMenu
MenuHandleEvent

Purpose
Handles events in the current menu. This routine handles two types of events, penDownEvent and keyDownEvent.
Prototype
Boolean MenuHandleEvent (MenuBarType *menuP, EventType *event, UInt16 *error)
Parameters
-> menuP | Pointer to a MenuBarType data structure. |
-> event | Pointer to an EventType structure. |
-> error | Error (or 0 if no error). Currently this function always sets error to zero. |
Result
Returns true if the event is handled; that is, if the event is a penDownEvent within the menu bar or the menu, or the event is a keyDownEvent that the menu supports. Returns false on any other event.
Comments
When a penDownEvent is received in the menu bar, MenuHandleEvent tracks the pen until it comes up. If the pen comes up within the bounds of the menu bar, the selected title is inverted and the appropriate pull-down menu is drawn. Any previous pull-down menu is erased. If the pen comes up outside of the menu bar and pull-down menu, the menu is erased.
When a penDownEvent is received in a pull-down menu, MenuHandleEvent tracks the pen until it comes up. If the pen comes up within the bounds of the menu, a menuEvent containing the resource ID of the selected menu item is added to the event queue. If the pen comes up outside of the bounds of the menu and menu bar, the menu is erased.
If a keyDownEvent is received with a vchrMenu, the menu is drawn if it is not visible and erased if it is visible.
If a keyDownEvent is received with a vchrCommand, a command shortcut is in progress. Command shortcuts are handled differently depending on which version of Palm OS is running. On versions earlier than 3.5, the next keyDownEvent is checked to see if it is a valid menu shortcut. If so, a menuEvent is added to the event queue.
If a keyDownEvent is received with a vchrCommand on Palm OS 3.5 and higher, MenuHandleEvent enqueues a menuCmdBarOpenEvent if the command toolbar is not already open. The menuCmdBarOpenEvent provides a chance for applications to add their own buttons to the command toolbar. The next event might be either a keyDownEvent with a character that completes the shortcut or a penDownEvent on one of the buttons on the toolbar. The keyDownEvent is processed as with the earlier releases- if it is a valid menu shortcut, a menuEvent is added to the event queue. If the next event is a penDownEvent, the pen is tracked until it comes up. If the pen comes up within the bounds of a button, the appropriate action is taken. See the description of MenuCmdBarAddButton for more information.
In Palm OS version 3.5 or higher, if either the vchrMenu or the vchrCommand event causes a menu to be activated and initialized for the first time, a menuOpenEvent containing the reason the menu was initialized (menuButtonCause for a vchrMenu or menuCommandCause for a vchrCommand) is added to the event queue, and then the current event is added after it.
MenuHideItem

Purpose
Makes the specified menu item hidden.
Prototype
Boolean MenuHideItem (UInt16 id)
Parameters
-> id | ID of the menu item to hide. |
Result
Returns true if the hidden attribute of the specified item was successfully enabled, 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.
Compatibility
Implemented only if 3.5 New Feature Set is present.
See Also
MenuShowItem
MenuInit

Purpose
Loads a menu resource from a resource file.
Prototype
MenuBarType *MenuInit (UInt16 resourceId)
Parameters
-> resourceId | ID that identifies the menu resource. |
Result
Returns the pointer to a memory block allocated to hold the menu resource (a pointer to a MenuBarType).
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

Purpose
Sets the current menu.
Prototype
MenuBarType *MenuSetActiveMenu (MenuBarType *menuP)
Parameters
-> menuP | Pointer to the memory block that contains the new menu, or NULL for none. |
Result
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

Purpose
Sets the current menu by resource ID.
Prototype
void MenuSetActiveMenuRscID (UInt16 resourceId)
Parameters
-> resourceId | Resource ID of the menu to be made active. |
Result
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.
Compatibility
Implemented only if 2.0 New Feature Set is present.
MenuShowItem

Purpose
Makes the specified menu item visible.
Prototype
Boolean MenuShowItem (UInt16 id)
Parameters
-> id | ID of the menu item to display. |
Result
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.
Compatibility
Implemented only if 3.5 New Feature Set is present.
See Also
MenuHideItem
|