Inherits From:
NSButton : NSControl : NSView : NSResponder : NSObject
Conforms To:
NSCoding (NSResponder)
NSObject (NSObject)
Declared In:
AppKit/NSPopUpButton.h
- selectedItem | Returns the currently selected item. |
- indexOfSelectedItem | Returns an integer identifying the currently selected item. |
- titleOfSelectedItem | Returns a string identifying the currently selected item. |
When configured to display a pop-up list, an NSPopUpButton contains a number of options and usually displays the option that was last selected. A pop-up list is often used for selecting items from a small- to medium-sized set of options (like the zoom factor for a document window). It's a useful alternative to a matrix of radio buttons or an NSBrowser or NSTableView when screen space is at a premium; a zoom factor pop-up can easily fit next to a scroll bar at the bottom of a window, for example.
When configured to display a pull-down list, an NSPopUpButton is generally used for selecting commands in a very specific context. You can think of a pull-down list as a compact form of menu. A pull-down list's display isn't affected by the user's actions, and a pull-down list usually displays the first item in the list. When the commands only make sense in the context of a particular display, a pull-down list can be used in that display to keep the related actions nearby and to keep them out of the way when that display isn't visible.
The items in the pop-up list or pull-down list (referred to simply as a list in this class description) are objects that conform to the NSMenuItem protocol. Thus, you can send any message defined in that protocol to any item in the list.
For example, suppose you want to create a pop-up list from which your user may select a language. You want your controller object to set an instance variable named language
to an enum constant that corresponds to the value that the user has chosen. You use Interface Builder to create the NSPopUpButton object, name it (languagePopUp
in this example) add items to it, and configure it as a pop-up list. The actual code you write might look like this:
typedef enum _languageValue {
English,
French,
German
} languageValue;
- (void)setLanguage:(id)sender{
NSString *title = [languagePopUp titleOfSelectedItem];
if ([title isEqualToString:@"English"])
language = English;
else if ([title isEqualToString:@"French"])
language = French;
else if ([title isEqualToString:@"German"])
language = German;
}
addItemWithTitle:
(NSString *)title
Adds an item named title to the end of the list. This method then calls synchronizeTitleAndSelectedItem
to make sure that the item displayed matches the currently selected item.
See also:
- insertItemWithTitle:atIndex:
, - removeItemWithTitle:
, - setTitle:
addItemsWithTitles:
(NSArray *)itemTitles
Adds multiple items to the end of the list. The titles for the new items are taken from the itemTitles array. Once the items are added, this method uses synchronizeTitleAndSelectedItem
to make sure that the item displayed matches the currently selected item.
See also:
- insertItemWithTitle:atIndex:
, - removeAllItems
, - removeItemWithTitle:
autoenablesItems
Returns whether the NSPopUpButton automatically enables and disables its items every time a user event occurs. Autoenabling is turned on unless you send the message setAutoenablesItems:NO
to the NSPopUpButton. See the NSMenuActionResponder informal protocol for more information on autoenabling menu items.
See also:
- setAutoenablesItems:
indexOfItem:
(id <NSMenuItem>)anObject
Returns the index of menu item anObject in the pop-up list or -1 if the menu item is not found. This method invokes the method of the same name of its NSPopUpButtonCell.
indexOfItemWithRepresentedObject:
(id)anObject
Returns the index of the first menu item in the pop-up list that holds the represented object anObject, or -1 if no menu item with this object is found. Represented objects bear some direct relation to the title or image of a menu item; for example, an item entitled "100" might have an NSNumber encapsulating that value as its represented object. This method invokes the method of its NSPopUpButtonCell that has the same name.
indexOfItemWithTag:
(int)tag
Returns the index of the first menu item in the pop-up list that has the tag value tag or -1 if the item is not found. This method invokes the method of the same name of its NSPopUpButtonCell.
indexOfItemWithTarget:
(id)target andAction:
(SEL)actionSelector
Returns the index of the first menu item in the pop-up list that has the target of target and the action actionSelector. If actionSelector is NULL, the index of the first menu item in the pop-up list that has a target of target is returned. If no menu item matching the above criteria is found, -1 is returned. This method invokes the method of the same name of its NSPopUpButtonCell.
indexOfItemWithTitle:
(NSString *)title
Returns the index of the first item whose title matches title or -1 if no match is found.
indexOfSelectedItem
Returns the index of the item last selected by the user or -1 if there's no selected item.
See also:
- selectedItem
, - titleOfSelectedItem
initWithFrame:
(NSRect)frameRect pullsDown:
(BOOL)flag
Initializes a newly allocated NSPopUpButton, giving it the dimensions specified by frameRect. If flag is YES, the receiver is initialized to operate as a pull-down list; otherwise, it operates as a pop-up list. I
See also:
- pullsDown
, - setPullsDown:
insertItemWithTitle:
(NSString *)title atIndex:
(int)index
Inserts an item with the name title at position index in the list. Index 0 indicates the top item. Once the item is inserted, this method uses synchronizeTitleAndSelectedItem
to make sure that the item displayed matches the currently selected item.
If an item with the name title already exists in the list, it's removed and the new one is added. This essentially moves title to a new position. If you want to move an item, it's better to invoke removeItemWithTitle:
explicitly and then send this method.
See also:
- addItemWithTitle:
, - addItemsWithTitles:
, - indexOfItemWithTitle:
,
- removeItemWithTitle:
itemArray
Returns the NSArray that holds the list's items. The NSPopUpButton's list is actually an NSArray of objects conforming to the NSMenuItem protocol. Usually you access the list's items and modify the list by sending messages directly to the NSPopUpButton rather than accessing the NSArray.
See also:
- itemAtIndex:
, - insertItemWithTitle:atIndex:
, - removeItemAtIndex:
itemAtIndex:
(int)index
Returns the list item at index. If there is no item at index, this method returns nil
.
See also:
- itemWithTitle:
, - lastItem
itemTitleAtIndex:
(int)index
Returns the title of the item at index. If there is no item at index, this method returns the empty string.
See also:
- itemTitles
itemTitles
Returns an NSArray object that holds the titles of all of the items in the list. The titles appear in the order in which the items appear in the list.
See also:
- itemTitleAtIndex:
, - itemWithTitle:
, - numberOfItems
itemWithTitle:
(NSString *)title
Returns the first item whose title is title. If there is no item with this title, this method returns nil
.
See also:
- addItemWithTitle:
, - selectItemWithTitle:
, - itemAtIndex:
, - indexOfItemWithTitle:
lastItem
Returns the last item in the list.
See also:
- itemAtIndex:
numberOfItems
Returns the number of items in the list.
See also:
- lastItem
preferredEdge
Returns the edge of the receiver next to which the pop-up list is displayed under restrictive screen conditions. For pull-down lists, the default behavior is to display the list under the receiver. For most pop-up lists, NSPopUpButton attempts to show the selected item directly over the button.
See also:
- setPreferredEdge:
pullsDown
Returns YES if the receiver is configured as a pull-down list or NO if it's configured as a pop-up list.
See also:
- setPullsDown:
removeAllItems
Removes all items in the receiver's item list. This method then uses synchronizeTitleAndSelectedItem
to refresh the list.
See also:
- numberOfItems
, - removeItemAtIndex:
, - removeItemWithTitle:
removeItemAtIndex:
(int)index
Removes the item at index. This method then uses synchronizeTitlesAndSelectedItem
to make sure the title displayed matches the currently selected item.
See also:
- insertItemWithTitle:atIndex:
, - removeAllItems
, - removeItemWithTitle:
removeItemWithTitle:
(NSString *)title
Removes the first item named title. This method then uses synchronizeTitleAndSelectedItem
to refresh the list.
See also:
- addItemWithTitle:
, - removeAllItems
, - removeItemAtIndex:
selectedItem
Returns the item last selected by the user (the item that was highlighted when the user released the mouse button). If there is no selected item, this method returns nil
. It is possible for a pull-down list's selected item to be its first item.
selectItem
(id <NSMenuItem>)
anObject
Selects the menu item anObject in the pop-up list. If anObject is nil
, all items in the list are deselected (this is a technique for obtaining a pop-up list with no items selected).
selectItemAtIndex:
(int)index
Selects the item in the list at index and invokes synchronizeTitleAndSelectedItem
to make sure the title displayed matches the currently selected item. If index is -1 all items in the list are deselected.
See also:
- indexOfSelectedItem
selectItemWithTitle:
(NSString *)title
Selects the first item with the given title and invokes synchronizeTitleAndSelectedItem
to make sure the title displayed matches the currently selected item.
See also:
- indexOfItemWithTitle:
, - addItemWithTitle:
, - setTitle:
setAutoenablesItems:
(BOOL)flag
Sets whether the NSPopUpButton automatically enables and disables its items every time a user event occurs. Autoenabling is turned on unless you specify NO as the value for flag. See the NSMenuActionResponder informal protocol for more information on autoenabling menu items.
See also:
- autoenablesItems
setFont:
(NSFont *)fontObject
Sets the font used for the items' titles to fontObject. The NSPopUpButton invalidates its display at this point, but since it normally won't be on the screen when it receives this message, this shouldn't cause any undesirable side-effects.
setPreferredEdge:
(NSRectEdge)edge
Sets the edge of the receiver next to which the pop-up list should appear under restrictive screen conditions. For pull-down lists, the default behavior is to display the list under the receiver. For most pop-up lists, NSPopUpButton attempts to show the selected item directly over the button.
See also:
- preferredEdge
setPullsDown:
(BOOL)flag
If flag is YES, the receiver is configured as a pull-down list. If flag is NO, the receiver is configured as a pop-up list.
See also:
- initWithFrame:pullsDown:
, - pullsDown
setTitle:
(NSString *)aString
<<forthcoming>>
synchronizeTitleAndSelectedItem
Ensures that the item being displayed by the receiver agrees with the selected item (see indexOfSelectedItem
). If there's no selected item, this method selects the first item in the item list and sets the receiver's item to match. For pull-down lists, this method makes sure that the first item is being displayed (the NSPopUpButtonCell must be set to use the selected menu item, which happens by default).
See also:
- itemArray
titleOfSelectedItem
Returns the title of the item last selected by the user or the empty string if there's no such item.
See also:
- indexOfSelectedItem
,
- stringValue
(NSControl)