1/* 2 * Copyright 2014 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * John Scipione, jscipione@gmail.com 7 * 8 * Corresponds to: 9 * headers/os/interface/Rect.h hrev47289 10 * src/kits/interface/Rect.cpp hrev47289 11 */ 12 13 14/*! 15 \file Rect.h 16 \ingroup interface 17 \ingroup libbe 18 \brief BRect class definition. 19*/ 20 21 22/*! 23 \class BRect 24 \ingroup interface 25 \ingroup libbe 26 \brief Defines a rectangular area aligned along pixel dimensions. 27 28 BRect's are used throughout the Interface Kit to define the frames 29 of windows, views, and bitmaps. BRect's are always oriented with 30 completely vertical and horizontal lines, they cannot be rotated. 31 32 A BRect must have a non-negative width and height to be valid, that is 33 the left value must be greater than or equal to the right value and the 34 bottom edge value be greater than or equal to the top value. You can test 35 whether or not a BRect is valid by calling IsValid(). Nothing prevents 36 you from creating an invalid BRect, but, using one to define an area can 37 produce unpredictable results. 38 39 A gotcha of using BRect's is that the starting point is 0, not 1, so 40 in order to create a BRect with a 32x32 pixel area you write: 41 42\code 43BRect(0, 0, 31, 31); 44\endcode 45 46 or if you have the width and height stored in a variable you subtract 1 47 like this: 48 49\code 50BRect(0, 0, width - 1, height -1); 51\endcode 52*/ 53 54 55/*! 56 \var BRect::left 57 \brief The value of the rectangle's left edge. 58*/ 59 60 61/*! 62 \var BRect::top 63 \brief The value of the rectangle's top edge. 64*/ 65 66 67/*! 68 \var BRect::right 69 \brief The value of the rectangle's right edge. 70*/ 71 72 73/*! 74 \var BRect::bottom 75 \brief The value of the rectangle's bottom edge. 76*/ 77 78 79/*! 80 \fn inline BRect::BRect() 81 \brief Creates an empty BRect object with dimensions (0, 0, -1, -1). 82 83 These dimensions are invalid, use Set() to provide valid dimensions. 84 85 \sa BRect::Set() 86 \sa BRect::IsValid() 87*/ 88 89 90/*! 91 \fn inline BRect::BRect(float left, float top, float right, float bottom) 92 \brief Creates a new BRect object with the given dimensions. 93 94 \param left The left dimension. 95 \param top The top dimension. 96 \param right The right dimension. 97 \param bottom The bottom dimension. 98*/ 99 100 101/*! 102 \fn inline BRect::BRect(const BRect& other) 103 \brief Creates a new BRect object as a copy of \a other. 104 105 \param other The BRect object to copy. 106*/ 107 108 109/*! 110 \fn inline BRect::BRect(BPoint leftTop, BPoint rightBottom) 111 \brief Creates a new BRect object with its dimensions defined by the 112 \a leftTop and \a rightBottom points. 113 114 \param leftTop The position to set the left top corner to. 115 \param rightBottom The position to set the bottom right corner to. 116*/ 117 118 119/*! 120 \fn inline BRect::BRect(BPoint leftTop, BSize size) 121 \brief Creates a new BRect object with its dimensions defined by the 122 \a leftTop point and \a size. 123 124 \param leftTop The position of the left top corner. 125 \param size The \a size of the rect defining its width and height. 126*/ 127 128 129/*! 130 \fn inline BRect::BRect(float side) 131 \brief Creates a new BRect object setting the left and top dimensions 132 to 0 and setting the right and bottom dimensions to \a side - 1. 133 134 \param side The dimension to set the right and bottom sides. 135*/ 136 137 138/*! 139 \fn inline BRect& BRect::operator=(const BRect& other) 140 \brief Creates a new BRect object as a copy of \a other by overloading 141 the = operator. 142 143 \param other The BRect object to copy. 144 145 \return The newly created BRect object. 146*/ 147 148 149/*! 150 \fn inline bool BRect::IsValid() const 151 \brief Returns whether or not the BRect is valid. 152 153 A BRect is valid if its width and height are non-negative, that is its 154 right value is greater than or equal to its left value and its bottom value 155 is greater than or equal to its top value. 156 157 \return \c true if the BRect is valid, \c false if the BRect is invalid. 158*/ 159 160 161/*! 162 \fn bool BRect::Intersects(BRect rect) const 163 \brief Returns whether or not the BRect and \a rect intersect. 164 165 \param rect The BRect to use to test for intersection. 166 167 \return \c true if the rectangles intersect, \a false otherwise. 168*/ 169 170 171/*! 172 \fn bool BRect::Contains(BPoint point) const 173 \brief Returns whether or not the BRect contains \a point. 174 175 \param point The point to test. 176 177 \return \c true if the BRect contains \a point, \c false otherwise. 178*/ 179 180 181/*! 182 \fn bool BRect::Contains(BRect rect) const 183 \brief Returns whether or not the BRect wholly contains \a rect. 184 185 \param rect The rectangle to test. 186 187 \return \c true if the BRect contains \a rect, \c false otherwise. 188*/ 189 190 191/*! 192 \fn void BRect::PrintToStream() const 193 \brief Prints the BRect dimensions to standard output. 194 195 The format of the output looks like this: 196\verbatim 197 BRect(l:%.1f, t:%.1f, r:%.1f, b:%.1f). 198\endverbatim 199*/ 200 201 202/*! 203 \fn inline int32 BRect::IntegerWidth() const 204 \brief Returns The width of the rectangle rounded using 205 ceil(\a right - \a left). 206 207 \return The width of the rectangle as an int32. 208*/ 209 210 211/*! 212 \fn inline float BRect::Width() const 213 \brief Returns the width of the rectangle. 214 215 \return The width of the rectangle as a float. 216*/ 217 218 219/*! 220 \fn inline int32 BRect::IntegerHeight() const 221 \brief Returns The height of the rectangle rounded using 222 ceil(\a bottom - \a top). 223 224 \return The height of the rectangle as an int32. 225*/ 226 227 228/*! 229 \fn inline float BRect::Height() const 230 \brief Returns the height of the rectangle. 231 232 \return The height of the rectangle as a float. 233*/ 234 235 236/*! 237 \fn inline BSize BRect::Size() const 238 \brief Returns the dimensions of the BRect. 239 240 \return The dimensions of the BRect as a BSize. 241*/ 242 243 244/*! 245 \fn inline void BRect::Set(float left, float top, float right, 246 float bottom) 247 \brief Sets the dimensions of a BRect. 248 249 \param left The \a left dimension to set. 250 \param top The \a top dimension to set. 251 \param right The \a right dimension to set. 252 \param bottom The \a bottom dimension to set. 253*/ 254 255 256/*! 257 \fn void BRect::SetLeftTop(const BPoint point) 258 \brief Sets the left top \a point of the BRect. 259 260 \param point The \a point to set. 261*/ 262 263 264/*! 265 \fn void BRect::SetRightBottom(const BPoint point) 266 \brief Sets the right bottom \a point of the BRect. 267 268 \param point The \a point to set. 269*/ 270 271 272/*! 273 \fn void BRect::SetLeftBottom(const BPoint point) 274 \brief Sets the left bottom \a point of the BRect. 275 276 \param point The \a point to set. 277*/ 278 279 280/*! 281 \fn void BRect::SetRightTop(const BPoint point) 282 \brief Sets the right top \a point of the BRect. 283 284 \param point The \a point to set. 285*/ 286 287 288/*! 289 \fn inline BPoint BRect::LeftTop() const 290 \brief Returns the left top point of the BRect. 291 292 \return The left top point as a BPoint. 293*/ 294 295 296/*! 297 \fn inline BPoint BRect::RightBottom() const 298 \brief Returns the right bottom point of the BRect. 299 300 \return The right bottom point as a BPoint. 301*/ 302 303 304/*! 305 \fn inline BPoint BRect::LeftBottom() const 306 \brief Returns the left bottom point of the BRect. 307 308 \return The left bottom point as a BPoint. 309*/ 310 311 312/*! 313 \fn inline BPoint BRect::RightTop() const 314 \brief Returns the right top point of the BRect. 315 316 \return The left right point as a BPoint. 317*/ 318 319 320/*! 321 \name Transformation methods 322 323 Positive values make the rectangle smaller, negative values make it larger. 324 325 The …Self() versions also return the transformed BRect when they are done. 326 The …Copy() versions transform a copy without changing the original. 327*/ 328 329 330//! @{ 331 332 333/*! 334 \fn void BRect::InsetBy(BPoint point) 335 \brief Inset the BRect by the x and y coordinates of \a point. 336 337 \param point The \a point to use to inset the BRect. 338*/ 339 340 341/*! 342 \fn void BRect::InsetBy(float dx, float dy) 343 \brief Inset the BRect by \a dx units in the horizontal direction and 344 \a dy units in the vertical direction. 345 346 \param dx The horizontal distance to inset the BRect by. 347 \param dy The vertical distance to inset the BRect by. 348*/ 349 350 351/*! 352 \fn BRect& BRect::InsetBySelf(BPoint point) 353 \brief Like BRect::InsetBy() but returns the transformed BRect. 354 355 \param point The \a point to use to inset the BRect. 356 357 \return The transformed BRect. 358 359 \sa BRect::InsetBy(BPoint point) 360*/ 361 362 363/*! 364 \fn BRect& BRect::InsetBySelf(float dx, float dy) 365 \brief Like BRect::InsetBy() but returns the transformed BRect. 366 367 \param dx The horizontal distance to inset the BRect by. 368 \param dy The vertical distance to inset the BRect by. 369 370 \return The transformed BRect. 371 372 \sa BRect::InsetBy(float dx, float dy) 373*/ 374 375 376/*! 377 \fn BRect BRect::InsetByCopy(BPoint point) const 378 \brief Like BRect::InsetBy() but returns a copy of the transformed BRect 379 leaving the original unmodified. 380 381 \param point The \a point to use to inset the BRect. 382 383 \return A copy of the BRect after it has been transformed. 384 385 \sa BRect::InsetBy(BPoint point) 386*/ 387 388 389/*! 390 \fn BRect BRect::InsetByCopy(float dx, float dy) const 391 \brief Like BRect::InsetBy() but returns a copy of the transformed BRect 392 leaving the original unmodified. 393 394 \param dx The horizontal distance to inset the BRect by. 395 \param dy The vertical distance to inset the BRect by. 396 397 \return A copy of the BRect after it has been transformed. 398 399 \sa BRect::InsetBy(float dx, float dy) 400*/ 401 402 403//! @} 404 405 406/*! 407 \name Translation methods 408 409 Positive values move the rectangle right and down, negative values move the 410 rectangle left and up. 411 412 The …Self() versions also return the translated BRect when they are done. 413 The …Copy() versions translate a copy without changing the original. 414*/ 415 416 417//! @{ 418 419 420/*! 421 \fn void BRect::OffsetBy(BPoint point) 422 \brief Moves the BRect horizontally by the x value of \a point and 423 vertically by y value of \a point without changing the size 424 of the rectangle. 425 426 \param point The \a point to use to move the rectangle. 427*/ 428 429 430/*! 431 \fn void BRect::OffsetBy(float dx, float dy) 432 \brief Moves the BRect horizontally by \a dx units and vertically by 433 \a dy units point without changing the size of the rectangle. 434 435 \param dx The number of units the move the rectangle vertically. 436 \param dy The number of units the move the rectangle horizontally. 437*/ 438 439 440/*! 441 \fn BRect& BRect::OffsetBySelf(BPoint point) 442 \brief Like BRect::OffsetBy() but returns the translated BRect. 443 444 \param point The \a point to use to move the rectangle. 445 446 \sa BRect::OffsetBy(BPoint point) 447*/ 448 449 450/*! 451 \fn BRect& BRect::OffsetBySelf(float dx, float dy) 452 \brief Like BRect::OffsetBy() but returns the translated BRect. 453 454 \param dx The number of units the move the rectangle vertically. 455 \param dy The number of units the move the rectangle horizontally. 456 457 \return The translated BRect. 458 459 \sa BRect::OffsetBy(float dx, float dy) 460*/ 461 462 463/*! 464 \fn BRect BRect::OffsetByCopy(BPoint point) const 465 \brief Like BRect::OffsetBy() but returns a copy of the translated 466 BRect leaving the original unmodified. 467 468 \param point The \a point to use to move the rectangle. 469 470 \return A copy of the BRect after it has been translated. 471 472 \sa BRect::OffsetBy(BPoint point) 473*/ 474 475 476/*! 477 \fn BRect BRect::OffsetByCopy(float dx, float dy) const 478 \brief Like BRect::OffsetBy() but returns a copy of the translated 479 BRect leaving the original unmodified. 480 481 \param dx The number of units the move the rectangle vertically. 482 \param dy The number of units the move the rectangle horizontally. 483 484 \return A copy of the BRect after it has been translated. 485 486 \sa BRect::OffsetBy(float dx, float dy) 487*/ 488 489 490/*! 491 \fn void BRect::OffsetTo(BPoint point) 492 \brief Move the BRect to the location specified by \a point. 493 494 \param point The location to move the BRect to. 495*/ 496 497 498/*! 499 \fn void BRect::OffsetTo(float x, float y) 500 \brief Move the BRect to the point specified by the given \a x and \a y 501 coordinates. 502 503 \param x The vertical coordinate of the point to move the BRect to. 504 \param y The horizontal coordinate of the point to move the BRect to. 505*/ 506 507 508/*! 509 \fn BRect& BRect::OffsetToSelf(BPoint point) 510 \brief Like BRect::OffsetTo() but returns the translated BRect. 511 512 \param point The \a point to use to move the rectangle. 513 514 \return The translated BRect. 515 516 \sa BRect::OffsetTo(BPoint point) 517*/ 518 519 520/*! 521 \fn BRect& BRect::OffsetToSelf(float x, float y) 522 \brief Like BRect::OffsetTo() but returns the translated BRect. 523 524 \param x The vertical coordinate of the point to move the BRect to. 525 \param y The horizontal coordinate of the point to move the BRect to. 526 527 \return The translated BRect. 528 529 \sa BRect::OffsetTo(float x, float y) 530*/ 531 532 533/*! 534 \fn BRect BRect::OffsetToCopy(BPoint point) const 535 \brief Like BRect::OffsetTo() but returns a copy of the translated 536 BRect leaving the original unmodified. 537 538 \param point The \a point to use to move the rectangle. 539 540 \return A copy of the BRect after it has been translated. 541 542 \sa BRect::OffsetTo(BPoint point) 543*/ 544 545 546/*! 547 \fn BRect BRect::OffsetToCopy(float x, float y) const 548 \brief Like BRect::OffsetTo() but returns a copy of the translated 549 BRect leaving the original unmodified. 550 551 \param x The number of units the move the rectangle vertically. 552 \param y The number of units the move the rectangle horizontally. 553 554 \return A copy of the BRect after it has been translated. 555 556 \sa BRect::OffsetTo(float x, float y) 557*/ 558 559 560//! @} 561 562 563/*! 564 \name Comparison methods 565*/ 566 567 568//! @{ 569 570 571/*! 572 \fn bool BRect::operator==(BRect other) const 573 \brief Returns whether or not two rectangles coincide exactly. 574 575 \param other The BRect to compare with. 576 577 \return \c true if the rectangles coincide, \c false otherwise. 578*/ 579 580 581/*! 582 \fn bool BRect::operator!=(BRect other) const 583 \brief Returns whether or not two rectangles do NOT coincide exactly. 584 585 \param other The BRect to compare with. 586 587 \return \c true if the rectangles do NOT coincide, \c false otherwise. 588*/ 589 590 591//! @} 592 593 594/*! 595 \name Intersection and union methods 596*/ 597 598 599//! @{ 600 601 602/*! 603 \fn BRect BRect::operator&(BRect other) const 604 \brief Returns a new BRect that is the intersection of the BRect and 605 \a other. 606 607 The intersection of two rectangles is the area that they both share. 608 609 \param other The BRect to take the intersection of. 610 611 \return A new BRect that is the intersection of the BRect and \a other. 612*/ 613 614 615/*! 616 \fn BRect BRect::operator|(BRect other) const 617 \brief Returns a new BRect that is the union of the BRect and \a other. 618 619 The union of two rectangles is the area that encloses both rectangles. 620 621 \param other The BRect to take the union of. 622 623 \return A new BRect that is the union of the BRect and \a other. 624*/ 625 626 627//! @} 628