Inherits from: NSMenuItemCell : NSButtonCell : NSActionCell : NSCell : NSObject
Conforms to: NSCoding
(from NSCell)
NSCopying (from NSCell)
NSObject (from NSObject)
Declared in: AppKit/NSPopUpButtonCell.h
The NSPopupButtonCell class is under development, so the descriptions for this class are currently incomplete. Those API and descriptions that are included in this class specification should be considered draft quality and subject to change.
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 preffered edge if there is enough space on the user's screen. If there is not enough space, the cell positions the list somewhere else.
Unlike other menu-related classes implemented for Windows, 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
- - performClick:
- (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)performClick:(id)sender
This method is currently unimplemented. <<JPM: Should we even document this? Does performClickWithFrameInView: remove the need for this method?>>
- (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:
- (id <NSMenuItem>)selectedItem
nil
of no menu item
is selected.See Also: - selectItem:, - selectItemAtIndex:, - selectItemWithTitle:
- (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 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)
- (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 the NSMenuValidation protocol specification
for more information.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:
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.