source: trunk/doc/src/examples/spinboxes.qdoc@ 1168

Last change on this file since 1168 was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.

File size: 7.4 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
6**
7** This file is part of the documentation of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:FDL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in a
14** written agreement between you and Nokia.
15**
16** GNU Free Documentation License
17** Alternatively, this file may be used under the terms of the GNU Free
18** Documentation License version 1.3 as published by the Free Software
19** Foundation and appearing in the file included in the packaging of this
20** file.
21**
22** If you have questions regarding the use of this file, please contact
23** Nokia at [email protected].
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29 \example widgets/spinboxes
30 \title Spin Boxes Example
31
32 The Spin Boxes example shows how to use the many different types of spin boxes
33 available in Qt, from a simple QSpinBox widget to more complex editors like
34 the QDateTimeEdit widget.
35
36 \image spinboxes-example.png
37
38 The example consists of a single \c Window class that is used to display the
39 different spin box-based widgets available with Qt.
40
41 \section1 Window Class Definition
42
43 The \c Window class inherits QWidget and contains two slots that are used
44 to provide interactive features:
45
46 \snippet examples/widgets/spinboxes/window.h 0
47
48 The private functions are used to set up each type of spin box in the window.
49 We use member variables to keep track of various widgets so that they can
50 be reconfigured when required.
51
52 \section1 Window Class Implementation
53
54 The constructor simply calls private functions to set up the different types
55 of spin box used in the example, and places each group in a layout:
56
57 \snippet examples/widgets/spinboxes/window.cpp 0
58
59 We use the layout to manage the arrangement of the window's child widgets,
60 and change the window title.
61
62 The \c createSpinBoxes() function constructs a QGroupBox and places three
63 QSpinBox widgets inside it with descriptive labels to indicate the types of
64 input they expect.
65
66 \snippet examples/widgets/spinboxes/window.cpp 1
67
68 The first spin box shows the simplest way to use QSpinBox. It accepts values
69 from -20 to 20, the current value can be increased or decreased by 1 with
70 either the arrow buttons or \key{Up} and \key{Down} keys, and the default
71 value is 0.
72
73 The second spin box uses a larger step size and displays a suffix to
74 provide more information about the type of data the number represents:
75
76 \snippet examples/widgets/spinboxes/window.cpp 2
77
78 This spin box also displays a
79 \l{QAbstractSpinBox::specialValueText}{special value} instead of the minimum
80 value defined for it. This means that it will never show \gui{0%}, but will
81 display \gui{Automatic} when the minimum value is selected.
82
83 The third spin box shows how a prefix can be used:
84
85 \snippet examples/widgets/spinboxes/window.cpp 4
86
87 For simplicity, we show a spin box with a prefix and no suffix. It is also
88 possible to use both at the same time.
89
90 \snippet examples/widgets/spinboxes/window.cpp 5
91
92 The rest of the function sets up a layout for the group box and places each
93 of the widgets inside it.
94
95 The \c createDateTimeEdits() function constructs another group box with a
96 selection of spin boxes used for editing dates and times.
97
98 \snippet examples/widgets/spinboxes/window.cpp 6
99
100 The first spin box is a QDateEdit widget that is able to accept dates
101 within a given range specified using QDate values. The arrow buttons and
102 \key{Up} and \key{Down} keys can be used to increase and decrease the
103 values for year, month, and day when the cursor is in the relevant section.
104
105 The second spin box is a QTimeEdit widget:
106
107 \snippet examples/widgets/spinboxes/window.cpp 7
108
109 Acceptable values for the time are defined using QTime values.
110
111 The third spin box is a QDateTimeEdit widget that can display both date and
112 time values, and we place a label above it to indicate the range of allowed
113 times for a meeting. These widgets will be updated when the user changes a
114 format string.
115
116 \snippet examples/widgets/spinboxes/window.cpp 8
117
118 The format string used for the date time editor, which is also shown in the
119 string displayed by the label, is chosen from a set of strings in a combobox:
120
121 \snippet examples/widgets/spinboxes/window.cpp 9
122 \codeline
123 \snippet examples/widgets/spinboxes/window.cpp 10
124
125 A signal from this combobox is connected to a slot in the \c Window class
126 (shown later).
127
128 \snippet examples/widgets/spinboxes/window.cpp 11
129
130 Each child widget of the group box in placed in a layout.
131
132 The \c setFormatString() slot is called whenever the user selects a new
133 format string in the combobox. The display format for the QDateTimeEdit
134 widget is set using the raw string passed by the signal:
135
136 \snippet examples/widgets/spinboxes/window.cpp 12
137
138 Depending on the visible sections in the widget, we set a new date or time
139 range, and update the associated label to provide relevant information for
140 the user:
141
142 \snippet examples/widgets/spinboxes/window.cpp 13
143
144 When the format string is changed, there will be an appropriate label and
145 entry widget for dates, times, or both types of input.
146
147 The \c createDoubleSpinBoxes() function constructs three spin boxes that are
148 used to input double-precision floating point numbers:
149
150 \snippet examples/widgets/spinboxes/window.cpp 14
151
152 Before the QDoubleSpinBox widgets are constructed, we create a spin box to
153 control how many decimal places they show. By default, only two decimal places
154 are shown in the following spin boxes, each of which is the equivalent of a
155 spin box in the group created by the \c createSpinBoxes() function.
156
157 The first double spin box shows a basic double-precision spin box with the
158 same range, step size, and default value as the first spin box in the
159 \c createSpinBoxes() function:
160
161 \snippet examples/widgets/spinboxes/window.cpp 15
162
163 However, this spin box also allows non-integer values to be entered.
164
165 The second spin box displays a suffix and shows a special value instead
166 of the minimum value:
167
168 \snippet examples/widgets/spinboxes/window.cpp 16
169
170 The third spin box displays a prefix instead of a suffix:
171
172 \snippet examples/widgets/spinboxes/window.cpp 17
173
174 We connect the QSpinBox widget that specifies the precision to a slot in
175 the \c Window class.
176
177 \snippet examples/widgets/spinboxes/window.cpp 18
178
179 The rest of the function places each of the widgets into a layout for the
180 group box.
181
182 The \c changePrecision() slot is called when the user changes the value in
183 the precision spin box:
184
185 \snippet examples/widgets/spinboxes/window.cpp 19
186
187 This function simply uses the integer supplied by the signal to specify the
188 number of decimal places in each of the QDoubleSpinBox widgets. Each one
189 of these will be updated automatically when their
190 \l{QDoubleSpinBox::decimals}{decimals} property is changed.
191*/
Note: See TracBrowser for help on using the repository browser.