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
@JavaBean(defaultProperty="UI",description="A small window that pops up and displays a series of choices.")public classJPopupMenuextendsJComponentimplementsAccessible,MenuElement
An implementation of a popup menu -- a small window that pops up and displays a series of choices. AJPopupMenu 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, aJPopupMenu 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, seeHow to Use Menus inThe Java Tutorial.

Warning: Swing is not thread safe. For more information seeSwing'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 has been added to thejava.beans package. Please seeXMLEncoder.

Since:
1.2

  • Constructor Details

    • JPopupMenu

      public JPopupMenu()
      Constructs aJPopupMenu without an "invoker".

    • JPopupMenu

      public JPopupMenu(String label)
      Constructs aJPopupMenu with the specified title.
      Parameters:
      label - the string that a UI may use to display as a title for the popup menu.

  • Method Details

    • setDefaultLightWeightPopupEnabled

      public static void setDefaultLightWeightPopupEnabled(boolean aFlag)
      Sets the default value of thelightWeightPopupEnabled property.
      Parameters:
      aFlag -true if popups can be lightweight, otherwisefalse
      See Also:

    • getDefaultLightWeightPopupEnabled

      public static boolean getDefaultLightWeightPopupEnabled()
      Gets thedefaultLightWeightPopupEnabled property, which by default istrue.
      Returns:
      the value of thedefaultLightWeightPopupEnabled property
      See Also:

    • getUI

      public PopupMenuUI getUI()
      Returns the look and feel (L&F) object that renders this component.
      Overrides:
      getUI in class JComponent
      Returns:
      thePopupMenuUI object that renders this component

    • setUI

      @BeanProperty(hidden=true,visualUpdate=true,description="The UI object that implements the Component's LookAndFeel.")public void setUI(PopupMenuUI ui)
      Sets the L&F object that renders this component.
      Parameters:
      ui - the newPopupMenuUI L&F object
      See Also:

    • updateUI

      public void updateUI()
      Resets the UI property to a value from the current look and feel.
      Overrides:
      updateUI in class JComponent
      See Also:

    • getUIClassID

      @BeanProperty(bound=false)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:

    • processKeyEvent

    • getSelectionModel

      public SingleSelectionModel getSelectionModel()
      Returns the model object that handles single selections.
      Returns:
      theselectionModel property
      See Also:

    • setSelectionModel

      @BeanProperty(bound=false,expert=true,description="The selection model for the popup menu")public void setSelectionModel(SingleSelectionModel model)
      Sets the model object to handle single selections.
      Parameters:
      model - the newSingleSelectionModel
      See Also:

    • add

      public JMenuItem add(JMenuItem menuItem)
      Appends the specified menu item to the end of this menu.
      Parameters:
      menuItem - theJMenuItem to add
      Returns:
      theJMenuItem 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
      Returns:
      a newJMenuItem created usings

    • add

      public JMenuItem add(Action a)
      Appends a new menu item to the end of the menu which dispatches the specifiedAction object.
      Parameters:
      a - theAction to add to the menu
      Returns:
      the new menu item
      See Also:

    • createActionComponent

      protected JMenuItem createActionComponent(Action a)
      Factory method which creates theJMenuItem forActions added to theJPopupMenu.
      Parameters:
      a - theAction for the menu item to be added
      Returns:
      the new menu item
      Since:
      1.3
      See Also:

    • createActionChangeListener

      protected PropertyChangeListener createActionChangeListener(JMenuItem b)
      Returns a properly configuredPropertyChangeListener which updates the control as changes to theAction occur.
      Parameters:
      b - the menu item for which to create a listener
      Returns:
      a properly configuredPropertyChangeListener

    • 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 ofpos < 0, or if the value ofpos is greater than the number of items
      See Also:

    • setLightWeightPopupEnabled

      @BeanProperty(bound=false,expert=true,description="Determines whether lightweight popups are used when possible")public void setLightWeightPopupEnabled(boolean aFlag)
      Sets the value of thelightWeightPopupEnabled property, which by default istrue. 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

      public boolean isLightWeightPopupEnabled()
      Gets thelightWeightPopupEnabled property.
      Returns:
      the value of thelightWeightPopupEnabled property
      See Also:

    • getLabel

      public String getLabel()
      Returns the popup menu's label
      Returns:
      a string containing the popup menu's label
      See Also:

    • setLabel

      @BeanProperty(description="The label for the popup menu.")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:

    • 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 specifiedAction object at a given position.
      Parameters:
      a - theAction object to insert
      index - specifies the position at which to insert theAction, where 0 is the first
      Throws:
      IllegalArgumentException - ifindex < 0
      See Also:

    • insert

      public void insert(Component component, int index)
      Inserts the specified component into the menu at a given position.
      Parameters:
      component - theComponent to insert
      index - specifies the position at which to insert the component, where 0 is the first
      Throws:
      IllegalArgumentException - ifindex < 0

    • addPopupMenuListener

      public void addPopupMenuListener(PopupMenuListener l)
      Adds aPopupMenu listener.
      Parameters:
      l - thePopupMenuListener to add

    • removePopupMenuListener

      public void removePopupMenuListener(PopupMenuListener l)
      Removes aPopupMenu listener.
      Parameters:
      l - thePopupMenuListener to remove

    • getPopupMenuListeners

      @BeanProperty(bound=false)public PopupMenuListener[] getPopupMenuListeners()
      Returns an array of all thePopupMenuListeners added to this JMenuItem with addPopupMenuListener().
      Returns:
      all of thePopupMenuListeners added or an empty array if no listeners have been added
      Since:
      1.4

    • addMenuKeyListener

      public void addMenuKeyListener(MenuKeyListener l)
      Adds aMenuKeyListener to the popup menu.
      Parameters:
      l - theMenuKeyListener to be added
      Since:
      1.5

    • removeMenuKeyListener

      public void removeMenuKeyListener(MenuKeyListener l)
      Removes aMenuKeyListener from the popup menu.
      Parameters:
      l - theMenuKeyListener to be removed
      Since:
      1.5

    • getMenuKeyListeners

      @BeanProperty(bound=false)public MenuKeyListener[] getMenuKeyListeners()
      Returns an array of all theMenuKeyListeners added to this JPopupMenu with addMenuKeyListener().
      Returns:
      all of theMenuKeyListeners added or an empty array if no listeners have been added
      Since:
      1.5

    • firePopupMenuWillBecomeVisible

      protected void firePopupMenuWillBecomeVisible()
      NotifiesPopupMenuListeners that this popup menu will become visible.

    • firePopupMenuWillBecomeInvisible

      protected void firePopupMenuWillBecomeInvisible()
      NotifiesPopupMenuListeners that this popup menu will become invisible.

    • firePopupMenuCanceled

      protected void firePopupMenuCanceled()
      NotifiesPopupMenuListeners that this popup menu is cancelled.

    • pack

      public void pack()
      Lays out the container so that it uses the minimum space needed to display its contents.

    • setVisible

      @BeanProperty(description="Makes the popup visible")public void setVisible(boolean b)
      Sets the visibility of the popup menu.
      Overrides:
      setVisible in class JComponent
      Parameters:
      b - true to make the popup visible, or false to hide it
      See Also:

    • isVisible

      public boolean isVisible()
      Returns true if the popup menu is visible (currently being displayed).
      Overrides:
      isVisible in class Component
      Returns:
      true if the component is visible,false otherwise
      See Also:

    • setLocation

      @BeanProperty(description="The location of the popup menu.")public void setLocation(int x, int y)
      Sets the location of the upper left corner of the popup menu using x, y coordinates.

      The method changes the geometry-related data. Therefore, the native windowing system may ignore such requests, or it may modify the requested data, so that theJPopupMenu object is placed and sized in a way that corresponds closely to the desktop settings.

      Overrides:
      setLocation in class Component
      Parameters:
      x - the x coordinate of the popup's new position in the screen's coordinate space
      y - the y coordinate of the popup's new position in the screen's coordinate space
      See Also:

    • getInvoker

      public Component getInvoker()
      Returns the component which is the 'invoker' of this popup menu.
      Returns:
      theComponent in which the popup menu is displayed

    • setInvoker

      @BeanProperty(bound=false,expert=true,description="The invoking component for the popup menu")public void setInvoker(Component invoker)
      Sets the invoker of this popup menu -- the component in which the popup menu is to be displayed.
      Parameters:
      invoker - theComponent in which the popup menu is displayed

    • show

      public 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.
      Parameters:
      invoker - the component in whose space the popup menu 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

      @Deprecatedpublic Component getComponentAtIndex(int i)
      Deprecated.
      Returns the component at the specified index.
      Parameters:
      i - the index of the component, where 0 is the first
      Returns:
      theComponent at that index

    • getComponentIndex

      public int getComponentIndex(Component c)
      Returns the index of the specified component.
      Parameters:
      c - theComponent to find
      Returns:
      the index of the component, where 0 is the first; or -1 if the component is not found

    • setPopupSize

      @BeanProperty(description="The size of the popup menu")public void setPopupSize(Dimension d)
      Sets the size of the Popup window using aDimension object. This is equivalent tosetPreferredSize(d).
      Parameters:
      d - theDimension specifying the new size of this component.

    • setPopupSize

      @BeanProperty(description="The size of the popup menu")public void setPopupSize(int width, int height)
      Sets the size of the Popup window to the specified width and height. This is equivalent tosetPreferredSize(new Dimension(width, height)).
      Parameters:
      width - the new width of the Popup in pixels
      height - the new height of the Popup in pixels

    • setSelected

      @BeanProperty(expert=true,hidden=true,description="The selected component on the popup menu")public void setSelected(Component sel)
      Sets the currently selected component, This will result in a change to the selection model.
      Parameters:
      sel - theComponent to select

    • isBorderPainted

      public boolean isBorderPainted()
      Checks whether the border should be painted.
      Returns:
      true if the border is painted, false otherwise
      See Also:

    • setBorderPainted

      @BeanProperty(bound=false,description="Is the border of the popup menu painted")public void setBorderPainted(boolean b)
      Sets whether the border should be painted.
      Parameters:
      b - if true, the border is painted.
      See Also:

    • paintBorder

      protected void paintBorder(Graphics g)
      Paints the popup menu's border if theborderPainted property istrue.
      Overrides:
      paintBorder in class JComponent
      Parameters:
      g - theGraphics object
      See Also:

    • getMargin

      @BeanProperty(bound=false)public Insets getMargin()
      Returns the margin, in pixels, between the popup menu's border and its containers.
      Returns:
      anInsets object containing the margin values.

    • paramString

      protected String paramString()
      Returns a string representation of thisJPopupMenu. 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 benull.
      Overrides:
      paramString in class JComponent
      Returns:
      a string representation of thisJPopupMenu.

    • getAccessibleContext

      @BeanProperty(bound=false)public AccessibleContext getAccessibleContext()
      Gets the AccessibleContext associated with this JPopupMenu. For JPopupMenus, the AccessibleContext takes the form of an AccessibleJPopupMenu. A new AccessibleJPopupMenu instance is created if necessary.
      Specified by:
      getAccessibleContext in interface Accessible
      Overrides:
      getAccessibleContext in class Component
      Returns:
      an AccessibleJPopupMenu that serves as the AccessibleContext of this JPopupMenu

    • processMouseEvent

      public void processMouseEvent(MouseEvent event,MenuElement[] path,MenuSelectionManager manager)
      This method is required to conform to theMenuElement interface, but it not implemented.
      Specified by:
      processMouseEvent in interface MenuElement
      Parameters:
      event - aMouseEvent to be processed
      path - the path of the receiving element in the menu hierarchy
      manager - theMenuSelectionManager for the menu hierarchy
      See Also:

    • processKeyEvent

      public void processKeyEvent(KeyEvent e,MenuElement[] path,MenuSelectionManager manager)
      Processes a key event forwarded from theMenuSelectionManager and changes the menu selection, if necessary, by usingMenuSelectionManager's API.

      Note: you do not have to forward the event to sub-components. This is done automatically by theMenuSelectionManager.

      Specified by:
      processKeyEvent in interface MenuElement
      Parameters:
      e - aKeyEvent
      path - theMenuElement path array
      manager - theMenuSelectionManager

    • menuSelectionChanged

      public void menuSelectionChanged(boolean isIncluded)
      Messaged when the menubar selection changes to activate or deactivate this menu. This implements thejavax.swing.MenuElement interface. OverridesMenuElement.menuSelectionChanged.
      Specified by:
      menuSelectionChanged in interface MenuElement
      Parameters:
      isIncluded - true if this menu is active, false if it is not
      See Also:

    • getSubElements

      @BeanProperty(bound=false)public MenuElement[] getSubElements()
      Returns an array ofMenuElements containing the submenu for this menu component. It will only return items conforming to theJMenuElement interface. If popup menu isnull returns an empty array. This method is required to conform to theMenuElement interface.
      Specified by:
      getSubElements in interface MenuElement
      Returns:
      an array ofMenuElement objects
      See Also:

    • getComponent

      public Component getComponent()
      Returns thisJPopupMenu component.
      Specified by:
      getComponent in interface MenuElement
      Returns:
      thisJPopupMenu object
      See Also:

    • isPopupTrigger

      public boolean isPopupTrigger(MouseEvent e)
      Returns true if theMouseEvent is considered a popup trigger by theJPopupMenu's currently installed UI.
      Parameters:
      e - aMouseEvent
      Returns:
      true if the mouse event is a popup trigger
      Since:
      1.3