1QSpinBox(3qt)                                                    QSpinBox(3qt)
2
3
4

NAME

6       QSpinBox - Spin box widget (spin button)
7

SYNOPSIS

9       #include <qspinbox.h>
10
11       Inherits QWidget and QRangeControl.
12
13   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
41   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
49   Signals
50       void valueChanged ( int value )
51       void valueChanged ( const QString & valueText )
52
53   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
69   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
80   Protected Slots
81       void textChanged ()
82

DESCRIPTION

84       The QSpinBox class provides a spin box widget (spin button).
85
86       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
92       Every time the value changes QSpinBox emits the valueChanged() signal.
93       The current value can be fetched with value() and set with setValue().
94
95       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
103       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
108       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
116       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
121       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
125       The default QWidget::focusPolicy() is StrongFocus.
126
127       If using prefix(), suffix() and specialValueText() don't provide enough
128       control, you can ignore them and subclass QSpinBox instead.
129
130       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
136       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
140               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
160                                   [Image Omitted]
161
162                                   [Image Omitted]
163
164       See also QScrollBar, QSlider, GUI Design Handbook: Spin Box, and Basic
165       Widgets.
166
167   Member Type Documentation

QSpinBox::ButtonSymbols

169       This enum type determines what the buttons in a spin box show.
170
171       QSpinBox::UpDownArrows - the buttons show little arrows in the classic
172       style.
173
174       QSpinBox::PlusMinus - the buttons show + and - symbols.
175
176       See also QSpinBox::buttonSymbols.
177

MEMBER FUNCTION DOCUMENTATION

QSpinBox::QSpinBox ( QWidget * parent = 0, const char * name = 0 )

180       Constructs a spin box with the default QRangeControl range and step
181       values. It is called name and has parent parent.
182
183       See also minValue, maxValue, setRange(), lineStep, and setSteps().
184

QSpinBox::QSpinBox ( int minValue, int maxValue, int step = 1, QWidget *

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
191       The spin box is called name and has parent parent.
192
193       See also minValue, maxValue, setRange(), lineStep, and setSteps().
194

QSpinBox::~QSpinBox ()

196       Destroys the spin box, freeing all memory and other resources.
197

ButtonSymbols QSpinBox::buttonSymbols () const

199       Returns the current button symbol mode. See the "buttonSymbols"
200       property for details.
201

QString QSpinBox::cleanText () const [virtual]

203       Returns the spin box's text with no prefix(), suffix() or leading or
204       trailing whitespace. See the "cleanText" property for details.
205

QString QSpinBox::currentValueText () [protected]

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

QRect QSpinBox::downRect () const

212       Returns the geometry of the "down" button.
213

QLineEdit * QSpinBox::editor () const [protected]

215       Returns a pointer to the embedded QLineEdit.
216

bool QSpinBox::eventFilter ( QObject * o, QEvent * ev ) [virtual protected]

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
222       Reimplemented from QObject.
223

void QSpinBox::interpretText () [virtual protected]

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
229       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
233       See also editor().
234

int QSpinBox::lineStep () const

236       Returns the line step. See the "lineStep" property for details.
237

int QSpinBox::mapTextToValue ( bool * ok ) [virtual protected]

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
245       Subclasses that need to display spin box values in a non-numeric way
246       need to reimplement this function.
247
248       Note that Qt handles specialValueText() separately; this function is
249       only concerned with the other values.
250
251       The default implementation tries to interpret the text() as an integer
252       in the standard way and returns the integer value.
253
254       See also interpretText() and mapValueToText().
255

QString QSpinBox::mapValueToText ( int v ) [virtual protected]

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
262       Note that Qt does not call this function for specialValueText() and
263       that neither prefix() nor suffix() are included in the return value.
264
265       If you reimplement this, you may also need to reimplement
266       mapTextToValue().
267
268       See also updateDisplay() and mapTextToValue().
269

int QSpinBox::maxValue () const

271       Returns the maximum value of the spin box. See the "maxValue" property
272       for details.
273

int QSpinBox::minValue () const

275       Returns the minimum value of the spin box. See the "minValue" property
276       for details.
277

QString QSpinBox::prefix () const [virtual]

279       Returns the spin box's prefix. See the "prefix" property for details.
280

void QSpinBox::rangeChange () [virtual protected]

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
286       Reimplemented from QRangeControl.
287

void QSpinBox::selectAll () [virtual slot]

289       Selects all the text in the spin box's editor.
290

void QSpinBox::setButtonSymbols ( ButtonSymbols ) [virtual]

292       Sets the current button symbol mode. See the "buttonSymbols" property
293       for details.
294

void QSpinBox::setLineStep ( int )

296       Sets the line step. See the "lineStep" property for details.
297

void QSpinBox::setMaxValue ( int )

299       Sets the maximum value of the spin box. See the "maxValue" property for
300       details.
301

void QSpinBox::setMinValue ( int )

303       Sets the minimum value of the spin box. See the "minValue" property for
304       details.
305

void QSpinBox::setPrefix ( const QString & text ) [virtual slot]

307       Sets the spin box's prefix to text. See the "prefix" property for
308       details.
309

void QSpinBox::setSpecialValueText ( const QString & text ) [virtual]

311       Sets the special-value text to text. See the "specialValueText"
312       property for details.
313

void QSpinBox::setSuffix ( const QString & text ) [virtual slot]

315       Sets the suffix of the spin box to text. See the "suffix" property for
316       details.
317

void QSpinBox::setValidator ( const QValidator * v ) [virtual]

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
323       Use setValidator(0) to turn off input validation (entered input will
324       still be kept within the spin box's range).
325

void QSpinBox::setValue ( int value ) [virtual slot]

327       Sets the value of the spin box to value. See the "value" property for
328       details.
329

void QSpinBox::setWrapping ( bool on ) [virtual]

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

QString QSpinBox::specialValueText () const

336       Returns the special-value text. See the "specialValueText" property for
337       details.
338

void QSpinBox::stepDown () [virtual slot]

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
344       See also stepUp(), subtractLine(), lineStep, setSteps(), value, and
345       value.
346

void QSpinBox::stepUp () [virtual slot]

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
352       See also stepDown(), addLine(), lineStep, setSteps(), value, and value.
353

QString QSpinBox::suffix () const [virtual]

355       Returns the suffix of the spin box. See the "suffix" property for
356       details.
357

QString QSpinBox::text () const

359       Returns the spin box's text, including any prefix() and suffix(). See
360       the "text" property for details.
361

void QSpinBox::textChanged () [protected slot]

363       This slot is called whenever the user edits the spin box's text.
364

QRect QSpinBox::upRect () const

366       Returns the geometry of the "up" button.
367

void QSpinBox::updateDisplay () [virtual protected]

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
373       See also mapValueToText().
374

const QValidator * QSpinBox::validator () const

376       Returns the validator that constrains editing for this spin box if
377       there is any; otherwise returns 0.
378
379       See also setValidator() and QValidator.
380

int QSpinBox::value () const

382       Returns the value of the spin box. See the "value" property for
383       details.
384

void QSpinBox::valueChange () [virtual protected]

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
391       Reimplemented from QRangeControl.
392

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

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
399       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
403       See also value.
404
405       Examples:
406

void QSpinBox::valueChanged ( const QString & valueText ) [signal]

408       This is an overloaded member function, provided for convenience. It
409       behaves essentially like the above function.
410
411       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
416       The valueText parameter is the same string that is displayed in the
417       edit field of the spin box.
418
419       See also value, prefix, suffix, and specialValueText.
420

bool QSpinBox::wrapping () const

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
426   Property Documentation

ButtonSymbols buttonSymbols

428       This property holds the current button symbol mode.
429
430       The possible values can be either UpDownArrows or PlusMinus. The
431       default is UpDownArrows.
432
433       See also ButtonSymbols.
434
435       Set this property's value with setButtonSymbols() and get this
436       property's value with buttonSymbols().
437

QString cleanText

439       This property holds the spin box's text with no prefix(), suffix() or
440       leading or trailing whitespace.
441
442       Get this property's value with cleanText().
443
444       See also text, prefix, and suffix.
445

int lineStep

447       This property holds the line step.
448
449       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
452       The setLineStep() function calls the virtual stepChange() function if
453       the new line step is different from the previous setting.
454
455       See also QRangeControl::setSteps() and setRange().
456
457       Set this property's value with setLineStep() and get this property's
458       value with lineStep().
459

int maxValue

461       This property holds the maximum value of the spin box.
462
463       When setting this property, QSpinBox::minValue is adjusted, if
464       necessary, to ensure that the range remains valid.
465
466       See also setRange() and specialValueText.
467
468       Set this property's value with setMaxValue() and get this property's
469       value with maxValue().
470

int minValue

472       This property holds the minimum value of the spin box.
473
474       When setting this property, QSpinBox::maxValue is adjusted, if
475       necessary, to ensure that the range remains valid.
476
477       See also setRange() and specialValueText.
478
479       Set this property's value with setMinValue() and get this property's
480       value with minValue().
481

QString prefix

483       This property holds the spin box's prefix.
484
485       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
489               sb->setPrefix( "$" );
490
491       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
495       If no prefix is set, prefix() returns QString::null.
496
497       See also suffix.
498
499       Set this property's value with setPrefix() and get this property's
500       value with prefix().
501

QString specialValueText

503       This property holds the special-value text.
504
505       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
509       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
513               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
521       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
524       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
528       If no special-value text is set, specialValueText() returns
529       QString::null.
530
531       Set this property's value with setSpecialValueText() and get this
532       property's value with specialValueText().
533

QString suffix

535       This property holds the suffix of the spin box.
536
537       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
540               sb->setSuffix( " km" );
541
542       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
546       If no suffix is set, suffix() returns a QString::null.
547
548       See also prefix.
549
550       Set this property's value with setSuffix() and get this property's
551       value with suffix().
552

QString text

554       This property holds the spin box's text, including any prefix() and
555       suffix().
556
557       There is no default text.
558
559       See also value.
560
561       Get this property's value with text().
562

int value

564       This property holds the value of the spin box.
565
566       Set this property's value with setValue() and get this property's value
567       with value().
568
569       See also QRangeControl::setValue().
570

bool wrapping

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
575       By default, wrapping is turned off.
576
577       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
583       See also minValue, maxValue, and setRange().
584
585       Set this property's value with setWrapping() and get this property's
586       value with wrapping().
587
588

SEE ALSO

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

AUTHOR

599       Generated automatically from the source code.
600

BUGS

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
606       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
612       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).
615
616
617
618Trolltech AS                    2 February 2007                  QSpinBox(3qt)
Impressum