Derived from: none
Declared in: <interface/Region.h>
A BRegion object describes an arbitrary area within a two-dimensional coordinate system. The area can have irregular boundaries, contain holes, or be discontinuous. It's often convenient to think of a region as a set of locations or points, rather than as a closed shape like a rectangle or a polygon.
The points that a region includes can be described by a set of rectangles. Any point that lies within at least one of the rectangles belongs to the region. You can define a region incrementally by passing rectangles to functions like Set(), Include(), and Exclude(). By calling CountRects() and RectAt(), you can also look at the rectangles the BRegion object keeps to define the region. Since the object optimizes its description of the region, these rectangles may differ from the ones you passed to it.
BView's GetClippingRegion() function modifies a BRegion object so that it represents the current clipping region of the view. A BView can pass GetClippingRegion() a pointer to an empty BRegion,
BRegion temp; GetClippingRegion(&temp);
then call BRegion's Intersects() and Contains() functions to test whether the potential drawing it might do falls within the region:
if ( temp.Intersects(someRect) )
. . .
BView's FillRegion() fills a region with a specified pattern. This is equivalent to filling all the rectangles that define the region.
BRegion(const BRegion& region)
BRegion(void)
Initializes the BRegion object to have the same area as another region--or, if no other region is specified, to an empty region.
The original BRegion object and the newly constructed one each have their own copies of the data describing the region. Altering or freeing one of the objects will not affect the other.
BRegion objects can be allocated on the stack and assigned to other objects:
BRegion regionOne(anotherRegion); BRegion regionTwo = regionOne;
However, due to their size, it's more efficient to pass them by pointer than by value.
virtual ~BRegion(void)
Frees any memory that was allocated to hold data describing the region.
bool Contains(BPoint point) const
Returns true if point lies within the region, and false if not.
void Exclude(BRect rect)
void Exclude(const BRegion *region)
Modifies the region so that it excludes all points contained within rect or region that it might have included before.
See also: Include(), IntersectWith()
BRect Frame(void) const
Returns the frame rectangle of the BRegion--the smallest rectangle that encloses all the points within the region.
If the region is empty, the rectangle returned won't be valid.
See also: BRect::IsValid()
void Include(BRect rect)
void Include(const BRegion *region)
Modifies the region so that it includes all points contained within the rect or region passed as an argument.
See also: Exclude()
void IntersectWith(const BRegion *region)
Modifies the region so that it includes only those points that it has in common with another region.
See also: Include()
bool Intersects(BRect rect) const
Returns true if the BRegion has any area in common with rect, and false if not.
void MakeEmpty(void)
Empties the BRegion of all its points. It will no longer designate any area and its frame rectangle won't be valid.
See also: the BRegion constructor
void OffsetBy(int32 horizontal, int32 vertical)
Offsets all points contained within the region by adding horizontal to each x coordinate value and vertical to each y coordinate value.
void PrintToStream(void) const
Prints the contents of the BRegion to the standard output stream (stdout) as an array of strings. Each string describes a rectangle in the form:
"BRect(left, top, right, bottom)"
where left, top, right, and bottom are the coordinate values that define the rectangle.
The first string in the array describes the BRegion's frame rectangle. Each subsequent string describes one portion of the area included in the BRegion.
See also: BRect::PrintToStream(), Frame()
BRect RectAt(int32 index)
int32 CountRects(void)
These functions provide access to the array of rectangles that define the region. Each coordinate point or pixel that's included within a rectangle is part of the region; points or pixels not inside a rectangle are not in the region.
CountRects() returns the total number of rectangles in the array; RectAt() returns the rectangle at a particular index in the array.
void Set(BRect rect)
Modifies the BRegion so that it describes an area identical to rect. A subsequent call to Frame() should return the same rectangle (unless some other change was made to the region in the interim).
See also: Include(), Exclude()
BRegion& operator =(const BRegion&)
Assigns the region described by one BRegion object to another BRegion:
BRegion region = anotherRegion;
After the assignment, the two regions will be identical, but independent, copies of one another. Each object allocates its own memory to store the description of the region.
The Be Book, in lovely HTML, for the BeOS Preview Release.
Copyright © 1997 Be, Inc. All rights reserved.
Be is a registered trademark; BeOS, BeBox, BeWare, GeekPort, the Be logo, and the BeOS logo are trademarks of Be, Inc.
Last modified June 30, 1997.