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.

x

A real number.

y

A real number.

closed

A boolean.

filled

A boolean.

fill-rule

One of the keywords :even-odd and :winding.

args

graphics-state parameters passed as keyword arguments.

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; the closed argument is ignored if filled is non-nil. transform , foreground , background , thickness , scale-thickness , dashed , dash , line-end-style , line-joint-style and mask from port 's graphics state (see graphics-state) are all used. 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:

• A sequence of lists, each of which is a path element as described below.
• A function designator to generate the path elements. Graphics ports calls the function when it wants to obtain the path elements. The function takes a single argument, which is a function that should be called with each path elements as its arguments.

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 x y

Closes the current figure and starts a new one at ( x y ).

:line x y

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

:arc x y width height start-angle sweep &optional movep

Adds an elliptical arc to the current figure, contained in the rectangle from ( x y ) to ( x+width y+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 x y

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

:rectangle x y width height

Adds a self contained figure, a rectangle from ( x y ) to ( x+width y+width ).

:ellipse x y x-radius y-radius

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

: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 Self-contained examples.

See also

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