edu.neu.ccs.gui
Class AutomaticShape

java.lang.Object
  extended byedu.neu.ccs.gui.BaseShape
      extended byedu.neu.ccs.gui.BaseVertexShape
          extended byedu.neu.ccs.gui.AutomaticShape
All Implemented Interfaces:
Shape, SupportsPropertyChange
Direct Known Subclasses:
AutomaticCurve

public class AutomaticShape
extends BaseVertexShape

Class AutomaticShape implements a BaseVertexShape in which the tangent array is always automatically computed from the vertex array and other settings using a Tangent.Strategy object.

The default tangent strategy produces tangents for Bezier curves in which the first and second derivatives of the curve are continuous at each vertex. This strategy is described in the article:

Richard Rasala, Explicit Cubic Spline Interpolation Formulas, in Andrew S. Glassner, Graphics Gems, Academic Press, 1990, 579-584.

The derived class AutomaticCurve was introduced in 2.4.0 to fix the path strategy to be Path.BEZIER_CUBIC since that is the most common case.

To define a shape in which the tangent array varies independently of the vertex array, use the class TweakableShape.

The internal tangent array will be maintained as non-null as a byproduct of computing tangents via a tangent strategy.

To efficiently define a polygonal shape that does not use tangents, use either PolygonShape or PolygonDotsShape.

Since:
2.3
Version:
2.4.0

Field Summary
private  float[][] endTangent
          The end tangent data.
static String SET_END_TANGENT
          Bound property name to set one or both end tangents.
static String SET_TANGENT_STRATEGY
          Bound property name to set the tangent strategy.
private  Tangent.Strategy tangentstrategy
          The tangent strategy.
 
Fields inherited from class edu.neu.ccs.gui.BaseVertexShape
ADD_VERTEX, REMOVE_VERTEX, SET_VERTEX
 
Fields inherited from class edu.neu.ccs.gui.BaseShape
REMOVE_SHAPE_DATA, SET_CLOSURE_MODE, SET_PATH_STRATEGY, SET_WINDING_RULE, tangent, vertex
 
Constructor Summary
AutomaticShape()
          The default constructor with an empty shape.
AutomaticShape(float[][] vertex)
          The constructor with the given vertex data.
AutomaticShape(float[][] vertex, float[][] endTangent)
          The constructor with the given vertex data and the given end tangent data.
AutomaticShape(float[][] vertex, float[][] endTangent, Tangent.Strategy tangentstrategy)
          The constructor with the given vertex data, the given end tangent data, and the given tangent strategy.
AutomaticShape(float[][] vertex, float[][] endTangent, Tangent.Strategy tangentstrategy, Path.Strategy pathstrategy)
          The constructor with the given vertex data, the given end tangent data, the given tangent strategy, and the given path strategy.
AutomaticShape(float[][] vertex, float[][] endTangent, Tangent.Strategy tangentstrategy, Path.Strategy pathstrategy, ClosureMode closuremode)
          The constructor with the given vertex data, the given end tangent data, the given tangent strategy, the given path strategy, and the given closure mode.
AutomaticShape(float[][] vertex, float[][] endTangent, Tangent.Strategy tangentstrategy, Path.Strategy pathstrategy, ClosureMode closuremode, WindingRule windingrule)
          The constructor with the given vertex data, the given end tangent data, the given tangent strategy, the given path strategy, the given closure mode, and the given winding rule.
 
Method Summary
 int findEndTangentControl(double x, double y, double epsilon)
          Returns the index of the first end tangent control that is within epsilon of (x,y) relative to the metric Metric.MAX; returns -1 if no such end tangent control exists.
 int findEndTangentControl(double x, double y, double epsilon, Metric metric)
          Returns the index of the first end tangent control that is within epsilon of (x,y) relative to the given metric; returns -1 if no such end tangent control exists.
 float[] getEndTangent(int index)
          Returns a copy of the end tangent at the given index which should be 0 or 1.
 float[] getEndTangentControl(int index)
          Returns a copy of the end tangent control that corresponds to the given index 0 or 1.
 float[][] getEndTangentControlData()
          Returns an array float[2][] that contains the two end tangent control points.
 float[][] getEndTangentData()
          Returns a clone of the end tangent array.
 float getEndTX(int index)
          Returns the x-coordinate of the end tangent data if the given index is 0 or 1 or returns 0 if the index is out of bounds or if the end tangent data is null.
 float getEndTY(int index)
          Returns the y-coordinate of the end tangent data if the given index is 0 or 1 or returns 0 if the index is out of bounds or if the end tangent data is null.
 Tangent.Strategy getTangentStrategy()
          Returns the tangent strategy.
 boolean isEndTangentNull()
          Returns true if the internal end tangent data is null.
 PolygonDotsShape makeEndTangentControlDots()
          Returns a new PolygonDotsShape whose vertex data is a copy of the end tangent control points.
protected  void makePath()
          Makes the path for this AutomaticShape taking into account the vertex and end tangent arrays and the closure mode to construct the full tangent array automatically using the current tangent strategy as the tangent algorithm.
 void setEndTangent(int index, float[] delta)
          Sets the end tangent at the given index 0 or 1 to the given delta and makes a new path.
 void setEndTangent(int index, float dx, float dy)
          Sets the end tangent at the given index 0 or 1 to the given delta coordinates dx, dy and makes a new path.
 void setEndTangentData(float[][] endTangent)
          Sets the end tangent data of the shape using a 2-by-2 array of single precision numbers and makes a new path.
 void setEndTangentViaControl(int index, float[] control)
          Sets the end tangent at the given index 0 or 1 assuming the given control is an associated control point and then makes a new path.
 void setEndTangentViaControl(int index, float x, float y)
          Sets the end tangent at the given index 0 or 1 assuming the given coordinates (x,y) are the coordinates of the associated control point and then makes a new path.
 void setTangentStrategy(Tangent.Strategy tangentstrategy)
          Sets the tangent strategy of the shape and makes a new path.
 
Methods inherited from class edu.neu.ccs.gui.BaseVertexShape
addVertex, addVertex, addVertices, appendVertex, appendVertex, appendVertices, removeAllVertices, removeVertex, removeVertices, setVertex, setVertex, setVertexData
 
Methods inherited from class edu.neu.ccs.gui.BaseShape
addForwardingListener, addPropertyChangeListener, addPropertyChangeListener, addPropertyChangeListeners, addPropertyChangeListeners, bezierTangentSegmentPoints, closedBezierControlPoints, closedBezierFramePoints, contains, contains, contains, contains, findControlA, findControlA, findControlB, findControlB, findVertex, findVertex, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAX, getAY, getBezierTangentSegmentData, getBounds, getBounds2D, getBX, getBY, getClosedBezierControlData, getClosedBezierFrameData, getClosureMode, getControlA, getControlB, getCubicCurvePoint, getForwardingListener, getOpenBezierControlData, getOpenBezierFrameData, getPath, getPathIterator, getPathIterator, getPathStrategy, getPolygonPoint, getPropertyChangeListeners, getPropertyChangeListeners, getTangent, getTangentData, getTransformedShape, getTransformedShape, getTX, getTY, getVertex, getVertexData, getVertexTangent, getVertexTangentData, getVX, getVY, getWindingRule, hasListeners, intersects, intersects, isTangentNull, length, makeBezierTangentSegments, makeClosedBezierFrame, makeClosedControlDots, makeClosedPolygon, makeOpenBezierFrame, makeOpenControlDots, makeOpenPolygon, makePolygonDots, openBezierControlPoints, openBezierFramePoints, removeAndAddForwardingListener, removeForwardingListener, removePropertyChangeListener, removePropertyChangeListener, removeShapeData, setClosureMode, setPathStrategy, setWindingRule, setWindingRule
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SET_TANGENT_STRATEGY

public static final String SET_TANGENT_STRATEGY
Bound property name to set the tangent strategy.

See Also:
Constant Field Values

SET_END_TANGENT

public static final String SET_END_TANGENT
Bound property name to set one or both end tangents.

See Also:
Constant Field Values

tangentstrategy

private Tangent.Strategy tangentstrategy
The tangent strategy.


endTangent

private float[][] endTangent
The end tangent data.

Constructor Detail

AutomaticShape

public AutomaticShape()

The default constructor with an empty shape.

The default settings are as follows:


AutomaticShape

public AutomaticShape(float[][] vertex)

The constructor with the given vertex data.

Preconditions:

If the given vertex array is null then the internal vertex array is set to float[0][2].

Parameters:
vertex - the vertex data

AutomaticShape

public AutomaticShape(float[][] vertex,
                      float[][] endTangent)

The constructor with the given vertex data and the given end tangent data.

Preconditions:

If the given vertex array is null then the internal vertex array is set to float[0][2].

If the given end tangent array is null then an open curve is rendered with the same end tangents as are computed automatically for the corresponding closed curve.

Parameters:
vertex - the vertex data
endTangent - the end tangent data

AutomaticShape

public AutomaticShape(float[][] vertex,
                      float[][] endTangent,
                      Tangent.Strategy tangentstrategy)

The constructor with the given vertex data, the given end tangent data, and the given tangent strategy.

Preconditions:

If the given vertex array is null then the internal vertex array is set to float[0][2].

If the given end tangent array is null then an open curve is rendered with the same end tangents as are computed automatically for the corresponding closed curve.

Parameters:
vertex - the vertex data
endTangent - the end tangent data
tangentstrategy - the tangent strategy

AutomaticShape

public AutomaticShape(float[][] vertex,
                      float[][] endTangent,
                      Tangent.Strategy tangentstrategy,
                      Path.Strategy pathstrategy)

The constructor with the given vertex data, the given end tangent data, the given tangent strategy, and the given path strategy.

Preconditions:

If the given vertex array is null then the internal vertex array is set to float[0][2].

If the given end tangent array is null then an open curve is rendered with the same end tangents as are computed automatically for the corresponding closed curve.

Parameters:
vertex - the vertex data
endTangent - the end tangent data
tangentstrategy - the tangent strategy
pathstrategy - the path strategy

AutomaticShape

public AutomaticShape(float[][] vertex,
                      float[][] endTangent,
                      Tangent.Strategy tangentstrategy,
                      Path.Strategy pathstrategy,
                      ClosureMode closuremode)

The constructor with the given vertex data, the given end tangent data, the given tangent strategy, the given path strategy, and the given closure mode.

Preconditions:

If the given vertex array is null then the internal vertex array is set to float[0][2].

If the given end tangent array is null then an open curve is rendered with the same end tangents as are computed automatically for the corresponding closed curve.

Parameters:
vertex - the vertex data
endTangent - the end tangent data
tangentstrategy - the tangent strategy
pathstrategy - the path strategy
closuremode - the closure mode

AutomaticShape

public AutomaticShape(float[][] vertex,
                      float[][] endTangent,
                      Tangent.Strategy tangentstrategy,
                      Path.Strategy pathstrategy,
                      ClosureMode closuremode,
                      WindingRule windingrule)

The constructor with the given vertex data, the given end tangent data, the given tangent strategy, the given path strategy, the given closure mode, and the given winding rule.

Preconditions:

If the given vertex array is null then the internal vertex array is set to float[0][2].

If the given end tangent array is null then an open curve is rendered with the same end tangents as are computed automatically for the corresponding closed curve.

Parameters:
vertex - the vertex data
endTangent - the end tangent data
tangentstrategy - the tangent strategy
pathstrategy - the path strategy
closuremode - the closure mode
windingrule - the winding rule
Method Detail

isEndTangentNull

public final boolean isEndTangentNull()
Returns true if the internal end tangent data is null.


setEndTangentData

public final void setEndTangentData(float[][] endTangent)

Sets the end tangent data of the shape using a 2-by-2 array of single precision numbers and makes a new path.

Sets the tangents to be used when the shape is displayed as an open curve.

Precondition:

If the given end tangent array is null then an open curve is rendered with the same end tangents as are computed automatically for the corresponding closed curve.

Does nothing if the precondition fails.

Fires property change: SET_END_TANGENT.

Parameters:
endTangent - the end tangent data to set

getEndTangentData

public final float[][] getEndTangentData()

Returns a clone of the end tangent array.

The returned array will either be null or have the form float[2][2].

You may use the method isEndTangentNull() to test if the internal end tangent array is null without needing to ask for the data.

Returns:
a clone of the end tangent array

setEndTangent

public final void setEndTangent(int index,
                                float dx,
                                float dy)

Sets the end tangent at the given index 0 or 1 to the given delta coordinates dx, dy and makes a new path.

Does nothing if the index is not 0 or 1.

If the current end tangent array is null, then this array will be set to new float[2][2] before setting the delta value.

Fires property change: SET_END_TANGENT.

Parameters:
index - the end tangent index
dx - the new x-coordinate for the end tangent
dy - the new y-coordinate for the end tangent

setEndTangent

public final void setEndTangent(int index,
                                float[] delta)

Sets the end tangent at the given index 0 or 1 to the given delta and makes a new path.

Does nothing if the index is not 0 or 1.

Does nothing if delta is not float[2].

If the current end tangent array is null, then this array will be set to new float[2][2] before setting the delta value.

Fires property change: SET_END_TANGENT.

Parameters:
index - the vertex index
delta - the new delta for the vertex at the given index

getEndTX

public final float getEndTX(int index)

Returns the x-coordinate of the end tangent data if the given index is 0 or 1 or returns 0 if the index is out of bounds or if the end tangent data is null.

This method should only be used if the caller knows that the internal end tangent data is non-null. This may be tested using isTangentNull().

Parameters:
index - the index of the end tangent (0 or 1)

getEndTY

public final float getEndTY(int index)

Returns the y-coordinate of the end tangent data if the given index is 0 or 1 or returns 0 if the index is out of bounds or if the end tangent data is null.

This method should only be used if the caller knows that the internal end tangent data is non-null. This may be tested using isTangentNull().

Parameters:
index - the index of the end tangent (0 or 1)

getEndTangent

public final float[] getEndTangent(int index)

Returns a copy of the end tangent at the given index which should be 0 or 1.

More precisely, if the index is 0 or 1 and the end tangent array is non-null, then returns:

  new float[] { getEndTX(index), getEndTY(index) }

Otherwise, returns null.

This methods returns null if the end tangent array is null because that signifies a different rendering behavior for the shape. A null end tangent array does not signify a default of 0 for the end tangents.

Parameters:
index - the index of the end tangent (0 or 1)

setEndTangentViaControl

public final void setEndTangentViaControl(int index,
                                          float x,
                                          float y)

Sets the end tangent at the given index 0 or 1 assuming the given coordinates (x,y) are the coordinates of the associated control point and then makes a new path.

Does nothing if:

If the current end tangent array is null, then this array will be set to new float[2][2] before setting the delta value.

For index = 0, computes the end tangent as:

  (x,y) - getVertex(0)

For index = 1, computes the end tangent as:

  getVertex(N-1) - (x,y)

Fires property change: SET_END_TANGENT.

Parameters:
index - the end tangent index
x - the x-coordinate for the control
y - the y-coordinate for the control

setEndTangentViaControl

public final void setEndTangentViaControl(int index,
                                          float[] control)

Sets the end tangent at the given index 0 or 1 assuming the given control is an associated control point and then makes a new path.

Does nothing if:

If the current end tangent array is null, then this array will be set to new float[2][2] before setting the delta value.

For index = 0, computes the end tangent as:

  control - getVertex(0)

For index = 1, computes the end tangent as:

  getVertex(N-1) - control

Fires property change: SET_END_TANGENT.

Parameters:
index - the end tangent index
control - the control point

getEndTangentControl

public final float[] getEndTangentControl(int index)

Returns a copy of the end tangent control that corresponds to the given index 0 or 1.

Returns null under the following conditions:

The non-null return value for index = 0 is the first ahead control:

  getVertex(0)   + getEndTangent(0)

The non-null return value for index = 1 is the final behind control:

  getVertex(N-1) - getEndTangent(1)

Parameters:
index - the end tangent index 0 or 1

getEndTangentControlData

public final float[][] getEndTangentControlData()

Returns an array float[2][] that contains the two end tangent control points.

Specifically, contains:

  getEndTangentControl(0)
  getEndTangentControl(1)

Note that these control point might be null if the requirements of getEndTangentControl are not met.


findEndTangentControl

public final int findEndTangentControl(double x,
                                       double y,
                                       double epsilon)

Returns the index of the first end tangent control that is within epsilon of (x,y) relative to the metric Metric.MAX; returns -1 if no such end tangent control exists.

The intended use of this method is to locate an end tangent control using an approximate mouse position.

Automatically returns -1 if:

Parameters:
x - the x-coordinate of the search point
y - the y-coordinate of the search point
epsilon - the measure of closeness

findEndTangentControl

public final int findEndTangentControl(double x,
                                       double y,
                                       double epsilon,
                                       Metric metric)

Returns the index of the first end tangent control that is within epsilon of (x,y) relative to the given metric; returns -1 if no such end tangent control exists.

If the given metric is null then Metric.MAX is used.

The intended use of this method is to locate an end tangent control using an approximate mouse position.

Automatically returns -1 if:

Parameters:
x - the x-coordinate of the search point
y - the y-coordinate of the search point
epsilon - the measure of closeness
metric - the metric to do the distance computation

makeEndTangentControlDots

public final PolygonDotsShape makeEndTangentControlDots()

Returns a new PolygonDotsShape whose vertex data is a copy of the end tangent control points.

If the necessary conditions for computing control points do not hold then the shape returned will have no dots.


setTangentStrategy

public final void setTangentStrategy(Tangent.Strategy tangentstrategy)

Sets the tangent strategy of the shape and makes a new path.

Does nothing if its parameter is null.

Fires property change: SET_TANGENT_STRATEGY.

Parameters:
tangentstrategy - the tangent strategy

getTangentStrategy

public final Tangent.Strategy getTangentStrategy()
Returns the tangent strategy.

Returns:
the tangent strategy

makePath

protected final void makePath()
Makes the path for this AutomaticShape taking into account the vertex and end tangent arrays and the closure mode to construct the full tangent array automatically using the current tangent strategy as the tangent algorithm.

Overrides:
makePath in class BaseShape