Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 3 - Menu Manager / Menu Manager Reference

Menu Manager Routines / Creating Menus

NewMenu

You can use the NewMenu function to create an empty menu with a specified title and menu ID. In most cases you should store information about your menus (such as their titles, items, and characteristics) in resources; use the GetMenu or GetNewMBar function to create menus from resource definitions.

FUNCTION NewMenu (menuID: Integer; menuTitle: Str255): MenuHandle;

menuID

The menu ID of the menu. (Note that this is not the resource ID of a 'MENU' resource.) The menu ID is a number that identifies the menu. Use positive menu IDs for menus belonging to your application. Use negative menu IDs for desk accessories (except for submenus of a desk accessory). Submenus must have menu IDs from 1 through 255. For submenus of an application, use menu IDs from 1 through 235; for submenus of a desk accessory, use menu IDs from 236 through 255. Apple reserves the menu ID of 0.

menuTitle

The title of the new menu. Note that in most cases you should store
the titles of menus in resources, so that your menu titles can be more easily localized.

DESCRIPTION

The NewMenu function creates a menu with the specified title, assigns it the specified menu ID, creates a menu record for the menu, and returns a handle to the menu record. It sets up the menu record to use the standard menu definition procedure (and it reads the standard menu definition procedure into memory if it isn't already there). The NewMenu function does not insert the newly created menu into the current menu list.

After creating a menu with NewMenu, use AppendMenu, InsertMenuItem, AppendResMenu, or InsertResMenu to add menu items to the menu. To add a menu created by NewMenu to the current menu list, use the InsertMenu procedure. To update the menu bar with any new menu titles, use the DrawMenuBar procedure.

SPECIAL CONSIDERATIONS

To release the memory associated with a menu that you created using NewMenu, first
call DeleteMenu to remove the menu from the current menu list and to remove any entries for this menu in your application's menu color information table; then call DisposeMenu to dispose of the menu's menu record. After disposing of a menu, use DrawMenuBar to update the menu bar.

If the NewMenu function is unable to create the menu record, it returns NIL as its function result.

SEE ALSO

For information on how to add items to a menu, see the description of AppendMenu on page 3-126, InsertMenuItem on page 3-128, AppendResMenu on page 3-130, and InsertResMenu on page 3-131. For information on InsertMenu, see page 3-110. To dispose of a menu, see the description of DeleteMenu on page 3-111 and DisposeMenu on page 3-142.