BRegion

Derived from: none

Declared in: be/interface/Region.h

Library: libbe.so

A BRegion object comprises a set of rectangles in a two-dimensional coordinate system. The rectangles needn't overlap; a single BRegion can contain a little rectangle way down there, a big one over yonder, and another that lives somewhere to the left of Baden Baden.

You define and modify the contents of a region through to Set(), Include(), Exclude(), and IntersectWith(). You can examine a region's rectangle's through RectAt(), but note that the object coalesces rectangles when it can, so the rectangles that you retrieve may not match the ones that you passed in.

The BRegion class is designed to be used with coordinates with integral values only; if any non-integral values are used in the BRegion, it functions in the class may behave unpredictably.

BRegion objects can be allocated on the stack.

Constructor and Destructor

BRegion()

      BRegion(const BRegion& region) 
      BRegion(void)

Initializes the BRegion object to be a copy of region. If no argument is supplied, the BRegion is empty and Frame() returns and invalid BRect.

~BRegion

      virtual ~BRegion()

Frees the memory that was allocated to hold data describing the region.

Member Functions

Contains()

      bool Contains(BPoint point) const

Returns true if point lies within the region, and false if not.

CountRects() see RectAt()

Exclude() see Set()

Frame()

      BRect Frame(void) const

Returns the smallest rectangle that encloses all the rectangles in the region.

If the region is empty, the returned object will be invalid. Check the return thus:

   rect = region.Frame();
   if (rect.IsValid()) 
      /* okay */
   else
      /* nope */

Include() see Set()

Intersects()

      bool Intersects(BRect rect) const

Returns true if the BRegion has any area in common with rect, and false if not.

IntersectWith() see Set()

MakeEmpty()

      void MakeEmpty(void)

Empties the BRegion and invalidates the object's Frame() rectangle.

OffsetBy()

      void OffsetBy(int32 horizontal, int32 vertical)

Offsets all rectangles in the region by horizontal and vertical deltas.

PrintToStream()

      void PrintToStream(void) const

Prints (to standard out) each rectangle in the BRegion in the form:

   "BRect(left, top, right, bottom)"

The first string that's printed is the object's frame rectangle. Each subsequent string describes a single rectangle in the BRegion.

RectAt(), CountRects()

      BRect RectAt(int32 index) 
      int32 CountRects(void)

CountRects() returns the total number of rectangles in the BRegion; RectAt() returns the rectangle at a particular index. The order of the rectangles is unimportant.

Set(), Include(), Exclude(), IntersectWith()

      void Set(BRect rect)
      void Include(BRect rect)
      void Include(const BRegion *region)
      void Exclude(BRect rect)
      void Exclude(const BRegion *region)
      void IntersectWith(const BRegion *region)

Set()modifies the BRegion so that it only contains rect.

Include() modifies the region to include (copies of) the rectangles contained in rect or region.

Exclude() modifies the region to exclude all rectangles contained in rect or region..

IntersectWith() modifies the region so that it includes only those areas that it has in common with another region.

Operators

= (assignment)

      BRegion& operator =(const BRegion&)

Sets the left region to be an independent copy of the right region:

   BRegion left_region = right_region;

The Be Book, in lovely HTML, for BeOS Release 4.

Last modified October 14, 1998.