All Manuals > Common Lisp Interface Manager 2.0 User's Guide > Chapter 3 The CLIM Drawing Environment

NextPrevUpTopContentsIndex

3.1 CLIM Mediums

Drawing in CLIM is done through a medium. A medium can be thought of as an object that knows how to draw on a specific device. For example, a medium translates a CLIM draw-rectangle call into the appropriate draw-rectangle call to the underlying graphics host. Mediums also keep track of default drawing options, such as a drawing plane, foreground and background inks, a transformation, a clipping region, a line style, and a text style. These default values are used when these function-call parameters are left otherwise unspecified. For related information, refer to 2.1.4, Mediums, Sheets, and Streams

The drawing environment is dynamic. The CLIM facilities for affecting the drawing environment do so within their dynamic extent. For example, any drawing done by the user function draw-stuff (as well as any drawing performed by its callees) will be affected by the scaling transformation:

 (clim:with-scaling (medium
 2 1) (draw-stuff medium
))

The medium has components that are used to keep track of the drawing environment. The drawing environment is controlled through the use of drawing options that can be provided as keyword arguments to all of the drawing functions.

Each CLIM medium contains components that correspond to the drawing options. These components provide the default values for the drawing options. When drawing functions are called and some options are unspecified, the options default to the values maintained by the medium.

CLIM provides accessors that enable you to read and write the values of these components. Also, these components are temporarily bound within a dynamic context by using with-drawing-options , with-text-style , and related forms. Using setf on a component while it is temporarily bound takes effect immediately but is undone when the dynamic context is exited.

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 that support the sheet output protocol and on streams that output to such sheets. All classes that support the medium protocol implement methods for these generic functions. Often, a sheet class that supports the output protocol will implement a "trampoline" method that passes the operation directly on to sheet-medium of the sheet.

medium-foreground [Generic Function]

Arguments: medium

medium-background [Generic Function]

Arguments: medium

Summary: 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 5, Drawing in Color for a more complete description of designs.

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

(setf medium-foreground) [Generic Function]

Arguments: ink medium

(setf medium-background) [Generic Function]

Arguments: ink medium

Summary: Sets the foreground and background ink, respectively, for the medium medium to ink . You may not set medium-foreground or medium-background to an indirect ink.

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.

medium-ink [Generic Function]

Arguments: medium

Summary: 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 5, Drawing in Color for a more complete description of inks. The :ink drawing option temporarily changes the value of medium-ink .

(setf medium-ink) [Generic Function]

Arguments: ink medium

Summary: Sets the current drawing ink for the medium medium to ink . ink is as for medium-foreground , and may be an indirect ink as well.

medium-transformation [Generic Function]

Arguments: medium

Summary: The current user transformation for the medium medium . This is used to transform the coordinates supplied as arguments to drawing functions to the coordinate system of the drawing plane. See 3.5, The Transformations Used by CLIM for a complete description of transformations. The :transformation drawing option temporarily changes the value of medium-transformation .

(setf medium-transformation) [Generic Function]

Arguments: transformation medium

Summary: Sets the current user transformation for the medium medium to the transformation transformation .

medium-clipping-region [Generic Function]

Arguments: medium

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

The clipping region is expressed in user coordinates.

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

Arguments: region medium

Summary: Sets the current clipping region for the medium medium to region . region must be a subclass of area .

medium-line-style [Generic Function]

Arguments: medium

Summary: The current line style for the medium medium . The line and arc drawing functions render according to this line style. See 3.3, CLIM Line Styles for a complete description of line styles. The :line-style drawing option temporarily changes the value of medium-line-style .

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

Arguments: line-style medium

Summary: Sets the current line style for the medium medium to the line style line-style .

medium-default-text-style [Generic Function]

Arguments: medium

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

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

Chapter 4, Text Styles for a complete description of text styles.

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

Arguments: text-style medium

Summary: Sets the default text style for the medium medium to the text style text-style . text-style must be a fully specified text style.

medium-text-style [Generic Function]

Arguments: medium

Summary: 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 ). Chapter 4, Text Styles for a complete description of text styles. The :text-style drawing option temporarily changes the value of medium-text-style .

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

Arguments: text-style medium

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

medium-current-text-style [Generic Function]

Arguments: medium

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


Common Lisp Interface Manager 2.0 User's Guide - 20 Sep 2011

NextPrevUpTopContentsIndex