Class

NSPopUpButton

A display of a single item from a list of items, and provide an interface for selecting items from the list.

Declaration

@interface NSPopUpButton : NSButton

Overview

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

Note that while a menu is tracking user input, programmatic changes to the menu such as adding, removing, or changing items on the menu is not reflected.

Topics

Initializing an NSPopUpButton

- initWithFrame:pullsDown:

Returns an NSPopUpButton object initialized to the specified dimensions.

Configuring the Cell

NSPopUpButtonCell

The NSPopUpButtonCell class defines the visual appearance of pop-up buttons that display pop-up or pull-down menus. Pop-up menus present the user with a set of choices, much the way radio buttons do, but using much less space. Pull-down menus 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.

Setting the type of menu

pullsDown

A Boolean value indicating whether the button displays a pull-down or pop-up menu.

autoenablesItems

A Boolean value indicating whether the button enables and disables its items every time a user event occurs.

Inserting and deleting items

- addItemWithTitle:

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

- addItemsWithTitles:

Adds multiple items to the end of the menu.

- insertItemWithTitle:atIndex:

Inserts an item at the specified position in the menu.

- removeAllItems

Removes all items in the receiver’s item menu.

- removeItemWithTitle:

Removes the item with the specified title from the menu.

- removeItemAtIndex:

Removes the item at the specified index.

Getting the user’s selection

selectedItem

The menu item that was last selected by the user.

titleOfSelectedItem

The title of the item that was last selected by the user.

indexOfSelectedItem

The index of the item that was last selected by the user.

- objectValue

Returns the index of the selected item.

selectedTag

The tag of the menu item that was last selected by the user.

Setting the current selection

- selectItem:

Selects the specified menu item.

- selectItemAtIndex:

Selects the item in the menu at the specified index.

- selectItemWithTag:

Selects the menu item with the specified tag.

- selectItemWithTitle:

Selects the item with the specified title.

- setObjectValue:

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

Getting menu items

menu

The menu associated with the pop-up button.

numberOfItems

The number of items in the menu.

itemArray

The array of menu item objects associated with the button.

- itemAtIndex:

Returns the menu item at the specified index.

- itemTitleAtIndex:

Returns the title of the item at the specified index.

itemTitles

An array of strings corresponding to the titles of the items in the menu.

- itemWithTitle:

Returns the menu item with the specified title.

lastItem

The last item in the menu.

Getting the indices of menu items

- indexOfItem:

Returns the index of the specified menu item.

- indexOfItemWithTag:

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

- indexOfItemWithTitle:

Returns the index of the item with the specified title.

- indexOfItemWithRepresentedObject:

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

- indexOfItemWithTarget:andAction:

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

Setting the cell edge to pop out in restricted situations

preferredEdge

The edge of the button on which to display the menu when screen space is constrained.

Setting the title

- setTitle:

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

Setting the image

- setImage:

This method has no effect.

Setting the state

- synchronizeTitleAndSelectedItem

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

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.

Relationships

Inherits From

See Also

Controls

NSButton

A control that defines an area on the screen that can be used to trigger actions.

NSColorWell

A control that displays a color value and lets the user change that color value.

Date Picker

Display a calendar date and provide controls for editing the date value.

NSImageView

A display of image data from an NSImage object in a frame.

NSLevelIndicator

A visual representation of a level or quantity, using discrete values.

Path Control

A display of a file system path or virtual path information.

NSProgressIndicator

An interface that provides visual feedback to the user about the status of an ongoing task.

NSRuleEditor

An interface for configuring a rule-based list of options.

NSPredicateEditor

A defined set of rules that allows the editing of predicate objects.

Search Field

Provide a text field that is optimized for text-based search interfaces.

NSSegmentedControl

Display one or more buttons in a single horizontal group.

Slider

Display a range of values from which the user selects a single value.

NSStepper

An interface with up and down arrow buttons for incrementing or decrementing a value.

Text Field

Provide a simple interface for displaying and editing text, including support for password fields and secure forms of text entry.

Token Field

Provide a text field whose text can be rendered in a visually distinct way so that users can recognize portions more easily.

Toolbar

Provide a space for controls under a window's title bar and above your custom content.

Combo Box

Display a list of values in a pop-up menu that lets the user select a value or type in a custom value.

NSMatrix

A legacy interface for grouping radio buttons or other types of cells together.