A mirrored sheet is a special class of sheet that is attached directly to a window on a display server. Grafts, for example, are always mirrored sheets. However, any sheet anywhere in a sheet hierarchy may be a mirrored sheet. A mirrored sheet will usually contain a reference to a window system object, called a mirror. For example, a mirrored sheet attached to a Motif server might have an X window system object stored in one of its slots. Allowing mirrored sheets at any point in the hierarchy enables the adaptive toolkit facilities.
Since not all sheets in the hierarchy have mirrors, there is no direct correspondence between the sheet hierarchy and the mirror hierarchy. However, on those display servers that support hierarchical windows, the hierarchies must be parallel. If a mirrored sheet is an ancestor of another mirrored sheet, their corresponding mirrors must have a similar ancestor/descendant relationship.
CLIM interacts with mirrors when it must display output or process events. On output, the mirrored sheet closest in ancestry to the sheet on which we wish to draw provides the mirror on which to draw. The mirror's drawing clipping region is set up to be the intersection of the user's clipping region and the sheet's region (both transformed to the appropriate coordinate system) for the duration of the output. On input, events are delivered from mirrors to the sheet hierarchy. The CLIM port must determine which sheet shall receive events based on information such as the location of the pointer.
In both of these cases, we must have a coordinate transformation that converts coordinates in the mirror (so-called "native" coordinates) into coordinates in the sheet and vice-versa.
A mirror is the Lisp object that is the handle to the actual toolkit window or gadget.
sheet-direct-mirror Generic Function
sheet-direct-mirror sheet
Summary: Returns the mirror of the sheet sheet. If the sheet is not mirrored (or does not currently have a mirror), sheet-mirror returns nil.
sheet-mirrored-ancestor Generic Function
sheet-mirrored-ancestor sheet
Summary: Returns the nearest mirrored ancestor of the sheet sheet.
sheet-mirror sheet
Summary: Returns the mirror of the sheet sheet. If the sheet is not itself mirrored, sheet-mirror returns the direct mirror of its nearest mirrored ancestor. sheet-mirror could be implemented as:
(defun sheet-mirror (sheet) (sheet-direct-mirror (sheet-mirrored-ancestor sheet)))
realize-mirror Generic Function
realize-mirror port mirrored-sheet
Summary: Creates a mirror for the sheet mirrored-sheet on the port port, if it does not already have one. The returned value is the sheet's mirror.
sheet-native-transformation Generic Function
sheet-native-transformation sheet
Summary: Returns the transformation for the sheet sheet that converts sheet coordinates into native coordinates. The object returned by this function is volatile, so programmers must not depend on the components of the object remaining constant.
sheet-native-region Generic Function
sheet-native-region sheet
Summary: Returns the region for the sheet sheet in native coordinates. The object returned by this function is volatile, so programmers must not depend on the components of the object remaining constant.
sheet-device-transformation Generic Function
sheet-device-transformation sheet
Summary: Returns the transformation used by the graphics output routines when drawing on the mirror. This is the composition of the sheet's native transformation and the user transformation. The object returned by this function is volatile, so programmers must not depend on the components of the object remaining constant.
sheet-device-region Generic Function
sheet-device-region sheet
Summary: Returns the actual clipping region to be used when drawing on the mirror. This is the intersection of the user's clipping region (transformed by the device transformation) with the sheet's native region. The object returned by this function is volatile, so programmers must not depend on the components of the object remaining constant.
invalidate-cached-transformations Generic Function
invalidate-cached-transformations sheet
Summary: sheet-native-transformation and sheet-device-transformation typically cache the transformations for performance reasons. invalidate-cached-transformations clears the cached native and device values for the sheet sheet's transformation and clipping region. It is invoked when a sheet's native transformation changes, which happens when a sheet's transformation is changed or when invalidate-cached-transformations is called on any of its ancestors.
invalidate-cached-regions Generic Function
invalidate-cached-regions sheet
Summary: sheet-native-region and sheet-device-region typically cache the regions for performance reasons. invalidate-cached-regions clears the cached native and device values for the sheet sheet's native clipping region. It is invoked when a sheet's native clipping region changes, which happens when the clipping region changes or when invalidate-cached-regions is called on any of its ancestors.
CLIM 2.0 User Guide - 01 Dec 2021 19:39:01