- Inherits from:
- NSTextField : NSControl : NSView : NSResponder : NSObject
- Conforms to:
- NSCoding
- (NSResponder)
- NSObject (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)addItemWithObjectValue:(id)anObject
- (void)addItemsWithObjectValues:(id)objects
- (BOOL)completes
See Also: setCompletes:
- (id)dataSource
- (void)deselectItemAtIndex:(int)index
See Also: - indexOfSelectedItem, - numberOfItems, - selectItemAtIndex:
- (void)encodeWithCoder:(NSCoder
*)encoder
See Also: - initWithCoder:
- (BOOL)hasVerticalScroller
See Also: - numberOfItems, - numberOfVisibleItems
- (int)indexOfItemWithObjectValue:(id)anObject
NSNotFound
.
This method logs a warning if usesDataSource returnsYES.See Also: - selectItemWithObjectValue:
- (int)indexOfSelectedItem
See Also: - objectValueOfSelectedItem
- (id)initWithCoder:(NSCoder
*)decoder
See Also: - encodeWithCoder:
- (void)insertItemWithObjectValue:(id)anObject
atIndex:(int)index
See Also: - addItemWithObjectValue:, - numberOfItems
- (NSSize)intercellSpacing
See Also: - itemHeight, - numberOfVisibleItems
- (float)itemHeight
See Also: - intercellSpacing, - numberOfVisibleItems
- (id)itemObjectValueAtIndex:(int)index
See Also: - objectValueOfSelectedItem
- (void)noteNumberOfItemsChanged
See the NSComboBoxDataSource informal protocol specification for 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
See Also: - indexOfSelectedItem, - comboBox:objectValueForItemAtIndex: (NSComboBoxDataSource protocol)
- (NSArray *)objectValues
- (void)reloadData
See Also: - noteNumberOfItemsChanged
- (void)removeAllItems
See Also: - objectValues
- (void)removeItemAtIndex:(int)index
- (void)removeItemWithObjectValue:(id)anObject
See Also: - indexOfItemWithObjectValue:
- (void)scrollItemAtIndexToTop:(int)index
- (void)scrollItemAtIndexToVisible:(int)index
- (void)selectItemAtIndex:(int)index
See Also: - setObjectValue: (NSControl)
- (void)selectItemWithObjectValue:(id)anObject
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
This method logs a warning if aSource doesn't respond to either numberOfItemsInComboBox: or comboBox:objectValueForItemAtIndex:.
See Also: - setUsesDataSource:
- (void)setHasVerticalScroller:(BOOL)flag
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
See Also: - dataSource
- (void)comboBoxWillPopUp:(NSNotification
*)notification
- (void)comboBoxWillDismiss:(NSNotification
*)notification
- (void)comboBoxSelectionDidChange:(NSNotification
*)notification
- (void)comboBoxSelectionIsChanging:(NSNotification
*)notification
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 |