NSMenu

NSMenu Mac OS X 10.0

This class provides an interface to an application's menus. Generally, you won't have to work directly with menus since Interface Builder provides facilities for creating an application's entire menu structure, including the main menu bar, the Dock menu, contextual menus for views, and menus for pop-up buttons. However, if your application requires some degree of dynamicism in its menus, then you will need to use NSMenu's API.

Menus are initialized with initWithTitle:. The string passed in this method appears as the title of the menu. A menu manages a collection of menu items, which are instances of the class NSMenuItem. To manage a menu's items, we have several methods at our disposal. To add an item to the end of the menu, use addItem:; to insert an item at some position in the menu, use insertItem:atIndex:. Menu items are removed from a menu using the methods removeItem: and removeItemAtIndex:.

Menus can also be queried for their menu items. The method itemArray returns an NSArray containing the menu's items. Items can also be retrieved by their index, title, and tag using itemAtIndex:, itemWithTitle:, and itemWithTag:, respectively.

To add a submenu to a menu, first add a menu item to represent that submenu, and then associate another instance of NSMenu with that menu item using the method setSubmenu:forItem:.

figs/cocn_1548.gif

@interface NSMenu : NSObject <NSCoding, NSCopying>
 // Convenience Constructors
   + (BOOL)menuBarVisible;
   + (NSZone *)menuZone;
 // Initializers
   - (id)initWithTitle:(NSString *)aTitle;
 // Accessor Methods
   - (void)setTearOffMenuRepresentation:(id)menuRep;
   - (id)tearOffMenuRepresentation;
   - (void)setTitle:(NSString *)aString;
   - (NSString *)title;
   - (void)setSupermenu:(NSMenu *)supermenu;
   - (NSMenu *)supermenu;
   - (void)setAutoenablesItems:(BOOL)flag;
   - (BOOL)autoenablesItems;
   - (void)setSubmenu:(NSMenu *)aMenu forItem:(id <NSMenuItem>)anItem;
   - (void)setMenuRepresentation:(id)menuRep;
   - (id)menuRepresentation;
   - (void)setContextMenuRepresentation:(id)menuRep;
   - (id)contextMenuRepresentation;
   - (void)setMenuChangedMessagesEnabled:(BOOL)flag;
   - (BOOL)menuChangedMessagesEnabled;
 // Class Methods
   + (void)popUpContextMenu:(NSMenu*)menu withEvent:(NSEvent*)event forView:(NSView*)view;
   + (void)setMenuBarVisible:(BOOL)visible;
   + (void)setMenuZone:(NSZone *)aZone;
 // Instance Methods
   - (NSMenu *)attachedMenu;
   - (void)addItem:(id <NSMenuItem>)newItem;
   - (id <NSMenuItem>)addItemWithTitle:(NSString *)aString action:(SEL)aSelector 
        keyEquivalent:(NSString *)charCode;
   - (void)helpRequested:(NSEvent *)eventPtr;
   - (int)indexOfItem:(id <NSMenuItem>)index;
   - (int)indexOfItemWithRepresentedObject:(id)object;
   - (int)indexOfItemWithSubmenu:(NSMenu *)submenu;
   - (int)indexOfItemWithTag:(int)aTag;
   - (int)indexOfItemWithTarget:(id)target andAction:(SEL)actionSelector;
   - (int)indexOfItemWithTitle:(NSString *)aTitle;
   - (void)insertItem:(id <NSMenuItem>)newItem atIndex:(int)index;
   - (id <NSMenuItem>)insertItemWithTitle:(NSString *)aString action:(SEL)aSelector 
        keyEquivalent:(NSString *)charCode atIndex:(int)index;
   - (BOOL)isAttached;
   - (BOOL)isTornOff;
   - (NSArray *)itemArray;
   - (id <NSMenuItem>)itemAtIndex:(int)index;
   - (void)itemChanged:(id <NSMenuItem>)item;
   - (id <NSMenuItem>)itemWithTag:(int)tag;
   - (id <NSMenuItem>)itemWithTitle:(NSString *)aTitle;
   - (NSPoint)locationForSubmenu:(NSMenu *)aSubmenu;
   - (int)numberOfItems;
   - (void)performActionForItemAtIndex:(int)index;
   - (BOOL)performKeyEquivalent:(NSEvent *)theEvent;
   - (void)removeItem:(id <NSMenuItem>)item;
   - (void)removeItemAtIndex:(int)index;
   - (void)sizeToFit;
   - (void)submenuAction:(id)sender;
   - (void)update;
 // Methods Implementing NSCoding
   - (void)encodeWithCoder:(NSCoder *)aCoder;
   - (id)initWithCoder:(NSCoder *)aDecoder;
 // Methods Implementing NSCopying
   - (id)copyWithZone:(NSZone *)zone;
// Notifications
   NSMenuDidAddItemNotification;
   NSMenuDidChangeItemNotification;
   NSMenuDidRemoveItemNotification;
   NSMenuDidSendActionNotification;
   NSMenuWillSendActionNotification;



    Part II: API Quick Reference
    Chapter 13. Foundation Classes