Package docking.action.builder

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

java.lang.Object
docking.action.builder.AbstractActionBuilder<T,C,B>
Type Parameters:
T - The type of DockingAction to build
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.
B - the Type of action builder
Direct Known Subclasses:
ActionBuilder, MultiActionBuilder, MultiStateActionBuilder, ToggleActionBuilder
public abstract class AbstractActionBuilder<T extends DockingActionIf,C extends ActionContext,B extends AbstractActionBuilder<T,C,B>> extends 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.

  • Field Details

    • name

      protected String name
      Name for the DockingAction

    • owner

      protected String owner
      Owner for the DockingAction

    • actionContextClass

      protected 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 Consumer<C extends ActionContext> actionCallback
      The callback to perform when the action is invoked

  • Constructor Details

    • AbstractActionBuilder

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

  • Method Details

    • self

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

    • build

      public abstract T build()
      Builds the action. To build and install the action in one step, use buildAndInstall(Tool) or buildAndInstallLocal(ComponentProvider). inWindow(When)
      Returns:
      the newly build action

    • buildAndInstall

      public T buildAndInstall(Tool tool)
      Builds and adds the action globally to the tool
      Parameters:
      tool - the tool to add the action to
      Returns:
      the newly created action
      See Also:

    • 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:

    • description

      public B description(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:

    • 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)

    • popupMenuPath

      public B popupMenuPath(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

      public B popupMenuGroup(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(String group, 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:

    • popupMenuIcon

      public B popupMenuIcon(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(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

      public B toolBarIcon(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:

    • toolBarGroup

      public B toolBarGroup(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

      public B toolBarGroup(String group, 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:

    • keyBinding

      public B keyBinding(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(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(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(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(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:

    • validContextWhen

      public B validContextWhen(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)

    • 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(Class<AC2> newActionContextClass)
      Sets the action context for this action. If this context is set, then this action is only valid when the current context is that type or extends that type.

      After this method has been called, any the following methods will use this new context type in the method signature: (validContextWhen(Predicate), enabledWhen(Predicate), and popupWhen(Predicate)).

      For example, assume you have an action that is only enabled when the context is of type FooContext. If you don't call this method to set the action context 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), then the context will be the new type and you can simply write: 
       builder.enabledWhen(context -> context.isAwesome())

      Note: this triggers automatic action enablement based on context for the action, so you should not later manually manage action enablement using the action's DockingAction.setEnabled(boolean) method.

      For more details on how the action context system works, see ActionContext.

      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.

    • withContext

      public <AC2 extends ActionContext, B2 extends AbstractActionBuilder<T, AC2, B2>> B2 withContext(Class<AC2> newActionContextClass, boolean useDefaultContext)
      Sets the action context for this action and whether or not this action supports default context as explained in ActionContext. If this context is set, then this action is only valid when the current context is that type or extends that type.

      After this method has been called, any the following methods will use this new context type in the method signature: (validContextWhen(Predicate), enabledWhen(Predicate), and popupWhen(Predicate)).

      For example, assume you have an action that is only enabled when the context is of type FooContext. If you don't call this method to set the action context 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), then the context will be the new type and you can simply write: 
       builder.enabledWhen(context -> context.isAwesome())

      Note: this triggers automatic action enablement based on context for the action, so you should not later manually manage action enablement using the action's DockingAction.setEnabled(boolean) method.

      For more details on how the action context system works, see ActionContext.

      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.
      useDefaultContext - if true, then this action also supports operating on a default context other than the active (focused) provider's context
      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()