com.ehsbe.commons.action
Class ActionManager

java.lang.Object
  com.ehsbe.commons.action.ActionManager

All Implemented Interfaces:

ActionListener, ItemListener, PropertyChangeListener, EventListener

public class ActionManager
extends Object
implements ActionListener, ItemListener, PropertyChangeListener

The ActionManager manages sets of javax.swing.Actions and lists of actions.

All managed actions as well as action lists have a unique ID, which is used by the ActionManager to lookup them up. For actions, this ID maps to the Action.ACTION_COMMAND_KEY on the Action.

The ActionManager registers itself to all added actions as a Listener automatically and delegates all action and state change events to its registered listeners. So there is no need for an [application] controller, to registers to all available actions, just register with the used ActionManager.

On removal of an action, the ActionManager also automatically removes itself from the listener list of the appropriate action.

Author:

Mark Davidson

See Also:

ActionContainerFactory, TargetableAction, BoundAction, TriggerAction

Field Summary

protected CopyOnWriteArrayList<ActionListener>	actionListeners all registered action listeners
protected CopyOnWriteArrayList<ItemListener>	itemListeners all registered item listeners

Constructor Summary

ActionManager()
Creates the action manager.

ActionManager(StreamSource src, Translator i18n, String resPath)
Convinience constructor.

Method Summary

void	actionPerformed(ActionEvent e)
Action	addAction(Action action) Add the given action to this instance.
protected Action	addAction(Object id, Action action) Adds an action to the ActionManager
List<Object>	addActionIDList(String id, List<Object> actionList) Add the given action list with the given id to this instance.
void	addActionIDs(Map<String,List<Object>> cmdLists) Convinience method to add all the action lists in the given map to this instance.
void	addActionListener(ActionListener listener) Register the given listener for receiving action events sent by registered actions of this instance.
void	addActionMap(Collection<Action> actions) Convinience method to add all the actions in the given map to this instance.
void	addGroupButton(String groupId, AbstractButton button) Convinience method to add a button to the button group associated with the given groupId.
void	addItemListener(ItemListener listener) Register the given listener for receiving item events sent by registered actions of this instance.
<T> T	getAction(Class<T> clazz, Object id) Convinience method to get the action with the given ID of the given class.
Action	getAction(Object id) Get the action corresponding to an action id.
List<Action>	getActionCopy(List<?> src, boolean withoutMnemonic, ActionListener listener) Get a list of all actions wrt. to the given possibly nested list of IDs.
ManagedAction	getActionCopy(Object id, boolean withoutMnemonics, ActionListener listener) Get a copy aka clone of the action corresponding to an action id.
Set<Object>	getActionIDs() Get the ids for all the managed actions.
List<Object>	getActionIDs(String id) Get the possibly nested action ID list for the given id.
Set<String>	getActionListIDs() Get the ids for all the managed action lists.
ButtonGroup	getButtonGroup(String groupId) Get the button group associated with the given group ID
Set<String>	getGroup(String groupId) Get all action IDs, which belong to the group with the given id.
Set<String>	getGroupIDs() Get the IDs of all managed action groups.
static ActionManager	getInstance() Get the instance of the ActionManger.
boolean	isEnabled(Object id) Get the enabled state of the action with the given id.
boolean	isSelected(Object id) Gets the selected state of a toggle action.
void	itemStateChanged(ItemEvent e)
void	propertyChange(PropertyChangeEvent evt) Adjust groups, when a managed action changes is group value.
Action	removeAction(Object id) Remove the action with the given id from this instance.
List<Object>	removeActionIDList(String id) Remove the action list with the given id from this instance.
void	removeActionListener(ActionListener listener) Unregister the given listener for receiving action events sent by registered actions of this instance.
void	removeItemListener(ItemListener listener) Unregister the given listener for receiving item events sent by registered actions of this instance.
void	setEnabled(Object id, boolean enabled) Enables or disables the state of the Action corresponding to the action id.
void	setSelected(Object id, boolean selected) Sets the selected state of a toggle action.

Methods inherited from class java.lang.Object

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

Field Detail

actionListeners

protected CopyOnWriteArrayList<ActionListener> actionListeners

all registered action listeners

itemListeners

protected CopyOnWriteArrayList<ItemListener> itemListeners

all registered item listeners

Constructor Detail

ActionManager

public ActionManager()

Creates the action manager. Use this constuctor if the application should support many ActionManagers. Otherwise, using the getInstance method will return a singleton.

ActionManager

public ActionManager(StreamSource src,
                     Translator i18n,
                     String resPath)

Convinience constructor.

Parameters:

src - stream to read and parse (passed to ActionFactory)

i18n - bundle to use for i18n (passed to ActionFactory)

resPath - base path for resolving relative pathes to icons (passed to ActionFactory)

See Also:

ActionFactory.load(StreamSource, Translator, String, HashMap, HashMap), addActionMap(Collection), addActionIDs(Map)

Method Detail

getInstance

public static ActionManager getInstance()

Get the instance of the ActionManger.

Returns:

the ActionManager singleton instance.

getActionIDs

public Set<Object> getActionIDs()

Get the ids for all the managed actions.

An action id is a unique idenitfier which can be used to retrieve the corrsponding Action from the ActionManager. This identifier can also be used to set the properties of the action through the action manager like setting the state of the enabled or selected flags.

Returns:

a set which represents all the action ids

getActionListIDs

public Set<String> getActionListIDs()

Get the ids for all the managed action lists.

An action list id is a unique idenitfier which can be used to retrieve the corrsponding action lists from the ActionManager.

Returns:

a set which represents all the action list ids

getGroupIDs

public Set<String> getGroupIDs()

Get the IDs of all managed action groups.

Returns:

null if this instance does not contain any action which belongs to a group, the IDs of all groups otherwise.

getGroup

public Set<String> getGroup(String groupId)

Get all action IDs, which belong to the group with the given id.

Parameters:

groupId - action group ID

Returns:

null, if there is no registered action associated with the given group ID, a set of action IDs otherwise.

getButtonGroup

public ButtonGroup getButtonGroup(String groupId)

Get the button group associated with the given group ID

Parameters:

groupId - ID of the button group to lookup

Returns:

null if not found, the button group otherwise.

addGroupButton

public void addGroupButton(String groupId,
                           AbstractButton button)

Convinience method to add a button to the button group associated with the given groupId.

Parameters:

groupId - group ID of the target button group

button - button to add

Throws:

IllegalArgumentException - if the given groupId is not known by this instance (i.e. there is no action with such a groupID)

addAction

public Action addAction(Action action)

Add the given action to this instance. The actions Action.ACTION_COMMAND_KEY will be used as the action's ID.

Parameters:

action - action to add.

Returns:

the action, which has been replaced by the given action.

addActionMap

public void addActionMap(Collection<Action> actions)

Convinience method to add all the actions in the given map to this instance.

Parameters:

actions - list of actions to add.

See Also:

addAction(Action)

addActionIDs

public void addActionIDs(Map<String,List<Object>> cmdLists)

Convinience method to add all the action lists in the given map to this instance.

Parameters:

cmdLists - action list map to add.

See Also:

Map.putAll(java.util.Map)

addAction

protected Action addAction(Object id,
                           Action action)

Adds an action to the ActionManager

Parameters:

id - value of the action id. The action manager relies on the fact, that the given id is the same as the ACTION_COMMAND_KEY. If not, you may see unexpected behavior !

action - Action to be managed

Returns:

the action, which has been replaced by the given action.

removeAction

public Action removeAction(Object id)

Remove the action with the given id from this instance.

Parameters:

id - id of the action to remove

Returns:

null if there is no action with the given id, the removed action otherwise.

addActionIDList

public List<Object> addActionIDList(String id,
                                    List<Object> actionList)

Add the given action list with the given id to this instance.

An action list should contain action IDs, null, and/or other action lists (i.e. action sublists). Usually one does not need to register action sublists with this instance, however it might be helpful to do so.

Action lists might be used to create complete menu trees and/or toolbars, etc.

Parameters:

id - id of the action list to add.

actionList - actionList to add.

Returns:

the action list, which has been replaced by the given action list.

See Also:

ActionContainerFactory.createMenuBar(List, ActionManager), ActionContainerFactory.createPopup(List, ActionManager), ActionContainerFactory.createMenu(List, javax.swing.JComponent, ActionManager), ActionContainerFactory.createToolBar(List, ActionManager)

removeActionIDList

public List<Object> removeActionIDList(String id)

Remove the action list with the given id from this instance. NOTE: It just removes the list, but NOT the action, the list refers to.

Parameters:

id - id fo the action list to remove

Returns:

null if no list with the given ID has been found, the removed list otherwise.

getAction

public Action getAction(Object id)

Get the action corresponding to an action id.

Parameters:

id - value of the action id

Returns:

null if there is no action with the given id, the appropriate action otherwise.

getActionCopy

public ManagedAction getActionCopy(Object id,
                                   boolean withoutMnemonics,
                                   ActionListener listener)

Get a copy aka clone of the action corresponding to an action id.

At the moment, ManagedAction action copies are supported, only (since they provide a public clone() method).

Parameters:

id - value of the action id

withoutMnemonics - if true, mnemonics are removed from the action cloned.

listener - an optional action listener, which should be added to the action clone immediately. If null it gets ignored.

Returns:

null if there is no action with the given id or the action in question is not clonable, the appropriate cloned action otherwise.

See Also:

ManagedAction.clone()

getActionCopy

public List<Action> getActionCopy(List<?> src,
                                  boolean withoutMnemonic,
                                  ActionListener listener)

Get a list of all actions wrt. to the given possibly nested list of IDs. All actions in the returned list are clones.

Parameters:

src - a (possibly nested) list of action IDs or null

withoutMnemonic - if true, mnemonics are removed from the action clone.

listener - an optional action listener, which should be added to the action clone immediately. If null it gets ignored.

Returns:

a possibly empty action list.

See Also:

getActionCopy(Object, boolean, ActionListener)

getActionIDs

public List<Object> getActionIDs(String id)

Get the possibly nested action ID list for the given id.

Parameters:

id - ID of the action ID list to lookup

Returns:

null if there is no action list with the given id, the appropriate action list otherwise (which might be null as well).

getAction

public <T> T getAction(Class<T> clazz,
                       Object id)

Convinience method to get the action with the given ID of the given class.

Type Parameters:

T - type of the action to lookup

Parameters:

clazz - class of the action to lookup

id - id of the action in question

Returns:

null if the is no action with the given ID or the found action is not of the specified type, the found action otherwise

setEnabled

public void setEnabled(Object id,
                       boolean enabled)

Enables or disables the state of the Action corresponding to the action id. This method should be used by application developers to ensure that all components created from an action remain in synch with respect to their enabled state.

Parameters:

id - value of the action id

enabled - true if the action is to be enabled; otherwise false

isEnabled

public boolean isEnabled(Object id)

Get the enabled state of the action with the given id.

Parameters:

id - value of the action id

Returns:

true if the action with the given id has been found and is enabled.

See Also:

Action.isEnabled()

setSelected

public void setSelected(Object id,
                        boolean selected)

Sets the selected state of a toggle action. If the id doesn't correspond to a toggle action then it will fail silently.

Parameters:

id - the value of the action id

selected - true if the action is to be selected; otherwise false.

isSelected

public boolean isSelected(Object id)

Gets the selected state of a toggle action. If the id doesn't correspond to a toggle action then it will fail silently.

Parameters:

id - the value of the action id

Returns:

true if the action with the given id has been found and is selected.

addActionListener

public void addActionListener(ActionListener listener)

Register the given listener for receiving action events sent by registered actions of this instance.

Parameters:

listener - listener to add

addItemListener

public void addItemListener(ItemListener listener)

Register the given listener for receiving item events sent by registered actions of this instance.

Parameters:

listener - listener to add

removeActionListener

public void removeActionListener(ActionListener listener)

Unregister the given listener for receiving action events sent by registered actions of this instance.

Parameters:

listener - listener to remove

removeItemListener

public void removeItemListener(ItemListener listener)

Unregister the given listener for receiving item events sent by registered actions of this instance.

Parameters:

listener - listener to remove

actionPerformed

public void actionPerformed(ActionEvent e)

Specified by:

actionPerformed in interface ActionListener

itemStateChanged

public void itemStateChanged(ItemEvent e)

Specified by:

itemStateChanged in interface ItemListener

propertyChange

public void propertyChange(PropertyChangeEvent evt)

Adjust groups, when a managed action changes is group value.

Specified by:

propertyChange in interface PropertyChangeListener

Parameters:

evt - action change event