javax.swing

Class JPopupMenu

public class JPopupMenu extends JComponent implements Accessible, MenuElement

JPopupMenu is a container that is used to display popup menu's menu items. By default JPopupMenu is a lightweight container, however if it is the case that JPopupMenu's bounds are outside of main window, then heawyweight container will be used to display menu items. It is also possible to change JPopupMenu's default behavior and set JPopupMenu to always use heavyweight container. JPopupMenu can be displayed anywhere; it is a floating free popup menu. However before JPopupMenu is diplayed, its invoker property should be set. JPopupMenu's invoker is a component relative to which popup menu is displayed. JPopupMenu fires PopupMenuEvents to its registered listeners. Whenever JPopupMenu becomes visible on the screen then PopupMenuEvent indicating that popup menu became visible will be fired. In the case when JPopupMenu becomes invisible or cancelled without selection, then popupMenuBecomeInvisible() or popupMenuCancelled() methods of PopupMenuListeners will be invoked. JPopupMenu also fires PropertyChangeEvents when its bound properties change.In addittion to inheritted bound properties, JPopupMenu has 'visible' bound property. When JPopupMenu becomes visible/invisible on the screen it fires PropertyChangeEvents to its registered PropertyChangeListeners.
Nested Class Summary
protected classJPopupMenu.AccessibleJPopupMenu
static classJPopupMenu.Separator
This is the separator that can be used in popup menu.
Field Summary
protected SingleSelectionModelselectionModel
SelectionModel that keeps track of menu selection.
Constructor Summary
JPopupMenu()
Creates a new JPopupMenu object.
JPopupMenu(String label)
Creates a new JPopupMenu with specified label
Method Summary
JMenuItemadd(JMenuItem item)
Adds given menu item to the popup menu
JMenuItemadd(String text)
Constructs menu item with a specified label and adds it to popup menu
JMenuItemadd(Action action)
Constructs menu item associated with the specified action and adds it to the popup menu
voidaddMenuKeyListener(MenuKeyListener l)
Adds a MenuKeyListener to the popup.
voidaddPopupMenuListener(PopupMenuListener listener)
Adds popupMenuListener to listen for PopupMenuEvents fired by the JPopupMenu
voidaddSeparator()
Adds separator to this popup menu
protected PropertyChangeListenercreateActionChangeListener(JMenuItem item)
Creates PropertyChangeListener that listens to PropertyChangeEvents occuring in the Action associated with given menu item in this popup menu.
protected JMenuItemcreateActionComponent(Action action)
Creates new menu item associated with a given action.
protected voidfirePopupMenuCanceled()
This method calls popupMenuCanceled() of popup menu's PopupMenuListeners.
protected voidfirePopupMenuWillBecomeInvisible()
This method calls popupMenuWillBecomeInvisible() of popup menu's PopupMenuListeners.
protected voidfirePopupMenuWillBecomeVisible()
This method calls popupMenuWillBecomeVisible() of popup menu's PopupMenuListeners.
AccessibleContextgetAccessibleContext()
DOCUMENT ME!
ComponentgetComponent()
Method of the MenuElement interface.
ComponentgetComponentAtIndex(int index)
Returns component located at the specified index in the popup menu
intgetComponentIndex(Component component)
Returns index of the specified component in the popup menu
static booleangetDefaultLightWeightPopupEnabled()
Returns flag indicating if newly created JPopupMenu will use heavyweight or lightweight container to display its menu items
ComponentgetInvoker()
Returns popup menu's invoker.
StringgetLabel()
Returns label for this popup menu
InsetsgetMargin()
Returns margin for this popup menu.
MenuKeyListener[]getMenuKeyListeners()
Returns array of getMenuKeyListeners that are listening to JPopupMenu.
PopupMenuListener[]getPopupMenuListeners()
Returns array of PopupMenuListeners that are listening to JPopupMenu
SingleSelectionModelgetSelectionModel()
Returns selectionModel used by this popup menu to keep track of the selection.
MenuElement[]getSubElements()
Return subcomonents of this popup menu.
PopupMenuUIgetUI()
This method returns the UI used to display the JPopupMenu.
StringgetUIClassID()
This method returns a name to identify which look and feel class will be the UI delegate for the menuItem.
voidinsert(Action action, int index)
Create menu item associated with the given action and inserts it into the popup menu at the specified index
voidinsert(Component component, int index)
Insert given component to the popup menu at the specified index
booleanisBorderPainted()
Checks if this popup menu paints its border.
booleanisLightWeightPopupEnabled()
Returns true if this popup menu will display its menu item in a lightweight container and false otherwise.
booleanisPopupTrigger(MouseEvent event)
Checks if observing mouse event should trigger popup menu to show on the screen.
booleanisVisible()
Return visibility of the popup menu
voidmenuSelectionChanged(boolean changed)
Method of MenuElement Interface.
voidpack()
This methods sets popup menu's size to its' preferred size.
protected StringparamString()
A string that describes this JPopupMenu.
voidprocessKeyEvent(KeyEvent event, MenuElement[] path, MenuSelectionManager manager)
Process key events forwarded from MenuSelectionManager.
voidprocessMouseEvent(MouseEvent event, MenuElement[] path, MenuSelectionManager manager)
Process mouse events forwarded from MenuSelectionManager.
voidremove(int index)
Revomes component at the given index from the menu.
voidremoveMenuKeyListener(MenuKeyListener l)
Removes a MenuKeyListener from the popup.
voidremovePopupMenuListener(PopupMenuListener listener)
Removes PopupMenuListener from JPopupMenu's list of listeners
voidsetBorderPainted(boolean painted)
Sets if the border of the popup menu should be painter or not.
static voidsetDefaultLightWeightPopupEnabled(boolean enabled)
Sets whether JPopupMenu should use ligthWeight container to display it menu items by default
voidsetInvoker(Component component)
Sets popup menu's invoker.
voidsetLabel(String label)
Sets label for this popup menu.
voidsetLightWeightPopupEnabled(boolean enabled)
DOCUMENT ME!
voidsetLocation(int x, int y)
Sets location of the popup menu.
voidsetPopupSize(Dimension size)
Sets size of the popup
voidsetPopupSize(int width, int height)
Sets size of the popup menu
voidsetSelected(Component selected)
Selects specified component in this popup menu.
voidsetSelectionModel(SingleSelectionModel model)
Sets selection model for this popup menu
voidsetUI(PopupMenuUI ui)
Set the "UI" property of the menu item, which is a look and feel class responsible for handling popupMenu's input events and painting it.
voidsetVisible(boolean visible)
Sets visibility property of this popup menu.
voidshow(Component component, int x, int y)
This method displays JPopupMenu on the screen at the specified location.
voidupdateUI()
This method sets this menuItem's UI to the UIManager's default for the current look and feel.

Field Detail

selectionModel

protected SingleSelectionModel selectionModel
SelectionModel that keeps track of menu selection.

Constructor Detail

JPopupMenu

public JPopupMenu()
Creates a new JPopupMenu object.

JPopupMenu

public JPopupMenu(String label)
Creates a new JPopupMenu with specified label

Parameters: label Label for popup menu.

Method Detail

add

public JMenuItem add(JMenuItem item)
Adds given menu item to the popup menu

Parameters: item menu item to add to the popup menu

Returns: menu item that was added to the popup menu

add

public JMenuItem add(String text)
Constructs menu item with a specified label and adds it to popup menu

Parameters: text label for the menu item to be added

Returns: constructed menu item that was added to the popup menu

add

public JMenuItem add(Action action)
Constructs menu item associated with the specified action and adds it to the popup menu

Parameters: action Action for the new menu item

Returns: menu item that was added to the menu

addMenuKeyListener

public void addMenuKeyListener(MenuKeyListener l)
Adds a MenuKeyListener to the popup.

Parameters: l - the listener to add.

addPopupMenuListener

public void addPopupMenuListener(PopupMenuListener listener)
Adds popupMenuListener to listen for PopupMenuEvents fired by the JPopupMenu

Parameters: listener PopupMenuListener to add to JPopupMenu

addSeparator

public void addSeparator()
Adds separator to this popup menu

createActionChangeListener

protected PropertyChangeListener createActionChangeListener(JMenuItem item)
Creates PropertyChangeListener that listens to PropertyChangeEvents occuring in the Action associated with given menu item in this popup menu.

Parameters: item MenuItem

Returns: The PropertyChangeListener

createActionComponent

protected JMenuItem createActionComponent(Action action)
Creates new menu item associated with a given action.

Parameters: action Action used to create new menu item

Returns: new created menu item associated with a given action.

firePopupMenuCanceled

protected void firePopupMenuCanceled()
This method calls popupMenuCanceled() of popup menu's PopupMenuListeners. This method is invoked just before popup menu is cancelled. This happens when popup menu is closed without selecting any of its menu items. This usually happens when the top-level window is resized or moved.

firePopupMenuWillBecomeInvisible

protected void firePopupMenuWillBecomeInvisible()
This method calls popupMenuWillBecomeInvisible() of popup menu's PopupMenuListeners. This method is invoked just before popup menu will disappear from the screen

firePopupMenuWillBecomeVisible

protected void firePopupMenuWillBecomeVisible()
This method calls popupMenuWillBecomeVisible() of popup menu's PopupMenuListeners. This method is invoked just before popup menu will appear on the screen.

getAccessibleContext

public AccessibleContext getAccessibleContext()
DOCUMENT ME!

Returns: DOCUMENT ME!

getComponent

public Component getComponent()
Method of the MenuElement interface. Returns reference to itself.

Returns: Returns reference to itself

getComponentAtIndex

public Component getComponentAtIndex(int index)

Deprecated: Replaced by getComponent(int)

Returns component located at the specified index in the popup menu

Parameters: index index of the component to return

Returns: component located at the specified index in the popup menu

getComponentIndex

public int getComponentIndex(Component component)
Returns index of the specified component in the popup menu

Parameters: component Component to look for

Returns: index of the specified component in the popup menu

getDefaultLightWeightPopupEnabled

public static boolean getDefaultLightWeightPopupEnabled()
Returns flag indicating if newly created JPopupMenu will use heavyweight or lightweight container to display its menu items

Returns: true if JPopupMenu will use lightweight container to display menu items by default, and false otherwise.

getInvoker

public Component getInvoker()
Returns popup menu's invoker.

Returns: popup menu's invoker

getLabel

public String getLabel()
Returns label for this popup menu

Returns: label for this popup menu

getMargin

public Insets getMargin()
Returns margin for this popup menu.

Returns: margin for this popup menu.

getMenuKeyListeners

public MenuKeyListener[] getMenuKeyListeners()
Returns array of getMenuKeyListeners that are listening to JPopupMenu.

Returns: array of getMenuKeyListeners that are listening to JPopupMenu

getPopupMenuListeners

public PopupMenuListener[] getPopupMenuListeners()
Returns array of PopupMenuListeners that are listening to JPopupMenu

Returns: Array of PopupMenuListeners that are listening to JPopupMenu

getSelectionModel

public SingleSelectionModel getSelectionModel()
Returns selectionModel used by this popup menu to keep track of the selection.

Returns: popup menu's selection model

getSubElements

public MenuElement[] getSubElements()
Return subcomonents of this popup menu. This method returns only components that implement the MenuElement interface.

Returns: array of menu items belonging to this popup menu

getUI

public PopupMenuUI getUI()
This method returns the UI used to display the JPopupMenu.

Returns: The UI used to display the JPopupMenu.

getUIClassID

public String getUIClassID()
This method returns a name to identify which look and feel class will be the UI delegate for the menuItem.

Returns: The Look and Feel classID. "PopupMenuUI"

insert

public void insert(Action action, int index)
Create menu item associated with the given action and inserts it into the popup menu at the specified index

Parameters: action Action for the new menu item index index in the popup menu at which to insert new menu item.

insert

public void insert(Component component, int index)
Insert given component to the popup menu at the specified index

Parameters: component Component to insert index Index at which to insert given component

isBorderPainted

public boolean isBorderPainted()
Checks if this popup menu paints its border.

Returns: true if this popup menu paints its border and false otherwise.

isLightWeightPopupEnabled

public boolean isLightWeightPopupEnabled()
Returns true if this popup menu will display its menu item in a lightweight container and false otherwise.

Returns: true if this popup menu will display its menu items in a lightweight container and false otherwise.

isPopupTrigger

public boolean isPopupTrigger(MouseEvent event)
Checks if observing mouse event should trigger popup menu to show on the screen.

Parameters: event MouseEvent to check

Returns: true if the observing mouse event is popup trigger and false otherwise

isVisible

public boolean isVisible()
Return visibility of the popup menu

Returns: true if popup menu is visible on the screen and false otherwise.

menuSelectionChanged

public void menuSelectionChanged(boolean changed)
Method of MenuElement Interface. It is invoked when popupMenu's selection has changed

Parameters: changed true if this popupMenu is part of current menu hierarchy and false otherwise.

pack

public void pack()
This methods sets popup menu's size to its' preferred size. If the popup menu's size is previously set it will be ignored.

paramString

protected String paramString()
A string that describes this JPopupMenu. Normally only used for debugging.

Returns: A string describing this JMenuItem

processKeyEvent

public void processKeyEvent(KeyEvent event, MenuElement[] path, MenuSelectionManager manager)
Process key events forwarded from MenuSelectionManager. This method doesn't do anything. It is here to conform to the MenuElement interface.

Parameters: event event forwarded from MenuSelectionManager path path to the menu element from which event was generated manager MenuSelectionManager for the current menu hierarchy

processMouseEvent

public void processMouseEvent(MouseEvent event, MenuElement[] path, MenuSelectionManager manager)
Process mouse events forwarded from MenuSelectionManager. This method doesn't do anything. It is here to conform to the MenuElement interface.

Parameters: event event forwarded from MenuSelectionManager path path to the menu element from which event was generated manager MenuSelectionManager for the current menu hierarchy

remove

public void remove(int index)
Revomes component at the given index from the menu.

Parameters: index index of the component that will be removed in the menu

removeMenuKeyListener

public void removeMenuKeyListener(MenuKeyListener l)
Removes a MenuKeyListener from the popup.

Parameters: l - the listener to remove.

removePopupMenuListener

public void removePopupMenuListener(PopupMenuListener listener)
Removes PopupMenuListener from JPopupMenu's list of listeners

Parameters: listener PopupMenuListener which needs to be removed

setBorderPainted

public void setBorderPainted(boolean painted)
Sets if the border of the popup menu should be painter or not.

Parameters: painted true if the border should be painted and false otherwise

setDefaultLightWeightPopupEnabled

public static void setDefaultLightWeightPopupEnabled(boolean enabled)
Sets whether JPopupMenu should use ligthWeight container to display it menu items by default

Parameters: enabled true if JPopupMenu should use lightweight container for displaying its menu items, and false otherwise.

setInvoker

public void setInvoker(Component component)
Sets popup menu's invoker.

Parameters: component The new invoker of this popup menu

setLabel

public void setLabel(String label)
Sets label for this popup menu. This method fires PropertyChangeEvent when the label property is changed. Please note that most of the Look & Feel will ignore this property.

Parameters: label label for this popup menu

setLightWeightPopupEnabled

public void setLightWeightPopupEnabled(boolean enabled)
DOCUMENT ME!

Parameters: enabled DOCUMENT ME!

setLocation

public void setLocation(int x, int y)
Sets location of the popup menu.

Parameters: x X coordinate of the popup menu's location y Y coordinate of the popup menu's location

setPopupSize

public void setPopupSize(Dimension size)
Sets size of the popup

Parameters: size Dimensions representing new size of the popup menu

setPopupSize

public void setPopupSize(int width, int height)
Sets size of the popup menu

Parameters: width width for the new size height height for the new size

setSelected

public void setSelected(Component selected)
Selects specified component in this popup menu.

Parameters: selected component to select

setSelectionModel

public void setSelectionModel(SingleSelectionModel model)
Sets selection model for this popup menu

Parameters: model new selection model of this popup menu

setUI

public void setUI(PopupMenuUI ui)
Set the "UI" property of the menu item, which is a look and feel class responsible for handling popupMenu's input events and painting it.

Parameters: ui The new "UI" property

setVisible

public void setVisible(boolean visible)
Sets visibility property of this popup menu. If the property is set to true then popup menu will be dispayed and popup menu will hide itself if visible property is set to false.

Parameters: visible true if popup menu will become visible and false otherwise.

show

public void show(Component component, int x, int y)
This method displays JPopupMenu on the screen at the specified location. Note that x and y coordinates given to this method should be expressed in terms of the popup menus' invoker.

Parameters: component Invoker for this popup menu x x-coordinate of the popup menu relative to the specified invoker y y-coordiate of the popup menu relative to the specified invoker

updateUI

public void updateUI()
This method sets this menuItem's UI to the UIManager's default for the current look and feel.