|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). |
|
4 ** All rights reserved. |
|
5 ** Contact: Nokia Corporation (qt-info@nokia.com) |
|
6 ** |
|
7 ** This file is part of the documentation of the Qt Toolkit. |
|
8 ** |
|
9 ** $QT_BEGIN_LICENSE:LGPL$ |
|
10 ** No Commercial Usage |
|
11 ** This file contains pre-release code and may not be distributed. |
|
12 ** You may use this file in accordance with the terms and conditions |
|
13 ** contained in the Technology Preview License Agreement accompanying |
|
14 ** this package. |
|
15 ** |
|
16 ** GNU Lesser General Public License Usage |
|
17 ** Alternatively, this file may be used under the terms of the GNU Lesser |
|
18 ** General Public License version 2.1 as published by the Free Software |
|
19 ** Foundation and appearing in the file LICENSE.LGPL included in the |
|
20 ** packaging of this file. Please review the following information to |
|
21 ** ensure the GNU Lesser General Public License version 2.1 requirements |
|
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
|
23 ** |
|
24 ** In addition, as a special exception, Nokia gives you certain additional |
|
25 ** rights. These rights are described in the Nokia Qt LGPL Exception |
|
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
|
27 ** |
|
28 ** If you have questions regarding the use of this file, please contact |
|
29 ** Nokia at qt-info@nokia.com. |
|
30 ** |
|
31 ** |
|
32 ** |
|
33 ** |
|
34 ** |
|
35 ** |
|
36 ** |
|
37 ** |
|
38 ** $QT_END_LICENSE$ |
|
39 ** |
|
40 ****************************************************************************/ |
|
41 |
|
42 /*! |
|
43 \example widgets/sliders |
|
44 \title Sliders Example |
|
45 |
|
46 Qt provides three types of slider-like widgets: QSlider, |
|
47 QScrollBar and QDial. They all inherit most of their |
|
48 functionality from QAbstractSlider, and can in theory replace |
|
49 each other in an application since the differences only concern |
|
50 their look and feel. This example shows what they look like, how |
|
51 they work and how their behavior and appearance can be |
|
52 manipulated through their properties. |
|
53 |
|
54 The example also demonstrates how signals and slots can be used to |
|
55 synchronize the behavior of two or more widgets. |
|
56 |
|
57 \image sliders-example.png Screenshot of the Sliders example |
|
58 |
|
59 The Sliders example consists of two classes: |
|
60 |
|
61 \list |
|
62 |
|
63 \o \c SlidersGroup is a custom widget. It combines a QSlider, a |
|
64 QScrollBar and a QDial. |
|
65 |
|
66 \o \c Window is the main widget combining a QGroupBox and a |
|
67 QStackedWidget. In this example, the QStackedWidget provides a |
|
68 stack of two \c SlidersGroup widgets. The QGroupBox contain |
|
69 several widgets that control the behavior of the slider-like |
|
70 widgets. |
|
71 |
|
72 \endlist |
|
73 |
|
74 First we will review the \c Window class, then we |
|
75 will take a look at the \c SlidersGroup class. |
|
76 |
|
77 \section1 Window Class Definition |
|
78 |
|
79 \snippet examples/widgets/sliders/window.h 0 |
|
80 |
|
81 The \c Window class inherits from QWidget. It displays the slider |
|
82 widgets and allows the user to set their minimum, maximum and |
|
83 current values and to customize their appearance, key bindings |
|
84 and orientation. We use a private \c createControls() function to |
|
85 create the widgets that provide these controlling mechanisms and |
|
86 to connect them to the slider widgets. |
|
87 |
|
88 \section1 Window Class Implementation |
|
89 |
|
90 \snippet examples/widgets/sliders/window.cpp 0 |
|
91 |
|
92 In the constructor we first create the two \c SlidersGroup |
|
93 widgets that display the slider widgets horizontally and |
|
94 vertically, and add them to the QStackedWidget. QStackedWidget |
|
95 provides a stack of widgets where only the top widget is visible. |
|
96 With \c createControls() we create a connection from a |
|
97 controlling widget to the QStackedWidget, making the user able to |
|
98 choose between horizontal and vertical orientation of the slider |
|
99 widgets. The rest of the controlling mechanisms is implemented by |
|
100 the same function call. |
|
101 |
|
102 \snippet examples/widgets/sliders/window.cpp 1 |
|
103 \snippet examples/widgets/sliders/window.cpp 2 |
|
104 |
|
105 Then we connect the \c horizontalSliders, \c verticalSliders and |
|
106 \c valueSpinBox to each other, so that the slider widgets and the |
|
107 control widget will behave synchronized when the current value of |
|
108 one of them changes. The \c valueChanged() signal is emitted with |
|
109 the new value as argument. The \c setValue() slot sets the |
|
110 current value of the widget to the new value, and emits \c |
|
111 valueChanged() if the new value is different from the old one. |
|
112 |
|
113 We put the group of control widgets and the stacked widget in a |
|
114 horizontal layout before we initialize the minimum, maximum and |
|
115 current values. The initialization of the current value will |
|
116 propagate to the slider widgets through the connection we made |
|
117 between \c valueSpinBox and the \c SlidersGroup widgets. The |
|
118 minimum and maximum values propagate through the connections we |
|
119 created with \c createControls(). |
|
120 |
|
121 \snippet examples/widgets/sliders/window.cpp 3 |
|
122 \snippet examples/widgets/sliders/window.cpp 4 |
|
123 |
|
124 In the private \c createControls() function, we let a QGroupBox |
|
125 (\c controlsGroup) display the control widgets. A group box can |
|
126 provide a frame, a title and a keyboard shortcut, and displays |
|
127 various other widgets inside itself. The group of control widgets |
|
128 is composed by two checkboxes, three spin boxes (with labels) and |
|
129 one combobox. |
|
130 |
|
131 After creating the labels, we create the two checkboxes. |
|
132 Checkboxes are typically used to represent features in an |
|
133 application that can be enabled or disabled. When \c |
|
134 invertedAppearance is enabled, the slider values are inverted. |
|
135 The table below shows the appearance for the different |
|
136 slider-like widgets: |
|
137 |
|
138 \table |
|
139 \header \o \o{2,1} QSlider \o{2,1} QScrollBar \o{2,1} QDial |
|
140 \header \o \o Normal \o Inverted \o Normal \o Inverted \o Normal \o Inverted |
|
141 \row \o Qt::Horizontal \o Left to right \o Right to left \o Left to right \o Right to left \o Clockwise \o Counterclockwise |
|
142 \row \o Qt::Vertical \o Bottom to top \o Top to bottom \o Top to bottom \o Bottom to top \o Clockwise \o Counterclockwise |
|
143 \endtable |
|
144 |
|
145 It is common to invert the appearance of a vertical QSlider. A |
|
146 vertical slider that controls volume, for example, will typically |
|
147 go from bottom to top (the non-inverted appearance), whereas a |
|
148 vertical slider that controls the position of an object on screen |
|
149 might go from top to bottom, because screen coordinates go from |
|
150 top to bottom. |
|
151 |
|
152 When the \c invertedKeyBindings option is enabled (corresponding |
|
153 to the QAbstractSlider::invertedControls property), the slider's |
|
154 wheel and key events are inverted. The normal key bindings mean |
|
155 that scrolling the mouse wheel "up" or using keys like page up |
|
156 will increase the slider's current value towards its maximum. |
|
157 Inverted, the same wheel and key events will move the value |
|
158 toward the slider's minimum. This can be useful if the \e |
|
159 appearance of a slider is inverted: Some users might expect the |
|
160 keys to still work the same way on the value, whereas others |
|
161 might expect \key PageUp to mean "up" on the screen. |
|
162 |
|
163 Note that for horizontal and vertical scroll bars, the key |
|
164 bindings are inverted by default: \key PageDown increases the |
|
165 current value, and \key PageUp decreases it. |
|
166 |
|
167 \snippet examples/widgets/sliders/window.cpp 5 |
|
168 \snippet examples/widgets/sliders/window.cpp 6 |
|
169 |
|
170 Then we create the spin boxes. QSpinBox allows the user to choose |
|
171 a value by clicking the up and down buttons or pressing the \key |
|
172 Up and \key Down keys on the keyboard to modify the value |
|
173 currently displayed. The user can also type in the value |
|
174 manually. The spin boxes control the minimum, maximum and current |
|
175 values for the QSlider, QScrollBar, and QDial widgets. |
|
176 |
|
177 We create a QComboBox that allows the user to choose the |
|
178 orientation of the slider widgets. The QComboBox widget is a |
|
179 combined button and popup list. It provides a means of presenting |
|
180 a list of options to the user in a way that takes up the minimum |
|
181 amount of screen space. |
|
182 |
|
183 \snippet examples/widgets/sliders/window.cpp 7 |
|
184 \snippet examples/widgets/sliders/window.cpp 8 |
|
185 |
|
186 We synchronize the behavior of the control widgets and the slider |
|
187 widgets through their signals and slots. We connect each control |
|
188 widget to both the horizontal and vertical group of slider |
|
189 widgets. We also connect \c orientationCombo to the |
|
190 QStackedWidget, so that the correct "page" is shown. Finally, we |
|
191 lay out the control widgets in a QGridLayout within the \c |
|
192 controlsGroup group box. |
|
193 |
|
194 \section1 SlidersGroup Class Definition |
|
195 |
|
196 \snippet examples/widgets/sliders/slidersgroup.h 0 |
|
197 |
|
198 The \c SlidersGroup class inherits from QGroupBox. It provides a |
|
199 frame and a title, and contains a QSlider, a QScrollBar and a |
|
200 QDial. |
|
201 |
|
202 We provide a \c valueChanged() signal and a public \c setValue() |
|
203 slot with equivalent functionality to the ones in QAbstractSlider |
|
204 and QSpinBox. In addition, we implement several other public |
|
205 slots to set the minimum and maximum value, and invert the slider |
|
206 widgets' appearance as well as key bindings. |
|
207 |
|
208 \section1 SlidersGroup Class Implementation |
|
209 |
|
210 \snippet examples/widgets/sliders/slidersgroup.cpp 0 |
|
211 |
|
212 First we create the slider-like widgets with the appropiate |
|
213 properties. In particular we set the focus policy for each |
|
214 widget. Qt::FocusPolicy is an enum type that defines the various |
|
215 policies a widget can have with respect to acquiring keyboard |
|
216 focus. The Qt::StrongFocus policy means that the widget accepts |
|
217 focus by both tabbing and clicking. |
|
218 |
|
219 Then we connect the widgets with each other, so that they will |
|
220 stay synchronized when the current value of one of them changes. |
|
221 |
|
222 \snippet examples/widgets/sliders/slidersgroup.cpp 1 |
|
223 \snippet examples/widgets/sliders/slidersgroup.cpp 2 |
|
224 |
|
225 We connect \c {dial}'s \c valueChanged() signal to the |
|
226 \c{SlidersGroup}'s \c valueChanged() signal, to notify the other |
|
227 widgets in the application (i.e., the control widgets) of the |
|
228 changed value. |
|
229 |
|
230 \snippet examples/widgets/sliders/slidersgroup.cpp 3 |
|
231 \codeline |
|
232 \snippet examples/widgets/sliders/slidersgroup.cpp 4 |
|
233 |
|
234 Finally, depending on the \l {Qt::Orientation}{orientation} given |
|
235 at the time of construction, we choose and create the layout for |
|
236 the slider widgets within the group box. |
|
237 |
|
238 \snippet examples/widgets/sliders/slidersgroup.cpp 5 |
|
239 \snippet examples/widgets/sliders/slidersgroup.cpp 6 |
|
240 |
|
241 The \c setValue() slot sets the value of the QSlider. We don't |
|
242 need to explicitly call |
|
243 \l{QAbstractSlider::setValue()}{setValue()} on the QScrollBar and |
|
244 QDial widgets, since QSlider will emit the |
|
245 \l{QAbstractSlider::valueChanged()}{valueChanged()} signal when |
|
246 its value changes, triggering a domino effect. |
|
247 |
|
248 \snippet examples/widgets/sliders/slidersgroup.cpp 7 |
|
249 \snippet examples/widgets/sliders/slidersgroup.cpp 8 |
|
250 \codeline |
|
251 \snippet examples/widgets/sliders/slidersgroup.cpp 9 |
|
252 \snippet examples/widgets/sliders/slidersgroup.cpp 10 |
|
253 |
|
254 The \c setMinimum() and \c setMaximum() slots are used by the \c |
|
255 Window class to set the range of the QSlider, QScrollBar, and |
|
256 QDial widgets. |
|
257 |
|
258 \snippet examples/widgets/sliders/slidersgroup.cpp 11 |
|
259 \snippet examples/widgets/sliders/slidersgroup.cpp 12 |
|
260 \codeline |
|
261 \snippet examples/widgets/sliders/slidersgroup.cpp 13 |
|
262 \snippet examples/widgets/sliders/slidersgroup.cpp 14 |
|
263 |
|
264 The \c invertAppearance() and \c invertKeyBindings() slots |
|
265 control the child widgets' |
|
266 \l{QAbstractSlider::invertedAppearance}{invertedAppearance} and |
|
267 \l{QAbstractSlider::invertedControls}{invertedControls} |
|
268 properties. |
|
269 */ |