Drawing options control various aspects of the drawing process. You can supply drawing options in a number of ways:
In some cases, it is important to distinguish between drawing options and suboptions. Both text and lines have an option that controls the complete specification of the text and line style, and there are suboptions that can affect one aspect of the text or line style. For example, the value of the :text-style option is a text style object, which describes a complete text style consisting of family, face, and size. There are also suboptions called :text-family, :text-face, and :text-size. Each suboption specifies a single aspect of the text style, while the option specifies the entire text style. Line styles are analogous to text styles; there is a :line-style option and some suboptions.
In a given call to with-drawing-options or a drawing function, you would normally supply either the :text-style option or a text style suboption (or more than one suboption), but not both. If you do supply both, then the text style comes from the result of merging the suboptions with the :text-style option, and then merging that with the prevailing text style.
with-drawing-options (medium &rest drawing-options) &body body
Summary: Binds the state of the medium designated by medium to correspond to the supplied drawing options, and executes the body with the new drawing options specified by drawing-options in effect. Each option causes binding of the corresponding component of the medium for the dynamic extent of the body. The drawing functions effectively do a with-drawing-options when drawing option arguments are supplied to them.
medium can be a medium, a sheet that supports the sheet output protocol, or a stream that outputs to such a sheet. The medium argument is not evaluated, and must be a symbol that is bound to a sheet or medium. If medium is t, *standard- output* is used. body may have zero or more declarations as its first forms.
with-drawing-options expands into a call to invoke-with-drawing-options, supplying a function that executes body as the continuation argument to invoke- with-drawing-options.
invoke-with-drawing-options Generic Function
invoke-with-drawing-options medium continuation &rest drawing-options
Summary: Binds the state of the medium medium to correspond to the supplied drawing options, and then calls the function continuation with the new drawing options in effect. continuation is a function of one argument, the medium; it has dynamic extent. drawing-options is a list of alternating keyword-value pairs, and must have even length. Each option in drawing-options causes binding of the corresponding component of the medium for the dynamic extent of the body.
medium can be a medium, a sheet that supports the sheet output protocol, or a stream that outputs to such a sheet. All classes that obey the medium protocol implement a method for invoke-with-drawing-options.
drawing-options can be any of the following, plus any of the suboptions for line and text styles. The default value specified for a drawing option is the value to which the corresponding component of a medium is normally initialized.
Drawing options can be any of the following, plus any of the line-style or text-style suboptions.
Summary: The drawing functions draw with the color and pattern that this ink specifies. The default value is +foreground-ink+. 5 Drawing in Color for a complete description of inks.
The :ink drawing option temporarily changes the value of (medium-ink medium) to ink, replacing (not combining) the previous ink.
Summary: This transforms the coordinates used as arguments to drawing functions to the coordinate system of the drawing plane. The default value is +identity-transformation+. See 3.5 The Transformations Used by CLIM for a complete description of transformations.
The :transformation xform drawing option temporarily changes the value of (medium-transformation medium) to:
(compose-transformations (medium-transformation medium) xform)
Summary: The drawing functions do not affect the drawing plane outside this region, which must be an area. Rendering is clipped both by this clipping region and by other clipping regions associated with the mapping from the target drawing plane to the viewport that displays a portion of the drawing plane. The default is +everywhere+, or in other words, no clipping occurs in the drawing plane, only in the viewport.
The :clipping-region region drawing option temporarily changes the value of (medium-clipping-region medium) to:
(region-intersection (transform-region (medium-transformation medium) region) (medium-clipping-region medium))
If both a clipping region and a transformation are supplied in the same set of drawing options, the clipping region argument is transformed by the newly composed transformation before calling region-intersection.
Summary: The line- and arc-drawing functions render according to this line style. The line style suboptions and default are defined in 3.3 CLIM Line Styles.
The :line-style ls drawing option temporarily changes the value of (medium-line-style medium) to ls, replacing the previous line style; the new and old line styles are not combined in any way.
If line-style suboptions are supplied, they temporarily change the value of (medium-line-style medium) to a line style constructed from the specified suboptions. Components not specified by suboptions default from the :line-style drawing option, if it is supplied, or else from the previous value of (medium-line-style medium). That is, if both the :line-style option and line-style suboptions are supplied, the suboptions take precedence over the components of the :line-style option.
Summary: The text drawing functions, including ordinary stream output, render text as directed by this text style merged against the default text style. The default value has all null components. See 4 Text Styles for a complete description of text styles, including the text style suboptions.
The :text-style ts drawing option temporarily changes the value of (medium-text-style medium) to:
(merge-text-styles ts (medium-text-style medium))
If text-style suboptions are supplied, they temporarily change the value of (medium-text-style medium) to a text style constructed from the specified suboptions, merged with the :text-style drawing option if it is specified, and then merged with the previous value of (medium-text-style medium). That is, if both the :text-style option and text-style suboptions are supplied, the suboptions take precedence over the components of the :text-style option.
Certain drawing functions can draw either an area or the outline of that area. This is controlled by the :filled keyword argument to these functions. If the value is t (the default), then the function paints the entire area. If the value is nil, then the function outlines the area under the control of the line-style drawing option.
The :filled keyword argument is not a drawing option and cannot be specified to with-drawing-options.
The following functions have a :filled keyword argument:
CLIM 2.0 User Guide - 01 Dec 2021 19:38:56