Qt Documentation

SpinBox QML Type

A spinbox control that allows the user to select from a set of preset values. More...

Import Statement:	import QtQuick.Controls 2.0
Since:	Qt 5.7
Inherits:	Control

List of all members, including inherited members

Properties

down
- down.pressed : bool
- down.indicator : Item
editable : bool
from : int
stepSize : int
textFromValue : function
to : int
up
- up.pressed : bool
- up.indicator : Item
validator : Validator
value : int
valueFromText : function

Methods

void decrease()
void increase()

Detailed Description

SpinBox allows the user to choose an integer value by clicking the up or down indicator buttons, or by pressing up or down on the keyboard. Optionally, SpinBox can be also made editable, so the user can enter a text value in the input field.

By default, SpinBox provides discrete values in the range of [0-99] with a stepSize of 1.

SpinBox {
    value: 50
}

Custom Values

Even though SpinBox works on integer values, it can be customized to accept arbitrary input values. The following snippet demonstrates how validator, textFromValue and valueFromText can be used to customize the default behavior.

SpinBox {
    from: 0
    to: items.length - 1
    value: 1 // "Medium"

    property var items: ["Small", "Medium", "Large"]

    validator: RegExpValidator {
        regExp: new RegExp("(Small|Medium|Large)", "i")
    }

    textFromValue: function(value) {
        return items[value];
    }

    valueFromText: function(text) {
        for (var i = 0; i < items.length; ++i) {
            if (items[i].toLowerCase().indexOf(text.toLowerCase()) === 0)
                return i
        }
        return sb.value
    }
}

In the same manner, SpinBox can be customized to accept floating point numbers:

SpinBox {
    id: spinbox
    from: 0
    value: 110
    to: 100 * 100
    stepSize: 100
    anchors.centerIn: parent

    property int decimals: 2
    property real realValue: value / 100

    validator: DoubleValidator {
        bottom: Math.min(spinbox.from, spinbox.to)
        top:  Math.max(spinbox.from, spinbox.to)
    }

    textFromValue: function(value, locale) {
        return Number(value / 100).toLocaleString(locale, 'f', spinbox.decimals)
    }

    valueFromText: function(text, locale) {
        return Number.fromLocaleString(locale, text) * 100
    }
}

See also Tumbler and Customizing SpinBox.

Property Documentation

down group
down.pressed : bool
down.indicator : Item

These properties hold the down indicator item and whether it is pressed.

See also decrease().

editable : bool

This property holds whether the spinbox is editable. The default value is false.

See also validator.

from : int

This property holds the starting value for the range. The default value is 0.

See also to and value.

stepSize : int

This property holds the step size. The default value is 1.

See also increase() and decrease().

textFromValue : function

This property holds a callback function that is called whenever an integer value needs to be converted to display text.

The callback function signature is string function(value, locale). The function can have one or two arguments, where the first argument is the value to be converted, and the optional second argument is the locale that should be used for the conversion, if applicable.

The default implementation does the conversion using Number.toLocaleString():

textFromValue: function(value, locale) { return Number(value).toLocaleString(locale, 'f', 0); }

See also valueFromText, validator, and locale.

to : int

This property holds the end value for the range. The default value is 99.

See also from and value.

up group
up.pressed : bool
up.indicator : Item

These properties hold the up indicator item and whether it is pressed.

See also increase().

validator : Validator

This property holds the input text validator for editable spinboxes. By default, SpinBox uses IntValidator to accept input of integer numbers.

validator: IntValidator {
    locale: control.locale.name
    bottom: Math.min(control.from, control.to)
    top: Math.max(control.from, control.to)
}

See also editable, textFromValue, valueFromText, and locale.

value : int

This property holds the value in the range from - to. The default value is 0.

valueFromText : function

This property holds a callback function that is called whenever input text needs to be converted to an integer value.

The callback function signature is int function(text, locale). The function can have one or two arguments, where the first argument is the text to be converted, and the optional second argument is the locale that should be used for the conversion, if applicable.

The default implementation does the conversion using Number.fromLocaleString():

valueFromText: function(text, locale) { return Number.fromLocaleString(locale, text); }

See also textFromValue, validator, and locale.

Method Documentation

void decrease()

Decreases the value by stepSize.

See also stepSize.

void increase()

Increases the value by stepSize.