10.4 MenuItem

A MenuItem is the basic item that goes on a Menu. Menus themselves are menu items, allowing submenus to be nested inside of menus. MenuItem is a subclass of MenuComponent.

public String getLabel ()

The getLabel() method retrieves the label associated with the MenuItem.

public void setLabel (String label)

The setLabel() method changes the label of the MenuItem to label.

public MenuShortcut getMenuShortcut ()

The getMenuShortcut() method retrieves the shortcut associated with this MenuItem.

public void setShortcut (MenuShortcut shortcut)

The setShortcut() method allows you to change the shortcut associated with a MenuItem to shortcut after the MenuItem has been created.

public void deleteMenuShortcut ()

The deleteMenuShortcut() method removes any associated MenuShortcut from the MenuItem. If there was no shortcut, nothing happens.

public boolean isEnabled ()

The isEnabled() method checks to see if the MenuItem is currently enabled. An enabled MenuItem can be selected by the user. A disabled MenuItem, by convention, appears grayed out on the Menu. Initially, each MenuItem is enabled.

public synchronized void setEnabled(boolean b)
public void enable (boolean condition)

The setEnabled() method either enables or disables the MenuItem based on the value of condition. If condition is true, the MenuItem is enabled. If condition is false, it is disabled. When enabled, the user can select it, generating ACTION_EVENT or notifying the ActionListener. When disabled, the peer does not generate an ACTION_EVENT if the user tries to select the MenuItem. A disabled MenuItem is usually grayed out to signify its state. The way that disabling is signified is platform specific.

enable() is the Java 1.0 name for this method.

public synchronized void enable ()

The enable() method enables the MenuItem. In Java 1.1, it is better to use setEnabled().

public synchronized void disable ()

The disable() method disables the component so that the user cannot select it. In Java 1.1, it is better to use setEnabled().

public synchronized void addNotify ()

The addNotify() method creates the MenuItem peer.

public String paramString ()

The paramString() method of MenuItem should be protected like other paramString() methods. However, it is public so you have access to it. When you call the toString() method of a MenuItem, the default toString() method of MenuComponent is called. This in turn calls paramString() which builds up the string to display. At the MenuItem level, the current label of the object and the shortcut (if present) is appended to the output. If the constructor for the MenuItem was new MenuItem(`File`), the results of toString() would be:

java.awt.MenuItem[label=File]

MenuItem Events

With 1.0 event handing, a MenuItem generates an ACTION_EVENT when it is selected. The argument to action() will be the label of the MenuItem. But the target of the ACTION_EVENT is the Frame containing the menu. You cannot subclass MenuItem and catch the Event within it with action(), but you can with postEvent(). No other events are generated for MenuItem instances.

public boolean action (Event e, Object o)--overridden by user, called by system

The action() method for a MenuItem signifies that the user selected it. e is the Event instance for the specific event, while o is the label of the MenuItem.

With the 1.1 event model, you register listeners, and they are told when the event happens.

public String getActionCommand()

The getActionCommand() method retrieves the command associated with this MenuItem. By default, it is the label. However, the default can be changed by using the setActionCommand() method (described next). The command acts like the second parameter to the action() method in the 1.0 event model.

public void setActionCommand(String command)

The setActionCommand() method changes the command associated with a MenuItem. When an ActionEvent happens, the command is part of the event. By default, this would be the label of the MenuItem. However, you can change the action command by calling this method. Using action commands is a good idea, particularly if you expect your code to run in a multilingual environment.

public void addActionListener(ItemListener listener)

The addActionListener() method registers listener as an object interested in being notified when an ActionEvent passes through the EventQueue with this MenuItem as its target. The listener.actionPerformed() method is called whenever these events occur. Multiple listeners can be registered.

public void removeActionListener(ItemListener listener)

The removeActionListener() method removes listener as an interested listener. If listener is not registered, nothing happens.

protected final void enableEvents(long eventsToEnable)

Using the enableEvents() method is usually not necessary. When you register an action listener, the MenuItem listens for action events. However, if you wish to listen for events when listeners are not registered, you must enable the events explicitly by calling this method. The settings for the eventsToEnable parameter are found in the AWTEvent class; you can use any of the EVENT_MASK constants like COMPONENT_EVENT_MASK, MOUSE_EVENT_MASK, and WINDOW_EVENT_MASK ORed together for the events you care about. For instance, to listen for action events, call:

enableEvents (AWTEvent.ACTION_EVENT_MASK);

protected final void disableEvents(long eventsToDisable)

Using the disableEvents() method is usually not necessary. When you remove an action listener, the MenuItem stops listening for action events if there are no more listeners. However, if you need to, you can disable events explicitly by calling disableEvents(). The settings for the eventsToDisable parameter are found in the AWTEvent class; you can use any of the EVENT_MASK constants such as FOCUS_EVENT_MASK, MOUSE_MOTION_EVENT_MASK, and ACTION_EVENT_MASK ORed together for the events you no longer care about.

protected void processEvent(AWTEvent e)

The processEvent() method receives all AWTEvents with this MenuItem as its target. processEvent() then passes them along to any listeners for processing. When you subclass MenuItem, overriding processEvent() allows you to process all events yourself, before sending them to any listeners. In a way, overriding processEvent() is like overriding postEvent() using the 1.0 event model.

If you override processEvent(), remember to call super.processEvent(e) last to ensure that regular event processing can occur. If you want to process your own events, it's a good idea to call enableEvents() to ensure that events are delivered even in the absence of registered listeners.

protected void processActionEvent(ItemEvent e)

The processActionEvent() method receives all ActionEvents with this MenuItem as its target. processActionEvent() then passes them along to any listeners for processing. When you subclass MenuItem, overriding processActionEvent() allows you to process all action events yourself, before sending them to any listeners. In a way, overriding processActionEvent() is like overriding action() using the 1.0 event model.

If you override processActionEvent(), remember to call the method super.processActionEvent(e) last to ensure that regular event processing can occur. If you want to process your own events, it's a good idea to call enableEvents() to ensure that events are delivered even in the absence of registered listeners.