Inherits from: NSTextField : NSControl : NSView : NSResponder : NSObject
Conforms to: NSObject
(NSObject)
NSCoding (NSObject)
NSCopying (NSObject)
Declared in: AppKit/NSComboBox.h
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. Use this control whenever you want the user to enter information that can be selected from a finite list of options. Note that while you can construct your NSComboBox so that users are restricted to only selecting items from the combo box's pop-up list, this isn't the combo box's normal behavior: a user can either select an item from the list, or enter text that may or may not be contained in the pop-up list.
While the pop-up list is visible, typing into the text field causes an incremental search to be performed on the list. If there's a match, the selection in the pop-up list changes to reflect the match.
The NSComboBox normally looks like this:
When you click the downward-pointing arrow at the right-hand side of the text field the pop-up list appears, like this:
If there isn't sufficient room for the pop-up list to be displayed below the text field, it's instead displayed above the text field. Selecting an item from the list, clicking anywhere outside the control, or activating another window dismisses the pop-up list.
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. If you use a data source, your data source object can store items in any way, but it must be able to identify them by an integer index. See the NSComboBoxDataSource informal protocol specification for more information on constructing an NSComboBox data source.
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.
Use setUsesDataSource: to specify whether a given combo box uses a data source or maintains an internal list of items. A combo box can only use one or the other; for instance, if you construct combo box that uses a data source and then attempt to execute an item-oriented method-such as addItemWithObjectValue:-a warning will be logged and the method will have no effect.
Because NSComboBox is a type of NSControl, you typically use the methods provided by the NSControl class-such as stringValue, floatValue, or intValue-when working with the contents of the combo box's text field; see the NSControl class specification for more information on these methods. NSControl's set...Value: methods are also useful, primarily when initializing a combo box. For instance, the following excerpt shows how to "pre-select" the third item in the list of a combo box that maintains an internal item list:
[myComboBox selectItemAtIndex:2]; // List items start at index 0 [myComboBox setObjectValue:[myComboBox objectValueOfSelectedItem]];
To do the same thing for a combo box that relies upon a data source, use:
[myComboBox selectItemAtIndex:2]; [myComboBox setObjectValue:[myComboBoxDataSource comboBox:myComboBox objectValueForItemAtIndex:[myComboBox indexOfSelectedItem]]];
Note that NSComboBox is a also a subclass of NSTextField, and thus inherits all of NSTextField's methods. NSComboBox relies heavily upon its cell class, NSComboBoxCell. NSComboBoxCell is a NSTextFieldCell subclass, which combines a text field cell with a button cell.
- Setting display attributes
- - hasVerticalScroller
- - intercellSpacing
- - itemHeight
- - numberOfVisibleItems
- - 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
- - completes
- - setCompletes:
- (void)addItemsWithObjectValues:(id)objects
YES
.- (void)addItemWithObjectValue:(id)anObject
YES
.- (BOOL)completes
YES
if
the combo box tries to complete what the user types in the text field. It
returns NO
otherwise.See Also: setCompletes:
- (id)dataSource
NO
.
See the class description and the NSComboBoxDataSource informal
protocol specification for more information on combo box data source
objects.- (void)deselectItemAtIndex:
(int)index
See Also: - indexOfSelectedItem, - numberOfItems, - selectItemAtIndex:
- (void)encodeWithCoder:(NSCoder
*)encoder
See Also: - initWithCoder:
- (BOOL)hasVerticalScroller
YES
if
the receiver will display a vertical scroller. Note
that the scoller will be displayed even if the pop-up list contains
fewer items than will fit in the area specified for display. Returns NO
if
the receiver won't display a vertical scroller.See Also: - numberOfItems, - numberOfVisibleItems
- (int)indexOfItemWithObjectValue:(id)anObject
YES
.
If none of the objects in the receiver's internal item list are
equal to anObject, indexOfItemWithObjectValue: returns NSNotFound.
This method logs a warning if usesDataSource returns YES
.See Also: - selectItemWithObjectValue:
- (int)indexOfSelectedItem
See Also: - objectValueOfSelectedItem
- (id)initWithCoder:(NSCoder
*)decoder
See Also: - encodeWithCoder:
- (void)insertItemWithObjectValue:
(id)anObject
atIndex:(int)
index
YES
.See Also: - addItemWithObjectValue:, - numberOfItems
- (NSSize)intercellSpacing
See Also: - itemHeight, - numberOfVisibleItems
- (float)itemHeight
See Also: - intercellSpacing, - numberOfVisibleItems
- (id)itemObjectValueAtIndex:(int)index
YES
. See Also: - objectValueOfSelectedItem
- (void)noteNumberOfItemsChanged
See the NSComboBoxDataSource informal protocol specificationfor information on the messages an NSComboBox sends to its data source.
See Also: - reloadData
- (int)numberOfItems
See Also: - numberOfVisibleItems, - numberOfItemsInComboBox: (NSComboBoxDataSource protocol)
- (int)numberOfVisibleItems
See Also: - numberOfItems
- (id)objectValueOfSelectedItem
YES
.See Also: - indexOfSelectedItem, - comboBox:objectValueForItemAtIndex: (NSComboBoxDataSource protocol), -
- (NSArray *)objectValues
YES
.- (void)reloadData
See Also: - noteNumberOfItemsChanged
- (void)removeAllItems
YES
.See Also: - objectValues
- (void)removeItemAtIndex:(int)index
YES
.- (void)removeItemWithObjectValue:(id)anObject
YES
.
This method logs a warning if usesDataSource returns YES
.See Also: - indexOfItemWithObjectValue:
- (void)scrollItemAtIndexToTop:(int)index
- (void)scrollItemAtIndexToVisible:(int)index
- (void)selectItemAtIndex:(int)index
See Also: - setObjectValue:(NSControl)
- (void)selectItemWithObjectValue:(id)anObject
YES
.
Posts 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 "Interacting
with the Text Field" in the class description for more information.See Also: - setObjectValue:(NSControl)
- (void)setCompletes:(BOOL)completes
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:.
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.
See Also: completes
- (void)setDataSource:(id)aSource
NO
,
and in fact logs a warning if usesDataSource returns NO
.This method logs a warning if aSource doet respond to either numberOfRowsInComboBox: or comboBox:objectValueForItemAtIndex:.
See Also: - setUsesDataSource:
- (void)setHasVerticalScroller:(BOOL)flag
YES
.
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
will be displayed. NSComboBox'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 has fewer list
items than are allowed by numberOfVisibleItems.
See Also: - numberOfItems, - scrollItemAtIndexToTop:, - scrollItemAtIndexToVisible:
- (void)setIntercellSpacing:(NSSize)aSize
See Also: - setItemHeight:, - setNumberOfVisibleItems:
- (void)setItemHeight:(float)itemHeight
See Also: - setIntercellSpacing:, - setNumberOfVisibleItems:
- (void)setNumberOfVisibleItems:(int)visibleItems
See Also: - numberOfItems, - setItemHeight:, - setIntercellSpacing:
- (void)setUsesDataSource:(BOOL)flag
- (BOOL)usesDataSource
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.See Also: - dataSource
Posted after the NSComboBox's pop-up list selection changes. The notification contains:
Notification Object | The NSComboBox whose selection changed. |
Userinfo | None |
Posted whenever the NSComboBox's pop-up list selection is changing. The notification contains:
Notification Object | The NSComboBox whose selection is changing. |
Userinfo | None |
Posted whenever the NSComboBox's pop-up list is going to be displayed. The notification contains:
Notification Object | The NSComboBox whose popup window will be displayed. |
Userinfo | None |
Posted whenever the NSComboBox's pop-up list is about to be dismissed. The notification contains:
Notification Object | The NSComboBox whose pop-up list will be dismissed. |
Userinfo | None |