Package docking.action.builder

Class AbstractActionBuilder<T extends DockingActionIf,​C extends ActionContext,​B extends AbstractActionBuilder<T,​C,​B>>

  • Type Parameters:
    T - The type of DockingAction to build
    B - the Type of action builder
    C - The type of ActionContext. By default, the ActionContext type always starts as the base ActionContext class. If the client calls the withContext(Class) method on the builder, then that class (which must be a subclass of ActionContext) becomes the ActionContext type that will be used for future calls to the builder methods that take predicates with ActionContext (i.e. enabledWhen(Predicate) and validContextWhen(Predicate). This works by substituting a builder with a different ActionContext type when chaining after the withContext(Class) call.
    Direct Known Subclasses:
    ActionBuilder, MultiActionBuilder, MultiStateActionBuilder, ToggleActionBuilder
    public abstract class AbstractActionBuilder<T extends DockingActionIf,​C extends ActionContext,​B extends AbstractActionBuilder<T,​C,​B>>
extends java.lang.Object
    Base class for DockingAction builders.

    Building an action requires a few steps. One of the few required calls when using a builder is onAction(Consumer). This is the callback used when the action is invoked. A typical action will also complete the enabledWhen(Predicate) method, which tells the tool when an action is valid.

    To see more detailed documentation for a given method of this builder, or to understand how actions are used in the tool, see the DockingActionIf interface.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  AbstractActionBuilder.When
      For use with the inWindow(When) method to specify which windows (main window or secondary windows) a global tool bar or menu action will appear in.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.util.function.Consumer<C> actionCallback
      The callback to perform when the action is invoked
      protected java.lang.Class<? extends ActionContext> actionContextClass
      Specifies the type of ActionContext that the built action works on.
      protected KeyBindingType keyBindingType
      The KeyBindingType for this DockingAction
      protected java.lang.String name
      Name for the DockingAction
      protected java.lang.String owner
      Owner for the DockingAction

    • Constructor Summary

      Constructors 
      Constructor Description
      AbstractActionBuilder​(java.lang.String name, java.lang.String owner)
      Builder constructor

    • Method Summary

      All Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      abstract T build()
      Builds the action.
      T buildAndInstall​(Tool tool)
      Builds and adds the action globally to the tool
      T buildAndInstallLocal​(ComponentProvider provider)
      Builds and adds the action as a local action for the given provider
      protected void decorateAction​(DockingAction action)  
      B description​(java.lang.String text)
      Configure the description for the action.
      B enabled​(boolean b)
      Configure whether this DockingAction is enabled.
      B enabledWhen​(java.util.function.Predicate<C> predicate)
      Sets a predicate for dynamically determining the action's enabled state.
      B helpLocation​(HelpLocation help)
      Configure HelpLocation for this DockingAction
      B inWindow​(AbstractActionBuilder.When when)
      Specifies when a global action should appear in a window (main or secondary).
      protected boolean isKeyBindingAction()  
      protected boolean isMenuAction()  
      protected boolean isPopupAction()  
      protected boolean isToolbarAction()  
      B keyBinding​(java.lang.String keyStrokeString)
      Sets the key binding for this action
      B keyBinding​(javax.swing.KeyStroke keyStroke)
      Sets the key binding for this action
      B menuGroup​(java.lang.String group)
      Sets the group for the action in the menu bar.
      B menuGroup​(java.lang.String group, java.lang.String subGroup)
      Sets the group and sub-group for the action in the menu bar.
      B menuIcon​(javax.swing.Icon icon)
      Sets the icon to use in this action's menu bar item
      B menuMnemonic​(int mnemonic)
      Sets the mnemonic to use in this action's menu bar item
      B menuPath​(java.lang.String... pathElement)
      Sets the menu bar path for the action.
      B onAction​(java.util.function.Consumer<C> action)
      Sets the primary callback to be executed when this action is invoked.
      B popupMenuGroup​(java.lang.String group)
      Sets the group for the action in the pop-up menu.
      B popupMenuGroup​(java.lang.String group, java.lang.String subGroup)
      Sets the group and sub-group for the action in the pop-up menu.
      B popupMenuIcon​(javax.swing.Icon icon)
      Sets the icon to use in this action's pop-up menu item
      B popupMenuPath​(java.lang.String... pathElement)
      Sets the pop-up menu path for the action.
      B popupWhen​(java.util.function.Predicate<C> predicate)
      Sets a predicate for dynamically determining if this action should be included in an impending pop-up menu.
      protected abstract B self()
      Returns this (typed for subclass) for chaining
      B sharedKeyBinding()
      Marks this action as one that shares a key binding with other actions in the tool.
      B supportsDefaultToolContext​(boolean b)
      Sets whether the action will support using the default tool context if the focused provider's context is invalid.
      B toolBarGroup​(java.lang.String group)
      Sets the group for the action in the tool bar.
      B toolBarGroup​(java.lang.String group, java.lang.String subGroup)
      Sets the group and sub-group for the action in the tool bar.
      B toolBarIcon​(java.lang.String iconFilepath)
      Sets the path for the icon to use in this action's tool bar button.
      B toolBarIcon​(javax.swing.Icon icon)
      Sets the icon to use in this action's tool bar button.
      protected void validate()  
      B validContextWhen​(java.util.function.Predicate<C> predicate)
      Sets a predicate for dynamically determining if this action is valid for the current ActionContext.
      <AC2 extends ActionContext,​B2 extends AbstractActionBuilder<T,​AC2,​B2>>
      B2      		 withContext​(java.lang.Class<AC2> newActionContextClass)
      Sets the specific ActionContext type to use for the various predicate calls (validContextWhen(Predicate), enabledWhen(Predicate), and popupWhen(Predicate)).

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • name

        protected java.lang.String name
        Name for the DockingAction

      • owner

        protected java.lang.String owner
        Owner for the DockingAction

      • actionContextClass

        protected java.lang.Class<? extends ActionContext> actionContextClass
        Specifies the type of ActionContext that the built action works on.

      • keyBindingType

        protected KeyBindingType keyBindingType
        The KeyBindingType for this DockingAction

      • actionCallback

        protected java.util.function.Consumer<C extends ActionContext> actionCallback
        The callback to perform when the action is invoked

    • Constructor Detail

      • AbstractActionBuilder

        public AbstractActionBuilder​(java.lang.String name,
                             java.lang.String owner)
        Builder constructor
        Parameters:
        name - the name of the action to be built
        owner - the owner of the action to be built

    • Method Detail

      • self

        protected abstract B self()
        Returns this (typed for subclass) for chaining
        Returns:
        this for chaining

      • buildAndInstallLocal

        public T buildAndInstallLocal​(ComponentProvider provider)
        Builds and adds the action as a local action for the given provider
        Parameters:
        provider - the provider to add the action to
        Returns:
        the newly created action
        See Also:
        build(), buildAndInstall(Tool)

      • description

        public B description​(java.lang.String text)
        Configure the description for the action. This description will appear as a tooltip over tool bar buttons.
        Parameters:
        text - the description
        Returns:
        this builder (for chaining)

      • enabled

        public B enabled​(boolean b)
        Configure whether this DockingAction is enabled.

        Note: most clients do not need to use this method. Enablement is controlled by validContextWhen(Predicate).

        Parameters:
        b - true if enabled
        Returns:
        this builder (for chaining)
        See Also:
        validContextWhen(Predicate)

      • sharedKeyBinding

        public B sharedKeyBinding()
        Marks this action as one that shares a key binding with other actions in the tool. This allows multiple clients to supply actions that use the same key binding, each working within its respective action context. See KeyBindingType.

        Actions are not shared by default; they are KeyBindingType.INDIVIDUAL. This means that each action must have its key binding assigned individually.

        Returns:
        this builder (for chaining)

      • helpLocation

        public B helpLocation​(HelpLocation help)
        Configure HelpLocation for this DockingAction

        Clients are free to specify their help location directly, but many do not. A default help location is created that uses the action name as the anchor name and the action owner as the topic. If your anchor or topic do not follow this convention, then you need to set help topic yourself.

        Parameters:
        help - the HelpLocation to configure
        Returns:
        this builder (for chaining)

      • menuPath

        public B menuPath​(java.lang.String... pathElement)
        Sets the menu bar path for the action. Setting this attribute is what causes the action to appear on the tools menu bar.
        Parameters:
        pathElement - the menu bar path for the action
        Returns:
        this builder (for chaining)

      • menuGroup

        public B menuGroup​(java.lang.String group)
        Sets the group for the action in the menu bar. Actions in the same group will appear next to other actions in the same group and actions in different groups will be separated by menu dividers.
        Parameters:
        group - for this action
        Returns:
        this builder (for chaining)

      • menuGroup

        public B menuGroup​(java.lang.String group,
                   java.lang.String subGroup)
        Sets the group and sub-group for the action in the menu bar. Actions in the same group will appear next to other actions in the same group and actions in different groups will be separated by menu dividers. The sub-group is used to order the actions within the group.
        Parameters:
        group - the group used to clump actions together
        subGroup - the sub-group used to order actions within a group
        Returns:
        this builder (for chaining)
        See Also:
        menuGroup(String)

      • menuIcon

        public B menuIcon​(javax.swing.Icon icon)
        Sets the icon to use in this action's menu bar item
        Parameters:
        icon - the icon to use in the action's menu bar item
        Returns:
        this builder (for chaining)

      • menuMnemonic

        public B menuMnemonic​(int mnemonic)
        Sets the mnemonic to use in this action's menu bar item
        Parameters:
        mnemonic - the mnemonic to use for this action's menu bar item.
        Returns:
        this builder (for chaining)

      • popupMenuPath

        public B popupMenuPath​(java.lang.String... pathElement)
        Sets the pop-up menu path for the action. Setting this attribute is what causes the action to appear on the tool's pop-up menu (assuming it is applicable for the context).
        Parameters:
        pathElement - the menu path for the action in the pop-up menu
        Returns:
        this builder (for chaining)
        See Also:
        popupMenuGroup(String)

      • popupMenuGroup

        public B popupMenuGroup​(java.lang.String group)
        Sets the group for the action in the pop-up menu. Actions in the same group will appear next to other actions in the same group and actions in different groups will be separated by menu dividers.
        Parameters:
        group - for this action
        Returns:
        this builder (for chaining)

      • popupMenuGroup

        public B popupMenuGroup​(java.lang.String group,
                        java.lang.String subGroup)
        Sets the group and sub-group for the action in the pop-up menu. Actions in the same group will appear next to other actions in the same group and actions in different groups will be separated by menu dividers. The sub-group is used to order the actions within the group
        Parameters:
        group - the group used to clump actions together
        subGroup - the sub-group used to order actions within a group
        Returns:
        this builder (for chaining)
        See Also:
        popupMenuGroup(String)

      • popupMenuIcon

        public B popupMenuIcon​(javax.swing.Icon icon)
        Sets the icon to use in this action's pop-up menu item
        Parameters:
        icon - the icon to use in the action's pop-up menu item
        Returns:
        this builder (for chaining)

      • toolBarIcon

        public B toolBarIcon​(javax.swing.Icon icon)
        Sets the icon to use in this action's tool bar button. Setting this attribute is what causes the action to appear on the tool's or component provider's action tool bar.
        Parameters:
        icon - the icon to use in the action's tool bar
        Returns:
        this builder (for chaining)
        See Also:
        toolBarIcon(String)

      • toolBarIcon

        public B toolBarIcon​(java.lang.String iconFilepath)
        Sets the path for the icon to use in this action's tool bar button. Setting this attribute causes the action to appear on the tool's or component provider's action tool bar.
        Parameters:
        iconFilepath - the module-relative path for the icon to use in the action's tool bar
        Returns:
        this builder (for chaining)
        See Also:
        toolBarIcon(Icon)

      • toolBarGroup

        public B toolBarGroup​(java.lang.String group)
        Sets the group for the action in the tool bar. Actions in the same group will appear next to other actions in the same group and actions in different groups will be separated by menu dividers.

        Note: you must call toolBarIcon(Icon) or toolBarIcon(String) for this action to appear in the toolbar. Calling this method without the other will not cause this action to be placed in the tool bar.

        Parameters:
        group - for this action
        Returns:
        this builder (for chaining)
        See Also:
        toolBarGroup(String, String)

      • toolBarGroup

        public B toolBarGroup​(java.lang.String group,
                      java.lang.String subGroup)
        Sets the group and sub-group for the action in the tool bar. Actions in the same group will appear next to other actions in the same group and actions in different groups will be separated by menu dividers. The sub-group is used to order the actions within the group.

        Note: you must call toolBarIcon(Icon) or toolBarIcon(String) for this action to appear in the toolbar. Calling this method without the other will not cause this action to be placed in the tool bar.

        Parameters:
        group - the group used to clump actions together.
        subGroup - the sub-group used to order actions within a group.
        Returns:
        this builder (for chaining)
        See Also:
        toolBarGroup(String)

      • keyBinding

        public B keyBinding​(javax.swing.KeyStroke keyStroke)
        Sets the key binding for this action
        Parameters:
        keyStroke - the KeyStroke to bind to this action
        Returns:
        this builder (for chaining)

      • keyBinding

        public B keyBinding​(java.lang.String keyStrokeString)
        Sets the key binding for this action
        Parameters:
        keyStrokeString - the string to parse as a KeyStroke. See KeyStroke.getKeyStroke(String) for the format of the string.
        Returns:
        this builder (for chaining)

      • onAction

        public B onAction​(java.util.function.Consumer<C> action)
        Sets the primary callback to be executed when this action is invoked. This builder will throw an IllegalStateException if one of the build methods is called without providing this callback.
        Parameters:
        action - the callback to execute when the action is invoked
        Returns:
        this builder (for chaining)

      • enabledWhen

        public B enabledWhen​(java.util.function.Predicate<C> predicate)
        Sets a predicate for dynamically determining the action's enabled state. See DockingActionIf.isEnabledForContext(ActionContext)

        If this predicate is not set, the action's enable state must be controlled directly using the DockingAction.setEnabled(boolean) method. We do not recommend controlling enablement directly. And, of course, if you do set this predicate, you should not later call DockingAction.setEnabled(boolean) to manually manage enablement.

        Parameters:
        predicate - the predicate that will be used to dynamically determine an action's enabled state
        Returns:
        this builder (for chaining)

      • popupWhen

        public B popupWhen​(java.util.function.Predicate<C> predicate)
        Sets a predicate for dynamically determining if this action should be included in an impending pop-up menu. If this predicate is not set, the action will be included in an impending pop-up, if it is enabled. See DockingActionIf.isAddToPopup(ActionContext).

        Note: use this method when you wish for an action to be added to a popup menu regardless of whether it is enabled. As mentioned above, standard popup actions will only be added to the popup when they are enabled.

        Note: using this method is not sufficient to cause the action to appear in a popup menu. You must also use popupMenuPath(String...).

        Parameters:
        predicate - the predicate that will be used to dynamically determine whether an action is added to a popup menu
        Returns:
        this builder (for chaining)
        See Also:
        popupMenuPath(String...)

      • validContextWhen

        public B validContextWhen​(java.util.function.Predicate<C> predicate)
        Sets a predicate for dynamically determining if this action is valid for the current ActionContext. See DockingActionIf.isValidContext(ActionContext).

        Note: most actions will not use this method, but rely instead on enabledWhen(Predicate).

        Note: this triggers automatic action enablement so you should not later call DockingAction.setEnabled(boolean) to manually manage action enablement.

        Parameters:
        predicate - the predicate that will be used to dynamically determine an action's validity for a given ActionContext
        Returns:
        this builder (for chaining)

      • supportsDefaultToolContext

        public B supportsDefaultToolContext​(boolean b)
        Sets whether the action will support using the default tool context if the focused provider's context is invalid.

        By default, actions only work on the current focused provider's context. Setting this to true will cause the action to be evaluated against the default tool context if the focused context is not valid for this action.

        Parameters:
        b - the new value
        Returns:
        this builder (for chaining)

      • inWindow

        public B inWindow​(AbstractActionBuilder.When when)
        Specifies when a global action should appear in a window (main or secondary).

        Global menu or toolbar actions can be configured to appear in 1) only the main window, or 2) all windows, or 3) any window that has a provider that generates an action context that matches the context that this action consumes. If the "context matches" options is chosen, then the withContext(Class) method must also be called to specify the matching context; otherwise an exception will be thrown when the action is built.

        The default is that the action will only appear in the main window.

        Parameters:
        when - use the AbstractActionBuilder.When enum to specify the windowing behavior of the action.
        Returns:
        this builder (for chaining)

      • withContext

        public <AC2 extends ActionContext,​B2 extends AbstractActionBuilder<T,​AC2,​B2>> B2 withContext​(java.lang.Class<AC2> newActionContextClass)
        Sets the specific ActionContext type to use for the various predicate calls (validContextWhen(Predicate), enabledWhen(Predicate), and popupWhen(Predicate)).

        In other words, this allows the client to specify the type of ActionContext that is valid for the action being built.

        To be effective, this method must be called before setting any of the predicates such as the enabledWhen(Predicate). Once this method is called you can define your predicates using the more specific ActionContext and be assured your predicates will only be called when the current action context is the type (or sub-type) of the context you have specified here.

        For example, assume you have an action that is only enabled when the context is of type FooActionContext. If you don't call this method to set the ActionContext type, you would have to write your predicate something like this: 

         builder.enabledWhen(context -> {
     if (!(context instanceof FooContext)) {
         return false;
     }
     return ((FooContext) context).isAwesome();
 });
        But by first calling the builder method withContext(FooContext.class), you can simply write: 
         builder.enabledWhen(context -> return context.isAwesome() }

        Note: this triggers automatic action enablement so you should not later call DockingAction.setEnabled(boolean) to manually manage action enablement.

        Type Parameters:
        AC2 - The new ActionContext type (as determined by the newActionContextClass) that the returned builder will have.
        B2 - the new builder type.
        Parameters:
        newActionContextClass - the more specific ActionContext type.
        Returns:
        an ActionBuilder whose generic types have been modified to match the new ActionContext. It still contains all the configuration that has been applied so far.

      • validate

        protected void validate()

      • decorateAction

        protected void decorateAction​(DockingAction action)

      • isPopupAction

        protected boolean isPopupAction()

      • isToolbarAction

        protected boolean isToolbarAction()

      • isMenuAction

        protected boolean isMenuAction()

      • isKeyBindingAction

        protected boolean isKeyBindingAction()