src/corelib/tools/qrect.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: http://www.qt-project.org/
   6 **
   7 ** This file is part of the QtCore module of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** GNU Lesser General Public License Usage
  11 ** This file may be used under the terms of the GNU Lesser General Public
  12 ** License version 2.1 as published by the Free Software Foundation and
  13 ** appearing in the file LICENSE.LGPL included in the packaging of this
  14 ** file. Please review the following information to ensure the GNU Lesser
  15 ** General Public License version 2.1 requirements will be met:
  16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  17 **
  18 ** In addition, as a special exception, Nokia gives you certain additional
  19 ** rights. These rights are described in the Nokia Qt LGPL Exception
  20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  21 **
  22 ** GNU General Public License Usage
  23 ** Alternatively, this file may be used under the terms of the GNU General
  24 ** Public License version 3.0 as published by the Free Software Foundation
  25 ** and appearing in the file LICENSE.GPL included in the packaging of this
  26 ** file. Please review the following information to ensure the GNU General
  27 ** Public License version 3.0 requirements will be met:
  28 ** http://www.gnu.org/copyleft/gpl.html.
  29 **
  30 ** Other Usage
  31 ** Alternatively, this file may be used in accordance with the terms and
  32 ** conditions contained in a signed written agreement between you and Nokia.
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qrect.h"
  43 #include "qdatastream.h"
  44 #include "qdebug.h"
  45 #include "qmath.h"
  46
  47 #include <math.h>
  48
  49 QT_BEGIN_NAMESPACE
  50
  51 /*!
  52     \class QRect
  53     \ingroup painting
  54
  55     \brief The QRect class defines a rectangle in the plane using
  56     integer precision.
  57
  58     A rectangle is normally expressed as an upper-left corner and a
  59     size.  The size (width and height) of a QRect is always equivalent
  60     to the mathematical rectangle that forms the basis for its
  61     rendering.
  62
  63     A QRect can be constructed with a set of left, top, width and
  64     height integers, or from a QPoint and a QSize.  The following code
  65     creates two identical rectangles.
  66
  67     \snippet doc/src/snippets/code/src_corelib_tools_qrect.cpp 0
  68
  69     There is a third constructor that creates a QRect using the
  70     top-left and bottom-right coordinates, but we recommend that you
  71     avoid using it. The rationale is that for historical reasons the
  72     values returned by the bottom() and right() functions deviate from
  73     the true bottom-right corner of the rectangle.
  74
  75     The QRect class provides a collection of functions that return the
  76     various rectangle coordinates, and enable manipulation of
  77     these. QRect also provide functions to move the rectangle relative
  78     to the various coordinates. In addition there is a moveTo()
  79     function that moves the rectangle, leaving its top left corner at
  80     the given coordinates. Alternatively, the translate() function
  81     moves the rectangle the given offset relative to the current
  82     position, and the translated() function returns a translated copy
  83     of this rectangle.
  84
  85     The size() function returns the rectange's dimensions as a
  86     QSize. The dimensions can also be retrieved separately using the
  87     width() and height() functions. To manipulate the dimensions use
  88     the setSize(), setWidth() or setHeight() functions. Alternatively,
  89     the size can be changed by applying either of the functions
  90     setting the rectangle coordinates, for example, setBottom() or
  91     setRight().
  92
  93     The contains() function tells whether a given point is inside the
  94     rectangle or not, and the intersects() function returns true if
  95     this rectangle intersects with a given rectangle. The QRect class
  96     also provides the intersected() function which returns the
  97     intersection rectangle, and the united() function which returns the
  98     rectangle that encloses the given rectangle and this:
  99
 100     \table
 101     \row
 102     \o \inlineimage qrect-intersect.png
 103     \o \inlineimage qrect-unite.png
 104     \row
 105     \o intersected()
 106     \o united()
 107     \endtable
 108
 109     The isEmpty() function returns true if left() > right() or top() >
 110     bottom(). Note that an empty rectangle is not valid: The isValid()
 111     function returns true if left() <= right() \e and top() <=
 112     bottom(). A null rectangle (isNull() == true) on the other hand,
 113     has both width and height set to 0.
 114
 115     Note that due to the way QRect and QRectF are defined, an
 116     empty QRect is defined in essentially the same way as QRectF.
 117
 118     Finally, QRect objects can be streamed as well as compared.
 119
 120     \tableofcontents
 121
 122     \section1 Rendering
 123
 124     When using an \l {QPainter::Antialiasing}{anti-aliased} painter,
 125     the boundary line of a QRect will be rendered symmetrically on
 126     both sides of the mathematical rectangle's boundary line. But when
 127     using an aliased painter (the default) other rules apply.
 128
 129     Then, when rendering with a one pixel wide pen the QRect's boundary
 130     line will be rendered to the right and below the mathematical
 131     rectangle's boundary line.
 132
 133     When rendering with a two pixels wide pen the boundary line will
 134     be split in the middle by the mathematical rectangle. This will be
 135     the case whenever the pen is set to an even number of pixels,
 136     while rendering with a pen with an odd number of pixels, the spare
 137     pixel will be rendered to the right and below the mathematical
 138     rectangle as in the one pixel case.
 139
 140     \table
 141     \row
 142         \o \inlineimage qrect-diagram-zero.png
 143         \o \inlineimage qrect-diagram-one.png
 144     \row
 145         \o Logical representation
 146         \o One pixel wide pen
 147     \row
 148         \o \inlineimage qrect-diagram-two.png
 149         \o \inlineimage qrect-diagram-three.png
 150     \row
 151         \o Two pixel wide pen
 152         \o Three pixel wide pen
 153     \endtable
 154
 155     \section1 Coordinates
 156
 157     The QRect class provides a collection of functions that return the
 158     various rectangle coordinates, and enable manipulation of
 159     these. QRect also provide functions to move the rectangle relative
 160     to the various coordinates.
 161
 162     For example the left(), setLeft() and moveLeft() functions as an
 163     example: left() returns the x-coordinate of the rectangle's left
 164     edge, setLeft() sets the left edge of the rectangle to the given x
 165     coordinate (it may change the width, but will never change the
 166     rectangle's right edge) and moveLeft() moves the entire rectangle
 167     horizontally, leaving the rectangle's left edge at the given x
 168     coordinate and its size unchanged.
 169
 170     \image qrect-coordinates.png
 171
 172     Note that for historical reasons the values returned by the
 173     bottom() and right() functions deviate from the true bottom-right
 174     corner of the rectangle: The right() function returns \e { left()
 175     + width() - 1} and the bottom() function returns \e {top() +
 176     height() - 1}. The same is the case for the point returned by the
 177     bottomRight() convenience function. In addition, the x and y
 178     coordinate of the topRight() and bottomLeft() functions,
 179     respectively, contain the same deviation from the true right and
 180     bottom edges.
 181
 182     We recommend that you use x() + width() and y() + height() to find
 183     the true bottom-right corner, and avoid right() and
 184     bottom(). Another solution is to use QRectF: The QRectF class
 185     defines a rectangle in the plane using floating point accuracy for
 186     coordinates, and the QRectF::right() and QRectF::bottom()
 187     functions \e do return the right and bottom coordinates.
 188
 189     It is also possible to add offsets to this rectangle's coordinates
 190     using the adjust() function, as well as retrieve a new rectangle
 191     based on adjustments of the original one using the adjusted()
 192     function. If either of the width and height is negative, use the
 193     normalized() function to retrieve a rectangle where the corners
 194     are swapped.
 195
 196     In addition, QRect provides the getCoords() function which extracts
 197     the position of the rectangle's top-left and bottom-right corner,
 198     and the getRect() function which extracts the rectangle's top-left
 199     corner, width and height. Use the setCoords() and setRect()
 200     function to manipulate the rectangle's coordinates and dimensions
 201     in one go.
 202
 203     \sa QRectF, QRegion
 204 */
 205
 206 /*****************************************************************************
 207   QRect member functions
 208  *****************************************************************************/
 209
 210 /*!
 211     \fn QRect::QRect()
 212
 213     Constructs a null rectangle.
 214
 215     \sa isNull()
 216 */
 217
 218 /*!
 219     \fn QRect::QRect(const QPoint &topLeft, const QPoint &bottomRight)
 220
 221     Constructs a rectangle with the given \a topLeft and \a bottomRight corners.
 222
 223     \sa setTopLeft(), setBottomRight()
 224 */
 225
 226
 227 /*!
 228     \fn QRect::QRect(const QPoint &topLeft, const QSize &size)
 229
 230     Constructs a rectangle with the given \a topLeft corner and the
 231     given \a size.
 232
 233     \sa setTopLeft(), setSize()
 234 */
 235
 236
 237 /*!
 238     \fn QRect::QRect(int x, int y, int width, int height)
 239
 240     Constructs a rectangle with (\a x, \a y) as its top-left corner
 241     and the given \a width and \a height.
 242
 243     \sa setRect()
 244 */
 245
 246
 247 /*!
 248     \fn bool QRect::isNull() const
 249
 250     Returns true if the rectangle is a null rectangle, otherwise
 251     returns false.
 252
 253     A null rectangle has both the width and the height set to 0 (i.e.,
 254     right() == left() - 1 and bottom() == top() - 1). A null rectangle
 255     is also empty, and hence is not valid.
 256
 257     \sa isEmpty(), isValid()
 258 */
 259
 260 /*!
 261     \fn bool QRect::isEmpty() const
 262
 263     Returns true if the rectangle is empty, otherwise returns false.
 264
 265     An empty rectangle has a left() > right() or top() > bottom(). An
 266     empty rectangle is not valid (i.e., isEmpty() == !isValid()).
 267
 268     Use the normalized() function to retrieve a rectangle where the
 269     corners are swapped.
 270
 271     \sa isNull(), isValid(), normalized()
 272 */
 273
 274 /*!
 275     \fn bool QRect::isValid() const
 276
 277     Returns true if the rectangle is valid, otherwise returns false.
 278
 279     A valid rectangle has a left() < right() and top() <
 280     bottom(). Note that non-trivial operations like intersections are
 281     not defined for invalid rectangles. A valid rectangle is not empty
 282     (i.e., isValid() == !isEmpty()).
 283
 284     \sa isNull(), isEmpty(), normalized()
 285 */
 286
 287
 288 /*!
 289     Returns a normalized rectangle; i.e., a rectangle that has a
 290     non-negative width and height.
 291
 292     If width() < 0 the function swaps the left and right corners, and
 293     it swaps the top and bottom corners if height() < 0.
 294
 295     \sa isValid(), isEmpty()
 296 */
 297
 298 QRect QRect::normalized() const
 299 {
 300     QRect r;
 301     if (x2 < x1 - 1) {                                // swap bad x values
 302         r.x1 = x2;
 303         r.x2 = x1;
 304     } else {
 305         r.x1 = x1;
 306         r.x2 = x2;
 307     }
 308     if (y2 < y1 - 1) {                                // swap bad y values
 309         r.y1 = y2;
 310         r.y2 = y1;
 311     } else {
 312         r.y1 = y1;
 313         r.y2 = y2;
 314     }
 315     return r;
 316 }
 317
 318
 319 /*!
 320     \fn int QRect::left() const
 321
 322     Returns the x-coordinate of the rectangle's left edge. Equivalent
 323     to x().
 324
 325     \sa setLeft(),  topLeft(), bottomLeft()
 326 */
 327
 328 /*!
 329     \fn int QRect::top() const
 330
 331     Returns the y-coordinate of the rectangle's top edge.
 332     Equivalent to y().
 333
 334     \sa setTop(), topLeft(), topRight()
 335 */
 336
 337 /*!
 338     \fn int QRect::right() const
 339
 340     Returns the x-coordinate of the rectangle's right edge.
 341
 342     Note that for historical reasons this function returns left() +
 343     width() - 1; use x() + width() to retrieve the true x-coordinate.
 344
 345     \sa setRight(), topRight(), bottomRight()
 346 */
 347
 348 /*!
 349     \fn int QRect::bottom() const
 350
 351     Returns the y-coordinate of the rectangle's bottom edge.
 352
 353     Note that for historical reasons this function returns top() +
 354     height() - 1; use y() + height() to retrieve the true y-coordinate.
 355
 356     \sa setBottom(), bottomLeft(), bottomRight()
 357 */
 358
 359 /*!
 360     \fn int QRect::x() const
 361
 362     Returns the x-coordinate of the rectangle's left edge. Equivalent to left().
 363
 364     \sa setX(), y(), topLeft()
 365 */
 366
 367 /*!
 368     \fn int QRect::y() const
 369
 370     Returns the y-coordinate of the rectangle's top edge. Equivalent to top().
 371
 372     \sa setY(), x(), topLeft()
 373 */
 374
 375 /*!
 376     \fn void QRect::setLeft(int x)
 377
 378     Sets the left edge of the rectangle to the given \a x
 379     coordinate. May change the width, but will never change the right
 380     edge of the rectangle.
 381
 382     Equivalent to setX().
 383
 384     \sa left(), moveLeft()
 385 */
 386
 387 /*!
 388     \fn void QRect::setTop(int y)
 389
 390     Sets the top edge of the rectangle to the given \a y
 391     coordinate. May change the height, but will never change the
 392     bottom edge of the rectangle.
 393
 394     Equivalent to setY().
 395
 396     \sa top(), moveTop()
 397 */
 398
 399 /*!
 400     \fn void QRect::setRight(int x)
 401
 402     Sets the right edge of the rectangle to the given \a x
 403     coordinate. May change the width, but will never change the left
 404     edge of the rectangle.
 405
 406     \sa right(), moveRight()
 407 */
 408
 409 /*!
 410     \fn void QRect::setBottom(int y)
 411
 412     Sets the bottom edge of the rectangle to the given \a y
 413     coordinate. May change the height, but will never change the top
 414     edge of the rectangle.
 415
 416     \sa bottom(), moveBottom(),
 417 */
 418
 419 /*!
 420     \fn void QRect::setX(int x)
 421
 422     Sets the left edge of the rectangle to the given \a x
 423     coordinate. May change the width, but will never change the right
 424     edge of the rectangle.
 425
 426     Equivalent to setLeft().
 427
 428     \sa x(), setY(), setTopLeft()
 429 */
 430
 431 /*!
 432     \fn void QRect::setY(int y)
 433
 434     Sets the top edge of the rectangle to the given \a y
 435     coordinate. May change the height, but will never change the
 436     bottom edge of the rectangle.
 437
 438     Equivalent to setTop().
 439
 440     \sa y(), setX(), setTopLeft()
 441 */
 442
 443 /*!
 444     \fn void QRect::setTopLeft(const QPoint &position)
 445
 446     Set the top-left corner of the rectangle to the given \a
 447     position. May change the size, but will never change the
 448     bottom-right corner of the rectangle.
 449
 450     \sa topLeft(), moveTopLeft()
 451 */
 452
 453 /*!
 454     \fn void QRect::setBottomRight(const QPoint &position)
 455
 456     Set the bottom-right corner of the rectangle to the given \a
 457     position. May change the size, but will never change the
 458     top-left corner of the rectangle.
 459
 460     \sa bottomRight(), moveBottomRight()
 461 */
 462
 463 /*!
 464     \fn void QRect::setTopRight(const QPoint &position)
 465
 466     Set the top-right corner of the rectangle to the given \a
 467     position. May change the size, but will never change the
 468     bottom-left corner of the rectangle.
 469
 470     \sa topRight(), moveTopRight()
 471 */
 472
 473 /*!
 474     \fn void QRect::setBottomLeft(const QPoint &position)
 475
 476     Set the bottom-left corner of the rectangle to the given \a
 477     position. May change the size, but will never change the
 478     top-right corner of the rectangle.
 479
 480     \sa bottomLeft(), moveBottomLeft()
 481 */
 482
 483 /*!
 484     \fn QPoint QRect::topLeft() const
 485
 486     Returns the position of the rectangle's top-left corner.
 487
 488     \sa setTopLeft(), top(), left()
 489 */
 490
 491 /*!
 492     \fn QPoint QRect::bottomRight() const
 493
 494     Returns the position of the rectangle's bottom-right corner.
 495
 496     Note that for historical reasons this function returns
 497     QPoint(left() + width() -1, top() + height() - 1).
 498
 499     \sa setBottomRight(), bottom(), right()
 500 */
 501
 502 /*!
 503     \fn QPoint QRect::topRight() const
 504
 505     Returns the position of the rectangle's top-right corner.
 506
 507     Note that for historical reasons this function returns
 508     QPoint(left() + width() -1, top()).
 509
 510     \sa setTopRight(), top(), right()
 511 */
 512
 513 /*!
 514     \fn QPoint QRect::bottomLeft() const
 515
 516     Returns the position of the rectangle's bottom-left corner. Note
 517     that for historical reasons this function returns QPoint(left(),
 518     top() + height() - 1).
 519
 520     \sa setBottomLeft(), bottom(), left()
 521 */
 522
 523 /*!
 524     \fn QPoint QRect::center() const
 525
 526     Returns the center point of the rectangle.
 527
 528     \sa moveCenter()
 529 */
 530
 531
 532 /*!
 533     \fn void QRect::getRect(int *x, int *y, int *width, int *height) const
 534
 535     Extracts the position of the rectangle's top-left corner to *\a x
 536     and *\a y, and its dimensions to *\a width and *\a height.
 537
 538     \sa setRect(), getCoords()
 539 */
 540
 541
 542 /*!
 543     \fn void QRect::getCoords(int *x1, int *y1, int *x2, int *y2) const
 544
 545     Extracts the position of the rectangle's top-left corner to *\a x1
 546     and *\a y1, and the position of the bottom-right corner to *\a x2
 547     and *\a y2.
 548
 549     \sa setCoords(), getRect()
 550 */
 551
 552 /*!
 553     \fn void QRect::moveLeft(int x)
 554
 555     Moves the rectangle horizontally, leaving the rectangle's left
 556     edge at the given \a x coordinate. The rectangle's size is
 557     unchanged.
 558
 559     \sa left(), setLeft(), moveRight()
 560 */
 561
 562 /*!
 563     \fn void QRect::moveTop(int y)
 564
 565     Moves the rectangle vertically, leaving the rectangle's top edge
 566     at the given \a y coordinate. The rectangle's size is unchanged.
 567
 568     \sa top(), setTop(), moveBottom()
 569 */
 570
 571
 572 /*!
 573     \fn void QRect::moveRight(int x)
 574
 575     Moves the rectangle horizontally, leaving the rectangle's right
 576     edge at the given \a x coordinate. The rectangle's size is
 577     unchanged.
 578
 579     \sa right(), setRight(), moveLeft()
 580 */
 581
 582
 583 /*!
 584     \fn void QRect::moveBottom(int y)
 585
 586     Moves the rectangle vertically, leaving the rectangle's bottom
 587     edge at the given \a y coordinate. The rectangle's size is
 588     unchanged.
 589
 590     \sa bottom(), setBottom(), moveTop()
 591 */
 592
 593
 594 /*!
 595     \fn void QRect::moveTopLeft(const QPoint &position)
 596
 597     Moves the rectangle, leaving the top-left corner at the given \a
 598     position. The rectangle's size is unchanged.
 599
 600     \sa setTopLeft(), moveTop(), moveLeft()
 601 */
 602
 603
 604 /*!
 605     \fn void QRect::moveBottomRight(const QPoint &position)
 606
 607     Moves the rectangle, leaving the bottom-right corner at the given
 608     \a position. The rectangle's size is unchanged.
 609
 610     \sa setBottomRight(), moveRight(), moveBottom()
 611 */
 612
 613
 614 /*!
 615     \fn void QRect::moveTopRight(const QPoint &position)
 616
 617     Moves the rectangle, leaving the top-right corner at the given \a
 618     position. The rectangle's size is unchanged.
 619
 620     \sa setTopRight(), moveTop(), moveRight()
 621 */
 622
 623
 624 /*!
 625     \fn void QRect::moveBottomLeft(const QPoint &position)
 626
 627     Moves the rectangle, leaving the bottom-left corner at the given
 628     \a position. The rectangle's size is unchanged.
 629
 630     \sa setBottomLeft(), moveBottom(), moveLeft()
 631 */
 632
 633
 634 /*!
 635     \fn void QRect::moveCenter(const QPoint &position)
 636
 637     Moves the rectangle, leaving the center point at the given \a
 638     position. The rectangle's size is unchanged.
 639
 640     \sa center()
 641 */
 642
 643 void QRect::moveCenter(const QPoint &p)
 644 {
 645     int w = x2 - x1;
 646     int h = y2 - y1;
 647     x1 = p.x() - w/2;
 648     y1 = p.y() - h/2;
 649     x2 = x1 + w;
 650     y2 = y1 + h;
 651 }
 652
 653 /*!
 654     \fn void QRect::moveTo(int x, int y)
 655
 656     Moves the rectangle, leaving the top-left corner at the given
 657     position (\a x, \a y).  The rectangle's size is unchanged.
 658
 659     \sa translate(), moveTopLeft()
 660 */
 661
 662 /*!
 663     \fn void QRect::moveTo(const QPoint &position)
 664
 665     Moves the rectangle, leaving the top-left corner at the given \a
 666     position.
 667 */
 668
 669 /*!
 670     \fn void QRect::translate(int dx, int dy)
 671
 672     Moves the rectangle \a dx along the x axis and \a dy along the y
 673     axis, relative to the current position. Positive values move the
 674     rectangle to the right and down.
 675
 676     \sa moveTopLeft(), moveTo(), translated()
 677 */
 678
 679
 680 /*!
 681     \fn void QRect::translate(const QPoint &offset)
 682     \overload
 683
 684     Moves the rectangle \a{offset}.\l{QPoint::x()}{x()} along the x
 685     axis and \a{offset}.\l{QPoint::y()}{y()} along the y axis,
 686     relative to the current position.
 687 */
 688
 689
 690 /*!
 691     \fn QRect QRect::translated(int dx, int dy) const
 692
 693     Returns a copy of the rectangle that is translated \a dx along the
 694     x axis and \a dy along the y axis, relative to the current
 695     position. Positive values move the rectangle to the right and
 696     down.
 697
 698     \sa translate()
 699
 700 */
 701
 702
 703 /*!
 704     \fn QRect QRect::translated(const QPoint &offset) const
 705
 706     \overload
 707
 708     Returns a copy of the rectangle that is translated
 709     \a{offset}.\l{QPoint::x()}{x()} along the x axis and
 710     \a{offset}.\l{QPoint::y()}{y()} along the y axis, relative to the
 711     current position.
 712 */
 713
 714
 715 /*!
 716     \fn void QRect::setRect(int x, int y, int width, int height)
 717
 718     Sets the coordinates of the rectangle's top-left corner to (\a{x},
 719     \a{y}), and its size to the given \a width and \a height.
 720
 721     \sa getRect(), setCoords()
 722 */
 723
 724
 725 /*!
 726     \fn void QRect::setCoords(int x1, int y1, int x2, int y2)
 727
 728     Sets the coordinates of the rectangle's top-left corner to (\a x1,
 729     \a y1), and the coordinates of its bottom-right corner to (\a x2,
 730     \a y2).
 731
 732     \sa getCoords(), setRect()
 733 */
 734
 735
 736 /*! \fn QRect QRect::adjusted(int dx1, int dy1, int dx2, int dy2) const
 737
 738     Returns a new rectangle with \a dx1, \a dy1, \a dx2 and \a dy2
 739     added respectively to the existing coordinates of this rectangle.
 740
 741     \sa adjust()
 742 */
 743
 744 /*! \fn void QRect::adjust(int dx1, int dy1, int dx2, int dy2)
 745
 746     Adds \a dx1, \a dy1, \a dx2 and \a dy2 respectively to the
 747     existing coordinates of the rectangle.
 748
 749     \sa adjusted(), setRect()
 750 */
 751
 752 /*!
 753     \fn QSize QRect::size() const
 754
 755     Returns the size of the rectangle.
 756
 757     \sa setSize(), width(), height()
 758 */
 759
 760 /*!
 761     \fn int QRect::width() const
 762
 763     Returns the width of the rectangle.
 764
 765     \sa setWidth(), height(),  size()
 766 */
 767
 768 /*!
 769     \fn int QRect::height() const
 770
 771     Returns the height of the rectangle.
 772
 773     \sa setHeight(), width(), size()
 774 */
 775
 776 /*!
 777     \fn void QRect::setWidth(int width)
 778
 779     Sets the width of the rectangle to the given \a width. The right
 780     edge is changed, but not the left one.
 781
 782     \sa width(), setSize()
 783 */
 784
 785
 786 /*!
 787     \fn void QRect::setHeight(int height)
 788
 789     Sets the height of the rectangle to the given \a height. The bottom
 790     edge is changed, but not the top one.
 791
 792     \sa height(), setSize()
 793 */
 794
 795
 796 /*!
 797     \fn void QRect::setSize(const QSize &size)
 798
 799     Sets the size of the rectangle to the given \a size. The top-left
 800     corner is not moved.
 801
 802     \sa size(), setWidth(), setHeight()
 803 */
 804
 805
 806 /*!
 807     \fn bool QRect::contains(const QPoint &point, bool proper) const
 808
 809     Returns true if the given \a point is inside or on the edge of
 810     the rectangle, otherwise returns false. If \a proper is true, this
 811     function only returns true if the given \a point is \e inside the
 812     rectangle (i.e., not on the edge).
 813
 814     \sa intersects()
 815 */
 816
 817 bool QRect::contains(const QPoint &p, bool proper) const
 818 {
 819     int l, r;
 820     if (x2 < x1 - 1) {
 821         l = x2;
 822         r = x1;
 823     } else {
 824         l = x1;
 825         r = x2;
 826     }
 827     if (proper) {
 828         if (p.x() <= l || p.x() >= r)
 829             return false;
 830     } else {
 831         if (p.x() < l || p.x() > r)
 832             return false;
 833     }
 834     int t, b;
 835     if (y2 < y1 - 1) {
 836         t = y2;
 837         b = y1;
 838     } else {
 839         t = y1;
 840         b = y2;
 841     }
 842     if (proper) {
 843         if (p.y() <= t || p.y() >= b)
 844             return false;
 845     } else {
 846         if (p.y() < t || p.y() > b)
 847             return false;
 848     }
 849     return true;
 850 }
 851
 852
 853 /*!
 854     \fn bool QRect::contains(int x, int y, bool proper) const
 855     \overload
 856
 857     Returns true if the point (\a x, \a y) is inside or on the edge of
 858     the rectangle, otherwise returns false. If \a proper is true, this
 859     function only returns true if the point is entirely inside the
 860     rectangle(not on the edge).
 861 */
 862
 863 /*!
 864     \fn bool QRect::contains(int x, int y) const
 865     \overload
 866
 867     Returns true if the point (\a x, \a y) is inside this rectangle,
 868     otherwise returns false.
 869 */
 870
 871 /*!
 872     \fn bool QRect::contains(const QRect &rectangle, bool proper) const
 873     \overload
 874
 875     Returns true if the given \a rectangle is inside this rectangle.
 876     otherwise returns false. If \a proper is true, this function only
 877     returns true if the \a rectangle is entirely inside this
 878     rectangle (not on the edge).
 879 */
 880
 881 bool QRect::contains(const QRect &r, bool proper) const
 882 {
 883     if (isNull() || r.isNull())
 884         return false;
 885
 886     int l1 = x1;
 887     int r1 = x1;
 888     if (x2 - x1 + 1 < 0)
 889         l1 = x2;
 890     else
 891         r1 = x2;
 892
 893     int l2 = r.x1;
 894     int r2 = r.x1;
 895     if (r.x2 - r.x1 + 1 < 0)
 896         l2 = r.x2;
 897     else
 898         r2 = r.x2;
 899
 900     if (proper) {
 901         if (l2 <= l1 || r2 >= r1)
 902             return false;
 903     } else {
 904         if (l2 < l1 || r2 > r1)
 905             return false;
 906     }
 907
 908     int t1 = y1;
 909     int b1 = y1;
 910     if (y2 - y1 + 1 < 0)
 911         t1 = y2;
 912     else
 913         b1 = y2;
 914
 915     int t2 = r.y1;
 916     int b2 = r.y1;
 917     if (r.y2 - r.y1 + 1 < 0)
 918         t2 = r.y2;
 919     else
 920         b2 = r.y2;
 921
 922     if (proper) {
 923         if (t2 <= t1 || b2 >= b1)
 924             return false;
 925     } else {
 926         if (t2 < t1 || b2 > b1)
 927             return false;
 928     }
 929
 930     return true;
 931 }
 932
 933 /*!
 934     \fn QRect& QRect::operator|=(const QRect &rectangle)
 935
 936     Unites this rectangle with the given \a rectangle.
 937
 938     \sa united(), operator|()
 939 */
 940
 941 /*!
 942     \fn QRect& QRect::operator&=(const QRect &rectangle)
 943
 944     Intersects this rectangle with the given \a rectangle.
 945
 946     \sa intersected(), operator&()
 947 */
 948
 949
 950 /*!
 951     \fn QRect QRect::operator|(const QRect &rectangle) const
 952
 953     Returns the bounding rectangle of this rectangle and the given \a
 954     rectangle.
 955
 956     \sa operator|=(), united()
 957 */
 958
 959 QRect QRect::operator|(const QRect &r) const
 960 {
 961     if (isNull())
 962         return r;
 963     if (r.isNull())
 964         return *this;
 965
 966     int l1 = x1;
 967     int r1 = x1;
 968     if (x2 - x1 + 1 < 0)
 969         l1 = x2;
 970     else
 971         r1 = x2;
 972
 973     int l2 = r.x1;
 974     int r2 = r.x1;
 975     if (r.x2 - r.x1 + 1 < 0)
 976         l2 = r.x2;
 977     else
 978         r2 = r.x2;
 979
 980     int t1 = y1;
 981     int b1 = y1;
 982     if (y2 - y1 + 1 < 0)
 983         t1 = y2;
 984     else
 985         b1 = y2;
 986
 987     int t2 = r.y1;
 988     int b2 = r.y1;
 989     if (r.y2 - r.y1 + 1 < 0)
 990         t2 = r.y2;
 991     else
 992         b2 = r.y2;
 993
 994     QRect tmp;
 995     tmp.x1 = qMin(l1, l2);
 996     tmp.x2 = qMax(r1, r2);
 997     tmp.y1 = qMin(t1, t2);
 998     tmp.y2 = qMax(b1, b2);
 999     return tmp;
1000 }
1001
1002 /*!
1003     \fn QRect QRect::unite(const QRect &rectangle) const
1004     \obsolete
1005
1006     Use united(\a rectangle) instead.
1007 */
1008
1009 /*!
1010     \fn QRect QRect::united(const QRect &rectangle) const
1011     \since 4.2
1012
1013     Returns the bounding rectangle of this rectangle and the given \a rectangle.
1014
1015     \image qrect-unite.png
1016
1017     \sa intersected()
1018 */
1019
1020
1021 /*!
1022     \fn QRect QRect::operator&(const QRect &rectangle) const
1023
1024     Returns the intersection of this rectangle and the given \a
1025     rectangle. Returns an empty rectangle if there is no intersection.
1026
1027     \sa operator&=(), intersected()
1028 */
1029
1030 QRect QRect::operator&(const QRect &r) const
1031 {
1032     if (isNull() || r.isNull())
1033         return QRect();
1034
1035     int l1 = x1;
1036     int r1 = x1;
1037     if (x2 - x1 + 1 < 0)
1038         l1 = x2;
1039     else
1040         r1 = x2;
1041
1042     int l2 = r.x1;
1043     int r2 = r.x1;
1044     if (r.x2 - r.x1 + 1 < 0)
1045         l2 = r.x2;
1046     else
1047         r2 = r.x2;
1048
1049     if (l1 > r2 || l2 > r1)
1050         return QRect();
1051
1052     int t1 = y1;
1053     int b1 = y1;
1054     if (y2 - y1 + 1 < 0)
1055         t1 = y2;
1056     else
1057         b1 = y2;
1058
1059     int t2 = r.y1;
1060     int b2 = r.y1;
1061     if (r.y2 - r.y1 + 1 < 0)
1062         t2 = r.y2;
1063     else
1064         b2 = r.y2;
1065
1066     if (t1 > b2 || t2 > b1)
1067         return QRect();
1068
1069     QRect tmp;
1070     tmp.x1 = qMax(l1, l2);
1071     tmp.x2 = qMin(r1, r2);
1072     tmp.y1 = qMax(t1, t2);
1073     tmp.y2 = qMin(b1, b2);
1074     return tmp;
1075 }
1076
1077 /*!
1078     \fn QRect QRect::intersect(const QRect &rectangle) const
1079     \obsolete
1080
1081     Use intersected(\a rectangle) instead.
1082 */
1083
1084 /*!
1085     \fn QRect QRect::intersected(const QRect &rectangle) const
1086     \since 4.2
1087
1088     Returns the intersection of this rectangle and the given \a
1089     rectangle. Note that \c{r.intersected(s)} is equivalent to \c{r & s}.
1090
1091     \image qrect-intersect.png
1092
1093     \sa intersects(), united(), operator&=()
1094 */
1095
1096 /*!
1097     \fn bool QRect::intersects(const QRect &rectangle) const
1098
1099     Returns true if this rectangle intersects with the given \a
1100     rectangle (i.e., there is at least one pixel that is within both
1101     rectangles), otherwise returns false.
1102
1103     The intersection rectangle can be retrieved using the intersected()
1104     function.
1105
1106     \sa  contains()
1107 */
1108
1109 bool QRect::intersects(const QRect &r) const
1110 {
1111     if (isNull() || r.isNull())
1112         return false;
1113
1114     int l1 = x1;
1115     int r1 = x1;
1116     if (x2 - x1 + 1 < 0)
1117         l1 = x2;
1118     else
1119         r1 = x2;
1120
1121     int l2 = r.x1;
1122     int r2 = r.x1;
1123     if (r.x2 - r.x1 + 1 < 0)
1124         l2 = r.x2;
1125     else
1126         r2 = r.x2;
1127
1128     if (l1 > r2 || l2 > r1)
1129         return false;
1130
1131     int t1 = y1;
1132     int b1 = y1;
1133     if (y2 - y1 + 1 < 0)
1134         t1 = y2;
1135     else
1136         b1 = y2;
1137
1138     int t2 = r.y1;
1139     int b2 = r.y1;
1140     if (r.y2 - r.y1 + 1 < 0)
1141         t2 = r.y2;
1142     else
1143         b2 = r.y2;
1144
1145     if (t1 > b2 || t2 > b1)
1146         return false;
1147
1148     return true;
1149 }
1150
1151 /*!
1152     \fn bool operator==(const QRect &r1, const QRect &r2)
1153     \relates QRect
1154
1155     Returns true if the rectangles \a r1 and \a r2 are equal,
1156     otherwise returns false.
1157 */
1158
1159
1160 /*!
1161     \fn bool operator!=(const QRect &r1, const QRect &r2)
1162     \relates QRect
1163
1164     Returns true if the rectangles \a r1 and \a r2 are different, otherwise
1165     returns false.
1166 */
1167
1168
1169 /*****************************************************************************
1170   QRect stream functions
1171  *****************************************************************************/
1172 #ifndef QT_NO_DATASTREAM
1173 /*!
1174     \fn QDataStream &operator<<(QDataStream &stream, const QRect &rectangle)
1175     \relates QRect
1176
1177     Writes the given \a rectangle to the given \a stream, and returns
1178     a reference to the stream.
1179
1180     \sa {Serializing Qt Data Types}
1181 */
1182
1183 QDataStream &operator<<(QDataStream &s, const QRect &r)
1184 {
1185     if (s.version() == 1)
1186         s << (qint16)r.left() << (qint16)r.top()
1187           << (qint16)r.right() << (qint16)r.bottom();
1188     else
1189         s << (qint32)r.left() << (qint32)r.top()
1190           << (qint32)r.right() << (qint32)r.bottom();
1191     return s;
1192 }
1193
1194 /*!
1195     \fn QDataStream &operator>>(QDataStream &stream, QRect &rectangle)
1196     \relates QRect
1197
1198     Reads a rectangle from the given \a stream into the given \a
1199     rectangle, and returns a reference to the stream.
1200
1201     \sa {Serializing Qt Data Types}
1202 */
1203
1204 QDataStream &operator>>(QDataStream &s, QRect &r)
1205 {
1206     if (s.version() == 1) {
1207         qint16 x1, y1, x2, y2;
1208         s >> x1; s >> y1; s >> x2; s >> y2;
1209         r.setCoords(x1, y1, x2, y2);
1210     }
1211     else {
1212         qint32 x1, y1, x2, y2;
1213         s >> x1; s >> y1; s >> x2; s >> y2;
1214         r.setCoords(x1, y1, x2, y2);
1215     }
1216     return s;
1217 }
1218
1219 #endif // QT_NO_DATASTREAM
1220
1221
1222 #ifndef QT_NO_DEBUG_STREAM
1223 QDebug operator<<(QDebug dbg, const QRect &r) {
1224     dbg.nospace() << "QRect(" << r.x() << ',' << r.y() << ' '
1225                   << r.width() << 'x' << r.height() << ')';
1226     return dbg.space();
1227 }
1228 #endif
1229
1230 /*!
1231     \class QRectF
1232     \ingroup painting
1233
1234     \brief The QRectF class defines a rectangle in the plane using floating
1235     point precision.
1236
1237     A rectangle is normally expressed as an upper-left corner and a
1238     size.  The size (width and height) of a QRectF is always equivalent
1239     to the mathematical rectangle that forms the basis for its
1240     rendering.
1241
1242     A QRectF can be constructed with a set of left, top, width and
1243     height integers, or from a QPoint and a QSize.  The following code
1244     creates two identical rectangles.
1245
1246     \snippet doc/src/snippets/code/src_corelib_tools_qrect.cpp 1
1247
1248     There is also a third constructor creating a QRectF from a QRect,
1249     and a corresponding toRect() function that returns a QRect object
1250     based on the values of this rectangle (note that the coordinates
1251     in the returned rectangle are rounded to the nearest integer).
1252
1253     The QRectF class provides a collection of functions that return
1254     the various rectangle coordinates, and enable manipulation of
1255     these. QRectF also provide functions to move the rectangle
1256     relative to the various coordinates. In addition there is a
1257     moveTo() function that moves the rectangle, leaving its top left
1258     corner at the given coordinates. Alternatively, the translate()
1259     function moves the rectangle the given offset relative to the
1260     current position, and the translated() function returns a
1261     translated copy of this rectangle.
1262
1263     The size() function returns the rectange's dimensions as a
1264     QSize. The dimensions can also be retrieved separately using the
1265     width() and height() functions. To manipulate the dimensions use
1266     the setSize(), setWidth() or setHeight() functions. Alternatively,
1267     the size can be changed by applying either of the functions
1268     setting the rectangle coordinates, for example, setBottom() or
1269     setRight().
1270
1271     The contains() function tells whether a given point is inside the
1272     rectangle or not, and the intersects() function returns true if
1273     this rectangle intersects with a given rectangle (otherwise
1274     false). The QRectF class also provides the intersected() function
1275     which returns the intersection rectangle, and the united() function
1276     which returns the rectangle that encloses the given rectangle and
1277     this:
1278
1279     \table
1280     \row
1281     \o \inlineimage qrect-intersect.png
1282     \o \inlineimage qrect-unite.png
1283     \row
1284     \o intersected()
1285     \o united()
1286     \endtable
1287
1288     The isEmpty() function returns true if the rectangle's width or
1289     height is less than, or equal to, 0. Note that an empty rectangle
1290     is not valid: The isValid() function returns true if both width
1291     and height is larger than 0. A null rectangle (isNull() == true)
1292     on the other hand, has both width and height set to 0.
1293
1294     Note that due to the way QRect and QRectF are defined, an
1295     empty QRectF is defined in essentially the same way as QRect.
1296
1297     Finally, QRectF objects can be streamed as well as compared.
1298
1299     \tableofcontents
1300
1301     \section1 Rendering
1302
1303     When using an \l {QPainter::Antialiasing}{anti-aliased} painter,
1304     the boundary line of a QRectF will be rendered symmetrically on both
1305     sides of the mathematical rectangle's boundary line. But when
1306     using an aliased painter (the default) other rules apply.
1307
1308     Then, when rendering with a one pixel wide pen the QRectF's boundary
1309     line will be rendered to the right and below the mathematical
1310     rectangle's boundary line.
1311
1312     When rendering with a two pixels wide pen the boundary line will
1313     be split in the middle by the mathematical rectangle. This will be
1314     the case whenever the pen is set to an even number of pixels,
1315     while rendering with a pen with an odd number of pixels, the spare
1316     pixel will be rendered to the right and below the mathematical
1317     rectangle as in the one pixel case.
1318
1319     \table
1320     \row
1321         \o \inlineimage qrect-diagram-zero.png
1322         \o \inlineimage qrectf-diagram-one.png
1323     \row
1324         \o Logical representation
1325         \o One pixel wide pen
1326     \row
1327         \o \inlineimage qrectf-diagram-two.png
1328         \o \inlineimage qrectf-diagram-three.png
1329     \row
1330         \o Two pixel wide pen
1331         \o Three pixel wide pen
1332     \endtable
1333
1334     \section1 Coordinates
1335
1336     The QRectF class provides a collection of functions that return
1337     the various rectangle coordinates, and enable manipulation of
1338     these. QRectF also provide functions to move the rectangle
1339     relative to the various coordinates.
1340
1341     For example: the bottom(), setBottom() and moveBottom() functions:
1342     bottom() returns the y-coordinate of the rectangle's bottom edge,
1343     setBottom() sets the bottom edge of the rectangle to the given y
1344     coordinate (it may change the height, but will never change the
1345     rectangle's top edge) and moveBottom() moves the entire rectangle
1346     vertically, leaving the rectangle's bottom edge at the given y
1347     coordinate and its size unchanged.
1348
1349     \image qrectf-coordinates.png
1350
1351     It is also possible to add offsets to this rectangle's coordinates
1352     using the adjust() function, as well as retrieve a new rectangle
1353     based on adjustments of the original one using the adjusted()
1354     function. If either of the width and height is negative, use the
1355     normalized() function to retrieve a rectangle where the corners
1356     are swapped.
1357
1358     In addition, QRectF provides the getCoords() function which extracts
1359     the position of the rectangle's top-left and bottom-right corner,
1360     and the getRect() function which extracts the rectangle's top-left
1361     corner, width and height. Use the setCoords() and setRect()
1362     function to manipulate the rectangle's coordinates and dimensions
1363     in one go.
1364
1365     \sa QRect, QRegion
1366 */
1367
1368 /*****************************************************************************
1369   QRectF member functions
1370  *****************************************************************************/
1371
1372 /*!
1373     \fn QRectF::QRectF()
1374
1375     Constructs a null rectangle.
1376
1377     \sa isNull()
1378 */
1379
1380 /*!
1381     \fn QRectF::QRectF(const QPointF &topLeft, const QSizeF &size)
1382
1383     Constructs a rectangle with the given \a topLeft corner and the given \a size.
1384
1385     \sa setTopLeft(), setSize()
1386 */
1387
1388 /*!
1389     \fn QRectF::QRectF(const QPointF &topLeft, const QPointF &bottomRight)
1390     \since 4.3
1391
1392     Constructs a rectangle with the given \a topLeft and \a bottomRight corners.
1393
1394     \sa setTopLeft(), setBottomRight()
1395 */
1396
1397 /*!
1398     \fn QRectF::QRectF(qreal x, qreal y, qreal width, qreal height)
1399
1400     Constructs a rectangle with (\a x, \a y) as its top-left corner
1401     and the given \a width and \a height.
1402
1403     \sa setRect()
1404 */
1405
1406 /*!
1407     \fn QRectF::QRectF(const QRect &rectangle)
1408
1409     Constructs a QRectF rectangle from the given QRect \a rectangle.
1410
1411     \sa toRect()
1412 */
1413
1414 /*!
1415     \fn bool QRectF::isNull() const
1416
1417     Returns true if the rectangle is a null rectangle, otherwise returns false.
1418
1419     A null rectangle has both the width and the height set to 0. A
1420     null rectangle is also empty, and hence not valid.
1421
1422     \sa isEmpty(), isValid()
1423 */
1424
1425 /*!
1426     \fn bool QRectF::isEmpty() const
1427
1428     Returns true if the rectangle is empty, otherwise returns false.
1429
1430     An empty rectangle has width() <= 0 or height() <= 0.  An empty
1431     rectangle is not valid (i.e., isEmpty() == !isValid()).
1432
1433     Use the normalized() function to retrieve a rectangle where the
1434     corners are swapped.
1435
1436     \sa isNull(),  isValid(),  normalized()
1437 */
1438
1439 /*!
1440     \fn bool QRectF::isValid() const
1441
1442     Returns true if the rectangle is valid, otherwise returns false.
1443
1444     A valid rectangle has a width() > 0 and height() > 0. Note that
1445     non-trivial operations like intersections are not defined for
1446     invalid rectangles. A valid rectangle is not empty (i.e., isValid()
1447     == !isEmpty()).
1448
1449     \sa isNull(), isEmpty(), normalized()
1450 */
1451
1452
1453 /*!
1454     Returns a normalized rectangle; i.e., a rectangle that has a
1455     non-negative width and height.
1456
1457     If width() < 0 the function swaps the left and right corners, and
1458     it swaps the top and bottom corners if height() < 0.
1459
1460     \sa isValid(), isEmpty()
1461 */
1462
1463 QRectF QRectF::normalized() const
1464 {
1465     QRectF r = *this;
1466     if (r.w < 0) {
1467         r.xp += r.w;
1468         r.w = -r.w;
1469     }
1470     if (r.h < 0) {
1471         r.yp += r.h;
1472         r.h = -r.h;
1473     }
1474     return r;
1475 }
1476
1477 /*!
1478     \fn qreal QRectF::x() const
1479
1480     Returns the x-coordinate of the rectangle's left edge. Equivalent
1481     to left().
1482
1483
1484     \sa setX(), y(), topLeft()
1485 */
1486
1487 /*!
1488     \fn qreal QRectF::y() const
1489
1490     Returns the y-coordinate of the rectangle's top edge. Equivalent
1491     to top().
1492
1493     \sa setY(), x(),  topLeft()
1494 */
1495
1496
1497 /*!
1498     \fn void QRectF::setLeft(qreal x)
1499
1500     Sets the left edge of the rectangle to the given \a x
1501     coordinate. May change the width, but will never change the right
1502     edge of the rectangle.
1503
1504     Equivalent to setX().
1505
1506     \sa left(), moveLeft()
1507 */
1508
1509 /*!
1510     \fn void QRectF::setTop(qreal y)
1511
1512     Sets the top edge of the rectangle to the given \a y coordinate. May
1513     change the height, but will never change the bottom edge of the
1514     rectangle.
1515
1516     Equivalent to setY().
1517
1518     \sa top(), moveTop()
1519 */
1520
1521 /*!
1522     \fn void QRectF::setRight(qreal x)
1523
1524     Sets the right edge of the rectangle to the given \a x
1525     coordinate. May change the width, but will never change the left
1526     edge of the rectangle.
1527
1528     \sa right(), moveRight()
1529 */
1530
1531 /*!
1532     \fn void QRectF::setBottom(qreal y)
1533
1534     Sets the bottom edge of the rectangle to the given \a y
1535     coordinate. May change the height, but will never change the top
1536     edge of the rectangle.
1537
1538     \sa bottom(), moveBottom()
1539 */
1540
1541 /*!
1542     \fn void QRectF::setX(qreal x)
1543
1544     Sets the left edge of the rectangle to the given \a x
1545     coordinate. May change the width, but will never change the right
1546     edge of the rectangle.
1547
1548     Equivalent to setLeft().
1549
1550     \sa x(), setY(), setTopLeft()
1551 */
1552
1553 /*!
1554     \fn void QRectF::setY(qreal y)
1555
1556     Sets the top edge of the rectangle to the given \a y
1557     coordinate. May change the height, but will never change the
1558     bottom edge of the rectangle.
1559
1560     Equivalent to setTop().
1561
1562     \sa y(), setX(), setTopLeft()
1563 */
1564
1565 /*!
1566     \fn void QRectF::setTopLeft(const QPointF &position)
1567
1568     Set the top-left corner of the rectangle to the given \a
1569     position. May change the size, but will never change the
1570     bottom-right corner of the rectangle.
1571
1572     \sa topLeft(), moveTopLeft()
1573 */
1574
1575 /*!
1576     \fn void QRectF::setBottomRight(const QPointF &position)
1577
1578     Set the bottom-right corner of the rectangle to the given \a
1579     position. May change the size, but will never change the
1580     top-left corner of the rectangle.
1581
1582     \sa bottomRight(), moveBottomRight()
1583 */
1584
1585 /*!
1586     \fn void QRectF::setTopRight(const QPointF &position)
1587
1588     Set the top-right corner of the rectangle to the given \a
1589     position. May change the size, but will never change the
1590     bottom-left corner of the rectangle.
1591
1592     \sa topRight(), moveTopRight()
1593 */
1594
1595 /*!
1596     \fn void QRectF::setBottomLeft(const QPointF &position)
1597
1598     Set the bottom-left corner of the rectangle to the given \a
1599     position. May change the size, but will never change the
1600     top-right corner of the rectangle.
1601
1602     \sa bottomLeft(), moveBottomLeft()
1603 */
1604
1605 /*!
1606     \fn QPointF QRectF::center() const
1607
1608     Returns the center point of the rectangle.
1609
1610     \sa moveCenter()
1611 */
1612
1613
1614 /*!
1615     \fn void QRectF::getRect(qreal *x, qreal *y, qreal *width, qreal *height) const
1616
1617     Extracts the position of the rectangle's top-left corner to *\a x and
1618     *\a y, and its dimensions to *\a width and *\a height.
1619
1620     \sa setRect(), getCoords()
1621 */
1622
1623
1624 /*!
1625     \fn void QRectF::getCoords(qreal *x1, qreal *y1, qreal *x2, qreal *y2) const
1626
1627     Extracts the position of the rectangle's top-left corner to *\a x1
1628     and *\a y1, and the position of the bottom-right corner to *\a x2 and
1629     *\a y2.
1630
1631     \sa setCoords(), getRect()
1632 */
1633
1634 /*!
1635     \fn void QRectF::moveLeft(qreal x)
1636
1637     Moves the rectangle horizontally, leaving the rectangle's left
1638     edge at the given \a x coordinate. The rectangle's size is
1639     unchanged.
1640
1641     \sa left(), setLeft(), moveRight()
1642 */
1643
1644 /*!
1645     \fn void QRectF::moveTop(qreal y)
1646
1647     Moves the rectangle vertically, leaving the rectangle's top line
1648     at the given \a y coordinate. The rectangle's size is unchanged.
1649
1650     \sa top(), setTop(), moveBottom()
1651 */
1652
1653
1654 /*!
1655     \fn void QRectF::moveRight(qreal x)
1656
1657     Moves the rectangle horizontally, leaving the rectangle's right
1658     edge at the given \a x coordinate. The rectangle's size is
1659     unchanged.
1660
1661     \sa right(), setRight(), moveLeft()
1662 */
1663
1664
1665 /*!
1666     \fn void QRectF::moveBottom(qreal y)
1667
1668     Moves the rectangle vertically, leaving the rectangle's bottom
1669     edge at the given \a y coordinate. The rectangle's size is
1670     unchanged.
1671
1672     \sa bottom(), setBottom(), moveTop()
1673 */
1674
1675
1676 /*!
1677     \fn void QRectF::moveTopLeft(const QPointF &position)
1678
1679     Moves the rectangle, leaving the top-left corner at the given \a
1680     position. The rectangle's size is unchanged.
1681
1682     \sa setTopLeft(), moveTop(), moveLeft()
1683 */
1684
1685
1686 /*!
1687     \fn void QRectF::moveBottomRight(const QPointF &position)
1688
1689     Moves the rectangle, leaving the bottom-right corner at the given
1690     \a position. The rectangle's size is unchanged.
1691
1692     \sa setBottomRight(), moveBottom(), moveRight()
1693 */
1694
1695
1696 /*!
1697     \fn void QRectF::moveTopRight(const QPointF &position)
1698
1699     Moves the rectangle, leaving the top-right corner at the given
1700     \a position. The rectangle's size is unchanged.
1701
1702     \sa setTopRight(), moveTop(), moveRight()
1703 */
1704
1705
1706 /*!
1707     \fn void QRectF::moveBottomLeft(const QPointF &position)
1708
1709     Moves the rectangle, leaving the bottom-left corner at the given
1710     \a position. The rectangle's size is unchanged.
1711
1712     \sa setBottomLeft(), moveBottom(), moveLeft()
1713 */
1714
1715
1716 /*!
1717     \fn void QRectF::moveTo(qreal x, qreal y)
1718
1719     Moves the rectangle, leaving the top-left corner at the given
1720     position (\a x, \a y). The rectangle's size is unchanged.
1721
1722     \sa translate(), moveTopLeft()
1723 */
1724
1725 /*!
1726     \fn void QRectF::moveTo(const QPointF &position)
1727     \overload
1728
1729     Moves the rectangle, leaving the top-left corner at the given \a
1730     position.
1731 */
1732
1733 /*!
1734     \fn void QRectF::translate(qreal dx, qreal dy)
1735
1736     Moves the rectangle \a dx along the x-axis and \a dy along the y-axis,
1737     relative to the current position. Positive values move the rectangle to the
1738     right and downwards.
1739
1740     \sa moveTopLeft(),  moveTo(),  translated()
1741 */
1742
1743
1744 /*!
1745     \fn void QRectF::translate(const QPointF &offset)
1746     \overload
1747
1748     Moves the rectangle \a{offset}.\l{QPointF::x()}{x()} along the x
1749     axis and \a{offset}.\l{QPointF::y()}{y()} along the y axis,
1750     relative to the current position.
1751 */
1752
1753
1754 /*!
1755     \fn QRectF QRectF::translated(qreal dx, qreal dy) const
1756
1757     Returns a copy of the rectangle that is translated \a dx along the
1758     x axis and \a dy along the y axis, relative to the current
1759     position. Positive values move the rectangle to the right and
1760     down.
1761
1762     \sa translate()
1763 */
1764
1765
1766 /*!
1767     \fn QRectF QRectF::translated(const QPointF &offset) const
1768     \overload
1769
1770     Returns a copy of the rectangle that is translated
1771     \a{offset}.\l{QPointF::x()}{x()} along the x axis and
1772     \a{offset}.\l{QPointF::y()}{y()} along the y axis, relative to the
1773     current position.
1774 */
1775
1776
1777 /*!
1778     \fn void QRectF::setRect(qreal x, qreal y, qreal width, qreal height)
1779
1780     Sets the coordinates of the rectangle's top-left corner to (\a x,
1781     \a y), and its size to the given \a width and \a height.
1782
1783     \sa getRect(), setCoords()
1784 */
1785
1786
1787 /*!
1788     \fn void QRectF::setCoords(qreal x1, qreal y1, qreal x2, qreal y2)
1789
1790     Sets the coordinates of the rectangle's top-left corner to (\a x1,
1791     \a y1), and the coordinates of its bottom-right corner to (\a x2,
1792     \a y2).
1793
1794     \sa getCoords() setRect()
1795 */
1796
1797 /*!
1798     \fn QRectF QRectF::adjusted(qreal dx1, qreal dy1, qreal dx2, qreal dy2) const
1799
1800     Returns a new rectangle with \a dx1, \a dy1, \a dx2 and \a dy2
1801     added respectively to the existing coordinates of this rectangle.
1802
1803     \sa adjust()
1804 */
1805
1806 /*! \fn void QRectF::adjust(qreal dx1, qreal dy1, qreal dx2, qreal dy2)
1807
1808     Adds \a dx1, \a dy1, \a dx2 and \a dy2 respectively to the
1809     existing coordinates of the rectangle.
1810
1811     \sa adjusted(), setRect()
1812 */
1813 /*!
1814     \fn QSizeF QRectF::size() const
1815
1816     Returns the size of the rectangle.
1817
1818     \sa setSize(), width(), height()
1819 */
1820
1821 /*!
1822     \fn qreal QRectF::width() const
1823
1824     Returns the width of the rectangle.
1825
1826     \sa setWidth(), height(), size()
1827 */
1828
1829 /*!
1830     \fn qreal QRectF::height() const
1831
1832     Returns the height of the rectangle.
1833
1834     \sa setHeight(), width(), size()
1835 */
1836
1837 /*!
1838     \fn void QRectF::setWidth(qreal width)
1839
1840     Sets the width of the rectangle to the given \a width. The right
1841     edge is changed, but not the left one.
1842
1843     \sa width(), setSize()
1844 */
1845
1846
1847 /*!
1848     \fn void QRectF::setHeight(qreal height)
1849
1850     Sets the height of the rectangle to the given \a height. The bottom
1851     edge is changed, but not the top one.
1852
1853     \sa height(), setSize()
1854 */
1855
1856
1857 /*!
1858     \fn void QRectF::setSize(const QSizeF &size)
1859
1860     Sets the size of the rectangle to the given \a size. The top-left
1861     corner is not moved.
1862
1863     \sa size(), setWidth(), setHeight()
1864 */
1865
1866
1867 /*!
1868     \fn bool QRectF::contains(const QPointF &point) const
1869
1870     Returns true if the given \a point is inside or on the edge of the
1871     rectangle; otherwise returns false.
1872
1873     \sa intersects()
1874 */
1875
1876 bool QRectF::contains(const QPointF &p) const
1877 {
1878     qreal l = xp;
1879     qreal r = xp;
1880     if (w < 0)
1881         l += w;
1882     else
1883         r += w;
1884     if (l == r) // null rect
1885         return false;
1886
1887     if (p.x() < l || p.x() > r)
1888         return false;
1889
1890     qreal t = yp;
1891     qreal b = yp;
1892     if (h < 0)
1893         t += h;
1894     else
1895         b += h;
1896     if (t == b) // null rect
1897         return false;
1898
1899     if (p.y() < t || p.y() > b)
1900         return false;
1901
1902     return true;
1903 }
1904
1905
1906 /*!
1907     \fn bool QRectF::contains(qreal x, qreal y) const
1908     \overload
1909
1910     Returns true if the point (\a x, \a y) is inside or on the edge of
1911     the rectangle; otherwise returns false.
1912 */
1913
1914 /*!
1915     \fn bool QRectF::contains(const QRectF &rectangle) const
1916     \overload
1917
1918     Returns true if the given \a rectangle is inside this rectangle;
1919     otherwise returns false.
1920 */
1921
1922 bool QRectF::contains(const QRectF &r) const
1923 {
1924     qreal l1 = xp;
1925     qreal r1 = xp;
1926     if (w < 0)
1927         l1 += w;
1928     else
1929         r1 += w;
1930     if (l1 == r1) // null rect
1931         return false;
1932
1933     qreal l2 = r.xp;
1934     qreal r2 = r.xp;
1935     if (r.w < 0)
1936         l2 += r.w;
1937     else
1938         r2 += r.w;
1939     if (l2 == r2) // null rect
1940         return false;
1941
1942     if (l2 < l1 || r2 > r1)
1943         return false;
1944
1945     qreal t1 = yp;
1946     qreal b1 = yp;
1947     if (h < 0)
1948         t1 += h;
1949     else
1950         b1 += h;
1951     if (t1 == b1) // null rect
1952         return false;
1953
1954     qreal t2 = r.yp;
1955     qreal b2 = r.yp;
1956     if (r.h < 0)
1957         t2 += r.h;
1958     else
1959         b2 += r.h;
1960     if (t2 == b2) // null rect
1961         return false;
1962
1963     if (t2 < t1 || b2 > b1)
1964         return false;
1965
1966     return true;
1967 }
1968
1969 /*!
1970     \fn qreal QRectF::left() const
1971
1972     Returns the x-coordinate of the rectangle's left edge. Equivalent
1973     to x().
1974
1975     \sa setLeft(), topLeft(), bottomLeft()
1976 */
1977
1978 /*!
1979     \fn qreal QRectF::top() const
1980
1981     Returns the y-coordinate of the rectangle's top edge. Equivalent
1982     to y().
1983
1984     \sa setTop(), topLeft(), topRight()
1985 */
1986
1987 /*!
1988     \fn qreal QRectF::right() const
1989
1990     Returns the x-coordinate of the rectangle's right edge.
1991
1992     \sa setRight(), topRight(), bottomRight()
1993 */
1994
1995 /*!
1996     \fn qreal QRectF::bottom() const
1997
1998     Returns the y-coordinate of the rectangle's bottom edge.
1999
2000     \sa setBottom(), bottomLeft(), bottomRight()
2001 */
2002
2003 /*!
2004     \fn QPointF QRectF::topLeft() const
2005
2006     Returns the position of the rectangle's top-left corner.
2007
2008     \sa setTopLeft(), top(), left()
2009 */
2010
2011 /*!
2012     \fn QPointF QRectF::bottomRight() const
2013
2014     Returns the position of the rectangle's  bottom-right corner.
2015
2016     \sa setBottomRight(), bottom(), right()
2017 */
2018
2019 /*!
2020     \fn QPointF QRectF::topRight() const
2021
2022     Returns the position of the rectangle's top-right corner.
2023
2024     \sa setTopRight(), top(), right()
2025 */
2026
2027 /*!
2028     \fn QPointF QRectF::bottomLeft() const
2029
2030     Returns the position of the rectangle's  bottom-left corner.
2031
2032     \sa setBottomLeft(),  bottom(), left()
2033 */
2034
2035 /*!
2036     \fn QRectF& QRectF::operator|=(const QRectF &rectangle)
2037
2038     Unites this rectangle with the given \a rectangle.
2039
2040     \sa united(), operator|()
2041 */
2042
2043 /*!
2044     \fn QRectF& QRectF::operator&=(const QRectF &rectangle)
2045
2046     Intersects this rectangle with the given \a rectangle.
2047
2048     \sa intersected(), operator|=()
2049 */
2050
2051
2052 /*!
2053     \fn QRectF QRectF::operator|(const QRectF &rectangle) const
2054
2055     Returns the bounding rectangle of this rectangle and the given \a rectangle.
2056
2057     \sa united(), operator|=()
2058 */
2059
2060 QRectF QRectF::operator|(const QRectF &r) const
2061 {
2062     if (isNull())
2063         return r;
2064     if (r.isNull())
2065         return *this;
2066
2067     qreal left = xp;
2068     qreal right = xp;
2069     if (w < 0)
2070         left += w;
2071     else
2072         right += w;
2073
2074     if (r.w < 0) {
2075         left = qMin(left, r.xp + r.w);
2076         right = qMax(right, r.xp);
2077     } else {
2078         left = qMin(left, r.xp);
2079         right = qMax(right, r.xp + r.w);
2080     }
2081
2082     qreal top = yp;
2083     qreal bottom = yp;
2084     if (h < 0)
2085         top += h;
2086     else
2087         bottom += h;
2088
2089     if (r.h < 0) {
2090         top = qMin(top, r.yp + r.h);
2091         bottom = qMax(bottom, r.yp);
2092     } else {
2093         top = qMin(top, r.yp);
2094         bottom = qMax(bottom, r.yp + r.h);
2095     }
2096
2097     return QRectF(left, top, right - left, bottom - top);
2098 }
2099
2100 /*!
2101     \fn QRectF QRectF::unite(const QRectF &rectangle) const
2102     \obsolete
2103
2104     Use united(\a rectangle) instead.
2105 */
2106
2107 /*!
2108     \fn QRectF QRectF::united(const QRectF &rectangle) const
2109     \since 4.2
2110
2111     Returns the bounding rectangle of this rectangle and the given \a
2112     rectangle.
2113
2114     \image qrect-unite.png
2115
2116     \sa intersected()
2117 */
2118
2119
2120 /*!
2121     \fn QRectF QRectF::operator &(const QRectF &rectangle) const
2122
2123     Returns the intersection of this rectangle and the given \a
2124     rectangle. Returns an empty rectangle if there is no intersection.
2125
2126     \sa operator&=(), intersected()
2127 */
2128
2129 QRectF QRectF::operator&(const QRectF &r) const
2130 {
2131     qreal l1 = xp;
2132     qreal r1 = xp;
2133     if (w < 0)
2134         l1 += w;
2135     else
2136         r1 += w;
2137     if (l1 == r1) // null rect
2138         return QRectF();
2139
2140     qreal l2 = r.xp;
2141     qreal r2 = r.xp;
2142     if (r.w < 0)
2143         l2 += r.w;
2144     else
2145         r2 += r.w;
2146     if (l2 == r2) // null rect
2147         return QRectF();
2148
2149     if (l1 >= r2 || l2 >= r1)
2150         return QRectF();
2151
2152     qreal t1 = yp;
2153     qreal b1 = yp;
2154     if (h < 0)
2155         t1 += h;
2156     else
2157         b1 += h;
2158     if (t1 == b1) // null rect
2159         return QRectF();
2160
2161     qreal t2 = r.yp;
2162     qreal b2 = r.yp;
2163     if (r.h < 0)
2164         t2 += r.h;
2165     else
2166         b2 += r.h;
2167     if (t2 == b2) // null rect
2168         return QRectF();
2169
2170     if (t1 >= b2 || t2 >= b1)
2171         return QRectF();
2172
2173     QRectF tmp;
2174     tmp.xp = qMax(l1, l2);
2175     tmp.yp = qMax(t1, t2);
2176     tmp.w = qMin(r1, r2) - tmp.xp;
2177     tmp.h = qMin(b1, b2) - tmp.yp;
2178     return tmp;
2179 }
2180
2181 /*!
2182     \fn QRectF QRectF::intersect(const QRectF &rectangle) const
2183     \obsolete
2184
2185     Use intersected(\a rectangle) instead.
2186 */
2187
2188 /*!
2189     \fn QRectF QRectF::intersected(const QRectF &rectangle) const
2190     \since 4.2
2191
2192     Returns the intersection of this rectangle and the given \a
2193     rectangle. Note that \c {r.intersected(s)} is equivalent to \c
2194     {r & s}.
2195
2196     \image qrect-intersect.png
2197
2198     \sa intersects(), united(), operator&=()
2199 */
2200
2201 /*!
2202     \fn bool QRectF::intersects(const QRectF &rectangle) const
2203
2204     Returns true if this rectangle intersects with the given \a
2205     rectangle (i.e. there is a non-empty area of overlap between
2206     them), otherwise returns false.
2207
2208     The intersection rectangle can be retrieved using the intersected()
2209     function.
2210
2211     \sa contains()
2212 */
2213
2214 bool QRectF::intersects(const QRectF &r) const
2215 {
2216     qreal l1 = xp;
2217     qreal r1 = xp;
2218     if (w < 0)
2219         l1 += w;
2220     else
2221         r1 += w;
2222     if (l1 == r1) // null rect
2223         return false;
2224
2225     qreal l2 = r.xp;
2226     qreal r2 = r.xp;
2227     if (r.w < 0)
2228         l2 += r.w;
2229     else
2230         r2 += r.w;
2231     if (l2 == r2) // null rect
2232         return false;
2233
2234     if (l1 >= r2 || l2 >= r1)
2235         return false;
2236
2237     qreal t1 = yp;
2238     qreal b1 = yp;
2239     if (h < 0)
2240         t1 += h;
2241     else
2242         b1 += h;
2243     if (t1 == b1) // null rect
2244         return false;
2245
2246     qreal t2 = r.yp;
2247     qreal b2 = r.yp;
2248     if (r.h < 0)
2249         t2 += r.h;
2250     else
2251         b2 += r.h;
2252     if (t2 == b2) // null rect
2253         return false;
2254
2255     if (t1 >= b2 || t2 >= b1)
2256         return false;
2257
2258     return true;
2259 }
2260
2261 /*!
2262     \fn QRect QRectF::toRect() const
2263
2264     Returns a QRect based on the values of this rectangle.  Note that the
2265     coordinates in the returned rectangle are rounded to the nearest integer.
2266
2267     \sa QRectF(), toAlignedRect()
2268 */
2269
2270 /*!
2271     \fn QRect QRectF::toAlignedRect() const
2272     \since 4.3
2273
2274     Returns a QRect based on the values of this rectangle that is the
2275     smallest possible integer rectangle that completely contains this
2276     rectangle.
2277
2278     \sa toRect()
2279 */
2280
2281 QRect QRectF::toAlignedRect() const
2282 {
2283     int xmin = int(qFloor(xp));
2284     int xmax = int(qCeil(xp + w));
2285     int ymin = int(qFloor(yp));
2286     int ymax = int(qCeil(yp + h));
2287     return QRect(xmin, ymin, xmax - xmin, ymax - ymin);
2288 }
2289
2290 /*!
2291     \fn void QRectF::moveCenter(const QPointF &position)
2292
2293     Moves the rectangle, leaving the center point at the given \a
2294     position. The rectangle's size is unchanged.
2295
2296     \sa center()
2297 */
2298
2299 /*!
2300     \fn bool operator==(const QRectF &r1, const QRectF &r2)
2301     \relates QRectF
2302
2303     Returns true if the rectangles \a r1 and \a r2 are equal,
2304     otherwise returns false.
2305 */
2306
2307
2308 /*!
2309     \fn bool operator!=(const QRectF &r1, const QRectF &r2)
2310     \relates QRectF
2311
2312     Returns true if the rectangles \a r1 and \a r2 are different, otherwise
2313     returns false.
2314 */
2315
2316 /*****************************************************************************
2317   QRectF stream functions
2318  *****************************************************************************/
2319 #ifndef QT_NO_DATASTREAM
2320 /*!
2321     \fn QDataStream &operator<<(QDataStream &stream, const QRectF &rectangle)
2322
2323     \relates QRectF
2324
2325     Writes the \a rectangle to the \a stream, and returns a reference to the
2326     stream.
2327
2328     \sa {Serializing Qt Data Types}
2329 */
2330
2331 QDataStream &operator<<(QDataStream &s, const QRectF &r)
2332 {
2333     s << double(r.x()) << double(r.y()) << double(r.width()) << double(r.height());
2334     return s;
2335 }
2336
2337 /*!
2338     \fn QDataStream &operator>>(QDataStream &stream, QRectF &rectangle)
2339
2340     \relates QRectF
2341
2342     Reads a \a rectangle from the \a stream, and returns a reference to the
2343     stream.
2344
2345     \sa {Serializing Qt Data Types}
2346 */
2347
2348 QDataStream &operator>>(QDataStream &s, QRectF &r)
2349 {
2350     double x, y, w, h;
2351     s >> x;
2352     s >> y;
2353     s >> w;
2354     s >> h;
2355     r.setRect(qreal(x), qreal(y), qreal(w), qreal(h));
2356     return s;
2357 }
2358
2359 #endif // QT_NO_DATASTREAM
2360
2361
2362 #ifndef QT_NO_DEBUG_STREAM
2363 QDebug operator<<(QDebug dbg, const QRectF &r) {
2364     dbg.nospace() << "QRectF(" << r.x() << ',' << r.y() << ' '
2365                   << r.width() << 'x' << r.height() << ')';
2366     return dbg.space();
2367 }
2368 #endif
2369
2370 QT_END_NAMESPACE