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

15    Menus

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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

For more information on menus, see the section "Menus" in the Palm OS Programmer's Companion, vol. I.

Menu Data Structures ^TOP^

MenuBarAttrType Struct ^TOP^

Purpose

The MenuBarAttrType bit field defines some characteristics of the menu bar.


WARNING! PalmSource, 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.

Prototype

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.

Fields

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 Struct ^TOP^

Purpose

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! PalmSource, 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.

Prototype

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.

Fields

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 Enum ^TOP^

Purpose

The MenuCmdBarResultType enum specifies how the result field in the MenuCmdBarButtonType structure should be interpreted.

Prototype

typedef enum {
menuCmdBarResultNone,
menuCmdBarResultChar,
menuCmdBarResultMenuItem,
menuCmdBarResultNotify
} MenuCmdBarResultType;

Constants

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 Struct ^TOP^

Purpose

The MenuCmdBarType structure defines the command toolbar. This command toolbar is allocated and displayed when the user draws the shortcut stroke in the input area. It is deallocated when MenuEraseStatus() is called, which occurs most frequently when the timeout value has elapsed.


WARNING! PalmSource, 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.

Prototype

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.

Fields

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 shift indicator was enabled before the command toolbar was displayed and should be re-enabled when the command toolbar is erased. If false, the 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 Typedef ^TOP^

Purpose

The MenuBarPtr type defines a pointer to a MenuBarType.

Prototype

typedef MenuBarType *MenuBarPtr;

MenuBarType Struct ^TOP^

Purpose

The MenuBarType structure defines the menu bar. There is one menu bar per form.


WARNING! PalmSource, 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.

Prototype

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.

Fields

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 Struct ^TOP^

Purpose

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! PalmSource, 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.

Prototype

typedef struct {
UInt16 id;
Char command;
UInt8 hidden: 1;
UInt8 reserved: 7;
Char *itemStr;
} MenuItemType;

Fields

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 Typedef ^TOP^

Purpose

The MenuPullDownPtr type defines a pointer to a MenuPullDownType.

Prototype

typedef MenuPullDownType *MenuPullDownPtr;

MenuPullDownType Struct ^TOP^

Purpose

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! PalmSource, 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.

Prototype

typedef struct {
WinHandle menuWin;
RectangleType bounds;
WinHandle bitsBehind;
RectangleType titleBounds;
Char *title;
UInt16 hidden : 1;
UInt16 numItems : 15;
MenuItemType *items;
} MenuPullDownType;

Fields

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 ^TOP^

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 ^TOP^

The menu bar (MBAR) and pull-down menu (MENU) resources are used jointly to represent a menu object on screen. See Palm OS User Interface Guidelines for more information.

Menu Functions ^TOP^

MenuAddItem Function ^TOP^

Purpose

Adds an item to the currently active menu.

Declared In

Menu.h

Prototype

Err MenuAddItem (
   UInt16positionId,
   UInt16id,
   Charcmd,
   constChar*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.

Returns

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 Function ^TOP^

Purpose

Defines a button to be displayed on the command toolbar.

Declared In

Menu.h

Prototype

Err MenuCmdBarAddButton (
   UInt8where,
   UInt16bitmapId,
   MenuCmdBarResultTyperesultType,
   UInt32result,
   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.
resultType
The type of data contained in the result parameter. See MenuCmdBarResultType.
result
The data to send when the user taps this button. This can be a character, a menu item ID, or a notification constant.
nameP
Pointer to the text to display in the status message if the user taps the button. If NULL, the text is taken from the menu item that matches the ID or shortcut character contained in result, if a match is found.
If you supply a text buffer for this parameter, MenuCmdBarAddButton makes a copy of the buffer.

Returns

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 Function ^TOP^

Purpose

Displays the command toolbar.

Declared In

Menu.h

Prototype

void MenuCmdBarDisplay (
   void
)

Parameters

None

Returns

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 Function ^TOP^

Purpose

Gets the data for a given command button.

Declared In

Menu.h

Prototype

Boolean MenuCmdBarGetButtonData(
   Int16buttonIndex,
   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.

Returns

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 Function ^TOP^

Purpose

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

Declared In

Menu.h

Prototype

void MenuDispose (
   MenuBarType*menuP
)

Parameters

menuP
Pointer to the menu object to dispose. (See MenuBarType.) If NULL, this function returns immediately.

Returns

Returns nothing.

Comments

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

See Also

MenuInit(), MenuDrawMenu()

MenuDrawMenu Function ^TOP^

Purpose

Draws the current menu bar and the last pull-down that was visible.

Declared In

Menu.h

Prototype

void MenuDrawMenu (
   MenuBarType*menuP
)

Parameters

menuP
Pointer to a MenuBarType. Must not be NULL.

Returns

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 Function ^TOP^

Purpose

Erases the menu command status.

Declared In

Menu.h

Prototype

void MenuEraseStatus (
   MenuBarType*menuP
)

Parameters

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

Returns

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® or Graffiti 2 command stroke.

In Palm OS 3.5 and higher, entering the command stroke 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 Function ^TOP^

Purpose

Returns a pointer to the currently active menu.

Declared In

Menu.h

Prototype

MenuBarType*MenuGetActiveMenu (
   void
)

Parameters

None.

Returns

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.

Applications that perform custom drawing to a window often check to see if the menu is visible to ensure that they don't draw on top of the menu. See "Checking Menu Visibility" of the Palm OS Programmer's Companion, vol. I for instructions on how to verify a menu's visibility.

See Also

MenuHandleEvent(), MenuSetActiveMenu()

MenuHandleEvent Function ^TOP^

Purpose

Handles events in the current menu. This routine handles two types of events, penDownEvent and keyDownEvent.

Declared In

Menu.h

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.

Returns

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 Function ^TOP^

Purpose

Makes the specified menu item hidden.

Declared In

Menu.h

Prototype

Boolean MenuHideItem (
   UInt16id
)

Parameters

id
ID of the menu item to hide.

Returns

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 Function ^TOP^

Purpose

Loads a menu resource from a resource file.

Declared In

Menu.h

Prototype

MenuBarType*MenuInit (
   UInt16resourceId
)

Parameters

resourceId
ID that identifies the menu resource.

Returns

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 Function ^TOP^

Purpose

Sets the current menu.

Declared In

Menu.h

Prototype

MenuBarType*MenuSetActiveMenu(
   MenuBarType*menuP
)

Parameters

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

Returns

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

Comments

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

See Also

MenuGetActiveMenu()

MenuSetActiveMenuRscID Function ^TOP^

Purpose

Sets the current menu by resource ID.

Declared In

Menu.h

Prototype

void MenuSetActiveMenuRscID (
   UInt16resourceId
)

Parameters

resourceId
Resource ID of the menu to be made active.

Returns

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 Function ^TOP^

Purpose

Makes the specified menu item visible.

Declared In

Menu.h

Prototype

Boolean MenuShowItem (
   UInt16id
)

Parameters

id
ID of the menu item to display.

Returns

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()