Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 3 - Menu Manager / Menu Manager Reference

Menu Manager Routines / Creating Menus

GetMenu

Use the GetMenu function to create a menu with the title, items, and other characteristics defined in a 'MENU' resource with the specified resource ID. You typically use this function only when you create submenus; you can create all your pull-down menus at once using the GetNewMBar function, and you can create pop-up menus using the standard pop-up control definition function.

FUNCTION GetMenu (resourceID: Integer): MenuHandle;

resourceID

The resource ID of the 'MENU' resource that defines the characteristics of the menu. (You usually use the same number for a menu's resource ID as the number that you specify for the menu ID in the menu resource.)

DESCRIPTION

The GetMenu function creates a menu according to the specified menu resource, and it also creates a menu record for the menu. It reads the menu definition procedure (specified in the menu resource) into memory if it isn't already in memory, and it stores
a handle to the menu definition procedure in the menu record. The GetMenu function does not insert the newly created menu into the current menu list.

After reading the 'MENU' resource, the GetMenu function searches for an 'mctb' resource with the same resource ID as the 'MENU' resource. If GetMenu finds this 'mctb' resource, it uses the information in the 'mctb' resource to add entries for this menu to the application's menu color information table. The GetMenu function uses SetMCEntries to add the entries defined by the 'mctb' resource to the application's menu color information table. If GetMenu doesn't find this 'mctb' resource, it uses the default colors specified in the menu bar entry of the application's menu color information, or, if the menu bar entry doesn't exist, it uses the standard colors for
the menu.

The GetMenu function returns a handle to the menu record of the menu. You can use the returned menu handle to refer to this menu in most Menu Manager routines. If GetMenu is unable to read the menu or menu definition procedure from the resource file, GetMenu returns NIL.

After creating a menu with GetMenu, you can use AppendMenu, InsertMenuItem, AppendResMenu, or InsertResMenu to add more menu items to the menu if necessary.

To add a menu created by GetMenu to a menu list, use the InsertMenu procedure. To update the menu bar with any new menu titles, use the DrawMenuBar procedure.

Storing the definitions of your menus in resources (especially menu titles and menu items) makes your application easier to localize.

WARNING

Menus in a resource must not be purgeable.

SPECIAL CONSIDERATIONS

To release the memory associated with a menu that you read from a resource file using GetMenu, first call DeleteMenu to remove the menu from the menu list and to remove any menu title entry or menu item entries for this menu in the application's menu color information table, then call the Resource Manager procedure ReleaseResource to dispose of the menu's menu record. Use DrawMenuBar to update the menu bar.

WARNING

Call GetMenu only once for a particular menu. If you need the handle of a menu currently in the menu list, use GetMenuHandle or the Resource Manager function GetResource.

SEE ALSO

For a description of the 'MENU' resource, see "The Menu Resource" on page 3-154; for a sample 'MENU' resource in Rez format, see Listing 3-2 on page 3-48. For information on the 'mctb' resource, see "The Menu Color Information Table Resource" on page 3-157.

For details 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. To remove a menu, see the description of DeleteMenu on page 3-111. To update the menu bar, use the DrawMenuBar procedure, described on page 3-115.