print: Clamp margins entered by the user in the page setup dialog

The current functionality discards all margins if any values fall
outside the minimum or maximum limits. This can confuse and
frustrate users since the Windows native page setup dialog doesn't
enforce minimum values.

Introduce a new parameter outOfBoundsPolicy for the set margins
functions in the QPageLayout:
- OutOfBoundsPolicy::Reject The old behavior rejecting out of
  bounds values.
- OutOfBoundsPolicy::Clamp The new behavior for clamping the values.

The OutOfBoundsPolicy is applied only in StandardMode to maintain
backwards compatibility in FullPageMode, where all margins are
accepted.

Use the new Clamp policy in the printsupport where the clamping is
necessary.

Maintain binary compatibility by putting the declaration of the old
symbols without policy parameter behind QT_GUI_REMOVED_SINCE, and
implement them in removed_api.cpp to call the new versions.

Task-number: QTBUG-122410
Change-Id: I06aee292c1daff2863502f471b03798dafbcd81b
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>

7 files changed, 153 insertions, 61 deletions

diff --git a/src/gui/compat/removed_api.cpp b/src/gui/compat/removed_api.cpp
index a64580e9e1..659a27ecb6 100644
--- a/src/gui/compat/removed_api.cpp
+++ b/src/gui/compat/removed_api.cpp
@@ -26,8 +26,34 @@ bool Qt::mightBeRichText(const QString& text)
     return Qt::mightBeRichText(qToStringViewIgnoringNull(text));
 }
 
+#endif // QT_GUI_REMOVED_SINCE(6, 7)
+
+#if QT_GUI_REMOVED_SINCE(6, 8)
+
+#include "qpagelayout.h"
+
+bool QPageLayout::setMargins(const QMarginsF &margins)
+{
+    return setMargins(margins, OutOfBoundsPolicy::Reject);
+}
+
+bool QPageLayout::setLeftMargin(qreal leftMargin)
+{
+    return setLeftMargin(leftMargin, OutOfBoundsPolicy::Reject);
+}
+
+bool QPageLayout::setRightMargin(qreal rightMargin)
+{
+    return setRightMargin(rightMargin, OutOfBoundsPolicy::Reject);
+}
+
+bool QPageLayout::setTopMargin(qreal topMargin)
+{
+    return setTopMargin(topMargin, OutOfBoundsPolicy::Reject);
+}
+
 // #include "qotherheader.h"
 // // implement removed functions from qotherheader.h
 // order sections alphabetically
 
-#endif // QT_GUI_REMOVED_SINCE(6, 7)
+#endif // QT_GUI_REMOVED_SINCE(6, 8)
diff --git a/src/gui/painting/qpagelayout.cpp b/src/gui/painting/qpagelayout.cpp
index ec505f2cce..e60f464d6e 100644
--- a/src/gui/painting/qpagelayout.cpp
+++ b/src/gui/painting/qpagelayout.cpp
@@ -79,7 +79,7 @@ public:
 
     bool isValid() const;
 
-    void clampMargins(const QMarginsF &margins);
+    QMarginsF clampMargins(const QMarginsF &margins) const;
 
     QMarginsF margins(QPageLayout::Unit units) const;
     QMarginsF marginsPoints() const;
@@ -151,12 +151,12 @@ bool QPageLayoutPrivate::isValid() const
     return m_pageSize.isValid();
 }
 
-void QPageLayoutPrivate::clampMargins(const QMarginsF &margins)
+QMarginsF QPageLayoutPrivate::clampMargins(const QMarginsF &margins) const
 {
-    m_margins = QMarginsF(qBound(m_minMargins.left(),   margins.left(),   m_maxMargins.left()),
-                          qBound(m_minMargins.top(),    margins.top(),    m_maxMargins.top()),
-                          qBound(m_minMargins.right(),  margins.right(),  m_maxMargins.right()),
-                          qBound(m_minMargins.bottom(), margins.bottom(), m_maxMargins.bottom()));
+    return QMarginsF(qBound(m_minMargins.left(),   margins.left(),   m_maxMargins.left()),
+                     qBound(m_minMargins.top(),    margins.top(),    m_maxMargins.top()),
+                     qBound(m_minMargins.right(),  margins.right(),  m_maxMargins.right()),
+                     qBound(m_minMargins.bottom(), margins.bottom(), m_maxMargins.bottom()));
 }
 
 QMarginsF QPageLayoutPrivate::margins(QPageLayout::Unit units) const
@@ -182,7 +182,7 @@ void QPageLayoutPrivate::setDefaultMargins(const QMarginsF &minMargins)
                              qMax(m_fullSize.width() - m_minMargins.left(), qreal(0)),
                              qMax(m_fullSize.height() - m_minMargins.top(), qreal(0)));
     if (m_mode == QPageLayout::StandardMode)
-        clampMargins(m_margins);
+        m_margins = clampMargins(m_margins);
 }
 
 QSizeF QPageLayoutPrivate::fullSizeUnits(QPageLayout::Unit units) const
@@ -288,6 +288,27 @@ QRectF QPageLayoutPrivate::paintRect() const
 
     \value StandardMode Paint Rect includes margins, margins must fall between the minimum and maximum.
     \value FullPageMode Paint Rect excludes margins, margins can be any value and must be managed manually.
+
+    In StandardMode, when setting margins, use \l{QPageLayout::OutOfBoundsPolicy::}{Clamp} to
+    automatically clamp the margins to fall between the minimum and maximum
+    allowed values.
+
+    \sa OutOfBoundsPolicy
+*/
+
+/*!
+    \enum QPageLayout::OutOfBoundsPolicy
+    \since 6.8
+
+    Defines the policy for margins that are out of bounds
+
+    \value Reject The margins must fall within the minimum and maximum values,
+                  otherwise they will be rejected.
+    \value Clamp  The margins are clamped between the minimum and maximum
+                  values to ensure they are valid.
+
+    \note The policy has no effect in \l{QPageLayout::Mode}{FullPageMode},
+          where all margins are accepted.
 */
 
 /*!
@@ -525,39 +546,52 @@ QPageLayout::Unit QPageLayout::units() const
 }
 
 /*!
-    Sets the page margins of the page layout to \a margins
+    Sets the page margins of the page layout to \a margins.
     Returns true if the margins were successfully set.
 
     The units used are those currently defined for the layout.  To use different
     units then call setUnits() first.
 
-    If in the default StandardMode then all the new margins must fall between the
-    minimum margins set and the maximum margins allowed by the page size,
-    otherwise the margins will not be set.
-
-    If in FullPageMode then any margin values will be accepted.
+    Since Qt 6.8, the optional \a outOfBoundsPolicy can be used to specify how
+    margins that are out of bounds are handled.
 
     \sa margins(), units()
 */
 
-bool QPageLayout::setMargins(const QMarginsF &margins)
+bool QPageLayout::setMargins(const QMarginsF &margins, OutOfBoundsPolicy outOfBoundsPolicy)
 {
     if (d->m_mode == FullPageMode) {
-        d.detach();
-        d->m_margins = margins;
+        if (margins != d->m_margins) {
+            d.detach();
+            d->m_margins = margins;
+        }
         return true;
-    } else if (margins.left() >= d->m_minMargins.left()
-               && margins.right() >= d->m_minMargins.right()
-               && margins.top() >= d->m_minMargins.top()
-               && margins.bottom() >= d->m_minMargins.bottom()
-               && margins.left() <= d->m_maxMargins.left()
-               && margins.right() <= d->m_maxMargins.right()
-               && margins.top() <= d->m_maxMargins.top()
-               && margins.bottom() <= d->m_maxMargins.bottom()) {
-        d.detach();
-        d->m_margins = margins;
+    }
+
+    if (outOfBoundsPolicy == OutOfBoundsPolicy::Clamp) {
+        const QMarginsF clampedMargins = d->clampMargins(margins);
+        if (clampedMargins != d->m_margins) {
+            d.detach();
+            d->m_margins = clampedMargins;
+        }
         return true;
     }
+
+    if (margins.left() >= d->m_minMargins.left()
+        && margins.right() >= d->m_minMargins.right()
+        && margins.top() >= d->m_minMargins.top()
+        && margins.bottom() >= d->m_minMargins.bottom()
+        && margins.left() <= d->m_maxMargins.left()
+        && margins.right() <= d->m_maxMargins.right()
+        && margins.top() <= d->m_maxMargins.top()
+        && margins.bottom() <= d->m_maxMargins.bottom()) {
+        if (margins != d->m_margins) {
+            d.detach();
+            d->m_margins = margins;
+        }
+        return true;
+    }
+
     return false;
 }
 
@@ -568,23 +602,27 @@ bool QPageLayout::setMargins(const QMarginsF &margins)
     The units used are those currently defined for the layout.  To use different
     units call setUnits() first.
 
-    If in the default StandardMode then the new margin must fall between the
-    minimum margin set and the maximum margin allowed by the page size,
-    otherwise the margin will not be set.
-
-    If in FullPageMode then any margin values will be accepted.
+    Since Qt 6.8, the optional \a outOfBoundsPolicy can be used to specify how
+    margins that are out of bounds are handled.
 
     \sa setMargins(), margins()
 */
 
-bool QPageLayout::setLeftMargin(qreal leftMargin)
+bool QPageLayout::setLeftMargin(qreal leftMargin, OutOfBoundsPolicy outOfBoundsPolicy)
 {
+    if (d->m_mode == StandardMode && outOfBoundsPolicy == OutOfBoundsPolicy::Clamp)
+        leftMargin = qBound(d->m_minMargins.left(), leftMargin, d->m_maxMargins.left());
+
+    if (qFuzzyCompare(leftMargin, d->m_margins.left()))
+        return true;
+
     if (d->m_mode == FullPageMode
         || (leftMargin >= d->m_minMargins.left() && leftMargin <= d->m_maxMargins.left())) {
         d.detach();
         d->m_margins.setLeft(leftMargin);
         return true;
     }
+
     return false;
 }
 
@@ -595,23 +633,27 @@ bool QPageLayout::setLeftMargin(qreal leftMargin)
     The units used are those currently defined for the layout.  To use different
     units call setUnits() first.
 
-    If in the default StandardMode then the new margin must fall between the
-    minimum margin set and the maximum margin allowed by the page size,
-    otherwise the margin will not be set.
-
-    If in FullPageMode then any margin values will be accepted.
+    Since Qt 6.8, the optional \a outOfBoundsPolicy can be used to specify how
+    margins that are out of bounds are handled.
 
     \sa setMargins(), margins()
 */
 
-bool QPageLayout::setRightMargin(qreal rightMargin)
+bool QPageLayout::setRightMargin(qreal rightMargin, OutOfBoundsPolicy outOfBoundsPolicy)
 {
+    if (d->m_mode == StandardMode && outOfBoundsPolicy == OutOfBoundsPolicy::Clamp)
+        rightMargin = qBound(d->m_minMargins.right(), rightMargin, d->m_maxMargins.right());
+
+    if (qFuzzyCompare(rightMargin, d->m_margins.right()))
+        return true;
+
     if (d->m_mode == FullPageMode
         || (rightMargin >= d->m_minMargins.right() && rightMargin <= d->m_maxMargins.right())) {
         d.detach();
         d->m_margins.setRight(rightMargin);
         return true;
     }
+
     return false;
 }
 
@@ -622,23 +664,27 @@ bool QPageLayout::setRightMargin(qreal rightMargin)
     The units used are those currently defined for the layout.  To use different
     units call setUnits() first.
 
-    If in the default StandardMode then the new margin must fall between the
-    minimum margin set and the maximum margin allowed by the page size,
-    otherwise the margin will not be set.
-
-    If in FullPageMode then any margin values will be accepted.
+    Since Qt 6.8, the optional \a outOfBoundsPolicy can be used to specify how
+    margins that are out of bounds are handled.
 
     \sa setMargins(), margins()
 */
 
-bool QPageLayout::setTopMargin(qreal topMargin)
+bool QPageLayout::setTopMargin(qreal topMargin, OutOfBoundsPolicy outOfBoundsPolicy)
 {
+    if (d->m_mode == StandardMode && outOfBoundsPolicy == OutOfBoundsPolicy::Clamp)
+        topMargin = qBound(d->m_minMargins.top(), topMargin, d->m_maxMargins.top());
+
+    if (qFuzzyCompare(topMargin, d->m_margins.top()))
+        return true;
+
     if (d->m_mode == FullPageMode
         || (topMargin >= d->m_minMargins.top() && topMargin <= d->m_maxMargins.top())) {
         d.detach();
         d->m_margins.setTop(topMargin);
         return true;
     }
+
     return false;
 }
 
@@ -649,23 +695,27 @@ bool QPageLayout::setTopMargin(qreal topMargin)
     The units used are those currently defined for the layout.  To use different
     units call setUnits() first.
 
-    If in the default StandardMode then the new margin must fall between the
-    minimum margin set and the maximum margin allowed by the page size,
-    otherwise the margin will not be set.
-
-    If in FullPageMode then any margin values will be accepted.
+    Since Qt 6.8, the optional \a outOfBoundsPolicy can be used to specify how
+    margins that are out of bounds are handled.
 
     \sa setMargins(), margins()
 */
 
-bool QPageLayout::setBottomMargin(qreal bottomMargin)
+bool QPageLayout::setBottomMargin(qreal bottomMargin, OutOfBoundsPolicy outOfBoundsPolicy)
 {
+    if (d->m_mode == StandardMode && outOfBoundsPolicy == OutOfBoundsPolicy::Clamp)
+        bottomMargin = qBound(d->m_minMargins.bottom(), bottomMargin, d->m_maxMargins.bottom());
+
+    if (qFuzzyCompare(bottomMargin, d->m_margins.bottom()))
+        return true;
+
     if (d->m_mode == FullPageMode
         || (bottomMargin >= d->m_minMargins.bottom() && bottomMargin <= d->m_maxMargins.bottom())) {
         d.detach();
         d->m_margins.setBottom(bottomMargin);
         return true;
     }
+
     return false;
 }
 
diff --git a/src/gui/painting/qpagelayout.h b/src/gui/painting/qpagelayout.h
index 29be2f9725..1e340b6d75 100644
--- a/src/gui/painting/qpagelayout.h
+++ b/src/gui/painting/qpagelayout.h
@@ -40,6 +40,11 @@ public:
         FullPageMode   // Paint Rect excludes margins
     };
 
+    enum class OutOfBoundsPolicy {
+        Reject,
+        Clamp
+    };
+
     QPageLayout();
     QPageLayout(const QPageSize &pageSize, Orientation orientation,
                 const QMarginsF &margins, Unit units = Point,
@@ -68,11 +73,19 @@ public:
     void setUnits(Unit units);
     Unit units() const;
 
+#if QT_GUI_REMOVED_SINCE(6, 8)
     bool setMargins(const QMarginsF &margins);
     bool setLeftMargin(qreal leftMargin);
     bool setRightMargin(qreal rightMargin);
     bool setTopMargin(qreal topMargin);
     bool setBottomMargin(qreal bottomMargin);
+#endif
+
+    bool setMargins(const QMarginsF &margins, OutOfBoundsPolicy outOfBoundsPolicy = OutOfBoundsPolicy::Reject);
+    bool setLeftMargin(qreal leftMargin, OutOfBoundsPolicy outOfBoundsPolicy = OutOfBoundsPolicy::Reject);
+    bool setRightMargin(qreal rightMargin, OutOfBoundsPolicy outOfBoundsPolicy = OutOfBoundsPolicy::Reject);
+    bool setTopMargin(qreal topMargin, OutOfBoundsPolicy outOfBoundsPolicy = OutOfBoundsPolicy::Reject);
+    bool setBottomMargin(qreal bottomMargin, OutOfBoundsPolicy outOfBoundsPolicy = OutOfBoundsPolicy::Reject);
 
     QMarginsF margins() const;
     QMarginsF margins(Unit units) const;
diff --git a/src/printsupport/dialogs/qpagesetupdialog_win.cpp b/src/printsupport/dialogs/qpagesetupdialog_win.cpp
index 0f3011a638..1d2fdc98b7 100644
--- a/src/printsupport/dialogs/qpagesetupdialog_win.cpp
+++ b/src/printsupport/dialogs/qpagesetupdialog_win.cpp
@@ -123,10 +123,10 @@ int QPageSetupDialog::exec()
             pageSize = QPageSize(unitSize, layout.units() == QPageLayout::Inch
                                                            ? QPageSize::Inch : QPageSize::Millimeter);
         }
-        layout.setPageSize(pageSize);
+        layout.setPageSize(pageSize, layout.minimumMargins());
 
         const QMarginsF margins(psd.rtMargin.left, psd.rtMargin.top, psd.rtMargin.right, psd.rtMargin.bottom);
-        layout.setMargins(margins / multiplier);
+        layout.setMargins(margins / multiplier, QPageLayout::OutOfBoundsPolicy::Clamp);
         d->printer->setPageLayout(layout);
 
         // copy from our temp DEVMODE struct
diff --git a/src/printsupport/kernel/qprintengine_pdf.cpp b/src/printsupport/kernel/qprintengine_pdf.cpp
index 9dec15ae5b..3e50247186 100644
--- a/src/printsupport/kernel/qprintengine_pdf.cpp
+++ b/src/printsupport/kernel/qprintengine_pdf.cpp
@@ -184,7 +184,8 @@ void QPdfPrintEngine::setProperty(PrintEnginePropertyKey key, const QVariant &va
         Q_ASSERT(margins.size() == 4);
         d->m_pageLayout.setUnits(QPageLayout::Point);
         d->m_pageLayout.setMargins(QMarginsF(margins.at(0).toReal(), margins.at(1).toReal(),
-                                             margins.at(2).toReal(), margins.at(3).toReal()));
+                                             margins.at(2).toReal(), margins.at(3).toReal()),
+                                   QPageLayout::OutOfBoundsPolicy::Clamp);
         break;
     }
     case PPK_QPageSize: {
@@ -196,7 +197,7 @@ void QPdfPrintEngine::setProperty(PrintEnginePropertyKey key, const QVariant &va
     case PPK_QPageMargins: {
         QPair<QMarginsF, QPageLayout::Unit> pair = qvariant_cast<QPair<QMarginsF, QPageLayout::Unit> >(value);
         d->m_pageLayout.setUnits(pair.second);
-        d->m_pageLayout.setMargins(pair.first);
+        d->m_pageLayout.setMargins(pair.first, QPageLayout::OutOfBoundsPolicy::Clamp);
         break;
     }
     case PPK_QPageLayout: {
diff --git a/src/printsupport/platform/macos/qprintengine_mac.mm b/src/printsupport/platform/macos/qprintengine_mac.mm
index 1e6ca5ba26..d6eb71f66d 100644
--- a/src/printsupport/platform/macos/qprintengine_mac.mm
+++ b/src/printsupport/platform/macos/qprintengine_mac.mm
@@ -576,7 +576,8 @@ void QMacPrintEngine::setProperty(PrintEnginePropertyKey key, const QVariant &va
         QList<QVariant> margins(value.toList());
         Q_ASSERT(margins.size() == 4);
         d->m_pageLayout.setMargins(QMarginsF(margins.at(0).toReal(), margins.at(1).toReal(),
-                                             margins.at(2).toReal(), margins.at(3).toReal()));
+                                             margins.at(2).toReal(), margins.at(3).toReal()),
+                                   QPageLayout::OutOfBoundsPolicy::Clamp);
         break;
     }
     case PPK_QPageSize:
@@ -585,7 +586,7 @@ void QMacPrintEngine::setProperty(PrintEnginePropertyKey key, const QVariant &va
     case PPK_QPageMargins: {
         QPair<QMarginsF, QPageLayout::Unit> pair = value.value<QPair<QMarginsF, QPageLayout::Unit> >();
         d->m_pageLayout.setUnits(pair.second);
-        d->m_pageLayout.setMargins(pair.first);
+        d->m_pageLayout.setMargins(pair.first, QPageLayout::OutOfBoundsPolicy::Clamp);
         break;
     }
     case PPK_QPageLayout: {
@@ -595,7 +596,7 @@ void QMacPrintEngine::setProperty(PrintEnginePropertyKey key, const QVariant &va
             setProperty(PPK_FullPage, pageLayout.mode() == QPageLayout::FullPageMode);
             setProperty(PPK_Orientation, QVariant::fromValue(pageLayout.orientation()));
             d->m_pageLayout.setUnits(pageLayout.units());
-            d->m_pageLayout.setMargins(pageLayout.margins());
+            d->m_pageLayout.setMargins(pageLayout.margins(), QPageLayout::OutOfBoundsPolicy::Clamp);
         }
         break;
     }
diff --git a/src/printsupport/platform/windows/qprintengine_win.cpp b/src/printsupport/platform/windows/qprintengine_win.cpp
index d11f20dde2..fa8d03a615 100644
--- a/src/printsupport/platform/windows/qprintengine_win.cpp
+++ b/src/printsupport/platform/windows/qprintengine_win.cpp
@@ -1285,7 +1285,8 @@ void QWin32PrintEngine::setProperty(PrintEnginePropertyKey key, const QVariant &
         Q_ASSERT(margins.size() == 4);
         d->m_pageLayout.setUnits(QPageLayout::Point);
         d->m_pageLayout.setMargins(QMarginsF(margins.at(0).toReal(), margins.at(1).toReal(),
-                                             margins.at(2).toReal(), margins.at(3).toReal()));
+                                             margins.at(2).toReal(), margins.at(3).toReal()),
+                                   QPageLayout::OutOfBoundsPolicy::Clamp);
         d->updateMetrics();
 #ifdef QT_DEBUG_METRICS
         qDebug() << "QWin32PrintEngine::setProperty(PPK_PageMargins," << margins << ')';
@@ -1313,7 +1314,7 @@ void QWin32PrintEngine::setProperty(PrintEnginePropertyKey key, const QVariant &
     case PPK_QPageMargins: {
         QPair<QMarginsF, QPageLayout::Unit> pair = value.value<QPair<QMarginsF, QPageLayout::Unit> >();
         d->m_pageLayout.setUnits(pair.second);
-        d->m_pageLayout.setMargins(pair.first);
+        d->m_pageLayout.setMargins(pair.first, QPageLayout::OutOfBoundsPolicy::Clamp);
         d->updateMetrics();
 #ifdef QT_DEBUG_METRICS
         qDebug() << "QWin32PrintEngine::setProperty(PPK_QPageMargins," << pair.first << pair.second << ')';
@@ -1329,7 +1330,7 @@ void QWin32PrintEngine::setProperty(PrintEnginePropertyKey key, const QVariant &
             setProperty(PPK_FullPage, pageLayout.mode() == QPageLayout::FullPageMode);
             setProperty(PPK_Orientation, QVariant::fromValue(pageLayout.orientation()));
             d->m_pageLayout.setUnits(pageLayout.units());
-            d->m_pageLayout.setMargins(pageLayout.margins());
+            d->m_pageLayout.setMargins(pageLayout.margins(), QPageLayout::OutOfBoundsPolicy::Clamp);
             d->updateMetrics();
 #ifdef QT_DEBUG_METRICS
             qDebug() << "QWin32PrintEngine::setProperty(PPK_QPageLayout," << pageLayout << ')';