The Interface Kit: BRegion

Derived from: public BObject

Declared in: <interface/Region.h>


Overview

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 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().

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) )
       . . .


Constructor and Destructor


BRegion()

      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 rather than by value.


~BRegion

      virtual ~BRegion(void)

Frees any 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.


Exclude()

      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()


Frame()

      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()


Include()

      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()


IntersectWith()

      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()


Intersects()

      bool Intersects(BRect rect) const

Returns TRUE if the BRegion has any area in common with rect, and FALSE if not.


MakeEmpty()

      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


OffsetBy()

      void OffsetBy(long horizontal, long vertical)

Offsets all points contained within the region by adding horizontal to each x coordinate value and vertical to each y coordinate value.


PrintToStream()

      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()


Set()

      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()


Operators


= (assignment)

      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, HTML Edition, for Developer Release 8 of the Be Operating System.

Copyright © 1996 Be, Inc. All rights reserved.

Be, the Be logo, BeBox, BeOS, BeWare, and GeekPort are trademarks of Be, Inc.

Last modified September 6, 1996.