All Manuals > CAPI User Guide and Reference Manual > 22 GRAPHICS-PORTS Reference Entries

draw-path Function

Summary

Draws a path at a given point, optionally closing it or filling it.

Package

graphics-ports

Signature

draw-path port path x y &rest args &key closed filled fill-rule

Arguments
port
A graphics port.
path
A path specification.
A real number.
A real number.
args
graphics-state parameters passed as keyword arguments.
closed
A boolean.
filled
A boolean.
fill-rule
One of the keywords :even-odd and :winding.
Description

The function draw-path draws the path path at (x y) in port.

When closed is non-nil, a line is drawn from the last point in the path to the start of the last figure in the path. When filled is non-nil, the path is filled, otherwise its outline is drawn; closed is ignored if filled is non-nil. The transform, foreground, background, thickness, scale-thickness, dashed, dash, line-end-style, line-joint-style and mask from port's graphics-state are all used, unless overridden in args. fill-rule specifies how overlapping regions are filled. Possible values for fill-rule are :even-odd and :winding.

path is a path specification, which consists of path elements that describe a number of disconnected figures. The origin of the path is (x y), so all other coordinates within the path are translated relative to that point.

The following formats of path specification are supported:

The following path elements can be used:

:close

Closes the current figure by adding a straight line from the current point to the start point.

:move nx ny

Closes the current figure and starts a new one at (nx ny).

:line nx ny

Adds a straight line to the current figure, from the current point to (nx ny) and makes (nx ny) be the current point.

:arc ax ay width height start-angle sweep &optional movep

Adds an elliptical arc to the current figure, contained in the rectangle from (ax ay) to (ax+width ay+width) from start-angle to start-angle+sweep-angle. Both angles are specified in radians and positive values mean anticlockwise. If movep is nil (the default), then a straight line is also added from the current point to the start of the arc, otherwise a new figure is started from the start of the arc. The end of the arc becomes the new current point.

:bezier cx1 cy1 cx2 cy2 nx ny

Adds a cubic Bézier curve to the current figure, from the current point to (nx ny) using control points (cx1 cy1) and (cx2 cy2).

:rectangle rx ry width height

Adds a self contained figure, a rectangle from (rx ry) to (rx+width ry+width).

:ellipse ex ey x-radius y-radius

Adds a self contained figure, an ellipse of the given radii centered on (ex ey).

:scale sx sy elements

Adds the path elements elements, scaling them by sx and sy.

:rotate theta elements

Adds the path elements elements, rotating them theta radians about the origin. If theta is positive, then the rotation is clockwise.

:translate dx dy elements

Adds the path elements elements, translating them by dx and dy.

:transform transform elements

Adds the path elements elements, transformed by transform.

Examples

Draws two lines from (40 30) to (140 30) and from (140 30) to (140 130):

(draw-path port '((:line 100 0) (:line 100 100)) 40 30)

Draws an outline triangle with vertices (40 30), (140 30) and (140 130):

(draw-path port '((:line 100 0) (:line 100 100))
           40 30 :closed t)

Draws a filled triangle with vertices (40 30), (140 30) and (140 130):

(draw-path port '((:line 100 0) (:line 100 100))
           40 30 :filled t)

Draws a filled triangle exactly as in the previous example but using a function to generate the path elements:

(flet ((generate (fn)
          (funcall fn :line 100 0)
          (funcall fn :line 100 100)))
  (draw-path port #'generate 40 30 :filled t))

Draws 6 copies of a shape consisting of two lines and an arc:

(labels ((generate-1 (fn)
           (funcall fn :line 50 0)
           (funcall fn :line 50 50)
           (funcall fn :arc 0 -50 100 100
                    (/ pi -2) (/ pi -2)))
         (generate-6 (fn)
           (dotimes (x 6)
             (funcall fn :rotate (* 2 pi (/ x 6))
                      #'generate-1))))
  (draw-path port #'generate-6 80 80))

There are more examples in:

(example-edit-file "capi/graphics/paths")

There are further examples in 20 Self-contained examples.

See also

draw-polygon
draw-line
draw-arc
draw-ellipse
graphics-state
13 Drawing - Graphics Ports


CAPI User Guide and Reference Manual (Macintosh version) - 01 Dec 2021 19:31:44