1QRangeControl(3qt) QRangeControl(3qt)
2
6 QRangeControl - Integer value within a range
7
9 #include <qrangecontrol.h>
10 Inherited by QDial, QScrollBar, QSlider, and QSpinBox.
12 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 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
44 The QRangeControl class provides an integer value within a range.
45 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 <ol type=1>
51 1 Current value The bounded integer that QRangeControl maintains.
53 value() returns it, and several functions, including setValue(),
54 set it.
55 2 Minimum The lowest value that value() can ever return. Returned
57 by minValue() and set by setRange() or one of the constructors.
58 3 Maximum The highest value that value() can ever return. Returned
60 by maxValue() and set by setRange() or one of the constructors.
61 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 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 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 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 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 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 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 See also Miscellaneous Classes.
99
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
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
113 Destroys the range control
114
116 Equivalent to setValue( value() + lineStep() ).
117 If the value is changed, then valueChange() is called.
119 See also subtractLine(), addPage(), and setValue().
121
123 Equivalent to setValue( value() + pageStep() ).
124 If the value is changed, then valueChange() is called.
126 See also subtractPage(), addLine(), and setValue().
128
130 Forces the value v to be within the range from minValue() to maxValue()
131 inclusive, and returns the result.
132 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 See also setValue(), value(), minValue(), and maxValue().
138
140 Sets the range control value directly without calling valueChange().
141 Forces the new value to be within the legal range.
143 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 See also setValue().
150
152 Returns the line step.
153 See also setSteps() and pageStep().
155
157 Returns the maximum value of the range.
158 See also setMaxValue(), setRange(), and minValue().
160
162 Returns the minimum value of the range.
163 See also setMinValue(), setRange(), and maxValue().
165
167 Returns the page step.
168 See also setSteps() and lineStep().
170
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 This function can handle the entire integer range without overflow,
178 providing span is <= 4096.
179 Calling this method is useful when actually drawing a range control
181 such as a QScrollBar on-screen.
182 See also valueFromPosition().
184
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 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 See also value() and setRange().
198
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 Note that this method is called after the range has changed.
205 See also setRange(), valueChange(), and stepChange().
207 Reimplemented in QDial, QSlider, and QSpinBox.
209
211 Sets the minimum value of the range to maxVal.
212 If necessary, the minValue() is adjusted so that the range remains
214 valid.
215 See also maxValue() and setMinValue().
217
219 Sets the minimum value of the range to minVal.
220 If necessary, the maxValue() is adjusted so that the range remains
222 valid.
223 See also minValue() and setMaxValue().
225
227 Sets the range control's minimum value to minValue and its maximum
228 value to maxValue.
229 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 If maxValue is smaller than minValue, minValue becomes the only legal
236 value.
237 See also minValue() and maxValue().
239 Examples:
241
243 Sets the range's line step to lineStep and page step to pageStep.
244 Calls the virtual stepChange() function if the new line step or page
246 step are different from the previous settings.
247 See also lineStep(), pageStep(), and setRange().
249
251 Sets the range control's value to value and forces it to be within the
252 legal range.
253 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 See also value().
259
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 Note that this method is called after a step setting has changed.
267 See also setSteps(), rangeChange(), and valueChange().
269
271 Equivalent to setValue( value() - lineStep() ).
272 If the value is changed, then valueChange() is called.
274 See also addLine(), subtractPage(), and setValue().
276
278 Equivalent to setValue( value() - pageStep() ).
279 If the value is changed, then valueChange() is called.
281 See also addPage(), subtractLine(), and setValue().
283
285 Returns the current range control value. This is guaranteed to be
286 within the range [minValue(), maxValue()].
287 See also setValue() and prevValue().
289
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 Note that this method is called after the value has changed. The
296 previous value can be retrieved using prevValue().
297 See also setValue(), addPage(), subtractPage(), addLine(),
299 subtractLine(), rangeChange(), and stepChange().
300 Reimplemented in QDial, QSlider, and QSpinBox.
302
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 This function can handle the entire integer range without overflow.
308 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 See also positionFromValue().
315
318 http://doc.trolltech.com/qrangecontrol.html
319 http://www.trolltech.com/faq/tech.html
320
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
327 Generated automatically from the source code.
328
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 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 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).
343Trolltech AS 2 February 2007 QRangeControl(3qt)