---

NSComboBoxCell Class Reference

Overview

NSComboBoxCell is a subclass of NSTextFieldCell used to implement the user interface of “combo boxes” (see NSComboBox for information on how combo boxes look and work). The NSComboBox subclass of NSTextField uses a single NSComboBoxCell, and essentially all of the NSComboBox class’ methods simply invoke the corresponding NSComboBoxCell method.

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

Tasks

Initializing a Combo Box Cell

• – initWithCoder:
• – encodeWithCoder:

Setting Display Attributes

• – hasVerticalScroller
• – isButtonBordered
• – intercellSpacing
• – itemHeight
• – numberOfVisibleItems
• – setButtonBordered:
• – setHasVerticalScroller:
• – setIntercellSpacing:
• – setItemHeight:
• – setNumberOfVisibleItems:

Setting a Data Source

• – dataSource
• – setDataSource:
• – setUsesDataSource:
• – usesDataSource

Working with an Internal List

• – addItemsWithObjectValues:
• – addItemWithObjectValue:
• – insertItemWithObjectValue:atIndex:
• – objectValues
• – removeAllItems
• – removeItemAtIndex:
• – removeItemWithObjectValue:
• – numberOfItems

Manipulating the Displayed List

• – indexOfItemWithObjectValue:
• – itemObjectValueAtIndex:
• – noteNumberOfItemsChanged
• – reloadData
• – scrollItemAtIndexToTop:
• – scrollItemAtIndexToVisible:

Manipulating the Selection

• – deselectItemAtIndex:
• – indexOfSelectedItem
• – objectValueOfSelectedItem
• – selectItemAtIndex:
• – selectItemWithObjectValue:

Completing the Text Field

• – completedString:
• – completes
• – setCompletes:

Instance Methods

addItemsWithObjectValues:

Adds multiple objects to the internal item list.

- (void)addItemsWithObjectValues:(NSArray *)objects

Parameters

objects

The object to add to the end of the receiver’s internal item list.

Discussion

This method logs a warning if usesDataSource returns YES.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSComboBoxCell.h

addItemWithObjectValue:

Adds the specified object to the internal item list.

- (void)addItemWithObjectValue:(id)anObject

Parameters

anObject

The object to add to the end of the receiver's internal item list.

Discussion

This method logs a warning if usesDataSource returns YES.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSComboBoxCell.h

completedString:

Returns a string from the receiver’s pop-up list that starts with the given substring.

- (NSString *)completedString:(NSString *)substring

Parameters

substring

The substring to search for. This is what the user entered in the combo box’s text field.

Return Value

The string from the receiver's pop-up list that starts with the specified substring or nil if there is no such string.

Discussion

The default implementation of this method first checks whether the combo box uses a data source and whether the data source responds to comboBox:completedString: or comboBoxCell:completedString:. If so, the combo box cell returns that method’s return value. Otherwise, this method goes through the combo box’s items one by one and returns an item that starts with substring.

Override this method only if your subclass completes strings differently. The overriding method does not need to call the superclass’s method. Generally, you do not need to call this method directly.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSComboBoxCell.h

completes

Returns a Boolean value indicating whether the receiver tries to complete text entered by the user.

- (BOOL)completes

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setCompletes:

Declared In

NSComboBoxCell.h

dataSource

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

- (id)dataSource

Return Value

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

Discussion

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSComboBoxCell.h

deselectItemAtIndex:

Deselects the pop-up list item at the given 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 Mac OS X v10.0 and later.

See Also

• – indexOfSelectedItem
• – numberOfItems
• – selectItemAtIndex:

Declared In

NSComboBoxCell.h

encodeWithCoder:

Encodes the receiver using the specified coder.

- (void)encodeWithCoder:(NSCoder *)encoder

Parameters

encoder

The coder to use when encoding the receiver. If the receiver uses a data source, the data source is conditionally encoded as well.

Availability

• Available in Mac OS X v10.0 through Mac OS X v10.2.

See Also

• – initWithCoder:

Declared In

NSComboBoxCell.h

hasVerticalScroller

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

- (BOOL)hasVerticalScroller

Return Value

YES if the receiver displays 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 Mac OS X v10.0 and later.

See Also

• – numberOfItems
• – numberOfVisibleItems

Declared In

NSComboBoxCell.h

indexOfItemWithObjectValue:

Searches the receiver’s internal item list for the given object and returns the matching index number.

- (NSInteger)indexOfItemWithObjectValue:(id)anObject

Parameters

anObject

The object for which to return the index.

Return Value

The lowest index whose corresponding value is equal to anObject. 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 is equal to anObject, indexOfItemWithObjectValue: returns NSNotFound.

Discussion

This method logs a warning if usesDataSource returns YES.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – selectItemWithObjectValue:

Declared In

NSComboBoxCell.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 cell.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – objectValueOfSelectedItem

Declared In

NSComboBoxCell.h

initWithCoder:

Initializes a newly allocated instance from data in the specified coder.

- (id)initWithCoder:(NSCoder *)decoder

Parameters

decoder

The coder from which to draw the data to initialize the combo box cell.

Return Value

The initialized NSComboBoxCell object.

Discussion

If the decoded instance uses a data source, initWithCoder: decodes the data source as well.

Availability

• Available in Mac OS X v10.0 through Mac OS X v10.2.

See Also

• – encodeWithCoder:

Declared In

NSComboBoxCell.h

insertItemWithObjectValue:atIndex:

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

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

Parameters

anObject

The object to add to the receiver's internal item list.

index

The index at which to add the specified 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 Mac OS X v10.0 and later.

See Also

• – addItemWithObjectValue:
• – numberOfItems

Declared In

NSComboBoxCell.h

intercellSpacing

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

- (NSSize)intercellSpacing

Return Value

The horizontal and vertical spacing between cells in the receiver’s pop-up list. The default spacing is (3.0, 2.0).

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – itemHeight
• – numberOfVisibleItems

Declared In

NSComboBoxCell.h

isButtonBordered

Returns a Boolean value indicating 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 Mac OS X v10.3 and later.

See Also

• – setButtonBordered:

Declared In

NSComboBoxCell.h

itemHeight

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

- (CGFloat)itemHeight

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – intercellSpacing
• – numberOfVisibleItems

Declared In

NSComboBoxCell.h

itemObjectValueAtIndex:

Returns the object located at the specified location in the internal item list.

- (id)itemObjectValueAtIndex:(NSInteger)index

Parameters

index

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

Return Value

The object at the given location in the receiver's internal item list.

Discussion

This method logs a warning if usesDataSource returns YES.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – objectValueOfSelectedItem

Declared In

NSComboBoxCell.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 NSComboBoxCell can remain responsive to the user while the data is received.

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – reloadData

Declared In

NSComboBoxCell.h

numberOfItems

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

- (NSInteger)numberOfItems

Return Value

The number of items in the pop-up list.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – numberOfVisibleItems
• – numberOfItemsInComboBoxCell: (NSComboBoxCellDataSource protocol)

Declared In

NSComboBoxCell.h

numberOfVisibleItems

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

- (NSInteger)numberOfVisibleItems

Return Value

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – numberOfItems

Declared In

NSComboBoxCell.h

objectValueOfSelectedItem

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

- (id)objectValueOfSelectedItem

Return Value

The object from 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 cell. This method logs a warning if usesDataSource returns YES.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – indexOfSelectedItem
• – comboBoxCell:objectValueForItemAtIndex: (NSComboBoxCellDataSource protocol)

Declared In

NSComboBoxCell.h

objectValues

Returns the receiver’s internal item list.

- (NSArray *)objectValues

Return Value

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

Discussion

This method logs a warning if usesDataSource returns YES.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSComboBoxCell.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 Mac OS X v10.0 and later.

See Also

• – noteNumberOfItemsChanged

Declared In

NSComboBoxCell.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 Mac OS X v10.0 and later.

See Also

• – objectValues

Declared In

NSComboBoxCell.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 from the receiver's internal item list. 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 Mac OS X v10.0 and later.

Declared In

NSComboBoxCell.h

removeItemWithObjectValue:

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

- (void)removeItemWithObjectValue:(id)anObject

Parameters

anObject

The object to remove from the receiver's 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 Mac OS X v10.0 and later.

See Also

• – indexOfItemWithObjectValue:

Declared In

NSComboBoxCell.h

scrollItemAtIndexToTop:

Scrolls the receiver’s pop-up list vertically so that the item at the given 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 Mac OS X v10.0 and later.

Declared In

NSComboBoxCell.h

scrollItemAtIndexToVisible:

Scrolls the receiver’s pop-up list vertically so that the item at the given 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 Mac OS X v10.0 and later.

Declared In

NSComboBoxCell.h

selectItemAtIndex:

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

- (void)selectItemAtIndex:(NSInteger)index

Parameters

index

The index of the row to select.

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 cell’s text field—see “Setting the Combo Box’s Value” for more information.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setObjectValue: (NSControl)

Declared In

NSComboBoxCell.h

selectItemWithObjectValue:

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

- (void)selectItemWithObjectValue:(id)anObject

Parameters

anObject

The object for which to select the corresponding pop-up list item. 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 cell’s text field—see “Setting the Combo Box’s Value” for more information.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setObjectValue: (NSControl)

Declared In

NSComboBoxCell.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. For example, it is often useful when using a combo box in an NSTableView to display the button without the border.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – isButtonBordered

Declared In

NSComboBoxCell.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 text typed 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 Mac OS X v10.0 and later.

See Also

• – completes

Declared In

NSComboBoxCell.h

setDataSource:

Sets the receiver’s data source.

- (void)setDataSource:(id)aSource

Parameters

aSource

The data source for the receiver. aSource should implement the appropriate methods of the NSComboBoxCellDataSource informal protocol.

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

Discussion

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setUsesDataSource:

Declared In

NSComboBoxCell.h

setHasVerticalScroller:

Determines whether the receiver displays a vertical scroller.

- (void)setHasVerticalScroller:(BOOL)flag

Parameters

flag

YES to have the receiver display a vertical scroller. By default, flag is YES.

Discussion

If flag is NO and the combo box cell has more list items (either in its internal item list or from its data source) than are allowed by numberOfVisibleItems, only a subset will be displayed. NSComboBoxCell’s 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 cell has fewer list items than are allowed by numberOfVisibleItems.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – numberOfItems
• – scrollItemAtIndexToTop:
• – scrollItemAtIndexToVisible:

Declared In

NSComboBoxCell.h

setIntercellSpacing:

Sets the spacing between pop-up list items.

- (void)setIntercellSpacing:(NSSize)aSize

Parameters

aSize

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setItemHeight:
• – setNumberOfVisibleItems:

Declared In

NSComboBoxCell.h

setItemHeight:

Sets the height for items.

- (void)setItemHeight:(CGFloat)itemHeight

Parameters

itemHeight

The height of pop-up list items.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setIntercellSpacing:
• – setNumberOfVisibleItems:

Declared In

NSComboBoxCell.h

setNumberOfVisibleItems:

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

- (void)setNumberOfVisibleItems:(NSInteger)visibleItems

Parameters

visibleItems

The maximum number of items that should be visible at one time in the receiver's pop-up list.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – numberOfItems
• – numberOfVisibleItems
• – setIntercellSpacing:
• – setItemHeight:

Declared In

NSComboBoxCell.h

setUsesDataSource:

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

- (void)setUsesDataSource:(BOOL)flag

Parameters

flag

YES to indicate that the receiver uses an external data source (specified by setDataSource:) to populate the receiver’s pop-up list.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSComboBoxCell.h

usesDataSource

Returns a Boolean value indicating whether the receiver uses an external data source.

- (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 Mac OS X v10.0 and later.

See Also

• – dataSource

Declared In

NSComboBoxCell.h

---