Module java.desktop
Package javax.swing

Class JMenu

  • All Implemented Interfaces:
    ImageObserver, ItemSelectable, MenuContainer, Serializable, Accessible, MenuElement, SwingConstants
    @JavaBean(description="A popup window containing menu items displayed in a menu bar.")
public class JMenu
extends JMenuItem
implements Accessible, MenuElement
    An implementation of a menu -- a popup window containing JMenuItems that is displayed when the user selects an item on the JMenuBar. In addition to JMenuItems, a JMenu can also contain JSeparators.

    In essence, a menu is a button with an associated JPopupMenu. When the "button" is pressed, the JPopupMenu appears. If the "button" is on the JMenuBar, the menu is a top-level window. If the "button" is another menu item, then the JPopupMenu is "pull-right" menu.

    Menus can be configured, and to some degree controlled, by Actions. Using an Action with a menu has many benefits beyond directly configuring a menu. Refer to Swing Components Supporting Action for more details, and you can find more information in How to Use Actions, a section in The Java Tutorial.

    For information and examples of using menus see How to Use Menus, a section 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™ has been added to the java.beans package. Please see XMLEncoder.

    Since:
    1.2
    See Also:
    JMenuItem, JSeparator, JMenuBar, JPopupMenu, Serialized Form

    • Constructor Detail

      • JMenu

        public JMenu()
        Constructs a new JMenu with no text.

      • JMenu

        public JMenu​(String s)
        Constructs a new JMenu with the supplied string as its text.
        Parameters:
        s - the text for the menu label

      • JMenu

        public JMenu​(Action a)
        Constructs a menu whose properties are taken from the Action supplied.
        Parameters:
        a - an Action
        Since:
        1.3

      • JMenu

        public JMenu​(String s,
             boolean b)
        Constructs a new JMenu with the supplied string as its text and specified as a tear-off menu or not.
        Parameters:
        s - the text for the menu label
        b - can the menu be torn off (not yet implemented)

    • Method Detail

      • isSelected

        public boolean isSelected()
        Returns true if the menu is currently selected (highlighted).
        Overrides:
        isSelected in class AbstractButton
        Returns:
        true if the menu is selected, else false

      • setSelected

        @BeanProperty(expert=true,
              hidden=true,
              description="When the menu is selected, its popup child is shown.")
public void setSelected​(boolean b)
        Sets the selection status of the menu.
        Overrides:
        setSelected in class AbstractButton
        Parameters:
        b - true to select (highlight) the menu; false to de-select the menu

      • isPopupMenuVisible

        public boolean isPopupMenuVisible()
        Returns true if the menu's popup window is visible.
        Returns:
        true if the menu is visible, else false

      • setPopupMenuVisible

        @BeanProperty(bound=false,
              expert=true,
              hidden=true,
              description="The popup menu\'s visibility")
public void setPopupMenuVisible​(boolean b)
        Sets the visibility of the menu's popup. If the menu is not enabled, this method will have no effect.
        Parameters:
        b - a boolean value -- true to make the menu visible, false to hide it

      • getPopupMenuOrigin

        protected Point getPopupMenuOrigin()
        Computes the origin for the JMenu's popup menu. This method uses Look and Feel properties named Menu.menuPopupOffsetX, Menu.menuPopupOffsetY, Menu.submenuPopupOffsetX, and Menu.submenuPopupOffsetY to adjust the exact location of popup.
        Returns:
        a Point in the coordinate space of the menu which should be used as the origin of the JMenu's popup menu
        Since:
        1.3

      • getDelay

        public int getDelay()
        Returns the suggested delay, in milliseconds, before submenus are popped up or down. Each look and feel (L&F) may determine its own policy for observing the delay property. In most cases, the delay is not observed for top level menus or while dragging. The default for delay is 0. This method is a property of the look and feel code and is used to manage the idiosyncrasies of the various UI implementations.
        Returns:
        the delay property

      • setDelay

        @BeanProperty(bound=false,
              expert=true,
              description="The delay between menu selection and making the popup menu visible")
public void setDelay​(int d)
        Sets the suggested delay before the menu's PopupMenu is popped up or down. Each look and feel (L&F) may determine it's own policy for observing the delay property. In most cases, the delay is not observed for top level menus or while dragging. This method is a property of the look and feel code and is used to manage the idiosyncrasies of the various UI implementations.
        Parameters:
        d - the number of milliseconds to delay
        Throws:
        IllegalArgumentException - if d is less than 0

      • setMenuLocation

        public void setMenuLocation​(int x,
                            int y)
        Sets the location of the popup component.
        Parameters:
        x - the x coordinate of the popup's new position
        y - the y coordinate of the popup's new position

      • add

        public JMenuItem add​(JMenuItem menuItem)
        Appends a menu item to the end of this menu. Returns the menu item added.
        Parameters:
        menuItem - the JMenuitem to be added
        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
        Returns:
        the new JMenuItem

      • add

        public JMenuItem add​(Action a)
        Creates a new menu item attached to the specified Action object and appends it to the end of this menu.
        Parameters:
        a - the Action for the menu item to be added
        Returns:
        the new JMenuItem
        See Also:
        Action

      • createActionComponent

        protected JMenuItem createActionComponent​(Action a)
        Factory method which creates the JMenuItem for Actions added to the JMenu.
        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.
        Parameters:
        b - a menu item for which to create a PropertyChangeListener
        Returns:
        a PropertyChangeListener for b

      • addSeparator

        public void addSeparator()
        Appends a new separator to the end of the menu.

      • insert

        public void insert​(String s,
                   int pos)
        Inserts a new menu item with the specified text at a given position.
        Parameters:
        s - the text for the menu item to add
        pos - an integer specifying the position at which to add the new menu item
        Throws:
        IllegalArgumentException - when the value of pos < 0

      • insert

        public JMenuItem insert​(JMenuItem mi,
                        int pos)
        Inserts the specified JMenuitem at a given position.
        Parameters:
        mi - the JMenuitem to add
        pos - an integer specifying the position at which to add the new JMenuitem
        Returns:
        the new menu item
        Throws:
        IllegalArgumentException - if the value of pos < 0

      • insert

        public JMenuItem insert​(Action a,
                        int pos)
        Inserts a new menu item attached to the specified Action object at a given position.
        Parameters:
        a - the Action object for the menu item to add
        pos - an integer specifying the position at which to add the new menu item
        Returns:
        the new menu item
        Throws:
        IllegalArgumentException - if the value of pos < 0

      • insertSeparator

        public void insertSeparator​(int index)
        Inserts a separator at the specified position.
        Parameters:
        index - an integer specifying the position at which to insert the menu separator
        Throws:
        IllegalArgumentException - if the value of index < 0

      • getItem

        public JMenuItem getItem​(int pos)
        Returns the JMenuItem at the specified position. If the component at pos is not a menu item, null is returned. This method is included for AWT compatibility.
        Parameters:
        pos - an integer specifying the position
        Returns:
        the menu item at the specified position; or null if the item as the specified position is not a menu item
        Throws:
        IllegalArgumentException - if the value of pos < 0

      • getItemCount

        @BeanProperty(bound=false)
public int getItemCount()
        Returns the number of items on the menu, including separators. This method is included for AWT compatibility.
        Returns:
        an integer equal to the number of items on the menu
        See Also:
        getMenuComponentCount()

      • isTearOff

        @BeanProperty(bound=false)
public boolean isTearOff()
        Returns true if the menu can be torn off. This method is not yet implemented.
        Returns:
        true if the menu can be torn off, else false
        Throws:
        Error - if invoked -- this method is not yet implemented

      • remove

        public void remove​(JMenuItem item)
        Removes the specified menu item from this menu. If there is no popup menu, this method will have no effect.
        Parameters:
        item - the JMenuItem to be removed from the menu

      • getMenuComponentCount

        @BeanProperty(bound=false)
public int getMenuComponentCount()
        Returns the number of components on the menu.
        Returns:
        an integer containing the number of components on the menu

      • getMenuComponent

        public Component getMenuComponent​(int n)
        Returns the component at position n.
        Parameters:
        n - the position of the component to be returned
        Returns:
        the component requested, or null if there is no popup menu

      • getMenuComponents

        @BeanProperty(bound=false)
public Component[] getMenuComponents()
        Returns an array of Components of the menu's subcomponents. Note that this returns all Components in the popup menu, including separators.
        Returns:
        an array of Components or an empty array if there is no popup menu

      • isTopLevelMenu

        @BeanProperty(bound=false)
public boolean isTopLevelMenu()
        Returns true if the menu is a 'top-level menu', that is, if it is the direct child of a menubar.
        Returns:
        true if the menu is activated from the menu bar; false if the menu is activated from a menu item on another menu

      • isMenuComponent

        public boolean isMenuComponent​(Component c)
        Returns true if the specified component exists in the submenu hierarchy.
        Parameters:
        c - the Component to be tested
        Returns:
        true if the Component exists, false otherwise

      • getPopupMenu

        @BeanProperty(bound=false)
public JPopupMenu getPopupMenu()
        Returns the popupmenu associated with this menu. If there is no popupmenu, it will create one.
        Returns:
        the JPopupMenu associated with this menu

      • addMenuListener

        public void addMenuListener​(MenuListener l)
        Adds a listener for menu events.
        Parameters:
        l - the listener to be added

      • removeMenuListener

        public void removeMenuListener​(MenuListener l)
        Removes a listener for menu events.
        Parameters:
        l - the listener to be removed

      • getMenuListeners

        @BeanProperty(bound=false)
public MenuListener[] getMenuListeners()
        Returns an array of all the MenuListeners added to this JMenu with addMenuListener().
        Returns:
        all of the MenuListeners added or an empty array if no listeners have been added
        Since:
        1.4

      • fireMenuSelected

        protected void fireMenuSelected()
        Notifies all listeners that have registered interest for notification on this event type. The event instance is created lazily.
        Throws:
        Error - if there is a null listener
        See Also:
        EventListenerList

      • fireMenuDeselected

        protected void fireMenuDeselected()
        Notifies all listeners that have registered interest for notification on this event type. The event instance is created lazily.
        Throws:
        Error - if there is a null listener
        See Also:
        EventListenerList

      • fireMenuCanceled

        protected void fireMenuCanceled()
        Notifies all listeners that have registered interest for notification on this event type. The event instance is created lazily.
        Throws:
        Error - if there is a null listener
        See Also:
        EventListenerList

      • createWinListener

        protected JMenu.WinListener createWinListener​(JPopupMenu p)
        Creates a window-closing listener for the popup.
        Parameters:
        p - the JPopupMenu
        Returns:
        the new window-closing listener
        See Also:
        JMenu.WinListener

      • getSubElements

        @BeanProperty(bound=false)
public MenuElement[] getSubElements()
        Returns an array of MenuElements containing the submenu for this menu component. If popup menu is null returns an empty array. This method is required to conform to the MenuElement interface. Note that since JSeparators do not conform to the MenuElement interface, this array will only contain JMenuItems.
        Specified by:
        getSubElements in interface MenuElement
        Overrides:
        getSubElements in class JMenuItem
        Returns:
        an array of MenuElement objects

      • getComponent

        public Component getComponent()
        Returns the java.awt.Component used to paint this MenuElement. The returned component is used to convert events and detect if an event is inside a menu component.
        Specified by:
        getComponent in interface MenuElement
        Overrides:
        getComponent in class JMenuItem
        Returns:
        the Component that paints this menu item

      • setAccelerator

        public void setAccelerator​(KeyStroke keyStroke)
        setAccelerator is not defined for JMenu. Use setMnemonic instead.
        Overrides:
        setAccelerator in class JMenuItem
        Parameters:
        keyStroke - the keystroke combination which will invoke the JMenuItem's actionlisteners without navigating the menu hierarchy
        Throws:
        Error - if invoked -- this method is not defined for JMenu. Use setMnemonic instead

      • doClick

        public void doClick​(int pressTime)
        Programmatically performs a "click". This overrides the method AbstractButton.doClick in order to make the menu pop up.
        Overrides:
        doClick in class AbstractButton
        Parameters:
        pressTime - indicates the number of milliseconds the button was pressed for

      • paramString

        protected String paramString()
        Returns a string representation of this JMenu. 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 JMenuItem
        Returns:
        a string representation of this JMenu.

      • getAccessibleContext

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