QSpinBox(3qt)QSpinBox(3qt)NAMEQSpinBox - Spin box widget, sometimes called up-down
widget, little arrows widget or spin button
#include <qspinbox.h>
Inherits QFrame and QRangeControl.
Public Members
QSpinBox ( QWidget * parent = 0, const char * name = 0 )
QSpinBox ( int minValue, int maxValue, int step = 1,
QWidget * parent = 0, const char * name = 0 )
~QSpinBox ()
QString text () const
virtual QString prefix () const
virtual QString suffix () const
virtual QString cleanText () const
virtual void setSpecialValueText ( const QString & text )
QString specialValueText () const
virtual void setWrapping ( bool on )
bool wrapping () const
enum ButtonSymbols { UpDownArrows, PlusMinus }
void setButtonSymbols ( ButtonSymbols )
ButtonSymbols buttonSymbols () const
virtual void setValidator ( const QValidator * v )
const QValidator* validator () const
void setMinValue ( int )
void setMaxValue ( int )
void setLineStep ( int )
Public Slots
virtual void setValue ( int value )
virtual void setPrefix ( const QString & text )
virtual void setSuffix ( const QString & text )
virtual void stepUp ()
virtual void stepDown ()
Signals
void valueChanged ( int value )
void valueChanged ( const QString & valueText )
Protected Members
virtual QString mapValueToText ( int value )
virtual int mapTextToValue ( bool * ok )
QString currentValueText ()
virtual void updateDisplay ()
virtual void interpretText ()
QPushButton* upButton () const
QPushButton* downButton () const
QLineEdit* editor () const
virtual void valueChange ()
virtual void rangeChange ()
virtual bool eventFilter ( QObject * obj, QEvent * ev )
Trolltech AS 13 June 2001 1
QSpinBox(3qt)QSpinBox(3qt)
Protected Slots
void textChanged ()
Properties
l l l l l
- - - - -
l l l l l.
Type Name READ WRITE Options
QString text text
QString prefix prefix setPrefix
QString suffix suffix setSuffix
QString cleanText cleanText
QString specialValueText specialValueText setSpecialValueText
bool wrapping wrapping setWrapping
ButtonSymbols buttonSymbols buttonSymbols setButtonSymbols
int maxValue maxValue setMaxValue
int minValue minValue setMinValue
int lineStep lineStep setLineStep
int value value setValue
DESCRIPTION
The QSpinBox class provides a spin box widget, sometimes
called up-down widget, little arrows widget or spin
button.
QSpinBox allows the user to choose a value, either by
clicking the up/down buttons to increase/decrease the
value currently displayed, or by typing the value directly
into the spin box. Usually the value is an integer.
Every time the value changes, QSpinBox emits the
valueChanged() signal. The current value can be fetched
with value() and set with setValue().
The spin box clamps the value within a numeric range, see
QRangeControl for details. Clicking the up/down down
buttons (or using the keyboard accelerators: Up-arrow and
Down-arrow) will increase or decrease the current value in
steps of size lineStep().
Most spin boxes are directional, but QSpinBox can also
operate as a circular spin box, i.e. if the range is 0-99
and the current value is 99, clicking Up will give 0. Use
setWrapping() if you want circular behavior.
The displayed value can be prepended and/or appended with
an arbitrary string indicating for example the unit of
measurement. See setPrefix() and setSuffix().
Normally, the spin box displays up and down arrows in the
buttons. You can use setButtonSymbols() to change the
display to show + and - symbols, if this is clearer for
your intended purpose. In either case, the up and down
Trolltech AS 13 June 2001 2
QSpinBox(3qt)QSpinBox(3qt)
arrow keys always work.
It is often desirable to give the user a special, often
default, choice in addition to the range of numeric
values. See setSpecialValueText() for how to do this with
QSpinBox.
The default QWidget::focusPolicy() is StrongFocus.
QSpinBox can easily be subclassed to allow the user to
input other things than an integer value, as long as the
allowed input can be mapped down to a range of integers.
This can be done by overriding the virtual functions
mapValueToText() and mapTextToValue() and setting another,
suitable validator using setValidator(). For example,
these function could be changed so that the user provided
values from 0.0 to 10.0 while the range of integers used
inside the program would be 0 to 100:
class MySpinBox : public QSpinBox {
public:
...
QString mapValueToText( int value )
{
return QString("%1.%2").arg(value/10).arg(value%10);
}
int mapTextToValue( bool* ok )
{
return int(text().toFloat()*10);
}
};
[Image Omitted]
[Image Omitted]
See also QScrollBar, QSlider and GUI Design Handbook: Spin
Box
Member Type Documentation
QSpinBox::ButtonSymbols
This enum type determines what the buttons in a spin box
show. The currently defined values are:
UpDownArrows - the buttons show little arrows, in the
classic style. This is the default.
PlusMinus - the buttons show '+' and '-' symbols. This is
often considered to be more meaningful than UpDownArrows.
MEMBER FUNCTION DOCUMENTATIONTrolltech AS 13 June 2001 3
QSpinBox(3qt)QSpinBox(3qt)QSpinBox::QSpinBox ( QWidget * parent = 0, const char * name = 0
)
Constructs a spin box with the default QRangeControl range
and step values.
See also minValue(), maxValue(), setRange(), lineStep()
and setSteps().
QSpinBox::QSpinBox ( int minValue, int maxValue, int step = 1,
QWidget * parent = 0, const char * name = 0 )
Constructs a spin box with range from minValue to maxValue
inclusive, with step amount step. The value is initially
set to minValue.
See also minValue(), maxValue(), setRange(), lineStep()
and setSteps().
QSpinBox::~QSpinBox ()
Destroys the spin box, freeing all memory and other
resources.
QSpinBox::ButtonSymbols QSpinBox::buttonSymbols() const
Returns the current button symbol mode. The default is
UpDownArrows.
See also setButtonSymbols() and ButtonSymbols.
QString QSpinBox::cleanText () const [virtual]
Returns a copy of the current text of the spin box with
any prefix and/or suffix and white space at the start and
end removed.
See also text(), setPrefix() and setSuffix().
QString QSpinBox::currentValueText () [protected]
Returns the full text calculated from the current value,
including any prefix, suffix or special-value text.
QPushButton* QSpinBox::downButton () const [protected]
Returns a pointer to the embedded 'down' button.
QLineEdit* QSpinBox::editor () const [protected]
Returns a pointer to the embedded QLineEdit.
bool QSpinBox::eventFilter ( QObject * obj, QEvent * ev )
[virtual protected]
Intercepts and handles those events coming to the embedded
QLineEdit which have special meaning for the QSpinBox.
Reimplemented from QObject.
void QSpinBox::interpretText () [virtual protected]
QSpinBox calls this after the user has manually edited the
contents of the spin box (not using the up/down
Trolltech AS 13 June 2001 4
QSpinBox(3qt)QSpinBox(3qt)
buttons/keys).
The default implementation of this function interprets the
new text using mapTextToValue(). If mapTextToValue() is
successful, it changes the spin box' value. If not the
value if left unchanged.
void QSpinBox::leaveEvent ( QEvent * ) [virtual protected]
Reimplemented for internal reasons; the API is not
affected.
Reimplemented from QWidget.
int QSpinBox::lineStep () const
Reimplemented for internal reasons; the API is not
affected.
int QSpinBox::mapTextToValue ( bool * ok ) [virtual protected]
This virtual function is used by the spin box whenever it
needs to interpret the text entered by the user as a
value. The default implementation tries to interpret it as
an integer in the standard way, and returns the integer
value.
Reimplement this function in in a subclass if you want a
specialized spin box, handling something else than
integers. It should call text() (or cleanText() ) and
return the value corresponding to that text. If the text
does not represent a legal value (uninterpretable), the
bool pointed to by ok should be set to FALSE.
This function need not be concerned with special-value
text, the QSpinBox handles that automatically.
See also interpretText() and mapValueToText().
QString QSpinBox::mapValueToText ( int v ) [virtual protected]
This virtual function is used by the spin box whenever it
needs to display value v. The default implementation
returns a string containing v printed in the standard way.
Reimplement this function in in a subclass if you want a
specialized spin box, handling something else than
integers. This function need not be concerned with prefix
or suffix or special-value text, the QSpinBox handles that
automatically.
See also updateDisplay() and mapTextToValue().
int QSpinBox::maxValue () const
Reimplemented for internal reasons; the API is not
affected.
Trolltech AS 13 June 2001 5
QSpinBox(3qt)QSpinBox(3qt)int QSpinBox::minValue () const
Reimplemented for internal reasons; the API is not
affected.
QString QSpinBox::prefix () const [virtual]
Returns the currently set prefix, or a null string if no
prefix is set.
See also setPrefix(), setSuffix() and suffix().
void QSpinBox::rangeChange () [virtual protected]
This method gets called by QRangeControl whenever the
range has changed. It adjusts the default validator and
updates the display.
void QSpinBox::resizeEvent ( QResizeEvent * ) [virtual protected]
Reimplemented for internal reasons; the API is not
affected.
Reimplemented from QWidget.
void QSpinBox::setButtonSymbols ( ButtonSymbols newSymbols )
Sets the spin box to display newSymbols on its buttons.
newSymbols can be either UpDownArrows (the default) or
PlusMinus.
See also buttonSymbols() and ButtonSymbols.
void QSpinBox::setEnabled ( bool on ) [virtual slot]
Reimplemented for internal reasons; the API is not
affected.
void QSpinBox::setLineStep ( int i )
Sets the line step to i.
Calls the virtual stepChange() function if the new line
step is different from the previous setting.
See also lineStep(), QRangeControl::setSteps() and
setRange().
void QSpinBox::setMaxValue ( int i )
A convenience function which just calls setRange(
minValue(), i )
See also setRange().
void QSpinBox::setMinValue ( int i )
A convenience function which just calls setRange( i,
maxValue() )
See also setRange().
Trolltech AS 13 June 2001 6
QSpinBox(3qt)QSpinBox(3qt)void QSpinBox::setPrefix ( const QString & text ) [virtual slot]
Sets the prefix to text. The prefix is prepended to the
start of the displayed value. Typical use is to indicate
the unit of measurement to the user. eg.
sb->setPrefix("$");
To turn off the prefix display, call this function with an
empty string as parameter. The default is no prefix.
See also prefix(), setSuffix() and suffix().
void QSpinBox::setSpecialValueText ( const QString & text )
[virtual]
Sets the special-value text to text. If set, the spin box
will display this text instead of a numeric value whenever
the current value is equal to minVal(). Typically used for
indicating that this choice has a special (default)
meaning.
For example, if your spin box allows the user to choose
the margin width in a print dialog, and your application
is able to automatically choose a good margin width, you
can set up the spin box like this:
QSpinBox marginBox( -1, 20, 1, parent, "marginBox" );
marginBox->setSuffix( " mm" );
marginBox->setSpecialValueText( "Auto" );
The user will then be able to choose a margin width from
0-20 millimeters, or select "Auto" to leave it to the
application to choose. Your code must then interpret the
spin box value of -1 as the user requesting automatic
margin width.
Neither prefix nor suffix, if set, are added to the
special-value text when displayed.
To turn off the special-value text display, call this
function with an empty string as parameter. The default is
no special-value text, i.e. the numeric value is shown as
usual.
See also specialValueText().
void QSpinBox::setSuffix ( const QString & text ) [virtual slot]
Sets the suffix to text. The suffix is appended to the end
of the displayed value. Typical use is to indicate the
unit of measurement to the user. eg.
sb->setSuffix("cm");
To turn off the suffix display, call this function with an
empty string as parameter. The default is no suffix.
Trolltech AS 13 June 2001 7
QSpinBox(3qt)QSpinBox(3qt)
See also suffix(), setPrefix() and prefix().
void QSpinBox::setValidator ( const QValidator * v ) [virtual]
Sets the validator to v. The validator controls what
keyboard input is accepted when the user is editing in the
value field. The default is to use a suitable
QIntValidator.
Use setValidator(0) to turn off input validation (entered
input will still be clamped to the range of the spinbox).
void QSpinBox::setValue ( int value ) [virtual slot]
Sets the current value of the spin box to value. This is
QRangeControl::setValue() made available as a slot.
void QSpinBox::setWrapping ( bool on ) [virtual]
Setting wrapping to TRUE will allow the value to be
stepped from the highest value to the lowest, and vice
versa. By default, wrapping is turned off.
See also wrapping(), minValue(), maxValue() and
setRange().
QSize QSpinBox::sizeHint () const [virtual]
Reimplemented for internal reasons; the API is not
affected.
Reimplemented from QWidget.
QSizePolicy QSpinBox::sizePolicy () const [virtual]
Reimplemented for internal reasons; the API is not
affected.
Reimplemented from QWidget.
QString QSpinBox::specialValueText () const
Returns the currently special-value text, or a null string
if no special-value text is currently set.
See also setSpecialValueText().
void QSpinBox::stepDown () [virtual slot]
Decreases the current value one step, wrapping as
necessary. This is the same as clicking on the pointing-
down button, and can be used for e.g. keyboard
accelerators.
See also stepUp(), subtractLine(), lineStep(), setSteps(),
setValue() and value().
void QSpinBox::stepUp () [virtual slot]
Increases the current value one step, wrapping as
necessary. This is the same as clicking on the pointing-up
button, and can be used for e.g. keyboard accelerators.
Trolltech AS 13 June 2001 8
QSpinBox(3qt)QSpinBox(3qt)
See also stepDown(), addLine(), lineStep(), setSteps(),
setValue() and value().
void QSpinBox::styleChange ( QStyle & old ) [virtual protected]
Reimplemented for internal reasons; the API is not
affected.
Reimplemented from QWidget.
QString QSpinBox::suffix () const [virtual]
Returns the currently set suffix, or a null string if no
suffix is set.
See also setSuffix(), setPrefix() and suffix().
QString QSpinBox::text () const
Returns the current text of the spin box, including any
prefix() and suffix().
See also value().
void QSpinBox::textChanged () [protected slot]
This slot gets called whenever the user edits the text of
the spin box.
QPushButton* QSpinBox::upButton () const [protected]
Returns a pointer to the embedded 'up' button.
void QSpinBox::updateDisplay () [virtual protected]
Updates the contents of the embedded QLineEdit to reflect
current value, using mapValueToText(). Also
enables/disables the push buttons accordingly.
See also mapValueToText().
const QValidator * QSpinBox::validator () const
Returns the validator which constrains editing for this
spin box if there is any, or else 0.
See also setValidator() and QValidator.
int QSpinBox::value () const
Reimplemented for internal reasons; the API is not
affected.
void QSpinBox::valueChange () [virtual protected]
This method gets called by QRangeControl whenever the
value has changed. Updates the display and emits the
valueChanged() signals.
void QSpinBox::valueChanged ( const QString & valueText )
[signal]
This signal is emitted whenever the valueChanged( int )
signal is emitted, i.e. every time the value of the spin
Trolltech AS 13 June 2001 9
QSpinBox(3qt)QSpinBox(3qt)
box changes (whatever the cause - by setValue(), by a
keyboard accelerator, by mouse clicks etc.).
The valueText parameter is the same string that is
displayed in the edit field of the spin box.
See also value().
void QSpinBox::valueChanged ( int value ) [signal]
This signal is emitted every time the value of the spin
box changes (whatever the cause - by setValue(), by a
keyboard accelerator, by mouse clicks etc.).
Note that it is emitted every time, not just for the
"final" step - if the user clicks 'up' three times, this
signal is emitted three times.
See also value().
void QSpinBox::wheelEvent ( QWheelEvent * e ) [virtual protected]
Reimplemented for internal reasons; the API is not
affected.
Reimplemented from QWidget.
bool QSpinBox::wrapping () const
Returns the current setWrapping() value.
SEE ALSO
http://doc.trolltech.com/qspinbox.html
http://www.trolltech.com/faq/tech.html
COPYRIGHT
Copyright 1992-2001 Trolltech AS,
http://www.trolltech.com. See the license file included
in the distribution for a complete license statement.
AUTHOR
Generated automatically from the source code.
BUGS
If you find a bug in Qt, please report it as described in
http://doc.trolltech.com/bughowto.html. Good bug reports
make our job much simpler. Thank you.
In case of content or formattting problems with this
manual page, please report them to qt-bugs@trolltech.com.
Please include the name of the manual page (qspinbox.3qt)
and the Qt version (2.3.1).
Trolltech AS 13 June 2001 10
