# The Interface Kit: BRect

Derived from: none

Declared in: be/interface/Rect.h

Library: libbe.so

## Overview

A BRect object represents a rectangle, one with sides that parallel the x and y coordinate axes. The rectangle is defined by its left, top, right, and bottom coordinates, as illustrated below:

In a valid rectangle, the top y coordinate value is never greater than the bottom y coordinate, and the left x coordinate value is never greater than the right.

A BRect is the simplest, most basic way of specifying an area in a two-dimensional coordinate system. Windows, scroll bars, buttons, text fields, and the screen itself are all specified as rectangles.

When used to define the frame of a window or a view, or the bounds of a bitmap, the sides of the rectangle must line up on screen pixels. For this reason, the rectangle can't have any fractional coordinates. Coordinate units have a one-to-one correspondence with screen pixels.

Integral coordinates fall at the center of screen pixels, so frame rectangles cover a larger area than their coordinate values would indicate. Just as the number of elements in an array is one greater than the largest index, a frame rectangle covers one more column of pixels than its width and one more row than its height.

The figure below illustrates why this is the case. It shows a rectangle with a right side 8.0 units from its left (62.0-54.0) and a bottom 4.0 units below its top (17.0-13.0). Because the pixels that lie on all four sides of the rectangle are considered to be inside it, there's an extra pixel in each direction. When the rectangle is filled on-screen, it covers a 9-pixel-by-5-pixel area.

Because the BRect structure is a basic data type for graphic operations, it's constructed more simply than most other Interface Kit classes: All its data members are publicly accessible, it doesn't have virtual functions, and it doesn't inherit from BArchivable or any other class. Within the Interface Kit, BRect objects are passed and returned by value.

## Data Members

float `left
` The coordinate value of the rectangle's leftmost side (the smallest x coordinate in a valid rectangle).

float `top`
The coordinate value of the rectangle's top (the smallest y coordinate in a valid rectangle).

float `right`
The coordinate value of the rectangle's rightmost side (the largest x coordinate in a valid rectangle).

float `bottom`
The coordinate value of the rectangle's bottom (the largest y coordinate in a valid rectangle).

## 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 with its four coordinate values--left, top, right, and bottom. The four values can be directly stated,

       BRect rect(11.0, 24.7, 301.5, 99.0);

or they can be taken from two points designating the rectangle's left top and right bottom corners,

       BPoint leftTop(11.0, 24.7);
       BPoint rightBottom(301.5, 99.0);
       BRect rect(leftTop, rightBottom);

or they can be copied from another rectangle:

       BRect anotherRect(11.0, 24.7, 301.5, 99.0);
       BRect rect(anotherRect);

A rectangle that's not assigned any initial values,

       BRect rect;

is constructed to be invalid (its top and left are greater than its right and bottom), until a specific assignment is made, typically with the `Set()` function:

       rect.Set(77.0, 2.25, 510.8, 393.0);

See also: `Set()`

## Member Functions

### Contains()

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

Returns `true` if point--or rect--lies inside the area the BRect defines, and `false` if not. A rectangle contains a point even if the point coincides with one of the rectangle's corners or lies on one of its edges.

One rectangle contains another if their union is the same as the first rectangle and their intersection is the same as the second--that is, if the second rectangle lies entirely within the first. A rectangle is considered to be inside another rectangle even if they have one or more sides in common. Two identical rectangles contain each other.

See also: `Intersects()`, the `&` (intersection) and `|` (union) operators, `BPoint::ConstrainTo()`

### Height() see Width()

### InsetBy()

          void InsetBy(float horizontal, float vertical)
          void InsetBy(BPoint point)

Modifies the BRect by insetting its left and right sides by horizontal units and its top and bottom sides by vertical units. (If a point is passed, its x coordinate value substitutes for horizontal and its y coordinate value substitutes for vertical.)

For example, this code

       BRect rect(10.0, 40.0, 100.0, 140.0);
       rect.InsetBy(20.0, 30.0);

produces a rectangle identical to one that could be constructed as follows:

       BRect rect(30.0, 70.0, 80.0, 110.0);

If horizontal or vertical is negative, the rectangle becomes larger in that dimension, rather than smaller.

See also: `OffsetBy()`

### IntegerWidth(), IntegerHeight()

          inline int32 IntegerWidth(void) const

          inline int32 IntegerHeight(void) const

These functions return the width and height of the rectangle expressed as integers. Fractional widths and heights are rounded up to the next whole number.

See also: `Width()`

### Intersects()

          bool Intersects(BRect rect) const

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.

See also: the `&` (intersection) operator

### 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 doesn't designate any area, not even a line or a point.

### LeftBottom() see SetLeftBottom()

### LeftTop() see SetLeftTop()

### OffsetBy(), OffsetTo()

          void OffsetBy(float horizontal, float vertical)
          void OffsetBy(BPoint point)

          void OffsetTo(BPoint point)
          void OffsetTo(float x, float y)

These functions reposition the rectangle in its coordinate system, without altering its size or shape.

`OffsetBy()` adds horizontal to the left and right coordinate values of the rectangle and vertical to its top and bottom coordinates. (If a point is passed, point.x substitutes for horizontal and point.y for vertical.)

`OffsetTo()` moves the rectangle so that its left top corner is at point--or at (x, y). The coordinate values of all its sides are adjusted accordingly.

See also: `InsetBy()`

### PrintToStream()

          void PrintToStream(void) const

Prints the contents of the BRect object to the standard output stream (`stdout`) in the form:

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

where left, top, right, and bottom stand for the current values of the BRect's data members.

### RightBottom() see SetRightBottom()

### RightTop() see SetRightTop()

### Set()

          inline void Set(float left, float top, float right, float bottom)

Assigns the values left, top, right, and bottom to the BRect's corresponding data members. The following code

       BRect rect;
       rect.Set(0.0, 25.0, 50.0, 75.0);

is equivalent to:

       BRect rect;
       rect.left = 0.0;
       rect.top = 25.0;
       rect.right = 50.0;
       rect.bottom = 75.0;

See also: the BRect constructor

### SetLeftBottom(), LeftBottom()

          void SetLeftBottom(const BPoint point)

          inline BPoint LeftBottom(void) const

These functions set and return the left bottom corner of the rectangle. `SetLeftBottom()` alters the BRect so that its left bottom corner is at point, and `LeftBottom()` returns its current left and bottom coordinates as a BPoint object.

See also: `SetLeftTop()`, `SetRightBottom()`, `SetRightTop()`

### SetLeftTop(), LeftTop()

          void SetLeftTop(const BPoint point)

          inline BPoint LeftTop(void) const

These functions set and return the left top corner of the rectangle. `SetLeftTop()` alters the BRect so that its left top corner is at point, and `LeftTop()` returns its current left and top coordinates as a BPoint object.

See also: `SetLeftBottom()`, `SetRightTop()`, `SetRightBottom()`

### SetRightBottom(), RightBottom()

          void SetRightBottom(const BPoint point)

          inline BPoint RightBottom(void) const

These functions set and return the right bottom corner of the rectangle. `SetRightBottom()` alters the BRect so that its right bottom corner is at point, and `RightBottom()` returns its current right and bottom coordinates as a BPoint object.

See also: `SetRightTop()`, `SetLeftBottom()`, `SetLeftTop()`

### SetRightTop(), RightTop()

          void SetRightTop(const BPoint point)

          inline BPoint RightTop(void) const

These functions set and return the right top corner of the rectangle. `SetRightTop()` alters the BRect so that its right top corner is at point, and `RightTop()` returns its current right and top coordinates as a BPoint object.

See also: `SetRightBottom()`, `SetLeftTop()`, `SetLeftBottom()`

### Width(), Height()

          inline float Width(void) const

          inline float Height(void) const

These functions return the width of the rectangle (the difference between the coordinates of its left and right sides) and its height (the difference between its top and bottom coordinates). If either value is negative, the rectangle is invalid.

The width and height of a rectangle are not accurate guides to the number of pixels it covers on-screen. As illustrated in the Overview to this class, a rectangle without fractional coordinates covers an area that's one pixel broader than its coordinate width and one pixel taller than its coordinate height.

See also: `IntegerWidth()`

## Operators

### = (assignment)

          inline BRect& operator =(const BRect&)

Assigns the data members of one BRect object to another BRect:

       BRect a(27.2, 36.8, 230.0, 359.1);
       BRect b;
       b = a;

Rectangle b is made identical to rectangle a.

### == (equality)

          bool operator ==(BRect) const

Compares the data members of two BRect objects and returns `true` if each one exactly matches its counterpart in the other object, and `false` if any of the members don't match. In the following example, the equality operator would return `false`, since the two objects have different right boundaries:

       BRect a(11.5, 22.5, 66.5, 88.5);
       BRect b(11.5, 22.5, 46.5, 88.5);
       if ( a == b )
           . . .

### != (inequality)

          char operator !=(BRect) const

Compares two BRect objects and returns `true` unless their data members match exactly (the two rectangles are identical), in which case it returns `false`. This operator is the inverse of the `==` (equality) operator.

### & (intersection)

          BRect operator &(BRect) const

Returns the intersection of two rectangles--a rectangle enclosing the area they have in common. The shaded area below shows where the two outlined rectangles intersect.

The intersection is computed by taking the greatest left and top coordinate values of the two rectangles, and the smallest right and bottom values. In the following example,

       BRect a(10.0, 40.0, 80.0, 100.0);
       BRect b(35.0, 15.0, 95.0, 65.0);
       BRect c = a & b;

rectangle c will be identical to one constructed as follows:

       BRect c(35.0, 40.0, 80.0, 65.0);

If the two rectangles don't actually intersect, the result will be invalid. You can test for this by calling the `Intersects()` function on the original rectangles, or by calling `IsValid()` on the result.

See also: `Intersects()`, `IsValid()`, the `|` (union) operator

### | (union)

          BRect operator |(BRect) const

Returns the union of two rectangles--the smallest rectangle that encloses them both. The shaded area below illustrates the union of the two outlined rectangles. Note that it includes areas not in either of them.

The union is computed by selecting the smallest left and top coordinate values from the two rectangles, and the greatest right and bottom coordinate values. In the following example,

       BRect a(10.0, 40.0, 80.0, 100.0);
       BRect b(35.0, 15.0, 95.0, 65.0);
       BRect c = a | b;

rectangle c will be identical to one constructed as follows:

       BRect c(10.0, 15.0, 95.0, 100.0);

Note that two rectangles will have a valid union even if they don't intersect.

See also: the `&` (intersection) operator

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

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.