PATH  Documentation > Mac OS X > Application Kit Reference: Java

Table of Contents

NSComboBox


Inherits from:
NSTextField : NSControl : NSView : NSResponder : NSObject
Package:
com.apple.yellow.application


Class Description


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:

[image: Art/combobox.gif]

When you click the downward-pointing arrow at the right-hand side of the text field the pop-up list appears, like this:

[image: Art/comboboxlist.gif]

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.


Providing Data for the Combo Box's 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.


Interacting with the Text Field


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.




Method Types


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


Constructors



NSComboBox

public NSComboBox()

Description forthcoming.

public NSComboBox(NSRect aRect)

Description forthcoming.

public NSComboBox(NSCoder decoder)

Creates an instance from data in decoder.


Instance Methods



addItemWithObjectValue

public void addItemWithObjectValue(Object anObject)

Adds anObject to the end of the combo box's internal item list. This method logs a warning if usesDataSource returnstrue.

addItemsWithObjectValues

public void addItemsWithObjectValues(NSArray objects)

Adds multiple objects to the end of the combo box's internal item list. This method logs a warning if usesDataSource returns true.

completes

public boolean completes()

Returns true if the combo box tries to complete what the user types in the text field. It returns false otherwise.

See Also: setCompletes



dataSource

public Object dataSource()

Returns the object that provides the data displayed in the receiver's pop-up list. This method logs a warning if usesDataSource returns false. See the class description and the NSComboBoxDataSource informal protocol specification for more information on combo box data source objects.

deselectItemAtIndex

public void deselectItemAtIndex(int index)

Deselects the pop-up list item at index if it's selected. If the selection does in fact change, this method posts a ComboBoxSelectionDidChangeNotification to the default notification center.

See Also: indexOfSelectedItem, numberOfItems, selectItemAtIndex



encodeWithCoder

public void encodeWithCoder(NSCoder encoder)

Encodes the receiver using encoder. If the receiver uses a data source, the data source is conditionally encoded as well.

hasVerticalScroller

public boolean hasVerticalScroller()

Returns true if the receiver will display a vertical scroller. 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. Returns false if the receiver won't display a vertical scroller.

See Also: numberOfItems, numberOfVisibleItems



indexOfItemWithObjectValue

public int indexOfItemWithObjectValue(Object anObject)

Searches the receiver's internal item list for anObject and returns the lowest index whose corresponding value is equal to anObject. Objects are considered equal if equals returns 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 returnstrue.

See Also: selectItemWithObjectValue



indexOfSelectedItem

public int indexOfSelectedItem()

Returns 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.

See Also: objectValueOfSelectedItem



insertItemWithObjectValueAtIndex

public void insertItemWithObjectValueAtIndex( Object anObject, int index)

Inserts anObject at index in the combo box's internal item list, shifting the previous item at index-along with all following items-down one slot to make room. This method logs a warning if usesDataSource returns true.

See Also: addItemWithObjectValue, numberOfItems



intercellSpacing

public NSSize intercellSpacing()

Returns the horizontal and vertical spacing between cells in the receiver's pop-up list. The default spacing is (3.0, 2.0).

See Also: itemHeight, numberOfVisibleItems



itemHeight

public float itemHeight()

Returns the height of each item in the receiver's pop-up list. The default item height is 16.0.

See Also: intercellSpacing, numberOfVisibleItems



itemObjectValueAtIndex

public Object itemObjectValueAtIndex(int index)

Returns the object located at index within the receiver's internal item list. If index is beyond the end of the list, a RangeException is thrown. This method logs a warning if usesDataSource returns true.

See Also: objectValueOfSelectedItem



noteNumberOfItemsChanged

public void noteNumberOfItemsChanged()

Informs the receiver that the number of items in its data source has changed, allowing the receiver to update the scrollers in its displayed pop-up list without actually reloading data into the receiver. This method 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.

See Also: reloadData



numberOfItems

public int numberOfItems()

Returns the total number of items in the pop-up list.

See Also: numberOfVisibleItems, numberOfItemsInComboBox (NSComboBoxDataSource protocol)



numberOfVisibleItems

public int numberOfVisibleItems()

Returns the maximum number of items visible at any one time in the pop-up list.

See Also: numberOfItems



objectValueOfSelectedItem

public Object objectValueOfSelectedItem()

Returns the object from the receiver's internal item list corresponding to the last item selected from the pop-up list, or null 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 true.

See Also: indexOfSelectedItem, comboBoxValueForItemAtIndex (NSComboBoxDataSource protocol)



objectValues

public NSArray objectValues()

Returns as an array the receiver's internal item list. This method logs a warning if usesDataSource returns true.

reloadData

public void reloadData()

Marks the receiver as needing redisplay, so that it will reload the data for visible pop-up items and draw the new values.

See Also: noteNumberOfItemsChanged



removeAllItems

public void removeAllItems()

Removes all items from the receiver's internal item list. This method logs a warning if usesDataSource returns true.

See Also: objectValues



removeItemAtIndex

public void removeItemAtIndex(int index)

Removes the object at index from the receiver's internal item list and moves all items beyond index up one slot to fill the gap. This method throws a RangeException if index is beyond the end of the list, and logs a warning if usesDataSource returns true.

removeItemWithObjectValue

public void removeItemWithObjectValue(Object anObject)

Removes all occurrences of anObject from the receiver's internal item list. Objects are considered equal if equals returns true. This method logs a warning if usesDataSource returns true.

See Also: indexOfItemWithObjectValue



scrollItemAtIndexToTop

public void scrollItemAtIndexToTop(int index)

Scrolls the receiver's pop-up list vertically so that the item at index is as close to the top as possible. The pop-up list need not be displayed at the time this method is invoked.

scrollItemAtIndexToVisible

public void scrollItemAtIndexToVisible(int index)

Scrolls the receiver's pop-up list vertically so that the item at index is visible. The pop-up list need not be displayed at the time this method is invoked.

selectItemAtIndex

public void scrollItemAtIndexToVisible(int index)

Selects the pop-up list row at index. Posts a ComboBoxSelectionDidChangeNotification 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 "Interacting with the Text Field" in the class description for more information.

See Also: setObjectValue (NSControl)



selectItemWithObjectValue

public void selectItemWithObjectValue(Object anObject)

Selects the first pop-up list item that corresponds to anObject. Objects are considered equal if equals returns true. This method logs a warning if usesDataSource returns true. Posts a ComboBoxSelectionDidChangeNotification 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)



setCompletes

public void setCompletes(boolean completes)

Sets whether the combo box tries to complete what the user types in the text field. By default, the combo box does not try to.

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



setDataSource

public void setDataSource(Object aSource)

Sets the receiver's data source to aSource. aSource should implement the appropriate methods of the NSComboBoxDataSource informal protocol. This method doesn't automatically set usesDataSource to false, and in fact logs a warning if usesDataSource returns false.

This method logs a warning if aSource doesn't respond to either numberOfItemsInComboBox or comboBoxValueForItemAtIndex.

See Also: setUsesDataSource



setHasVerticalScroller

public void setHasVerticalScroller(boolean flag)

Determines according to flag whether the receiver displays a vertical scroller. By default, flag is 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



setIntercellSpacing

public void setIntercellSpacing(NSSize aSize)

Sets the width and height between pop-up list items to the values in aSize. The default intercell spacing is (3.0, 2.0).

See Also: setItemHeight, setNumberOfVisibleItems



setItemHeight

public void setItemHeight(float itemHeight)

Sets the height for items to itemHeight.

See Also: setIntercellSpacing, setNumberOfVisibleItems



setNumberOfVisibleItems

public void setNumberOfVisibleItems(int visibleItems)

Sets the maximum number of items that will be visible at one time in the receiver's pop-up list to visibleItems.

See Also: numberOfItems, setItemHeight, setIntercellSpacing



setUsesDataSource

public void setUsesDataSource(boolean flag)

Sets according to flag whether the receiver uses an external data source (specified by setDataSource) to populate the receiver's pop-up list.

usesDataSource

public boolean usesDataSource()

Returns 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




Notifications


ComboBoxSelectionDidChangeNotification

Posted after the NSComboBox's pop-up list selection changes. The notification contains:


Notification Object The NSComboBox whose selection changed
Userinfo None

ComboBoxSelectionIsChangingNotification

Posted whenever the NSComboBox's pop-up list selection is changing. The notification contains:


Notification Object The NSComboBox whose selection is changing
Userinfo None

ComboBoxWillPopUpNotification

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

ComboBoxWillDismissNotification

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



Table of Contents