skrueger.geotools
Class MouseSelectionTracker

java.lang.Object
  extended by java.awt.event.MouseAdapter
      extended by javax.swing.event.MouseInputAdapter
          extended by skrueger.geotools.MouseSelectionTracker
All Implemented Interfaces:
MouseListener, MouseMotionListener, MouseWheelListener, EventListener, MouseInputListener
Direct Known Subclasses:
MouseSelectionTracker

public abstract class MouseSelectionTracker
extends MouseInputAdapter

Controller which allows the user to select a region of a component. The user must click on a point in the component, then drag the mouse pointer whilst keeping the button pressed. During the dragging, the shape which is drawn will normally be a rectangle. Other shapes could always be used such as, for example, an ellipse. To use this class, it is necessary to create a derived class which defines the following methods:

This controller should then be registered with one, and only one, component using the following syntax:
 Component component=...
 MouseSelectionTracker control=...
 component.addMouseListener(control);
 

Since:
2.0
Version:
$Id: MouseSelectionTracker.java 22482 2006-10-31 02:58:00Z desruisseaux $
Author:
Martin Desruisseaux

Constructor Summary
MouseSelectionTracker()
          Constructs an object which will allow rectangular regions to be selected using the mouse.
 
Method Summary
protected  Shape getModel(MouseEvent event)
          Returns the geometric shape to use for marking the boundaries of a region.
 Shape getSelectedArea(AffineTransform transform)
          Returns the geometric shape surrounding the last region to be selected by the user.
 void mouseDragged(MouseEvent event)
          Informs this controller that the mouse has been dragged.
 void mouseMoved(MouseEvent event)
          Informs this controller that the mouse has been moved but not as a result of the user selecting a region.
 void mousePressed(MouseEvent event)
          Informs this controller that the mouse button has been pressed.
 void mouseReleased(MouseEvent event)
          Informs this controller that the mouse button has been released.
protected abstract  void selectionPerformed(int ox, int oy, int px, int py)
          Method which is automatically called after the user selects a region with the mouse.
 void setXORColors(Color a, Color b)
          Specifies the colours to be used for drawing the outline of a box when the user selects a region.
 
Methods inherited from class java.awt.event.MouseAdapter
mouseClicked, mouseEntered, mouseExited, mouseWheelMoved
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface java.awt.event.MouseListener
mouseClicked, mouseEntered, mouseExited
 

Constructor Detail

MouseSelectionTracker

public MouseSelectionTracker()
Constructs an object which will allow rectangular regions to be selected using the mouse.

Method Detail

setXORColors

public void setXORColors(Color a,
                         Color b)
Specifies the colours to be used for drawing the outline of a box when the user selects a region. All a colours will be replaced by b colours and vice versa.


getModel

protected Shape getModel(MouseEvent event)
Returns the geometric shape to use for marking the boundaries of a region. This shape is normally a rectangle but could also be an ellipse, an arrow or even other shapes. The coordinates of the returned shape will not be taken into account. In fact, these coordinates will regularly be discarded. Only the class of the returned shape will count (for example, Ellipse2D vs Rectangle2D) and their parameters which are not linked to their position (for example, the rounding of a rectangle's corners).

The shape returned will normally be from a class derived from RectangularShape, but could also be from the Line2D class. Any other class risks throwing a ClassCastException when executed. The default implementation always returns an object Rectangle.

Parameters:
event - Mouse coordinate when the button is pressed. This information can be used by the derived classes which like to be informed of the position of the mouse before chosing a geometric shape.
Returns:
Shape from the class {link RectangularShape} or {link Line2D}, or null to indicate that we do not want to make a selection.

selectionPerformed

protected abstract void selectionPerformed(int ox,
                                           int oy,
                                           int px,
                                           int py)
Method which is automatically called after the user selects a region with the mouse. All coordinates passed in as parameters are expressed in pixels.

Parameters:
ox - x coordinate of the mouse when the user pressed the mouse button.
oy - y coordinate of the mouse when the user pressed the mouse button.
px - x coordinate of the mouse when the user released the mouse button.
py - y coordinate of the mouse when the user released the mouse button.

getSelectedArea

public Shape getSelectedArea(AffineTransform transform)
                      throws NoninvertibleTransformException
Returns the geometric shape surrounding the last region to be selected by the user. An optional affine transform can be specified to convert the region selected by the user into logical coordinates. The class of the shape returned depends on the model returned by getModel(java.awt.event.MouseEvent):

Parameters:
transform - Affine transform which converts logical coordinates into pixel coordinates. It is usually an affine transform which is used in a paint(...) method to draw shapes expressed in logical coordinates.
Returns:
A geometric shape enclosing the last region to be selected by the user, or null if no selection has yet been made.
Throws:
NoninvertibleTransformException - If the affine transform can't be inverted.

mousePressed

public void mousePressed(MouseEvent event)
                  throws ClassCastException
Informs this controller that the mouse button has been pressed. The default implementation retains the mouse coordinate (which will become one of the corners of the future rectangle to be drawn) and prepares this to observe the mouse movements.

Specified by:
mousePressed in interface MouseListener
Overrides:
mousePressed in class MouseAdapter
Throws:
ClassCastException - if getModel(java.awt.event.MouseEvent) doesn't return a shape from the class {link RectangularShape} or {link Line2D}.

mouseDragged

public void mouseDragged(MouseEvent event)
Informs this controller that the mouse has been dragged. The default implementation uses this to move a corner of the rectangle used to select the region. The other corner remains fixed at the point where the mouse was at the moment its button was pressed..

Specified by:
mouseDragged in interface MouseMotionListener
Overrides:
mouseDragged in class MouseAdapter

mouseReleased

public void mouseReleased(MouseEvent event)
Informs this controller that the mouse button has been released. The default implementation calls selectionPerformed(int, int, int, int) with the bounds of the selected region as parameters.

Specified by:
mouseReleased in interface MouseListener
Overrides:
mouseReleased in class MouseAdapter

mouseMoved

public void mouseMoved(MouseEvent event)
Informs this controller that the mouse has been moved but not as a result of the user selecting a region. The default implementation signals to the source component that this is no longer interested in being informed about mouse movements.

Specified by:
mouseMoved in interface MouseMotionListener
Overrides:
mouseMoved in class MouseAdapter