1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
/****************************************************************************
**
** 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
*/
|
