The Interface Kit: BRegion

The Interface Kit Table of Contents | The Interface Kit Index

# BRegion

Derived from: none

Declared in: be/interface/Region.h

Library: libbe.so

###### Summary

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(`const BRect rect`)`
`BRegion(`void`) `

Initializes the BRegion object to be a copy of region, or to be a rectangular region containing the space indicated by rect. 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 Interface Kit Table of Contents | The Interface Kit Index

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

Copyright © 2000 Be, Inc. All rights reserved..