javax.swing
Class JPopupMenu

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              javax.swing.JPopupMenu

All Implemented Interfaces:

ImageObserver, MenuContainer, Serializable, Accessible, MenuElement

Direct Known Subclasses:

BasicComboPopup

public class JPopupMenu
extends JComponent
implements Accessible, MenuElement

An implementation of a popup menu -- a small window that pops up and displays a series of choices. A JPopupMenu is used for the menu that appears when the user selects an item on the menu bar. It is also used for "pull-right" menu that appears when the selects a menu item that activates it. Finally, a JPopupMenu can also be used anywhere else you want a menu to appear. For example, when the user right-clicks in a specified area.

For information and examples of using popup menus, see How to Use Menus in The Java Tutorial.

Warning: Swing is not thread safe. For more information see Swing's Threading Policy.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeans^TM has been added to the java.beans package. Please see XMLEncoder.

Nested Class Summary
protected  class	JPopupMenu.AccessibleJPopupMenu           This class implements accessibility support for the JPopupMenu class.
static class	JPopupMenu.Separator           A popup menu-specific separator.

 

Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent

 

Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer

 

Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy

 

Field Summary

 

Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

 

Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

 

Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

 

Constructor Summary
JPopupMenu()           Constructs a JPopupMenu without an "invoker".
JPopupMenu(String label)           Constructs a JPopupMenu with the specified title.

 

Method Summary
JMenuItem	add(Action a)           Appends a new menu item to the end of the menu which dispatches the specified Action object.
JMenuItem	add(JMenuItem menuItem)           Appends the specified menu item to the end of this menu.
JMenuItem	add(String s)           Creates a new menu item with the specified text and appends it to the end of this menu.
void	addMenuKeyListener(MenuKeyListener l)           Adds a MenuKeyListener to the popup menu.
void	addPopupMenuListener(PopupMenuListener l)           Adds a PopupMenu listener.
void	addSeparator()           Appends a new separator at the end of the menu.
protected  PropertyChangeListener	createActionChangeListener(JMenuItem b)           Returns a properly configured PropertyChangeListener which updates the control as changes to the Action occur.
protected  JMenuItem	createActionComponent(Action a)           Factory method which creates the JMenuItem for Actions added to the JPopupMenu.
protected  void	firePopupMenuCanceled()           Notifies PopupMenuListeners that this popup menu is cancelled.
protected  void	firePopupMenuWillBecomeInvisible()           Notifies PopupMenuListeners that this popup menu will become invisible.
protected  void	firePopupMenuWillBecomeVisible()           Notifies PopupMenuListeners that this popup menu will become visible.
AccessibleContext	getAccessibleContext()           Gets the AccessibleContext associated with this JPopupMenu.
Component	getComponent()           Returns this JPopupMenu component.
Component	getComponentAtIndex(int i)           Deprecated. replaced by Container.getComponent(int)
int	getComponentIndex(Component c)           Returns the index of the specified component.
static boolean	getDefaultLightWeightPopupEnabled()           Gets the defaultLightWeightPopupEnabled property, which by default is true.
Component	getInvoker()           Returns the component which is the 'invoker' of this popup menu.
String	getLabel()           Returns the popup menu's label
Insets	getMargin()           Returns the margin, in pixels, between the popup menu's border and its containees.
MenuKeyListener[]	getMenuKeyListeners()           Returns an array of all the MenuKeyListeners added to this JPopupMenu with addMenuKeyListener().
PopupMenuListener[]	getPopupMenuListeners()           Returns an array of all the PopupMenuListeners added to this JMenuItem with addPopupMenuListener().
SingleSelectionModel	getSelectionModel()           Returns the model object that handles single selections.
MenuElement[]	getSubElements()           Returns an array of MenuElements containing the submenu for this menu component.
PopupMenuUI	getUI()           Returns the look and feel (L&F) object that renders this component.
String	getUIClassID()           Returns the name of the L&F class that renders this component.
void	insert(Action a, int index)           Inserts a menu item for the specified Action object at a given position.
void	insert(Component component, int index)           Inserts the specified component into the menu at a given position.
boolean	isBorderPainted()           Checks whether the border should be painted.
boolean	isLightWeightPopupEnabled()           Gets the lightWeightPopupEnabled property.
boolean	isPopupTrigger(MouseEvent e)           Returns true if the MouseEvent is considered a popup trigger by the JPopupMenu's currently installed UI.
boolean	isVisible()           Returns true if the popup menu is visible (currently being displayed).
void	menuSelectionChanged(boolean isIncluded)           Messaged when the menubar selection changes to activate or deactivate this menu.
void	pack()           Lays out the container so that it uses the minimum space needed to display its contents.
protected  void	paintBorder(Graphics g)           Paints the popup menu's border if the borderPainted property is true.
protected  String	paramString()           Returns a string representation of this JPopupMenu.
protected  void	processFocusEvent(FocusEvent evt)           Processes focus events occurring on this component by dispatching them to any registered FocusListener objects.
protected  void	processKeyEvent(KeyEvent evt)           Processes key stroke events such as mnemonics and accelerators.
void	processKeyEvent(KeyEvent e, MenuElement[] path, MenuSelectionManager manager)           Processes a key event forwarded from the MenuSelectionManager and changes the menu selection, if necessary, by using MenuSelectionManager's API.
void	processMouseEvent(MouseEvent event, MenuElement[] path, MenuSelectionManager manager)           This method is required to conform to the MenuElement interface, but it not implemented.
void	remove(int pos)           Removes the component at the specified index from this popup menu.
void	removeMenuKeyListener(MenuKeyListener l)           Removes a MenuKeyListener from the popup menu.
void	removePopupMenuListener(PopupMenuListener l)           Removes a PopupMenu listener.
void	setBorderPainted(boolean b)           Sets whether the border should be painted.
static void	setDefaultLightWeightPopupEnabled(boolean aFlag)           Sets the default value of the lightWeightPopupEnabled property.
void	setInvoker(Component invoker)           Sets the invoker of this popup menu -- the component in which the popup menu menu is to be displayed.
void	setLabel(String label)           Sets the popup menu's label.
void	setLightWeightPopupEnabled(boolean aFlag)           Sets the value of the lightWeightPopupEnabled property, which by default is true.
void	setLocation(int x, int y)           Sets the location of the upper left corner of the popup menu using x, y coordinates.
void	setPopupSize(Dimension d)           Sets the size of the Popup window using a Dimension object.
void	setPopupSize(int width, int height)           Sets the size of the Popup window to the specified width and height.
void	setSelected(Component sel)           Sets the currently selected component, This will result in a change to the selection model.
void	setSelectionModel(SingleSelectionModel model)           Sets the model object to handle single selections.
void	setUI(PopupMenuUI ui)           Sets the L&F object that renders this component.
void	setVisible(boolean b)           Sets the visibility of the popup menu.
void	show(Component invoker, int x, int y)           Displays the popup menu at the position x,y in the coordinate space of the component invoker.
void	updateUI()           Resets the UI property to a value from the current look and feel.

 

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, unregisterKeyboardAction, update

 

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree

 

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle

 

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

 

Constructor Detail

JPopupMenu

public JPopupMenu()

Constructs a JPopupMenu without an "invoker".

JPopupMenu

public JPopupMenu(String label)

Constructs a JPopupMenu with the specified title.

Parameters:

label - the string that a UI may use to display as a title for the popup menu.

setDefaultLightWeightPopupEnabled

public static void setDefaultLightWeightPopupEnabled(boolean aFlag)

Sets the default value of the lightWeightPopupEnabled property.

Parameters:

aFlag - true if popups can be lightweight, otherwise false

See Also:

getDefaultLightWeightPopupEnabled(), setLightWeightPopupEnabled(boolean)

getDefaultLightWeightPopupEnabled

public static boolean getDefaultLightWeightPopupEnabled()

Gets the defaultLightWeightPopupEnabled property, which by default is true.

Returns:

the value of the defaultLightWeightPopupEnabled property

See Also:

setDefaultLightWeightPopupEnabled(boolean)

getUI

public PopupMenuUI getUI()

Returns the look and feel (L&F) object that renders this component.

Returns:

the PopupMenuUI object that renders this component

setUI

public void setUI(PopupMenuUI ui)

Sets the L&F object that renders this component.

Parameters:

ui - the new PopupMenuUI L&F object

See Also:

UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()

Resets the UI property to a value from the current look and feel.

Overrides:

updateUI in class JComponent

See Also:

JComponent.updateUI()

getUIClassID

public String getUIClassID()

Returns the name of the L&F class that renders this component.

Overrides:

getUIClassID in class JComponent

Returns:

the string "PopupMenuUI"

See Also:

JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

processFocusEvent

protected void processFocusEvent(FocusEvent evt)

Description copied from class: Component

Processes focus events occurring on this component by dispatching them to any registered FocusListener objects.

This method is not called unless focus events are enabled for this component. Focus events are enabled when one of the following occurs:

• A FocusListener object is registered via addFocusListener.
• Focus events are enabled via enableEvents.

If focus events are enabled for a Component, the current KeyboardFocusManager determines whether or not a focus event should be dispatched to registered FocusListener objects. If the events are to be dispatched, the KeyboardFocusManager calls the Component's dispatchEvent method, which results in a call to the Component's processFocusEvent method.

If focus events are enabled for a Component, calling the Component's dispatchEvent method with a FocusEvent as the argument will result in a call to the Component's processFocusEvent method regardless of the current KeyboardFocusManager.

Note that if the event parameter is null the behavior is unspecified and may result in an exception.

Overrides:

processFocusEvent in class Component

Parameters:

evt - the focus event

See Also:

FocusEvent, FocusListener, KeyboardFocusManager, Component.addFocusListener(java.awt.event.FocusListener), Component.enableEvents(long), Component.dispatchEvent(java.awt.AWTEvent)

processKeyEvent

protected void processKeyEvent(KeyEvent evt)

Processes key stroke events such as mnemonics and accelerators.

Overrides:

processKeyEvent in class JComponent

Parameters:

evt - the key event to be processed

See Also:

KeyEvent, KeyListener, KeyboardFocusManager, DefaultKeyboardFocusManager, Component.processEvent(java.awt.AWTEvent), Component.dispatchEvent(java.awt.AWTEvent), Component.addKeyListener(java.awt.event.KeyListener), Component.enableEvents(long), Component.isShowing()

getSelectionModel

public SingleSelectionModel getSelectionModel()

Returns the model object that handles single selections.

Returns:

the selectionModel property

See Also:

SingleSelectionModel

setSelectionModel

public void setSelectionModel(SingleSelectionModel model)

Sets the model object to handle single selections.

Parameters:

model - the new SingleSelectionModel

See Also:

SingleSelectionModel

add

public JMenuItem add(JMenuItem menuItem)

Appends the specified menu item to the end of this menu.

Parameters:

menuItem - the JMenuItem to add

Returns:

the JMenuItem added

add

public JMenuItem add(String s)

Creates a new menu item with the specified text and appends it to the end of this menu.

Parameters:

s - the string for the menu item to be added

add

public JMenuItem add(Action a)

Appends a new menu item to the end of the menu which dispatches the specified Action object.

Parameters:

a - the Action to add to the menu

Returns:

the new menu item

See Also:

Action

createActionComponent

protected JMenuItem createActionComponent(Action a)

Factory method which creates the JMenuItem for Actions added to the JPopupMenu.

Parameters:

a - the Action for the menu item to be added

Returns:

the new menu item

Since:

1.3

See Also:

Action

createActionChangeListener

protected PropertyChangeListener createActionChangeListener(JMenuItem b)

Returns a properly configured PropertyChangeListener which updates the control as changes to the Action occur.

remove

public void remove(int pos)

Removes the component at the specified index from this popup menu.

Overrides:

remove in class Container

Parameters:

pos - the position of the item to be removed

Throws:

IllegalArgumentException - if the value of pos < 0, or if the value of pos is greater than the number of items

See Also:

Container.add(java.awt.Component), Container.validate(), Container.getComponentCount()

setLightWeightPopupEnabled

public void setLightWeightPopupEnabled(boolean aFlag)

Sets the value of the lightWeightPopupEnabled property, which by default is true. By default, when a look and feel displays a popup, it can choose to use a lightweight (all-Java) popup. Lightweight popup windows are more efficient than heavyweight (native peer) windows, but lightweight and heavyweight components do not mix well in a GUI. If your application mixes lightweight and heavyweight components, you should disable lightweight popups. Some look and feels might always use heavyweight popups, no matter what the value of this property.

Parameters:

aFlag - false to disable lightweight popups

See Also:

isLightWeightPopupEnabled()

isLightWeightPopupEnabled

public boolean isLightWeightPopupEnabled()

Gets the lightWeightPopupEnabled property.

Returns:

the value of the lightWeightPopupEnabled property

See Also:

setLightWeightPopupEnabled(boolean)

getLabel

public String getLabel()

Returns the popup menu's label

Returns:

a string containing the popup menu's label

See Also:

setLabel(java.lang.String)

setLabel

public void setLabel(String label)

Sets the popup menu's label. Different look and feels may choose to display or not display this.

Parameters:

label - a string specifying the label for the popup menu

See Also:

setLabel(java.lang.String)

addSeparator

public void addSeparator()

Appends a new separator at the end of the menu.

insert

public void insert(Action a,
                   int index)

Inserts a menu item for the specified Action object at a given position.

Parameters:

a - the Action object to insert

index - specifies the position at which to insert the Action, where 0 is the first

Throws:

IllegalArgumentException - if index < 0

See Also:

Action

insert

public void insert(Component component,
                   int index)

Inserts the specified component into the menu at a given position.

Parameters:

component - the Component to insert

index - specifies the position at which to insert the component, where 0 is the first

Throws:

IllegalArgumentException - if index < 0

addPopupMenuListener

public void addPopupMenuListener(PopupMenuListener l)

Adds a PopupMenu listener.

Parameters:

l - the PopupMenuListener to add

removePopupMenuListener

public void removePopupMenuListener(PopupMenuListener l)

Removes a PopupMenu listener.

Parameters:

l - the PopupMenuListener to remove

getPopupMenuListeners

public PopupMenuListener[] getPopupMenuListeners()

Returns an array of all the PopupMenuListeners added to this JMenuItem with addPopupMenuListener().

Returns:

all of the PopupMenuListeners added or an empty array if no listeners have been added

Since:

1.4

addMenuKeyListener

public void addMenuKeyListener(MenuKeyListener l)

Adds a MenuKeyListener to the popup menu.

Parameters:

l - the MenuKeyListener to be added

Since:

1.5

removeMenuKeyListener

public void removeMenuKeyListener(MenuKeyListener l)

Removes a MenuKeyListener from the popup menu.

Parameters:

l - the MenuKeyListener to be removed

Since:

1.5

getMenuKeyListeners

public MenuKeyListener[] getMenuKeyListeners()

Returns an array of all the MenuKeyListeners added to this JPopupMenu with addMenuKeyListener().

Returns:

all of the MenuKeyListeners added or an empty array if no listeners have been added

Since:

1.5