dc-path% : class?

superclass: object%

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.

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.

(make-object dc-path%) → (is-a?/c dc-path%)

Creates a new path that contains no sub-paths (and no open sub-path).

(send a-dc-path append path) → void?

path : (is-a?/c dc-path%)

Adds the sub-paths of path to a-dc-path. Closed sub-paths of path are added as closed sub-paths to a-dc-path. If both paths have an open sub-path, then this path’s sub-path is extended by the given path’s open sub-path, adding a line from this path’s current ending point to the given path’s starting point. If only one of the paths has an open sub-path, then it becomes (or remains) this path’s open sub-path.

(send a-dc-path arc   x             y             width             height             start-radians             end-radians            [ counter-clockwise?])   →   void?

x : real?

y : real?

width : (and/c real? (not/c negative?))

height : (and/c real? (not/c negative?))

start-radians : real?

end-radians : real?

counter-clockwise? : any/c = #t

Extends or starts the path’s open sub-path with a curve that corresponds to a section of an ellipse. The ellipse is the one bounded by a rectangle whose top-left corner is (x, y) and whose dimensions are width by height. The ellipse section starts a the angle start-radians (0 is three o’clock and half-pi 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.

(send a-dc-path close) → void?

Closes the path’s open sub-path. If the path has no open sub-path, an exn:fail:contract exception is raised.

(send a-dc-path curve-to x1 y1 x2 y2 x3 y3) → void?

x1 : real?

y1 : real?

x2 : real?

y2 : real?

x3 : real?

y3 : real?

Extends the path’s open sub-path with a Bezier curve to the given point (x3,y3), using the points (x1, y1) and (x2, y2) as control points. If the path has no open sub-path, an exn:fail:contract exception is raised.

(send a-dc-path ellipse x y width height) → void?

x : real?

y : real?

width : (and/c real? (not/c negative?))

height : (and/c real? (not/c negative?))

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.)

(send a-dc-path get-bounding-box)   →   real?   real?   real?   real?

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.

(send a-dc-path line-to x y) → void?

x : real?

y : real?

Extends the path’s open sub-path with a line to the given point. If the path has no open sub-path, an exn:fail:contract exception is raised.

(send a-dc-path lines   points            [ xoffset             yoffset])   →   void?

points : (listof (is-a?/c point%))

xoffset : real? = 0

yoffset : real? = 0

Extends the path’s open sub-path with a sequences of lines to the given points. 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.)

(send a-dc-path move-to x y) → void?

x : real?

y : real?

After closing the open sub-path, if any, starts a new open sub-path with the given initial point.

(send a-dc-path open?) → boolean?

Returns #t if the path has an open sub-path, #f otherwise.

(send a-dc-path rectangle x y width height) → void?

x : real?

y : real?

width : (and/c real? (not/c negative?))

height : (and/c real? (not/c negative?))

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.)

(send a-dc-path reset) → void?

Removes all sub-paths of the path.

(send a-dc-path reverse) → void?

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.

(send a-dc-path rotate radians) → void?

radians : real?

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.

(send a-dc-path rounded-rectangle   x             y             width             height            [ radius])   →   void?

x : real?

y : real?

width : (and/c real? (not/c negative?))

height : (and/c real? (not/c negative?))

radius : real? = -0.25

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.

(send a-dc-path scale x y) → void?

x : real?

y : real?

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.

(send a-dc-path translate x y) → void?

x : real?

y : real?

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.