/*******************************************************************************
 * Copyright (c) 2000, 2005 IBM Corporation 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
 *******************************************************************************/
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);

}