source: trunk/doc/html/qrangecontrol.html

Last change on this file was 190, checked in by rudi, 14 years ago

reference documentation added
File size: 19.2 KB
RevLine 
[190]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/widgets/qrangecontrol.cpp:46 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>QRangeControl Class</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QRangeControl Class Reference</h1>
33
34<p>The QRangeControl class provides an integer value within a range.
35<a href="#details">More...</a>
36<p><tt>#include &lt;<a href="qrangecontrol-h.html">qrangecontrol.h</a>&gt;</tt>
37<p>Inherited by <a href="qdial.html">QDial</a>, <a href="qscrollbar.html">QScrollBar</a>, <a href="qslider.html">QSlider</a>, and <a href="qspinbox.html">QSpinBox</a>.
38<p><a href="qrangecontrol-members.html">List of all member functions.</a>
39<h2>Public Members</h2>
40<ul>
41<li class=fn><a href="#QRangeControl"><b>QRangeControl</b></a> ()</li>
42<li class=fn><a href="#QRangeControl-2"><b>QRangeControl</b></a> ( int&nbsp;minValue, int&nbsp;maxValue, int&nbsp;lineStep, int&nbsp;pageStep, int&nbsp;value )</li>
43<li class=fn>virtual <a href="#~QRangeControl"><b>~QRangeControl</b></a> ()</li>
44<li class=fn>int <a href="#value"><b>value</b></a> () const</li>
45<li class=fn>void <a href="#setValue"><b>setValue</b></a> ( int&nbsp;value )</li>
46<li class=fn>void <a href="#addPage"><b>addPage</b></a> ()</li>
47<li class=fn>void <a href="#subtractPage"><b>subtractPage</b></a> ()</li>
48<li class=fn>void <a href="#addLine"><b>addLine</b></a> ()</li>
49<li class=fn>void <a href="#subtractLine"><b>subtractLine</b></a> ()</li>
50<li class=fn>int <a href="#minValue"><b>minValue</b></a> () const</li>
51<li class=fn>int <a href="#maxValue"><b>maxValue</b></a> () const</li>
52<li class=fn>void <a href="#setRange"><b>setRange</b></a> ( int&nbsp;minValue, int&nbsp;maxValue )</li>
53<li class=fn>void <a href="#setMinValue"><b>setMinValue</b></a> ( int&nbsp;minVal )</li>
54<li class=fn>void <a href="#setMaxValue"><b>setMaxValue</b></a> ( int&nbsp;maxVal )</li>
55<li class=fn>int <a href="#lineStep"><b>lineStep</b></a> () const</li>
56<li class=fn>int <a href="#pageStep"><b>pageStep</b></a> () const</li>
57<li class=fn>void <a href="#setSteps"><b>setSteps</b></a> ( int&nbsp;lineStep, int&nbsp;pageStep )</li>
58<li class=fn>int <a href="#bound"><b>bound</b></a> ( int&nbsp;v ) const</li>
59</ul>
60<h2>Protected Members</h2>
61<ul>
62<li class=fn>int <a href="#positionFromValue"><b>positionFromValue</b></a> ( int&nbsp;logical_val, int&nbsp;span ) const</li>
63<li class=fn>int <a href="#valueFromPosition"><b>valueFromPosition</b></a> ( int&nbsp;pos, int&nbsp;span ) const</li>
64<li class=fn>void <a href="#directSetValue"><b>directSetValue</b></a> ( int&nbsp;value )</li>
65<li class=fn>int <a href="#prevValue"><b>prevValue</b></a> () const</li>
66<li class=fn>virtual void <a href="#valueChange"><b>valueChange</b></a> ()</li>
67<li class=fn>virtual void <a href="#rangeChange"><b>rangeChange</b></a> ()</li>
68<li class=fn>virtual void <a href="#stepChange"><b>stepChange</b></a> ()</li>
69</ul>
70<hr><a name="details"></a><h2>Detailed Description</h2>
71
72
73The QRangeControl class provides an integer value within a range.
74<p>
75<p> Although originally designed for the <a href="qscrollbar.html">QScrollBar</a> widget, the
76QRangeControl can also be used in conjunction with other widgets
77such as <a href="qslider.html">QSlider</a> and <a href="qspinbox.html">QSpinBox</a>. Here are the five main concepts in
78the class:
79<p> <ol type=1>
80<p> <li> <em>Current value</em> The bounded integer that
81QRangeControl maintains. <a href="#value">value</a>() returns it, and several
82functions, including <a href="#setValue">setValue</a>(), set it.
83<p> <li> <em>Minimum</em> The lowest value that value() can ever
84return. Returned by <a href="#minValue">minValue</a>() and set by <a href="#setRange">setRange</a>() or one of the
85constructors.
86<p> <li> <em>Maximum</em> The highest value that value() can ever
87return. Returned by <a href="#maxValue">maxValue</a>() and set by setRange() or one of the
88constructors.
89<p> <li> <em>Line step</em> The smaller of two natural steps that
90QRangeControl provides and typically corresponds to the user
91pressing an arrow key. The line step is returned by <a href="#lineStep">lineStep</a>()
92and set using <a href="#setSteps">setSteps</a>(). The functions <a href="#addLine">addLine</a>() and
93<a href="#subtractLine">subtractLine</a>() respectively increment and decrement the current
94value by lineStep().
95<p> <li> <em>Page step</em> The larger of two natural steps that
96QRangeControl provides and typically corresponds to the user
97pressing PageUp or PageDown. The page step is returned by
98<a href="#pageStep">pageStep</a>() and set using setSteps(). The functions <a href="#addPage">addPage</a>() and
99substractPage() respectively increment and decrement the current
100value by pageStep().
101<p> </ol>
102<p> Unity (1) may be viewed as a third step size. <a href="#setValue">setValue</a>() lets you
103set the current value to any integer in the allowed range, not
104just <a href="#minValue">minValue</a>() + <em>n</em> * lineStep() for integer values of <em>n</em>.
105Some widgets may allow the user to set any value at all; others
106may just provide multiples of lineStep() or pageStep().
107<p> QRangeControl provides three virtual functions that are well
108suited for updating the on-screen representation of range controls
109and emitting signals: <a href="#valueChange">valueChange</a>(), <a href="#rangeChange">rangeChange</a>() and
110<a href="#stepChange">stepChange</a>().
111<p> QRangeControl also provides a function called <a href="#bound">bound</a>() which lets
112you force arbitrary integers to be within the allowed range of the
113range control.
114<p> We recommend that all widgets that inherit QRangeControl provide
115at least a signal called valueChanged(); many widgets will want to
116provide addStep(), <a href="#addPage">addPage</a>(), substractStep() and substractPage()
117as slots.
118<p> Note that you must use multiple inheritance if you plan to
119implement a widget using QRangeControl because QRangeControl is
120not derived from <a href="qwidget.html">QWidget</a>.
121<p>See also <a href="misc.html">Miscellaneous Classes</a>.
122
123<hr><h2>Member Function Documentation</h2>
124<h3 class=fn><a name="QRangeControl"></a>QRangeControl::QRangeControl ()
125</h3>
126Constructs a range control with a minimum value of 0, maximum
127value of 99, line step of 1, page step of 10 and initial value 0.
128
129<h3 class=fn><a name="QRangeControl-2"></a>QRangeControl::QRangeControl ( int&nbsp;minValue, int&nbsp;maxValue, int&nbsp;lineStep, int&nbsp;pageStep, int&nbsp;value )
130</h3>
131Constructs a range control whose value can never be smaller than
132<em>minValue</em> or greater than <em>maxValue</em>, whose line step size is
133<em>lineStep</em> and page step size is <em>pageStep</em> and whose value is
134initially <em>value</em> (which is guaranteed to be in range using
135<a href="#bound">bound</a>()).
136
137<h3 class=fn><a name="~QRangeControl"></a>QRangeControl::~QRangeControl ()<tt> [virtual]</tt>
138</h3>
139Destroys the range control
140
141<h3 class=fn>void <a name="addLine"></a>QRangeControl::addLine ()
142</h3>
143Equivalent to <tt>setValue( value() + lineStep() )</tt>.
144<p> If the value is changed, then <a href="#valueChange">valueChange</a>() is called.
145<p> <p>See also <a href="#subtractLine">subtractLine</a>(), <a href="#addPage">addPage</a>(), and <a href="#setValue">setValue</a>().
146
147<h3 class=fn>void <a name="addPage"></a>QRangeControl::addPage ()
148</h3>
149Equivalent to <tt>setValue( value() + pageStep() )</tt>.
150<p> If the value is changed, then <a href="#valueChange">valueChange</a>() is called.
151<p> <p>See also <a href="#subtractPage">subtractPage</a>(), <a href="#addLine">addLine</a>(), and <a href="#setValue">setValue</a>().
152
153<h3 class=fn>int <a name="bound"></a>QRangeControl::bound ( int&nbsp;v ) const
154</h3>
155Forces the value <em>v</em> to be within the range from <a href="#minValue">minValue</a>() to
156<a href="#maxValue">maxValue</a>() inclusive, and returns the result.
157<p> This function is provided so that you can easily force other
158numbers than <a href="#value">value</a>() into the allowed range. You do not need to
159call it in order to use QRangeControl itself.
160<p> <p>See also <a href="#setValue">setValue</a>(), <a href="#value">value</a>(), <a href="#minValue">minValue</a>(), and <a href="#maxValue">maxValue</a>().
161
162<h3 class=fn>void <a name="directSetValue"></a>QRangeControl::directSetValue ( int&nbsp;value )<tt> [protected]</tt>
163</h3>
164Sets the range control <em>value</em> directly without calling
165<a href="#valueChange">valueChange</a>().
166<p> Forces the new <em>value</em> to be within the legal range.
167<p> You will rarely have to call this function. However, if you want
168to change the range control's value inside the overloaded method
169valueChange(), <a href="#setValue">setValue</a>() would call the function valueChange()
170again. To avoid this recursion you must use <a href="#directSetValue">directSetValue</a>()
171instead.
172<p> <p>See also <a href="#setValue">setValue</a>().
173
174<h3 class=fn>int <a name="lineStep"></a>QRangeControl::lineStep () const
175</h3>
176
177<p> Returns the line step.
178<p> <p>See also <a href="#setSteps">setSteps</a>() and <a href="#pageStep">pageStep</a>().
179
180<h3 class=fn>int <a name="maxValue"></a>QRangeControl::maxValue () const
181</h3>
182
183<p> Returns the maximum value of the range.
184<p> <p>See also <a href="#setMaxValue">setMaxValue</a>(), <a href="#setRange">setRange</a>(), and <a href="#minValue">minValue</a>().
185
186<h3 class=fn>int <a name="minValue"></a>QRangeControl::minValue () const
187</h3>
188
189<p> Returns the minimum value of the range.
190<p> <p>See also <a href="#setMinValue">setMinValue</a>(), <a href="#setRange">setRange</a>(), and <a href="#maxValue">maxValue</a>().
191
192<h3 class=fn>int <a name="pageStep"></a>QRangeControl::pageStep () const
193</h3>
194
195<p> Returns the page step.
196<p> <p>See also <a href="#setSteps">setSteps</a>() and <a href="#lineStep">lineStep</a>().
197
198<h3 class=fn>int <a name="positionFromValue"></a>QRangeControl::positionFromValue ( int&nbsp;logical_val, int&nbsp;span ) const<tt> [protected]</tt>
199</h3>
200Converts <em>logical_val</em> to a pixel position. <a href="#minValue">minValue</a>() maps to 0,
201<a href="#maxValue">maxValue</a>() maps to <em>span</em> and other values are distributed evenly
202in-between.
203<p> This function can handle the entire integer range without
204overflow, providing <em>span</em> is &lt;= 4096.
205<p> Calling this method is useful when actually drawing a range
206control such as a <a href="qscrollbar.html">QScrollBar</a> on-screen.
207<p> <p>See also <a href="#valueFromPosition">valueFromPosition</a>().
208
209<h3 class=fn>int <a name="prevValue"></a>QRangeControl::prevValue () const<tt> [protected]</tt>
210</h3>
211
212<p> Returns the previous value of the range control. "Previous value"
213means the value before the last change occurred. Setting a new
214range may affect the value, too, because the value is forced to be
215inside the specified range. When the range control is initially
216created, this is the same as <a href="#value">value</a>().
217<p> <a href="#prevValue">prevValue</a>() can be outside the current legal range if a call to
218<a href="#setRange">setRange</a>() causes the current value to change. For example, if the
219range was [0, 1000] and the current value is 500, setRange(0, 400)
220makes value() return 400 and prevValue() return 500.
221<p> <p>See also <a href="#value">value</a>() and <a href="#setRange">setRange</a>().
222
223<h3 class=fn>void <a name="rangeChange"></a>QRangeControl::rangeChange ()<tt> [virtual protected]</tt>
224</h3>
225This virtual function is called whenever the range control's range
226changes. You can reimplement it if you want to be notified when
227the range changes. The default implementation does nothing.
228<p> Note that this method is called after the range has changed.
229<p> <p>See also <a href="#setRange">setRange</a>(), <a href="#valueChange">valueChange</a>(), and <a href="#stepChange">stepChange</a>().
230
231<p>Reimplemented in <a href="qdial.html#rangeChange">QDial</a>, <a href="qslider.html#rangeChange">QSlider</a>, and <a href="qspinbox.html#rangeChange">QSpinBox</a>.
232<h3 class=fn>void <a name="setMaxValue"></a>QRangeControl::setMaxValue ( int&nbsp;maxVal )
233</h3>
234Sets the minimum value of the range to <em>maxVal</em>.
235<p> If necessary, the <a href="#minValue">minValue</a>() is adjusted so that the range remains
236valid.
237<p> <p>See also <a href="#maxValue">maxValue</a>() and <a href="#setMinValue">setMinValue</a>().
238
239<h3 class=fn>void <a name="setMinValue"></a>QRangeControl::setMinValue ( int&nbsp;minVal )
240</h3>
241Sets the minimum value of the range to <em>minVal</em>.
242<p> If necessary, the <a href="#maxValue">maxValue</a>() is adjusted so that the range remains
243valid.
244<p> <p>See also <a href="#minValue">minValue</a>() and <a href="#setMaxValue">setMaxValue</a>().
245
246<h3 class=fn>void <a name="setRange"></a>QRangeControl::setRange ( int&nbsp;minValue, int&nbsp;maxValue )
247</h3>
248Sets the range control's minimum value to <em>minValue</em> and its
249maximum value to <em>maxValue</em>.
250<p> Calls the virtual <a href="#rangeChange">rangeChange</a>() function if one or both of the new
251minimum and maximum values are different from the previous
252setting. Calls the virtual <a href="#valueChange">valueChange</a>() function if the current
253value is adjusted because it was outside the new range.
254<p> If <em>maxValue</em> is smaller than <em>minValue</em>, <em>minValue</em> becomes
255the only legal value.
256<p> <p>See also <a href="#minValue">minValue</a>() and <a href="#maxValue">maxValue</a>().
257
258<p>Examples: <a href="listbox-example.html#x1441">listbox/listbox.cpp</a>, <a href="tutorial1-12.html#x2387">t12/lcdrange.cpp</a>, <a href="tutorial1-05.html#x2315">t5/main.cpp</a>, <a href="tutorial1-06.html#x2325">t6/main.cpp</a>, <a href="tutorial1-08.html#x2334">t8/lcdrange.cpp</a>, and <a href="xform-example.html#x1250">xform/xform.cpp</a>.
259<h3 class=fn>void <a name="setSteps"></a>QRangeControl::setSteps ( int&nbsp;lineStep, int&nbsp;pageStep )
260</h3>
261Sets the range's line step to <em>lineStep</em> and page step to <em>pageStep</em>.
262<p> Calls the virtual <a href="#stepChange">stepChange</a>() function if the new line step
263or page step are different from the previous settings.
264<p> <p>See also <a href="#lineStep">lineStep</a>(), <a href="#pageStep">pageStep</a>(), and <a href="#setRange">setRange</a>().
265
266<h3 class=fn>void <a name="setValue"></a>QRangeControl::setValue ( int&nbsp;value )
267</h3>
268Sets the range control's value to <em>value</em> and forces it to be
269within the legal range.
270<p> Calls the virtual <a href="#valueChange">valueChange</a>() function if the new value is
271different from the previous value. The old value can still be
272retrieved using <a href="#prevValue">prevValue</a>().
273<p> <p>See also <a href="#value">value</a>().
274
275<h3 class=fn>void <a name="stepChange"></a>QRangeControl::stepChange ()<tt> [virtual protected]</tt>
276</h3>
277This virtual function is called whenever the range control's
278line or page step settings change. You can reimplement it if you
279want to be notified when the step changes. The default
280implementation does nothing.
281<p> Note that this method is called after a step setting has changed.
282<p> <p>See also <a href="#setSteps">setSteps</a>(), <a href="#rangeChange">rangeChange</a>(), and <a href="#valueChange">valueChange</a>().
283
284<h3 class=fn>void <a name="subtractLine"></a>QRangeControl::subtractLine ()
285</h3>
286Equivalent to <tt>setValue( value() - lineStep() )</tt>.
287<p> If the value is changed, then <a href="#valueChange">valueChange</a>() is called.
288<p> <p>See also <a href="#addLine">addLine</a>(), <a href="#subtractPage">subtractPage</a>(), and <a href="#setValue">setValue</a>().
289
290<h3 class=fn>void <a name="subtractPage"></a>QRangeControl::subtractPage ()
291</h3>
292Equivalent to <tt>setValue( value() - pageStep() )</tt>.
293<p> If the value is changed, then <a href="#valueChange">valueChange</a>() is called.
294<p> <p>See also <a href="#addPage">addPage</a>(), <a href="#subtractLine">subtractLine</a>(), and <a href="#setValue">setValue</a>().
295
296<h3 class=fn>int <a name="value"></a>QRangeControl::value () const
297</h3>
298
299<p> Returns the current range control value. This is guaranteed to be
300within the range [minValue(), <a href="#maxValue">maxValue</a>()].
301<p> <p>See also <a href="#setValue">setValue</a>() and <a href="#prevValue">prevValue</a>().
302
303<h3 class=fn>void <a name="valueChange"></a>QRangeControl::valueChange ()<tt> [virtual protected]</tt>
304</h3>
305This virtual function is called whenever the range control value
306changes. You can reimplement it if you want to be notified when
307the value changes. The default implementation does nothing.
308<p> Note that this method is called after the value has changed. The
309previous value can be retrieved using <a href="#prevValue">prevValue</a>().
310<p> <p>See also <a href="#setValue">setValue</a>(), <a href="#addPage">addPage</a>(), <a href="#subtractPage">subtractPage</a>(), <a href="#addLine">addLine</a>(), <a href="#subtractLine">subtractLine</a>(), <a href="#rangeChange">rangeChange</a>(), and <a href="#stepChange">stepChange</a>().
311
312<p>Reimplemented in <a href="qdial.html#valueChange">QDial</a>, <a href="qslider.html#valueChange">QSlider</a>, and <a href="qspinbox.html#valueChange">QSpinBox</a>.
313<h3 class=fn>int <a name="valueFromPosition"></a>QRangeControl::valueFromPosition ( int&nbsp;pos, int&nbsp;span ) const<tt> [protected]</tt>
314</h3>
315Converts the pixel position <em>pos</em> to a value. 0 maps to
316<a href="#minValue">minValue</a>(), <em>span</em> maps to <a href="#maxValue">maxValue</a>() and other values are
317distributed evenly in-between.
318<p> This function can handle the entire integer range without
319overflow.
320<p> Calling this method is useful if you actually implemented a range
321control widget such as <a href="qscrollbar.html">QScrollBar</a> and want to handle mouse press
322events. This function then maps screen coordinates to the logical
323values.
324<p> <p>See also <a href="#positionFromValue">positionFromValue</a>().
325
326<!-- eof -->
327<hr><p>
328This file is part of the <a href="index.html">Qt toolkit</a>.
329Copyright &copy; 1995-2007
330<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
331<table width=100% cellspacing=0 border=0><tr>
332<td>Copyright &copy; 2007
333<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
334<td align=right><div align=right>Qt 3.3.8</div>
335</table></div></address></body>
336</html>
Note: See TracBrowser for help on using the repository browser.