gumbo.graphic.probe
Class AbstractPickEngine

java.lang.Object
  |
  +--gumbo.graphic.probe.AbstractPickEngine

All Implemented Interfaces:

Graphic, PickEngine

Direct Known Subclasses:

SwingTreeView.SwingPickEngine

public class AbstractPickEngine

extends java.lang.Object

implements PickEngine

A full implementation of the PickEngine interface. The default implementation performs non-native unordered picking based on intersection using the IntersectableGraphic interface (see doRawPick()).

Version:

$Revision: 1.2 $

Author:

Jon Barrilleaux (jonb@jmbaai.com) of JMB and Associates Inc.

Nested Class Summary

static class	AbstractPickEngine.DistanceComparator A comparator for ordering hits (HitResult) by distance, from closest to farthest.
static class	AbstractPickEngine.GroupComparator A comparator for ordering groups (List) of ordered hits (HitResult) by group distance, from closest to farthest.

Constructor Summary

AbstractPickEngine()
Creates an instance.

Method Summary

protected void	checkPickSpecs(java.util.Set specs, java.util.Collection pickers, java.util.Collection pickables) Called by the system to check the pick specs for compatibility with this engine and the pick players, and throws an exception if a problem is found.
PickResult	doGraphicPick(java.util.Set specs, java.util.Collection pickers, java.util.Collection pickables) Default implementation: Independent of the picker/pickable type.
protected java.util.List	doRawPick(java.util.Set specs, java.lang.Object picker, java.lang.Object pickable, java.util.List retVal) Called by the system to perform a pick operation between each combination of picker and pickable.
java.lang.Object	getGraphic() Default implementation: Returns this object.

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractPickEngine

public AbstractPickEngine()

Creates an instance.

Method Detail

checkPickSpecs

protected void checkPickSpecs(java.util.Set specs,
                              java.util.Collection pickers,
                              java.util.Collection pickables)

Called by the system to check the pick specs for compatibility with this engine and the pick players, and throws an exception if a problem is found.

The default implementation only checks for null parameters and unsupported pick flags, specifically the PICK_ORDERED flag.

Parameters:

specs - The pick specs. Never null.

pickers - The pickers (Object). Never null.

pickables - The pickables (Object). Never null.

Throws:

java.lang.IllegalArgumentException - Specs is null.

java.lang.UnsupportedOperationException - The PICK_ORDERED flag is not supported.

doRawPick

protected java.util.List doRawPick(java.util.Set specs,
                                   java.lang.Object picker,
                                   java.lang.Object pickable,
                                   java.util.List retVal)

Called by the system to perform a pick operation between each combination of picker and pickable. Default implementation: Performs intersection testing using IntersectableGraphic for the intersectable and GraphicGeometry for the intersector. First tries the picker, then the pickable, as the intersector. Returns none or one hit result. The hit result will have no distance (hence cannot support PICK_ORDERED) or other information, regardless of the pick specs.

Parameters:

specs - The pick specs. Never null.

picker - The picker. Never null.

pickable - The pickable. Never null.

retVal - Return value object. Hit results (HitResult), ordered if required. Never null.

Returns:

Reference to retVal. Null if the pick operation is benignly invalid (picking is inactive) or should be ignored (consumed by the native graphic system).

Throws:

java.lang.UnsupportedOperationException - The picker and pickable are incompatible.

doGraphicPick

public PickResult doGraphicPick(java.util.Set specs,
                                java.util.Collection pickers,
                                java.util.Collection pickables)

Default implementation: Independent of the picker/pickable type. If doRawPick() returns null, quits immediately and returns null. Handles all PICK_??? flags but with no optimization. (Ideally, if hits are ordered and only one picker/pickable/hit is needed, then should find the closest hits with no hit information first, and then resolve the hit information just for the returned hits).

Specified by:

doGraphicPick in interface PickEngine

Parameters:

specs - Flags (Picks.PICK_???, Picks.HIT_???) specifying the pick operation and its result. Never null. PICK_??? flag compliance is mandatory. HIT_??? flag compliance is typically optional.

pickers - Group of pickers (Object). Never null. If empty, no hits. A picker's reference space is assumed to be absolute or natively defined unless it implements GraphicGeometry.

pickables - Group of pickables (Object). Never null. If empty, no hits. A pickable's reference space is assumed to be absolute or natively defined unless it implements GraphicGeometry.

Returns:

New pick result. Null if the pick operation is benignly invalid (picking is inactive) or should be ignored (consumed by the native graphic system).

getGraphic

public java.lang.Object getGraphic()

Default implementation: Returns this object.

Specified by:

getGraphic in interface Graphic

Returns:

The target graphic object. Possibly this object (self-proxy, direct implementation), but never null.