Package org.jdesktop.application

# Class ApplicationAction

java.lang.Object
javax.swing.AbstractAction
org.jdesktop.application.ApplicationAction

All Implemented Interfaces:
  `ActionListener`, `Serializable`, `Cloneable`, `EventListener`, `Action`

public class ApplicationAction extends AbstractAction
The `Action` class used to implement the `@Action` annotation. This class is typically not instantiated directly, it's created as a side effect of constructing an `ApplicationActionMap`:

     public class MyActions {
         @Action public void anAction() { }  // an @Action named "anAction"
     }
     ApplicationContext ac = ApplicationContext.getInstance();
     ActionMap actionMap = ac.getActionMap(new MyActions());
     myButton.setAction(actionMap.get("anAction"));

When an ApplicationAction is constructed, it initializes all of its properties from the specified `ResourceMap`. Resource names must match the `@Action's` name, which is the name of the corresponding method, or the value of the optional `@Action` name parameter. To initialize the text and shortDescription properties of the action named `"anAction"` in the previous example, one would define two resources:

     anAction.Action.text = Button/Menu/etc label text for anAction
     anAction.Action.shortDescription = Tooltip text for anAction

A complete description of the mapping between resources and Action properties can be found in the ApplicationAction `constructor` documentation.

An ApplicationAction's `enabled` and `selected` properties can be delegated to boolean properties of the Actions class, by specifying the corresponding property names. This can be done with the `@Action` annotation, e.g.:

     public class MyActions {
         @Action(enabledProperty = "anActionEnabled")
         public void anAction() { }
         public boolean isAnActionEnabled() {
             // will fire PropertyChange when anActionEnabled changes
             return anActionEnabled;
         }
     }

If the MyActions class supports PropertyChange events, then then ApplicationAction will track the state of the specified property ("anActionEnabled" in this case) with a PropertyChangeListener.

ApplicationActions can automatically `block` the GUI while the `actionPerformed` method is running, depending on the value of block annotation parameter. For example, if the value of block is `Task.BlockingScope.ACTION`, then the action will be disabled while the actionPerformed method runs.

An ApplicationAction can have a `proxy` Action, i.e. another Action that provides the `actionPerformed` method, the enabled/selected properties, and values for the Action's long and short descriptions. If the proxy property is set, this ApplicationAction tracks all of the aforementioned properties, and the `actionPerformed` method just calls the proxy's `actionPerformed` method. If a `proxySource` is specified, then it becomes the source of the ActionEvent that's passed to the proxy `actionPerformed` method. Proxy action dispatching is as simple as this:

     public void actionPerformed(ActionEvent actionEvent) {
         javax.swing.Action proxy = getProxy();
         if (proxy != null) {
             actionEvent.setSource(getProxySource());
             proxy.actionPerformed(actionEvent);
         }
         // ....
     }

Author:
  Hans Muller (Hans.Muller@Sun.COM)
See Also:
  - `ApplicationContext.getActionMap(Object)`
  - `ResourceMap`
  - Serialized Form

## Field Summary

### Fields inherited from class javax.swing.AbstractAction

`changeSupport, enabled`

### Fields inherited from interface javax.swing.Action

`ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, DISPLAYED_MNEMONIC_INDEX_KEY, LARGE_ICON_KEY, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SELECTED_KEY, SHORT_DESCRIPTION, SMALL_ICON`

## Constructor Summary

Constructors
Constructor
Description
`ApplicationAction(ApplicationActionMap appAM, ResourceMap resourceMap, String baseName, Method actionMethod, String enabledProperty, boolean enabledNegated, String selectedProperty, String taskService, Task.BlockingScope block)`
Construct an `ApplicationAction` that implements an `@Action`.

## Method Summary

Modifier and Type
Method
Description
`void`
`actionPerformed(ActionEvent actionEvent)`
This method implements this `Action's` behavior.
`protected Object`
`getActionArgument(Class pType, String pKey, ActionEvent actionEvent)`
Provides parameter values to @Action methods.
`String`
`getName()`
The name of this Action.
`Action`
`getProxy()`
Return the proxy for this action or null.
`Object`
`getProxySource()`
Return the value that becomes the `ActionEvent` source before the ActionEvent is passed along to the proxy Action.
`ResourceMap`
`getResourceMap()`
The resourceMap for this Action.
`boolean`
`isEnabled()`
If the proxy action is null and `enabledProperty` was specified, then return the value of the enabled property's is/get method applied to our ApplicationActionMap's `actionsObject`.
`boolean`
`isSelected()`
If the proxy action is null and `selectedProperty` was specified, then return the value of the selected property's is/get method applied to our ApplicationActionMap's `actionsObject`.
`void`
`putValue(String key, Object value)`
Keeps the `@Action selectedProperty` in sync when the value of `key` is `Action.SELECTED_KEY`.
`void`
`setEnabled(boolean enabled)`
If the proxy action is null and `enabledProperty` was specified, then set the value of the enabled property by invoking the corresponding `set` method on our ApplicationActionMap's `actionsObject`.
`void`
`setProxy(Action proxy)`
Set the proxy for this action.
`void`
`setProxySource(Object source)`
Set the value that becomes the `ActionEvent` source before the ActionEvent is passed along to the proxy Action.
`void`
`setSelected(boolean selected)`
If the proxy action is null and `selectedProperty` was specified, then set the value of the selected property by invoking the corresponding `set` method on our ApplicationActionMap's `actionsObject`.
`String`
`toString()`
Returns a string representation of this `ApplicationAction` that should be useful for debugging.

### Methods inherited from class javax.swing.AbstractAction

`addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, removePropertyChangeListener`

### Methods inherited from class java.lang.Object

`equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

### Methods inherited from interface javax.swing.Action

`accept`

## Constructor Details

### ApplicationAction

public ApplicationAction(ApplicationActionMap appAM, ResourceMap resourceMap, String baseName, Method actionMethod, String enabledProperty, boolean enabledNegated, String selectedProperty, String taskService, Task.BlockingScope block)
Construct an `ApplicationAction` that implements an `@Action`.

If a `ResourceMap` is provided, then all of the `Action` properties are initialized with the values of resources whose key begins with `baseName`. ResourceMap keys are created by appending an @Action resource name, like "Action.shortDescription" to the @Action's baseName For example, Given an @Action defined like this:

     @Action void actionBaseName() { }

Then the shortDescription resource key would be `actionBaseName.Action.shortDescription`, as in:

     actionBaseName.Action.shortDescription = Do perform some action

The complete set of @Action resources is:

     Action.icon
     Action.text
     Action.shortDescription
     Action.longDescription
     Action.smallIcon
     Action.largeIcon
     Action.command
     Action.accelerator
     Action.mnemonic
     Action.displayedMnemonicIndex

A few the resources are handled specially:

- `Action.text`
  Used to initialize the Action properties with keys `Action.NAME`, `Action.MNEMONIC_KEY` and `Action.DISPLAYED_MNEMONIC_INDEX`. If the resources's value contains an "invalid input: '&'" or an "_" it's assumed to mark the following character as the mnemonic. If Action.mnemonic/Action.displayedMnemonic resources are also defined (an odd case), they'll override the mnemonic specfied with the Action.text marker character.
- `Action.icon`
  Used to initialize both ACTION.SMALL_ICON,LARGE_ICON. If Action.smallIcon or Action.largeIcon resources are also defined they'll override the value defined for Action.icon.
- `Action.displayedMnemonicIndexKey`
  The corresponding javax.swing.Action constant is only defined in Java SE 6. We'll set the Action property in Java SE 5 too.

Parameters:
  `appAM` - the ApplicationActionMap this action is being constructed for.
  `resourceMap` - initial Action properties are loaded from this ResourceMap.
  `baseName` - the name of the @Action
  `actionMethod` - unless a proxy is specified, actionPerformed calls this method.
  `enabledProperty` - name of the enabled property.
  `enabledNegated` - enabled property is inverted
  `selectedProperty` - name of the selected property.
  `taskService` - name of the task service for this action
  `block` - how much of the GUI to block while this action executes.
See Also:
  - `getName()`
  - `ApplicationActionMap.getActionsClass()`
  - `ApplicationActionMap.getActionsObject()`

## Method Details

### getProxy

public Action getProxy()
Return the proxy for this action or null.

Returns:
  the value of the proxy property.
See Also:
  - `setProxy(javax.swing.Action)`
  - `setProxySource(java.lang.Object)`
  - `actionPerformed(java.awt.event.ActionEvent)`

### setProxy

public void setProxy(Action proxy)
Set the proxy for this action. If the proxy is non-null then we delegate/track the following:

- `actionPerformed`
  Our `actionPerformed` method calls the delegate's after the ActionEvent source to be the value of `getProxySource`
- `shortDescription`
  If the proxy's shortDescription, i.e. the value for key `SHORT_DESCRIPTION` is not null, then set this action's shortDescription. Most Swing components use the shortDescription to initialize their tooltip.
- `longDescription`
  If the proxy's longDescription, i.e. the value for key `LONG_DESCRIPTION` is not null, then set this action's longDescription.

Parameters:
  `proxy` -
See Also:
  - `setProxy(javax.swing.Action)`
  - `setProxySource(java.lang.Object)`
  - `actionPerformed(java.awt.event.ActionEvent)`

### getProxySource

public Object getProxySource()
Return the value that becomes the `ActionEvent` source before the ActionEvent is passed along to the proxy Action.

Returns:
  the value of the proxySource property.
See Also:
  - `getProxy()`
  - `setProxySource(java.lang.Object)`
  - `EventObject.getSource()`

### setProxySource

public void setProxySource(Object source)
Set the value that becomes the `ActionEvent` source before the ActionEvent is passed along to the proxy Action.

Parameters:
  `source` - the `ActionEvent` source/
See Also:
  - `getProxy()`
  - `getProxySource()`
  - `AWTEvent.setSource(java.lang.Object)`

### getName

public String getName()
The name of this Action. This string begins with the name the corresponding @Action method (unless the `name` @Action parameter was specified).

This name is used as a prefix to look up action resources, and the ApplicationContext Framework uses it as the key for this Action in ApplicationActionMaps.

Note: this property should not confused with the `Action.NAME` key. That key is actually used to initialize the `text` properties of Swing components, which is why we call the corresponding ApplicationAction resource "Action.text", as in:

     myCloseButton.Action.text = Close

Returns:
  the (read-only) value of the name property

### getResourceMap

public ResourceMap getResourceMap()
The resourceMap for this Action.

Returns:
  the (read-only) value of the resourceMap property

### getActionArgument

protected Object getActionArgument(Class pType, String pKey, ActionEvent actionEvent)
Provides parameter values to @Action methods. By default, parameter values are selected based exclusively on their type:

Parameter Type | Parameter Value
--- | ---
`ActionEvent` | `actionEvent`
`javax.swing.Action` | this `ApplicationAction` object
`ActionMap` | the `ActionMap` that contains this `Action`
`ResourceMap` | the `ResourceMap` of the the `ActionMap` that contains this `Action`
`ApplicationContext` | the value of `ApplicationContext.getInstance()`

ApplicationAction subclasses may also select values based on the value of the `Action.Parameter` annotation, which is passed along as the `pKey` argument to this method:

     @Action public void doAction(@Action.Parameter("myKey") String myParameter) {
        // The value of myParameter is computed by:
        // getActionArgument(String.class, "myKey", actionEvent)
     }

If `pType` and `pKey` aren't recognized, this method calls `actionFailed(java.lang.Exception)` with an IllegalArgumentException.

Parameters:
  `pType` - parameter type
  `pKey` - the value of the @Action.Parameter annotation
  `actionEvent` - the ActionEvent that trigged this Action

### actionPerformed

public void actionPerformed(ActionEvent actionEvent)
This method implements this `Action's` behavior.

If there's a proxy Action then call its actionPerformed method. Otherwise, call the @Action method with parameter values provided by `getActionArgument()`. If anything goes wrong call `actionFailed()`.

Parameters:
  `actionEvent` - @{inheritDoc}
See Also:
  - `setProxy(javax.swing.Action)`
  - `getActionArgument(java.lang.Class, java.lang.String, java.awt.event.ActionEvent)`
  - `Task`

### isEnabled

public boolean isEnabled()
If the proxy action is null and `enabledProperty` was specified, then return the value of the enabled property's is/get method applied to our ApplicationActionMap's `actionsObject`. Otherwise return the value of this Action's enabled property.

Specified by:
  `isEnabled` in interface `Action`
Overrides:
  `isEnabled` in class `AbstractAction`
Returns:
See Also:
  - `setProxy(javax.swing.Action)`
  - `setEnabled(boolean)`
  - `ApplicationActionMap.getActionsObject()`

### setEnabled

public void setEnabled(boolean enabled)
If the proxy action is null and `enabledProperty` was specified, then set the value of the enabled property by invoking the corresponding `set` method on our ApplicationActionMap's `actionsObject`. Otherwise set the value of this Action's enabled property.

Specified by:
  `setEnabled` in interface `Action`
Overrides:
  `setEnabled` in class `AbstractAction`
Parameters:
  `enabled` -
See Also:
  - `setProxy(javax.swing.Action)`
  - `isEnabled()`
  - `ApplicationActionMap.getActionsObject()`

### isSelected

public boolean isSelected()
If the proxy action is null and `selectedProperty` was specified, then return the value of the selected property's is/get method applied to our ApplicationActionMap's `actionsObject`. Otherwise return the value of this Action's enabled property.

Returns:
  true if this Action's JToggleButton is selected
See Also:
  - `setProxy(javax.swing.Action)`
  - `setSelected(boolean)`
  - `ApplicationActionMap.getActionsObject()`

### setSelected

public void setSelected(boolean selected)
If the proxy action is null and `selectedProperty` was specified, then set the value of the selected property by invoking the corresponding `set` method on our ApplicationActionMap's `actionsObject`. Otherwise set the value of this Action's selected property.

Parameters:
  `selected` - this Action's JToggleButton's value
See Also:
  - `setProxy(javax.swing.Action)`
  - `isSelected()`
  - `ApplicationActionMap.getActionsObject()`

### putValue

public void putValue(String key, Object value)
Keeps the `@Action selectedProperty` in sync when the value of `key` is `Action.SELECTED_KEY`.

Specified by:
  `putValue` in interface `Action`
Overrides:
  `putValue` in class `AbstractAction`
Parameters:
  `key` -
  `value` -

### toString

public String toString()
Returns a string representation of this `ApplicationAction` that should be useful for debugging. If the action is enabled it's name is enclosed by parentheses; if it's selected then a "+" appears after the name. If the action will appear with a text label, then that's included too. If the action has a proxy, then we append the string for the proxy action.

Overrides:
  `toString` in class `Object`
Returns:
  A string representation of this ApplicationAction