com.sun.jaf.ui
Class ActionManager

java.lang.Object
  |
  +--com.sun.jaf.ui.ActionManager

public class ActionManager

extends Object

The ActionManager manages sets of javax.swing.Action. The Actions are speficied in an XML configuration file and will be lazily created when referenced. The schema for the XML document contains three major elements.

• action Represents the properties of an Action.
• action-list Represents lists and trees of actions which can be used to construct user interface components like toolbars, menus and popups.
• action-set The document root which contains a set of action-lists and actions.

All of these elements have a unique id tag which is used by the ActionManager to reference the element. Refer to action-set.dtd for details on the elements and attributes.

The order of an action in an action-list will reflect to the order of the Action based component in the container. A tree is represented as an action-list that contains one or more action-lists.

Once the Actions have been created you need to register callback methods that perform the logic of the associated Action. A typical use case of the ActionManager is:

   ActionManager manager = ActionManager.getInstance();
   // Load an action-set XML document

   manager.loadActions(new URL("my-actions.xml));
   // Register a callback for a particular Action

   manager.registerCallback("new-action", actionHandler, "handleNewCommand");
 
   // Change the state of the action:
   manager.setEnabled("new-action", newState);
 

The ActionManager also supports Actions that can have a selected state associated with them. These Actions are typically represented by a JCheckBox or similar widget. For such actions the registered method is invoked with an additional parameter indicating the selected state of the widget. For example, for the callback handler:

 
  public class Handler {
      public void stateChanged(boolean newState);
   }
 

The registration method would look similar:

  manager.registerCallback("select-action", new Handler(), "stateChanged");
 

The stateChanged method would be invoked as the selected state of the widget changed. Additionally if you need to change the selected state of the Action use the ActionManager method setSelected.

The UIFactory uses the managed Actions in the ActionManager to create user interface components. For example, to create a JMenu based on an action-list id:

 JMenu file = UIFactory.getInstance().createMenu("file-menu");
 

Author:

Mark Davidson

See Also:

UIFactory, action-set.dtd

Constructor Summary

ActionManager()
Creates the action manager

Method Summary

Action	getAction(Object id) Retrieves the action corresponding to an action id.
Set	getActionIDs() Returns the ids for all the managed actions.
Set	getActionListIDs() Retrieve the ids for all the managed action-lists.
Set	getActionSetIDs() Retrieve the ids for all the managed actions-sets.
static com.sun.jaf.ui.ActionManager	getInstance() Return the instance of the ActionManger.
boolean	isEnabled(Object id) Returns the enabled state of the Action.
boolean	isSelected(Object id) Gets the selected state of a toggle action.
boolean	isStateChangeAction(Object id) Determines if the Action corresponding to the action id is a state changed action (toggle, group type action).
void	loadActions(InputStream stream) Adds the set of actions and action-lists from an action-set document into the ActionManager.
void	loadActions(URL url) Adds the set of actions and action-lists from an action-set document into the ActionManager.
void	registerCallback(Object id, Object handler, String method) Registers a callback method when the Action corresponding to the action id is invoked.
void	setEnabled(Object id, boolean enabled) Enables or disables the state of the Action corresponding to the action id.
static void	setInstance(com.sun.jaf.ui.ActionManager manager) Sets the ActionManager instance.
void	setSelected(Object id, boolean selected) Sets the selected state of a toggle action.
void	unloadActions(Object actionset) Unloads the actions that are assocated with the action-set from the action manager.

Methods inherited from class java.lang.Object

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

Constructor Detail

ActionManager

public ActionManager()

Creates the action manager

Method Detail

getInstance

public static com.sun.jaf.ui.ActionManager getInstance()

Return the instance of the ActionManger. If this has not been explicity set then it will be created.

Returns:

the ActionManager instance.

See Also:

setInstance(com.sun.jaf.ui.ActionManager)

setInstance

public static void setInstance(com.sun.jaf.ui.ActionManager manager)

Sets the ActionManager instance.

unloadActions

public void unloadActions(Object actionset)

Unloads the actions that are assocated with the action-set from the action manager. Note: This method removes the actions and references from the action manager. References to the action may still be held in component that were created from actions.

Parameters:

actionset - the action-set id

getActionIDs

public Set getActionIDs()

Returns the ids for all the managed actions.

An action id is a unique idenitfier which can be used to retrieve the corrspondng 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

getActionSetIDs

public Set getActionSetIDs()

Retrieve the ids for all the managed actions-sets.

An action set is an association between an action-set id and the action ids that it contains. For example, the actions-core.xml action-set document has the action-set id: "core-actions" that contains the actions: new-command, open-command, save-command, etc...

Returns:

a set which represents all the action-set ids

getActionListIDs

public Set getActionListIDs()

Retrieve the ids for all the managed action-lists.

An action-list is an ordered collection of actions, action-lists and empty elements which could represent containers of actions. These action-list ids can be used in factory classes to construct ui action containers like menus, toolbars and popups.

Returns:

a set which represents all the action-list ids

getAction

public Action getAction(Object id)

Retrieves the action corresponding to an action id.

Parameters:

id - value of the action id

Returns:

an Action or null if id

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)

Returns the enabled state of the Action. When enabled, any component associated with this object is active and able to fire this object's actionPerformed method.

Parameters:

id - value of the action id

Returns:

true if this Action is enabled; false if the action doesn't exist or disabled.

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 is selected; false if the action doesn't exist or is disabled.

loadActions

public void loadActions(URL url)
                 throws IOException

Adds the set of actions and action-lists from an action-set document into the ActionManager. A call to this method usually takes the form: ActionManager.getInstance().loadActions(getClass().getResource("myActions.xml"));

Parameters:

url - URL pointing to an actionSet document

Throws:

IOException - If there is an error in parsing

loadActions

public void loadActions(InputStream stream)
                 throws IOException

Adds the set of actions and action-lists from an action-set document into the ActionManager.

Parameters:

stream - InputStream containing an actionSet document

Throws:

IOException - If there is an error in parsing

registerCallback

public void registerCallback(Object id,
                             Object handler,
                             String method)

Registers a callback method when the Action corresponding to the action id is invoked. When a Component that was constructed from the Action identified by the action id invokes actionPerformed then the method named will be invoked on the handler Object.

If the Action represented by the action id is a StateChangeAction, then the method passed should take an int as an argument. The value of getStateChange() on the ItemEvent object will be passed as the parameter.

Parameters:

id - value of the action id

handler - the object which will be perform the action

method - the name of the method on the handler which will be called.

isStateChangeAction

public boolean isStateChangeAction(Object id)

Determines if the Action corresponding to the action id is a state changed action (toggle, group type action).

Parameters:

id - value of the action id

Returns:

true if the action id represents a multi state action; false otherwise