Mac Developer Library

Developer

AppKit Framework Reference NSPopUpButton Class Reference

Options
Deployment Target:

On This Page
Language:

NSPopUpButton

Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.

The NSPopUpButton class defines objects that implement the pop-up and pull-down menus of the graphical user interface.

An NSPopUpButton object uses an NSPopUpButtonCell object to implement its user interface.

Note that while a menu is tracking user input, programmatic changes to the menu such as adding, removing, or changing items on the menu is not reflected.

  • Returns an NSPopUpButton object initialized to the specified dimensions.

    Declaration

    Swift

    init(frame frameRect: NSRect, pullsDown flag: Bool)

    Objective-C

    - (instancetype)initWithFrame:(NSRect)frameRect pullsDown:(BOOL)flag

    Parameters

    frameRect

    The frame rectangle for the button, specified in the parent view's coordinate system.

    flag

    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 NSPopUpButton object, or nil if the object could not be initialized.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    pullsDown

  • pullsDown pullsDown Property

    A Boolean value indicating whether the button displays a pull-down or pop-up menu.

    Declaration

    Swift

    var pullsDown: Bool

    Objective-C

    @property BOOL pullsDown

    Discussion

    When the value of this property is YEStrue, the button displays a pull-down menu; otherwise, it displays a pop-up menu. This property does not affect the contents of the menu; it affects only the style of the menu.

    When changing the menu type to a pull-down menu, if the menu was a pop-up menu and the cell alters the state of its selected items, this method sets the state of the currently selected item to NSStateOff before changing the menu type.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value indicating whether the button 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, user events cause the button to enable and disable its items automatically according to the NSMenuValidation protocol specification.

    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 menu-item entry. If an item with the same title already exists in the menu, the existing item is removed and the new one is added.

    Discussion

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

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

  • 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

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

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

  • 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

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

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

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

    Declaration

    Swift

    func removeAllItems()

    Objective-C

    - (void)removeAllItems

    Discussion

    After removing the items, this method uses the synchronizeTitleAndSelectedItem method to refresh the menu.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Discussion

    This method removes the first item it finds with the specified name. This method then uses synchronizeTitleAndSelectedItem to refresh the menu.

    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.

    Discussion

    After removing the item, this method uses the synchronizeTitleAndSelectedItem method to make sure the title displayed matches the currently selected item.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var selectedItem: NSMenuItem? { get }

    Objective-C

    @property(readonly, strong) NSMenuItem *selectedItem

    Discussion

    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. If no item is selected, the value in this property is nil.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var titleOfSelectedItem: String? { get }

    Objective-C

    @property(readonly, copy) NSString *titleOfSelectedItem

    Discussion

    If no item is selected, the value in this property is nil.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    selectedItem

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

    Declaration

    Swift

    var indexOfSelectedItem: Int { get }

    Objective-C

    @property(readonly) NSInteger indexOfSelectedItem

    Discussion

    If no item is selected, the value in this property is -1.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the index of the selected item.

    Declaration

    Objective-C

    - (id)objectValue

    Return Value

    An object (typically an NSNumber object) that responds to the intValue message and contains the index of the selected item.

  • The tag of the menu item that was last selected by the user. (read-only)

    Declaration

    Objective-C

    @property(readonly) NSInteger selectedTag

    Discussion

    Tags are integers that you assign to items to identify them in your code. Tags are not used by AppKit.

    If no menu item is selected, the value in this property is -1.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.10 and later.

  • Selects the specified menu item.

    Declaration

    Swift

    func selectItem(_ anObject: NSMenuItem?)

    Objective-C

    - (void)selectItem:(NSMenuItem *)anObject

    Parameters

    anObject

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

    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.

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Selects the item at a specific index using an object value.

    Declaration

    Objective-C

    - (void)setObjectValue:(id)object

    Parameters

    object

    An NSNumber object containing the index (an integer) of the item you want to select. Specify the index -1 to deselect all items. You can also use an object other than an NSNumber object. In that case, the object must respond to the intValue method and return an appropriate index value.

    Discussion

    See Also

    – objectValue

  • menu menu Property

    The menu associated with the pop-up button.

    Declaration

    Swift

    var menu: NSMenu?

    Objective-C

    @property(strong) NSMenu *menu

    Discussion

    If another menu was already associated with the pop-up button, this method releases its reference to the old menu.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The number of items in the menu. (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

    menu
    lastItem

  • itemArray itemArray Property

    The array of menu item objects associated with the button. (read-only)

    Declaration

    Swift

    var itemArray: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *itemArray

    Discussion

    This property contains an array of NSMenuItem objects representing the items in the menu. Usually, you access menu items using the methods and properties of this class rather than accessing the items directly.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the menu item at the specified index.

    Declaration

    Swift

    func itemAtIndex(_ index: Int) -> NSMenuItem?

    Objective-C

    - (NSMenuItem *)itemAtIndex:(NSInteger)index

    Parameters

    index

    The index of the item you want.

    Return Value

    The menu item, or nil 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.

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

    See Also

    itemTitles

  • An array of strings corresponding to the titles of the items in the menu. (read-only)

    Declaration

    Swift

    var itemTitles: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *itemTitles

    Discussion

    This property contains an array of NSString objects, each of which contains the title of an item in the menu. The order of the titles in this array matches the order of the items 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.

  • Returns the menu item with the specified title.

    Declaration

    Swift

    func itemWithTitle(_ title: String) -> NSMenuItem?

    Objective-C

    - (NSMenuItem *)itemWithTitle:(NSString *)title

    Parameters

    title

    The title of the menu item you want.

    Return Value

    The menu item, or nil if no item with the specified title exists in the menu.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • lastItem lastItem Property

    The last item in the menu. (read-only)

    Declaration

    Swift

    var lastItem: NSMenuItem? { get }

    Objective-C

    @property(readonly, strong) NSMenuItem *lastItem

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the index of the specified menu item.

    Declaration

    Swift

    func indexOfItem(_ anObject: NSMenuItem) -> Int

    Objective-C

    - (NSInteger)indexOfItem:(NSMenuItem *)anObject

    Parameters

    anObject

    The menu item whose index you want.

    Return Value

    The index of the item or -1 if no such item was found.

    Discussion

    This method invokes the method of the same name of its NSPopUpButtonCell object.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the index of the menu item with the specified tag.

    Declaration

    Swift

    func indexOfItemWithTag(_ tag: Int) -> Int

    Objective-C

    - (NSInteger)indexOfItemWithTag:(NSInteger)tag

    Parameters

    tag

    The tag of the menu item you want.

    Return Value

    The index of the item or -1 if no item with the specified tag was found.

    Discussion

    This method invokes the method of the same name of its NSPopUpButtonCell object.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func indexOfItemWithTitle(_ title: String) -> Int

    Objective-C

    - (NSInteger)indexOfItemWithTitle:(NSString *)title

    Parameters

    title

    The title of the item you want.

    Return Value

    The index of the item or -1 if no item with the specified title was found.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the index of the menu item that holds the specified represented object.

    Declaration

    Swift

    func indexOfItemWithRepresentedObject(_ anObject: AnyObject?) -> Int

    Objective-C

    - (NSInteger)indexOfItemWithRepresentedObject:(id)anObject

    Parameters

    anObject

    The represented object associated with a menu item.

    Return Value

    The index of the menu item that owns the specified object, or -1 if no such menu item was found.

    Discussion

    Represented objects bear some direct relation to the title or image of a menu item; for example, an item entitled “100” might have an NSNumber object encapsulating that value as its represented object. This method invokes the method of the same name of its NSPopUpButtonCell object.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the index of the menu item with the specified target and action.

    Declaration

    Swift

    func indexOfItemWithTarget(_ target: AnyObject?, andAction actionSelector: Selector) -> Int

    Objective-C

    - (NSInteger)indexOfItemWithTarget:(id)target andAction:(SEL)actionSelector

    Parameters

    target

    The target object associated with the menu item.

    actionSelector

    The action method associated with the menu item.

    Return Value

    The index of the menu item, or -1 if no menu item contains the specified target and action.

    Discussion

    If you specify NULL for the actionSelector parameter, the index of the first menu item with the specified target is returned. This method invokes the method of the same name of its NSPopUpButtonCell object.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The edge of the button on which to display the menu when screen space is constrained.

    Declaration

    Swift

    var preferredEdge: NSRectEdge

    Objective-C

    @property NSRectEdge preferredEdge

    Discussion

    Possible values include NSMinXEdge, NSMinYEdge, NSMaxXEdge, or NSMaxYEdge. For pull-down menus, the default behavior is to position the menu under the button. The bottom edge corresponds to the value NSMaxYEdge for flipped views or NSMinYEdge for unflipped views. For most pop-up menus, the NSPopUpButton object attempts to show the selected item directly over the button.

    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

    If the receiver displays a pop-up menu, this method changes the current item to be the item with the specified title, adding a new item by that name if one does not already exist. If the receiver displays a pull-down list, this method sets its title to the specified string.

    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 cell 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).

  • Ensures that the item being displayed by the receiver agrees with the selected item.

    Declaration

    Swift

    func synchronizeTitleAndSelectedItem()

    Objective-C

    - (void)synchronizeTitleAndSelectedItem

    Discussion

    If there’s no selected item, this method selects the first item in the item menu and sets the receiver’s item to match. For pull-down menus, this method makes sure that the first item is being displayed (the NSPopUpButtonCell object must be set to use the selected menu item, which happens by default).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Posted when an NSPopUpButton object receives a mouse-down event—that is, when the user is about to select an item from the menu.

    The notification object is the selected NSPopUpButton object. 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.