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

Table of Contents

NSPopUpButtonCell


Inherits from:
NSMenuItemCell : NSButtonCell : NSActionCell : NSCell : NSObject
Package:
com.apple.yellow.application


Class Description


NSPopupButtonCell defines the visual appearance of popup buttons that display popup or pulldown lists. Popup lists present the user with a set of choices much in the way that radio buttons do but they do so using much less space. Pulldown lists 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.

Typically you do not create instances of NSPopUpButtonCell directly. Instead, you create an instance of NSPopUpButton which creates the appropriate cell. If you load your popup button from a nib file, the cell is similarly created for you when the popup button is initialized. You should not need to manipulate the interface of NSPopUpButtonCell directly. The methods of NSPopUpButton simply invoke methods of NSPopUpButtonCell to set or get the appropriate information.

To add items to a popup button cell's list, you can use the methods addItem, addItemsWithTitles, and insertItemAtIndex. These methods create or replace a menu item with the given title and assign it a default action and key equivalent. Once the item is added to the list, you must use the NSMenuItem interface to modify the attributes of the item. To remove one or more items, use the removeItemWithTitle, removeItemAtIndex, or removeAllItems method.


Popup and Pulldown List Displays


When the popup list is displayed, the popup-button cell displays the list on top of the popup button. The currently selected choice appears in the same location as the popup button with the other items arranged above or below the current selection according to the order of the cell's menu. When the popup list is dismissed, the title of the popup button changes to match the title of the currently selected item.

Pulldown lists typically display themselves adjacent to the popup button in the same way a submenu is displayed next to its parent item. Unlike popup lists, the title of a popup button displaying a pulldown list is not based on the currently selected item and thus remains fixed unless you change using the cell's setTitle method.

While popup lists are displayed on top of their button, the location of the pulldown list depends on the preferred edge, set through the cell's setPreferredEdge method. When drawing the list, the cell does its best to honor the preferred edge if there is enough space on the user's screen. If there is not enough space, the cell positions the list somewhere else.

NSPopupButtonCell uses an NSMenuView to draw the popup menu.


Pulldown List Indexes


Indexes for items in a pulldown list are a little different than indexes in popup lists or in the application's regular menus. Most lists and menus contain a set of n items (where n is some integer) with indexes running from 0 to n - 1. By default, both pulldown and popup lists obtain their title from a list item and therefore use this range of indexes. However, you can send a setUsesItemFromMenu message to the popup button, passing the value false, to disable this option. However, doing so causes the first item in a pulldown list to have the index 1. The reason for this is that the pulldown list uses the original first item (at index 0) to store the title of the popup button.

When using pulldown lists, you should never try to change the title of the popup button by accessing the menu item at index 0 directly. Instead, you should always use the cell's setTitle method to change the button's title.




Method Types


Constructors
NSPopUpButtonCell
Getting and setting attributes
setMenu
menu
setPullsDown
pullsDown
setAutoenablesItems
autoenablesItems
setPreferredEdge
preferredEdge
setUsesItemFromMenu
usesItemFromMenu
setAltersStateOfSelectedItem
altersStateOfSelectedItem
Adding and removing items
addItem
addItemsWithTitles
insertItemAtIndex
removeItemWithTitle
removeItemAtIndex
removeAllItems
Accessing the items
itemArray
numberOfItems
indexOfItem
indexOfItemWithTitle
indexOfItemWithTag
indexOfItemWithRepresentedObject
indexOfItemWithTargetAndAction
itemAtIndex
itemWithTitle
lastItem
Dealing with selection
selectItem
selectItemAtIndex
selectItemWithTitle
setTitle
selectedItem
indexOfSelectedItem
synchronizeTitleAndSelectedItem
Title conveniences
itemTitleAtIndex
itemTitles
titleOfSelectedItem
Handling events and action messages
attachPopUpWithFrameInView
dismissPopUp


Constructors



NSPopUpButtonCell

public NSPopUpButtonCell()

Description forthcoming.

public NSPopUpButtonCell(String aString)

Description forthcoming.

public NSPopUpButtonCell(NSImage anImage)

Description forthcoming.

public NSPopUpButtonCell( String aString, boolean flag)

Creates a new button with the title stringValue. If pullDown is true, the menu style is a pulldown menu, otherwise the menu is a pop-up menu. If stringValue contains a non-empty string, stringValue is used to create the first menu item in the menu. This menu item is assigned the default popup-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.

See Also: setAction (NSMenuItem), setTarget (NSMenuItem)




Instance Methods



addItem

public void addItem(String title)

Creates a new menu item with the specified title and adds it to the end of the menu. The menu item uses the popup button's default action and target, but you can change these using the setAction and setTarget methods of the corresponding NSMenuItem object.

See Also: addItemsWithTitles, setAction (NSMenuItem), setTarget (NSMenuItem)



addItemsWithTitles

public void addItemsWithTitles(NSArray itemTitles)

For each string in itemTitles, this method creates a new menu item and adds it to the end of the menu. The menu items use the popup button's default action and target, but you can change these using the setAction and setTarget methods of the corresponding NSMenuItem object.

See Also: addItem, setAction (NSMenuItem), setTarget (NSMenuItem)



altersStateOfSelectedItem

public boolean altersStateOfSelectedItem()

Returns true if the popup button cell sets the state of the selected menu item to NSCell.StateOn. This option is usually only used by popup menus. You typically do not alter the state of menu items in a pulldown menu.

See Also: selectItemAtIndex, selectItemWithTitle



arrowPosition

public int arrowPosition()

Description forthcoming.

attachPopUpWithFrameInView

public void attachPopUpWithFrameInView( NSRect cellFrame, NSView controlView)

Displays the popup button's menu, making adjustments as necessary to display the menu along the preferred edge of the cell if possible. The cellFrame parameter specifies the rectangle of the cell in the specified controlView to which the menu is to be attached. Before displaying the menu, this method sends the notification PopUpButtonCellWillPopUpNotification to both the controlView and to this cell. (The NSPopupButton object sends a corresponding PopUpButtonWillPopUpNotification notification.)

See Also: dismissPopUp, PopUpButtonCellWillPopUpNotification (notification)



autoenablesItems

public boolean autoenablesItems()

Returns whether the popup button's menu automatically enables and disables its menu items. By default NSMenu objects do autoenable their menu items.

See Also: setAutoenablesItems



dismissPopUp

public void dismissPopUp()

Dismisses the popup button's menu by ordering its window out. If the popup button was not displaying its menu, this method does nothing.

See Also: attachPopUpWithFrameInView, orderOut (NSWindow)



indexOfItem

public int indexOfItem(NSMenuItem item)

Returns the index of item. If item is null or cannot be found, this method returns -1.

See Also: indexOfItemWithRepresentedObject, indexOfItemWithTag, indexOfItemWithTargetAndAction, indexOfItemWithTitle, indexOfSelectedItem



indexOfItemWithRepresentedObject

public int indexOfItemWithRepresentedObject(Object obj)

Returns the index of the first menu item with the represented object specified by obj. If obj is null or if a menu item with the given represented object cannot be found, this method returns -1.

See Also: indexOfItem, indexOfItemWithTag, indexOfItemWithTargetAndAction, indexOfItemWithTitle, indexOfSelectedItem, representedObject (NSMenuItem), setRepresentedObject (NSMenuItem)



indexOfItemWithTag

public int indexOfItemWithTag(int tag)

Returns the index of the first menu item with the specified tag. If a menu item with tag cannot be found, this method returns -1.

Tags are values your application assigns to an object to identify it. You can assign tags to menu items using the setTag method of NSMenuItem.

See Also: indexOfItem, indexOfItemWithRepresentedObject, indexOfItemWithTargetAndAction, indexOfItemWithTitle, indexOfSelectedItem, setTag (NSMenuItem)



indexOfItemWithTargetAndAction

public int indexOfItemWithTargetAndAction( Object target, NSSelector actionSelector)

Returns the index of the first menu item that invokes the specified actionSelector on the given target. If a menu item with the given actionSelector and target cannot be found, this method returns -1.

NSPopupButtonCell assigns a default action and target to each menu item but you can change these values using the setAction and setTarget methods of NSMenuItem.

See Also: indexOfItem, indexOfItemWithRepresentedObject, indexOfItemWithTag, indexOfItemWithTargetAndAction, indexOfItemWithTitle, indexOfSelectedItem, setAction (NSMenuItem), setTarget (NSMenuItem)



indexOfItemWithTitle

public int indexOfItemWithTitle(String title)

Returns the index of the first menu item with the specified title. title must not be null. If title contains a string that does not match the title of any menu item, this method returns -1.

See Also: indexOfItem, indexOfItemWithRepresentedObject, indexOfItemWithTag, indexOfItemWithTargetAndAction, indexOfItemWithTitle, indexOfSelectedItem



indexOfSelectedItem

public int indexOfSelectedItem()

Returns the index of the currently selected menu item. If no menu item is selected, this method returns -1.

See Also: indexOfItem, indexOfItemWithRepresentedObject, indexOfItemWithTag, indexOfItemWithTargetAndAction, indexOfItemWithTitle



insertItemAtIndex

public void insertItemAtIndex( String title, int index)

Creates a new menu item with the specified title and inserts it into the array of menu items at index. 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 popup 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.

See Also: - insertObject:atIndex: (NSMutableArray), setAction (NSMenuItem), setTarget (NSMenuItem)



itemArray

public NSArray itemArray()

Returns the array of menu items associated with the menu.

See Also: - itemArray (NSMenu)



itemAtIndex

public NSMenuItem itemAtIndex(int index)

Returns the menu item at index. The value in index must refer to an existing menu item.

See Also: itemTitleAtIndex, itemAtIndex (NSMenu)



itemTitleAtIndex

public String itemTitleAtIndex(int index)

Returns the title of the menu item located at index.

See Also: itemAtIndex



itemTitles

public NSArray itemTitles()

Returns a mutable array of strings containing the titles of this popup button's menu items. If the menu contains separator items, the array contains an empty string ("") for each separator item.

See Also: itemTitleAtIndex



itemWithTitle

public NSMenuItem itemWithTitle(String aString)

Returns the first menu item whose title matches title, or null if no such item exists.

See Also: itemTitleAtIndex, itemAtIndex



lastItem

public NSMenuItem lastItem()

Returns the last menu item in the popup button's menu.

menu

public NSMenu menu()

Returns the menu object associated with the popup button.

See Also: setMenu



numberOfItems

public int numberOfItems()

Returns the number of menu items in the popup button's menu.

See Also: - count (NSArray)



performClickWithFrameinView

public void performClickWithFrameInView( NSRect frame, NSView controlView)

Description forthcoming.

preferredEdge

public int preferredEdge()

Returns the preferred edge on which to attach the menu. If no edge was set using the setPreferredEdge method, this method sets the preferred edge to the bottom edge of the popup button and returns that value.

See Also: setPreferredEdge



pullsDown

public boolean pullsDown()

Returns true if the menu is a pulldown-style menu, otherwise returns false.

See Also: setPullsDown



removeAllItems

public void removeAllItems()

Removes all of the popup button's menu items.

See Also: removeItemAtIndex, removeItemWithTitle, insertItemAtIndex



removeItemAtIndex

public void removeItemAtIndex(int index)

Removes the menu item at index from the popup button's menu. index must be a valid index into the array of menu items and therefore must not be negative.

See Also: removeAllItems, removeItemWithTitle, insertItemAtIndex



removeItemWithTitle

public void removeItemWithTitle(String title)

Removes the first menu item with the specified title from the popup button's menu. An assertion is triggered if the string in title does not correspond to an existing menu item.

See Also: removeAllItems, removeItemAtIndex, insertItemAtIndex



selectItem

public void selectItem(NSMenuItem item)

Makes item the currently selected menu item. If item is null, this method deselects the currently selected menu item.

By default, selecting or deselecting a menu item from a popup menu changes its state. Selecting a menu item from a pulldown menu does not automatically alter the state of the item. Use the setAltersStateOfSelectedItem method, passing it a value of false, to disassociate the current selection from the state of menu items.

See Also: selectedItem, selectItemAtIndex, selectItemWithTitle, setAltersStateOfSelectedItem, setState (NSMenuItem)



selectItemAtIndex

public void selectItemAtIndex(int index)

Makes the item at index the current selection. If index is -1, this method deselects the currently selected menu item.

By default, selecting or deselecting a menu item from a popup menu changes its state. Selecting a menu item from a pulldown menu does not automatically alter the state of the item. Use the setAltersStateOfSelectedItem method, passing it a value of false, to disassociate the current selection from the state of menu items.

See Also: selectedItem, selectItem, selectItemWithTitle, setAltersStateOfSelectedItem, setState (NSMenuItem)



selectItemWithTitle

public void selectItemWithTitle(String title)

Makes the first menu item with the given title the currently selected item. If title is null or contains a string that does not match the title of any menu item, this method deselects the currently selected menu item.

By default, selecting or deselecting a menu item changes its state. Use the setAltersStateOfSelectedItem method, passing it a value of false, to disassociate the current selection from the state of menu items.

See Also: selectedItem, selectItem, selectItemAtIndex, setAltersStateOfSelectedItem, setState (NSMenuItem)



selectedItem

public NSMenuItem selectedItem()

Returns the currently selected menu item or null of no menu item is selected.

See Also: selectItem, selectItemAtIndex, selectItemWithTitle



setAltersStateOfSelectedItem

public void setAltersStateOfSelectedItem(boolean flag)

If flag is false, this method disassociates the current selection from the state of menu items. Before disassociating the selection from the menu item state, this method first sets the state of the currently selected menu item to NSCell.StateOff. If flag is true, this method sets the state of the currently selected menu item to NSCell.StateOn.

See Also: altersStateOfSelectedItem, selectedItem, selectItem, selectItemAtIndex, setState (NSMenuItem)



setArrowPosition

public void setArrowPosition(int position)

Description forthcoming.

setAutoenablesItems

public void setAutoenablesItems(boolean flag)

Controls whether the popup button's menu automatically enables and disables its menu items. If flag is true, menu items are automatically enabled and disabled. If flag is false, menu items are not automatically enabled or disabled.

See Also: autoenablesItems



setMenu

public void setMenu(NSMenu menu)

Sets the menu object to be used by this popup button. If another menu was already associated with the popup button, this method releases the old menu. If you want to explicitly save the old menu, you should retain it before invoking this method.

See Also: menu



setPreferredEdge

public void setPreferredEdge(int edge)

Sets the edge of the popup button to which menus are attached. At display time, if attaching the menu to the preferred edge would cause part of the menu to be obscured, the popup button may use a different edge. If no preferred edge is set, the popup button uses the bottom edge by default.

See Also: preferredEdge



setPullsDown

public void setPullsDown(boolean flag)

Sets whether the popup button uses a popup or a pulldown menu. If flag is true, the popup button displays a pulldown menu, otherwise the popup button displays a popup menu. This method does not change the contents of the menu, it only changes the style of the menu.

When changing the menu type to a pulldown 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 NSCell.StateOff before changing the menu type.

See Also: pullsDown, synchronizeTitleAndSelectedItem



setTitle

public void setTitle(String aString)

For pulldown menus that get their titles from a menu item, this method simply sets the popup button cell's menu item to the first item in the menu. For popup 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 popup menu, and selects it.

See Also: initTextCell:pullsDown:



setUsesItemFromMenu

public void setUsesItemFromMenu(boolean flag)

Controls whether the popup button uses an item from the menu for its own purposes. For pulldown menus, the popup button uses the first menu item as its own title if flag is true. For popup menus, the popup button uses the title of the currently selected menu item; if no menu item is selected, the popup button displays no item and is drawn empty.

See Also: usesItemFromMenu



synchronizeTitleAndSelectedItem

public void synchronizeTitleAndSelectedItem()

For popup menus, this method sets the popup-button's menu item to the currently selected menu item or to the first menu item if none is selected. For pulldown menus, this method sets the item to the first menu item. If the popup button cell does not get its title from a menu item, this method does nothing.

If the popup button's menu does not contain any menu items, this method sets the popup button's item to null.



titleOfSelectedItem

public String titleOfSelectedItem()

Returns a string containing the title of the currently selected menu item or an empty string of no item is selected.

See Also: selectItemWithTitle



usesItemFromMenu

public boolean usesItemFromMenu()

Returns true if the popup button uses the title text of a menu item for its own title. If this option is set, pulldown menus use the title of the first menu item in the menu while popup menus use the title of the currently selected menu.

See Also: setUsesItemFromMenu




Notifications


PopUpButtonCellWillPopUpNotification

This notification contains a notification object but no userInfo dictionary. The notification object can be either a popup button or its enclosed popup-button cell.The notification is posted just before the popup 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.

Table of Contents