Menus.h File Reference

Menu Manager Interfaces. More...

#include <MacTypes.h>
#include <Events.h>
#include <Quickdraw.h>
#include <Fonts.h>
#include <TextCommon.h>
#include <Processes.h>
#include <AppleEvents.h>
#include <Collections.h>
#include <MacErrors.h>
#include <CFString.h>
#include <CFUUID.h>

Go to the source code of this file.

Data Structures
struct	MenuInfo
struct	MCEntry
struct	MenuCRsrc
struct	MenuTrackingData
struct	MDEFHiliteItemData
struct	MDEFDrawData
struct	MDEFFindItemData
struct	MDEFDrawItemsData
struct	MenuItemDataRec
struct	MenuDefSpec
struct	ContextualMenuInterfaceStruct

Macros
#define	NewMenuDefUPP(userRoutine)
#define	DisposeMenuDefUPP(userUPP)   DisposeRoutineDescriptor(userUPP)
#define	InvokeMenuDefUPP(message, theMenu, menuRect, hitPt, whichItem, userUPP)
#define	NewMenuDefProc(userRoutine)   NewMenuDefUPP(userRoutine)
#define	CallMenuDefProc(userRoutine, message, theMenu, menuRect, hitPt, whichItem)    InvokeMenuDefUPP(message, theMenu, menuRect, hitPt, whichItem, userRoutine)
#define	NewMenuBarDefUPP(userRoutine)
#define	NewMenuHookUPP(userRoutine)
#define	NewMBarHookUPP(userRoutine)
#define	DisposeMenuBarDefUPP(userUPP)   DisposeRoutineDescriptor(userUPP)
#define	DisposeMenuHookUPP(userUPP)   DisposeRoutineDescriptor(userUPP)
#define	DisposeMBarHookUPP(userUPP)   DisposeRoutineDescriptor(userUPP)
#define	InvokeMenuBarDefUPP(selector, message, parameter1, parameter2, userUPP)
#define	InvokeMenuHookUPP(userUPP)    CALL_ZERO_PARAMETER_UPP((userUPP), uppMenuHookProcInfo)
#define	InvokeMBarHookUPP(menuRect, userUPP)    (short)CALL_ONE_PARAMETER_UPP((userUPP), uppMBarHookProcInfo, (menuRect))
#define	NewMenuBarDefProc(userRoutine)   NewMenuBarDefUPP(userRoutine)
#define	NewMenuHookProc(userRoutine)   NewMenuHookUPP(userRoutine)
#define	NewMBarHookProc(userRoutine)   NewMBarHookUPP(userRoutine)
#define	CallMenuBarDefProc(userRoutine, selector, message, parameter1, parameter2)    InvokeMenuBarDefUPP(selector, message, parameter1, parameter2, userRoutine)
#define	CallMenuHookProc(userRoutine)   InvokeMenuHookUPP(userRoutine)
#define	CallMBarHookProc(userRoutine, menuRect)    InvokeMBarHookUPP(menuRect, userRoutine)
#define	CountMenuItems(theMenu)   (CountMItems(theMenu))
#define	GetMenuRef   GetMenuHandle
#define	SetMenuFlashCount(count)   (SetMenuFlash(count))
#define	MacCheckMenuItem(theMenu, item, checked)    (CheckItem(theMenu, item, checked))

Typedefs
typedef UInt32	MenuAttributes
typedef UInt32	MenuItemAttributes
typedef UInt32	MenuTrackingMode
typedef UInt32	MenuEventOptions
typedef SInt16	MenuID
typedef UInt16	MenuItemIndex
typedef UInt32	MenuCommand
typedef struct MenuInfo	MenuInfo
typedef MenuInfo *	MenuPtr
typedef MenuPtr *	MenuHandle
typedef MenuHandle	MenuRef
typedef Handle	MenuBarHandle
typedef struct MCEntry	MCEntry
typedef MCEntry *	MCEntryPtr
typedef MCEntry	MCTable[1]
typedef MCEntry *	MCTablePtr
typedef MCTablePtr *	MCTableHandle
typedef struct MenuCRsrc	MenuCRsrc
typedef MenuCRsrc *	MenuCRsrcPtr
typedef MenuCRsrcPtr *	MenuCRsrcHandle
typedef struct MenuTrackingData	MenuTrackingData
typedef MenuTrackingData *	MenuTrackingDataPtr
typedef struct MDEFHiliteItemData	MDEFHiliteItemData
typedef MDEFHiliteItemData *	MDEFHiliteItemDataPtr
typedef MDEFHiliteItemData	HiliteMenuItemData
typedef MDEFHiliteItemDataPtr	HiliteMenuItemDataPtr
typedef struct MDEFDrawData	MDEFDrawData
typedef MDEFDrawData *	MDEFDrawDataPtr
typedef struct MDEFFindItemData	MDEFFindItemData
typedef MDEFFindItemData *	MDEFFindItemDataPtr
typedef struct MDEFDrawItemsData	MDEFDrawItemsData
typedef MDEFDrawItemsData *	MDEFDrawItemsDataPtr
typedef UInt64	MenuItemDataFlags
typedef struct MenuItemDataRec	MenuItemDataRec
typedef MenuItemDataRec *	MenuItemDataPtr
typedef UInt32	MenuItemID
typedef MenuRef	theMenu
typedef MenuRef Rect *	menuRect
typedef MenuRef Rect Point	hitPt
typedef MenuRef Rect Point short *	whichItem
typedef short	message
typedef short short	parameter1
typedef short short long	parameter2
typedef UInt32	MenuDefType
typedef struct MenuDefSpec	MenuDefSpec
typedef MenuDefSpec *	MenuDefSpecPtr
typedef struct ContextualMenuInterfaceStruct	ContextualMenuInterfaceStruct

Enumerations
enum	{ noMark = 0 }
enum	{   kMenuDrawMsg = 0 , kMenuSizeMsg = 2 , kMenuPopUpMsg = 3 , kMenuCalcItemMsg = 5 ,   kMenuThemeSavvyMsg , mDrawMsg = 0 , mSizeMsg = 2 , mPopUpMsg = 3 ,   mCalcItemMsg = 5 }
enum	{ mChooseMsg = 1 , mDrawItemMsg = 4 , kMenuChooseMsg = 1 , kMenuDrawItemMsg = 4 }
enum	{ kThemeSavvyMenuResponse = 0x7473 }
enum	{   kMenuInitMsg = 8 , kMenuDisposeMsg = 9 , kMenuFindItemMsg = 10 , kMenuHiliteItemMsg = 11 ,   kMenuDrawItemsMsg = 12 }
enum	{   textMenuProc = 0 , hMenuCmd = 27 , hierMenu = -1 , kInsertHierarchicalMenu = -1 ,   mctAllItems = -98 , mctLastIDIndic = -99 }
enum	{ kMenuStdMenuProc = 63 , kMenuStdMenuBarProc = 63 }
enum	{   kMenuNoModifiers = 0 , kMenuShiftModifier = (1 << 0) , kMenuOptionModifier = (1 << 1) , kMenuControlModifier = (1 << 2) ,   kMenuNoCommandModifier = (1 << 3) }
enum	{   kMenuNoIcon = 0 , kMenuIconType = 1 , kMenuShrinkIconType = 2 , kMenuSmallIconType = 3 ,   kMenuColorIconType = 4 , kMenuIconSuiteType = 5 , kMenuIconRefType = 6 , kMenuCGImageRefType = 7 ,   kMenuSystemIconSelectorType , kMenuIconResourceType }
enum	{   kMenuNullGlyph = 0x00 , kMenuTabRightGlyph , kMenuTabLeftGlyph , kMenuEnterGlyph = 0x04 ,   kMenuShiftGlyph = 0x05 , kMenuControlGlyph = 0x06 , kMenuOptionGlyph = 0x07 , kMenuSpaceGlyph = 0x09 ,   kMenuDeleteRightGlyph , kMenuReturnGlyph = 0x0B , kMenuReturnR2LGlyph = 0x0C , kMenuNonmarkingReturnGlyph = 0x0D ,   kMenuPencilGlyph = 0x0F , kMenuDownwardArrowDashedGlyph = 0x10 , kMenuCommandGlyph = 0x11 , kMenuCheckmarkGlyph = 0x12 ,   kMenuDiamondGlyph = 0x13 , kMenuAppleLogoFilledGlyph = 0x14 , kMenuParagraphKoreanGlyph = 0x15 , kMenuDeleteLeftGlyph ,   kMenuLeftArrowDashedGlyph = 0x18 , kMenuUpArrowDashedGlyph = 0x19 , kMenuRightArrowDashedGlyph = 0x1A , kMenuEscapeGlyph = 0x1B ,   kMenuClearGlyph = 0x1C , kMenuLeftDoubleQuotesJapaneseGlyph , kMenuRightDoubleQuotesJapaneseGlyph , kMenuTrademarkJapaneseGlyph = 0x1F ,   kMenuBlankGlyph = 0x61 , kMenuPageUpGlyph = 0x62 , kMenuCapsLockGlyph = 0x63 , kMenuLeftArrowGlyph = 0x64 ,   kMenuRightArrowGlyph = 0x65 , kMenuNorthwestArrowGlyph = 0x66 , kMenuHelpGlyph = 0x67 , kMenuUpArrowGlyph = 0x68 ,   kMenuSoutheastArrowGlyph = 0x69 , kMenuDownArrowGlyph = 0x6A , kMenuPageDownGlyph = 0x6B , kMenuAppleLogoOutlineGlyph = 0x6C ,   kMenuContextualMenuGlyph = 0x6D , kMenuPowerGlyph = 0x6E , kMenuF1Glyph = 0x6F , kMenuF2Glyph = 0x70 ,   kMenuF3Glyph = 0x71 , kMenuF4Glyph = 0x72 , kMenuF5Glyph = 0x73 , kMenuF6Glyph = 0x74 ,   kMenuF7Glyph = 0x75 , kMenuF8Glyph = 0x76 , kMenuF9Glyph = 0x77 , kMenuF10Glyph = 0x78 ,   kMenuF11Glyph = 0x79 , kMenuF12Glyph = 0x7A , kMenuF13Glyph = 0x87 , kMenuF14Glyph = 0x88 ,   kMenuF15Glyph = 0x89 , kMenuControlISOGlyph = 0x8A }
enum	{ kMenuAttrExcludesMarkColumn = (1 << 0) , kMenuAttrAutoDisable = (1 << 2) , kMenuAttrUsePencilGlyph = (1 << 3) }
enum	{   kMenuItemAttrDisabled = (1 << 0) , kMenuItemAttrIconDisabled = (1 << 1) , kMenuItemAttrSubmenuParentChoosable = (1 << 2) , kMenuItemAttrDynamic = (1 << 3) ,   kMenuItemAttrNotPreviousAlternate = (1 << 4) , kMenuItemAttrHidden = (1 << 5) , kMenuItemAttrSeparator = (1 << 6) , kMenuItemAttrSectionHeader = (1 << 7) ,   kMenuItemAttrIgnoreMeta = (1 << 8) , kMenuItemAttrAutoRepeat = (1 << 9) , kMenuItemAttrUseVirtualKey = (1 << 10) , kMenuItemAttrCustomDraw = (1 << 11) }
enum	{ kMenuTrackingModeMouse = 1 , kMenuTrackingModeKeyboard = 2 }
enum	{ kMenuEventIncludeDisabledItems = 0x0001 , kMenuEventQueryOnly = 0x0002 , kMenuEventDontCheckSubmenus = 0x0004 }
enum	{   kMenuItemDataText = (1 << 0) , kMenuItemDataMark = (1 << 1) , kMenuItemDataCmdKey = (1 << 2) , kMenuItemDataCmdKeyGlyph = (1 << 3) ,   kMenuItemDataCmdKeyModifiers = (1 << 4) , kMenuItemDataStyle = (1 << 5) , kMenuItemDataEnabled = (1 << 6) , kMenuItemDataIconEnabled = (1 << 7) ,   kMenuItemDataIconID = (1 << 8) , kMenuItemDataIconHandle = (1 << 9) , kMenuItemDataCommandID = (1 << 10) , kMenuItemDataTextEncoding = (1 << 11) ,   kMenuItemDataSubmenuID = (1 << 12) , kMenuItemDataSubmenuHandle = (1 << 13) , kMenuItemDataFontID = (1 << 14) , kMenuItemDataRefcon = (1 << 15) ,   kMenuItemDataAttributes = (1 << 16) , kMenuItemDataCFString = (1 << 17) , kMenuItemDataProperties = (1 << 18) , kMenuItemDataIndent = (1 << 19) ,   kMenuItemDataCmdVirtualKey = (1 << 20) , kMenuItemDataAllDataVersionOne = 0x000FFFFF , kMenuItemDataAllDataVersionTwo }
enum	{ uppMenuDefProcInfo = 0x0000FF80 }
enum	{ uppMenuBarDefProcInfo = 0x00003AB0 }
enum	{ uppMenuHookProcInfo = 0x00000000 }
enum	{ uppMBarHookProcInfo = 0x000000CF }
enum	{ kMenuDefProcPtr = 0 }
enum	{ kMenuPropertyPersistent }
enum	{ kHierarchicalFontMenuOption = 0x00000001 }
enum	{ gestaltContextualMenuAttr = FOUR_CHAR_CODE('cmnu') , gestaltContextualMenuUnusedBit = 0 , gestaltContextualMenuTrapAvailable = 1 }
enum	{ kCMHelpItemNoHelp = 0 , kCMHelpItemAppleGuide = 1 , kCMHelpItemOtherHelp = 2 }
enum	{ kCMNothingSelected = 0 , kCMMenuItemSelected = 1 , kCMShowHelpSelected = 3 }

Functions
typedef	CALLBACK_API (void, MenuDefProcPtr)(short message
typedef	STACK_UPP_TYPE (MenuDefProcPtr) MenuDefUPP
MenuDefUPP	NewMenuDefUPP (MenuDefProcPtr userRoutine)
void	DisposeMenuDefUPP (MenuDefUPP userUPP)
void	InvokeMenuDefUPP (short message, MenuRef theMenu, Rect *menuRect, Point hitPt, short *whichItem, MenuDefUPP userUPP)
typedef	CALLBACK_API (long, MenuBarDefProcPtr)(short selector
typedef	CALLBACK_API (void, MenuHookProcPtr)(void)
typedef	CALLBACK_API_REGISTER68K (short, MBarHookProcPtr,(Rect *menuRect))
typedef	STACK_UPP_TYPE (MenuBarDefProcPtr) MenuBarDefUPP
typedef	STACK_UPP_TYPE (MenuHookProcPtr) MenuHookUPP
typedef	REGISTER_UPP_TYPE (MBarHookProcPtr) MBarHookUPP
MenuBarDefUPP	NewMenuBarDefUPP (MenuBarDefProcPtr userRoutine)
MenuHookUPP	NewMenuHookUPP (MenuHookProcPtr userRoutine)
MBarHookUPP	NewMBarHookUPP (MBarHookProcPtr userRoutine)
void	DisposeMenuBarDefUPP (MenuBarDefUPP userUPP)
void	DisposeMenuHookUPP (MenuHookUPP userUPP)
void	DisposeMBarHookUPP (MBarHookUPP userUPP)
long	InvokeMenuBarDefUPP (short selector, short message, short parameter1, long parameter2, MenuBarDefUPP userUPP)
void	InvokeMenuHookUPP (MenuHookUPP userUPP)
short	InvokeMBarHookUPP (Rect *menuRect, MBarHookUPP userUPP)
void	InitProcMenu (short resID)
void	InitMenus (void)
MenuRef	NewMenu (MenuID menuID, ConstStr255Param menuTitle)
MenuRef	MacGetMenu (short resourceID)
void	DisposeMenu (MenuRef theMenu)
void	CalcMenuSize (MenuRef theMenu)
UInt16	CountMItems (MenuRef theMenu)
	Find how many items are in a menu. More...
OSStatus	GetMenuFont (MenuRef menu, SInt16 *outFontID, UInt16 *outFontSize)
OSStatus	SetMenuFont (MenuRef menu, SInt16 inFontID, UInt16 inFontSize)
Boolean	GetMenuExcludesMarkColumn (MenuRef menu)
OSStatus	SetMenuExcludesMarkColumn (MenuRef menu, Boolean excludesMark)
OSStatus	RegisterMenuDefinition (SInt16 inResID, MenuDefSpecPtr inDefSpec)
OSStatus	CreateNewMenu (MenuID inMenuID, MenuAttributes inMenuAttributes, MenuRef *outMenuRef)
OSStatus	CreateCustomMenu (const MenuDefSpec *inDefSpec, MenuID inMenuID, MenuAttributes inMenuAttributes, MenuRef *outMenuRef)
Boolean	IsValidMenu (MenuRef inMenu)
ItemCount	GetMenuRetainCount (MenuRef inMenu)
OSStatus	RetainMenu (MenuRef inMenu)
OSStatus	ReleaseMenu (MenuRef inMenu)
OSStatus	DuplicateMenu (MenuRef inSourceMenu, MenuRef *outMenu)
OSStatus	CopyMenuTitleAsCFString (MenuRef inMenu, CFStringRef *outString)
OSStatus	SetMenuTitleWithCFString (MenuRef inMenu, CFStringRef inString)
OSStatus	SetMenuTitleIcon (MenuRef inMenu, UInt32 inType, void *inIcon)
OSStatus	GetMenuTitleIcon (MenuRef inMenu, UInt32 *outType, void **outIcon)
OSStatus	InvalidateMenuSize (MenuRef inMenu)
Boolean	IsMenuSizeInvalid (MenuRef inMenu)
OSStatus	EraseMenuBackground (MenuRef inMenu, const Rect *inEraseRect, CGContextRef inContext)
OSStatus	ScrollMenuImage (MenuRef inMenu, const Rect *inScrollRect, int inHScroll, int inVScroll, CGContextRef inContext)
void	MacAppendMenu (MenuRef menu, ConstStr255Param data)
void	InsertResMenu (MenuRef theMenu, ResType theType, short afterItem)
void	AppendResMenu (MenuRef theMenu, ResType theType)
void	MacInsertMenuItem (MenuRef theMenu, ConstStr255Param itemString, short afterItem)
void	DeleteMenuItem (MenuRef theMenu, short item)
void	InsertFontResMenu (MenuRef theMenu, short afterItem, short scriptFilter)
void	InsertIntlResMenu (MenuRef theMenu, ResType theType, short afterItem, short scriptFilter)
OSStatus	AppendMenuItemText (MenuRef menu, ConstStr255Param inString)
OSStatus	InsertMenuItemText (MenuRef menu, ConstStr255Param inString, MenuItemIndex afterItem)
OSStatus	CopyMenuItems (MenuRef inSourceMenu, MenuItemIndex inFirstItem, ItemCount inNumItems, MenuRef inDestMenu, MenuItemIndex inInsertAfter)
OSStatus	DeleteMenuItems (MenuRef inMenu, MenuItemIndex inFirstItem, ItemCount inNumItems)
OSStatus	AppendMenuItemTextWithCFString (MenuRef inMenu, CFStringRef inString, MenuItemAttributes inAttributes, MenuCommand inCommandID, MenuItemIndex *outNewItem)
OSStatus	InsertMenuItemTextWithCFString (MenuRef inMenu, CFStringRef inString, MenuItemIndex inAfterItem, MenuItemAttributes inAttributes, MenuCommand inCommandID)
long	MenuKey (CharParameter ch)
long	MenuSelect (Point startPt)
long	PopUpMenuSelect (MenuRef menu, short top, short left, short popUpItem)
long	MenuChoice (void)
	See if user attempted to select a disabled item. More...
UInt32	MenuEvent (const EventRecord *inEvent)
Boolean	IsMenuKeyEvent (MenuRef inStartMenu, EventRef inEvent, MenuEventOptions inOptions, MenuRef *outMenu, MenuItemIndex *outMenuItem)
OSStatus	InvalidateMenuEnabling (MenuRef inMenu)
short	GetMBarHeight (void)
	Fetch the height of the menu bar. More...
void	MacDrawMenuBar (void)
void	InvalMenuBar (void)
Boolean	IsMenuBarInvalid (MenuRef rootMenu)
void	HiliteMenu (MenuID menuID)
MenuBarHandle	GetNewMBar (short menuBarID)
MenuBarHandle	GetMenuBar (void)
void	SetMenuBar (MenuBarHandle mbar)
	Install an entire menu list. More...
OSStatus	DuplicateMenuBar (MenuBarHandle inMbar, MenuBarHandle *outMbar)
OSStatus	DisposeMenuBar (MenuBarHandle inMbar)
MenuRef	GetMenuHandle (MenuID menuID)
void	MacInsertMenu (MenuRef theMenu, MenuID beforeID)
void	MacDeleteMenu (MenuID menuID)
void	ClearMenuBar (void)
	Redraw the menu bar with no menus. More...
void	SetMenuFlash (short count)
	Set the number of times a menu item blinks upon selection. More...
void	SetMenuFlashCount (short count)
void	FlashMenuBar (MenuID menuID)
Boolean	SystemEdit (short editCmd)
void	SystemMenu (long menuResult)
Boolean	IsMenuBarVisible (void)
void	ShowMenuBar (void)
void	HideMenuBar (void)
MenuRef	AcquireRootMenu (void)
OSStatus	SetRootMenu (MenuRef inMenu)
void	CheckItem (MenuRef theMenu, short item, Boolean checked)
void	MacCheckMenuItem (MenuRef theMenu, short item, Boolean checked)
void	SetMenuItemText (MenuRef theMenu, short item, ConstStr255Param itemString)
void	GetMenuItemText (MenuRef theMenu, short item, Str255 itemString)
void	SetItemMark (MenuRef theMenu, short item, CharParameter markChar)
void	GetItemMark (MenuRef theMenu, short item, CharParameter *markChar)
	Query the current mark character of a menu item. More...
	AppendMenu (windowsSubMenu, "\pMyFile")
void	GetItemCmd (MenuRef theMenu, short item, CharParameter *cmdChar)
	Query current command character of a menu item. More...
void	SetItemIcon (MenuRef theMenu, short item, short iconIndex)
void	GetItemIcon (MenuRef theMenu, short item, short *iconIndex)
	See which icon, if any, is attached to a menu item. More...
void	SetItemStyle (MenuRef theMenu, short item, StyleParameter chStyle)
void	GetItemStyle (MenuRef theMenu, short item, Style *chStyle)
	Obtain the current character formatting of a menu item. More...
OSErr	SetMenuItemCommandID (MenuRef inMenu, SInt16 inItem, MenuCommand inCommandID)
	Dim a menu or a menu item; make non-selectable. More...
OSErr	GetMenuItemCommandID (MenuRef inMenu, SInt16 inItem, MenuCommand *outCommandID)
OSErr	SetMenuItemModifiers (MenuRef inMenu, SInt16 inItem, UInt8 inModifiers)
OSErr	GetMenuItemModifiers (MenuRef inMenu, SInt16 inItem, UInt8 *outModifiers)
OSErr	SetMenuItemIconHandle (MenuRef inMenu, SInt16 inItem, UInt8 inIconType, Handle inIconHandle)
OSErr	GetMenuItemIconHandle (MenuRef inMenu, SInt16 inItem, UInt8 *outIconType, Handle *outIconHandle)
OSErr	SetMenuItemTextEncoding (MenuRef inMenu, SInt16 inItem, TextEncoding inScriptID)
OSErr	GetMenuItemTextEncoding (MenuRef inMenu, SInt16 inItem, TextEncoding *outScriptID)
OSErr	SetMenuItemHierarchicalID (MenuRef inMenu, SInt16 inItem, MenuID inHierID)
OSErr	GetMenuItemHierarchicalID (MenuRef inMenu, SInt16 inItem, MenuID *outHierID)
OSErr	SetMenuItemFontID (MenuRef inMenu, SInt16 inItem, SInt16 inFontID)
OSErr	GetMenuItemFontID (MenuRef inMenu, SInt16 inItem, SInt16 *outFontID)
OSErr	SetMenuItemRefCon (MenuRef inMenu, SInt16 inItem, UInt32 inRefCon)
OSErr	GetMenuItemRefCon (MenuRef inMenu, SInt16 inItem, UInt32 *outRefCon)
OSErr	SetMenuItemRefCon2 (MenuRef inMenu, SInt16 inItem, UInt32 inRefCon2)
OSErr	GetMenuItemRefCon2 (MenuRef inMenu, SInt16 inItem, UInt32 *outRefCon2)
OSErr	SetMenuItemKeyGlyph (MenuRef inMenu, SInt16 inItem, SInt16 inGlyph)
OSErr	GetMenuItemKeyGlyph (MenuRef inMenu, SInt16 inItem, SInt16 *outGlyph)
void	MacEnableMenuItem (MenuRef theMenu, MenuItemIndex item)
void	DisableMenuItem (MenuRef theMenu, MenuItemIndex item)
Boolean	IsMenuItemEnabled (MenuRef menu, MenuItemIndex item)
void	EnableMenuItemIcon (MenuRef theMenu, MenuItemIndex item)
void	DisableMenuItemIcon (MenuRef theMenu, MenuItemIndex item)
Boolean	IsMenuItemIconEnabled (MenuRef menu, MenuItemIndex item)
OSStatus	SetMenuItemHierarchicalMenu (MenuRef inMenu, MenuItemIndex inItem, MenuRef inHierMenu)
OSStatus	GetMenuItemHierarchicalMenu (MenuRef inMenu, MenuItemIndex inItem, MenuRef *outHierMenu)
OSStatus	CopyMenuItemTextAsCFString (MenuRef inMenu, MenuItemIndex inItem, CFStringRef *outString)
OSStatus	SetMenuItemTextWithCFString (MenuRef inMenu, MenuItemIndex inItem, CFStringRef inString)
OSStatus	GetMenuItemIndent (MenuRef inMenu, MenuItemIndex inItem, UInt32 *outIndent)
OSStatus	SetMenuItemIndent (MenuRef inMenu, MenuItemIndex inItem, UInt32 inIndent)
OSStatus	GetMenuItemCommandKey (MenuRef inMenu, MenuItemIndex inItem, Boolean inGetVirtualKey, UInt16 *outKey)
OSStatus	SetMenuItemCommandKey (MenuRef inMenu, MenuItemIndex inItem, Boolean inSetVirtualKey, UInt16 inKey)
void	DeleteMCEntries (MenuID menuID, short menuItem)
MCTableHandle	GetMCInfo (void)
void	SetMCInfo (MCTableHandle menuCTbl)
void	DisposeMCInfo (MCTableHandle menuCTbl)
	MyHeapScramble ()
	SetMCEntries (1, &myMCE)
void	SetMCEntries (short numEntries, MCTablePtr menuCEntries)
OSStatus	GetMenuItemProperty (MenuRef menu, MenuItemIndex item, OSType propertyCreator, OSType propertyTag, UInt32 bufferSize, UInt32 *actualSize, void *propertyBuffer)
OSStatus	GetMenuItemPropertySize (MenuRef menu, MenuItemIndex item, OSType propertyCreator, OSType propertyTag, UInt32 *size)
OSStatus	SetMenuItemProperty (MenuRef menu, MenuItemIndex item, OSType propertyCreator, OSType propertyTag, UInt32 propertySize, const void *propertyData)
OSStatus	RemoveMenuItemProperty (MenuRef menu, MenuItemIndex item, OSType propertyCreator, OSType propertyTag)
OSStatus	GetMenuItemPropertyAttributes (MenuRef menu, MenuItemIndex item, OSType propertyCreator, OSType propertyTag, UInt32 *attributes)
OSStatus	ChangeMenuItemPropertyAttributes (MenuRef menu, MenuItemIndex item, OSType propertyCreator, OSType propertyTag, UInt32 attributesToSet, UInt32 attributesToClear)
OSStatus	GetMenuAttributes (MenuRef menu, MenuAttributes *outAttributes)
OSStatus	ChangeMenuAttributes (MenuRef menu, MenuAttributes setTheseAttributes, MenuAttributes clearTheseAttributes)
OSStatus	GetMenuItemAttributes (MenuRef menu, MenuItemIndex item, MenuItemAttributes *outAttributes)
OSStatus	ChangeMenuItemAttributes (MenuRef menu, MenuItemIndex item, MenuItemAttributes setTheseAttributes, MenuItemAttributes clearTheseAttributes)
void	DisableAllMenuItems (MenuRef theMenu)
void	EnableAllMenuItems (MenuRef theMenu)
Boolean	MenuHasEnabledItems (MenuRef theMenu)
OSStatus	GetMenuTrackingData (MenuRef theMenu, MenuTrackingData *outData)
OSStatus	GetMenuType (MenuRef theMenu, UInt16 *outType)
ItemCount	CountMenuItemsWithCommandID (MenuRef inMenu, MenuCommand inCommandID)
OSStatus	GetIndMenuItemWithCommandID (MenuRef inMenu, MenuCommand inCommandID, UInt32 inItemIndex, MenuRef *outMenu, MenuItemIndex *outIndex)
void	EnableMenuCommand (MenuRef inMenu, MenuCommand inCommandID)
void	DisableMenuCommand (MenuRef inMenu, MenuCommand inCommandID)
Boolean	IsMenuCommandEnabled (MenuRef inMenu, MenuCommand inCommandID)
OSStatus	SetMenuCommandMark (MenuRef inMenu, MenuCommand inCommandID, UniChar inMark)
OSStatus	GetMenuCommandMark (MenuRef inMenu, MenuCommand inCommandID, UniChar *outMark)
OSStatus	GetMenuCommandProperty (MenuRef inMenu, MenuCommand inCommandID, OSType inPropertyCreator, OSType inPropertyTag, ByteCount inBufferSize, ByteCount *outActualSize, void *inPropertyBuffer)
OSStatus	GetMenuCommandPropertySize (MenuRef inMenu, MenuCommand inCommandID, OSType inPropertyCreator, OSType inPropertyTag, ByteCount *outSize)
OSStatus	SetMenuCommandProperty (MenuRef inMenu, MenuCommand inCommandID, OSType inPropertyCreator, OSType inPropertyTag, ByteCount inPropertySize, const void *inPropertyData)
OSStatus	RemoveMenuCommandProperty (MenuRef inMenu, MenuCommand inCommandID, OSType inPropertyCreator, OSType inPropertyTag)
OSStatus	CopyMenuItemData (MenuRef menu, MenuItemID item, Boolean isCommandID, MenuItemDataPtr outData)
OSStatus	SetMenuItemData (MenuRef menu, MenuItemID item, Boolean isCommandID, const MenuItemDataRec *data)
Boolean	IsMenuItemInvalid (MenuRef menu, MenuItemIndex item)
OSStatus	InvalidateMenuItems (MenuRef menu, MenuItemIndex firstItem, ItemCount numItems)
OSStatus	UpdateInvalidMenuItems (MenuRef menu)
OSStatus	CreateStandardFontMenu (MenuRef menu, MenuItemIndex afterItem, MenuID firstHierMenuID, OptionBits options, ItemCount *outHierMenuCount)
OSStatus	UpdateStandardFontMenu (MenuRef menu, ItemCount *outHierMenuCount)
OSStatus	GetFontFamilyFromMenuSelection (MenuRef menu, MenuItemIndex item, FMFontFamily *outFontFamily, FMFontStyle *outStyle)
OSStatus	InitContextualMenus (void)
Boolean	IsShowContextualMenuClick (const EventRecord *inEvent)
Boolean	IsShowContextualMenuEvent (EventRef inEvent)
OSStatus	ContextualMenuSelect (MenuRef inMenu, Point inGlobalLocation, Boolean inReserved, UInt32 inHelpType, ConstStr255Param inHelpItemString, const AEDesc *inSelection, UInt32 *outUserSelectionType, SInt16 *outMenuID, MenuItemIndex *outMenuItem)
Boolean	ProcessIsContextualMenuClient (ProcessSerialNumber *inPSN)
OSStatus	CMPluginExamineContext (void *thisInstance, const AEDesc *inContext, AEDescList *outCommandPairs)
OSStatus	CMPluginHandleSelection (void *thisInstance, AEDesc *inContext, SInt32 inCommandID)
void	CMPluginPostMenuCleanup (void *thisInstance)
SInt16	LMGetTheMenu (void)
MenuRef	newmenu (MenuID menuID, const char *menuTitle)
void	appendmenu (MenuRef menu, const char *data)
void	insertmenuitem (MenuRef theMenu, const char *itemString, short afterItem)
long	menuselect (const Point *startPt)
void	setmenuitemtext (MenuRef menu, short item, const char *itemString)
void	getmenuitemtext (MenuRef menu, short item, char *itemString)
MenuID	GetMenuID (MenuRef menu)
SInt16	GetMenuWidth (MenuRef menu)
SInt16	GetMenuHeight (MenuRef menu)
StringPtr	GetMenuTitle (MenuRef menu, Str255 title)
OSStatus	GetMenuDefinition (MenuRef menu, MenuDefSpecPtr outDefSpec)
void	SetMenuID (MenuRef menu, MenuID menuID)
void	SetMenuWidth (MenuRef menu, SInt16 width)
void	SetMenuHeight (MenuRef menu, SInt16 height)
OSStatus	SetMenuTitle (MenuRef menu, ConstStr255Param title)
OSStatus	SetMenuDefinition (MenuRef menu, const MenuDefSpec *defSpec)
*	setmenuitemtext (menu, item, itemString) MenuID GetMenuID(MenuRef menu)

Variables
	windowsSubMenu = NewMenu(SMID_CLWIND, "\pClose Window")
	Assign a command-key to a menu item; make submenu. More...
</pre > *par	Copyright
</pre > *par short	item
</pre > *par short CharParameter	cmdChar
myMCE mctRGB2	green = 0
	Get the address of a particular menu color table entry. More...
myMCE mctRGB2	blue = 0
Use GetMCInfo to get a copy of the entire menu color table</pre > *par short	menuItem

Detailed Description

Menu Manager Interfaces.

Introduced In: Mac OS 9

Avaliable From: Universal Interfaces 3.4.1

Copyright: © 1985-2001 by Apple Computer, Inc., all rights reserved.

For bug reports, consult the following page on the World Wide Web:

http://developer.apple.com/bugreporter/

Macro Definition Documentation

CountMenuItems

UInt16 CountMenuItems

(

MenuReftheMenu

)

(CountMItems(theMenu))

CountMenuItems()

Non-Carbon CFM: in CarbonAccessors.o 1.3 and later or as macro/inline

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

InvokeMenuBarDefUPP

#define InvokeMenuBarDefUPP	(		selector,
			message,
			parameter1,
			parameter2,
			userUPP
	)

Value:

  (long)CALL_FOUR_PARAMETER_UPP((userUPP), uppMenuBarDefProcInfo, (selector), \
                                (message), (parameter1), (parameter2))

InvokeMenuDefUPP

#define InvokeMenuDefUPP	(		message,
			theMenu,
			menuRect,
			hitPt,
			whichItem,
			userUPP
	)

Value:

  CALL_FIVE_PARAMETER_UPP((userUPP), uppMenuDefProcInfo, (message), (theMenu), \
                          (menuRect), (hitPt), (whichItem))

NewMBarHookUPP

#define NewMBarHookUPP

(

userRoutine

)

Value:

  (MBarHookUPP) NewRoutineDescriptor( \
      (ProcPtr)(userRoutine), uppMBarHookProcInfo, GetCurrentArchitecture())

NewMenuBarDefUPP

#define NewMenuBarDefUPP

(

userRoutine

)

Value:

  (MenuBarDefUPP) NewRoutineDescriptor( \
      (ProcPtr)(userRoutine), uppMenuBarDefProcInfo, GetCurrentArchitecture())

NewMenuDefUPP

#define NewMenuDefUPP

(

userRoutine

)

Value:

  (MenuDefUPP) NewRoutineDescriptor( \
      (ProcPtr)(userRoutine), uppMenuDefProcInfo, GetCurrentArchitecture())

NewMenuHookUPP

#define NewMenuHookUPP

(

userRoutine

)

Value:

  (MenuHookUPP) NewRoutineDescriptor( \
      (ProcPtr)(userRoutine), uppMenuHookProcInfo, GetCurrentArchitecture())

Typedef Documentation

MenuAttributes

typedef UInt32 MenuAttributes

MenuAttributes

Summary: Menu attributes control behavior of the entire menu. They are used with the Get/ChangeMenuAttributes APIs.

MenuEventOptions

typedef UInt32 MenuEventOptions

MenuEventOptions

Summary: Menu event options control how the menus are searched for an item matching a particular keyboard event. They are used with the IsMenuKeyEvent API.

MenuItemAttributes

typedef UInt32 MenuItemAttributes

MenuItemAttributes

Summary: Menu item attributes control behavior of individual menu items. They are used with the Get/ChangeMenuItemAttributes APIs.

MenuTrackingMode

typedef UInt32 MenuTrackingMode

MenuTrackingMode

Summary: A menu tracking mode constant is part of the kEventMenuBeginTracking and kEventMenuChangeTrackingMode Carbon events. It indicates whether menus are being tracked using the mouse or keyboard.

Enumeration Type Documentation

anonymous enum

anonymous enum

Menu Manager

anonymous enum

anonymous enum

A Short Course on Menu Definition Functions

A menu definition function is used to implement a custom visual appearance for a menu. Menu definition functions are still supported in Carbon, but the messages sent to a menu definition function in Carbon are different than for a non-Carbon application.

In general, Apple recommends using the system menu definition whenever possible. Menu definition functions will continue to be supported, but it is not easy to write a correct menu definition, especially one that attempts to imitate the standard system menu appearance. If you require special features in your menu that the system menu definition does not support, please mail toolb.nosp@m.ox@a.nosp@m.pple..nosp@m.com and describe your requirements; we would much rather enhance the system menu definition than have you write a custom one.

Menu definition functions before Carbon used the following messages:

kMenuDrawMsg
kMenuChooseMsg
kMenuSizeMsg
kMenuPopUpMsg
kMenuDrawItemMsg
kMenuCalcItemMsg
kMenuThemeSavvyMsg

kMenuChooseMsg and kMenuDrawItemMsg are not supported in Carbon and are not sent to Carbon menu definitions. In Carbon, kMenuChooseMsg is replaced by kMenuFindItemMsg and kMenuHiliteItemMsg. Menu definition functions in Carbon use the following messages:

 kMenuInitMsg
 kMenuDisposeMsg
 kMenuFindItemMsg
 kMenuHiliteItemMsg
 kMenuDrawItemsMsg
 kMenuDrawMsg
 kMenuSizeMsg
 kMenuPopUpMsg
 kMenuCalcItemMsg
 kMenuThemeSavvyMsg

The rest of this documentation will focus on Carbon menu definitions only.

Menu Definition Messages

Carbon menu definition functions should support the following messages:

kMenuInitMsg

    menuRect        unused
    hitPt           unused
    whichItem       OSErr*

    Sent when a menu is created. This message gives the menu definition

an opportunity to initialize its own state. If the menu definition encounters an error while initializing, it should set *whichItem to a non-zero error code; this will cause the Menu Manager to destroy the menu and return an error back from the API that was used to create the menu.

 kMenuDisposeMsg

     menuRect        unused
     hitPt           unused
     whichItem       unused

     Sent when a menu is destroyed. This message gives the menu

definition an opportunity to destroy its own data.

 kMenuFindItemMsg

     menuRect        menu bounds
     hitPt           point to hit-test
     whichItem       MDEFFindItemData*

     Sent when the Menu Manager is displaying a menu and needs to know

what item is under the mouse. The whichItem parameter is actually a pointer to a MenuTrackingData structure. On entry, the menu, virtualMenuTop, and virtualMenuBottom fields of this structure are valid. The menu definition should determine which item containst the given point, if any, and fill in the itemUnderMouse, itemSelected, and itemRect fields. If an item is found, the menu definition should always fill in the itemUnderMouse and itemRect fields. The menu definition should only fill in the itemSelected field if the item is available for selection; if it is unavailable (because it is disabled, or for some other reason), the menu definition should set the itemSelected field to zero.

     The values placed in the itemUnderMouse and itemSelected fields

should be less than or equal to the number of items returned by CountMenuItems on this menu.

     The menu definition should not hilite the found item during this

message. The Menu Manager will send a separate kMenuHiliteItemMsg to request hiliting of the item.

     If the menu definition supports scrolling, it should scroll the menu

during this message, and update the virtualMenuTop and virtualMenuBottom fields of the MenuTrackingData to indicate the menu's new scrolled position.

     If the menu definition uses QuickDraw to draw while scrolling, it

should draw into the current port.

     If the menu definition uses CoreGraphics to draw while scrolling, it

should use the CGContextRef passed in the context field of the MDEFHiliteItemData structure.

     Menu definitions must use the ScrollMenuImage API, if available, to

scroll the menu contents. This API is available in CarbonLib 1.4 and later, and in Mac OS X after 10.0.x. ScrollMenuImage properly supports scrolling the alpha channel in the menu's image data. Use of QuickDraw's ScrollRect API to scroll the menu contents will result in the alpha channel being set to 0xFF (opaque) and the menu will no longer be transparent.

The menu definition should not modify the menu field of the MenuTrackingData.

 kMenuHiliteItemMsg

     menuRect        menu bounds
     hitPt           unused
     whichItem       MDEFHiliteItemData*

     Sent when the Menu Manager is displaying a menu and needs to hilite

a newly selected item. The whichItem parameter is actually a pointer to a MDEFHiliteItemData structure. The menu definition should unhilite the item in the previousItem field, if non-zero, and hilite the item in the newItem field.

     Menu definitions should use the EraseMenuBackground API to erase the

old menu contents before unhiliting a menu item, if the menu definition is using the Appearance Manager's menu drawing APIs. This is necessary because the background of a menu is transparent on Aqua, and if the old hilite is not erased first, it will show through the new unhilited menu background.

     If the menu definition uses QuickDraw to draw, it should draw into

the current port.

     If the menu definition uses CoreGraphics to draw, it should use the

CGContextRef passed in the context field of the MDEFHiliteItemData structure.

 kMenuDrawItemsMsg

     menuRect        menu bounds
     hitPt           unused
     whichItem       MDEFDrawItemsData*

     Sent when the Menu Manager is displaying a menu and needs to redraw

a portion of the menu. This message is used by the dynamic menu item support code in the Menu Manager; for example, if items five and six in a menu are a dynamic group, the Menu Manager will send a DrawItems message when the group's modifier key is pressed or released to redraw the appropriate item, but no other items in the menu.

     The whichItem parameter for this message is actually a pointer to a

MDEFDrawItemsData structure. The menu definition should redraw the items starting with firstItem and ending with lastItem, inclusive.

     If the menu definition uses QuickDraw to draw, it should draw into

the current port.

     If the menu definition uses CoreGraphics to draw, it should use the

CGContextRef passed in the context field of the MDEFDrawItemsData structure.

 kMenuDrawMsg

     menuRect        menu bounds
     hitPt           unused
     whichItem       MDEFDrawData*

     Sent when the Menu Manager is displaying a menu and needs to redraw

the entire menu. The whichItem parameter is actually a pointer to a MenuTrackingData structure. On entry, the menu field of this structure is valid. The menu definition should draw the menu and, if it supports scrolling, should also fill in the virtualMenuTop and virtualMenuBottom fields of the structure to indicate the menu's initial unscrolled position; typically, virtualMenuTop would be set to the same value as the top coordinate of the menu rect, and virtualMenuBottom would be set to virtualMenuTop plus the virtual height of the menu.

     If the menu definition uses QuickDraw to draw, it should draw into

the current port.

     If the menu definition uses CoreGraphics to draw, it should use the

CGContextRef passed in the context field of the MDEFDrawData structure.

 kMenuSizeMsg

     menuRect        unused
     hitPt           maximum width and height of the menu
     whichItem       unused

     Sent when the Menu Manager needs to determine the size of a menu.

The menu definition should calculate the width and height of the menu and store the sizes into the menu with SetMenuWidth and SetMenuHeight.

     If the gestaltMenuMgrSendsMenuBoundsToDefProc bit is set in the Menu

Manager's Gestalt value, then the hitPt parameter to this message is the maximum width (hitPt.h) and height (hitPt.v) of the menu. The menu definition should ensure that the width and height that it places in the menu do not exceed these values. If the gestalt bit is not set, the menu definition should just use the main GDevice's width and height as constraints on the menu's width and height.

 kMenuPopUpMsg

     menuRect        on entry, constraints on the menu's position; on

exit, menu bounds hitPt requested menu location, with swapped coordinates whichItem on entry, requested initial selection; on exit, virtual menu top

     Sent when the Menu Manager is about to display a popup menu. The

menu definition should calculate the appropriate menu bounds to contain the menu based on the requested menu location and selected item. It should write the menuBounds into the rect given by the menuRect parameter.

     If the gestaltMenuMgrSendsMenuBoundsToDefProc bit is set in the Menu

Manager's Gestalt value, then the menuRect parameter on entry to this message contains a constraint rect, in global coordinates, outside of which the popup menu should not be positioned. The menu definition should take this constraint rect into account as it calculates the menu bounds. If the gestalt bit is not set, the menu definition should use the bounds of the GDevice containing the menu's top left corner as a constraint on the menu's position.

     The hitPt parameter is a requested location for the top left corner

of the menu. The coordinates of this parameter are swapped from their normal order; the h field of the hitPt parameter contains the vertical coordinate, and the v field of hitPt contains the horizontal coordinate.

     On entry, the whichItem parameter points at a menu item index which

is requested to be the initial selection when the menu is displayed. After calculating the menu's bounds, the menu definition should write the menu's virtual top coordinate into the location pointed at by the whichItem parameter. If displaying the menu at the requested location does not require scrolling, the virtual top will be the same as the menu bounds top; if the menu must scroll to fit in the requested location, the virtual top may be different.

 kMenuCalcItemMsg

     menuRect        on exit, item bounds
     hitPt           unused
     whichItem       the item whose rect to calculate

     Sent when the Menu Manager needs to know the bounds of a menu item.

The menu definition should calculate the size of the item specified by the whichItem parameter, and store the bounds in the rect specified by the menuRect parameter.

     Some sample menu definition code provided by Apple has previously

shown an implementation of this message that always sets the top left corner of the item bounds to (0,0), regardless of the item's actual position in the menu. For best future compatibility, menu definitions should begin storing an item bounds that gives the item's actual position in the menu based on the menu's current virtual top. For example, if the virtual menu top starts at 20, then the menu definition would calculate an item bounds for the first item that starts at (0,20), an item bounds for the second item that starts at (0,40), and so on. The menu definition should call GetMenuTrackingData to get the menu's current virtual position, and use zero for the menu top if GetMenuTrackingData returns an error.

 kMenuThemeSavvyMsg

     menuRect        unused
     hitPt           unused
     whichItem       on exit, indicates theme-savvyness of the menu

definition

     Sent by the Menu Manager to determine whether the MDEF uses the

Appearance Manager menu-drawing functions to draw its menu. If it does, the menu definition should return kThemeSavvyMenuResponse in the location pointed to by whichItem. If the menu definition draws its own custom content without using the Appearance Manager menu-drawing functions, it should ignore this message.

Low-memory Global Replacements

Pre-Carbon menu definitions needed to use several low-memory globals to

communicate with the Menu Manager. These globals have all been replaced or made obsolete in Carbon, as follows:

 MenuDisable

     MenuDisable is now set automatically by the Menu Manager using the

value returned in the itemUnderMouse field of the MenuTrackingData structure passed to kMenuFindItemMsg.

 TopMenuItem
 AtMenuBottom

     TopMenuItem and AtMenuBottom are now set automatically by the Menu

Manager using the values returned in the virtualMenuTop and virtualMenuBottom fields of the MenuTrackingData structure passed to kMenuDrawMsg and kMenuFindItemMsg.

 mbSaveLoc

     This undocumented low-memory global was used by pre-Carbon menu

definitions to store the bounding rect of the currently selected item and to avoid drawing glitches while the menu definition was scrolling the contents of a menu that had submenus. The Menu Manager now automatically sets the selected item bounds using the value returned in the itemRect field of the MenuTrackingData structure passed to kMenuFindItemMsg. In order to correctly support scrolling of menus with submenus, a menu definition should verify, before scrolling the menu contents, that no submenus of the scrolling menu are currently visible. A menu definition can use GetMenuTrackingData to verify this condition, as follows:

         Boolean SafeToScroll( MenuRef menuBeingScrolled )
         {
             MenuTrackingData lastMenuData;
             return GetMenuTrackingData( NULL, &lastMenuData ) == noErr
                    && lastMenuData.menu == menuBeingScrolled;
         }

     If SafeToScroll returns false, the menu definition should not scroll

the menu.

anonymous enum

anonymous enum

Carbon MDEFs must replace mChooseMsg with the new messages kMenuFindItemMsg and kMenuHiliteItemMsg. mDrawItemMsg was used by the popup menu control before 8.5, but is no longer used.

anonymous enum

anonymous enum

Enumerator
kMenuAttrExcludesMarkColumn	No column space is allocated for the mark character when this menu is drawn.
kMenuAttrAutoDisable	The menu title is automatically disabled when all items are disabled.
kMenuAttrUsePencilGlyph	The pencil glyph from the Keyboard font (kMenuPencilGlyph) is used to draw the Control modifier key in menu keyboard equivalents. This appearance is typically used only by Japanese input method menus.

anonymous enum

anonymous enum

Enumerator
kMenuItemAttrDisabled	This item is disabled.
kMenuItemAttrIconDisabled	This item's icon is disabled.
kMenuItemAttrSubmenuParentChoosable	Allows the parent item of a submenu to be selectable.
kMenuItemAttrDynamic	This item changes dynamically based on modifier key state.
kMenuItemAttrNotPreviousAlternate	This item is not part of the same dynamic group as the previous item.
kMenuItemAttrHidden	This item is not drawn when the menu is displayed.
kMenuItemAttrSeparator	This item is a separator; the text of the item is ignored.
kMenuItemAttrSectionHeader	This item is a menu section header; it is disabled and unselectable.
kMenuItemAttrIgnoreMeta	Metacharacters in the text of this item (such as the dash) are ignored.
kMenuItemAttrAutoRepeat	This item is recognized by IsMenuKeyEvent when it is passed an auto-repeat keyboard event.
kMenuItemAttrUseVirtualKey	When MenuEvent and IsMenuKeyEvent compare this item's keyboard equivalent against a keyboard event, they use the item's virtual keycode equivalent rather than its character code equivalent.
kMenuItemAttrCustomDraw	This item is drawn in a customized fashion by the application. Causes custom menu item drawing Carbon events to be sent. This attribute is available in CarbonLib 1.4 and later, and in Mac OS X after 10.0.x.

anonymous enum

anonymous enum

Enumerator
kMenuTrackingModeMouse	Menus are being tracked using the mouse.
kMenuTrackingModeKeyboard	Menus are being tracked using the keyboard.

anonymous enum

anonymous enum

Enumerator
kMenuEventIncludeDisabledItems	Disabled items are examined for a match.
kMenuEventQueryOnly	Don't hilite the menu title if a match is found.
kMenuEventDontCheckSubmenus	Don't look for a match in submenus of the starting menu.

anonymous enum

anonymous enum

Summary: A MenuItemDataFlags value indicates which fields of a MenuItemDataRec structure should be used by the Copy/SetMenuItemData APIs. All MenuItemDataFlags may be used when getting or setting the contents of a menu item; some may also be used when getting or setting information about the menu itself, if the item index given to Copy/SetMenuItemData is 0.

Enumerator
kMenuItemDataText	Set or return the Str255 text of a menu using the MenuItemDataRec.text field. If getting the text, the text field must be initialized with a pointer to a Str255 variable before calling CopyMenuItemData. If both kMenuItemDataText and kMenuItemCFString are set on entry to CopyMenuItemData, the API will determine whether the menu text was most recently set using a Str255 or CFString, and return only that text format; the flags value for the other format will be cleared. Valid for both menu items and the menu title (if item number is 0).
kMenuItemDataMark	Set or return the mark character of a menu item using the MenuItemDataRec.mark field. Valid only for menu items.
kMenuItemDataCmdKey	Set or return the command key of a menu item using the MenuItemDataRec.cmdKey field. Valid only for menu items.
kMenuItemDataCmdKeyGlyph	Set or return the command key glyph of a menu item using the MenuItemDataRec.cmdKeyGlyph field. Valid only for menu items.
kMenuItemDataCmdKeyModifiers	Set or return the command key modifiers of a menu item using the MenuItemDataRec.cmdKeyModifiers field. Valid only for menu items.
kMenuItemDataStyle	Set or return the QuickDraw text style of a menu item using the MenuItemDataRec.style field. Valid only for menu items.
kMenuItemDataEnabled	Set or return the enable state of a menu using the MenuItemDataRec.enabled field. Valid for both menu items and the menu itself (if item number is 0).
kMenuItemDataIconEnabled	Set or return the enable state of a menu item icon using the MenuItemDataRec.iconEnabled field. Valid only for menu items.
kMenuItemDataIconID	Set or return the icon resource ID of a menu item using the MenuItemDataRec.iconID field. Valid only for menu items.
kMenuItemDataIconHandle	Set or return the icon handle of a menu item using the MenuItemDataRec.iconType and MenuItemDataRec.iconHandle fields. Both fields must be initialized if setting the icon handle; both fields will be returned when getting the handle. The iconType field should contain one of the constants kMenuIconType, kMenuShrinkIconType, kMenuSmallIconType, kMenuColorIconType, kMenuIconSuiteType, or kMenuIconRefType. An icon handle may be a handle to an ICON resource, a SICN resource, a cicn resource, an IconSuite, or an IconRef. Valid only for menu items.
kMenuItemDataCommandID	Set or return the command ID of a menu item using the MenuItemDataRec.cmdID field. Valid only for menu items.
kMenuItemDataTextEncoding	Set or return the text encoding of a menu item using the MenuItemDataRec.encoding field. Valid only for menu items.
kMenuItemDataProperties	Set or return the properties of a menu using the MenuItemDataRec.properties field. If setting the properties, the properties field should contain a collection with the new properties; existing menu properties with the same collection creator and tag will be replaced by the new properties. If getting the properties, the properties field should either be set to NULL or to a valid Collection. If NULL, a new collection is allocated by the CopyMenuItemData and returned in the properties field. If not NULL, the entire contents of the collection are replaced by the properties of the menu. Valid for both menu items and the menu itself (if item number is 0).
kMenuItemDataIndent	Set or return the item indent level of a menu item using the MenuItemDataRec.indent field. Valid only for menu items.
kMenuItemDataCmdVirtualKey	Set or return the virtual key code keyboard equivalent of a menu item using the MenuItemDataRec.cmdVirtualKey field. Valid only for menu items. On output, only valid if the item has the kMenuItemAttrUseVirtualKeyCode attribute.

Function Documentation

AcquireRootMenu()

MenuRef AcquireRootMenu

(

void

)

AcquireRootMenu()

Summary: Get the menu whose contents are displayed in the menubar.

Discussion: The refcount of the root menu is incremented by this API. The caller should release a refcount with ReleaseMenu when it©s done with the menu.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

appendmenu()

void appendmenu	(	MenuRef	menu,
		const char *	data
	)

appendmenu()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

AppendMenuItemText()

OSStatus AppendMenuItemText	(	MenuRef	menu,
		ConstStr255Param	inString
	)

AppendMenuItemText()

Non-Carbon CFM: in MenusLib 8.5 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

AppendMenuItemTextWithCFString()

OSStatus AppendMenuItemTextWithCFString	(	MenuRef	inMenu,
		CFStringRef	inString,
		MenuItemAttributes	inAttributes,
		MenuCommand	inCommandID,
		MenuItemIndex *	outNewItem
	)

AppendMenuItemTextWithCFString()

Summary: Appends a new menu item with text from a CFString.

Discussion: The Menu Manager will either make its own copy or just increment the refcount of the CFString before returning from AppendMenuItemWithTextCFString, depending on whether the string is mutable or immutable. If the string is mutable, modifying the string after calling AppendMenuItemTextWithCFString will have no effect on the menu item's actual text. The caller may release the string after calling AppendMenuItemTextWithCFString.

Parameters:

inMenu: The menu to which to append the new item.

inString: The text of the new item.

inAttributes: The attributes of the new item.

inCommandID: The command ID of the new item.

outNewItem: On exit, the index of the new item. May be NULL if the caller does not need this information.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

AppendResMenu()

void AppendResMenu	(	MenuRef	theMenu,
		ResType	theType
	)

AppendResMenu()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

CalcMenuSize()

void CalcMenuSize

(

MenuRef

theMenu

)

CalcMenuSize()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

ChangeMenuAttributes()

OSStatus ChangeMenuAttributes	(	MenuRef	menu,
		MenuAttributes	setTheseAttributes,
		MenuAttributes	clearTheseAttributes
	)

ChangeMenuAttributes()

Summary: Changes the attributes of a menu.

Parameters:

menu: The menu.

setTheseAttributes: The attributes to add to the menu.

clearTheseAttributes: The attributes to remove from the menu.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

ChangeMenuItemAttributes()

OSStatus ChangeMenuItemAttributes	(	MenuRef	menu,
		MenuItemIndex	item,
		MenuItemAttributes	setTheseAttributes,
		MenuItemAttributes	clearTheseAttributes
	)

ChangeMenuItemAttributes()

Summary: Changes the attributes of a menu item.

Parameters:

menu: The menu.

item: The menu item.

setTheseAttributes: The attributes to add to the menu item.

clearTheseAttributes: The attributes to remove from the menu item.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

ChangeMenuItemPropertyAttributes()

OSStatus ChangeMenuItemPropertyAttributes	(	MenuRef	menu,
		MenuItemIndex	item,
		OSType	propertyCreator,
		OSType	propertyTag,
		UInt32	attributesToSet,
		UInt32	attributesToClear
	)

ChangeMenuItemPropertyAttributes()

Summary: Changes the attributes of a menu item property.

Parameters:

menu: The menu.

item: The menu item.

propertyCreator: The creator code of the property.

propertyTag: The property tag.

attributesToSet: The attributes to add to the menu item property.

attributesToClear: The attributes to remove from the menu item property.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

CheckItem()

void CheckItem	(	MenuRef	theMenu,
		short	item,
		Boolean	checked
	)

CheckItem()

Summary: Renamed to CheckMenuItem in Carbon

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

ClearMenuBar()

void ClearMenuBar

(

void

)

Redraw the menu bar with no menus.

  @par Non-Carbon CFM:   in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

CMPluginExamineContext()

OSStatus CMPluginExamineContext	(	void *	thisInstance,
		const AEDesc *	inContext,
		AEDescList *	outCommandPairs
	)

CMPluginExamineContext()

Implemented by client

CMPluginHandleSelection()

OSStatus CMPluginHandleSelection	(	void *	thisInstance,
		AEDesc *	inContext,
		SInt32	inCommandID
	)

CMPluginHandleSelection()

Implemented by client

CMPluginPostMenuCleanup()

void CMPluginPostMenuCleanup

(

void *

thisInstance

)

CMPluginPostMenuCleanup()

Implemented by client

ContextualMenuSelect()

OSStatus ContextualMenuSelect	(	MenuRef	inMenu,
		Point	inGlobalLocation,
		Boolean	inReserved,
		UInt32	inHelpType,
		ConstStr255Param	inHelpItemString,
		const AEDesc *	inSelection,
		UInt32 *	outUserSelectionType,
		SInt16 *	outMenuID,
		MenuItemIndex *	outMenuItem
	)

ContextualMenuSelect()

Non-Carbon CFM: in ContextualMenu 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

CopyMenuItemData()

OSStatus CopyMenuItemData	(	MenuRef	menu,
		MenuItemID	item,
		Boolean	isCommandID,
		MenuItemDataPtr	outData
	)

CopyMenuItemData()

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

CopyMenuItems()

OSStatus CopyMenuItems	(	MenuRef	inSourceMenu,
		MenuItemIndex	inFirstItem,
		ItemCount	inNumItems,
		MenuRef	inDestMenu,
		MenuItemIndex	inInsertAfter
	)

CopyMenuItems()

Summary: Copies menu items from one menu to another.

Parameters:

inSourceMenu: The menu from which to copy items.

inFirstItem: The first item to copy.

inNumItems: The number of items to copy.

inDestMenu: The menu to which to copy items.

inInsertAfter: The menu item in the destination menu after which to insert the copied items.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

CopyMenuItemTextAsCFString()

OSStatus CopyMenuItemTextAsCFString	(	MenuRef	inMenu,
		MenuItemIndex	inItem,
		CFStringRef *	outString
	)

CopyMenuItemTextAsCFString()

Summary: Returns a CFString containing the text of a menu item.

Parameters:

inMenu: The menu containing the item.

inItem: The item whose text to return.

outString: On exit, a CFString containing the item's text. This string must be released by the caller.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

CopyMenuTitleAsCFString()

OSStatus CopyMenuTitleAsCFString	(	MenuRef	inMenu,
		CFStringRef *	outString
	)

CopyMenuTitleAsCFString()

Summary: Returns a CFString containing the title of a menu.

Parameters:

inMenu: The menu whose title to return.

outString: On exit, a CFString containing the menu's title. This string must be released by the caller.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

CountMenuItemsWithCommandID()

ItemCount CountMenuItemsWithCommandID	(	MenuRef	inMenu,
		MenuCommand	inCommandID
	)

CountMenuItemsWithCommandID()

Summary: Counts the menu items with a specified command ID.

Discussion: In CarbonLib 1.0.x and 1.1, this API will always return zero or one; it stops after finding the first menu item with the specified command ID. In CarbonLib 1.2 and Mac OS X 1.0, it will count all menu items with the specified command ID.

Parameters:

inMenu: The menu in which to begin searching for items with the specified command ID. Pass NULL to hegin searching with the root menu. The search will descend into all submenus of this menu.

inCommandID: The command ID for which to search.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

CountMItems()

UInt16 CountMItems

(

MenuRef

theMenu

)

Find how many items are in a menu.

CountMItems returns the number of items in a specified menu. You may
use it as a way to get information about resource menus.
theMenu is a handle leading to a variable-length MenuInfo structure. It
identifies the menu about which you wish information.

Returns

a 16-bit short integer; the number of items in menu theMenu .

Note

For menus created in your application, you should probably keep track of
how many items are in each menu.
For menus containing items inserted via AddResMenu and
InsertResMenu , this provides a way to find the number of items inserted
into the menu. You can use the return value as an index limit in subsequent
operations that examine the menu items.
See GetItem for an example of usage.

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

CreateCustomMenu()

OSStatus CreateCustomMenu	(	const MenuDefSpec *	inDefSpec,
		MenuID	inMenuID,
		MenuAttributes	inMenuAttributes,
		MenuRef *	outMenuRef
	)

CreateCustomMenu()

Summary: Creates a new, untitled, empty menu using a custom menu definition function.

Discussion: Similar to CreateNewMenu, but also allows you to specify a custom menu definition function.

Parameters:

inDefSpec: Specifies a custom menu definition function. defSpec->defType must be kMenuDefProcPtr.

inMenuID: The menu ID to use for the new menu.

inMenuAttributes: The menu attributes to use for the new menu.

outMenuRef: On exit, contains the new menu.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

CreateNewMenu()

OSStatus CreateNewMenu	(	MenuID	inMenuID,
		MenuAttributes	inMenuAttributes,
		MenuRef *	outMenuRef
	)

CreateNewMenu()

Summary: Creates a new, untitled, empty menu.

Discussion: 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 can use either SetMenuTitle or SetMenuTitleWithCFString.

Parameters:

inMenuID: The menu ID to use for the new menu.

inMenuAttributes: The menu attributes to use for the new menu.

outMenuRef: On exit, contains the new menu.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

CreateStandardFontMenu()

OSStatus CreateStandardFontMenu	(	MenuRef	menu,
		MenuItemIndex	afterItem,
		MenuID	firstHierMenuID,
		OptionBits	options,
		ItemCount *	outHierMenuCount
	)

CreateStandardFontMenu()

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

DeleteMCEntries()

void DeleteMCEntries	(	MenuID	menuID,
		short	menuItem
	)

DeleteMCEntries()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

DeleteMenuItem()

void DeleteMenuItem	(	MenuRef	theMenu,
		short	item
	)

DeleteMenuItem()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

DeleteMenuItems()

OSStatus DeleteMenuItems	(	MenuRef	inMenu,
		MenuItemIndex	inFirstItem,
		ItemCount	inNumItems
	)

DeleteMenuItems()

Summary: Deletes multiple menu items.

Discussion: This API is more efficient than calling DeleteMenuItem multiple times.

Parameters:

inMenu: The menu from which to delete items.

inFirstItem: The first item to delete.

inNumItems: The number of items to delete.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

DisableAllMenuItems()

void DisableAllMenuItems

(

MenuRef

theMenu

)

DisableAllMenuItems()

Summary: Disables all items in a menu.

Discussion: This API is equivalent to pre-Carbon code that masked the enableFlags field of the MenuInfo with 0x01. It disables all items (including items past item 31) but does not affect the state of the menu title.

Parameters:

theMenu: The menu whose items to disable.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

DisableMenuCommand()

void DisableMenuCommand	(	MenuRef	inMenu,
		MenuCommand	inCommandID
	)

DisableMenuCommand()

Summary: Disables the menu item with a specified command ID.

Parameters:

inMenu: The menu in which to begin searching for the item. Pass NULL to begin searching with the root menu. The search will descend into all submenus of this menu.

inCommandID: The command ID of the menu item to be disabled. If more than one item has this command ID, only the first will be disabled.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

DisableMenuItem()

void DisableMenuItem	(	MenuRef	theMenu,
		MenuItemIndex	item
	)

DisableMenuItem()

Non-Carbon CFM: in MenusLib 8.5 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

DisableMenuItemIcon()

void DisableMenuItemIcon	(	MenuRef	theMenu,
		MenuItemIndex	item
	)

DisableMenuItemIcon()

Non-Carbon CFM: in MenusLib 8.5 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

DisposeMBarHookUPP()

void DisposeMBarHookUPP

(

MBarHookUPP

userUPP

)

DisposeMBarHookUPP()

Non-Carbon CFM: available as macro/inline

Carbon Lib: not available

Mac OS X: not available

DisposeMCInfo()

void DisposeMCInfo

(

MCTableHandle

menuCTbl

)

DisposeMCInfo()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

DisposeMenu()

void DisposeMenu

(

MenuRef

theMenu

)

DisposeMenu()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

DisposeMenuBar()

OSStatus DisposeMenuBar

(

MenuBarHandle

inMbar

)

DisposeMenuBar()

Summary: Releases a menubar handle.

Discussion: This API should be used in Carbon applications when releasing a handle returned from GetMenuBar or GetNewMBar. You should not use DisposeHandle to release such a handle. This is necessary in Carbon so that the refcounts of the menus in the menubar handle can be decremented when the handle is released.

Parameters:

inMbar: The menubar handle to release.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0.2 and later

Mac OS X: in version 10.0 and later

DisposeMenuBarDefUPP()

void DisposeMenuBarDefUPP

(

MenuBarDefUPP

userUPP

)

DisposeMenuBarDefUPP()

Non-Carbon CFM: available as macro/inline

Carbon Lib: not available

Mac OS X: not available

DisposeMenuDefUPP()

void DisposeMenuDefUPP

(

MenuDefUPP

userUPP

)

DisposeMenuDefUPP()

Non-Carbon CFM: available as macro/inline

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

DisposeMenuHookUPP()

void DisposeMenuHookUPP

(

MenuHookUPP

userUPP

)

DisposeMenuHookUPP()

Non-Carbon CFM: available as macro/inline

Carbon Lib: not available

Mac OS X: not available

DuplicateMenu()

OSStatus DuplicateMenu	(	MenuRef	inSourceMenu,
		MenuRef *	outMenu
	)

DuplicateMenu()

Summary: Creates a new menu that is a copy of another menu.

Discussion: Unlike CloneMenu, DuplicateMenu creates an entirely new menu that is an exact copy of the original menu. The MDEF for the new menu will receive an init message after the menu has been fully created.

Parameters:

inSourceMenu: The menu to duplicate.

outMenu: On exit, a copy of the source menu.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

DuplicateMenuBar()

OSStatus DuplicateMenuBar	(	MenuBarHandle	inMbar,
		MenuBarHandle *	outMbar
	)

DuplicateMenuBar()

Summary: Duplicates a menubar handle.

Discussion: This API should be used in Carbon applications when duplicating a handle returned from GetMenuBar or GetNewMBar. You should not use Memory Manager APIs (HandToHand, NewHandle, etc) to duplicate such a handle. This is necessary in Carbon so that the refcounts of the menus in the menubar handle can be incremented when the handle is duplicated.

Parameters:

inMbar: The menubar handle to duplicate.

outMbar: On exit, contains the new menubar handle.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0.2 and later

Mac OS X: in version 10.0 and later

EnableAllMenuItems()

void EnableAllMenuItems

(

MenuRef

theMenu

)

EnableAllMenuItems()

Summary: Enables all items in a menu.

Discussion: This API is equivalent to pre-Carbon code that or'd the enableFlags field of the MenuInfo with 0xFFFFFFFE. It enables all items (including items past item 31) but does not affect the state of the menu title.

Parameters:

theMenu: The menu whose items to enable.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

EnableMenuCommand()

void EnableMenuCommand	(	MenuRef	inMenu,
		MenuCommand	inCommandID
	)

EnableMenuCommand()

Summary: Enables the menu item with a specified command ID.

Parameters:

inMenu: The menu in which to begin searching for the item. Pass NULL to begin searching with the root menu. The search will descend into all submenus of this menu.

inCommandID: The command ID of the menu item to be enabled. If more than one item has this command ID, only the first will be enabled.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

EnableMenuItemIcon()

void EnableMenuItemIcon	(	MenuRef	theMenu,
		MenuItemIndex	item
	)

EnableMenuItemIcon()

Non-Carbon CFM: in MenusLib 8.5 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

EraseMenuBackground()

OSStatus EraseMenuBackground	(	MenuRef	inMenu,
		const Rect *	inEraseRect,
		CGContextRef	inContext
	)

EraseMenuBackground()

Summary: Erases a portion of a menu background in preparation for further drawing.

Discussion: It is necessary to erase the menu background before calling DrawThemeMenuBackground because some themes (such as Aqua on Mac OS X) draw the menu background using the alpha channel, and if the area underneath the menu background is not erased, portions of the old image will show through the menu background.

Parameters:

inMenu: The menu whose background to erase.

inEraseRect: The bounds of the area to erase, in local coordinates to the current port.

inContext: The CG context to erase. If NULL, EraseMenuBackground will create a context based on the current port.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.5 and later

Mac OS X: in version 10.1 and later

FlashMenuBar()

void FlashMenuBar

(

MenuID

menuID

)

FlashMenuBar()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetFontFamilyFromMenuSelection()

OSStatus GetFontFamilyFromMenuSelection	(	MenuRef	menu,
		MenuItemIndex	item,
		FMFontFamily *	outFontFamily,
		FMFontStyle *	outStyle
	)

GetFontFamilyFromMenuSelection()

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetIndMenuItemWithCommandID()

OSStatus GetIndMenuItemWithCommandID	(	MenuRef	inMenu,
		MenuCommand	inCommandID,
		UInt32	inItemIndex,
		MenuRef *	outMenu,
		MenuItemIndex *	outIndex
	)

GetIndMenuItemWithCommandID()

Summary: Finds a menu item with a specified command ID.

Discussion: This API searches the specified menu and its submenus for the n'th menu item with the specified command ID. In CarbonLib 1.0.x and 1.1, only the first menu item will be returned. In CarbonLib 1.2 and Mac OS X 1.0, this API will iterate over all menu items with the specified command ID.

Parameters:

inMenu: The menu in which to begin searching for items with the specified command ID. Pass NULL to hegin searching with the root menu. The search will descend into all submenus of this menu.

inCommandID: The command ID for which to search.

inItemIndex: The 1-based index of the menu item to retrieve. In CarbonLib 1.0.x and 1.1, this parameter must be 1. In CarbonLib 1.2 and Mac OS X 1.0, this parameter may vary from 1 to the number of menu items with the specified command ID.

outMenu: On exit, the menu containing the menu item with the specified command ID.

outIndex: On exit, the item index of the menu item with the specified command ID.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetItemCmd()

void GetItemCmd	(	MenuRef	theMenu,
		short	item,
		CharParameter *	cmdChar
	)

Query current command character of a menu item.

GetItemCmd copies the command character of a selected menu item into the
caller's variable. A command character is normally assigned when a menu
item is inserted or appended (see InsMenuItem and AppendMenu ) with the
item text containing a metacharacter of " /". It is the command-key code that
is assigned to a menu item (as obtained via MenuKey ).
theMenu is a handle leading to a variable-length MenuInfo structure. It
identifies the menu containing the item whose command character
you wish to obtain.
whichItem identifies which item in menu theMenu to query. Items are
numbered sequentially with the topmost item having an ID of 1.
cmdChar is the address of a 2-byte buffer. Upon return, the byte will
contain the ASCII value of the current command character.  If the
return value is hMenuCmd (0x1B), the menu item has a submenu. A
returned value of 0 indicates that no command character is currently
assigned.
The designation as a short* is not a typo. Pascal CHAR data types
are actually 16-bit words.  Using a 1-byte char variable will cause
the Menu Manager to overwrite the next higher byte in memory.

Returns

none

Note

GetItemCmd is new with the 256K ROMs and might be handy for working
with hierarchical menu systems. If the value returned in cmdChar  is
0x1B, you may use GetItemMark to learn the ID of the submenu associated
with item whichItem .
Most applications, having defined each menu internally, will already know
the command key equivalent of each menu item; therefore, this function is
needed rarely.

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetItemIcon()

void GetItemIcon	(	MenuRef	theMenu,
		short	item,
		short *	iconIndex
	)

See which icon, if any, is attached to a menu item.

GetItemIcon obtains a value indicating which icon, if any, is associated with
a specified menu item. This can be used to see if a previous SetItemIcon call
succeeded.
theMenu is a handle leading to a variable-length MenuInfo structure. It
identifies the menu containing the item whose icon you wish to query.
whichItem identifies which item in theMenu to query. Items are numbered
sequentially with the topmost item having an ID of 1.
iconis the address of a 16-bit short integer. Upon return, it will
contain 0 if no icon is associated with the menu item. Otherwise, it
returns a value ranging from 1 to 255 that is 256 less than the
resource ID of the 'ICON' or 'cicn' resource. For instance, if this
contains 3, the resource ID of the icon is 259.
The designation as a short* is not a typo. A Pascal Byte data type is
actually a 16-bit word. If you use a 1-byte char variable, the Menu
Manager will overwrite the byte above it.

Returns

none

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetItemMark()

void GetItemMark	(	MenuRef	theMenu,
		short	item,
		CharParameter *	markChar
	)

Query the current mark character of a menu item.

GetItemMark copies the mark character of a selected menu item into the
caller's variable. A mark character is any character, such as a check mark,
that is displayed to the left of the menu item's text.
On 256K ROMs, this returns the menu ID of a submenu (i.e., a menu whose
command character is 0x1B).
theMenu is a handle leading to a variable-length MenuInfo structure. It
identifies the menu containing the item whose mark you wish to
obtain.
whichItem identifies which item in menu theMenu to query. Items are
numbered sequentially with the topmost item having an ID of 1.
markChar is the address of a 2-byte buffer. Upon return, the low byte will
contain the ASCII value of the current mark character. If the value
equates with the defined constant noMark (0), no mark is currently
present.
If whichItem  is a submenu (i.e., its command character is 0x1B),
this returns the menu ID of the that submenu.
The designation as a short* is not a typo. Pascal CHAR data types
are actually 16-bit words.  Using a 1-byte char variable will cause
the Menu Manager to overwrite the next higher byte in memory.

Returns

none

Note

This function can be used as an aid in deciding which way to toggle the mark
after the user selects an item. For instance:
shortcurMark;
GetItemMark ( theMenu, theItem, &curMark );
if ( curMark == noMark)
CheckItem ( theMenu, theItem, TRUE );
else
CheckItem ( theMenu, theItem, FALSE );
Most applications keep track of the current state of each item separately;
whether it is enabled or disabled, marked or unmarked, this function is used
rarely.

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetItemStyle()

void GetItemStyle	(	MenuRef	theMenu,
		short	item,
		Style *	chStyle
	)

Obtain the current character formatting of a menu item.

  @par Non-Carbon CFM:   in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMBarHeight()

short GetMBarHeight

(

void

)

Fetch the height of the menu bar.

GetMBarHeight gets the height of the menu bar as required to hold menu
titles in its current font.

Note

This routine is in the Pascal interface, not ROM and can't be used with the
64K ROM.

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMCInfo()

MCTableHandle GetMCInfo

(

void

)

GetMCInfo()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuAttributes()

OSStatus GetMenuAttributes	(	MenuRef	menu,
		MenuAttributes *	outAttributes
	)

GetMenuAttributes()

Summary: Gets the attributes of a menu.

Parameters:

menu: The menu.

outAttributes: On exit, contains the attributes of the menu.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuBar()

MenuBarHandle GetMenuBar

(

void

)

GetMenuBar()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuCommandMark()

OSStatus GetMenuCommandMark	(	MenuRef	inMenu,
		MenuCommand	inCommandID,
		UniChar *	outMark
	)

GetMenuCommandMark()

Summary: Locates the menu item with a specified command ID and returns its mark character.

Parameters:

inMenu: The menu in which to begin searching for the item. Pass NULL to begin searching with the root menu. The search will descend into all submenus of this menu.

inCommandID: The command ID of the menu item to be examined. If more than one item has this command ID, only the first will be examined.

outMark: On exit, the menu item's mark character.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

GetMenuCommandProperty()

OSStatus GetMenuCommandProperty	(	MenuRef	inMenu,
		MenuCommand	inCommandID,
		OSType	inPropertyCreator,
		OSType	inPropertyTag,
		ByteCount	inBufferSize,
		ByteCount *	outActualSize,
		void *	inPropertyBuffer
	)

GetMenuCommandProperty()

Summary: Retrives property data for a menu item with a specified command ID.

Parameters:

inMenu: The menu in which to begin searching for the item. Pass NULL to begin searching with the root menu. The search will descend into all submenus of this menu.

inCommandID: The command ID of the menu item containing the property. If more than one item has this command ID, only the first will be used.

inPropertyCreator: The property creator.

inPropertyTag: The property tag.

inBufferSize: The size of the output buffer, in bytes.

outActualSize: On exit, contains the actual size of the property data. May be NULL if you do not need this information.

inPropertyBuffer: The address of a buffer in which to place the property data.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuCommandPropertySize()

OSStatus GetMenuCommandPropertySize	(	MenuRef	inMenu,
		MenuCommand	inCommandID,
		OSType	inPropertyCreator,
		OSType	inPropertyTag,
		ByteCount *	outSize
	)

GetMenuCommandPropertySize()

Summary: Retrives the size of property data for a menu item with a specified command ID.

Parameters:

inMenu: The menu in which to begin searching for the item. Pass NULL to begin searching with the root menu. The search will descend into all submenus of this menu.

inCommandID: The command ID of the menu item containing the property. If more than one item has this command ID, only the first will be used.

inPropertyCreator: The property creator.

inPropertyTag: The property tag.

outSize: On exit, contains the size of the property data.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuDefinition()

OSStatus GetMenuDefinition	(	MenuRef	menu,
		MenuDefSpecPtr	outDefSpec
	)

GetMenuDefinition()

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuExcludesMarkColumn()

Boolean GetMenuExcludesMarkColumn

(

MenuRef

menu

)

GetMenuExcludesMarkColumn()

Non-Carbon CFM: in MenusLib 8.5 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuFont()

OSStatus GetMenuFont	(	MenuRef	menu,
		SInt16 *	outFontID,
		UInt16 *	outFontSize
	)

GetMenuFont()

Non-Carbon CFM: in MenusLib 8.5 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuHandle()

MenuRef GetMenuHandle

(

MenuID

menuID

)

GetMenuHandle()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuHeight()

SInt16 GetMenuHeight

(

MenuRef

menu

)

GetMenuHeight()

Non-Carbon CFM: in CarbonAccessors.o 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuID()

MenuID GetMenuID

(

MenuRef

menu

)

GetMenuID()

Non-Carbon CFM: in CarbonAccessors.o 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuItemAttributes()

OSStatus GetMenuItemAttributes	(	MenuRef	menu,
		MenuItemIndex	item,
		MenuItemAttributes *	outAttributes
	)

GetMenuItemAttributes()

Summary: Gets the attributes of a menu item.

Parameters:

menu: The menu.

item: The menu item.

outAttributes: On exit, contains the attributes of the menu item.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuItemCommandID()

OSErr GetMenuItemCommandID	(	MenuRef	inMenu,
		SInt16	inItem,
		MenuCommand *	outCommandID
	)

GetMenuItemCommandID()

Non-Carbon CFM: in AppearanceLib 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuItemCommandKey()

OSStatus GetMenuItemCommandKey	(	MenuRef	inMenu,
		MenuItemIndex	inItem,
		Boolean	inGetVirtualKey,
		UInt16 *	outKey
	)

GetMenuItemCommandKey()

Summary: Gets the keyboard equivalent of a menu item.

Discussion: A menu item's keyboard equivalent may be either a character code or a virtual keycode. An item's character code and virtual keycode are stored separately and may contain different values, but only one is used by the Menu Manager at any given time. When requesting a menu item's virtual keycode equivalent, you should first check that the item is using a virtual keycode by testing the kMenuItemAttrUseVirtualKey attribute for that item. If this attribute is not set, the item's virtual keycode is ignored by the Menu Manager. Note that zero is a valid virtual keycode, so you cannot test the returned keycode against zero to determine if the item is using a virtual keycode equivalent. You must test the kMenuItemAttrUseVirtualKey attribute.

Parameters:

inMenu: The menu containing the item.

inItem: The item whose keyboard equivalent to retrieve.

inGetVirtualKey: Indicates whether to retrieve the item's character code or virtual keycode equivalent.

outKey: On exit, the keyboard equivalent of the item.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

GetMenuItemFontID()

OSErr GetMenuItemFontID	(	MenuRef	inMenu,
		SInt16	inItem,
		SInt16 *	outFontID
	)

GetMenuItemFontID()

Non-Carbon CFM: in AppearanceLib 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuItemHierarchicalID()

OSErr GetMenuItemHierarchicalID	(	MenuRef	inMenu,
		SInt16	inItem,
		MenuID *	outHierID
	)

GetMenuItemHierarchicalID()

Non-Carbon CFM: in AppearanceLib 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuItemHierarchicalMenu()

OSStatus GetMenuItemHierarchicalMenu	(	MenuRef	inMenu,
		MenuItemIndex	inItem,
		MenuRef *	outHierMenu
	)

GetMenuItemHierarchicalMenu()

Summary: Returns the submenu attached to a menu item.

Discussion: GetMenuItemHierarchicalMenu will return the submenu attached to a menu item regardless of how the submenu was specified. If the submenu was specified by menu ID (using SetItemCmd or SetMenuItemHierarchicalID), GetMenuItemHierarchicalMenu will return the currently installed menu with that ID, if any. The only case where GetMenuItemHierarchicalMenu will fail to return the item's submenu is when the submenu is specified by menu ID, but the submenu is not currently inserted in the menu bar.

Parameters:

inMenu: The parent menu.

inItem: The parent item.

outHierMenu: On exit, the item's submenu, or NULL if it does not have one.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

GetMenuItemIconHandle()

OSErr GetMenuItemIconHandle	(	MenuRef	inMenu,
		SInt16	inItem,
		UInt8 *	outIconType,
		Handle *	outIconHandle
	)

GetMenuItemIconHandle()

Non-Carbon CFM: in AppearanceLib 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuItemIndent()

OSStatus GetMenuItemIndent	(	MenuRef	inMenu,
		MenuItemIndex	inItem,
		UInt32 *	outIndent
	)

GetMenuItemIndent()

Summary: Gets the indent level of a menu item.

Discussion: The indent level of an item is an amount of extra space added to the left of the item's icon or checkmark. The level is simply a number, starting at zero, which the Menu Manager multiplies by a constant to get the indent in pixels. The default indent level is zero.

Parameters:

inMenu: The menu containing the item.

inItem: The item whose indent to retrieve.

outIndent: On exit, the indent level of the item.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

GetMenuItemKeyGlyph()

OSErr GetMenuItemKeyGlyph	(	MenuRef	inMenu,
		SInt16	inItem,
		SInt16 *	outGlyph
	)

GetMenuItemKeyGlyph()

Non-Carbon CFM: in AppearanceLib 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuItemModifiers()

OSErr GetMenuItemModifiers	(	MenuRef	inMenu,
		SInt16	inItem,
		UInt8 *	outModifiers
	)

GetMenuItemModifiers()

Non-Carbon CFM: in AppearanceLib 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuItemProperty()

OSStatus GetMenuItemProperty	(	MenuRef	menu,
		MenuItemIndex	item,
		OSType	propertyCreator,
		OSType	propertyTag,
		UInt32	bufferSize,
		UInt32 *	actualSize,
		void *	propertyBuffer
	)

GetMenuItemProperty()

Non-Carbon CFM: in MenusLib 8.5 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuItemPropertyAttributes()

OSStatus GetMenuItemPropertyAttributes	(	MenuRef	menu,
		MenuItemIndex	item,
		OSType	propertyCreator,
		OSType	propertyTag,
		UInt32 *	attributes
	)

GetMenuItemPropertyAttributes()

Summary: Gets the attributes of a menu item property.

Parameters:

menu: The menu.

item: The menu item.

propertyCreator: The creator code of the property.

propertyTag: The property tag.

attributes: On exit, contains the attributes of the property.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuItemPropertySize()

OSStatus GetMenuItemPropertySize	(	MenuRef	menu,
		MenuItemIndex	item,
		OSType	propertyCreator,
		OSType	propertyTag,
		UInt32 *	size
	)

GetMenuItemPropertySize()

Non-Carbon CFM: in MenusLib 8.5 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuItemRefCon()

OSErr GetMenuItemRefCon	(	MenuRef	inMenu,
		SInt16	inItem,
		UInt32 *	outRefCon
	)

GetMenuItemRefCon()

Non-Carbon CFM: in AppearanceLib 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuItemRefCon2()

OSErr GetMenuItemRefCon2	(	MenuRef	inMenu,
		SInt16	inItem,
		UInt32 *	outRefCon2
	)

GetMenuItemRefCon2()

Non-Carbon CFM: in AppearanceLib 1.0 and later

Carbon Lib: not available

Mac OS X: not available

getmenuitemtext()

void getmenuitemtext	(	MenuRef	menu,
		short	item,
		char *	itemString
	)

getmenuitemtext()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

GetMenuItemText()

void GetMenuItemText	(	MenuRef	theMenu,
		short	item,
		Str255	itemString
	)

GetMenuItemText()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuItemTextEncoding()

OSErr GetMenuItemTextEncoding	(	MenuRef	inMenu,
		SInt16	inItem,
		TextEncoding *	outScriptID
	)

GetMenuItemTextEncoding()

Non-Carbon CFM: in AppearanceLib 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuRetainCount()

ItemCount GetMenuRetainCount

(

MenuRef

inMenu

)

GetMenuRetainCount()

Summary: Returns the retain count of this menu.

Parameters:

inMenu: The menu whose retain count to increment.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

GetMenuTitle()

StringPtr GetMenuTitle	(	MenuRef	menu,
		Str255	title
	)

GetMenuTitle()

Non-Carbon CFM: in CarbonAccessors.o 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuTitleIcon()

OSStatus GetMenuTitleIcon	(	MenuRef	inMenu,
		UInt32 *	outType,
		void **	outIcon
	)

GetMenuTitleIcon()

Summary: Retrieves the icon, if any, being used as the title of a menu.

Discussion: This API does not increment a refcount on the returned icon. The caller should not release the icon.

Parameters:

inMenu: The menu whose icon title to retrieve.

outType: On exit, contains the type of icon being used as the title of the menu. Contains kMenuNoIcon if the menu does not have an icon title.

outIcon: On exit, contains the IconSuiteRef or IconRef being used as the title of the menu, or NULL if the menu does not have an icon title. May be NULL.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

GetMenuTrackingData()

OSStatus GetMenuTrackingData	(	MenuRef	theMenu,
		MenuTrackingData *	outData
	)

GetMenuTrackingData()

Summary: Gets information about the menu currently selected by the user.

Discussion: This API replaces direct access to the low-memory globals TopMenuItem, AtMenuBottom, MenuDisable, and mbSaveLoc. It is only valid to call this API while menu tracking is occurring. This API will most commonly be used by custom MDEFs.

Parameters:

theMenu: The menu about which to get tracking information. May be NULL to get information about the menu that the user is currently selecting. If the menu is not currently open, menuNotFoundErr is returned.

outData: On exit, contains tracking data about the menu. On CarbonLib, the itemRect field is not supported and is always set to an empty rect.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetMenuType()

OSStatus GetMenuType	(	MenuRef	theMenu,
		UInt16 *	outType
	)

GetMenuType()

Summary: Gets the display type (pulldown, hierarchical, or popup) of a menu.

Discussion: This API may only be called when the menu is displayed. If the menu is not currently open, an error is returned. The display type of a menu may vary from one menu tracking session to another; for example, the same menu might be displayed as a pulldown menu and as a popup menu.

Parameters:

theMenu: The menu whose type to get.

outType: On exit, the type of the menu. The returned value will be one of the ThemeMenuType constants: kThemeMenuTypePullDown, PopUp, or Hierarchical. The kThemeMenuTypeInactive bit will never be set.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

GetMenuWidth()

SInt16 GetMenuWidth

(

MenuRef

menu

)

GetMenuWidth()

Non-Carbon CFM: in CarbonAccessors.o 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

GetNewMBar()

MenuBarHandle GetNewMBar

(

short

menuBarID

)

GetNewMBar()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

HideMenuBar()

void HideMenuBar

(

void

)

HideMenuBar()

Non-Carbon CFM: in MenusLib 8.5 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

HiliteMenu()

void HiliteMenu

(

MenuID

menuID

)

HiliteMenu()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

InitContextualMenus()

OSStatus InitContextualMenus

(

void

)

InitContextualMenus()

Non-Carbon CFM: in ContextualMenu 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

InitMenus()

void InitMenus

(

void

)

InitMenus()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

InitProcMenu()

void InitProcMenu

(

short

resID

)

InitProcMenu()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

InsertFontResMenu()

void InsertFontResMenu	(	MenuRef	theMenu,
		short	afterItem,
		short	scriptFilter
	)

InsertFontResMenu()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

InsertIntlResMenu()

void InsertIntlResMenu	(	MenuRef	theMenu,
		ResType	theType,
		short	afterItem,
		short	scriptFilter
	)

InsertIntlResMenu()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

insertmenuitem()

void insertmenuitem	(	MenuRef	theMenu,
		const char *	itemString,
		short	afterItem
	)

insertmenuitem()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

InsertMenuItemText()

OSStatus InsertMenuItemText	(	MenuRef	menu,
		ConstStr255Param	inString,
		MenuItemIndex	afterItem
	)

InsertMenuItemText()

Non-Carbon CFM: in MenusLib 8.5 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

InsertMenuItemTextWithCFString()

OSStatus InsertMenuItemTextWithCFString	(	MenuRef	inMenu,
		CFStringRef	inString,
		MenuItemIndex	inAfterItem,
		MenuItemAttributes	inAttributes,
		MenuCommand	inCommandID
	)

InsertMenuItemTextWithCFString()

Summary: Inserts a new menu item with text from a CFString.

Discussion: The Menu Manager will either make its own copy or just increment the refcount of the CFString before returning from InsertMenuItemWithCFString, depending on whether the string is mutable or immutable. If the string is mutable, modifying the string after calling InsertMenuItemWithCFString will have no effect on the menu item's actual text. The caller may release the string after calling InsertMenuItemWithCFString.

Parameters:

inMenu: The menu in which to insert the new item.

inString: The text of the new item.

inAfterItem: The item after which to insert the new item.

inAttributes: The attributes of the new item.

inCommandID: The command ID of the new item.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

InsertResMenu()

void InsertResMenu	(	MenuRef	theMenu,
		ResType	theType,
		short	afterItem
	)

InsertResMenu()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

InvalidateMenuEnabling()

OSStatus InvalidateMenuEnabling

(

MenuRef

inMenu

)

InvalidateMenuEnabling()

Summary: Causes the menu enable state to be recalculated at the next convenient opportunity.

Discussion: It is common for state changes in an application (for example, selection of text) to cause a change in the enabling of items in the application's menu (for example, the Copy menu item might become enabled). In a Carbon-event-savvy application, menu items are enabled or disabled in response to an kEventCommandUpdateStatus event; however, this event is normally only sent before a command key press or a click in the menubar. You can request an explicit recalculation of a menu's enable state with the InvalidateMenuEnabling API. The Carbon Event Manager will automatically invalidate the enable state of all top-level menus when a user event is dispatched, the user focus changes, or the active window changes, so in many cases you will not need to explicitly invalidate the menu enabling state.

Parameters:

inMenu: A menu to re-enable, or NULL if all menus in the root menu should be re-enabled.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.3 and later

Mac OS X: in version 10.0 and later

InvalidateMenuItems()

OSStatus InvalidateMenuItems	(	MenuRef	menu,
		MenuItemIndex	firstItem,
		ItemCount	numItems
	)

InvalidateMenuItems()

Summary: Invalidates a group of menu items so that they will be redrawn when UpdateInvalidMenuItems is next called.

Discussion: Menu items are automatically invalidated when their contents are changed using Menu Manager APIs while the menu is open. However, you might need to use this API if you have a custom MDEF that draws using state not contained in the menu.

Parameters:

menu: The menu whose items to invalidate.

firstItem: The first item to invalidate.

numItems: The number of items to invalidate.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

InvalidateMenuSize()

OSStatus InvalidateMenuSize

(

MenuRef

inMenu

)

InvalidateMenuSize()

Summary: Invalidates the menu size so that it will be recalculated when next displayed.

Discussion: The pre-Carbon technique for invalidating the menu size was to set the width and height to -1. Although this technique still works, for best compatibility it's preferable to use the InvalidateMenuSize API so that the Menu Manager has explicit notification that the menu is invalid.

Parameters:

inMenu: The menu whose size to invalidate.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

InvalMenuBar()

void InvalMenuBar

(

void

)

InvalMenuBar()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

InvokeMBarHookUPP()

short InvokeMBarHookUPP	(	Rect *	menuRect,
		MBarHookUPP	userUPP
	)

InvokeMBarHookUPP()

Non-Carbon CFM: available as macro/inline

Carbon Lib: not available

Mac OS X: not available

InvokeMenuBarDefUPP()

long InvokeMenuBarDefUPP	(	short	selector,
		short	message,
		short	parameter1,
		long	parameter2,
		MenuBarDefUPP	userUPP
	)

InvokeMenuBarDefUPP()

Non-Carbon CFM: available as macro/inline

Carbon Lib: not available

Mac OS X: not available

InvokeMenuDefUPP()

void InvokeMenuDefUPP	(	short	message,
		MenuRef	theMenu,
		Rect *	menuRect,
		Point	hitPt,
		short *	whichItem,
		MenuDefUPP	userUPP
	)

InvokeMenuDefUPP()

Non-Carbon CFM: available as macro/inline

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

InvokeMenuHookUPP()

void InvokeMenuHookUPP

(

MenuHookUPP

userUPP

)

InvokeMenuHookUPP()

Non-Carbon CFM: available as macro/inline

Carbon Lib: not available

Mac OS X: not available

IsMenuBarInvalid()

Boolean IsMenuBarInvalid

(

MenuRef

rootMenu

)

IsMenuBarInvalid()

Summary: Determines if the menubar is invalid and should be redrawn.

Parameters:

rootMenu: The root menu for the menubar to be examined. Pass NULL to check the state of the current menubar.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

IsMenuBarVisible()

Boolean IsMenuBarVisible

(

void

)

IsMenuBarVisible()

Non-Carbon CFM: in MenusLib 8.5 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

IsMenuCommandEnabled()

Boolean IsMenuCommandEnabled	(	MenuRef	inMenu,
		MenuCommand	inCommandID
	)

IsMenuCommandEnabled()

Summary: Determines if the menu item with a specified command ID is enabled.

Parameters:

inMenu: The menu in which to begin searching for the item. Pass NULL to begin searching with the root menu. The search will descend into all submenus of this menu.

inCommandID: The command ID of the menu item to examine. If more than one item has this command ID, only the first will be examined.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

IsMenuItemEnabled()

Boolean IsMenuItemEnabled	(	MenuRef	menu,
		MenuItemIndex	item
	)

IsMenuItemEnabled()

Non-Carbon CFM: in MenusLib 8.5 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

IsMenuItemIconEnabled()

Boolean IsMenuItemIconEnabled	(	MenuRef	menu,
		MenuItemIndex	item
	)

IsMenuItemIconEnabled()

Non-Carbon CFM: in MenusLib 8.5 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

IsMenuItemInvalid()

Boolean IsMenuItemInvalid	(	MenuRef	menu,
		MenuItemIndex	item
	)

IsMenuItemInvalid()

Summary: Determines if a menu item is invalid and should be redrawn.

Parameters:

menu: The menu whose item to examine.

item: The item to examine.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

IsMenuKeyEvent()

Boolean IsMenuKeyEvent	(	MenuRef	inStartMenu,
		EventRef	inEvent,
		MenuEventOptions	inOptions,
		MenuRef *	outMenu,
		MenuItemIndex *	outMenuItem
	)

IsMenuKeyEvent()

Summary: Determines if an event corresponds to a menu command key.

Discussion: By default, IsMenuKeyEvent searches the menus in the current menu bar and hilites the menu title of the menu containing the selected item.

Parameters:

inStartMenu: IsMenuKeyEvent searches for matching menu items in this menu and all of its submenus. May be NULL to search the current menu bar contents.

inEvent: The event to match against. Non-keyboard events are ignored.

inOptions: Options controlling how to search. Pass kNilOptions for the default behavior.

outMenu: On exit, the menu containing the matching item. May be NULL.

outMenuItem: On exit, the menu item that matched. May be NULL.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

IsMenuSizeInvalid()

Boolean IsMenuSizeInvalid

(

MenuRef

inMenu

)

IsMenuSizeInvalid()

Summary: Determines if a menu's size is invalid and should be recalculated.

Discussion: The pre-Carbon technique for determining if a menu's size is invalid was to check if the width or height was -1. This technique is not always reliable on Carbon due to implementation changes in the Menu Manager. You should now use IsMenuSizeInvalid instead.

Parameters:

inMenu: The menu whose size to examine.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

IsShowContextualMenuClick()

Boolean IsShowContextualMenuClick

(

const EventRecord *

inEvent

)

IsShowContextualMenuClick()

Non-Carbon CFM: in ContextualMenu 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

IsShowContextualMenuEvent()

Boolean IsShowContextualMenuEvent

(

EventRef

inEvent

)

IsShowContextualMenuEvent()

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

IsValidMenu()

Boolean IsValidMenu

(

MenuRef

inMenu

)

IsValidMenu()

Summary: Determines if a menu is valid.

Parameters:

inMenu: The menu to check for validity.

Result: Indicates whether the menu is valid.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

LMGetTheMenu()

SInt16 LMGetTheMenu

(

void

)

LMGetTheMenu()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

MacAppendMenu()

void MacAppendMenu	(	MenuRef	menu,
		ConstStr255Param	data
	)

[Mac]AppendMenu()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

MacCheckMenuItem()

void MacCheckMenuItem	(	MenuRef	theMenu,
		short	item,
		Boolean	checked
	)

[Mac]CheckMenuItem()

Non-Carbon CFM: in CarbonAccessors.o 1.3 and later or as macro/inline

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

MacDeleteMenu()

void MacDeleteMenu

(

MenuID

menuID

)

[Mac]DeleteMenu()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

MacDrawMenuBar()

void MacDrawMenuBar

(

void

)

[Mac]DrawMenuBar()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

MacGetMenu()

MenuRef MacGetMenu

(

short

resourceID

)

[Mac]GetMenu()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

MacInsertMenu()

void MacInsertMenu	(	MenuRef	theMenu,
		MenuID	beforeID
	)

[Mac]InsertMenu()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

MacInsertMenuItem()

void MacInsertMenuItem	(	MenuRef	theMenu,
		ConstStr255Param	itemString,
		short	afterItem
	)

[Mac]InsertMenuItem()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

MenuChoice()

long MenuChoice

(

void

)

See if user attempted to select a disabled item.

MenuChoice can be called after a previous call to MenuSelect returns 0
(i.e., no selection made). It identifies the menu and item at which the mouse
was pointing when the button was released (even if the item is disabled).

Returns

a 32-bit long that indicates which menu and item was pointed to by
the mouse. It is made up of two values as follows:
High Word menu ID of disabled "selection"
Low Word item number of "selection". If 0, then the mouse
was over the menu title or outside the menu.

Note

This can be used to see if the user has chosen a disabled item from a menu
at which point you could display a help message.
MenuChoice works by returning the current value in MenuDisable (and
on older Mac systems, you can read this variable to obtain the item
number). If you create a Custom Menus , this function will return
garbage unless your custom code puts the information into that variable.

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

MenuEvent()

UInt32 MenuEvent

(

const EventRecord *

inEvent

)

MenuEvent()

Non-Carbon CFM: in AppearanceLib 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

MenuHasEnabledItems()

Boolean MenuHasEnabledItems

(

MenuRef

theMenu

)

MenuHasEnabledItems()

Summary: Determines if any items in a menu are enabled.

Discussion: This API is equivalent to pre-Carbon code that compared the enableFlags field of the MenuInfo with 0. It checks the enable state of all items to see if any are enabled, but ignores the state of the menu title. It will return true even if the menu title is disabled.

Parameters:

theMenu: The menu whose items to examine.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

MenuKey()

long MenuKey

(

CharParameter

ch

)

MenuKey()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

menuselect()

long menuselect

(

const Point *

startPt

)

menuselect()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

MenuSelect()

long MenuSelect

(

Point

startPt

)

MenuSelect()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

NewMBarHookUPP()

MBarHookUPP NewMBarHookUPP

(

MBarHookProcPtr

userRoutine

)

NewMBarHookUPP()

Non-Carbon CFM: available as macro/inline

Carbon Lib: not available

Mac OS X: not available

newmenu()

MenuRef newmenu	(	MenuID	menuID,
		const char *	menuTitle
	)

newmenu()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

NewMenu()

MenuRef NewMenu	(	MenuID	menuID,
		ConstStr255Param	menuTitle
	)

NewMenu()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

NewMenuBarDefUPP()

MenuBarDefUPP NewMenuBarDefUPP

(

MenuBarDefProcPtr

userRoutine

)

NewMenuBarDefUPP()

Non-Carbon CFM: available as macro/inline

Carbon Lib: not available

Mac OS X: not available

NewMenuDefUPP()

MenuDefUPP NewMenuDefUPP

(

MenuDefProcPtr

userRoutine

)

NewMenuDefUPP()

Non-Carbon CFM: available as macro/inline

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

NewMenuHookUPP()

MenuHookUPP NewMenuHookUPP

(

MenuHookProcPtr

userRoutine

)

NewMenuHookUPP()

Non-Carbon CFM: available as macro/inline

Carbon Lib: not available

Mac OS X: not available

PopUpMenuSelect()

long PopUpMenuSelect	(	MenuRef	menu,
		short	top,
		short	left,
		short	popUpItem
	)

PopUpMenuSelect()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

ProcessIsContextualMenuClient()

Boolean ProcessIsContextualMenuClient

(

ProcessSerialNumber *

inPSN

)

ProcessIsContextualMenuClient()

Non-Carbon CFM: in ContextualMenu 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

RegisterMenuDefinition()

OSStatus RegisterMenuDefinition	(	SInt16	inResID,
		MenuDefSpecPtr	inDefSpec
	)

RegisterMenuDefinition()

Summary: Registers or unregisters a binding between a resource ID and a menu definition function.

Discussion: In the Mac OS 8.x Menu Manager, a 'MENU' resource can contain an embedded MDEF procID that is used by the Menu Manager as the resource ID of an 'MDEF' resource to measure and draw the menu. The 'MDEF' resource is loaded by the Menu Manager when you load the menu with GetMenu. Since MDEFs can no longer be packaged as code resources on Carbon, the procID can no longer refer directly to an MDEF resource. However, using RegisterMenuDefinition you can instead specify a UniversalProcPtr pointing to code in your application code fragment.

Parameters:

inResID: An MDEF proc ID, as used in a 'MENU' resource.

inDefSpec: Specifies the MenuDefUPP that should be used for menus with the given MDEF proc ID. Passing NULL allows you to unregister the menu definition that had been associated with the given MDEF proc ID.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

ReleaseMenu()

OSStatus ReleaseMenu

(

MenuRef

inMenu

)

ReleaseMenu()

Summary: Decrements the retain count of a menu.

Discussion: If called on a menu that was not created by CarbonLib, it will not affect the menu's retain count.

Parameters:

inMenu: The menu whose retain count to decrement. If the retain count falls to zero, the menu is destroyed.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

RemoveMenuCommandProperty()

OSStatus RemoveMenuCommandProperty	(	MenuRef	inMenu,
		MenuCommand	inCommandID,
		OSType	inPropertyCreator,
		OSType	inPropertyTag
	)

RemoveMenuCommandProperty()

Summary: Removes a property from a menu item with a specified command ID.

Parameters:

inMenu: The menu in which to begin searching for the item. Pass NULL to begin searching with the root menu. The search will descend into all submenus of this menu.

inCommandID: The command ID of the menu item from which the property will be removed. If more than one item has this command ID, only the first will be modified.

inPropertyCreator: The property creator.

inPropertyTag: The property tag.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

RemoveMenuItemProperty()

OSStatus RemoveMenuItemProperty	(	MenuRef	menu,
		MenuItemIndex	item,
		OSType	propertyCreator,
		OSType	propertyTag
	)

RemoveMenuItemProperty()

Non-Carbon CFM: in MenusLib 8.5 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

RetainMenu()

OSStatus RetainMenu

(

MenuRef

inMenu

)

RetainMenu()

Summary: Increments the retain count of a menu.

Discussion: RetainMenu does not create a new menu. It simply adds one to the retain count. If called on a menu that was not created by CarbonLib, it will not affect the menu's retain count.

Parameters:

inMenu: The menu whose retain count to increment.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

ScrollMenuImage()

OSStatus ScrollMenuImage	(	MenuRef	inMenu,
		const Rect *	inScrollRect,
		int	inHScroll,
		int	inVScroll,
		CGContextRef	inContext
	)

ScrollMenuImage()

Summary: Scrolls a portion of the menu image.

Discussion: Menus on Mac OS X use an alpha channel, and QuickDraw does not support alpha channels. Therefore, scrolling a menu image with ScrollRect or other QuickDraw APIs does not work correctly; it results in the destruction of the alpha channel data. The ScrollMenuImage API uses CoreGraphics to move the menu image, preserving the alpha channel.

Parameters:

inMenu: The menu whose image to scroll.

inScrollRect: The bounds of the rect to scroll.

inHScroll: The distance to scroll horizontally.

inVScroll: The distance to scroll vertically.

inContext: The CG context to erase. If NULL, ScrollMenuImage will create a context based on the current port.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.5 and later

Mac OS X: in version 10.1 and later

SetItemIcon()

void SetItemIcon	(	MenuRef	theMenu,
		short	item,
		short	iconIndex
	)

SetItemIcon()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetItemMark()

void SetItemMark	(	MenuRef	theMenu,
		short	item,
		CharParameter	markChar
	)

SetItemMark()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetItemStyle()

void SetItemStyle	(	MenuRef	theMenu,
		short	item,
		StyleParameter	chStyle
	)

SetItemStyle()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetMCEntries()

void SetMCEntries	(	short	numEntries,
		MCTablePtr	menuCEntries
	)

SetMCEntries()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetMCInfo()

void SetMCInfo

(

MCTableHandle

menuCTbl

)

SetMCInfo()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetMenuBar()

void SetMenuBar

(

MenuBarHandle

mbar

)

Install an entire menu list.

  @par Non-Carbon CFM:   in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetMenuCommandMark()

OSStatus SetMenuCommandMark	(	MenuRef	inMenu,
		MenuCommand	inCommandID,
		UniChar	inMark
	)

SetMenuCommandMark()

Summary: Locates the menu item with a specified command ID and sets its mark character.

Parameters:

inMenu: The menu in which to begin searching for the item. Pass NULL to begin searching with the root menu. The search will descend into all submenus of this menu.

inCommandID: The command ID of the menu item to be modified. If more than one item has this command ID, only the first will be modified.

inMark: The new mark character. This is a Unicode character. On Mac OS 8.x, the low byte of this character will be used as the mark character. On Mac OS X, the entire UniChar will be used and drawn.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

SetMenuCommandProperty()

OSStatus SetMenuCommandProperty	(	MenuRef	inMenu,
		MenuCommand	inCommandID,
		OSType	inPropertyCreator,
		OSType	inPropertyTag,
		ByteCount	inPropertySize,
		const void *	inPropertyData
	)

SetMenuCommandProperty()

Summary: Sets property data for a menu item with a specified command ID.

Parameters:

inMenu: The menu in which to begin searching for the item. Pass NULL to begin searching with the root menu. The search will descend into all submenus of this menu.

inCommandID: The command ID of the menu item that will receive the property. If more than one item has this command ID, only the first will be modified.

inPropertyCreator: The property creator.

inPropertyTag: The property tag.

inPropertySize: The size of the property data, in bytes.

inPropertyData: The address of the property data.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetMenuDefinition()

OSStatus SetMenuDefinition	(	MenuRef	menu,
		const MenuDefSpec *	defSpec
	)

SetMenuDefinition()

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetMenuExcludesMarkColumn()

OSStatus SetMenuExcludesMarkColumn	(	MenuRef	menu,
		Boolean	excludesMark
	)

SetMenuExcludesMarkColumn()

Non-Carbon CFM: in MenusLib 8.5 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetMenuFlash()

void SetMenuFlash

(

short

count

)

Set the number of times a menu item blinks upon selection.

SetMenuFlash can be used to adjust the number of times a menu item blinks
when it is selected.
blinkCount specifies how many times menu items flash when selected. Typical
value is 3. Use 0 to disable blinking.

Returns

none

Note

The blink count is normally set by a Control Panel DA - not by
applications. This call simply sets the low-memory global variable,
MenuFlash . SetMenuFlash is functionally identical to:
MenuFlash =blinkCount ;

Copyright: THINK Reference © 1991-1992 Symantec Corporation

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

SetMenuFlashCount()

void SetMenuFlashCount

(

short

count

)

SetMenuFlashCount()

Non-Carbon CFM: in CarbonAccessors.o 1.3 and later or as macro/inline

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetMenuFont()

OSStatus SetMenuFont	(	MenuRef	menu,
		SInt16	inFontID,
		UInt16	inFontSize
	)

SetMenuFont()

Non-Carbon CFM: in MenusLib 8.5 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetMenuHeight()

void SetMenuHeight	(	MenuRef	menu,
		SInt16	height
	)

SetMenuHeight()

Non-Carbon CFM: in CarbonAccessors.o 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetMenuID()

void SetMenuID	(	MenuRef	menu,
		MenuID	menuID
	)

SetMenuID()

Non-Carbon CFM: in CarbonAccessors.o 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetMenuItemCommandID()

OSErr SetMenuItemCommandID	(	MenuRef	inMenu,
		SInt16	inItem,
		MenuCommand	inCommandID
	)

Dim a menu or a menu item; make non-selectable.

DisableItem dims a menu title or an individual item in a menu. When
disabled, the item (or menu) is not highlighted when the cursor moves over it
and cannot be selected.
theMenu is a handle leading to a variable-length MenuInfo structure. It is a
value obtained via NewMenu or GetMenu . It identifies the menu
containing the item to disable, or if whichItem = 0, the menu to
disable.
whichItem identifies which item to disable or specifies your intention to
disable an entire menu. When whichItem =0, the menu title is
dimmed and all items in that menu are disabled. If it is a valid item
ID, it specifies an item in theMenu. Items are numbered sequentially
with the topmost item having an ID of 1; the last item ID can be
obtained via CountMItems

Returns

none

Note

Use DisableItem on all menu items that are not valid in the current
context; e.g., disable "Paste" when there is nothing in the paste buffer.
Disabling an item also excludes it from the search performed by
MenuKey . Use EnableItem when you want the item to be selectable.
When you disable or re-enable an entire menu ( whichItem =0), you
should call DrawMenuBar to display the changed menu title.
This works by clearing bit number whichItem  in the enableFlags field of
the relevant MenuInfo structure. For instance, the following calls are
functionally equivalent:
DisableItem ( myMenu, 2 );
(*myMenu)-> enableFlags &= ~4; // clear bit 2
All menus and items are implicitly enabled when inserted into the menu
      unless explicitly disabled by including the " (" metacharacter in the item
          text.Items with IDs higher than 31 are always enabled,
      since there is no
              "enable flag" to control them.</ pre>
                    

Copyright: THINK Reference © 1991 -

              1992 Symantec Corporation
                       

Non-Carbon CFM: in InterfaceLib 7.1 and

          later
                       

Carbon Lib: not available * @par Mac OS X: not available *

              /
              void
                  DisableItem(MenuRef theMenu, short item);

  /**

Undim a menu or a menu item; make selectable

  
EnableItem undims a menu title or an individual item in a menu. Use this
after dimming an item or a menu title via DisableItem .
theMenu is a handle leading to a variable-length MenuInfo structure. It is a
value obtained via NewMenu or GetMenu . It identifies the menu
containing the item to enable, or if whichItem = 0, the menu to
enable.
whichItem identifies which item to enable or specifies to enable an entire
menu. When whichItem =0, the menu title is undimmed and all items
in that menu are enabled. If it is a valid item ID, it specifies an item
in theMenu. Items are numbered sequentially with the topmost item
having an ID of 1; the ID of the last item can be obtained via
CountMItems
 

Returns

 
none
 

Note

 
After using DisableItem on a menu item (or including the " ("
metacharacter in its item text), use EnableItem to make the item
selectable and to include it in the search performed by MenuKey .
When you disable or re-enable an entire menu ( whichItem =0), you
should call DrawMenuBar to display the changed menu title.
This works by setting bit number whichItem  in the enableFlags field of the
relevant MenuInfo structure. For instance, the following calls are
functionally equivalent:
EnableItem ( myMenu, 2 );
(*myMenu)->enableFlags |= 4; // set bit 2
All menus and items are enabled when inserted into the menu unless
              explicitly disabled by including the " (" metacharacter in the item text.Items with IDs higher than 31 are always enabled.</ pre>
                    

Copyright: THINK Reference © 1991 -

          1992 Symantec Corporation
                   

Non-Carbon CFM: in InterfaceLib 7.1 and

      later
                   

Carbon Lib: not available * @par Mac OS X: not available *

          /
          void
              EnableItem(MenuRef theMenu, short item);

#endif /* CALL_NOT_IN_CARBON 
SetMenuItemCommandID()


  

Non-Carbon CFM: in AppearanceLib 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetMenuItemCommandKey()

OSStatus SetMenuItemCommandKey	(	MenuRef	inMenu,
		MenuItemIndex	inItem,
		Boolean	inSetVirtualKey,
		UInt16	inKey
	)

SetMenuItemCommandKey()

Summary: Sets the keyboard equivalent of a menu item.

Discussion: A menu item's keyboard equivalent may be either a character code or a virtual keycode. The character code is always used to draw the item's keyboard equivalent in the menu, but either may be used for keyboard equivalent matching by MenuEvent and IsMenuKeyEvent, depending on whether the kMenuItemAttrUseVirtualKey item attribute is set. If SetMenuItemCommandKey is used to set the virtual keycode equivalent for a menu item, it also automatically sets the kMenuItemAttrUseVirtualKey item attribute. To make the menu item stop using the virtual keycode equivalent and use the character code equivalent instead, use ChangeMenuItemAttributes to clear the kMenuItemAttrUseVirtualKey item attribute.

Parameters:

inMenu: The menu containing the item.

inItem: The item whose keyboard equivalent to set.

inSetVirtualKey: Indicates whether to set the item's character code or virtual keycode equivalent.

inKey: The item's new character code or virtual keycode equivalent.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

SetMenuItemData()

OSStatus SetMenuItemData	(	MenuRef	menu,
		MenuItemID	item,
		Boolean	isCommandID,
		const MenuItemDataRec *	data
	)

SetMenuItemData()

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

SetMenuItemFontID()

OSErr SetMenuItemFontID	(	MenuRef	inMenu,
		SInt16	inItem,
		SInt16	inFontID
	)

SetMenuItemFontID()

Non-Carbon CFM: in AppearanceLib 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetMenuItemHierarchicalID()

OSErr SetMenuItemHierarchicalID	(	MenuRef	inMenu,
		SInt16	inItem,
		MenuID	inHierID
	)

SetMenuItemHierarchicalID()

Non-Carbon CFM: in AppearanceLib 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetMenuItemHierarchicalMenu()

OSStatus SetMenuItemHierarchicalMenu	(	MenuRef	inMenu,
		MenuItemIndex	inItem,
		MenuRef	inHierMenu
	)

SetMenuItemHierarchicalMenu()

Summary: Attaches a submenu to a menu item.

Discussion: Using SetMenuItemHierarchicalMenu, it is possible to directly specify the submenu for a menu item without specifying its menu ID. It is not necessary to insert the submenu into the hierarchical portion of the menubar, and it is not necessary for the submenu to have a unique menu ID; it is recommended that you use 0 as the menu ID for the submenu, and identify selections from the menu by command ID. The Menu Manager will increment the refcount of the submenu that you specify, and the submenu's refcount will be decremented automatically when the parent menu item is deleted or the parent menu is disposed.

Parameters:

inMenu: The parent menu.

inItem: The parent item.

inHierMenu: The submenu. You may pass NULL to remove any existing submenu.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

SetMenuItemIconHandle()

OSErr SetMenuItemIconHandle	(	MenuRef	inMenu,
		SInt16	inItem,
		UInt8	inIconType,
		Handle	inIconHandle
	)

SetMenuItemIconHandle()

Non-Carbon CFM: in AppearanceLib 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetMenuItemIndent()

OSStatus SetMenuItemIndent	(	MenuRef	inMenu,
		MenuItemIndex	inItem,
		UInt32	inIndent
	)

SetMenuItemIndent()

Summary: Sets the indent level of a menu item.

Discussion: The indent level of an item is an amount of extra space added to the left of the item's icon or checkmark. The level is simply a number, starting at zero, which the Menu Manager multiplies by a constant to get the indent in pixels. The default indent level is zero.

Parameters:

inMenu: The menu containing the item.

inItem: The item whose indent to set.

inIndent: The new indent level of the item.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

SetMenuItemKeyGlyph()

OSErr SetMenuItemKeyGlyph	(	MenuRef	inMenu,
		SInt16	inItem,
		SInt16	inGlyph
	)

SetMenuItemKeyGlyph()

Non-Carbon CFM: in AppearanceLib 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetMenuItemModifiers()

OSErr SetMenuItemModifiers	(	MenuRef	inMenu,
		SInt16	inItem,
		UInt8	inModifiers
	)

SetMenuItemModifiers()

Non-Carbon CFM: in AppearanceLib 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetMenuItemProperty()

OSStatus SetMenuItemProperty	(	MenuRef	menu,
		MenuItemIndex	item,
		OSType	propertyCreator,
		OSType	propertyTag,
		UInt32	propertySize,
		const void *	propertyData
	)

SetMenuItemProperty()

Non-Carbon CFM: in MenusLib 8.5 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetMenuItemRefCon()

OSErr SetMenuItemRefCon	(	MenuRef	inMenu,
		SInt16	inItem,
		UInt32	inRefCon
	)

SetMenuItemRefCon()

Non-Carbon CFM: in AppearanceLib 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetMenuItemRefCon2()

OSErr SetMenuItemRefCon2	(	MenuRef	inMenu,
		SInt16	inItem,
		UInt32	inRefCon2
	)

SetMenuItemRefCon2()

Non-Carbon CFM: in AppearanceLib 1.0 and later

Carbon Lib: not available

Mac OS X: not available

setmenuitemtext() [1/2]

* setmenuitemtext	(	menu	,
		item	,
		itemString
	)

GetMenuID()

Non-Carbon CFM: in CarbonAccessors.o 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

setmenuitemtext() [2/2]

void setmenuitemtext	(	MenuRef	menu,
		short	item,
		const char *	itemString
	)

setmenuitemtext()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

SetMenuItemText()

void SetMenuItemText	(	MenuRef	theMenu,
		short	item,
		ConstStr255Param	itemString
	)

SetMenuItemText()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetMenuItemTextEncoding()

OSErr SetMenuItemTextEncoding	(	MenuRef	inMenu,
		SInt16	inItem,
		TextEncoding	inScriptID
	)

SetMenuItemTextEncoding()

Non-Carbon CFM: in AppearanceLib 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetMenuItemTextWithCFString()

OSStatus SetMenuItemTextWithCFString	(	MenuRef	inMenu,
		MenuItemIndex	inItem,
		CFStringRef	inString
	)

SetMenuItemTextWithCFString()

Summary: Sets the text of a menu item to the text contained in a CFString.

Discussion: The Menu Manager will either make its own copy or just increment the refcount of the CFString before returning from SetMenuItemTextWithCFString, depending on whether the string is mutable or immutable. If the string is mutable, modifying the string after calling SetMenuItemTextWithCFString will have no effect on the menu item's actual text. The caller may release the string after calling SetMenuItemTextWithCFString.

Parameters:

inMenu: The menu containing the item.

inItem: The item whose text to return.

inString: The string containing the new menu item text.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

SetMenuTitle()

OSStatus SetMenuTitle	(	MenuRef	menu,
		ConstStr255Param	title
	)

SetMenuTitle()

Non-Carbon CFM: in CarbonAccessors.o 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetMenuTitleIcon()

OSStatus SetMenuTitleIcon	(	MenuRef	inMenu,
		UInt32	inType,
		void *	inIcon
	)

SetMenuTitleIcon()

Summary: Sets the title of a menu to be an icon.

Discussion: The Menu Manager takes ownership of the supplied icon after this call. When a menu with an title icon is disposed, the Menu Manager will dispose the icon also; the Menu Manager will also dispose of the current title icon when a new text or icon title is supplied for a menu. If an IconRef is specified, the Menu Manager will increment its refcount, so you may freely release your reference to the IconRef without invalidating the Menu Manager's copy. The menubar will be invalidated by this call, and redrawn at the next opportunity.

Parameters:

inMenu: The menu whose title to set.

inType: The type of icon being used to specify the icon title; use kMenuNoIcon to remove the icon from the menu title. The supported types are kMenuIconSuiteType and kMenuIconRefType.

inIcon: The icon; must be NULL if inType is kMenuNoIcon. The supported icon formats are IconSuiteRef and IconRef.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

SetMenuTitleWithCFString()

OSStatus SetMenuTitleWithCFString	(	MenuRef	inMenu,
		CFStringRef	inString
	)

SetMenuTitleWithCFString()

Summary: Sets the title of a menu to the text contained in a CFString.

Discussion: The Menu Manager will either make its own copy or just increment the refcount of the CFString before returning from SetMenuTitleWithCFString, depending on whether the string is mutable or immutable. If the string is mutable, modifying the string after calling SetMenuTitleWithCFString will have no effect on the menu's actual title. The caller may release the string after calling SetMenuTitleWithCFString.

Parameters:

inMenu: The menu whose title to set.

inString: The string containing the new menu title text.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

SetMenuWidth()

void SetMenuWidth	(	MenuRef	menu,
		SInt16	width
	)

SetMenuWidth()

Non-Carbon CFM: in CarbonAccessors.o 1.0 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SetRootMenu()

OSStatus SetRootMenu

(

MenuRef

inMenu

)

SetRootMenu()

Summary: Sets the menu whose contents are displayed in the menubar.

Discussion: The refcount of the root menu is incremented by this API. The caller may release the menu after calling SetRootMenu.

Parameters:

inMenu: The new root menu.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

ShowMenuBar()

void ShowMenuBar

(

void

)

ShowMenuBar()

Non-Carbon CFM: in MenusLib 8.5 and later

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

SystemEdit()

Boolean SystemEdit

(

short

editCmd

)

SystemEdit()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

SystemMenu()

void SystemMenu

(

long

menuResult

)

SystemMenu()

Non-Carbon CFM: in InterfaceLib 7.1 and later

Carbon Lib: not available

Mac OS X: not available

UpdateInvalidMenuItems()

OSStatus UpdateInvalidMenuItems

(

MenuRef

menu

)

UpdateInvalidMenuItems()

Summary: Redraws the invalid items of an open menu.

Discussion: It is not necessary to use UpdateInvalidMenuItems if you are using Carbon's built-in support for dynamic items based on modifier key state. However, if you are modifying items dynamically using your own implementation, you should call UpdateInvalidMenuItems after completing your modifications for a single menu. It will redraw any items that have been marked as invalid, and clear the invalid flag for those items.

Parameters:

menu: The menu to update.

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.1 and later

Mac OS X: in version 10.0 and later

UpdateStandardFontMenu()

OSStatus UpdateStandardFontMenu	(	MenuRef	menu,
		ItemCount *	outHierMenuCount
	)

UpdateStandardFontMenu()

Non-Carbon CFM: not available

Carbon Lib: in CarbonLib 1.0 and later

Mac OS X: in version 10.0 and later

Variable Documentation

green

myMCE mctRGB2 green = 0

Get the address of a particular menu color table entry.

GetMCEntry returns the address of the color information for the specified
menu and item.
menuID is the ID of a menu (as used in NewMenu or GetMenu ). A value of
0 specifies the menubar.
itemIDidentifies the menu item of interest. A value of 0 specifies the title
of menu menuID.

Returns

none

Note

The pointer returned by this call is an address within a relocatable
block. Thus, if you want to retain it across calls that may move or purge
memory (see TrapWords ), you should make a copy:
MCEntry myMCE;
MCEntryPtr ptrMCE;
ptrMCE = GetMCEntry ( mnuFile, itmSave );
myMCE = ptrMCE; // make a duplicate
myMCE.mctRGB2.red = 0xFFFF; / change something in the copy

windowsSubMenu

windowsSubMenu = NewMenu(SMID_CLWIND, "\pClose Window")

Assign a command-key to a menu item; make submenu.

SetItemCmd assigns a command-key equivalent to a menu item (so that
subsequent calls to MenuKey can return whichItem ). It also provides a way
to convert a normal menu item into a hierarchical submenu title.
theMenu is a handle leading to a variable-length MenuInfo structure. It is a
value obtained via NewMenu or GetMenu and it identifies the menu
containing the item to modify.
whichItem identifies which item in theMenu to modify. Items are numbered
sequentially with the topmost item having an ID of 1.
cmdChar is a character to be used as the command-key equivalent for menu
item whichItem (i.e., a value of 'B' or 'b' will cause a call to
MenuKey to return whichItem  after the user presses ␑B or ␑b).
If cmdChar is hMenuCmd (0x1B), whichItem becomes submenu title
and you should call SetItemMark to identify which submenu should
be attached to whichItem .

Returns

none

Note

SetItemCmd is new with the 256K ROMs. It provides a way to change
which command key is associated with a menu item or to convert a simple
menu item into a hierarchical submenu title.
Mac User Guidelines recommend that you never change command-key
equivalents unless a user has specifically requested you to do so.
Furthermore, the normal way to set up a command key for an item is to use
the '/' metacharacter in the initial call to InsMenuItem or AppendMenu
(or when creating the menu via a resource tool).
This call would be more often used to toggle an item to and from a submenu.
For instance, a menu item named Close MyFile , seen when only one
window is open, might be changed to Close Window (a submenu title)
when two or more windows are open.
MenuHandle  windowsSubMenu, otherMenu;
/* after user has opened a second window