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 \since BeOS R3 54*/ 55 56 57/*! 58 \var BRect::left 59 \brief The value of the rectangle's left edge. 60 61 \since BeOS R3 62*/ 63 64 65/*! 66 \var BRect::top 67 \brief The value of the rectangle's top edge. 68 69 \since BeOS R3 70*/ 71 72 73/*! 74 \var BRect::right 75 \brief The value of the rectangle's right edge. 76 77 \since BeOS R3 78*/ 79 80 81/*! 82 \var BRect::bottom 83 \brief The value of the rectangle's bottom edge. 84 85 \since BeOS R3 86*/ 87 88 89/*! 90 \fn inline BRect::BRect() 91 \brief Creates an empty BRect object with dimensions (0, 0, -1, -1). 92 93 These dimensions are invalid, use Set() to provide valid dimensions. 94 95 \sa BRect::Set() 96 \sa BRect::IsValid() 97 98 \since BeOS R3 99*/ 100 101 102/*! 103 \fn inline BRect::BRect(float left, float top, float right, float bottom) 104 \brief Creates a new BRect object with the given dimensions. 105 106 \param left The left dimension. 107 \param top The top dimension. 108 \param right The right dimension. 109 \param bottom The bottom dimension. 110 111 \since BeOS R3 112*/ 113 114 115/*! 116 \fn inline BRect::BRect(const BRect& other) 117 \brief Creates a new BRect object as a copy of \a other. 118 119 \param other The BRect object to copy. 120 121 \since BeOS R3 122*/ 123 124 125/*! 126 \fn inline BRect::BRect(BPoint leftTop, BPoint rightBottom) 127 \brief Creates a new BRect object with its dimensions defined by the 128 \a leftTop and \a rightBottom points. 129 130 \param leftTop The position to set the left top corner to. 131 \param rightBottom The position to set the bottom right corner to. 132 133 \since BeOS R3 134*/ 135 136 137/*! 138 \fn inline BRect::BRect(BPoint leftTop, BSize size) 139 \brief Creates a new BRect object with its dimensions defined by the 140 \a leftTop point and \a size. 141 142 \param leftTop The position of the left top corner. 143 \param size The \a size of the rect defining its width and height. 144 145 \since Haiku R1 146*/ 147 148 149/*! 150 \fn inline BRect::BRect(float side) 151 \brief Creates a new BRect object setting the left and top dimensions 152 to 0 and setting the right and bottom dimensions to \a side - 1. 153 154 \param side The dimension to set the right and bottom sides. 155 156 \since Haiku R1 157*/ 158 159 160/*! 161 \fn inline bool BRect::IsValid() const 162 \brief Returns whether or not the BRect is valid. 163 164 A BRect is valid if its width and height are non-negative, that is its 165 right value is greater than or equal to its left value and its bottom value 166 is greater than or equal to its top value. 167 168 \return \c true if the BRect is valid, \c false if the BRect is invalid. 169 170 \since BeOS R3 171*/ 172 173 174/*! 175 \fn bool BRect::Intersects(BRect rect) const 176 \brief Returns whether or not the BRect and \a rect intersect. 177 178 \param rect The BRect to use to test for intersection. 179 180 \return \c true if the rectangles intersect, \a false otherwise. 181 182 \since BeOS R3 183*/ 184 185 186/*! 187 \fn bool BRect::Contains(BPoint point) const 188 \brief Returns whether or not the BRect contains \a point. 189 190 \param point The point to test. 191 192 \return \c true if the BRect contains \a point, \c false otherwise. 193 194 \since BeOS R3 195*/ 196 197 198/*! 199 \fn bool BRect::Contains(BRect rect) const 200 \brief Returns whether or not the BRect wholly contains \a rect. 201 202 \param rect The rectangle to test. 203 204 \return \c true if the BRect contains \a rect, \c false otherwise. 205 206 \since BeOS R3 207*/ 208 209 210/*! 211 \fn void BRect::PrintToStream() const 212 \brief Prints the BRect dimensions to standard output. 213 214 The format of the output looks like this: 215\verbatim 216 BRect(l:%.1f, t:%.1f, r:%.1f, b:%.1f). 217\endverbatim 218 219 \since BeOS R3 220*/ 221 222 223/*! 224 \fn inline int32 BRect::IntegerWidth() const 225 \brief Returns The width of the rectangle rounded using 226 ceil(\a right - \a left). 227 228 \return The width of the rectangle as an int32. 229 230 \since BeOS R3 231*/ 232 233 234/*! 235 \fn inline float BRect::Width() const 236 \brief Returns the width of the rectangle. 237 238 \return The width of the rectangle as a float. 239*/ 240 241 242/*! 243 \fn inline int32 BRect::IntegerHeight() const 244 \brief Returns The height of the rectangle rounded using 245 ceil(\a bottom - \a top). 246 247 \return The height of the rectangle as an int32. 248 249 \since BeOS R3 250*/ 251 252 253/*! 254 \fn inline float BRect::Height() const 255 \brief Returns the height of the rectangle. 256 257 \return The height of the rectangle as a float. 258 259 \since BeOS R3 260*/ 261 262 263/*! 264 \fn inline BSize BRect::Size() const 265 \brief Returns the dimensions of the BRect. 266 267 \return The dimensions of the BRect as a BSize. 268 269 \since Haiku R1 270*/ 271 272 273/*! 274 \fn inline void BRect::Set(float left, float top, float right, 275 float bottom) 276 \brief Sets the dimensions of a BRect. 277 278 \param left The \a left dimension to set. 279 \param top The \a top dimension to set. 280 \param right The \a right dimension to set. 281 \param bottom The \a bottom dimension to set. 282 283 \since BeOS R3 284*/ 285 286 287/*! 288 \fn void BRect::SetLeftTop(const BPoint point) 289 \brief Sets the left top \a point of the BRect. 290 291 \param point The \a point to set. 292 293 \since BeOS R3 294*/ 295 296 297/*! 298 \fn void BRect::SetRightBottom(const BPoint point) 299 \brief Sets the right bottom \a point of the BRect. 300 301 \param point The \a point to set. 302 303 \since BeOS R3 304*/ 305 306 307/*! 308 \fn void BRect::SetLeftBottom(const BPoint point) 309 \brief Sets the left bottom \a point of the BRect. 310 311 \param point The \a point to set. 312 313 \since BeOS R3 314*/ 315 316 317/*! 318 \fn void BRect::SetRightTop(const BPoint point) 319 \brief Sets the right top \a point of the BRect. 320 321 \param point The \a point to set. 322 323 \since BeOS R3 324*/ 325 326 327/*! 328 \fn inline BPoint BRect::LeftTop() const 329 \brief Returns the left top point of the BRect. 330 331 \return The left top point as a BPoint. 332 333 \since BeOS R3 334*/ 335 336 337/*! 338 \fn inline BPoint BRect::RightBottom() const 339 \brief Returns the right bottom point of the BRect. 340 341 \return The right bottom point as a BPoint. 342 343 \since BeOS R3 344*/ 345 346 347/*! 348 \fn inline BPoint BRect::LeftBottom() const 349 \brief Returns the left bottom point of the BRect. 350 351 \return The left bottom point as a BPoint. 352 353 \since BeOS R3 354*/ 355 356 357/*! 358 \fn inline BPoint BRect::RightTop() const 359 \brief Returns the right top point of the BRect. 360 361 \return The left right point as a BPoint. 362 363 \since BeOS R3 364*/ 365 366 367/*! 368 \name Transformation 369 370 Positive values make the rectangle smaller, negative values make it larger. 371 372 The …Self() versions also return the transformed BRect when they are done. 373 The …Copy() versions transform a copy without changing the original. 374*/ 375 376 377//! @{ 378 379 380/*! 381 \fn void BRect::InsetBy(BPoint point) 382 \brief Inset the BRect by the x and y coordinates of \a point. 383 384 \param point The \a point to use to inset the BRect. 385 386 \since BeOS R3 387*/ 388 389 390/*! 391 \fn void BRect::InsetBy(float dx, float dy) 392 \brief Inset the BRect by \a dx units in the horizontal direction and 393 \a dy units in the vertical direction. 394 395 \param dx The horizontal distance to inset the BRect by. 396 \param dy The vertical distance to inset the BRect by. 397 398 \since BeOS R3 399*/ 400 401 402/*! 403 \fn BRect& BRect::InsetBySelf(BPoint point) 404 \brief Like BRect::InsetBy() but returns the transformed BRect. 405 406 \param point The \a point to use to inset the BRect. 407 408 \return The transformed BRect. 409 410 \sa BRect::InsetBy(BPoint point) 411 412 \since BeOS R5 413*/ 414 415 416/*! 417 \fn BRect& BRect::InsetBySelf(float dx, float dy) 418 \brief Like BRect::InsetBy() but returns the transformed BRect. 419 420 \param dx The horizontal distance to inset the BRect by. 421 \param dy The vertical distance to inset the BRect by. 422 423 \return The transformed BRect. 424 425 \sa BRect::InsetBy(float dx, float dy) 426 427 \since BeOS R5 428*/ 429 430 431/*! 432 \fn BRect BRect::InsetByCopy(BPoint point) const 433 \brief Like BRect::InsetBy() but returns a copy of the transformed BRect 434 leaving the original unmodified. 435 436 \param point The \a point to use to inset the BRect. 437 438 \return A copy of the BRect after it has been transformed. 439 440 \sa BRect::InsetBy(BPoint point) 441 442 \since BeOS R5 443*/ 444 445 446/*! 447 \fn BRect BRect::InsetByCopy(float dx, float dy) const 448 \brief Like BRect::InsetBy() but returns a copy of the transformed BRect 449 leaving the original unmodified. 450 451 \param dx The horizontal distance to inset the BRect by. 452 \param dy The vertical distance to inset the BRect by. 453 454 \return A copy of the BRect after it has been transformed. 455 456 \sa BRect::InsetBy(float dx, float dy) 457 458 \since BeOS R5 459*/ 460 461 462//! @} 463 464 465/*! 466 \name Translation 467 468 Positive values move the rectangle right and down, negative values move the 469 rectangle left and up. 470 471 The …Self() versions also return the translated BRect when they are done. 472 The …Copy() versions translate a copy without changing the original. 473*/ 474 475 476//! @{ 477 478 479/*! 480 \fn void BRect::OffsetBy(BPoint point) 481 \brief Moves the BRect horizontally by the x value of \a point and 482 vertically by y value of \a point without changing the size 483 of the rectangle. 484 485 \param point The \a point to use to move the rectangle. 486 487 \since BeOS R3 488*/ 489 490 491/*! 492 \fn void BRect::OffsetBy(float dx, float dy) 493 \brief Moves the BRect horizontally by \a dx units and vertically by 494 \a dy units point without changing the size of the rectangle. 495 496 \param dx The number of units the move the rectangle vertically. 497 \param dy The number of units the move the rectangle horizontally. 498 499 \since BeOS R3 500*/ 501 502 503/*! 504 \fn BRect& BRect::OffsetBySelf(BPoint point) 505 \brief Like BRect::OffsetBy() but returns the translated BRect. 506 507 \param point The \a point to use to move the rectangle. 508 509 \sa BRect::OffsetBy(BPoint point) 510 511 \since BeOS R5 512*/ 513 514 515/*! 516 \fn BRect& BRect::OffsetBySelf(float dx, float dy) 517 \brief Like BRect::OffsetBy() but returns the translated BRect. 518 519 \param dx The number of units the move the rectangle vertically. 520 \param dy The number of units the move the rectangle horizontally. 521 522 \return The translated BRect. 523 524 \sa BRect::OffsetBy(float dx, float dy) 525 526 \since BeOS R5 527*/ 528 529 530/*! 531 \fn BRect BRect::OffsetByCopy(BPoint point) const 532 \brief Like BRect::OffsetBy() but returns a copy of the translated 533 BRect leaving the original unmodified. 534 535 \param point The \a point to use to move the rectangle. 536 537 \return A copy of the BRect after it has been translated. 538 539 \sa BRect::OffsetBy(BPoint point) 540 541 \since BeOS R5 542*/ 543 544 545/*! 546 \fn BRect BRect::OffsetByCopy(float dx, float dy) const 547 \brief Like BRect::OffsetBy() but returns a copy of the translated 548 BRect leaving the original unmodified. 549 550 \param dx The number of units the move the rectangle vertically. 551 \param dy The number of units the move the rectangle horizontally. 552 553 \return A copy of the BRect after it has been translated. 554 555 \sa BRect::OffsetBy(float dx, float dy) 556 557 \since BeOS R5 558*/ 559 560 561/*! 562 \fn void BRect::OffsetTo(BPoint point) 563 \brief Move the BRect to the location specified by \a point. 564 565 \param point The location to move the BRect to. 566 567 \since BeOS R3 568*/ 569 570 571/*! 572 \fn void BRect::OffsetTo(float x, float y) 573 \brief Move the BRect to the point specified by the given \a x and \a y 574 coordinates. 575 576 \param x The vertical coordinate of the point to move the BRect to. 577 \param y The horizontal coordinate of the point to move the BRect to. 578 579 \since BeOS R3 580*/ 581 582 583/*! 584 \fn BRect& BRect::OffsetToSelf(BPoint point) 585 \brief Like BRect::OffsetTo() but returns the translated BRect. 586 587 \param point The \a point to use to move the rectangle. 588 589 \return The translated BRect. 590 591 \sa BRect::OffsetTo(BPoint point) 592 593 \since BeOS R5 594*/ 595 596 597/*! 598 \fn BRect& BRect::OffsetToSelf(float x, float y) 599 \brief Like BRect::OffsetTo() but returns the translated BRect. 600 601 \param x The vertical coordinate of the point to move the BRect to. 602 \param y The horizontal coordinate of the point to move the BRect to. 603 604 \return The translated BRect. 605 606 \sa BRect::OffsetTo(float x, float y) 607 608 \since BeOS R5 609*/ 610 611 612/*! 613 \fn BRect BRect::OffsetToCopy(BPoint point) const 614 \brief Like BRect::OffsetTo() but returns a copy of the translated 615 BRect leaving the original unmodified. 616 617 \param point The \a point to use to move the rectangle. 618 619 \return A copy of the BRect after it has been translated. 620 621 \sa BRect::OffsetTo(BPoint point) 622 623 \since BeOS R5 624*/ 625 626 627/*! 628 \fn BRect BRect::OffsetToCopy(float x, float y) const 629 \brief Like BRect::OffsetTo() but returns a copy of the translated 630 BRect leaving the original unmodified. 631 632 \param x The number of units the move the rectangle vertically. 633 \param y The number of units the move the rectangle horizontally. 634 635 \return A copy of the BRect after it has been translated. 636 637 \sa BRect::OffsetTo(float x, float y) 638 639 \since BeOS R5 640*/ 641 642 643//! @} 644 645 646/*! 647 \name Operators 648*/ 649 650 651//! @{ 652 653 654/*! 655 \fn inline BRect& BRect::operator=(const BRect& other) 656 \brief Creates a new BRect object as a copy of \a other by overloading 657 the = operator. 658 659 \param other The BRect object to copy. 660 661 \return The newly created BRect object. 662 663 \since BeOS R3 664*/ 665 666 667/*! 668 \fn bool BRect::operator==(BRect other) const 669 \brief Returns whether or not two rectangles coincide exactly. 670 671 \param other The BRect to compare with. 672 673 \return \c true if the rectangles coincide, \c false otherwise. 674 675 \since BeOS R3 676*/ 677 678 679/*! 680 \fn bool BRect::operator!=(BRect other) const 681 \brief Returns whether or not two rectangles do NOT coincide exactly. 682 683 \param other The BRect to compare with. 684 685 \return \c true if the rectangles do NOT coincide, \c false otherwise. 686 687 \since BeOS R3 688*/ 689 690 691/*! 692 \fn BRect BRect::operator&(BRect other) const 693 \brief Creates and returns a new BRect that is the intersection of the 694 BRect and \a other. 695 696 The intersection of two rectangles is the area that they both share. 697 698 \param other The BRect to take the intersection of. 699 700 \return A new BRect that is the intersection of the BRect and \a other. 701 702 \since BeOS R3 703*/ 704 705 706/*! 707 \fn BRect BRect::operator|(BRect other) const 708 \brief Returns a new BRect that is the union of the BRect and \a other. 709 710 The union of two rectangles is the area that encloses both rectangles. 711 712 \param other The BRect to take the union of. 713 714 \return A new BRect that is the union of the BRect and \a other. 715 716 \since BeOS R3 717*/ 718 719 720//! @} 721