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

Table of Contents

NSPopUpButton


Inherits from:
NSButton : NSControl : NSView : NSResponder : NSObject
Conforms to:
NSCoding
(NSResponder)
NSObject (NSObject)
Declared in:
AppKit/NSPopUpButton.h



Class at a Glance


An NSPopUpButton object controls a pop-up list or a pull-down list, from which a user can select an item.

Principal Attributes


Creation



Interface Builder

Commonly Used Methods



- selectedItem Returns the currently selected item.
- indexOfSelectedItem Returns an integer identifying the currently selected item.
- titleOfSelectedItem Returns a string identifying the currently selected item.


Class Description


The NSPopUpButton class defines objects that implement the pop-up and pull-down lists of the graphical user interface. You normally create an NSPopUpButton using Interface Builder.

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.


Using an NSPopUpButton

Although the NSPopUpButton class defines an initialization method and methods that set up the list created by this class, you usually don't invoke these methods in your program. The typical way to create an NSPopUpButton is to use Interface Builder. You can define the NSPopUpButton's target and action, as well as the targets and actions of each item in the NSPopUpButton's list, programmatically or through Interface Builder. The NSPopUpButton methods you use most often are the methods that tell you which item is selected.

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 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;
}




Method Types


Initializing an NSPopUpButton
- initWithFrame:pullsDown:
Setting the type of list
- setPullsDown:
- pullsDown
- setAutoenablesItems:
- autoenablesItems
Inserting and deleting Items
- addItemWithTitle:
- addItemsWithTitles:
- insertItemWithTitle:atIndex:
- removeAllItems
- removeItemWithTitle:
- removeItemAtIndex:
Getting the user's selection
- selectedItem
- titleOfSelectedItem
- indexOfSelectedItem
Setting the current selection
- selectItem:
- selectItemAtIndex:
- selectItemWithTitle:
Getting menu items
- numberOfItems
- itemArray
- itemAtIndex:
- itemTitleAtIndex:
- itemTitles
- itemWithTitle:
- lastItem
Getting the indices of menu items
- indexOfItem:
- indexOfItemWithTag:
- indexOfItemWithTitle:
- indexOfItemWithRepresentedObject:
- indexOfItemWithTarget:andAction:
Setting the cell edge to pop out from in restricted situations
- preferredEdge
- setPreferredEdge:
Setting the title
- setTitle:
Setting the state
- synchronizeTitleAndSelectedItem


Instance Methods



addItemWithTitle:

- (void)addItemWithTitle:(NSString *)title

Adds an item named title to the end of the list. This method then calls synchronizeTitleAndSelectedItem to make sure the item displayed matches the currently selected item.

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



addItemsWithTitles:

- (void)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 the item displayed matches the currently selected item.

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



autoenablesItems

- (BOOL)autoenablesItems

Returns whether the receiver automatically enables and disables its items every time a user event occurs. Autoenabling is turned on unless you send the message setAutoenablesItems: with an argument of NO to the NSPopUpButton.

See Also: - setAutoenablesItems:



indexOfItem:

- (int)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:

- (int)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 the same name of its NSPopUpButtonCell.

indexOfItemWithTag:

- (int)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:andAction:

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

Returns the index of the first menu item in the pop-up list that has the target target and the action actionSelector. If actionSelector is nil, the index of the first menu item in the pop-up list that has target 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:

- (int)indexOfItemWithTitle:(NSString *)title

Returns the index of the first item whose title matches title or -1 if no match is found.

indexOfSelectedItem

- (int)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:pullsDown:

- (id)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.

See Also: - pullsDown, - setPullsDown:



insertItemWithTitle:atIndex:

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

Inserts an item with title 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 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

- (NSArray *)itemArray

Returns the NSArray that holds the list's items. The receiver's list is actually an NSArray of NSMenuItems. 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:

- (id <NSMenuItem>)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:

- (NSString *)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

- (NSArray *)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:

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

Returns the first item whose title is title. If there is no item with title, this method returns nil.

See Also: - addItemWithTitle:, - selectItemWithTitle:, - itemAtIndex:, - indexOfItemWithTitle:



lastItem

- (id <NSMenuItem>)lastItem

Returns the last item in the list.

See Also: - itemAtIndex:



menu

- (NSMenu *)menu

Description forthcoming.

numberOfItems

- (int)numberOfItems

Returns the number of items in the list.

See Also: - lastItem



preferredEdge

- (NSRectEdge)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

- (BOOL)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

- (void)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:

- (void)removeItemAtIndex:(int)index

Removes the item at index. This method then uses synchronizeTitleAndSelectedItem to make sure the title displayed matches the currently selected item.

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



removeItemWithTitle:

- (void)removeItemWithTitle:(NSString *)title

Removes the first item named title. This method then uses synchronizeTitleAndSelectedItem to refresh the list.

See Also: - addItemWithTitle:, - removeAllItems, - removeItemAtIndex:



selectItem:

- (void)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:

- (void)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:

- (void)selectItemWithTitle:(NSString *)title

Selects the first item with title and invokes synchronizeTitleAndSelectedItem to make sure the title displayed matches the currently selected item.

See Also: - indexOfItemWithTitle:, - addItemWithTitle:, - setTitle:



selectedItem

- (id <NSMenuItem>)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.

setAutoenablesItems:

- (void)setAutoenablesItems:(BOOL)flag

Sets whether the receiver 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 Also: - autoenablesItems



setMenu:

- (void)setMenu:(NSMenu *)menu

Description forthcoming.

setPreferredEdge:

- (void)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:

- (void)setPullsDown:(BOOL)flag

Controls whether the receiver behaves as a pull-down or pop-up list. 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:

- (int)setTitle:(NSString *)aString

Description forthcoming.

synchronizeTitleAndSelectedItem

- (void)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

- (NSString *)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




Notifications


NSPopUpButtonWillPopUpNotification

Posted when the NSPopUpButton receives a mouse-down event; that is, when the user is about to select an item from the list. This notification contains a notification object but no userInfo dictionary. The notification object is the selected NSPopUpButton.

Table of Contents