Package org.eclipse.gef.tools
Class TargetingTool
- java.lang.Object
-
- org.eclipse.gef.util.FlagSupport
-
- org.eclipse.gef.tools.AbstractTool
-
- org.eclipse.gef.tools.TargetingTool
-
- All Implemented Interfaces:
RequestConstants
,Tool
- Direct Known Subclasses:
AbstractConnectionCreationTool
,ConnectionEndpointTracker
,CreationTool
,SelectEditPartTracker
,SelectionTool
public abstract class TargetingTool extends AbstractTool
The base implementation for tools which perform targeting of editparts. Targeting tools may operate using either mouse drags or just mouse moves. Targeting tools work with a target request. This request is used along with the mouse location to obtain an active target from the current EditPartViewer. This target is then asked for theCommand
that performs the given request. The target is also asked to show target feedback.TargetingTool also provides support for auto-expose (a.k.a. auto-scrolling). Subclasses that wish to commence auto-expose can do so by calling
updateAutoexposeHelper()
. An an AutoExposeHelper is found, auto-scrolling begins. Whenever that helper scrolls the diagram of performs any other change,handleMove
will be called as if the mouse had moved. This is because the target has probably moved, but there is no input event to trigger an update of the operation.
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from class org.eclipse.gef.tools.AbstractTool
AbstractTool.Input
-
-
Field Summary
Fields Modifier and Type Field Description protected static int
MAX_FLAG
The max flag.-
Fields inherited from class org.eclipse.gef.tools.AbstractTool
MAX_STATE, MOUSE_BUTTON_ANY, MOUSE_BUTTON1, MOUSE_BUTTON2, MOUSE_BUTTON3, PROPERTY_UNLOAD_WHEN_FINISHED, STATE_ACCESSIBLE_DRAG, STATE_ACCESSIBLE_DRAG_IN_PROGRESS, STATE_DRAG, STATE_DRAG_IN_PROGRESS, STATE_INITIAL, STATE_INVALID, STATE_TERMINAL
-
Fields inherited from interface org.eclipse.gef.RequestConstants
REQ_ADD, REQ_ALIGN, REQ_ALIGN_CHILDREN, REQ_CLONE, REQ_CONNECTION_END, REQ_CONNECTION_START, REQ_CREATE, REQ_CREATE_BENDPOINT, REQ_DELETE, REQ_DELETE_DEPENDANT, REQ_DIRECT_EDIT, REQ_MOVE, REQ_MOVE_BENDPOINT, REQ_MOVE_CHILDREN, REQ_OPEN, REQ_ORPHAN, REQ_ORPHAN_CHILDREN, REQ_RECONNECT_SOURCE, REQ_RECONNECT_TARGET, REQ_RESIZE, REQ_RESIZE_CHILDREN, REQ_SELECTION, REQ_SELECTION_HOVER
-
-
Constructor Summary
Constructors Constructor Description TargetingTool()
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description protected Request
createTargetRequest()
Creates the target request that will be used with the target editpart.void
deactivate()
Deactivates the tool.protected void
doAutoexpose()
Called to perform an iteration of the autoexpose process.protected void
eraseTargetFeedback()
Asks the current target editpart to erase target feedback using the target request.protected AutoexposeHelper
getAutoexposeHelper()
Returnsnull
or the current autoexpose helper.protected Command
getCommand()
Queries the target editpart for a command.protected java.util.Collection
getExclusionSet()
Returns a List of objects that should be excluded as potential targets for the operation.protected EditPart
getTargetEditPart()
Returnsnull
or the current target editpart.protected EditPartViewer.Conditional
getTargetingConditional()
Returns the conditional object used for obtaining the target editpart from the current viewer.protected Request
getTargetRequest()
Lazily creates and returns the request used when communicating with the target editpart.protected void
handleAutoexpose()
This method is called whenever an autoexpose occurs.protected boolean
handleEnteredEditPart()
Called whenever the target editpart has changed.protected boolean
handleExitingEditPart()
Called whenever the target editpart is about to change.protected boolean
handleHoverStop()
Called from resetHover() iff hover is active.protected boolean
handleInvalidInput()
Called when invalid input is encountered.protected void
handleLeavingEditPart()
An archaic method name that has been left here to force use of the new name.protected boolean
handleViewerExited()
Sets the target tonull
.protected boolean
isShowingTargetFeedback()
Returnstrue
if target feedback is being shown.protected boolean
isTargetLocked()
Returntrue
if the current target is locked.protected void
lockTargetEditPart(EditPart editpart)
Locks-in the given editpart as the target.protected void
resetFlags()
Extended to reset the target lock flag.protected void
resetHover()
Resets hovering to inactive.protected void
setAutoexposeHelper(AutoexposeHelper helper)
Sets the active autoexpose helper to the given helper, ornull
.protected void
setTargetEditPart(EditPart editpart)
Sets the target editpart.protected void
setTargetRequest(Request req)
Sets the target request.protected void
showTargetFeedback()
Asks the target editpart to show target feedback and sets the target feedback flag.protected void
unlockTargetEditPart()
Releases the targeting lock, and updates the target in case the mouse is already over a new target.protected void
updateAutoexposeHelper()
Updates the activeAutoexposeHelper
.protected void
updateTargetRequest()
Subclasses should override to update the target request.protected boolean
updateTargetUnderMouse()
Updates the target editpart and returnstrue
if the target changes.-
Methods inherited from class org.eclipse.gef.tools.AbstractTool
acceptArrowKey, activate, addFeedback, applyProperty, calculateCursor, commitDrag, createOperationSet, debug, executeCommand, executeCurrentCommand, focusGained, focusLost, getCommandName, getCurrentCommand, getCurrentInput, getCurrentViewer, getDebugName, getDebugNameForState, getDefaultCursor, getDisabledCursor, getDomain, getDragMoveDelta, getLocation, getOperationSet, getStartLocation, getState, handleButtonDown, handleButtonUp, handleCommandStackChanged, handleDoubleClick, handleDrag, handleDragInProgress, handleDragStarted, handleFinished, handleFocusGained, handleFocusLost, handleHover, handleKeyDown, handleKeyTraversed, handleKeyUp, handleMove, handleNativeDragFinished, handleNativeDragStarted, handleViewerEntered, isActive, isHoverActive, isInState, isViewerImportant, keyDown, keyTraversed, keyUp, mouseDoubleClick, mouseDown, mouseDrag, mouseHover, mouseMove, mouseUp, mouseWheelScrolled, movedPastThreshold, nativeDragFinished, nativeDragStarted, performViewerMouseWheel, placeMouseInViewer, reactivate, refreshCursor, releaseToolCapture, removeFeedback, setCurrentCommand, setCursor, setDefaultCursor, setDisabledCursor, setEditDomain, setHoverActive, setProperties, setStartLocation, setState, setToolCapture, setUnloadWhenFinished, setViewer, stateTransition, unloadWhenFinished, viewerEntered, viewerExited
-
Methods inherited from class org.eclipse.gef.util.FlagSupport
getFlag, setFlag
-
-
-
-
Field Detail
-
MAX_FLAG
protected static final int MAX_FLAG
The max flag.- See Also:
- Constant Field Values
-
-
Method Detail
-
createTargetRequest
protected Request createTargetRequest()
Creates the target request that will be used with the target editpart. This request will be cached and updated as needed.- Returns:
- the new target request
- See Also:
getTargetRequest()
-
deactivate
public void deactivate()
Description copied from class:AbstractTool
Deactivates the tool. This method is called whenever the user switches to another tool. Use this method to do some clean-up when the tool is switched. The abstract tool allows cursors for viewers to be changed. When the tool is deactivated it must revert to normal the cursor of the last tool it changed.- Specified by:
deactivate
in interfaceTool
- Overrides:
deactivate
in classAbstractTool
- See Also:
Tool.deactivate()
-
doAutoexpose
protected void doAutoexpose()
Called to perform an iteration of the autoexpose process. If the expose helper is set, it will be asked to step at the current mouse location. If it returns true, another expose iteration will be queued. There is no delay between autoexpose events, other than the time required to perform the step().
-
eraseTargetFeedback
protected void eraseTargetFeedback()
Asks the current target editpart to erase target feedback using the target request. If target feedback is not being shown, this method does nothing and returns. Otherwise, the target feedback flag is reset to false, and the target editpart is asked to erase target feedback. This methods should rarely be overridden.
-
getCommand
protected Command getCommand()
Queries the target editpart for a command.- Overrides:
getCommand
in classAbstractTool
- Returns:
- a newly obtained command
- See Also:
AbstractTool.getCommand()
-
getExclusionSet
protected java.util.Collection getExclusionSet()
Returns a List of objects that should be excluded as potential targets for the operation.- Returns:
- the list of objects to be excluded as targets
-
getTargetingConditional
protected EditPartViewer.Conditional getTargetingConditional()
Returns the conditional object used for obtaining the target editpart from the current viewer. By default, a conditional is returned that tests whether an editpart at the current mouse location indicates a target for the operation's request, usingEditPart.getTargetEditPart(Request)
. Ifnull
is returned, then the conditional fails, and the search continues.- Returns:
- the targeting conditional
- See Also:
EditPartViewer.findObjectAtExcluding(Point, Collection, EditPartViewer.Conditional)
-
getTargetEditPart
protected EditPart getTargetEditPart()
Returnsnull
or the current target editpart.- Returns:
null
or a target part
-
getTargetRequest
protected Request getTargetRequest()
Lazily creates and returns the request used when communicating with the target editpart.- Returns:
- the target request
-
handleAutoexpose
protected void handleAutoexpose()
This method is called whenever an autoexpose occurs. When an autoexpose occurs, it is possible that everything in the viewer has moved a little. Therefore, by default,handleMove()
is called to simulate the mouse moving even though it didn't.
-
handleEnteredEditPart
protected boolean handleEnteredEditPart()
Called whenever the target editpart has changed. By default, the target request is updated, and the new target is asked to show feedback. Subclasses may extend this method if needed.- Returns:
true
-
handleExitingEditPart
protected boolean handleExitingEditPart()
Called whenever the target editpart is about to change. By default, hover is reset, in the case that a hover was showing something, and the target being exited is asked to erase its feedback.- Returns:
true
-
handleHoverStop
protected boolean handleHoverStop()
Called from resetHover() iff hover is active. Subclasses may extend this method to handle the hover stop event. Returnstrue
if something was done in response to the call.- Returns:
true
if the hover stop is processed in some way- See Also:
AbstractTool.isHoverActive()
-
handleInvalidInput
protected boolean handleInvalidInput()
Called when invalid input is encountered. By default, feedback is erased, and the current command is set to the unexecutable command. The state does not change, so the caller must set the state toAbstractTool.STATE_INVALID
.- Overrides:
handleInvalidInput
in classAbstractTool
- Returns:
true
-
handleLeavingEditPart
protected final void handleLeavingEditPart() throws java.lang.Exception
An archaic method name that has been left here to force use of the new name.- Throws:
java.lang.Exception
- exc
-
handleViewerExited
protected boolean handleViewerExited()
Sets the target tonull
.- Overrides:
handleViewerExited
in classAbstractTool
- Returns:
true
if the viewer exited was handled- See Also:
AbstractTool.handleViewerExited()
-
isShowingTargetFeedback
protected boolean isShowingTargetFeedback()
Returnstrue
if target feedback is being shown.- Returns:
true
if showing target feedback
-
isTargetLocked
protected boolean isTargetLocked()
Returntrue
if the current target is locked.- Returns:
true
if the target is locked- See Also:
lockTargetEditPart(EditPart)
-
lockTargetEditPart
protected void lockTargetEditPart(EditPart editpart)
Locks-in the given editpart as the target. Updating of the target will not occur untilunlockTargetEditPart()
is called.- Parameters:
editpart
- the target to be locked-in
-
resetFlags
protected void resetFlags()
Extended to reset the target lock flag.- Overrides:
resetFlags
in classAbstractTool
- See Also:
AbstractTool.resetFlags()
,lockTargetEditPart(EditPart)
-
resetHover
protected void resetHover()
Resets hovering to inactive.- Since:
- 3.4
-
setAutoexposeHelper
protected void setAutoexposeHelper(AutoexposeHelper helper)
Sets the active autoexpose helper to the given helper, ornull
. If the helper is notnull
, a runnable is queued on the event thread that will trigger a subsequentdoAutoexpose()
. The helper is typically updated only on a hover event.- Parameters:
helper
- the new autoexpose helper ornull
-
setTargetEditPart
protected void setTargetEditPart(EditPart editpart)
Sets the target editpart. If the target editpart is changing, this method will callhandleExitingEditPart()
for the previous target if notnull
, andhandleEnteredEditPart()
for the new target, if notnull
.- Parameters:
editpart
- the new target
-
setTargetRequest
protected void setTargetRequest(Request req)
Sets the target request. This method is typically not called; subclasses normally overridecreateTargetRequest()
.- Parameters:
req
- the target request
-
showTargetFeedback
protected void showTargetFeedback()
Asks the target editpart to show target feedback and sets the target feedback flag.
-
unlockTargetEditPart
protected void unlockTargetEditPart()
Releases the targeting lock, and updates the target in case the mouse is already over a new target.
-
updateAutoexposeHelper
protected void updateAutoexposeHelper()
Updates the activeAutoexposeHelper
. Does nothing if there is still an active helper. Otherwise, obtains a new helper (possiblenull
) at the current mouse location and callssetAutoexposeHelper(AutoexposeHelper)
.
-
updateTargetRequest
protected void updateTargetRequest()
Subclasses should override to update the target request.
-
updateTargetUnderMouse
protected boolean updateTargetUnderMouse()
Updates the target editpart and returnstrue
if the target changes. The target is updated by using the target conditional and the target request. If the target has been locked, this method does nothing and returnsfalse
.- Returns:
true
if the target was changed
-
getAutoexposeHelper
protected AutoexposeHelper getAutoexposeHelper()
Returnsnull
or the current autoexpose helper.- Returns:
- null or a helper
-
-