[Previous] [Class List] [Next]

NSComboBoxCell


Inherits from: NSTextFieldCell : NSActionCell : NSCell : NSObject
Conforms to: NSObject
(from NSObject)
NSCoding (from NSCell)
NSCopying (from 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



addItemsWithObjectValues:

- (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 returns YES.

addItemWithObjectValue:

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

completedString:

- (NSString *)completedString:(NSString *)substring

Returns a string from the combo box's pop-up list that starts with the substring, or nilif 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.



completes

- (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:



dataSource

- (id)dataSource

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

deselectItemAtIndex:

- (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:



encodeWithCoder:

- (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:



hasVerticalScroller

- (BOOL)hasVerticalScroller

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

See Also: - numberOfItems, - numberOfVisibleItems



indexOfItemWithObjectValue:

- (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:



indexOfSelectedItem

- (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



initWithCoder:

- (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:



insertItemWithObjectValue:atIndex:

- (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



intercellSpacing

- (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

- (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:

- (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 returns YES.

See Also: - objectValueOfSelectedItem



noteNumberOfItemsChanged

- (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



numberOfItems

- (int)numberOfItems

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

See Also: - numberOfVisibleItems, - numberOfItemsInComboBoxCell: (NSComboBoxCellDataSource protocol), -



numberOfVisibleItems

- (int)numberOfVisibleItems

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

See Also: - numberOfItems



objectValueOfSelectedItem

- (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)



objectValues

- (NSArray *)objectValues

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

reloadData

- (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

- (void)removeAllItems

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

See Also: - objectValues



removeItemAtIndex:

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

removeItemWithObjectValue:

- (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:



scrollItemAtIndexToTop:

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

scrollItemAtIndexToVisible:

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

selectItemAtIndex:

- (void)selectItemAtIndex:(int)index

Selects the pop-up list row at index. Posts 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 the class description for more information.

See Also: - setObjectValue:(NSControl)



selectItemWithObjectValue:

- (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. 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 cell's text field-see "Interacting with the Text Field" in the class description for more information.

See Also: - setObjectValue:(NSControl)



setCompletes:

- (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 somwhere besides the end of the string, the combo box does not try to complete it.

See Also: completes



setDataSource:

- (void)setDataSource:(id)aSource

Sets the receiver's data source to aSource. aSource should implement the appropriate methods of the 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 numberOfRowsInComboBoxCell: or comboBoxCell:objectValueForItemAtIndex:.

See Also: - setUsesDataSource:



setHasVerticalScroller:

- (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:



setIntercellSpacing:

- (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:

- (void)setItemHeight:(float)itemHeight

Sets the height for items to itemHeight.

See Also: - setIntercellSpacing:, - setNumberOfVisibleItems:



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:



setUsesDataSource:

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

usesDataSource

- (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




[Previous] [Next]