Using the JFC/Swing Packages

How to Use Actions

If you have two or more components that perform the same function, consider using an Action object to implement the function. An Action object is an ActionListener that provides not only action-event handling, but also centralized handling of the text, icon, and enabled state of tool bar buttons or menu items. By adding an Action to a JToolBar, JMenu, or JPopupMenu, you get the following features:

• A new JButton (for JToolBar) or JMenuItem (for JMenu and JPopupMenu) that is automatically added to the tool bar or menu. The button or menu item automatically uses the icon and text specified by the Action.
• A registered action listener (the Action object) for the button or menu item.
• Centralized handling of the button or menu item's enabled state.

Here's an example of using an Action to create a tool-bar button and menu item that perform the same function:

Action leftAction = new <a class that implements Action>(...);
JButton button = toolBar.add(leftAction);
JMenuItem menuItem = mainMenu.add(leftAction);

For a button or menu item to get the full benefit of using an Action, you must create the component using the add(Action) method of JToolBar, JMenu, or JPopupMenu. Currently, no API beyond addActionListener(ActionListener) exists to connect an Action to an already existing component. For example, although you can add an Action object as an action listener to any button, the button won't be notified when the action is disabled.

To create an Action object, you generally create a subclass of AbstractAction and then instantiate it. In your subclass, you must implement the actionPerformed method to react appropriately when the action event occurs. Here's an example of creating and instantiating an AbstractAction subclass:

leftAction = new AbstractAction("Go left",
                                new ImageIcon("images/left.gif")) {
    public void actionPerformed(ActionEvent e) {
        displayResult("Action for first button/menu item", e);
    }
};

Here's a picture of a demo application that uses actions to implement three features.

---

Try this:

1. Compile and run the application. The source file is ActionDemo.java. You will also need three image files: left.gif, middle.gif, and right.gif.
   See Getting Started with Swing if you need help.
2. Choose the top item from the left menu (Menu->Go left).
   The text area displays some text identifying both the event source and the action listener that received the event.
3. Click the leftmost button in the tool bar.
   The text area again displays information about the event. Note that although the source of the events is different, both events were detected by the same action listener: the Action object with which the components were created.
4. Choose the top item from the Action State menu.
   This disables the "Go left" Action object, which in turn disables its associated menu item and button.

---

Here is what the user sees when the "Go left" action is disabled:

Here's the code that disables the "Go left" action:

boolean selected = ...//true if the action should be enabled; false, otherwise
leftAction.setEnabled(selected);

After you create components using an Action, you might well need to customize them. For example, you might want to set the tool-tip text for a button. Or you might want to customize the appearance of one of the components by adding or deleting the icon or text. For example, ActionDemo.java has no icons in its menus, no text in its buttons, and tool tips for its buttons. Here's the code that accomplishes this:

button = toolBar.add(leftAction);
button.setText(""); //an icon-only button
button.setToolTipText("This is the left button");
menuItem = mainMenu.add(leftAction);
menuItem.setIcon(null); //arbitrarily chose not to use icon in menu

The Action API

The following tables list the commonly used Action constructors and methods. The API for using Action objects falls into two categories:

• Creating and Using an Action
• Creating an Action-Controlled Component

Creating and Using an Action

Constructor or Method	Purpose
AbstractAction() AbstractAction(String) AbstractAction(String, Icon)	Create an Action object. Through arguments, you can specify the text and icon to be used in the components that the action controls.
void setEnabled(boolean) boolean isEnabled()	Set or get whether the components the action controls are enabled. Invoking setEnabled(false) disables all the components that the action controls. Similarly, invoking setEnabled(true) enables the action's components.

Creating an Action-Controlled Component

Method	Purpose
JMenuItem add(Action) JMenuItem insert(Action, int) (in JMenu and JPopupMenu)	Create a JMenuItem object and put it in the menu or popup menu. See the discussion in this section and in How to Use Menus for details.
JButton add(Action) (in JToolBar)	Create a JButton object and put it in the tool bar. See the discussion in this section and in How to Use Tool Bars for details.

Examples that Use Actions

Currently, the only example that uses Action objects is ActionDemo.java, which is used and described in this section.

Using the JFC/Swing Packages