- Inherits from:
- NSTextField : NSControl : NSView : NSResponder : NSObject
- Package:
- com.apple.yellow.application
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.
- Constructors
- NSComboBox
- 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()
public NSComboBox(NSRect aRect)
public NSComboBox(NSCoder decoder)
public void addItemWithObjectValue(Object anObject)
public void addItemsWithObjectValues(NSArray objects)
public boolean completes()
See Also: setCompletes
public Object dataSource()
public void deselectItemAtIndex(int index)
See Also: indexOfSelectedItem, numberOfItems, selectItemAtIndex
public void encodeWithCoder(NSCoder encoder)
public boolean hasVerticalScroller()
See Also: numberOfItems, numberOfVisibleItems
public int indexOfItemWithObjectValue(Object anObject)
NSArray.NotFound
.
This method logs a warning if usesDataSource returnstrue.See Also: selectItemWithObjectValue
public int indexOfSelectedItem()
See Also: objectValueOfSelectedItem
public void insertItemWithObjectValueAtIndex(
Object anObject,
int index)
See Also: addItemWithObjectValue, numberOfItems
public NSSize intercellSpacing()
See Also: itemHeight, numberOfVisibleItems
public float itemHeight()
See Also: intercellSpacing, numberOfVisibleItems
public Object itemObjectValueAtIndex(int index)
See Also: objectValueOfSelectedItem
public void noteNumberOfItemsChanged()
See the NSComboBoxDataSource informal protocol specification for 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()
See Also: indexOfSelectedItem, comboBoxValueForItemAtIndex (NSComboBoxDataSource protocol)
public NSArray objectValues()
public void reloadData()
See Also: noteNumberOfItemsChanged
public void removeAllItems()
See Also: objectValues
public void removeItemAtIndex(int index)
public void removeItemWithObjectValue(Object anObject)
See Also: indexOfItemWithObjectValue
public void scrollItemAtIndexToTop(int index)
public void scrollItemAtIndexToVisible(int index)
public void scrollItemAtIndexToVisible(int index)
See Also: setObjectValue (NSControl)
public void selectItemWithObjectValue(Object anObject)
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)
This method logs a warning if aSource doesn't respond to either numberOfItemsInComboBox or comboBoxValueForItemAtIndex.
See Also: setUsesDataSource
public void setHasVerticalScroller(boolean flag)
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()
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 |