All DatabasesInside Mac - Basic Toolbox
AppendMenu
AppendMenu Add one or more items to a menu
#include <Menus.h> Menu Manager
void AppendMenu(theMenu, itemText );
MenuHandle theMenu ; handle of a menu
Str255 itemText ; address of length-prefixed text; metachars OK
This should be called "AppendMenuItem". The text of one or more items is
added to the menu. You may put special meta characters embedded in the item
text to provide control over character style, identify an icon or a check mark,
set up a command-key equivalent, and so forth.
theMenu is the handle of a menu obtained via NewMenu or GetMenu. It
leads to a variable-length MenuInfo structure that is allocated on the
heap.
itemText is the address of a length-prefixed, Pascal-style string containing
the text of the item to append to the menu. The string may be blank,
but must not be empty. Multiple items are separated by semi-colons
(;). The following lists special meta characters that may be embedded
in itemText :
Char Dec Hex Description
; 59 0x3B Item separator
Return 13 0x0D Item separator
^ 94 0x5E Next character specifies an icon (its
resource ID is char ASCII value + 208 )
! 33 0x21 Next char is "mark"; e.g., \030 = " ...OR...
when cmd-key is 0x1B, this is a submenu ID
< 60 0x3C Next char specifies style (B,I,U,O, or S)
/ 47 0x2f Next char is a command-key equivalent ...OR...
when next char is 0x1B, this is a submenu title
( 40 0x28 This item is disabled (dimmed)
- 45 0x2d (When first char) "item" is a dotted line
Normally used with ("; e.g. "\p(-
Returns: none
Notes: AppendMenu is normally used when building a menu at run-time (as
opposed to reading it from a resource). The item is added to the end of the
menu, becoming the bottom item. The MenuInfo structure is updated with
the item information and the menu's size is recalculated to the new height
and the width of the widest item.
You may prefer to use InsMenuItem, that does the same thing but is more
flexible, as it allows you to put an item anywhere in the menu.
The meta characters let you predefine special attributes for the menu
items. Use SetItem if you need to use one of them verbatim. All
capabilities of meta characters are duplicated by other Menu Manager
functions:
( DisableItem
! SetItemMark or CheckItem
^ SetItemIcon
< SetItemStyle (Note: the function has more options)
/ SetItemCmd (256K ROMs and later systems)
Some examples:
AppendMenu( fileMenu, "\pNew/N" ); /* New N */
AppendMenu( fileMenu, "\p(-" ); /* dotted-line divider*/
/* always disable via "(" */
AppendMenu( optMenu, "\p!\030Big" ); /* Big */
AppendMenu( optMenu, "\p^1Draw" ); /* insert icon ID 257 */
AppendMenu( optMenu, "\p
AppendMenu( optMenu, "\p */
/* submenu ID=6*/
AppendMenu( optMenu, "\pSubOptions/\033!\006");
/* multiple items */
AppendMenu( fileMenu, "\pNew/N;Open.../O;Save/S;Quit/Q" );
The position in the text of the metacharacter sequence is irrelevant. The
attribute applies to the entire string. For instance, the following are the
same:
AppendMenu( optMenu, "\p
AppendMenu( optMenu, "\pItalic/I
Note that the <" metacharacter (to assign character styles) must be
followed by one of B, I, U, O, or S (bold, italic, underline, outline, or
shadow). However, the condense and extend styles can be assigned using
SetItemStyle.
On hierarchical menus, the item mark identifies the submenu ID. See
SetItemMark, SetItemCmd, and InsMenuItem for related details.
Referenced by (43):