Action Framework

Overview

Action Configuration

The Commands Bean Definition File

The commands for the application will be stored in a separate bean definition file. This file can be given any name of your choosing, but if creating a new project using the Spring Rich Client archetype, the file will be called commands-context.xml and can be found in the src/main/resources/ui directory of the project. This file contains the definition of all global actions, the menubar and the toolbar. The easiest way to ensure that this file is loaded as part of your application context is to use a DefaultApplicationLifecycleAdvisor (or subclass thereof) and set its windowCommandBarDefinitions property to be the classpath-relative location of this file. Once again, this comes for free if using the archetype.

The Visual Side

Each action needs a unique id. This id is used to fetch the visual information to render the action on the screen.

Suppose you have an open command that has O pen as it's label (with O as mnemonic), that triggers on Ctrl-O the entries in the messages.properties files is as follows.
The caption attribute defines the tooltip text for the action.

openCommand.label=&Open@ctrl O
openCommand.caption=Open the selected item(s)

Label

The label attribute can be just label without mnemonic (Open), a label with mnemonic (&Open) and an optional @accelerator entry.

Accelerator key

The accelerator string must have the following syntax:

<modifiers>* (<typedID> | <pressedReleasedID>)

    modifiers := shift | control | ctrl | meta | alt | button1 | button2 | button3
    typedID := typed <typedKey>
    typedKey := string of length 1 giving Unicode character.
    pressedReleasedID := (pressed | released) key
    key := KeyEvent key code name, i.e. the name following "VK_".

See KeyEvent for possible key code names.

examples:

• INSERT
• control DELETE
• alt shift X
• F5

Caption

The caption attribute is used as tooltip text for the rendered action.

Icon

To have an icon associated with your action, add the following entry to the images.properties file:

openCommand.icon=open.gif

If the specified icon cannot be found, a broken image indicator will be used.

The Controller (Handler) Side

To implement an action, you have to extend ActionCommand, and override the doExecuteCommand method.

Example

The string passed to the super constructor is the id of the command, and is used to look up the label and icon.

public class RenameCommand extends ActionCommand {
    public RenameCommand() {
        super("renameCommand");
    }

    protected void doExecuteCommand() {
        // do whatever your command has to do
    }
}

You can also choose to implement ActionCommandExecutor in the cases where extending ActionCommand is just not an option. For example, the NewOwnerWizard does this, to encapsulate logic for opening up the NewOwnerWizard dialog. TODO: add code example

With this approach, you use composition with a TargetableActionCommand instance, setting the executor for the targetable action command (even if the command itself isn't retargeted after startup).

Action Bar Contribution Policies

To Menus

To ToolBars

Group Markers and Separators

Global Actions

Global commands are window-scoped commands. Global commands are defined in the commands-context.xml file.
Commands declared there are registered in the instantiating window's command registry. These typically consist of:

1. Targetable commands, whose executing implementation can be changed by registering a command executor. For example, "delete", "selectAll", or "properties."
2. Other commands used by the instantiaing window's command groups (bars): menubars, toolbar, etc.

There are several default global actions, defined in the GlobalCommandIds class.

The defined global actions are:

• cut
• copy
• paste
• undo
• redo
• save
• save as
• select all
• delete
• properties
• run

Handler Registration

See Views for an example.

Interaction with middle-tier

Creating PopupMenus

To create a context based popupmenu, you can use the PopupMenuMouseListener helper class.

The PopupMenuMouseListener can be used in two ways:

1. use a static PopupMenu
   Use the constructor to pass a static PopupMenu

   JTree tree = ...;
   JPopupMenu popupMenu = ...;
   tree.addMouseListener(new PopupMenuMouseListener(popupMenu));

2. use a dynamic PopupMenu
   Create an anonymous inner class that returns a PopupMenu, depending on an external factor.

   JTree tree = ...;
   tree.addMouseListener(new PopupMenuMouseListener() {
       protected JPopupMenu getPopupMenu() {
           // create your popup menu here based on the selection
       }
   });

To create a PopupMenu, you first have to create a CommandGroup. The CommandGroup has utility methods to create a ToolBar, PopupMenu, and so on, ...

CommandGroup group = getWindowCommandManager().createCommandGroup("ownerCommandGroup",
                new Object[] { renameCommand, "separator", "deleteCommand", "separator", "propertiesCommand" });
JPopupMenu poupMenu = group.createPopupMenu();

So you could create two different CommandGroups (for example one for Customer, and one for Order), and return the correct PopupMenu for the selected node when dealing with a tree, or create a static popupmenu when dealing with a table.