javax.swing
Class JPopupMenu

java.lang.Object
  |
  +--java.awt.Component
        |
        +--java.awt.Container
              |
              +--javax.swing.JComponent
                    |
                    +--javax.swing.JPopupMenu

Direct Known Subclasses:

BasicComboPopup

public class JPopupMenu

extends JComponent

implements Accessible, MenuElement

An implementation of a Popup Menu -- a small window which 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 the keyboard keys used by this component in the standard Look and Feel (L&F) renditions, see the JPopupMenu key assignments.

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. A future release of Swing will provide support for long term persistence.

See Also:

Serialized Form

Inner Class Summary

protected class	JPopupMenu.AccessibleJPopupMenu
static class	JPopupMenu.Separator A popupmenu-specific separator.

Inner classes inherited from class javax.swing.JComponent

JComponent.AccessibleJComponent

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

Constructor Summary

JPopupMenu()
Create a JPopupMenu without an "invoker".

JPopupMenu(String label)
Create a JPopupMenu with the specified title.

Method Summary

JMenuItem	add(Action a) Append a new menuitem 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 menuitem with the specified text and appends it to the end of this menu.
void	addPopupMenuListener(PopupMenuListener l) Add a PopupMenu listener param l the PopupMenuListener to add
void	addSeparator() Appends a new separator at the end of the menu.
protected PropertyChangeListener	createActionChangeListener(JMenuItem b)
protected void	firePopupMenuCanceled() Notifies PopupMenuListeners that this popup menu is canceled
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() Get the AccessibleContext associated with this JComponent
Component	getComponent() This method should return the java.awt.Component used to paint the receiving element.
Component	getComponentAtIndex(int i) Returns the component at the specified index.
int	getComponentIndex(Component c) Returns the index of the specified component.
static boolean	getDefaultLightWeightPopupEnabled() Return the default value for the lightWeightPopupEnabled property.
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 between the popupmenu's border and its containees.
SingleSelectionModel	getSelectionModel() Returns the model object that handles single selections.
MenuElement[]	getSubElements() This method should return an array containing the sub-elements for the receiving menu element
PopupMenuUI	getUI() Returns the 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() Returns true if lightweight (all-Java) popups are in use, or false if heavyweight (native peer) popups are being used.
boolean	isVisible() Returns true if the popupmenu is visible (currently being displayed).
void	menuSelectionChanged(boolean isIncluded) Call by the MenuSelection when the MenuElement is added or remove from the menu selection.
void	pack() Layout the container so that it uses the minimum space needed to display its contents.
protected void	paintBorder(Graphics g) Paint the popup menu's border if BorderPainted property is true.
protected String	paramString() Returns a string representation of this JPopupMenu.
void	processKeyEvent(KeyEvent e, MenuElement[] path, MenuSelectionManager manager) Process a key event.
void	processMouseEvent(MouseEvent event, MenuElement[] path, MenuSelectionManager manager) Process a mouse event.
void	remove(Component comp) Removes the specified component from this popup menu.
void	remove(int pos) Removes the component at the specified index from this popup menu.
void	removePopupMenuListener(PopupMenuListener l) Remove a PopupMenu listener param l the PopupMenuListener to remove
void	setBorderPainted(boolean b) Sets whether the border should be painted.
static void	setDefaultLightWeightPopupEnabled(boolean aFlag) Set the default value for the lightWeightPopupEnabled property.
void	setInvoker(Component invoker) Sets the invoker of this popupmenu -- the component in which the popupmenu menu is to be displayed.
void	setLabel(String label) Sets the popup menu's label.
void	setLightWeightPopupEnabled(boolean aFlag) When displaying the popup, JPopupMenu choose to use a light weight popup if it fits.
void	setLocation(int x, int y) Set 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) Set the model object to handle single selections.
void	setUI(PopupMenuUI ui) Sets the L&F object that renders this component.
void	setVisible(boolean b) Set the visibility of the popup menu.
void	show(Component invoker, int x, int y) Display the popupmenu at the position x,y in the coordinate space of the component invoker.
void	updateUI() Notification from the UIFactory that the L&F has changed.

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getAlignmentX, getAlignmentY, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getConditionForKeyStroke, getDebugGraphicsOptions, getGraphics, getHeight, getInsets, getInsets, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getVisibleRect, getWidth, getX, getY, grabFocus, hasFocus, isDoubleBuffered, isFocusCycleRoot, isFocusTraversable, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, paintComponent, paintImmediately, paintImmediately, processComponentKeyEvent, processFocusEvent, processKeyEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setDebugGraphicsOptions, setDoubleBuffered, setEnabled, setFont, setForeground, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setUI, unregisterKeyboardAction, update

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getLayout, insets, invalidate, isAncestorOf, layout, list, list, locate, minimumSize, paintComponents, preferredSize, print, printComponents, processContainerEvent, processEvent, removeAll, removeContainerListener, setCursor, setLayout, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getInputContext, getInputMethodRequests, getLocale, getLocation, getLocationOnScreen, getName, getParent, getPeer, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hide, imageUpdate, inside, isDisplayable, isEnabled, isLightweight, isShowing, isValid, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, printAll, processComponentEvent, processInputMethodEvent, processMouseEvent, remove, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setDropTarget, setLocale, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

JPopupMenu

public JPopupMenu()

Create a JPopupMenu without an "invoker".

JPopupMenu

public JPopupMenu(String label)

Create a JPopupMenu with the specified title.

Parameters:

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

Method Detail

setDefaultLightWeightPopupEnabled

public static void setDefaultLightWeightPopupEnabled(boolean aFlag)

Set the default value for the lightWeightPopupEnabled property.

getDefaultLightWeightPopupEnabled

public static boolean getDefaultLightWeightPopupEnabled()

Return the default value for the lightWeightPopupEnabled property.

getUI

public PopupMenuUI getUI()

Returns the 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()

Notification from the UIFactory that the L&F has changed. Called to replace the UI with the latest version from the UIFactory.

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:

"PopupMenuUI"

See Also:

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

getSelectionModel

public SingleSelectionModel getSelectionModel()

Returns the model object that handles single selections.

Returns:

the SingleSelectionModel in use

See Also:

SingleSelectionModel

setSelectionModel

public void setSelectionModel(SingleSelectionModel model)

Set the model object to handle single selections.

Parameters:

model - the SingleSelectionModel to use

See Also:

SingleSelectionModel

add

public JMenuItem add(JMenuItem menuItem)

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

Parameters:

c - the JMenuItem to add

Returns:

the JMenuItem added.

add

public JMenuItem add(String s)

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

Parameters:

s - the string for the menuitem to be added

add

public JMenuItem add(Action a)

Append a new menuitem to the end of the menu which dispatches the specified Action object.

Parameters:

a - the Action to add to the menu

See Also:

Action

remove

public void remove(Component comp)

Removes the specified component from this popup menu.

Overrides:

remove in class Container

Parameters:

item - the JMenuItem to be removed from the menu

remove

public void remove(int pos)

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

Overrides:

remove in class Container

Parameters:

index - the position of the item to be removed.

Throws:

IllegalArgumentException - if the value of index is less than 0.

createActionChangeListener

protected PropertyChangeListener createActionChangeListener(JMenuItem b)

setLightWeightPopupEnabled

public void setLightWeightPopupEnabled(boolean aFlag)

When displaying the popup, JPopupMenu choose to use a light weight popup if it fits. This method allows you to disable this feature. You have to do disable it if your application mixes light weight and heavy weights components.

isLightWeightPopupEnabled

public boolean isLightWeightPopupEnabled()

Returns true if lightweight (all-Java) popups are in use, or false if heavyweight (native peer) popups are being used.

Returns:

true if lightweight popups are in use

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:

component - the Action object to insert

index - an int specifying the position at which to insert the Action, where 0 is the first

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 - an int specifying the position at which to insert the component, where 0 is the first

addPopupMenuListener

public void addPopupMenuListener(PopupMenuListener l)

Add a PopupMenu listener param l the PopupMenuListener to add

removePopupMenuListener

public void removePopupMenuListener(PopupMenuListener l)

Remove a PopupMenu listener param l the PopupMenuListener to remove

firePopupMenuWillBecomeVisible

protected void firePopupMenuWillBecomeVisible()

Notifies PopupMenuListeners that this popup menu will become visible

firePopupMenuWillBecomeInvisible

protected void firePopupMenuWillBecomeInvisible()

Notifies PopupMenuListeners that this popup menu will become invisible

firePopupMenuCanceled

protected void firePopupMenuCanceled()

Notifies PopupMenuListeners that this popup menu is canceled

pack

public void pack()

Layout the container so that it uses the minimum space needed to display its contents.

setVisible

public void setVisible(boolean b)

Set the visibility of the popup menu.

Overrides:

setVisible in class JComponent

Parameters:

b - true to make the popup visible, or false to hide it

isVisible

public boolean isVisible()

Returns true if the popupmenu is visible (currently being displayed).

Overrides:

isVisible in class Component

Tags copied from class: Component

Returns:

true if the component is visible; false otherwise.

See Also:

Component.setVisible(boolean)

setLocation

public void setLocation(int x,
                        int y)

Set the location of the upper left corner of the popup menu using x, y coordinates.

Overrides:

setLocation in class Component

Parameters:

x - the x coordinate of the popup's new position

y - the y coordinate of the popup's new position

getInvoker

public Component getInvoker()

Returns the component which is the 'invoker' of this popup menu.

Returns:

the Component in which the popup menu is displayed

setInvoker

public void setInvoker(Component invoker)

Sets the invoker of this popupmenu -- the component in which the popupmenu menu is to be displayed.

Parameters:

invoker - the Component in which the popup menu is displayed

show

public void show(Component invoker,
                 int x,
                 int y)

Display the popupmenu at the position x,y in the coordinate space of the component invoker.

Parameters:

invoker - The component in whose space the popupmenu is to appear

x - the x coordinate in invoker's coordinate space at which the popup menu is to be displayed

y - the y coordinate in invoker's coordinate space at which the popup menu is to be displayed

getComponentAtIndex

public Component getComponentAtIndex(int i)

Returns the component at the specified index. This method is obsolete, please use getComponent(int i) instead.

Parameters:

i - the index of the component, where 0 is the first

Returns:

the Component at that index

getComponentIndex

public int getComponentIndex(Component c)

Returns the index of the specified component.

Parameters:

the - Component to find

Returns:

the index of the component, where 0 is the first, or -1 if the component is not found

setPopupSize

public void setPopupSize(Dimension d)

Sets the size of the Popup window using a Dimension object.

Parameters:

d - The dimension specifying the new size of this component.

setPopupSize

public void setPopupSize(int width,
                         int height)

Sets the size of the Popup window to the specified width and height.

Parameters:

width - The new width of the Popup in pixels.

height - The new height of the Popup in pixels.

setSelected

public void setSelected(Component sel)

Sets the currently selected component, This will result in a change to the selection model.

Parameters:

sel - the Component to select

isBorderPainted

public boolean isBorderPainted()

Checks whether the border should be painted.

Returns:

true if the border is painted

See Also:

setBorderPainted(boolean)

setBorderPainted

public void setBorderPainted(boolean b)

Sets whether the border should be painted.

Parameters:

b - if true, the border is painted.

See Also:

isBorderPainted()

paintBorder

protected void paintBorder(Graphics g)

Paint the popup menu's border if BorderPainted property is true.

Overrides:

paintBorder in class JComponent

See Also:

JComponent.paint(java.awt.Graphics), JComponent.setBorder(javax.swing.border.Border)

getMargin

public Insets getMargin()

Returns the margin between the popupmenu's border and its containees. return an Insets object containing the margin values.

paramString

protected String paramString()

Returns a string representation of this JPopupMenu. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:

paramString in class JComponent

Returns:

a string representation of this JPopupMenu.

getAccessibleContext

public AccessibleContext getAccessibleContext()

Get the AccessibleContext associated with this JComponent

Specified by:

getAccessibleContext in interface Accessible

Overrides:

getAccessibleContext in class JComponent

Returns:

the AccessibleContext of this JComponent

processMouseEvent

public void processMouseEvent(MouseEvent event,
                              MenuElement[] path,
                              MenuSelectionManager manager)

Description copied from interface: MenuElement

Process a mouse event. event is a MouseEvent with source being the receiving element's component. path is the path of the receiving element in the menu hierarchy including the receiving element itself. manager is the MenuSelectionManager for the menu hierarchy. This method should process the MouseEvent and change the menu selection if necessary by using MenuSelectionManager's API Note: you do not have to forward the event to sub-components. This is done automatically by the MenuSelectionManager

Specified by:

processMouseEvent in interface MenuElement

processKeyEvent

public void processKeyEvent(KeyEvent e,
                            MenuElement[] path,
                            MenuSelectionManager manager)

Description copied from interface: MenuElement

Process a key event.

Specified by:

processKeyEvent in interface MenuElement

menuSelectionChanged

public void menuSelectionChanged(boolean isIncluded)

Description copied from interface: MenuElement

Call by the MenuSelection when the MenuElement is added or remove from the menu selection.

Specified by:

menuSelectionChanged in interface MenuElement

getSubElements

public MenuElement[] getSubElements()

Description copied from interface: MenuElement

This method should return an array containing the sub-elements for the receiving menu element

Specified by:

getSubElements in interface MenuElement

Tags copied from interface: MenuElement

Returns:

an array of MenuElements

getComponent

public Component getComponent()

Description copied from interface: MenuElement

This method should return the java.awt.Component used to paint the receiving element. The returned component will be used to convert events and detect if an event is inside a MenuElement's component.

Specified by:

getComponent in interface MenuElement

Tags copied from interface: MenuElement

Returns:

the Component value