Providing Data for a Combo Box
The NSComboBox control can be set up to populate the pop-up list either from an internal item list or from an object that you provide, called its data source. Specify which to use with setUsesDataSource:
. By default, a combo box uses the internal list.
If you specify that a combo box uses an external data source and then try to invoke a method that uses the internal list—such as addItemWithObjectValue:
—the method throws an exception.
Working With an External Data Source
An external data source declares the methods that the combo box uses to access its data. Use one if an internal list isn’t efficient for your data. An external data source can store its items in any way, but it must be able to identify them by an integer index.
To specify that combo box uses an external data source, first use setUsesDataSource:
with YES
as the argument, then use setDataSource:
with your data source object as the argument. If you use setDataSource:
before setUsesDataSource:
, setDataSource:
throws an exception.
The data source must define these methods. The method setDataSource:
logs a warning if its argument doesn’t implement them.
numberOfItemsInComboBox:
returns how many items to display.comboBox:objectValueForItemAtIndex:
returns the object that corresponds to the specified index.
The data source can optionally define these methods. The method setDataSource
doesn’t check for them and the combo box invokes them only if they’re available.
comboBox:indexOfItemWithStringValue:
returns the index for the item that matches the specified string. If this method is available, the combo box performs incremental searches when the user types into the text field with the pop-up list displayed.comboBox:completedString:
returns a string that begins with the specified string. If autocompletion is enabled, the combo box tries to complete what the user enters into the text field with an item from the pop-up list. If this method isn’t available and autocompletion is enabled, the combo box goes through each item one-by-one to find a completion.
And here are some NSComboBox methods your data source may need if it loads data in the background:
noteNumberOfItemsChanged
informs the combo box that the number of items in the data source has changed.reloadData
marks the combo box as needing redisplay, so it reloads the data for the visible pop-up items and draws the new values.
The combo box treats objects provided by its data source as values to be displayed in the combo box’s pop-up list. If these objects aren’t of common value classes—such as strings, numbers, and so on—you’ll need to create a custom NSFormatter to display them. See Data Formatting Guide for more information.
Working with an Internal List
NSComboBox provides a complete set of methods that allow you to add, insert, and delete items in the internal item list for combo boxes that don’t use a data source:
To add one or more items to the end of the list, use
addItemWithObjectValue:
oraddItemsWithObjectValues:
To insert an item into the middle of the list, use
insertItemWithObjectValue:atIndex:
To find the index for a particular object, use
indexOfItemWithObjectValue:
.To find the object at a particular index, use
itemObjectValueAtIndex:
.To remove items from the list, use
removeAllItems
,removeItemAtIndex:
, orremoveItemWithObjectValue:
.To retrieve an array of all the list’s items, use
objectValues
.To retrieve the number of items in the list, use
numberOfItems
.
If usesDataSource
returns YES
and you use any of the above methods, the method will throw an exception. By default, usesDataSource
returns NO
.
Copyright © 2002 Apple Computer, Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2002-11-12