Interface ActionContext
- All Known Subinterfaces:
FunctionSupplierContext
- All Known Implementing Classes:
CheckoutsActionContext
,CodeComparisonActionContext
,DefaultActionContext
,DialogProjectTreeContext
,EdgeGraphActionContext
,FrontEndProjectTreeContext
,FSBActionContext
,GraphActionContext
,ListingActionContext
,ListingComparisonActionContext
,NavigatableActionContext
,ProgramActionContext
,ProgramLocationActionContext
,ProgramSymbolActionContext
,ProjectDataContext
,ThemeTableContext
,VertexGraphActionContext
,VgActionContext
,VgSatelliteContext
,VgVertexContext
DockingActionIf
s 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.
ComponentProvider
s 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
andexecution
. - 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 betweenenablement
andexecution
. - 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 Summary
Modifier and TypeMethodDescriptionReturns the object that was included by the ComponentProvider when this context was created.int
Returns the click modifiers for this event.Returns the context's mouse event.Returns the component that is the target of this context.Returns the sourceObject from the actionEvent that triggered this context to be generated.boolean
hasAnyEventClickModifiers
(int modifiersMask) Tests the click modifiers for this event to see if they contain any bit from the specified modifiersMask parameter.setContextObject
(Object contextObject) Sets the context object for this context.void
setEventClickModifiers
(int modifiers) Sets the modifiers for this event that were present when the item was clicked on.Updates the context's mouse event.setSourceComponent
(Component sourceComponent) Sets the source component for this ActionContext.setSourceObject
(Object sourceObject) Sets the sourceObject for this ActionContext.
-
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
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, seeActionEvent.getModifiers()
orMouseEvent.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
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
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
-
setSourceComponent
Sets the source component for this ActionContext.- Parameters:
sourceComponent
- the source component- Returns:
- this context
-