Mac Developer Library

Developer

AppKit Framework Reference NSPopUpButtonCell Class Reference

Options
Deployment Target:

On This Page
Language:

NSPopUpButtonCell

Inheritance


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.

The NSPopUpButtonCell class defines the visual appearance of pop-up buttons that display pop-up or pull-down menus. Pop-up menus present the user with a set of choices, much the way radio buttons do, but using much less space. Pull-down menus also provide a set of choices but present the information in a slightly different way, usually to provide a set of commands from which the user can choose.

The NSPopUpButtonCell class implements the user interface for the NSPopUpButton class.

Changes made to a menu (such as adding, removing, or changing the items) are not apparent while the menu is being displayed or interacted with.

  • Returns an NSPopUpButtonCell object initialized with the specified title.

    Declaration

    Swift

    init(textCell stringValue: String, pullsDown pullDown: Bool)

    Objective-C

    - (instancetype)initTextCell:(NSString *)stringValue pullsDown:(BOOL)pullDown

    Parameters

    stringValue

    The title of the first menu. You may specify an empty string if you do not want to add an initial menu item.

    pullDown

    YEStrue if you want the receiver to display a pull-down menu; otherwise, NOfalse if you want it to display a pop-up menu.

    Return Value

    An initialized NSPopUpButtonCell object, or nil if the object could not be initialized.

    Discussion

    This menu item is assigned the default pop-up button action that displays the menu. To set the action and target, use the setAction: and setTarget: methods of the item’s corresponding NSMenuItem object.

    This method is the designated initializer of the class.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – setAction: (NSMenuItem)
    – setTarget: (NSMenuItem)

  • menu menu Property

    The pop-up button’s associated menu.

    Declaration

    Swift

    var menu: NSMenu?

    Objective-C

    @property(strong) NSMenu *menu

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • pullsDown pullsDown Property

    A Boolean value that indicates the behavior of the button’s menu.

    Declaration

    Swift

    var pullsDown: Bool

    Objective-C

    @property BOOL pullsDown

    Discussion

    When the value of this property is YEStrue, the menu behaves like a pull-down menu; when the value is NOfalse, it behaves like a pop-up menu. If you use this property to change the menu type from a pop-up menu to a pull-down menu, and the cell alters the state of its selected items, the state of the currently selected item is set to NSOffState before the menu type is changed.

    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 button automatically enables and disables its items every time a user event occurs.

    Declaration

    Swift

    var autoenablesItems: Bool

    Objective-C

    @property BOOL autoenablesItems

    Discussion

    When the value of this property is YEStrue, the button automatically enables and disables items. The default value is YEStrue. For more information about enabling and disabling menu items, see NSMenuValidation.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The edge of the cell from which the menu should pop out when screen conditions are restrictive.

    Declaration

    Swift

    var preferredEdge: NSRectEdge

    Objective-C

    @property NSRectEdge preferredEdge

    Discussion

    At display time, if attaching the menu to the preferred edge would cause part of the menu to be obscured, the pop-up button may use a different edge. If no preferred edge is set, the pop-up button uses the bottom edge by default, which is NSMaxYEdge for flipped views or NSMinYEdge for unflipped views. Additional values for this property include NSMinXEdge and NSMaxXEdge.

    The exact location of the arrow is determined by examining the value of this property and arrowPosition.

    • If the arrow position is NSPopUpArrowAtCenter, the arrow stays in the center of the button and the value of this property determines which edge the arrow points to: NSMinXEdge points to the left, NSMaxYEdge points to the top, NSMaxXEdge points to the right, and NSMinYEdge points to the bottom.

    • If the arrow position is NSPopUpArrowAtBottom, the value of this property determines which edge at which the arrow is placed: NSMinXEdge places the arrow at the center of the left side, pointing to the left, NSMinYEdge places the arrow at bottom right corner, pointing up, NSMaxXEdge places the arrow at the center of the right side, pointing to the right, and NSMaxYEdge places the arrow at the bottom right corner, pointing down.

    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 control uses an item from the menu for its own title.

    Declaration

    Swift

    var usesItemFromMenu: Bool

    Objective-C

    @property BOOL usesItemFromMenu

    Discussion

    When the value of this property is YEStrue, a pull-down menu uses the title of the first menu item, and a pop-up menu uses the title of the currently selected menu (if no menu item is selected, the pop-up button displays no item and is drawn empty). When the value is NOfalse, the menu item set with setMenuItem: (NSMenuItem) is always displayed. The default value is YEStrue.

    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 pop-up button links the state of the selected menu item to the current selection.

    Declaration

    Swift

    var altersStateOfSelectedItem: Bool

    Objective-C

    @property BOOL altersStateOfSelectedItem

    Discussion

    When the value of this property is YEStrue (which is the default value), the state of the selected item is set to NSOnState. When the value of this property is NOfalse, the items in the menu are left alone. When you change the value of this property, the state of the currently selected item is updated appropriately.

    Note that this property affects only pop-up buttons (it is ignored for pull-down menus).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The position of the arrow displayed on the button.

    Declaration

    Swift

    var arrowPosition: NSPopUpArrowPosition

    Objective-C

    @property NSPopUpArrowPosition arrowPosition

    Discussion

    When the value of this property is NSPopUpNoArrow, the control displays no arrow. NSPopUpArrowAtCenter displays the arrow centered horizontally within the cell and NSPopUpArrowAtBottom displays the arrow at the edge of the cell. This property is used with preferredEdge to determine the exact location and orientation of the arrow.

    This property applies to only bezel style and borderless pop-up buttons.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Adds an item with the specified title to the end of the menu.

    Declaration

    Swift

    func addItemWithTitle(_ title: String)

    Objective-C

    - (void)addItemWithTitle:(NSString *)title

    Parameters

    title

    The title of the new menu item. If an item with the same title already exists in the menu, the existing item is removed and the new one is added.

    Discussion

    The menu item uses the pop-up button’s default action and target, but you can change these using the setAction: and setTarget: methods of the corresponding NSMenuItem object.

    Because this method searches for duplicate items, it should not be used if you are adding an item to an already populated menu with more than a few hundred items. In a situation like this, add items directly to the button's menu instead.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – addItemsWithTitles:
    – setAction: (NSMenuItem)
    – setTarget: (NSMenuItem)

  • Adds multiple items to the end of the menu.

    Declaration

    Swift

    func addItemsWithTitles(_ itemTitles: [AnyObject])

    Objective-C

    - (void)addItemsWithTitles:(NSArray *)itemTitles

    Parameters

    itemTitles

    An array of NSString objects containing the titles of the items you want to add. Each string in the array should be unique. If an item with the same title already exists in the menu, the existing item is removed and the new one is added.

    Discussion

    The new menu items use the pop-up button’s default action and target, but you can change these using the setAction: and setTarget: methods of the corresponding NSMenuItem object.

    If you want to move an item, it’s better to invoke removeItemWithTitle: explicitly and then call this method. After adding the items, this method uses the synchronizeTitleAndSelectedItem method to make sure the item being displayed matches the currently selected item.

    Because this method searches for duplicate items, it should not be used if you are adding items to an already populated menu with more than a few hundred items. In a situation like this, add items directly to the receiver's menu instead.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – addItemWithTitle:
    – setAction: (NSMenuItem)
    – setTarget: (NSMenuItem)

  • Inserts an item at the specified position in the menu.

    Declaration

    Swift

    func insertItemWithTitle(_ title: String, atIndex index: Int)

    Objective-C

    - (void)insertItemWithTitle:(NSString *)title atIndex:(NSInteger)index

    Parameters

    title

    The title of the new item. If an item with the same title already exists in the menu, the existing item is removed and the new one is added

    index

    The zero-based index at which to insert the item. Specifying 0 inserts the item at the top of the menu.

    Discussion

    The value in index must represent a valid position in the array. The menu item at index and all those that follow it are shifted down one slot to make room for the new menu item.

    This method assigns the pop-up button’s default action and target to the new menu item. Use the menu item’s setAction: and setTarget: methods to assign a new action and target.

    Because this method searches for duplicate items, it should not be used if you are adding an item to an already populated menu with more than a few hundred items. In a situation like this, add items directly to the button's menu instead.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    insertObject:atIndex: (NSMutableArray)
    – setAction: (NSMenuItem)
    – setTarget: (NSMenuItem)

  • Removes the item with the specified title from the menu.

    Declaration

    Swift

    func removeItemWithTitle(_ title: String)

    Objective-C

    - (void)removeItemWithTitle:(NSString *)title

    Parameters

    title

    The title of the item you want to remove. If no menu item exists with the specified title, this method triggers an assertion.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Removes the item at the specified index.

    Declaration

    Swift

    func removeItemAtIndex(_ index: Int)

    Objective-C

    - (void)removeItemAtIndex:(NSInteger)index

    Parameters

    index

    The zero-based index indicating which item to remove. Specifying 0 removes the item at the top of the menu. The index must be valid and non-negative.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Removes all items in the receiver’s item menu.

    Declaration

    Swift

    func removeAllItems()

    Objective-C

    - (void)removeAllItems

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Selects the specified menu item.

    Declaration

    Swift

    func selectItem(_ item: NSMenuItem?)

    Objective-C

    - (void)selectItem:(NSMenuItem *)item

    Parameters

    item

    The menu item to select, or nil if you want to deselect all menu items.

    Discussion

    By default, selecting or deselecting a menu item from a pop-up menu changes its state. Selecting a menu item from a pull-down menu does not automatically alter the state of the item. To disassociate the current selection from the state of menu items, set the altersStateOfSelectedItem property to NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Selects the item in the menu at the specified index.

    Declaration

    Swift

    func selectItemAtIndex(_ index: Int)

    Objective-C

    - (void)selectItemAtIndex:(NSInteger)index

    Parameters

    index

    The index of the item you want to select, or -1 you want to deselect all menu items.

    Discussion

    By default, selecting or deselecting a menu item from a pop-up menu changes its state. Selecting a menu item from a pull-down menu does not automatically alter the state of the item. To disassociate the current selection from the state of menu items, set the altersStateOfSelectedItem property to NOfalse.

    Subclassers can override this method to catch all select calls.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Selects the menu item with the specified tag.

    Declaration

    Swift

    func selectItemWithTag(_ tag: Int) -> Bool

    Objective-C

    - (BOOL)selectItemWithTag:(NSInteger)tag

    Parameters

    tag

    The tag of the item you want to select.

    Return Value

    YEStrue if the item was successfully selected; otherwise, NOfalse.

    Discussion

    If no item with the specified tag is found, this method returns NOfalse and leaves the menu state unchanged.

    You typically assign tags to menu items from Interface Builder, but you can also assign them programmatically using the setTag: method of NSMenuItem.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Selects the item with the specified title.

    Declaration

    Swift

    func selectItemWithTitle(_ title: String)

    Objective-C

    - (void)selectItemWithTitle:(NSString *)title

    Parameters

    title

    The title of the item to select. If you specify nil, an empty string, or a string that does not match the title of a menu item, this method deselects the currently selected item.

    Discussion

    By default, selecting or deselecting a menu item changes its state. To disassociate the current selection from the state of menu items, set the altersStateOfSelectedItem property to NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the string displayed in the receiver when the user isn’t pressing the mouse button.

    Declaration

    Swift

    func setTitle(_ aString: String)

    Objective-C

    - (void)setTitle:(NSString *)aString

    Parameters

    aString

    The string to display.

    Discussion

    For pull-down menus that get their titles from a menu item, this method simply sets the pop-up button cell’s menu item to the first item in the menu. For pop-up menus, if a menu item whose title matches aString exists, this method makes that menu item the current selection; otherwise, it creates a new menu item with the title aString, adds it to the pop-up menu, and selects it.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The menu item last selected by the user. (read-only)

    Declaration

    Swift

    var selectedItem: NSMenuItem? { get }

    Objective-C

    @property(readonly, strong) NSMenuItem *selectedItem

    Discussion

    The value of this property is the menu item that is currently selected, or nil if no item is selected. The last selected menu item is the one that was highlighted when the user released the mouse button. It is possible for a pull-down menu’s selected item to be its first item.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The index of the item last selected by the user. (read-only)

    Declaration

    Swift

    var indexOfSelectedItem: Int { get }

    Objective-C

    @property(readonly) NSInteger indexOfSelectedItem

    Discussion

    The value of this property is the index of the selected item, or -1 if no item is selected.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Synchronizes the the pop-up button’s displayed item with the currently selected menu item.

    Declaration

    Swift

    func synchronizeTitleAndSelectedItem()

    Objective-C

    - (void)synchronizeTitleAndSelectedItem

    Discussion

    If no item is currently selected, this method synchronizes the pop-up buttons displayed item with the first menu item. If the pop-up button cell does not get its displayed item from a menu item, this method does nothing.

    For pull-down menus, this method sets the displayed item to the title first menu item.

    If the pop-up button’s menu does not contain any menu items, this method sets the pop-up button’s displayed item to nil, resulting in nothing being displayed in the control.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the title of the item at the specified index.

    Declaration

    Swift

    func itemTitleAtIndex(_ index: Int) -> String

    Objective-C

    - (NSString *)itemTitleAtIndex:(NSInteger)index

    Parameters

    index

    The index of the item you want.

    Return Value

    The title of the item, or an empty string if no item exists at the specified index.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • An array of NSString objects containing the titles of every item in the menu. (read-only)

    Declaration

    Swift

    var itemTitles: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *itemTitles

    Discussion

    The titles appear in the order in which the items appear in the menu. If the menu contains separator items, the array contains an empty string (@"") for each separator item.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The title of the item last selected by the user. (read-only)

    Declaration

    Swift

    var titleOfSelectedItem: String? { get }

    Objective-C

    @property(readonly, copy) NSString *titleOfSelectedItem

    Discussion

    The value of this property is the title of the selected menu item, or an empty string if no item is selected.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • This method has no effect.

    Declaration

    Objective-C

    - (void)setImage:(NSImage *)anImage

    Parameters

    anImage

    The image to display.

    Discussion

    The image displayed in a pop up button is taken from the selected menu item (in the case of a pop up menu) or from the first menu item (in the case of a pull-down menu).

  • Sets up the receiver to display a menu.

    Declaration

    Swift

    func attachPopUpWithFrame(_ cellFrame: NSRect, inView controlView: NSView)

    Objective-C

    - (void)attachPopUpWithFrame:(NSRect)cellFrame inView:(NSView *)controlView

    Parameters

    cellFrame

    The cell's rectangle, specified in points in the coordinate system of the view in the controlView parameter. The menu is attached to this rectangle.

    controlView

    The view in which to display the pop-up button's menu.

    Discussion

    This call sets up the popup button cell to display a menu, which occurs in performClickWithFrame:inView:. This method sets the cell's control view and then highlights and redraws the cell. It does not show the menu.

    This method also posts an NSPopUpButtonCellWillPopUpNotification. (The NSPopUpButton object sends a corresponding NSPopUpButtonWillPopUpNotification.)

    You normally do not call this method explicitly. It is called by the Application Kit automatically when the menu for the pop-up button is to be displayed.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Dismisses the pop-up button’s menu by ordering its window out.

    Declaration

    Swift

    func dismissPopUp()

    Objective-C

    - (void)dismissPopUp

    Discussion

    If the pop-up button was not displaying its menu, this method does nothing.

    You normally do not call this method explicitly. It is called by the Application Kit automatically to dismiss the menu for the pop-up button.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Displays the receiver’s menu and track mouse events in it.

    Declaration

    Swift

    func performClickWithFrame(_ frame: NSRect, inView controlView: NSView)

    Objective-C

    - (void)performClickWithFrame:(NSRect)frame inView:(NSView *)controlView

    Parameters

    frame

    The cell's rectangle, specified in points in the coordinate system of the view in the controlView parameter.

    controlView

    The view in which to display the pop-up button's menu.

    Discussion

    You normally do not call this method explicitly. It is called by the Application Kit automatically to handle events in the pop-up button.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

Data Types

  • These constants are defined for use with the arrowPosition property.

    Declaration

    Swift

    enum NSPopUpArrowPosition : UInt { case NoArrow case ArrowAtCenter case ArrowAtBottom }

    Objective-C

    typedef enum { NSPopUpNoArrow = 0, NSPopUpArrowAtCenter = 1, NSPopUpArrowAtBottom = 2 } NSPopUpArrowPosition;

    Constants

    • NoArrow

      NSPopUpNoArrow

      Does not display any arrow in the control.

      Available in OS X v10.0 and later.

    • ArrowAtCenter

      NSPopUpArrowAtCenter

      Arrow is centered vertically, pointing toward the preferredEdge.

      Available in OS X v10.0 and later.

    • ArrowAtBottom

      NSPopUpArrowAtBottom

      Arrow is drawn at the edge of the button, pointing toward the preferredEdge.

      Available in OS X v10.0 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • This notification is posted just before an pop-up menu is attached to its window frame. You can use this notification to lazily construct your part’s menus, thus preventing unnecessary calculations until they are needed. The notification object can be either a pop-up button or its enclosed pop-up button cell. 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.