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