Package ca.cgjennings.apps.arkham.project

Class SpecializedAction

  • All Implemented Interfaces:
    IconProvider
    public abstract class SpecializedAction
extends TaskAction
    A superclass for actions that specialize one of the built-in actions by modifying their behaviour. The same action can be specialized multiple times. As long as each instance is well-behaved and passes all calls that they don't care about on to superAction, multiple specializations can only interfere with each other if there is overlap between the cases they specialize. When two or more actions specialize the same case (such as files with a certain extension), only the last one registered takes effect.
    Author:
    Chris Jennings

    • Constructor Summary

      Constructors 
      Constructor Description
      SpecializedAction()
      Creates a specialized action that is initially uninstalled.
      SpecializedAction​(TaskAction action)
      Use this instance to specialize an already registered action.
      SpecializedAction​(java.lang.String name)
      Use this instance to specialize an already registered action by name.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean appliesTo​(Project project, Task task, Member member)
      Returns true if this action can be performed on the specified member of a project, project or a task.
      boolean appliesToSelection​(Member[] members)
      Returns true if this action is applicable to any of the specified Members.
      java.lang.String getActionName()
      Returns a unique internal name for this action.
      java.lang.String getLabel()
      Returns the human-readable name of this action.
      TaskAction getRootAction()
      Returns the topmost super action in the chain of specialized actions.
      TaskAction getSuperAction()
      Returns the action that this action specializes.
      void install​(TaskAction action)
      Installs this specialized action as a specialization of the specified action.
      void install​(java.lang.String name)
      Installs this specialized action as a specialized version of the action with the given name.
      boolean perform​(Project project, Task task, Member member)
      Perform this action on a member of a project, a project or a task.
      boolean performOnSelection​(Member[] members)
      Applies this action to all of the specified project members.
      void uninstall()
      Removes this action from the specialization chain of the root action.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

    • Constructor Detail

      • SpecializedAction

        public SpecializedAction()
        Creates a specialized action that is initially uninstalled. Specialized actions must be installed onto an existing action. The result of trying to use this action before it is installed are undefined.

      • SpecializedAction

        public SpecializedAction​(TaskAction action)
        Use this instance to specialize an already registered action.
        Parameters:
        action - the action that this action specializes
        Throws:
        java.lang.IllegalArgumentException - if action is not registered

      • SpecializedAction

        public SpecializedAction​(java.lang.String name)
        Use this instance to specialize an already registered action by name.
        Parameters:
        name - the name of the action that this action specializes
        Throws:
        java.lang.IllegalArgumentException - if there is no action registered with the given name

    • Method Detail

      • install

        public void install​(java.lang.String name)
        Installs this specialized action as a specialized version of the action with the given name.
        Parameters:
        name - the name of the action to specialize
        Throws:
        java.lang.IllegalArgumentException - if no task is registered with the given name
        See Also:
        install(ca.cgjennings.apps.arkham.project.TaskAction)

      • install

        public void install​(TaskAction action)
        Installs this specialized action as a specialization of the specified action. Note that this action can only be installed once: to reinstall a specialized action after uninstallation, create a new instance of the specialized action.
        Parameters:
        action - the action that this action is a more specialized version of

      • getActionName

        public final java.lang.String getActionName()
        Returns a unique internal name for this action. Actions can be looked up by this name. The default implementation returns the class name, converted to lowercase.

        This implementation returns the same name as that of the original action.

        Overrides:
        getActionName in class TaskAction
        Returns:
        the internal name of this action

      • getLabel

        public java.lang.String getLabel()
        Returns the human-readable name of this action.

        This implementation returns the result of calling this method on the original action.

        Specified by:
        getLabel in class TaskAction
        Returns:
        the name used to create menu items for this action, localized if possible

      • performOnSelection

        public boolean performOnSelection​(Member[] members)
        Applies this action to all of the specified project members. By overriding this, you can modify what happens when the user tries to initiate this action. For example, you could add a verification dialog and call the super implementation only if the user verifies the action.

        This implementation returns the result of calling this method on the original action.

        Overrides:
        performOnSelection in class TaskAction
        Returns:
        true if and only if the action is successfully applied to all of the members

      • perform

        public boolean perform​(Project project,
                       Task task,
                       Member member)
        Perform this action on a member of a project, a project or a task. If the project itself is the target, task and member will be null. If a task is the target, then member will be null. If an error occurs while executing the task, then it is the action's responsibility to inform the user. This method can return false to indicate that if the action is being applied to multiple members, it should stop immediately rather than continue to the next member.

        This implementation returns the result of calling this method on the original action.

        Specified by:
        perform in class TaskAction
        Parameters:
        project - the project that is being acted upon
        task - the task within the project that is being acted upon; null if acting on a project
        member - the specific member within the task to act upon; null if this is a project or task

      • appliesToSelection

        public boolean appliesToSelection​(Member[] members)
        Returns true if this action is applicable to any of the specified Members. By overriding this, you can modify whether an action is listed depending on which other members are selected. For example, you could create a command that can only be applied to a singleton selection by checking the length of members and returning false if it is not 1, and otherwise calling the super implementation.

        This implementation returns the result of calling this method on the original action.

        Overrides:
        appliesToSelection in class TaskAction
        Parameters:
        members - a list of zero or more members
        Returns:
        true is the action can be applied to at least one member

      • appliesTo

        public boolean appliesTo​(Project project,
                         Task task,
                         Member member)
        Returns true if this action can be performed on the specified member of a project, project or a task. If the project itself is the target, task and member will be null. If a task is the target, then member will be null. If an error occurs while executing the task, then it is the action's responsibility to inform the user. This method can return false to indicate that if the action is being applied to multiple members, it should stop immediately rather than continue to the next member.

        This implementation returns the result of calling this method on the original action.

        Specified by:
        appliesTo in class TaskAction
        Parameters:
        project - the project that is being acted upon
        task - the task within the project that is being acted upon; null if acting on a project
        member - the specific member within the task to act upon; null if this is a project or task

      • getSuperAction

        public final TaskAction getSuperAction()
        Returns the action that this action specializes.
        Returns:
        the parent action that this action specialized

      • getRootAction

        public final TaskAction getRootAction()
        Returns the topmost super action in the chain of specialized actions. This is similar to getSuperAction(), except that if an action has been specialized multiple times, this method will return the original, unspecialized action at the top of the specialization chain.
        Returns:
        the original, unspecialized action

      • uninstall

        public void uninstall()
        Removes this action from the specialization chain of the root action.