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. [annotate] 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. [annotate] with-drawing-options must be implemented by expanding into a call to invoke-with-drawing-options, supplying a function that executes body as the continuation argument to invoke-with-drawing-options. The exact behavior of this macro is described under invoke-with-drawing-options. [annotate] |
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. [annotate] 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 must implement a method for invoke-with-drawing-options. [annotate] Note: The first and second paragraphs taken together could imply that the continuation is called with the same medium object passed to invoke-with-drawing-options. McClim assumes this is the case since it yields more consistent behavior in case the medium argument is a sheet with output recording: in this case, passing e.g. the sheet's medium with the appropriate drawing options to the continuation instead of the sheet itself would bypass output recording. In the past, McClim passed the sheet's medium instead of the sheet to the continuation and that lead to 1) output not being recording 2) therefor different behavior between equivalent with-drawing-options and invoke-with-drawing-options forms [edit]-- Jan Moringen 2018-10-17 20:22ZThe drawing options can be any of the following, plus any of the suboptions for line styles 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. [annotate] |
A design that will be used as the ink for drawing operations. The drawing functions draw with the color and pattern that this specifies. The default value is +foreground-ink+. See Chapter 13 for a complete description of inks. [annotate] The :ink ink drawing option temporarily changes the value of (medium-ink medium) to ink, replacing the previous ink; the new and old inks are not combined in any way. [annotate] |
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 Chapter 5 for a complete description of transformations. [annotate] The :transformation xform drawing option temporarily changes the value of(medium-transformation medium) to (compose-transformations (medium-transformation medium) xform). [annotate] |
The drawing functions do not affect the drawing plane outside this region. The clipping region must be an area. Furthermore, some implementations might signal an error if the clipping region is not a rectangle or a region set composed entirely of rectangles. 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. [annotate] 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. [annotate] Minor issue: A better explanation is needed. It does the right thing, but it's hard to tell that from this description. That is, the clipping region is expressed in user coordinates. --- DCPL [annotate] |
The line and arc drawing functions render according to this line style. The line style suboptions and default are defined in Section 10.3. [annotate] 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. [annotate] 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 are defaulted 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. [annotate] |
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 Chapter 11 for a complete description of text styles, including the text style suboptions. [annotate] The :text-style ts drawing option temporarily changes the value of (medium-text-style medium) to (merge-text-styles ts (medium-text-style medium)). [annotate] 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. [annotate] |
The following three functions are no different than using with-drawing-options with the :transformation keyword argument supplied. However, they are sufficiently useful that they are provided as a convenience to programmers. [annotate]
In order to preserve referential transparency, these three forms apply the translation, rotation, or scaling transformation first, then the rest of the transformation from (medium-transformation medium). That is, the following two forms would return the same transformation (assuming that the medium's transformation in the second example is the identity transformation): [annotate]
(compose-transformations
(make-translation-transformation dx dy)
(make-rotation-transformation angle))
(with-translation (medium dx dy)
(with-rotation (medium angle)
(medium-transformation medium)))
Establishes a translation on the medium designated by medium that translates by dx in the x direction and dy in the y direction, and then executes body with that transformation in effect. [annotate] dx and dy are as for make-translation-transformation. [annotate] 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. [annotate] |
Establishes a scaling transformation on the medium designated by medium that scales by sx in the x direction and sy in the y direction, and then executes body with that transformation in effect. If sy is not supplied, it defaults to sx. If origin is supplied, the scaling is about that point; if it is not supplied, it defaults to (0,0). [annotate] sx and sy are as for make-scaling-transformation. [annotate] 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. [annotate] |
Establishes a rotation on the medium designated by medium that rotates by angle, and then executes body with that transformation in effect. If origin is supplied, the rotation is about that point; if it is not supplied, it defaults to (0,0). [annotate] angle and origin are as for make-rotation-transformation. [annotate] 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. [annotate] |
Establishes the identity transformation on the medium designated by medium. [annotate] 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. [annotate] Note: I believe this macro should set the medium transformation to the
identity transformation. This is in contrast to the macros above as
this does not compose the identity transformation with the existing
transformation. That would render with-identity-transformation being
the same as progn! [edit]-- Gilbert Baumann 2003-06-02 05:36Z |
Binds the dynamic environment to establish a local coordinate system on the medium designated by medium with the origin of the new coordinate system at the position (x,y). The "directionality" of the coordinate system is otherwise unchanged. x and y are real numbers, and both default to 0. [annotate] Note: From looking at what real CLIM (Lispworks)
does, it seems that the effect of this macro
is to compensate for an exitsing translational component of the
transformation of the medium. And then shift the origin to (x,y).
Further the defaults for x and y seem to be the
current cursor position and not (0,0). [edit]-- Gilbert Baumann 2003-05-28 13:51Z 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. [annotate] |
Binds the dynamic environment to establish a local coordinate system on the medium designated by medium with the positive x axis extending to the right and the positive y axis extending upward, with the origin of the new coordinate system at the position (x,y). x and y are real numbers, and both default to 0. [annotate] 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. [annotate] |