org.eclipse.gef.tools

## Class AbstractTool

- java.lang.Object
- - org.eclipse.gef.util.FlagSupport
  - - org.eclipse.gef.tools.AbstractTool

All Implemented Interfaces:
  RequestConstants, Tool

Direct Known Subclasses:
  MarqueeSelectionTool, SimpleDragTracker, TargetingTool

    public abstract class AbstractTool
    extends FlagSupport
    implements Tool, RequestConstants

The base implementation for `Tool`s. The base implementation provides a framework for a state machine which processes mouse and keyboard input. The state machine consists of a series of states identified by `int`s. Each mouse or keyboard event results in a transition, sometimes to the same state in which the input was received. The interesting transitions have corresponding actions assigned to them, such as `handleDragStarted()`.

The base implementation performs no state transitions by default, but does route events to different method handlers based on state. It is up to subclasses to set the appropriate states.

There are two broad "categories" of methods on AbstractTool. There are the methods defined on the `Tool` interface which handle the job of receiving raw user input. For example, `mouseDrag(MouseEvent, EditPartViewer)`. Then, there are the methods which correspond to higher-level interpretation of these events, such as `handleDragInProgress()`, which is called from `mouseMove(...)`, but only when the drag threshold has been passed. These methods are generally more subclass-friendly. Subclasses should not override the methods which receive raw input.

### Nested Class Summary

Nested Classes
`static class` `AbstractTool.Input` Allows the user to access mouse and keyboard input.

### Field Summary

Fields
`protected static int` `MAX_FLAG` The highest-bit flag being used.
`protected static int` `MAX_STATE` The maximum state flag defined by this class
`protected static int` `MOUSE_BUTTON_ANY` Deprecated. Use `SWT.BUTTON_MASK` instead.
`protected static int` `MOUSE_BUTTON1` Deprecated. Use `SWT.BUTTON1` instead.
`protected static int` `MOUSE_BUTTON2` Deprecated. Use `SWT.BUTTON2` instead.
`protected static int` `MOUSE_BUTTON3` Deprecated. Use `SWT.BUTTON3` instead.
`static java.lang.Object` `PROPERTY_UNLOAD_WHEN_FINISHED` The property to be used in `setProperties(Map)` for `setUnloadWhenFinished(boolean)`
`protected static int` `STATE_ACCESSIBLE_DRAG` The state indicating that the keyboard is being used to perform a drag that is normally done using the mouse.
`protected static int` `STATE_ACCESSIBLE_DRAG_IN_PROGRESS` The state indicating that a keyboard drag is in progress.
`protected static int` `STATE_DRAG` The state indicating that one or more buttons are pressed, but the user has not moved past the drag threshold.
`protected static int` `STATE_DRAG_IN_PROGRESS` The state indicating that the drag detection theshold has been passed, and a drag is in progress.
`protected static int` `STATE_INITIAL` The first state that a tool is in.
`protected static int` `STATE_INVALID` The state indicating that an input event has invalidated the interaction.
`protected static int` `STATE_TERMINAL` The final state for a tool to be in.

### 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 and Description
`AbstractTool()`

### Method Summary

Methods
`protected boolean` `acceptArrowKey(KeyEvent e)` Returns true if the event corresponds to an arrow key with the appropriate modifiers and if the system is in a state where the arrow key should be accepted.
`void` `activate()` Activates the tool.
`protected void` `addFeedback(IFigure figure)` Convenience method to add the given figure to the feedback layer.
`protected void` `applyProperty(java.lang.Object key, java.lang.Object value)` This method is invoked from `setProperties(Map)`.
`protected Cursor` `calculateCursor()` Returns the appropriate cursor for the tools current state.
`void` `commitDrag()` Added for compatibility.
`protected java.util.List` `createOperationSet()` Returns a new List of editparts that this tool is operating on.
`void` `deactivate()` Deactivates the tool.
`protected void` `debug(java.lang.String message)` Deprecated.
`protected void` `executeCommand(Command command)` Executes the given command on the command stack.
`protected void` `executeCurrentCommand()` Execute the currently active command.
`void` `focusGained(FocusEvent event, EditPartViewer viewer)` Called when a viewer that the editor controls gains focus.
`void` `focusLost(FocusEvent event, EditPartViewer viewer)` Called when a viewer that the editor controls loses focus.
`protected Command` `getCommand()` Returns a new, updated command based on the tool's current properties.
`protected abstract java.lang.String` `getCommandName()` Returns the identifier of the command that is being sought.
`protected Command` `getCurrentCommand()` Returns the currently cached command.
`protected AbstractTool.Input` `getCurrentInput()` Returns the input object encapsulating the current mouse and keyboard state.
`protected EditPartViewer` `getCurrentViewer()` Return the viewer that the tool is currently receiving input from, or `null`.
`protected java.lang.String` `getDebugName()` Returns the debug name for this tool.
`protected java.lang.String` `getDebugNameForState(int state)` Returns a String representation of the given state for debug purposes.
`protected Cursor` `getDefaultCursor()` Returns the cursor used under normal conditions.
`protected Cursor` `getDisabledCursor()` Returns the cursor used under abnormal conditions.
`protected EditDomain` `getDomain()` Returns the EditDomain.
`protected Dimension` `getDragMoveDelta()` Return the number of pixels that the mouse has been moved since that drag was started.
`protected Point` `getLocation()` Returns the current x, y position of the mouse cursor.
`protected java.util.List` `getOperationSet()` Lazily creates and returns the list of editparts on which the tool operates.
`protected Point` `getStartLocation()` Returns the starting mouse location for the current tool operation.
`protected int` `getState()` Returns the tool's current state.
`protected boolean` `handleButtonDown(int button)` Called when the mouse button has been pressed.
`protected boolean` `handleButtonUp(int button)` Called when the mouse button has been released.
`protected boolean` `handleCommandStackChanged()` Called when the command stack has changed, for instance, when a delete or undo command has been executed.
`protected boolean` `handleDoubleClick(int button)` Called when a mouse double-click occurs.
`protected boolean` `handleDrag()` Called whenever the mouse is being dragged.
`protected boolean` `handleDragInProgress()` Called whenever a mouse is being dragged and the drag threshold has been exceeded.
`protected boolean` `handleDragStarted()` Called only one time during a drag when the drag threshold has been exceeded.
`protected void` `handleFinished()` Called when the current tool operation is to be completed.
`protected boolean` `handleFocusGained()` Handles high-level processing of a focus gained event.
`protected boolean` `handleFocusLost()` Handles high-level processing of a focus lost event.
`protected boolean` `handleHover()` Handles high-level processing of a mouse hover event.
`protected boolean` `handleInvalidInput()` Called when invalid input is encountered.
`protected boolean` `handleKeyDown(KeyEvent e)` Handles high-level processing of a key down event.
`protected void` `handleKeyTraversed(TraverseEvent event)` Override to process a traverse event.
`protected boolean` `handleKeyUp(KeyEvent e)` Handles high-level processing of a key up event.
`protected boolean` `handleMove()` Handles high-level processing of a mouse move.
`protected boolean` `handleNativeDragFinished(DragSourceEvent event)` Handles when a native drag has ended.
`protected boolean` `handleNativeDragStarted(DragSourceEvent event)` Handles when a native drag has started.
`protected boolean` `handleViewerEntered()` Called when the mouse enters an EditPartViewer.
`protected boolean` `handleViewerExited()` Called when the mouse exits an EditPartViewer.
`protected boolean` `isActive()` Returns `true` if the tool is active.
`protected boolean` `isHoverActive()` Returns `true` if the tool is hovering.
`protected boolean` `isInState(int state)` Returns `true` if the tool is in the given state.
`protected boolean` `isViewerImportant(EditPartViewer viewer)` Default implementation always returns `true`.
`void` `keyDown(KeyEvent evt, EditPartViewer viewer)` Receives a KeyDown event for the given viewer.
`void` `keyTraversed(TraverseEvent event, EditPartViewer viewer)` Receives a traversal event for the given viewer.
`void` `keyUp(KeyEvent evt, EditPartViewer viewer)` Receives a KeyUp event for the given viewer.
`void` `mouseDoubleClick(MouseEvent me, EditPartViewer viewer)` Handles mouse double click events within a viewer.
`void` `mouseDown(MouseEvent me, EditPartViewer viewer)` Handles mouse down events within a viewer.
`void` `mouseDrag(MouseEvent me, EditPartViewer viewer)` Handles mouse drag events within a viewer.
`void` `mouseHover(MouseEvent me, EditPartViewer viewer)` Handles mouse hover event. within a viewer.
`void` `mouseMove(MouseEvent me, EditPartViewer viewer)` Handles mouse moves (if the mouse button is up) within a viewer.
`void` `mouseUp(MouseEvent me, EditPartViewer viewer)` Handles mouse up within a viewer.
`void` `mouseWheelScrolled(Event event, EditPartViewer viewer)` Handles mouse-wheel scrolling for a viewer.
`protected boolean` `movedPastThreshold()` Returns `true` if the threshold has been exceeded during a mouse drag.
`void` `nativeDragFinished(DragSourceEvent event, EditPartViewer viewer)` Called when a native drag ends on a Viewer.
`void` `nativeDragStarted(DragSourceEvent event, EditPartViewer viewer)` Called when a native drag begins on a Viewer.
`protected void` `performViewerMouseWheel(Event event, EditPartViewer viewer)` Delegates mouse-wheel event handling to registered `MouseWheelHandlers` based on the given Event's statemask.
`protected void` `placeMouseInViewer(Point p)` Places the mouse in the viewer based on the point given.
`protected void` `reactivate()` Calls `deactivate()` and then `activate()`.
`protected void` `refreshCursor()` Sets the cursor being displayed to the appropriate cursor.
`protected void` `releaseToolCapture()` Releases tool capture.
`protected void` `removeFeedback(IFigure figure)` Convenience method to removes a figure from the feedback layer.
`protected void` `resetFlags()` Resets all stateful flags to their initial values.
`protected void` `setCurrentCommand(Command c)` Used to cache a command obtained from `getCommand()`.
`protected void` `setCursor(Cursor cursor)` Shows the given cursor on the current viewer.
`void` `setDefaultCursor(Cursor cursor)` Sets the default cursor.
`void` `setDisabledCursor(Cursor cursor)` Sets the disabled cursor.
`void` `setEditDomain(EditDomain domain)` Sets the EditDomain.
`protected void` `setHoverActive(boolean value)` Sets whether the hover flag is true or false.
`void` `setProperties(java.util.Map properties)` An example is `PROPERTY_UNLOAD_WHEN_FINISHED` -> Boolean.
`protected void` `setStartLocation(Point p)` Sets the start mouse location, typically for a drag operation.
`protected void` `setState(int state)` Sets the tools state.
`protected void` `setToolCapture()` Sets tool capture.
`void` `setUnloadWhenFinished(boolean value)` Setting this to `true` will cause the tool to be unloaded after one operation has completed.
`void` `setViewer(EditPartViewer viewer)` Sets the active EditPartViewer.
`protected boolean` `stateTransition(int start, int end)` Returns `true` if the give state transition succeeds.
`protected boolean` `unloadWhenFinished()` Returns `true` if the tool is set to unload when its current operation is complete.
`void` `viewerEntered(MouseEvent me, EditPartViewer viewer)` Receives the mouse entered event.
`void` `viewerExited(MouseEvent me, EditPartViewer viewer)` Handles the mouse exited event.

### 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

#### PROPERTY_UNLOAD_WHEN_FINISHED

    public static final java.lang.Object PROPERTY_UNLOAD_WHEN_FINISHED

The property to be used in `setProperties(Map)` for `setUnloadWhenFinished(boolean)`

#### MAX_FLAG

    protected static final int MAX_FLAG

The highest-bit flag being used.

See Also:
  Constant Field Values

#### MAX_STATE

    protected static final int MAX_STATE

The maximum state flag defined by this class

See Also:
  Constant Field Values

#### MOUSE_BUTTON1

    protected static final int MOUSE_BUTTON1

Deprecated. Use `SWT.BUTTON1` instead.
constant used for mouse button 1.

See Also:
  Constant Field Values

#### MOUSE_BUTTON2

    protected static final int MOUSE_BUTTON2

Deprecated. Use `SWT.BUTTON2` instead.
constant used for mouse button 2.

See Also:
  Constant Field Values

#### MOUSE_BUTTON3

    protected static final int MOUSE_BUTTON3

Deprecated. Use `SWT.BUTTON3` instead.
constant used for mouse button 3.

See Also:
  Constant Field Values

#### MOUSE_BUTTON_ANY

    protected static final int MOUSE_BUTTON_ANY

Deprecated. Use `SWT.BUTTON_MASK` instead.
constant used to indicate any of the mouse buttons.

#### STATE_ACCESSIBLE_DRAG

    protected static final int STATE_ACCESSIBLE_DRAG

The state indicating that the keyboard is being used to perform a drag that is normally done using the mouse.

See Also:
  Constant Field Values

#### STATE_ACCESSIBLE_DRAG_IN_PROGRESS

    protected static final int STATE_ACCESSIBLE_DRAG_IN_PROGRESS

The state indicating that a keyboard drag is in progress. The threshold for keyboard drags is non-existent, so this state would be entered very quickly.

See Also:
  Constant Field Values

#### STATE_DRAG

    protected static final int STATE_DRAG

The state indicating that one or more buttons are pressed, but the user has not moved past the drag threshold. Many tools will do nothing during this state but wait until `STATE_DRAG_IN_PROGRESS` is entered.

See Also:
  Constant Field Values

#### STATE_DRAG_IN_PROGRESS

    protected static final int STATE_DRAG_IN_PROGRESS

The state indicating that the drag detection theshold has been passed, and a drag is in progress.

See Also:
  Constant Field Values

#### STATE_INITIAL

    protected static final int STATE_INITIAL

The first state that a tool is in. The tool will generally be in this state immediately following `activate()`.

See Also:
  Constant Field Values

#### STATE_INVALID

    protected static final int STATE_INVALID

The state indicating that an input event has invalidated the interaction. For example, during a mouse drag, pressing additional mouse button might invalidate the drag.

See Also:
  Constant Field Values

#### STATE_TERMINAL

    protected static final int STATE_TERMINAL

The final state for a tool to be in. Once a tool reaches this state, it will not change states until it is activated() again.

See Also:
  Constant Field Values

### Constructor Detail

#### AbstractTool

    public AbstractTool()

### Method Detail

#### acceptArrowKey

    protected boolean acceptArrowKey(KeyEvent e)

Returns true if the event corresponds to an arrow key with the appropriate modifiers and if the system is in a state where the arrow key should be accepted.

Parameters:
  `e` - the key event
Returns:
  true if the arrow key should be accepted by this tool
Since:
  3.4

#### activate

    public void activate()

Activates the tool. Any initialization should be performed here. This method is called when a tool is selected.

Specified by:
  `activate` in interface `Tool`
See Also:
  `deactivate()`

#### addFeedback

    protected void addFeedback(IFigure figure)

Convenience method to add the given figure to the feedback layer.

Parameters:
  `figure` - the feedback being added

#### applyProperty

    protected void applyProperty(java.lang.Object key,
                     java.lang.Object value)

This method is invoked from `setProperties(Map)`. Sub-classes can override to add support for more properties. This method should fail silently in case of any error.

AbstractTool uses introspection to match any keys with properties. For instance, the key "defaultCursor" would lead to the invocation of `setDefaultCursor(Cursor)` with the provided value.

Parameters:
  `key` - the key; may be `null`
  `value` - the new value
Since:
  3.1
See Also:
  `setProperties(Map)`

#### calculateCursor

    protected Cursor calculateCursor()

Returns the appropriate cursor for the tools current state. If the tool is in its terminal state, `null` is returned. Otherwise, either the default or disabled cursor is returned, based on the existence of a current command, and whether that current command is executable.

Subclasses may override or extend this method to calculate the appropriate cursor based on other conditions.

Returns:
  `null` or a cursor to be displayed.
See Also:
  `getDefaultCursor()`, `getDisabledCursor()`, `getCurrentCommand()`

#### commitDrag

    public void commitDrag()

Added for compatibility. `DragTracker.commitDrag()` was added for accessibility reasons. Since all tool implementations must inherit from this base class, then implementing this method here avoids breaking subclasses that implemented the `DragTracker` interface.

#### createOperationSet

    protected java.util.List createOperationSet()

Returns a new List of editparts that this tool is operating on. This method is called once during `getOperationSet()`, and its result is cached.

By default, the operations set is the current viewer's entire selection. Subclasses may override this method to filter or alter the operation set as necessary.

Returns:
  a list of editparts being operated on

#### deactivate

    public void deactivate()

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`
See Also:
  `activate()`

#### debug

    protected void debug(java.lang.String message)

Deprecated.
Prints a string in the GEF Debug console if the Tools debug option is selected.

Parameters:
  `message` - a message for the debug trace tool

#### executeCommand

    protected void executeCommand(Command command)

Executes the given command on the command stack.

Parameters:
  `command` - the command to execute
Since:
  3.1

#### executeCurrentCommand

    protected void executeCurrentCommand()

Execute the currently active command.

#### focusGained

    public void focusGained(FocusEvent event,
                   EditPartViewer viewer)

Called when a viewer that the editor controls gains focus.

Specified by:
  `focusGained` in interface `Tool`
Parameters:
  `event` - The SWT focus event
  `viewer` - The viewer that the focus event is over.

#### focusLost

    public void focusLost(FocusEvent event,
                 EditPartViewer viewer)

Called when a viewer that the editor controls loses focus.

Specified by:
  `focusLost` in interface `Tool`
Parameters:
  `event` - The SWT focus event
  `viewer` - The viewer that the focus event is over.

#### getCommand

    protected Command getCommand()

Returns a new, updated command based on the tool's current properties. The default implementation returns an unexecutable command. Some tools do not work commands and the model, but simply change the viewer's state in some way.

Returns:
  a newly obtained command

#### getCommandName

    protected abstract java.lang.String getCommandName()

Returns the identifier of the command that is being sought. This name is also the named that will be logged in the debug view.

Returns:
  the identifier for the command

#### getCurrentCommand

    protected Command getCurrentCommand()

Returns the currently cached command.

Returns:
  the current command
See Also:
  `setCurrentCommand(Command)`

#### getCurrentInput

    protected AbstractTool.Input getCurrentInput()

Returns the input object encapsulating the current mouse and keyboard state.

Returns:
  the current input

#### getCurrentViewer

    protected EditPartViewer getCurrentViewer()

Return the viewer that the tool is currently receiving input from, or `null`. The last viewer to dispatch an event is defined as the current viewer. Current viewer is automatically updated as events are received, and is set to `null` on `deactivate()`.

Returns:
  the current viewer

#### getDebugName

    protected java.lang.String getDebugName()

Returns the debug name for this tool.

Returns:
  the debug name

#### getDebugNameForState

    protected java.lang.String getDebugNameForState(int state)

Returns a String representation of the given state for debug purposes.

Parameters:
  `state` - the state
Returns:
  the string for the given state

#### getDefaultCursor

    protected Cursor getDefaultCursor()

Returns the cursor used under normal conditions.

Returns:
  the default cursor
See Also:
  `setDefaultCursor(Cursor)`

#### getDisabledCursor

    protected Cursor getDisabledCursor()

Returns the cursor used under abnormal conditions.

Returns:
  the disabled cursor
See Also:
  `calculateCursor()`, `setDisabledCursor(Cursor)`

#### getDomain

    protected EditDomain getDomain()

Returns the EditDomain. A tool is told its EditDomain when it becomes active. A tool may need to know its edit domain prior to receiving any events from any of that domain's viewers.

Returns:
  the editdomain

#### getDragMoveDelta

    protected Dimension getDragMoveDelta()

Return the number of pixels that the mouse has been moved since that drag was started. The drag start is determined by where the mouse button was first pressed.

Returns:
  the drag delta
See Also:
  `getStartLocation()`

#### getLocation

    protected Point getLocation()

Returns the current x, y position of the mouse cursor.

Returns:
  the mouse location

#### getOperationSet

    protected java.util.List getOperationSet()

Lazily creates and returns the list of editparts on which the tool operates. The list is initially `null`, in which case `createOperationSet()` is called, and its results cached until the tool is deactivated.

Returns:
  the operation set.

#### getStartLocation

    protected Point getStartLocation()

Returns the starting mouse location for the current tool operation. This is typically the mouse location where the user first pressed a mouse button. This is important for tools that interpret mouse drags.

Returns:
  the start location

#### getState

    protected int getState()

Returns the tool's current state.

Returns:
  the current state

#### handleButtonDown

    protected boolean handleButtonDown(int button)

Called when the mouse button has been pressed. By default, nothing happens and `false` is returned. Subclasses may override this method to interpret the meaning of a mouse down. Returning `true` indicates that the button down was handled in some way.

Parameters:
  `button` - which button went down
Returns:
  `true` if the buttonDown was handled

#### handleButtonUp

    protected boolean handleButtonUp(int button)

Called when the mouse button has been released. By default, nothing happens and `false` is returned. Subclasses may override this method to interpret the mouse up. Returning `true` indicates that the mouse up was handled in some way.

Parameters:
  `button` - the button being released
Returns:
  `true` if the button up was handled
See Also:
  `mouseUp(MouseEvent, EditPartViewer)`

#### handleCommandStackChanged

    protected boolean handleCommandStackChanged()

Called when the command stack has changed, for instance, when a delete or undo command has been executed. By default, state is set to `STATE_INVALID` and handleInvalidInput is called. Subclasses may override this method to change what happens when the command stack changes. Returning `true` indicates that the change was handled in some way.

Returns:
  `true` if the change was handled in some way

#### handleDoubleClick

    protected boolean handleDoubleClick(int button)

Called when a mouse double-click occurs. By default, nothing happens and `false` is returned. Subclasses may override this method to interpret double-clicks. Returning `true` indicates that the event was handled in some way.

Parameters:
  `button` - which button was double-clicked
Returns:
  `true` if the event was handled
See Also:
  `mouseDoubleClick(MouseEvent, EditPartViewer)`

#### handleDrag

    protected boolean handleDrag()

Called whenever the mouse is being dragged. This method continues to be called even once `handleDragInProgress()` starts getting called. By default, nothing happens, and `false` is returned. Subclasses may override this method to interpret a drag. Returning `true` indicates that the drag was handled in some way.

Returns:
  `true` if the drag is handled
See Also:
  `mouseDrag(MouseEvent, EditPartViewer)`

#### handleDragInProgress

    protected boolean handleDragInProgress()

Called whenever a mouse is being dragged and the drag threshold has been exceeded. Prior to the drag threshold being exceeded, only `handleDrag()` is called. This method gets called repeatedly for every mouse move during the drag. By default, nothing happens and `false` is returned. Subclasses may override this method to interpret the drag. Returning `true` indicates that the drag was handled.

Returns:
  `true` if the drag was handled
See Also:
  `movedPastThreshold()`, `mouseDrag(MouseEvent, EditPartViewer)`

#### handleDragStarted

    protected boolean handleDragStarted()

Called only one time during a drag when the drag threshold has been exceeded. By default, nothing happens and `false` is returned. Subclasses may override to interpret the drag starting. Returning `true` indicates that the event was handled.

Returns:
  true if the drag starting was handled
See Also:
  `movedPastThreshold()`, `mouseDrag(MouseEvent, EditPartViewer)`

#### handleFinished

    protected void handleFinished()

Called when the current tool operation is to be completed. In other words, the "state machine" and has accepted the sequence of input (i.e. the mouse gesture). By default, the tool will either reactivate itself, or ask the edit domain to load the default tool.

Subclasses should extend this method to first do whatever it is that the tool does, and then call `super`.

See Also:
  `unloadWhenFinished()`

#### handleFocusGained

    protected boolean handleFocusGained()

Handles high-level processing of a focus gained event. By default, nothing happens and `false` is returned. Subclasses may override this method to interpret the focus gained event. Return `true` to indicate that the event was processed.

Returns:
  `true` if the event was handled
See Also:
  `focusGained(FocusEvent, EditPartViewer)`

#### handleFocusLost

    protected boolean handleFocusLost()

Handles high-level processing of a focus lost event. By default, nothing happens and `false` is returned. Subclasses may override this method to interpret the focus lost event. Return `true` to indicate that the event was processed.

Returns:
  `true` if the event was handled
See Also:
  `focusLost(FocusEvent, EditPartViewer)`

#### handleHover

    protected boolean handleHover()

Handles high-level processing of a mouse hover event. By default, nothing happens and `false` is returned. Subclasses may override this method to interpret the hover. Return `true` to indicate that the hover was handled.

Returns:
  `true` if the hover was handled
See Also:
  `mouseHover(MouseEvent, EditPartViewer)`

#### handleInvalidInput

    protected boolean handleInvalidInput()

Called when invalid input is encountered. The state does not change, so the caller must set the state to `STATE_INVALID`.

Returns:
  `true`

#### handleKeyDown

    protected boolean handleKeyDown(KeyEvent e)

Handles high-level processing of a key down event. By default, the KeyEvent is checked to see if it is the ESCAPE key. If so, the domain's default tool is reloaded, and `true` is returned. Subclasses may extend this method to interpret additional key down events. Returns `true` if the given key down was handled.

Parameters:
  `e` - the key event
Returns:
  `true` if the key down was handled.
See Also:
  `keyDown(KeyEvent, EditPartViewer)`

#### handleKeyTraversed

    protected void handleKeyTraversed(TraverseEvent event)

Override to process a traverse event. If the event's `doit` field is set to `false`, the traversal will be prevented from occurring. Otherwise, a traverse will occur.

Parameters:
  `event` - the SWT traverse event
Since:
  3.1

#### handleKeyUp

    protected boolean handleKeyUp(KeyEvent e)

Handles high-level processing of a key up event. By default, does nothing and returns `false`. Subclasses may extend this method to process key up events. Returns `true` if the key up was processed in some way.

Parameters:
  `e` - the key event
Returns:
  `true` if the event was handled
See Also:
  `keyUp(KeyEvent, EditPartViewer)`

#### handleMove

    protected boolean handleMove()

Handles high-level processing of a mouse move. By default, does nothing and returns `false`. Subclasses may extend this method to process mouse moves. Returns `true` if the mouse move was processed.

Returns:
  `true` if the mouse move was handled
See Also:
  `mouseMove(MouseEvent, EditPartViewer)`

#### handleNativeDragFinished

    protected boolean handleNativeDragFinished(DragSourceEvent event)

Handles when a native drag has ended. By default, does nothing and returns `false`. Subclasses may extend this method to process native drags ending.

Parameters:
  `event` - the drag event
Returns:
  `true` if the native drag finished was handled

#### handleNativeDragStarted

    protected boolean handleNativeDragStarted(DragSourceEvent event)

Handles when a native drag has started. By default, does nothing and returns `false`. Subclasses may extend this method to process native drag starts.

When a native drag starts, all subsequent mouse events will not be received, including the mouseUp event. The only event that will be received is the drag finished event.

Parameters:
  `event` - the drag event
Returns:
  `true` if the native drag start was handled

#### handleViewerEntered

    protected boolean handleViewerEntered()

Called when the mouse enters an EditPartViewer. By default, does nothing and returns `false`. Subclasses may extend this method to process the viewer enter. Returns `true` to indicate if the viewer entered was process in some way.

Returns:
  `true` if the viewer entered was handled

#### handleViewerExited

    protected boolean handleViewerExited()

Called when the mouse exits an EditPartViewer. By default, does nothing and returns `false`. Subclasses may extend this method to process viewer exits. Returns `true` to indicate if the viewer exited was process in some way.

Returns:
  `true` if the viewer exited was handled

#### isActive

    protected boolean isActive()

Returns `true` if the tool is active.

Returns:
  `true` if active

#### isHoverActive

    protected boolean isHoverActive()

Returns `true` if the tool is hovering.

Returns:
  `true` if hovering

#### isInState

    protected boolean isInState(int state)

Returns `true` if the tool is in the given state.

Parameters:
  `state` - the state being queried
Returns:
  `true` if the tool is in the given state

#### isViewerImportant

    protected boolean isViewerImportant(EditPartViewer viewer)

Default implementation always returns `true`. Sub-classes may override.

Parameters:
  `viewer` - the viewer where the event occured
Returns:
  `true` if this tool is interested in events occuring in the given viewer; `false` otherwise
Since:
  3.1

#### keyDown

    public void keyDown(KeyEvent evt,
               EditPartViewer viewer)

Receives a KeyDown event for the given viewer. Subclasses wanting to handle this event should override `handleKeyDown(KeyEvent)`.

Specified by:
  `keyDown` in interface `Tool`
Parameters:
  `evt` - the key event
  `viewer` - the originating viewer

#### keyTraversed

    public void keyTraversed(TraverseEvent event,
                    EditPartViewer viewer)

Receives a traversal event for the given viewer. Subclasses wanting to handle this event should override `handleKeyTraversed(TraverseEvent)`.

Specified by:
  `keyTraversed` in interface `Tool`
Parameters:
  `event` - the traverse event
  `viewer` - the originating viewer

#### keyUp

    public void keyUp(KeyEvent evt,
             EditPartViewer viewer)

Receives a KeyUp event for the given viewer. Subclasses wanting to handle this event should override `handleKeyUp(KeyEvent)`.

Specified by:
  `keyUp` in interface `Tool`
Parameters:
  `evt` - the key event
  `viewer` - the originating viewer

#### mouseDoubleClick

    public void mouseDoubleClick(MouseEvent me,
                        EditPartViewer viewer)

Handles mouse double click events within a viewer. Subclasses wanting to handle this event should override `handleDoubleClick(int)`.

Specified by:
  `mouseDoubleClick` in interface `Tool`
Parameters:
  `me` - the mouse event
  `viewer` - the originating viewer

#### mouseDown

    public void mouseDown(MouseEvent me,
                 EditPartViewer viewer)

Handles mouse down events within a viewer. Subclasses wanting to handle this event should override `handleButtonDown(int)`.

Specified by:
  `mouseDown` in interface `Tool`
Parameters:
  `me` - the mouse event
  `viewer` - the originating viewer

#### mouseDrag

    public void mouseDrag(MouseEvent me,
                 EditPartViewer viewer)

Handles mouse drag events within a viewer. Subclasses wanting to handle this event should override `handleDrag()` and/or `handleDragInProgress()`.

Specified by:
  `mouseDrag` in interface `Tool`
Parameters:
  `me` - the mouse event
  `viewer` - the originating viewer

#### mouseHover

    public void mouseHover(MouseEvent me,
                  EditPartViewer viewer)

Handles mouse hover event. within a viewer. Subclasses wanting to handle this event should override `handleHover()`.

Specified by:
  `mouseHover` in interface `Tool`
Parameters:
  `me` - the mouse event
  `viewer` - the originating viewer
See Also:
  `MouseTrackListener.mouseHover(MouseEvent)`

#### mouseMove

    public void mouseMove(MouseEvent me,
                 EditPartViewer viewer)

Handles mouse moves (if the mouse button is up) within a viewer. Subclasses wanting to handle this event should override `handleMove()`.

Specified by:
  `mouseMove` in interface `Tool`
Parameters:
  `me` - the mouse event
  `viewer` - the originating viewer
See Also:
  `Tool.mouseDrag(MouseEvent, EditPartViewer)`

#### mouseUp

    public void mouseUp(MouseEvent me,
               EditPartViewer viewer)

Handles mouse up within a viewer. Subclasses wanting to handle this event should override `handleButtonUp(int)`.

Specified by:
  `mouseUp` in interface `Tool`
Parameters:
  `me` - the mouse event
  `viewer` - the originating viewer

#### mouseWheelScrolled

    public void mouseWheelScrolled(Event event,
                          EditPartViewer viewer)

Handles mouse-wheel scrolling for a viewer. Sub-classes may override as needed. The default implementation delegates to `performViewerMouseWheel(Event, EditPartViewer)` IFF the tool is in the initial state. Mouse-wheel events generated at other times are ignored.

Specified by:
  `mouseWheelScrolled` in interface `Tool`
Parameters:
  `event` - the SWT scroll event
  `viewer` - the originating viewer
See Also:
  `performViewerMouseWheel(Event, EditPartViewer)`

#### movedPastThreshold

    protected boolean movedPastThreshold()

Returns `true` if the threshold has been exceeded during a mouse drag.

Returns:
  `true` if the threshold has been exceeded

#### nativeDragFinished

    public void nativeDragFinished(DragSourceEvent event,
                          EditPartViewer viewer)

Description copied from interface: `Tool`
Called when a native drag ends on a Viewer. This event is important to Tools because `mouseUp(..)` will not occur once a native drag has started. The Tool should correct its state to handle this lost Event.

Specified by:
  `nativeDragFinished` in interface `Tool`
Parameters:
  `event` - the SWT DragSourceEvent
  `viewer` - the Viewer on which a native drag started
See Also:
  `Tool.nativeDragFinished(DragSourceEvent, EditPartViewer)`

#### nativeDragStarted

    public void nativeDragStarted(DragSourceEvent event,
                         EditPartViewer viewer)

Description copied from interface: `Tool`
Called when a native drag begins on a Viewer. This event is important to Tools because `mouseUp(..)` will not occur once a native drag has started. The Tool should correct its state to handle this lost Event.

Specified by:
  `nativeDragStarted` in interface `Tool`
Parameters:
  `event` - the SWT DragSourceEvent
  `viewer` - the Viewer on which a native drag started
See Also:
  `Tool.nativeDragStarted(DragSourceEvent, EditPartViewer)`

#### performViewerMouseWheel

    protected void performViewerMouseWheel(Event event,
                               EditPartViewer viewer)

Delegates mouse-wheel event handling to registered `MouseWheelHandlers` based on the given Event's statemask. Does nothing if there are no matching handlers found.

Parameters:
  `event` - the SWT scroll event
  `viewer` - the originating viewer
Since:
  3.1

#### placeMouseInViewer

    protected void placeMouseInViewer(Point p)

Places the mouse in the viewer based on the point given. If the point given is outside the viewer, then the mouse is placed in the location nearest the given point but within the viewer.

Parameters:
  `p` - the point
Since:
  3.4

#### reactivate

    protected void reactivate()

Calls `deactivate()` and then `activate()`.

#### refreshCursor

    protected void refreshCursor()

Sets the cursor being displayed to the appropriate cursor. If the tool is active, the current cursor being displayed is updated by calling `calculateCursor()`.

#### releaseToolCapture

    protected void releaseToolCapture()

Releases tool capture.

See Also:
  `setToolCapture()`

#### removeFeedback

    protected void removeFeedback(IFigure figure)

Convenience method to removes a figure from the feedback layer.

Parameters:
  `figure` - the figure being removed

#### resetFlags

    protected void resetFlags()

Resets all stateful flags to their initial values. Subclasses should extend this method to reset their own custom flags.

#### setCurrentCommand

    protected void setCurrentCommand(Command c)

Used to cache a command obtained from `getCommand()`.

Parameters:
  `c` - the command
See Also:
  `getCurrentCommand()`

#### setCursor

    protected void setCursor(Cursor cursor)

Shows the given cursor on the current viewer.

Parameters:
  `cursor` - the cursor to display

#### setDefaultCursor

    public void setDefaultCursor(Cursor cursor)

Sets the default cursor.

Parameters:
  `cursor` - the cursor
See Also:
  `getDefaultCursor()`

#### setDisabledCursor

    public void setDisabledCursor(Cursor cursor)

Sets the disabled cursor.

Parameters:
  `cursor` - the cursor
See Also:
  `getDisabledCursor()`

#### setEditDomain

    public void setEditDomain(EditDomain domain)

Sets the EditDomain.

Specified by:
  `setEditDomain` in interface `Tool`
Parameters:
  `domain` - the edit domain
See Also:
  `getDomain()`

#### setHoverActive

    protected void setHoverActive(boolean value)

Sets whether the hover flag is true or false. Subclasses which do something on hover can use this flag to track whether they have received a hover or not.

Parameters:
  `value` - whether hover is active

#### setProperties

    public void setProperties(java.util.Map properties)

An example is `PROPERTY_UNLOAD_WHEN_FINISHED` -> Boolean. AbstractTool uses introspection to set properties that are not explicitly specified. For instance, the key "defaultCursor" will cause `setDefaultCursor(Cursor)` to be invoked with the given value.

Specified by:
  `setProperties` in interface `Tool`
Parameters:
  `properties` - a mapping of the properties to be set and their new values; can be `null`
See Also:
  `Tool.setProperties(java.util.Map)`

#### setStartLocation

    protected void setStartLocation(Point p)

Sets the start mouse location, typically for a drag operation.

Parameters:
  `p` - the start location

#### setState

    protected void setState(int state)

Sets the tools state.

Parameters:
  `state` - the new state

#### setToolCapture

    protected void setToolCapture()

Sets tool capture. When a tool has capture, viewers will make every effort to send events through the editdomain to the tool. Therefore, the default handling of some events is bypassed.

#### setUnloadWhenFinished

    public void setUnloadWhenFinished(boolean value)

Setting this to `true` will cause the tool to be unloaded after one operation has completed. The default value is `true` . The tool is unloaded, and the edit domains default tool will be activated.

Parameters:
  `value` - whether the tool should be unloaded on completion

#### setViewer

    public void setViewer(EditPartViewer viewer)

Sets the active EditPartViewer. The active viewer is the viewer from which the last event was received.

Specified by:
  `setViewer` in interface `Tool`
Parameters:
  `viewer` - the viewer

#### stateTransition

    protected boolean stateTransition(int start,
                          int end)

Returns `true` if the give state transition succeeds. This is a "test and set" operation, where the tool is tested to be in the specified start state, and if so, is set to the given end state. The method returns the result of the first test.

Parameters:
  `start` - the start state being tested
  `end` - the end state
Returns:
  `true` if the state transition is successful

#### unloadWhenFinished

    protected final boolean unloadWhenFinished()

Returns `true` if the tool is set to unload when its current operation is complete.

Returns:
  `true` if the tool should be unloaded when finished

#### viewerEntered

    public void viewerEntered(MouseEvent me,
                     EditPartViewer viewer)

Receives the mouse entered event. Subclasses wanting to handle this event should override `handleViewerEntered()`.

FEATURE in SWT: mouseExit comes after mouseEntered on the new control. Therefore, if the current viewer is not `null`, it means the exit has not been sent yet by SWT. To maintain proper ordering, GEF fakes the exit and calls `handleViewerExited()`. The real exit will then be ignored.

Specified by:
  `viewerEntered` in interface `Tool`
Parameters:
  `me` - the mouse event
  `viewer` - the originating viewer

#### viewerExited

    public void viewerExited(MouseEvent me,
                    EditPartViewer viewer)

Handles the mouse exited event. Subclasses wanting to handle this event should override `handleViewerExited()`.

Specified by:
  `viewerExited` in interface `Tool`
Parameters:
  `me` - the mouse event
  `viewer` - the originating viewer