summaryrefslogtreecommitdiffstats
path: root/doc/man/man3/tqdial.3qt
blob: b0a034afd3c4cc364128740a0e39ed7fc1b4e470 (plain)
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
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
'\" t
.TH QDial 3qt "2 February 2007" "Trolltech AS" \" -*- nroff -*-
.\" Copyright 1992-2007 Trolltech ASA.  All rights reserved.  See the
.\" license file included in the distribution for a complete license
.\" statement.
.\"
.ad l
.nh
.SH NAME
QDial \- Rounded range control (like a speedometer or potentiometer)
.SH SYNOPSIS
\fC#include <ntqdial.h>\fR
.PP
Inherits QWidget and QRangeControl.
.PP
.SS "Public Members"
.in +1c
.ti -1c
.BI "\fBQDial\fR ( QWidget * parent = 0, const char * name = 0, WFlags f = 0 )"
.br
.ti -1c
.BI "\fBQDial\fR ( int minValue, int maxValue, int pageStep, int value, QWidget * parent = 0, const char * name = 0 )"
.br
.ti -1c
.BI "\fB~QDial\fR ()"
.br
.ti -1c
.BI "bool \fBtracking\fR () const"
.br
.ti -1c
.BI "bool \fBwrapping\fR () const"
.br
.ti -1c
.BI "int \fBnotchSize\fR () const"
.br
.ti -1c
.BI "virtual void \fBsetNotchTarget\fR ( double )"
.br
.ti -1c
.BI "double \fBnotchTarget\fR () const"
.br
.ti -1c
.BI "bool \fBnotchesVisible\fR () const"
.br
.ti -1c
.BI "int \fBminValue\fR () const"
.br
.ti -1c
.BI "int \fBmaxValue\fR () const"
.br
.ti -1c
.BI "void \fBsetMinValue\fR ( int )"
.br
.ti -1c
.BI "void \fBsetMaxValue\fR ( int )"
.br
.ti -1c
.BI "int \fBlineStep\fR () const"
.br
.ti -1c
.BI "int \fBpageStep\fR () const"
.br
.ti -1c
.BI "void \fBsetLineStep\fR ( int )"
.br
.ti -1c
.BI "void \fBsetPageStep\fR ( int )"
.br
.ti -1c
.BI "int \fBvalue\fR () const"
.br
.in -1c
.SS "Public Slots"
.in +1c
.ti -1c
.BI "virtual void \fBsetValue\fR ( int )"
.br
.ti -1c
.BI "void \fBaddLine\fR ()"
.br
.ti -1c
.BI "void \fBsubtractLine\fR ()"
.br
.ti -1c
.BI "void \fBaddPage\fR ()"
.br
.ti -1c
.BI "void \fBsubtractPage\fR ()"
.br
.ti -1c
.BI "virtual void \fBsetNotchesVisible\fR ( bool b )"
.br
.ti -1c
.BI "virtual void \fBsetWrapping\fR ( bool on )"
.br
.ti -1c
.BI "virtual void \fBsetTracking\fR ( bool enable )"
.br
.in -1c
.SS "Signals"
.in +1c
.ti -1c
.BI "void \fBvalueChanged\fR ( int value )"
.br
.ti -1c
.BI "void \fBdialPressed\fR ()"
.br
.ti -1c
.BI "void \fBdialMoved\fR ( int value )"
.br
.ti -1c
.BI "void \fBdialReleased\fR ()"
.br
.in -1c
.SS "Properties"
.in +1c
.ti -1c
.BI "int \fBlineStep\fR - the current line step"
.br
.ti -1c
.BI "int \fBmaxValue\fR - the current maximum value"
.br
.ti -1c
.BI "int \fBminValue\fR - the current minimum value"
.br
.ti -1c
.BI "int \fBnotchSize\fR - the current notch size  \fI(read " "only" ")\fR"
.br
.ti -1c
.BI "double \fBnotchTarget\fR - the target number of pixels between notches"
.br
.ti -1c
.BI "bool \fBnotchesVisible\fR - whether the notches are shown"
.br
.ti -1c
.BI "int \fBpageStep\fR - the current page step"
.br
.ti -1c
.BI "bool \fBtracking\fR - whether tracking is enabled"
.br
.ti -1c
.BI "int \fBvalue\fR - the current dial value"
.br
.ti -1c
.BI "bool \fBwrapping\fR - whether wrapping is enabled"
.br
.in -1c
.SS "Protected Members"
.in +1c
.ti -1c
.BI "virtual void \fBvalueChange\fR ()"
.br
.ti -1c
.BI "virtual void \fBrangeChange\fR ()"
.br
.ti -1c
.BI "virtual void \fBrepaintScreen\fR ( const QRect * cr = 0 )"
.br
.in -1c
.SH DESCRIPTION
The QDial class provides a rounded range control (like a speedometer or potentiometer).
.PP
QDial is used when the user needs to control a value within a program-definable range, and the range either wraps around (typically, 0..359 degrees) or the dialog layout needs a square widget.
.PP
Both API- and UI-wise, the dial is very similar to a slider. Indeed, when wrapping() is FALSE (the default) there is no real difference between a slider and a dial. They have the same signals, slots and member functions, all of which do the same things. Which one you use depends only on your taste and on the application.
.PP
The dial initially emits valueChanged() signals continuously while the slider is being moved; you can make it emit the signal less often by calling setTracking(FALSE). dialMoved() is emitted continuously even when tracking() is FALSE.
.PP
The slider also emits dialPressed() and dialReleased() signals when the mouse button is pressed and released. But note that the dial's value can change without these signals being emitted; the keyboard and wheel can be used to change the value.
.PP
Unlike the slider, QDial attempts to draw a "nice" number of notches rather than one per lineStep(). If possible, the number of notches drawn is one per lineStep(), but if there aren't enough pixels to draw every one, QDial will draw every second, third etc., notch. notchSize() returns the number of units per notch, hopefully a multiple of lineStep(); setNotchTarget() sets the target distance between neighbouring notches in pixels. The default is 3.75 pixels.
.PP
Like the slider, the dial makes the QRangeControl functions setValue(), addLine(), subtractLine(), addPage() and subtractPage() available as slots.
.PP
The dial's keyboard interface is fairly simple: The left/up and right/down arrow keys move by lineStep(), page up and page down by pageStep() and Home and End to minValue() and maxValue().
.PP
.ce 1
.B "[Image Omitted]"
.PP

.ce 1
.B "[Image Omitted]"
.PP
See also QScrollBar, QSpinBox, GUI Design Handbook: Slider, and Basic Widgets.
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QDial::QDial ( QWidget * parent = 0, const char * name = 0, WFlags f = 0 )"
Constructs a dial called \fIname\fR with parent \fIparent\fR. \fIf\fR is propagated to the QWidget constructor. It has the default range of a QRangeControl.
.SH "QDial::QDial ( int minValue, int maxValue, int pageStep, int value, QWidget * parent = 0, const char * name = 0 )"
Constructs a dial called \fIname\fR with parent \fIparent\fR. The dial's value can never be smaller than \fIminValue\fR or greater than \fImaxValue\fR. Its page step size is \fIpageStep\fR, and its initial value is \fIvalue\fR.
.PP
\fIvalue\fR is forced to be within the legal range.
.SH "QDial::~QDial ()"
Destroys the dial.
.SH "void QDial::addLine ()\fC [slot]\fR"
Increments the dial's value() by one lineStep().
.SH "void QDial::addPage ()\fC [slot]\fR"
Increments the dial's value() by one pageStep() of steps.
.SH "void QDial::dialMoved ( int value )\fC [signal]\fR"
This signal is emitted whenever the dial \fIvalue\fR changes. The frequency of this signal is \fInot\fR influenced by setTracking().
.PP
See also valueChanged().
.SH "void QDial::dialPressed ()\fC [signal]\fR"
This signal is emitted when the user begins mouse interaction with the dial.
.PP
See also dialReleased().
.SH "void QDial::dialReleased ()\fC [signal]\fR"
This signal is emitted when the user ends mouse interaction with the dial.
.PP
See also dialPressed().
.SH "int QDial::lineStep () const"
Returns the current line step. See the "lineStep" property for details.
.SH "int QDial::maxValue () const"
Returns the current maximum value. See the "maxValue" property for details.
.SH "int QDial::minValue () const"
Returns the current minimum value. See the "minValue" property for details.
.SH "int QDial::notchSize () const"
Returns the current notch size. See the "notchSize" property for details.
.SH "double QDial::notchTarget () const"
Returns the target number of pixels between notches. See the "notchTarget" property for details.
.SH "bool QDial::notchesVisible () const"
Returns TRUE if the notches are shown; otherwise returns FALSE. See the "notchesVisible" property for details.
.SH "int QDial::pageStep () const"
Returns the current page step. See the "pageStep" property for details.
.SH "void QDial::rangeChange ()\fC [virtual protected]\fR"
Reimplemented to ensure tick-marks are consistent with the new range.
.PP
Reimplemented from QRangeControl.
.SH "void QDial::repaintScreen ( const QRect * cr = 0 )\fC [virtual protected]\fR"
Paints the dial using clip region \fIcr\fR.
.SH "void QDial::setLineStep ( int )"
Sets the current line step. See the "lineStep" property for details.
.SH "void QDial::setMaxValue ( int )"
Sets the current maximum value. See the "maxValue" property for details.
.SH "void QDial::setMinValue ( int )"
Sets the current minimum value. See the "minValue" property for details.
.SH "void QDial::setNotchTarget ( double )\fC [virtual]\fR"
Sets the target number of pixels between notches. See the "notchTarget" property for details.
.SH "void QDial::setNotchesVisible ( bool b )\fC [virtual slot]\fR"
Sets whether the notches are shown to \fIb\fR. See the "notchesVisible" property for details.
.SH "void QDial::setPageStep ( int )"
Sets the current page step. See the "pageStep" property for details.
.SH "void QDial::setTracking ( bool enable )\fC [virtual slot]\fR"
Sets whether tracking is enabled to \fIenable\fR. See the "tracking" property for details.
.SH "void QDial::setValue ( int )\fC [virtual slot]\fR"
Sets the current dial value. See the "value" property for details.
.SH "void QDial::setWrapping ( bool on )\fC [virtual slot]\fR"
Sets whether wrapping is enabled to \fIon\fR. See the "wrapping" property for details.
.SH "void QDial::subtractLine ()\fC [slot]\fR"
Decrements the dial's value() by one lineStep().
.SH "void QDial::subtractPage ()\fC [slot]\fR"
Decrements the dial's value() by one pageStep() of steps.
.SH "bool QDial::tracking () const"
Returns TRUE if tracking is enabled; otherwise returns FALSE. See the "tracking" property for details.
.SH "int QDial::value () const"
Returns the current dial value. See the "value" property for details.
.SH "void QDial::valueChange ()\fC [virtual protected]\fR"
Reimplemented to ensure the display is correct and to emit the valueChanged(int) signal when appropriate.
.PP
Reimplemented from QRangeControl.
.SH "void QDial::valueChanged ( int value )\fC [signal]\fR"
This signal is emitted whenever the dial's \fIvalue\fR changes. The frequency of this signal is influenced by setTracking().
.SH "bool QDial::wrapping () const"
Returns TRUE if wrapping is enabled; otherwise returns FALSE. See the "wrapping" property for details.
.SS "Property Documentation"
.SH "int lineStep"
This property holds the current line step.
.PP
setLineStep() calls the virtual stepChange() function if the new line step is different from the previous setting.
.PP
See also QRangeControl::setSteps(), pageStep, and setRange().
.PP
Set this property's value with setLineStep() and get this property's value with lineStep().
.SH "int maxValue"
This property holds the current maximum value.
.PP
When setting this property, the QDial::minValue is adjusted if necessary to ensure that the range remains valid.
.PP
See also setRange().
.PP
Set this property's value with setMaxValue() and get this property's value with maxValue().
.SH "int minValue"
This property holds the current minimum value.
.PP
When setting this property, the QDial::maxValue is adjusted if necessary to ensure that the range remains valid.
.PP
See also setRange().
.PP
Set this property's value with setMinValue() and get this property's value with minValue().
.SH "int notchSize"
This property holds the current notch size.
.PP
The notch size is in range control units, not pixels, and if possible it is a multiple of lineStep() that results in an on-screen notch size near notchTarget().
.PP
See also notchTarget and lineStep.
.PP
Get this property's value with notchSize().
.SH "double notchTarget"
This property holds the target number of pixels between notches.
.PP
The notch target is the number of pixels QDial attempts to put between each notch.
.PP
The actual size may differ from the target size.
.PP
Set this property's value with setNotchTarget() and get this property's value with notchTarget().
.SH "bool notchesVisible"
This property holds whether the notches are shown.
.PP
If TRUE, the notches are shown. If FALSE (the default) notches are not shown.
.PP
Set this property's value with setNotchesVisible() and get this property's value with notchesVisible().
.SH "int pageStep"
This property holds the current page step.
.PP
setPageStep() calls the virtual stepChange() function if the new page step is different from the previous setting.
.PP
See also stepChange().
.PP
Set this property's value with setPageStep() and get this property's value with pageStep().
.SH "bool tracking"
This property holds whether tracking is enabled.
.PP
If TRUE (the default), tracking is enabled. This means that the arrow can be moved using the mouse; otherwise the arrow cannot be moved with the mouse.
.PP
Set this property's value with setTracking() and get this property's value with tracking().
.SH "int value"
This property holds the current dial value.
.PP
This is guaranteed to be within the range QDial::minValue..QDial::maxValue.
.PP
See also minValue and maxValue.
.PP
Set this property's value with setValue() and get this property's value with value().
.SH "bool wrapping"
This property holds whether wrapping is enabled.
.PP
If TRUE, wrapping is enabled. This means that the arrow can be turned around 360°. Otherwise there is some space at the bottom of the dial which is skipped by the arrow.
.PP
This property's default is FALSE.
.PP
Set this property's value with setWrapping() and get this property's value with wrapping().

.SH "SEE ALSO"
.BR http://doc.trolltech.com/ntqdial.html
.BR http://www.trolltech.com/faq/tech.html
.SH COPYRIGHT
Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
license file included in the distribution for a complete license
statement.
.SH AUTHOR
Generated automatically from the source code.
.SH BUGS
If you find a bug in Qt, please report it as described in
.BR http://doc.trolltech.com/bughowto.html .
Good bug reports help us to help you. Thank you.
.P
The definitive TQt documentation is provided in HTML format; it is
located at $TQTDIR/doc/html and can be read using TQt Assistant or with
a web browser. This man page is provided as a convenience for those
users who prefer man pages, although this format is not officially
supported by Trolltech. 
.P
If you find errors in this manual page, please report them to
.BR qt-bugs@trolltech.com .
Please include the name of the manual page (tqdial.3qt) and the Qt
version (3.3.8).