org.gicentre.utils.move
Class ZoomPan

java.lang.Object
  extended by org.gicentre.utils.move.ZoomPan

public class ZoomPan
extends java.lang.Object

Class to allow interactive zooming and panning of the Processing display. To use, simply create a ZoomPan object in setup(), then call its transform() method at the start of draw(). Panning is controlled with the right mouse button dragging. Zooming is, by default, controlled with a left mouse drag up to zoom in, left-drag down to zoom out. Can also zoom in and out with the mouse wheel if present. Mouse actions can be filtered so that they only work if a modifier key is pressed (ALT, SHIFT or CONTROL) by calling the setMouseMask() method.

Version:
3.0, 10th August, 2010.
Author:
Jo Wood, giCentre, City University London.

Constructor Summary
ZoomPan(processing.core.PApplet aContext)
          Initialises the zooming and panning transformations for the given applet context.
ZoomPan(processing.core.PApplet aContext, processing.core.PGraphics graphics)
          Initialises the zooming and panning transformations for the given applet and graphics contexts.
 
Method Summary
 void addZoomPanListener(ZoomPanListener zoomPanListener)
          Adds a listener to be informed when some zooming or panning has finished.
 processing.core.PVector getCoordToDisp(processing.core.PVector p)
          Transforms the given point from coordinate to display space.
 processing.core.PVector getDispToCoord(processing.core.PVector p)
          Transforms the given point from display to coordinate space.
 processing.core.PVector getMouseCoord()
          Reports the current mouse position in coordinate space.
 double getZoomScale()
          Reports the current zoom scale.
 boolean isMouseCaptured()
          Reports whether a mouse event has been captured by the zoomer.
 boolean isPanning()
          Reports whether display is currently being panned (ie mouse is being dragged with pan key/button pressed).
 boolean isZooming()
          Reports whether display is currently being zoomed (ie mouse is being dragged with zoom key/button pressed).
 void mouseEvent(java.awt.event.MouseEvent e)
          Updates zoom and pan transformation according to mouse activity.
 boolean removeZoomPanListener(ZoomPanListener zoomPanListener)
          Removes the given listener from those to be informed when zooming/panning has finished.
 void reset()
          Resets the display to unzoomed and unpanned position.
 void setMouseMask(int mouseMask)
          Sets the key that must be pressed before mouse actions are active.
 void setZoomMouseButton(int zoomMouseButton)
          Sets mouse buttons for zooming and implies that the other mouse button will be for panning.
 void transform()
          Performs the zooming/panning transformation.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ZoomPan

public ZoomPan(processing.core.PApplet aContext)
Initialises the zooming and panning transformations for the given applet context. Can be used to have independent zooming in multiple windows by creating multiple objects each with a different PApplet object.

Parameters:
aContext - Applet context in which zooming and panning are to take place.

ZoomPan

public ZoomPan(processing.core.PApplet aContext,
               processing.core.PGraphics graphics)
Initialises the zooming and panning transformations for the given applet and graphics contexts. This version of the constructor allows a graphics context separate from the applet to be applied so that buffered off-screen drawing can be applied.

Parameters:
aContext - Applet context in which zooming and panning are to take place.
graphics - Graphics context in which to draw.
Method Detail

transform

public void transform()
Performs the zooming/panning transformation. This method must be called at the start of the draw() method.


reset

public void reset()
Resets the display to unzoomed and unpanned position.


addZoomPanListener

public void addZoomPanListener(ZoomPanListener zoomPanListener)
Adds a listener to be informed when some zooming or panning has finished.

Parameters:
zoomPanListener - Listener to be informed when some zooming or panning has finished.

removeZoomPanListener

public boolean removeZoomPanListener(ZoomPanListener zoomPanListener)
Removes the given listener from those to be informed when zooming/panning has finished.

Parameters:
zoomPanListener - Listener to remove.
Returns:
True if listener found and removed.

setMouseMask

public void setMouseMask(int mouseMask)
Sets the key that must be pressed before mouse actions are active. By default, no key is needed for the mouse to be active. Specifying a value allows normal mouse actions to be intercepted without zooming or panning. To set the mouse mask to no key, specify a mouseMask value of 0. Mouse actions can be disabled entirely by setting the mouseMask to a negative value.

Parameters:
mouseMask - Keyboard modifier required to activate mouse actions. Valid values are CONTROL, SHIFT, ALT, 0 and -1.

getMouseCoord

public processing.core.PVector getMouseCoord()
Reports the current mouse position in coordinate space. This method should be used in preference to mouseX and mouseY if the current display has been zoomed or panned.

Returns:
Coordinates of current mouse position accounting for any zooming or panning.

getZoomScale

public double getZoomScale()
Reports the current zoom scale. Can be used for drawing objects that maintain their size when zooming.

Returns:
Current zoom scale.

isZooming

public boolean isZooming()
Reports whether display is currently being zoomed (ie mouse is being dragged with zoom key/button pressed).

Returns:
True if display is being actively zoomed.

isPanning

public boolean isPanning()
Reports whether display is currently being panned (ie mouse is being dragged with pan key/button pressed).

Returns:
True if display is being actively panned.

isMouseCaptured

public boolean isMouseCaptured()
Reports whether a mouse event has been captured by the zoomer. This allows zoom and pan events to be separated from other mouse actions. Usually only useful if the zoomer uses some mouse mask.

Returns:
True if mouse event has been captured by the zoomer.

mouseEvent

public void mouseEvent(java.awt.event.MouseEvent e)
Updates zoom and pan transformation according to mouse activity.

Parameters:
e - Mouse event.

getDispToCoord

public processing.core.PVector getDispToCoord(processing.core.PVector p)
Transforms the given point from display to coordinate space. Display space is that which has been subjected to zooming and panning. Coordinate space is the original space into which objects have been placed before zooming and panning. For most drawing operations you should not need to use this method. It is available for those operations that do not draw directly, but need to know the transformation between coordinate and screen space.

Parameters:
p - 2D point in zoomed display space.
Returns:
Location of point in original coordinate space.

getCoordToDisp

public processing.core.PVector getCoordToDisp(processing.core.PVector p)
Transforms the given point from coordinate to display space. Display space is that which has been subjected to zooming and panning. Coordinate space is the original space into which objects have been placed before zooming and panning. For most drawing operations you should not need to use this method. It is available for those operations that do not draw directly, but need to know the transformation between coordinate and screen space.

Parameters:
p - 2D point in original coordinate space.
Returns:
Location of point in zoomed display space.

setZoomMouseButton

public void setZoomMouseButton(int zoomMouseButton)
Sets mouse buttons for zooming and implies that the other mouse button will be for panning.

Parameters:
zoomMouseButton - Zoom mouse button (must be either PConstants.LEFT or PConstants.RIGHT)


gicentreUtils V.3.0, API documentation generated 13th August, 2010