Inherits from | |
Conforms to | |
Framework | /System/Library/Frameworks/AppKit.framework |
Availability | Available in Mac OS X v10.0 and later. |
Companion guide | |
Declared in | NSComboBox.h |
Related sample code |
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. It normally looks like this:
When you click the downward-pointing arrow at the right side of the text field, the pop-up list appears, like this:
The NSComboBox
class uses NSComboBoxCell
to implement its user interface.
Also see the NSComboBoxDataSource
informal protocol, which declares the methods that an NSComboBox
uses to access the contents of its data source object.
– hasVerticalScroller
– intercellSpacing
– isButtonBordered
– itemHeight
– numberOfVisibleItems
– setButtonBordered:
– setHasVerticalScroller:
– setIntercellSpacing:
– setItemHeight:
– setNumberOfVisibleItems:
– addItemsWithObjectValues:
– addItemWithObjectValue:
– insertItemWithObjectValue:atIndex:
– objectValues
– removeAllItems
– removeItemAtIndex:
– removeItemWithObjectValue:
– numberOfItems
– indexOfItemWithObjectValue:
– itemObjectValueAtIndex:
– noteNumberOfItemsChanged
– reloadData
– scrollItemAtIndexToTop:
– scrollItemAtIndexToVisible:
– deselectItemAtIndex:
– indexOfSelectedItem
– objectValueOfSelectedItem
– selectItemAtIndex:
– selectItemWithObjectValue:
– comboBoxWillDismiss:
delegate method
– comboBoxWillPopUp:
delegate method
– comboBoxSelectionDidChange:
delegate method
– comboBoxSelectionIsChanging:
delegate method
Adds multiple objects to the end of the receiver’s internal item list.
- (void)addItemsWithObjectValues:(NSArray *)objects
An array of the objects to add to the internal item list.
This method logs a warning if usesDataSource
returns YES
.
NSComboBox.h
Adds an object to the end of the receiver’s internal item list.
- (void)addItemWithObjectValue:(id)anObject
The object to add to the internal item list.
This method logs a warning if usesDataSource
returns YES
.
NSComboBox.h
Returns a Boolean value indicating whether the receiver tries to complete what the user types in the text field.
- (BOOL)completes
YES
if the receiver tries to complete what the user types in the text field; otherwise NO
.
NSComboBox.h
Returns the object that provides the data displayed in the receiver’s pop-up list.
- (id)dataSource
The data source for the combo box's pop-up list.
This method logs a warning if usesDataSource
returns NO
. See the class description and the NSComboBoxDataSource
informal protocol specification for more information on combo box data source objects.
NSComboBox.h
Deselects the pop-up list item at the specified index if it’s selected.
- (void)deselectItemAtIndex:(NSInteger)index
The index of the item to deselect.
If the selection does in fact change, this method posts an NSComboBoxSelectionDidChangeNotification
to the default notification center.
NSComboBox.h
Encodes the receiver using the specified coder.
- (void)encodeWithCoder:(NSCoder *)encoder
The coder to use to encode the receiver.
If the receiver uses a data source, the data source is conditionally encoded as well.
NSComboBox.h
Returns a Boolean value indicating whether the receiver will display a vertical scroller.
- (BOOL)hasVerticalScroller
YES
if the receiver will display a vertical scroller; otherwise NO
.
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.
NSComboBox.h
Searches the receiver’s internal item list for the specified object and returns the lowest matching index.
- (NSInteger)indexOfItemWithObjectValue:(id)anObject
The object for which to return the index.
The lowest index in the internal item list whose corresponding value is equal to that of the specified object. 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 are equal to anObject, indexOfItemWithObjectValue:
returns NSNotFound
.
This method logs a warning if usesDataSource
returns YES
.
NSComboBox.h
Returns the index of the last item selected from the pop-up list.
- (NSInteger)indexOfSelectedItem
The index of the last item selected from the receiver's pop-up list or -1 if no item is selected.
Note that nothing is initially selected in a newly initialized combo box.
NSComboBox.h
Initializes a newly allocated instance from the data in the given coder.
- (id)initWithCoder:(NSCoder *)decoder
The coder object containing the data for the combo box. If the decoded instance uses a data source, initWithCoder:
decodes the data source as well.
The initialized NSComboBox
object.
NSComboBox.h
Inserts an object at the specified location in the receiver’s internal item list.
- (void)insertItemWithObjectValue:(id)anObject atIndex:(NSInteger)index
The object to add to the internal item list.
The index in the list at which to add the new object. The previous item at index—along with all following items—is shifted down one slot to make room
This method logs a warning if usesDataSource
returns YES
.
NSComboBox.h
Returns the horizontal and vertical spacing between cells in the receiver’s pop-up list.
- (NSSize)intercellSpacing
The space between cells in the pop-up list. The default spacing is (3.0, 2.0).
NSComboBox.h
Returns whether the combo box button is set to display a border.
- (BOOL)isButtonBordered
YES
if the button has a border; otherwise NO
.
NSComboBox.h
Returns the height of each item in the receiver’s pop-up list.
- (CGFloat)itemHeight
The height of items in the pop-up list. The default item height is 16.0.
NSComboBox.h
Returns the object located at the given index within the receiver’s internal item list.
- (id)itemObjectValueAtIndex:(NSInteger)index
The index of the object to retrieve. If index is beyond the end of the list, an NSRangeException
is raised.
The object located at the specified index in the internal item list.
This method logs a warning if usesDataSource
returns YES
.
NSComboBox.h
Informs the receiver that the number of items in its data source has changed.
- (void)noteNumberOfItemsChanged
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 NSComboBox
can remain responsive to the user while the data is received.
See the NSComboBoxDataSource
informal protocol specification for information on the messages an NSComboBox
sends to its data source.
NSComboBox.h
Returns the total number of items in the pop-up list.
- (NSInteger)numberOfItems
The number of items in the list.
– numberOfVisibleItems
– numberOfItemsInComboBox:
(NSComboBoxDataSource
protocol)NSComboBox.h
Returns the maximum number of items visible in the pop-up list.
- (NSInteger)numberOfVisibleItems
The maximum number of items visible at any one time in the pop-up list.
NSComboBox.h
Returns the object corresponding to the last item selected from the pop-up list.
- (id)objectValueOfSelectedItem
The object in the receiver's internal item list corresponding to the last item selected from the pop-up list, or nil
if no item is selected.
Note that nothing is initially selected in a newly initialized combo box. This method logs a warning if usesDataSource
returns YES
.
– indexOfSelectedItem
– comboBox:objectValueForItemAtIndex:
(NSComboBoxDataSource protocol)NSComboBox.h
Returns as an array the receiver’s internal item list.
- (NSArray *)objectValues
The array containing the objects in the receiver's internal item list.
This method logs a warning if usesDataSource
returns YES
.
NSComboBox.h
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
NSComboBox.h
Removes all items from the receiver’s internal item list.
- (void)removeAllItems
This method logs a warning if usesDataSource
returns YES
.
NSComboBox.h
Removes the object at the specified location from the receiver’s internal item list.
- (void)removeItemAtIndex:(NSInteger)index
The index of the object to remove. All items beyond index are moved up one slot to fill the gap.
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
.
NSComboBox.h
Removes all occurrences of the given object from the receiver’s internal item list.
- (void)removeItemWithObjectValue:(id)anObject
The object to remove from the internal item list. Objects are considered equal if they have the same id or if isEqual:
returns YES
.
This method logs a warning if usesDataSource
returns YES
.
NSComboBox.h
Scrolls the receiver’s pop-up list vertically so that the item at the specified index is as close to the top as possible.
- (void)scrollItemAtIndexToTop:(NSInteger)index
The index of the item to scroll to the top.
The pop-up list need not be displayed at the time this method is invoked.
NSComboBox.h
Scrolls the receiver’s pop-up list vertically so that the item at the specified index is visible.
- (void)scrollItemAtIndexToVisible:(NSInteger)index
The index of the item to make visible.
The pop-up list need not be displayed at the time this method is invoked.
NSComboBox.h
Selects the pop-up list row at the given index.
- (void)selectItemAtIndex:(NSInteger)index
The index of the item to select in the pop-up list.
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’s text field—see “Setting the Combo Box’s Value” for more information.
– setObjectValue:
(NSControl)NSComboBox.h
Selects the first pop-up list item that corresponds to the given object.
- (void)selectItemWithObjectValue:(id)anObject
The object to select in the pop-up list. Objects are considered equal if they have the same id or if isEqual:
returns YES
.
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’s text field—see “Setting the Combo Box’s Value” for more information.
– setObjectValue:
(NSControl)NSComboBox.h
Determines whether the button in the combo box is displayed with a border.
- (void)setButtonBordered:(BOOL)flag
YES
to display a border; NO
to display the button without a border. For example, it is often useful when using a combo box in an NSTableView
to display the button without the border.
NSComboBox.h
Sets whether the receiver tries to complete what the user types in the text field.
- (void)setCompletes:(BOOL)completes
YES
to indicate that the receiver should try to complete test entered 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:
.
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.
NSComboBox.h
Sets the receiver’s data source to aSource.
- (void)setDataSource:(id)aSource
The new data source for the receiver. The data source should implement the appropriate methods of the NSComboBoxDataSource
informal protocol.
This method logs a warning if aSource doesn’t respond to either numberOfItemsInComboBox:
or comboBox:objectValueForItemAtIndex:
.
This method doesn’t automatically set usesDataSource
to NO
and in fact logs a warning if usesDataSource
returns NO
.
NSComboBox.h
Determines whether the receiver displays a vertical scroller.
- (void)setHasVerticalScroller:(BOOL)flag
YES
to display a vertical scroller; NO
otherwise. By default, flag is 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 are displayed. The NSComboBox
class' 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
.
NSComboBox.h
Sets the spacing between pop-up list items.
- (void)setIntercellSpacing:(NSSize)aSize
The new width and height between pop-up list items. The default intercell spacing is (3.0, 2.0).
NSComboBox.h
Sets the height for items.
- (void)setItemHeight:(CGFloat)itemHeight
The new height for items in the pop-up list.
NSComboBox.h
Sets the maximum number of items that are visible in the receiver’s pop-up list.
- (void)setNumberOfVisibleItems:(NSInteger)visibleItems
The maximum number of items that are visible at one time in the pop-up list.
NSComboBox.h
Sets whether the receiver uses an external data source to populate the receiver’s pop-up list.
- (void)setUsesDataSource:(BOOL)flag
YES
if the receiver uses an external data source (specified by setDataSource:
); otherwise NO
.
NSComboBox.h
Returns a Boolean value indicating whether the receiver uses an external data source to populate its pop-up list.
- (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.
NSComboBox.h
Informs the delegate that the pop-up list selection has finished changing.
- (void)comboBoxSelectionDidChange:(NSNotification *)notification
NSComboBox.h
Informs the delegate that the pop-up list selection is changing.
- (void)comboBoxSelectionIsChanging:(NSNotification *)notification
NSComboBox.h
Informs the delegate that the pop-up list is about to be dismissed.
- (void)comboBoxWillDismiss:(NSNotification *)notification
NSComboBox.h
Informs the delegate that the pop-up list is about to be displayed.
- (void)comboBoxWillPopUp:(NSNotification *)notification
NSComboBox.h
Posted after the pop-up list selection of the NSComboBox
changes.
The notification object is the NSComboBox
whose selection changed. This notification does not contain a userInfo dictionary.
NSComboBox.h
Posted whenever the pop-up list selection of the NSComboBox
is changing.
The notification object is the NSComboBox
whose selection is changing. This notification does not contain a userInfo dictionary.
NSComboBox.h
Posted whenever the pop-up list of the NSComboBox
is about to be dismissed.
The notification object is the NSComboBox
whose pop-up list will be dismissed. This notification does not contain a userInfo dictionary.
NSComboBox.h
Posted whenever the pop-up list of the NSComboBox
is going to be displayed.
The notification object is the NSComboBox
whose pop-up window will be displayed. This notification does not contain a userInfo dictionary.
NSComboBox.h
© 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-05-23)