mirror of
https://github.com/NationalSecurityAgency/ghidra.git
synced 2025-10-05 10:49:34 +02:00
GT-1 - Documentation - fixup docs for new action builder
This commit is contained in:
dragonmacher
parent
87839a58eb
commit
341f1008f1
3 changed files with 142 additions and 55 deletions
|
|
@ -14,6 +14,7 @@
|
|||
* limitations under the License.
|
||||
*/
|
||||
package docking.action.builder;
|
||||
|
||||
import java.util.function.Consumer;
|
||||
import java.util.function.Predicate;
|
||||
|
||||
|
|
@ -25,85 +26,112 @@ import ghidra.util.HelpLocation;
|
|||
import resources.ResourceManager;
|
||||
|
||||
/**
|
||||
* Base class for DockingAction builders
|
||||
* Base class for DockingAction builders.
|
||||
*
|
||||
* <p>Building an action requires a few steps. One of the few required calls when using a builder
|
||||
* is {@link #onAction(Consumer)}. This is the callback used when the action is invoked. A
|
||||
* typical action will also complete the {@link #enabledWhen(Predicate)} method, which tells the
|
||||
* tool when an action is valid.
|
||||
*
|
||||
* <p>To see more detailed documentation for a given method of this builder, or to understand
|
||||
* how actions are used in the tool, see the {@link DockingActionIf}
|
||||
* interface.
|
||||
*
|
||||
* @param <T> The type of DockingAction to build
|
||||
* @param <B> the Type of DockingActionBuilder
|
||||
* @param <B> the Type of action builder
|
||||
*/
|
||||
public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends AbstractActionBuilder<T, B>> {
|
||||
|
||||
/**
|
||||
* a name for the {@code DockingAction}
|
||||
* Name for the {@code DockingAction}
|
||||
*/
|
||||
protected String name;
|
||||
|
||||
/**
|
||||
* an owner for the {@code DockingAction}
|
||||
* Owner for the {@code DockingAction}
|
||||
*/
|
||||
protected String owner;
|
||||
|
||||
/**
|
||||
* the {@code KeyBindingType} for this {@code DockingAction}
|
||||
* The {@code KeyBindingType} for this {@code DockingAction}
|
||||
*/
|
||||
protected KeyBindingType keyBindingType = KeyBindingType.INDIVIDUAL;
|
||||
|
||||
/**
|
||||
* The callback to perform when the action is invoked
|
||||
*/
|
||||
protected Consumer<ActionContext> actionCallback;
|
||||
|
||||
/**
|
||||
* a description for the {@code DockingAction}
|
||||
* Description for the {@code DockingAction}. (optional)
|
||||
*/
|
||||
private String description = "";
|
||||
|
||||
/**
|
||||
* whether this {@code DockingAction} is enabled
|
||||
* Whether this {@code DockingAction} is enabled
|
||||
*/
|
||||
private boolean isEnabled = true;
|
||||
|
||||
/**
|
||||
* the {@code HelpLocation} for this {@code DockingAction}
|
||||
* The {@code HelpLocation} for this {@code DockingAction}
|
||||
*/
|
||||
private HelpLocation helpLocation;
|
||||
|
||||
/**
|
||||
* The menu bar path. This is the key attribute for including the action on the menu bar
|
||||
* The menu bar path. This is the key attribute for including the action on the menu bar.
|
||||
*/
|
||||
private String[] menuPath;
|
||||
|
||||
/**
|
||||
* The menu bar menu item icon. (optional)
|
||||
*/
|
||||
private Icon menuIcon;
|
||||
|
||||
/**
|
||||
* The menu bar menu item sub group. (optional)
|
||||
*/
|
||||
private String menuSubGroup;
|
||||
|
||||
/**
|
||||
* The menu bar menu item group. (optional)
|
||||
*/
|
||||
private String menuGroup;
|
||||
|
||||
/**
|
||||
* The mnemonic for the menu action (optional)
|
||||
*/
|
||||
private int menuMnemonic;
|
||||
|
||||
/**
|
||||
* The icon for the menu item (optional)
|
||||
*/
|
||||
private Icon popupIcon;
|
||||
|
||||
/**
|
||||
* The menu path in a pop-up menu. This is the key attribute for pop-up menu actions
|
||||
*/
|
||||
private String[] popupPath;
|
||||
|
||||
/**
|
||||
* The menu group for the item in the pop-up menu (optional)
|
||||
*/
|
||||
private String popupGroup;
|
||||
|
||||
/**
|
||||
* The menu sub group for the item in the pop-up menu (optional)
|
||||
*/
|
||||
private String popupSubGroup;
|
||||
|
||||
/**
|
||||
* The icon for the tool bar action. This is the key attribute for actions in the toolbar.
|
||||
*/
|
||||
private Icon toolbarIcon;
|
||||
|
||||
/**
|
||||
* The group for the items on the tool bar (optional)
|
||||
*/
|
||||
private String toolBarGroup;
|
||||
|
||||
/**
|
||||
* The menu group for the item in the tool bar menu (optional)
|
||||
*/
|
||||
|
|
@ -113,24 +141,26 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
* Predicate for determining if an action is enabled for a given context
|
||||
*/
|
||||
private Predicate<ActionContext> enabledPredicate;
|
||||
|
||||
/**
|
||||
* Predicate for determining if an action should be included on the pop-up menu
|
||||
*/
|
||||
private Predicate<ActionContext> popupPredicate;
|
||||
|
||||
/**
|
||||
* Predicate for determining if an action is applicable for a given context
|
||||
*/
|
||||
private Predicate<ActionContext> validContextPredicate;
|
||||
|
||||
/**
|
||||
* Predicate for determining if an action is applicable for a given global context
|
||||
*/
|
||||
private Predicate<ActionContext> validGlobalContextPredicate;
|
||||
|
||||
|
||||
/**
|
||||
* Builder constructor
|
||||
* @param name the name of the action to be built
|
||||
* @param owner the owner of the action to be build
|
||||
* @param owner the owner of the action to be built
|
||||
*/
|
||||
public AbstractActionBuilder(String name, String owner) {
|
||||
this.name = name;
|
||||
|
|
@ -138,13 +168,15 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
}
|
||||
|
||||
/**
|
||||
* returns this (typed for subclass) for chaining
|
||||
* Returns this (typed for subclass) for chaining
|
||||
* @return this for chaining
|
||||
*/
|
||||
protected abstract B self();
|
||||
|
||||
/**
|
||||
* builds the action
|
||||
* Builds the action. To build and install the action in one step, use
|
||||
* {@link #buildAndInstall(DockingTool)} or {@link #buildAndInstallLocal(ComponentProvider)}.
|
||||
*
|
||||
* @return the newly build action
|
||||
*/
|
||||
public abstract T build();
|
||||
|
|
@ -154,6 +186,8 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
*
|
||||
* @param tool the tool to add the action to
|
||||
* @return the newly created action
|
||||
* @see #build()
|
||||
* @see #buildAndInstallLocal(ComponentProvider)
|
||||
*/
|
||||
public T buildAndInstall(DockingTool tool) {
|
||||
T action = build();
|
||||
|
|
@ -166,6 +200,8 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
*
|
||||
* @param provider the provider to add the action to
|
||||
* @return the newly created action
|
||||
* @see #build()
|
||||
* @see #buildAndInstall(DockingTool)
|
||||
*/
|
||||
public T buildAndInstallLocal(ComponentProvider provider) {
|
||||
T action = build();
|
||||
|
|
@ -174,7 +210,8 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
}
|
||||
|
||||
/**
|
||||
* Configure the {@code String} description for this {@code DockingAction}
|
||||
* Configure the description for the action. This description will appear as a tooltip
|
||||
* over tool bar buttons.
|
||||
*
|
||||
* @param text the description
|
||||
* @return this builder (for chaining)
|
||||
|
|
@ -185,10 +222,15 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
}
|
||||
|
||||
/**
|
||||
* Configure whether this {@code DockingAction} is enabled
|
||||
* Configure whether this {@code DockingAction} is enabled.
|
||||
*
|
||||
* <p><b>Note: most clients do not need to use this method. Enablement is controlled by
|
||||
* {@link #validContextWhen(Predicate)} or {@link #validGlobalContextWhen(Predicate)}.
|
||||
* </b>
|
||||
*
|
||||
* @param b {@code true} if enabled
|
||||
* @return this builder (for chaining)
|
||||
* @see #validContextWhen(Predicate)
|
||||
*/
|
||||
public B enabled(boolean b) {
|
||||
this.isEnabled = b;
|
||||
|
|
@ -196,17 +238,28 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
}
|
||||
|
||||
/**
|
||||
* Configure {@link KeyBindingType} for this {@code DockingAction}
|
||||
* @param type the {@link KeyBindingType} to configure
|
||||
* 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 {@link KeyBindingType}.
|
||||
*
|
||||
* <p>Actions are not shared by default; they are {@link KeyBindingType#INDIVIDUAL}. This
|
||||
* means that each action must have its key binding assigned individually.
|
||||
*
|
||||
* @return this builder (for chaining)
|
||||
*/
|
||||
public B keyBindingType(KeyBindingType type) {
|
||||
this.keyBindingType = type;
|
||||
public B sharedKeyBinding() {
|
||||
this.keyBindingType = KeyBindingType.SHARED;
|
||||
return self();
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Configure {@link HelpLocation} for this {@code DockingAction}
|
||||
*
|
||||
* <p>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.
|
||||
*
|
||||
* @param help the {@link HelpLocation} to configure
|
||||
* @return this builder (for chaining)
|
||||
*/
|
||||
|
|
@ -217,7 +270,8 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
|
||||
/**
|
||||
* Sets the menu bar path for the action. Setting this attribute is what causes the action
|
||||
* to appear on the tools menu bar
|
||||
* to appear on the tools menu bar.
|
||||
*
|
||||
* @param pathElement the menu bar path for the action
|
||||
* @return this builder (for chaining)
|
||||
*/
|
||||
|
|
@ -229,7 +283,7 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
/**
|
||||
* 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
|
||||
* by menu dividers.
|
||||
*
|
||||
* @param group for this action
|
||||
* @return this builder (for chaining)
|
||||
|
|
@ -240,13 +294,14 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
}
|
||||
|
||||
/**
|
||||
* 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 withing the group.
|
||||
* 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.
|
||||
*
|
||||
* @param group the group used to clump actions together.
|
||||
* @param subGroup the sub-group used to order actions within a group.
|
||||
* @param group the group used to clump actions together
|
||||
* @param subGroup the sub-group used to order actions within a group
|
||||
* @return this builder (for chaining)
|
||||
* @see #menuGroup(String)
|
||||
*/
|
||||
public B menuGroup(String group, String subGroup) {
|
||||
menuSubGroup = group;
|
||||
|
|
@ -254,9 +309,9 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
}
|
||||
|
||||
/**
|
||||
* Sets the icon to use in this action's menu bar item.
|
||||
* Sets the icon to use in this action's menu bar item
|
||||
*
|
||||
* @param icon the icon to use in the action's menu bar item.
|
||||
* @param icon the icon to use in the action's menu bar item
|
||||
* @return this builder (for chaining)
|
||||
*/
|
||||
public B menuIcon(Icon icon) {
|
||||
|
|
@ -265,7 +320,7 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
}
|
||||
|
||||
/**
|
||||
* Sets the mnemonic to use in this action's menu bar item.
|
||||
* Sets the mnemonic to use in this action's menu bar item
|
||||
*
|
||||
* @param mnemonic the mnemonic to use for this action's menu bar item.
|
||||
* @return this builder (for chaining)
|
||||
|
|
@ -277,10 +332,11 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
|
||||
/**
|
||||
* Sets the pop-up menu path for the action. Setting this attribute is what causes the action
|
||||
* to appear on the tools pop-up menu (Assuming it is applicable for the context)
|
||||
* to appear on the tool's pop-up menu (assuming it is applicable for the context).
|
||||
*
|
||||
* @param pathElement the menu path for the action in the pop-up menu
|
||||
* @return this builder (for chaining)
|
||||
* @see #popupMenuGroup(String)
|
||||
*/
|
||||
public B popupMenuPath(String... pathElement) {
|
||||
popupPath = pathElement;
|
||||
|
|
@ -290,7 +346,7 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
/**
|
||||
* 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
|
||||
* by menu dividers.
|
||||
*
|
||||
* @param group for this action
|
||||
* @return this builder (for chaining)
|
||||
|
|
@ -305,9 +361,10 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
* 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
|
||||
*
|
||||
* @param group the group used to clump actions together.
|
||||
* @param subGroup the sub-group used to order actions within a group.
|
||||
* @param group the group used to clump actions together
|
||||
* @param subGroup the sub-group used to order actions within a group
|
||||
* @return this builder (for chaining)
|
||||
* @see #popupMenuGroup(String)
|
||||
*/
|
||||
public B popupMenuGroup(String group, String subGroup) {
|
||||
popupSubGroup = group;
|
||||
|
|
@ -315,9 +372,9 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
}
|
||||
|
||||
/**
|
||||
* Sets the icon to use in this action's pop-up menu item.
|
||||
* Sets the icon to use in this action's pop-up menu item
|
||||
*
|
||||
* @param icon the icon to use in the action's pop-up menu item.
|
||||
* @param icon the icon to use in the action's pop-up menu item
|
||||
* @return this builder (for chaining)
|
||||
*/
|
||||
public B popupMenuIcon(Icon icon) {
|
||||
|
|
@ -327,10 +384,11 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
|
||||
/**
|
||||
* Sets the icon to use in this action's tool bar button. Setting this attribute is what
|
||||
* causes the action to appear on the tools or component provider's action tool bar.
|
||||
* causes the action to appear on the tool's or component provider's action tool bar.
|
||||
*
|
||||
* @param icon the icon to use in the action's tool bar.
|
||||
* @param icon the icon to use in the action's tool bar
|
||||
* @return this builder (for chaining)
|
||||
* @see #toolBarIcon(String)
|
||||
*/
|
||||
public B toolBarIcon(Icon icon) {
|
||||
toolbarIcon = icon;
|
||||
|
|
@ -339,10 +397,11 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
|
||||
/**
|
||||
* 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 tools or component provider's action tool bar.
|
||||
* causes the action to appear on the tool's or component provider's action tool bar.
|
||||
*
|
||||
* @param iconFilepath the module relative path for the icon to use in the action's tool bar.
|
||||
* @param iconFilepath the module-relative path for the icon to use in the action's tool bar
|
||||
* @return this builder (for chaining)
|
||||
* @see #toolBarIcon(Icon)
|
||||
*/
|
||||
public B toolBarIcon(String iconFilepath) {
|
||||
toolbarIcon = ResourceManager.loadImage(iconFilepath);
|
||||
|
|
@ -352,10 +411,16 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
/**
|
||||
* 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
|
||||
* by menu dividers.
|
||||
*
|
||||
* <p><b>Note: you must call {@link #toolBarIcon(Icon)} or {@link #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.
|
||||
* </b>
|
||||
*
|
||||
* @param group for this action
|
||||
* @return this builder (for chaining)
|
||||
* @see #toolBarGroup(String)
|
||||
*/
|
||||
public B toolBarGroup(String group) {
|
||||
toolBarGroup = group;
|
||||
|
|
@ -365,11 +430,17 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
/**
|
||||
* 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
|
||||
* be separated by menu dividers. The sub-group is used to order the actions within the group.
|
||||
*
|
||||
* <p><b>Note: you must call {@link #toolBarIcon(Icon)} or {@link #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.
|
||||
* </b>
|
||||
*
|
||||
* @param group the group used to clump actions together.
|
||||
* @param subGroup the sub-group used to order actions within a group.
|
||||
* @return this builder (for chaining)
|
||||
* @see #toolBarGroup(String)
|
||||
*/
|
||||
public B toolBarGroup(String group, String subGroup) {
|
||||
toolBarSubGroup = group;
|
||||
|
|
@ -379,7 +450,7 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
/**
|
||||
* Sets the primary callback to be executed when this action is invoked. This builder will
|
||||
* throw an {@link IllegalStateException} if one of the build methods is called without
|
||||
* providing this callback
|
||||
* providing this callback.
|
||||
*
|
||||
* @param action the callback to execute when the action is invoked
|
||||
* @return this builder (for chaining)
|
||||
|
|
@ -390,13 +461,15 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
}
|
||||
|
||||
/**
|
||||
* Sets a predicate for dynamically determining the action's enabled state. If this
|
||||
* predicate is not set, the action's enable state must be controlled directly using the
|
||||
* {@link DockingAction#setEnabled(boolean)} method. See
|
||||
* Sets a predicate for dynamically determining the action's enabled state. See
|
||||
* {@link DockingActionIf#isEnabledForContext(ActionContext)}
|
||||
*
|
||||
* <p>If this predicate is not set, the action's enable state must be controlled
|
||||
* directly using the {@link DockingAction#setEnabled(boolean)} method. We do not recommend
|
||||
* controlling enablement directly.
|
||||
*
|
||||
* @param predicate the predicate that will be used to dynamically determine an action's
|
||||
* enabled state.
|
||||
* enabled state
|
||||
* @return this builder (for chaining)
|
||||
*/
|
||||
public B enabledWhen(Predicate<ActionContext> predicate) {
|
||||
|
|
@ -406,13 +479,21 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
|
||||
/**
|
||||
* 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's will be included
|
||||
* 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
|
||||
* {@link DockingActionIf#isAddToPopup(ActionContext)}
|
||||
* {@link DockingActionIf#isAddToPopup(ActionContext)}.
|
||||
*
|
||||
* <p>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.
|
||||
*
|
||||
* @param predicate the predicate that will be used to dynamically determine an action's
|
||||
* enabled state.
|
||||
* <p>Note: using this method is not sufficient to cause the action to appear in a popup
|
||||
* menu. You must also use {@link #popupMenuPath(String...)}.
|
||||
*
|
||||
* @param predicate the predicate that will be used to dynamically determine whether an
|
||||
* action is added to a popup menu
|
||||
* @return this builder (for chaining)
|
||||
* @see #popupMenuPath(String...)
|
||||
*/
|
||||
public B popupWhen(Predicate<ActionContext> predicate) {
|
||||
popupPredicate = predicate;
|
||||
|
|
@ -421,7 +502,10 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
|
||||
/**
|
||||
* Sets a predicate for dynamically determining if this action is valid for the current
|
||||
* {@link ActionContext}. See {@link DockingActionIf#isValidContext(ActionContext)}
|
||||
* {@link ActionContext}. See {@link DockingActionIf#isValidContext(ActionContext)}.
|
||||
*
|
||||
* <p>Note: most actions will not use this method, but rely instead on
|
||||
* {@link #enabledWhen(Predicate)}.
|
||||
*
|
||||
* @param predicate the predicate that will be used to dynamically determine an action's
|
||||
* validity for a given {@link ActionContext}
|
||||
|
|
@ -434,7 +518,10 @@ public abstract class AbstractActionBuilder<T extends DockingActionIf, B extends
|
|||
|
||||
/**
|
||||
* Sets a predicate for dynamically determining if this action is valid for the current global
|
||||
* {@link ActionContext}. See {@link DockingActionIf#isValidGlobalContext(ActionContext)}
|
||||
* {@link ActionContext}. See {@link DockingActionIf#isValidGlobalContext(ActionContext)}.
|
||||
*
|
||||
* <p>Note: most actions will not use this method, but rely instead on
|
||||
* {@link #enabledWhen(Predicate)}.
|
||||
*
|
||||
* @param predicate the predicate that will be used to dynamically determine an action's
|
||||
* validity for a given global {@link ActionContext}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue