Merge remote-tracking branch 'origin/master' into api_changes
[profile/ivi/qtbase.git] / src / corelib / tools / qsize.cpp
1 /****************************************************************************
2 **
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
5 **
6 ** This file is part of the QtCore module of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** GNU Lesser General Public License Usage
10 ** This file may be used under the terms of the GNU Lesser General Public
11 ** License version 2.1 as published by the Free Software Foundation and
12 ** appearing in the file LICENSE.LGPL included in the packaging of this
13 ** file. Please review the following information to ensure the GNU Lesser
14 ** General Public License version 2.1 requirements will be met:
15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
16 **
17 ** In addition, as a special exception, Nokia gives you certain additional
18 ** rights. These rights are described in the Nokia Qt LGPL Exception
19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
20 **
21 ** GNU General Public License Usage
22 ** Alternatively, this file may be used under the terms of the GNU General
23 ** Public License version 3.0 as published by the Free Software Foundation
24 ** and appearing in the file LICENSE.GPL included in the packaging of this
25 ** file. Please review the following information to ensure the GNU General
26 ** Public License version 3.0 requirements will be met:
27 ** http://www.gnu.org/copyleft/gpl.html.
28 **
29 ** Other Usage
30 ** Alternatively, this file may be used in accordance with the terms and
31 ** conditions contained in a signed written agreement between you and Nokia.
32 **
33 **
34 **
35 **
36 **
37 **
38 ** $QT_END_LICENSE$
39 **
40 ****************************************************************************/
41
42 #include "qsize.h"
43 #include "qdatastream.h"
44 #include "qdebug.h"
45
46 QT_BEGIN_NAMESPACE
47
48 /*!
49     \class QSize
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 zero). The isEmpty()
64     function returns true if either of the width and height is less
65     than, or equal to, zero, while the isNull() function returns 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 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 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 true if either of the width and height is less than or
114     equal to 0; otherwise returns false.
115
116     \sa isNull(), isValid()
117 */
118
119 /*!
120     \fn bool QSize::isValid() const
121
122     Returns true if both the width and height is equal to or greater
123     than 0; otherwise returns 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
166 void QSize::transpose()
167 {
168     int tmp = wd;
169     wd = ht;
170     ht = tmp;
171 }
172
173 /*!
174   \fn QSize QSize::transposed() const
175   \since 5.0
176
177   Returns a QSize with width and height swapped.
178
179   \sa transpose()
180 */
181
182 /*!
183   \fn void QSize::scale(int width, int height, Qt::AspectRatioMode mode)
184
185     Scales the size to a rectangle with the given \a width and \a
186     height, according to the specified \a mode:
187
188     \list
189     \li If \a mode is Qt::IgnoreAspectRatio, the size is set to (\a width, \a height).
190     \li If \a mode is Qt::KeepAspectRatio, the current size is scaled to a rectangle
191        as large as possible inside (\a width, \a height), preserving the aspect ratio.
192     \li If \a mode is Qt::KeepAspectRatioByExpanding, the current size is scaled to a rectangle
193        as small as possible outside (\a width, \a height), preserving the aspect ratio.
194     \endlist
195
196     Example:
197     \snippet doc/src/snippets/code/src_corelib_tools_qsize.cpp 0
198
199     \sa setWidth(), setHeight(), scaled()
200 */
201
202 /*!
203     \fn void QSize::scale(const QSize &size, Qt::AspectRatioMode mode)
204     \overload
205
206     Scales the size to a rectangle with the given \a size, according to
207     the specified \a mode.
208 */
209
210 /*!
211     \fn QSize QSize::scaled(int width, int height, Qt::AspectRatioMode mode) const
212     \since 5.0
213
214     Return a size scaled to a rectangle with the given \a width and \a
215     height, according to the specified \a mode.
216
217     \sa scale()
218 */
219
220 /*!
221   \overload
222   \since 5.0
223 */
224 QSize QSize::scaled(const QSize &s, Qt::AspectRatioMode mode) const
225 {
226     if (mode == Qt::IgnoreAspectRatio || wd == 0 || ht == 0) {
227         return s;
228     } else {
229         bool useHeight;
230         qint64 rw = qint64(s.ht) * qint64(wd) / qint64(ht);
231
232         if (mode == Qt::KeepAspectRatio) {
233             useHeight = (rw <= s.wd);
234         } else { // mode == Qt::KeepAspectRatioByExpanding
235             useHeight = (rw >= s.wd);
236         }
237
238         if (useHeight) {
239             return QSize(rw, s.ht);
240         } else {
241             return QSize(s.wd,
242                          qint32(qint64(s.wd) * qint64(ht) / qint64(wd)));
243         }
244     }
245 }
246
247 /*!
248     \fn int &QSize::rwidth()
249
250     Returns a reference to the width.
251
252     Using a reference makes it possible to manipulate the width
253     directly. For example:
254
255     \snippet doc/src/snippets/code/src_corelib_tools_qsize.cpp 1
256
257     \sa rheight(), setWidth()
258 */
259
260 /*!
261     \fn int &QSize::rheight()
262
263     Returns a reference to the height.
264
265     Using a reference makes it possible to manipulate the height
266     directly. For example:
267
268     \snippet doc/src/snippets/code/src_corelib_tools_qsize.cpp 2
269
270     \sa rwidth(), setHeight()
271 */
272
273 /*!
274     \fn QSize &QSize::operator+=(const QSize &size)
275
276     Adds the given \a size to \e this size, and returns a reference to
277     this size. For example:
278
279     \snippet doc/src/snippets/code/src_corelib_tools_qsize.cpp 3
280 */
281
282 /*!
283     \fn QSize &QSize::operator-=(const QSize &size)
284
285     Subtracts the given \a size from \e this size, and returns a
286     reference to this size. For example:
287
288     \snippet doc/src/snippets/code/src_corelib_tools_qsize.cpp 4
289 */
290
291 /*!
292     \fn QSize &QSize::operator*=(qreal factor)
293     \overload
294
295     Multiplies both the width and height by the given \a factor, and
296     returns a reference to the size.
297
298     Note that the result is rounded to the nearest integer.
299
300     \sa scale()
301 */
302
303 /*!
304     \fn bool operator==(const QSize &s1, const QSize &s2)
305     \relates QSize
306
307     Returns true if \a s1 and \a s2 are equal; otherwise returns false.
308 */
309
310 /*!
311     \fn bool operator!=(const QSize &s1, const QSize &s2)
312     \relates QSize
313
314     Returns true if \a s1 and \a s2 are different; otherwise returns false.
315 */
316
317 /*!
318     \fn const QSize operator+(const QSize &s1, const QSize &s2)
319     \relates QSize
320
321     Returns the sum of \a s1 and \a s2; each component is added separately.
322 */
323
324 /*!
325     \fn const QSize operator-(const QSize &s1, const QSize &s2)
326     \relates QSize
327
328     Returns \a s2 subtracted from \a s1; each component is subtracted
329     separately.
330 */
331
332 /*!
333     \fn const QSize operator*(const QSize &size, qreal factor)
334     \relates QSize
335
336     Multiplies the given \a size by the given \a factor, and returns
337     the result rounded to the nearest integer.
338
339     \sa QSize::scale()
340 */
341
342 /*!
343     \fn const QSize operator*(qreal factor, const QSize &size)
344     \overload
345     \relates QSize
346
347     Multiplies the given \a size by the given \a factor, and returns
348     the result rounded to the nearest integer.
349 */
350
351 /*!
352     \fn QSize &QSize::operator/=(qreal divisor)
353     \overload
354
355     Divides both the width and height by the given \a divisor, and
356     returns a reference to the size.
357
358     Note that the result is rounded to the nearest integer.
359
360     \sa QSize::scale()
361 */
362
363 /*!
364     \fn const QSize operator/(const QSize &size, qreal divisor)
365     \relates QSize
366     \overload
367
368     Divides the given \a size by the given \a divisor, and returns the
369     result rounded to the nearest integer.
370
371     \sa QSize::scale()
372 */
373
374 /*!
375     \fn QSize QSize::expandedTo(const QSize & otherSize) const
376
377     Returns a size holding the maximum width and height of this size
378     and the given \a otherSize.
379
380     \sa boundedTo(), scale()
381 */
382
383 /*!
384     \fn QSize QSize::boundedTo(const QSize & otherSize) const
385
386     Returns a size holding the minimum width and height of this size
387     and the given \a otherSize.
388
389     \sa expandedTo(), scale()
390 */
391
392
393
394 /*****************************************************************************
395   QSize stream functions
396  *****************************************************************************/
397 #ifndef QT_NO_DATASTREAM
398 /*!
399     \fn QDataStream &operator<<(QDataStream &stream, const QSize &size)
400     \relates QSize
401
402     Writes the given \a size to the given \a stream, and returns a
403     reference to the stream.
404
405     \sa {Serializing Qt Data Types}
406 */
407
408 QDataStream &operator<<(QDataStream &s, const QSize &sz)
409 {
410     if (s.version() == 1)
411         s << (qint16)sz.width() << (qint16)sz.height();
412     else
413         s << (qint32)sz.width() << (qint32)sz.height();
414     return s;
415 }
416
417 /*!
418     \fn QDataStream &operator>>(QDataStream &stream, QSize &size)
419     \relates QSize
420
421     Reads a size from the given \a stream into the given \a size, and
422     returns a reference to the stream.
423
424     \sa {Serializing Qt Data Types}
425 */
426
427 QDataStream &operator>>(QDataStream &s, QSize &sz)
428 {
429     if (s.version() == 1) {
430         qint16 w, h;
431         s >> w;  sz.rwidth() = w;
432         s >> h;  sz.rheight() = h;
433     }
434     else {
435         qint32 w, h;
436         s >> w;  sz.rwidth() = w;
437         s >> h;  sz.rheight() = h;
438     }
439     return s;
440 }
441 #endif // QT_NO_DATASTREAM
442
443 #ifndef QT_NO_DEBUG_STREAM
444 QDebug operator<<(QDebug dbg, const QSize &s) {
445     dbg.nospace() << "QSize(" << s.width() << ", " << s.height() << ')';
446     return dbg.space();
447 }
448 #endif
449
450
451
452 /*!
453     \class QSizeF
454     \brief The QSizeF class defines the size of a two-dimensional object
455     using floating point precision.
456
457     \ingroup painting
458
459     A size is specified by a width() and a height().  It can be set in
460     the constructor and changed using the setWidth(), setHeight(), or
461     scale() functions, or using arithmetic operators. A size can also
462     be manipulated directly by retrieving references to the width and
463     height using the rwidth() and rheight() functions. Finally, the
464     width and height can be swapped using the transpose() function.
465
466     The isValid() function determines if a size is valid. A valid size
467     has both width and height greater than or equal to zero. The
468     isEmpty() function returns true if either of the width and height
469     is \e less than (or equal to) zero, while the isNull() function
470     returns true only if both the width and the height is zero.
471
472     Use the expandedTo() function to retrieve a size which holds the
473     maximum height and width of this size and a given
474     size. Similarly, the boundedTo() function returns a size which
475     holds the minimum height and width of this size and a given size.
476
477     The QSizeF class also provides the toSize() function returning a
478     QSize copy of this size, constructed by rounding the width and
479     height to the nearest integers.
480
481     QSizeF objects can be streamed as well as compared.
482
483     \sa QSize, QPointF, QRectF
484 */
485
486
487 /*****************************************************************************
488   QSizeF member functions
489  *****************************************************************************/
490
491 /*!
492     \fn QSizeF::QSizeF()
493
494     Constructs an invalid size.
495
496     \sa isValid()
497 */
498
499 /*!
500     \fn QSizeF::QSizeF(const QSize &size)
501
502     Constructs a size with floating point accuracy from the given \a
503     size.
504
505     \sa toSize()
506 */
507
508 /*!
509     \fn QSizeF::QSizeF(qreal width, qreal height)
510
511     Constructs a size with the given \a width and \a height.
512 */
513
514 /*!
515     \fn bool QSizeF::isNull() const
516
517     Returns true if both the width and height are +0.0; otherwise returns
518     false.
519
520     \note Since this function treats +0.0 and -0.0 differently, sizes with
521     zero width and height where either or both values have a negative
522     sign are not defined to be null sizes.
523
524     \sa isValid(), isEmpty()
525 */
526
527 /*!
528     \fn bool QSizeF::isEmpty() const
529
530     Returns true if either of the width and height is less than or
531     equal to 0; otherwise returns false.
532
533     \sa isNull(), isValid()
534 */
535
536 /*!
537     \fn bool QSizeF::isValid() const
538
539     Returns true if both the width and height is equal to or greater
540     than 0; otherwise returns false.
541
542     \sa isNull(), isEmpty()
543 */
544
545 /*!
546     \fn int QSizeF::width() const
547
548     Returns the width.
549
550     \sa height(), setWidth()
551 */
552
553 /*!
554     \fn int QSizeF::height() const
555
556     Returns the height.
557
558     \sa width(), setHeight()
559 */
560
561 /*!
562     \fn void QSizeF::setWidth(qreal width)
563
564     Sets the width to the given \a width.
565
566     \sa width(), rwidth(), setHeight()
567 */
568
569 /*!
570     \fn void QSizeF::setHeight(qreal height)
571
572     Sets the height to the given \a height.
573
574     \sa height(), rheight(), setWidth()
575 */
576
577 /*!
578     \fn QSize QSizeF::toSize() const
579
580     Returns an integer based copy of this size.
581
582     Note that the coordinates in the returned size will be rounded to
583     the nearest integer.
584
585     \sa QSizeF()
586 */
587
588 /*!
589     Swaps the width and height values.
590
591     \sa setWidth(), setHeight(), transposed()
592 */
593
594 void QSizeF::transpose()
595 {
596     qreal tmp = wd;
597     wd = ht;
598     ht = tmp;
599 }
600
601 /*!
602     \fn QSizeF QSizeF::transposed() const
603     \since 5.0
604
605     Returns the size with width and height values swapped.
606
607     \sa transpose()
608 */
609
610 /*!
611   \fn void QSizeF::scale(qreal width, qreal height, Qt::AspectRatioMode mode)
612
613     Scales the size to a rectangle with the given \a width and \a
614     height, according to the specified \a mode.
615
616     \list
617     \li If \a mode is Qt::IgnoreAspectRatio, the size is set to (\a width, \a height).
618     \li If \a mode is Qt::KeepAspectRatio, the current size is scaled to a rectangle
619        as large as possible inside (\a width, \a height), preserving the aspect ratio.
620     \li If \a mode is Qt::KeepAspectRatioByExpanding, the current size is scaled to a rectangle
621        as small as possible outside (\a width, \a height), preserving the aspect ratio.
622     \endlist
623
624     Example:
625     \snippet doc/src/snippets/code/src_corelib_tools_qsize.cpp 5
626
627     \sa setWidth(), setHeight(), scaled()
628 */
629
630 /*!
631     \fn void QSizeF::scale(const QSizeF &size, Qt::AspectRatioMode mode)
632     \overload
633
634     Scales the size to a rectangle with the given \a size, according to
635     the specified \a mode.
636 */
637
638 /*!
639     \fn QSizeF QSizeF::scaled(int width, int height, Qt::AspectRatioMode mode) const
640     \since 5.0
641
642     Returns a size scaled to a rectangle with the given \a width and
643     \a height, according to the specified \mode.
644
645     \sa scale()
646 */
647
648 /*!
649   \overload
650   \since 5.0
651 */
652 QSizeF QSizeF::scaled(const QSizeF &s, Qt::AspectRatioMode mode) const
653 {
654     if (mode == Qt::IgnoreAspectRatio || qIsNull(wd) || qIsNull(ht)) {
655         return s;
656     } else {
657         bool useHeight;
658         qreal rw = s.ht * wd / ht;
659
660         if (mode == Qt::KeepAspectRatio) {
661             useHeight = (rw <= s.wd);
662         } else { // mode == Qt::KeepAspectRatioByExpanding
663             useHeight = (rw >= s.wd);
664         }
665
666         if (useHeight) {
667             return QSizeF(rw, s.ht);
668         } else {
669             return QSizeF(s.wd, s.wd * ht / wd);
670         }
671     }
672 }
673
674 /*!
675     \fn int &QSizeF::rwidth()
676
677     Returns a reference to the width.
678
679     Using a reference makes it possible to manipulate the width
680     directly. For example:
681
682     \snippet doc/src/snippets/code/src_corelib_tools_qsize.cpp 6
683
684     \sa rheight(), setWidth()
685 */
686
687 /*!
688     \fn int &QSizeF::rheight()
689
690     Returns a reference to the height.
691
692     Using a reference makes it possible to manipulate the height
693     directly. For example:
694
695     \snippet doc/src/snippets/code/src_corelib_tools_qsize.cpp 7
696
697     \sa rwidth(), setHeight()
698 */
699
700 /*!
701     \fn QSizeF &QSizeF::operator+=(const QSizeF &size)
702
703     Adds the given \a size to this size and returns a reference to
704     this size. For example:
705
706     \snippet doc/src/snippets/code/src_corelib_tools_qsize.cpp 8
707 */
708
709 /*!
710     \fn QSizeF &QSizeF::operator-=(const QSizeF &size)
711
712     Subtracts the given \a size from this size and returns a reference
713     to this size. For example:
714
715     \snippet doc/src/snippets/code/src_corelib_tools_qsize.cpp 9
716 */
717
718 /*!
719     \fn QSizeF &QSizeF::operator*=(qreal factor)
720     \overload
721
722     Multiplies both the width and height by the given \a factor and
723     returns a reference to the size.
724
725     \sa scale()
726 */
727
728 /*!
729     \fn bool operator==(const QSizeF &s1, const QSizeF &s2)
730     \relates QSizeF
731
732     Returns true if \a s1 and \a s2 are equal; otherwise returns
733     false.
734 */
735
736 /*!
737     \fn bool operator!=(const QSizeF &s1, const QSizeF &s2)
738     \relates QSizeF
739
740     Returns true if \a s1 and \a s2 are different; otherwise returns false.
741 */
742
743 /*!
744     \fn const QSizeF operator+(const QSizeF &s1, const QSizeF &s2)
745     \relates QSizeF
746
747     Returns the sum of \a s1 and \a s2; each component is added separately.
748 */
749
750 /*!
751     \fn const QSizeF operator-(const QSizeF &s1, const QSizeF &s2)
752     \relates QSizeF
753
754     Returns \a s2 subtracted from \a s1; each component is subtracted
755     separately.
756 */
757
758 /*!
759     \fn const QSizeF operator*(const QSizeF &size, qreal factor)
760
761     \overload
762     \relates QSizeF
763
764     Multiplies the given \a size by the given \a factor and returns
765     the result.
766
767     \sa QSizeF::scale()
768 */
769
770 /*!
771     \fn const QSizeF operator*(qreal factor, const QSizeF &size)
772
773     \overload
774     \relates QSizeF
775
776     Multiplies the given \a size by the given \a factor and returns
777     the result.
778 */
779
780 /*!
781     \fn QSizeF &QSizeF::operator/=(qreal divisor)
782
783     \overload
784
785     Divides both the width and height by the given \a divisor and
786     returns a reference to the size.
787
788     \sa scale()
789 */
790
791 /*!
792     \fn const QSizeF operator/(const QSizeF &size, qreal divisor)
793
794     \relates QSizeF
795     \overload
796
797     Divides the given \a size by the given \a divisor and returns the
798     result.
799
800     \sa QSizeF::scale()
801 */
802
803 /*!
804     \fn QSizeF QSizeF::expandedTo(const QSizeF & otherSize) const
805
806     Returns a size holding the maximum width and height of this size
807     and the given \a otherSize.
808
809     \sa boundedTo(), scale()
810 */
811
812 /*!
813     \fn QSizeF QSizeF::boundedTo(const QSizeF & otherSize) const
814
815     Returns a size holding the minimum width and height of this size
816     and the given \a otherSize.
817
818     \sa expandedTo(), scale()
819 */
820
821
822
823 /*****************************************************************************
824   QSizeF stream functions
825  *****************************************************************************/
826 #ifndef QT_NO_DATASTREAM
827 /*!
828     \fn QDataStream &operator<<(QDataStream &stream, const QSizeF &size)
829     \relates QSizeF
830
831     Writes the given \a size to the given \a stream and returns a
832     reference to the stream.
833
834     \sa {Serializing Qt Data Types}
835 */
836
837 QDataStream &operator<<(QDataStream &s, const QSizeF &sz)
838 {
839     s << double(sz.width()) << double(sz.height());
840     return s;
841 }
842
843 /*!
844     \fn QDataStream &operator>>(QDataStream &stream, QSizeF &size)
845     \relates QSizeF
846
847     Reads a size from the given \a stream into the given \a size and
848     returns a reference to the stream.
849
850     \sa {Serializing Qt Data Types}
851 */
852
853 QDataStream &operator>>(QDataStream &s, QSizeF &sz)
854 {
855     double w, h;
856     s >> w;
857     s >> h;
858     sz.setWidth(qreal(w));
859     sz.setHeight(qreal(h));
860     return s;
861 }
862 #endif // QT_NO_DATASTREAM
863
864 #ifndef QT_NO_DEBUG_STREAM
865 QDebug operator<<(QDebug dbg, const QSizeF &s) {
866     dbg.nospace() << "QSizeF(" << s.width() << ", " << s.height() << ')';
867     return dbg.space();
868 }
869 #endif
870
871 QT_END_NAMESPACE