A region is an object that denotes a set of points in the plane. Regions include their boundaries; that is, they are closed. Regions have infinite resolution.
A bounded region is a region that contains at least one point for which there exists a number, d, called the region's diameter, such that if p1 and p2 are points in the region, the distance between p1 and p2 is always less than or equal to d.
An unbounded region either contains no points or contains points arbitrarily far apart. +nowhere+ and +everywhere+ are examples of unbounded regions.
Another way to describe a region is to say that it maps every (x, y) pair into either true or false (meaning member or not a member, respectively, of the region). Later, in Chapter 5, we will generalize a region to something called an ink that maps every point (x, y) into color and opacity values.
CLIM classifies the various types of regions in the following way. All regions are a subclass of region, and all bounded regions are also a subclass of either point, path, or area, as shown in The Class Structure for All Regions.
Summary: The protocol class that corresponds to a set of points. This includes both bounded and unbounded regions. This is a subclass of ink (see 5 Drawing in Color for details).
If you want to create a new class that behaves like a region, it should be a subclass of region. Subclasses of region must obey the region protocol.
There is no general constructor called make-region because of the impossibility of a uniform way to specify the arguments to such a function.
regionp object
Summary: Returns t if object is a region; otherwise, it returns nil.
Summary: The protocol class path denotes bounded regions that have dimensionality 1 (that is, lines or curves). It is a subclass of region and bounding-rectangle. If you want to create a new class that behaves like a path, it should be a subclass of path. Subclasses of path must obey the path protocol.
Constructing a path object with no length (via make-line*, for example) canonicalizes it to +nowhere+.
Some rendering models support the constructing of areas by filling a closed path. In this case, the path needs a direction associated with it. Since CLIM does not currently support the path-filling model, paths are directionless.
pathp object
Summary: Returns t if object is a path; otherwise, it returns nil.
Note that constructing a path object with no length (by calling make-line with two coincident points, for example) canonicalizes it to +nowhere+.
Summary: The protocol class area denotes bounded regions that have dimensionality 2 (that is, are flat surfaces). It is a subclass of region and bounding-rectangle. If you want to create a new class that behaves like an area, it should be a subclass of area. Subclasses of area must obey the area protocol.
Note that constructing an area object with no area (by calling make-rectangle with two coincident points, for example) canonicalizes it to +nowhere+.
areap object
Summary: Returns t if object is an area; otherwise, it returns nil.
Summary: The type that represents a coordinate. All of the specific region classes and subclasses of bounding-rectangle will use this type to store their coordinates. However, the constructor functions for the region classes and for bounding rectangles accept numbers of any type and coerce them to coordinate.
The following two constants represent the regions that correspond, respectively, to all of the points on the drawing plane and to none of the points on the drawing plane.
Summary: The region that includes all the points on the infinite drawing plane.
Summary: The empty region (the opposite of +everywhere+).
The following generic functions comprise the region predicate protocol. All classes that are subclasses of region must either inherit or implement methods for these generic functions.
The methods for region-equal, region-contains-region-p, and region-intersects-region-p will typically specialize both the region1 and region2 arguments.
region-equal region1 region2
Summary: Returns t if the two regions region1 and region2 contain exactly the same set of points; otherwise, it returns nil.
region-contains-region-p Generic Function
region-contains-region-p region1 region2
Summary: Returns t if all points in the region region2 are members of the region region1; otherwise, it returns nil.
region-contains-position-p Generic Function
region-contains-position-p region x y
Summary: Returns t if the point at (x, y) is contained in the region region; otherwise, it returns nil. Since regions in CLIM are closed, this must return t if the point at (x, y) is on the region's boundary.
region-contains-position-p is a special case of region-contains-region-p in which the region is the point (x, y).
region-intersects-region-p Generic Function
region-intersects-region-p region1 region2
Summary: Returns nil if region-intersection of the two regions region1 and region2 would be +nowhere+; otherwise, it returns t.
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.
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 object
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.
standard-region-union
standard-region-intersection
standard-region-difference Classes
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
region-set-regions 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.
Note: 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
map-over-region-set-regions 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 region1 region2
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
region-intersection region1 region2
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
region-difference region1 region2
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.
A point is a mathematical point in the drawing plane that is identified by its coordinates, a pair of real numbers. Points have neither area nor length. Note that a point is not the same thing as a pixel; CLIM's model of the drawing plane has continuous coordinates.
You can create point objects and use them as arguments to the drawing functions. Alternatively, you can use the spread versions of the drawing functions, that is, the drawing functions with stars appended to their names. For example, instead of draw-point, use draw-point*, which takes two arguments specifying a point by its coordinates. (Note that, for performance reasons, we generally recommend the use of the spread versions.)
The operations for creating and dealing with points are:
Summary: The protocol class that corresponds to a mathematical point. This is a subclass of region and bounding-rectangle. If you want to create a new class that behaves like a point, it should be a subclass of point. Subclasses of point obey the point protocol.
pointp object
Summary: Returns t if object is a point; otherwise, it returns nil.
Summary: An instantiable class that implements a point. This is a subclass of point. This is the class that make-point instantiates. Members of this class are immutable.
make-point x y
Summary: Returns an object of class standard-point whose coordinates are x and y. x and y must be real numbers.
The following generic functions comprise the point Application Programmer Interface. Only point-position is in the point protocol; that is, all classes that are subclasses of point must implement methods for point-position, but need not implement methods for point-x and point-y.
point-position Generic Function
point-position point
Summary: Returns both the x and y coordinates of the point point as two values.
point-x point
point-y point
Summary: Returns the x or y coordinate of the point point, respectively. CLIM will supply default methods for point-x and point-y on the protocol class point that are implemented by calling point-position.
A polyline is a path that consists of one or more line segments joined consecutively at their end-points. A line is a polyline that has only one segment.
Polylines that have the end-point of their last line segment coincident with the start-point of their first line segment are called closed; this use of the term "closed" should not be confused with closed sets of points.
A polygon is an area bounded by a closed polyline.
If the boundary of a polygon intersects itself, the odd-even winding-rule defines the polygon: a point is inside the polygon if a ray from the point to infinity crosses the boundary an odd number of times.
Polylines and polygons are closed under affine transformations.
The classes that correspond to polylines and polygons are:
Summary: The protocol class that corresponds to a polyline. It is a subclass of path. If you want to create a new class that behaves like a polyline, it should be a subclass of polyline. Subclasses of polyline must obey the polyline protocol.
polylinep object
Summary: Returns t if object is a polyline; otherwise, it returns nil.
Summary: The protocol class (a subclass of area) that corresponds to a mathematical polygon. If you want to create a new class that behaves like a polygon, it should be a subclass of polygon. Subclasses of polygon must obey the polygon protocol.
polygonp object
Summary: Returns t if object is a polygon; otherwise, it returns nil.
Summary: A class that implements a polyline. This is a subclass of polyline. This is the class that make-polyline and make-polyline* instantiate. Members of this class are immutable.
Summary: A class that implements a polygon. This is a subclass of polygon. This is the class that make-polygon and make-polygon* instantiate. Members of this class are immutable.
The following functions can be used to create polylines and polygons:
make-polyline point-seq &key closed
make-polyline* coord-seq &key closed
Summary: Returns an object of class standard-polyline consisting of the segments connecting each of the points in point-seq (or the points represented by the coordinate pairs in coord-seq).
If closed is t, then the segment connecting the first point and the last point is included in the polyline. The default for closed is nil.
These functions capture their mutable inputs; the consequences of modifying those objects are unspecified.
make-polygon point-seq
make-polygon* coord-seq
Summary: Returns an object of class standard-polygon consisting of the area contained in the boundary that is specified by the segments connecting each of the points in point-seq (or the points represented by the coordinate pairs in coord-seq).
These functions capture their mutable inputs; the consequences of modifying those objects are unspecified.
The following generic functions comprise the polygon and polyline protocol. All classes that are subclasses of polygon or polyline must implement methods for them. Some of the functions take an argument polygon-or-polyline, which may be a polygon or a polyline.
polygon-points Generic Function
polygon-points polygon-or-polyline
Summary: Returns a sequence of points that specify the segments in polygon-or-polyline. This function returns objects that reveal CLIM's internal state; do not modify those objects.
map-over-polygon-coordinates Generic Function
map-over-polygon-coordinates function polygon-or-polyline
Summary: Applies function to all of the coordinates of the vertices of polygon-or-polyline. function is a function of two arguments, the x and y coordinates of the vertex; it has dynamic extent.
map-over-polygon-segments Generic Function
map-over-polygon-segments function polygon-or-polyline
Summary: Applies function to the segments that compose polygon-or-polyline. function is a function of four arguments, the x and y coordinates of the start of the segment, and the x and y coordinates of the end of the segment; it has dynamic extent. When map-over-polygon-segments is called on a closed polyline, it will call function on the segment that connects the last point back to the first point.
polyline-closed Generic Function
polyline-closed polyline
Summary: Returns t if the polyline polyline is closed; otherwise, it returns nil.
A line is a special case of a polyline having only one segment. The functions for making and dealing with lines are the following:
Summary: The protocol class that corresponds to a mathematical line segment, that is, a polyline with only a single segment. This is a subclass of polyline. If you want to create a new class that behaves like a line, it should be a subclass of line. Subclasses of line must obey the line protocol.
linep object
Summary: Returns t if object is a line; otherwise, it returns nil.
Summary: An instantiable class that implements a line segment. This is a subclass of line. This is the class that make-line and make-line* instantiate. Members of this class are immutable.
make-line start-point end-point
make-line* start-x start-y end-x end-y
Summary: Returns an object of class standard-line that connects the two points start-point and end-point, or the positions (start-x, start-y) and (end-x, end-y).
These functions capture their mutable inputs; the consequences of modifying those objects are unspecified.
The following generic functions comprise the line Application Programmer Interface. Only line-start-point* and line-end-point* are in the line protocol; that is, all classes that are subclasses of line must implement methods for line-start-point* and line-end-point*, but need not implement methods for line-start-point and line-end-point.
line-start-point* Generic Function
line-start-point* line
line-end-point* Generic Function
line-end-point* line
Summary: Returns the starting or ending point, respectively, of the line line as two real numbers representing the coordinates of the point.
line-start-point Generic Function
line-start-point line
line-end-point Generic Function
line-end-point line
Summary: Returns the starting or ending point of the line line, respectively.
CLIM will supply default methods for line-start-point and line-end-point on the protocol class line that are implemented by calling line-start-point* and line-end-point*.
A rectangle is a special case of a four-sided polygon whose edges are parallel to the coordinate axes. A rectangle can be specified completely by four real numbers (min-x, min-y, max-x, max-y). They are not closed under affine transformations, although they are closed under rectilinear transformations. CLIM uses rectangles extensively for various purposes, particularly in optimizations.
The functions for creating and dealing with rectangles are the following:
Summary: The protocol class that corresponds to a mathematical rectangle, that is, a rectangular polygons whose sides are parallel to the coordinate axes. This is a subclass of polygon. If you want to create a new class that behaves like a rectangle, it should be a subclass of rectangle. Subclasses of rectangle must obey the rectangle protocol.
rectanglep object
Summary: Returns t if object is a rectangle; otherwise, it returns nil.
Summary: An instantiable class that implements an axis-aligned rectangle. This is a subclass of rectangle. This is the class that make-rectangle and make-rectangle* instantiate. Members of this class are immutable.
make-rectangle point1 point2
make-rectangle* x1 y1 x2 y2
Summary: Returns an object of class standard-rectangle whose edges are parallel to the coordinate axes. One corner is at the point point1, or the position (x1, y1), and the opposite corner is at the point point2, or the position (x2, y2). There are no ordering constraints among point1 and point2 (or x1 and x2, and y1 and y2).
This function captures its mutable inputs; the consequences of modifying those objects are unspecified.
The following generic functions comprise the rectangle Application Programmer Interface. Only rectangle-edges* is in the rectangle protocol; that is, all classes that are subclasses of rectangle must implement methods for rectangle-edges*, but need not implement methods for the remaining functions.
rectangle-edges* Generic Function
rectangle-edges* rectangle
Summary: Returns the coordinates of the minimum x and y and maximum x and y of the rectangle rectangle as four values, min-x, min-y, max-x, and max-y.
rectangle-min-point Generic Function
rectangle-min-point rectangle
rectangle-max-point Generic Function
rectangle-max-point rectangle
Summary: Returns the min point and max point of the rectangle rectangle, respectively. The position of a rectangle is specified by its min point.
CLIM supplies default methods for rectangle-min-point and rectangle-max-point on the protocol class rectangle that are implemented by calling rectangle-edges*.
rectangle-min-x Generic Function
rectangle-min-x rectangle
rectangle-min-y Generic Function
rectangle-min-y rectangle
rectangle-max-x Generic Function
rectangle-max-x rectangle
rectangle-max-y Generic Function
rectangle-max-y rectangle
Summary: Returns (respectively) the minimum x and y coordinate and maximum x and y coordinate of the rectangle rectangle.
CLIM supplies default methods for these four generic functions on the protocol class rectangle that are implemented by calling rectangle-edges*.
rectangle-width Generic Function
rectangle-width rectangle
rectangle-height Generic Function
rectangle-height rectangle
rectangle-size Generic Function
rectangle-size rectangle
Summary: rectangle-width returns the width of the rectangle rectangle, which is the difference between its maximum and minimum x values. rectangle-height returns the height, which is the difference between its maximum and minimum y values. rectangle-size returns two values, the width and the height.
CLIM supplies default methods for these four generic functions on the protocol class rectangle that are implemented by calling rectangle-edges*.
An ellipse is an area that is the outline and interior of an ellipse. Circles are special cases of ellipses.
An elliptical arc is a path consisting of all or a portion of the outline of an ellipse. Circular arcs are special cases of elliptical arcs.
An ellipse is specified in a manner that is easy to transform, and treats all ellipses on an equal basis. An ellipse is specified by its center point and two vectors that describe a bounding parallelogram of the ellipse. The bounding parallelogram is made by adding and subtracting the vectors from the center point in the following manner:
The special case of an ellipse with its axes aligned with the coordinate axes can be obtained by setting dx2 and dy1 to 0, or setting dx1 and dy2 to 0.
Note that several different parallelograms specify the same ellipse, as shown here:
One parallelogram is bound to be a rectangle—the vectors will be perpendicular and correspond to the semi-axes of the ellipse.
The following classes and functions are used to represent and operate on ellipses and elliptical arcs.
Summary: The protocol class that corresponds to a mathematical ellipse. This is a subclass of area. If you want to create a new class that behaves like an ellipse, it should be a subclass of ellipse. Subclasses of ellipse must obey the ellipse protocol.
ellipsep object
Summary: Returns t if object is an ellipse; otherwise, it returns nil.
Summary: An instantiable class that implements an ellipse. This is a subclass of ellipse. This is the class that make-ellipse and make-ellipse* instantiate. Members of this class are immutable.
Summary: The protocol class that corresponds to a mathematical elliptical arc. This is a subclass of path. If you want to create a new class that behaves like an elliptical arc, it should be a subclass of elliptical-arc. Subclasses of elliptical-arc must obey the elliptical arc protocol.
elliptical-arc-p object
Summary: Returns t if object is an elliptical arc; otherwise, it returns nil.
Summary: An instantiable class that implements an elliptical arc. This is a subclass of elliptical-arc. This is the class that make-elliptical-arc and make-elliptical-arc* instantiate. Members of this class are immutable.
make-ellipse center-point radius-1-dx radius-1-dy radius-2-dx radius-2-dy &key start-angle end-angle
make-ellipse* center-x center-y radius-1-dx radius-1-dy radius-2-dx radius-2-dy &key start-angle end-angle
Summary: Returns an object of class standard-ellipse. The center of the ellipse is at the point center-point, or the position (center-x, center-y).
Two vectors, (radius-1-dx, radius-1-dy) and (radius-2-dx, radius-2-dy) specify the bounding parallelogram of the ellipse as explained previously. All of the radii are real numbers. If the two vectors are collinear, the ellipse is not well-defined and the ellipse-not-well-defined error will be signaled. The special case of an ellipse with its axes aligned with the coordinate axes can be obtained by setting both radius-1-dy and radius-2-dx to 0.
If start-angle or end-angle are supplied, the ellipse is the "pie slice" area swept out by a line from the center of the ellipse to a point on the boundary as the boundary point moves from the angle start-angle to end-angle. Angles are measured counter-clockwise with respect to the positive x axis. If end-angle is supplied, the default for start-angle is 0; if start-angle is supplied, the default for end-angle is 2π; if neither is supplied, then the region is a full ellipse and the angles are meaningless.
This function captures its mutable inputs; the consequences of modifying those objects are unspecified.
make-elliptical-arc center-point radius-1-dx radius-1-dy radius-2-dx radius-2-dy &key start-angle end-angle
make-elliptical-arc* center-x center-y radius-1-dx radius-1-dy radius-2-dx radius-2-dy &key start-angle end-angle
Summary: Returns an object of class standard-elliptical-arc. The center of the ellipse is at the point center-point, or the position (center-x, center-y).
Two vectors, (radius-1-dx, radius-1-dy) and (radius-2-dx, radius-2-dy), specify the bounding parallelogram of the ellipse as explained previously. All of the radii are real numbers. If the two vectors are collinear, the ellipse is not well-defined and the ellipse-not-well-defined error will be signaled. The special case of an elliptical arc with its axes aligned with the coordinate axes can be obtained by setting both radius-1-dy and radius-2-dx to 0.
If start-angle and start-angle are supplied, the arc is swept from start-angle to end-angle. Angles are measured counter-clockwise with respect to the positive x axis. If end-angle is supplied, the default for start-angle is 0; if start-angle is supplied, the default for end-angle is 2π; if neither is supplied, then the region is a closed elliptical path and the angles are meaningless.
This function captures its mutable inputs; the consequences of modifying those objects are unspecified.
The following functions apply to both ellipses and elliptical arcs. In all cases, the name elliptical-object means that the argument may be an ellipse or an elliptical arc. These generic functions comprise the ellipse protocol. All classes that are subclasses of either ellipse or elliptical-arc must implement methods for these functions.
ellipse-center-point* Generic Function
ellipse-center-point* elliptical-object
Summary: Returns the center point of elliptical-object as two values representing the coordinate pair.
ellipse-center-point Generic Function
ellipse-center-point elliptical-object
Summary: Returns the center point of elliptical-object.
ellipse-center-point is part of the ellipse Application Programmer Interface, but not part of the ellipse protocol. CLIM will supply default methods for ellipse- center-point on the protocol classes ellipse and elliptical-arc that are implemented by calling ellipse-center-point*.
ellipse-radii Generic Function
ellipse-radii elliptical-object
Summary: Returns four values corresponding to the two radius vectors of elliptical-arc. These values may be canonicalized in some way, and so may not be the same as the values passed to the constructor function.
ellipse-start-angle Generic Function
ellipse-start-angle elliptical-object
Summary: Returns the start angle of elliptical-object. If elliptical-object is a full ellipse or closed path, then ellipse-start-angle will return nil; otherwise the value will be a number greater than or equal to zero, and less than 2π.
ellipse-end-angle Generic Function
ellipse-end-angle elliptical-object
Summary: Returns the end angle of elliptical-object. If elliptical-object is a full ellipse or closed path, then ellipse-end-angle will return nil; otherwise the value will be a number greater than zero, and less than or equal to 2π.
Every bounded region in CLIM has a derived bounding rectangle, which is the smallest rectangle that contains every point in the region and which may contain additional points as well. Unbounded regions do not have any bounding rectangle. For example, all windows and output records have bounding rectangles whose coordinates are relative to the bounding rectangle of the parent of the window or output record.
The coordinate system in which the bounding rectangle is maintained depends on the context. For example, the coordinates of the bounding rectangle of a sheet are expressed in the sheet's parent's coordinate system. For output records, the coordinates of the bounding rectangle are maintained in the coordinate system of the stream with which the output record is associated.
Note that the bounding rectangle of a transformed region is not in general the same as the result of transforming the bounding rectangle of a region, as shown in The Bounding Rectangle of an Output Record. For transformations that satisfy rectilinear-transformation-p, the following equality holds. For all other transformations, it does not hold.
(region-equal
(transform-region transformation
(bounding-rectangle region))
(bounding-rectangle (transform-region
transformation region)))
CLIM uses bounding rectangles for a variety of purposes. For example, repainting of windows is driven from the bounding rectangle of the window's viewport, intersected with a "damage" region. The formatting engines used by formatting-table and formatting- graph operate on the bounding rectangles of the output records in the output. Bounding rectangles are also used internally by CLIM to achieve greater efficiency. For instance, when performing hit detection to see if the pointer is within the region of an output record, CLIM first checks to see if the pointer is within the bounding rectangle of the output record.
Note that the bounding rectangle for an output record may have a different size depending on the medium on which the output record is rendered. Consider the case of rendering text on different output devices; the font chosen for a particular text style may vary considerably in size from one device to another.
bounding-rectangle Protocol Class
Summary: The protocol class that represents a bounding rectangle. If you want to create a new class that behaves like a bounding rectangle, it should be a subclass of bounding-rectangle. Subclasses of bounding-rectangle must obey the bounding rectangle protocol.
Note that bounding rectangles are not a subclass of rectangle, nor even a subclass of region. This is because, in general, bounding rectangles do not obey the region protocols. However, all bounded regions and sheets that obey the bounding rectangle protocol are subclasses of bounding-rectangle.
Bounding rectangles are immutable, but since they reflect the live state of such mutable objects as sheets and output records, bounding rectangles are volatile. Therefore, programmers must not depend on the bounding rectangle associated with a mutable object remaining constant.
bounding-rectangle-p object
Summary: Returns t if object is a bounding rectangle (that is, supports the bounding rectangle protocol); otherwise, it returns nil.
standard-bounding-rectangle Class
Summary: An instantiable class that implements a bounding rectangle. This is a subclass of both bounding-rectangle and rectangle; that is, standard bounding rectangles obey the rectangle protocol.
make-bounding-rectangle returns an object of this class.
The representation of bounding rectangles in CLIM is chosen to be efficient. CLIM represents such rectangles by storing the coordinates of two opposing corners of the rectangle, namely, the "min point" and the "max point." Because this representation is not sufficient to represent the result of arbitrary transformations of arbitrary rectangles, CLIM returns a polygon as the result of such a transformation. (The most general class of transformations that is guaranteed to always turn a rectangle into another rectangle is the class of transformations that satisfy rectilinear-transformation-p.)
make-bounding-rectangle Function
make-bounding-rectangle x1 y1 x2 y2
Summary: Returns an object of the class standard-bounding-rectangle with the edges specified by x1, y1, x2, and y2, which must be real numbers.
x1, y1, x2, and y2 are "canonicalized" in the following way. The min point of the rectangle has an x coordinate that is the smaller of x1 and x2 and a y coordinate that is the smaller of y1 and y2. The max point of the rectangle has an x coordinate that is the larger of x1 and x2 and a y coordinate that is the larger of y1 and y2. (Therefore, in a right-handed coordinate system the canonicalized values of x1, y1, x2, and y2 correspond to the left, top, right, and bottom edges of the rectangle, respectively.)
This function returns fresh objects that may be modified.
The following generic functions comprise the bounding rectangle protocol. All classes that participate in this protocol (including all subclasses of region that are bounded regions) implement a method for bounding-rectangle*.
These functions take the argument region, which must be either a bounded region (such as a line or an ellipse) or some other object that obeys the bounding rectangle protocol, such as a sheet or an output record.
bounding-rectangle* Generic Function
bounding-rectangle* region
Summary: Returns the bounding rectangle of region as four real numbers specifying the x and y coordinates of the min point and the x and y coordinates of the max point of the rectangle.
The four returned values min-x, min-y, max-x, and max-y satisfy the inequalities:
min-x ≤ max-x
min-y ≤ max-y
bounding-rectangle Generic Function
bounding-rectangle region
Summary: Returns the bounding rectangle of region as an object that is a subclass of rectangle (described in 2.5.5 Rectangles in CLIM). Since bounding rectangles are volatile, programmers should not depend on the object returned by bounding-rectangle remaining constant.
bounding-rectangle is part of the bounding rectangle Application Programmer Interface, but is not part of the bounding rectangle protocol. CLIM supplies a default method for bounding-rectangle on the protocol class bounding-rectangle that calls bounding-rectangle*.
The following functions are part of the bounding rectangle Application Programmer Interface, but are not part of the bounding rectangle protocol. They are provided as a convenience to programmers who wish to specialize classes that participate in the bounding rectangle protocol, but they will not complicate the task of those programmers who define their own types (such as sheet classes) that participate in this protocol.
CLIM supplies default methods for all of these generic functions on the protocol class bounding-rectangle that are implemented by calling bounding-rectangle*.
with-bounding-rectangle* Macro
with-bounding-rectangle* (min-x min-y max-x max-y) region &body body
Summary: Binds min-x, min-y, max-x, and max-y to the edges of the bounding rectangle of region, and then executes body in that context. The argument region must be either a bounded region (such as a line or an ellipse) or some other object that obeys the bounding rectangle protocol, such as a sheet or an output record.
The arguments min-x, min-y, max-x, and max-y are not evaluated. body may have zero or more declarations as its first forms.
with-bounding-rectangle* calls bounding-rectangle*.
bounding-rectangle-position Generic Function
bounding-rectangle-position region
Summary: Returns the position of the bounding rectangle of region. The position of a bounding rectangle is specified by its min point.
bounding-rectangle-min-x Generic Function
bounding-rectangle-min-x region
bounding-rectangle-min-y Generic Function
bounding-rectangle-min-y region
bounding-rectangle-max-x Generic Function
bounding-rectangle-max-x region
bounding-rectangle-max-y Generic Function
bounding-rectangle-max-y region
Summary: Returns (respectively) the x and y coordinates of the min point and the x and y coordinates of the max point of the bounding rectangle of region. The argument region must be either a bounded region or some other object that obeys the bounding rectangle protocol.
bounding-rectangle-width Generic Function
bounding-rectangle-width region
bounding-rectangle-height Generic Function
bounding-rectangle-height region
bounding-rectangle-size Generic Function
bounding-rectangle-size region
Summary: Returns the width, height, or size (as two values, the width and height) of the bounding rectangle of region, respectively. region must be either a bounded region or some other object that obeys the bounding rectangle protocol.
The width of a bounding rectangle is the difference between its maximum x coordinate and its minimum x coordinate. The height is the difference between the maximum y coordinate and its minimum y coordinate.
CLIM 2.0 User Guide - 01 Dec 2021 19:38:56