clipping-box

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 should be a cg-stream but 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.

An application may call (setf clipping-box) at any time to set the current clipping-box of a Common Graphics stream. The value argument may be either a box to establish clipping, or else nil to remove all clipping. The macro with-clipping-box is a handy alternative because it guarrantees that the original clipping-box will be restored after its body executes.

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.

Platform note: the box that is returned will exclude any part of the window that happens to be covered by other windows on the Microsoft Windows platform, but will not exclude these areas on GTK. Also, the second return value will never be :complex on GTK.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.