org.jdesktop.swingx.action

Class TargetManager

java.lang.Object

org.jdesktop.swingx.action.TargetManager

public class TargetManager
extends Object

The target manager dispatches commands to Targetable objects that it manages. This design of this class is based on the Chain of Responsiblity and Mediator design patterns. The target manager acts as a mediator between TargetableActions and the intended targets. This allows Action based components to invoke commands on components without explicitly binding the user Action to the component action.

The target manager maintains a reference to a current target and a target list. The target list is managed using the addTarget and removeTarget methods. The current target is managed using the setTarget and getTarget methods.

Commands are dispatched to the Targetable objects in the doCommand method in a well defined order. The doCommand method on the Targetable object is called and if it returns true then the command has been handled and command dispatching will stop. If the Targetable doCommand method returns false then the

If none of the Targetable objects can handle the command then the default behaviour is to retrieve an Action from the ActionMap of the permanent focus owner with a key that matches the command key. If an Action can be found then the actionPerformed method is invoked using an ActionEvent that was constructed using the command string.

If the Action is not found on the focus order then the ActionMaps of the ancestor hierarchy of the focus owner is searched until a matching Action can be found. Finally, if none of the components can handle the command then it is dispatched to the ActionMap of the current Application instance.

The order of command dispatch is as follows:

• Current Targetable object invoking doCommand method
• List order of Targetable objects invoking doCommand method
• ActionMap entry of the permanent focus owner invoking actionPerfomed
• ActionMap entry of the ancestor hierarchy of the permanent focus owner
• ActionMap entry of the current Application instance

Author:

Mark Davidson

See Also:

Targetable, TargetableAction

Constructor Summary

Constructors

Constructor and Description
TargetManager() Create a target manager.

Method Summary

Modifier and Type	Method and Description
void	addPropertyChangeListener(PropertyChangeListener listener)
void	addTarget(Targetable target) Appends the target to the target list.
void	addTarget(Targetable target, boolean prepend) Add a target to the target list.
boolean	doCommand(Object command, Object value) Executes the command on the current targetable component.
static TargetManager	getInstance() Return the singleton instance.
Targetable	getTarget() Return the current targetable component.
Targetable[]	getTargets() Returns an array of managed targets that were added with the addTarget methods.
void	removePropertyChangeListener(PropertyChangeListener listener)
void	removeTarget(Targetable target) Remove the target from the list
void	setTarget(Targetable newTarget) Gets the current targetable component.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TargetManager

public TargetManager()

Create a target manager. Use this constructor if the application may support many target managers. Otherwise, using the getInstance method will return a singleton.

Method Detail

getInstance

public static TargetManager getInstance()

Return the singleton instance.

addTarget

public void addTarget(Targetable target,
                      boolean prepend)

Add a target to the target list. Will be appended to the list by default. If the prepend flag is true then the target will be added at the head of the list.

Targets added to the head of the list will will be the first to handle the command.

Parameters:

target - the targeted object to add

prepend - if true add at the head of the list; false append

addTarget

public void addTarget(Targetable target)

Appends the target to the target list.

Parameters:

target - the targeted object to add

removeTarget

public void removeTarget(Targetable target)

Remove the target from the list

getTargets

public Targetable[] getTargets()

Returns an array of managed targets that were added with the addTarget methods.

Returns:

all the Targetable added or an empty array if no targets have been added

setTarget

public void setTarget(Targetable newTarget)

Gets the current targetable component. May or may not in the target list. If the current target is null then the the current targetable component will be the first one in the target list which can execute the command. This is a bound property and will fire a property change event if the value changes.

Parameters:

newTarget - the current targetable component to set or null if the TargetManager shouldn't have a current targetable component.

getTarget

public Targetable getTarget()

Return the current targetable component. The curent targetable component is the first place where commands will be dispatched.

Returns:

the current targetable component or null

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)

doCommand

public boolean doCommand(Object command,
                         Object value)

Executes the command on the current targetable component. If there isn't current targetable component then the list of targetable components are searched and the first component which can execute the command. If none of the targetable components handle the command then the ActionMaps of the focused components are searched.

Parameters:

command - the key of the command

value - the value of the command; depends on context

Returns:

true if the command has been handled otherwise false