| Allegro CL version 6.2 Minimally revised from 6.1 |
Arguments: stream box
Modifies and returns box (as the first of two
returned values) to be the clipping box of
stream. 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.
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.
Contrast with clipping-box, which does not take a box argument and returns a new box object.
Copyright (c) 1998-2002, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 6.2. This page has had minimal revisions compared to the 6.1 page.
Created 2002.2.26.
| Allegro CL version 6.2 Minimally revised from 6.1 |