QDial(3qt)

1QDial(3qt)                                                          QDial(3qt)
2
3
4

NAME

6       QDial - Rounded range control (like a speedometer or potentiometer)
7

SYNOPSIS

9       #include <qdial.h>
10
11       Inherits QWidget and QRangeControl.
12
13   Public Members
14       QDial ( QWidget * parent = 0, const char * name = 0, WFlags f = 0 )
15       QDial ( int minValue, int maxValue, int pageStep, int value, QWidget *
16           parent = 0, const char * name = 0 )
17       ~QDial ()
18       bool tracking () const
19       bool wrapping () const
20       int notchSize () const
21       virtual void setNotchTarget ( double )
22       double notchTarget () const
23       bool notchesVisible () const
24       int minValue () const
25       int maxValue () const
26       void setMinValue ( int )
27       void setMaxValue ( int )
28       int lineStep () const
29       int pageStep () const
30       void setLineStep ( int )
31       void setPageStep ( int )
32       int value () const
33
34   Public Slots
35       virtual void setValue ( int )
36       void addLine ()
37       void subtractLine ()
38       void addPage ()
39       void subtractPage ()
40       virtual void setNotchesVisible ( bool b )
41       virtual void setWrapping ( bool on )
42       virtual void setTracking ( bool enable )
43
44   Signals
45       void valueChanged ( int value )
46       void dialPressed ()
47       void dialMoved ( int value )
48       void dialReleased ()
49
50   Properties
51       int lineStep - the current line step
52       int maxValue - the current maximum value
53       int minValue - the current minimum value
54       int notchSize - the current notch size  (read only)
55       double notchTarget - the target number of pixels between notches
56       bool notchesVisible - whether the notches are shown
57       int pageStep - the current page step
58       bool tracking - whether tracking is enabled
59       int value - the current dial value
60       bool wrapping - whether wrapping is enabled
61
62   Protected Members
63       virtual void valueChange ()
64       virtual void rangeChange ()
65       virtual void repaintScreen ( const QRect * cr = 0 )
66

DESCRIPTION

68       The QDial class provides a rounded range control (like a speedometer or
69       potentiometer).
70
71       QDial is used when the user needs to control a value within a program-
72       definable range, and the range either wraps around (typically, 0..359
73       degrees) or the dialog layout needs a square widget.
74
75       Both API- and UI-wise, the dial is very similar to a slider. Indeed,
76       when wrapping() is FALSE (the default) there is no real difference
77       between a slider and a dial. They have the same signals, slots and
78       member functions, all of which do the same things. Which one you use
79       depends only on your taste and on the application.
80
81       The dial initially emits valueChanged() signals continuously while the
82       slider is being moved; you can make it emit the signal less often by
83       calling setTracking(FALSE). dialMoved() is emitted continuously even
84       when tracking() is FALSE.
85
86       The slider also emits dialPressed() and dialReleased() signals when the
87       mouse button is pressed and released. But note that the dial's value
88       can change without these signals being emitted; the keyboard and wheel
89       can be used to change the value.
90
91       Unlike the slider, QDial attempts to draw a "nice" number of notches
92       rather than one per lineStep(). If possible, the number of notches
93       drawn is one per lineStep(), but if there aren't enough pixels to draw
94       every one, QDial will draw every second, third etc., notch. notchSize()
95       returns the number of units per notch, hopefully a multiple of
96       lineStep(); setNotchTarget() sets the target distance between
97       neighbouring notches in pixels. The default is 3.75 pixels.
98
99       Like the slider, the dial makes the QRangeControl functions setValue(),
100       addLine(), subtractLine(), addPage() and subtractPage() available as
101       slots.
102
103       The dial's keyboard interface is fairly simple: The left/up and
104       right/down arrow keys move by lineStep(), page up and page down by
105       pageStep() and Home and End to minValue() and maxValue().
106
107                                   [Image Omitted]
108
109                                   [Image Omitted]
110
111       See also QScrollBar, QSpinBox, GUI Design Handbook: Slider, and Basic
112       Widgets.
113

MEMBER FUNCTION DOCUMENTATION

QDial::QDial ( QWidget * parent = 0, const char * name = 0, WFlags f = 0 )

116       Constructs a dial called name with parent parent. f is propagated to
117       the QWidget constructor. It has the default range of a QRangeControl.
118

QDial::QDial ( int minValue, int maxValue, int pageStep, int value, QWidget *

120       parent = 0, const char * name = 0 )
121       Constructs a dial called name with parent parent. The dial's value can
122       never be smaller than minValue or greater than maxValue. Its page step
123       size is pageStep, and its initial value is value.
124
125       value is forced to be within the legal range.
126

QDial::~QDial ()

128       Destroys the dial.
129

void QDial::addLine () [slot]

131       Increments the dial's value() by one lineStep().
132

void QDial::addPage () [slot]

134       Increments the dial's value() by one pageStep() of steps.
135

void QDial::dialMoved ( int value ) [signal]

137       This signal is emitted whenever the dial value changes. The frequency
138       of this signal is not influenced by setTracking().
139
140       See also valueChanged().
141

void QDial::dialPressed () [signal]

143       This signal is emitted when the user begins mouse interaction with the
144       dial.
145
146       See also dialReleased().
147

void QDial::dialReleased () [signal]

149       This signal is emitted when the user ends mouse interaction with the
150       dial.
151
152       See also dialPressed().
153

int QDial::lineStep () const

155       Returns the current line step. See the "lineStep" property for details.
156

int QDial::maxValue () const

158       Returns the current maximum value. See the "maxValue" property for
159       details.
160

int QDial::minValue () const

162       Returns the current minimum value. See the "minValue" property for
163       details.
164

int QDial::notchSize () const

166       Returns the current notch size. See the "notchSize" property for
167       details.
168

double QDial::notchTarget () const

170       Returns the target number of pixels between notches. See the
171       "notchTarget" property for details.
172

bool QDial::notchesVisible () const

174       Returns TRUE if the notches are shown; otherwise returns FALSE. See the
175       "notchesVisible" property for details.
176

int QDial::pageStep () const

178       Returns the current page step. See the "pageStep" property for details.
179

void QDial::rangeChange () [virtual protected]

181       Reimplemented to ensure tick-marks are consistent with the new range.
182
183       Reimplemented from QRangeControl.
184

void QDial::repaintScreen ( const QRect * cr = 0 ) [virtual protected]

186       Paints the dial using clip region cr.
187

void QDial::setLineStep ( int )

189       Sets the current line step. See the "lineStep" property for details.
190

void QDial::setMaxValue ( int )

192       Sets the current maximum value. See the "maxValue" property for
193       details.
194

void QDial::setMinValue ( int )

196       Sets the current minimum value. See the "minValue" property for
197       details.
198

void QDial::setNotchTarget ( double ) [virtual]

200       Sets the target number of pixels between notches. See the "notchTarget"
201       property for details.
202

void QDial::setNotchesVisible ( bool b ) [virtual slot]

204       Sets whether the notches are shown to b. See the "notchesVisible"
205       property for details.
206

void QDial::setPageStep ( int )

208       Sets the current page step. See the "pageStep" property for details.
209

void QDial::setTracking ( bool enable ) [virtual slot]

211       Sets whether tracking is enabled to enable. See the "tracking" property
212       for details.
213

void QDial::setValue ( int ) [virtual slot]

215       Sets the current dial value. See the "value" property for details.
216

void QDial::setWrapping ( bool on ) [virtual slot]

218       Sets whether wrapping is enabled to on. See the "wrapping" property for
219       details.
220

void QDial::subtractLine () [slot]

222       Decrements the dial's value() by one lineStep().
223

void QDial::subtractPage () [slot]

225       Decrements the dial's value() by one pageStep() of steps.
226

bool QDial::tracking () const

228       Returns TRUE if tracking is enabled; otherwise returns FALSE. See the
229       "tracking" property for details.
230

int QDial::value () const

232       Returns the current dial value. See the "value" property for details.
233

void QDial::valueChange () [virtual protected]

235       Reimplemented to ensure the display is correct and to emit the
236       valueChanged(int) signal when appropriate.
237
238       Reimplemented from QRangeControl.
239

void QDial::valueChanged ( int value ) [signal]

241       This signal is emitted whenever the dial's value changes. The frequency
242       of this signal is influenced by setTracking().
243

bool QDial::wrapping () const

245       Returns TRUE if wrapping is enabled; otherwise returns FALSE. See the
246       "wrapping" property for details.
247
248   Property Documentation

int lineStep

250       This property holds the current line step.
251
252       setLineStep() calls the virtual stepChange() function if the new line
253       step is different from the previous setting.
254
255       See also QRangeControl::setSteps(), pageStep, and setRange().
256
257       Set this property's value with setLineStep() and get this property's
258       value with lineStep().
259

int maxValue

261       This property holds the current maximum value.
262
263       When setting this property, the QDial::minValue is adjusted if
264       necessary to ensure that the range remains valid.
265
266       See also setRange().
267
268       Set this property's value with setMaxValue() and get this property's
269       value with maxValue().
270

int minValue

272       This property holds the current minimum value.
273
274       When setting this property, the QDial::maxValue is adjusted if
275       necessary to ensure that the range remains valid.
276
277       See also setRange().
278
279       Set this property's value with setMinValue() and get this property's
280       value with minValue().
281

int notchSize

283       This property holds the current notch size.
284
285       The notch size is in range control units, not pixels, and if possible
286       it is a multiple of lineStep() that results in an on-screen notch size
287       near notchTarget().
288
289       See also notchTarget and lineStep.
290
291       Get this property's value with notchSize().
292

double notchTarget

294       This property holds the target number of pixels between notches.
295
296       The notch target is the number of pixels QDial attempts to put between
297       each notch.
298
299       The actual size may differ from the target size.
300
301       Set this property's value with setNotchTarget() and get this property's
302       value with notchTarget().
303

bool notchesVisible

305       This property holds whether the notches are shown.
306
307       If TRUE, the notches are shown. If FALSE (the default) notches are not
308       shown.
309
310       Set this property's value with setNotchesVisible() and get this
311       property's value with notchesVisible().
312

int pageStep

314       This property holds the current page step.
315
316       setPageStep() calls the virtual stepChange() function if the new page
317       step is different from the previous setting.
318
319       See also stepChange().
320
321       Set this property's value with setPageStep() and get this property's
322       value with pageStep().
323

bool tracking

325       This property holds whether tracking is enabled.
326
327       If TRUE (the default), tracking is enabled. This means that the arrow
328       can be moved using the mouse; otherwise the arrow cannot be moved with
329       the mouse.
330
331       Set this property's value with setTracking() and get this property's
332       value with tracking().
333

int value

335       This property holds the current dial value.
336
337       This is guaranteed to be within the range
338       QDial::minValue..QDial::maxValue.
339
340       See also minValue and maxValue.
341
342       Set this property's value with setValue() and get this property's value
343       with value().
344

bool wrapping

346       This property holds whether wrapping is enabled.
347
348       If TRUE, wrapping is enabled. This means that the arrow can be turned
349       around 360°. Otherwise there is some space at the bottom of the dial
350       which is skipped by the arrow.
351
352       This property's default is FALSE.
353
354       Set this property's value with setWrapping() and get this property's
355       value with wrapping().
356
357

COPYRIGHT

363       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
364       license file included in the distribution for a complete license
365       statement.
366

AUTHOR

368       Generated automatically from the source code.
369

BUGS

371       If you find a bug in Qt, please report it as described in
372       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
373       help you. Thank you.
374
375       The definitive Qt documentation is provided in HTML format; it is
376       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
377       web browser. This man page is provided as a convenience for those users
378       who prefer man pages, although this format is not officially supported
379       by Trolltech.
380
381       If you find errors in this manual page, please report them to qt-
382       bugs@trolltech.com.  Please include the name of the manual page
383       (qdial.3qt) and the Qt version (3.3.8).
384
385
386
387Trolltech AS                    2 February 2007                     QDial(3qt)