edu.umd.cs.jazz.event
Class ZDragSequenceEventHandler

java.lang.Object
  |
  +--edu.umd.cs.jazz.event.ZFilteredEventHandler
        |
        +--edu.umd.cs.jazz.event.ZDragSequenceEventHandler

All Implemented Interfaces:

ZEventHandler

Direct Known Subclasses:

ZHandleEventHandler, ZoomEventHandler, ZPanEventHandler, ZSelectionModifyHandler, ZSelectionMoveHandler

public class ZDragSequenceEventHandler

extends ZFilteredEventHandler

ZDragSequenceEventHandler is designed to support drag sequence interactions normally consisting of filtered mouse pressed, filtered mouse dragged, and filtered mouse released events. This class doesn't do anything useful on its own but it helps to support drag sequences in the event handlers that subclass it.

ZDragSequenceEventHandler works by setting up three template methods;

• protected void startDrag(ZMouseEvent e)
• protected void drag(ZMouseEvent e)
• protected void dragInScreenCoords(ZMouseEvent e, Dimension2D aScreenDelta)
• protected void endDrag(ZMouseEvent e)

Event handlers that use drag sequences in their interactions should override these template methods and invoke the appropriate behavior from within those methods.

Using this class to implement your drag sequences increases flexibility in a number of ways. Since this class removes the coupling between filtered mouse down events and startDrag it's fairly easy for someone to subclass your event handler and map the drag sequence to a different set of filtered mouse events instead of the standard filtered mouse pressed, filtered mouse dragged, filtered mouse released sequence.

This class also supports the notion of a minimum drag start distance. That is the distance that the mouse must be dragged before the drag sequence will start.

Author:

Jesse Grosjean

ZDragSequenceEventHandler

public ZDragSequenceEventHandler(ZSceneGraphObject aFilteredMouseEventSource)

Constructs a new ZDragSequenceEventHandler.

Parameters:

aFilteredMouseEventSource - the source for filtered ZMouseEvents and ZMouseMotionEvents. See the ZFilteredEventHandler class comment to customize this behavior.

ZDragSequenceEventHandler

public ZDragSequenceEventHandler(ZSceneGraphObject aFilteredMouseEventSource,
                                 ZCanvas aFilteredKeyEventSouce)

Constructs a new ZDragSequenceEventHandler.

Parameters:

aFilteredMouseEventSource - the source for filtered ZMouseEvents and ZMouseMotionEvents. See the ZFilteredEventHandler class comment to customize this behavior.

aFilteredKeyEventSouce - the source for filtered KeyEvents. See the ZFilteredEventHandler class comment to customize this behavior.

filteredMousePressed

protected void filteredMousePressed(ZMouseEvent e)

Maps filtered mouse pressed onto the startDrag method if a drag interaction should be started as determined by shouldStartDragInteraction.

Overrides:

filteredMousePressed in class ZFilteredEventHandler

Parameters:

e - the filtered mouse pressed event.

filteredMouseDragged

protected void filteredMouseDragged(ZMouseEvent e)

Maps filtered mouse dragged onto the drag method if a drag sequence is in progress. Or maps it onto the startDrag method if a drag sequence is not in progress but should be started as determined by shouldStartDragInteraction.

Overrides:

filteredMouseDragged in class ZFilteredEventHandler

Parameters:

e - the filtered mouse dragged event.

filteredMouseReleased

protected void filteredMouseReleased(ZMouseEvent e)

Maps filtered mouse released onto the endDrag method if a drag sequence was in progress when the mouse was released. If a drag sequence was not in progress endDrag will not be called.

Overrides:

filteredMouseReleased in class ZFilteredEventHandler

Parameters:

e - the filtered mouse released event.

startDrag

protected void startDrag(ZMouseEvent e)

This method is called when a drag sequence is started. Subclasses that need to know about this should override this method, but also must call super.startDrag since this method sets up the drag sequence state. This method sets the current drawing surface to interacting mode.

Parameters:

e - the event starting the drag sequence.

drag

protected void drag(ZMouseEvent e)

This method is called during a drag sequence. Its default implementation is to figure out the current distance that the mouse has moved and then call dragInScreenCoords with this information. It also updates the current screen delta, and last screen point values.

Parameters:

e - the event causing the drag.

dragInScreenCoords

protected void dragInScreenCoords(ZMouseEvent e,
                                  java.awt.geom.Dimension2D aScreenDelta)

This method is called by drag during at a drag sequence. It can be more useful to override this method then drag since the screen delta is provided for you. The screen delta parameter in this method is the same object as the one returned by getScreenDelta. So if you modify this object (such as transform from one coord system to another) the object returned from getScreenDelta will also be modified. But for most event handlers its still ok to modify it since the screen delta object is refreshed on each new event.

Parameters:

e - the event causing the drag.

aScreenDelta - the change in mouse position between the current and last filtered mouse events.

endDrag

protected void endDrag(ZMouseEvent e)

This method is called at the end of a drag sequence. This method sets the current drawing surface to not interacting mode.

Parameters:

e - the event causing the end of the drag sequence.

shouldStartDragInteraction

protected boolean shouldStartDragInteraction(ZMouseEvent e)

Invoked to determine if a drag interaction should be started. The normal behavior is to determine if the mouse has moved the getMinDragStartDistance from the getMousePressedScreenPoint.

Parameters:

e - the event containing the current filtered mouse position.

Returns:

true if a drag sequence should be started.

isDragging

public boolean isDragging()

Returns true if the event handler is currently dragging.

Returns:

true if the event handler is dragging.

setIsDragging

protected void setIsDragging(boolean aBoolean)

Set to true if the event handler is currently dragging. This will normaly only be used internaly.

Parameters:

aBoolean - true if the event handler is dragging..

getMinDragStartDistance

public double getMinDragStartDistance()

Return the distance in screen coords that the mouse needs to move before a drag sequence will be started.

Returns:

the minimum distance that mouse must be dragged for a drag sequence to start.

setMinDragStartDistance

public void setMinDragStartDistance(double aDouble)

Set the distance (in screen coords) that the mouse needs to move before a drag sequence is started.

getMousePressedScreenPoint

public java.awt.geom.Point2D getMousePressedScreenPoint()

Return the point in screen coords where the mouse was pressed.

Returns:

the mouse press point in screen coords.

getDragStartScreenPoint

public java.awt.geom.Point2D getDragStartScreenPoint()

Return the point in screen coords where the drag sequence started. This will normally be the same as the mouse pressed screen point, but is not set until the drag sequence is started.

Returns:

the point where the drag sequence started in screen coords.

getPreviousScreenPoint

public java.awt.geom.Point2D getPreviousScreenPoint()

Returns the screen location of the previous filtered mouse event.

Returns:

the previous filtered mouse position in screen coords.

getCurrentScreenPoint

public java.awt.geom.Point2D getCurrentScreenPoint()

Returns the screen point of the current filtered mouse event.

Returns:

the current filtered mouse position in screen coords.

getCurrentScreenDelta

public java.awt.geom.Dimension2D getCurrentScreenDelta()

Returns the current distance that the mouse has moved between the current and previous filtered mouse events in screen coords. This returns the same object that is passed as a paramater into dragInScreenCoords so if you modify (changing from screen to local coords for example) that object it will also be modified when you access it here. But is its value is refreshed on each new call to drag so it is normally safe to modify it if you event handler only accesses it once per event.