QSpinBox Class
Die Klasse „QSpinBox“ stellt ein Spin-Box-Widget bereit. Mehr...
| Header: | #include <QSpinBox> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Erbt von: | QAbstractSpinBox |
Eigenschaften
|
|
Öffentliche Funktionen
| QSpinBox(QWidget *parent = nullptr) | |
| virtual | ~QSpinBox() |
| QString | cleanText() const |
| int | displayIntegerBase() const |
| int | maximum() const |
| int | minimum() const |
| QString | prefix() const |
| void | setDisplayIntegerBase(int base) |
| void | setMaximum(int max) |
| void | setMinimum(int min) |
| void | setPrefix(const QString &prefix) |
| void | setRange(int minimum, int maximum) |
| void | setSingleStep(int val) |
| void | setStepType(QAbstractSpinBox::StepType stepType) |
| void | setSuffix(const QString &suffix) |
| int | singleStep() const |
| QAbstractSpinBox::StepType | stepType() const |
| QString | suffix() const |
| int | value() const |
Öffentliche Slots
| void | setValue(int val) |
Signale
| void | textChanged(const QString &text) |
| void | valueChanged(int i) |
Geschützte Funktionen
| virtual QString | textFromValue(int value) const |
| virtual int | valueFromText(const QString &text) const |
Neu implementierte geschützte Funktionen
| virtual bool | event(QEvent *event) override |
| virtual void | fixup(QString &input) const override |
| virtual QValidator::State | validate(QString &text, int &pos) const override |
Ausführliche Beschreibung
QSpinBox ist für die Verarbeitung von Ganzzahlen und diskreten Wertemengen (z. B. Monatsnamen) ausgelegt; verwenden Sie QDoubleSpinBox für Gleitkommawerte.
Mit QSpinBox kann der Benutzer einen Wert auswählen, indem er auf die Auf-/Ab-Schaltflächen klickt oder die Auf-/Ab-Tasten auf der Tastatur drückt, um den aktuell angezeigten Wert zu erhöhen bzw. zu verringern. Der Benutzer kann den Wert auch manuell eingeben. Die Spin-Box unterstützt ganzzahlige Werte, kann jedoch mithilfe von validate(), textFromValue() und valueFromText() auf die Verwendung verschiedener Zeichenketten erweitert werden.
Jedes Mal, wenn sich der Wert ändert, sendet QSpinBox die Signale „ valueChanged()“ und „ textChanged()“ aus, wobei das erstere einen int-Wert und das letztere einen QString-Wert liefert. Das Signal „ textChanged()“ liefert den Wert sowohl mit „ prefix()“ als auch mit „ suffix()“. Der aktuelle Wert kann mit „ value()“ abgerufen und mit „ setValue()“ gesetzt werden.
Durch Klicken auf die Auf-/Ab-Schaltflächen oder die Verwendung der Auf- und Ab-Pfeiltasten als Tastaturkürzel wird der aktuelle Wert in Schritten der Größe singleStep() erhöht oder verringert. Wenn Sie dieses Verhalten ändern möchten, können Sie die virtuelle Funktion ` stepBy()` neu implementieren. Der Minimal- und Maximalwert sowie die Schrittweite können mithilfe eines der Konstruktoren festgelegt und später mit ` setMinimum()`, ` setMaximum()` und ` setSingleStep()` geändert werden.
Die meisten Spin-Boxen sind gerichtet, aber QSpinBox kann auch als zirkuläre Spin-Box fungieren, d. h., wenn der Bereich 0–99 beträgt und der aktuelle Wert 99 ist, ergibt ein Klick auf „Nach oben“ den Wert 0, sofern ` wrapping()` auf „true“ gesetzt ist. Verwenden Sie ` setWrapping()`, wenn Sie ein zirkuläres Verhalten wünschen.
Dem angezeigten Wert können beliebige Zeichenfolgen vorangestellt oder angehängt werden, die beispielsweise die Währung oder die Maßeinheit angeben. Siehe setPrefix() und setSuffix(). Der Text im Drehfeld wird mit text() abgerufen (einschließlich aller prefix() und suffix()) oder mit cleanText() (ohne prefix(), ohne suffix() und ohne führende oder nachgestellte Leerzeichen).
Häufig ist es wünschenswert, dem Benutzer zusätzlich zum Bereich der numerischen Werte eine spezielle (oftmals standardmäßige) Auswahlmöglichkeit anzubieten. Unter setSpecialValueText() erfahren Sie, wie dies mit QSpinBox umgesetzt werden kann.
Unterklassen von QSpinBox
Wenn die Verwendung von ` prefix` (), ` suffix` () und ` specialValueText` () nicht genügend Kontrolle bietet, erstellen Sie eine Unterklasse von `QSpinBox` und implementieren ` valueFromText` () sowie ` textFromValue` () neu. Hier ist beispielsweise der Code für ein benutzerdefiniertes Drehfeld, mit dem der Benutzer Symbolgrößen eingeben kann (z. B. „32 x 32“):
int IconSizeSpinBox::valueFromText(const QString &text) const
{
static const QRegularExpression regExp(tr("(\\d+)(\\s*[xx]\\s*\\d+)?"));
Q_ASSERT(regExp.isValid());
const QRegularExpressionMatch match = regExp.match(text);
if (match.isValid())
return match.captured(1).toInt();
return 0;
}
QString IconSizeSpinBox::textFromValue(int value) const
{
return tr("%1 x %1").arg(value);
}Siehe auch QDoubleSpinBox, QDateTimeEdit, QSlider und das Beispiel zu Spin-Boxen.
Dokumentation zu Eigenschaften
[read-only] cleanText : QString
Diese Eigenschaft enthält den Text des Spin-Feldes ohne Präfixe, Suffixe sowie führende oder nachfolgende Leerzeichen.
Zugriffsfunktionen:
| QString | cleanText() const |
Siehe auch „ text “, „ QSpinBox::prefix “ und „ QSpinBox::suffix “.
displayIntegerBase : int
Diese Eigenschaft legt die Basis fest, die zur Anzeige des Wertes im Drehfeld verwendet wird
Der Standardwert für „displayIntegerBase“ ist 10.
Zugriffsfunktionen:
| int | displayIntegerBase() const |
| void | setDisplayIntegerBase(int base) |
Siehe auch „ textFromValue()“ und „ valueFromText()“.
maximum : int
Diese Eigenschaft enthält den Maximalwert des Spin-Feldes
Bei der Festlegung dieser Eigenschaft wird der Mindestwert bei Bedarf angepasst, um sicherzustellen, dass der Wertebereich gültig bleibt.
Der Standard-Maximalwert beträgt 99.
Zugriffsfunktionen:
| int | maximum() const |
| void | setMaximum(int max) |
Siehe auch setRange() und specialValueText.
minimum : int
Diese Eigenschaft enthält den Mindestwert des Drehfelds
Bei der Festlegung dieser Eigenschaft wird der „ maximum “ (Bereichsbegrenzer) bei Bedarf angepasst, um sicherzustellen, dass der Bereich gültig bleibt.
Der Standard-Mindestwert ist 0.
Zugriffsfunktionen:
| int | minimum() const |
| void | setMinimum(int min) |
Siehe auch „ setRange()“ und „ specialValueText “.
prefix : QString
Diese Eigenschaft enthält das Präfix des Spin-Feldes
Das Präfix wird dem angezeigten Wert vorangestellt. Typischerweise wird damit eine Maßeinheit oder ein Währungssymbol angezeigt. Beispiel:
sb->setPrefix("$");Um die Anzeige des Präfixes zu deaktivieren, setzen Sie diese Eigenschaft auf eine leere Zeichenkette. Standardmäßig wird kein Präfix angezeigt. Das Präfix wird nicht angezeigt, wenn „ value()“ == „ minimum()“ ist und „ specialValueText()“ gesetzt ist.
Wenn kein Präfix festgelegt ist, gibt prefix() eine leere Zeichenfolge zurück.
Zugriffsfunktionen:
| QString | prefix() const |
| void | setPrefix(const QString &prefix) |
Siehe auch suffix(), setSuffix(), specialValueText() und setSpecialValueText().
singleStep : int
Diese Eigenschaft enthält den Schrittwert
Wenn der Benutzer den Wert des Drehfelds mithilfe der Pfeiltasten ändert, wird der Wert um den Wert von „singleStep“ erhöht bzw. verringert. Der Standardwert ist 1. Die Einstellung eines „singleStep“-Werts kleiner als 0 hat keine Auswirkung.
Zugriffsfunktionen:
| int | singleStep() const |
| void | setSingleStep(int val) |
stepType : StepType
Diese Eigenschaft gibt den Schritt-Typ an.
Der Schritt-Typ kann ein Einzelschritt oder ein adaptiver Dezimalschritt sein.
Zugriffsfunktionen:
| QAbstractSpinBox::StepType | stepType() const |
| void | setStepType(QAbstractSpinBox::StepType stepType) |
suffix : QString
Diese Eigenschaft enthält das Suffix des Eingabefelds
Das Suffix wird an das Ende des angezeigten Werts angehängt. Typischerweise wird damit eine Maßeinheit oder ein Währungssymbol angezeigt. Beispiel:
sb->setSuffix(" km");Um die Anzeige des Suffixes zu deaktivieren, setzen Sie diese Eigenschaft auf eine leere Zeichenkette. Standardmäßig wird kein Suffix angezeigt. Das Suffix wird für die Funktion „ minimum()“ nicht angezeigt, wenn „ specialValueText()“ gesetzt ist.
Wenn kein Suffix festgelegt ist, gibt suffix() eine leere Zeichenkette zurück.
Zugriffsfunktionen:
| QString | suffix() const |
| void | setSuffix(const QString &suffix) |
Siehe auch „ prefix()“, „ setPrefix()“, „ specialValueText()“ und „ setSpecialValueText()“.
value : int
Diese Eigenschaft enthält den Wert des Drehfelds
setValue() löst „ valueChanged()“ aus, wenn sich der neue Wert vom alten unterscheidet. Die Eigenschaft „value“ verfügt über ein zweites Notifier-Signal, das das Präfix und das Suffix des Spin-Feldes enthält.
Zugriffsfunktionen:
| int | value() const |
| void | setValue(int val) |
Notifier-Signal:
| void | valueChanged(int i) |
Dokumentation zu den Member-Funktionen
[explicit] QSpinBox::QSpinBox(QWidget *parent = nullptr)
Erstellt ein Spin-Feld mit dem Mindestwert 0 und dem Höchstwert 99 sowie einer Schrittweite von 1. Der Wert ist anfänglich auf 0 gesetzt. Es ist ein untergeordnetes Element von parent.
Siehe auch setMinimum(), setMaximum() und setSingleStep().
[virtual noexcept] QSpinBox::~QSpinBox()
Destruktor.
[override virtual protected] bool QSpinBox::event(QEvent *event)
Umsetzt: ` QAbstractSpinBox::event(QEvent *event)`.
[override virtual protected] void QSpinBox::fixup(QString &input) const
Implementiert neu: ` QAbstractSpinBox::fixup` (QString &input) const.
void QSpinBox::setRange(int minimum, int maximum)
Praktische Funktion zum Festlegen der Werte für „ minimum “ und „ maximum “ mit einem einzigen Funktionsaufruf.
setRange(minimum, maximum);entspricht:
setMinimum(minimum);
setMaximum(maximum);Siehe auch „ minimum “ und „ maximum “.
void QSpinBox::setStepType(QAbstractSpinBox::StepType stepType)
Legt den Schritt-Typ für das Eingabefeld auf „ stepType “ fest, was einem Einzelschritt oder einem adaptiven Dezimalschritt entspricht.
„Adaptiver Dezimalschritt“ bedeutet, dass die Schrittweite kontinuierlich auf eine Zehnerpotenz unterhalb des aktuellen Werts von „ value “ angepasst wird. Wenn der Wert also 1100 beträgt, wird der Schritt auf 100 festgelegt, sodass eine Erhöhung um einen Schritt den Wert auf 1200 erhöht. Bei einem Wert von 1200 führt eine Erhöhung um einen Schritt zu 1300. Bei negativen Werten führt ein Schritt nach unten von -1100 zu -1200.
Die Schritt-Richtung wird berücksichtigt, um Randfälle zu behandeln, sodass ein Schritt nach unten von 100 den Wert auf 99 statt auf 90 setzt. Somit landet ein Schritt nach oben, gefolgt von einem Schritt nach unten – oder umgekehrt – immer wieder beim Ausgangswert: 99 -> 100 -> 99.
Wird diese Option aktiviert, ignoriert das Eingabefeld den Wert von „ singleStep “, obwohl dieser beibehalten wird, sodass „ singleStep “ wirksam wird, falls die adaptive Dezimalschrittweite später deaktiviert wird.
Hinweis: Setter -Funktion für die Eigenschaft „ stepType “.
Siehe auch stepType().
[signal] void QSpinBox::textChanged(const QString &text)
Dieses Signal wird immer dann ausgelöst, wenn der Text des Spin-Feldes geändert wird. Der neue Text wird über die Methoden ` prefix()` und ` suffix()` an ` text ` übergeben.
[virtual protected] QString QSpinBox::textFromValue(int value) const
Diese virtuelle Funktion wird vom Spin-Feld verwendet, wann immer es den angegebenen Wert ` value` anzeigen muss. Die Standardimplementierung gibt eine Zeichenkette zurück, die ` value ` enthält und auf die übliche Weise mit ` QWidget::locale()` und `toString()` ausgegeben wird, wobei jedoch das Tausendertrennzeichen entfernt wird, sofern ` setGroupSeparatorShown()` nicht gesetzt ist. Eigenimplementierungen können beliebige Werte zurückgeben. (Siehe das Beispiel in der ausführlichen Beschreibung.)
Hinweis: QSpinBox ruft diese Funktion nicht für specialValueText() auf, und weder prefix() noch suffix() sollten im Rückgabewert enthalten sein.
Wenn Sie diese Funktion neu implementieren, müssen Sie möglicherweise auch valueFromText() und validate() neu implementieren.
Siehe auch valueFromText(), validate() und QLocale::groupSeparator().
[override virtual protected] QValidator::State QSpinBox::validate(QString &text, int &pos) const
Implementiert: ` QAbstractSpinBox::validate(QString &input, int &pos) const`.
[signal] void QSpinBox::valueChanged(int i)
Dieses Signal wird immer dann ausgelöst, wenn der Wert des Spin-Feldes geändert wird. Der ganzzahlige Wert des neuen Werts wird in „ i “ übergeben.
Hinweis: Notifier -Signal für die Eigenschaft „ value “.
[virtual protected] int QSpinBox::valueFromText(const QString &text) const
Diese virtuelle Funktion wird vom Spin-Feld immer dann verwendet, wenn es vom Benutzer eingegebene „ text “ als Wert interpretieren muss.
Unterklassen, die Werte aus dem Spin-Feld auf nicht-numerische Weise anzeigen müssen, müssen diese Funktion neu implementieren.
Hinweis: QSpinBox behandelt specialValueText() separat; diese Funktion befasst sich ausschließlich mit den anderen Werten.
Siehe auch ` textFromValue()` und ` validate()`.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
