/*
 * @(#)Tool.java 5.1
 *
 */

package de.renew.draw.ui.ontology;

import java.awt.Graphics;
import java.awt.event.KeyEvent;
import java.awt.event.MouseEvent;

/**
 * A tool defines a mode of the drawing view. All input events
 * targeted to the drawing view are forwarded to its current tool.
 * <p>
 * Tools inform their editor when they are done with an interaction
 * by calling the editor's toolDone() method.
 * The Tools are created once and reused. They
 * are initialized/deinitialized with activate()/deactivate().
 * <hr>
 * <b>Design Patterns</b><P>
 * <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
 * <b><a href=../pattlets/sld032.htm>State</a></b><br>
 * Tool plays the role of the State. It encapsulates all state-specific behavior.
 * {@link DrawingView} plays the role of the StateContext.
 */
public interface Tool {

    /**
     * Activates the tool for the given view. This method is called
     * whenever the user switches to this tool. Use this method to
     * reinitialize a tool.
     */
    void activate();

    /**
     * Deactivates the tool. This method is called whenever the user
     * switches to another tool. Use this method to do some cleanup
     * when the tool is switched. Subclassers should always call
     * super.deactivate.
     */
    void deactivate();

    /**
     * Handles mouse down events in the drawing view.
     *
     * @param e the MouseEvent to be processed
     * @param x the horizontal axis
     * @param y the vertical axis
     */
    void mouseDown(MouseEvent e, int x, int y);

    /**
     * Handles mouse drag events in the drawing view.
     *
     * @param e the MouseEvent to be processed
     * @param x the horizontal axis
     * @param y the vertical axis
     */
    void mouseDrag(MouseEvent e, int x, int y);

    /**
     * Handles mouse up in the drawing view.
     *
     * @param e the MouseEvent to be processed
     * @param x the horizontal axis
     * @param y the vertical axis
     */
    void mouseUp(MouseEvent e, int x, int y);

    /**
     * Handles clean-up whenever the user
     * cancels a tool before completion.
     */
    void cancel();

    /**
     * Handles mouse moves (if the mouse button is up).
     *
     * @param evt the MouseEvent to be processed
     * @param x   the horizontal axis
     * @param y   the vertical axis
     */
    void mouseMove(MouseEvent evt, int x, int y);

    /**
     * Handles key down events in the drawing view.
     *
     * @param evt the KeyEvent to be processed
     * @param key the keycode of the pressed key
     */
    void keyDown(KeyEvent evt, int key);

    /**
     * Updates the graphical visualization of the tool.
     * <p>
     * If the tool gives visual feedback by drawing additional
     * things onto the drawing without using normal figures, it
     * may refresh the graphics in this method. This is needed
     * because an AWT repaint event can occur concurrently to the
     * operation of the tool and the tool's graphical visualization
     * would be hidden by the repainted figures.
     * </p>
     * Currently, there is only one known tool that doesn't use
     * usual figures to give visual feedback: the area tracker of
     * the selection tool.
     *
     * @param g the graphics context to use for drawing
     **/
    void draw(Graphics g);
}