Mac Developer Library

Developer

AppKit Framework Reference NSComboBox Class Reference

Options
Deployment Target:

On This Page
Language:

NSComboBox

Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.

An NSComboBox is a kind of control that allows you to enter text directly (as you would with an NSTextField) or click the attached arrow at the right of the combo box and select from a displayed (“pop-up”) list of items.

Normally an instance of NSComboBox looks like this:

image: Art/combobox.gif is missing from your submission.

When you click the downward-pointing arrow at the right side of the text field, the pop-up list appears, like this:

image: Art/comboboxlist.gif is missing from your submission.

The NSComboBox class uses NSComboBoxCell to implement its user interface.

Also see the NSComboBoxDataSource informal protocol, which declares the methods that an NSComboBox uses to access the contents of its data source object.

  • A Boolean value indicating whether the combo box has 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 even when the pop-up list contains few enough items that a scroller is not needed. The default value of this property is YEStrue.

    If the value of this property is NOfalse and the combo box has more list items (either in its internal item list or from its data source) than are allowed by numberOfVisibleItems, only a subset of items are displayed. The NSComboBox class' 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.

  • The horizontal and vertical spacing between cells in the pop-up list.

    Declaration

    Swift

    var intercellSpacing: NSSize

    Objective-C

    @property NSSize intercellSpacing

    Discussion

    Spacing values are measured in points. 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.

  • A Boolean value indicating whether the combo box 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 combo box displays a border. For example, when displaying a combo box in a table, it is often useful to display the combo box without a border. The default value of this property is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • The height of each item in the pop-up list.

    Declaration

    Swift

    var itemHeight: CGFloat

    Objective-C

    @property CGFloat itemHeight

    Discussion

    The height of items is measured in points. The default item height is 16.0 points.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var numberOfVisibleItems: Int

    Objective-C

    @property NSInteger numberOfVisibleItems

    Discussion

    Use this property to configure how many items can be displayed at the same time. If the combo box has a scroller, the user can scroll to view additional items beyond the visible range.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The object that provides the item data for the combo box.

    Declaration

    Swift

    unowned(unsafe) var dataSource: NSComboBoxDataSource?

    Objective-C

    @property(assign) id< NSComboBoxDataSource > dataSource

    Discussion

    Assigning an object to this property does not automatically set the usesDataSource property to YEStrue. If the usesDataSource property is NOfalse, accessing this property logs a warning. The default value of this property is nil.

    For information about how to implement a combo box data source, see NSComboBoxDataSource Protocol Reference.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    usesDataSource

  • A Boolean value indicating whether the combo box retrieves its items from a data source object.

    Declaration

    Swift

    var usesDataSource: Bool

    Objective-C

    @property BOOL usesDataSource

    Discussion

    When the value of this property is YEStrue, the combo box retrieves its items from the object in the dataSource property. When the value is NOfalse, the combo box manages an internal list of items, which it gets from the ones specified at design time and the ones you add programmatically.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Adds multiple objects to the end of the receiver’s internal item list.

    Declaration

    Swift

    func addItemsWithObjectValues(_ objects: [AnyObject])

    Objective-C

    - (void)addItemsWithObjectValues:(NSArray *)objects

    Parameters

    objects

    An array of the objects to add to the internal item list.

    Discussion

    This method logs a warning if the usesDataSource property is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Adds an object to the end of the receiver’s internal item list.

    Declaration

    Swift

    func addItemWithObjectValue(_ anObject: AnyObject)

    Objective-C

    - (void)addItemWithObjectValue:(id)anObject

    Parameters

    anObject

    The object to add to the internal item list.

    Discussion

    This method logs a warning if the usesDataSource property 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 receiver’s 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 internal item list.

    index

    The index in the list at which to add the new 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 the usesDataSource property is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • An array of the items from the combo box’s internal list. (read-only)

    Declaration

    Swift

    var objectValues: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *objectValues

    Discussion

    The array contains the objects you added or inserted into the combo box, so the type of each object can vary. Accessing this property logs a warning if the usesDataSource property 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 receiver’s internal item list.

    Declaration

    Swift

    func removeAllItems()

    Objective-C

    - (void)removeAllItems

    Discussion

    This method logs a warning if the usesDataSource property 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 receiver’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. 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 the usesDataSource property 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 given object from the receiver’s internal item list.

    Declaration

    Swift

    func removeItemWithObjectValue(_ anObject: AnyObject)

    Objective-C

    - (void)removeItemWithObjectValue:(id)anObject

    Parameters

    anObject

    The object to remove from the 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 the usesDataSource property 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
    – numberOfItemsInComboBox: (NSComboBoxDataSource protocol)

  • Searches the receiver’s internal item list for the specified object and returns the lowest matching index.

    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 in the internal item list whose corresponding value is equal to that of the specified object. Objects are considered equal if they have the same id or if isEqual: returns YEStrue.

    If none of the objects in the receiver’s internal item list are equal to anObject, indexOfItemWithObjectValue: returns NSNotFound.

    Discussion

    This method logs a warning if the usesDataSource property 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 given index within the receiver’s internal item list.

    Declaration

    Swift

    func itemObjectValueAtIndex(_ index: Int) -> AnyObject

    Objective-C

    - (id)itemObjectValueAtIndex:(NSInteger)index

    Parameters

    index

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

    Return Value

    The object located at the specified index in the internal item list.

    Discussion

    This method logs a warning if the usesDataSource property is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func noteNumberOfItemsChanged()

    Objective-C

    - (void)noteNumberOfItemsChanged

    Discussion

    This method allows the receiver to update the scrollers in its displayed pop-up list without actually reloading data into the receiver. It is particularly useful for a data source that continually receives data in the background over a period of time, in which case the NSComboBox can remain responsive to the user while the data is received.

    See the NSComboBoxDataSource informal protocol specification for information on the messages an NSComboBox 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 receiver 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 receiver’s pop-up list vertically so that the item at the specified 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 receiver’s pop-up list vertically so that the item at the specified 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 specified 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 value of this property is -1 if no item is selected; otherwise, it is the index of the selected item. Nothing is selected in a newly initialized combo box.

    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

    For combo boxes that use their own internally maintained list of items, this property contains the object in that list that is selected. If no item is selected, the value in this property is nil. Nothing is selected in a newly initialized combo box. This method logs a warning if the usesDataSource property is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    indexOfSelectedItem
    – comboBox:objectValueForItemAtIndex: (NSComboBoxDataSource 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 item to select in the pop-up list.

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

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

    Declaration

    Swift

    func selectItemWithObjectValue(_ anObject: AnyObject?)

    Objective-C

    - (void)selectItemWithObjectValue:(id)anObject

    Parameters

    anObject

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

    Discussion

    This method logs a warning if usesDataSource returns 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’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)

  • completes completes Property

    A Boolean value indicating whether the combo box tries to complete what the user types.

    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 is typing. Every time the user types a new character, the combo box uses the completedString: method of its cell to get the new value. If the string returned by that method is longer than the string typed by the user, 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.

    When the value of this property is NOfalse, the combo box does not try to complete the string typed by the user.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the receiver’s delegate.

    Declaration

    Swift

    func delegate() -> NSComboBoxDelegate?

    Objective-C

    - (id<NSComboBoxDelegate>)delegate

    Return Value

    The receiver’s delegate.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Sets the receiver’s delegate.

    Declaration

    Swift

    func setDelegate(_ anObject: NSComboBoxDelegate?)

    Objective-C

    - (void)setDelegate:(id<NSComboBoxDelegate>)anObject

    Parameters

    anObject

    The delegate for the receiver. The delegate must conform to the NSComboBoxDelegate Protocol protocol.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

    See Also

    – delegate

  • Posted after the pop-up list selection of the NSComboBox changes.

    The notification object is the NSComboBox whose selection changed. This notification does not contain a userInfo dictionary.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Posted whenever the pop-up list selection of the NSComboBox is changing.

    The notification object is the NSComboBox whose selection is changing. This notification does not contain a userInfo dictionary.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Posted whenever the pop-up list of the NSComboBox is about to be dismissed.

    The notification object is the NSComboBox whose pop-up list will be dismissed. This notification does not contain a userInfo dictionary.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Posted whenever the pop-up list of the NSComboBox is going to be displayed.

    The notification object is the NSComboBox whose pop-up window will be displayed. This notification does not contain a userInfo dictionary.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.