On this page:
append
arc
close
curve-to
ellipse
get-bounding-box
line-to
lines
move-to
open?
rectangle
reset
reverse
rotate
rounded-rectangle
scale
text-outline
translate

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

(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 : real?
  height : real?
  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. 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.

(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 : 
(or/c (listof (is-a?/c point%))
      (listof (cons/c real? real?)))
  xoffset : real? = 0
  yoffset : real? = 0
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.)

(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 text-outline font    
  str    
  x    
  y    
  [combine?])  void?
  font : (is-a?/c font%)
  str : string?
  x : real?
  y : real?
  combine? : any/c = #f
Closes the open sub-path, if any, and adds a closed sub-path to outline str using font. The top left of the text is positioned at x and y. The combine? argument enables kerning and character combinations as for draw-text in dc<%>.

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