diff options
Diffstat (limited to 'src/corelib/tools/qmargins.cpp')
-rw-r--r-- | src/corelib/tools/qmargins.cpp | 225 |
1 files changed, 132 insertions, 93 deletions
diff --git a/src/corelib/tools/qmargins.cpp b/src/corelib/tools/qmargins.cpp index 74be7bb2ba..c4cd0da30d 100644 --- a/src/corelib/tools/qmargins.cpp +++ b/src/corelib/tools/qmargins.cpp @@ -1,41 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the QtCore module of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 3 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL3 included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 3 requirements -** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. -** -** GNU General Public License Usage -** Alternatively, this file may be used under the terms of the GNU -** General Public License version 2.0 or (at your option) the GNU General -** Public license version 3 or any later version approved by the KDE Free -** Qt Foundation. The licenses are as published by the Free Software -** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 -** included in the packaging of this file. Please review the following -** information to ensure the GNU General Public License requirements will -** be met: https://www.gnu.org/licenses/gpl-2.0.html and -** https://www.gnu.org/licenses/gpl-3.0.html. -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only #include "qmargins.h" #include "qdatastream.h" @@ -50,9 +14,13 @@ QT_BEGIN_NAMESPACE \ingroup painting \since 4.6 + \compares equality + \compareswith equality QMarginsF + \endcompareswith + \brief The QMargins class defines the four margins of a rectangle. - QMargin defines a set of four margins; left, top, right and bottom, + QMargin defines a set of four margins; left, top, right, and bottom, that describe the size of the borders surrounding a rectangle. The isNull() function returns \c true only if all margins are set to zero. @@ -76,7 +44,7 @@ QT_BEGIN_NAMESPACE /*! \fn QMargins::QMargins(int left, int top, int right, int bottom) - Constructs margins with the given \a left, \a top, \a right, \a bottom + Constructs margins with the given \a left, \a top, \a right, and \a bottom \sa setLeft(), setRight(), setTop(), setBottom() */ @@ -143,21 +111,19 @@ QT_BEGIN_NAMESPACE */ /*! - \fn bool operator==(const QMargins &m1, const QMargins &m2) - \relates QMargins + \fn bool QMargins::operator==(const QMargins &lhs, const QMargins &rhs) - Returns \c true if \a m1 and \a m2 are equal; otherwise returns \c false. + Returns \c true if \a lhs and \a rhs are equal; otherwise returns \c false. */ /*! - \fn bool operator!=(const QMargins &m1, const QMargins &m2) - \relates QMargins + \fn bool QMargins::operator!=(const QMargins &lhs, const QMargins &rhs) - Returns \c true if \a m1 and \a m2 are different; otherwise returns \c false. + Returns \c true if \a lhs and \a rhs are different; otherwise returns \c false. */ /*! - \fn const QMargins operator+(const QMargins &m1, const QMargins &m2) + \fn QMargins operator+(const QMargins &m1, const QMargins &m2) \relates QMargins Returns a QMargins object that is the sum of the given margins, \a m1 @@ -169,7 +135,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn const QMargins operator-(const QMargins &m1, const QMargins &m2) + \fn QMargins operator-(const QMargins &m1, const QMargins &m2) \relates QMargins Returns a QMargins object that is formed by subtracting \a m2 from @@ -181,7 +147,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn const QMargins operator+(const QMargins &lhs, int rhs) + \fn QMargins operator+(const QMargins &lhs, int rhs) \relates QMargins Returns a QMargins object that is formed by adding \a rhs to @@ -193,7 +159,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn const QMargins operator+(int lhs, const QMargins &rhs) + \fn QMargins operator+(int lhs, const QMargins &rhs) \relates QMargins Returns a QMargins object that is formed by adding \a lhs to @@ -205,7 +171,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn const QMargins operator-(const QMargins &lhs, int rhs) + \fn QMargins operator-(const QMargins &lhs, int rhs) \relates QMargins Returns a QMargins object that is formed by subtracting \a rhs from @@ -217,7 +183,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn const QMargins operator*(const QMargins &margins, int factor) + \fn QMargins operator*(const QMargins &margins, int factor) \relates QMargins Returns a QMargins object that is formed by multiplying each component @@ -229,7 +195,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn const QMargins operator*(int factor, const QMargins &margins) + \fn QMargins operator*(int factor, const QMargins &margins) \relates QMargins \overload @@ -242,7 +208,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn const QMargins operator*(const QMargins &margins, qreal factor) + \fn QMargins operator*(const QMargins &margins, qreal factor) \relates QMargins \overload @@ -255,7 +221,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn const QMargins operator*(qreal factor, const QMargins &margins) + \fn QMargins operator*(qreal factor, const QMargins &margins) \relates QMargins \overload @@ -268,7 +234,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn const QMargins operator/(const QMargins &margins, int divisor) + \fn QMargins operator/(const QMargins &margins, int divisor) \relates QMargins Returns a QMargins object that is formed by dividing the components of @@ -280,7 +246,7 @@ QT_BEGIN_NAMESPACE */ /*! - \fn const QMargins operator/(const QMargins &, qreal) + \fn QMargins operator/(const QMargins &, qreal) \relates QMargins \overload @@ -311,6 +277,18 @@ QT_BEGIN_NAMESPACE */ /*! + \fn QMargins operator|(const QMargins &m1, const QMargins &m2) + \relates QMargins + + Returns a QMargins object that is formed from the maximum of each + component of \a m2 and \a m1. + + \sa QMargins::operator+=(), QMargins::operator-=() + + \since 6.0 +*/ + +/*! \fn QMargins &QMargins::operator+=(const QMargins &margins) Add each component of \a margins to the respective component of this object @@ -396,6 +374,15 @@ QT_BEGIN_NAMESPACE \since 5.1 */ +/*! + \fn QMargins::toMarginsF() const + \since 6.4 + + Returns these margins as margins with floating point accuracy. + + \sa QMarginsF::toMargins() +*/ + /***************************************************************************** QMargins stream functions *****************************************************************************/ @@ -455,12 +442,16 @@ QDebug operator<<(QDebug dbg, const QMargins &m) \ingroup painting \since 5.3 + \compares equality + \compareswith equality QMargins + \endcompareswith + \brief The QMarginsF class defines the four margins of a rectangle. - QMarginsF defines a set of four margins; left, top, right and bottom, - that describe the size of the borders surrounding a rectangle. + QMarginsF defines a set of four margins; left, top, right, and bottom, + that describe the finite size of the borders surrounding a rectangle. - The isNull() function returns \c true only if all margins are set to zero. + The isNull() function returns \c true only if all margins are very close to zero. QMarginsF objects can be streamed as well as compared. */ @@ -481,7 +472,8 @@ QDebug operator<<(QDebug dbg, const QMargins &m) /*! \fn QMarginsF::QMarginsF(qreal left, qreal top, qreal right, qreal bottom) - Constructs margins with the given \a left, \a top, \a right, \a bottom + Constructs margins with the given \a left, \a top, \a right, and \a bottom. + All parameters must be finite. \sa setLeft(), setRight(), setTop(), setBottom() */ @@ -489,14 +481,18 @@ QDebug operator<<(QDebug dbg, const QMargins &m) /*! \fn QMarginsF::QMarginsF(const QMargins &margins) - Constructs margins copied from the given \a margins + Constructs margins copied from the given \a margins. + + \sa QMargins::toMarginsF() */ /*! \fn bool QMarginsF::isNull() const - Returns \c true if all margins are 0; otherwise returns + Returns \c true if all margins are very close to 0; otherwise returns false. + + \sa {<QtNumeric>::}{qFuzzyIsNull()} */ @@ -530,41 +526,51 @@ QDebug operator<<(QDebug dbg, const QMargins &m) /*! - \fn void QMarginsF::setLeft(qreal left) + \fn void QMarginsF::setLeft(qreal aleft) - Sets the left margin to \a left. + Sets the left margin to \a aleft (which must be finite). */ /*! - \fn void QMarginsF::setTop(qreal Top) + \fn void QMarginsF::setTop(qreal atop) - Sets the Top margin to \a Top. + Sets the top margin to \a atop (which must be finite). */ /*! - \fn void QMarginsF::setRight(qreal right) + \fn void QMarginsF::setRight(qreal aright) - Sets the right margin to \a right. + Sets the right margin to \a aright (which must be finite). */ /*! - \fn void QMarginsF::setBottom(qreal bottom) + \fn void QMarginsF::setBottom(qreal abottom) - Sets the bottom margin to \a bottom. + Sets the bottom margin to \a abottom (which must be finite). */ /*! - \fn bool operator==(const QMarginsF &lhs, const QMarginsF &rhs) - \relates QMarginsF + \fn bool QMarginsF::operator==(const QMarginsF &lhs, const QMarginsF &rhs) - Returns \c true if \a lhs and \a rhs are equal; otherwise returns \c false. + Returns \c true if \a lhs and \a rhs are approximately equal; otherwise + returns false. + + \warning This function does not check for strict equality; instead, + it uses a fuzzy comparison to compare the margins. + + \sa qFuzzyCompare */ /*! - \fn bool operator!=(const QMarginsF &lhs, const QMarginsF &rhs) - \relates QMarginsF + \fn bool QMarginsF::operator!=(const QMarginsF &lhs, const QMarginsF &rhs) - Returns \c true if \a lhs and \a rhs are different; otherwise returns \c false. + Returns \c true if \a lhs and \a rhs are sufficiently different; otherwise + returns \c false. + + \warning This function does not check for strict inequality; instead, + it uses a fuzzy comparison to compare the margins. + + \sa qFuzzyCompare */ /*! @@ -591,8 +597,8 @@ QDebug operator<<(QDebug dbg, const QMargins &m) \fn const QMarginsF operator+(const QMarginsF &lhs, qreal rhs) \relates QMarginsF - Returns a QMarginsF object that is formed by adding \a rhs to - \a lhs. + Returns a QMarginsF object that is formed by adding \a rhs (which must be + finite) to each component of \a lhs. \sa QMarginsF::operator+=(), QMarginsF::operator-=() */ @@ -601,8 +607,8 @@ QDebug operator<<(QDebug dbg, const QMargins &m) \fn const QMarginsF operator+(qreal lhs, const QMarginsF &rhs) \relates QMarginsF - Returns a QMarginsF object that is formed by adding \a lhs to - \a rhs. + Returns a QMarginsF object that is formed by adding \a lhs (which must be + finite) to each component of \a rhs. \sa QMarginsF::operator+=(), QMarginsF::operator-=() */ @@ -611,8 +617,8 @@ QDebug operator<<(QDebug dbg, const QMargins &m) \fn const QMarginsF operator-(const QMarginsF &lhs, qreal rhs) \relates QMarginsF - Returns a QMarginsF object that is formed by subtracting \a rhs from - \a lhs. + Returns a QMarginsF object that is formed by subtracting \a rhs (which must + be finite) from each component of \a lhs. \sa QMarginsF::operator+=(), QMarginsF::operator-=() */ @@ -623,7 +629,7 @@ QDebug operator<<(QDebug dbg, const QMargins &m) \overload Returns a QMarginsF object that is formed by multiplying each component - of the given \a lhs margins by \a rhs factor. + of the given \a lhs margins by finite factor \a rhs. \sa QMarginsF::operator*=(), QMarginsF::operator/=() */ @@ -634,7 +640,7 @@ QDebug operator<<(QDebug dbg, const QMargins &m) \overload Returns a QMarginsF object that is formed by multiplying each component - of the given \a lhs margins by \a rhs factor. + of the given \a lhs margins by finite factor \a rhs. \sa QMarginsF::operator*=(), QMarginsF::operator/=() */ @@ -647,10 +653,25 @@ QDebug operator<<(QDebug dbg, const QMargins &m) Returns a QMarginsF object that is formed by dividing the components of the given \a lhs margins by the given \a rhs divisor. + The divisor must not be either zero or NaN. + \sa QMarginsF::operator*=(), QMarginsF::operator/=() */ /*! + \fn QMarginsF operator|(const QMarginsF &m1, const QMarginsF &m2) + \relates QMarginsF + \overload + + Returns a QMarginsF object that is formed from the maximum of each + component of \a m2 and \a m1. + + \sa QMarginsF::operator+=(), QMarginsF::operator-=() + + \since 6.0 +*/ + +/*! \fn QMarginsF operator+(const QMarginsF &margins) \relates QMarginsF @@ -686,7 +707,7 @@ QDebug operator<<(QDebug dbg, const QMargins &m) \fn QMarginsF &QMarginsF::operator+=(qreal addend) \overload - Adds the \a addend to each component of this object + Adds the given finite \a addend to each component of this object and returns a reference to it. \sa operator-=() @@ -696,7 +717,7 @@ QDebug operator<<(QDebug dbg, const QMargins &m) \fn QMarginsF &QMarginsF::operator-=(qreal subtrahend) \overload - Subtracts the \a subtrahend from each component of this object + Subtracts the given finite \a subtrahend from each component of this object and returns a reference to it. \sa operator+=() @@ -705,8 +726,8 @@ QDebug operator<<(QDebug dbg, const QMargins &m) /*! \fn QMarginsF &QMarginsF::operator*=(qreal factor) - Multiplies each component of this object by \a factor - and returns a reference to it. + Multiplies each component of this object by the given finite \a factor + and returns a reference to this object. \sa operator/=() */ @@ -714,8 +735,10 @@ QDebug operator<<(QDebug dbg, const QMargins &m) /*! \fn QMarginsF &QMarginsF::operator/=(qreal divisor) - Divides each component of this object by \a divisor - and returns a reference to it. + Divides each component of this object by \a divisor and returns a reference + to this object. + + The \a divisor must not be either zero or NaN. \sa operator*=() */ @@ -723,12 +746,28 @@ QDebug operator<<(QDebug dbg, const QMargins &m) /*! \fn QMargins QMarginsF::toMargins() const - Returns an integer based copy of this margins object. + Returns an integer-based copy of this margins object. Note that the components in the returned margins will be rounded to the nearest integer. - \sa QMarginsF() + \sa QMarginsF(), QMargins::toMarginsF() +*/ + +/*! + \fn bool QMarginsF::qFuzzyCompare(const QMarginsF &lhs, const QMarginsF &rhs) + \since 6.8 + + Returns \c true if \a lhs is approximately equal to \a rhs; + otherwise returns \c false. +*/ + +/*! + \fn bool QMarginsF::qFuzzyIsNull(const QMarginsF &margins) + \since 6.8 + + Returns \c true if all components of margsins \a margins are + approximately equal to zero; otherwise returns \c false. */ /***************************************************************************** |