All Manuals > CAPI User Guide and Reference Manual > 3 General Properties of CAPI Panes

3.7 Hierarchy of panes

Every element that is displayed has a parent, which you can find by the element accessor element-parent. The ultimate ancestor is a screen, which you can find by element-screen. The element is inside some window which is associated with a CAPI interface instance (that is, an instance of subclass of interface) which is called the "top level interface" and can be found by by top-level-interface. Note that inside MDI on Microsoft Windows the top level interface is the one inside the MDI, rather than the enclosing MDI window. You can test whether an object is a top level interface by top-level-interface-p. The function element-container returns the parent of the top level interface, that is the screen outside the MDI, but the document-frame inside the MDI.

Some elements have children. You can operate on the children of an element by using map-pane-children or map-pane-descendant-children. These functions will work on any element, and they will do nothing for elements without children.

The implementation of the panes you specify may internally involve generating more panes, and element-parent, map-pane-children and map-pane-descendant-children will find these. Thus when using these functions you cannot assume that you know the hierarchy, and you need to check if the pane that you got is the right one. For example, if you create a layout like this:

(setq layout
      (make-instance 'capi:row-layout
(list (make-instance 'capi:list-panel))))

then doing something like:

(capi:map-pane-children layout
        #'(lambda (pane) (setf (capi:collection-items pane) nil)

may not work, because the list panel may not be a direct child of the layout. In most cases it is best to record the actual panes so you know where to access them (most commonly in a slot in the interface). Alternatively you can use map-pane-descendant-children with a function that checks each child pane before operating on it.

Note that all these functions give useful results only for displayed elements.

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