edu.neu.ccs.gui
Class AutomaticShape

java.lang.Object
  edu.neu.ccs.gui.BaseShape
      edu.neu.ccs.gui.BaseVertexShape
          edu.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:

• Vertex data: new float[0][2]
• End tangent data: null
• Tangent strategy: Tangent.bezierStrategy()
• Path strategy: Path.BEZIER_CUBIC
• Closure mode: ClosureMode.CLOSED
• Winding rule: WindingRule.WIND_NON_ZERO.

AutomaticShape

public AutomaticShape(float[][] vertex)

The constructor with the given vertex data.

Preconditions:

• The given vertex array is either null or float[N][2] for some N.

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:

• The given vertex array is either null or float[N][2] for some N.
• The given end tangent array is either null or float[2][2].

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:

• The given vertex array is either null or float[N][2] for some N.
• The given end tangent array is either null or float[2][2].

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:

• The given vertex array is either null or float[N][2] for some N.
• The given end tangent array is either null or float[2][2].

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:

• The given vertex array is either null or float[N][2] for some N.
• The given end tangent array is either null or float[2][2].

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:

• The given vertex array is either null or float[N][2] for some N.
• The given end tangent array is either null or float[2][2].

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:

• The given end tangent array is either null or float[2][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.

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:

• The given index is not 0 or 1.
• The internal vertex array has length N less than 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.

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:

• The given index is not 0 or 1.
• The internal vertex array has length N less than 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.

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 given index is not 0 or 1.
• The internal vertex array has length N less than 2.
• The internal end tangent array is null.

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:

• The internal vertex array has length N less than 2.
• The internal end tangent array is null.

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:

• The internal vertex array has length N less than 2.
• The internal end tangent array is null.

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