cairo:dash (cr)

cr -- a cairo:context-t instance
dashes -- a list of numbers coerced to double floats specifying alternate lengths of on and off stroke portions
offset -- a number coerced to a double float for an offset into the dash pattern at which the stroke should start

The cairo:dash function gets the current dash list to be used by the cairo:stroke function. The (setf cairo:dash) function sets the dash pattern. A dash pattern is specified by dashes, a list of positive values. Each value provides the length of alternate "on" and "off" portions of the stroke. The offset specifies an offset into the pattern at which the stroke begins.

Each "on" segment will have caps applied as if the segment were a separate sub-path. In particular, it is valid to use an "on" length of 0.0 with :round or :square in order to distributed dots or squares along a path.

If the dashes argument is an empty list dashing is disabled. If the dashes argument has one list element a symmetric pattern is assumed with alternating on and off portions of the size specified by the single value in dashes. If any value in dashes is negative, or if all values are 0, then cr will be put into an error state with a status of :invalid-dash. The length values are in user-space units as evaluated at the time of stroking. This is not necessarily the same as the user space at the time of the call of the (setf cairo:dash) function.