drawing-object is the root class for drawing objects, which are used to create hierarchies of drawings. The hierarchy is made of compound-drawing-object objects, which group other drawing objects and affect their geometry, lists of drawing-objects, and leaf drawing objects (currently apply-drawing-object and string-drawing-object), which actually do the drawing.
drawing-object is part of the hierarchy when it is in the
slot of an objects-displayer or a pinboard-objects-displayer, or it is inside a list which is in a hierarchy, or it is in the
slot of a compound-drawing-object. The root of the hierarchy is always an objects-displayer or a pinboard-objects-displayer. A node in the hierarchy (except the root) is either a
drawing-object or a list, which is collectively called "drawing-object-spec". In a list all the elements must be "drawing-object-specs".
drawing-objects is always done top-down: the root object draws its
. Typically this is either a compound-drawing-object or a list, which will draw their
or elements respectively. Each object which is a geometry-drawing-object does something to the geometry, that is set up some Graphics Ports transformation, and then draw all its objects inside this context. For lists the elements are drawn in the same context in which the list is drawn. Leaf
drawing-objects actually draw something.
When the drawing operation reaches a
drawing-object, it is because it is inside the hierarchy inside a compound-drawing-object or directly inside the hierarchy under an objects-displayer or a pinboard-objects-displayer. This compound-drawing-object, objects-displayer or pinboard-objects-displayer is the "parent" of the
drawing-object for this drawing operation, and determines its geometry. During the drawing operation there is also the "root" (the objects-displayer or pinboard-objects-displayer from which the drawing started), and the "root pane" (the objects-displayer when the root is an objects-displayer, or the pane of the pinboard-objects-displayer).
Note that "parent", "root" and "root pane" of a
drawing-object are transient concepts, and are applicable only inside the context of a drawing operation of the
drawing-object. The same
drawing-object may be drawn many times, with (potentially) different "parent", "root" and "root pane". It can be even drawn concurrently with different "root panes".
CAPI User Guide and Reference Manual (Unix version) - 3 Aug 2017