Menus
 

 < Home   < Developers   < Development Support   < Documentation

15 Menus


 Table of Contents  |  < Previous  |  Next >  |  Index
   
   

Title -
Palm OS® Programmer's API Reference

Part I: User Interface

15 Menus

Menu Data Structures

MenuBarAttrType

MenuCmdBarButtonType

MenuCmdBarResultType

MenuCmdBarType

MenuBarPtr

MenuBarType

MenuItemType

MenuPullDownPtr

MenuPullDownType

Menu Constants

Menu Resources

Menu Functions

MenuAddItem

MenuCmdBarAddButton

MenuCmdBarDisplay

MenuCmdBarGetButtonData

MenuDispose

MenuDrawMenu

MenuEraseStatus

MenuGetActiveMenu

MenuHandleEvent

MenuHideItem

MenuInit

MenuSetActiveMenu

MenuSetActiveMenuRscID

MenuShowItem

       

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

-> positionIdID of an existing menu item. The new menu item is added after this menu item.
-> idID value to use for the new menu item.
-> cmdShortcut key. If you provide shortcuts, make sure that each shortcut is unique among all commands available at that time.
-> textPPointer 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:

menuErrNoMenuThe textP parameter is NULL.
menuErrSameIdThe menu already contains an item with the ID id.
menuErrNotFoundThe 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

-> whereEither 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.
-> bitmapIdResource ID of the bitmap to display on the button. The bitmap's dimensions should be 13 pixels high by 16 pixels wide.
-> resultTypeThe type of data contained in the result parameter. See MenuCmdBarResultType.
-> resultThe data to send when the user taps this button. This can be a character, a menu item ID, or a notification constant.
-> namePPointer 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:

menuErrOutOfMemoryThere is not enough memory available to perform the operation.
menuErrTooManyItemsThe 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

None

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

-> buttonIndexIndex of the button for which you want to obtain information. Buttons are ordered from right to left, with the rightmost button at index 0.
<- bitmapIdPThe resource ID of the bitmap displayed on the button. Pass NULL if you don't want to retrieve this value.
<- resultTypePThe type of action this button takes. Pass NULL if you don't want to retrieve this value.
<- resultPThe result of tapping the button. Pass NULL if you don't want to retrieve this information.
<- namePThe 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

-> menuPPointer 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

-> menuPPointer to a MenuBarType. Must not be NULL.

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

-> menuPPointer 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

None.

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

-> menuPPointer to a MenuBarType data structure.
-> eventPointer to an EventType structure.
-> errorError (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

-> idID 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

-> resourceIdID 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

-> menuPPointer 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

-> resourceIdResource 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

-> idID 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