draw-path

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.
`x`⇩	A real number.
`y`⇩	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:

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