Inherits from: NSMenuItemCell : NSButtonCell : NSActionCell : NSCell : NSObject
Package: com.apple.yellow.application
The NSPopupButtonCell class is under development, so the descriptions for this class are currently incomplete. Those API and descriptions that are included in this class specification should be considered draft quality and subject to change.
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 addItemWithTitle, 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.
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 preffered edge if there is enough space on the user's screen. If there is not enough space, the cell positions the list somewhere else.
Unlike other menu-related classes implemented for Windows, NSPopupButtonCell uses an NSMenuView to draw the popup menu.
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 setTitlemethod to change the button's title.
- Initialization
- initTextCell:pullsDown:
- Getting and setting attributes
- setMenu
- menu
- setPullsDown:
- pullsDown
- setAutoenablesItems
- autoenablesItems
- setPreferredEdge
- preferredEdge
- setUsesItemFromMenu
- usesItemFromMenu
- setAltersStateOfSelectedItem
- altersStateOfSelectedItem
- Adding and removing items
- addItemWithTitle
- 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
- performClick:
public NSPopUpButtonCell(String aString)
public NSPopUpButtonCell(NSImage aNSImage)
public NSPopUpButtonCell(String aString, boolean flag)
See Also: - setAction: (NSMenuItem) - setTarget: (NSMenuItem)
public void addItem(String title)
See Also: addItemsWithTitles, - setAction: (NSMenuItem) - setTarget: (NSMenuItem)
public void addItemsWithTitles(NSArray itemTitles)
See Also: addItemWithTitle, - setAction: (NSMenuItem) - setTarget: (NSMenuItem)
public boolean altersStateOfSelectedItem()
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
public int arrowPosition()
public void attachPopUpWithFrameInView(NSRect cellFrame, NSView controlView)
See Also: dismissPopUp, NSPopUpButtonCellWillPopUpNotification (notification)
public boolean autoenablesItems()
See Also: setAutoenablesItems
public void dismissPopUp()
See Also: attachPopUpWithFrameInView, - orderOut: (NSWindow)
public int indexOfItem(NSMenuItem item)
null
or
cannot be found, this method returns -1.See Also: indexOfItemWithRepresentedObject, indexOfItemWithTag, indexOfItemWithTargetAndAction, indexOfItemWithTitle, indexOfSelectedItem
public int indexOfItemWithRepresentedObject(Object obj)
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)
public int indexOfItemWithTag(int tag)
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)
public int indexOfItemWithTargetAndAction(Object target, NSSelector actionSelector)
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)
public int indexOfItemWithTitle(String title)
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
public int indexOfSelectedItem()
See Also: indexOfItem, indexOfItemWithRepresentedObject, indexOfItemWithTag, indexOfItemWithTargetAndAction, indexOfItemWithTitle
public void insertItemAtIndex(String title, int index)
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)
public NSArray itemArray()
See Also: - itemArray (NSMenu)
public NSMenuItem itemAtIndex(int index)
See Also: itemTitleAtIndex, - itemAtIndex: (NSMenu)
public String itemTitleAtIndex(int index)
See Also: itemAtIndex
public NSArray itemTitles()
See Also: itemTitleAtIndex
public NSMenuItem itemWithTitle(String aString)
null
if
no such item exists.See Also: itemTitleAtIndex, itemAtIndex
public NSMenuItem lastItem()
public NSMenu menu()
See Also: setMenu
public int numberOfItems()
See Also: - count (NSArray)
public void performClickWithFrameInView(NSRect frame, NSView controlView)
public int preferredEdge()
See Also: setPreferredEdge
public boolean pullsDown()
true
if
the menu is a pulldown-style menu, otherwise returns false
.See Also: setPullsDown:
public void removeAllItems()
See Also: removeItemAtIndex, removeItemWithTitle, insertItemAtIndex
public void removeItemAtIndex(int index)
See Also: removeAllItems, removeItemWithTitle, insertItemAtIndex
public void removeItemWithTitle(String title)
See Also: removeAllItems, removeItemAtIndex, insertItemAtIndex
public NSMenuItem selectedItem()
null
of no menu item
is selected.See Also: selectItem, selectItemAtIndex, selectItemWithTitle
public void selectItem(NSMenuItem item)
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)
public void selectItemAtIndex(int index)
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)
public void selectItemWithTitle(String title)
null
or
contains a string that does not match the title of any menu item,
this method deselects the curently 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)
public void setAltersStateOfSelectedItem(boolean flag)
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)
public void setArrowPosition(int anInt)
public void setAutoenablesItems(boolean flag)
true
,
menu items are automatically enabled and disabled. If flag is false
,
menu items are not automatically enabled or disabled. See the NSMenuValidation interface specification
for more information.See Also: autoenablesItems
public void setMenu(NSMenu menu)
See Also: menu
public void setPreferredEdge(int edge)
See Also: preferredEdge
public void setPullsDown(boolean flag)
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
public void setTitle(String aString)
See Also: initTextCell:pullsDown:
public void setUsesItemFromMenu(boolean flag)
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
public void synchronizeTitleAndSelectedItem()
If the popup button's menu does not
contain any menu items, this method sets the popup button's item
to null
.
public String titleOfSelectedItem()
See Also: selectItemWithTitle
public boolean usesItemFromMenu()
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
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.