SpinBox QML Type

Allows the user to select from a set of preset values. 更多...

import 语句：	import QtQuick.Controls
继承：	Control

所有成员列表，包括继承成员

特性

displayText : string (since QtQuick.Controls 2.4 (Qt 5.11))
down
- down.hovered : bool
- down.implicitIndicatorHeight : real
- down.implicitIndicatorWidth : real
- down.indicator : Item
- down.pressed : bool
editable : bool
from : int
inputMethodComposing : bool (since QtQuick.Controls 2.2 (Qt 5.9))
inputMethodHints : flags (since QtQuick.Controls 2.2 (Qt 5.9))
live : bool (从 6.6 起)
stepSize : int
textFromValue : function
to : int
up
- up.hovered : bool
- up.implicitIndicatorHeight : real
- up.implicitIndicatorWidth : real
- up.indicator : Item
- up.pressed : bool
validator : Validator
value : int
valueFromText : function
wrap : bool (since QtQuick.Controls 2.3 (Qt 5.10))

信号

valueModified () (since QtQuick.Controls 2.2 (Qt 5.9))

方法

void decrease ()
void increase ()

详细描述

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] 采用 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 {
    id: spinBox
    from: 0
    to: items.length - 1
    value: 1 // "Medium"
    property var items: ["Small", "Medium", "Large"]
    validator: RegularExpressionValidator {
        regularExpression: 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 spinBox.value
    }
}

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

SpinBox {
    id: spinBox
    from: 0
    value: decimalToInt(1.1)
    to: decimalToInt(100)
    stepSize: decimalFactor
    editable: true
    anchors.centerIn: parent
    property int decimals: 2
    property real realValue: value / decimalFactor
    readonly property int decimalFactor: Math.pow(10, decimals)
    function decimalToInt(decimal) {
        return decimal * decimalFactor
    }
    validator: DoubleValidator {
        bottom: Math.min(spinBox.from, spinBox.to)
        top:  Math.max(spinBox.from, spinBox.to)
        decimals: spinBox.decimals
        notation: DoubleValidator.StandardNotation
    }
    textFromValue: function(value, locale) {
        return Number(value / decimalFactor).toLocaleString(locale, 'f', spinBox.decimals)
    }
    valueFromText: function(text, locale) {
        return Math.round(Number.fromLocaleString(locale, text) * decimalFactor)
    }
}

A prefix and suffix can be added using regular expressions:

SpinBox {
    id: spinBox
    from: 0
    value: 11
    to: 100
    editable: true
    anchors.centerIn: parent
    property string prefix: "L="
    property string suffix: "m"
    validator: RegularExpressionValidator { regularExpression: /\D*(-?\d*\.?\d*)\D*/ }
    textFromValue: function(value, locale) {
        return prefix + Number(value).toLocaleString(locale, 'f', 0) + suffix
    }
    valueFromText: function(text, locale) {
        let re = /\D*(-?\d*\.?\d*)\D*/
        return Number.fromLocaleString(locale, re.exec(text)[1])
    }
}

另请参阅 Tumbler , Customizing SpinBox ，和 Focus Management in Qt Quick Controls .

特性文档编制

displayText : string [read-only, since QtQuick.Controls 2.4 (Qt 5.11)]

This property holds the textual value of the spinbox.

The value of the property is based on textFromValue and locale , and equal to:

var text = spinBox.textFromValue(spinBox.value, spinBox.locale)

This property was introduced in QtQuick.Controls 2.4 (Qt 5.11).

另请参阅 textFromValue .

down group
down.hovered : bool
down.implicitIndicatorHeight : real
down.implicitIndicatorWidth : real
down.indicator : Item
down.pressed : bool

These properties hold the down indicator item and whether it is pressed or hovered. The down.hovered property was introduced in QtQuick .Controls 2.1, and the down.implicitIndicatorWidth and down.implicitIndicatorHeight properties were introduced in QtQuick .Controls 2.5.

另请参阅 decrease ().

editable : bool

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

另请参阅 validator .

from : int

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

另请参阅 to and value .

inputMethodComposing : bool [read-only, since QtQuick.Controls 2.2 (Qt 5.9)]

This property holds whether an editable spin box has partial text input from an input method.

While it is composing, an input method may rely on mouse or key events from the spin box to edit or commit the partial text. This property can be used to determine when to disable event handlers that may interfere with the correct operation of an input method.

This property was introduced in QtQuick.Controls 2.2 (Qt 5.9).

inputMethodHints : flags [since QtQuick.Controls 2.2 (Qt 5.9)]

This property provides hints to the input method about the expected content of the spin box and how it should operate.

默认值为 Qt.ImhDigitsOnly .

The value is a bit-wise combination of flags or Qt.ImhNone if no hints are set.

Flags that alter behavior are:

Qt.ImhHiddenText - Characters should be hidden, as is typically used when entering passwords.
Qt.ImhSensitiveData - Typed text should not be stored by the active input method in any persistent storage like predictive user dictionary.
Qt.ImhNoAutoUppercase - The input method should not try to automatically switch to upper case when a sentence ends.
Qt.ImhPreferNumbers - Numbers are preferred (but not required).
Qt.ImhPreferUppercase - Upper case letters are preferred (but not required).
Qt.ImhPreferLowercase - Lower case letters are preferred (but not required).
Qt.ImhNoPredictiveText - Do not use predictive text (i.e. dictionary lookup) while typing.
Qt.ImhDate - The text editor functions as a date field.
Qt.ImhTime - The text editor functions as a time field.

Flags that restrict input (exclusive flags) are:

Qt.ImhDigitsOnly - Only digits are allowed.
Qt.ImhFormattedNumbersOnly - Only number input is allowed. This includes decimal point and minus sign.
Qt.ImhUppercaseOnly - Only upper case letter input is allowed.
Qt.ImhLowercaseOnly - Only lower case letter input is allowed.
Qt.ImhDialableCharactersOnly - Only characters suitable for phone dialing are allowed.
Qt.ImhEmailCharactersOnly - Only characters suitable for email addresses are allowed.
Qt.ImhUrlCharactersOnly - Only characters suitable for URLs are allowed.

掩码：

Qt.ImhExclusiveInputMask - This mask yields nonzero if any of the exclusive flags are used.

This property was introduced in QtQuick.Controls 2.2 (Qt 5.9).

live : bool [since 6.6]

This property holds whether the value is updated when the user edits the displayText 。默认值为 false . If this property is true and the value entered by the user is valid and within the bounds of the spinbox [ from , to ], the value of the SpinBox will be set. If this property is false or the value entered by the user is outside the boundaries, the value will not be updated until the enter or return keys are pressed, or the input field loses focus.

该特性在 Qt 6.6 引入。

另请参阅 editable and displayText .

stepSize : int

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

另请参阅 increase () 和 decrease ().

textFromValue : function

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

The default function can be overridden to display custom text for a given value. This applies to both editable and non-editable spinboxes; for example, when using the up and down buttons or a mouse wheel to increment and decrement the value, the new value is converted to display text using this function.

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); }

注意： When applying a custom textFromValue implementation for editable spinboxes, a matching valueFromText implementation must be provided to be able to convert the custom text back to an integer value.

另请参阅 valueFromText , validator ，和 locale .

to : int

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

另请参阅 from and value .

up group
up.hovered : bool
up.implicitIndicatorHeight : real
up.implicitIndicatorWidth : real
up.indicator : Item
up.pressed : bool

These properties hold the up indicator item and whether it is pressed or hovered. The up.hovered property was introduced in QtQuick .Controls 2.1, and the up.implicitIndicatorWidth and up.implicitIndicatorHeight properties were introduced in QtQuick .Controls 2.5.

另请参阅 increase ().

validator : Validator

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

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

另请参阅 editable , textFromValue , valueFromText , locale ，和 Validating Input Text .

value : int

This property holds the value in the range from - to 。默认值为 0 .

valueFromText : function

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

This function only needs to be overridden when textFromValue is overridden for an editable spinbox.

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); }

注意： When applying a custom textFromValue implementation for editable spinboxes, a matching valueFromText implementation must be provided to be able to convert the custom text back to an integer value.

另请参阅 textFromValue , validator ，和 locale .

wrap : bool [since QtQuick.Controls 2.3 (Qt 5.10)]

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

If wrap is true , stepping past to changes the value to from and vice versa.

该特性在 QtQuick.Controls 2.3 (Qt 5.10) 引入。

信号文档编制

[since QtQuick.Controls 2.2 (Qt 5.9)] valueModified ()

This signal is emitted when the spin box value has been interactively modified by the user by either touch, mouse, wheel, or keys. In the case of interaction via keyboard, the signal is only emitted when the text has been accepted; meaning when the enter or return keys are pressed, or the input field loses focus.

注意： 相应处理程序是 onValueModified .

This signal was introduced in QtQuick.Controls 2.2 (Qt 5.9).

方法文档编制

void decrease ()

Decreases the value by stepSize ，或 1 if stepSize is not defined.

另请参阅 stepSize .

void increase ()

Increases the value by stepSize ，或 1 if stepSize is not defined.

另请参阅 stepSize .