com.flagstone.transform.util
Class FSShapeConstructor

java.lang.Object
  extended by com.flagstone.transform.util.FSShapeConstructor

public class FSShapeConstructor
extends java.lang.Object

The FSShapeConstructor class is used to create shape definitions. Arbitrary paths can be created using a series of move, line or curve segments. Drawing operations using both absolute coordinates and coordinates relative to the current point (updated after every operation) are supported. For curves both cubic and quadratic curves are supported. Flash only supports quadratic curves so cubic curves are approximated by a series of line segments using (converting cubic to quadratic curves is mathematically difficult). The smoothness of cubic curves is controlled by the flatness attribute which can be used to limit the number of line segments that are drawn. While drawing the start of the first segment to be drawn is recorded so the path can easily be closed by drawing a line from the current point to the start of the first segment drawn. To account for the rounded mitering supported by Flash the path is closed by re-adding the first segment drawn so the line ends overlap. As a path is drawn the maximum and minimum x and y coordinates are recorded so that the bounding rectangle that completely encloses the shape can be defined. This is used when creating shape definitions using the FSDefineShape, FSDefineShape2 or FSDefineShape3 classes. The FSShapeConstructor class also supports a number of method to create closed paths that represent different geometric shapes. Basic rectangles, ellipses and circles are supported. More complex shapes can be drawn using the polygon() method which uses pairs of points to specified the vertices of an arbitrary shapes. When drawing paths whether coordinates are specified in twips or pixels is controlled by the attributes COORDINATES_ARE_PIXELS. This is independent of the flag of the same name supported in the Transform SWF frameworks. When true coordinates are specified in pixels, while coordinates are specified in twips when false. 1 pixel == 20 twips. Internally all coordinates are converted to twips to perform the actual drawing. The styles used to draw the path and fill the area enclosed is specified using the ordinal position of the style object in the arrays of styles maintained by the shape definition object (FSDefineShape, SDefineShape2 or FSDefineShape3) used to construct the final shape. Examples The following code samples illustrate how to use the FSShapeConstructor class create shapes. 1. Defining a rectangle using move and line drawing operations.\n

    FSShapeConstructor path = new FSShapeConstructor();
 
    path.COORDINATES_ARE_PIXELS = true;
 
    int width = 200;
    int height = 100;

    // Setting the line style before any drawing commands is important
    // so the thickness of the line can be taken into account when
    // calculating the bounding rectangle which must completely enclose
    // the shape so it will be drawn correctly.

    path.add(new FSSolidLine(1, FSColorTable.black()));
    path.add(new FSSolidFill(FSColorTable.red()));

    newPath();                   // start a new path
    selectStyle(1, 1);              // select the first line and fill style objects
    move(-width/2, -height/2);   // Move to the top left corner
    rline(width, 0);             // Draw the sides of the rectangle
    rline(0, height);
    rline(-width, 0);
    rline(0, -height);
    closePath();                 // close the path to correctly seal the line ends.
 
    // Now define the shape.
 
    FSDefineShape3 rect = path.defineShape(movie.newIdentifier());
 
2. Defining a rectangle using the path creation method.\n
    FSShapeConstructor path = new FSShapeConstructor();
 
    path.COORDINATES_ARE_PIXELS = true;

    // Define the origin for the shape so the bottom left corner of the 
    // rectangle will appear at the coordinates the shape is place at 
    // using the FSPlaceObject or FSPlaceObject2 class.
 
    int xorigin = 100;
    int yorigin = -50;
 
    int width = 200;
    int height = 100;
    int cornerRadius = 10

    path.add(new FSSolidLine(1, FSColorTable.black()));
    path.add(new FSSolidFill(FSColorTable.red()));

    // Create a rectangle with rounded corners.
 
    path.rect(xorign, yorigin, width, height, cornerRadius);
 
    // Now define the shape.
 
    FSDefineShape3 rect = path.defineShape(movie.newIdentifier());


Field Summary
 boolean COORDINATES_ARE_PIXELS
          The COORDINATES_ARE_PIXELS flag controls whether the coordinates passed to methods when creating a path of predefined shape are expressed in pixels (true) or twips (false).
 
Constructor Summary
FSShapeConstructor()
          Creates an FSShapeConstructor object with no path defined.
 
Method Summary
 void add(FSFillStyle aFillStyle)
          Add the fill style object to the array of fill styles.
 void add(FSLineStyle aLineStyle)
          Add a FSSolidLine object to the array of line styles.
 FSBounds bounds()
          Generates the bounding box that encloses the current path.
 void circle(int r)
          Creates a closed path in the shape of a circle.
 void circle(int x, int y, int r)
          Creates a closed path in the shape of a circle.
 void closePath()
          Closes the current path by drawing a line from the current point to the starting point of the path.
 void curve(int x1, int y1, int x, int y)
          draw a quadratic bezier curve from the current point to the point (x,y) with the control point (x1, y1).
 void curve(int x1, int y1, int x2, int y2, int x, int y)
          draw a cubic bezier curve from the current point to the point (x,y) with the off-curve control points (x1, y1) and (x2, y2).
 FSDefineShape2 defineShape(int identifier)
          Generates a shape containing the current path and styles.
 FSDefineShape3 defineTransparentShape(int identifier)
          Generates a transparent shape containing the current path and styles.
 void ellipse(int rx, int ry)
          Creates a closed path in the shape of an ellipse.
 void ellipse(int x, int y, int rx, int ry)
          Creates a closed path in the shape of an ellipse.
 java.util.ArrayList getFillStyles()
          Gets the array fill styles.
 java.util.ArrayList getLineStyles()
          Gets the array line styles.
 void line(int x, int y)
          draw a line from the current point to the point (x,y).
 void move(int x, int y)
          move to the point (x,y).
 void newPath()
          Creates a new path, discarding any path elements drawn.
 void polygon(int[] points)
          Create a closed shape with vertices defines by pairs of coordinates from the array argument.
 void rcurve(int x1, int y1, int x, int y)
          draw a quadratic bezier curve relative to the current point to the point.
 void rcurve(int x1, int y1, int x2, int y2, int x, int y)
          draw a cubic bezier curve relative to the current point.
 void rect(int width, int height)
          Creates a closed path in the shape of a rectangle with the specified width and height.
 void rect(int width, int height, int radius)
          Creates a closed path in the shape of a rectangle with rounded corners.
 void rect(int x, int y, int width, int height)
          Creates a closed path in the shape of a rectangle with the specified width and height.
 void rect(int x, int y, int width, int height, int radius)
          Creates a closed path in the shape of a rectangle with rounded corners.
 void reflect(int x, int y)
          draw a quadratic bezier curve from the current point to the point (x,y) using the control point for the previously drawn curve.
 void reflect(int x2, int y2, int x, int y)
          draw a cubic bezier curve from the current point to the point (x,y).
 void rline(int x, int y)
          draw a line relative to the current point.
 void rmove(int x, int y)
          move relative to the current point.
 void rpolygon(int[] points)
          Create a closed shape with vertices defines by pairs of coordinates from the array argument.
 void rreflect(int x, int y)
          draw a quadratic bezier curve relative to the current point to the point using the control point for the previously drawn curve.
 void rreflect(int x2, int y2, int x, int y)
          draw a cubic bezier curve relative to the current point.
 void selectAltStyle(int index)
          Selects the style used to fill overlapping areas of the shape from the array of fill styles.
 void selectFillStyle(int index)
          Selects the style used to fill the contents of the shape from the array of fill styles.
 void selectLineStyle(int index)
          Selects the style used to draw the outline of the shape from the array of line styles.
 void selectStyle(int lineIndex, int fillIndex)
          Selects the styles used to draw the outline and fill the contents of the shape from the array of line and fill styles.
 void selectStyle(int lineIndex, int fillIndex, int altIndex)
          Selects the styles used to draw the outline and fill the contents of the shape, including overlapping area, from the array of line and fill styles.
 void set(int index, FSFillStyle aFillStyle)
          Sets the fill style at the index in the array of fill styles.
 void set(int index, FSLineStyle aLineStyle)
          Sets the line style at the index in the array of line styles.
 void setFillStyles(java.util.ArrayList anArray)
          Sets the fill styles.
 void setLineStyles(java.util.ArrayList anArray)
          Sets the line styles.
 FSShape shape()
          Generates an FSShape object containing the objects used to draw the current path.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

COORDINATES_ARE_PIXELS

public boolean COORDINATES_ARE_PIXELS
The COORDINATES_ARE_PIXELS flag controls whether the coordinates passed to methods when creating a path of predefined shape are expressed in pixels (true) or twips (false). Flash coordinates are specified in twips (1 twip equals 1/1440th of an inch or 1/20th of a point). Allowing coordinates to be specified in pixels simplifies the drawing process avoiding the conversion to twips by multiplying each value by 20. IMPORTANT: The value of this flag is independent of the COORDINATES_ARE_PIXELS flag specified in the Transform class of the Transform SWF framework.

Constructor Detail

FSShapeConstructor

public FSShapeConstructor()
Creates an FSShapeConstructor object with no path defined.

Method Detail

set

public void set(int index,
                FSLineStyle aLineStyle)
Sets the line style at the index in the array of line styles.

Parameters:
index - the position in the array of line styles.
aLineStyle - and FSSolidLine object.
Throws:
ArrayIndexOutOfBounds - if the index < 0 or index > array size.

add

public void add(FSLineStyle aLineStyle)
Add a FSSolidLine object to the array of line styles.

Parameters:
aLineStyle - and FSSolidLine object.

set

public void set(int index,
                FSFillStyle aFillStyle)
Sets the fill style at the index in the array of fill styles.

Parameters:
index - the position in the array of fill styles.
aFillStyle - an FSFillStyle object.
Throws:
ArrayIndexOutOfBounds - if the index < 0 or index > array size.

add

public void add(FSFillStyle aFillStyle)
Add the fill style object to the array of fill styles.

Parameters:
aFillStyle - and FSFillStyle object.

getLineStyles

public java.util.ArrayList getLineStyles()
Gets the array line styles.

Returns:
the line styles used in the shape.

setLineStyles

public void setLineStyles(java.util.ArrayList anArray)
Sets the line styles.

Parameters:
anArray - set the line styles for the shape.

getFillStyles

public java.util.ArrayList getFillStyles()
Gets the array fill styles.

Returns:
the fill styles used in the shape.

setFillStyles

public void setFillStyles(java.util.ArrayList anArray)
Sets the fill styles.

Parameters:
anArray - set the fill styles for the shape.

selectLineStyle

public void selectLineStyle(int index)
Selects the style used to draw the outline of the shape from the array of line styles.

Parameters:
index - the position of the style used to draw the shape.

selectFillStyle

public void selectFillStyle(int index)
Selects the style used to fill the contents of the shape from the array of fill styles.

Parameters:
index - the position of the style used to fill the shape.

selectAltStyle

public void selectAltStyle(int index)
Selects the style used to fill overlapping areas of the shape from the array of fill styles.

Parameters:
index - the position of the style used to fill overlapping areas.

selectStyle

public void selectStyle(int lineIndex,
                        int fillIndex)
Selects the styles used to draw the outline and fill the contents of the shape from the array of line and fill styles.

Parameters:
lineIndex - the position of the style used to draw the outline of the shape.
fillIndex - the position of the style used to fill the shape.

selectStyle

public void selectStyle(int lineIndex,
                        int fillIndex,
                        int altIndex)
Selects the styles used to draw the outline and fill the contents of the shape, including overlapping area, from the array of line and fill styles.

Parameters:
lineIndex - the position of the style used to draw the outline of the shape.
fillIndex - the position of the style used to fill the shape.
altIndex - the position of the style used to fill overlapping areas of the shape.

bounds

public FSBounds bounds()
Generates the bounding box that encloses the current path.

Returns:
an FSBounds object representing the bounding box that encloses the path.

shape

public FSShape shape()
Generates an FSShape object containing the objects used to draw the current path.

Returns:
an FSShape object contain the FSLine, FSCurve and FSShapeStyle objects used to construct the current path.

defineShape

public FSDefineShape2 defineShape(int identifier)
Generates a shape containing the current path and styles. The shape is constructed with copies of the style arrays and the shape representing the path drawn. This allows the number of styles to be changed without affecting previously created shapes.

Parameters:
identifier - an unique identifier for the shape.

defineTransparentShape

public FSDefineShape3 defineTransparentShape(int identifier)
Generates a transparent shape containing the current path and styles. The shape is constructed with copies of the style arrays and the shape representing the path drawn. This allows the number of styles to be changed without affecting previously created shapes.

Parameters:
identifier - an unique identifier for the shape.

newPath

public void newPath()
Creates a new path, discarding any path elements drawn.


closePath

public void closePath()
Closes the current path by drawing a line from the current point to the starting point of the path.


move

public void move(int x,
                 int y)
move to the point (x,y). If the COORDINATES_ARE_PIXELS attribute is true then the coordinates are specified in pixels, otherwise the coordinates are specified in twips.

Parameters:
x - the x-coordinate of the point to move to.
y - the y-coordinate of the point to move to.

rmove

public void rmove(int x,
                  int y)
move relative to the current point. If the COORDINATES_ARE_PIXELS attribute is true then the coordinates are specified in pixels, otherwise the coordinates are specified in twips.

Parameters:
x - the distance along the x-axis.
y - the distance along the y-axis.

line

public void line(int x,
                 int y)
draw a line from the current point to the point (x,y). If the COORDINATES_ARE_PIXELS attribute is true then the coordinates are specified in pixels, otherwise the coordinates are specified in twips.

Parameters:
x - the x-coordinate of the end of the line.
y - the y-coordinate of the end of the line.

rline

public void rline(int x,
                  int y)
draw a line relative to the current point. If the COORDINATES_ARE_PIXELS attribute is true then the coordinates are specified in pixels, otherwise the coordinates are specified in twips.

Parameters:
x - the distance along the x-axis to the end of the line.
y - the distance along the y-axis to the end of the line.

curve

public void curve(int x1,
                  int y1,
                  int x,
                  int y)
draw a quadratic bezier curve from the current point to the point (x,y) with the control point (x1, y1). If the COORDINATES_ARE_PIXELS attribute is true then the coordinates are specified in pixels, otherwise the coordinates are specified in twips.

Parameters:
x1 - the x-coordinate of the control point.
y1 - the y-coordinate of the control point.
x - the x-coordinate of the end of the curve.
y - the y-coordinate of the end of the curve.

rcurve

public void rcurve(int x1,
                   int y1,
                   int x,
                   int y)
draw a quadratic bezier curve relative to the current point to the point. If the COORDINATES_ARE_PIXELS attribute is true then the coordinates are specified in pixels, otherwise the coordinates are specified in twips.

Parameters:
x1 - the distance along the x-axis from the current point to the control point.
y1 - the distance along the y-axis from the current point to the control point.
x - the distance along the x-axis from the current point to the end of the curve.
y - the distance along the y-axis from the current point to the end of the curve.

curve

public void curve(int x1,
                  int y1,
                  int x2,
                  int y2,
                  int x,
                  int y)
draw a cubic bezier curve from the current point to the point (x,y) with the off-curve control points (x1, y1) and (x2, y2). IMPORTANT: Converting cubic bezier curves to the quadratic bezier curves supported by Flash is mathematically difficult. The cubic curve is approximated by a series of straight line segments. If the COORDINATES_ARE_PIXELS attribute is true then the coordinates are specified in pixels, otherwise the coordinates are specified in twips.

Parameters:
x1 - the x-coordinate of the first control point.
y1 - the y-coordinate of the first control point.
x2 - the x-coordinate of the second control point.
y2 - the y-coordinate of the second control point.
x - the x-coordinate of the end of the curve.
y - the y-coordinate of the end of the curve.

rcurve

public void rcurve(int x1,
                   int y1,
                   int x2,
                   int y2,
                   int x,
                   int y)
draw a cubic bezier curve relative to the current point. IMPORTANT: Converting cubic bezier curves to the quadratic bezier curves supported by Flash is mathematically difficult. The cubic curve is approximated by a series of straight line segments. If the COORDINATES_ARE_PIXELS attribute is true then the coordinates are specified in pixels, otherwise the coordinates are specified in twips.

Parameters:
x1 - the distance along the x-axis from the current point to the first control point.
y1 - the distance along the y-axis from the current point to the first control point.
x2 - the distance along the x-axis from the current point to the second control point.
y2 - the distance along the y-axis from the current point to the second control point.
x - the distance along the x-axis from the current point to the end of the curve.
y - the distance along the y-axis from the current point to the end of the curve.

reflect

public void reflect(int x,
                    int y)
draw a quadratic bezier curve from the current point to the point (x,y) using the control point for the previously drawn curve. If no curve has been drawn previously then a control point midway along the previous line or move is used. If the COORDINATES_ARE_PIXELS attribute is true then the coordinates are specified in pixels, otherwise the coordinates are specified in twips.

Parameters:
x - the x-coordinate of the end of the curve.
y - the y-coordinate of the end of the curve.

rreflect

public void rreflect(int x,
                     int y)
draw a quadratic bezier curve relative to the current point to the point using the control point for the previously drawn curve. If no curve has been drawn previously then a control point midway along the previous line or move is used. If the COORDINATES_ARE_PIXELS attribute is true then the coordinates are specified in pixels, otherwise the coordinates are specified in twips.

Parameters:
x - the distance along the x-axis from the current point to the end of the curve.
y - the distance along the y-axis from the current point to the end of the curve.

reflect

public void reflect(int x2,
                    int y2,
                    int x,
                    int y)
draw a cubic bezier curve from the current point to the point (x,y). The first control point is the one defined for the previously drawn curve. The second control point is the coordinates (x2, y2). If no curve has been drawn previously then a control point midway along the previous line or move is used. If the COORDINATES_ARE_PIXELS attribute is true then the coordinates are specified in pixels, otherwise the coordinates are specified in twips.

Parameters:
x2 - the x-coordinate of the control point.
y2 - the y-coordinate of the control point.
x - the x-coordinate of the end of the curve.
y - the y-coordinate of the end of the curve.

rreflect

public void rreflect(int x2,
                     int y2,
                     int x,
                     int y)
draw a cubic bezier curve relative to the current point. The first control point is the one defined for the previously drawn curve. The second control point is the relative point (x2, y2). If no curve has been drawn previously then a control point midway along the previous line or move is used. If the COORDINATES_ARE_PIXELS attribute is true then the coordinates are specified in pixels, otherwise the coordinates are specified in twips.

Parameters:
x2 - the distance along the x-axis from the current point to the second control point.
y2 - the distance along the y-axis from the current point to the second control point.
x - the distance along the x-axis from the current point to the end of the curve.
y - the distance along the y-axis from the current point to the end of the curve.

rect

public void rect(int x,
                 int y,
                 int width,
                 int height)
Creates a closed path in the shape of a rectangle with the specified width and height. The centre of the rectangle is located at the point (x,y). If the COORDINATES_ARE_PIXELS attribute is true then the coordinates are specified in pixels, otherwise the coordinates are specified in twips. The origin of the shape can be used to control the relative placement of the rectangle when it is placed on the Flash Player's display list using either the FSPlaceObject or FSPlaceObject2 class.

Parameters:
x - the x-coordinate of the centre of the rectangle.
y - the y-coordinate of the centre of the rectangle.
width - the width of the rectangle.
height - the height of the rectangle.

rect

public void rect(int width,
                 int height)
Creates a closed path in the shape of a rectangle with the specified width and height. The centre of the rectangle is located at the point (0,0). If the COORDINATES_ARE_PIXELS attribute is true then the coordinates are specified in pixels, otherwise the coordinates are specified in twips.

Parameters:
width - the width of the rectangle.
height - the height of the rectangle.

rect

public void rect(int x,
                 int y,
                 int width,
                 int height,
                 int radius)
Creates a closed path in the shape of a rectangle with rounded corners. The shape is drawn with specified width and height and the radius argument specified the radius of the quarter circle used to draw the corners. The centre of the rectangle is located at the point (x,y). If the COORDINATES_ARE_PIXELS attribute is true then the coordinates are specified in pixels, otherwise the coordinates are specified in twips. The origin of the shape can be used to control the relative placement of the rectangle when it is placed on the Flash Player's display list using either the FSPlaceObject or FSPlaceObject2 class.

Parameters:
x - the x-coordinate of the centre of the rectangle.
y - the y-coordinate of the centre of the rectangle.
width - the width of the rectangle.
height - the height of the rectangle.
radius - the radius of the quarter circle used to draw the corners.

rect

public void rect(int width,
                 int height,
                 int radius)
Creates a closed path in the shape of a rectangle with rounded corners. The shape is drawn with specified width and height and the radius argument specified the radius of the quarter circle used to draw the corners. The centre of the rectangle is located at the point (0,0). If the COORDINATES_ARE_PIXELS attribute is true then the coordinates are specified in pixels, otherwise the coordinates are specified in twips.

Parameters:
width - the width of the rectangle.
height - the height of the rectangle.
radius - the radius of the quarter circle used to draw the corners.

ellipse

public void ellipse(int x,
                    int y,
                    int rx,
                    int ry)
Creates a closed path in the shape of an ellipse. The arguments rx and ry specify the radius of the ellipse in the x and y directions respectively. The centre of the ellipse is located at the point (x,y). If the COORDINATES_ARE_PIXELS attribute is true then the coordinates are specified in pixels, otherwise the coordinates are specified in twips. The origin of the shape can be used to control the relative placement of the ellipse when it is placed on the Flash Player's display list using either the FSPlaceObject or FSPlaceObject2 class.

Parameters:
x - the x-coordinate of the centre of the ellipse.
y - the y-coordinate of the centre of the ellipse.
rx - the radius of the ellipse in the x direction.
ry - the radius of the ellipse in the y direction.

ellipse

public void ellipse(int rx,
                    int ry)
Creates a closed path in the shape of an ellipse. The arguments rx and ry specify the radius of the ellipse in the x and y directions respectively. The centre of the ellipse is located at the point (0,0). If the COORDINATES_ARE_PIXELS attribute is true then the coordinates are specified in pixels, otherwise the coordinates are specified in twips.

Parameters:
rx - the radius of the ellipse in the x direction.
ry - the radius of the ellipse in the y direction.

circle

public void circle(int x,
                   int y,
                   int r)
Creates a closed path in the shape of a circle. The centre of the circle is located at the point (x,y) with radius r. If the COORDINATES_ARE_PIXELS attribute is true then the coordinates are specified in pixels, otherwise the coordinates are specified in twips. The origin of the shape can be used to control the relative placement of the circle when it is placed on the Flash Player's display list using either the FSPlaceObject or FSPlaceObject2 class.

Parameters:
x - the x-coordinate of the centre of the circle.
y - the y-coordinate of the centre of the circle.
r - the radius of the circle.

circle

public void circle(int r)
Creates a closed path in the shape of a circle. The centre of the circle is located at the point (0,0) with radius r. If the COORDINATES_ARE_PIXELS attribute is true then the coordinates are specified in pixels, otherwise the coordinates are specified in twips.

Parameters:
r - the radius of the circle.

rpolygon

public void rpolygon(int[] points)
Create a closed shape with vertices defines by pairs of coordinates from the array argument. The first pair of points in the array specifies a move. Line segments a drawn relative to the current point which is updated after each segment is drawn. If the number of points is an odd number then the last point will be ignored. If the COORDINATES_ARE_PIXELS attribute is true then the coordinates are specified in pixels, otherwise the coordinates are specified in twips.

Parameters:
points - and array of coordinate pairs. The first pair of points defines the coordinates of a move operation, successive pairs define the coordinates for relative lines.

polygon

public void polygon(int[] points)
Create a closed shape with vertices defines by pairs of coordinates from the array argument. The first pair of points in the array specifies a move. Line segments a drawn using abolute coordinates. The current point which is updated after each segment is drawn. If the number of points is an odd number then the last point will be ignored. If the COORDINATES_ARE_PIXELS attribute is true then the coordinates are specified in pixels, otherwise the coordinates are specified in twips.

Parameters:
points - and array of coordinate pairs. The first pair of points defines the coordinates of a move operation, successive pairs define the coordinates of the lines.