*
Region composition*
in CLIM is the process in which two regions are combined in some way (such as union or intersection) to produce a third region.

Since all regions in CLIM are closed, region composition is not always equivalent to simple set operations. Instead, composition attempts to return an object that has the same dimensionality as one of its arguments. If this is not possible, then the result is defined to be an empty region, which is canonicalized to +nowhere+ . (The exact details of this are specified with each function.)

Sometimes composition of regions can produce a result that is not a simple contiguous region. For example,
region-union
of two rectangular regions might not be rectangular. In order to support cases like this, CLIM has the concept of a *
region set*
, an object that represents one or more region objects related by some region operation, usually a union.

region-set [Protocol Class]

Summary: The protocol class that represents a region set; a subclass of region and bounding-rectangle .

Members of this class are immutable.

region-set-p [Function]

Summary: Returns
t
if *
object*
is a region set; otherwise, it returns
nil
.

Summary: This instantiable subclass of region-set and bounding-rectangle represents the union of several axis-aligned rectangles.

Summary: These three instantiable classes respectively implement the union, intersection, and differences of regions.

Region sets that are composed entirely of axis-aligned rectangles must be canonicalized into either a single rectangle or a union of rectangles. Furthermore, the rectangles in the union must not overlap each other.

The following generic functions comprise the region composition protocol. All classes that are subclasses of region must implement methods for these generic functions.

The methods for
region-union
,
region-intersection
, and
region-difference
will typically specialize both the *
region1*
and *
region2*
arguments.

region-set-regions [Generic Function]

Arguments: region ```
&key
```

normalize

Summary: Returns a sequence of the regions in the region set *
region*
. *
region*
can be either a region set or a "simple" region, in which case the result is simply a sequence of one element: *
region*
.

This function returns objects that reveal CLIM's internal state; do not modify these objects.

For the case of region sets that are unions of axis-aligned rectangles, the rectangles returned by region-set-regions are guaranteed not to overlap.

If *
normalize*
is supplied, it must be either
:x-banding
or
:y-banding
. If it is
:x-banding
and all the regions in *
region*
are axis-aligned rectangles, the result is normalized by merging adjacent rectangles with banding done in the *
x*
direction. If it is
:y-banding
and all the regions in *
region*
are rectangles, the result is normalized with banding done in the *
y*
direction. Normalizing a region set that is not composed entirely of axis-aligned rectangles using x- or y-banding causes CLIM to signal the
region-set-not-rectangular
error.

map-over-region-set-regions [Generic Function]

Arguments: function region ```
&key
```

normalize

Summary: Calls *
function*
on each region in the region set *
region*
. This is often more efficient than calling
region-set-regions
. *
function*
is a function of one argument, a region; it has dynamic extent. *
region*
can be either a region set or a "simple" region, in which case *
function*
is called once on *
region*
itself. *
normalize*
is as for
region-set-regions
.

region-union [Generic Function]

Summary: Returns a region that contains all points that are in either of the regions *
region1*
or *
region2*
(possibly with some points removed in order to satisfy the dimensionality rule). The result of
region-union
always has dimensionality that is the maximum dimensionality of *
region1*
and *
region2*
. For example, the union of a path and an area produces an area; the union of two paths is a path.

region-union will return either a simple region or a member of the class standard-region-union .

This function captures its mutable inputs; the consequences of modifying those objects are unspecified.

region-intersection [Generic Function]

Summary: Returns a region that contains all points that are in both of the regions *
region1*
and *
region2*
(possibly with some points removed in order to satisfy the dimensionality rule). The result of
region-intersection
has dimensionality that is the minimum dimensionality of *
region1*
and *
region2*
, or is
+nowhere+
. For example, the intersection of two areas is either another area or
+nowhere+
; the intersection of two paths is either another path or
+nowhere+
; the intersection of a path and an area produces the path clipped to stay inside of the area.

region-intersection will return either a simple region or a member of the class standard-region-intersection .

This function captures its mutable inputs; the consequences of modifying those objects are unspecified.

region-difference [Generic Function]

Summary: Returns a region that contains all points in the region *
region1*
that are not in the region *
region2*
(possibly plus additional boundary points to make the result closed). The result of
region-difference
has the same dimensionality as *
region1*
, or is
+nowhere+
. For example, the difference of an area and a path produces the same area; the difference of a path and an area produces the path clipped to stay outside of the area.

region-difference will return either a simple region, a region set, or a member of the class standard-region-difference .

This function captures its mutable inputs; the consequences of modifying those objects are unspecified.

CommonLisp Interface Manager 2.0 User's Guide - 18 Mar 2005