1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the QtCore module of the Qt Toolkit.
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.
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.
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.
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.
40 ****************************************************************************/
43 #include "qdatastream.h"
52 \brief The QSize class defines the size of a two-dimensional
53 object using integer point precision.
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.
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.
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
74 QSize objects can be streamed as well as compared.
76 \sa QSizeF, QPoint, QRect
80 /*****************************************************************************
81 QSize member functions
82 *****************************************************************************/
87 Constructs a size with an invalid width and height (i.e., isValid()
94 \fn QSize::QSize(int width, int height)
96 Constructs a size with the given \a width and \a height.
98 \sa setWidth(), setHeight()
102 \fn bool QSize::isNull() const
104 Returns true if both the width and height is 0; otherwise returns
107 \sa isValid(), isEmpty()
111 \fn bool QSize::isEmpty() const
113 Returns true if either of the width and height is less than or
114 equal to 0; otherwise returns false.
116 \sa isNull(), isValid()
120 \fn bool QSize::isValid() const
122 Returns true if both the width and height is equal to or greater
123 than 0; otherwise returns false.
125 \sa isNull(), isEmpty()
129 \fn int QSize::width() const
133 \sa height(), setWidth()
137 \fn int QSize::height() const
141 \sa width(), setHeight()
145 \fn void QSize::setWidth(int width)
147 Sets the width to the given \a width.
149 \sa rwidth(), width(), setHeight()
153 \fn void QSize::setHeight(int height)
155 Sets the height to the given \a height.
157 \sa rheight(), height(), setWidth()
161 Swaps the width and height values.
163 \sa setWidth(), setHeight(), transposed()
166 void QSize::transpose()
174 \fn QSize QSize::transposed() const
177 Returns a QSize with width and height swapped.
183 \fn void QSize::scale(int width, int height, Qt::AspectRatioMode mode)
185 Scales the size to a rectangle with the given \a width and \a
186 height, according to the specified \a mode:
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.
197 \snippet doc/src/snippets/code/src_corelib_tools_qsize.cpp 0
199 \sa setWidth(), setHeight(), scaled()
203 \fn void QSize::scale(const QSize &size, Qt::AspectRatioMode mode)
206 Scales the size to a rectangle with the given \a size, according to
207 the specified \a mode.
211 \fn QSize QSize::scaled(int width, int height, Qt::AspectRatioMode mode) const
214 Return a size scaled to a rectangle with the given \a width and \a
215 height, according to the specified \a mode.
224 QSize QSize::scaled(const QSize &s, Qt::AspectRatioMode mode) const
226 if (mode == Qt::IgnoreAspectRatio || wd == 0 || ht == 0) {
230 qint64 rw = qint64(s.ht) * qint64(wd) / qint64(ht);
232 if (mode == Qt::KeepAspectRatio) {
233 useHeight = (rw <= s.wd);
234 } else { // mode == Qt::KeepAspectRatioByExpanding
235 useHeight = (rw >= s.wd);
239 return QSize(rw, s.ht);
242 qint32(qint64(s.wd) * qint64(ht) / qint64(wd)));
248 \fn int &QSize::rwidth()
250 Returns a reference to the width.
252 Using a reference makes it possible to manipulate the width
253 directly. For example:
255 \snippet doc/src/snippets/code/src_corelib_tools_qsize.cpp 1
257 \sa rheight(), setWidth()
261 \fn int &QSize::rheight()
263 Returns a reference to the height.
265 Using a reference makes it possible to manipulate the height
266 directly. For example:
268 \snippet doc/src/snippets/code/src_corelib_tools_qsize.cpp 2
270 \sa rwidth(), setHeight()
274 \fn QSize &QSize::operator+=(const QSize &size)
276 Adds the given \a size to \e this size, and returns a reference to
277 this size. For example:
279 \snippet doc/src/snippets/code/src_corelib_tools_qsize.cpp 3
283 \fn QSize &QSize::operator-=(const QSize &size)
285 Subtracts the given \a size from \e this size, and returns a
286 reference to this size. For example:
288 \snippet doc/src/snippets/code/src_corelib_tools_qsize.cpp 4
292 \fn QSize &QSize::operator*=(qreal factor)
295 Multiplies both the width and height by the given \a factor, and
296 returns a reference to the size.
298 Note that the result is rounded to the nearest integer.
304 \fn bool operator==(const QSize &s1, const QSize &s2)
307 Returns true if \a s1 and \a s2 are equal; otherwise returns false.
311 \fn bool operator!=(const QSize &s1, const QSize &s2)
314 Returns true if \a s1 and \a s2 are different; otherwise returns false.
318 \fn const QSize operator+(const QSize &s1, const QSize &s2)
321 Returns the sum of \a s1 and \a s2; each component is added separately.
325 \fn const QSize operator-(const QSize &s1, const QSize &s2)
328 Returns \a s2 subtracted from \a s1; each component is subtracted
333 \fn const QSize operator*(const QSize &size, qreal factor)
336 Multiplies the given \a size by the given \a factor, and returns
337 the result rounded to the nearest integer.
343 \fn const QSize operator*(qreal factor, const QSize &size)
347 Multiplies the given \a size by the given \a factor, and returns
348 the result rounded to the nearest integer.
352 \fn QSize &QSize::operator/=(qreal divisor)
355 Divides both the width and height by the given \a divisor, and
356 returns a reference to the size.
358 Note that the result is rounded to the nearest integer.
364 \fn const QSize operator/(const QSize &size, qreal divisor)
368 Divides the given \a size by the given \a divisor, and returns the
369 result rounded to the nearest integer.
375 \fn QSize QSize::expandedTo(const QSize & otherSize) const
377 Returns a size holding the maximum width and height of this size
378 and the given \a otherSize.
380 \sa boundedTo(), scale()
384 \fn QSize QSize::boundedTo(const QSize & otherSize) const
386 Returns a size holding the minimum width and height of this size
387 and the given \a otherSize.
389 \sa expandedTo(), scale()
394 /*****************************************************************************
395 QSize stream functions
396 *****************************************************************************/
397 #ifndef QT_NO_DATASTREAM
399 \fn QDataStream &operator<<(QDataStream &stream, const QSize &size)
402 Writes the given \a size to the given \a stream, and returns a
403 reference to the stream.
405 \sa {Serializing Qt Data Types}
408 QDataStream &operator<<(QDataStream &s, const QSize &sz)
410 if (s.version() == 1)
411 s << (qint16)sz.width() << (qint16)sz.height();
413 s << (qint32)sz.width() << (qint32)sz.height();
418 \fn QDataStream &operator>>(QDataStream &stream, QSize &size)
421 Reads a size from the given \a stream into the given \a size, and
422 returns a reference to the stream.
424 \sa {Serializing Qt Data Types}
427 QDataStream &operator>>(QDataStream &s, QSize &sz)
429 if (s.version() == 1) {
431 s >> w; sz.rwidth() = w;
432 s >> h; sz.rheight() = h;
436 s >> w; sz.rwidth() = w;
437 s >> h; sz.rheight() = h;
441 #endif // QT_NO_DATASTREAM
443 #ifndef QT_NO_DEBUG_STREAM
444 QDebug operator<<(QDebug dbg, const QSize &s) {
445 dbg.nospace() << "QSize(" << s.width() << ", " << s.height() << ')';
454 \brief The QSizeF class defines the size of a two-dimensional object
455 using floating point precision.
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.
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.
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.
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.
481 QSizeF objects can be streamed as well as compared.
483 \sa QSize, QPointF, QRectF
487 /*****************************************************************************
488 QSizeF member functions
489 *****************************************************************************/
494 Constructs an invalid size.
500 \fn QSizeF::QSizeF(const QSize &size)
502 Constructs a size with floating point accuracy from the given \a
509 \fn QSizeF::QSizeF(qreal width, qreal height)
511 Constructs a size with the given \a width and \a height.
515 \fn bool QSizeF::isNull() const
517 Returns true if both the width and height are +0.0; otherwise returns
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.
524 \sa isValid(), isEmpty()
528 \fn bool QSizeF::isEmpty() const
530 Returns true if either of the width and height is less than or
531 equal to 0; otherwise returns false.
533 \sa isNull(), isValid()
537 \fn bool QSizeF::isValid() const
539 Returns true if both the width and height is equal to or greater
540 than 0; otherwise returns false.
542 \sa isNull(), isEmpty()
546 \fn int QSizeF::width() const
550 \sa height(), setWidth()
554 \fn int QSizeF::height() const
558 \sa width(), setHeight()
562 \fn void QSizeF::setWidth(qreal width)
564 Sets the width to the given \a width.
566 \sa width(), rwidth(), setHeight()
570 \fn void QSizeF::setHeight(qreal height)
572 Sets the height to the given \a height.
574 \sa height(), rheight(), setWidth()
578 \fn QSize QSizeF::toSize() const
580 Returns an integer based copy of this size.
582 Note that the coordinates in the returned size will be rounded to
589 Swaps the width and height values.
591 \sa setWidth(), setHeight(), transposed()
594 void QSizeF::transpose()
602 \fn QSizeF QSizeF::transposed() const
605 Returns the size with width and height values swapped.
611 \fn void QSizeF::scale(qreal width, qreal height, Qt::AspectRatioMode mode)
613 Scales the size to a rectangle with the given \a width and \a
614 height, according to the specified \a mode.
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.
625 \snippet doc/src/snippets/code/src_corelib_tools_qsize.cpp 5
627 \sa setWidth(), setHeight(), scaled()
631 \fn void QSizeF::scale(const QSizeF &size, Qt::AspectRatioMode mode)
634 Scales the size to a rectangle with the given \a size, according to
635 the specified \a mode.
639 \fn QSizeF QSizeF::scaled(int width, int height, Qt::AspectRatioMode mode) const
642 Returns a size scaled to a rectangle with the given \a width and
643 \a height, according to the specified \mode.
652 QSizeF QSizeF::scaled(const QSizeF &s, Qt::AspectRatioMode mode) const
654 if (mode == Qt::IgnoreAspectRatio || qIsNull(wd) || qIsNull(ht)) {
658 qreal rw = s.ht * wd / ht;
660 if (mode == Qt::KeepAspectRatio) {
661 useHeight = (rw <= s.wd);
662 } else { // mode == Qt::KeepAspectRatioByExpanding
663 useHeight = (rw >= s.wd);
667 return QSizeF(rw, s.ht);
669 return QSizeF(s.wd, s.wd * ht / wd);
675 \fn int &QSizeF::rwidth()
677 Returns a reference to the width.
679 Using a reference makes it possible to manipulate the width
680 directly. For example:
682 \snippet doc/src/snippets/code/src_corelib_tools_qsize.cpp 6
684 \sa rheight(), setWidth()
688 \fn int &QSizeF::rheight()
690 Returns a reference to the height.
692 Using a reference makes it possible to manipulate the height
693 directly. For example:
695 \snippet doc/src/snippets/code/src_corelib_tools_qsize.cpp 7
697 \sa rwidth(), setHeight()
701 \fn QSizeF &QSizeF::operator+=(const QSizeF &size)
703 Adds the given \a size to this size and returns a reference to
704 this size. For example:
706 \snippet doc/src/snippets/code/src_corelib_tools_qsize.cpp 8
710 \fn QSizeF &QSizeF::operator-=(const QSizeF &size)
712 Subtracts the given \a size from this size and returns a reference
713 to this size. For example:
715 \snippet doc/src/snippets/code/src_corelib_tools_qsize.cpp 9
719 \fn QSizeF &QSizeF::operator*=(qreal factor)
722 Multiplies both the width and height by the given \a factor and
723 returns a reference to the size.
729 \fn bool operator==(const QSizeF &s1, const QSizeF &s2)
732 Returns true if \a s1 and \a s2 are equal; otherwise returns
737 \fn bool operator!=(const QSizeF &s1, const QSizeF &s2)
740 Returns true if \a s1 and \a s2 are different; otherwise returns false.
744 \fn const QSizeF operator+(const QSizeF &s1, const QSizeF &s2)
747 Returns the sum of \a s1 and \a s2; each component is added separately.
751 \fn const QSizeF operator-(const QSizeF &s1, const QSizeF &s2)
754 Returns \a s2 subtracted from \a s1; each component is subtracted
759 \fn const QSizeF operator*(const QSizeF &size, qreal factor)
764 Multiplies the given \a size by the given \a factor and returns
771 \fn const QSizeF operator*(qreal factor, const QSizeF &size)
776 Multiplies the given \a size by the given \a factor and returns
781 \fn QSizeF &QSizeF::operator/=(qreal divisor)
785 Divides both the width and height by the given \a divisor and
786 returns a reference to the size.
792 \fn const QSizeF operator/(const QSizeF &size, qreal divisor)
797 Divides the given \a size by the given \a divisor and returns the
804 \fn QSizeF QSizeF::expandedTo(const QSizeF & otherSize) const
806 Returns a size holding the maximum width and height of this size
807 and the given \a otherSize.
809 \sa boundedTo(), scale()
813 \fn QSizeF QSizeF::boundedTo(const QSizeF & otherSize) const
815 Returns a size holding the minimum width and height of this size
816 and the given \a otherSize.
818 \sa expandedTo(), scale()
823 /*****************************************************************************
824 QSizeF stream functions
825 *****************************************************************************/
826 #ifndef QT_NO_DATASTREAM
828 \fn QDataStream &operator<<(QDataStream &stream, const QSizeF &size)
831 Writes the given \a size to the given \a stream and returns a
832 reference to the stream.
834 \sa {Serializing Qt Data Types}
837 QDataStream &operator<<(QDataStream &s, const QSizeF &sz)
839 s << double(sz.width()) << double(sz.height());
844 \fn QDataStream &operator>>(QDataStream &stream, QSizeF &size)
847 Reads a size from the given \a stream into the given \a size and
848 returns a reference to the stream.
850 \sa {Serializing Qt Data Types}
853 QDataStream &operator>>(QDataStream &s, QSizeF &sz)
858 sz.setWidth(qreal(w));
859 sz.setHeight(qreal(h));
862 #endif // QT_NO_DATASTREAM
864 #ifndef QT_NO_DEBUG_STREAM
865 QDebug operator<<(QDebug dbg, const QSizeF &s) {
866 dbg.nospace() << "QSizeF(" << s.width() << ", " << s.height() << ')';