A path is a set of figures defined by curves. A path can be used with
the
draw-path method of a
dc<%> object to draw
the path’s curves as lines, fill the region bounded by the path’s
curves, or both. A path can also be used with the
set-path method of a
region% object to generate a region
bounded by the path’s curves.
A path consists of zero or more closed sub-paths, and
possibly one open sub-path. Some dc-path% methods
extend the open sub-path, some dc-path% methods close the
open sub-path, and some dc-path% methods add closed
sub-paths. This approach to drawing formulation is inherited from
PostScript [Adobe99].
When a path is drawn as a line, a closed sub-path is drawn as a closed
figure, analogous to a polygon. An open sub-path is drawn with
disjoint start and end points, analogous lines drawn with
draw-lines in dc<%>.
When a path is filled or used as a region, the open sub-path (if any)
is treated as if it were closed. The content of a path is determined
either through the 'even-odd rule or the 'winding
rule, as selected at the time when the path is filled or used to
generate a region.
A path is not connected to any particular dc<%> object, so
setting a dc<%> origin or scale does not affect path
operations. Instead, a dc<%>’s origin and scale apply at the
time that the path is drawn or used to set a region.
Creates a new path that contains no sub-paths (and no
open
sub-path).
Extends or starts the path’s
open sub-path with a curve that
corresponds to a section of an ellipse. If
width and
height
are non-negative, the ellipse is the one
bounded by a rectangle whose top-left corner is
(
x,
y)
and whose dimensions are
width by
height; if
width is negative, then
the rectangle’s right edge is
x, and the ellipse
width is
(abs width), while a negative
height
similarly makes
y is the bottom edge of the ellipse and
the height
(abs height).
Support for negative width and height
helps avoid round-off problems for aligned drawing in an eventual
destination, since arc reduces its input to a sequence of curves.
In contrast, draw-arc in dc<%> can automatically correct for round off,
since the drawing mode is known immediately.
The ellipse section starts a the angle
start-radians (
0 is three o’clock and half-π is
twelve o’clock) and continues to the angle
end-radians; if
counter-clockwise? is true, then the arc runs
counter-clockwise from
start-radians to
end-radians, otherwise it runs clockwise.
If the path has no open sub-path, a new one is started with the
arc’s starting point. Otherwise, the arc extends the existing
sub-path, and the existing path is connected with a line to the arc’s
starting point.
Closes the
open sub-path, if any, and adds a
closed
sub-path that represents an ellipse bounded by a rectangle whose
top-left corner is
(
x, y)
and whose
dimensions are
width by
height. (This convenience
method is implemented in terms of
close and
arc.)
Returns a rectangle that encloses the path’s points. The return
values are the left, top, width, and height of the rectangle.
For curves within the path, the bounding box enclosed the two control
points as well as the start and end points. Thus, the bounding box
does not always tightly bound the path.
Extends the path’s
open sub-path with a sequences of lines to
the given points. A pair is treated as a point where the
car
of the pair is the x-value and the
cdr is the y-value.
If the path has no
open sub-path,
an
exn:fail:contract exception is raised. (This convenience method is implemented in terms of
line-to.)
Closes the
open sub-path, if any, and adds a closed path that
represents a rectangle whose top-left corner is
(
x,
y)
and whose dimensions are
width by
height. (This convenience method is implemented in terms of
close,
move-to, and
line-to.)
Removes all sub-paths of the path.
Reverses the order of all points in all sub-paths. If the path has an
open sub-path, the starting point becomes the ending point,
and extensions to the
open sub-path build on this new ending
point. Reversing a
closed sub-path affects how it combines
with other sub-paths when determining the content of a path in
'winding mode.
Adjusts all points within the path (including all sub-paths), rotating
them radians counter-clockwise around (0, 0). Future
additions to the path are not rotated by this call.
Closes the
open sub-path, if any, and adds a
closed
sub-path that represents a round-cornered rectangle whose top-left
corner is
(
x y)
and whose dimensions are
width by
height. (This convenience method is
implemented in terms of
close,
move-to,
arc, and
line-to.)
If radius is positive, the value is used as the radius of the
rounded corner. If radius is negative, the absolute value is
used as the proportion of the smallest dimension of the
rectangle.
If radius is less than -0.5 or more than half of
width or height, an exn:fail:contract exception is raised.
Adjusts all points within the path
(including all sub-paths), multiplying each x-coordinate by
x and each y-coordinate by
y. Scaling by a negative
number flips the path over the corresponding axis. Future additions
to the path are not scaled by this call.
Adjusts all points within the path (including all sub-paths), shifting
then x to the right and y down. Future additions
to the path are not translated by this call.