Start of Tutorial > Start of Trail > Start of Lesson

Search Feedback Form

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.

[PENDING: We need to change the text and examples to reflect that, as of v 1.3, you can invoke setAction 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:

• 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);

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 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.
   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:

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

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	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.

Start of Tutorial > Start of Trail > Start of Lesson

Search Feedback Form

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