Import Qt Quick Extras (the former Qt Quick Enterprise Controls)

Change-Id: I59c5c97c564f707da4ce617e25e13ff8124f7d4b
Reviewed-by: J-P Nurmi <jpnurmi@theqtcompany.com>

1 files changed, 145 insertions, 0 deletions

diff --git a/src/extras/doc/src/styling-circulargauge.qdoc b/src/extras/doc/src/styling-circulargauge.qdoc
new file mode 100644
index 00000000..9cf94087
--- /dev/null
+++ b/src/extras/doc/src/styling-circulargauge.qdoc
@@ -0,0 +1,145 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 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$
+**
+****************************************************************************/
+
+/*!
+    \page styling-circulargauge.html
+    \title Styling CircularGauge
+    \brief Tutorial for styling CircularGauge.
+    \ingroup extrasstyling
+
+    \target styling-circulargauge-needle
+    \section2 The Needle Component
+
+    The \l {QtQuick.Extras.Styles::CircularGaugeStyle::}{needle}
+    component is rotated around the gauge to represent the current value.
+
+    Starting from the default style, we'll add a very basic white needle:
+
+    \snippet circulargauge-background-range.qml needle
+
+    \image styling-circulargauge-needle-example.png
+
+    As mentioned in the documentation for \l {QtQuick.Extras.Styles::}
+    {CircularGaugeStyle}, \c implicitWidth
+    and \c implicitHeight properties need to be set. This is so that the needle
+    can be positioned properly. We always scale items by the
+    \l {QtQuick.Extras.Styles::CircularGaugeStyle::}{outerRadius}
+    property of the style, ensuring the control resizes gracefully.
+
+    We offset the needle vertically so that its back sits beyond the knob.
+
+    \target styling-circulargauge-foreground
+    \section2 The Foreground Component
+
+    We've now changed the needle, but the default knob is still there; let's
+    replace it. The \l {QtQuick.Extras.Styles::CircularGaugeStyle::}
+    {foreground} component defines the default knob, so we can specify our own by
+    overriding it (note that we could also set it to \c null if we didn't want a
+    foreground):
+
+    \snippet circulargauge-background-range.qml foreground
+
+    \image styling-circulargauge-knob-example.png
+
+    Firstly, we create a circle from the Rectangle item by setting the radius to
+    be half the width (either width or height will work here; they are always
+    equal in this case). We make it a child of the Item, because the foreground
+    fills the gauge. We then center it within the Item.
+
+    We set the color of the knob to the same white that we used before.
+
+    \target styling-circulargauge-tickmarkLabel
+    \section2 The Tickmark Label Component
+
+    Suppose we want to caution the user if the value displayed by the gauge goes
+    above or below a certain range. We could present this range to the user in
+    several ways:
+
+    \list A
+        \li Change the color of the tickmarks depending on \c styleData.value
+        \li Add an image to the background
+        \li Draw it with \l {QtQuick::}{Canvas}
+    \endlist
+
+    We'll choose options 1 and 3, as they are more flexible than using an
+    image.
+
+    Firstly, let's change the color of the three highest tickmark labels:
+
+    \snippet circulargauge-background-range.qml tickmarkLabel
+
+    \image styling-circulargauge-tickmarkLabel-example.png tickmarkLabel
+
+    We also change the color of the rest of the labels to the same white that
+    we used for the needle and knob.
+
+    \target styling-circulargauge-tickmark
+    \section2 The Tickmark Component
+
+    Now let's do the same for the three highest tickmarks:
+
+    \snippet circulargauge-background-range.qml tickmark
+
+    \image styling-circulargauge-tickmark-example.png tickmark
+
+    \target styling-circulargauge-minorTickmark
+    \section2 The Minor Tickmark Component
+
+    For the minor tickmarks, we'll only show those which are not higher than
+    \c 80:
+
+    \snippet circulargauge-background-range.qml minorTickmark
+
+    \image styling-circulargauge-minorTickmark-example.png minorTickmark
+
+    This is because we'll draw something between that range in the next section.
+
+    \target styling-circulargauge-background
+    \section2 The Background Component
+
+    We'll display the range that indicates caution with an orange arc:
+
+    \snippet circulargauge-background-range.qml background
+
+    We define a function to convert degrees to radians, which are the
+    units used by \l {QtQuick::}{Canvas}.
+
+    Next, we do the drawing of the range using Canvas. We draw an arc between
+    \c 80 and \c 100, using the
+    \l {QtQuick.Extras.Styles::CircularGaugeStyle::}{valueToAngle()}
+    function provided by CircularGaugeStyle. Note that we subtract \c 90 degrees
+    before converting to radians, as our origin is north and Canvas' is east.
+
+    The finished product:
+
+    \image styling-circulargauge-background-example.png background
+
+    The complete code for this example is as follows:
+
+    \snippet circulargauge-background-range.qml range
+*/
+