NSComboBoxDataSource Protocol Reference

Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.6 and later.
Companion guide
Declared in
NSComboBox.h

Overview

The NSComboBoxDataSource informal protocol declares the methods that an NSComboBox object uses to access the contents of its data source object.

For more information, see Combo Box Programming Topics.

Tasks

Populating Combo Boxes

String Completion

Instance Methods

comboBox:completedString:

Returns the first item from the pop-up list that starts with the text the user has typed.

- (NSString *)comboBox:(NSComboBox *)aComboBox completedString:(NSString *)uncompletedString
Parameters
aComboBox

The combo box.

uncompletedString

The string to match against items in the combo box's pop-up list. This is text that the user has typed.

Return Value

The first complete string from the items in the combo box's pop-up list that starts with the string in uncompletedString.

Discussion

An NSComboBox object uses this method to perform incremental—or “smart”—searches when the user types into the text field. As the user types in the text field, the receiver uses this method to search for items from the pop-up list that start with what the user has typed. The receiver adds the new text to the end of the field and selects the new text, so when the user types another character, it replaces the new text.

This method is optional. If you don’t implement it, the receiver does not perform incremental searches.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSComboBox.h

comboBox:indexOfItemWithStringValue:

Returns the index of the combo box item matching the specified string.

- (NSUInteger)comboBox:(NSComboBox *)aComboBox indexOfItemWithStringValue:(NSString *)aString
Parameters
aComboBox

The combo box.

aString

The string to match against the items in the combo box. If the datasource implementscomboBox:completedString:, this is the string returned by that method. Otherwise, it is the text that the user has typed.

Return Value

The index for the item that matches the specified string, or NSNotFound if no item matches.

Discussion

An NSComboBox object uses this method to synchronize the pop-up list’s selected item with the text field’s contents. If you don’t implement this method the receiver does not synchronize the pop-up list’s selected item with the text field’s contents.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSComboBox.h

comboBox:objectValueForItemAtIndex:

Returns the object that corresponds to the item at the specified index in the combo box.

- (id)comboBox:(NSComboBox *)aComboBox objectValueForItemAtIndex:(NSInteger)index
Parameters
aComboBox

The combo box.

index

The index of the item to return.

Return Value

The object corresponding to the specified index number.

Discussion

An NSComboBox object uses this method to populate the items displayed in its pop-up list.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSComboBox.h

numberOfItemsInComboBox:

Returns the number of items that the data source manages for the combo box.

- (NSInteger)numberOfItemsInComboBox:(NSComboBox *)aComboBox
Parameters
aComboBox

The combo box.

Return Value

The number of items that the data source object manages for the specified combo box.

Discussion

An NSComboBox object uses this method to determine how many items it should display in its pop-up list.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSComboBox.h