Menu Manager Reference February 26, 2004 Even though Apple has reviewed this manual, APPLE MAKES NO WARRANTY OR Apple Computer, Inc. REPRESENTATION, EITHER EXPRESS OR © 1992, 2004 Apple Computer, Inc. IMPLIED, WITH RESPECT TO THIS MANUAL, ITS QUALITY, ACCURACY, All rights reserved. MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS MANUAL IS SOLD ªAS IS,º AND YOU, THE No part of this publication may be PURCHASER, ARE ASSUMING THE ENTIRE reproduced, stored in a retrieval system, or RISK AS TO ITS QUALITY AND ACCURACY. transmitted, in any form or by any means, IN NO EVENT WILL APPLE BE LIABLE FOR mechanical, electronic, photocopying, DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES recording, or otherwise, without prior RESULTING FROM ANY DEFECT OR written permission of Apple Computer, Inc., INACCURACY IN THIS MANUAL, even if with the following exceptions: Any person advised of the possibility of such damages. is hereby authorized to store documentation THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN on a single computer for personal use only LIEU OF ALL OTHERS, ORAL OR WRITTEN, and to print copies of documentation for EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any personal use provided that the modification, extension, or addition to this documentation contains Apple’s copyright warranty. notice. Some states do not allow the exclusion or limitation of implied warranties or liability for The Apple logo is a trademark of Apple incidental or consequential damages, so the Computer, Inc. above limitation or exclusion may not apply to you. This warranty gives you specific legal Use of the “keyboard” Apple logo rights, and you may also have other rights which vary from state to state. (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled or Apple-licensed computers. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Aqua, Carbon, Mac, Mac OS, MacApp, Macintosh, and QuickDraw are trademarks of Apple Computer, Inc., registered in the United States and other countries. PowerPC and and the PowerPC logo are trademarks of International Business Machines Corporation, used under license therefrom. Simultaneously published in the United States and Canada. Contents Chapter 1 Menu Manager Reference 7 Menu Manager Functions 7 Creating and Disposing of Menus 8 Manipulating the Root Menu 14 Manipulating the Menu Bar 16 Adding and Removing Menus 21 Manipulating and Accessing Menu Characteristics 24 Drawing Menus and Menu Items 34 Adding and Deleting Menu Items 39 Associating Data With Menu Items 41 Enabling Menus and Menu Items 51 Manipulating Menu Item Text 59 Manipulating and Accessing Menu Item Characteristics 68 Responding to Menu Events and User Selections 89 Handling Contextual Menu Plugins 98 Deprecated Functions 100 Menu Manager Callback 129 MenuDefProcPtr 129 Menu Manager Data Types 135 HMenuBarHeader 135 HMenuBarMenu 136 MCEntry 136 MDEFDrawData 140 MDEFDrawItemsData 140 MDEFFindItemData 141 MDEFHiliteItemData 141 MenuBarHandle 142 MenuBarHeader 142 MenuBarMenu 143 MenuCommand 143 MenuCRsrc 143 MenuDefSpec 143 MenuDefUPP 144 MenuHandle 144 MenuID 144 MenuItemDataRec 145 MenuItemID 147 3 © 1992, 2004 Apple Computer, Inc. All Rights Reserved. CONTENTS MenuItemIndex 147 MenuRef 147 MenuTrackingData 147 Menu Manager Constants 148 Menu Manager Result Codes 171 Appendix A Unsupported Functions 173 Document Revision History 175 Index 177 4 © 1992, 2004 Apple Computer, Inc. All Rights Reserved. Tables Chapter 1 Menu Manager Reference 7 Table 1-1 Metacharacters available to pass in AppendMenu 101 Appendix A Unsupported Functions 173 Table A-1 Porting notes for unsupported Menu Manager functions 174 Document Revision History 175 Table RH-1 Document revision history 175 5 © 1992, 2004 Apple Computer, Inc. All Rights Reserved. TABLES 6 © 1992, 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Menu Manager Reference Framework: Carbon/Carbon.h Header: Menus.h You can use the Menu Manager to create and manage the menus in your application. Menus allow the user to view or choose from a list of choices and commands that your application provides. All Mac OS applications should provide these standard menus: the Application menu, the File menu, and the Edit menu. Carbon supports the Menu Manager, with the following changes: ■ Your application must use the functions defined by the Menu Manager whenever it creates and disposes of Menu Manager data structures. Some applications, for example, create menus by using the Resource Manager function GetResource (instead of the Menu Manager function GetMenu) and dispose of them by calling ReleaseResource instead of DisposeMenu. This practice is not supported in Carbon. ■ The MenuInfo structure is opaque in Carbon. You must revise your application so that it accesses Menu Manager data structures only through accessor functions. ■ Menu color information tables are not recommended in Carbon. ■ You are strongly encouraged to adopt the standard Mac OS menu definition functions (also known as MDEFs) in your application. Your menus will then inherit the systemwide appearance and, furthermore, take advantage of other Menu Manager enhancements planned for the future. Note, however, that if you must use custom menu definition procedures, you must compile them as PowerPC-native code. If you are deploying applications for Mac OS X v10.3 and later, you should create your custom menu definitions by creating HIView menu subclasses. Menu Manager Functions Function descriptions are grouped by the tasks for which you use the functions. For an alphabetical list of functions, go to the API index at the end of the document. Menu Manager Functions 7 © 1992, 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Menu Manager Reference Creating and Disposing of Menus CreateNewMenu Creates a new, untitled, empty menu. OSStatus CreateNewMenu ( MenuID inMenuID, MenuAttributes inMenuAttributes, MenuRef * outMenuRef ); Parameter Descriptions inMenuID The menu ID to use for the new menu. Note that zero is a valid ID in Carbon. inMenuAttributes The menu attributes to use for the new menu. See ªMenu Item Attribute Constantsº (page 154) for a list of possible values. outMenuRef On exit, contains the new menu. function result A result code. See ªMenu Manager Result Codesº (page 171). Discussion Unless you need to create new menus on-the-fly, you should not use functions like CreateNewMenu that create menus programmatically. Instead, you should define menus in Interface Builder, store them as nib files, and then call the Interface Builder Services function CreateMenuFromNib to create them. CreateNewMenu is preferred over NewMenu because it allows you to specify the menu©s attributes and it does not require you to specify a Str255-based menu title. To set the menu title, you should use SetMenuTitleWithCFString (page 25). Availability Available in CarbonLib 1.0 and later. Available in Mac OS X v10.0 and later. Header: Menus.h DuplicateMenu Creates a new menu that is a copy of another menu. OSStatus DuplicateMenu ( MenuRef inSourceMenu, MenuRef * outMenu ); Parameter Descriptions inSourceMenu The menu to duplicate. 8 Menu Manager Functions © 1992, 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Menu Manager Reference outMenu On exit, a copy of the source menu. function result A result code. See ªMenu Manager Result Codesº (page 171). Discussion Unlike RetainMenu (page 9), DuplicateMenu creates an entirely new menu that is an exact copy of the original menu. The menu definition for the new menu will receive an initialization message/event after the menu has been fully created. Availability Available in CarbonLib 1.1 and later. Available in Mac OS X v10.0 and later. Header: Menus.h RetainMenu Increments the reference count of a menu. OSStatus RetainMenu ( MenuRef inMenu ); Parameter Descriptions inMenu The menu whose reference count you want to increment. function result A result code. See ªMenu Manager Result Codesº (page 171). Discussion RetainMenu does not create a new menu. It simply adds one to the reference count. Version Notes In Mac OS X v10.2 and later, all menus are Core Foundation CFTypes, so you can optionally call CFRetain instead of RetainMenu. Availability Available in CarbonLib 1.1 and later. Available in Mac OS X v10.0 and later. Header: Menus.h ReleaseMenu Decrements the retain count of a menu. OSStatus ReleaseMenu ( MenuRef inMenu ); Menu Manager Functions 9 © 1992, 2004 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 Menu Manager Reference Parameter Descriptions inMenu The menu whose retain count to decrement. If the retain count falls to zero, the menu is destroyed. function result A result code. See ªMenu Manager Result Codesº (page 171). Discussion The reference that you pass in the theMenu parameter is not valid after DisposeMenu returns. This function is identical to DisposeMenu (page 10). Version Notes In Mac OS X v10.2 and later, all menus are Core Foundation CFTypes, so you can optionally call CFRelease instead of ReleaseMenu. Availability Available in CarbonLib 1.1 and later. Available in Mac OS X v10.0 and later. Header: Menus.h DisposeMenu Decrements the retain count of a menu. void DisposeMenu ( MenuRef theMenu ); Parameter Descriptions theMenu The menu whose retain count to decrement. If the retain count falls to zero, the menu is destroyed. Discussion The reference that you pass in the theMenu parameter is not valid after DisposeMenu returns. This function is identical to ReleaseMenu (page 9). Availability Available in CarbonLib 1.0 and later when running Mac OS 8.1 or later.