vmm.core
Class MouseTask

java.lang.Object
  vmm.core.MouseTask

Direct Known Subclasses:

BasicMouseTask2D, BasicMouseTask3D, TwoPointInput

public abstract class MouseTask
extends java.lang.Object

A MouseTask can be installed in a Display to respond to a mouse gesture starting from a mouse press, through a sequence of mouse drags, and ending with a mouse release. It has access to the mouse events and to the Display object and View objects that were clicked, and through the View object, it has access to the Exhibit in the View.

See Also:

Display.installMouseTask(MouseTask)

Constructor Summary

MouseTask()

Method Summary

abstract boolean	doMouseDown(java.awt.event.MouseEvent evt, Display display, View view, int width, int height) Called when the user presses the mouse in the Display in which this MouseTask is installed.
void	doMouseDrag(java.awt.event.MouseEvent evt, Display display, View view, int width, int height) Continue processing a mouse gesture for which doMouseDown returned a value of true.
void	doMouseUp(java.awt.event.MouseEvent evt, Display display, View view, int width, int height) Finish processing a mouse gesture for which doMouseDown returned a value of true.
void	drawWhileDragging(java.awt.Graphics2D g, Display display, View view, int width, int height) When the Display is repainted during a drag operation, this method will be called after the Exhibit is drawn, to give the MouseTask a chance to draw some extra stuff on top of the Exhibit.
void	finish(Display display, View view) This method is called by a Display when this MouseTask is removed from the Display, to give the MouseTask a chance to do any display-specific clean-up (such as removing a decoration).
java.awt.Cursor	getCursor(Display display, View view) Return a cursor to be used in the display when this MouseTask is installed and waiting for a mouse-down event.
java.awt.Cursor	getCursorForDragging(java.awt.event.MouseEvent mouseDownEvent, Display display, View view) When doMouseDown returns true, the Display class calls this method to determine which cursor to use during dragging.
java.lang.String	getStatusText() Returns a string to be displayed in the status bar while this mouse task is active, or null to use the default text.
void	start(Display display, View view) This method is called by a Display when this MouseTask is installed in the Display, to give the MouseTask a chance to do any display-specific initialization (such as adding a decoration).
boolean	wantsMoreClicks(Display display, View view) This method is called by a Display immediately after processing a click or click-and-drag for a one-shot mouse task to test whether the one-shot mouse task wants to receive additional mouse events.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MouseTask

public MouseTask()

Method Detail

doMouseDown

public abstract boolean doMouseDown(java.awt.event.MouseEvent evt,
                                    Display display,
                                    View view,
                                    int width,
                                    int height)

Called when the user presses the mouse in the Display in which this MouseTask is installed. The return value indicates whether or not the MouseTask wants to recieve the mouse drag and mouse up events that follow the mouse down event. If the return value is false, then the Display will not call the other two methods. This is an abstract method that must be redefined in a subclass. It should not be necessary to call this method directly.

Parameters:

evt - The mouse-down event, except that the x and y coordinates have been translated so that the top left corner of the View is at coordinates (0,0).

width - The width the drawing area (not including any insets).

height - The height the drawing area (not including any insets).

doMouseDrag

public void doMouseDrag(java.awt.event.MouseEvent evt,
                        Display display,
                        View view,
                        int width,
                        int height)

Continue processing a mouse gesture for which doMouseDown returned a value of true. If not redefined in a subclass, this method does nothing.

Parameters:

evt - The mouse-dragged event, except that the x and y coordinates have been translated by display.getInsets().left and display.getInsets().top to account for any border that has been applied to the display.

width - The width the drawing area (not including any insets).

height - The height the drawing area (not including any insets).

doMouseUp

public void doMouseUp(java.awt.event.MouseEvent evt,
                      Display display,
                      View view,
                      int width,
                      int height)

Finish processing a mouse gesture for which doMouseDown returned a value of true. If not redefined in a subclass, does nothing.

Parameters:

evt - The mouse-up event, except that the x and y coordinates have been translated by display.getInsets().left and display.getInsets().top to account for any border that has been applied to the display.

width - The width the drawing area (not including any insets).

height - The height the drawing area (not including any insets).

start

public void start(Display display,
                  View view)

This method is called by a Display when this MouseTask is installed in the Display, to give the MouseTask a chance to do any display-specific initialization (such as adding a decoration). The default, as defined in this class, is to do nothing; subclasses can override this behavior if necessary. It should not be necessary to call this method directly.

finish

public void finish(Display display,
                   View view)

This method is called by a Display when this MouseTask is removed from the Display, to give the MouseTask a chance to do any display-specific clean-up (such as removing a decoration). The default, as defined in this class, is to do nothing; subclasses can override this behavior if necessary. It should not be necessary to call this method directly.

getCursor

public java.awt.Cursor getCursor(Display display,
                                 View view)

Return a cursor to be used in the display when this MouseTask is installed and waiting for a mouse-down event. If the return value is null, the default cursor will be used. If not redefined in a subclass, returns null.

See Also:

getCursorForDragging(MouseEvent, Display, View)

getCursorForDragging

public java.awt.Cursor getCursorForDragging(java.awt.event.MouseEvent mouseDownEvent,
                                            Display display,
                                            View view)

When doMouseDown returns true, the Display class calls this method to determine which cursor to use during dragging. The first parameter is the same mouseDownEvent that was passed to doMouseDown; it can can be used to decide the appropriate cursor. The version in this class simply returns "getCursor(display)". Override it if you want the possibility of using a different cursor during dragging.

See Also:

doMouseDown(MouseEvent, Display, View, int, int), getCursor(Display, View)

drawWhileDragging

public void drawWhileDragging(java.awt.Graphics2D g,
                              Display display,
                              View view,
                              int width,
                              int height)

When the Display is repainted during a drag operation, this method will be called after the Exhibit is drawn, to give the MouseTask a chance to draw some extra stuff on top of the Exhibit. The graphics context is a newly created one, which has been translated and clipped, if necessary, to account for any border that has been applied to the Display. The width and height parameters give the width and height of the drawing area, in pixels.

wantsMoreClicks

public boolean wantsMoreClicks(Display display,
                               View view)

This method is called by a Display immediately after processing a click or click-and-drag for a one-shot mouse task to test whether the one-shot mouse task wants to receive additional mouse events. This method is called only for one-shot mouse tasks. It will probably be fairly unusual for this to occur; however, some one-shot mouse tasks might need two or more clicks to do their jobs. If this method returns true, the Display will call this MouseTask's getCursor method immediately after calling this method; a one-shot MouseTask that processes more than one click could use a distinctive cursor to help the user know what is going on, and it should consider setting the status bar text to tell the user what is going on.

Returns:

returns false, in the top-level MouseTask class.

See Also:

Display.installOneShotMouseTask(MouseTask), getStatusText()

getStatusText

public java.lang.String getStatusText()

Returns a string to be displayed in the status bar while this mouse task is active, or null to use the default text.

Returns:

returns null to indicate that the default status text is to be used. For a one-shot mouse task, the default message is "Waiting for mouse input" (in the English version). For a default mouse task, the default message is set by the view.