/*******************************************************************************
* Copyright (c) 2000, 2010, 2012 IBM Corporation, Gerhardt Informatics Kft. and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
* Gerhardt Informatics Kft. - GEFGWT port
*******************************************************************************/
package org.eclipse.gef;
import java.util.Map;
import org.eclipse.swt.dnd.DragSourceEvent;
import org.eclipse.swt.events.FocusEvent;
import org.eclipse.swt.events.KeyEvent;
import org.eclipse.swt.events.MouseEvent;
import org.eclipse.swt.events.MouseTrackListener;
import org.eclipse.swt.events.TraverseEvent;
import org.eclipse.swt.widgets.Event;
/**
* A <code>Tool</code> interprets Mouse and Keyboard input from an
* {@link EditDomain} and its {@link EditPartViewer EditPartViewers}. The active
* Tool and its state determines how the EditDomain will interpret input. Input
* flows from a Viewer, to the EditDomain, to the EditDomain's active Tool.
* <P>
* <code>Tools</code> process low-level events and turn them into higher-level
* operations. These operations are encapsulated by {@link Request Requests}.
* The Requests are then used to communicate with EditParts in the Viewer to
* perform the User's operation. Using Requests, Tools will:
* <UL>
* <LI>Ask EditParts for {@link org.eclipse.gef.commands.Command Commands} to
* perform changes on the model.
* <LI>Ask EditParts to show and erase feedback during an operation.
* <LI>Ask EditParts to perform a generic function, using
* {@link org.eclipse.gef.EditPart#performRequest(Request)}.
* <P>
* Tools also perform operations that do not involve the EditParts directly,
* such as changing the Viewer's selection, scrolling the viewer, or invoking an
* {@link org.eclipse.jface.action.IAction Action}.
* <table>
* <tr>
* <td valign=top><img src="doc-files/important.gif"/>
* <td>All feedback should be erased and temporary changes reverted prior to
* executing any command.
* </tr>
* <tr>
* <td valign=top><img src="doc-files/important.gif"/>
* <td>Tools should process most keystrokes. For example, the DELETE key should
* <EM>not</EM> be handled by adding a KeyListener to the Viewer's Control.
* Doing so would mean that pressing DELETE would <EM>not</EM> be sensitive to
* which Tool is currently active, and the state of the Tool. See
* {@link org.eclipse.gef.KeyHandler} for how keystrokes are generally
* processed.
* </tr>
* </table>
* <p>
* IMPORTANT: This interface is <EM>not</EM> intended to be implemented by
* clients. Clients should inherit from
* {@link org.eclipse.gef.tools.AbstractTool}. New methods may be added in the
* future.
*/
public interface Tool {
/**
* Called when this tool becomes the active tool for the EditDomain.
* implementors can perform any necessary initialization here.
*
* @see #deactivate()
*/
void activate();
/**
* Called when another Tool becomes the active tool for the EditDomain.
* implementors can perform state clean-up or to free resources.
*/
void deactivate();
/**
* Called when a Viewer's Control gains keyboard focus.
*
* @param event
* The SWT focus event
* @param viewer
* The Viewer which gained focus
*/
void focusGained(FocusEvent event, EditPartViewer viewer);
/**
* Called when a Viewer's Control loses keyboard focus.
*
* @param event
* The SWT focus event
* @param viewer
* The viewer that is losing focus
*/
void focusLost(FocusEvent event, EditPartViewer viewer);
/**
* Called when a Viewer receives a key press.
*
* @param keyEvent
* the SWT KeyEvent
* @param viewer
* the Viewer which received a key press
*/
void keyDown(KeyEvent keyEvent, EditPartViewer viewer);
/**
* Called when a viewer receives a key traversal. A tool can prevent the
* traversal from occuring by setting the doit field to <code>false</code>.
*
* @param event
* the SWT event
* @param viewer
* the viewer which received the traversal
* @since 3.1
*/
void keyTraversed(TraverseEvent event, EditPartViewer viewer);
/**
* Called when a Viewer receives a key up.
*
* @param keyEvent
* the SWT KeyEvent
* @param viewer
* the Viewer which received a key up
*/
void keyUp(KeyEvent keyEvent, EditPartViewer viewer);
/**
* Called when a Viewer receives a double-click.
*
* @param mouseEvent
* the SWT mouse event
* @param viewer
* the Viewer which received a double-click
*/
void mouseDoubleClick(MouseEvent mouseEvent, EditPartViewer viewer);
/**
* Called when a Viewer receives a mouse down.
*
* @param mouseEvent
* the SWT mouse event
* @param viewer
* the Viewer which received a mouse down
*/
void mouseDown(MouseEvent mouseEvent, EditPartViewer viewer);
/**
* Called when a Viewer receives a mouse drag. SWT does not distinguish
* between mouse drags and mouse moves, but GEF Viewers will make this
* distinction when dispatching events. A drag occurs if any mouse button is
* down.
*
* @param mouseEvent
* the SWT mouse event
* @param viewer
* the Viewer which received a drag
*/
void mouseDrag(MouseEvent mouseEvent, EditPartViewer viewer);
/**
* Called when a Viewer receives a mouse hover.
*
* @see MouseTrackListener#mouseHover(MouseEvent)
* @param mouseEvent
* the SWT mouse event
* @param viewer
* the Viewer which received a mouse down
*/
void mouseHover(MouseEvent mouseEvent, EditPartViewer viewer);
/**
* Called when a Viewer receives a mouse move.
*
* @see #mouseDrag(MouseEvent, EditPartViewer)
* @param mouseEvent
* the SWT mouse event
* @param viewer
* the Viewer which received a mouse move
*/
void mouseMove(MouseEvent mouseEvent, EditPartViewer viewer);
/**
* Called when a Viewer receives a mouse up.
*
* @param mouseEvent
* the SWT mouse event
* @param viewer
* the Viewer which received a mouse up
*/
void mouseUp(MouseEvent mouseEvent, EditPartViewer viewer);
/**
* Called when the mouse wheel has been scrolled.
*
* @param event
* The SWT event
* @param viewer
* The source of the event
*/
void mouseWheelScrolled(Event event, EditPartViewer viewer);
/**
* Called when a native drag ends on a Viewer. This event is important to
* Tools because {@link #mouseUp(MouseEvent, EditPartViewer) mouseUp(..)}
* will not occur once a native drag has started. The Tool should correct
* its state to handle this lost Event.
*
* @param event
* the SWT DragSourceEvent
* @param viewer
* the Viewer on which a native drag started
*/
void nativeDragFinished(DragSourceEvent event, EditPartViewer viewer);
/**
* Called when a native drag begins on a Viewer. This event is important to
* Tools because {@link #mouseUp(MouseEvent, EditPartViewer) mouseUp(..)}
* will not occur once a native drag has started. The Tool should correct
* its state to handle this lost Event.
*
* @param event
* the SWT DragSourceEvent
* @param viewer
* the Viewer on which a native drag started
*/
void nativeDragStarted(DragSourceEvent event, EditPartViewer viewer);
/**
* Called to set the EditDomain for this Tool. This is called right before
* {@link #activate()}.
*
* @param domain
* The EditDomain to which this Tool belongs
*/
void setEditDomain(EditDomain domain);
/**
* Called to set the current Viewer receiving events. This method is rarely
* called, since the Viewer is always passed along with the events
* themselves. This method really just applies to {@link DragTracker
* DragTrackers}.
*
* @param viewer
* The current Viewer
*/
void setViewer(EditPartViewer viewer);
/**
* Called when a Viewer receives a mouse enter.
*
* @param mouseEvent
* the SWT mouse event
* @param viewer
* the Viewer which received a mouse enter
*/
void viewerEntered(MouseEvent mouseEvent, EditPartViewer viewer);
/**
* Called when a Viewer receives a mouse exit.
*
* @param mouseEvent
* the SWT mouse event
* @param viewer
* the Viewer which received a mouse exit
*/
void viewerExited(MouseEvent mouseEvent, EditPartViewer viewer);
/**
* This method can be invoked to set any properties of this tool. This
* allows clients who do not have direct access to a Tool to still be able
* to configure that tool. The given Map should have the property's key and
* value. This method will ignore unrecognized keys and values that are not
* of the expected type.
* <p>
* This method should only be invoked once when the tool is first
* constructed and is being initialized. Invoking this method at other times
* may have undesired effects.
*
* @param properties
* a mapping of the properties to be set and their new values;
* can be <code>null</code>
* @since 3.1
*/
void setProperties(Map properties);
}