edu.neu.ccs.gui
Class PathNode

java.lang.Object
  |
  +--edu.neu.ccs.gui.PathNode
All Implemented Interfaces:
Stringable

public class PathNode
extends Object
implements Stringable

Class PathNode makes explicit a data structure for the ingredients that may be used to build a Java object of class GeneralPath.

In JPT, we introduce the PathList class that combines an explicit sequence of PathNode objects together with a winding rule to provide a flexible alternative to GeneralPath.

Class PathNode introduces abbreviations for the somewhat cumbersome names in the Java class PathIterator. The table below shows the corresponding names and also the number of parameters for each type of path segment.

PathIterator Constant PathNode Constant Float Parameters
SEG_MOVETO MOVE x1, y1
SEG_LINETO LINE x1, y1
SEG_QUADTO QUAD x1, y1, x2, y2
SEG_CUBICTO CUBIC x1, y1, x2, y2, x3, y3
SEG_CLOSE CLOSE None

By Java convention in the PathIterator documentation, the path segment parameters are referred to as x1, y1, x2, y2, x3, y3 although it is clear that only the CUBIC segment requires all 6 parameters. We will follow these conventions in naming methods and parameters for this class.

We will also refer to the pair x1,y1 as slot 1, x2,y2 as slot 2, and x3,y3 as slot 3 when we speak of methods that set or query slots.


Field Summary
static int CLOSE
          Shorthand constant for PathIterator.SEG_CLOSE.
static int CUBIC
          Shorthand constant for PathIterator.SEG_CUBICTO.
static int LINE
          Shorthand constant for PathIterator.SEG_LINETO.
static int MOVE
          Shorthand constant for PathIterator.SEG_MOVETO.
protected  int nodetype
          The type of the path node; must be one of the constants: MOVE, LINE, QUAD, CUBIC, CLOSE.
static int QUAD
          Shorthand constant for PathIterator.SEG_QUADTO.
static String standardMessage
          The standard error message for fromStringData.
protected  float x1
          The x1 parameter.
protected  float x2
          The x2 parameter.
protected  float x3
          The x3 parameter.
protected  float y1
          The y1 parameter.
protected  float y2
          The y2 parameter.
protected  float y3
          The y3 parameter.
 
Constructor Summary
PathNode()
          The default constructor that sets the node type to MOVE and sets all numeric data to 0.
PathNode(int type, double[] parameters)
          The constructor that sets the node type and as much of the numeric data as is in the parameters array.
PathNode(int type, float[] parameters)
          The constructor that sets the node type and as much of the numeric data as is in the parameters array.
PathNode(int type, float x1, float y1, float x2, float y2, float x3, float y3)
          The constructor that sets the node type and the numeric node data.
PathNode(PathNode node)
          The constructor that copies the data of an existing path node.
PathNode(String data)
          Constructor that initializes a new node using the data in the String format that is produced by the method toString().
 
Method Summary
 void changeLineToMove()
          If the node type is LINE, changes it to MOVE, otherwise does nothing.
 void changeMoveToLine()
          If the node type is MOVE, changes it to LINE, otherwise does nothing.
 void fromStringData(String state)
          Sets the data of this path node using String data in the format produced by toString().
 int getNodeType()
          Returns the node type which is one of the constants: MOVE, LINE, QUAD, CUBIC, CLOSE.
 int getNodeTypeFromStringData(String data)
          Returns the node type constant that corresponds to the given String data.
 String getNodeTypeString()
          Returns a String label corresponding to the node type.
 int getParameterCount()
          Returns the number of numeric data parameters needed by the current node type.
 float[] getParameters()
          Returns a copy of the current numeric data parameters.
static PathNode[] getPathNodes(PathIterator iterator)
          Returns an array of PathNode objects that corresponds to the information in the given iterator.
static PathNode[] getPathNodes(Shape shape)
          Returns an array of PathNode objects that corresponds to the information in the given shape.
static PathNode[] getPathNodes(Shape shape, AffineTransform transform)
          Returns an array of PathNode objects that corresponds to the information in the given shape after being transformed by the given transform.
static PathNode[] getPathNodes(Shape shape, AffineTransform transform, double flatness)
          Returns an array of PathNode objects that corresponds to the information in the given shape after being transformed by the given transform and appying the given flatness parameter.
 float[] getSlot(int slot)
          Returns an (x,y) pair of values corresponding to the given slot index or null if the index is invalid.
 int getSlotCount()
          Returns the number of x,y slots needed by the current node type.
 float getSlotX(int slot)
          Returns the x-coordinate corresponding to the given slot index or 0 if the index is invalid.
 float getSlotY(int slot)
          Returns the y-coordinate corresponding to the given slot index or 0 if the index is invalid.
 float getX1()
          Returns the internal parameter x1.
 float getX2()
          Returns the internal parameter x2.
 float getX3()
          Returns the internal parameter x3.
 float getY1()
          Returns the internal parameter y1.
 float getY2()
          Returns the internal parameter y2.
 float getY3()
          Returns the internal parameter y3.
 int nearSlot(double x, double y, double epsilon)
          Searches the slots in this node and returns a slot index if the given (x,y) is within epsilon of the values in that slot; returns -1 if no such slot exists.
 int nearSlot(double x, double y, double epsilon, Metric metric)
          Searches the valid slots in this node in order and returns a slot index if the given (x,y) is within epsilon of the values in that slot relative to the given metric; returns -1 if no such slot exists.
 int nodeInfo(double[] coords)
          Returns the node type as the return value and stores the node numeric data in the supplied array which must be non-null and of size at least 6.
 int nodeInfo(float[] coords)
          Returns the node type as the return value and stores the node numeric data in the supplied array which must be non-null and of size at least 6.
 void setNodeType(int type)
          Sets the node type of the node.
 void setParameters(double[] parameters)
          Sets the internal parameters appropriate for the current node type but does not set parameters that are unused.
 void setParameters(float[] parameters)
          Sets the internal parameters appropriate for the current node type but does not set parameters that are unused.
 void setParameters(float x1, float y1)
          Sets the parameters appropriate for the current node type using explicit float values.
 void setParameters(float x1, float y1, float x2, float y2)
          Sets the parameters appropriate for the current node type using explicit float values.
 void setParameters(float x1, float y1, float x2, float y2, float x3, float y3)
          Sets the parameters appropriate for the current node type using explicit float values.
 void setPathNode(PathNode node)
          Sets this path node to have a copy of the settings of the given path node.
 void setSlot(int slot, float[] pair)
          Sets the slot with the given slot index to the given x,y pair array.
 void setSlot(int slot, float x, float y)
          Sets the slot with the given slot index to the given x,y values.
 void setX1(float x1)
          Sets the internal parameter x1.
 void setX2(float x2)
          Sets the internal parameter x2.
 void setX3(float x3)
          Sets the internal parameter x3.
 void setY1(float y1)
          Sets the internal parameter y1.
 void setY2(float y2)
          Sets the internal parameter y2.
 void setY3(float y3)
          Sets the internal parameter y3.
 String toString()
          Writes the data of this path node to a String.
 String toStringData()
          Returns the same result as toString().
 void transform(AffineTransform T)
          Transforms the internal data points using the given affine transform.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

MOVE

public static final int MOVE
Shorthand constant for PathIterator.SEG_MOVETO.

See Also:
Constant Field Values

LINE

public static final int LINE
Shorthand constant for PathIterator.SEG_LINETO.

See Also:
Constant Field Values

QUAD

public static final int QUAD
Shorthand constant for PathIterator.SEG_QUADTO.

See Also:
Constant Field Values

CUBIC

public static final int CUBIC
Shorthand constant for PathIterator.SEG_CUBICTO.

See Also:
Constant Field Values

CLOSE

public static final int CLOSE
Shorthand constant for PathIterator.SEG_CLOSE.

See Also:
Constant Field Values

standardMessage

public static final String standardMessage
The standard error message for fromStringData.

See Also:
Constant Field Values

nodetype

protected int nodetype
The type of the path node; must be one of the constants: MOVE, LINE, QUAD, CUBIC, CLOSE.


x1

protected float x1
The x1 parameter.


y1

protected float y1
The y1 parameter.


x2

protected float x2
The x2 parameter.


y2

protected float y2
The y2 parameter.


x3

protected float x3
The x3 parameter.


y3

protected float y3
The y3 parameter.

Constructor Detail

PathNode

public PathNode()
The default constructor that sets the node type to MOVE and sets all numeric data to 0.


PathNode

public PathNode(int type,
                float[] parameters)

The constructor that sets the node type and as much of the numeric data as is in the parameters array.

The number of data cells used in the parameters array depends on the node type according to the following rules:

Throws IllegalArgumentException if the node type is not one of the constants: MOVE, LINE, QUAD, CUBIC, or CLOSE.

If the parameters array is null, the missing data is treated as 0.

If the parameters array is non-null, then its length must be large enough to fill the required number of parameters for the current node type or else an IllegalArgumentException is thrown.

Parameters:
type - the node type
parameters - the numeric data for the node
Throws:
IllegalArgumentException

PathNode

public PathNode(int type,
                double[] parameters)

The constructor that sets the node type and as much of the numeric data as is in the parameters array.

The number of data cells used in the parameters array depends on the node type according to the following rules:

Throws IllegalArgumentException if the node type is not one of the constants: MOVE, LINE, QUAD, CUBIC, or CLOSE.

If the parameters array is null, the missing data is treated as 0.

If the parameters array is non-null, then its length must be large enough to fill the required number of parameters for the current node type or else an IllegalArgumentException is thrown.

This is a convenience constructor so that the parameters may be specified by an array of double rather than float.

Parameters:
type - the node type
parameters - the numeric data for the node
Throws:
IllegalArgumentException

PathNode

public PathNode(int type,
                float x1,
                float y1,
                float x2,
                float y2,
                float x3,
                float y3)

The constructor that sets the node type and the numeric node data.

The number of data items used depends on the node type according to the following rules:

Data items that will not be used may be passed as 0.

Throws IllegalArgumentException if the node type is not one of the constants: MOVE, LINE, QUAD, CUBIC, or CLOSE.

Parameters:
type - the node type
x1 - parameter 0
y1 - parameter 1
x2 - parameter 2
y2 - parameter 3
x3 - parameter 4
y3 - parameter 5
Throws:
IllegalArgumentException

PathNode

public PathNode(PathNode node)

The constructor that copies the data of an existing path node.

If the given path node is null then acts as the default constructor.

Parameters:
node - the path node to copy

PathNode

public PathNode(String data)
         throws ParseException

Constructor that initializes a new node using the data in the String format that is produced by the method toString().

Throws ParseException if the data is not in the correct format or has numeric errors.

Parameters:
data - the String with the state information
Throws:
ParseException
Method Detail

setPathNode

public final void setPathNode(PathNode node)

Sets this path node to have a copy of the settings of the given path node.

If the given path node is null then does nothing.

Parameters:
node - the path node to copy

setNodeType

public void setNodeType(int type)

Sets the node type of the node.

Throws IllegalArgumentException if the node type is not one of the constants: MOVE, LINE, QUAD, CUBIC, or CLOSE.

Does nothing if the node type will not be changed.

If the node type is changed then it is almost certain that the numeric data in this node is invalid and it is the responsibility of the caller to use one or more of the set methods to provide valid data.

Parameters:
type - the node type

getNodeType

public int getNodeType()

Returns the node type which is one of the constants: MOVE, LINE, QUAD, CUBIC, CLOSE.


setParameters

public void setParameters(float[] parameters)

Sets the internal parameters appropriate for the current node type but does not set parameters that are unused.

If the parameters array is null, the missing data is treated as 0.

If the parameters array is non-null, then its length must be large enough to fill the required number of parameters for the current node type or else an IllegalArgumentException is thrown.

Parameters:
parameters - the numeric data for the node

setParameters

public void setParameters(double[] parameters)

Sets the internal parameters appropriate for the current node type but does not set parameters that are unused.

If the parameters array is null, the missing data is treated as 0.

If the parameters array is non-null, then its length must be large enough to fill the required number of parameters for the current node type or else an IllegalArgumentException is thrown.

Parameters:
parameters - the numeric data for the node

setParameters

public void setParameters(float x1,
                          float y1,
                          float x2,
                          float y2,
                          float x3,
                          float y3)

Sets the parameters appropriate for the current node type using explicit float values.

Does not set internal parameters that are unused for the current node type.

Parameters:
x1 - parameter 0
y1 - parameter 1
x2 - parameter 2
y2 - parameter 3
x3 - parameter 4
y3 - parameter 5

setParameters

public void setParameters(float x1,
                          float y1,
                          float x2,
                          float y2)

Sets the parameters appropriate for the current node type using explicit float values.

Does not set internal parameters that are unused for the current node type.

Since 4 parameters is insufficient for a CUBIC node type, throws IllegalArgumentException in this case.

Therefore, this method requires that the caller know that the node type is suitable prior to calling the method.

Parameters:
x1 - parameter 0
y1 - parameter 1
x2 - parameter 2
y2 - parameter 3

setParameters

public void setParameters(float x1,
                          float y1)

Sets the parameters appropriate for the current node type using explicit float values.

Does not set internal parameters that are unused for the current node type.

Since 2 parameters is insufficient for a QUAD or CUBIC node type, throws IllegalArgumentException in this case.

Therefore, this method requires that the caller know that the node type is suitable prior to calling the method.

Parameters:
x1 - parameter 0
y1 - parameter 1

getParameters

public float[] getParameters()
Returns a copy of the current numeric data parameters.


getParameterCount

public int getParameterCount()
Returns the number of numeric data parameters needed by the current node type.


getSlotCount

public int getSlotCount()
Returns the number of x,y slots needed by the current node type. This is half of the parameter count.


setX1

public final void setX1(float x1)

Sets the internal parameter x1.

This method does not check whether the cell is used by the current node type.


setY1

public final void setY1(float y1)

Sets the internal parameter y1.

This method does not check whether the cell is used by the current node type.


setX2

public final void setX2(float x2)

Sets the internal parameter x2.

This method does not check whether the cell is used by the current node type.


setY2

public final void setY2(float y2)

Sets the internal parameter y2.

This method does not check whether the cell is used by the current node type.


setX3

public final void setX3(float x3)

Sets the internal parameter x3.

This method does not check whether the cell is used by the current node type.


setY3

public final void setY3(float y3)

Sets the internal parameter y3.

This method does not check whether the cell is used by the current node type.


getX1

public final float getX1()

Returns the internal parameter x1.

This method does not check whether the cell is used by the current node type.


getY1

public final float getY1()

Returns the internal parameter y1.

This method does not check whether the cell is used by the current node type.


getX2

public final float getX2()

Returns the internal parameter x2.

This method does not check whether the cell is used by the current node type.


getY2

public final float getY2()

Returns the internal parameter y2.

This method does not check whether the cell is used by the current node type.


getX3

public final float getX3()

Returns the internal parameter x3.

This method does not check whether the cell is used by the current node type.


getY3

public final float getY3()

Returns the internal parameter y3.

This method does not check whether the cell is used by the current node type.


setSlot

public final void setSlot(int slot,
                          float x,
                          float y)

Sets the slot with the given slot index to the given x,y values.

Requires 1 <= index <= getSlotCount() or does nothing.

Parameters:
slot - the slot index 1, 2, 3
x - the x-coordinate
y - the y-coordinate

setSlot

public final void setSlot(int slot,
                          float[] pair)

Sets the slot with the given slot index to the given x,y pair array.

Requires 1 <= slot <= getSlotCount() or does nothing.

Also does nothing if pair is not float[2].

Parameters:
slot - the slot index 1, 2, 3
pair - the float[2] array with x, y

getSlot

public final float[] getSlot(int slot)

Returns an (x,y) pair of values corresponding to the given slot index or null if the index is invalid.

Requires 1 <= slot <= getSlotCount() to return a non-null value.

Parameters:
slot - the slot index 1, 2, 3

getSlotX

public final float getSlotX(int slot)

Returns the x-coordinate corresponding to the given slot index or 0 if the index is invalid.

Requires 1 <= slot <= getSlotCount() to return a valid value.

Parameters:
slot - the slot index 1, 2, 3

getSlotY

public final float getSlotY(int slot)

Returns the y-coordinate corresponding to the given slot index or 0 if the index is invalid.

Requires 1 <= slot <= getSlotCount() to return a valid value.

Parameters:
slot - the slot index 1, 2, 3

nearSlot

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

Searches the slots in this node and returns a slot index if the given (x,y) is within epsilon of the values in that slot; returns -1 if no such slot exists.

The metric Metric.MAX is used.

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

nearSlot

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

Searches the valid slots in this node in order and returns a slot index if the given (x,y) is within epsilon of the values in that slot relative to the given metric; returns -1 if no such slot exists.

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

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

nodeInfo

public int nodeInfo(float[] coords)

Returns the node type as the return value and stores the node numeric data in the supplied array which must be non-null and of size at least 6.

Throws IllegalArgumentException if the supplied array does not meet the preconditions.

Overwrites the existing contents of the first 6 cells of the supplied array.

This method is intended to provide the behavior for a single node that the method currentSegment provides for each successive node in the Java interface PathIterator.

Parameters:
coords - an array of size 6 to hold the node data
Throws:
IllegalArgumentException

nodeInfo

public int nodeInfo(double[] coords)

Returns the node type as the return value and stores the node numeric data in the supplied array which must be non-null and of size at least 6.

Throws IllegalArgumentException if the supplied array does not meet the preconditions.

Overwrites the existing contents of the first 6 cells of the supplied array.

This method is intended to provide the behavior for a single node that the method currentSegment provides for each successive node in the Java interface PathIterator.

Parameters:
coords - an array of size 6 to hold the node data
Throws:
IllegalArgumentException

changeMoveToLine

public void changeMoveToLine()

If the node type is MOVE, changes it to LINE, otherwise does nothing.

This is a helper method that may permit one to connect a node sequence to a node sequence.


changeLineToMove

public void changeLineToMove()

If the node type is LINE, changes it to MOVE, otherwise does nothing.

This is a helper method that may permit one to disconnect a node sequence from a node sequence.


transform

public final void transform(AffineTransform T)

Transforms the internal data points using the given affine transform.

Does nothing if the given affine transform is null.

Parameters:
T - the affine transform

toString

public String toString()

Writes the data of this path node to a String.

The format is one of the following:

MOVE[x1;y1]
LINE[x1;y1]
QUAD[x1;y1;x2;y2]
CUBIC[x1;y1;x2;y2;x3;y3]
CLOSE[]

where x1, y1, x2, y2, x3, y3 are floats.

Overrides:
toString in class Object

toStringData

public String toStringData()
Returns the same result as toString().

Specified by:
toStringData in interface Stringable
See Also:
Stringable.fromStringData(String)

fromStringData

public void fromStringData(String state)
                    throws ParseException

Sets the data of this path node using String data in the format produced by toString().

For convenience, views an empty data String as equivalent to the following default: MOVE[0;0].

Throws ParseException if the data is not in the correct format or has numeric errors.

Specified by:
fromStringData in interface Stringable
Parameters:
state - the String with the state information
Throws:
ParseException
See Also:
Stringable.toStringData()

getNodeTypeString

public String getNodeTypeString()
Returns a String label corresponding to the node type.


getNodeTypeFromStringData

public int getNodeTypeFromStringData(String data)
                              throws ParseException

Returns the node type constant that corresponds to the given String data.

The valid input data is "MOVE", "LINE", "QUAD", "CUBIC", and "CLOSE".

Throws ParseException if the node type String does not match any node type.

Parameters:
data - the String with the node type
Throws:
ParseException

getPathNodes

public static PathNode[] getPathNodes(PathIterator iterator)

Returns an array of PathNode objects that corresponds to the information in the given iterator.

The method must execute the iteration so when it is complete then iterator.isDone() will be true.

Returns an empty array if the given iterator is null.

Parameters:
iterator - the iterator whose data is to be extracted

getPathNodes

public static PathNode[] getPathNodes(Shape shape)

Returns an array of PathNode objects that corresponds to the information in the given shape.

Returns an empty array if the given shape is null.

Parameters:
shape - the shape whose data is to be extracted

getPathNodes

public static PathNode[] getPathNodes(Shape shape,
                                      AffineTransform transform)

Returns an array of PathNode objects that corresponds to the information in the given shape after being transformed by the given transform.

Returns an empty array if the given shape is null.

Parameters:
shape - the shape whose data is to be extracted
transform - the transform to apply to the shape data

getPathNodes

public static PathNode[] getPathNodes(Shape shape,
                                      AffineTransform transform,
                                      double flatness)

Returns an array of PathNode objects that corresponds to the information in the given shape after being transformed by the given transform and appying the given flatness parameter.

Returns an empty array if the given shape is null.

Parameters:
shape - the shape whose data is to be extracted
transform - the transform to apply to the shape data
flatness - the flatness to require