edu.umd.cs.piccolo.util
Class PPickPath

java.lang.Object
  edu.umd.cs.piccolo.util.PPickPath

All Implemented Interfaces:

PInputEventListener, EventListener

public class PPickPath
extends Object
implements PInputEventListener

PPickPath represents a ordered list of nodes that have been picked. The topmost ancestor node is the first node in the list (and should be a camera), the bottommost child node is at the end of the list. It is this bottom node that is given first chance to handle events, and that any active event handlers usually manipulate.

Note that because of layers (which can be picked by multiple camera's) the ordered list of nodes in a pick path do not all share a parent child relationship with the nodes in the list next to them. This means that the normal localToGlobal methods don't work when trying to transform geometry up and down the pick path, instead you should use the pick paths canvasToLocal methods to get the mouse event points into your local coord system.

Note that PInputEvent wraps most of the useful PPickPath methods, so often you can use a PInputEvent directly instead of having to access its pick path.

Version:

1.0

Author:

Jesse Grosjean

See Also:

PInputEvent

Field Summary

static PPickPath

CURRENT_PICK_PATH Global pick path.

Constructor Summary

PPickPath(PCamera camera, PBounds aScreenPickBounds)
Creates a pick pack originating from the provided camera and with the given screen pick bounds.

Method Summary

boolean	acceptsNode(PNode node) Determines if the passed node has been excluded from being a member of the pickpath.
Dimension2D	canvasToLocal(Dimension2D canvasDimension, PNode nodeOnPath) Convert the given dimension from the canvas coordinates, down through the pick path (and through any camera view transforms applied to the path) to the local coordinates of the given node.
Point2D	canvasToLocal(Point2D canvasPoint, PNode nodeOnPath) Convert the given point from the canvas coordinates, down through the pick path (and through any camera view transforms applied to the path) to the local coordinates of the given node.
Rectangle2D	canvasToLocal(Rectangle2D canvasRectangle, PNode nodeOnPath) Convert the given rectangle from the canvas coordinates, down through the pick path (and through any camera view transforms applied to the path) to the local coordinates of the given node.
PCamera	getBottomCamera() Get the bottom camera on the pick path.
PStack	getNodeStackReference() Returns a reference to the node stack.
PAffineTransform	getPathTransformTo(PNode nodeOnPath) Calculates the context at which the given node is being interacted with.
PBounds	getPickBounds() Returns the bounds of the entire PickPath taken as a whole.
PNode	getPickedNode() Get the bottom node on the pick path node stack.
double	getScale() Returns the resulting scale of applying the transforms of the entire pick path.
PCamera	getTopCamera() Get the top camera on the pick path.
PNode	nextPickedNode() Return the next node that will be picked after the current picked node.
void	popNode(PNode node) Removes the topmost node from the node stack.
void	popTransform(PAffineTransform transform) Pops the top most transform from the pick path.
void	processEvent(PInputEvent event, int eventType) Process Events - Give each node in the pick path, starting at the bottom most one, a chance to handle the event.
void	pushNode(PNode node) Pushes the provided node to the top of the pick path.
void	pushTransform(PAffineTransform transform) Adds the transform to the pick path's transform.

Methods inherited from class java.lang.Object

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

Field Detail

CURRENT_PICK_PATH

public static PPickPath CURRENT_PICK_PATH

Global pick path.

Constructor Detail

PPickPath

public PPickPath(PCamera camera,
                 PBounds aScreenPickBounds)

Creates a pick pack originating from the provided camera and with the given screen pick bounds.

Parameters:

camera - camera from which the pickpath originates

aScreenPickBounds - bounds of pick area

Method Detail

getPickBounds

public PBounds getPickBounds()

Returns the bounds of the entire PickPath taken as a whole.

Returns:

bounds of the entire PickPath

acceptsNode

public boolean acceptsNode(PNode node)

Determines if the passed node has been excluded from being a member of the pickpath.

Parameters:

node - node being tested

Returns:

true if node is acceptable to the path

pushNode

public void pushNode(PNode node)

Pushes the provided node to the top of the pick path.

Parameters:

node - node to be added to the pick path

popNode

public void popNode(PNode node)

Removes the topmost node from the node stack.

Parameters:

node - completely unused in this method, but is passed in so that subclasses may be informed of it.

getPickedNode

public PNode getPickedNode()

Get the bottom node on the pick path node stack. That is the last node to be picked.

Returns:

the bottom node on the pick path

nextPickedNode

public PNode nextPickedNode()

Return the next node that will be picked after the current picked node. For instance of you have two overlapping children nodes then the topmost child will always be picked first, use this method to find the covered child. Return the camera when no more visual will be picked.

Returns:

next node to picked after the picked node

getTopCamera

public PCamera getTopCamera()

Get the top camera on the pick path. This is the camera that originated the pick action.

Returns:

the topmost camera of this pick pack

getBottomCamera

public PCamera getBottomCamera()

Get the bottom camera on the pick path. This may be different then the top camera if internal cameras are in use.

Returns:

the camera closest to the picked node

getNodeStackReference

public PStack getNodeStackReference()

Returns a reference to the node stack. Be Careful!

Returns:

the node stack

getScale

public double getScale()

Returns the resulting scale of applying the transforms of the entire pick path. In essence it gives you the scale at which interaction is occurring.

Returns:

scale at which interaction is occurring.

pushTransform

public void pushTransform(PAffineTransform transform)

Adds the transform to the pick path's transform. This is used when determining the context of the current interaction.

Parameters:

transform - transform to be added to applied to the pickpath.

popTransform

public void popTransform(PAffineTransform transform)

Pops the top most transform from the pick path.

Parameters:

transform - unused in this method

getPathTransformTo

public PAffineTransform getPathTransformTo(PNode nodeOnPath)

Calculates the context at which the given node is being interacted with.

Parameters:

nodeOnPath - a node currently on the pick path. An exception will be thrown if the node cannot be found.

Returns:

Transform at which the given node is being interacted with.

processEvent

public void processEvent(PInputEvent event,
                         int eventType)

Process Events - Give each node in the pick path, starting at the bottom most one, a chance to handle the event.

Specified by:

processEvent in interface PInputEventListener

Parameters:

event - event to be processed

eventType - the type of event being processed

canvasToLocal

public Point2D canvasToLocal(Point2D canvasPoint,
                             PNode nodeOnPath)

Convert the given point from the canvas coordinates, down through the pick path (and through any camera view transforms applied to the path) to the local coordinates of the given node.

Parameters:

canvasPoint - point to be transformed

nodeOnPath - node into which the point is to be transformed iteratively through the pick path

Returns:

transformed canvasPoint in local coordinates of the picked node

canvasToLocal

public Dimension2D canvasToLocal(Dimension2D canvasDimension,
                                 PNode nodeOnPath)

Convert the given dimension from the canvas coordinates, down through the pick path (and through any camera view transforms applied to the path) to the local coordinates of the given node.

Parameters:

canvasDimension - dimension to be transformed

nodeOnPath - node into which the dimension is to be transformed iteratively through the stack

Returns:

transformed canvasDimension in local coordinates of the picked node

canvasToLocal

public Rectangle2D canvasToLocal(Rectangle2D canvasRectangle,
                                 PNode nodeOnPath)

Convert the given rectangle from the canvas coordinates, down through the pick path (and through any camera view transforms applied to the path) to the local coordinates of the given node.

Parameters:

canvasRectangle - rectangle to be transformed

nodeOnPath - node into which the rectangle is to be transformed iteratively through the stack

Returns:

transformed canvasRectangle in local coordinates of the picked node