Package docking

Class ActionContext

  • Direct Known Subclasses:
    CheckoutsActionContext, DialogProjectTreeContext, DualDecompilerActionContext, FSBActionContext, GraphActionContext, ProgramActionContext, ProjectDataContext, VgActionContext

    public class ActionContext
    extends java.lang.Object
    Action context is a class that contains state information that is given to DockingActionIfs for them to decide if they are enabled for a given user action. User actions are toolbar button presses, menu bar item presses and popup menu item presses. As the user changes focus in the system, all actions are queried with the current context. Thus, toolbar buttons and menu items will enable and disable as the user interacts with the system. Further, popup menu items will not be added to popup menus when they report false for DockingActionIf.isAddToPopup(ActionContext); they will appear in the popup, but be disabled if they report true for the above call, but false for DockingActionIf.isEnabledForContext(ActionContext). When the user executes an action, the current context will be passed to the backing DockingActionIf. Ultimately, context serves to control action enablement and to allow plugins to share state with actions without having to store that state information in class fields of the plugin.

    ComponentProviders are required to return Objects of this type in their getActionContext() methods. Generally, ComponentProviders have two ways to use this class. They can either create an ActionContext 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.

    The data contained by this class has meaning that can change relative to the code that created it. The intended purpose for the fields of this class 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.

    Ultimately, clients can pass any values they wish for the fields of this class, even if that changes the meaning of the fields outlined above.

    • Constructor Detail

      • ActionContext

        public ActionContext()
      • ActionContext

        public ActionContext​(ComponentProvider provider,
                             java.awt.Component sourceComponent)
        Basic constructor for ActionContext
        Parameters:
        provider - the ComponentProvider that generated this context.
        sourceComponent - an optional source object; this is intended to be the component that is the source of the context, usually the focused component
      • ActionContext

        public ActionContext​(ComponentProvider provider,
                             java.lang.Object contextObject,
                             java.awt.Component sourceComponent)
        Constructor
        Parameters:
        provider - the ComponentProvider that generated this context.
        contextObject - an optional contextObject that the ComponentProvider can provide; this can be anything that actions wish to later retrieve
        sourceComponent - an optional source object; this is intended to be the component that is the source of the context, usually the focused component
    • Method Detail

      • getContextObject

        public java.lang.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

        public ActionContext setContextObject​(java.lang.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

        public java.lang.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.
      • setSourceObject

        public ActionContext setSourceObject​(java.lang.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

        public ActionContext setMouseEvent​(java.awt.event.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

        public java.awt.event.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

        public java.awt.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
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • getGlobalContext

        public ActionContext getGlobalContext()
        Returns the global action context for the tool. The global context is the context of the default focused component, instead of the normal action context which is the current focused component.
        Returns:
        the global action context for the tool