Up
Authors
- Gerrit van Dyk (
gerritvd@decillion.net)
-
- Quentin Mathe (
qmathe@club-internet.fr)
-
Date: Generated at 2025-12-03
Copyright: (C) 1999 Free Software Foundation, Inc.
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.
- Declared in:
- AppKit/NSComboBoxCell.h
Availability: OpenStep
NSComboBoxCell provides the core
implementation for combo box functionality,
extending NSTextFieldCell to add dropdown list
capabilities. It serves as the cell component
used by NSComboBox controls and can be used
independently in custom controls requiring
combo box behavior. Key features include: * Text input
with dropdown selection capabilities * Dual data
management: internal item storage or external
data source * Customizable dropdown appearance and
behavior * Mouse tracking for dropdown interaction *
Text completion support for enhanced user experience *
Flexible selection and navigation API * Full
integration with the cell architecture Data
Management: Similar to NSComboBox, NSComboBoxCell
supports two data management approaches. When
usesDataSource is
NO, items are
managed internally using methods like
addItemWithObjectValue: and
removeItemAtIndex:. When
YES
, data is provided through an external data source
implementing the NSComboBoxCellDataSource
protocol. The cell handles all aspects of dropdown
display including scrolling behavior, item height,
intercell spacing, and the number of visible items.
Mouse tracking is implemented to handle dropdown
interaction and item selection. Text completion
can be enabled to provide automatic completion of user
input based on available items, improving the user
experience for data entry tasks. Visual
customization includes control over the
dropdown button appearance, including bordered and
borderless styles. The cell integrates seamlessly
with the NSControl/NSCell architecture while providing
specialized combo box functionality.
No special instructions to use NSComboBoxCell or text to
detail the implementation.
NSComboBoxCell declares 12 Instance Variables
- (void)
addItemWithObjectValue: (id)object;
Availability: OpenStep
Adds an item to the end of the dropdown list. object:
The object value to add to the list
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.
- (void)
addItemsWithObjectValues: (
NSArray*)objects;
Availability: OpenStep
Adds multiple items to the end of the dropdown list.
objects: An array of object values to add to the
list
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.
- (
NSString*)
completedString: (
NSString*)substring;
Availability: MacOS-X 10.0.0
Returns a completed string based on the
substring. substring: The partial string
to complete Returns: The completed string, or the
original if no completion found
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.
- (BOOL)
completes;
Availability: MacOS-X 10.0.0
Returns whether the combo box cell automatically
completes text. Returns: YES if
automatic text completion is enabled,
NO otherwise
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.
- (id)
dataSource;
Availability: OpenStep
Returns the data source object providing items to
the combo box cell. Returns: The data source object, or
nil if none is set
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.
- (void)
deselectItemAtIndex: (
NSInteger)index;
Availability: OpenStep
Deselects the item at the specified
index in the dropdown list. index: The
index of the item to deselect
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.
- (BOOL)
hasVerticalScroller;
Availability: OpenStep
Returns whether the dropdown list displays a
vertical scroller. Returns: YES if a
vertical scroller is shown, NO
otherwise
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.
- (
NSInteger)
indexOfItemWithObjectValue: (id)object;
Availability: OpenStep
Returns the index of the first item matching the
specified object. object: The
object value to search for Returns: The
index of the matching item, or -1 if not found
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.
- (
NSInteger)
indexOfSelectedItem;
Availability: OpenStep
Returns the index of the currently selected item.
Returns: The index of the selected item, or -1 if
no item is selected
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.
- (void)
insertItemWithObjectValue: (id)object
atIndex: (
NSInteger)index;
Availability: OpenStep
Inserts an item at the specified index
in the dropdown list. object: The object
value to insert index: The index at which
to insert the item
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.
- (
NSSize)
intercellSpacing;
Availability: OpenStep
Returns the spacing between cells in the dropdown
list. Returns: An NSSize specifying the horizontal
and vertical intercell spacing
Returns the width
and the height (as the values of an NSSize variable)
between each item of the combo box cell list.
- (BOOL)
isButtonBordered;
Availability: MacOS-X 10.3.0
Returns whether the combo box button has a border.
Returns: YES if the button is
bordered, NO otherwise
- (CGFloat)
itemHeight;
Availability: OpenStep
Returns the height of each item in the dropdown
list. Returns: The height in points for dropdown list
items
Returns the height of the items in the
combo box cell list.
- (id)
itemObjectValueAtIndex: (
NSInteger)index;
Availability: OpenStep
Returns the object value at the specified
index. index: The index of the
desired item Returns: The object value at the
specified index
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.
- (void)
noteNumberOfItemsChanged;
Availability: OpenStep
Notifies the combo box cell that the number of
items has changed.
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.
- (
NSInteger)
numberOfItems;
Availability: OpenStep
Returns the total number of items in the combo box
cell. Returns: The count of items available for
selection
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.
- (
NSInteger)
numberOfVisibleItems;
Availability: OpenStep
Returns the number of items visible in the dropdown
without scrolling. Returns: The number of items
shown in the dropdown list
Returns the maximum
number of allowed items to be displayed in the combo
box cell list.
- (id)
objectValueOfSelectedItem;
Availability: OpenStep
Returns the object value of the currently selected
item. Returns: The object value of the selected item,
or nil if none selected
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.
- (
NSArray*)
objectValues;
Availability: OpenStep
Returns an array containing all object values in
the dropdown list. Returns: An NSArray of all object
values in the list
Returns the combo box cell
default items list in an array.
- (void)
reloadData;
Availability: OpenStep
Reloads the dropdown list data from the data
source.
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.
- (void)
removeAllItems;
Availability: OpenStep
Removes all items from the dropdown list.
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.
- (void)
removeItemAtIndex: (
NSInteger)index;
Availability: OpenStep
Removes the item at the specified index
from the dropdown list. index: The index of
the item to remove
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.
- (void)
removeItemWithObjectValue: (id)object;
Availability: OpenStep
Removes the first occurrence of the specified
object from the list. object: The
object value to remove from the list
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.
- (void)
scrollItemAtIndexToTop: (
NSInteger)index;
Availability: OpenStep
Scrolls the dropdown list to position the specified
item at the top. index: The index of the
item to scroll to the top of the visible area
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.
- (void)
scrollItemAtIndexToVisible: (
NSInteger)index;
Availability: OpenStep
Scrolls the dropdown list to make the specified
item visible. index: The index of the item
to make visible in the dropdown
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.
- (void)
selectItemAtIndex: (
NSInteger)index;
Availability: OpenStep
Selects the item at the specified index
in the dropdown list. index: The index of the
item to select
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.
- (void)
selectItemWithObjectValue: (id)object;
Availability: OpenStep
Selects the first item in the list that matches the
specified object. object: The
object value to select in the list
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.
- (void)
setButtonBordered: (BOOL)flag;
Availability: MacOS-X 10.3.0
Sets whether the combo box button has a border. flag:
YES to draw a border around the button,
NO to remove it
- (void)
setCompletes: (BOOL)completes;
Availability: MacOS-X 10.0.0
Sets whether the combo box cell automatically
completes text. completes:
YES to enable automatic text
completion, NO to disable
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.
- (void)
setDataSource: (id)aSource;
Availability: OpenStep
Sets the data source object to provide items to the
combo box cell. aSource: The data source object
implementing NSComboBoxCellDataSource protocol
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.
- (void)
setHasVerticalScroller: (BOOL)flag;
Availability: OpenStep
Sets whether the dropdown list should display a
vertical scroller. flag: YES to show
a vertical scroller, NO to hide it
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.
- (void)
setIntercellSpacing: (
NSSize)aSize;
Availability: OpenStep
Sets the spacing between cells in the dropdown list.
aSize: An NSSize specifying the horizontal and
vertical intercell spacing
Sets the width
and the height between each item of the combo box cell
list to the values in aSize.
- (void)
setItemHeight: (CGFloat)itemHeight;
Availability: OpenStep
Sets the height of each item in the dropdown list.
itemHeight: The height in points for dropdown
list items
Sets the height of the items in the
combo box cell list to itemHeight.
- (void)
setNumberOfVisibleItems: (
NSInteger)visibleItems;
Availability: OpenStep
Sets the number of items visible in the dropdown
without scrolling. visibleItems: The number of
items to show in the dropdown list
Sets the
maximum number of allowed items to be displayed in
the combo box cell list.
- (void)
setUsesDataSource: (BOOL)flag;
Availability: OpenStep
Sets whether the combo box cell should use an external
data source. flag: YES to use a data
source, NO to manage items internally
Sets according to flag whether the
combo box cell uses a data source (which is external)
to populate its items list.
- (BOOL)
trackMouse: (
NSEvent*)theEvent
inRect: (
NSRect)cellFrame
ofView: (
NSView*)controlView
untilMouseUp: (BOOL)untilMouseUp;
Availability: OpenStep
Tracks mouse events for the combo box cell.
theEvent: The mouse event to track inRect: The
rectangle in which to track ofView: The view
containing the cell untilMouseUp:
YES to track until mouse up,
NO otherwise Returns: YES
if the mouse tracking was successful
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).
- (BOOL)
usesDataSource;
Availability: OpenStep
Returns whether the combo box cell uses an external
data source. Returns: YES if using a data
source, NO if managing items
internally
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
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@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.
@protected NSInteger
_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.
@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.
@protected NSInteger
_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.
- Declared in:
- AppKit/NSComboBoxCell.h
Availability: OpenStep
Description forthcoming.
- (
NSString*)
comboBoxCell: (
NSComboBoxCell*)aComboBoxCell
completedString: (
NSString*)uncompletedString;
Availability: MacOS-X 10.0.0
Returns a completed string based on the partial
input. aComboBoxCell: The combo box cell requesting
completion uncompletedString: The partial string
to complete Returns: The completed string, or the
original if no completion found
- (
NSUInteger)
comboBoxCell: (
NSComboBoxCell*)aComboBoxCell
indexOfItemWithStringValue: (
NSString*)string;
Availability: OpenStep
Returns the index of the first item that matches
the given string. aComboBoxCell: The combo
box cell performing the search string: The
string value to search for Returns: The
index of the first matching item, or NSNotFound if
none found
- (id)
comboBoxCell: (
NSComboBoxCell*)aComboBoxCell
objectValueForItemAtIndex: (
NSInteger)index;
Availability: OpenStep
Returns the object value for the item at the
specified index. aComboBoxCell: The
combo box cell requesting the data index: The
index of the requested item Returns: The
object value at the specified index
- (
NSInteger)
numberOfItemsInComboBoxCell: (
NSComboBoxCell*)comboBoxCell;
Availability: OpenStep
Returns the total number of items in the combo box.
comboBoxCell: The combo box cell requesting
the count Returns: The number of items available from
the data source
- Declared in:
- AppKit/NSComboBoxCell.h
- Conforms to:
- NSObject
Availability: OpenStep
This protocol defines methods that a data source must
implement to provide data for a combo box cell when
using external data management.
Up