section-box

Arguments: top-pane parent-section section &optional include-border-p box

Returns a box indicating where a grid section lies on the grid widget window, clipped according to grid boundaries and section boundaries.

When the specified section or subsection is scrolled completely out of view, this function returns a box whose box-width and/or box-height is negative. We regard this as a design bug and plan to change it in a future release to return nil in that case. In the meantime, an application needs to check for this itself. Also, the parameters of this function are not as convenient as they should be for a user function, and may change in a future release.

top-pane is the widget-window of a grid-widget, as returned by calling window on the widget.

parent-section is the parent of the section whose box is being returned. For a grid-row this is its grid-row-section, for a grid-column this is its grid-column-section, and for a grid-row-section or grid-column-section this is the grid-widget itself. (In all cases this object is returned by calling parent on the section argument.)

section is the section whose box is being returned. This should be either a grid-row-section, grid-column-section, grid-row, or grid-column.

If include-border-p is true, then the area occupied by the border line at the right or bottom edge of the section is included in the returned box. Otherwise it is excluded.

box may be either a box (see make-box) or nil. If a box, then that box is modified and returned. If nil, a new box object is created and returned. Passing a scratch box avoids consing one that must be garbage collected.

See also cross-section-box and invalidate-whole-section.

Copyright (c) 1998-2009, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had moderate revisions compared to the 8.0 page.
Created 2007.4.30.