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.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `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 Consumer<C>`
  `actionCallback`
  The callback to perform when the action is invoked
  `protected Class<? extends ActionContext>`
  `actionContextClass`
  Specifies the type of ActionContext that the built action works on.
  `protected KeyBindingType`
  `keyBindingType`
  The `KeyBindingType` for this `DockingAction`
  `protected String`
  `name`
  Name for the `DockingAction`
  `protected String`
  `owner`
  Owner for the `DockingAction`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AbstractActionBuilder(String name, String owner)`
  Builder constructor

- ## Method Summary

  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(String text)`
  Configure the description for the action.
  `B`
  `enabled(boolean b)`
  Configure whether this `DockingAction` is enabled.
  `B`
  `enabledWhen(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(String keyStrokeString)`
  Sets the key binding for this action
  `B`
  `keyBinding(KeyStroke keyStroke)`
  Sets the key binding for this action
  `B`
  `menuGroup(String group)`
  Sets the group for the action in the menu bar.
  `B`
  `menuGroup(String group, String subGroup)`
  Sets the group and sub-group for the action in the menu bar.
  `B`
  `menuIcon(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(String... pathElement)`
  Sets the menu bar path for the action.
  `B`
  `onAction(Consumer<C> action)`
  Sets the primary callback to be executed when this action is invoked.
  `B`
  `popupMenuGroup(String group)`
  Sets the group for the action in the pop-up menu.
  `B`
  `popupMenuGroup(String group, String subGroup)`
  Sets the group and sub-group for the action in the pop-up menu.
  `B`
  `popupMenuIcon(Icon icon)`
  Sets the icon to use in this action's pop-up menu item
  `B`
  `popupMenuPath(String... pathElement)`
  Sets the pop-up menu path for the action.
  `B`
  `popupWhen(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`
  `toolBarGroup(String group)`
  Sets the group for the action in the tool bar.
  `B`
  `toolBarGroup(String group, String subGroup)`
  Sets the group and sub-group for the action in the tool bar.
  `B`
  `toolBarIcon(String iconFilepath)`
  Sets the path for the icon to use in this action's tool bar button.
  `B`
  `toolBarIcon(Icon icon)`
  Sets the icon to use in this action's tool bar button.
  `protected void`
  `validate()`
  `B`
  `validContextWhen(Predicate<C> predicate)`
  Deprecated, for removal: This API element is subject to removal in a future version.
  use `validWhen(Predicate)`
  `B`
  `validWhen(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(Class<AC2> newActionContextClass)`
  Sets the action context for this action.
  `<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`.

  ### Methods inherited from class java.lang.Object

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

- ## 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:
      - `build()`
      - `buildAndInstallLocal(ComponentProvider)`

  - ### 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(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(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(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(String group, 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(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(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(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:
      - `popupMenuGroup(String)`

  - ### 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(String)`

  - ### 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:
      - `toolBarIcon(Icon)`

  - ### 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(String, String)`

  - ### 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:
      - `toolBarGroup(String)`

  - ### 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:
      - `popupMenuPath(String...)`

  - ### validContextWhen

    @Deprecated(forRemoval=true, since="11.4") public B validContextWhen(Predicate<C> predicate)
    Deprecated, for removal: This API element is subject to removal in a future version.
    use `validWhen(Predicate)`
    Parameters:
      `predicate` - the predicate
    Returns:
      this builder (for chaining)

  - ### validWhen

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