10.1 Medium Components

Medium objects contain components that correspond to the drawing options; when no value for a drawing option is explicitly provided to a drawing function, it is taken from the medium. These values can be directly queried or modified using accessors defined on the sheet or medium. They can also be temporarily bound within a dynamic context using with-drawing-options, with-text-style, and related forms. [annotate]

setf of one of these components while it is temporarily bound (via with-drawing-options, for instance) takes effect immediately but is undone when the dynamic binding context is exited. [annotate]

In systems that support multiple processes, the consequences are unspecified if one process reads or writes a medium component that is temporarily bound by another process. [annotate]

The following functions read and write components of a medium related to drawing options. While these functions are defined for mediums, they can also be called on sheets support the sheet output protocol and on streams that output to such sheets. All classes that support the medium protocol must implement methods for these generic functions. Often, a sheet class that supports the output protocol will implement a "trampoline" method that passes the operation on to sheet-medium of the sheet. [annotate]

medium-foreground  medium [Generic Function]
medium-background  medium [Generic Function]
          

Returns the foreground and background inks (which are designs) for the medium medium, respectively. The foreground ink is the default ink used when drawing. The background ink is the ink used when erasing. See Chapter 13 for a more complete description of designs. [annotate]

Any indirect inks are resolved against the foreground and background at the time a design is rendered. [annotate]

[annotate]

(setf medium-foreground)  design medium [Generic Function]
(setf medium-background)  design medium [Generic Function]
          

Sets the foreground and background ink, respectively, for the medium medium to design. You may not set medium-foreground or medium-background to an indirect ink. [annotate]

Note: It appears (setf (medium-foreground medium) +everywhere+) is legal, but the consequences are unclear. Should this be more strict, specifying that the design must be colored (14.4)? [edit]-- Andy Hefner 2007-01-16 22:03Z
 

design is an unbounded design. If the background design is not completely opaque at all points, the consequences are unspecified. [annotate]

Changing the foreground or background of a sheet that supports output recording causes the contents of the stream's viewport to be erased and redrawn using the new foreground and background. [annotate]

[annotate]

medium-ink  medium [Generic Function]
          

The current drawing ink for the medium medium, which can be any design. The drawing functions draw with the color and pattern that this specifies. See Chapter 13 for a more complete description of inks. The :ink drawing option temporarily changes the value of medium-ink. [annotate]

[annotate]

(setf medium-ink)  design medium [Generic Function]
          

Sets the current drawing ink for the medium medium to design. design is as for medium-foreground, and may be an indirect ink as well. [annotate]

[annotate]

medium-transformation  medium [Generic Function]
          

The current user transformation for the medium medium. This transformation is used to transform the coordinates supplied as arguments to drawing functions to the coordinate system of the drawing plane. See Chapter 5 for a complete description of transformations. The :transformation drawing option temporarily changes the value of medium-transformation. [annotate]

[annotate]

(setf medium-transformation)  transformation medium [Generic Function]
          

Sets the current user transformation for the medium medium to the transformation transformation. [annotate]

[annotate]

medium-clipping-region  medium [Generic Function]
          

The current clipping region for the medium medium. The drawing functions do not affect the drawing plane outside this region. The :clipping-region drawing option temporarily changes the value of medium-clipping-region. [annotate]

The clipping region is expressed in user coordinates. [annotate]

[annotate]

(setf medium-clipping-region)  region medium [Generic Function]
          

Sets the current clipping region for the medium medium to region. region must be a subclass of area. Furthermore, some implementations may signal an error if the clipping region is not a rectangle or a region set composed entirely of rectangles. [annotate]

[annotate]

medium-line-style  medium [Generic Function]
          

The current line style for the medium medium. The line and arc drawing functions render according to this line style. See Section 10.3 for a complete description of line styles. The :line-style drawing option temporarily changes the value of medium-line-style. [annotate]

[annotate]

(setf medium-line-style)  line-style medium [Generic Function]
          

Sets the current line style for the medium medium to the line style line-style. [annotate]

[annotate]

medium-default-text-style  medium [Generic Function]
          

The default text style for the medium medium. medium-default-text-style will return a fully specified text style, unlike medium-text-style, which may return a text style with null components. Any text styles that are not fully specified by the time they are used for rendering are merged against medium-default-text-style using merge-text-styles. [annotate]

The default value for medium-default-text-style for any medium is *default-text-style*. [annotate]

See Chapter 11 for a complete description of text styles. [annotate]

[annotate]

(setf medium-default-text-style)  text-style medium [Generic Function]
          

Sets the default text style for the medium medium to the text style text-style. text-style must be a fully specified text style. [annotate]

Some CLIM implementations may arrange to erase and redraw the output on an output recording stream when the default text style of the stream is changed. Implementations that do this must obey the proper vertical spacing for output streams, and must reformat tables, graphs, and so forth, as necessary. Because of the expense of this operation, CLIM implementations are not required to support this. [annotate]

[annotate]

medium-text-style  medium [Generic Function]
          

The current text style for the medium medium. The text drawing functions, including ordinary stream output, render text as directed by this text style merged against the default text style. This controls both graphical text (such as that drawn by draw-text*) and stream text (such as that written by write-string). See Chapter 11 for a complete description of text styles. The :text-style drawing option temporarily changes the value of medium-text-style. [annotate]

[annotate]

(setf medium-text-style)  text-style medium [Generic Function]
          

Sets the current text style for the medium medium to the text style text-style. text-style need not be a fully merged text style. [annotate]

[annotate]

medium-current-text-style  medium [Generic Function]
          

The current, fully merged text style for the medium medium. This is the text style that will be used when drawing text output, and is the result of merging medium-text-style against medium-default-text-style. [annotate]

[annotate]

Note: How is this different from medium-merged-text-style? [edit]-- Gilbert Baumann 2005-03-06 16:18Z