The Extended Action Framework

The Extended Action Framework extends the Action framework provided by Swing. It mainly provides convenience methods and fields.

The XAction Interface
Reflective Actions
The XActions Utility Class
The Standard Action Factories

The XAction Interface

The Action interface provided by Swing defines some static final fields, which can be used as keys for its getValue and putValue methods. Unfortunalty this interface has some shortcomings:

Although you can set all values used by AbstractButton's and JMenuItem's configurePropertiesFromAction method by using the putValue method, you have first to figure out, of which type the values have to be, since the putValue method just takes an Object.
It only defines a key for a small icon. Large icons as well as small and large disabled, pressed, rollover, rollover selected and selected icons aren't supported.

The XAction interface overcomes these shortcomings by defining static final fields for all these icons and providing setter and getter methods with the right type for each field it defines.
Note: The getter method might throw a ClassCastException if the putValue method has been called directly with a wrong type. The safest way is to use the convenience methods to set the values.

This extended Action interface builds the base of the rest of the Extended Action Framework and since it extends the Action interface, it can be used everywhere an ordinary Action can be used!
The AbstractXAction class implements the XAction interface by extending the AbstractAction and implementing all new methods of XAction. The actionPerfomed method remains abstract.

                    XAction saveAction = new AbstractXAction() {
            public void actionPerformed(ActionEvent e) {
                // save things
            }
        };
        
        saveAction.setName("Save");
        saveAction.setSmallIcon(new ImageIcon(getClass().getResource("/toolbarButtonGraphics/general/Save16.gif")));
        saveAction.setLargeIcon(new ImageIcon(getClass().getResource("/toolbarButtonGraphics/general/Save24.gif")));
        saveAction.setShortDescription("Save");
        saveAction.setAccelerator(KeyStroke.getKeyStroke("control S"));
        saveAction.setMnemonicKey('S');

Reflective Actions

ReflectiveXAction is a trampoline class that implements the XAction interface and delegates the actionPerformed method to a reflectivly called action method. That method must be public and take an ActionEvent object as its single parameter.

Normally there are two standard ways to implement the ActionListener interface: The first is to let a class implement the ActionListener interface and then add an object of this class to the addActionListener methods of the components firing ActionEvents. You then have to check the source in the actionPerformed method. You end up with a big ugly, unmaintainable and unstable if-then-else- statement. The second approach is to define a class for every such component. You end up with tons of small classes all increasing the memory footprint (typically 3K per class).

Now this approach using reflection lets you define a method for each such component avoiding the mentioned drawbacks and has the following advantages:

No other classes implementing ActionListener are used.
The code is very clear.

The new drawbacks are however:

Reflectivly calling method does not identify typos during compile-time.
Calling a method refectivly is slower (but it's unlikely the user notices it).

More to read about reflective actions and trampolines: Chapter 6.2.3, p. 73 of the Java Series Book Java Platform Performance Strategies and Tactics by Steve Wilson and Jeff Kesselman.

Although there are no compile time errors if the specified method doesn't exist, you don't have to wait for the method to be called to get an Exception. The constructor will already throw a NoSuchMethodException in that case.

                    try {
            Action myAction = new ReflectiveXAction(this, "myActionMethod");
        } catch (NoSuchMethodException ex) {
            ex.printStackTrace();
        }
        ...
        
        
        public void myActionMethod(ActionEvent e){
            // do something
        }

Reflective actions are heavily used and supported throughout the whole Extended Action Framework.

The XActions Utility Class

The XActions class is a utility class providing convenience methods, which are described in this section.

The Button Configuration Methods

Let's first have a look at the configureButton method:

        public static void configureButton(AbstractButton button, XAction action, IconType iconType, boolean showText, boolean coolStyle)

This method configures an AbstractButton with an XAction. It can be specified, which icon type should be use (small icons, large icons or no icons), if the text should be displayed and if the buttons should have a cool style. If cool style is set to true, then the border of the button will be drawn only if the mouse pointer is over the button. Note: Since Java 1.4 you can create a similar effect by setting the rollover property of the toolbar to true. However look and feels may ignore this property and the Java Look and Feel does so.

               private void addMenuItems(XAction[] xActions ) {
        for (int i=0; i < xActions.length; i++){
            JMenuItem item = new JMenuItem();
            XActions.configureButton(item, xActions[i], IconType.SMALL_ICON, true, false);
            menu.add(item);
        }
    }
    
    private void addToolbarStandardButtons(XAction[] xActions ) {
        for (int i=0; i < xActions.length; i++){
            JButton button = new JButton();
            XActions.configureButton(button, xActions[i], IconType.LARGE_ICON, false, false);
            toolBarStandard.add(button);
        }
    }
    
    private void addToolbarCoolButtons(XAction[] xActions ) {
        for (int i=0; i < xActions.length; i++){
            JButton button = new JButton();
            XActions.configureButton(button, xActions[i], IconType.LARGE_ICON, false, true);
            toolBarCool.add(button);
        }
    }

Try this:

using Java Web Start.

This sample shows 1 menu and 2 toolbars all configured by the same XAction objects.

Note: This sample uses the GeneralActionFactory class, which will be discussed later in the section The Standard Action Factories.
Source code: ConfigureButtonsSample.java

Like this you can first specify all information in one XAction object and then specify which data should be displayed using this same XAction object.

The configureButton method is twice overloaded:

            public static void configureButton(AbstractButton button, XAction action, ButtonGroup group, IconType iconType, boolean showText, boolean coolStyle)
            
            public static void configureButton(AbstractButton button, XAction action, ItemListener listener, IconType iconType, boolean showText, boolean coolStyle)

The first variant additionally adds the button to a ButtonGroup. The second variant registers an ItemListener to the button.

The Button Creation Methods

Instead of first creating a button and then configuring it using one of the methods discussed above, the XAcions class also provides convenience methods to create such configured buttons directly:

            public static JButton createButton(XAction action, IconType iconType, boolean showText, boolean coolStyle)
  
            public static JCheckBox createCheckBox(XAction action, ItemListener listener, IconType iconType, boolean showText)
  
            public static JCheckBoxMenuItem createCheckBoxMenuItem(XAction action, ItemListener listener, IconType iconType, boolean showText)
  
            public static JMenuItem createMenuItem(XAction action, IconType iconType, boolean showText)
  
            public static JRadioButton createRadioButton(XAction action, ButtonGroup group, IconType iconType, boolean showText)
  
            public static JRadioButtonMenuItem createRadioButtonMenuItem(XAction action, ButtonGroup group, IconType iconType, boolean showText)
  
            public static JToggleButton createToggleButton(XAction action, ButtonGroup group, IconType iconType, boolean showText, boolean coolStyle)
  
            public static JToggleButton createToggleButton(XAction action, ItemListener listener, IconType iconType, boolean showText, boolean coolStyle)

With these methods the previous sample could be rewritten like this:

                private void addMenuItems(XAction[] xActions ) {
        for (int i=0; i < xActions.length; i++){
            JMenuItem item = XActions.createMenuItem(xActions[i], IconType.SMALL_ICON, true);
            menu.add(item);
        }
    }
    
    private void addToolbarStandardButtons(XAction[] xActions ) {
        for (int i=0; i < xActions.length; i++){
            JButton button = XActions.createButton(xActions[i], IconType.LARGE_ICON, false, false);
            toolBarStandard.add(button);
        }
    }
    
    private void addToolbarCoolButtons(XAction[] xActions ) {
        for (int i=0; i < xActions.length; i++){
            JButton button = XActions.createButton(xActions[i], IconType.LARGE_ICON, false, true);
            toolBarCool.add(button);
        }
    }

The modified source code: CreateButtonsSample.java
Now that we have looked at how to configure and create buttons using XAction objects, let's see how we can configure and create these XAction objects using a ResourceBundle.

The XAction Configuration Method

The XActions class provides the following utility method to configure a XAction object from a ResourceBundle:

                public static void configureXAction(XAction action, String name, ResourceBundle rb)

This method is looking for the following keys:

Key Value

<name>.name The Name to be Displayed

<name>.shortDescription Tool Tip

<name>.acceleratorKey Shortcut

<name>.mnemonicKey Mnemonic

<name>.largeDisabledIcon File Name

<name>.largeDisabledSelectedIcon File Name

<name>.largeIcon File Name

<name>.largePressedIcon File Name

<name>.largeRolloverIcon File Name

<name>.largeRolloverSelectedIcon File Name

<name>.largeSelectedIcon File Name

<name>.smallDisabledIcon File Name

<name>.smallDisabledSelectedIcon File Name

<name>.smallIcon File Name

<name>.smallPressedIcon File Name

<name>.smallRolloverIcon File Name

<name>.smallRolloverSelectedIcon File Name

<name>.smallSelectedIcon File Name

Key	Value
<name>.name	The Name to be Displayed
<name>.shortDescription	Tool Tip
<name>.acceleratorKey	Shortcut
<name>.mnemonicKey	Mnemonic
<name>.largeDisabledIcon	File Name
<name>.largeDisabledSelectedIcon	File Name
<name>.largeIcon	File Name
<name>.largePressedIcon	File Name
<name>.largeRolloverIcon	File Name
<name>.largeRolloverSelectedIcon	File Name
<name>.largeSelectedIcon	File Name
<name>.smallDisabledIcon	File Name
<name>.smallDisabledSelectedIcon	File Name
<name>.smallIcon	File Name
<name>.smallPressedIcon	File Name
<name>.smallRolloverIcon	File Name
<name>.smallRolloverSelectedIcon	File Name
<name>.smallSelectedIcon	File Name

E.g.

            myAction.name = MyAction
            myAction.shortDescription = My Action
            myAction.acceleratorKey = Control M
            myAction.mnemonicKey = A
            myAction.largeIcon = /myGraphics/MyAction24.gif
            myAction.smallIcon = /myGraphics/MyAction16.gif

If a key is not specified it in the ResourceBundle it will be ignored!

The XAction Creation Method

Instead of first creating a XAction object and then configuring it using configureXAction method discussed above, the XAcions class also provides a convenience method to create such a configured XAction object directly:

                public static XAction createXAction(String name, Object target, ResourceBundle rb) throws NoSuchMethodException

This method will create a ReflectiveXAction. (See the Reflective Actions section to learn more about reflective actions.) The object 'target' is expected to have a method:

                public void <name>(ActionEvent e)

The Standard Action Factories

The Standard Action Factories provide utility methods to create and configure XActions for standard actions. However they do not provide any functionality for the actions since that is application specific.

All Standard Action Factory classes are typesafe enums, which provide one action factory instance for each supported standard action. They all derive from the base class StandardActionFactory. The StandardActionFactory provides two methods:

                public XAction createXAction(Object target, Locale locale) throws NoSuchMethodException
                public void configureXAction(XAction action, Locale locale)

Note: The createXAction-method expects that the object 'target' has a method:

                public void <name>(ActionEvent e)

where <name> is equal to the output of the toString()-method of the action factory.

E.g. to create the standard action "save" you could use:

                                try {
                    XAction saveAction = GeneralActionFactory.SAVE.createXAction(this, Locale.ENGLISH);
                } catch (NoSuchMethodException ex) {
                    ex.printStackTrace();
                }
                
                ...
        
                public void save(ActionEvent e){
                    // do save
                }

or:

                                XAction saveAction = new AbstractXAction() {
                    public void actionPerformed(ActionEvent actionEvent) {
                        // do save
                    }
                };
                GeneralActionFactory.SAVE.configureXAction(saveAction, Locale.ENGLISH);

The data in the resource bundles that backup the Standard Action Factories is based on the following sources:

The Java Look and Feel Graphics Repository
The Java Look and Feel Design Guidelines, Second Edition
Especially on the follwing sections:

Currently the following locales are supported:

english (en)
german (de)

Note: The data in the resource bundles is not complete yet!

There is one Standard Action Factory class for each part of the Java Look and Feel Graphics Repository:

Action Factory Button Graphics

DevelopmentActionFactory Development Toolbar Button Graphics

GeneralActionFactory General Toolbar Button Graphics

MediaActionFactory Media Toolbar Button Graphics

NavigationActionFactory Navigation Toolbar Button Graphics

TableActionFactory Table Toolbar Button Graphics

TextActionFactory Text Toolbar Button Graphics

Action Factory	Button Graphics
DevelopmentActionFactory	Development Toolbar Button Graphics
GeneralActionFactory	General Toolbar Button Graphics
MediaActionFactory	Media Toolbar Button Graphics
NavigationActionFactory	Navigation Toolbar Button Graphics
TableActionFactory	Table Toolbar Button Graphics
TextActionFactory	Text Toolbar Button Graphics

The follwing sample provides an overview over what data is already available.

Try this:

using Java Web Start.

This sample shows 1 menu and 1 toolbar for each Standard Action Factory class.
(Except the GeneralActionFactory class for which there are 2 toolbars.)

Source code: StandardActionFactoriesSample.java

From the source code:

                private XAction[] createActions(StandardActionFactory[] factories) {
        XAction[] xActions = new XAction[factories.length];
        for (int i=0; i < factories.length; i++){
            StandardActionFactory factory = factories[i];
            XAction xAction = new AbstractXAction(){
                public void actionPerformed(ActionEvent e) {
                    JOptionPane.showMessageDialog(StandardActionFactoriesSample.this,
                            "Action performed: " + getName(), "Action Performed!", JOptionPane.INFORMATION_MESSAGE);
                }
            };
            factory.configureXAction(xAction, Locale.getDefault());
            xActions[i] = xAction;
        }
        return xActions;
    }
    
    
    private XAction[] createDevelopmentActions() {
        DevelopmentActionFactory[] factories = {
            DevelopmentActionFactory.APPLET,
            DevelopmentActionFactory.APPLICATION,
            DevelopmentActionFactory.APPLICATION_DEPLOY,
            DevelopmentActionFactory.BEAN,
            DevelopmentActionFactory.BEAN_ADD,
            DevelopmentActionFactory.ENTERPRISE_JAVA_BEAN,
            DevelopmentActionFactory.ENTERPRISE_JAVA_BEAN_JAR,
            DevelopmentActionFactory.HOST,
            DevelopmentActionFactory.J2EE_APPLICATION,
            DevelopmentActionFactory.J2EE_APPLICATION_CLIENT,
            DevelopmentActionFactory.J2EE_APPLICATION_CLIENT_ADD,
            DevelopmentActionFactory.J2EE_SERVER,
            DevelopmentActionFactory.JAR,
            DevelopmentActionFactory.JAR_ADD,
            DevelopmentActionFactory.SERVER,
            DevelopmentActionFactory.WAR,
            DevelopmentActionFactory.WAR_ADD,
            DevelopmentActionFactory.WEB_COMPONENT,
            DevelopmentActionFactory.WEB_COMPONENT_ADD};
        return createActions(factories);
    }
    
    private XAction[] createGeneralActions() {
        GeneralActionFactory[] factories = {
            GeneralActionFactory.ABOUT,
            GeneralActionFactory.ADD,
            GeneralActionFactory.ALIGN_BOTTOM,
            GeneralActionFactory.ALIGN_CENTER,
            GeneralActionFactory.ALIGN_JUSTIFY_HORIZONTAL,
            GeneralActionFactory.ALIGN_JUSTIFY_VERTICAL,
            GeneralActionFactory.ALIGN_LEFT,
            GeneralActionFactory.ALIGN_RIGHT,
            GeneralActionFactory.ALIGN_TOP,
            GeneralActionFactory.BOOKMARKS,
            GeneralActionFactory.COMPOSE_MAIL,
            GeneralActionFactory.CONTEXTUAL_HELP,
            GeneralActionFactory.COPY,
            GeneralActionFactory.CUT,
            GeneralActionFactory.DELETE,
            GeneralActionFactory.EDIT,
            GeneralActionFactory.EXPORT,
            GeneralActionFactory.FIND,
            GeneralActionFactory.FIND_AGAIN,
            GeneralActionFactory.HELP,
            GeneralActionFactory.HISTORY,
            GeneralActionFactory.IMPORT,
            GeneralActionFactory.INFORMATION,
            GeneralActionFactory.NEW,
            GeneralActionFactory.OPEN,
            GeneralActionFactory.PAGE_SETUP,
            GeneralActionFactory.PASTE,
            GeneralActionFactory.PREFERENCES,
            GeneralActionFactory.PRINT,
            GeneralActionFactory.PRINT_PREVIEW,
            GeneralActionFactory.PROPERTIES,
            GeneralActionFactory.REDO,
            GeneralActionFactory.REFRESH,
            GeneralActionFactory.REMOVE,
            GeneralActionFactory.REPLACE,
            GeneralActionFactory.SAVE,
            GeneralActionFactory.SAVE_ALL,
            GeneralActionFactory.SAVE_AS,
            GeneralActionFactory.SEARCH,
            GeneralActionFactory.SEND_MAIL,
            GeneralActionFactory.STOP,
            GeneralActionFactory.TIP_OF_THE_DAY,
            GeneralActionFactory.UNDO,
            GeneralActionFactory.ZOOM,
            GeneralActionFactory.ZOOM_IN,
            GeneralActionFactory.ZOOM_OUT};
        return createActions(factories);
    }
    
    private XAction[] createMediaActions() {
        MediaActionFactory[] factories = {
            MediaActionFactory.FAST_FORWARD,
            MediaActionFactory.MOVIE,
            MediaActionFactory.PAUSE,
            MediaActionFactory.PLAY,
            MediaActionFactory.REWIND,
            MediaActionFactory.STEP_BACK,
            MediaActionFactory.STEP_FORWARD,
            MediaActionFactory.STOP,
            MediaActionFactory.VOLUME};
        return createActions(factories);
    }
    
    private XAction[] createNavigationActions() {
         NavigationActionFactory[] factories = {
             NavigationActionFactory.BACK,
             NavigationActionFactory.DOWN,
             NavigationActionFactory.FORWARD,
             NavigationActionFactory.HOME,
             NavigationActionFactory.UP};
        return createActions(factories);
    }
    
    private XAction[] createTableActions() {
        TableActionFactory[] factories = {
            TableActionFactory.COLUMN_DELETE,
            TableActionFactory.COLUMN_INSERT_AFTER,
            TableActionFactory.COLUMN_INSERT_BEFORE,
            TableActionFactory.ROW_DELETE,
            TableActionFactory.ROW_INSERT_AFTER,
            TableActionFactory.ROW_INSERT_BEFORE};
        return createActions(factories);
    }

    private XAction[] createTextActions() {
        TextActionFactory[] factories = {
            TextActionFactory.ALIGN_CENTER,
            TextActionFactory.ALIGN_JUSTIFY,
            TextActionFactory.ALIGN_LEFT,
            TextActionFactory.ALIGN_RIGHT,
            TextActionFactory.BOLD,
            TextActionFactory.ITALIC,
            TextActionFactory.NORMAL,
            TextActionFactory.UNDERLINE};
       return createActions(factories);
    }