Eclipse GEF 3.2

## 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 the `Command` 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 inherited from class org.eclipse.gef.tools.AbstractTool
`AbstractTool.Input`

Field Summary
`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
`TargetingTool()`

Method Summary
`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()` Returns `null` or the current autoexpose helper.
`protected Command` `getCommand()` Queries the target editpart for a command.
`protected Collection` `getExclusionSet()` Returns a List of objects that should be excluded as potential targets for the operation.
`protected EditPart` `getTargetEditPart()` Returns `null` 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 to `null`.
`protected boolean` `isShowingTargetFeedback()` Returns `true` if target feedback is being shown.
`protected boolean` `isTargetLocked()` Return `true` 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` `setAutoexposeHelper(AutoexposeHelper helper)` Sets the active autoexpose helper to the given helper, or `null`.
`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 active `AutoexposeHelper`.
`protected void` `updateTargetRequest()` Subclasses should override to update the target request.
`protected boolean` `updateTargetUnderMouse()` Updates the target editpart and returns `true` if the target changes.

Methods inherited from class org.eclipse.gef.tools.AbstractTool

`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, 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`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### MAX_FLAG

    protected static final int MAX_FLAG

  The max flag.

  See Also:
    Constant Field Values

Constructor Detail

### TargetingTool

    public TargetingTool()

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 interface `Tool`
  Overrides:
    `deactivate` in class `AbstractTool`
  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 class `AbstractTool`
  Returns:
    a newly obtained command
  See Also:
    `AbstractTool.getCommand()`

### getExclusionSet

    protected 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, using `EditPart.getTargetEditPart(Request)`. If `null` 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()

  Returns `null` 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. Returns `true` 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 to `AbstractTool.STATE_INVALID`.

  Overrides:
    `handleInvalidInput` in class `AbstractTool`
  Returns:
    `true`

### handleLeavingEditPart

    protected final void handleLeavingEditPart()
                                        throws Exception

  An archaic method name that has been left here to force use of the new name.

  Throws:
    `Exception` - exc

### handleViewerExited

    protected boolean handleViewerExited()

  Sets the target to `null`.

  Overrides:
    `handleViewerExited` in class `AbstractTool`
  Returns:
    `true` if the viewer exited was handled
  See Also:
    `AbstractTool.handleViewerExited()`

### isShowingTargetFeedback

    protected boolean isShowingTargetFeedback()

  Returns `true` if target feedback is being shown.

  Returns:
    `true` if showing target feedback

### isTargetLocked

    protected boolean isTargetLocked()

  Return `true` 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 until `unlockTargetEditPart()` is called.

  Parameters:
    `editpart` - the target to be locked-in

### resetFlags

    protected void resetFlags()

  Extended to reset the target lock flag.

  Overrides:
    `resetFlags` in class `AbstractTool`
  See Also:
    `AbstractTool.resetFlags()`, `lockTargetEditPart(EditPart)`

### setAutoexposeHelper

    protected void setAutoexposeHelper(AutoexposeHelper helper)

  Sets the active autoexpose helper to the given helper, or `null`. If the helper is not `null`, a runnable is queued on the event thread that will trigger a subsequent `doAutoexpose()`. The helper is typically updated only on a hover event.

  Parameters:
    `helper` - the new autoexpose helper or `null`

### setTargetEditPart

    protected void setTargetEditPart(EditPart editpart)

  Sets the target editpart. If the target editpart is changing, this method will call `handleExitingEditPart()` for the previous target if not `null`, and `handleEnteredEditPart()` for the new target, if not `null`.

  Parameters:
    `editpart` - the new target

### setTargetRequest

    protected void setTargetRequest(Request req)

  Sets the target request. This method is typically not called; subclasses normally override `createTargetRequest()`.

  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 active `AutoexposeHelper`. Does nothing if there is still an active helper. Otherwise, obtains a new helper (possible `null`) at the current mouse location and calls `setAutoexposeHelper(AutoexposeHelper)`.

### updateTargetRequest

    protected void updateTargetRequest()

  Subclasses should override to update the target request.

### updateTargetUnderMouse

    protected boolean updateTargetUnderMouse()

  Updates the target editpart and returns `true` 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 returns `false`.

  Returns:
    `true` if the target was changed

### getAutoexposeHelper

    protected AutoexposeHelper getAutoexposeHelper()

  Returns `null` or the current autoexpose helper.

  Returns:
    null or a helper

Eclipse GEF 3.2

Copyright (c) IBM Corp. and others 2000, 2006. All Rights Reserved.