clipping-box

Function

Package: common-graphics

Arguments: stream

This function and the related nclipping-box returns two values. The first is a box representing the current clipping box of stream relative to the current origin. stream may not be a text-edit-window or a text-edit-pane.

The second returned value, which is one of the symbols :simple, :complex, or nil, indicates which type of clipping region the window currently has. :simple means that box returned as the first value exactly describes the clipping region. :complex means that the box encompasses a non-rectangular clipping region; Common Graphics does not provide any further information about this region however. nil means that the clipping region is empty (of size zero) and so nothing can be drawn on the stream currently; in this case the first return value is the box (0 0 0 0), though the arbitrary "position" of this box at (0 0) is not meaningful.

Note that the box returned (as the first value) is not merely the value that may have been set by a call to (setf clipping-box) or with-clipping-box; it also reflects how the window is partly or fully covered by other windows and how it is scrolled. Specifically, the returned box is the smallest box containing the currently visible parts of the window's interior (in stream units), intersected with the box most recently specified by a call to (setf clipping-box) or with-clipping-box, if any. A window whose interior is completely covered will always return the box (0 0 0 0) and a second value of nil to indicate a currently empty clipping region.

While the function (setf clipping-box) and the macro with-clipping-box are often useful for establishing a clipping region, applications generally are not expected to have a need to call clipping-box or nclipping-box to retrieve the current region. The functions are not reliable for recalling the region that was explicitly set, since the returned box is also affected by how the window is covered. Furthermore, all drawing code for a window (other than a bitmap-pane) normally should be placed within a redisplay-window method, which always receives a box argument denoting the area that needs to be redisplayed, and the clipping-box of the window is set to this box automatically during the call to redisplay-window.

setf may be used with this function to set the clipping box. (Doing so actually calls the function (setf clipping-box).)

Note: incompatible change in release 6.0: in releases prior to 6.0, when a frame-with-single-child instance was passed to this operator, the operator was actually applied to the child (the result of applying frame-child to the frame-with-single-child instance). In release 6.0, this redirection no longer occurs. If you intend this operator to apply to the frame-child, pass that to this operator rather than the parent. This is a non-backward-compatible-change. See the release notes for more information.

Common Graphics and IDE documentation is described in About Common Graphics and IDE documentation in cgide.htm.

The documentation is described in introduction.htm and the index is in index.htm.

Created 2000.10.5.