From 9f461353b37c3404191e557291a7f9a390190010 Mon Sep 17 00:00:00 2001
From: Mitch Curtis <mitch.curtis@qt.io>
Date: Tue, 31 Jan 2017 12:24:57 +0100
Subject: Doc: add missing information to "Attached properties" section
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A lot of details were left out, which makes it hard to follow along.

Task-number: QTBUG-56013
Change-Id: Ia21dd43e0d6e260463a2a91b28c248b962dd3401
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Reviewed-by: J-P Nurmi <jpnurmi@qt.io>
---
 .../doc/src/qtquickcontrols2-customize.qdoc        | 76 +++++++++++++++++-----
 1 file changed, 61 insertions(+), 15 deletions(-)

(limited to 'src/imports/controls/doc/src')

diff --git a/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc
index 487c5d6f..e86a6707 100644
--- a/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc
+++ b/src/imports/controls/doc/src/qtquickcontrols2-customize.qdoc
@@ -200,9 +200,11 @@
     style will illustrate the elevation with a drop shadow; the higher the
     elevation, the larger the shadow.
 
-    The first step is to add a C++ type that stores the elevation. Since the
-    type will be used for every control supported by our style, and because we
-    may wish to add other attached properties later on, we'll call it
+    The first step is to \l {Creating Qt Quick Projects}{create a new Qt Quick
+    Controls 2 application} in Qt Creator. After that, we
+    \l {Creating C++ Classes}{add a C++ type} that stores the elevation. Since
+    the type will be used for every control supported by our style, and because
+    we may wish to add other attached properties later on, we'll call it
     MyStyle. Here is \c MyStyle.h:
 
     \code
@@ -270,24 +272,45 @@
 
     The \c MyStyle type is special in the sense that it shouldn't be
     instantiated, but rather used for its attached properties. For that reason,
-    we register it in the following manner:
+    we register it in the following manner in \c main.cpp:
 
     \code
-    qmlRegisterUncreatableType<MyStyle>("MyStyle", 1, 0, "MyStyle", "MyStyle is an attached property");
+    #include <QGuiApplication>
+    #include <QQmlApplicationEngine>
+
+    #include "mystyle.h"
+
+    int main(int argc, char *argv[])
+    {
+        QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling);
+        QGuiApplication app(argc, argv);
+
+        qmlRegisterUncreatableType<MyStyle>("MyStyle", 1, 0, "MyStyle", "MyStyle is an attached property");
+
+        QQmlApplicationEngine engine;
+        engine.load(QUrl(QLatin1String("qrc:/main.qml")));
+
+        return app.exec();
+    }
     \endcode
 
-    We then copy the existing default Button style, and add the code for a drop
-    shadow (which was taken from the Material Button style). We modify that
-    slightly to ensure that we:
+    We then copy \c Button.qml from the Default style in
+    \c {$QTDIR/qml/QtQuick/Controls.2/} into a new \c myproject folder in our
+    project directory. Add the newly copied \c Button.qml to \c qml.qrc, which is
+    the resource file that contains our QML files.
 
-    \list
-    \li Don't bother using the drop shadow when the elevation is \c 0
-    \li Change the shadow's color depending on whether or not the button has
-        focus
-    \li Make the size of the shadow depend on the elevation
-    \endlist
+    Next, we add a drop shadow to the \l {Control::}{background} delegate of
+    the Button:
 
     \code
+    // ...
+    import QtGraphicalEffects 1.0
+    import MyStyle 1.0
+    // ...
+
+    background: Rectangle {
+        // ...
+
         layer.enabled: control.enabled && control.MyStyle.elevation > 0
         layer.effect: DropShadow {
             verticalOffset: 1
@@ -295,9 +318,20 @@
             samples: control.MyStyle.elevation
             spread: 0.5
         }
+    }
     \endcode
 
-    With that in place, we can try out our new elevation feature:
+    Note that we:
+
+    \list
+    \li Don't bother using the drop shadow when the elevation is \c 0
+    \li Change the shadow's color depending on whether or not the button has
+        focus
+    \li Make the size of the shadow depend on the elevation
+    \endlist
+
+    To try out the attached property, we create a \l Row with two Buttons in
+    \c main.qml:
 
     \qml
     import QtQuick 2.6
@@ -326,10 +360,22 @@
     }
     \endqml
 
+    One button has no elevation, and the other has an elevation of \c 10.
+
+    With that in place, we can run our example. To tell the application to
+    use our new style, we pass \c {-style :/mystyle} as an application
+    argument, but there are \l {Using Styles in Qt Quick Controls 2}{many
+    ways} to specify the style to use.
+
     The end result:
 
     \image qtquickcontrols2-customize-buttons.png
 
+    Note that the \c {import MyStyle 1.0} statement is only necessary
+    because we are using the attached property belonging to \c MyStyle.
+    Both buttons will use our custom style, even if we were to remove the
+    import.
+
     \section1 Customization Reference
 
     The following snippets present examples where the default style's controls
-- 
cgit v1.2.3