Up
Authors
- Gerrit van Dyk (
gerritvd@decillion.net)
-
Date: Generated at 2025-12-03
Copyright: (C) 1999 Free Software Foundation, Inc.
An NSComboBox is what we can call a completion/choices box,
derived from NSTextField, 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 NSControl classes, NSComboBox is a wrapper
around a core piece which implements the combo box
behavior, a cell, which is in this case an
NSComboBoxCell.
- Declared in:
- AppKit/NSComboBox.h
Availability: OpenStep
NSComboBox combines a text field with a dropdown
list, providing users with both direct text entry and
selection from predefined options. It extends
NSTextField to add list management, selection
handling, and dropdown display capabilities. Key
features include: * Dual input modes: direct text
entry and dropdown selection * Two data management
approaches: internal item storage or external
data source * Customizable dropdown appearance with
scrolling and sizing options * Text completion for
enhanced user experience * Rich selection and
navigation API * Delegate notifications for popup
and selection events * Full integration with Interface
Builder and archiving * Support for bordered and
borderless button styles Data Management:
NSComboBox supports two data management modes
controlled by the usesDataSource property. When
NO (default), items are managed
internally using methods like
addItemWithObjectValue: and
removeItemAtIndex:. When
YES
, data is provided through an external data source
implementing NSComboBoxDataSource protocol. The
dropdown list can be customized with intercell
spacing, item height, number of visible items, and
optional vertical scrolling. Text completion can be
enabled to automatically complete user input based on
available items. Selection and navigation methods
allow programmatic control over the dropdown state,
including scrolling items into view and managing
selection state. Delegate methods provide
notifications for popup display and selection
changes. Visual appearance includes customizable
button borders and standard text field styling
inherited from the NSTextField superclass.
No special instructions to use NSComboBox or text to
detail the implementation.
- (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.
- (BOOL)
completes;
Availability: MacOS-X 10.0.0
Returns whether the combo box performs automatic
text completion. Returns: YES if 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. 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 dropdown button displays a
border. Returns: YES if the button has
a border, 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 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.
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 dropdown button should display a
border. flag: YES to show a border on
the button, NO for borderless appearance
- (void)
setCompletes: (BOOL)completes;
Availability: MacOS-X 10.0.0
Sets whether the combo box performs automatic text
completion. completes: YES to
enable 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. aSource: The data source object
implementing NSComboBoxDataSource 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 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)
usesDataSource;
Availability: OpenStep
Returns whether the combo box 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.
- Declared in:
- AppKit/NSComboBox.h
- Conforms to:
- NSObject
Availability: MacOS-X 10.6.0
Description forthcoming.
- (
NSString*)
comboBox: (
NSComboBox*)aComboBox
completedString: (
NSString*)aString;
Availability: MacOS-X 10.0.0
Returns a completed string based on the partial
input string. aComboBox: The combo box requesting the
completion aString: The partial string to
complete Returns: A completed string, or
nil if no completion is available
- (
NSUInteger)
comboBox: (
NSComboBox*)aComboBox
indexOfItemWithStringValue: (
NSString*)string;
Availability: OpenStep
Returns the index of the item with the specified
string value. aComboBox: The combo box
requesting the index string: The
string value to search for Returns: The
index of the item matching the string, or
NSNotFound if not found
- (id)
comboBox: (
NSComboBox*)aComboBox
objectValueForItemAtIndex: (
NSInteger)index;
Availability: OpenStep
Returns the object value for the item at the
specified index. aComboBox: The combo
box requesting the object value index: The
index of the requested item Returns: The
object value for the item at the specified
index
- (
NSInteger)
numberOfItemsInComboBox: (
NSComboBox*)aComboBox;
Availability: OpenStep
Returns the number of items available in the combo
box. aComboBox: The combo box requesting the item
count Returns: The total number of items available
for selection
- Declared in:
- AppKit/NSComboBox.h
- Conforms to:
- NSTextFieldDelegate
Availability: MacOS-X 10.6.0
Description forthcoming.
- (void)
comboBoxSelectionDidChange: (
NSNotification*)notification;
Availability: OpenStep
Called when the combo box selection has changed.
notification: The notification
containing the combo box as the object
- (void)
comboBoxSelectionIsChanging: (
NSNotification*)notification;
Availability: OpenStep
Called when the combo box selection is in the
process of changing. notification: The
notification containing the combo box as
the object
- (void)
comboBoxWillDismiss: (
NSNotification*)notification;
Availability: OpenStep
Called when the combo box dropdown is about to
disappear. notification: The
notification containing the combo box as
the object
- (void)
comboBoxWillPopUp: (
NSNotification*)notification;
Availability: OpenStep
Called when the combo box dropdown is about to
appear. notification: The notification
containing the combo box as the object
Up