7.3 Sheet Geometry

• 7.3.1 Sheet Geometry Functions
• 7.3.2 Sheet Geometry Classes
• Every sheet has a region and a coordinate system. A sheet's region refers to its position and extent on the display device, and is represented by some sort of a region object, frequently a rectangle. A sheet's coordinate system is represented by a coordinate transformation that converts coordinates in its coordinate system to coordinates in its parent's coordinate system. [annotate]

7.3.1 Sheet Geometry Functions

 sheet-transformation sheet [Generic Function]
 (setf sheet-transformation) transformation sheet [Generic Function]
 Returns a transformation that converts coordinates in the sheet sheet's coordinate system into coordinates in its parent's coordinate system. Using setf on this accessor will modify the sheet's coordinate system, including moving its region in its parent's coordinate system. [annotate]When the sheet's transformation is changed, note-sheet-transformation-changed is called on the to notify the sheet of the change. [annotate]
 sheet-region sheet [Generic Function]
 (setf sheet-region) region sheet [Generic Function]
 Returns a region object that represents the set of points to which the sheet sheet refers. The region is in the sheet's coordinate system. Using setf on this accessor modifies the sheet's region. [annotate]When the sheet's region is changed, note-sheet-region-region is called on sheet to notify the sheet of the change. [annotate]Note: s/note-sheet-region-region/note-sheet-region-changed/ -- Daniel Kochmanski 2018-03-16 12:33Z Minor issue: To reshape and move a region, you generally have to manipulate both of the above. Maybe there should be a single function that takes either or both of a new transformation or region? Maybe region coordinates should be expressed in parents' coordinates, since that's easier to set only one? --- RSL [annotate]Minor issue: I'm not convinced I like this business of requesting a change by modifying an accessor. It might be better to have a request- function, so it would be clear that there might be some delay before the region or transformation was modified. Currently, using setf on mirrored sheets requests that the server move or resize the sheet; the accessor will continue to return the old value until the notification comes in from the display server that says that the mirror has been moved. --- RSL [annotate]
 move-sheet sheet x y [Generic Function]
 Moves the sheet sheet to the new position (x,y). x and y are expressed in the coordinate system of sheet's parent. [annotate]move-sheet simply modifies sheet's transformation, and could be implemented as follows: [annotate](defmethod move-sheet ((sheet basic-sheet) x y) (let ((transform (sheet-transformation sheet))) (multiple-value-bind (old-x old-y) (transform-position transform 0 0) (setf (sheet-transformation sheet) (compose-translation-with-transformation transform (- x old-x) (- y old-y))))))
 resize-sheet sheet width height [Generic Function]
 Resizes the sheet sheet to have a new width width and a new height height. width and height are real numbers. [annotate]resize-sheet simply modifies sheet's region, and could be implemented as follows: [annotate](defmethod resize-sheet ((sheet basic-sheet) width height) (setf (sheet-region sheet) (make-bounding-rectangle 0 0 width height))) Note: This definition is wrong, since a bounding-rectangle is not a region. -- Gilbert Baumann 2013-03-15 16:39Z Note: We use make-bounding-rectangle, because we want region to have proper coordinates even if x1=x2 and/or y1=y2. If we'd use make-rectangle*, that would be demoted to +nowhere+ region. -- Daniel Kochmanski 2018-03-16 12:11Z
 move-and-resize-sheet sheet x y width height [Generic Function]
 Moves the sheet sheet to the new position (x,y), and changes its size to the new width width and the new height height. x and y are expressed in the coordinate system of sheet's parent. width and height are real numbers. [annotate]move-and-resize-sheet could be implemented as follows: [annotate](defmethod move-and-resize-sheet ((sheet basic-sheet) x y width height) (move-sheet sheet x y) (resize-sheet sheet width height))
 map-sheet-position-to-parent sheet x y [Generic Function]
 Applies the sheet sheet's transformation to the point (x,y), returning the coordinates of that point in sheet's parent's coordinate system. [annotate]
 map-sheet-position-to-child sheet x y [Generic Function]
 Applies the inverse of the sheet sheet's transformation to the point (x,y) (represented in sheet's parent's coordinate system), returning the coordinates of that same point in sheet coordinate system. [annotate]
 map-sheet-rectangle*-to-parent sheet x1 y1 x2 y2 [Generic Function]
 Applies the sheet sheet's transformation to the bounding rectangle specified by the corner points (x1,y1) and (x2,y2), returning the bounding rectangle of the transformed region as four values, min-x, min-y, max-x, and max-y. The arguments x1, y1, x2, and y1 are canonicalized in the same way as for make-bounding-rectangle. [annotate]
 map-sheet-rectangle*-to-child sheet x1 y1 x2 y2 [Generic Function]
 Applies the inverse of the sheet sheet's transformation to the bounding rectangle delimited by the corner points (x1,y1) and (x2,y2) (represented in sheet's parent's coordinate system), returning the bounding rectangle of the transformed region as four values, min-x, min-y, max-x, and max-y. The arguments x1, y1, x2, and y1 are canonicalized in the same way as for make-bounding-rectangle. [annotate]Minor issue: I now think that map- in these names is misleading; maybe convert- is better? --- SWM [annotate]
 map-over-sheets-containing-position function sheet x y [Generic Function]
 Applies the function function to all of the children of the sheet sheet that contain the position (x,y). x and y are expressed in sheet's coordinate system. [annotate]Function is a function of one argument, the sheet; it has dynamic extent. [annotate]
 map-over-sheets-overlapping-region function sheet region [Generic Function]
 Applies the function function to all of the children of the sheet sheet that overlap the region region. region is expressed in sheet's coordinate system. [annotate]Function is a function of one argument, the sheet; it has dynamic extent. [annotate]
 child-containing-position sheet x y [Generic Function]
 Returns the topmost enabled direct child of the sheet sheet whose region contains the position (x,y). The position is expressed in sheet's coordinate system. [annotate]
 children-overlapping-region sheet region [Generic Function]
 children-overlapping-rectangle* sheet x1 y1 x2 y2 [Generic Function]
 Returns the list of enabled direct children of the sheet sheet whose region overlaps the region region. children-overlapping-rectangle* is a special case of children-overlapping-region in which the region is a bounding rectangle whose corner points are (x1,y1) and (x2,y2). The region is expressed in sheet's coordinate system. This function returns fresh objects that may be modified. [annotate]
 sheet-delta-transformation sheet ancestor [Generic Function]
 Returns a transformation that is the composition of all of the sheet transformations between the sheets sheet and ancestor. If ancestor is nil, sheet-delta-transformation will return the transformation to the root of the sheet hierarchy. If ancestor is not an ancestor of sheet, the sheet-is-not-ancestor error will be signalled. [annotate]The computation of the delta transformation is likely to be cached. [annotate]
 sheet-allocated-region sheet child [Generic Function]
 Returns the visible region of the sheet child in the sheet sheet's coordinate system. If child is occluded by any of its siblings, those siblings' regions are subtracted (using region-difference) from child's actual region. [annotate]

7.3.2 Sheet Geometry Classes

Each of the following implements the sheet geometry protocol in a different manner, according to the sheet's requirements. None of the four following classes is instantiable. [annotate]

 sheet-identity-transformation-mixin [Class]
 This class is mixed into sheet classes whose coordinate system is identical to that of its parent. [annotate]
 sheet-translation-mixin [Class]
 This class is mixed into sheet classes whose coordinate system is related to that of its parent by a simple translation. [annotate]
 sheet-y-inverting-transformation-mixin [Class]
 This class is mixed into sheet classes whose coordinate system is related to that of its parent by inverting the y coordinate system, and optionally translating by some amount in x and y. [annotate]
 sheet-transformation-mixin [Class]
 This class is mixed into sheet classes whose coordinate system is related to that of its parent by an arbitrary affine transformation. CLIM implementations are allowed to restrict these transformations to just rectilinear ones. [annotate]