/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://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 https://www.qt.io/terms-conditions. For further
** information use the contact form at https://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: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page styling-circulargauge.html
    \title Styling CircularGauge
    \brief Tutorial for styling CircularGauge.
    \ingroup stylingtutorials

    \target styling-circulargauge-needle
    \section2 The Needle Component

    The \l {QtQuick.Controls.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.Controls.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.Controls.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.Controls.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.Controls.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
*/