The output protocol is concerned with the appearance of displayed output on the window associated with a sheet. The sheet output protocol is responsible for providing a means of doing output to a sheet, and for delivering repaint requests to the sheet's client.
Sheets either participate fully in the output protocol or are mute for output. If any functions in the output protocol are called on a sheet that is mute for output, the sheet-is-mute-for-output error will be signaled.
Each sheet retains some output state that logically describes how output is to be rendered on its window. Such information as the foreground and background ink, line thickness, and transformation to be used during drawing are provided by this state. This state may be stored in a medium associated with the sheet itself, may be derived from a parent, or may have some global default, depending on the sheet itself.
If a sheet is mute for output, it is an error to set any of these values.
Summary: The protocol class that corresponds to the output state for some kind of sheet. There is no single advertised standard medium class. If you want to create a new class that behaves like a medium, it should be a subclass of medium. Subclasses of medium must obey the medium protocol.
mediump object
Summary: Returns t if object is a medium; otherwise, it returns nil.
Summary: The basic class on which all CLIM mediums are built, a subclass of medium. This class is an abstract class intended only to be subclassed, not instantiated.
The following generic functions comprise the basic medium protocol. All mediums 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.
medium-foreground Generic Function
medium-foreground medium
(setf medium-foreground) Generic Function
(setf medium-foreground) ink medium
Summary: Returns (or sets) the current foreground ink for the medium medium. For details, see 3.1 CLIM Mediums.
medium-background Generic Function
medium-background medium
(setf medium-background) Generic Function
(setf medium-background) ink medium
Summary: Returns (or sets) the current background ink for the medium medium. This is described in detail in 3.1 CLIM Mediums.
medium-ink medium
(setf medium-ink) Generic Function
(setf medium-ink) ink medium
Summary: Returns (or sets) the current drawing ink for the medium medium. This is described in detail in 3.1 CLIM Mediums.
medium-transformation Generic Function
medium-transformation medium
(setf medium-transformation) Generic Function
(setf medium-transformation) transformation medium
Summary: Returns (or sets) the user transformation that converts the coordinates presented to the drawing functions by the programmer to the medium medium's coordinate system. By default, it is the identity transformation. This is described in detail in 3.1 CLIM Mediums.
medium-clipping-region Generic Function
medium-clipping-region medium
(setf medium-clipping-region) Generic Function
(setf medium-clipping-region) region medium
Summary: Returns (or sets) the clipping region that encloses all output performed on the medium medium. It is returned and set in user coordinates. That is, to convert the user clipping region to medium coordinates, it must be transformed by the value of medium-transformation. For example, the values returned by:
(let (cr1 cr2)
;; Ensure that the sheet's clipping region
;; and transformation will be reset:
(with-drawing-options
(sheet :transformation +identity-transformation+
:clipping-region +everywhere+)
(setf (medium-clipping-region sheet)
(make-rectangle* 0 0 10 10))
(setf (medium-transformation sheet)
(clim:make-scaling-transformation 2 2))
(setf cr1 (medium-clipping-region sheet))
(setf (medium-clipping-region sheet)
(make-rectangle* 0 0 10 10))
(setf (medium-transformation sheet) +identity-transformation+)
(setf cr2 (medium-clipping-region sheet)))
(values cr1 cr2))
are two rectangles. The first one has edges of (0, 0, 5, 5), while the second one has edges of (0, 0, 20, 20).
By default, the user clipping region is the value of +everywhere+.
medium-line-style Generic Function
medium-line-style medium
(setf medium-line-style) Generic Function
(setf medium-line-style) line-style medium
Summary: Returns (or sets) the current line style for the medium medium. This is described in detail in 3.1 CLIM Mediums.
medium-text-style Generic Function
medium-text-style medium
(setf medium-text-style) Generic Function
(setf medium-text-style) text-style medium
Summary: Returns (or sets) the current text style for the medium medium of any textual output that may be displayed on the window. This is described in detail in 3.1 CLIM Mediums.
medium-default-text-style Generic Function
medium-default-text-style medium
(setf medium-default-text-style) Generic Function
(setf medium-default-text-style) text-style medium
Summary: Returns (or sets) the default text style for output on the medium medium. This is described in detail in 3.2 Using CLIM Drawing Options.
medium-merged-text-style Generic Function
medium-merged-text-style medium
Summary: Returns the actual text style used in rendering text on the medium medium. It returns the result of:
(merge-text-styles (medium-text-style medium)
(medium-default-text-style medium))
Those components of the current text style that are not nil will replace the defaults from medium's default text style. Unlike the preceding text style function, medium-merged-text-style is read-only.
The output protocol functions on mediums (and sheets that support the standard output protocol) include those functions described in 2.4 Graphics Protocols.
The following classes implement the standard output protocols.
standard-sheet-output-mixin Class
Summary: This class is mixed into any sheet that provides the standard output protocol, such as repainting and graphics.
Summary: This class is mixed into any sheet that provides none of the output protocol.
permanent-medium-sheet-output-mixin Class
Summary: This class is mixed into any sheet that always has a medium associated with it.
temporary-medium-sheet-output-mixin Class
Summary: This class is mixed into any sheet that may have a medium associated with it, but does not necessarily have a medium at any given instant.
Before a sheet may be used for output, it must be associated with a medium. Some sheets are permanently associated with mediums for output efficiency; for example, CLIM window stream sheets have mediums that are permanently allocated to windows.
However, many kinds of sheets only perform output infrequently, and therefore do not need to be associated with a medium except when output is actually required. Sheets without a permanently associated medium can be much more lightweight than they otherwise would be. For example, in a program that creates a sheet for the purpose of displaying a border for another sheet, the border sheet receives output only when the window's shape is changed.
To associate a sheet with a medium, use the macro with-sheet-medium.
Usually CLIM application programmers will not deal with mediums directly. In most cases, panes will automatically be associated with a medium upon creation. The specific medium object is chosen based on the port being used. An exception is when a "special" medium is created and used with sheets that normally default to a different medium.
with-sheet-medium (medium sheet) &body body
Summary: Within the body, the variable medium is bound to the sheet's medium. If the sheet does not have a medium permanently allocated, one will be allocated, associated with the sheet for the duration of the body, and deallocated when the body has been exited. The values of the last form of the body are returned as the values of with-sheet-medium.
The medium argument is not evaluated, and must be a symbol that is bound to a medium. body may have zero or more declarations as its first forms.
with-sheet-medium-bound (sheet medium) &body body
Summary: with-sheet-medium-bound is used to associate the specific medium medium with the sheet sheet for the duration of the body body. Typically, a single medium will be allocated and passed to several different sheets that can use the same medium.
If the sheet already has a medium allocated to it, the new medium will not be given to the sheet. If the value of medium is nil, with-sheet-medium-bound is exactly equivalent to with-sheet-medium. The values of the last form of the body are returned as the values of with-sheet-medium-bound.
body may have zero or more declarations as its first forms.
sheet-medium sheet
Summary: Returns the medium associated with the sheet sheet. If sheet does not have a medium allocated to it, sheet-medium returns nil.
CLIM 2.0 User Guide - 01 Dec 2021 19:39:01