Inherits from: NSTextField : NSControl : NSView : NSResponder : NSObject
Package: com.apple.yellow.application
Implements: NSCoding NSCopying
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.
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
- insertItemWithObjectValueAtIndex
- 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
public NSComboBox(NSRect aRect)
public NSComboBox(NSCoder deoder)
public void addItemsWithObjectValues(
NSArray objects)
true
.public void addItemWithObjectValue(
Object anObject)
true
.public boolean completes()
true
if
the combo box tries to complete what the user types in the text field. It
returns
false
otherwise.See Also: setCompletes
public Object dataSource()
false
.
See the class description and the NSComboBoxDataSource informal
protocol specification for more information on combo box data source
objects.public void deselectItemAtIndex(
int index)
See Also: indexOfSelectedItem, numberOfItems, selectItemAtIndex
public void encodeWithCoder(
NSCoder encoder)
See Also: initWithCoder:
public boolean hasVerticalScroller()
true
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
false
if
the receiver won't display a vertical scroller.See Also: numberOfItems, numberOfVisibleItems
public int indexOfItemWithObjectValue(Object
anObject)
true
.
If none of the objects in the receiver's internal item list are
equal to anObject, indexOfItemWithObjectValue returns NSArray.NotFound.
This method logs a warning if usesDataSource returns
true
.See Also: selectItemWithObjectValue
public int indexOfSelectedItem()
See Also: objectValueOfSelectedItem
public void insertItemWithObjectValueAtIndex(
Object anObject,
int index)
true
.See Also: addItemWithObjectValue, numberOfItems
public NSSize intercellSpacing()
See Also: itemHeight, numberOfVisibleItems
public float itemHeight()
See Also: intercellSpacing, numberOfVisibleItems
public Object itemObjectValueAtIndex(
int index)
true
. See Also: objectValueOfSelectedItem
public void noteNumberOfItemsChanged()
See the NSComboBoxDataSource informal protocol specificationfor information on the messages an NSComboBox sends to its data source.
See Also: reloadData
public int numberOfItems()
See Also: numberOfVisibleItems, - numberOfItemsInComboBox: (NSComboBoxDataSource protocol)
public int numberOfVisibleItems()
See Also: numberOfItems
public Object objectValueOfSelectedItem()
true
.See Also: indexOfSelectedItem, - comboBox:objectValueForItemAtIndex: (NSComboBoxDataSource protocol), -
public NSArray objectValues()
true
.public void reloadData()
See Also: noteNumberOfItemsChanged
public void removeAllItems()
true
.See Also: objectValues
public void removeItemAtIndex(
int index)
true
.public void removeItemWithObjectValue(
Object anObject)
true
.
This method logs a warning if usesDataSource returns
true
.See Also: indexOfItemWithObjectValue
public void scrollItemAtIndexToTop(
int index)
- (void)scrollItemAtIndexToVisible:(int)index
public void scrollItemAtIndexToVisible(
int index)
See Also: setObjectValue(NSControl)
public void selectItemWithObjectValue(
Object anObject)
true
.
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)
public void setCompletes(
boolean completes)
If completes is true
,
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
public void setDataSource(
Object aSource)
false
,
and in fact logs a warning if usesDataSource returns
false
.This method logs a warning if aSource doet respond to either numberOfRowsInComboBox: or comboBox:objectValueForItemAtIndex:.
See Also: setUsesDataSource
public void setHasVerticalScroller(
boolean flag)
true
.
If flag is
false
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 true
,
a scroller will be displayed even if the combo box has fewer list
items than are allowed by numberOfVisibleItems.
See Also: numberOfItems, scrollItemAtIndexToTop, scrollItemAtIndexToVisible
public void setIntercellSpacing(
NSSize aSize)
See Also: setItemHeight, setNumberOfVisibleItems
public void setItemHeight(
float itemHeight)
See Also: setIntercellSpacing, setNumberOfVisibleItems
public void setNumberOfVisibleItems(
int visibleItems)
See Also: numberOfItems, setItemHeight, setIntercellSpacing
public void setUsesDataSource(
boolean flag)
public boolean usesDataSource()
true
if
the receiver uses an external data source to populate the receiver's
pop-up list,
false 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 |