1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtCore module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    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 QRect QRect::normalize() const

   321     \compat

   322 

   323     Returns a normalized rectangle; i.e., a rectangle that has a

   324     non-negative width and height.

   325 

   326     Use the normalized() function instead

   327 */

   328 

   329 /*!

   330     \fn int QRect::left() const

   331 

   332     Returns the x-coordinate of the rectangle's left edge. Equivalent

   333     to x().

   334 

   335     \sa setLeft(),  topLeft(), bottomLeft()

   336 */

   337 

   338 /*!

   339     \fn int QRect::top() const

   340 

   341     Returns the y-coordinate of the rectangle's top edge.

   342     Equivalent to y().

   343 

   344     \sa setTop(), topLeft(), topRight()

   345 */

   346 

   347 /*!

   348     \fn int QRect::right() const

   349 

   350     Returns the x-coordinate of the rectangle's right edge.

   351 

   352     Note that for historical reasons this function returns left() +

   353     width() - 1; use x() + width() to retrieve the true x-coordinate.

   354 

   355     \sa setRight(), topRight(), bottomRight()

   356 */

   357 

   358 /*!

   359     \fn int QRect::bottom() const

   360 

   361     Returns the y-coordinate of the rectangle's bottom edge.

   362 

   363     Note that for historical reasons this function returns top() +

   364     height() - 1; use y() + height() to retrieve the true y-coordinate.

   365 

   366     \sa setBottom(), bottomLeft(), bottomRight()

   367 */

   368 

   369 /*!

   370     \fn int &QRect::rLeft()

   371     \compat

   372 

   373     Returns a reference to the left coordinate of the rectangle.

   374 

   375     Use the left() function instead.

   376 */

   377 

   378 /*!

   379     \fn int &QRect::rTop()

   380     \compat

   381 

   382     Returns a reference to the top coordinate of the rectangle.

   383 

   384     Use the top() function instead.

   385 */

   386 

   387 /*!

   388     \fn int &QRect::rRight()

   389     \compat

   390 

   391     Returns a reference to the right coordinate of the rectangle.

   392 

   393     Use the right() function instead.

   394 */

   395 

   396 /*!

   397     \fn int &QRect::rBottom()

   398     \compat

   399 

   400     Returns a reference to the bottom coordinate of the rectangle.

   401 

   402     Use the bottom() function instead.

   403 */

   404 

   405 /*!

   406     \fn int QRect::x() const

   407 

   408     Returns the x-coordinate of the rectangle's left edge. Equivalent to left().

   409 

   410     \sa setX(), y(), topLeft()

   411 */

   412 

   413 /*!

   414     \fn int QRect::y() const

   415 

   416     Returns the y-coordinate of the rectangle's top edge. Equivalent to top().

   417 

   418     \sa setY(), x(), topLeft()

   419 */

   420 

   421 /*!

   422     \fn void QRect::setLeft(int x)

   423 

   424     Sets the left edge of the rectangle to the given \a x

   425     coordinate. May change the width, but will never change the right

   426     edge of the rectangle.

   427 

   428     Equivalent to setX().

   429 

   430     \sa left(), moveLeft()

   431 */

   432 

   433 /*!

   434     \fn void QRect::setTop(int y)

   435 

   436     Sets the top edge of the rectangle to the given \a y

   437     coordinate. May change the height, but will never change the

   438     bottom edge of the rectangle.

   439 

   440     Equivalent to setY().

   441 

   442     \sa top(), moveTop()

   443 */

   444 

   445 /*!

   446     \fn void QRect::setRight(int x)

   447 

   448     Sets the right edge of the rectangle to the given \a x

   449     coordinate. May change the width, but will never change the left

   450     edge of the rectangle.

   451 

   452     \sa right(), moveRight()

   453 */

   454 

   455 /*!

   456     \fn void QRect::setBottom(int y)

   457 

   458     Sets the bottom edge of the rectangle to the given \a y

   459     coordinate. May change the height, but will never change the top

   460     edge of the rectangle.

   461 

   462     \sa bottom(), moveBottom(),

   463 */

   464 

   465 /*!

   466     \fn void QRect::setX(int x)

   467 

   468     Sets the left edge of the rectangle to the given \a x

   469     coordinate. May change the width, but will never change the right

   470     edge of the rectangle.

   471 

   472     Equivalent to setLeft().

   473 

   474     \sa x(), setY(), setTopLeft()

   475 */

   476 

   477 /*!

   478     \fn void QRect::setY(int y)

   479 

   480     Sets the top edge of the rectangle to the given \a y

   481     coordinate. May change the height, but will never change the

   482     bottom edge of the rectangle.

   483 

   484     Equivalent to setTop().

   485 

   486     \sa y(), setX(), setTopLeft()

   487 */

   488 

   489 /*!

   490     \fn void QRect::setTopLeft(const QPoint &position)

   491 

   492     Set the top-left corner of the rectangle to the given \a

   493     position. May change the size, but will never change the

   494     bottom-right corner of the rectangle.

   495 

   496     \sa topLeft(), moveTopLeft()

   497 */

   498 

   499 /*!

   500     \fn void QRect::setBottomRight(const QPoint &position)

   501 

   502     Set the bottom-right corner of the rectangle to the given \a

   503     position. May change the size, but will never change the

   504     top-left corner of the rectangle.

   505 

   506     \sa bottomRight(), moveBottomRight()

   507 */

   508 

   509 /*!

   510     \fn void QRect::setTopRight(const QPoint &position)

   511 

   512     Set the top-right corner of the rectangle to the given \a

   513     position. May change the size, but will never change the

   514     bottom-left corner of the rectangle.

   515 

   516     \sa topRight(), moveTopRight()

   517 */

   518 

   519 /*!

   520     \fn void QRect::setBottomLeft(const QPoint &position)

   521 

   522     Set the bottom-left corner of the rectangle to the given \a

   523     position. May change the size, but will never change the

   524     top-right corner of the rectangle.

   525 

   526     \sa bottomLeft(), moveBottomLeft()

   527 */

   528 

   529 /*!

   530     \fn QPoint QRect::topLeft() const

   531 

   532     Returns the position of the rectangle's top-left corner.

   533 

   534     \sa setTopLeft(), top(), left()

   535 */

   536 

   537 /*!

   538     \fn QPoint QRect::bottomRight() const

   539 

   540     Returns the position of the rectangle's bottom-right corner.

   541 

   542     Note that for historical reasons this function returns

   543     QPoint(left() + width() -1, top() + height() - 1).

   544 

   545     \sa setBottomRight(), bottom(), right()

   546 */

   547 

   548 /*!

   549     \fn QPoint QRect::topRight() const

   550 

   551     Returns the position of the rectangle's top-right corner.

   552 

   553     Note that for historical reasons this function returns

   554     QPoint(left() + width() -1, top()).

   555 

   556     \sa setTopRight(), top(), right()

   557 */

   558 

   559 /*!

   560     \fn QPoint QRect::bottomLeft() const

   561 

   562     Returns the position of the rectangle's bottom-left corner. Note

   563     that for historical reasons this function returns QPoint(left(),

   564     top() + height() - 1).

   565 

   566     \sa setBottomLeft(), bottom(), left()

   567 */

   568 

   569 /*!

   570     \fn QPoint QRect::center() const

   571 

   572     Returns the center point of the rectangle.

   573 

   574     \sa moveCenter()

   575 */

   576 

   577 

   578 /*!

   579     \fn void QRect::getRect(int *x, int *y, int *width, int *height) const

   580 

   581     Extracts the position of the rectangle's top-left corner to *\a x

   582     and *\a y, and its dimensions to *\a width and *\a height.

   583 

   584     \sa setRect(), getCoords()

   585 */

   586 

   587 

   588 /*!

   589     \fn void QRect::getCoords(int *x1, int *y1, int *x2, int *y2) const

   590 

   591     Extracts the position of the rectangle's top-left corner to *\a x1

   592     and *\a y1, and the position of the bottom-right corner to *\a x2

   593     and *\a y2.

   594 

   595     \sa setCoords(), getRect()

   596 */

   597 

   598 /*!

   599     \fn void QRect::rect(int *x, int *y, int *width, int *height) const

   600     \compat

   601 

   602     Extracts the position of the rectangle's top-left corner to *\a x and

   603     *\a y, and its dimensions to *\a width and * \a height.

   604 

   605     Use the getRect() function instead.

   606 */

   607 

   608 

   609 /*!

   610     \fn void QRect::coords(int *x1, int *y1, int *x2, int *y2) const

   611     \compat

   612 

   613     Extracts the position of the rectangle's top-left corner to *\a x1

   614     and *\a y1, and the position of the bottom-right corner to *\a x2

   615     and *\a y2.

   616 

   617     Use the getCoords() function instead.

   618 */

   619 

   620 /*!

   621     \fn void QRect::moveLeft(int x)

   622 

   623     Moves the rectangle horizontally, leaving the rectangle's left

   624     edge at the given \a x coordinate. The rectangle's size is

   625     unchanged.

   626 

   627     \sa left(), setLeft(), moveRight()

   628 */

   629 

   630 /*!

   631     \fn void QRect::moveTop(int y)

   632 

   633     Moves the rectangle vertically, leaving the rectangle's top edge

   634     at the given \a y coordinate. The rectangle's size is unchanged.

   635 

   636     \sa top(), setTop(), moveBottom()

   637 */

   638 

   639 

   640 /*!

   641     \fn void QRect::moveRight(int x)

   642 

   643     Moves the rectangle horizontally, leaving the rectangle's right

   644     edge at the given \a x coordinate. The rectangle's size is

   645     unchanged.

   646 

   647     \sa right(), setRight(), moveLeft()

   648 */

   649 

   650 

   651 /*!

   652     \fn void QRect::moveBottom(int y)

   653 

   654     Moves the rectangle vertically, leaving the rectangle's bottom

   655     edge at the given \a y coordinate. The rectangle's size is

   656     unchanged.

   657 

   658     \sa bottom(), setBottom(), moveTop()

   659 */

   660 

   661 

   662 /*!

   663     \fn void QRect::moveTopLeft(const QPoint &position)

   664 

   665     Moves the rectangle, leaving the top-left corner at the given \a

   666     position. The rectangle's size is unchanged.

   667 

   668     \sa setTopLeft(), moveTop(), moveLeft()

   669 */

   670 

   671 

   672 /*!

   673     \fn void QRect::moveBottomRight(const QPoint &position)

   674 

   675     Moves the rectangle, leaving the bottom-right corner at the given

   676     \a position. The rectangle's size is unchanged.

   677 

   678     \sa setBottomRight(), moveRight(), moveBottom()

   679 */

   680 

   681 

   682 /*!

   683     \fn void QRect::moveTopRight(const QPoint &position)

   684 

   685     Moves the rectangle, leaving the top-right corner at the given \a

   686     position. The rectangle's size is unchanged.

   687 

   688     \sa setTopRight(), moveTop(), moveRight()

   689 */

   690 

   691 

   692 /*!

   693     \fn void QRect::moveBottomLeft(const QPoint &position)

   694 

   695     Moves the rectangle, leaving the bottom-left corner at the given

   696     \a position. The rectangle's size is unchanged.

   697 

   698     \sa setBottomLeft(), moveBottom(), moveLeft()

   699 */

   700 

   701 

   702 /*!

   703     \fn void QRect::moveCenter(const QPoint &position)

   704 

   705     Moves the rectangle, leaving the center point at the given \a

   706     position. The rectangle's size is unchanged.

   707 

   708     \sa center()

   709 */

   710 

   711 void QRect::moveCenter(const QPoint &p)

   712 {

   713     int w = x2 - x1;

   714     int h = y2 - y1;

   715     x1 = p.x() - w/2;

   716     y1 = p.y() - h/2;

   717     x2 = x1 + w;

   718     y2 = y1 + h;

   719 }

   720 

   721 /*!

   722     \fn void QRect::moveBy(int dx, int dy)

   723     \compat

   724 

   725     Moves the rectangle \a dx along the x axis and \a dy along the y

   726     axis, relative to the current position.

   727 

   728     Use the translate() function instead.

   729 */

   730 

   731 /*!

   732     \fn void QRect::moveBy(const QPoint &)

   733     \compat

   734 

   735     Use the translate() function instead.

   736 */

   737 

   738 /*!

   739     \fn void QRect::moveTo(int x, int y)

   740 

   741     Moves the rectangle, leaving the top-left corner at the given

   742     position (\a x, \a y).  The rectangle's size is unchanged.

   743 

   744     \sa translate(), moveTopLeft()

   745 */

   746 

   747 /*!

   748     \fn void QRect::moveTo(const QPoint &position)

   749 

   750     Moves the rectangle, leaving the top-left corner at the given \a

   751     position.

   752 */

   753 

   754 /*!

   755     \fn void QRect::translate(int dx, int dy)

   756 

   757     Moves the rectangle \a dx along the x axis and \a dy along the y

   758     axis, relative to the current position. Positive values move the

   759     rectangle to the right and down.

   760 

   761     \sa moveTopLeft(), moveTo(), translated()

   762 */

   763 

   764 

   765 /*!

   766     \fn void QRect::translate(const QPoint &offset)

   767     \overload

   768 

   769     Moves the rectangle \a{offset}.\l{QPoint::x()}{x()} along the x

   770     axis and \a{offset}.\l{QPoint::y()}{y()} along the y axis,

   771     relative to the current position.

   772 */

   773 

   774 

   775 /*!

   776     \fn QRect QRect::translated(int dx, int dy) const

   777 

   778     Returns a copy of the rectangle that is translated \a dx along the

   779     x axis and \a dy along the y axis, relative to the current

   780     position. Positive values move the rectangle to the right and

   781     down.

   782 

   783     \sa translate()

   784 

   785 */

   786 

   787 

   788 /*!

   789     \fn QRect QRect::translated(const QPoint &offset) const

   790 

   791     \overload

   792 

   793     Returns a copy of the rectangle that is translated

   794     \a{offset}.\l{QPoint::x()}{x()} along the x axis and

   795     \a{offset}.\l{QPoint::y()}{y()} along the y axis, relative to the

   796     current position.

   797 */

   798 

   799 

   800 /*!

   801     \fn void QRect::setRect(int x, int y, int width, int height)

   802 

   803     Sets the coordinates of the rectangle's top-left corner to (\a{x},

   804     \a{y}), and its size to the given \a width and \a height.

   805 

   806     \sa getRect(), setCoords()

   807 */

   808 

   809 

   810 /*!

   811     \fn void QRect::setCoords(int x1, int y1, int x2, int y2)

   812 

   813     Sets the coordinates of the rectangle's top-left corner to (\a x1,

   814     \a y1), and the coordinates of its bottom-right corner to (\a x2,

   815     \a y2).

   816 

   817     \sa getCoords(), setRect()

   818 */

   819 

   820 

   821 /*!

   822     \fn void QRect::addCoords(int dx1, int dy1, int dx2, int dy2)

   823     \compat

   824 

   825     Adds \a dx1, \a dy1, \a dx2 and \a dy2 to the existing coordinates

   826     of the rectangle respectively.

   827 

   828     Use the adjust() function instead.

   829 */

   830 

   831 /*! \fn QRect QRect::adjusted(int dx1, int dy1, int dx2, int dy2) const

   832 

   833     Returns a new rectangle with \a dx1, \a dy1, \a dx2 and \a dy2

   834     added respectively to the existing coordinates of this rectangle.

   835 

   836     \sa adjust()

   837 */

   838 

   839 /*! \fn void QRect::adjust(int dx1, int dy1, int dx2, int dy2)

   840 

   841     Adds \a dx1, \a dy1, \a dx2 and \a dy2 respectively to the

   842     existing coordinates of the rectangle.

   843 

   844     \sa adjusted(), setRect()

   845 */

   846 

   847 /*!

   848     \fn QSize QRect::size() const

   849 

   850     Returns the size of the rectangle.

   851 

   852     \sa setSize(), width(), height()

   853 */

   854 

   855 /*!

   856     \fn int QRect::width() const

   857 

   858     Returns the width of the rectangle.

   859 

   860     \sa setWidth(), height(),  size()

   861 */

   862 

   863 /*!

   864     \fn int QRect::height() const

   865 

   866     Returns the height of the rectangle.

   867 

   868     \sa setHeight(), width(), size()

   869 */

   870 

   871 /*!

   872     \fn void QRect::setWidth(int width)

   873 

   874     Sets the width of the rectangle to the given \a width. The right

   875     edge is changed, but not the left one.

   876 

   877     \sa width(), setSize()

   878 */

   879 

   880 

   881 /*!

   882     \fn void QRect::setHeight(int height)

   883 

   884     Sets the height of the rectangle to the given \a height. The bottom

   885     edge is changed, but not the top one.

   886 

   887     \sa height(), setSize()

   888 */

   889 

   890 

   891 /*!

   892     \fn void QRect::setSize(const QSize &size)

   893 

   894     Sets the size of the rectangle to the given \a size. The top-left

   895     corner is not moved.

   896 

   897     \sa size(), setWidth(), setHeight()

   898 */

   899 

   900 

   901 /*!

   902     \fn bool QRect::contains(const QPoint &point, bool proper) const

   903 

   904     Returns true if the given \a point is inside or on the edge of

   905     the rectangle, otherwise returns false. If \a proper is true, this

   906     function only returns true if the given \a point is \e inside the

   907     rectangle (i.e., not on the edge).

   908 

   909     \sa intersects()

   910 */

   911 

   912 bool QRect::contains(const QPoint &p, bool proper) const

   913 {

   914     int l, r;

   915     if (x2 < x1 - 1) {

   916         l = x2;

   917         r = x1;

   918     } else {

   919         l = x1;

   920         r = x2;

   921     }

   922     if (proper) {

   923         if (p.x() <= l || p.x() >= r)

   924             return false;

   925     } else {

   926         if (p.x() < l || p.x() > r)

   927             return false;

   928     }

   929     int t, b;

   930     if (y2 < y1 - 1) {

   931         t = y2;

   932         b = y1;

   933     } else {

   934         t = y1;

   935         b = y2;

   936     }

   937     if (proper) {

   938         if (p.y() <= t || p.y() >= b)

   939             return false;

   940     } else {

   941         if (p.y() < t || p.y() > b)

   942             return false;

   943     }

   944     return true;

   945 }

   946 

   947 

   948 /*!

   949     \fn bool QRect::contains(int x, int y, bool proper) const

   950     \overload

   951 

   952     Returns true if the point (\a x, \a y) is inside or on the edge of

   953     the rectangle, otherwise returns false. If \a proper is true, this

   954     function only returns true if the point is entirely inside the

   955     rectangle(not on the edge).

   956 */

   957 

   958 /*!

   959     \fn bool QRect::contains(int x, int y) const

   960     \overload

   961 

   962     Returns true if the point (\a x, \a y) is inside this rectangle,

   963     otherwise returns false.

   964 */

   965 

   966 /*!

   967     \fn bool QRect::contains(const QRect &rectangle, bool proper) const

   968     \overload

   969 

   970     Returns true if the given \a rectangle is inside this rectangle.

   971     otherwise returns false. If \a proper is true, this function only

   972     returns true if the \a rectangle is entirely inside this

   973     rectangle (not on the edge).

   974 */

   975 

   976 bool QRect::contains(const QRect &r, bool proper) const

   977 {

   978     if (isNull() || r.isNull())

   979         return false;

   980 

   981     int l1 = x1;

   982     int r1 = x1;

   983     if (x2 - x1 + 1 < 0)

   984         l1 = x2;

   985     else

   986         r1 = x2;

   987 

   988     int l2 = r.x1;

   989     int r2 = r.x1;

   990     if (r.x2 - r.x1 + 1 < 0)

   991         l2 = r.x2;

   992     else

   993         r2 = r.x2;

   994 

   995     if (proper) {

   996         if (l2 <= l1 || r2 >= r1)

   997             return false;

   998     } else {

   999         if (l2 < l1 || r2 > r1)

  1000             return false;

  1001     }

  1002 

  1003     int t1 = y1;

  1004     int b1 = y1;

  1005     if (y2 - y1 + 1 < 0)

  1006         t1 = y2;

  1007     else

  1008         b1 = y2;

  1009 

  1010     int t2 = r.y1;

  1011     int b2 = r.y1;

  1012     if (r.y2 - r.y1 + 1 < 0)

  1013         t2 = r.y2;

  1014     else

  1015         b2 = r.y2;

  1016 

  1017     if (proper) {

  1018         if (t2 <= t1 || b2 >= b1)

  1019             return false;

  1020     } else {

  1021         if (t2 < t1 || b2 > b1)

  1022             return false;

  1023     }

  1024 

  1025     return true;

  1026 }

  1027 

  1028 /*!

  1029     \fn QRect& QRect::operator|=(const QRect &rectangle)

  1030 

  1031     Unites this rectangle with the given \a rectangle.

  1032 

  1033     \sa united(), operator|()

  1034 */

  1035 

  1036 /*!

  1037     \fn QRect& QRect::operator&=(const QRect &rectangle)

  1038 

  1039     Intersects this rectangle with the given \a rectangle.

  1040 

  1041     \sa intersected(), operator&()

  1042 */

  1043 

  1044 

  1045 /*!

  1046     \fn QRect QRect::operator|(const QRect &rectangle) const

  1047 

  1048     Returns the bounding rectangle of this rectangle and the given \a

  1049     rectangle.

  1050 

  1051     \sa operator|=(), united()

  1052 */

  1053 

  1054 QRect QRect::operator|(const QRect &r) const

  1055 {

  1056     if (isNull())

  1057         return r;

  1058     if (r.isNull())

  1059         return *this;

  1060 

  1061     int l1 = x1;

  1062     int r1 = x1;

  1063     if (x2 - x1 + 1 < 0)

  1064         l1 = x2;

  1065     else

  1066         r1 = x2;

  1067 

  1068     int l2 = r.x1;

  1069     int r2 = r.x1;

  1070     if (r.x2 - r.x1 + 1 < 0)

  1071         l2 = r.x2;

  1072     else

  1073         r2 = r.x2;

  1074 

  1075     int t1 = y1;

  1076     int b1 = y1;

  1077     if (y2 - y1 + 1 < 0)

  1078         t1 = y2;

  1079     else

  1080         b1 = y2;

  1081 

  1082     int t2 = r.y1;

  1083     int b2 = r.y1;

  1084     if (r.y2 - r.y1 + 1 < 0)

  1085         t2 = r.y2;

  1086     else

  1087         b2 = r.y2;

  1088 

  1089     QRect tmp;

  1090     tmp.x1 = qMin(l1, l2);

  1091     tmp.x2 = qMax(r1, r2);

  1092     tmp.y1 = qMin(t1, t2);

  1093     tmp.y2 = qMax(b1, b2);

  1094     return tmp;

  1095 }

  1096 

  1097 /*!

  1098     \fn QRect QRect::unite(const QRect &rectangle) const

  1099     \obsolete

  1100 

  1101     Use united(\a rectangle) instead.

  1102 */

  1103 

  1104 /*!

  1105     \fn QRect QRect::united(const QRect &rectangle) const

  1106     \since 4.2

  1107 

  1108     Returns the bounding rectangle of this rectangle and the given \a rectangle.

  1109 

  1110     \image qrect-unite.png

  1111 

  1112     \sa intersected()

  1113 */

  1114 

  1115 

  1116 /*!

  1117     \fn QRect QRect::operator&(const QRect &rectangle) const

  1118 

  1119     Returns the intersection of this rectangle and the given \a

  1120     rectangle. Returns an empty rectangle if there is no intersection.

  1121 

  1122     \sa operator&=(), intersected()

  1123 */

  1124 

  1125 QRect QRect::operator&(const QRect &r) const

  1126 {

  1127     if (isNull() || r.isNull())

  1128         return QRect();

  1129 

  1130     int l1 = x1;

  1131     int r1 = x1;

  1132     if (x2 - x1 + 1 < 0)

  1133         l1 = x2;

  1134     else