All Manuals > CAPI User Guide and Reference Manual > 23 LW-GT Reference Entries






rotate-object Functions


Create a geometry-drawing-object, where the sub-object is the drawing-object.




fit-object drawing-object intended-width intended-height &key data function => geometry-drawing-object

make-absolute-drawing &rest drawing-objects => geometry-drawing-object

make-absolute-drawing* drawing-objects => geometry-drawing-object

position-object drawing-object &key left-margin left-ratio right-margin right-ratio top-margin top-ratio bottom-margin bottom-ratio data function => geometry-drawing-object

position-and-fit-object drawing-object intended-width intended-height &key left-margin left-ratio right-margin right-ratio top-margin top-ratio bottom-margin bottom-ratio data function => geometry-drawing-object

rotate-object drawing-object angle &key left-margin left-ratio bottom-margin bottom-ratio data function => geometry-drawing-object

A "drawing-object-spec".
intended-width, intended-height
Real numbers or nil.
Any Lisp object.
A function designator or nil.
A list of "drawing-object-specs".
left-margin, left-ratio
Real numbers or nil.
right-margin, right-ratio
Real numbers or nil.
top-margin, top-ratio
Real numbers or nil.
bottom-margin, bottom-ratio
Real numbers or nil.
A real number or nil.

The functions fit-object, make-absolute-drawing, make-absolute-drawing*, position-object, position-and-fit-object and rotate-object are the "geometry" functions. Each creates a geometry-drawing-object, where the sub-object slot contains drawing-object.

Each drawing-object argument must be a "drawing-object-spec", which means either an instance of (a subclass of) drawing-object or a list of "drawing-object-specs".


When drawing, the geometry-drawing-object created by position-object computes its own position and size based on the keyword arguments and the position and size of its parent (see drawing-object for the meaning of "parent"). It then establishes a Graphics Ports translation to translate from its parent's left/bottom corner to its own left/bottom corner, and draws its sub-object.

left-margin, left-ratio, right-margin, right-ratio, top-margin, top-ratio, bottom-margin and bottom-ratio specify how to compute the left, right, bottom and top of the positioning object with respect to its parent. For each side, the value is computed by multiplying the ratio by the relevant dimension (width for left and right, height for top and bottom), and then add (for left and bottom) or subtract (for right and top) the margin. Note that the vertical coordinate is 0 at the bottom and increases towards the top.

The default values of right-ratio and top-ratio are 1, and the default values of all the other keyword arguments are 0, making it compute the same position and size as the parent.

  1. The width and height of a positioning object are not used explicitly, but will be used by any child object that is itself a geometry-drawing-object.
  2. A positioning geometry-drawing-object does not cause any scaling.
  3. Calling position-object without passing right and top values is a useful way to just shift objects around, but the resulting width and height are probably not useful. If drawing-object contains drawing objects that need the width and height (result of fit-object, position-and-fit-object, or rotate-object), you probably need to set the right and top too.

When drawing, the geometry-drawing-object created by fit-object computes scaling factors for the horizontal and vertical dimensions by dividing its width and height, which it inherits from its parent, by its intended-width and intended-height. It then establishes a Graphics Ports scaling transformation with these factors, and draws its sub-object.


position-and-fit-object creates a drawing-object that performs the equivalent of using position-object with the result of calling fit-object with drawing-object. In other words, it first positions and then fits.


When drawing, the geometry-drawing-object created by rotate-object computes the transform for rotating the object by angle radians around the point specified by the keyword arguments (default to left-bottom corner). left-margin, left-ratio, bottom-margin and bottom-ratio are used to compute the center of rotation, using the same algorithm as in position-object.

rotate-object does not affect the width and height of the drawing, but since the drawing itself is rotated, the direction in which the width and height apply are rotated too. For example, if you rotate by pi/2, the width is in the vertical dimension on the screen.

make-absolute-drawing and make-absolute-drawing*

make-absolute-drawing and make-absolute-drawing* create an object that displays drawing-objects in "absolute mode", which means drawing without scaling or rotation, but still taking account of the translation. When using a metafile, the absolute drawing is into the metafile. When the metafile is drawn, it normally scales and this scales everything, including absolute drawings.

  1. Inside the "absolute" scope, the y increases downwards rather than upwards.
  2. An example where absolute drawing is useful is drawing of strings and some associated drawing-objects inside a larger object, where you want to allow the larger object to scale and rotate and the strings displayed in the correct place, but you want the strings to be upright and optimal size for readability.
data and function

data argument can be anything, and is stored in the geometry-drawing-object, and can be accessed by compound-drawing-object-data. It can be used to keep arbitrary data, and is also used by compute-drawing-object-from-data.

function is used by compute-drawing-object-from-data only. See compute-drawing-object-from-data.

geometry-drawing-object objects can be used repeatedly and concurrently in the same or different panes. The sub-object can be changed dynamically by using (setf compound-drawing-object-sub-object) from any thread, but if it is already being displayed, you will need to ensure that they are redrawn. See force-objects-redraw.

See also

14.1 Lower level - drawing objects and objects displayers

CAPI User Guide and Reference Manual (Macintosh version) - 01 Dec 2021 19:31:48