Inherits From:
NSMenuItemCell : NSButtonCell : NSActionCell : NSCell : NSObject
Conforms To:
NSCoding (from NSCell)
NSCopying (from NSCell)
NSObject (from NSObject)
Declared In:
AppKit/NSPopupButtonCell.h
NSPopupButtonCell defines the visual appearance of popup buttons that display popup or pulldown menus. Popup menus 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 menus also provide a list of choices in a menu, but present the information in a slightly different way, usually to provide a list of commands from which the user can choose. The most noticeable difference between popup menus and pulldown menus is the way by which they attach their menus.
When the popup menu is displayed, the popup button cell displays the menu the on top of the popup button. The currently selected choice appears in the same location as the popup button with the other menu items located above or below the current selection as appropriate. When the popup menu is dismissed, the popup button uses the title of the selected menu item.
Pulldown menus typically display themselves next to the popup button, as opposed to on top of it. The location of the pulldown menu depends on the preferred edge, set by your application using the setPreferredEdge:
method, and the amount of available space on the user's screen. When the pulldown menu is dismissed, the title of the popup button does not change.
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:
(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
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
:
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
Returns whether the popup button's menu automatically enables and disables its menu items based on the NSMenuValidation informal protocol. By default NSMenu objects do autoenable their menu items. See the NSMenuValidation protocol specification for more information.
See also:
- setAutoenablesItems:
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:
(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:
(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)tag
Returns the index of the first menu item with the specified tag. If a menu item with the given tag cannot be found, this method returns -1.
Tags are values that 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:
(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:
(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
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:
(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 also 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:
(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
Returns the array of menu items associated with the menu.
See also:
- itemArray
(NSMenu)
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:
(int)index
Returns the title of the menu item located at index.
See also:
- itemAtIndex:
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:
(NSString *)title
Returns the first menu item whose title matches title, or nil
if no such item exists.
See also:
- itemTitleAtIndex:
, - itemAtIndex:
lastItem
Returns the last menu item in the popup button's menu.
menu
Returns the menu object associated with the popup button.
See also:
- setMenu:
numberOfItems
Returns the number of menu items in the popup button's menu.
See also:
- count
(NSArray)
performClick:
(id)sender
Simulates a simple click on the popup button by displaying the menu and tracking subsequent events.
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
Returns YES if the menu is a pulldown-style menu, otherwise returns NO.
See also:
- setPullsDown:
removeAllItems
Removes all of the popup button's menu items.
See also:
- removeItemAtIndex:
, - removeItemWithTitle
:, - insertItemWithTitle:atIndex
:
removeItemAtIndex:
(int)index
Removes the menu item at the specified index from the popup button's menu. The value in 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:
(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
:
selectedItem
Returns the currently selected menu item or nil
of no menu item is selected.
See also:
- selectItem:
, - selectItemAtIndex:
, - selectItemWithTitle:
selectItem:
(id <NSMenuItem>)item
Makes item the currently selected menu item. If item is nil
, this method simply 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:
(int)index
Makes the item at index the current selection. If index contains the value -1, this method simply 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:
(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 simply deselects the curently 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)
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)
setAutoenablesItems:
(BOOL)flag
Controls whether the popup button's menu automatically enables and disables its menu items based on delegates implementing the NSMenuValidation informal protocol. If flag is YES, menu items are automatically enabled and disabled. If flag is NO, menu items are not automatically enabled or disabled. See the NSMenuValidation protocol specification for more information.
See also:
- autoenablesItems
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:
(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:
(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:
(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:
(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
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
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
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:
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.