org.jdesktop.application
Class ApplicationAction

java.lang.Object
  extended by javax.swing.AbstractAction
      extended by org.jdesktop.application.ApplicationAction
All Implemented Interfaces:
java.awt.event.ActionListener, java.io.Serializable, java.lang.Cloneable, java.util.EventListener, javax.swing.Action

public class ApplicationAction
extends javax.swing.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);
     }
     // ....
 }
 

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, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SHORT_DESCRIPTION, SMALL_ICON
 
Constructor Summary
ApplicationAction(ApplicationActionMap appAM, ResourceMap resourceMap, java.lang.String baseName, java.lang.reflect.Method actionMethod, java.lang.String enabledProperty, java.lang.String selectedProperty, Task.BlockingScope block)
          Construct an ApplicationAction that implements an @Action.
 
Method Summary
 void actionPerformed(java.awt.event.ActionEvent actionEvent)
          This method implements this Action's behavior.
protected  java.lang.Object getActionArgument(java.lang.Class pType, java.lang.String pKey, java.awt.event.ActionEvent actionEvent)
          Provides parameter values to @Action methods.
 java.lang.String getName()
          The name of this Action.
 javax.swing.Action getProxy()
          Return the proxy for this action or null.
 java.lang.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(java.lang.String key, java.lang.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(javax.swing.Action proxy)
          Set the proxy for this action.
 void setProxySource(java.lang.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.
 java.lang.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
 

Constructor Detail

ApplicationAction

public ApplicationAction(ApplicationActionMap appAM,
                         ResourceMap resourceMap,
                         java.lang.String baseName,
                         java.lang.reflect.Method actionMethod,
                         java.lang.String enabledProperty,
                         java.lang.String selectedProperty,
                         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:

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.
selectedProperty - name of the selected property.
block - how much of the GUI to block while this action executes.
See Also:
getName(), ApplicationActionMap.getActionsClass(), ApplicationActionMap.getActionsObject()
Method Detail

getProxy

public javax.swing.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(javax.swing.Action proxy)
Set the proxy for this action. If the proxy is non-null then we delegate/track the following:

See Also:
setProxy(javax.swing.Action), setProxySource(java.lang.Object), actionPerformed(java.awt.event.ActionEvent)

getProxySource

public java.lang.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(java.lang.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 java.lang.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 java.lang.Object getActionArgument(java.lang.Class pType,
                                             java.lang.String pKey,
                                             java.awt.event.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.awt.event.ActionEvent, 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(java.awt.event.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 javax.swing.Action
Overrides:
isEnabled in class javax.swing.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 javax.swing.Action
Overrides:
setEnabled in class javax.swing.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(java.lang.String key,
                     java.lang.Object value)
Keeps the @Action selectedProperty in sync when the value of key is Action.SELECTED_KEY.

Specified by:
putValue in interface javax.swing.Action
Overrides:
putValue in class javax.swing.AbstractAction
Parameters:
key -
value -

toString

public java.lang.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 java.lang.Object
Returns:
A string representation of this ApplicationAction