|
|
|
|
14
MenusMenu.h. It discusses the following topics:
MenuBarAttrType bit field defines some characteristics of the menu bar.
typedef struct { UInt16 visible : 1; UInt16 commandPending : 1; UInt16 insPtEnabled : 1; UInt16 needsRecalc : 1;} MenuBarAttrType;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.
needsRecalc constant is present only if 3.5 New Feature Set is present.
MenuCmdBarButtonType struct defines a button to be displayed on the command toolbar. The buttonsData field of the typedef struct { UInt16 bitmapId; Char name[menuCmdBarMaxTextLength]; MenuCmdBarResultType resultType; UInt8 reserved; UInt32 result;} MenuCmdBarButtonType;MenuCmdBarButtonType structure as opaque. Do not attempt to change structure member values directly. Instead, use MenuCmdBarAddButton are the same as the fields in the MenuCmdBarButtonType, so there should be no need to alter these fields directly.
MenuCmdBarResultType enum specifies how the result field in the typedef enum { menuCmdBarResultNone, menuCmdBarResultChar, menuCmdBarResultMenuItem, menuCmdBarResultNotify} MenuCmdBarResultType;
MenuCmdBarType struct 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 typedef struct MenuCmdBarType { WinHandle bitsBehind; Int32 timeoutTick; Coord top; Int16 numButtons; Boolean insPtWasEnabled; Boolean gsiWasEnabled; Boolean feedbackMode; MenuCmdBarButtonType *buttonsData;} MenuCmdBarType;MenuCmdBarType structure as opaque. Do not attempt to change structure member values directly.
MenuBarPtr type defines a pointer to a typedef MenuBarType *MenuBarPtr;MenuBarType structure defines the menu bar. There is one menu bar per form.
typedef struct { WinHandle barWin; WinHandle bitsBehind; WinHandle savedActiveWin; WinHandle bitsBehindStatus; MenuBarAttrType attr; Int16 curMenu; Int16 curItem; Int32 commandTick; Int16 numMenus; MenuPullDownPtr menus;} MenuBarType;MenuBarType structure as opaque. Do not attempt to change structure member values directly.
bitsBehindStatus and commandTick fields are defined but are not used. Instead, the bitsBehind and timeoutTick fields in MenuItemType structure defines a specific item within a menu. The items array in the MenuItemType structure for each menu item in the pull-down menu.
typedef struct { UInt16 id; Char command; UInt8 hidden: 1; UInt8 reserved: 7; Char * itemStr;} MenuItemType;
hidden and reserved fields are defined only if 3.5 New Feature Set is present.
MenuPullDownPtr type defines a pointer to a typedef MenuPullDownType * MenuPullDownPtr;MenuPullDownType structure defines a specific menu accessed from the menu bar. The menus array in the MenuPullDownType structure for each pull-down menu associated with the menu bar.
typedef struct { WinHandle menuWin; RectangleType bounds; WinHandle bitsBehind; RectangleType titleBounds; Char * title; UInt16 hidden : 1; UInt16 numItems : 15; MenuItemType *items;} MenuPullDownType;
hidden field is defined only if 3.5 New Feature Set is present.
Err MenuAddItem (UInt16 positionId, UInt16 id, Char cmd, const Char *textP)
-> |
ID of an existing menu item. The new menu item is added after this menu item. |
-> |
ID value to use for the new menu item. |
-> |
Shortcut key. If you provide shortcuts, make sure that each shortcut is unique among all commands available at that time. |
|
To create a separator bar, create a one-character string containing the MenuSeparatorChar constant. |
|
The textP parameter is NULL. |
|
The menu already contains an item with the ID id. |
|
The menu doesn't contain an item with the ID positionId. |
vchrMenu or vchrCommand is generated, and it remains active until a new form (including a modal form or alert panel) is displayed or until Err MenuCmdBarAddButton (UInt8 where, UInt16 bitmapId, MenuCmdBarResultType resultType, UInt32 result, Char *nameP)
-> |
Resource ID of the bitmap to display on the button. The bitmap's dimensions should be 13 pixels high by 16 pixels wide. |
-> |
The type of data contained in the result parameter. See |
-> |
The data to send when the user taps this button. This can be a character, a menu item ID, or a notification constant. |
|
If you supply a text buffer for this parameter, MenuCmdBarAddButton makes a copy of the buffer. |
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.
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.
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.)
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.)
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.
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 resultType is menuCmdBarResultMenuItem and the result is the ID of the menu item that should included in the event.
result is a shortcut character, the 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.
MenuCmdBarAddButton outside of an application, you might not know of any menu items in the active menu (unless your code has added one using void MenuCmdBarDisplay (void)
Boolean MenuCmdBarGetButtonData (Int16 buttonIndex, UInt16 *bitmapIdP, MenuCmdBarResultType *resultTypeP, UInt32 *resultP, Char *nameP)
-> |
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. |
<- |
The resource ID of the bitmap displayed on the button. Pass NULL if you don't want to retrieve this value. |
<- |
The type of action this button takes. Pass NULL if you don't want to retrieve this value. |
<- |
The result of tapping the button. Pass NULL if you don't want to retrieve this information. |
true if the information was retrieved successfully, false if there is no command toolbar or if there is no button at buttonIndex.
false.
MenuCmdBarGetButtonData is in response to a sysNotifyMenuCmdBarOpenEvent notification.
void MenuDispose (MenuBarType *menuP)
-> |
Pointer to the menu object to dispose. (See NULL, this function returns immediately. |
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 void MenuDrawMenu (MenuBarType *menuP)
MenuDrawMenu when the user taps the Menu silk-screen button (or taps the form's title on Palm OS 3.5 and higher).
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.
void MenuEraseStatus (MenuBarType *menuP)
MenuEraseStatus erases the toolbar or status message.
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.
MenuEraseStatus on Palm OS 3.5 and higher deallocates the command toolbar data structure as well as erasing the command toolbar from the screen.
MenuEraseStatus more frequently in Palm OS 3.5 than in earlier versions.
MenuBarType *MenuGetActiveMenu (void)
NULL if there is none.
vchrMenu or vchrCommand is generated, and it remains active until a new form (including a modal form or alert panel) is displayed or until visible attribute. For example:myMenu = MenuGetActiveMenu();if (myMenu && myMenu->attr.visible) { // menu is visible}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.
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 }}winEnterEvent and winExitEvent.
Boolean MenuHandleEvent (MenuBarType *menuP, EventType *event, Uint16 *error)
-> menuP |
Pointer to a MenuBarType data structure. |
-> event |
Pointer to an EventType structure. |
-> error |
Error (or 0 if no error). |
false on any other event.
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.
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.
vchrMenu, the menu is drawn if it is not visible and erased if it is visible.
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 keyDownEvent is received with a vchrCommand on Palm OS 3.5 and higher, MenuHandleEvent enqueues a 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 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 vchrMenu or the vchrCommand event causes a menu to be activated and initialized for the first time, a menuButtonCause for a vchrMenu or menuCommandCause for a vchrCommand) is added to the event queue, and then the current event is added after it.
Boolean MenuHideItem (UInt16 id)
true if the menu item was hidden; false otherwise.
vchrMenu or vchrCommand is generated, and it remains active until a new form (including a modal form or alert panel) is displayed or until MenuBarType *MenuInit (Uint16 resourceId)
MenuBarType *MenuSetActiveMenu (MenuBarType *menuP)
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.
void MenuSetActiveMenuRscID (Uint16 resourceId)
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.
MenuSetActiveMenu.
Boolean MenuShowItem (UInt16 id)
true if the menu item was successfully displayed, false otherwise.
vchrMenu or vchrCommand is generated, and it remains active until a new form (including a modal form or alert panel) is displayed or until |
|
|
|