1QSpinBox(3qt) QSpinBox(3qt)
2
6 QSpinBox - Spin box widget (spin button)
7
9 #include <qspinbox.h>
10 Inherits QWidget and QRangeControl.
12 Public Members
14 QSpinBox ( QWidget * parent = 0, const char * name = 0 )
15 QSpinBox ( int minValue, int maxValue, int step = 1, QWidget * parent =
16 0, const char * name = 0 )
17 ~QSpinBox ()
18 QString text () const
19 virtual QString prefix () const
20 virtual QString suffix () const
21 virtual QString cleanText () const
22 virtual void setSpecialValueText ( const QString & text )
23 QString specialValueText () const
24 virtual void setWrapping ( bool on )
25 bool wrapping () const
26 enum ButtonSymbols { UpDownArrows, PlusMinus }
27 virtual void setButtonSymbols ( ButtonSymbols )
28 ButtonSymbols buttonSymbols () const
29 virtual void setValidator ( const QValidator * v )
30 const QValidator * validator () const
31 int minValue () const
32 int maxValue () const
33 void setMinValue ( int )
34 void setMaxValue ( int )
35 int lineStep () const
36 void setLineStep ( int )
37 int value () const
38 QRect upRect () const
39 QRect downRect () const
40 Public Slots
42 virtual void setValue ( int value )
43 virtual void setPrefix ( const QString & text )
44 virtual void setSuffix ( const QString & text )
45 virtual void stepUp ()
46 virtual void stepDown ()
47 virtual void selectAll ()
48 Signals
50 void valueChanged ( int value )
51 void valueChanged ( const QString & valueText )
52 Properties
54 ButtonSymbols buttonSymbols - the current button symbol mode
55 QString cleanText - the spin box's text with no prefix(), suffix() or
56 leading or trailing whitespace (read only)
57 int lineStep - the line step
58 int maxValue - the maximum value of the spin box
59 int minValue - the minimum value of the spin box
60 QString prefix - the spin box's prefix
61 QString specialValueText - the special-value text
62 QString suffix - the suffix of the spin box
63 QString text - the spin box's text, including any prefix() and suffix()
64 (read only)
65 int value - the value of the spin box
66 bool wrapping - whether it is possible to step the value from the
67 highest value to the lowest value and vice versa
68 Protected Members
70 virtual QString mapValueToText ( int v )
71 virtual int mapTextToValue ( bool * ok )
72 QString currentValueText ()
73 virtual void updateDisplay ()
74 virtual void interpretText ()
75 QLineEdit * editor () const
76 virtual void valueChange ()
77 virtual void rangeChange ()
78 virtual bool eventFilter ( QObject * o, QEvent * ev )
79 Protected Slots
81 void textChanged ()
82
84 The QSpinBox class provides a spin box widget (spin button).
85 QSpinBox allows the user to choose a value either by clicking the
87 up/down buttons to increase/decrease the value currently displayed or
88 by typing the value directly into the spin box. If the value is entered
89 directly into the spin box, Enter (or Return) must be pressed to apply
90 the new value. The value is usually an integer.
91 Every time the value changes QSpinBox emits the valueChanged() signal.
93 The current value can be fetched with value() and set with setValue().
94 The spin box keeps the value within a numeric range, and to multiples
96 of the lineStep() size (see QRangeControl for details). Clicking the
97 up/down buttons or using the keyboard accelerator's up and down arrows
98 will increase or decrease the current value in steps of size
99 lineStep(). The minimum and maximum value and the step size can be set
100 using one of the constructors, and can be changed later with
101 setMinValue(), setMaxValue() and setLineStep().
102 Most spin boxes are directional, but QSpinBox can also operate as a
104 circular spin box, i.e. if the range is 0-99 and the current value is
105 99, clicking "up" will give 0. Use setWrapping() if you want circular
106 behavior.
107 The displayed value can be prepended and appended with arbitrary
109 strings indicating, for example, currency or the unit of measurement.
110 See setPrefix() and setSuffix(). The text in the spin box is retrieved
111 with text() (which includes any prefix() and suffix()), or with
112 cleanText() (which has no prefix(), no suffix() and no leading or
113 trailing whitespace). currentValueText() returns the spin box's current
114 value as text.
115 Normally the spin box displays up and down arrows in the buttons. You
117 can use setButtonSymbols() to change the display to show + and -
118 symbols if you prefer. In either case the up and down arrow keys work
119 as expected.
120 It is often desirable to give the user a special (often default) choice
122 in addition to the range of numeric values. See setSpecialValueText()
123 for how to do this with QSpinBox.
124 The default QWidget::focusPolicy() is StrongFocus.
126 If using prefix(), suffix() and specialValueText() don't provide enough
128 control, you can ignore them and subclass QSpinBox instead.
129 QSpinBox can easily be subclassed to allow the user to input things
131 other than an integer value as long as the allowed input can be mapped
132 to a range of integers. This can be done by overriding the virtual
133 functions mapValueToText() and mapTextToValue(), and setting another
134 suitable validator using setValidator().
135 For example, these functions could be changed so that the user provided
137 values from 0.0 to 10.0, or -1 to signify 'Auto', while the range of
138 integers used inside the program would be -1 to 100:
139 class MySpinBox : public QSpinBox
141 {
142 Q_OBJECT
143 public:
144 ...
145 QString mapValueToText( int value )
146 {
147 if ( value == -1 ) // special case
148 return QString( "Auto" );
149 return QString( "%1.%2" ) // 0.0 to 10.0
150 .arg( value / 10 ).arg( value % 10 );
151 }
152 int mapTextToValue( bool *ok )
153 {
154 if ( text() == "Auto" ) // special case
155 return -1;
156 return (int) ( 10 * text().toFloat() ); // 0 to 100
157 }
158 };
159 [Image Omitted]
161 [Image Omitted]
163 See also QScrollBar, QSlider, GUI Design Handbook: Spin Box, and Basic
165 Widgets.
166 Member Type Documentation
169 This enum type determines what the buttons in a spin box show.
170 QSpinBox::UpDownArrows - the buttons show little arrows in the classic
172 style.
173 QSpinBox::PlusMinus - the buttons show + and - symbols.
175 See also QSpinBox::buttonSymbols.
177
180 Constructs a spin box with the default QRangeControl range and step
181 values. It is called name and has parent parent.
182 See also minValue, maxValue, setRange(), lineStep, and setSteps().
184
186 parent = 0, const char * name = 0 )
187 Constructs a spin box that allows values from minValue to maxValue
188 inclusive, with step amount step. The value is initially set to
189 minValue.
190 The spin box is called name and has parent parent.
192 See also minValue, maxValue, setRange(), lineStep, and setSteps().
194
196 Destroys the spin box, freeing all memory and other resources.
197
199 Returns the current button symbol mode. See the "buttonSymbols"
200 property for details.
201
203 Returns the spin box's text with no prefix(), suffix() or leading or
204 trailing whitespace. See the "cleanText" property for details.
205
207 Returns the full text calculated from the current value, including any
208 prefix and suffix. If there is special value text and the value is
209 minValue() the specialValueText() is returned.
210
212 Returns the geometry of the "down" button.
213
215 Returns a pointer to the embedded QLineEdit.
216
218 Intercepts and handles the events coming to the embedded QLineEdit that
219 have special meaning for the QSpinBox. The object is passed as o and
220 the event is passed as ev.
221 Reimplemented from QObject.
223
225 QSpinBox calls this after the user has manually edited the contents of
226 the spin box (i.e. by typing in the embedded QLineEdit, rather than
227 using the up/down buttons/keys).
228 The default implementation of this function interprets the new text
230 using mapTextToValue(). If mapTextToValue() is successful, it changes
231 the spin box's value; if not, the value is left unchanged.
232 See also editor().
234
236 Returns the line step. See the "lineStep" property for details.
237
239 This virtual function is used by the spin box whenever it needs to
240 interpret text entered by the user as a value. The text is available as
241 text() and as cleanText(), and this function must parse it if possible.
242 If ok is not 0: if it parses the text successfully, *ok is set to TRUE;
243 otherwise *ok is set to FALSE.
244 Subclasses that need to display spin box values in a non-numeric way
246 need to reimplement this function.
247 Note that Qt handles specialValueText() separately; this function is
249 only concerned with the other values.
250 The default implementation tries to interpret the text() as an integer
252 in the standard way and returns the integer value.
253 See also interpretText() and mapValueToText().
255
257 This virtual function is used by the spin box whenever it needs to
258 display value v. The default implementation returns a string containing
259 v printed in the standard way. Reimplementations may return anything.
260 (See the example in the detailed description.)
261 Note that Qt does not call this function for specialValueText() and
263 that neither prefix() nor suffix() are included in the return value.
264 If you reimplement this, you may also need to reimplement
266 mapTextToValue().
267 See also updateDisplay() and mapTextToValue().
269
271 Returns the maximum value of the spin box. See the "maxValue" property
272 for details.
273
275 Returns the minimum value of the spin box. See the "minValue" property
276 for details.
277
279 Returns the spin box's prefix. See the "prefix" property for details.
280
282 This virtual function is called by QRangeControl whenever the range has
283 changed. It adjusts the default validator and updates the display; if
284 you need additional processing, you can reimplement this function.
285 Reimplemented from QRangeControl.
287
289 Selects all the text in the spin box's editor.
290
292 Sets the current button symbol mode. See the "buttonSymbols" property
293 for details.
294
296 Sets the line step. See the "lineStep" property for details.
297
299 Sets the maximum value of the spin box. See the "maxValue" property for
300 details.
301
303 Sets the minimum value of the spin box. See the "minValue" property for
304 details.
305
307 Sets the spin box's prefix to text. See the "prefix" property for
308 details.
309
311 Sets the special-value text to text. See the "specialValueText"
312 property for details.
313
315 Sets the suffix of the spin box to text. See the "suffix" property for
316 details.
317
319 Sets the validator to v. The validator controls what keyboard input is
320 accepted when the user is editing in the value field. The default is to
321 use a suitable QIntValidator.
322 Use setValidator(0) to turn off input validation (entered input will
324 still be kept within the spin box's range).
325
327 Sets the value of the spin box to value. See the "value" property for
328 details.
329
331 Sets whether it is possible to step the value from the highest value to
332 the lowest value and vice versa to on. See the "wrapping" property for
333 details.
334
336 Returns the special-value text. See the "specialValueText" property for
337 details.
338
340 Decreases the spin box's value one lineStep(), wrapping as necessary if
341 wrapping() is TRUE. This is the same as clicking on the pointing-down
342 button and can be used for keyboard accelerators, for example.
343 See also stepUp(), subtractLine(), lineStep, setSteps(), value, and
345 value.
346
348 Increases the spin box's value by one lineStep(), wrapping as necessary
349 if wrapping() is TRUE. This is the same as clicking on the pointing-up
350 button and can be used for keyboard accelerators, for example.
351 See also stepDown(), addLine(), lineStep, setSteps(), value, and value.
353
355 Returns the suffix of the spin box. See the "suffix" property for
356 details.
357
359 Returns the spin box's text, including any prefix() and suffix(). See
360 the "text" property for details.
361
363 This slot is called whenever the user edits the spin box's text.
364
366 Returns the geometry of the "up" button.
367
369 Updates the contents of the embedded QLineEdit to reflect the current
370 value using mapValueToText(). Also enables/disables the up/down push
371 buttons accordingly.
372 See also mapValueToText().
374
376 Returns the validator that constrains editing for this spin box if
377 there is any; otherwise returns 0.
378 See also setValidator() and QValidator.
380
382 Returns the value of the spin box. See the "value" property for
383 details.
384
386 This virtual function is called by QRangeControl whenever the value has
387 changed. The QSpinBox reimplementation updates the display and emits
388 the valueChanged() signals; if you need additional processing, either
389 reimplement this or connect to one of the valueChanged() signals.
390 Reimplemented from QRangeControl.
392
394 This signal is emitted every time the value of the spin box changes;
395 the new value is passed in value. This signal will be emitted as a
396 result of a call to setValue(), or because the user changed the value
397 by using a keyboard accelerator or mouse click, etc.
398 Note that the valueChanged() signal is emitted every time, not just for
400 the "last" step; i.e. if the user clicks "up" three times, this signal
401 is emitted three times.
402 See also value.
404 Examples:
406
408 This is an overloaded member function, provided for convenience. It
409 behaves essentially like the above function.
410 This signal is emitted whenever the valueChanged( int ) signal is
412 emitted, i.e. every time the value of the spin box changes (whatever
413 the cause, e.g. by setValue(), by a keyboard accelerator, by mouse
414 clicks, etc.).
415 The valueText parameter is the same string that is displayed in the
417 edit field of the spin box.
418 See also value, prefix, suffix, and specialValueText.
420
422 Returns TRUE if it is possible to step the value from the highest value
423 to the lowest value and vice versa; otherwise returns FALSE. See the
424 "wrapping" property for details.
425 Property Documentation
428 This property holds the current button symbol mode.
429 The possible values can be either UpDownArrows or PlusMinus. The
431 default is UpDownArrows.
432 See also ButtonSymbols.
434 Set this property's value with setButtonSymbols() and get this
436 property's value with buttonSymbols().
437
439 This property holds the spin box's text with no prefix(), suffix() or
440 leading or trailing whitespace.
441 Get this property's value with cleanText().
443 See also text, prefix, and suffix.
445
447 This property holds the line step.
448 When the user uses the arrows to change the spin box's value the value
450 will be incremented/decremented by the amount of the line step.
451 The setLineStep() function calls the virtual stepChange() function if
453 the new line step is different from the previous setting.
454 See also QRangeControl::setSteps() and setRange().
456 Set this property's value with setLineStep() and get this property's
458 value with lineStep().
459
461 This property holds the maximum value of the spin box.
462 When setting this property, QSpinBox::minValue is adjusted, if
464 necessary, to ensure that the range remains valid.
465 See also setRange() and specialValueText.
467 Set this property's value with setMaxValue() and get this property's
469 value with maxValue().
470
472 This property holds the minimum value of the spin box.
473 When setting this property, QSpinBox::maxValue is adjusted, if
475 necessary, to ensure that the range remains valid.
476 See also setRange() and specialValueText.
478 Set this property's value with setMinValue() and get this property's
480 value with minValue().
481
483 This property holds the spin box's prefix.
484 The prefix is prepended to the start of the displayed value. Typical
486 use is to display a unit of measurement or a currency symbol. For
487 example:
488 sb->setPrefix( "$" );
490 To turn off the prefix display, set this property to an empty string.
492 The default is no prefix. The prefix is not displayed for the
493 minValue() if specialValueText() is not empty.
494 If no prefix is set, prefix() returns QString::null.
496 See also suffix.
498 Set this property's value with setPrefix() and get this property's
500 value with prefix().
501
503 This property holds the special-value text.
504 If set, the spin box will display this text instead of a numeric value
506 whenever the current value is equal to minVal(). Typical use is to
507 indicate that this choice has a special (default) meaning.
508 For example, if your spin box allows the user to choose the margin
510 width in a print dialog and your application is able to automatically
511 choose a good margin width, you can set up the spin box like this:
512 QSpinBox marginBox( -1, 20, 1, parent, "marginBox" );
514 marginBox->setSuffix( " mm" );
515 marginBox->setSpecialValueText( "Auto" );
516 The user will then be able to choose a margin width from 0-20
517 millimeters or select "Auto" to leave it to the application to choose.
518 Your code must then interpret the spin box value of -1 as the user
519 requesting automatic margin width.
520 All values are displayed with the prefix() and suffix() (if set),
522 except for the special value, which only shows the special value text.
523 To turn off the special-value text display, call this function with an
525 empty string. The default is no special-value text, i.e. the numeric
526 value is shown as usual.
527 If no special-value text is set, specialValueText() returns
529 QString::null.
530 Set this property's value with setSpecialValueText() and get this
532 property's value with specialValueText().
533
535 This property holds the suffix of the spin box.
536 The suffix is appended to the end of the displayed value. Typical use
538 is to display a unit of measurement or a currency symbol. For example:
539 sb->setSuffix( " km" );
541 To turn off the suffix display, set this property to an empty string.
543 The default is no suffix. The suffix is not displayed for the
544 minValue() if specialValueText() is not empty.
545 If no suffix is set, suffix() returns a QString::null.
547 See also prefix.
549 Set this property's value with setSuffix() and get this property's
551 value with suffix().
552
554 This property holds the spin box's text, including any prefix() and
555 suffix().
556 There is no default text.
558 See also value.
560 Get this property's value with text().
562
564 This property holds the value of the spin box.
565 Set this property's value with setValue() and get this property's value
567 with value().
568 See also QRangeControl::setValue().
570
572 This property holds whether it is possible to step the value from the
573 highest value to the lowest value and vice versa.
574 By default, wrapping is turned off.
576 If you have a range of 0..100 and wrapping is off when the user reaches
578 100 and presses the Up Arrow nothing will happen; but if wrapping is on
579 the value will change from 100 to 0, then to 1, etc. When wrapping is
580 on, navigating past the highest value takes you to the lowest and vice
581 versa.
582 See also minValue, maxValue, and setRange().
584 Set this property's value with setWrapping() and get this property's
586 value with wrapping().
587
590 http://doc.trolltech.com/qspinbox.html
591 http://www.trolltech.com/faq/tech.html
592
594 Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com. See the
595 license file included in the distribution for a complete license
596 statement.
597
599 Generated automatically from the source code.
600
602 If you find a bug in Qt, please report it as described in
603 http://doc.trolltech.com/bughowto.html. Good bug reports help us to
604 help you. Thank you.
605 The definitive Qt documentation is provided in HTML format; it is
607 located at $QTDIR/doc/html and can be read using Qt Assistant or with a
608 web browser. This man page is provided as a convenience for those users
609 who prefer man pages, although this format is not officially supported
610 by Trolltech.
611 If you find errors in this manual page, please report them to qt-
613 bugs@trolltech.com. Please include the name of the manual page
614 (qspinbox.3qt) and the Qt version (3.3.8).
615Trolltech AS 2 February 2007 QSpinBox(3qt)