Material: add snippets and screenshots for attached properties

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

12 files changed, 279 insertions, 25 deletions

diff --git a/src/imports/controls/doc/images/qtquickcontrols2-material-accent.png b/src/imports/controls/doc/images/qtquickcontrols2-material-accent.png
new file mode 100644
index 00000000..be0c8212
--- /dev/null
+++ b/src/imports/controls/doc/images/qtquickcontrols2-material-accent.png
diff --git a/src/imports/controls/doc/images/qtquickcontrols2-material-background.png b/src/imports/controls/doc/images/qtquickcontrols2-material-background.png
new file mode 100644
index 00000000..132fb538
--- /dev/null
+++ b/src/imports/controls/doc/images/qtquickcontrols2-material-background.png
diff --git a/src/imports/controls/doc/images/qtquickcontrols2-material-button.png b/src/imports/controls/doc/images/qtquickcontrols2-material-button.png
deleted file mode 100644
index 5181d8b1..00000000
--- a/src/imports/controls/doc/images/qtquickcontrols2-material-button.png
+++ /dev/null
diff --git a/src/imports/controls/doc/images/qtquickcontrols2-material-elevation.png b/src/imports/controls/doc/images/qtquickcontrols2-material-elevation.png
new file mode 100644
index 00000000..38c6dc00
--- /dev/null
+++ b/src/imports/controls/doc/images/qtquickcontrols2-material-elevation.png
diff --git a/src/imports/controls/doc/images/qtquickcontrols2-material-foreground.png b/src/imports/controls/doc/images/qtquickcontrols2-material-foreground.png
new file mode 100644
index 00000000..122f7f9b
--- /dev/null
+++ b/src/imports/controls/doc/images/qtquickcontrols2-material-foreground.png
diff --git a/src/imports/controls/doc/images/qtquickcontrols2-material-theme.png b/src/imports/controls/doc/images/qtquickcontrols2-material-theme.png
new file mode 100644
index 00000000..7109f57f
--- /dev/null
+++ b/src/imports/controls/doc/images/qtquickcontrols2-material-theme.png
diff --git a/src/imports/controls/doc/snippets/qtquickcontrols2-material-accent.qml b/src/imports/controls/doc/snippets/qtquickcontrols2-material-accent.qml
new file mode 100644
index 00000000..5238d876
--- /dev/null
+++ b/src/imports/controls/doc/snippets/qtquickcontrols2-material-accent.qml
@@ -0,0 +1,43 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 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.0
+import QtQuick.Layouts 1.0
+import QtQuick.Controls 2.0
+import QtQuick.Controls.Material 2.0
+
+Pane {
+    padding: 4
+
+//! [1]
+Button {
+    text: qsTr("Button")
+    highlighted: true
+    Material.accent: Material.Orange
+}
+//! [1]
+}
diff --git a/src/imports/controls/doc/snippets/qtquickcontrols2-material-background.qml b/src/imports/controls/doc/snippets/qtquickcontrols2-material-background.qml
new file mode 100644
index 00000000..264d5d28
--- /dev/null
+++ b/src/imports/controls/doc/snippets/qtquickcontrols2-material-background.qml
@@ -0,0 +1,42 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 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.0
+import QtQuick.Controls 2.0
+import QtQuick.Controls.Material 2.0
+
+Pane {
+    padding: 4
+
+//! [1]
+Button {
+    text: qsTr("Button")
+    highlighted: true
+    Material.background: Material.Teal
+}
+//! [1]
+}
diff --git a/src/imports/controls/doc/snippets/qtquickcontrols2-material-elevation.qml b/src/imports/controls/doc/snippets/qtquickcontrols2-material-elevation.qml
new file mode 100644
index 00000000..3ce1a722
--- /dev/null
+++ b/src/imports/controls/doc/snippets/qtquickcontrols2-material-elevation.qml
@@ -0,0 +1,51 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 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.0
+import QtQuick.Controls 2.0
+import QtQuick.Controls.Material 2.0
+
+Pane {
+    contentWidth: 120
+    contentHeight: 120
+    padding: 10
+    bottomPadding: 20
+
+//! [1]
+Pane {
+    width: 120
+    height: 120
+
+    Material.elevation: 6
+
+    Label {
+        text: qsTr("I'm a card!")
+        anchors.centerIn: parent
+    }
+}
+//! [1]
+}
diff --git a/src/imports/controls/doc/snippets/qtquickcontrols2-material-foreground.qml b/src/imports/controls/doc/snippets/qtquickcontrols2-material-foreground.qml
new file mode 100644
index 00000000..1fe96121
--- /dev/null
+++ b/src/imports/controls/doc/snippets/qtquickcontrols2-material-foreground.qml
@@ -0,0 +1,41 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 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.0
+import QtQuick.Controls 2.0
+import QtQuick.Controls.Material 2.0
+
+Pane {
+    padding: 4
+
+//! [1]
+Button {
+    text: qsTr("Button")
+    Material.foreground: Material.Pink
+}
+//! [1]
+}
diff --git a/src/imports/controls/doc/snippets/qtquickcontrols2-material-theme.qml b/src/imports/controls/doc/snippets/qtquickcontrols2-material-theme.qml
new file mode 100644
index 00000000..6bd91d5d
--- /dev/null
+++ b/src/imports/controls/doc/snippets/qtquickcontrols2-material-theme.qml
@@ -0,0 +1,44 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 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.0
+import QtQuick.Controls 2.0
+import QtQuick.Controls.Material 2.0
+
+Pane {
+    padding: 10
+
+//! [1]
+Pane {
+    Material.theme: Material.Dark
+
+    Button {
+        text: qsTr("Button")
+    }
+}
+//! [1]
+}
diff --git a/src/imports/controls/doc/src/qtquickcontrols2-material.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-material.qdoc
index a90581ec..3ff9f5ea 100644
--- a/src/imports/controls/doc/src/qtquickcontrols2-material.qdoc
+++ b/src/imports/controls/doc/src/qtquickcontrols2-material.qdoc
@@ -79,28 +79,6 @@
 
     \image qtquickcontrols2-material-attributes.png
 
-    The following example illustrates how to create a red \e stop button with light text:
-
-    \table
-        \row
-            \li
-                \qml
-                import QtQuick 2.0
-                import QtQuick.Controls 2.0
-                import QtQuick.Controls.Material 2.0
-
-                Button {
-                    text: "Stop"
-                    highlighted: true
-
-                    Material.accent: Material.Red
-                    Material.theme: Material.Dark
-                }
-                \endqml
-            \li
-                \image qtquickcontrols2-material-button.png
-    \endtable
-
     All attributes can be specified for any window or item, and they automatically
     propagate to children in the same manner as \l {Control::font}{fonts}. In the
     following example, the window and all three radio buttons appear in the dark
@@ -261,6 +239,17 @@
     This attached property holds the accent color of the theme. The property
     can be attached to any window or item. The value is propagated to children.
 
+    In the following example, the accent color of the highlighted button is
+    changed to \c Material.Orange:
+
+    \table
+        \row
+            \li
+                \snippet qtquickcontrols2-material-accent.qml 1
+            \li
+                \image qtquickcontrols2-material-accent.png
+    \endtable
+
     The default value is \c Material.Pink.
 
     \note Even though the accent can be any \l {colorbasictypedocs}{color}, it is
@@ -276,6 +265,17 @@
 
     The default value is theme-specific (light or dark).
 
+    In the following example, the background color of the button is changed to
+    \c Material.Teal:
+
+    \table
+        \row
+            \li
+                \snippet qtquickcontrols2-material-background.qml 1
+            \li
+                \image qtquickcontrols2-material-background.png
+    \endtable
+
     \endstyleproperty
 
     \styleproperty {Material.elevation} {int} {material-elevation-attached-prop}
@@ -286,6 +286,18 @@
 
     The default value is control-specific.
 
+    In the following example, the elevation of the pane is set to \c 6
+    in order to achieve the look of an
+    \l {https://material.google.com/components/cards.html}{elevated card}:
+
+    \table
+        \row
+            \li
+                \snippet qtquickcontrols2-material-elevation.qml 1
+            \li
+                \image qtquickcontrols2-material-elevation.png
+    \endtable
+
     \endstyleproperty
 
     \styleproperty {Material.foreground} {color} {material-foreground-attached-prop}
@@ -295,6 +307,17 @@
 
     The default value is theme-specific (light or dark).
 
+    In the following example, the foreground color of the button is set to \c
+    Material.Brown:
+
+    \table
+        \row
+            \li
+                \snippet qtquickcontrols2-material-foreground.qml 1
+            \li
+                \image qtquickcontrols2-material-foreground.png
+    \endtable
+
     \endstyleproperty
 
     \styleproperty {Material.primary} {color} {material-primary-attached-prop}
@@ -302,6 +325,8 @@
     This attached property holds the primary color of the theme. The property
     can be attached to any window or item. The value is propagated to children.
 
+    The primary color is used as the background color of ToolBar by default.
+
     The default value is \c Material.Indigo.
 
     \note Even though the primary can be any \l {colorbasictypedocs}{color}, it is
@@ -319,6 +344,17 @@
     \value Material.Light Light theme (default)
     \value Material.Dark Dark theme
 
+    In the following example, the theme for both the pane and the button is set
+    to \c Material.Dark:
+
+    \table
+        \row
+            \li
+                \snippet qtquickcontrols2-material-theme.qml 1
+            \li
+                \image qtquickcontrols2-material-theme.png
+    \endtable
+
     \endstyleproperty
 
     \section1 Attached Method Documentation
@@ -331,9 +367,6 @@
     defaults to \c Material.Shade500.
 
     \qml
-    import QtQuick 2.0
-    import QtQuick.Controls.Material 2.0
-
     Rectangle {
         color: Material.color(Material.Red)
     }