AT&T Home | AT&T Labs | Research
AT&T Labs, Inc. - Research

The Yoix® Scripting Language

Home | What's New | Grammar | Documentation | Download | License | YChart | YDAT | YWAIT | Byzgraf | FAQs
Path typedict
 
A Path is an object that represents a collection of lines, curves, and control information that describe a shape that can be manipulated using built-ins or displayed in an object, like a Canvas, Frame, Image, or JFrame, that can be drawn on your screen. A path is not associated with any drawable object and it does not represent a particular collection of pixels. Instead paths are rendered (or used in other ways) by built-ins, like fill, stroke, or clip, that are defined in a Graphics object that is associated with a drawable object. The fields in a Path are:
add A Builtin that adds the area covered by this path to the area covered by another path and replaces this path by a new path that covers that area.
appendpath A Builtin that appends a copy of a path to this path.
arc A Builtin that adds an arc to this path.
arcn A Builtin that adds an arc to this path.
closepath A Builtin that closes the current subpath in this path.
CTM A Matrix that is automatically used to transform points that a Yoix program works with into the points that are actually stored in the path, which are always interpreted as a physical location in an unspecified object, like a Canvas, Frame, Image, or JFrame, that can be drawn on your screen. The default CTM is a copy of VM.screen.defaultmatrix, which means it is a matrix that describes the default Yoix coordinate system.
currentpath A Builtin that returns a Path that is a copy of this path.
currentpoint A Builtin that returns this path's current point or NULL if this path is empty.
curveto A Builtin that adds a Bezier cubic curve to this path.
elements An Array of numbers that is the internal representation of the path, which is an undocumented format that is subject to change without notice. Reading always returns a snapshot of the array, which can be an expensive operation when paths are large.

The only property of elements that is guaranteed is that a zero length array means the path is empty, however the currentpoint built-in, which returns NULL when the path is empty, is usually a better choice.

eoadd A Builtin that adds the area covered by this path to the area covered by another path and replaces this path by a new path that covers that area.
eointersect A Builtin that intersects the area covered by this path with the area covered by another path and replaces this path by a new path that covers that area.
eointersects A Builtin that can be used to test whether this path intersects another path or Rectangle.
eosubtract A Builtin that subtracts the area covered by another path from the area covered by this path and replaces this path by a new path that covers that area.
eoxor A Builtin that finds the area that consists of points that belong to this path or another path, but not both, and replaces this path by a new path that covers that area.
flattenpath A Builtin that changes this path to one in which all curved components are replaced by sequences of line segments that approximate the curves.
ineofill A Builtin that tests if a point lies inside this path.
infill A Builtin that tests if a point lies inside this path.
instroke A Builtin that tests if a point would be painted if this path were stroked. It is the only Path built-in that uses the linecap, linejoin, linewidth, and miterlimit fields.
intersect A Builtin that intersects the area covered by this path with the area covered by another path and replaces this path by a new path that covers that area.
intersects A Builtin that can be used to test whether this path intersects another path or Rectangle.
linecap An int that determines what happens at the ends of open subpaths when the instroke built-in is called. The value should be one of CAP_BUTT (the default), CAP_ROUND, or CAP_SQUARE, which are all defined in yoix.graphics.
linejoin An int that determines what happens at the joints where curves and lines join when the instroke built-in is called. The value should be one of JOIN_MITER (the default), JOIN_ROUND, or JOIN_BEVEL, which are all defined in yoix.graphics.
lineto A Builtin that adds a line segment to this path.
linewidth A Number that represents the thickness of lines and curves produced when the instroke built-in is called. The value is always interpreted as a distance perpendicular to path in user space, which means results depend on the values stored in CTM when instroke is called. Pixels on either side of path that lie within half a linewidth of path are considered to be in the stroked path.
miterlimit A Number that should be greater than or equal to 1 that controls the joints produced when the instroke built-in is called and linejoin is set to JOIN_MITER. In particular, miter joints are truncated when the width of the joint (i.e., the distance between the inner and outer corners) divided by linewidth exceeds miterlimit.
moveto A Builtin that starts a new subpath in path.
moveto A Builtin that starts a new subpath in this path.
newpath A Builtin that clears this path.
pathbbox A Builtin that returns a rectangle that represents the bounding box of this path.
pathforall A Builtin that examines every element in this path and calls functions based on the type of each element that is encountered.
quadto A Builtin that adds a quadratic curve to this path.
rcurveto A Builtin that adds a Bezier cubic curve to this path.
rlineto A Builtin that adds a line segment to this path.
rmoveto A Builtin that starts a new subpath in this path.
rotatepath A Builtin that changes this path by applying a rotation to every point currently stored in this path.
rquadto A Builtin that adds a quadratic curve to this path.
scalepath A Builtin that changes this path by applying a horizontal and vertical scaling to every point currently stored in this path.
shearpath A Builtin that changes this path by applying a horizontal and vertical shearing to every point currently stored in this path.
subtract A Builtin that subtracts the area covered by another path from the area covered by this path and replaces this path by a new path that covers that area.
transformpath A Builtin that changes this path by applying an affine transformation to every point currently stored in this path.
translatepath A Builtin that changes this path by applying a horizontal and vertical translation to every point currently stored in this path.
xor A Builtin that finds the area that consists of points that belong to this path or another path, but not both, and replaces this path by a new path that covers that area.
Any permanent fields that have not been documented should not be referenced in Yoix applications.
 
 Example:   The program, 
import yoix.*.*;

Path p = {
    Matrix CTM;        // identity matrix
};

p.moveto(100, 100);
p.lineto(200, 100);
printf("Before CTM change: elements=%O\n", p.elements);
p.CTM.scale(2, 1);
p.lineto(200, 200);
printf("After CTM change: elements=%O\n", p.elements);
prints 
Before CTM change: elements=Array[6:0]
   >0
    100.0
    100.0
    1
    200.0
    100.0
After CTM change: elements=Array[9:0]
   >0
    100.0
    100.0
    1
    200.0
    100.0
    1
    400.0
    200.0
on standard output. Even though the internal representation of a path is undocumented and will not be described here, learning something from the output is not particularly difficult. Notice that the numbers that look like the coordinates of the moveto and the first lineto do not change when CTM is scaled, but the coordinates of the second lineto seem to reflect the change that we made to CTM. Do you know why we created a path with the identity matrix as the CTM and do you understand the output when that line is omitted?
 
 See Also:   Graphics, Matrix

 

Yoix is a registered trademark of AT&T Inc.