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 [Macro]
Arguments: (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 [Macro]
Arguments: (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 [Generic Function]
Summary: Returns the medium associated with the sheet sheet . If sheet does not have a medium allocated to it, sheet-medium returns nil .
Common Lisp Interface Manager 2.0 User's Guide - 7 Aug 2017