Mac Developer Library

Developer

AppKit Framework Reference NSComboBoxCell Class Reference

Options
Deployment Target:

On This Page
Language:

NSComboBoxCell

NSComboBoxCell is a subclass of NSTextFieldCell used to implement the user interface of “combo boxes” (see NSComboBox for information on how combo boxes look and work). The NSComboBox subclass of NSTextField uses a single NSComboBoxCell, and essentially all of the NSComboBox class’s methods simply invoke the corresponding NSComboBoxCell method.

Also see the NSComboBoxCellDataSource Protocol protocol, which declares the methods that an NSComboBoxCell object uses to access the contents of its data source object.

Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.
  • A Boolean value that indicates if the combo box displays a vertical scroller.

    Declaration

    Swift

    var hasVerticalScroller: Bool

    Objective-C

    @property BOOL hasVerticalScroller

    Discussion

    When the value of this property is YEStrue, the combo box displays a vertical scroller; when the value is NOfalse, it does not. The default value of this property is YEStrue. Note that the scroller is displayed even if the pop-up list contains fewer items than will fit in the area specified for display.

    If you set this property to NOfalse 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 are displayed. The NSComboBoxCell scroll... methods can be used to position this subset within the pop-up list.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value that indicates whether the combo box button displays a border.

    Declaration

    Swift

    var buttonBordered: Bool

    Objective-C

    @property(getter=isButtonBordered) BOOL buttonBordered

    Discussion

    When the value of this property is YEStrue, the button has a border; when it is NOfalse, the button is borderless. For example, it is often useful when using a combo box in an NSTableView to display the button without a border.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • The spacing between cells in the combo box’s pop-up list.

    Declaration

    Swift

    var intercellSpacing: NSSize

    Objective-C

    @property NSSize intercellSpacing

    Discussion

    The value of this property is the horizontal and vertical spacing between cells in the combo box’s pop-up list. The default spacing is (3.0, 2.0).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The height of each item in the combo box’s pop-up list.

    Declaration

    Swift

    var itemHeight: CGFloat

    Objective-C

    @property CGFloat itemHeight

    Discussion

    The default item height is 16.0.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var numberOfVisibleItems: Int

    Objective-C

    @property NSInteger numberOfVisibleItems

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The object that provides the data displayed in the combo box’s pop-up list.

    Declaration

    Swift

    unowned(unsafe) var dataSource: NSComboBoxCellDataSource?

    Objective-C

    @property(assign) id< NSComboBoxCellDataSource > dataSource

    Discussion

    The value of this property should be an object that implements the appropriate methods of the NSComboBoxCellDataSource informal protocol. Note that setting this property doesn’t automatically set usesDataSource to NOfalse and in fact logs a warning if usesDataSource is NOfalse. If you set this property to an object that doesn’t respond to either numberOfItemsInComboBoxCell: or comboBoxCell:objectValueForItemAtIndex:, a warning is logged if usesDataSource is NOfalse. See the class description and the NSComboBoxCellDataSource informal protocol specification for more information on combo box cell data source objects.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value that indicates if the combo box uses an external data source to populate its pop-up list.

    Declaration

    Swift

    var usesDataSource: Bool

    Objective-C

    @property BOOL usesDataSource

    Discussion

    When the value of this property is YEStrue, the combo box uses an external data source to populate its pop-up list; when it is NOfalse, the combo box uses an internal item list.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    dataSource

  • Adds multiple objects to the internal item list.

    Declaration

    Swift

    func addItemsWithObjectValues(_ objects: [AnyObject])

    Objective-C

    - (void)addItemsWithObjectValues:(NSArray *)objects

    Parameters

    objects

    The object to add to the end of the combo box’s internal item list.

    Discussion

    This method logs a warning if usesDataSource is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Adds the specified object to the internal item list.

    Declaration

    Swift

    func addItemWithObjectValue(_ anObject: AnyObject)

    Objective-C

    - (void)addItemWithObjectValue:(id)anObject

    Parameters

    anObject

    The object to add to the end of the combo box's internal item list.

    Discussion

    This method logs a warning if usesDataSource is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Inserts an object at the specified location in the internal item list.

    Declaration

    Swift

    func insertItemWithObjectValue(_ anObject: AnyObject, atIndex index: Int)

    Objective-C

    - (void)insertItemWithObjectValue:(id)anObject atIndex:(NSInteger)index

    Parameters

    anObject

    The object to add to the combo box's internal item list.

    index

    The index at which to add the specified object. The previous item at index—along with all following items—is shifted down one slot to make room.

    Discussion

    This method logs a warning if usesDataSource is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The combo box’s internal item list in an array. (read-only)

    Declaration

    Swift

    var objectValues: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *objectValues

    Discussion

    Accessing this property logs a warning if usesDataSource is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Removes all items from the combo box’s internal item list.

    Declaration

    Swift

    func removeAllItems()

    Objective-C

    - (void)removeAllItems

    Discussion

    This method logs a warning if usesDataSource is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    objectValues

  • Removes the object at the specified location from the combo box’s internal item list.

    Declaration

    Swift

    func removeItemAtIndex(_ index: Int)

    Objective-C

    - (void)removeItemAtIndex:(NSInteger)index

    Parameters

    index

    The index of the object to remove from the combo box's internal item list. All items beyond index are moved up one slot to fill the gap.

    Discussion

    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 is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Removes all occurrences of the specified object from the combo box’s internal item list.

    Declaration

    Swift

    func removeItemWithObjectValue(_ anObject: AnyObject)

    Objective-C

    - (void)removeItemWithObjectValue:(id)anObject

    Parameters

    anObject

    The object to remove from the combo box's internal item list. Objects are considered equal if they have the same id or if isEqual: returns YEStrue.

    Discussion

    This method logs a warning if usesDataSource is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The total number of items in the pop-up list. (read-only)

    Declaration

    Swift

    var numberOfItems: Int { get }

    Objective-C

    @property(readonly) NSInteger numberOfItems

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    numberOfVisibleItems
    – numberOfItemsInComboBoxCell: (NSComboBoxCellDataSource protocol)

  • Searches the combo box’s internal item list for the given object and returns the matching index number.

    Declaration

    Swift

    func indexOfItemWithObjectValue(_ anObject: AnyObject) -> Int

    Objective-C

    - (NSInteger)indexOfItemWithObjectValue:(id)anObject

    Parameters

    anObject

    The object for which to return the index.

    Return Value

    The lowest index whose corresponding value is equal to anObject. Objects are considered equal if they have the same id or if isEqual: returns YEStrue. If none of the objects in the combo box’s internal item list is equal to anObject, indexOfItemWithObjectValue: returns NSNotFound.

    Discussion

    This method logs a warning if usesDataSource is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the object located at the specified location in the internal item list.

    Declaration

    Swift

    func itemObjectValueAtIndex(_ index: Int) -> AnyObject

    Objective-C

    - (id)itemObjectValueAtIndex:(NSInteger)index

    Parameters

    index

    The index of the object to return. If index is beyond the end of the list, an NSRangeException is raised.

    Return Value

    The object at the given location in the combo box's internal item list.

    Discussion

    This method logs a warning if usesDataSource is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Informs the combo box that the number of items in its data source has changed.

    Declaration

    Swift

    func noteNumberOfItemsChanged()

    Objective-C

    - (void)noteNumberOfItemsChanged

    Discussion

    This method allows the combo box to update the scrollers in its displayed pop-up list without actually reloading data into the combo box. It 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – reloadData

  • Marks the combo box as needing redisplay, so that it will reload the data for visible pop-up items and draw the new values.

    Declaration

    Swift

    func reloadData()

    Objective-C

    - (void)reloadData

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Scrolls the combo box’s pop-up list vertically so that the item at the given index is as close to the top as possible.

    Declaration

    Swift

    func scrollItemAtIndexToTop(_ index: Int)

    Objective-C

    - (void)scrollItemAtIndexToTop:(NSInteger)index

    Parameters

    index

    The index of the item to scroll to the top.

    Discussion

    The pop-up list need not be displayed at the time this method is invoked.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Scrolls the combo box’s pop-up list vertically so that the item at the given index is visible.

    Declaration

    Swift

    func scrollItemAtIndexToVisible(_ index: Int)

    Objective-C

    - (void)scrollItemAtIndexToVisible:(NSInteger)index

    Parameters

    index

    The index of the item to make visible.

    Discussion

    The pop-up list need not be displayed at the time this method is invoked.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Deselects the pop-up list item at the given index if it’s selected.

    Declaration

    Swift

    func deselectItemAtIndex(_ index: Int)

    Objective-C

    - (void)deselectItemAtIndex:(NSInteger)index

    Parameters

    index

    The index of the item to deselect.

    Discussion

    If the selection does in fact change, this method posts an NSComboBoxSelectionDidChangeNotification to the default notification center.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The index of the last item selected from the pop-up list. (read-only)

    Declaration

    Swift

    var indexOfSelectedItem: Int { get }

    Objective-C

    @property(readonly) NSInteger indexOfSelectedItem

    Discussion

    The index of the last item selected from the combo box's pop-up list or –1 if no item is selected. Note that nothing is initially selected in a newly initialized combo box cell.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The object corresponding to the last item selected from the pop-up list. (read-only)

    Declaration

    Swift

    var objectValueOfSelectedItem: AnyObject? { get }

    Objective-C

    @property(readonly, strong) id objectValueOfSelectedItem

    Discussion

    The value of this property is the object from the combo box’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. Accessing this property logs a warning if usesDataSource is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    indexOfSelectedItem
    – comboBoxCell:objectValueForItemAtIndex: (NSComboBoxCellDataSource protocol)

  • Selects the pop-up list row at the given index.

    Declaration

    Swift

    func selectItemAtIndex(_ index: Int)

    Objective-C

    - (void)selectItemAtIndex:(NSInteger)index

    Parameters

    index

    The index of the row to select.

    Discussion

    Posts an 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 Combo Box Programming Topics for more information.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – setObjectValue: (NSControl)

  • Selects the first pop-up list item that corresponds to the specified object.

    Declaration

    Swift

    func selectItemWithObjectValue(_ anObject: AnyObject?)

    Objective-C

    - (void)selectItemWithObjectValue:(id)anObject

    Parameters

    anObject

    The object for which to select the corresponding pop-up list item. Objects are considered equal if they have the same id or if isEqual: returns YEStrue.

    Discussion

    This method logs a warning if usesDataSource is YEStrue. Posts an 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 Setting the Combo Box’s Value for more information.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – setObjectValue: (NSControl)

  • Returns a string from the combo box’s pop-up list that starts with the given substring.

    Declaration

    Swift

    func completedString(_ substring: String) -> String?

    Objective-C

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

    Parameters

    substring

    The substring to search for. This is what the user entered in the combo box’s text field.

    Return Value

    The string from the combo box's pop-up list that starts with the specified substring or nil if there is no such string.

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • completes completes Property

    A Boolean value that indicates if the combo box tries to complete text entered by the user.

    Declaration

    Swift

    var completes: Bool

    Objective-C

    @property BOOL completes

    Discussion

    When the value of this property is YEStrue, the combo box tries to complete what the user types in the text field and every time the user adds characters to the end of the text field, the combo box calls completedString:; when it is NOfalse, it does not.

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.