Popup: add support for background insets

[ChangeLog][Controls][Popup] Added topInset, bottomInset, leftInset,
and rightInset properties to control the geometry of the background
similarly to how paddings control the geometry of the contentItem.

Task-number: QTBUG-60156
Change-Id: I02873f129d2a804986d0db52d1b94899f9219c03
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>

2 files changed, 173 insertions, 4 deletions

diff --git a/src/quicktemplates2/qquickpopup.cpp b/src/quicktemplates2/qquickpopup.cpp
index 8c0624f2..08b3ee63 100644
--- a/src/quicktemplates2/qquickpopup.cpp
+++ b/src/quicktemplates2/qquickpopup.cpp
@@ -110,14 +110,42 @@ QT_BEGIN_NAMESPACE
     \image qtquickcontrols2-popup.png
 
     The \l implicitWidth and \l implicitHeight of a popup are typically based
-    on the implicit sizes of the background and the content item plus any
-    \l padding. These properties determine how large the popup will be when no
+    on the implicit sizes of the background and the content item plus any insets
+    and paddings. These properties determine how large the popup will be when no
     explicit \l width or \l height is specified.
 
+    The geometry of the \l contentItem is determined by the padding. The following
+    example reserves 10px padding between the boundaries of the popup and its content:
+
+    \code
+    Popup {
+        padding: 10
+
+        contentItem: Text {
+            text: "Content"
+        }
+    }
+    \endcode
+
     The \l background item fills the entire width and height of the popup,
-    unless an explicit size has been given for it.
+    unless insets or an explicit size have been given for it.
+
+    Negative insets can be used to make the background larger than the popup.
+    The following example uses negative insets to place a shadow outside the
+    popup's boundaries:
+
+    \code
+    Popup {
+        topInset: -2
+        leftInset: -2
+        rightInset: -6
+        bottomInset: -6
 
-    The geometry of the \l contentItem is determined by the \l padding.
+        background: BorderImage {
+            source: ":/images/shadowed-background.png"
+        }
+    }
+    \endcode
 
     \section1 Popup Sizing
 
@@ -2258,6 +2286,110 @@ qreal QQuickPopup::implicitBackgroundHeight() const
     return d->popupItem->implicitBackgroundHeight();
 }
 
+/*!
+    \since QtQuick.Controls 2.5 (Qt 5.12)
+    \qmlproperty real QtQuick.Controls::Popup::topInset
+
+    This property holds the top inset for the background.
+
+    \sa {Popup Layout}, bottomInset
+*/
+qreal QQuickPopup::topInset() const
+{
+    Q_D(const QQuickPopup);
+    return d->popupItem->topInset();
+}
+
+void QQuickPopup::setTopInset(qreal inset)
+{
+    Q_D(QQuickPopup);
+    d->popupItem->setTopInset(inset);
+}
+
+void QQuickPopup::resetTopInset()
+{
+    Q_D(QQuickPopup);
+    d->popupItem->resetTopInset();
+}
+
+/*!
+    \since QtQuick.Controls 2.5 (Qt 5.12)
+    \qmlproperty real QtQuick.Controls::Popup::leftInset
+
+    This property holds the left inset for the background.
+
+    \sa {Popup Layout}, rightInset
+*/
+qreal QQuickPopup::leftInset() const
+{
+    Q_D(const QQuickPopup);
+    return d->popupItem->leftInset();
+}
+
+void QQuickPopup::setLeftInset(qreal inset)
+{
+    Q_D(QQuickPopup);
+    d->popupItem->setLeftInset(inset);
+}
+
+void QQuickPopup::resetLeftInset()
+{
+    Q_D(QQuickPopup);
+    d->popupItem->resetLeftInset();
+}
+
+/*!
+    \since QtQuick.Controls 2.5 (Qt 5.12)
+    \qmlproperty real QtQuick.Controls::Popup::rightInset
+
+    This property holds the right inset for the background.
+
+    \sa {Popup Layout}, leftInset
+*/
+qreal QQuickPopup::rightInset() const
+{
+    Q_D(const QQuickPopup);
+    return d->popupItem->rightInset();
+}
+
+void QQuickPopup::setRightInset(qreal inset)
+{
+    Q_D(QQuickPopup);
+    d->popupItem->setRightInset(inset);
+}
+
+void QQuickPopup::resetRightInset()
+{
+    Q_D(QQuickPopup);
+    d->popupItem->resetRightInset();
+}
+
+/*!
+    \since QtQuick.Controls 2.5 (Qt 5.12)
+    \qmlproperty real QtQuick.Controls::Popup::bottomInset
+
+    This property holds the bottom inset for the background.
+
+    \sa {Popup Layout}, topInset
+*/
+qreal QQuickPopup::bottomInset() const
+{
+    Q_D(const QQuickPopup);
+    return d->popupItem->bottomInset();
+}
+
+void QQuickPopup::setBottomInset(qreal inset)
+{
+    Q_D(QQuickPopup);
+    d->popupItem->setBottomInset(inset);
+}
+
+void QQuickPopup::resetBottomInset()
+{
+    Q_D(QQuickPopup);
+    d->popupItem->resetBottomInset();
+}
+
 bool QQuickPopup::filtersChildMouseEvents() const
 {
     Q_D(const QQuickPopup);
@@ -2540,6 +2672,18 @@ void QQuickPopup::spacingChange(qreal newSpacing, qreal oldSpacing)
     emit spacingChanged();
 }
 
+void QQuickPopup::insetChange(const QMarginsF &newInset, const QMarginsF &oldInset)
+{
+    if (!qFuzzyCompare(newInset.top(), oldInset.top()))
+        emit topInsetChanged();
+    if (!qFuzzyCompare(newInset.left(), oldInset.left()))
+        emit leftInsetChanged();
+    if (!qFuzzyCompare(newInset.right(), oldInset.right()))
+        emit rightInsetChanged();
+    if (!qFuzzyCompare(newInset.bottom(), oldInset.bottom()))
+        emit bottomInsetChanged();
+}
+
 QFont QQuickPopup::defaultFont() const
 {
     return QQuickTheme::themeFont(QQuickTheme::System);
diff --git a/src/quicktemplates2/qquickpopup_p.h b/src/quicktemplates2/qquickpopup_p.h
index 1d232e92..12dbd247 100644
--- a/src/quicktemplates2/qquickpopup_p.h
+++ b/src/quicktemplates2/qquickpopup_p.h
@@ -130,6 +130,10 @@ class Q_QUICKTEMPLATES2_PRIVATE_EXPORT QQuickPopup : public QObject, public QQml
     Q_PROPERTY(qreal implicitContentHeight READ implicitContentHeight NOTIFY implicitContentHeightChanged FINAL REVISION 5)
     Q_PROPERTY(qreal implicitBackgroundWidth READ implicitBackgroundWidth NOTIFY implicitBackgroundWidthChanged FINAL REVISION 5)
     Q_PROPERTY(qreal implicitBackgroundHeight READ implicitBackgroundHeight NOTIFY implicitBackgroundHeightChanged FINAL REVISION 5)
+    Q_PROPERTY(qreal topInset READ topInset WRITE setTopInset RESET resetTopInset NOTIFY topInsetChanged FINAL REVISION 5)
+    Q_PROPERTY(qreal leftInset READ leftInset WRITE setLeftInset RESET resetLeftInset NOTIFY leftInsetChanged FINAL REVISION 5)
+    Q_PROPERTY(qreal rightInset READ rightInset WRITE setRightInset RESET resetRightInset NOTIFY rightInsetChanged FINAL REVISION 5)
+    Q_PROPERTY(qreal bottomInset READ bottomInset WRITE setBottomInset RESET resetBottomInset NOTIFY bottomInsetChanged FINAL REVISION 5)
     Q_CLASSINFO("DeferredPropertyNames", "background,contentItem")
     Q_CLASSINFO("DefaultProperty", "contentData")
 
@@ -325,6 +329,22 @@ public:
     qreal implicitBackgroundWidth() const;
     qreal implicitBackgroundHeight() const;
 
+    qreal topInset() const;
+    void setTopInset(qreal inset);
+    void resetTopInset();
+
+    qreal leftInset() const;
+    void setLeftInset(qreal inset);
+    void resetLeftInset();
+
+    qreal rightInset() const;
+    void setRightInset(qreal inset);
+    void resetRightInset();
+
+    qreal bottomInset() const;
+    void setBottomInset(qreal inset);
+    void resetBottomInset();
+
 public Q_SLOTS:
     void open();
     void close();
@@ -387,6 +407,10 @@ Q_SIGNALS:
     Q_REVISION(5) void implicitContentHeightChanged();
     Q_REVISION(5) void implicitBackgroundWidthChanged();
     Q_REVISION(5) void implicitBackgroundHeightChanged();
+    Q_REVISION(5) void topInsetChanged();
+    Q_REVISION(5) void leftInsetChanged();
+    Q_REVISION(5) void rightInsetChanged();
+    Q_REVISION(5) void bottomInsetChanged();
 
 protected:
     QQuickPopup(QQuickPopupPrivate &dd, QObject *parent);
@@ -424,6 +448,7 @@ protected:
     virtual void paddingChange(const QMarginsF &newPadding, const QMarginsF &oldPadding);
     virtual void paletteChange(const QPalette &newPalette, const QPalette &oldPalette);
     virtual void spacingChange(qreal newSpacing, qreal oldSpacing);
+    virtual void insetChange(const QMarginsF &newInset, const QMarginsF &oldInset);
 
     virtual QFont defaultFont() const;
     virtual QPalette defaultPalette() const;