NSComboBox Class Reference

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

Overview

An NSComboBox is a kind of NSControl that allows you to either enter text directly (as you would with an NSTextField) or click the attached arrow at the right of the combo box and select from a displayed (“pop-up”) list of items.

Normally an instance of NSComboBox looks like this:

Art/combobox.gif

When you click the downward-pointing arrow at the right side of the text field, the pop-up list appears, like this:

Art/comboboxlist.gif

The NSComboBox class uses NSComboBoxCell to implement its user interface.

Also see the NSComboBoxDataSource informal protocol, which declares the methods that an NSComboBox uses to access the contents of its data source object.

Tasks

Setting Display Attributes

Setting a Data Source

Working with an Internal List

Manipulating the Displayed List

Manipulating the Selection

Completing the Text Field

New Methods

Instance Methods

addItemsWithObjectValues:

Adds multiple objects to the end of the receiver’s internal item list.

- (void)addItemsWithObjectValues:(NSArray *)objects
Parameters
objects

An array of the objects to add to the internal item list.

Discussion

This method logs a warning if usesDataSource returns YES.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

addItemWithObjectValue:

Adds an object to the end of the receiver’s internal item list.

- (void)addItemWithObjectValue:(id)anObject
Parameters
anObject

The object to add to the internal item list.

Discussion

This method logs a warning if usesDataSource returns YES.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

completes

Returns a Boolean value indicating whether the receiver tries to complete what the user types in the text field.

- (BOOL)completes
Return Value

YES if the receiver tries to complete what the user types in the text field; otherwise NO.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

dataSource

Returns the object that provides the data displayed in the receiver’s pop-up list.

- (id < NSComboBoxDataSource >)dataSource
Return Value

The data source for the combo box's pop-up list.

Discussion

This method logs a warning if usesDataSource returns NO. See the class description and the NSComboBoxDataSource informal protocol specification for more information on combo box data source objects.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

delegate

Returns the receiver’s delegate.

- (id < NSComboBoxDelegate >)delegate
Return Value

The receiver’s delegate.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSComboBox.h

deselectItemAtIndex:

Deselects the pop-up list item at the specified index if it’s selected.

- (void)deselectItemAtIndex:(NSInteger)index
Parameters
index

The index of the item to deselect.

Discussion

If the selection does in fact change, this method posts an NSComboBoxSelectionDidChangeNotification to the default notification center.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

hasVerticalScroller

Returns a Boolean value indicating whether the receiver will display a vertical scroller.

- (BOOL)hasVerticalScroller
Return Value

YES if the receiver will display a vertical scroller; otherwise NO.

Discussion

Note that the scroller will be displayed even if the pop-up list contains fewer items than will fit in the area specified for display.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

indexOfItemWithObjectValue:

Searches the receiver’s internal item list for the specified object and returns the lowest matching index.

- (NSInteger)indexOfItemWithObjectValue:(id)anObject
Parameters
anObject

The object for which to return the index.

Return Value

The lowest index in the internal item list whose corresponding value is equal to that of the specified object. Objects are considered equal if they have the same id or if isEqual: returns YES.

If none of the objects in the receiver’s internal item list are equal to anObject, indexOfItemWithObjectValue: returns NSNotFound.

Discussion

This method logs a warning if usesDataSource returns YES.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

indexOfSelectedItem

Returns the index of the last item selected from the pop-up list.

- (NSInteger)indexOfSelectedItem
Return Value

The index of the last item selected from the receiver's pop-up list or -1 if no item is selected.

Discussion

Note that nothing is initially selected in a newly initialized combo box.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSComboBox.h

insertItemWithObjectValue:atIndex:

Inserts an object at the specified location in the receiver’s internal item list.

- (void)insertItemWithObjectValue:(id)anObject atIndex:(NSInteger)index
Parameters
anObject

The object to add to the internal item list.

index

The index in the list at which to add the new object. The previous item at index—along with all following items—is shifted down one slot to make room

Discussion

This method logs a warning if usesDataSource returns YES.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSComboBox.h

intercellSpacing

Returns the horizontal and vertical spacing between cells in the receiver’s pop-up list.

- (NSSize)intercellSpacing
Return Value

The space between cells in the pop-up list. The default spacing is (3.0, 2.0).

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

isButtonBordered

Returns whether the combo box button is set to display a border.

- (BOOL)isButtonBordered
Return Value

YES if the button has a border; otherwise NO.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSComboBox.h

itemHeight

Returns the height of each item in the receiver’s pop-up list.

- (CGFloat)itemHeight
Return Value

The height of items in the pop-up list. The default item height is 16.0.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

itemObjectValueAtIndex:

Returns the object located at the given index within the receiver’s internal item list.

- (id)itemObjectValueAtIndex:(NSInteger)index
Parameters
index

The index of the object to retrieve. If index is beyond the end of the list, an NSRangeException is raised.

Return Value

The object located at the specified index in the internal item list.

Discussion

This method logs a warning if usesDataSource returns YES.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

noteNumberOfItemsChanged

Informs the receiver that the number of items in its data source has changed.

- (void)noteNumberOfItemsChanged
Discussion

This method allows the receiver to update the scrollers in its displayed pop-up list without actually reloading data into the receiver. It is particularly useful for a data source that continually receives data in the background over a period of time, in which case the NSComboBox can remain responsive to the user while the data is received.

See the NSComboBoxDataSource informal protocol specification for information on the messages an NSComboBox sends to its data source.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

numberOfItems

Returns the total number of items in the pop-up list.

- (NSInteger)numberOfItems
Return Value

The number of items in the list.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSComboBox.h

numberOfVisibleItems

Returns the maximum number of items visible in the pop-up list.

- (NSInteger)numberOfVisibleItems
Return Value

The maximum number of items visible at any one time in the pop-up list.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

objectValueOfSelectedItem

Returns the object corresponding to the last item selected from the pop-up list.

- (id)objectValueOfSelectedItem
Return Value

The object in the receiver's internal item list corresponding to the last item selected from the pop-up list, or nil if no item is selected.

Discussion

Note that nothing is initially selected in a newly initialized combo box. This method logs a warning if usesDataSource returns YES.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSComboBox.h

objectValues

Returns as an array the receiver’s internal item list.

- (NSArray *)objectValues
Return Value

The array containing the objects in the receiver's internal item list.

Discussion

This method logs a warning if usesDataSource returns YES.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSComboBox.h

reloadData

Marks the receiver as needing redisplay, so that it will reload the data for visible pop-up items and draw the new values.

- (void)reloadData
Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

removeAllItems

Removes all items from the receiver’s internal item list.

- (void)removeAllItems
Discussion

This method logs a warning if usesDataSource returns YES.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

removeItemAtIndex:

Removes the object at the specified location from the receiver’s internal item list.

- (void)removeItemAtIndex:(NSInteger)index
Parameters
index

The index of the object to remove. All items beyond index are moved up one slot to fill the gap.

Discussion

The removed object receives a release message. This method raises an NSRangeException if index is beyond the end of the list and logs a warning if usesDataSource returns YES.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSComboBox.h

removeItemWithObjectValue:

Removes all occurrences of the given object from the receiver’s internal item list.

- (void)removeItemWithObjectValue:(id)anObject
Parameters
anObject

The object to remove from the internal item list. Objects are considered equal if they have the same id or if isEqual: returns YES.

Discussion

This method logs a warning if usesDataSource returns YES.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

scrollItemAtIndexToTop:

Scrolls the receiver’s pop-up list vertically so that the item at the specified index is as close to the top as possible.

- (void)scrollItemAtIndexToTop:(NSInteger)index
Parameters
index

The index of the item to scroll to the top.

Discussion

The pop-up list need not be displayed at the time this method is invoked.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

scrollItemAtIndexToVisible:

Scrolls the receiver’s pop-up list vertically so that the item at the specified index is visible.

- (void)scrollItemAtIndexToVisible:(NSInteger)index
Parameters
index

The index of the item to make visible.

Discussion

The pop-up list need not be displayed at the time this method is invoked.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

selectItemAtIndex:

Selects the pop-up list row at the given index.

- (void)selectItemAtIndex:(NSInteger)index
Parameters
index

The index of the item to select in the pop-up list.

Discussion

Posts an NSComboBoxSelectionDidChangeNotification to the default notification center if the selection does in fact change. Note that this method does not alter the contents of the combo box’s text field—see Setting the Combo Box’s Value for more information.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSComboBox.h

selectItemWithObjectValue:

Selects the first pop-up list item that corresponds to the given object.

- (void)selectItemWithObjectValue:(id)anObject
Parameters
anObject

The object to select in the pop-up list. Objects are considered equal if they have the same id or if isEqual: returns YES.

Discussion

This method logs a warning if usesDataSource returns YES. Posts an NSComboBoxSelectionDidChangeNotification to the default notification center if the selection does in fact change. Note that this method doesn’t alter the contents of the combo box’s text field—see Setting the Combo Box’s Value for more information.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSComboBox.h

setButtonBordered:

Determines whether the button in the combo box is displayed with a border.

- (void)setButtonBordered:(BOOL)flag
Parameters
flag

YES to display a border; NO to display the button without a border. For example, it is often useful when using a combo box in an NSTableView to display the button without the border.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSComboBox.h

setCompletes:

Sets whether the receiver tries to complete what the user types in the text field.

- (void)setCompletes:(BOOL)completes
Parameters
completes

YES to indicate that the receiver should try to complete test entered by the user. If completes is YES, every time the user adds characters to the end of the text field, the combo box calls the NSComboBoxCell method completedString:.

Discussion

If completedString: returns a string that’s longer than the existing string, the combo box replaces the existing string with the returned string and selects the additional characters. If the user is deleting characters or adds characters somewhere besides the end of the string, the combo box does not try to complete it.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

setDataSource:

Sets the receiver’s data source to aSource.

- (void)setDataSource:(id < NSComboBoxDataSource >)aSource
Parameters
aSource

The new data source for the receiver. The data source should implement the appropriate methods of the NSComboBoxDataSource informal protocol.

This method logs a warning if aSource doesn’t respond to either numberOfItemsInComboBox: or comboBox:objectValueForItemAtIndex:.

Discussion

This method doesn’t automatically set usesDataSource to NO and in fact logs a warning if usesDataSource returns NO.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

setDelegate:

Sets the receiver’s delegate.

- (void)setDelegate:(id < NSComboBoxDelegate >)anObject
Parameters
anObject

The delegate for the receiver. The delegate must conform to the NSComboBoxDelegate Protocol protocol.

Availability
  • Available in OS X v10.6 and later.
See Also
Declared In
NSComboBox.h

setHasVerticalScroller:

Determines whether the receiver displays a vertical scroller.

- (void)setHasVerticalScroller:(BOOL)flag
Parameters
flag

YES to display a vertical scroller; NO otherwise. By default, flag is YES.

Discussion

If flag is NO and the combo box has more list items (either in its internal item list or from its data source) than are allowed by numberOfVisibleItems, only a subset are displayed. The NSComboBox class' scroll... methods can be used to position this subset within the pop-up list.

Note that if flag is YES, a scroller will be displayed even if the combo box has fewer list items than are allowed by numberOfVisibleItems.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

setIntercellSpacing:

Sets the spacing between pop-up list items.

- (void)setIntercellSpacing:(NSSize)aSize
Parameters
aSize

The new width and height between pop-up list items. The default intercell spacing is (3.0, 2.0).

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

setItemHeight:

Sets the height for items.

- (void)setItemHeight:(CGFloat)itemHeight
Parameters
itemHeight

The new height for items in the pop-up list.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

setNumberOfVisibleItems:

Sets the maximum number of items that are visible in the receiver’s pop-up list.

- (void)setNumberOfVisibleItems:(NSInteger)visibleItems
Parameters
visibleItems

The maximum number of items that are visible at one time in the pop-up list.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

setUsesDataSource:

Sets whether the receiver uses an external data source to populate the receiver’s pop-up list.

- (void)setUsesDataSource:(BOOL)flag
Parameters
flag

YES if the receiver uses an external data source (specified by setDataSource:); otherwise NO.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

usesDataSource

Returns a Boolean value indicating whether the receiver uses an external data source to populate its pop-up list.

- (BOOL)usesDataSource
Return Value

YES if the receiver uses an external data source to populate the receiver’s pop-up list, NO if it uses an internal item list.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSComboBox.h

Notifications

NSComboBoxSelectionDidChangeNotification

Posted after the pop-up list selection of the NSComboBox changes.

The notification object is the NSComboBox whose selection changed. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSComboBox.h

NSComboBoxSelectionIsChangingNotification

Posted whenever the pop-up list selection of the NSComboBox is changing.

The notification object is the NSComboBox whose selection is changing. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSComboBox.h

NSComboBoxWillDismissNotification

Posted whenever the pop-up list of the NSComboBox is about to be dismissed.

The notification object is the NSComboBox whose pop-up list will be dismissed. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSComboBox.h

NSComboBoxWillPopUpNotification

Posted whenever the pop-up list of the NSComboBox is going to be displayed.

The notification object is the NSComboBox whose pop-up window will be displayed. This notification does not contain a userInfo dictionary.

Availability
Declared In
NSComboBox.h