# The Interface Kit: BRegion

Derived from: none

Declared in: be/interface/Region.h

Library: libbe.so

## Overview

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.

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

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.