ADC Home > Reference Library > Reference > Cocoa > User Experience > NSPopUpButton Class Reference >

Next Page > Hide TOC

NSPopUpButton Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in Mac OS X v10.0 and later.
Companion guide
Declared in
NSPopUpButton.h
Related sample code

Class at a Glance

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

Principal Attributes

Creation

Interface Builder

Use Interface Builder to add a pop-up or pull-down menu to a window or panel.

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.

Overview

The NSPopUpButton class defines objects that implement the pop-up and pull-down menus of the graphical user interface.

An NSPopUpButton object uses an NSPopUpButtonCell object to implement its user interface.

Note that while a menu is tracking, adding, removing, or changing items on the menu is not reflected.

Tasks

Initializing an NSPopUpButton

Setting the Type of Menu

Inserting and Deleting Items

Getting the User’s Selection

Setting the Current Selection

Getting Menu Items

Getting the Indices of Menu Items

Setting the Cell Edge to Pop out in Restricted Situations

Setting the Title

Setting the Image

Setting the State

Instance Methods

addItemsWithTitles:

Adds multiple items to the end of the menu.

- (void)addItemsWithTitles:(NSArray *)itemTitles

Parameters
itemTitles

An array of NSString objects containing the titles of the items you want to add. Each string in the array should be unique. If an item with the same title already exists in the menu, the existing item is removed and the new one is added.

Discussion

If you want to move an item, it’s better to invoke removeItemWithTitle: explicitly and then send this method. After adding the items, this method uses the synchronizeTitleAndSelectedItem method to make sure the item being displayed matches the currently selected item.

Since this method searches for duplicate items, it should not be used if you are adding items to an already populated menu with more than a few hundred items. Add items directly to the receiver's menu instead.

Availability
See Also
Related Sample Code
Declared In
NSPopUpButton.h

addItemWithTitle:

Adds an item with the specified title to the end of the menu.

- (void)addItemWithTitle:(NSString *)title

Parameters
title

The title of the menu-item entry. If an item with the same title already exists in the menu, the existing item is removed and the new one is added.

Discussion

If you want to move an item, it’s better to invoke removeItemWithTitle: explicitly and then send this method. After adding the item, this method calls the synchronizeTitleAndSelectedItem method to make sure the item being displayed matches the currently selected item.

Since this method searches for duplicate items, it should not be used if you are adding an item to an already populated menu with more than a few hundred items. Add items directly to the receiver's menu instead.

Availability
See Also
Related Sample Code
Declared In
NSPopUpButton.h

autoenablesItems

Returns whether the receiver automatically enables and disables its items every time a user event occurs.

- (BOOL)autoenablesItems

Return Value

YES if the receiver automatically enables and disables items; otherwise, NO. The default value is YES.

Discussion

For more information on enabling and disabling menu items, see the NSMenuValidation protocol specification.

Availability
See Also
Declared In
NSPopUpButton.h

indexOfItem:

Returns the index of the specified menu item.

- (NSInteger)indexOfItem:(NSMenuItem *)anObject

Parameters
anObject

The menu item whose index you want.

Return Value

The index of the item or -1 if no such item was found.

Discussion

This method invokes the method of the same name of its NSPopUpButtonCell object.

Availability
Declared In
NSPopUpButton.h

indexOfItemWithRepresentedObject:

Returns the index of the menu item that holds the specified represented object.

- (NSInteger)indexOfItemWithRepresentedObject:(id)anObject

Parameters
anObject

The represented object associated with a menu item.

Return Value

The index of the menu item that owns the specified object, or -1 if no such menu item was found.

Discussion

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 object encapsulating that value as its represented object. This method invokes the method of the same name of its NSPopUpButtonCell object.

Availability
Declared In
NSPopUpButton.h

indexOfItemWithTag:

Returns the index of the menu item with the specified tag.

- (NSInteger)indexOfItemWithTag:(NSInteger)tag

Parameters
tag

The tag of the menu item you want.

Return Value

The index of the item or -1 if no item with the specified tag was found.

Discussion

This method invokes the method of the same name of its NSPopUpButtonCell object.

Availability
Declared In
NSPopUpButton.h

indexOfItemWithTarget:andAction:

Returns the index of the menu item with the specified target and action.

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

Parameters
target

The target object associated with the menu item.

actionSelector

The action method associated with the menu item.

Return Value

The index of the menu item, or -1 if no menu item contains the specified target and action.

Discussion

If you specify NULL for the actionSelector parameter, the index of the first menu item with the specified target is returned. This method invokes the method of the same name of its NSPopUpButtonCell object.

Availability
Declared In
NSPopUpButton.h

indexOfItemWithTitle:

Returns the index of the item with the specified title.

- (NSInteger)indexOfItemWithTitle:(NSString *)title

Parameters
title

The title of the item you want.

Return Value

The index of the item or -1 if no item with the specified title was found.

Availability
Related Sample Code
Declared In
NSPopUpButton.h

indexOfSelectedItem

Returns the index of the item last selected by the user.

- (NSInteger)indexOfSelectedItem

Return Value

The index of the selected item, or -1 if no item is selected.

Availability
See Also
Related Sample Code
Declared In
NSPopUpButton.h

initWithFrame:pullsDown:

Returns an NSPopUpButton object initialized to the specified dimensions.

- (id)initWithFrame:(NSRect)frameRect pullsDown:(BOOL)flag

Parameters
frameRect

The frame rectangle for the button, specified in the parent view's coordinate system.

flag

YES if you want the receiver to display a pull-down menu; otherwise, NO if you want it to display a pop-up menu.

Return Value

An initialized NSPopUpButton object, or nil if the object could not be initialized.

Availability
See Also
Related Sample Code
Declared In
NSPopUpButton.h

insertItemWithTitle:atIndex:

Inserts an item at the specified position in the menu.

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

Parameters
title

The title of the new item. If an item with the same title already exists in the menu, the existing item is removed and the new one is added

index

The zero-based index at which to insert the item. Specifying 0 inserts the item at the top of the menu.

Discussion

If you want to move an item, it’s better to invoke removeItemWithTitle: explicitly and then send this method. After adding the item, this method uses the synchronizeTitleAndSelectedItem method to make sure the item displayed matches the currently selected item.

Since this method searches for duplicate items, it should not be used if you are adding an item to an already populated menu with more than a few hundred items. Add items directly to the receiver's menu instead.

Availability
See Also
Related Sample Code
Declared In
NSPopUpButton.h

itemArray

Returns the items in the menu.

- (NSArray *)itemArray

Return Value

An array of id <NSMenuItem> objects representing the items in the menu.

Discussion

Usually you access the menu’s items and modify the menu using the methods of NSPopUpButton rather than accessing the array of items directly.

Availability
See Also
Declared In
NSPopUpButton.h

itemAtIndex:

Returns the menu item at the specified index.

- (NSMenuItem *)itemAtIndex:(NSInteger)index

Parameters
index

The index of the item you want.

Return Value

The menu item, or nil if no item exists at the specified index.

Availability
See Also
Related Sample Code
Declared In
NSPopUpButton.h

itemTitleAtIndex:

Returns the title of the item at the specified index.

- (NSString *)itemTitleAtIndex:(NSInteger)index

Parameters
index

The index of the item you want.

Return Value

The title of the item, or an empty string if no item exists at the specified index.

Availability
See Also
Declared In
NSPopUpButton.h

itemTitles

Returns the titles of all of the items in the menu.

- (NSArray *)itemTitles

Return Value

An array of NSString objects containing the titles of every item in the menu. The titles appear in the order in which the items appear in the menu.

Discussion

If the menu contains separator items, the array contains an empty string (@””) for each separator item.

Availability
See Also
Declared In
NSPopUpButton.h

itemWithTitle:

Returns the menu item with the specified title.

- (NSMenuItem *)itemWithTitle:(NSString *)title

Parameters
title

The title of the menu item you want.

Return Value

The menu item, or nil if no item with the specified title exists in the menu.

Availability
See Also
Declared In
NSPopUpButton.h

lastItem

Returns the last item in the menu.

- (NSMenuItem *)lastItem

Return Value

The last menu item.

Availability
See Also
Related Sample Code
Declared In
NSPopUpButton.h

menu

Returns the pop-up button’s associated menu.

- (NSMenu *)menu

Return Value

The menu for the pop-up button.

Availability
Related Sample Code
Declared In
NSPopUpButton.h

numberOfItems

Returns the number of items in the menu.

- (NSInteger)numberOfItems

Return Value

The number of items in the menu.

Availability
See Also
Declared In
NSPopUpButton.h

objectValue

Returns the index of the selected item.

- (id)objectValue

Return Value

An object (typically an NSNumber object) that responds to the intValue message and contains the index of the selected item.

See Also

preferredEdge

Returns the edge of the receiver next to which the pop-up menu is displayed under restrictive screen conditions.

- (NSRectEdge)preferredEdge

Return Value

Possible values include NSMinXEdge, NSMinYEdge, NSMaxXEdge, or NSMaxYEdge. The default value is the bottom edge, which is NSMaxYEdge for flipped views or NSMinYEdge for unflipped views.

Discussion

For pull-down menus, the default behavior is to display the menu under the receiver. For most pop-up menus, the NSPopUpButton object attempts to show the selected item directly over the button.

Availability
See Also
Declared In
NSPopUpButton.h

pullsDown

Returns a Boolean value indicating the behavior of the control's menu.

- (BOOL)pullsDown

Return Value

YES if the menu behaves like a pull-down menu; otherwise, NO if it behaves like a pop-up menu.

Availability
See Also
Declared In
NSPopUpButton.h

removeAllItems

Removes all items in the receiver’s item menu.

- (void)removeAllItems

Discussion

After removing the items, this method uses the synchronizeTitleAndSelectedItem method to refresh the menu.

Availability
See Also
Related Sample Code
Declared In
NSPopUpButton.h

removeItemAtIndex:

Removes the item at the specified index.

- (void)removeItemAtIndex:(NSInteger)index

Parameters
index

The zero-based index indicating which item to remove. Specifying 0 removes the item at the top of the menu.

Discussion

After removing the item, this method uses the synchronizeTitleAndSelectedItem method to make sure the title displayed matches the currently selected item.

Availability
See Also
Declared In
NSPopUpButton.h

removeItemWithTitle:

Removes the item with the specified title from the menu.

- (void)removeItemWithTitle:(NSString *)title

Parameters
title

The title of the item you want to remove. If no menu item exists with the specified title, this method triggers an assertion.

Discussion

This method removes the first item it finds with the specified name. This method then uses synchronizeTitleAndSelectedItem to refresh the menu.

Availability
See Also
Declared In
NSPopUpButton.h

selectedItem

Returns the menu item last selected by the user.

- (NSMenuItem *)selectedItem

Return Value

The menu item that is currently selected, or nil if no item is selected.

Discussion

The last selected menu item is the one that was highlighted when the user released the mouse button. It is possible for a pull-down menu’s selected item to be its first item.

Availability
Related Sample Code
Declared In
NSPopUpButton.h

selectItem:

Selects the specified menu item.

- (void)selectItem:(NSMenuItem *)item

Parameters
anObject

The menu item to select, or nil if you want to deselect all menu items.

Availability
Related Sample Code
Declared In
NSPopUpButton.h

selectItemAtIndex:

Selects the item in the menu at the specified index.

- (void)selectItemAtIndex:(NSInteger)index

Parameters
index

The index of the item you want to select, or -1 you want to deselect all menu items.

Availability
See Also
Related Sample Code
Declared In
NSPopUpButton.h

selectItemWithTag:

Selects the menu item with the specified tag.

- (BOOL)selectItemWithTag:(NSInteger)tag

Parameters
tag

The tag of the item you want to select.

Return Value

YES if the item was successfully selected; otherwise, NO.

Discussion

If no item with the specified tag is found, this method returns NO and leaves the menu state unchanged.

You typically assign tags to menu items from Interface Builder, but you can also assign them programmatically using the setTag: method of NSMenuItem.

Availability
See Also
Related Sample Code
Declared In
NSPopUpButton.h

selectItemWithTitle:

Selects the item with the specified title.

- (void)selectItemWithTitle:(NSString *)title

Parameters
title

The title of the item to select. If you specify nil, an empty string, or a string that does not match the title of a menu item, this method deselects the currently selected item.

Availability
See Also
Declared In
NSPopUpButton.h

setAutoenablesItems:

Sets whether the receiver automatically enables and disables its items every time a user event occurs.

- (void)setAutoenablesItems:(BOOL)flag

Parameters
flag

YES if you want the receiver to automatically enable and disable items; otherwise, NO.

Availability
See Also
Related Sample Code
Declared In
NSPopUpButton.h

setImage:

This method has no effect.

- (void)setImage:(NSImage *)anImage

Parameters
anImage

The image to display.

Discussion

The image displayed in a pop up button cell is taken from the selected menu item (in the case of a pop up menu) or from the first menu item (in the case of a pull-down menu).

setMenu:

Sets the pop-up button’s associated menu .

- (void)setMenu:(NSMenu *)menu

Parameters
menu

The menu to associate with the pop-up button.

Discussion

If another menu was already associated with the pop-up button, this method releases the old menu. If you want to explicitly save the old menu, you should retain it before invoking this method.

Availability
Declared In
NSPopUpButton.h

setObjectValue:

Selects the item at a specific index using an object value.

- (void)setObjectValue:(id)object

Parameters
object

An NSNumber object containing the index (an integer) of the item you want to select. Specify the index -1 to deselect all items. You can also use an object other than an NSNumber object. In that case, the object must respond to the intValue method and return an appropriate index value.

Discussion

See Also

setPreferredEdge:

Sets the edge of the receiver next to which the pop-up menu should appear under restrictive screen conditions.

- (void)setPreferredEdge:(NSRectEdge)edge

Parameters
edge

The preferred edge. Possible values include NSMinXEdge, NSMinYEdge, NSMaxXEdge, or NSMaxYEdge.

Discussion

For pull-down menus, the default behavior is to display the menu under the receiver. For most pop-up menus, the NSPopUpButton object attempts to show the selected item directly over the button.

Availability
See Also
Declared In
NSPopUpButton.h

setPullsDown:

Sets whether the receiver behaves as a pull-down or pop-up menu.

- (void)setPullsDown:(BOOL)flag

Parameters
flag

YES if you want the receiver to operate as a pull-down menu; otherwise, NO if you want it to operate as a pop-up menu.

Discussion

This method does not change the contents of the menu; it changes only the style of the menu.

When changing the menu type to a pull-down 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.

Availability
See Also
Declared In
NSPopUpButton.h

setTitle:

Sets the string displayed in the receiver when the user isn’t pressing the mouse button.

- (void)setTitle:(NSString *)aString

Parameters
aString

The string to display.

Discussion

If the receiver displays a pop-up menu, this method changes the current item to be the item with the specified title, adding a new item by that name if one does not already exist. If the receiver displays a pull-down list, this method sets its title to the specified string.

Availability
Declared In
NSPopUpButton.h

synchronizeTitleAndSelectedItem

Ensures that the item being displayed by the receiver agrees with the selected item.

- (void)synchronizeTitleAndSelectedItem

Discussion

If there’s no selected item, this method selects the first item in the item menu and sets the receiver’s item to match. For pull-down menus, this method makes sure that the first item is being displayed (the NSPopUpButtonCell object must be set to use the selected menu item, which happens by default).

Availability
See Also
Declared In
NSPopUpButton.h

titleOfSelectedItem

Returns the title of the item last selected by the user.

- (NSString *)titleOfSelectedItem

Return Value

The title of the selected menu item, or an empty string if no item is selected.

Availability
See Also
Related Sample Code
Declared In
NSPopUpButton.h

Notifications

NSPopUpButtonWillPopUpNotification

Posted when an NSPopUpButton object receives a mouse-down event—that is, when the user is about to select an item from the menu.

The notification object is the selected NSPopUpButton object. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSPopUpButton.h

Next Page > Hide TOC

© 2008 Apple Inc. All Rights Reserved. (Last updated: 2008-10-15)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.