- Inherits from:
- NSMenuItemCell : NSButtonCell : NSActionCell : NSCell : NSObject
- Conforms to:
- NSCoding
- (NSCell)
- NSCopying (NSCell)
- NSObject (NSObject)
Declared in:
- AppKit/NSPopUpButtonCell.h
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.
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.
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.
- 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
- (void)addItemWithTitle:(NSString
*)title
See Also: - addItemsWithTitles:, - setAction: (NSMenuItem), - setTarget: (NSMenuItem)
- (void)addItemsWithTitles:(NSArray
*)itemTitles
See Also: - addItemWithTitle:, - setAction: (NSMenuItem), - setTarget: (NSMenuItem)
- (BOOL)altersStateOfSelectedItem
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:
- (NSPopUpArrowPosition)arrowPosition
- (void)attachPopUpWithFrame:(NSRect)cellFrame
inView:(NSView *)controlView
See Also: - dismissPopUp, NSPopUpButtonCellWillPopUpNotification (notification)
- (BOOL)autoenablesItems
See Also: - setAutoenablesItems:
- (void)dismissPopUp
See Also: - attachPopUpWithFrame:inView:, - orderOut: (NSWindow)
- (int)indexOfItem:(id
<NSMenuItem>)item
nil
or
cannot be found, this method returns -1.See Also: - indexOfItemWithRepresentedObject:, - indexOfItemWithTag:, - indexOfItemWithTarget:andAction:, - indexOfItemWithTitle:, - indexOfSelectedItem
- (int)indexOfItemWithRepresentedObject:(id)obj
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)
- (int)indexOfItemWithTag:(int)tag
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)
- (int)indexOfItemWithTarget:(id)target
andAction:(SEL)actionSelector
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)
- (int)indexOfItemWithTitle:(NSString
*)title
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
- (int)indexOfSelectedItem
See Also: - indexOfItem:, - indexOfItemWithRepresentedObject:, - indexOfItemWithTag:, - indexOfItemWithTarget:andAction:, - indexOfItemWithTitle:
- (id)initTextCell:(NSString
*)stringValue
pullsDown:(BOOL)pullDown
This method is the designated initializer of the class.
See Also: - setAction: (NSMenuItem), - setTarget: (NSMenuItem)
- (void)insertItemWithTitle:(NSString
*)title
atIndex:(int)index
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)
- (NSArray *)itemArray
See Also: - itemArray (NSMenu)
- (id <NSMenuItem>)itemAtIndex:(int)index
See Also: - itemTitleAtIndex:, - itemAtIndex: (NSMenu)
- (NSString *)itemTitleAtIndex:(int)index
See Also: - itemAtIndex:
- (NSArray *)itemTitles
See Also: - itemTitleAtIndex:
- (id <NSMenuItem>)itemWithTitle:(NSString
*)title
nil
if
no such item exists.See Also: - itemTitleAtIndex:, - itemAtIndex:
- (id <NSMenuItem>)lastItem
- (NSMenu *)menu
See Also: - setMenu:
- (int)numberOfItems
See Also: - count (NSArray)
- (void)performClickWithFrame:(NSRect)frame
inView:(NSView *)controlView
- (NSRectEdge)preferredEdge
See Also: - setPreferredEdge:
- (BOOL)pullsDown
YES
if
the menu is a pulldown-style menu, otherwise returns NO
.See Also: - setPullsDown:
- (void)removeAllItems
See Also: - removeItemAtIndex:, - removeItemWithTitle:, - insertItemWithTitle:atIndex:
- (void)removeItemAtIndex:(int)index
See Also: - removeAllItems, - removeItemWithTitle:, - insertItemWithTitle:atIndex:
- (void)removeItemWithTitle:(NSString
*)title
See Also: - removeAllItems, - removeItemAtIndex:, - insertItemWithTitle:atIndex:
- (void)selectItem:(id
<NSMenuItem>)item
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)
- (void)selectItemAtIndex:(int)index
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)
- (void)selectItemWithTitle:(NSString
*)title
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)
- (id <NSMenuItem>)selectedItem
nil
of no menu item
is selected.See Also: - selectItem:, - selectItemAtIndex:, - selectItemWithTitle:
- (void)setAltersStateOfSelectedItem:(BOOL)flag
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)
- (void)setArrowPosition:(NSPopUpArrowPosition)position
- (void)setAutoenablesItems:(BOOL)flag
YES
,
menu items are automatically enabled and disabled. If flag is NO
,
menu items are not automatically enabled or disabled.See Also: - autoenablesItems
- (void)setMenu:(NSMenu
*)menu
See Also: - menu
- (void)setPreferredEdge:(NSRectEdge)edge
See Also: - preferredEdge
- (void)setPullsDown:(BOOL)flag
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
- (void)setTitle:(NSString
*)aString
See Also: - initTextCell:pullsDown:
- (void)setUsesItemFromMenu:(BOOL)flag
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
- (void)synchronizeTitleAndSelectedItem
If the popup button's menu does
not contain any menu items, this method sets the popup button's
item to nil
.
- (NSString *)titleOfSelectedItem
See Also: - selectItemWithTitle:
- (BOOL)usesItemFromMenu
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: