
PATH
Mac OS X Documentation >
Application Kit Reference: Objective-C
- Inherits
from:
- NSTextFieldCell : NSActionCell : NSCell : NSObject
- Conforms to:
- NSObject
- (NSObject)
- NSCoding (NSCell)
- NSCopying (NSCell)
Declared in: - AppKit/NSComboBoxCell.h
Class Description
NSComboBoxCell is a subclass of NSTextFieldCell used to implement
the user interface of "combo boxes" (see the Class Description
in the NSComboBox class specification for information on how combo
boxes look and work). The NSComboBox subclass of NSTextField uses
a single NSComboBoxCell, and essentially all of NSComboBox's methods
simply invoke the corresponding NSComboBoxCell method.
Method Types
- 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
- - completedString:
- - completes
- - setCompletes:
Instance Methods
- (void)addItemWithObjectValue:(id)anObject
Adds anObject to
the end of the combo box cell's internal item list. This
method logs a warning if usesDataSource returns YES.
- (void)addItemsWithObjectValues:(id)objects
Adds multiple objects to the end of the combo
box cell's internal item list. This method logs a warning if usesDataSource returnsYES.
- (NSString *)completedString:(NSString
*)substring
Returns a string from the combo
box's pop-up list that starts with the substring,
or nil if there is no such string. The argument substring is
what the user entered in the combo box's text field. The default
implementation of this method first checks whether the combo box
uses a data source and whether the data source responds to comboBox:completedString: or comboBoxCell:completedString:. If
so, the combo box cell returns that method's return value. Otherwise,
this method goes through the combo box's items one-by-one and
returns an item which starts with substring. Override
this method only if your subclass completes strings differently.
The overriding method does not need to call the superclass's method.
Generally, you do not need to call this method directly.
- (BOOL)completes
Returns YES if the combo box
tries to complete what the user types in the text field. It
returns NO otherwise.See Also: - setCompletes:
- (id)dataSource
Returns the object that provides
the data displayed in the receiver's pop-up list. This
method logs a warning if usesDataSource returnsNO.
See the class description and the NSComboBoxCellDataSource informal
protocol specification for more information on combo box cell data
source objects.
- (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 an NSComboBoxSelectionDidChangeNotification
to the default notification center.See Also: - indexOfSelectedItem, - numberOfItems, - selectItemAtIndex:
- (void)encodeWithCoder:(NSCoder
*)encoder
Encodes the receiver using encoder. If
the receiver uses a data source, the data source is conditionally
encoded as well.See Also: - initWithCoder:
- (BOOL)hasVerticalScroller
Returns YES 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 NO if
the receiver won't display a vertical scroller.See
Also: - numberOfItems, - numberOfVisibleItems
- (int)indexOfItemWithObjectValue:(id)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 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.See
Also: - selectItemWithObjectValue:
- (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 cell.See
Also: - objectValueOfSelectedItem
- (id)initWithCoder:(NSCoder
*)decoder
Initializes a newly-allocated
instance from data in decoder. If
the decoded instance uses a data source, initWithCoder: decodes
the data source as well. Returns self.See
Also: - encodeWithCoder:
- (void)insertItemWithObjectValue:(id)anObject
atIndex:(int)index
Inserts anObject at
index in the combo box cell'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 YES.See
Also: - addItemWithObjectValue:, - numberOfItems
- (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
- (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
- (id)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, an NSRangeException is raised. This
method logs a warning if usesDataSource returnsYES.See
Also: - objectValueOfSelectedItem
- (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
NSComboBoxCell can remain responsive to the user while the data
is received.See the NSComboBoxCellDataSource informal
protocol specification for information on the messages an NSComboBoxCell
sends to its data source.
See Also: - reloadData
- (int)numberOfItems
Returns the total number of
items in the pop-up list.See
Also: - numberOfVisibleItems, - numberOfItemsInComboBoxCell: (NSComboBoxCellDataSource protocol)
- (int)numberOfVisibleItems
Returns the maximum number
of items visible at any one time in the pop-up list.See
Also: - numberOfItems
- (id)objectValueOfSelectedItem
Returns the object from 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 cell. This method logs a warning if usesDataSource returns YES.See
Also: - indexOfSelectedItem, - comboBoxCell:objectValueForItemAtIndex: (NSComboBoxCellDataSource
protocol)
- (NSArray *)objectValues
Returns as an array the receiver's
internal item list. This method logs a warning
if usesDataSource returns YES.
- (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
- (void)removeAllItems
Removes all items from the
receiver's internal item list. This method logs
a warning if usesDataSource returns YES.See
Also: - objectValues
- (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. 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.
- (void)removeItemWithObjectValue:(id)anObject
Removes all occurrences of anObject from
the receiver's 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.See
Also: - indexOfItemWithObjectValue:
- (void)scrollItemAtIndexToTop:(int)index
Scrolls the receiver's pop-up
list vertically so that the item specified by index is
as close to the top as possible. The pop-up list
need not be displayed at the time this method is invoked.
- (void)scrollItemAtIndexToVisible:(int)index
Scrolls the receiver's pop-up
list vertically so that the item specified by index is
visible. The pop-up list need not be displayed
at the time this method is invoked.
- (void)selectItemAtIndex:(int)index
Selects the pop-up list row
at index. Posts
a 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 cell's text field-see "Interacting with the Text Field" in
NSComboBox's class description for more information.See
Also: - setObjectValue: (NSControl)
- (void)selectItemWithObjectValue:(id)anObject
Selects the first pop-up list
item that corresponds to anObject. 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 a 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 cell's text
field-see "Interacting with the Text Field" in
NSComboBox's class description for more information.See
Also: - setObjectValue: (NSControl)
- (void)setCompletes:(BOOL)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 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
Sets the receiver's data
source to aSource. aSource should
implement the appropriate methods of the NSComboBoxCellDataSource NSComboBoxCellDataSource informal protocol.
This method doesn't automatically set usesDataSource to NO, and in fact
logs a warning if usesDataSource returns NO.This
method logs a warning if aSource doesn't
respond to either numberOfItemsInComboBoxCell: or comboBoxCell:objectValueForItemAtIndex:.
See
Also: - setUsesDataSource:
- (void)setHasVerticalScroller:(BOOL)flag
Determines according to flag whether
the receiver displays a vertical scroller. By
default, flag is YES. If flag is NO and
the combo box cell 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. NSComboBoxCell's 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 cell has fewer list items than are
allowed by numberOfVisibleItems.
See
Also: - numberOfItems, - scrollItemAtIndexToTop:, - scrollItemAtIndexToVisible:
- (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:
- (void)setItemHeight:(float)itemHeight
Sets the height for items to itemHeight.See
Also: - setIntercellSpacing:, - setNumberOfVisibleItems:
- (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, - numberOfVisibleItems, - setIntercellSpacing:, - setItemHeight:
- (void)setUsesDataSource:(BOOL)flag
Sets according to flag whether
the receiver uses an external data source (specified by setDataSource:)
to populate the receiver's pop-up list.
- (BOOL)usesDataSource
Returns 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.See
Also: - dataSource