Derived from: none
Declared in: be/interface/Rect.h
Library: libbe.so
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.
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).
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()
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.
 |
This function's results are unpredictable if either rectangle is invalid. If there's any chance either rectangle could be invalid, be sure to check them by calling IsValid() before calling this function. |
See also: Intersects(), the & (intersection) and | (union) operators, BPoint::ConstrainTo()
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()
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()
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.
|
This function's results are unpredictable if either rectangle is invalid. If there's any chance either rectangle could be invalid, be sure to check them by calling IsValid() before calling this function. |
See also: the & (intersection) operator
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.
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()
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.
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
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()
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()
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()
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()
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()
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.
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 )
. . .
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.
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
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 4.
Copyright © 1998 Be, Inc. All rights reserved.
Last modified January 5, 1999.