Developer Documentation
PATH  Mac OS X Documentation > Application Kit Reference: Java


[Previous] [Class List] [Next]

NSPopUpButton


Inherits from: NSButton : NSControl : NSView : NSResponder : NSObject
Conforms to: NSCoding
(NSResponder)
NSObject (NSObject)
Declared in: AppKit/NSPopUpButton.h



Class at a Glance


An NSPopUpButton object controls a pop-up list or a pull-down list, from which a user can select an item.

Principal Attributes


Creation



Interface Builder

Commonly Used Methods



selectedItem Returns the currently selected item.
indexOfSelectedItem Returns an integer identifying the currently selected item.
titleOfSelectedItem Returns a string identifying the currently selected item.


Class Description


The NSPopUpButton class defines objects that implement the pop-up and pull-down lists of the OpenStep graphical user interface. You normally create an NSPopUpButton using Interface Builder.

When configured to display a pop-up list, an NSPopUpButton contains a number of options and usually displays 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 or NSTableView 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 display isn't affected by the user's actions, and a pull-down list usually displays the first item in the list. 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.

The items in the pop-up list or pull-down list (referred to simply as a list in this class description) are objects that conform to the NSMenuItem interface. Thus, you can send any message defined in that protocol to any item in the list.

Using an NSPopUpButton

Although the NSPopUpButton class defines an initialization method and methods that set up the list created by this class, you usually don't invoke these methods in your program. The typical way to create an NSPopUpButton is to use Interface Builder. You can define the NSPopUpButton's target and action, as well as the targets and actions of each item in the NSPopUpButton's list, programmatically or through Interface Builder. The NSPopUpButton methods you use most often are the methods that tell you which item is selected.


Method Types


Initializing an NSPopUpButton
initWithFrame:pullsDown:
Setting the type of list
setPullsDown
pullsDown
setAutoenablesItems
autoenablesItems
Inserting and deleting Items
addItemWithTitle
addItemsWithTitles
insertItemAtIndex
removeAllItems
removeItemWithTitle
removeItemAtIndex
Getting the user's selection
selectedItem
titleOfSelectedItem
indexOfSelectedItem
Setting the current selection
selectItem
selectItemAtIndex
selectItemWithTitle
Getting menu items
numberOfItems
itemArray
itemAtIndex
itemTitleAtIndex
itemTitles
itemWithTitle
lastItem
Getting the indices of menu items
indexOfItem
indexOfItemWithTag
indexOfItemWithTitle
indexOfItemWithRepresentedObject
indexOfItemWithTargetAndAction
Setting the cell edge to pop out from in restricted situations
preferredEdge
setPreferredEdge
Setting the font
setFont:
Setting the title
setTitle
Setting the state
synchronizeTitleAndSelectedItem

Constructors


NSPopUpButton

public NSPopUpButton(NSRect aNSRect)

<<Description Forthcoming>>

public NSPopUpButton(NSRect frameRect, boolean aFlag)

Creates an NSPopUpButton, giving it the dimensions specified by frameRect. If flag is true, the receiver is initialized to operate as a pull-down list; otherwise, it operates as a pop-up list.

See Also: - pullsDown, - setPullsDown:



Instance Methods



addItemWithTitle

public void addItem(String title)

Adds an item named title to the end of the list. This method then calls synchronizeTitleAndSelectedItem to make sure the item displayed matches the currently selected item.

See Also: insertItemAtIndex, removeItemWithTitle, setTitle



addItemsWithTitles

public void addItemsWithTitles(NSArray itemTitles)

Adds multiple items to the end of the list. The titles for the new items are taken from the itemTitles array. Once the items are added, this method uses synchronizeTitleAndSelectedItem to make sure the item displayed matches the currently selected item.

See Also: insertItemAtIndex, removeAllItems, removeItemWithTitle



autoenablesItems

public boolean autoenablesItems()

Returns whether the NSPopUpButton automatically enables and disables its items every time a user event occurs. Autoenabling is turned on unless you send the message setAutoenablesItems with an argument of false to the NSPopUpButton. See the NSMenuActionResponder interfacei for more information on autoenabling menu items.

See Also: setAutoenablesItems



indexOfItem

public int indexOfItem(NSMenuItem anObject)

Returns the index of menu item anObject in the pop-up list or -1 if the menu item is not found. This method invokes the method of the same name of its NSPopUpButtonCell.

indexOfItemWithRepresentedObject

public int indexOfItemWithRepresentedObject(Object anObject)

Returns the index of the first menu item in the pop-up list that holds the represented object anObject, or -1 if no menu item with this object is found. Represented objects bear some direct relation to the title or image of a menu item; for example, an item entitled "100" might have a Number encapsulating that value as its represented object. This method invokes the method of the same name of its NSPopUpButtonCell.

indexOfItemWithTag

public int indexOfItemWithTag(int tag)

Returns the index of the first menu item in the pop-up list that has the tag value tag or -1 if the item is not found. This method invokes the method of the same name of its NSPopUpButtonCell.

indexOfItemWithTargetAndAction

public int indexOfItemWithTargetAndAction(Object target, NSSelector actionSelector)

Returns the index of the first menu item in the pop-up list that has the target target and the action actionSelector. If actionSelector is null, the index of the first menu item in the pop-up list that has target target is returned. If no menu item matching the above criteria is found, -1 is returned. This method invokes the method of the same name of its NSPopUpButtonCell.

indexOfItemWithTitle

public int indexOfItemWithTitle(String title)

Returns the index of the first item whose title matches title or -1 if no match is found.

indexOfSelectedItem

public int indexOfSelectedItem()

Returns the index of the item last selected by the user or -1 if there's no selected item.

See Also: selectedItem, titleOfSelectedItem



insertItemAtIndex

public void insertItemAtIndex(String title, int index)

Inserts an item with title title at position index in the list. Index 0 indicates the top item. Once the item is inserted, this method uses synchronizeTitleAndSelectedItem to make sure the item displayed matches the currently selected item.

If an item with the name title already exists in the list, it's removed and the new one is added. This essentially moves title to a new position. If you want to move an item, it's better to invoke removeItemWithTitle explicitly and then send this method.

See Also: addItemWithTitle, addItemsWithTitles, indexOfItemWithTitle, removeItemWithTitle



itemArray

public NSArray itemArray()

Returns the NSArray that holds the list's items. The NSPopUpButton's list is actually an NSArray of objects conforming to the NSMenuItem interface. Usually you access the list's items and modify the list by sending messages directly to the NSPopUpButton rather than accessing the NSArray.

See Also: itemAtIndex, insertItemAtIndex, removeItemAtIndex



itemAtIndex

public NSMenuItem itemAtIndex(int index)

Returns the list item at index. If there is no item at index, this method returns null.

See Also: itemWithTitle, lastItem



itemTitleAtIndex

public String itemTitleAtIndex(int index)

Returns the title of the item at index. If there is no item at index, this method returns the empty string.

See Also: itemTitles



itemTitles

public NSArray itemTitles()

Returns an NSArray object that holds the titles of all of the items in the list. The titles appear in the order in which the items appear in the list.

See Also: itemTitleAtIndex, itemWithTitle, numberOfItems



itemWithTitle

public NSMenuItem itemWithTitle(String title)

Returns the first item whose title is title. If there is no item with title, this method returns null.

See Also: addItemWithTitle, selectItemWithTitle, itemAtIndex, indexOfItemWithTitle



lastItem

public NSMenuItem lastItem()

Returns the last item in the list.

See Also: itemAtIndex



menu

public NSMenu menu()

<<Description Forthcoming>>

numberOfItems

public int numberOfItems()

Returns the number of items in the list.

See Also: lastItem



preferredEdge

public int preferredEdge()

Returns the edge of the receiver next to which the pop-up list is displayed under restrictive screen conditions. For pull-down lists, the default behavior is to display the list under the receiver. For most pop-up lists, NSPopUpButton attempts to show the selected item directly over the button.

See Also: setPreferredEdge



pullsDown

public boolean pullsDown()

Returns true if the receiver is configured as a pull-down list or false if it's configured as a pop-up list.

See Also: setPullsDown



removeAllItems

public void removeAllItems()

Removes all items in the receiver's item list. This method then uses synchronizeTitleAndSelectedItem to refresh the list.

See Also: numberOfItems, removeItemAtIndex, removeItemWithTitle



removeItemAtIndex

public void removeItemAtIndex(int index)

Removes the item at index. This method then uses synchronizeTitleAndSelectedItem to make sure the title displayed matches the currently selected item.

See Also: insertItemAtIndex, removeAllItems, removeItemWithTitle



removeItemWithTitle

public void removeItemWithTitle(String title)

Removes the first item named title. This method then uses synchronizeTitleAndSelectedItem to refresh the list.

See Also: addItemWithTitle, removeAllItems, removeItemAtIndex



selectedItem

public NSMenuItem selectedItem()

Returns the item last selected by the user (the item that was highlighted when the user released the mouse button). If there is no selected item, this method returns null. It is possible for a pull-down list's selected item to be its first item.

selectItem

public void selectItem(NSMenuItem aNSMenuItem)

Selects the menu item anObject in the pop-up list. If anObject is null, all items in the list are deselected (this is a technique for obtaining a pop-up list with no items selected).

selectItemAtIndex

public void selectItemAtIndex(int index)

Selects the item in the list at index and invokes synchronizeTitleAndSelectedItem to make sure the title displayed matches the currently selected item. If index is -1 all items in the list are deselected.

See Also: indexOfSelectedItem



selectItemWithTitle

public void selectItemWithTitle(String title)

Selects the first item with title and invokes synchronizeTitleAndSelectedItem to make sure the title displayed matches the currently selected item.

See Also: indexOfItemWithTitle, addItemWithTitle, setTitle



setAutoenablesItems

public void setAutoenablesItems(boolean flag)

Sets whether the NSPopUpButton automatically enables and disables its items every time a user event occurs. Autoenabling is turned on unless you specify false as the value for flag. See the NSMenuActionResponder interface for more information on autoenabling menu items.

See Also: autoenablesItems



setMenu

public void setMenu(NSMenu menu)

<<Description Forthcoming>>

setPreferredEdge

public void setPreferredEdge(int edge)

Sets the edge of the receiver next to which the pop-up list should appear under restrictive screen conditions. For pull-down lists, the default behavior is to display the list under the receiver. For most pop-up lists, NSPopUpButton attempts to show the selected item directly over the button.

See Also: preferredEdge



setPullsDown

public void setPullsDown(boolean flag)

Controls whether the receiver behaves as a pull-down or pop-up list. If flag is true, the receiver is configured as a pull-down list. If flag is false, the receiver is configured as a pop-up list.

See Also: initWithFrame:pullsDown:pullsDown



setTitle

public void setTitle(String aString)

<<Description Forthcoming>>

synchronizeTitleAndSelectedItem

public void synchronizeTitleAndSelectedItem()

Ensures that the item being displayed by the receiver agrees with 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 item to match. For pull-down lists, this method makes sure that the first item is being displayed (the NSPopUpButtonCell must be set to use the selected menu item, which happens by default).

See Also: itemArray



titleOfSelectedItem

public String titleOfSelectedItem()

Returns the title of the item last selected by the user or the empty string if there's no such item.

See Also: indexOfSelectedItem





Notifications


NSPopUpButtonWillPopUpNotification

Posted when the NSPopUpButton receives a mouse-down event; that is, when the user is about to select an item from the list. This notification contains a notification object but no userInfo dictionary. The notification object is the selected NSPopUpButton.



[Previous] [Next]