The Interface Kit: BRect

The Interface Kit Table of Contents | The Interface Kit Index

# BRect

Derived from: none

Declared in: be/interface/Rect.h

Library: libbe.so

Allocation: Constructor or on the stack, typically the latter.

###### Summary

A BRect object represents a rectangle. BRects are used throughout the Interface Kit to define the frames of windows, views, bitmaps—even the screen itself. A BRect is defined by its four sides, expressed as the public data members `left`, `top`, `right`, and `bottom`.

When used in the screen coordinate system(as a window or view's frame, for example) a BRect's sides are aligned with the x and y axes (as shown here), and its coordinate values, which are stored as floats, are floored.

### Rectangle Size and Area

You would expect a BRect defined thus...:

       BRect rect(0, 0, 3, 3);

...to have a width of 3.0 and a height of 3.0. These, indeed, are the values returned by the `Width()` and `Height()` functions. However, the coordinate system considers integer coordinates to fall in the center of pixels, so the rectangle "touches" a 4x4 pixel grid when it's applied to the screen—it appears one pixel wider and one higher than `Width()` and `Height()` would have you believe. The mapping of rectangle coordinates to pixels is explained in greater detail in "The Coordinate Space".

A rectangle's area includes the points that lie along its sides, but it doesn't necessarily contain the entire area of the pixels that it "lights up." For example, consider the point at (3.1, 3.1). This point falls outside the (0,0,3,3) BRect defined above (i.e the point doesn't `Intersect()` with the BRect), even though it corresponds to one of the pixels that the BRect touches (as shown here).

### Rectangle Validity

To represent a valid rectangle, a BRect's `top` value must be less than or equal to `bottom`, and its `left` must be less than or equal to `right`. Invalid rectangles are meaningless and can't be used (to define a window or view's area, etc.) Note that the BRect constructor and Set...() function don't prevent you from creating an invalid rectangle. Use the `IsValid()` boolean function to test a BRect object's validity.

## Data Members

float `left
` The value of the rectangle's left side.

float `top`
The value of the rectangle's top.

float `right`
The value of the rectangle's right side.

float `bottom`
The value of the rectangle's bottom.

## Constructor

### BRect()

inline `BRect(`float left, float top, float right, float bottom`) `
inline `BRect(` BPoint leftTop, BPoint rightBottom`) `
inline `BRect(`const BRect& rect`) `
inline `BRect(`void`) `

Initializes a BRect as four sides, as two diametrically opposed corners, or as a copy of some other BRect object. A rectangle that's not assigned any initial values is invalid, until a specific assignment is made, either through a `Set()` function or by setting the object's data members directly.

## Member Functions

### Contains() , Intersects()

bool `Contains(` BPoint point`)` const
bool `Contains(`BRect rect`)` const
bool `Intersects(`BRect rect`)` const

`Contains()` returns `true` if point or rect lies entirely within the BRect's rectangle (and `false` if not). A rectangle contains the points that lie along its edges; for example, two identical rectangles contain each other.

`Intersect()` returns `true` if the BRect has any area—even a corner or part of a side—in common with rect, and `false` if it doesn't.

| This function's results are unpredictable if either rectangle is invalid.

See also: `&` (intersection), `|` (union), `BPoint::ConstrainTo()`

### Height() see Width()

### InsetBy() , InsetBySelf() , InsetByCopy() , OffsetBy() , OffsetBySelf() , OffsetByCopy() , OffsetTo() , OffsetToSelf() , OffsetToCopy()

void `InsetBy(`float x, float y`) `
void `InsetBy(` BPoint point`) `
BRect &`InsetBySelf(`float x, float y`) `
BRect &`InsetBySelf(` BPoint point`) `
BRect `InsetByCopy(`float x, float y`) `
BRect `InsetByCopy(` BPoint point`) `
void `OffsetBy(`float x, float y`) `
void `OffsetBy(` BPoint point`) `
BRect &`OffsetBySelf(`float x, float y`) `
BRect &`OffsetBySelf(` BPoint point`) `
BRect `OffsetByCopy(`float x, float y`) `
BRect `OffsetByCopy(` BPoint point`) `
void `OffsetTo(`float x, float y`) `
void `OffsetTo(` BPoint point`) `
BRect &`OffsetToSelf(`float x, float y`) `
BRect &`OffsetToSelf(` BPoint point`) `
BRect `OffsetToCopy(`float x, float y`) `
BRect `OffsetToCopy(` BPoint point`) `

Sorting out the different versions, there are three basic rectangle-manipulation functions here:

- `InsetBy()` insets the sides of the BRect's rectangle by x units (left and right sides) and y units (top and bottom). Positive inset values shrink the rectangle; negative values expand it. Note that both sides of each pair moves the full amount. For example, if you inset a BRect by (4,4), the left side moves (to the right) four units and the right side moves (to the left) four units (and similarly with the top and bottom).

- `OffsetBy()` moves the BRect horizontally by x units and vertically by y units. The rectangle's size doesn't change.

- `OffsetTo()` moves the BRect to the location (x,y).

If a BPoint argument is used, the BPoint's `x` and `y` values are used as the x and y arguments.

The `...Self()` versions of the functions are the same as the simpler versions, but they conveniently return the modified BRect. The `...Copy()` versions copy the BRect, and then modify and return the copy (without changing the original).

### Intersects() see Contains()

### IsValid()

inline bool `IsValid(`void`)` const

Returns `true` if the BRect's right side is greater than or equal to its left and its bottom is greater than or equal to its top, and `false` otherwise. An invalid rectangle can't be used to define an interface area (such as the frame of a view or window).

### LeftBottom(), LeftTop() see Set()

### OffsetBy(), OffsetByCopy(), OffsetBySelf() see InsetBy()

### OffsetTo(), OffsetToCopy(), OffsetToSelf() see InsetBy()

### PrintToStream()

void `PrintToStream(`void`)` const

Prints the contents of the BRect object to standard out in the form:

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

### RightBottom(), RightTop() see Set()

### Set() , SetLeftTop() , SetLeftBottom() , SetRightTop() , SetRightBottom()

inline void `Set(`float left, float top, float right, float bottom`) `
void `SetLeftTop(`const BPoint point`) `
void `SetLeftBottom(`const BPoint point`) `
void `SetRightTop(`const BPoint point`) `
void `SetRightBottom(`const BPoint point`) `
BPoint `LeftTop(`void`)` const
BPoint `LeftBottom(`void`)` const
BPoint `RightTop(`void`)` const
BPoint `RightBottom(`void`)` const

`Set()` sets the object's rectangle by defining the coordinates of all four sides. The other `Set...()` functions move one of the rectangle's corners to the BPoint argument; the other corners and sides are modified concomittantly. None of these functions prevents you from creating an invalid rectangle.

The BPoint-returning functions return the coordinates of one of the rectangle's four corners.

### Width() , IntegerWidth() , Height() , IntegerHeight()

inline float `Width(`void`)` const
inline int32 `IntegerWidth(`void`)` const
inline float `Height(`void`)` const
inline int32 `IntegerHeight(`void`)` const

`Width()` returns the numerical difference between the rectangle's right and left sides (i.e. `right` – `left`). `IntegerWidth()` does the same, but rounds up in the case of a fractional difference.

`Height()` and `IntegerHeight()` perform similar calculations for the height of the rectangle (i.e. `bottom` – `top` and ceil(`bottom` – `top`)).

The width and height of a BRect's rectangle, as returned through these functions

## Operators

### = (assignment)

inline BRect& `operator =(`const BRect& from`)`

Copies from's rectangle data into the left-side object.

### == (equality), != (inequality)

bool `operator ==(`BRect`)` const
bool `operator !=(`BRect`)` const

== returns `true` if the two objects' rectangles exactly coincide.

!= returns `true` if the two objects' rectangles don't coincide.

### & (intersection)

BRect `operator &(`BRect`)` const

Creates and returns a new BRect that's the intersection of the two operands. The new BRect encloses the area that the two operands have in common. If the two operands don't intersect, the new BRect will be invalid.

### | (union)

BRect `operator |(`BRect`)` const

Creates and returns a new BRect that minimally but completely encloses the area defined by both of the operands. The shaded area illustrates the union of the two outlined rectangles:

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