The JavaTM Tutorial
Previous Page Lesson Contents Next Page Start of Tutorial > Start of Trail > Start of Lesson Search
Feedback Form

Trail: Creating a GUI with JFC/Swing
Lesson: Using Other Swing Features

How to Use Actions

If you have two or more components that perform the same function, consider using an Action(in the API reference documentation) object to implement the function. An Action object is an ActionListener(in the Creating a GUI with JFC/Swing trail) 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.

[PENDING: We need to change the text and examples to reflect that, as of v 1.3, you can invoke setAction(in the API reference documentation) on all menu items and buttons. We no longer recommend using the tool bar and menu add(Action) methods.]

By adding an Action to a JToolBar, JMenu, or JPopupMenu, you get the following features:

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);
In releases prior to v 1.3, the only way for a button or menu item to get the full benefit of using an Action is to create the component using the add(Action) method of JToolBar, JMenu, or JPopupMenu. This is because the pre-1.3 releases have no API except addActionListener(ActionListener) to connect an Action to an already existing component. Although you can use addActionListener to add an Action object as an action listener to any button, for example, the button won't be notified when the action is disabled.

To create an Action object, you generally create a subclass of AbstractAction(in the API reference documentation) 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.

A snapshot of ActionDemo, which uses actions to coordinate menus and buttons.


Try this: 
  1. Compile and run the application. The source file is ActionDemo.java(in a .java source file). You will also need three image files.
    See Getting Started with Swing if you need help compiling or running this application.
  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:

A snapshot of ActionDemo when

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(in a .java source file) 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
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

The following examples use Action objects.

Example Where Described Notes
ActionDemo This section Uses actions to bind buttons and menu items to the same function.
TextComponentDemo General Rules for Using Text Components(in the Creating a GUI with JFC/Swing trail) Uses text actions to create menu items for text editing commands, such as cut, copy, and paste, and to bind key strokes to caret movement. Also implements custom AbstractAction subclasses to implement undo and redo. The text action discussion begins in Concepts: About Editor Kits.


Previous Page Lesson Contents Next Page Start of Tutorial > Start of Trail > Start of Lesson Search
Feedback Form

Copyright 1995-2002 Sun Microsystems, Inc. All rights reserved.