NSPopUpButton

Inherits From: NSButton : NSControl : NSView : NSResponder : NSObject

Conforms To: NSCoding (NSResponder) NSObject (NSObject)

Declared In: AppKit/NSPopUpButton.h

Class Description

The NSPopUpButton class defines objects that implement the pop-up and pull-down lists of the OpenStep graphical user interface. When configured to display a pop-up list, an NSPopUpButton contains a number of options and displays as its title the option that was last selected. A pop-up list is often used for selecting items from a small- to medium-sized set of options (like the zoom factor for a document window). It's a useful alternative to a matrix of radio buttons or an NSBrowser when screen space is at a premium; a zoom factor pop-up can easily fit next to a scroll bar at the bottom of a window, for example.

When configured to display a pull-down list, an NSPopUpButton is generally used for selecting commands in a very specific context. You can think of a pull-down list as a compact form of menu. A pull-down list's title isn't affected by the user's actions, and a pull-down list always displays a title that identifies the type of commands it contains. When the commands only make sense in the context of a particular display, a pull-down list can be used in that display to keep the related actions nearby, and to keep them out of the way when that display isn't visible.

Initializing an NSPopUpButton

• - (id)initWithFrame:(NSRect)frameRect Initializes a newly allocated NSPopUpButton, giving it the pullsDown:(BOOL)flag frame specified by frameRect. If flag is YES, the receiver is initialized to operate as a pull-down list; otherwise, it operates as a pop-up list.

• - (SEL)action Returns the NSPopUpButton's action method.
• - (void)setAction:(SEL)aSelector Sets the NSPopUpButton's action method to aSelector.

• - (void)addItemWithTitle:(NSString *)title Adds an item with title as its title to the end of the item list.
• - (void)addItemsWithTitles:(NSArray *)itemTitles Adds multiple items to the end of the item list. The titles for the new items are taken from the itemTitles array.
• - (void)insertItemWithTitle:(NSString *)title Inserts an item with title as its title at position index. atIndex:(unsigned int)index Removing Items
• - (void)removeAllItems Removes all items in the receiver's item list.
• - (void)removeItemWithTitle:(NSString *)title Removes the item whose title matches title.
• - (void)removeItemAtIndex:(int)index Removes the item at the specified index.

• - (int)indexOfItemWithTitle:(NSString *)title Returns the index of the item whose title matches title, or -1 if no match is found.
• - (int)indexOfSelectedItem Returns the index of the item last selected by the user, or -1 if there's no selected item.
• - (int)numberOfItems Returns the number of items in the receiver's item list.
• - (NSMenuCell *)itemAtIndex:(int)index Returns the NSMenuCell for the item at index, or nil if no such item exists.
• - (NSMatrix *)itemMatrix Returns the NSMatrix that holds the receiver's items.
• - (NSString *)itemTitleAtIndex:(int)index Returns the title of the item at index, or the empty string if no such item exists.
• - (NSArray *)itemTitles Returns an NSArray that holds the titles of the receiver's items.
• - (NSMenuCell *)itemWithTitle:(NSString *)title Returns the NSMenuCell for the item whose title is title, or nil if no such item exists
• - (NSMenuCell *)lastItem Returns the NSMenuCell corresponding to the last item in the list.
• - (NSMenuCell *)selectedItem Returns the NSMenuCell for the selected item.
• - (NSString *)titleOfSelectedItem Returns the title of the item last selected by the user, or the empty string if there's no such item.

• - (NSFont *)font Returns the font used to draw the items.
• - (BOOL)pullsDown Returns YES if the receiver is configured as a pull-down list, and NO if it's configured as a pop-up list.
• - (void)selectItemAtIndex:(int)index Selects the item at index and invokes synchronizeTitleAndSelectedItem.
• - (void)selectItemWithTitle:(NSString *)title Selects the item whose title is title and invokes synchronizeTitleAndSelectedItem.
• - (void)setFont:(NSFont *)fontObject Sets the font used to draw the items.
• - (void)setPullsDown:(BOOL)flag If flag is YES, the receiver is configured as a pull-down list. If flag is NO, the receiver is configured as a pop-up list.
• - (void)setTarget:(id)anObject Sets the target for action messages to anObject.
• - (void)setTitle:(NSString *)aString Adds a new item (if the receiver doesn't already have an item titled aString), makes it the selected item, and invokes synchronizeTitleAndSelectedItem.
• - (NSString *)stringValue Returns the title of the selected item.
• - (void)synchronizeTitleAndSelectedItem Ensures that the receiver's title agrees with the title of the selected item (see indexOfSelectedItem). If there's no selected item, this method selects the first item in the item list and sets the receiver's title to match. This method is useful in subclasses that directly select items in the item matrix or that override setTitle:.
• - (id)target Returns the target for action messages.

• - (BOOL)autoenablesItems Returns whether the NSPopUpButton enables and disables its items. (See the NSMenuActionResponder informal protocol.)
• - (void)setAutoenablesItems:(BOOL)flag Sets whether the NSPopUpButton enables and disables its items. (See the NSMenuActionResponder informal protocol.)