Up

# NSComboBoxCell

### Authors

Gerrit van Dyk (`gerritvd@decillion.net`)
Quentin Mathe (`qmathe@club-internet.fr`)

Copyright: (C) 1999 Free Software Foundation, Inc.

### Contents -

1. Class
2. Software documentation for the NSObject(NSComboBoxCellDataSource) informal protocol

# Class Description

An NSComboBoxCell is what we can call a completion/choices box cell, derived from NSTextFieldCell, it allows you to enter text like in a text field but also to click in the ellipsis button (indicating the fact other user inputs are possible) on the right of it to obtain a list of choices, you can use them as the text field value by selecting a row in this list. You can also obtain direct completion when it is enabled via `setCompletes:` to get a suggested text field value updated as you type.

Like other NSCell classes, NSComboBoxCell has a matching NSControl named NSComboBox which is relying on it to implement the combo box behavior in a standalone control.

## NSComboBoxCell : NSTextFieldCell

> Declared in:
>   AppKit/NSComboBoxCell.h

Availability: OpenStep

No special instructions to use NSComboBoxCell or text to detail the implementation.

Instance Variables
Method summary

- -addItemWithObjectValue:
- -addItemsWithObjectValues:
- -completedString:
- -completes
- -dataSource
- -deselectItemAtIndex:
- -hasVerticalScroller
- -indexOfItemWithObjectValue:
- -indexOfSelectedItem
- -insertItemWithObjectValue:atIndex:
- -intercellSpacing
- -isButtonBordered
- -itemHeight
- -itemObjectValueAtIndex:
- -noteNumberOfItemsChanged
- -numberOfItems
- -numberOfVisibleItems
- -objectValueOfSelectedItem
- -objectValues
- -reloadData
- -removeAllItems
- -removeItemAtIndex:
- -removeItemWithObjectValue:
- -scrollItemAtIndexToTop:
- -scrollItemAtIndexToVisible:
- -selectItemAtIndex:
- -selectItemWithObjectValue:
- -setButtonBordered:
- -setCompletes:
- -setDataSource:
- -setHasVerticalScroller:
- -setIntercellSpacing:
- -setItemHeight:
- -setNumberOfVisibleItems:
- -setUsesDataSource:
- -trackMouse:inRect:ofView:untilMouseUp:
- -usesDataSource

### addItemWithObjectValue:

- (void) addItemWithObjectValue: (id)object;
Availability: OpenStep
Adds an item to the combo box cell default items list which is used when `usesDataSource` returns `NO`. In the case `usesDataSource` returns `YES` , this method logs a warning.

### addItemsWithObjectValues:

- (void) addItemsWithObjectValues: (NSArray*)objects;
Availability: OpenStep
Adds several items in an array to the combo box cell default items list which is used when `usesDataSource` returns `NO`. In the case `usesDataSource` returns `YES`, this method logs a warning.

### completedString:

- (NSString*) completedString: (NSString*)substring;
Availability: MacOS-X 10.0.0
Returns a string by looking in the combo box cell list for an item wich starts with substring , or `nil` when there is no such string. substring is equal to what the user entered in the text field part. You rarely needs to call this method explicitly in your code. By default, the implementation of this method first checks whether the combo box cell uses a data source and whether the data source responds to `comboBox:completedString:` or `comboBoxCell:completedString:`. When it is the case, it uses this method to return str, else this method goes through the combo box cell items one by one and returns the first item found starting with substring. In the case, you want another behavior, you can override this method without need to call the superclass method.

### completes

- (BOOL) completes;
Availability: MacOS-X 10.0.0
Returns `YES` when the combo box cell automatic completion is active, returns `NO` otherwise. Take a look at the `setCompletes:` method documentation to know how the automatic completion works.

### dataSource

- (id) dataSource;
Availability: OpenStep
Returns the combo box cell data source object which is reponsible to provide the data to be displayed. To know how to implement a data source object, take a look at the NSComboBoxDataSource informal protocol description. In the case `usesDataSource` returns `NO`, this method logs a warning.

### deselectItemAtIndex:

- (void) deselectItemAtIndex: (int)index;
Availability: OpenStep
Deselects the combo box cell list row at index in the case this row is selected. Posts an NSComboBoxSelectionDidChangeNotification to the default notification center, when there is a new selection.

### hasVerticalScroller

- (BOOL) hasVerticalScroller;
Availability: OpenStep
Returns `YES` when the combo box cell displays a vertical scroller for its list, returns `NO` otherwise. Take note that the scroller will be displayed even when the sum of the items height in the list is inferior to the minimal height of the list displayed area.

### indexOfItemWithObjectValue:

- (int) indexOfItemWithObjectValue: (id)object;
Availability: OpenStep
Returns the lowest index associated with a value in the combo box cell default items list, which is equal to object, and returns NSNotFound when there is no such value. In the case `usesDataSource` returns `YES` , this method logs a warning.

### indexOfSelectedItem

- (int) indexOfSelectedItem;
Availability: OpenStep
Returns the index of the selected item in the combo box cell list or -1 when there is no selection, the selected item can be related to the data source object in the case `usesDataSource` returns `YES` else to the default items list.

### insertItemWithObjectValue: atIndex:

- (void) insertItemWithObjectValue: (id)object atIndex: (int)index;
Availability: OpenStep
Inserts an item in the combo box cell default items list which is used when `usesDataSource` returns `NO`. In the case `usesDataSource` returns `YES` , this method logs a warning.

### intercellSpacing

- (NSSize) intercellSpacing;
Availability: OpenStep
Returns the width and the height (as the values of an NSSize variable) between each item of the combo box cell list.

### isButtonBordered

- (BOOL) isButtonBordered;
Availability: Not in OpenStep/MacOS-X
Description forthcoming.

### itemHeight

- (float) itemHeight;
Availability: OpenStep
Returns the height of the items in the combo box cell list.

### itemObjectValueAtIndex:

- (id) itemObjectValueAtIndex: (int)index;
Availability: OpenStep
Returns the object value at index within combo box cell default items list. When the index is beyond the end of the list, an NSRangeException is raised. In the case `usesDataSource` returns `YES` , this method logs a warning.

### noteNumberOfItemsChanged

- (void) noteNumberOfItemsChanged;
Availability: OpenStep
Informs the combo box cell that the number of items in its data source has changed, in order to permit to the scrollers in its displayed list being updated without needing the reload of the data. It is recommended to use this method with a data source that continually receives data in the background, to keep the the combo box cell responsive to the user while the data is received. Take a look at the `NSComboBoxDataSource` informal protocol specification to know more on the messages NSComboBox sends to its data source.

### numberOfItems

- (int) numberOfItems;
Availability: OpenStep
Returns the number of items in the the combo box cell list, the numbers of items can be be related to the data source object in the case `usesDataSource` returns `YES` else to the default items list.

### numberOfVisibleItems

- (int) numberOfVisibleItems;
Availability: OpenStep
Returns the maximum number of allowed items to be displayed in the combo box cell list.

### objectValueOfSelectedItem

- (id) objectValueOfSelectedItem;
Availability: OpenStep
Returns the object value of the selected item in the combo box cell default items list or `nil` when there is no selection. In the case `usesDataSource` returns `YES`, this method logs a warning.

### objectValues

- (NSArray*) objectValues;
Availability: OpenStep
Returns the combo box cell default items list in an array.

### reloadData

- (void) reloadData;
Availability: OpenStep
Marks the combo box cell in order to have its items list reloaded in the case it uses a data source, and to have it redisplayed.

### removeAllItems

- (void) removeAllItems;
Availability: OpenStep
Removes all the items in the combo box cell default items list which is used when `usesDataSource` returns `NO`. In the case `usesDataSource` returns `YES`, this method logs a warning.

### removeItemAtIndex:

- (void) removeItemAtIndex: (int)index;
Availability: OpenStep
Removes the item with the specified index in the combo box cell default items list which is used when `usesDataSource` returns `NO`. In the case `usesDataSource` returns `YES` , this method logs a warning.

### removeItemWithObjectValue:

- (void) removeItemWithObjectValue: (id)object;
Availability: OpenStep
Removes an item in the combo box cell default items list which is used when `usesDataSource` returns `NO`. In the case `usesDataSource` returns `YES` , this method logs a warning.

### scrollItemAtIndexToTop:

- (void) scrollItemAtIndexToTop: (int)index;
Availability: OpenStep
Scrolls the combo box cell list vertically in order to have the item at index in the closest position relative to the top. There is no need to have the list displayed when this method is invoked.

### scrollItemAtIndexToVisible:

- (void) scrollItemAtIndexToVisible: (int)index;
Availability: OpenStep
Scrolls the combo box cell list vertically in order to have the item at index visible. There is no need to have the list displayed when this method is invoked.

### selectItemAtIndex:

- (void) selectItemAtIndex: (int)index;
Availability: OpenStep
Selects the combo box cell list row at index. Take note no changes occurs in the combo box cell list when this method is called. Posts an NSComboBoxSelectionDidChangeNotification to the default notification center when there is a new selection different from the previous one.

### selectItemWithObjectValue:

- (void) selectItemWithObjectValue: (id)object;
Availability: OpenStep
Selects the first item in the default combo box cell list which is equal to object. In the case `usesDataSource` returns `YES`, this method logs a warning. Take note that this method doesn't update the text field part value. Posts an NSComboBoxSelectionDidChange notification to the default notification center when the new selection is different than the previous one.

### setButtonBordered:

- (void) setButtonBordered: (BOOL)flag;
Availability: Not in OpenStep/MacOS-X
Description forthcoming.

### setCompletes:

- (void) setCompletes: (BOOL)completes;
Availability: MacOS-X 10.0.0
Sets whether the combo box cell automatic completion is active or not. The automatic completion tries to complete what the user types in the text field part, it tries to complete only when the the user adds characters at the end of the string, not when it deletes characters or when the insertion point precedes the end of the string. To do the automatic completion, the `completedString:` method is called, and when the returned string is longer than the current one in the text field, the completion occurs and the completed part gets selected.

### setDataSource:

- (void) setDataSource: (id)aSource;
Availability: OpenStep
Sets the combo box cell data source to aSource. Just calling this method doesn't set `usesDataSource` to return `YES`, you must call `setUsesDataSource:` with `YES` before or a warning will be logged. To know how to implement a data source objects, take a look at the NSComboBoxDataSource informal protocol description. When aSource doesn't respond to the methods `numberOfItemsInComboBox:` `comboBox:objectValueForItemAtIndex:`, this method logs a warning.

### setHasVerticalScroller:

- (void) setHasVerticalScroller: (BOOL)flag;
Availability: OpenStep
Sets whether the combo box cell list displays a vertical scroller, by default it is the case. When flag is `NO` and the combo cell list has more items (either in its default list or from its data source) than the number returned by `numberOfVisibleItems`, only a subset of them will be displayed. Uses scroll related methods to position this subset in the combo box cell list. Take note that the scroller will be displayed even when the sum of the items height in the list is inferior to the minimal height of the list displayed area.

### setIntercellSpacing:

- (void) setIntercellSpacing: (NSSize)aSize;
Availability: OpenStep
Sets the width and the height between each item of the combo box cell list to the values in aSize .

### setItemHeight:

- (void) setItemHeight: (float)itemHeight;
Availability: OpenStep
Sets the height of the items in the combo box cell list to itemHeight.

### setNumberOfVisibleItems:

- (void) setNumberOfVisibleItems: (int)visibleItems;
Availability: OpenStep
Sets the maximum number of allowed items to be displayed in the combo box cell list.

### setUsesDataSource:

- (void) setUsesDataSource: (BOOL)flag;
Availability: OpenStep
Sets according to flag whether the combo box cell uses a data source (which is external) to populate its items list.

### trackMouse: inRect: ofView: untilMouseUp:

- (BOOL) trackMouse: (NSEvent*)theEvent inRect: (NSRect)cellFrame ofView: (NSView*)controlView untilMouseUp: (BOOL)flag;
Availability: OpenStep
Overrides NSCell `trackMouse:inRect:ofView:untilMouseUp:` method to establish a new method behavior. In the case flag is `NO`, returns `NO` when the mouse down occurs in the text cell part or when the mouse down occurs in the button cell part followed by a mouse up outside, otherwise returns `YES` (when both the mouse down and the mouse up occurs in the button cell part). In the case flag is `YES`, returns `NO` when the mouse occurs in the text cell part, otherwise returns `YES` (when the mouse down occurs in the button cell part).

### usesDataSource

- (BOOL) usesDataSource;
Availability: OpenStep
Returns `YES` when the combo box cell uses a data source (which is external) to populate its items list, otherwise returns `NO` in the case it uses its default list.

## Instance Variables for NSComboBoxCell Class

### _buttonCell

@protected NSButtonCell* _buttonCell;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _completes

@protected BOOL _completes;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _dataSource

@protected id _dataSource;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _hasVerticalScroller

@protected BOOL _hasVerticalScroller;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _intercellSpacing

@protected NSSize _intercellSpacing;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _itemHeight

@protected float _itemHeight;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _lastValidFrame

@protected NSRect _lastValidFrame;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _popUpList

@protected NSMutableArray* _popUpList;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _prevSelectedRange

@protected NSRange _prevSelectedRange;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _selectedItem

@protected int _selectedItem;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _usesDataSource

@protected BOOL _usesDataSource;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _visibleItems

@protected int _visibleItems;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

# Software documentation for the NSObject(NSComboBoxCellDataSource) informal protocol

## NSObject(NSComboBoxCellDataSource)

> Declared in:
>   AppKit/NSComboBoxCell.h

Availability: OpenStep
Description forthcoming.
Method summary

- -comboBoxCell:completedString:
- -comboBoxCell:indexOfItemWithStringValue:
- -comboBoxCell:objectValueForItemAtIndex:
- -numberOfItemsInComboBoxCell:

### comboBoxCell: completedString:

- (NSString*) comboBoxCell: (NSComboBoxCell*)aComboBoxCell completedString: (NSString*)uncompletedString;
Availability: MacOS-X 10.0.0
Description forthcoming.

### comboBoxCell: indexOfItemWithStringValue:

- (unsigned int) comboBoxCell: (NSComboBoxCell*)aComboBoxCell indexOfItemWithStringValue: (NSString*)string;
Availability: OpenStep
Description forthcoming.

### comboBoxCell: objectValueForItemAtIndex:

- (id) comboBoxCell: (NSComboBoxCell*)aComboBoxCell objectValueForItemAtIndex: (int)index;
Availability: OpenStep
Description forthcoming.

### numberOfItemsInComboBoxCell:

- (int) numberOfItemsInComboBoxCell: (NSComboBoxCell*)comboBoxCell;
Availability: OpenStep
Description forthcoming.

Up