Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 3 - Menu Manager / Menu Manager Reference

Menu Manager Routines / Responding to the User's Choice of a Menu Command

MenuKey

If the user presses another key while holding down the Command key, call the MenuKey function to determine if the keyboard combination maps to the keyboard equivalent of a menu item in a menu in the current menu list.

FUNCTION MenuKey (ch: Char): LongInt; 

ch

The 1-byte character representing the key pressed by the user in combination with the Command key.

DESCRIPTION

The MenuKey function maps the given character to the menu and menu item with that keyboard equivalent. The MenuKey function returns as its function result a value that indicates the menu ID and menu item that has the keyboard equivalent corresponding to the given character.

The MenuKey function does not distinguish between uppercase and lowercase letters. It takes the 1-byte character passed to it and calls the UpperText procedure (which provides localizable uppercase conversion of the character). Thus, MenuKey translates any lowercase character to uppercase when comparing a keyboard event to keyboard equivalents. This allows a user to invoke a keyboard equivalent command, such as the Copy command, by pressing the Command key and "c" or "C". For consistency between applications, you should define the keyboard equivalents of your commands so that they appear in uppercase in your menus.

If the given character maps to an enabled menu item in the current menu list, MenuKey highlights the menu title of the chosen menu, returns the menu ID in the high-order word of its function result, and returns the chosen menu item in the low-order word of its function result. After performing the chosen task, your application should unhighlight the menu title using the HiliteMenu procedure.

If the given character does not map to an enabled menu item in the current menu list, MenuKey returns 0 in its high-order word and the low-order word is undefined.

If the given character maps to a menu item in a menu that a desk accessory has inserted into your application's menu list, MenuSelect uses the SystemMenu procedure to process this occurrence and returns 0 to your application in the high-order word.

You should not define menu items with identical keyboard equivalents. The MenuKey function scans the menus from right to left and the items from top to bottom. If you have defined more than one menu item with identical keyboard equivalents, MenuKey returns the first one it finds.

The MenuKey function first searches the regular portion of the current menu list for a menu item with a keyboard equivalent matching the given key. If it doesn't find one there, it searches the submenu portion of the current menu list. If the given key maps to a menu item in a submenu, MenuKey highlights the menu title in the menu bar that the user would normally pull down to begin traversing to the submenu. Your application should perform the desired command and then unhighlight the menu title.

You shouldn't assign a Command-Shift-number key sequence to a menu item as its keyboard equivalent; Command-Shift-number key sequences are reserved for use as 'FKEY' resources. Command-Shift-number key sequences are not returned to your application, but instead are processed by the Event Manager. The Event Manager invokes the 'FKEY' resource with a resource ID that corresponds to the number that activates it.

Apple reserves the Command-key codes $1B (Control-[ ) through $1F (Control-_ ) to indicate meanings other than keyboard equivalents. MenuKey ignores these character codes and returns a function result of 0 if you specify any of these values in the ch parameter. Your application should not use these character codes for its own use.

The global variable TheMenu contains the ID of the currently highlighted menu in the menu bar. If the user chooses an item from a submenu, TheMenu contains the menu ID of the submenu, not the menu to which the submenu is attached.

WARNING

Do not define a "circular" hierarchical menu--that is, a hierarchical menu in which a submenu has a submenu whose submenu is
a hierarchical menu higher in the chain. If MenuKey detects a circular hierarchical menu, it creates a system error with error number 86.

SEE ALSO

To unhighlight a menu, use the HiliteMenu procedure, described on page 3-121. To provide support for keyboard equivalents other than Command-key equivalents, see the discussion of 'KCHR' resources in Inside Macintosh: Text.