Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

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.

Target and Action 

- (SEL)action	Returns the NSPopUpButton's action method.

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

Adding Items 

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

Querying the NSPopUpButton about Its Items 

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

Manipulating the NSPopUpButton

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

Displaying the NSPopUpButton's Items 

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