Eclipse GEF
2.1

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

Default implementation support for Tools.


Nested Class Summary
static class AbstractTool.Input
          Allows the user to access mouse and keyboard input.
 
Field Summary
protected static int MAX_FLAG
           
protected static int MAX_STATE
           
protected static int MOUSE_BUTTON_ANY
           
protected static int MOUSE_BUTTON1
           
protected static int MOUSE_BUTTON2
           
protected static int MOUSE_BUTTON3
           
protected static int STATE_ACCESSIBLE_DRAG
           
protected static int STATE_ACCESSIBLE_DRAG_IN_PROGRESS
           
protected static int STATE_DRAG
           
protected static int STATE_DRAG_IN_PROGRESS
           
protected static int STATE_INITIAL
           
protected static int STATE_INVALID
           
protected static int STATE_TERMINAL
           
 
Fields inherited from interface org.eclipse.gef.RequestConstants
REQ_ADD, REQ_ALIGN, REQ_ALIGN_CHILDREN, 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
AbstractTool()
           
 
Method Summary
 void activate()
          Activates the tool.
protected  void addFeedback(org.eclipse.draw2d.IFigure figure)
          Adds the given figure to the feedback layer.
protected  Cursor calculateCursor()
          Determines (and returns) the appropriate cursur.
 void commitDrag()
           
protected  List createOperationSet()
          Creates and returns a List of EditParts that the tool will be working with.
 void deactivate()
          Deactivates the tool.
protected  void debug(String message)
          Prints a string in the GEF Debug console if the Tools debug option is selected.
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()
          Re-queries the target viewer object for a command
protected abstract  String getCommandName()
          Returns the name identifier of the command that the tool is currently looking for.
protected  Command getCurrentCommand()
          Returns the currently active command.
protected  AbstractTool.Input getCurrentInput()
          Returns the current mouse and keyboard input.
protected  EditPartViewer getCurrentViewer()
          Return the viewer that the tool is currently operating on.
protected abstract  String getDebugName()
          Returns the debug name for this tool.
protected  String getDebugNameForState(int state)
          Returns a String representation of the given state for debug purposes.
protected  Cursor getDefaultCursor()
          Returns the default Cursor.
protected  Cursor getDisabledCursor()
          Returns the disabled Cursor.
protected  EditDomain getDomain()
          Returns the EditDomain.
protected  org.eclipse.draw2d.geometry.Dimension getDragMoveDelta()
          Return the number of pixels that the mouse has been moved since that drag was started.
protected  org.eclipse.draw2d.geometry.Point getLocation()
          Return the current x, y position of the cursor.
protected  List getOperationSet()
          Returns the collection of editparts that the drag is operating on.
protected  org.eclipse.draw2d.geometry.Point getStartLocation()
          Returns the starting location for the current tool operation.
protected  int getState()
          Returns the current state.
protected  boolean handleButtonDown(int button)
          Called when the mouse button has been pressed.
protected  boolean handleButtonUp(int button)
          Handles the high-level processing of a mouse release.
protected  boolean handleDoubleClick(int button)
          Handles high-level processing of a double click.
protected  boolean handleDrag()
          Handles high-level processing of a mouse drag.
protected  boolean handleDragInProgress()
          Handles high-level processing of a mouse drag once the threshold has been passed.
protected  boolean handleDragStarted()
          Called once when the drag threshold has been passed.
protected  void handleFinished()
          Called when the current tool operation is complete.
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 handleKeyDown(KeyEvent e)
          Handles high-level processing of a key down 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)
           
protected  boolean handleNativeDragStarted(DragSourceEvent event)
           
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.
 void keyDown(KeyEvent evt, EditPartViewer viewer)
          Processes a KeyDown event for the given viewer.
 void keyUp(KeyEvent evt, EditPartViewer viewer)
          Processes 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.
protected  boolean movedPastThreshold()
          Returns true if the mouse has been dragged past the drag threshold.
 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 reactivate()
          Deactivates and then activates this tool.
protected  void refreshCursor()
          Selects the appropriate cursor.
protected  void releaseToolCapture()
          Releases capture.
protected  void removeFeedback(org.eclipse.draw2d.IFigure figure)
          Removes the given figure from the feedback layer.
protected  void resetFlags()
          Resets the flags.
protected  void setCurrentCommand(Command c)
          Sets the current command.
protected  void setCursor(Cursor cursor)
          Set the cursor on the argument to the not cursor Record the fact we have altered the cursor of this viewer so that when we are deactivated we can go back and set it to normal
 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 the hover flag to true.
protected  void setStartLocation(org.eclipse.draw2d.geometry.Point p)
           
protected  void setState(int state)
          Sets the tool state.
protected  void setToolCapture()
          By setting capture on mouseDown, a tool can prevent native Drag operations from occuring.
 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)
          This method attempts to transistion the tool from state start to state end and returns true if successful.
protected  boolean unloadWhenFinished()
          Returns true if the tool is set to unload when its current operation is complete.
 void viewerEntered(MouseEvent me, EditPartViewer viewer)
          Handles the mouse entering a viewer.
 void viewerExited(MouseEvent me, EditPartViewer viewer)
          Handles the mouse exiting a viewer.
 
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

STATE_TERMINAL

protected static final int STATE_TERMINAL
See Also:
Constant Field Values

STATE_INITIAL

protected static final int STATE_INITIAL
See Also:
Constant Field Values

STATE_DRAG

protected static final int STATE_DRAG
See Also:
Constant Field Values

STATE_DRAG_IN_PROGRESS

protected static final int STATE_DRAG_IN_PROGRESS
See Also:
Constant Field Values

STATE_INVALID

protected static final int STATE_INVALID
See Also:
Constant Field Values

STATE_ACCESSIBLE_DRAG

protected static final int STATE_ACCESSIBLE_DRAG
See Also:
Constant Field Values

STATE_ACCESSIBLE_DRAG_IN_PROGRESS

protected static final int STATE_ACCESSIBLE_DRAG_IN_PROGRESS
See Also:
Constant Field Values

MAX_STATE

protected static final int MAX_STATE
See Also:
Constant Field Values

MOUSE_BUTTON1

protected static final int MOUSE_BUTTON1
See Also:
Constant Field Values

MOUSE_BUTTON2

protected static final int MOUSE_BUTTON2
See Also:
Constant Field Values

MOUSE_BUTTON3

protected static final int MOUSE_BUTTON3
See Also:
Constant Field Values

MOUSE_BUTTON_ANY

protected static final int MOUSE_BUTTON_ANY
See Also:
Constant Field Values

MAX_FLAG

protected static final int MAX_FLAG
See Also:
Constant Field Values
Constructor Detail

AbstractTool

public AbstractTool()
Method Detail

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(org.eclipse.draw2d.IFigure figure)
Adds the given figure to the feedback layer.


calculateCursor

protected Cursor calculateCursor()
Determines (and returns) the appropriate cursur.


commitDrag

public void commitDrag()

createOperationSet

protected List createOperationSet()
Creates and returns a List of EditParts that the tool will be working with.


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(String message)
Prints a string in the GEF Debug console if the Tools debug option is selected.


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.

executeCurrentCommand

protected void executeCurrentCommand()
Execute the currently active command.


getCommand

protected Command getCommand()
Re-queries the target viewer object for a command


getCommandName

protected abstract String getCommandName()
Returns the name identifier of the command that the tool is currently looking for.


getCurrentCommand

protected Command getCurrentCommand()
Returns the currently active command.


getCurrentInput

protected AbstractTool.Input getCurrentInput()
Returns the current mouse and keyboard input.


getCurrentViewer

protected EditPartViewer getCurrentViewer()
Return the viewer that the tool is currently operating on.


getDebugName

protected abstract String getDebugName()
Returns the debug name for this tool.


getDebugNameForState

protected String getDebugNameForState(int state)
Returns a String representation of the given state for debug purposes.


getDefaultCursor

protected Cursor getDefaultCursor()
Returns the default Cursor.


getDisabledCursor

protected Cursor getDisabledCursor()
Returns the disabled Cursor.


getDomain

protected EditDomain getDomain()
Returns the EditDomain.


getDragMoveDelta

protected org.eclipse.draw2d.geometry.Dimension getDragMoveDelta()
Return the number of pixels that the mouse has been moved since that drag was started.


getLocation

protected org.eclipse.draw2d.geometry.Point getLocation()
Return the current x, y position of the cursor.


getOperationSet

protected List getOperationSet()
Returns the collection of editparts that the drag is operating on.


getStartLocation

protected org.eclipse.draw2d.geometry.Point getStartLocation()
Returns the starting location for the current tool operation.


getState

protected int getState()
Returns the current state.


handleButtonDown

protected boolean handleButtonDown(int button)
Called when the mouse button has been pressed. Should be implemented to process the users input correctly. Boolean should be used to indicate to your subclasses if you processed the event (true) or you didn't process it (false) and the subclass might process it. Key presses are a good example of this type of behavior.


handleButtonUp

protected boolean handleButtonUp(int button)
Handles the high-level processing of a mouse release.

See Also:
mouseUp(MouseEvent, EditPartViewer)

handleDoubleClick

protected boolean handleDoubleClick(int button)
Handles high-level processing of a double click.

See Also:
mouseDoubleClick(MouseEvent, EditPartViewer)

handleDrag

protected boolean handleDrag()
Handles high-level processing of a mouse drag.

See Also:
mouseDrag(MouseEvent, EditPartViewer)

handleDragInProgress

protected boolean handleDragInProgress()
Handles high-level processing of a mouse drag once the threshold has been passed.

See Also:
movedPastThreshold(), mouseDrag(MouseEvent, EditPartViewer)

handleDragStarted

protected boolean handleDragStarted()
Called once when the drag threshold has been passed.

See Also:
movedPastThreshold(), mouseDrag(MouseEvent, EditPartViewer)

handleFinished

protected void handleFinished()
Called when the current tool operation is complete.


handleFocusGained

protected boolean handleFocusGained()
Handles high-level processing of a focus gained event.

See Also:
focusGained(FocusEvent, EditPartViewer)

handleFocusLost

protected boolean handleFocusLost()
Handles high-level processing of a focus lost event.

See Also:
focusLost(FocusEvent, EditPartViewer)

handleHover

protected boolean handleHover()
Handles high-level processing of a mouse hover event.

See Also:
mouseHover(MouseEvent, EditPartViewer)

handleKeyDown

protected boolean handleKeyDown(KeyEvent e)
Handles high-level processing of a key down event.

See Also:
keyDown(KeyEvent, EditPartViewer)

handleKeyUp

protected boolean handleKeyUp(KeyEvent e)
Handles high-level processing of a key up event.

See Also:
keyUp(KeyEvent, EditPartViewer)

handleMove

protected boolean handleMove()
Handles high-level processing of a mouse move.

See Also:
mouseMove(MouseEvent, EditPartViewer)

handleNativeDragFinished

protected boolean handleNativeDragFinished(DragSourceEvent event)

handleNativeDragStarted

protected boolean handleNativeDragStarted(DragSourceEvent event)

handleViewerEntered

protected boolean handleViewerEntered()
Called when the mouse enters an EditPartViewer.


handleViewerExited

protected boolean handleViewerExited()
Called when the mouse exits an EditPartViewer.


isActive

protected boolean isActive()
Returns true if the tool is active.


isHoverActive

protected boolean isHoverActive()
Returns true if the tool is hovering.


isInState

protected boolean isInState(int state)
Returns true if the tool is in the given state.


keyDown

public void keyDown(KeyEvent evt,
                    EditPartViewer viewer)
Processes 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 SWT KeyEvent
viewer - the Viewer which received a key press

keyUp

public void keyUp(KeyEvent evt,
                  EditPartViewer viewer)
Processes 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 SWT KeyEvent
viewer - the Viewer which received a key up

movedPastThreshold

protected boolean movedPastThreshold()
Returns true if the mouse has been dragged past the drag threshold.


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.nativeDragStarted(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)

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 SWT mouse event
viewer - the Viewer which received a double-click

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 SWT mouse event
viewer - the Viewer which received a mouse down

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 SWT mouse event
viewer - the Viewer which received a drag

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 SWT mouse event
viewer - the Viewer which received a mouse down
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 SWT mouse event
viewer - the Viewer which received a mouse move
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 SWT mouse event
viewer - the Viewer which received a mouse up

reactivate

protected void reactivate()
Deactivates and then activates this tool.


refreshCursor

protected void refreshCursor()
Selects the appropriate cursor.

See Also:
calculateCursor()

releaseToolCapture

protected void releaseToolCapture()
Releases capture.

See Also:
setToolCapture()

removeFeedback

protected void removeFeedback(org.eclipse.draw2d.IFigure figure)
Removes the given figure from the feedback layer.


resetFlags

protected void resetFlags()
Resets the flags.


setCurrentCommand

protected void setCurrentCommand(Command c)
Sets the current command.


setCursor

protected void setCursor(Cursor cursor)
Set the cursor on the argument to the not cursor Record the fact we have altered the cursor of this viewer so that when we are deactivated we can go back and set it to normal


setDefaultCursor

public void setDefaultCursor(Cursor cursor)
Sets the default cursor.


setDisabledCursor

public void setDisabledCursor(Cursor cursor)
Sets the disabled cursor.


setEditDomain

public void setEditDomain(EditDomain domain)
Sets the EditDomain.

Specified by:
setEditDomain in interface Tool
Parameters:
domain - The EditDomain to which this Tool belongs

setHoverActive

protected void setHoverActive(boolean value)
Sets the hover flag to true.


setStartLocation

protected void setStartLocation(org.eclipse.draw2d.geometry.Point p)

setState

protected void setState(int state)
Sets the tool state.


setToolCapture

protected void setToolCapture()
By setting capture on mouseDown, a tool can prevent native Drag operations from occuring. releaseToolCapture() must be called when capture is no longer needed.


setUnloadWhenFinished

public void setUnloadWhenFinished(boolean value)
Setting this to true will cause the tool to be unloaded after one operation has completed.


setViewer

public void setViewer(EditPartViewer viewer)
Sets the active EditPartViewer.

Specified by:
setViewer in interface Tool
Parameters:
viewer - The current Viewer

stateTransition

protected boolean stateTransition(int start,
                                  int end)
This method attempts to transistion the tool from state start to state end and returns true if successful. If the tool is not in state start, the tool remains in its current state and false is returned to indicate the failure.


unloadWhenFinished

protected final boolean unloadWhenFinished()
Returns true if the tool is set to unload when its current operation is complete.


viewerEntered

public void viewerEntered(MouseEvent me,
                          EditPartViewer viewer)
Handles the mouse entering a viewer. Subclasses wanting to handle this event should override handleViewerEntered().

FEATURE in SWT: mouseExit comes after mouseEntered. 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 SWT mouse event
viewer - the Viewer which received a mouse enter

viewerExited

public void viewerExited(MouseEvent me,
                         EditPartViewer viewer)
Handles the mouse exiting a viewer. Subclasses wanting to handle this event should override handleViewerExited().

Specified by:
viewerExited in interface Tool
Parameters:
me - the SWT mouse event
viewer - the Viewer which received a mouse exit

Eclipse GEF
2.1

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