AbstractButton: add display property

This property allows control over how icons and text are displayed
within buttons, without having to implement custom delegates. It is
also necessary for the upcoming Action type.

[ChangeLog][Controls][AbstractButton] Added display property to
allow control over how icons and text are displayed within buttons,
without having to implement custom delegates.

Task-number: QTBUG-49820
Change-Id: Ie924e2c54ed49961fd40129999875c8175606ecd
Reviewed-by: J-P Nurmi <jpnurmi@qt.io>

13 files changed, 208 insertions, 2 deletions

diff --git a/src/imports/controls/Button.qml b/src/imports/controls/Button.qml
index bdf09f32..814448a2 100644
--- a/src/imports/controls/Button.qml
+++ b/src/imports/controls/Button.qml
@@ -60,6 +60,7 @@ T.Button {
     contentItem: DisplayLayout {
         spacing: control.spacing
         mirrored: control.mirrored
+        display: control.display
 
         icon: IconImage {
             id: iconImage
diff --git a/src/imports/controls/doc/images/qtquickcontrols2-button-icononly.png b/src/imports/controls/doc/images/qtquickcontrols2-button-icononly.png
new file mode 100644
index 00000000..91a21d17
--- /dev/null
+++ b/src/imports/controls/doc/images/qtquickcontrols2-button-icononly.png
diff --git a/src/imports/controls/doc/images/qtquickcontrols2-button-textbesideicon.png b/src/imports/controls/doc/images/qtquickcontrols2-button-textbesideicon.png
new file mode 100644
index 00000000..1d46133f
--- /dev/null
+++ b/src/imports/controls/doc/images/qtquickcontrols2-button-textbesideicon.png
diff --git a/src/imports/controls/doc/images/qtquickcontrols2-button-textonly.png b/src/imports/controls/doc/images/qtquickcontrols2-button-textonly.png
new file mode 100644
index 00000000..4449e748
--- /dev/null
+++ b/src/imports/controls/doc/images/qtquickcontrols2-button-textonly.png
diff --git a/src/imports/controls/doc/snippets/screenshots/qtquickcontrols2-button-icononly.qml b/src/imports/controls/doc/snippets/screenshots/qtquickcontrols2-button-icononly.qml
new file mode 100644
index 00000000..0a58d4ad
--- /dev/null
+++ b/src/imports/controls/doc/snippets/screenshots/qtquickcontrols2-button-icononly.qml
@@ -0,0 +1,34 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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 http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+import QtQuick 2.9
+import QtQuick.Controls 2.3
+
+Button {
+    icon.source: "qrc:/qt-project.org/imports/QtQuick/Controls.2/images/check.png"
+    display: Button.IconOnly
+}
diff --git a/src/imports/controls/doc/snippets/screenshots/qtquickcontrols2-button-textbesideicon.qml b/src/imports/controls/doc/snippets/screenshots/qtquickcontrols2-button-textbesideicon.qml
new file mode 100644
index 00000000..308837f7
--- /dev/null
+++ b/src/imports/controls/doc/snippets/screenshots/qtquickcontrols2-button-textbesideicon.qml
@@ -0,0 +1,35 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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 http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+import QtQuick 2.9
+import QtQuick.Controls 2.3
+
+Button {
+    text: "Button"
+    icon.source: "qrc:/qt-project.org/imports/QtQuick/Controls.2/images/check.png"
+    display: Button.TextBesideIcon
+}
diff --git a/src/imports/controls/doc/snippets/screenshots/qtquickcontrols2-button-textonly.qml b/src/imports/controls/doc/snippets/screenshots/qtquickcontrols2-button-textonly.qml
new file mode 100644
index 00000000..89d335e4
--- /dev/null
+++ b/src/imports/controls/doc/snippets/screenshots/qtquickcontrols2-button-textonly.qml
@@ -0,0 +1,34 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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 http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+import QtQuick 2.9
+import QtQuick.Controls 2.3
+
+Button {
+    text: "Button"
+    display: Button.TextOnly
+}
diff --git a/src/imports/controls/material/Button.qml b/src/imports/controls/material/Button.qml
index d73eb240..47a02e53 100644
--- a/src/imports/controls/material/Button.qml
+++ b/src/imports/controls/material/Button.qml
@@ -67,6 +67,7 @@ T.Button {
     contentItem: DisplayLayout {
         spacing: control.spacing
         mirrored: control.mirrored
+        display: control.display
 
         icon: IconImage {
             id: iconImage
diff --git a/src/imports/controls/universal/Button.qml b/src/imports/controls/universal/Button.qml
index 5b6951a5..a5e03ea2 100644
--- a/src/imports/controls/universal/Button.qml
+++ b/src/imports/controls/universal/Button.qml
@@ -63,6 +63,7 @@ T.Button {
     contentItem: DisplayLayout {
         spacing: control.spacing
         mirrored: control.mirrored
+        display: control.display
 
         icon: IconImage {
             id: iconImage
diff --git a/src/quicktemplates2/qquickabstractbutton.cpp b/src/quicktemplates2/qquickabstractbutton.cpp
index 0a2c7e6d..c0d8101e 100644
--- a/src/quicktemplates2/qquickabstractbutton.cpp
+++ b/src/quicktemplates2/qquickabstractbutton.cpp
@@ -92,6 +92,9 @@ static const int AUTO_REPEAT_INTERVAL = 100;
     the behavior is the same as the \l {Image::}{sourceSize} property of
     \l Image.
 
+    The \l display property can be used to control how the icon and text are
+    displayed within the button.
+
     \sa ButtonGroup, {Button Controls}
 */
 
@@ -157,7 +160,8 @@ QQuickAbstractButtonPrivate::QQuickAbstractButtonPrivate()
       repeatButton(Qt::NoButton),
       indicator(nullptr),
       group(nullptr),
-      icon(nullptr)
+      icon(nullptr),
+      display(QQuickAbstractButton::TextBesideIcon)
 {
 }
 
@@ -815,4 +819,36 @@ QAccessible::Role QQuickAbstractButton::accessibleRole() const
 }
 #endif
 
+/*!
+    \since QtQuick.Controls 2.3
+    \qmlproperty enumeration QtQuick.Controls::AbstractButton::display
+
+    This property determines how the \l icon and \l text are displayed within
+    the button.
+
+    \table
+    \header \li Display \li Result
+    \row \li \c AbstractButton.IconOnly \li \image qtquickcontrols2-button-icononly.png
+    \row \li \c AbstractButton.TextOnly \li \image qtquickcontrols2-button-textonly.png
+    \row \li \c AbstractButton.TextBesideIcon \li \image qtquickcontrols2-button-textbesideicon.png
+    \endtable
+
+    \sa {Control::}{spacing}, {Control::}{padding}
+*/
+QQuickAbstractButton::Display QQuickAbstractButton::display() const
+{
+    Q_D(const QQuickAbstractButton);
+    return d->display;
+}
+
+void QQuickAbstractButton::setDisplay(Display display)
+{
+    Q_D(QQuickAbstractButton);
+    if (display == d->display)
+        return;
+
+    d->display = display;
+    emit displayChanged();
+}
+
 QT_END_NAMESPACE
diff --git a/src/quicktemplates2/qquickabstractbutton_p.h b/src/quicktemplates2/qquickabstractbutton_p.h
index 42af6650..e6041e28 100644
--- a/src/quicktemplates2/qquickabstractbutton_p.h
+++ b/src/quicktemplates2/qquickabstractbutton_p.h
@@ -67,6 +67,7 @@ class Q_QUICKTEMPLATES2_PRIVATE_EXPORT QQuickAbstractButton : public QQuickContr
     Q_PROPERTY(bool autoExclusive READ autoExclusive WRITE setAutoExclusive NOTIFY autoExclusiveChanged FINAL)
     Q_PROPERTY(QQuickItem *indicator READ indicator WRITE setIndicator NOTIFY indicatorChanged FINAL)
     Q_PROPERTY(QQuickIcon *icon READ icon CONSTANT FINAL REVISION 3)
+    Q_PROPERTY(Display display READ display WRITE setDisplay NOTIFY displayChanged REVISION 3)
 
 public:
     explicit QQuickAbstractButton(QQuickItem *parent = nullptr);
@@ -99,6 +100,17 @@ public:
 
     QQuickIcon *icon() const;
 
+    enum Display {
+        IconOnly,
+        TextOnly,
+        TextBesideIcon,
+        TextUnderIcon // unused, but reserved for future use
+    };
+    Q_ENUM(Display)
+
+    Display display() const;
+    void setDisplay(Display display);
+
 public Q_SLOTS:
     void toggle();
 
@@ -117,6 +129,7 @@ Q_SIGNALS:
     void checkableChanged();
     void autoExclusiveChanged();
     void indicatorChanged();
+    Q_REVISION(3) void displayChanged();
 
 protected:
     QQuickAbstractButton(QQuickAbstractButtonPrivate &dd, QQuickItem *parent);
diff --git a/src/quicktemplates2/qquickabstractbutton_p_p.h b/src/quicktemplates2/qquickabstractbutton_p_p.h
index 388e5517..4864356b 100644
--- a/src/quicktemplates2/qquickabstractbutton_p_p.h
+++ b/src/quicktemplates2/qquickabstractbutton_p_p.h
@@ -105,6 +105,7 @@ public:
     QQuickItem *indicator;
     QQuickButtonGroup *group;
     QQuickIcon *icon;
+    QQuickAbstractButton::Display display;
 };
 
 QT_END_NAMESPACE
diff --git a/tests/auto/controls/data/tst_button.qml b/tests/auto/controls/data/tst_button.qml
index e3081354..d0f8bbf3 100644
--- a/tests/auto/controls/data/tst_button.qml
+++ b/tests/auto/controls/data/tst_button.qml
@@ -50,7 +50,7 @@
 
 import QtQuick 2.2
 import QtTest 1.0
-import QtQuick.Controls 2.2
+import QtQuick.Controls 2.3
 
 TestCase {
     id: testCase
@@ -448,4 +448,54 @@ TestCase {
         // The implicitWidth of the Button itself should, therefore, also never include spacing while no icon is set.
         compare(control.implicitWidth, control.contentItem.text.implicitWidth + control.leftPadding + control.rightPadding)
     }
+
+    function test_display_data() {
+        return [
+            { "tag": "IconOnly", display: Button.IconOnly },
+            { "tag": "TextOnly", display: Button.TextOnly },
+            { "tag": "TextBesideIcon", display: Button.TextBesideIcon },
+            { "tag": "IconOnly, mirrored", display: Button.IconOnly, mirrored: true },
+            { "tag": "TextOnly, mirrored", display: Button.TextOnly, mirrored: true },
+            { "tag": "TextBesideIcon, mirrored", display: Button.TextBesideIcon, mirrored: true }
+        ]
+    }
+
+    function test_display(data) {
+        var control = createTemporaryObject(button, testCase, {
+            text: "Button",
+            display: data.display,
+            "icon.source": "qrc:/qt-project.org/imports/QtQuick/Controls.2/images/check.png",
+            "LayoutMirroring.enabled": !!data.mirrored
+        })
+        verify(control)
+        verify(control.icon.source.length > 0)
+
+        var iconImage = control.contentItem.icon
+        verify(iconImage)
+        verify(iconImage.hasOwnProperty("name"))
+        var text = control.contentItem.text
+        verify(text)
+        verify(text.hasOwnProperty("text"))
+
+        switch (control.display) {
+        case Button.IconOnly:
+            compare(iconImage.visible, true)
+            compare(text.visible, false)
+            compare(iconImage.x, (control.availableWidth - iconImage.width) / 2)
+            break;
+        case Button.TextOnly:
+            compare(iconImage.visible, false)
+            compare(text.visible, true)
+            compare(text.x, (control.availableWidth - text.width) / 2)
+            break;
+        case Button.TextBesideIcon:
+            compare(iconImage.visible, true)
+            compare(text.visible, true)
+            if (control.mirrored)
+                verify(text.x < iconImage.x)
+            else
+                verify(iconImage.x < text.x)
+            break;
+        }
+    }
 }