org.pietschy.command
Class ActionCommand

java.lang.Object
  extended by org.pietschy.command.Command
      extended by org.pietschy.command.ActionCommand
All Implemented Interfaces:
ActionCommandExecutor
Direct Known Subclasses:
AboutCommand, AbstractFileCommand, BeepCommand, CompoundCommand, DelegatingCommand, LazyCommand, OpenUrlCommand, ReflectionCommand, ToggleCommand, UndoableActionCommand

public abstract class ActionCommand
extends Command
implements ActionCommandExecutor

ActionCommands provide the base for all executable commands. Subclasses must implement handleExecute() to provide command specific behaviour.


Field Summary
static java.lang.String HINT_ACTION_EVENT
          The key for the action event hint.
static java.lang.String HINT_INVOKER
          The key for the invoker hint.
static java.lang.String HINT_INVOKER_WINDOW
          The key for the invoker window hint.
static java.lang.String HINT_MODIFIERS
          The key for the modifiers hint.
 
Fields inherited from class org.pietschy.command.Command
internalLog, listenerList, pcs
 
Constructor Summary
ActionCommand()
          Creates a new anonymous ActionCommand.
ActionCommand(CommandManager commandManager)
          Creates a new anonymous command bound to the specified CommandManager.defaultInstance().
ActionCommand(CommandManager commandManager, java.lang.String commandId)
          Creates a new ActionCommand with the specified id that is bound to the specified CommandManager.
ActionCommand(java.lang.String id)
          Creates a new command with the speicifed Id that is bound to the CommandManager.defaultInstance().
 
Method Summary
 void addCommandListener(CommandListener l)
          Deprecated. Use addInterceptor(ActionCommandInterceptor) instead.
 void addInterceptor(ActionCommandInterceptor interceptor)
          Adds an ActionCommandInterceptor the the command.
protected  boolean areEqual(java.lang.Object oldValue, java.lang.Object newValue)
          Checks if the the two values are equal.
 void attach(javax.swing.AbstractButton button, java.lang.String faceName)
          Overrides the default implementation to also installFace an ActionListener to the button.
protected  void configureButtonStates(javax.swing.AbstractButton button)
          This method is called to configure newly created buttons.
 void detach(javax.swing.AbstractButton button)
          Overrides the default implementation to remove the ActionListener installed by attach(javax.swing.AbstractButton, String).
 void execute()
          Causes the command to perform it's operation.
 void execute(java.util.Map hints)
          Executes this command with the specified hints.
 javax.swing.Action getActionAdapter()
          Gets an action that mirrors the default face of this command.
 javax.swing.Action getActionAdapter(java.lang.String faceName)
          Gets an action that mirrors this the specified face of this command.
 java.lang.String getActionCommand()
          Gets the value of this commands actionCommand string.
 java.awt.event.ActionEvent getActionEvent()
          Convenience method for getHint(ActionCommand.HINT_ACTION_EVENT).
 java.lang.Object getHint(java.lang.Object key)
          Gets any hints that may have been specified by a call to execute(java.util.Map) or that have been explicitly set by putHint(java.lang.Object, java.lang.Object).
 java.lang.Object getHint(java.lang.Object key, java.lang.Object defaultValue)
          Gets any hints that may have been specified by a call to execute(java.util.Map) or that have been explicitly set by putHint(java.lang.Object, java.lang.Object).
 java.util.Map getHints()
          Gets any hints that may have been specified by a call to execute(java.util.Map) or that have been explicitly set by putHint(java.lang.Object, java.lang.Object).
 java.lang.Object getInvoker()
          Convenience method to get the object that invoked the command.
 java.awt.Window getInvokerWindow()
          Convenience method to get the Window ancestor of the object that invoked the command.
 int getModifiers()
          Convenience method to get any modifiers that were specified.
protected abstract  void handleExecute()
          Main entry point for command subclasses that must be implemented to provide command specific behaviour.
 void installShortCut(javax.swing.JComponent component, int condition)
          Installs a shortcut into the components input and action maps using the accelerator specified by the default face.
 void installShortCut(javax.swing.JComponent component, java.lang.String faceName, int condition)
          Installs a shortcut into the components input and action maps using the accelerator of the specified face.
protected  void postExecute()
          This method is called after handleExecute() has been called.
protected  boolean preExecute()
          This method is called prior to handleExecute() being called.
 void putHint(java.lang.Object key, java.lang.Object value)
          Adds the specified hint to be available the next time execute(java.util.Map) is called.
 void putHints(java.util.Map hints)
          Adds the specified hints to be available the next time execute(java.util.Map) is called.
 void removeCommandListener(CommandListener l)
          Deprecated. use removeInterceptor(ActionCommandInterceptor) instead.
 void removeInterceptor(ActionCommandInterceptor interceptor)
          Removes an ActionCommandInterceptor from the command.
 void requestDefautIn(javax.swing.RootPaneContainer container)
          This method will find the first button from this command in the RootPaneContainer and set it to be the default button by calling JRootPane.setDefaultButton(javax.swing.JButton).
 void setActionCommand(java.lang.String actionCommand)
          Sets the value of this commands actionCommand string.
 void uninstallShortCut(javax.swing.JComponent component, int condition)
          Removes the short cut installed by a previous call to installShortCut(javax.swing.JComponent, int)
 void uninstallShortCut(javax.swing.JComponent component, java.lang.String faceName, int condition)
          Removes the short cut installed by a previous call to installShortCut(javax.swing.JComponent, String, int)
 
Methods inherited from class org.pietschy.command.Command
addFace, addHoverListener, addNewFace, addNotify, addPropertyChangeListener, addPropertyChangeListener, buttonIterator, configureButtonAppearance, configureButtonAppearances, configureButtonAppearances, createButton, createButton, createButton, createButton, createMenuItem, createMenuItem, createMenuItem, createMenuItem, export, faceExists, fireHoverEnded, fireHoverStarted, getAccelerator, getAlternativeFaceNames, getButtonFactory, getButtonIn, getCommandManager, getDefaultFace, getDefaultFace, getDescription, getFace, getFace, getIcon, getId, getLongDescription, getMenuFactory, getMnemonic, getMnemonicIndex, getProperty, getProperty, getPropertyNames, getSelectedIcon, getText, getTextPosition, getToolbarFactory, initCommandManager, installFace, isAnonymous, isAttachedTo, isEnabled, isVisible, putProperty, removeHoverListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, requestFocusIn, setAccelerator, setButtonFactory, setDescription, setEnabled, setIcon, setLongDescription, setMenuFactory, setMnemonic, setMnemonicIndex, setSelectedIcon, setText, setTextPosition, setToolbarFactory, setVisible, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.pietschy.command.ActionCommandExecutor
addPropertyChangeListener, addPropertyChangeListener, isEnabled, removePropertyChangeListener, removePropertyChangeListener
 

Field Detail

HINT_ACTION_EVENT

public static final java.lang.String HINT_ACTION_EVENT
The key for the action event hint. This hint will be present when ever the command is invoked from an attached AbstractButton.

See Also:
Constant Field Values

HINT_MODIFIERS

public static final java.lang.String HINT_MODIFIERS
The key for the modifiers hint. This hint will be present when ever the command is invoked from an attached AbstractButton.

See Also:
getModifiers(), Constant Field Values

HINT_INVOKER

public static final java.lang.String HINT_INVOKER
The key for the invoker hint. This hint will be present when ever the command is invoked from an attached AbstractButton.

See Also:
getInvoker(), Constant Field Values

HINT_INVOKER_WINDOW

public static final java.lang.String HINT_INVOKER_WINDOW
The key for the invoker window hint. This hint will be present whenever the a Window parent can be found from the invoker.

See Also:
getInvokerWindow(), Constant Field Values
Constructor Detail

ActionCommand

public ActionCommand()
Creates a new anonymous ActionCommand. Anonymous commands must be fully programatically generated and can only be added to groups manually by calling groupCommand.installFace(myAnonymousCommand).


ActionCommand

public ActionCommand(java.lang.String id)
Creates a new command with the speicifed Id that is bound to the CommandManager.defaultInstance().


ActionCommand

public ActionCommand(CommandManager commandManager)
Creates a new anonymous command bound to the specified CommandManager.defaultInstance().


ActionCommand

public ActionCommand(CommandManager commandManager,
                     java.lang.String commandId)
Creates a new ActionCommand with the specified id that is bound to the specified CommandManager.

Method Detail

handleExecute

protected abstract void handleExecute()
Main entry point for command subclasses that must be implemented to provide command specific behaviour.

This method should never be called directly to invoke a comand. All command invocation must be performed using the execute() and execute(Map) methods.


execute

public final void execute(java.util.Map hints)
Executes this command with the specified hints. The hints are added to any existing hints that have been configured using putHint(java.lang.Object, java.lang.Object). The hints are only available for this execution of the command.

Specified by:
execute in interface ActionCommandExecutor
Parameters:
hints - the hints this command is to use.
See Also:
putHint(java.lang.Object, java.lang.Object), getHint(java.lang.Object)

execute

public final void execute()
Causes the command to perform it's operation. Subclasses must implement handleExecute() to customize this commands behaviour.


requestDefautIn

public void requestDefautIn(javax.swing.RootPaneContainer container)
This method will find the first button from this command in the RootPaneContainer and set it to be the default button by calling JRootPane.setDefaultButton(javax.swing.JButton).

Parameters:
container - the root pane container to check.

putHint

public void putHint(java.lang.Object key,
                    java.lang.Object value)
Adds the specified hint to be available the next time execute(java.util.Map) is called.

Parameters:
key - the name of the hint.
value - the hint value.

putHints

public void putHints(java.util.Map hints)
Adds the specified hints to be available the next time execute(java.util.Map) is called.

Parameters:
hints - a list of hints to insert.

getHint

public java.lang.Object getHint(java.lang.Object key)
Gets any hints that may have been specified by a call to execute(java.util.Map) or that have been explicitly set by putHint(java.lang.Object, java.lang.Object).

Parameters:
key - the name of the hint.
Returns:
the hint or null if the hint doesn't exist.

getHint

public java.lang.Object getHint(java.lang.Object key,
                                java.lang.Object defaultValue)
Gets any hints that may have been specified by a call to execute(java.util.Map) or that have been explicitly set by putHint(java.lang.Object, java.lang.Object).

Parameters:
key - the name of the hint.
defaultValue - a default to return if the hint wasn't provided.
Returns:
the hint or defaultValue if the hint wasn't specified exist.
See Also:
putHint(java.lang.Object, java.lang.Object)

getHints

public java.util.Map getHints()
Gets any hints that may have been specified by a call to execute(java.util.Map) or that have been explicitly set by putHint(java.lang.Object, java.lang.Object).

Returns:
the hint or defaultValue if the hint wasn't specified exist.
See Also:
putHint(java.lang.Object, java.lang.Object)

getModifiers

public int getModifiers()
Convenience method to get any modifiers that were specified. Modifiers are always copied from any action event that triggers this command.


getInvoker

public java.lang.Object getInvoker()
Convenience method to get the object that invoked the command. If the command was invoked from from a button (or menu) then the invoker will be that button.

Returns:
the AbstractButton that invoked to command. If the command was manually invoked this will return null unless the hint HINT_INVOKER has been explicitly set.

getInvokerWindow

public java.awt.Window getInvokerWindow()
Convenience method to get the Window ancestor of the object that invoked the command. If the invoker is null, or doesn't decend from Component then null is returned. Otherwise, an attempt to find the Window ancestor is made using SwingUtilities.getWindowAncestor(java.awt.Component) or by traversing the ancestors and invokers of popup menus.

Returns:
null if the invoker is null, doesn't extend Component or doesn't have a Window ancestor. Otherwise the invokers Window ancestor is returned.
See Also:
getInvoker()

getActionEvent

public java.awt.event.ActionEvent getActionEvent()
Convenience method for getHint(ActionCommand.HINT_ACTION_EVENT).


attach

public void attach(javax.swing.AbstractButton button,
                   java.lang.String faceName)
Overrides the default implementation to also installFace an ActionListener to the button.

Overrides:
attach in class Command
Parameters:
button - the button to attach to.
faceName - the face the button will be using.

detach

public void detach(javax.swing.AbstractButton button)
Overrides the default implementation to remove the ActionListener installed by attach(javax.swing.AbstractButton, String).

Overrides:
detach in class Command
Parameters:
button - the button to attach to.

configureButtonStates

protected void configureButtonStates(javax.swing.AbstractButton button)
This method is called to configure newly created buttons. Subclasses may override this method to perform special configuration if required.

Overrides:
configureButtonStates in class Command
Parameters:
button - the button to configure.

getActionAdapter

public javax.swing.Action getActionAdapter()
Gets an action that mirrors the default face of this command. This is useful for use with the native cut and paste clipboard methods that require an action.


getActionAdapter

public javax.swing.Action getActionAdapter(java.lang.String faceName)
Gets an action that mirrors this the specified face of this command. This is useful for use with the native cut and paste clipboard methods that require an action.


getActionCommand

public java.lang.String getActionCommand()
Gets the value of this commands actionCommand string. The actionCommand is provided for compatability with Swing actions. If it isn't explicity configured using setActionCommand(java.lang.String) it will be equal to the id of the command.

Returns:
the 'actionCommand' value of this command.

setActionCommand

public void setActionCommand(java.lang.String actionCommand)
Sets the value of this commands actionCommand string. The actionCommand is provided for compatability with Swing actions. If it isn't explicity configured it will be equal to the id of the command.

Parameters:
actionCommand - the new value of the 'actionCommand'.

areEqual

protected boolean areEqual(java.lang.Object oldValue,
                           java.lang.Object newValue)
Checks if the the two values are equal. This method is null safe, that is either value may be null.

Returns:
true if oldValue equals newValue or if both values are null, false otherwise.

preExecute

protected boolean preExecute()
This method is called prior to handleExecute() being called. It simply calls firePreExecute to notify all the register CommandListener that the command is about to execute.


postExecute

protected void postExecute()
This method is called after handleExecute() has been called. It simply calls firePostExecute to notify all the register CommandListener that the command has just completed.


addCommandListener

public void addCommandListener(CommandListener l)
Deprecated. Use addInterceptor(ActionCommandInterceptor) instead.

Adds a CommandListener the the command. The listener will be notified when the command is executed.

Parameters:
l - the CommandListener to register
See Also:
removeCommandListener(org.pietschy.command.CommandListener)

removeCommandListener

public void removeCommandListener(CommandListener l)
Deprecated. use removeInterceptor(ActionCommandInterceptor) instead.

Removes a CommandListener the the command.

Parameters:
l - the CommandListener to removed
See Also:
addCommandListener(org.pietschy.command.CommandListener)

addInterceptor

public void addInterceptor(ActionCommandInterceptor interceptor)
Adds an ActionCommandInterceptor the the command. The interceptor will be invoked before and after the command is executed.

Parameters:
interceptor - the ActionCommandInterceptor to register
See Also:
removeInterceptor(ActionCommandInterceptor)

removeInterceptor

public void removeInterceptor(ActionCommandInterceptor interceptor)
Removes an ActionCommandInterceptor from the command.

Parameters:
interceptor - the ActionCommandInterceptor to remove
See Also:
addInterceptor(ActionCommandInterceptor)

installShortCut

public void installShortCut(javax.swing.JComponent component,
                            int condition)
Installs a shortcut into the components input and action maps using the accelerator specified by the default face.

Parameters:
component - The component to install the short cut in.
condition - The condition as per JComponent.getInputMap(int).

installShortCut

public void installShortCut(javax.swing.JComponent component,
                            java.lang.String faceName,
                            int condition)
Installs a shortcut into the components input and action maps using the accelerator of the specified face.

Parameters:
component - The component to install the short cut in.
faceName - The face that defines the required accelerator.
condition - The condition as per JComponent.getInputMap(int).

uninstallShortCut

public void uninstallShortCut(javax.swing.JComponent component,
                              int condition)
Removes the short cut installed by a previous call to installShortCut(javax.swing.JComponent, int)

Parameters:
component - The component the short cut was installed on.
condition - The condition as per JComponent.getInputMap(int).

uninstallShortCut

public void uninstallShortCut(javax.swing.JComponent component,
                              java.lang.String faceName,
                              int condition)
Removes the short cut installed by a previous call to installShortCut(javax.swing.JComponent, String, int)

Parameters:
component - The component the short cut was installed on.
condition - The condition as per JComponent.getInputMap(int).