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 "qsize.h"
41#include "qdatastream.h"
42
43#include <private/qdebug_p.h>
44
45QT_BEGIN_NAMESPACE
46
47/*!
48 \class QSize
49 \inmodule QtCore
50 \ingroup painting
51
52 \brief The QSize class defines the size of a two-dimensional
53 object using integer point precision.
54
55 A size is specified by a width() and a height(). It can be set in
56 the constructor and changed using the setWidth(), setHeight(), or
57 scale() functions, or using arithmetic operators. A size can also
58 be manipulated directly by retrieving references to the width and
59 height using the rwidth() and rheight() functions. Finally, the
60 width and height can be swapped using the transpose() function.
61
62 The isValid() function determines if a size is valid (a valid size
63 has both width and height greater than or equal to zero). The isEmpty()
64 function returns \c true if either of the width and height is less
65 than, or equal to, zero, while the isNull() function returns \c true
66 only if both the width and the height is zero.
67
68 Use the expandedTo() function to retrieve a size which holds the
69 maximum height and width of \e this size and a given
70 size. Similarly, the boundedTo() function returns a size which
71 holds the minimum height and width of \e this size and a given
72 size.
73
74 QSize objects can be streamed as well as compared.
75
76 \sa QSizeF, QPoint, QRect
77*/
78
79
80/*****************************************************************************
81 QSize member functions
82 *****************************************************************************/
83
84/*!
85 \fn QSize::QSize()
86
87 Constructs a size with an invalid width and height (i.e., isValid()
88 returns \c false).
89
90 \sa isValid()
91*/
92
93/*!
94 \fn QSize::QSize(int width, int height)
95
96 Constructs a size with the given \a width and \a height.
97
98 \sa setWidth(), setHeight()
99*/
100
101/*!
102 \fn bool QSize::isNull() const
103
104 Returns \c true if both the width and height is 0; otherwise returns
105 false.
106
107 \sa isValid(), isEmpty()
108*/
109
110/*!
111 \fn bool QSize::isEmpty() const
112
113 Returns \c true if either of the width and height is less than or
114 equal to 0; otherwise returns \c false.
115
116 \sa isNull(), isValid()
117*/
118
119/*!
120 \fn bool QSize::isValid() const
121
122 Returns \c true if both the width and height is equal to or greater
123 than 0; otherwise returns \c false.
124
125 \sa isNull(), isEmpty()
126*/
127
128/*!
129 \fn int QSize::width() const
130
131 Returns the width.
132
133 \sa height(), setWidth()
134*/
135
136/*!
137 \fn int QSize::height() const
138
139 Returns the height.
140
141 \sa width(), setHeight()
142*/
143
144/*!
145 \fn void QSize::setWidth(int width)
146
147 Sets the width to the given \a width.
148
149 \sa rwidth(), width(), setHeight()
150*/
151
152/*!
153 \fn void QSize::setHeight(int height)
154
155 Sets the height to the given \a height.
156
157 \sa rheight(), height(), setWidth()
158*/
159
160/*!
161 Swaps the width and height values.
162
163 \sa setWidth(), setHeight(), transposed()
164*/
165
166void QSize::transpose() noexcept
167{
168 qSwap(wd, ht);
169}
170
171/*!
172 \fn QSize QSize::transposed() const
173 \since 5.0
174
175 Returns a QSize with width and height swapped.
176
177 \sa transpose()
178*/
179
180/*!
181 \fn void QSize::scale(int width, int height, Qt::AspectRatioMode mode)
182
183 Scales the size to a rectangle with the given \a width and \a
184 height, according to the specified \a mode:
185
186 \list
187 \li If \a mode is Qt::IgnoreAspectRatio, the size is set to (\a width, \a height).
188 \li If \a mode is Qt::KeepAspectRatio, the current size is scaled to a rectangle
189 as large as possible inside (\a width, \a height), preserving the aspect ratio.
190 \li If \a mode is Qt::KeepAspectRatioByExpanding, the current size is scaled to a rectangle
191 as small as possible outside (\a width, \a height), preserving the aspect ratio.
192 \endlist
193
194 Example:
195 \snippet code/src_corelib_tools_qsize.cpp 0
196
197 \sa setWidth(), setHeight(), scaled()
198*/
199
200/*!
201 \fn void QSize::scale(const QSize &size, Qt::AspectRatioMode mode)
202 \overload
203
204 Scales the size to a rectangle with the given \a size, according to
205 the specified \a mode.
206*/
207
208/*!
209 \fn QSize QSize::scaled(int width, int height, Qt::AspectRatioMode mode) const
210 \since 5.0
211
212 Return a size scaled to a rectangle with the given \a width and \a
213 height, according to the specified \a mode.
214
215 \sa scale()
216*/
217
218/*!
219 \overload
220 \since 5.0
221
222 Return a size scaled to a rectangle with the given size \a s,
223 according to the specified \a mode.
224*/
225QSize QSize::scaled(const QSize &s, Qt::AspectRatioMode mode) const noexcept
226{
227 if (mode == Qt::IgnoreAspectRatio || wd == 0 || ht == 0) {
228 return s;
229 } else {
230 bool useHeight;
231 qint64 rw = qint64(s.ht) * qint64(wd) / qint64(ht);
232
233 if (mode == Qt::KeepAspectRatio) {
234 useHeight = (rw <= s.wd);
235 } else { // mode == Qt::KeepAspectRatioByExpanding
236 useHeight = (rw >= s.wd);
237 }
238
239 if (useHeight) {
240 return QSize(rw, s.ht);
241 } else {
242 return QSize(s.wd,
243 qint32(qint64(s.wd) * qint64(ht) / qint64(wd)));
244 }
245 }
246}
247
248/*!
249 \fn int &QSize::rwidth()
250
251 Returns a reference to the width.
252
253 Using a reference makes it possible to manipulate the width
254 directly. For example:
255
256 \snippet code/src_corelib_tools_qsize.cpp 1
257
258 \sa rheight(), setWidth()
259*/
260
261/*!
262 \fn int &QSize::rheight()
263
264 Returns a reference to the height.
265
266 Using a reference makes it possible to manipulate the height
267 directly. For example:
268
269 \snippet code/src_corelib_tools_qsize.cpp 2
270
271 \sa rwidth(), setHeight()
272*/
273
274/*!
275 \fn QSize &QSize::operator+=(const QSize &size)
276
277 Adds the given \a size to \e this size, and returns a reference to
278 this size. For example:
279
280 \snippet code/src_corelib_tools_qsize.cpp 3
281*/
282
283/*!
284 \fn QSize &QSize::operator-=(const QSize &size)
285
286 Subtracts the given \a size from \e this size, and returns a
287 reference to this size. For example:
288
289 \snippet code/src_corelib_tools_qsize.cpp 4
290*/
291
292/*!
293 \fn QSize &QSize::operator*=(qreal factor)
294 \overload
295
296 Multiplies both the width and height by the given \a factor, and
297 returns a reference to the size.
298
299 Note that the result is rounded to the nearest integer.
300
301 \sa scale()
302*/
303
304/*!
305 \fn bool QSize::operator==(const QSize &s1, const QSize &s2)
306
307 Returns \c true if \a s1 and \a s2 are equal; otherwise returns \c false.
308*/
309
310/*!
311 \fn bool QSize::operator!=(const QSize &s1, const QSize &s2)
312
313 Returns \c true if \a s1 and \a s2 are different; otherwise returns \c false.
314*/
315
316/*!
317 \fn QSize QSize::operator+(const QSize &s1, const QSize &s2)
318
319 Returns the sum of \a s1 and \a s2; each component is added separately.
320*/
321
322/*!
323 \fn QSize QSize::operator-(const QSize &s1, const QSize &s2)
324
325 Returns \a s2 subtracted from \a s1; each component is subtracted
326 separately.
327*/
328
329/*!
330 \fn QSize QSize::operator*(const QSize &size, qreal factor)
331
332 Multiplies the given \a size by the given \a factor, and returns
333 the result rounded to the nearest integer.
334
335 \sa QSize::scale()
336*/
337
338/*!
339 \fn QSize QSize::operator*(qreal factor, const QSize &size)
340 \overload
341
342 Multiplies the given \a size by the given \a factor, and returns
343 the result rounded to the nearest integer.
344*/
345
346/*!
347 \fn QSize &QSize::operator/=(qreal divisor)
348 \overload
349
350 Divides both the width and height by the given \a divisor, and
351 returns a reference to the size.
352
353 Note that the result is rounded to the nearest integer.
354
355 \sa QSize::scale()
356*/
357
358/*!
359 \fn QSize QSize::operator/(const QSize &size, qreal divisor)
360 \overload
361
362 Divides the given \a size by the given \a divisor, and returns the
363 result rounded to the nearest integer.
364
365 \sa QSize::scale()
366*/
367
368/*!
369 \fn QSize QSize::expandedTo(const QSize & otherSize) const
370
371 Returns a size holding the maximum width and height of this size
372 and the given \a otherSize.
373
374 \sa boundedTo(), scale()
375*/
376
377/*!
378 \fn QSize QSize::boundedTo(const QSize & otherSize) const
379
380 Returns a size holding the minimum width and height of this size
381 and the given \a otherSize.
382
383 \sa expandedTo(), scale()
384*/
385
386/*!
387 \fn QSize QSize::grownBy(QMargins margins) const
388 \fn QSizeF QSizeF::grownBy(QMarginsF margins) const
389 \since 5.14
390
391 Returns the size that results from growing this size by \a margins.
392
393 \sa shrunkBy()
394*/
395
396/*!
397 \fn QSize QSize::shrunkBy(QMargins margins) const
398 \fn QSizeF QSizeF::shrunkBy(QMarginsF margins) const
399 \since 5.14
400
401 Returns the size that results from shrinking this size by \a margins.
402
403 \sa grownBy()
404*/
405
406/*****************************************************************************
407 QSize stream functions
408 *****************************************************************************/
409#ifndef QT_NO_DATASTREAM
410/*!
411 \fn QDataStream &operator<<(QDataStream &stream, const QSize &size)
412 \relates QSize
413
414 Writes the given \a size to the given \a stream, and returns a
415 reference to the stream.
416
417 \sa {Serializing Qt Data Types}
418*/
419
420QDataStream &operator<<(QDataStream &s, const QSize &sz)
421{
422 if (s.version() == 1)
423 s << (qint16)sz.width() << (qint16)sz.height();
424 else
425 s << (qint32)sz.width() << (qint32)sz.height();
426 return s;
427}
428
429/*!
430 \fn QDataStream &operator>>(QDataStream &stream, QSize &size)
431 \relates QSize
432
433 Reads a size from the given \a stream into the given \a size, and
434 returns a reference to the stream.
435
436 \sa {Serializing Qt Data Types}
437*/
438
439QDataStream &operator>>(QDataStream &s, QSize &sz)
440{
441 if (s.version() == 1) {
442 qint16 w, h;
443 s >> w; sz.rwidth() = w;
444 s >> h; sz.rheight() = h;
445 }
446 else {
447 qint32 w, h;
448 s >> w; sz.rwidth() = w;
449 s >> h; sz.rheight() = h;
450 }
451 return s;
452}
453#endif // QT_NO_DATASTREAM
454
455#ifndef QT_NO_DEBUG_STREAM
456QDebug operator<<(QDebug dbg, const QSize &s)
457{
458 QDebugStateSaver saver(dbg);
459 dbg.nospace();
460 dbg << "QSize(";
461 QtDebugUtils::formatQSize(dbg, s);
462 dbg << ')';
463 return dbg;
464}
465#endif
466
467
468
469/*!
470 \class QSizeF
471 \inmodule QtCore
472 \brief The QSizeF class defines the size of a two-dimensional object
473 using floating point precision.
474
475 \ingroup painting
476
477 A size is specified by a width() and a height(). It can be set in
478 the constructor and changed using the setWidth(), setHeight(), or
479 scale() functions, or using arithmetic operators. A size can also
480 be manipulated directly by retrieving references to the width and
481 height using the rwidth() and rheight() functions. Finally, the
482 width and height can be swapped using the transpose() function.
483
484 The isValid() function determines if a size is valid. A valid size
485 has both width and height greater than or equal to zero. The
486 isEmpty() function returns \c true if either of the width and height
487 is \e less than (or equal to) zero, while the isNull() function
488 returns \c true only if both the width and the height is zero.
489
490 Use the expandedTo() function to retrieve a size which holds the
491 maximum height and width of this size and a given
492 size. Similarly, the boundedTo() function returns a size which
493 holds the minimum height and width of this size and a given size.
494
495 The QSizeF class also provides the toSize() function returning a
496 QSize copy of this size, constructed by rounding the width and
497 height to the nearest integers.
498
499 QSizeF objects can be streamed as well as compared.
500
501 \sa QSize, QPointF, QRectF
502*/
503
504
505/*****************************************************************************
506 QSizeF member functions
507 *****************************************************************************/
508
509/*!
510 \fn QSizeF::QSizeF()
511
512 Constructs an invalid size.
513
514 \sa isValid()
515*/
516
517/*!
518 \fn QSizeF::QSizeF(const QSize &size)
519
520 Constructs a size with floating point accuracy from the given \a
521 size.
522
523 \sa toSize()
524*/
525
526/*!
527 \fn QSizeF::QSizeF(qreal width, qreal height)
528
529 Constructs a size with the given \a width and \a height.
530*/
531
532/*!
533 \fn bool QSizeF::isNull() const
534
535 Returns \c true if both the width and height are 0.0 (ignoring the sign);
536 otherwise returns \c false.
537
538 \sa isValid(), isEmpty()
539*/
540
541/*!
542 \fn bool QSizeF::isEmpty() const
543
544 Returns \c true if either of the width and height is less than or
545 equal to 0; otherwise returns \c false.
546
547 \sa isNull(), isValid()
548*/
549
550/*!
551 \fn bool QSizeF::isValid() const
552
553 Returns \c true if both the width and height is equal to or greater
554 than 0; otherwise returns \c false.
555
556 \sa isNull(), isEmpty()
557*/
558
559/*!
560 \fn int QSizeF::width() const
561
562 Returns the width.
563
564 \sa height(), setWidth()
565*/
566
567/*!
568 \fn int QSizeF::height() const
569
570 Returns the height.
571
572 \sa width(), setHeight()
573*/
574
575/*!
576 \fn void QSizeF::setWidth(qreal width)
577
578 Sets the width to the given \a width.
579
580 \sa width(), rwidth(), setHeight()
581*/
582
583/*!
584 \fn void QSizeF::setHeight(qreal height)
585
586 Sets the height to the given \a height.
587
588 \sa height(), rheight(), setWidth()
589*/
590
591/*!
592 \fn QSize QSizeF::toSize() const
593
594 Returns an integer based copy of this size.
595
596 Note that the coordinates in the returned size will be rounded to
597 the nearest integer.
598
599 \sa QSizeF()
600*/
601
602/*!
603 Swaps the width and height values.
604
605 \sa setWidth(), setHeight(), transposed()
606*/
607
608void QSizeF::transpose() noexcept
609{
610 qSwap(wd, ht);
611}
612
613/*!
614 \fn QSizeF QSizeF::transposed() const
615 \since 5.0
616
617 Returns the size with width and height values swapped.
618
619 \sa transpose()
620*/
621
622/*!
623 \fn void QSizeF::scale(qreal width, qreal height, Qt::AspectRatioMode mode)
624
625 Scales the size to a rectangle with the given \a width and \a
626 height, according to the specified \a mode.
627
628 \list
629 \li If \a mode is Qt::IgnoreAspectRatio, the size is set to (\a width, \a height).
630 \li If \a mode is Qt::KeepAspectRatio, the current size is scaled to a rectangle
631 as large as possible inside (\a width, \a height), preserving the aspect ratio.
632 \li If \a mode is Qt::KeepAspectRatioByExpanding, the current size is scaled to a rectangle
633 as small as possible outside (\a width, \a height), preserving the aspect ratio.
634 \endlist
635
636 Example:
637 \snippet code/src_corelib_tools_qsize.cpp 5
638
639 \sa setWidth(), setHeight(), scaled()
640*/
641
642/*!
643 \fn void QSizeF::scale(const QSizeF &size, Qt::AspectRatioMode mode)
644 \overload
645
646 Scales the size to a rectangle with the given \a size, according to
647 the specified \a mode.
648*/
649
650/*!
651 \fn QSizeF QSizeF::scaled(qreal width, qreal height, Qt::AspectRatioMode mode) const
652 \since 5.0
653
654 Returns a size scaled to a rectangle with the given \a width and
655 \a height, according to the specified \a mode.
656
657 \sa scale()
658*/
659
660/*!
661 \overload
662 \since 5.0
663
664 Returns a size scaled to a rectangle with the given size \a s,
665 according to the specified \a mode.
666*/
667QSizeF QSizeF::scaled(const QSizeF &s, Qt::AspectRatioMode mode) const noexcept
668{
669 if (mode == Qt::IgnoreAspectRatio || qIsNull(wd) || qIsNull(ht)) {
670 return s;
671 } else {
672 bool useHeight;
673 qreal rw = s.ht * wd / ht;
674
675 if (mode == Qt::KeepAspectRatio) {
676 useHeight = (rw <= s.wd);
677 } else { // mode == Qt::KeepAspectRatioByExpanding
678 useHeight = (rw >= s.wd);
679 }
680
681 if (useHeight) {
682 return QSizeF(rw, s.ht);
683 } else {
684 return QSizeF(s.wd, s.wd * ht / wd);
685 }
686 }
687}
688
689/*!
690 \fn int &QSizeF::rwidth()
691
692 Returns a reference to the width.
693
694 Using a reference makes it possible to manipulate the width
695 directly. For example:
696
697 \snippet code/src_corelib_tools_qsize.cpp 6
698
699 \sa rheight(), setWidth()
700*/
701
702/*!
703 \fn int &QSizeF::rheight()
704
705 Returns a reference to the height.
706
707 Using a reference makes it possible to manipulate the height
708 directly. For example:
709
710 \snippet code/src_corelib_tools_qsize.cpp 7
711
712 \sa rwidth(), setHeight()
713*/
714
715/*!
716 \fn QSizeF &QSizeF::operator+=(const QSizeF &size)
717
718 Adds the given \a size to this size and returns a reference to
719 this size. For example:
720
721 \snippet code/src_corelib_tools_qsize.cpp 8
722*/
723
724/*!
725 \fn QSizeF &QSizeF::operator-=(const QSizeF &size)
726
727 Subtracts the given \a size from this size and returns a reference
728 to this size. For example:
729
730 \snippet code/src_corelib_tools_qsize.cpp 9
731*/
732
733/*!
734 \fn QSizeF &QSizeF::operator*=(qreal factor)
735 \overload
736
737 Multiplies both the width and height by the given \a factor and
738 returns a reference to the size.
739
740 \sa scale()
741*/
742
743/*!
744 \fn bool QSizeF::operator==(const QSizeF &s1, const QSizeF &s2)
745
746 Returns \c true if \a s1 and \a s2 are approximately equal; otherwise
747 returns false.
748
749 \warning This function does not check for strict equality; instead,
750 it uses a fuzzy comparison to compare the sizes' extents.
751
752 \sa qFuzzyCompare
753*/
754
755/*!
756 \fn bool QSizeF::operator!=(const QSizeF &s1, const QSizeF &s2)
757
758 Returns \c true if \a s1 and \a s2 are sufficiently different; otherwise
759 returns \c false.
760
761 \warning This function does not check for strict inequality; instead,
762 it uses a fuzzy comparison to compare the sizes' extents.
763*/
764
765/*!
766 \fn QSizeF QSizeF::operator+(const QSizeF &s1, const QSizeF &s2)
767
768 Returns the sum of \a s1 and \a s2; each component is added separately.
769*/
770
771/*!
772 \fn QSizeF QSizeF::operator-(const QSizeF &s1, const QSizeF &s2)
773
774 Returns \a s2 subtracted from \a s1; each component is subtracted
775 separately.
776*/
777
778/*!
779 \fn QSizeF QSizeF::operator*(const QSizeF &size, qreal factor)
780
781 \overload
782
783 Multiplies the given \a size by the given \a factor and returns
784 the result.
785
786 \sa QSizeF::scale()
787*/
788
789/*!
790 \fn QSizeF QSizeF::operator*(qreal factor, const QSizeF &size)
791
792 \overload
793
794 Multiplies the given \a size by the given \a factor and returns
795 the result.
796*/
797
798/*!
799 \fn QSizeF &QSizeF::operator/=(qreal divisor)
800
801 \overload
802
803 Divides both the width and height by the given \a divisor and
804 returns a reference to the size.
805
806 \sa scale()
807*/
808
809/*!
810 \fn QSizeF QSizeF::operator/(const QSizeF &size, qreal divisor)
811
812 \overload
813
814 Divides the given \a size by the given \a divisor and returns the
815 result.
816
817 \sa QSizeF::scale()
818*/
819
820/*!
821 \fn QSizeF QSizeF::expandedTo(const QSizeF & otherSize) const
822
823 Returns a size holding the maximum width and height of this size
824 and the given \a otherSize.
825
826 \sa boundedTo(), scale()
827*/
828
829/*!
830 \fn QSizeF QSizeF::boundedTo(const QSizeF & otherSize) const
831
832 Returns a size holding the minimum width and height of this size
833 and the given \a otherSize.
834
835 \sa expandedTo(), scale()
836*/
837
838
839
840/*****************************************************************************
841 QSizeF stream functions
842 *****************************************************************************/
843#ifndef QT_NO_DATASTREAM
844/*!
845 \fn QDataStream &operator<<(QDataStream &stream, const QSizeF &size)
846 \relates QSizeF
847
848 Writes the given \a size to the given \a stream and returns a
849 reference to the stream.
850
851 \sa {Serializing Qt Data Types}
852*/
853
854QDataStream &operator<<(QDataStream &s, const QSizeF &sz)
855{
856 s << double(sz.width()) << double(sz.height());
857 return s;
858}
859
860/*!
861 \fn QDataStream &operator>>(QDataStream &stream, QSizeF &size)
862 \relates QSizeF
863
864 Reads a size from the given \a stream into the given \a size and
865 returns a reference to the stream.
866
867 \sa {Serializing Qt Data Types}
868*/
869
870QDataStream &operator>>(QDataStream &s, QSizeF &sz)
871{
872 double w, h;
873 s >> w;
874 s >> h;
875 sz.setWidth(qreal(w));
876 sz.setHeight(qreal(h));
877 return s;
878}
879#endif // QT_NO_DATASTREAM
880
881#ifndef QT_NO_DEBUG_STREAM
882QDebug operator<<(QDebug dbg, const QSizeF &s)
883{
884 QDebugStateSaver saver(dbg);
885 dbg.nospace();
886 dbg << "QSizeF(";
887 QtDebugUtils::formatQSize(dbg, s);
888 dbg << ')';
889 return dbg;
890}
891#endif
892
893QT_END_NAMESPACE
894