47852bff02
* Add \since directive to each method. * Add documentation for BScrollBar and BScrollView classes. * Title Case group titles. * Some other minor documentation updates.
721 lines
15 KiB
Plaintext
721 lines
15 KiB
Plaintext
/*
|
|
* Copyright 2014 Haiku, Inc. All rights reserved.
|
|
* Distributed under the terms of the MIT License.
|
|
*
|
|
* Authors:
|
|
* John Scipione, jscipione@gmail.com
|
|
*
|
|
* Corresponds to:
|
|
* headers/os/interface/Rect.h hrev47289
|
|
* src/kits/interface/Rect.cpp hrev47289
|
|
*/
|
|
|
|
|
|
/*!
|
|
\file Rect.h
|
|
\ingroup interface
|
|
\ingroup libbe
|
|
\brief BRect class definition.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\class BRect
|
|
\ingroup interface
|
|
\ingroup libbe
|
|
\brief Defines a rectangular area aligned along pixel dimensions.
|
|
|
|
BRect's are used throughout the Interface Kit to define the frames
|
|
of windows, views, and bitmaps. BRect's are always oriented with
|
|
completely vertical and horizontal lines, they cannot be rotated.
|
|
|
|
A BRect must have a non-negative width and height to be valid, that is
|
|
the left value must be greater than or equal to the right value and the
|
|
bottom edge value be greater than or equal to the top value. You can test
|
|
whether or not a BRect is valid by calling IsValid(). Nothing prevents
|
|
you from creating an invalid BRect, but, using one to define an area can
|
|
produce unpredictable results.
|
|
|
|
A gotcha of using BRect's is that the starting point is 0, not 1, so
|
|
in order to create a BRect with a 32x32 pixel area you write:
|
|
|
|
\code
|
|
BRect(0, 0, 31, 31);
|
|
\endcode
|
|
|
|
or if you have the width and height stored in a variable you subtract 1
|
|
like this:
|
|
|
|
\code
|
|
BRect(0, 0, width - 1, height -1);
|
|
\endcode
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var BRect::left
|
|
\brief The value of the rectangle's left edge.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var BRect::top
|
|
\brief The value of the rectangle's top edge.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var BRect::right
|
|
\brief The value of the rectangle's right edge.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\var BRect::bottom
|
|
\brief The value of the rectangle's bottom edge.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn inline BRect::BRect()
|
|
\brief Creates an empty BRect object with dimensions (0, 0, -1, -1).
|
|
|
|
These dimensions are invalid, use Set() to provide valid dimensions.
|
|
|
|
\sa BRect::Set()
|
|
\sa BRect::IsValid()
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn inline BRect::BRect(float left, float top, float right, float bottom)
|
|
\brief Creates a new BRect object with the given dimensions.
|
|
|
|
\param left The left dimension.
|
|
\param top The top dimension.
|
|
\param right The right dimension.
|
|
\param bottom The bottom dimension.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn inline BRect::BRect(const BRect& other)
|
|
\brief Creates a new BRect object as a copy of \a other.
|
|
|
|
\param other The BRect object to copy.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn inline BRect::BRect(BPoint leftTop, BPoint rightBottom)
|
|
\brief Creates a new BRect object with its dimensions defined by the
|
|
\a leftTop and \a rightBottom points.
|
|
|
|
\param leftTop The position to set the left top corner to.
|
|
\param rightBottom The position to set the bottom right corner to.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn inline BRect::BRect(BPoint leftTop, BSize size)
|
|
\brief Creates a new BRect object with its dimensions defined by the
|
|
\a leftTop point and \a size.
|
|
|
|
\param leftTop The position of the left top corner.
|
|
\param size The \a size of the rect defining its width and height.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn inline BRect::BRect(float side)
|
|
\brief Creates a new BRect object setting the left and top dimensions
|
|
to 0 and setting the right and bottom dimensions to \a side - 1.
|
|
|
|
\param side The dimension to set the right and bottom sides.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn inline bool BRect::IsValid() const
|
|
\brief Returns whether or not the BRect is valid.
|
|
|
|
A BRect is valid if its width and height are non-negative, that is its
|
|
right value is greater than or equal to its left value and its bottom value
|
|
is greater than or equal to its top value.
|
|
|
|
\return \c true if the BRect is valid, \c false if the BRect is invalid.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BRect::Intersects(BRect rect) const
|
|
\brief Returns whether or not the BRect and \a rect intersect.
|
|
|
|
\param rect The BRect to use to test for intersection.
|
|
|
|
\return \c true if the rectangles intersect, \a false otherwise.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BRect::Contains(BPoint point) const
|
|
\brief Returns whether or not the BRect contains \a point.
|
|
|
|
\param point The point to test.
|
|
|
|
\return \c true if the BRect contains \a point, \c false otherwise.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BRect::Contains(BRect rect) const
|
|
\brief Returns whether or not the BRect wholly contains \a rect.
|
|
|
|
\param rect The rectangle to test.
|
|
|
|
\return \c true if the BRect contains \a rect, \c false otherwise.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRect::PrintToStream() const
|
|
\brief Prints the BRect dimensions to standard output.
|
|
|
|
The format of the output looks like this:
|
|
\verbatim
|
|
BRect(l:%.1f, t:%.1f, r:%.1f, b:%.1f).
|
|
\endverbatim
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn inline int32 BRect::IntegerWidth() const
|
|
\brief Returns The width of the rectangle rounded using
|
|
ceil(\a right - \a left).
|
|
|
|
\return The width of the rectangle as an int32.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn inline float BRect::Width() const
|
|
\brief Returns the width of the rectangle.
|
|
|
|
\return The width of the rectangle as a float.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn inline int32 BRect::IntegerHeight() const
|
|
\brief Returns The height of the rectangle rounded using
|
|
ceil(\a bottom - \a top).
|
|
|
|
\return The height of the rectangle as an int32.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn inline float BRect::Height() const
|
|
\brief Returns the height of the rectangle.
|
|
|
|
\return The height of the rectangle as a float.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn inline BSize BRect::Size() const
|
|
\brief Returns the dimensions of the BRect.
|
|
|
|
\return The dimensions of the BRect as a BSize.
|
|
|
|
\since Haiku R1
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn inline void BRect::Set(float left, float top, float right,
|
|
float bottom)
|
|
\brief Sets the dimensions of a BRect.
|
|
|
|
\param left The \a left dimension to set.
|
|
\param top The \a top dimension to set.
|
|
\param right The \a right dimension to set.
|
|
\param bottom The \a bottom dimension to set.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRect::SetLeftTop(const BPoint point)
|
|
\brief Sets the left top \a point of the BRect.
|
|
|
|
\param point The \a point to set.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRect::SetRightBottom(const BPoint point)
|
|
\brief Sets the right bottom \a point of the BRect.
|
|
|
|
\param point The \a point to set.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRect::SetLeftBottom(const BPoint point)
|
|
\brief Sets the left bottom \a point of the BRect.
|
|
|
|
\param point The \a point to set.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRect::SetRightTop(const BPoint point)
|
|
\brief Sets the right top \a point of the BRect.
|
|
|
|
\param point The \a point to set.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn inline BPoint BRect::LeftTop() const
|
|
\brief Returns the left top point of the BRect.
|
|
|
|
\return The left top point as a BPoint.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn inline BPoint BRect::RightBottom() const
|
|
\brief Returns the right bottom point of the BRect.
|
|
|
|
\return The right bottom point as a BPoint.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn inline BPoint BRect::LeftBottom() const
|
|
\brief Returns the left bottom point of the BRect.
|
|
|
|
\return The left bottom point as a BPoint.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn inline BPoint BRect::RightTop() const
|
|
\brief Returns the right top point of the BRect.
|
|
|
|
\return The left right point as a BPoint.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\name Transformation
|
|
|
|
Positive values make the rectangle smaller, negative values make it larger.
|
|
|
|
The …Self() versions also return the transformed BRect when they are done.
|
|
The …Copy() versions transform a copy without changing the original.
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn void BRect::InsetBy(BPoint point)
|
|
\brief Inset the BRect by the x and y coordinates of \a point.
|
|
|
|
\param point The \a point to use to inset the BRect.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRect::InsetBy(float dx, float dy)
|
|
\brief Inset the BRect by \a dx units in the horizontal direction and
|
|
\a dy units in the vertical direction.
|
|
|
|
\param dx The horizontal distance to inset the BRect by.
|
|
\param dy The vertical distance to inset the BRect by.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BRect& BRect::InsetBySelf(BPoint point)
|
|
\brief Like BRect::InsetBy() but returns the transformed BRect.
|
|
|
|
\param point The \a point to use to inset the BRect.
|
|
|
|
\return The transformed BRect.
|
|
|
|
\sa BRect::InsetBy(BPoint point)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BRect& BRect::InsetBySelf(float dx, float dy)
|
|
\brief Like BRect::InsetBy() but returns the transformed BRect.
|
|
|
|
\param dx The horizontal distance to inset the BRect by.
|
|
\param dy The vertical distance to inset the BRect by.
|
|
|
|
\return The transformed BRect.
|
|
|
|
\sa BRect::InsetBy(float dx, float dy)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BRect BRect::InsetByCopy(BPoint point) const
|
|
\brief Like BRect::InsetBy() but returns a copy of the transformed BRect
|
|
leaving the original unmodified.
|
|
|
|
\param point The \a point to use to inset the BRect.
|
|
|
|
\return A copy of the BRect after it has been transformed.
|
|
|
|
\sa BRect::InsetBy(BPoint point)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BRect BRect::InsetByCopy(float dx, float dy) const
|
|
\brief Like BRect::InsetBy() but returns a copy of the transformed BRect
|
|
leaving the original unmodified.
|
|
|
|
\param dx The horizontal distance to inset the BRect by.
|
|
\param dy The vertical distance to inset the BRect by.
|
|
|
|
\return A copy of the BRect after it has been transformed.
|
|
|
|
\sa BRect::InsetBy(float dx, float dy)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name Translation
|
|
|
|
Positive values move the rectangle right and down, negative values move the
|
|
rectangle left and up.
|
|
|
|
The …Self() versions also return the translated BRect when they are done.
|
|
The …Copy() versions translate a copy without changing the original.
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn void BRect::OffsetBy(BPoint point)
|
|
\brief Moves the BRect horizontally by the x value of \a point and
|
|
vertically by y value of \a point without changing the size
|
|
of the rectangle.
|
|
|
|
\param point The \a point to use to move the rectangle.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRect::OffsetBy(float dx, float dy)
|
|
\brief Moves the BRect horizontally by \a dx units and vertically by
|
|
\a dy units point without changing the size of the rectangle.
|
|
|
|
\param dx The number of units the move the rectangle vertically.
|
|
\param dy The number of units the move the rectangle horizontally.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BRect& BRect::OffsetBySelf(BPoint point)
|
|
\brief Like BRect::OffsetBy() but returns the translated BRect.
|
|
|
|
\param point The \a point to use to move the rectangle.
|
|
|
|
\sa BRect::OffsetBy(BPoint point)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BRect& BRect::OffsetBySelf(float dx, float dy)
|
|
\brief Like BRect::OffsetBy() but returns the translated BRect.
|
|
|
|
\param dx The number of units the move the rectangle vertically.
|
|
\param dy The number of units the move the rectangle horizontally.
|
|
|
|
\return The translated BRect.
|
|
|
|
\sa BRect::OffsetBy(float dx, float dy)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BRect BRect::OffsetByCopy(BPoint point) const
|
|
\brief Like BRect::OffsetBy() but returns a copy of the translated
|
|
BRect leaving the original unmodified.
|
|
|
|
\param point The \a point to use to move the rectangle.
|
|
|
|
\return A copy of the BRect after it has been translated.
|
|
|
|
\sa BRect::OffsetBy(BPoint point)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BRect BRect::OffsetByCopy(float dx, float dy) const
|
|
\brief Like BRect::OffsetBy() but returns a copy of the translated
|
|
BRect leaving the original unmodified.
|
|
|
|
\param dx The number of units the move the rectangle vertically.
|
|
\param dy The number of units the move the rectangle horizontally.
|
|
|
|
\return A copy of the BRect after it has been translated.
|
|
|
|
\sa BRect::OffsetBy(float dx, float dy)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRect::OffsetTo(BPoint point)
|
|
\brief Move the BRect to the location specified by \a point.
|
|
|
|
\param point The location to move the BRect to.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn void BRect::OffsetTo(float x, float y)
|
|
\brief Move the BRect to the point specified by the given \a x and \a y
|
|
coordinates.
|
|
|
|
\param x The vertical coordinate of the point to move the BRect to.
|
|
\param y The horizontal coordinate of the point to move the BRect to.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BRect& BRect::OffsetToSelf(BPoint point)
|
|
\brief Like BRect::OffsetTo() but returns the translated BRect.
|
|
|
|
\param point The \a point to use to move the rectangle.
|
|
|
|
\return The translated BRect.
|
|
|
|
\sa BRect::OffsetTo(BPoint point)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BRect& BRect::OffsetToSelf(float x, float y)
|
|
\brief Like BRect::OffsetTo() but returns the translated BRect.
|
|
|
|
\param x The vertical coordinate of the point to move the BRect to.
|
|
\param y The horizontal coordinate of the point to move the BRect to.
|
|
|
|
\return The translated BRect.
|
|
|
|
\sa BRect::OffsetTo(float x, float y)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BRect BRect::OffsetToCopy(BPoint point) const
|
|
\brief Like BRect::OffsetTo() but returns a copy of the translated
|
|
BRect leaving the original unmodified.
|
|
|
|
\param point The \a point to use to move the rectangle.
|
|
|
|
\return A copy of the BRect after it has been translated.
|
|
|
|
\sa BRect::OffsetTo(BPoint point)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BRect BRect::OffsetToCopy(float x, float y) const
|
|
\brief Like BRect::OffsetTo() but returns a copy of the translated
|
|
BRect leaving the original unmodified.
|
|
|
|
\param x The number of units the move the rectangle vertically.
|
|
\param y The number of units the move the rectangle horizontally.
|
|
|
|
\return A copy of the BRect after it has been translated.
|
|
|
|
\sa BRect::OffsetTo(float x, float y)
|
|
|
|
\since BeOS R5
|
|
*/
|
|
|
|
|
|
//! @}
|
|
|
|
|
|
/*!
|
|
\name Operators
|
|
*/
|
|
|
|
|
|
//! @{
|
|
|
|
|
|
/*!
|
|
\fn inline BRect& BRect::operator=(const BRect& other)
|
|
\brief Creates a new BRect object as a copy of \a other by overloading
|
|
the = operator.
|
|
|
|
\param other The BRect object to copy.
|
|
|
|
\return The newly created BRect object.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BRect::operator==(BRect other) const
|
|
\brief Returns whether or not two rectangles coincide exactly.
|
|
|
|
\param other The BRect to compare with.
|
|
|
|
\return \c true if the rectangles coincide, \c false otherwise.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn bool BRect::operator!=(BRect other) const
|
|
\brief Returns whether or not two rectangles do NOT coincide exactly.
|
|
|
|
\param other The BRect to compare with.
|
|
|
|
\return \c true if the rectangles do NOT coincide, \c false otherwise.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BRect BRect::operator&(BRect other) const
|
|
\brief Returns a new BRect that is the intersection of the BRect and
|
|
\a other.
|
|
|
|
The intersection of two rectangles is the area that they both share.
|
|
|
|
\param other The BRect to take the intersection of.
|
|
|
|
\return A new BRect that is the intersection of the BRect and \a other.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn BRect BRect::operator|(BRect other) const
|
|
\brief Returns a new BRect that is the union of the BRect and \a other.
|
|
|
|
The union of two rectangles is the area that encloses both rectangles.
|
|
|
|
\param other The BRect to take the union of.
|
|
|
|
\return A new BRect that is the union of the BRect and \a other.
|
|
|
|
\since BeOS R3
|
|
*/
|
|
|
|
|
|
//! @}
|