SpinBox QML Type

Ermöglicht dem Benutzer die Auswahl aus einer Reihe voreingestellter Werte. Mehr...

• Liste aller Elemente, einschließlich vererbter Elemente

Eigenschaften

• 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 (since 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))

Signale

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

Methoden

• void decrease()
• void increase()

Ausführliche Beschreibung

Mit der SpinBox kann der Benutzer einen ganzzahligen Wert auswählen, indem er auf die Aufwärts- oder Abwärts-Schaltflächen klickt oder die Aufwärts- bzw. Abwärts-Taste auf der Tastatur drückt. Optional kann die SpinBox auch als „ editable “ eingerichtet werden, sodass der Benutzer einen Textwert in das Eingabefeld eingeben kann.

Standardmäßig bietet SpinBox diskrete Werte im Bereich von [0-99] mit einem stepSize von 1 an.

SpinBox {
    value: 50
}

Für Gleitkommawerte verwenden Sie „ DoubleSpinBox “.

Benutzerdefinierte Werte

Obwohl die SpinBox mit ganzzahligen Werten arbeitet, lässt sie sich so anpassen, dass sie beliebige Eingabewerte akzeptiert. Der folgende Codeausschnitt zeigt, wie „ validator “, „ textFromValue “ und „ valueFromText “ verwendet werden können, um das Standardverhalten anzupassen.

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

    property list<string> 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
    }
}

Ein Präfix und ein Suffix können mithilfe regulärer Ausdrücke hinzugefügt werden:

SpinBox {
    id: spinBox
    from: -100
    value: 11
    to: 100
    editable: true
    anchors.centerIn: parent

    property string prefix: "L="
    property string suffix: "m"

    readonly property regexp numberExtractionRegExp: /\D*?(-?\d*\.?\d*)\D*$/

    validator: RegularExpressionValidator { regularExpression: numberExtractionRegExp }

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

    valueFromText: function(text, locale) {
        return Number.fromLocaleString(locale, numberExtractionRegExp.exec(text)[1])
    }
}

Siehe auch Tumbler, „SpinBox anpassen“, „Fokusverwaltung“ unter Qt Quick Controls sowie DoubleSpinBox.

Dokumentation zu Eigenschaften

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

Diese Eigenschaft enthält den Textwert des Spinbox-Feldes.

Der Wert der Eigenschaft basiert auf textFromValue und locale und entspricht:

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

Diese Eigenschaft wurde in QtQuick.Controls 2.4 (Qt 5.11) eingeführt.

Siehe auch textFromValue.

down group

Diese gruppierte Eigenschaft enthält das Element „Down-Indikator“ und die dazugehörigen Eigenschaften.

Die Eigenschaft „ down.hovered “ wurde in QtQuick.Controls 2.1 eingeführt, und die Eigenschaften „ down.implicitIndicatorWidth “ und „ down.implicitIndicatorHeight “ wurden in QtQuick.Controls 2.5 eingeführt.

Siehe auch decrease().

editable : bool

Diese Eigenschaft gibt an, ob das Spinbox-Feld bearbeitbar ist. Der Standardwert lautet „ false “.

Siehe auch „ validator “.

from : int

Diese Eigenschaft enthält den Startwert für den Bereich. Der Standardwert lautet „ 0 “.

Siehe auch „ to “ und „ value “.

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

Diese Eigenschaft gibt an, ob in ein bearbeitbares Drehfeld bereits ein Teiltext über eine Eingabemethode eingegeben wurde.

Während der Texterstellung kann eine Eingabemethode auf Maus- oder Tastenereignisse des Spin-Feldes zurückgreifen, um den Teiltext zu bearbeiten oder zu übernehmen. Diese Eigenschaft kann verwendet werden, um zu bestimmen, wann Ereignisbehandler deaktiviert werden sollen, die den korrekten Betrieb einer Eingabemethode beeinträchtigen könnten.

Diese Eigenschaft wurde in QtQuick.Controls 2.2 (Qt 5.9) eingeführt.

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

Diese Eigenschaft liefert der Eingabemethode Hinweise zum erwarteten Inhalt des Spin-Feldes und zu dessen Funktionsweise.

Der Standardwert ist „ Qt.ImhDigitsOnly “.

Der Wert ist eine bitweise Kombination aus Flags oder „ Qt.ImhNone “, wenn keine Hinweise festgelegt sind.

Flagge, die das Verhalten ändern, sind:

• Qt.ImhHiddenText – Zeichen sollten ausgeblendet werden, wie es typischerweise bei der Eingabe von Passwörtern der Fall ist.
• Qt.ImhSensitiveData – Der eingegebene Text sollte von der aktiven Eingabemethode nicht in einem dauerhaften Speicher wie dem vorausschauenden Benutzerwörterbuch gespeichert werden.
• Qt.ImhNoAutoUppercase – Die Eingabemethode sollte nicht versuchen, am Satzende automatisch auf Großbuchstaben umzuschalten.
• Qt.ImhPreferNumbers – Zahlen werden bevorzugt (sind aber nicht erforderlich).
• Qt.ImhPreferUppercase – Großbuchstaben werden bevorzugt (sind aber nicht erforderlich).
• Qt.ImhPreferLowercase – Kleinbuchstaben werden bevorzugt (sind aber nicht erforderlich).
• Qt.ImhNoPredictiveText – Während der Eingabe soll keine Texterkennung (d. h. keine Wörterbuchsuche) verwendet werden.
• Qt.ImhDate – Der Texteditor fungiert als Datumsfeld.
• Qt.ImhTime – Der Texteditor fungiert als Zeitfeld.

Flags, die die Eingabe einschränken (exklusive Flags), sind:

• Qt.ImhDigitsOnly – Es sind nur Ziffern zulässig.
• Qt.ImhFormattedNumbersOnly – Es ist nur die Eingabe von Zahlen erlaubt. Dazu gehören Dezimalpunkt und Minuszeichen.
• Qt.ImhUppercaseOnly – Es dürfen nur Großbuchstaben eingegeben werden.
• Qt.ImhLowercaseOnly – Es dürfen nur Kleinbuchstaben eingegeben werden.
• Qt.ImhDialableCharactersOnly – Es sind nur Zeichen erlaubt, die für die Telefonwahl geeignet sind.
• Qt.ImhEmailCharactersOnly – Es sind nur Zeichen erlaubt, die für E-Mail-Adressen geeignet sind.
• Qt.ImhUrlCharactersOnly – Es sind nur Zeichen erlaubt, die für URLs geeignet sind.

Masken:

• Qt.ImhExclusiveInputMask – Diese Maske liefert einen Wert ungleich Null, wenn eines der Ausschlussflags verwendet wird.

Diese Eigenschaft wurde in QtQuick.Controls 2.2 (Qt 5.9) eingeführt.

live : bool [since 6.6]

Diese Eigenschaft legt fest, ob die Eigenschaft „ value “ aktualisiert wird, wenn der Benutzer die Eigenschaft „ displayText “ bearbeitet. Der Standardwert ist „ false “. Wenn diese Eigenschaft auf „ true “ gesetzt ist und der vom Benutzer eingegebene Wert gültig ist und innerhalb der Grenzen des Spinbox-Feldes [from, to] liegt, wird der Wert der Eigenschaft „ SpinBox “ gesetzt. Ist diese Eigenschaft auf „ false “ gesetzt oder liegt der vom Benutzer eingegebene Wert außerhalb der Grenzen, wird der Wert erst aktualisiert, wenn die Eingabetaste oder die Return-Taste gedrückt wird oder das Eingabefeld den Fokus verliert.

Diese Eigenschaft wurde in Qt 6.6 eingeführt.

Siehe auch editable und displayText.

stepSize : int

Diese Eigenschaft enthält die Schrittweite. Der Standardwert lautet „ 1 “.

Siehe auch „ increase()“ und „ decrease()“.

textFromValue : function

Diese Eigenschaft enthält eine Callback-Funktion, die immer dann aufgerufen wird, wenn ein ganzzahliger Wert zur Anzeige als Text umgewandelt werden muss.

Die Standardfunktion kann überschrieben werden, um für einen bestimmten Wert benutzerdefinierten Text anzuzeigen. Dies gilt sowohl für bearbeitbare als auch für nicht bearbeitbare Spinboxen; wenn beispielsweise die Auf- und Ab-Schaltflächen oder das Mausrad zum Erhöhen oder Verringern des Werts verwendet werden, wird der neue Wert mithilfe dieser Funktion in Anzeigetext umgewandelt.

Die Signatur der Callback-Funktion lautet „ string function(value, locale) “. Die Funktion kann ein oder zwei Argumente haben, wobei das erste Argument der zu konvertierende Wert ist und das optionale zweite Argument gegebenenfalls die für die Konvertierung zu verwendende Locale angibt.

Die Standardimplementierung führt die Umwandlung mit ` Number.toLocaleString()` durch:

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

Siehe auch „ valueFromText “, „ validator “ und „ locale “.

to : int

Diese Eigenschaft enthält den Endwert des Bereichs. Der Standardwert lautet „ 99 “.

Siehe auch from und value.

up group

Diese gruppierte Eigenschaft enthält das Element „up“ und die dazugehörigen Eigenschaften.

Die Eigenschaft „ up.hovered “ wurde in „ QtQuick.Controls 2.1“ eingeführt, und die Eigenschaften „ up.implicitIndicatorWidth “ und „ up.implicitIndicatorHeight “ wurden in „ QtQuick.Controls 2.5“ eingeführt.

Siehe auch increase().

validator : Validator

Diese Eigenschaft enthält die Validierungsfunktion für den Eingabetext bei bearbeitbaren Spinboxen. Standardmäßig verwendet „ SpinBox “ die Funktion „ IntValidator “, um die Eingabe von ganzen Zahlen zuzulassen.

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

Siehe auch editable, textFromValue, valueFromText, locale und „Validierung von Eingabetext“.

value : int

Diese Eigenschaft nimmt Werte im Bereich von from bis to an. Der Standardwert lautet 0.

valueFromText : function

Diese Eigenschaft enthält eine Callback-Funktion, die immer dann aufgerufen wird, wenn Eingabetext in einen ganzzahligen Wert umgewandelt werden muss.

Diese Funktion muss nur überschrieben werden, wenn „ textFromValue “ für ein bearbeitbares Spinbox-Feld überschrieben wird.

Die Signatur der Callback-Funktion lautet ` int function(text, locale)`. Die Funktion kann ein oder zwei Argumente haben, wobei das erste Argument der zu konvertierende Text ist und das optionale zweite Argument die Locale angibt, die gegebenenfalls für die Konvertierung verwendet werden soll.

Die Standardimplementierung führt die Konvertierung mithilfe von ` Number.fromLocaleString()` durch:

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

Siehe auch „ textFromValue “, „ validator “ und „ locale “.

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

Diese Eigenschaft legt fest, ob die Spinbox umbricht. Der Standardwert ist „ false “.

Wenn „wrap“ auf „ true “ gesetzt ist, ändert sich der Wert bei einem Schritt über „ to “ hinaus auf „ from “ und umgekehrt.

Diese Eigenschaft wurde in QtQuick.Controls 2.3 (Qt 5.10) eingeführt.

Signal-Dokumentation

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

Dieses Signal wird ausgelöst, wenn der Wert des Spin-Box-Feldes vom Benutzer interaktiv geändert wurde – sei es per Touch, Maus, Scrollrad oder Tastatur. Bei einer Interaktion über die Tastatur wird das Signal erst ausgelöst, wenn der Text übernommen wurde, d. h. wenn die Eingabetaste gedrückt wird oder das Eingabefeld den Fokus verliert.

Dieses Signal wurde in QtQuick.Controls 2.2 (Qt 5.9) eingeführt.

Methodendokumentation

void decrease()

Verringert den Wert um „ stepSize “ oder um „ 1 “, falls „ stepSize “ nicht definiert ist.

Siehe auch stepSize.

void increase()

Erhöht den Wert um stepSize oder um 1, falls stepSize nicht definiert ist.

Siehe auch stepSize.