edu.umd.cs.piccolo.event
Class PDragSequenceEventHandler

java.lang.Object
  edu.umd.cs.piccolo.event.PBasicInputEventHandler
      edu.umd.cs.piccolo.event.PDragSequenceEventHandler

All Implemented Interfaces:

PInputEventListener, EventListener

Direct Known Subclasses:

PDragEventHandler, PPanEventHandler, PZoomEventHandler

public abstract class PDragSequenceEventHandler
extends PBasicInputEventHandler

PDragSequenceEventHandler is designed to support mouse pressed, dragged, and released interaction sequences. Support is also provided for running a continuous activity during the drag sequence.

PDragSequenceEventHandler should be subclassed by a concrete event handler that implements a particular interaction. See PPanEventHandler, PZoomEventHandler, and PDragEventHandler for examples.

Version:

1.0

Author:

Jesse Grosjean

Constructor Summary

PDragSequenceEventHandler()
Constructs a drag sequence event handler instance.

Method Summary

protected void	drag(PInputEvent event) Subclasses should override this method to get notified of the drag events in a drag sequence.
protected void	dragActivityFinalStep(PInputEvent aEvent) Subclasses should override this method to get notified when the drag activity stops stepping.
protected void	dragActivityFirstStep(PInputEvent event) Subclasses override this method to get notified when the drag activity starts stepping.
protected void	dragActivityStep(PInputEvent event) During a drag sequence an activity is scheduled that runs continuously while the drag sequence is active.
protected void	endDrag(PInputEvent event) Subclasses should override this method to get notified of the end event in a drag sequence.
protected PActivity	getDragActivity() Returns the scheduled activity that's updating the scene as a result to the current drag activity (if any).
double	getMinDragStartDistance() Returns the minimum distance (in screen coordinates) before a pressed mouse movement is registered as a drag event.
Point2D	getMousePressedCanvasPoint() Return the point in canvas coordinates where the mouse was last pressed.
boolean	isDragging() Returns true if this event handler is in the process of handling a drag.
void	mouseDragged(PInputEvent event) Subclasses should not override this method, instead they should override the appropriate drag method.
void	mousePressed(PInputEvent event) Subclasses should not override this method, instead they should override the appropriate drag callbacks.
void	mouseReleased(PInputEvent event) Subclasses should not override this method, instead they should override the appropriate drag method.
void	setIsDragging(boolean isDragging) Used to inform this handler that it is in the process of handling a drag.
void	setMinDragStartDistance(double minDistance) Set the minimum distance that the mouse should be dragged (in screen coordinates) before a new drag sequence is initiate.
protected boolean	shouldStartDragInteraction(PInputEvent event) Returns true if the provided event represents a valid start for a drag sequence.
protected void	startDrag(PInputEvent event) Subclasses should override this method to get notified of the start of a new drag sequence.
protected void	startDragActivity(PInputEvent event) Schedules the "infinite" drag activity so that auto-panning and zooming will continue to update the scene even if there are no further drag events fired.
protected void	stopDragActivity(PInputEvent event) Stops the activity responsible for updating the scene.

Methods inherited from class edu.umd.cs.piccolo.event.PBasicInputEventHandler

acceptsEvent, getEventFilter, keyboardFocusGained, keyboardFocusLost, keyPressed, keyReleased, keyTyped, mouseClicked, mouseEntered, mouseExited, mouseMoved, mouseWheelRotated, mouseWheelRotatedByBlock, paramString, processEvent, setEventFilter

Methods inherited from class java.lang.Object

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

Constructor Detail

PDragSequenceEventHandler

public PDragSequenceEventHandler()

Constructs a drag sequence event handler instance.

Method Detail

isDragging

public boolean isDragging()

Returns true if this event handler is in the process of handling a drag.

Returns:

true if handling a drag

setIsDragging

public void setIsDragging(boolean isDragging)

Used to inform this handler that it is in the process of handling a drag.

Parameters:

isDragging - true if handler is processing a drag

getMinDragStartDistance

public double getMinDragStartDistance()

Returns the minimum distance (in screen coordinates) before a pressed mouse movement is registered as a drag event. The smaller this value the more clicks will be incorrectly recognized as drag events.

Returns:

minimum distance a pressed mouse must move before it is registered as a drag

setMinDragStartDistance

public void setMinDragStartDistance(double minDistance)

Set the minimum distance that the mouse should be dragged (in screen coordinates) before a new drag sequence is initiate.

Parameters:

minDistance - in screen coordinates

getMousePressedCanvasPoint

public Point2D getMousePressedCanvasPoint()

Return the point in canvas coordinates where the mouse was last pressed.

Returns:

point in canvas coordinates of last mouse press

startDrag

protected void startDrag(PInputEvent event)

Subclasses should override this method to get notified of the start of a new drag sequence. Note that that overriding methods must still call super.startDrag() for correct behavior.

Parameters:

event - event that started the drag sequence

drag

protected void drag(PInputEvent event)

Subclasses should override this method to get notified of the drag events in a drag sequence. Note that that overriding methods must still call super.startDrag() for correct behavior.

Parameters:

event - event that caused the drag

endDrag

protected void endDrag(PInputEvent event)

Subclasses should override this method to get notified of the end event in a drag sequence. Note that that overriding methods must still call super.startDrag() for correct behavior.

Parameters:

event - event that ended the drag sequence

shouldStartDragInteraction

protected boolean shouldStartDragInteraction(PInputEvent event)

Returns true if the provided event represents a valid start for a drag sequence. Subclasses should override this method to add criteria for the start of a drag sequence. Subclasses are still responsible for calling super.shouldStartDragInteraction()

Parameters:

event - event being tested

Returns:

true if provided event is a good start to a drag sequence

getDragActivity

protected PActivity getDragActivity()

Returns the scheduled activity that's updating the scene as a result to the current drag activity (if any).

Returns:

scheduled activity that's updating the scene as a result to the drag activity

startDragActivity

protected void startDragActivity(PInputEvent event)

Schedules the "infinite" drag activity so that auto-panning and zooming will continue to update the scene even if there are no further drag events fired. For example, if the mouse is dragged to the right while pressing the right mouse button and then paused for a while, the scene should continue to zoom in.

Parameters:

event - the event that's responsible for the start of the activity

stopDragActivity

protected void stopDragActivity(PInputEvent event)

Stops the activity responsible for updating the scene.

Parameters:

event - The event responsible for stopping the drag activity

dragActivityFirstStep

protected void dragActivityFirstStep(PInputEvent event)

Subclasses override this method to get notified when the drag activity starts stepping.

Parameters:

event - the event responsible for the first step in the drag activity

dragActivityStep

protected void dragActivityStep(PInputEvent event)

During a drag sequence an activity is scheduled that runs continuously while the drag sequence is active. This can be used to support some additional behavior that is not driven directly by mouse events. For example PZoomEventHandler uses it for zooming and PPanEventHandler uses it for auto panning.

Parameters:

event - the event encapsulating the callback context for the activity step

dragActivityFinalStep

protected void dragActivityFinalStep(PInputEvent aEvent)

Subclasses should override this method to get notified when the drag activity stops stepping.

Parameters:

aEvent - the event responsible for ending the activity

mousePressed

public void mousePressed(PInputEvent event)

Subclasses should not override this method, instead they should override the appropriate drag callbacks.

Overrides:

mousePressed in class PBasicInputEventHandler

Parameters:

event - The event to be queried about the details of the mouse press

mouseDragged

public void mouseDragged(PInputEvent event)

Subclasses should not override this method, instead they should override the appropriate drag method.

Overrides:

mouseDragged in class PBasicInputEventHandler

Parameters:

event - The event to be queried about the details of the mouse press

mouseReleased

public void mouseReleased(PInputEvent event)

Subclasses should not override this method, instead they should override the appropriate drag method.

Overrides:

mouseReleased in class PBasicInputEventHandler

Parameters:

event - The event to be queried about the details of the mouse release