QRangeControl(3qt)

1QRangeControl(3qt)                                          QRangeControl(3qt)
2
3
4

NAME

6       QRangeControl - Integer value within a range
7

SYNOPSIS

9       #include <qrangecontrol.h>
10
11       Inherited by QDial, QScrollBar, QSlider, and QSpinBox.
12
13   Public Members
14       QRangeControl ()
15       QRangeControl ( int minValue, int maxValue, int lineStep, int pageStep,
16           int value )
17       virtual ~QRangeControl ()
18       int value () const
19       void setValue ( int value )
20       void addPage ()
21       void subtractPage ()
22       void addLine ()
23       void subtractLine ()
24       int minValue () const
25       int maxValue () const
26       void setRange ( int minValue, int maxValue )
27       void setMinValue ( int minVal )
28       void setMaxValue ( int maxVal )
29       int lineStep () const
30       int pageStep () const
31       void setSteps ( int lineStep, int pageStep )
32       int bound ( int v ) const
33
34   Protected Members
35       int positionFromValue ( int logical_val, int span ) const
36       int valueFromPosition ( int pos, int span ) const
37       void directSetValue ( int value )
38       int prevValue () const
39       virtual void valueChange ()
40       virtual void rangeChange ()
41       virtual void stepChange ()
42

DESCRIPTION

44       The QRangeControl class provides an integer value within a range.
45
46       Although originally designed for the QScrollBar widget, the
47       QRangeControl can also be used in conjunction with other widgets such
48       as QSlider and QSpinBox. Here are the five main concepts in the class:
49
50       <ol type=1>
51
52       1      Current value The bounded integer that QRangeControl maintains.
53              value() returns it, and several functions, including setValue(),
54              set it.
55
56       2      Minimum The lowest value that value() can ever return. Returned
57              by minValue() and set by setRange() or one of the constructors.
58
59       3      Maximum The highest value that value() can ever return. Returned
60              by maxValue() and set by setRange() or one of the constructors.
61
62       4      Line step The smaller of two natural steps that QRangeControl
63              provides and typically corresponds to the user pressing an arrow
64              key. The line step is returned by lineStep() and set using
65              setSteps(). The functions addLine() and subtractLine()
66              respectively increment and decrement the current value by
67              lineStep().
68
69       5      Page step The larger of two natural steps that QRangeControl
70              provides and typically corresponds to the user pressing PageUp
71              or PageDown. The page step is returned by pageStep() and set
72              using setSteps(). The functions addPage() and substractPage()
73              respectively increment and decrement the current value by
74              pageStep().
75
76       Unity (1) may be viewed as a third step size. setValue() lets you set
77       the current value to any integer in the allowed range, not just
78       minValue() + n * lineStep() for integer values of n. Some widgets may
79       allow the user to set any value at all; others may just provide
80       multiples of lineStep() or pageStep().
81
82       QRangeControl provides three virtual functions that are well suited for
83       updating the on-screen representation of range controls and emitting
84       signals: valueChange(), rangeChange() and stepChange().
85
86       QRangeControl also provides a function called bound() which lets you
87       force arbitrary integers to be within the allowed range of the range
88       control.
89
90       We recommend that all widgets that inherit QRangeControl provide at
91       least a signal called valueChanged(); many widgets will want to provide
92       addStep(), addPage(), substractStep() and substractPage() as slots.
93
94       Note that you must use multiple inheritance if you plan to implement a
95       widget using QRangeControl because QRangeControl is not derived from
96       QWidget.
97
98       See also Miscellaneous Classes.
99

MEMBER FUNCTION DOCUMENTATION

QRangeControl::QRangeControl ()

102       Constructs a range control with a minimum value of 0, maximum value of
103       99, line step of 1, page step of 10 and initial value 0.
104

QRangeControl::QRangeControl ( int minValue, int maxValue, int lineStep, int

106       pageStep, int value )
107       Constructs a range control whose value can never be smaller than
108       minValue or greater than maxValue, whose line step size is lineStep and
109       page step size is pageStep and whose value is initially value (which is
110       guaranteed to be in range using bound()).
111

QRangeControl::~QRangeControl () [virtual]

113       Destroys the range control
114

void QRangeControl::addLine ()

116       Equivalent to setValue( value() + lineStep() ).
117
118       If the value is changed, then valueChange() is called.
119
120       See also subtractLine(), addPage(), and setValue().
121

void QRangeControl::addPage ()

123       Equivalent to setValue( value() + pageStep() ).
124
125       If the value is changed, then valueChange() is called.
126
127       See also subtractPage(), addLine(), and setValue().
128

int QRangeControl::bound ( int v ) const

130       Forces the value v to be within the range from minValue() to maxValue()
131       inclusive, and returns the result.
132
133       This function is provided so that you can easily force other numbers
134       than value() into the allowed range. You do not need to call it in
135       order to use QRangeControl itself.
136
137       See also setValue(), value(), minValue(), and maxValue().
138

void QRangeControl::directSetValue ( int value ) [protected]

140       Sets the range control value directly without calling valueChange().
141
142       Forces the new value to be within the legal range.
143
144       You will rarely have to call this function. However, if you want to
145       change the range control's value inside the overloaded method
146       valueChange(), setValue() would call the function valueChange() again.
147       To avoid this recursion you must use directSetValue() instead.
148
149       See also setValue().
150

int QRangeControl::lineStep () const

152       Returns the line step.
153
154       See also setSteps() and pageStep().
155

int QRangeControl::maxValue () const

157       Returns the maximum value of the range.
158
159       See also setMaxValue(), setRange(), and minValue().
160

int QRangeControl::minValue () const

162       Returns the minimum value of the range.
163
164       See also setMinValue(), setRange(), and maxValue().
165

int QRangeControl::pageStep () const

167       Returns the page step.
168
169       See also setSteps() and lineStep().
170

int QRangeControl::positionFromValue ( int logical_val, int span ) const

172       [protected]
173       Converts logical_val to a pixel position. minValue() maps to 0,
174       maxValue() maps to span and other values are distributed evenly in-
175       between.
176
177       This function can handle the entire integer range without overflow,
178       providing span is <= 4096.
179
180       Calling this method is useful when actually drawing a range control
181       such as a QScrollBar on-screen.
182
183       See also valueFromPosition().
184

int QRangeControl::prevValue () const [protected]

186       Returns the previous value of the range control. "Previous value" means
187       the value before the last change occurred. Setting a new range may
188       affect the value, too, because the value is forced to be inside the
189       specified range. When the range control is initially created, this is
190       the same as value().
191
192       prevValue() can be outside the current legal range if a call to
193       setRange() causes the current value to change. For example, if the
194       range was [0, 1000] and the current value is 500, setRange(0, 400)
195       makes value() return 400 and prevValue() return 500.
196
197       See also value() and setRange().
198

void QRangeControl::rangeChange () [virtual protected]

200       This virtual function is called whenever the range control's range
201       changes. You can reimplement it if you want to be notified when the
202       range changes. The default implementation does nothing.
203
204       Note that this method is called after the range has changed.
205
206       See also setRange(), valueChange(), and stepChange().
207
208       Reimplemented in QDial, QSlider, and QSpinBox.
209

void QRangeControl::setMaxValue ( int maxVal )

211       Sets the minimum value of the range to maxVal.
212
213       If necessary, the minValue() is adjusted so that the range remains
214       valid.
215
216       See also maxValue() and setMinValue().
217

void QRangeControl::setMinValue ( int minVal )

219       Sets the minimum value of the range to minVal.
220
221       If necessary, the maxValue() is adjusted so that the range remains
222       valid.
223
224       See also minValue() and setMaxValue().
225

void QRangeControl::setRange ( int minValue, int maxValue )

227       Sets the range control's minimum value to minValue and its maximum
228       value to maxValue.
229
230       Calls the virtual rangeChange() function if one or both of the new
231       minimum and maximum values are different from the previous setting.
232       Calls the virtual valueChange() function if the current value is
233       adjusted because it was outside the new range.
234
235       If maxValue is smaller than minValue, minValue becomes the only legal
236       value.
237
238       See also minValue() and maxValue().
239
240       Examples:
241

void QRangeControl::setSteps ( int lineStep, int pageStep )

243       Sets the range's line step to lineStep and page step to pageStep.
244
245       Calls the virtual stepChange() function if the new line step or page
246       step are different from the previous settings.
247
248       See also lineStep(), pageStep(), and setRange().
249

void QRangeControl::setValue ( int value )

251       Sets the range control's value to value and forces it to be within the
252       legal range.
253
254       Calls the virtual valueChange() function if the new value is different
255       from the previous value. The old value can still be retrieved using
256       prevValue().
257
258       See also value().
259

void QRangeControl::stepChange () [virtual protected]

261       This virtual function is called whenever the range control's line or
262       page step settings change. You can reimplement it if you want to be
263       notified when the step changes. The default implementation does
264       nothing.
265
266       Note that this method is called after a step setting has changed.
267
268       See also setSteps(), rangeChange(), and valueChange().
269

void QRangeControl::subtractLine ()

271       Equivalent to setValue( value() - lineStep() ).
272
273       If the value is changed, then valueChange() is called.
274
275       See also addLine(), subtractPage(), and setValue().
276

void QRangeControl::subtractPage ()

278       Equivalent to setValue( value() - pageStep() ).
279
280       If the value is changed, then valueChange() is called.
281
282       See also addPage(), subtractLine(), and setValue().
283

int QRangeControl::value () const

285       Returns the current range control value. This is guaranteed to be
286       within the range [minValue(), maxValue()].
287
288       See also setValue() and prevValue().
289

void QRangeControl::valueChange () [virtual protected]

291       This virtual function is called whenever the range control value
292       changes. You can reimplement it if you want to be notified when the
293       value changes. The default implementation does nothing.
294
295       Note that this method is called after the value has changed. The
296       previous value can be retrieved using prevValue().
297
298       See also setValue(), addPage(), subtractPage(), addLine(),
299       subtractLine(), rangeChange(), and stepChange().
300
301       Reimplemented in QDial, QSlider, and QSpinBox.
302

int QRangeControl::valueFromPosition ( int pos, int span ) const [protected]

304       Converts the pixel position pos to a value. 0 maps to minValue(), span
305       maps to maxValue() and other values are distributed evenly in-between.
306
307       This function can handle the entire integer range without overflow.
308
309       Calling this method is useful if you actually implemented a range
310       control widget such as QScrollBar and want to handle mouse press
311       events. This function then maps screen coordinates to the logical
312       values.
313
314       See also positionFromValue().
315
316

COPYRIGHT

322       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
323       license file included in the distribution for a complete license
324       statement.
325

AUTHOR

327       Generated automatically from the source code.
328

BUGS

330       If you find a bug in Qt, please report it as described in
331       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
332       help you. Thank you.
333
334       The definitive Qt documentation is provided in HTML format; it is
335       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
336       web browser. This man page is provided as a convenience for those users
337       who prefer man pages, although this format is not officially supported
338       by Trolltech.
339
340       If you find errors in this manual page, please report them to qt-
341       bugs@trolltech.com.  Please include the name of the manual page
342       (qrangecontrol.3qt) and the Qt version (3.3.8).
343
344
345
346Trolltech AS                    2 February 2007             QRangeControl(3qt)