Package docking

Interface ActionContext

All Known Implementing Classes:
CheckoutsActionContext, CodeComparisonActionContext, DefaultActionContext, DialogProjectTreeContext, DualDecompilerActionContext, DualListingActionContext, EdgeGraphActionContext, FrontEndProjectTreeContext, FSBActionContext, GraphActionContext, ListingActionContext, NavigatableActionContext, ProgramActionContext, ProgramLocationActionContext, ProgramSymbolActionContext, ProjectDataContext, ThemeTableContext, VertexGraphActionContext, VgActionContext, VgSatelliteContext, VgVertexContext
public interface ActionContext
ActionContext is an interface used by DockingActionIfs that contains tool and plugin state information that allows an action to operate. Actions can use the context to get the information it needs to perform its intended purpose. Context is also used to determine if an action should be enabled, should be added to a popup menu, or if it is even valid for the current context.

The concept of an action being valid or invalid is critical to how the action system works. The reason is that actions can get their context from two different sources. The first source of action context is the current active (focused) ComponentProvider. This is always the preferred source of context for an action. However, if that context is not valid for an action, the action has the option of specifying that it works on default context. In this case, the tool will use the action's declared context type to see if anyone has registered a default provider for that type. If so, the action will be given that context to work on instead of the active context.

Whenever the user moves the focus around by clicking on different components or locations in the tool, all actions are given the opportunity to change their enablement state. The tool calls each action's DockingActionIf.isEnabledForContext(ActionContext) method with the new active context (or default context as explained above). Thus, toolbar buttons and menu items will enable and disable as the user interacts with the system.

When the user executes an action, the current context will be passed to the DockingActionIf, again using a possible default context if the active context isn't valid for that action. Ultimately, context serves to manage actions and to allow plugins to share state with actions without them being directly coupled together.

ComponentProviders are required to return ActionContext objects in their ComponentProvider.getActionContext(MouseEvent) methods. Generally, ComponentProviders have two ways to use this class. They can either create an DefaultActionContext instance and pass in a contextObject that will be useful to its actions or, subclass the ActionContext object to include specific methods to provide the information that actions will require. If actions want to work with default context, then they must declare a action context type that is more specific than just ActionContext.

The generic data that all instances of ActionContxt provide is as follows:

  • provider - the component provider to which this context belongs; the provider that contains the component that is the source of the user action
  • contextObject - client-defined data object. This allows clients to save any information desired to be used when the action is performed.
  • sourceObject - when checking enablement, this is the item that was clicked or activated; when performing an action this is either the active object or the component that was clicked. This value may change between the check for enablement and execution.
  • sourceComponent - this value is the component that is the source of the current context. Whereas the sourceObject is the actual clicked item, this value is the focused/active component and will not change between enablement and execution.
  • mouseEvent - the mouse event that triggered the action; null if the action was triggered by a key binding.

Typically, component providers will define more specific types of ActionContext where they can include any additional information that an action might need to work with that component.

  • Method Details

    • getComponentProvider

      ComponentProvider getComponentProvider()

    • getContextObject

      Object getContextObject()
      Returns the object that was included by the ComponentProvider when this context was created.
      Returns:
      the object that was included by the ComponentProvider when this context was created.

    • setContextObject

      ActionContext setContextObject(Object contextObject)
      Sets the context object for this context. This can be any object of the creator's choosing that can be provided for later retrieval.
      Parameters:
      contextObject - Sets the context object for this context.
      Returns:
      this context

    • getSourceObject

      Object getSourceObject()
      Returns the sourceObject from the actionEvent that triggered this context to be generated.
      Returns:
      the sourceObject from the actionEvent that triggered this context to be generated.

    • setEventClickModifiers

      void setEventClickModifiers(int modifiers)
      Sets the modifiers for this event that were present when the item was clicked on.
      Parameters:
      modifiers - bit-masked int, see ActionEvent.getModifiers() or MouseEvent.getModifiersEx()

    • getEventClickModifiers

      int getEventClickModifiers()
      Returns the click modifiers for this event.

      Only present for some mouse assisted events, e.g. clicking on a toolbar button or choosing a menu item in a popup menu.

      Returns:
      bit-masked int, see InputEvent.SHIFT_MASK, etc

    • hasAnyEventClickModifiers

      boolean hasAnyEventClickModifiers(int modifiersMask)
      Tests the click modifiers for this event to see if they contain any bit from the specified modifiersMask parameter.
      Parameters:
      modifiersMask - bitmask to test
      Returns:
      boolean true if any bit in the eventClickModifiers matches the mask

    • setSourceObject

      ActionContext setSourceObject(Object sourceObject)
      Sets the sourceObject for this ActionContext. This method is used internally by the DockingWindowManager. ComponentProvider and action developers should only use this method for testing.
      Parameters:
      sourceObject - the source object
      Returns:
      this context

    • setMouseEvent

      ActionContext setMouseEvent(MouseEvent e)
      Updates the context's mouse event. Contexts that are based upon key events will have no mouse event. This method is really for the framework to use. Client calls to this method will be overridden by the framework when menu items are clicked.
      Parameters:
      e - the event that triggered this context.
      Returns:
      this context

    • getMouseEvent

      MouseEvent getMouseEvent()
      Returns the context's mouse event. Contexts that are based upon key events will have no mouse event.
      Returns:
      the mouse event that triggered this context; null implies a key event-based context

    • getSourceComponent

      Component getSourceComponent()
      Returns the component that is the target of this context. This value should not change whether the context is triggered by a key binding or mouse event.
      Returns:
      the component; may be null