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 buildB
- the Type of action builderC
- The type of ActionContext. By default, the ActionContext type always starts as the base ActionContext class. If the client calls thewithContext(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)
andvalidContextWhen(Predicate)
. This works by substituting a builder with a different ActionContext type when chaining after thewithContext(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 theenabledWhen(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 theinWindow(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 invokedprotected java.lang.Class<? extends ActionContext>
actionContextClass
Specifies the type of ActionContext that the built action works on.protected KeyBindingType
keyBindingType
TheKeyBindingType
for thisDockingAction
protected java.lang.String
name
Name for theDockingAction
protected java.lang.String
owner
Owner for theDockingAction
-
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 toolT
buildAndInstallLocal(ComponentProvider provider)
Builds and adds the action as a local action for the given providerprotected void
decorateAction(DockingAction action)
B
description(java.lang.String text)
Configure the description for the action.B
enabled(boolean b)
Configure whether thisDockingAction
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)
ConfigureHelpLocation
for thisDockingAction
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 actionB
keyBinding(javax.swing.KeyStroke keyStroke)
Sets the key binding for this actionB
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 itemB
menuMnemonic(int mnemonic)
Sets the mnemonic to use in this action's menu bar itemB
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 itemB
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 chainingB
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 currentActionContext
.<AC2 extends ActionContext,B2 extends AbstractActionBuilder<T,AC2,B2>>
B2withContext(java.lang.Class<AC2> newActionContextClass)
Sets the specific ActionContext type to use for the various predicate calls (validContextWhen(Predicate)
,enabledWhen(Predicate)
, andpopupWhen(Predicate)
).
-
-
-
Field Detail
-
name
protected java.lang.String name
Name for theDockingAction
-
owner
protected java.lang.String owner
Owner for theDockingAction
-
actionContextClass
protected java.lang.Class<? extends ActionContext> actionContextClass
Specifies the type of ActionContext that the built action works on.
-
keyBindingType
protected KeyBindingType keyBindingType
TheKeyBindingType
for thisDockingAction
-
actionCallback
protected java.util.function.Consumer<C extends ActionContext> actionCallback
The callback to perform when the action is invoked
-
-
Method Detail
-
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, usebuildAndInstall(Tool)
orbuildAndInstallLocal(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(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 thisDockingAction
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. SeeKeyBindingType
.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)
ConfigureHelpLocation
for thisDockingAction
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
- theHelpLocation
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 togethersubGroup
- 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 togethersubGroup
- 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)
ortoolBarIcon(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)
ortoolBarIcon(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. SeeKeyStroke.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 anIllegalStateException
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. SeeDockingActionIf.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 callDockingAction.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. SeeDockingActionIf.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 currentActionContext
. SeeDockingActionIf.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 givenActionContext
- 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 theAbstractActionBuilder.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)
, andpopupWhen(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 methodwithContext(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()
-
-