Developer Documentation
PATH  Mac OS X Documentation > Application Kit Reference: Objective-C

Table of Contents

NSPopUpButtonCell


Inherits from:
NSMenuItemCell : NSButtonCell : NSActionCell : NSCell : NSObject
Conforms to:
NSCoding
(NSCell)
NSCopying (NSCell)
NSObject (NSObject)
Declared in:
AppKit/NSPopUpButtonCell.h




Class Description


NSPopupButtonCell defines the visual appearance of popup buttons that display popup or pulldown lists. Popup lists present the user with a set of choices much in the way that radio buttons do but they do so using much less space. Pulldown lists also provide a set of choices but present the information in a slightly different way, usually to provide a set of commands from which the user can choose.

Typically you do not create instances of NSPopUpButtonCell directly. Instead, you create an instance of NSPopUpButton which creates the appropriate cell. If you load your popup button from a nib file, the cell is similarly created for you when the popup button is initialized. You should not need to manipulate the interface of NSPopUpButtonCell directly. The methods of NSPopUpButton simply invoke methods of NSPopUpButtonCell to set or get the appropriate information.

To add items to a popup button cell's list, you can use the methods addItemWithTitle:, addItemsWithTitles:, and insertItemWithTitle:atIndex:. These methods create or replace a menu item with the given title and assign it a default action and key equivalent. Once the item is added to the list, you must use the NSMenuItem interface to modify the attributes of the item. To remove one or more items, use the removeItemWithTitle:, removeItemAtIndex:, or removeAllItems method.


Popup and Pulldown List Displays


When the popup list is displayed, the popup-button cell displays the list on top of the popup button. The currently selected choice appears in the same location as the popup button with the other items arranged above or below the current selection according to the order of the cell's menu. When the popup list is dismissed, the title of the popup button changes to match the title of the currently selected item.

Pulldown lists typically display themselves adjacent to the popup button in the same way a submenu is displayed next to its parent item. Unlike popup lists, the title of a popup button displaying a pulldown list is not based on the currently selected item and thus remains fixed unless you change using the cell's setTitle: method.

While popup lists are displayed on top of their button, the location of the pulldown list depends on the preferred edge, set through the cell's setPreferredEdge: method. When drawing the list, the cell does its best to honor the preferred edge if there is enough space on the user's screen. If there is not enough space, the cell positions the list somewhere else.

NSPopupButtonCell uses an NSMenuView to draw the popup menu.


Pulldown List Indexes


Indexes for items in a pulldown list are a little different than indexes in popup lists or in the application's regular menus. Most lists and menus contain a set of n items (where n is some integer) with indexes running from 0 to n - 1. By default, both pulldown and popup lists obtain their title from a list item and therefore use this range of indexes. However, you can send a setUsesItemFromMenu: message to the popup button, passing the value NO, to disable this option. However, doing so causes the first item in a pulldown list to have the index 1. The reason for this is that the pulldown list uses the original first item (at index 0) to store the title of the popup button.

When using pulldown lists, you should never try to change the title of the popup button by accessing the menu item at index 0 directly. Instead, you should always use the cell's setTitle: method to change the button's title.




Method Types


Initialization
- initTextCell:pullsDown:
Getting and setting attributes
- setMenu:
- menu
- setPullsDown:
- pullsDown
- setAutoenablesItems:
- autoenablesItems
- setPreferredEdge:
- preferredEdge
- setUsesItemFromMenu:
- usesItemFromMenu
- setAltersStateOfSelectedItem:
- altersStateOfSelectedItem
Adding and removing items
- addItemWithTitle:
- addItemsWithTitles:
- insertItemWithTitle:atIndex:
- removeItemWithTitle:
- removeItemAtIndex:
- removeAllItems
Accessing the items
- itemArray
- numberOfItems
- indexOfItem:
- indexOfItemWithTitle:
- indexOfItemWithTag:
- indexOfItemWithRepresentedObject:
- indexOfItemWithTarget:andAction:
- itemAtIndex:
- itemWithTitle:
- lastItem
Dealing with selection
- selectItem:
- selectItemAtIndex:
- selectItemWithTitle:
- setTitle:
- selectedItem
- indexOfSelectedItem
- synchronizeTitleAndSelectedItem
Title conveniences
- itemTitleAtIndex:
- itemTitles
- titleOfSelectedItem
Handling events and action messages
- attachPopUpWithFrame:inView:
- dismissPopUp


Instance Methods



addItemWithTitle:

- (void)addItemWithTitle:(NSString *)title

Creates a new menu item with the specified title and adds it to the end of the menu. The menu item uses the popup button's default action and target, but you can change these using the setAction: and setTarget: methods of the corresponding NSMenuItem object.

See Also: - addItemsWithTitles:, - setAction: (NSMenuItem), - setTarget: (NSMenuItem)



addItemsWithTitles:

- (void)addItemsWithTitles:(NSArray *)itemTitles

For each string in itemTitles, this method creates a new menu item and adds it to the end of the menu. The menu items use the popup button's default action and target, but you can change these using the setAction: and setTarget: methods of the corresponding NSMenuItem object.

See Also: - addItemWithTitle:, - setAction: (NSMenuItem), - setTarget: (NSMenuItem)



altersStateOfSelectedItem

- (BOOL)altersStateOfSelectedItem

Returns YES if the popup button cell sets the state of the selected menu item to NSStateOn. This option is usually only used by popup menus. You typically do not alter the state of menu items in a pulldown menu.

See Also: - selectItemAtIndex:, - selectItemWithTitle:



arrowPosition

- (NSPopUpArrowPosition)arrowPosition

Description forthcoming.

attachPopUpWithFrame:inView:

- (void)attachPopUpWithFrame:(NSRect)cellFrame inView:(NSView *)controlView

Displays the popup button's menu, making adjustments as necessary to display the menu along the preferred edge of the cell if possible. The cellFrame parameter specifies the rectangle of the cell in the specified controlView to which the menu is to be attached. Before displaying the menu, this method sends the notification NSPopUpButtonCellWillPopUpNotification to both the controlView and to this cell. (The NSPopupButton object sends a corresponding NSPopUpButtonWillPopUpNotification notification.)

See Also: - dismissPopUp, NSPopUpButtonCellWillPopUpNotification (notification)



autoenablesItems

- (BOOL)autoenablesItems

Returns whether the popup button's menu automatically enables and disables its menu items. By default NSMenu objects do autoenable their menu items.

See Also: - setAutoenablesItems:



dismissPopUp

- (void)dismissPopUp

Dismisses the popup button's menu by ordering its window out. If the popup button was not displaying its menu, this method does nothing.

See Also: - attachPopUpWithFrame:inView:, - orderOut: (NSWindow)



indexOfItem:

- (int)indexOfItem:(id <NSMenuItem>)item

Returns the index of item. If item is nil or cannot be found, this method returns -1.

See Also: - indexOfItemWithRepresentedObject:, - indexOfItemWithTag:, - indexOfItemWithTarget:andAction:, - indexOfItemWithTitle:, - indexOfSelectedItem



indexOfItemWithRepresentedObject:

- (int)indexOfItemWithRepresentedObject:(id)obj

Returns the index of the first menu item with the represented object specified by obj. If obj is nil or if a menu item with the given represented object cannot be found, this method returns -1.

See Also: - indexOfItem:, - indexOfItemWithTag:, - indexOfItemWithTarget:andAction:, - indexOfItemWithTitle:, - indexOfSelectedItem, - representedObject (NSMenuItem), - setRepresentedObject: (NSMenuItem)



indexOfItemWithTag:

- (int)indexOfItemWithTag:(int)tag

Returns the index of the first menu item with the specified tag. If a menu item with tag cannot be found, this method returns -1.

Tags are values your application assigns to an object to identify it. You can assign tags to menu items using the setTag: method of NSMenuItem.

See Also: - indexOfItem:, - indexOfItemWithRepresentedObject:, - indexOfItemWithTarget:andAction:, - indexOfItemWithTitle:, - indexOfSelectedItem, - setTag: (NSMenuItem)



indexOfItemWithTarget:andAction:

- (int)indexOfItemWithTarget:(id)target andAction:(SEL)actionSelector

Returns the index of the first menu item that invokes the specified actionSelector on the given target. If a menu item with the given actionSelector and target cannot be found, this method returns -1.

NSPopupButtonCell assigns a default action and target to each menu item but you can change these values using the setAction: and setTarget: methods of NSMenuItem.

See Also: - indexOfItem:, - indexOfItemWithRepresentedObject:, - indexOfItemWithTag:, - indexOfItemWithTarget:andAction:, - indexOfItemWithTitle:, - indexOfSelectedItem, - setAction: (NSMenuItem), - setTarget: (NSMenuItem)



indexOfItemWithTitle:

- (int)indexOfItemWithTitle:(NSString *)title

Returns the index of the first menu item with the specified title. title must not be nil. If title contains a string that does not match the title of any menu item, this method returns -1.

See Also: - indexOfItem:, - indexOfItemWithRepresentedObject:, - indexOfItemWithTag:, - indexOfItemWithTarget:andAction:, - indexOfItemWithTitle:, - indexOfSelectedItem



indexOfSelectedItem

- (int)indexOfSelectedItem

Returns the index of the currently selected menu item. If no menu item is selected, this method returns -1.

See Also: - indexOfItem:, - indexOfItemWithRepresentedObject:, - indexOfItemWithTag:, - indexOfItemWithTarget:andAction:, - indexOfItemWithTitle:



initTextCell:pullsDown:

- (id)initTextCell:(NSString *)stringValue pullsDown:(BOOL)pullDown

Initializes the new button with the title stringValue. If pullDown contains the value YES, the menu style is a pulldown menu, otherwise the menu is a pop-up menu. If stringValue contains a non-empty string, stringValue is used to create the first menu item in the menu. This menu item is assigned the default popup-button action that displays the menu. To set the action and target, use the setAction: and setTarget: methods of the item's corresponding NSMenuItem object.

This method is the designated initializer of the class.

See Also: - setAction: (NSMenuItem), - setTarget: (NSMenuItem)



insertItemWithTitle:atIndex:

- (void)insertItemWithTitle:(NSString *)title atIndex:(int)index

Creates a new menu item with the specified title and inserts it into the array of menu items at index. The value in index must represent a valid position in the array. The menu item at index and all those that follow it are shifted down one slot to make room for the new menu item.

This method assigns the popup button's default action and target to the new menu item. Use the menu item's setAction: and setTarget: methods to assign a new action and target.

See Also: - insertObject:atIndex: (NSMutableArray), - setAction: (NSMenuItem), - setTarget: (NSMenuItem)



itemArray

- (NSArray *)itemArray

Returns the array of menu items associated with the menu.

See Also: - itemArray (NSMenu)



itemAtIndex:

- (id <NSMenuItem>)itemAtIndex:(int)index

Returns the menu item at index. The value in index must refer to an existing menu item.

See Also: - itemTitleAtIndex:, - itemAtIndex: (NSMenu)



itemTitleAtIndex:

- (NSString *)itemTitleAtIndex:(int)index

Returns the title of the menu item located at index.

See Also: - itemAtIndex:



itemTitles

- (NSArray *)itemTitles

Returns a mutable array of strings containing the titles of this popup button's menu items. If the menu contains separator items, the array contains an empty string (@"") for each separator item.

See Also: - itemTitleAtIndex:



itemWithTitle:

- (id <NSMenuItem>)itemWithTitle:(NSString *)title

Returns the first menu item whose title matches title, or nil if no such item exists.

See Also: - itemTitleAtIndex:, - itemAtIndex:



lastItem

- (id <NSMenuItem>)lastItem

Returns the last menu item in the popup button's menu.

menu

- (NSMenu *)menu

Returns the menu object associated with the popup button.

See Also: - setMenu:



numberOfItems

- (int)numberOfItems

Returns the number of menu items in the popup button's menu.

See Also: - count (NSArray)



performClickWithFramei:InView:

- (void)performClickWithFrame:(NSRect)frame inView:(NSView *)controlView

Description forthcoming.

preferredEdge

- (NSRectEdge)preferredEdge

Returns the preferred edge on which to attach the menu. If no edge was set using the setPreferredEdge: method, this method sets the preferred edge to the bottom edge of the popup button and returns that value.

See Also: - setPreferredEdge:



pullsDown

- (BOOL)pullsDown

Returns YES if the menu is a pulldown-style menu, otherwise returns NO.

See Also: - setPullsDown:



removeAllItems

- (void)removeAllItems

Removes all of the popup button's menu items.

See Also: - removeItemAtIndex:, - removeItemWithTitle:, - insertItemWithTitle:atIndex:



removeItemAtIndex:

- (void)removeItemAtIndex:(int)index

Removes the menu item at index from the popup button's menu. index must be a valid index into the array of menu items and therefore must not be negative.

See Also: - removeAllItems, - removeItemWithTitle:, - insertItemWithTitle:atIndex:



removeItemWithTitle:

- (void)removeItemWithTitle:(NSString *)title

Removes the first menu item with the specified title from the popup button's menu. An assertion is triggered if the string in title does not correspond to an existing menu item.

See Also: - removeAllItems, - removeItemAtIndex:, - insertItemWithTitle:atIndex:



selectItem:

- (void)selectItem:(id <NSMenuItem>)item

Makes item the currently selected menu item. If item is nil, this method deselects the currently selected menu item.

By default, selecting or deselecting a menu item from a popup menu changes its state. Selecting a menu item from a pulldown menu does not automatically alter the state of the item. Use the setAltersStateOfSelectedItem: method, passing it a value of NO, to disassociate the current selection from the state of menu items.

See Also: - selectedItem, - selectItemAtIndex:, - selectItemWithTitle:, - setAltersStateOfSelectedItem:, - setState: (NSMenuItem)



selectItemAtIndex:

- (void)selectItemAtIndex:(int)index

Makes the item at index the current selection. If index is -1, this method deselects the currently selected menu item.

By default, selecting or deselecting a menu item from a popup menu changes its state. Selecting a menu item from a pulldown menu does not automatically alter the state of the item. Use the setAltersStateOfSelectedItem: method, passing it a value of NO, to disassociate the current selection from the state of menu items.

See Also: - selectedItem, - selectItem:, - selectItemWithTitle:, - setAltersStateOfSelectedItem:, - setState: (NSMenuItem)



selectItemWithTitle:

- (void)selectItemWithTitle:(NSString *)title

Makes the first menu item with the given title the currently selected item. If title is nil or contains a string that does not match the title of any menu item, this method deselects the currently selected menu item.

By default, selecting or deselecting a menu item changes its state. Use the setAltersStateOfSelectedItem: method, passing it a value of NO, to disassociate the current selection from the state of menu items.

See Also: - selectedItem, - selectItem:, - selectItemAtIndex:, - setAltersStateOfSelectedItem:, - setState: (NSMenuItem)



selectedItem

- (id <NSMenuItem>)selectedItem

Returns the currently selected menu item or nil of no menu item is selected.

See Also: - selectItem:, - selectItemAtIndex:, - selectItemWithTitle:



setAltersStateOfSelectedItem:

- (void)setAltersStateOfSelectedItem:(BOOL)flag

If flag is NO, this method disassociates the current selection from the state of menu items. Before disassociating the selection from the menu item state, this method first sets the state of the currently selected menu item to NSStateOff. If flag is YES, this method sets the state of the currently selected menu item to NSStateOn.

See Also: - altersStateOfSelectedItem, - selectedItem, - selectItem:, - selectItemAtIndex:, - setState: (NSMenuItem)



setArrowPosition:

- (void)setArrowPosition:(NSPopUpArrowPosition)position

Description forthcoming.

setAutoenablesItems:

- (void)setAutoenablesItems:(BOOL)flag

Controls whether the popup button's menu automatically enables and disables its menu items. If flag is YES, menu items are automatically enabled and disabled. If flag is NO, menu items are not automatically enabled or disabled.

See Also: - autoenablesItems



setMenu:

- (void)setMenu:(NSMenu *)menu

Sets the menu object to be used by this popup button. If another menu was already associated with the popup button, this method releases the old menu. If you want to explicitly save the old menu, you should retain it before invoking this method.

See Also: - menu



setPreferredEdge:

- (void)setPreferredEdge:(NSRectEdge)edge

Sets the edge of the popup button to which menus are attached. At display time, if attaching the menu to the preferred edge would cause part of the menu to be obscured, the popup button may use a different edge. If no preferred edge is set, the popup button uses the bottom edge by default.

See Also: - preferredEdge



setPullsDown:

- (void)setPullsDown:(BOOL)flag

Sets whether the popup button uses a popup or a pulldown menu. If flag is YES, the popup button displays a pulldown menu, otherwise the popup button displays a popup menu. This method does not change the contents of the menu, it only changes the style of the menu.

When changing the menu type to a pulldown menu, if the menu was a pop-up menu and the cell alters the state of its selected items, this method sets the state of the currently selected item to NSStateOff before changing the menu type.

See Also: - pullsDown, - synchronizeTitleAndSelectedItem



setTitle:

- (void)setTitle:(NSString *)aString

For pulldown menus that get their titles from a menu item, this method simply sets the popup button cell's menu item to the first item in the menu. For popup menus, if a menu item whose title matches aString exists, this method makes that menu item the current selection; otherwise, it creates a new menu item with the title aString, adds it to the popup menu, and selects it.

See Also: - initTextCell:pullsDown:



setUsesItemFromMenu:

- (void)setUsesItemFromMenu:(BOOL)flag

Controls whether the popup button uses an item from the menu for its own purposes. For pulldown menus, the popup button uses the first menu item as its own title if flag is YES. For popup menus, the popup button uses the title of the currently selected menu item; if no menu item is selected, the popup button displays no item and is drawn empty.

See Also: - usesItemFromMenu



synchronizeTitleAndSelectedItem

- (void)synchronizeTitleAndSelectedItem

For popup menus, this method sets the popup-button's menu item to the currently selected menu item or to the first menu item if none is selected. For pulldown menus, this method sets the item to the first menu item. If the popup button cell does not get its title from a menu item, this method does nothing.

If the popup button's menu does not contain any menu items, this method sets the popup button's item to nil.



titleOfSelectedItem

- (NSString *)titleOfSelectedItem

Returns a string containing the title of the currently selected menu item or an empty string of no item is selected.

See Also: - selectItemWithTitle:



usesItemFromMenu

- (BOOL)usesItemFromMenu

Returns YES if the popup button uses the title text of a menu item for its own title. If this option is set, pulldown menus use the title of the first menu item in the menu while popup menus use the title of the currently selected menu.

See Also: - setUsesItemFromMenu:




Notifications


NSPopUpButtonCellWillPopUpNotification

This notification contains a notification object but no userInfo dictionary. The notification object can be either a popup button or its enclosed popup-button cell.The notification is posted just before the popup menu is attached to its window frame. You can use this notification to lazily construct your part's menus, thus preventing unnecessary calculations until they are needed.

Table of Contents