Package docking.action

# Interface DockingActionIf

All Superinterfaces:
  `HelpDescriptor`

All Known Subinterfaces:
  `ComponentBasedDockingAction`, `ToggleDockingActionIf`

All Known Implementing Classes:
  `AbstractFindReferencesDataTypeAction`, `AbstractFindReferencesToAddressAction`, `AbstractHelpAction`, `AbstractSelectionNavigationAction`, `AddAllFieldAction`, `AddFieldAction`, `AddSpacerFieldAction`, `ClearCutAction`, `ComponentThemeInspectorAction`, `ContextSpecificAction`, `DeleteTableRowAction`, `DialogProjectDataCollapseAction`, `DialogProjectDataExpandAction`, `DialogProjectDataNewFolderAction`, `DisableFieldAction`, `DockingAction`, `DockingActionProxy`, `DomainFileProviderContextAction`, `EnableFieldAction`, `FindCheckoutsAction`, `FrontEndProjectDataCollapseAction`, `FrontEndProjectDataExpandAction`, `FrontEndProjectDataNewFolderAction`, `FrontendProjectTreeAction`, `GlobalFocusTraversalAction`, `HelpAction`, `HelpInfoAction`, `HorizontalRuleAction`, `InsertRowAction`, `ListingContextAction`, `MakeProgramSelectionAction`, `MultiActionDockingAction`, `MultiStateDockingAction`, `NavigatableContextAction`, `NextPreviousWindowAction`, `NextRangeAction`, `NonToolbarMultiStateAction`, `PreviousRangeAction`, `ProgramContextAction`, `ProgramLocationContextAction`, `ProgramSymbolContextAction`, `ProjectDataCollapseAction`, `ProjectDataContextToggleAction`, `ProjectDataCopyAction`, `ProjectDataCopyCutBaseAction`, `ProjectDataCutAction`, `ProjectDataDeleteAction`, `ProjectDataExpandAction`, `ProjectDataFollowLinkAction`, `ProjectDataNewFolderAction`, `ProjectDataOpenDefaultToolAction`, `ProjectDataOpenToolAction`, `ProjectDataPasteAction`, `ProjectDataPasteLinkAction`, `ProjectDataReadOnlyAction`, `ProjectDataRefreshAction`, `ProjectDataRenameAction`, `ProjectDataSelectAction`, `ProjectDataSelectRealFileOrFolderAction`, `ProjectRepoConnectAction`, `ProjectTreeAction`, `RemoveAllFieldsAction`, `RemoveFieldAction`, `RemoveRowAction`, `ResetAllFormatsAction`, `ResetFormatAction`, `ResetTranslationAction`, `SaveImageAction`, `SelectionNavigationAction`, `SetKeyBindingAction`, `SetSpacerTextAction`, `SharedStubKeyBindingAction`, `ShowActionChooserDialogAction`, `ShowAllComponentsAction`, `ShowContextMenuAction`, `ShowFocusCycleAction`, `ShowFocusInfoAction`, `ToggleDockingAction`, `VersionControlAction`, `VersionControlAddAction`, `VersionControlCheckInAction`, `VersionControlCheckOutAction`, `VersionControlDataTypeArchiveUndoCheckoutAction`, `VersionControlShowHistoryAction`, `VersionControlUndoCheckOutAction`, `VersionControlUndoHijackAction`, `VersionControlUpdateAction`, `VersionControlViewCheckOutAction`, `ViewInstructionDetailsAction`, `ZoomInAction`, `ZoomOutAction`, `ZoomResetAction`

public interface DockingActionIf extends HelpDescriptor
The base interface for clients that wish to create commands to be registered with a tool.

An action may appear in a primary menu, a popup menu or a toolbar. Further, an action may have a key binding assigned.

The particular support for key bindings is defined by `KeyBindingType`. Almost all client actions will use the default setting of `KeyBindingType.INDIVIDUAL`. To control the level of key binding support, you can pass the desired `KeyBindingType` to the base implementation of this interface.

`ActionContext` is a key concept for tool actions so that they can be context sensitive if appropriate. The context provides a consistent way for plugins and components to share tool state with actions. Actions can then use that context to make decisions, such as if they should be enabled or added to a popup menu. The context information is also typically used when the action is invoked. For example, an action context from a table element may provide the row in a table component that is selected and then a "delete table row" action can use that information to be enabled when a table selection exists and then delete that row if the action is invoked.

Actions can optionally operate on a default context if the current active context is invalid for that action. This allows actions to work on a more global level than just the component that is focused (and yet give preference to the active context.) The idea is that if an action is not valid for the current focused context (and it has been configured to support default context using `setContextClass(Class, boolean)`), then it can be validated against a default action context for its specific action context type. The source for the default context depends on the context type. Default context providers are registered on the tool for each specific ActionContext type. See `DockingWindowManager.registerDefaultContextProvider(Class, ActionContextProvider)` for more details.

The use of default context is primarily intended for tool-level actions which are the ones that appear in the tool's main menu bar or toolbar. This allows the tool actions to mostly work on the tool's main component context regardless of what has focus, and yet still work on the focused component if appropriate (such as a snapshot of the main component).

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `DESCRIPTION_PROPERTY`
  `static final String`
  `ENABLEMENT_PROPERTY`
  `static final String`
  `GLOBALCONTEXT_PROPERTY`
  `static final String`
  `KEYBINDING_DATA_PROPERTY`
  `static final String`
  `MENUBAR_DATA_PROPERTY`
  `static final String`
  `POPUP_MENU_DATA_PROPERTY`
  `static final String`
  `TOOLBAR_DATA_PROPERTY`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `actionPerformed(ActionContext context)`
  method to actually perform the action logic for this action.
  `void`
  `addPropertyChangeListener(PropertyChangeListener listener)`
  Adds a listener to be notified if any property changes
  `JButton`
  `createButton()`
  Returns a JButton that is suitable for this action.
  `default Component`
  `createMenuComponent(boolean isPopup)`
  Returns a component to represent this action in the menu.
  `JMenuItem`
  `createMenuItem(boolean isPopup)`
  Returns a JMenuItem that is suitable for this action.
  `void`
  `dispose()`
  Called when the action's owner is removed from the tool
  `Class<? extends ActionContext>`
  `getContextClass()`
  Returns the class of a specific action context that this action requires for it to operate.
  `KeyBindingData`
  `getDefaultKeyBindingData()`
  Returns the default `KeyBindingData` to be used to assign this action to a key binding.
  `String`
  `getDescription()`
  Returns a short description of this action.
  `String`
  `getFullName()`
  Returns the full name (the action name combined with the owner name)
  `String`
  `getInceptionInformation()`
  Returns a string that includes source file and line number information of where this action was created
  `KeyStroke`
  `getKeyBinding()`
  Convenience method for getting the keybinding for this action.
  `KeyBindingData`
  `getKeyBindingData()`
  Returns the `KeyBindingData` to be used to assign this action to a key binding.
  `default KeyBindingType`
  `getKeyBindingType()`
  Returns this actions level of support for key binding accelerator keys
  `MenuData`
  `getMenuBarData()`
  Returns the `MenuData` to be used to put this action in the menu bar.
  `String`
  `getName()`
  Returns the name of the action
  `String`
  `getOwner()`
  Returns the owner of this action
  `default String`
  `getOwnerDescription()`
  Returns a description of this actions owner.
  `MenuData`
  `getPopupMenuData()`
  Returns the `MenuData` to be used to put this action in a popup menu.
  `ToolBarData`
  `getToolBarData()`
  Returns the `ToolBarData` to be used to put this action in a toolbar.
  `boolean`
  `isAddToPopup(ActionContext context)`
  method is used to determine if this action should be displayed on the current popup.
  `boolean`
  `isEnabled()`
  Returns true if the action is enabled.
  `boolean`
  `isEnabledForContext(ActionContext context)`
  Method used to determine if this action should be enabled for the given context.
  `boolean`
  `isValidContext(ActionContext context)`
  Method that actions implement to indicate if this action is valid (knows how to work with, is appropriate for) for the given context.
  `void`
  `removePropertyChangeListener(PropertyChangeListener listener)`
  Removes a listener to be notified of property changes.
  `void`
  `setContextClass(Class<? extends ActionContext> type, boolean supportsDefaultContext)`
  Sets the specific action context class that this action works on and if the action supports default context.
  `void`
  `setEnabled(boolean newValue)`
  Enables or disables the action
  `void`
  `setKeyBindingData(KeyBindingData keyBindingData)`
  Sets the `KeyBindingData` on an action to either assign a keybinding or remove it (keyBindingData = null).
  `void`
  `setUnvalidatedKeyBindingData(KeyBindingData newKeyBindingData)`
  Users creating actions should not call this method, but should instead call `setKeyBindingData(KeyBindingData)`.
  `boolean`
  `shouldAddToWindow(boolean isMainWindow, Set<Class<?>> contextTypes)`
  Determines whether this action should be added to a window (either the main window or a secondary detached window).
  `boolean`
  `supportsDefaultContext()`
  Returns true if this action also supports operating on a default context other then the active (focused) provider's context.

  ### Methods inherited from interface help.HelpDescriptor

  `getHelpInfo, getHelpObject`

- ## Field Details

  - ### ENABLEMENT_PROPERTY

    static final String ENABLEMENT_PROPERTY
    See Also:
      - Constant Field Values

  - ### GLOBALCONTEXT_PROPERTY

    static final String GLOBALCONTEXT_PROPERTY
    See Also:
      - Constant Field Values

  - ### DESCRIPTION_PROPERTY

    static final String DESCRIPTION_PROPERTY
    See Also:
      - Constant Field Values

  - ### KEYBINDING_DATA_PROPERTY

    static final String KEYBINDING_DATA_PROPERTY
    See Also:
      - Constant Field Values

  - ### MENUBAR_DATA_PROPERTY

    static final String MENUBAR_DATA_PROPERTY
    See Also:
      - Constant Field Values

  - ### POPUP_MENU_DATA_PROPERTY

    static final String POPUP_MENU_DATA_PROPERTY
    See Also:
      - Constant Field Values

  - ### TOOLBAR_DATA_PROPERTY

    static final String TOOLBAR_DATA_PROPERTY
    See Also:
      - Constant Field Values

- ## Method Details

  - ### getName

    String getName()
    Returns the name of the action
    Returns:
      the name

  - ### getOwner

    String getOwner()
    Returns the owner of this action
    Returns:
      the owner

  - ### getOwnerDescription

    default String getOwnerDescription()
    Returns a description of this actions owner. For most actions this will return the same value as `getOwner()`.
    Returns:
      the description

  - ### getDescription

    String getDescription()
    Returns a short description of this action. Generally used for a tooltip
    Returns:
      the description

  - ### addPropertyChangeListener

    void addPropertyChangeListener(PropertyChangeListener listener)
    Adds a listener to be notified if any property changes
    Parameters:
      `listener` - The property change listener that will be notified of property change events.
    See Also:
      - `Action.addPropertyChangeListener(java.beans.PropertyChangeListener)`

  - ### removePropertyChangeListener

    void removePropertyChangeListener(PropertyChangeListener listener)
    Removes a listener to be notified of property changes.
    Parameters:
      `listener` - The property change listener that will be notified of property change events.
    See Also:
      - `addPropertyChangeListener(PropertyChangeListener)`
      - `Action.addPropertyChangeListener(java.beans.PropertyChangeListener)`

  - ### setEnabled

    void setEnabled(boolean newValue)
    Enables or disables the action
    Parameters:
      `newValue` - true to enable the action, false to disable it

  - ### isEnabled

    boolean isEnabled()
    Returns true if the action is enabled.
    Returns:
      true if the action is enabled, false otherwise

  - ### getMenuBarData

    MenuData getMenuBarData()
    Returns the `MenuData` to be used to put this action in the menu bar. The MenuData will be null if the action in not set to be in the menu bar.
    Returns:
      the `MenuData` for the menu bar or null if the action is not in the menu bar.

  - ### getPopupMenuData

    MenuData getPopupMenuData()
    Returns the `MenuData` to be used to put this action in a popup menu. The MenuData will be null if the action in not set to be in a popup menu.
    Returns:
      the `MenuData` for a popup menu or null if the action is not to be in a popup menu.

  - ### getToolBarData

    ToolBarData getToolBarData()
    Returns the `ToolBarData` to be used to put this action in a toolbar. The ToolBarData will be null if the action in not set to be in a toolbar.
    Returns:
      the `ToolBarData` for the popup menu or null if the action is not in a popup menu.

  - ### getKeyBindingData

    KeyBindingData getKeyBindingData()
    Returns the `KeyBindingData` to be used to assign this action to a key binding. The KeyBindingData will be null if the action is not set to have a keyBinding.
    Returns:
      the `KeyBindingData` for the action or null if the action does not have a keyBinding.

  - ### getDefaultKeyBindingData

    KeyBindingData getDefaultKeyBindingData()
    Returns the default `KeyBindingData` to be used to assign this action to a key binding. The KeyBindingData will be null if the action is not set to have a keyBinding. The value of this method is that which is set from a call to `setKeyBindingData(KeyBindingData)`.
    Returns:
      the `KeyBindingData` for the action or null if the action does not have a keyBinding.

  - ### getKeyBinding

    KeyStroke getKeyBinding()
    Convenience method for getting the keybinding for this action.
    Returns:
      the `KeyStroke` to be used as a keybinding for this action or null if there is no

  - ### getFullName

    String getFullName()
    Returns the full name (the action name combined with the owner name)
    Returns:
      the full name

  - ### actionPerformed

    void actionPerformed(ActionContext context)
    method to actually perform the action logic for this action.
    Parameters:
      `context` - the `ActionContext` object that provides information about where and how this action was invoked.

  - ### isAddToPopup

    boolean isAddToPopup(ActionContext context)
    method is used to determine if this action should be displayed on the current popup. This method will only be called if the action has popup `PopupMenuData` set.

    Generally, actions don't need to override this method as the default implementation will defer to the `isEnabledForContext(ActionContext)`, which will have the effect of adding the action to the popup only if it is enabled for a given context. By overriding this method, you can change this behavior so that the action will be added to the popup, even if it is disabled for the context, by having this method return true even if the `isEnabledForContext(ActionContext)` method will return false, resulting in the action appearing in the popup menu, but begin disabled.

    Parameters:
      `context` - the `ActionContext` from the active provider.
    Returns:
      true if this action is appropriate for the given context.

  - ### isValidContext

    boolean isValidContext(ActionContext context)
    Method that actions implement to indicate if this action is valid (knows how to work with, is appropriate for) for the given context. This method is used to determine if the action should be enabled based on the either the local context or the global context. The action is first asked if it is valid for the local context and if not, then it is asked if it is valid for the global context. If a context is valid, then it will then be asked if it is enabled for that context.
    Parameters:
      `context` - the `ActionContext` from the active provider.
    Returns:
      true if this action is appropriate for the given context.

  - ### isEnabledForContext

    boolean isEnabledForContext(ActionContext context)
    Method used to determine if this action should be enabled for the given context.

    This is the method implementors override to control when the action may be used.

    This method will be called by the DockingWindowManager for actions on the global menuBar and toolBar and for actions that have a keyBinding.

    This method will be called whenever one of the following events occur:

    1. when the user invokes the action via its keyBinding,
    2. the user changes focus from one component provider to another,
    3. the user moves a component to another position in the window or into another window,
    4. a component provider reports a change in it's context,
    5. any plugin or software component reports a general change in context (calls the tool.contextChanged(ComponentProvider) with a null parameter).
    The default implementation will simply return this action's enablement state.
    Parameters:
      `context` - the current `ActionContext` for the window.
    Returns:
      true if the action should be enabled for the context or false otherwise.

  - ### getInceptionInformation

    String getInceptionInformation()
    Returns a string that includes source file and line number information of where this action was created
    Returns:
      the inception information

  - ### createButton

    JButton createButton()
    Returns a JButton that is suitable for this action. For example, It creates a ToggleButton if the action is a `ToggleDockingActionIf`.
    Returns:
      a JButton to be used in a toolbar or null if the action does not have ToolBarData set.

  - ### createMenuItem

    JMenuItem createMenuItem(boolean isPopup)
    Returns a JMenuItem that is suitable for this action. For example, if the action is a `ToggleDockingActionIf`, then a JCheckBoxMenuItem will be created.
    Parameters:
      `isPopup` - true if the action should use its Popup MenuData, else it uses the MenuBar MenuData.
    Returns:
      a JMenuItem for placement in either the menu bar or a popup menu.

  - ### createMenuComponent

    default Component createMenuComponent(boolean isPopup)
    Returns a component to represent this action in the menu.

    Typically, this is the menu item that triggers the action. However, some actions may wish to use components other than menu items. For example, they may produce component for helping to organize the menu visually.

    Parameters:
      `isPopup` - true if the action should use its Popup MenuData, else it uses the MenuBar MenuData.
    Returns:
      the component
    See Also:
      - `createMenuItem(boolean)`

  - ### shouldAddToWindow

    boolean shouldAddToWindow(boolean isMainWindow, Set<Class<?>> contextTypes)
    Determines whether this action should be added to a window (either the main window or a secondary detached window). By default, this method will return true for the main window and false otherwise.
    Parameters:
      `isMainWindow` - true if the window in question is the main window
      `contextTypes` - a list of contextTypes (Classes) based on the providers that are currently in the window.
    Returns:
      true if this action should be added to the window, false otherwise.

  - ### getKeyBindingType

    default KeyBindingType getKeyBindingType()
    Returns this actions level of support for key binding accelerator keys

    Actions support key bindings by default. Some reserved actions do not support key bindings, while others wish to share the same key bindings with multiple, equivalent actions (this allows the user to set one binding that works in many different contexts).

    Returns:
      the key binding support

  - ### setKeyBindingData

    void setKeyBindingData(KeyBindingData keyBindingData)
    Sets the `KeyBindingData` on an action to either assign a keybinding or remove it (keyBindingData = null).
    Parameters:
      `keyBindingData` - if non-null, assigns a keybinding to the action. Otherwise, removes any keybinding from the action.

  - ### setUnvalidatedKeyBindingData

    void setUnvalidatedKeyBindingData(KeyBindingData newKeyBindingData)
    Users creating actions should not call this method, but should instead call `setKeyBindingData(KeyBindingData)`.

    Call this method when you wish to bypass the validation of `setKeyBindingData(KeyBindingData)` so that keybindings are set exactly as they are given (such as when set by the user and not by the programmer).

    Parameters:
      `newKeyBindingData` - the KeyBindingData to be used to assign this action to a keybinding

  - ### dispose

    void dispose()
    Called when the action's owner is removed from the tool

  - ### getContextClass

    Class<? extends ActionContext> getContextClass()
    Returns the class of a specific action context that this action requires for it to operate. See `ActionContext` for details on the action context system.
    Returns:
      the class of a specific action context that this action requires for it to operate

  - ### supportsDefaultContext

    boolean supportsDefaultContext()
    Returns true if this action also supports operating on a default context other then the active (focused) provider's context. See the class header for more details.
    Returns:
      true if this action also supports operating on a default context other then the active (focused) provider's context.

  - ### setContextClass

    void setContextClass(Class<? extends ActionContext> type, boolean supportsDefaultContext)
    Sets the specific action context class that this action works on and if the action supports default context. See `ActionContext` for details on how the action context system works.
    Parameters:
      `type` - the `ActionContext` class that this action works on.
      `supportsDefaultContext` - if true, then this action also support operating on a default context other than the active (focused) provider's context.