Author: rwhitcomb Date: Tue Apr 13 17:50:59 2021 New Revision: 1888738 URL: http://svn.apache.org/viewvc?rev=1888738&view=rev Log: PIVOT-1032: Fix "checkstyle" problems in Action; check "isEnabled" before calling "perform" in the Callback class and performAction method; add "getNamedAction" convenience method; add Javadoc.
Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/Action.java Modified: pivot/trunk/wtk/src/org/apache/pivot/wtk/Action.java URL: http://svn.apache.org/viewvc/pivot/trunk/wtk/src/org/apache/pivot/wtk/Action.java?rev=1888738&r1=1888737&r2=1888738&view=diff ============================================================================== --- pivot/trunk/wtk/src/org/apache/pivot/wtk/Action.java (original) +++ pivot/trunk/wtk/src/org/apache/pivot/wtk/Action.java Tue Apr 13 17:50:59 2021 @@ -26,14 +26,19 @@ import org.apache.pivot.util.Utils; /** * Abstract base class for "actions". Actions are common application behaviors - * generally triggered by buttons and keyboard shortcuts. + * generally triggered by buttons, menu items, and keyboard shortcuts. */ public abstract class Action { /** * Action dictionary implementation. + * <p> We wrap the underlying {@code Map<>} implementation so that only a few methods + * are available for use. */ public static final class NamedActionDictionary implements Dictionary<String, Action>, Iterable<String> { + /** + * Private constructor so only we can construct the singleton instance. + */ private NamedActionDictionary() { } @@ -60,14 +65,14 @@ public abstract class Action { @Override public Action remove(final String id) { - Action action = null; + Action removedAction = null; if (containsKey(id)) { - action = namedActions.remove(id); - actionClassListeners.actionRemoved(id, action); + removedAction = namedActions.remove(id); + actionClassListeners.actionRemoved(id, removedAction); } - return action; + return removedAction; } @Override @@ -82,12 +87,25 @@ public abstract class Action { } /** - * A callback for the GUI thread to perform the given action there. + * A callback for the GUI thread to perform the given action there, unless the + * action is disabled at the time {@code run()} is called. */ - public static class Callback implements Runnable { + public static final class Callback implements Runnable { + /** + * The action to be performed in this callback. + */ private Action action; + /** + * The source component that initiated the action. + */ private Component source; + /** + * Construct a callback to perform the action on the GUI (EDT) thread. + * + * @param actionToPerform The action. + * @param actionSource The source component. + */ public Callback(final Action actionToPerform, final Component actionSource) { Utils.checkNull(actionToPerform, "action"); @@ -97,19 +115,37 @@ public abstract class Action { @Override public void run() { - action.perform(source); + if (action.isEnabled()) { + action.perform(source); + } } } + /** + * Flag as to whether this action is currently enabled or not. + */ private boolean enabled = true; + /** + * List per action of the listeners for activity on that action. + */ private ActionListener.Listeners actionListeners = new ActionListener.Listeners(); + /** + * The backing map for the named action dictionary. + */ private static HashMap<String, Action> namedActions = new HashMap<>(); + /** + * The global dictionary associating action ids with their implementations. + */ private static NamedActionDictionary namedActionDictionary = new NamedActionDictionary(); + /** + * Global list of listeners for all action activity. + */ private static ActionClassListener.Listeners actionClassListeners = new ActionClassListener.Listeners(); + /** * Constructor which builds the action and sets it enabled to begin with. */ @@ -119,6 +155,7 @@ public abstract class Action { /** * Constructor to build the action and set the enabled state at the beginning. + * * @param initialEnable Whether the action is to be initially enabled. */ public Action(final boolean initialEnable) { @@ -143,7 +180,7 @@ public abstract class Action { public abstract void perform(Component source); /** - * Perform the named action. + * Perform the named action, unless the action is disabled. * <p> This is the equivalent of * <code>Action.getNamedActions().get(<i>actionName</i>).perform(<i>comp</i>)</code>. * @@ -158,13 +195,34 @@ public abstract class Action { Action action = namedActionDictionary.get(actionName); Utils.checkNull(action, "action"); - action.perform(comp); + if (action.isEnabled()) { + action.perform(comp); + } } + /** + * Check if this action is currently enabled. + * + * @return Whether or not this action is currently enabled. + * @see #setEnabled + */ public boolean isEnabled() { return enabled; } + /** + * Set this action enabled or disabled. + * <p> Note: in general, the {@link #perform} method can be called whether or not + * this flag is set, so it will be incumbent on the caller to determine if this is + * appropriate. However, using the {@link Callback} class or the {@link #performAction} + * method WILL check this flag before calling {@link #perform}. + * <p> Also note: buttons and menu items that invoke this action will automatically + * be enabled/disabled by setting this flag. + * <p> If the enabled state changes, the associated {@link ActionListener#enabledChanged} + * method(s) will be called. + * + * @param enabledState The new enabled state for the action. + */ public void setEnabled(final boolean enabledState) { if (enabled != enabledState) { enabled = enabledState; @@ -184,14 +242,35 @@ public abstract class Action { return namedActionDictionary.put(id, action); } + /** + * Get the named action from the dictionary. + * <p> This is the equivalent of <code>getNamedActions().get(<i>id</i>)</code> + * + * @param id The name this action was stored under in the dictionary. + * @return The action currently associated with this id (or {@code null} if + * there is no saved action with that id value). + */ + public static Action getNamedAction(final String id) { + return namedActionDictionary.get(id); + } + + /** + * @return The global named action dictionary. + */ public static NamedActionDictionary getNamedActions() { return namedActionDictionary; } + /** + * @return The list of listeners for this action. + */ public ListenerList<ActionListener> getActionListeners() { return actionListeners; } + /** + * @return The list of listeners for all action activities. + */ public static ListenerList<ActionClassListener> getActionClassListeners() { return actionClassListeners; }