Класс QSpinBox

Класс QSpinBox предоставляет виджет спин-бокса. Подробнее...

• Список всех членов, включая наследуемые
• Устаревшие члены

Свойства

Открытые функции

Открытые слоты

Сигналы

Защищённые функции

Переопределённые защищённые функции

Подробное описание

QSpinBox предназначен для работы с целыми числами и дискретными наборами значений (например, названиями месяцев); используйте QDoubleSpinBox для значений с плавающей точкой.

QSpinBox позволяет пользователю выбирать значение, нажимая на кнопки «вверх/вниз» или нажимая клавиши «вверх/вниз» на клавиатуре для увеличения/уменьшения текущего отображаемого значения. Пользователь также может ввести значение вручную. Спин-бокс поддерживает целые значения, но может быть расширен для использования различных строк с помощью validate(), textFromValue() и valueFromText().

Каждый раз, когда значение меняется, QSpinBox излучает сигналы valueChanged() и textChanged(), первый из которых предоставляет int, а второй — QString. Сигнал textChanged() предоставляет значение с prefix() и suffix(). Текущее значение можно получить с помощью value() и установить с помощью setValue().

Нажатие кнопок «вверх/вниз» или использование клавиш ускорения «вверх/вниз» увеличит или уменьшит текущее значение на величину singleStep(). Если вы хотите изменить это поведение, вы можете переопределить виртуальную функцию stepBy(). Минимальное и максимальное значение, а также шаг можно задать с помощью одного из конструкторов и изменить позже с помощью setMinimum(), setMaximum() и setSingleStep().

Большинство спин-боксов являются направленными, но QSpinBox также может работать как круговой спин-бокс, т. е. если диапазон составляет 0-99, а текущее значение равно 99, нажатие «вверх» даст 0, если wrapping() установлено в true. Используйте setWrapping(), если нужно круговое поведение.

Отображаемое значение может быть дополнено и завершено произвольными строками, указывающими, например, валюту или единицу измерения. См. setPrefix() и setSuffix(). Текст в спин-боксе извлекается с помощью text() (который включает в себя любой prefix() и suffix()), или с помощью cleanText() (который не имеет prefix(), не имеет suffix() и не имеет начальных или конечных пробелов).

Часто желательно предоставить пользователю специальный (часто по умолчанию) выбор помимо диапазона числовых значений. См. setSpecialValueText() для того, как это сделать с QSpinBox.

Наследование от QSpinBox

Если prefix(), suffix() и specialValueText() не обеспечивают достаточно контроля, вы наследуете QSpinBox и переопределяете valueFromText() и textFromValue(). Например, вот код для пользовательского спин-бокса, который позволяет пользователю вводить размеры значков (например, «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);
}

См. пример Значки для полного исходного кода.

См. также QDoubleSpinBox, QDateTimeEdit, QSlider и Пример спин-боксов.

sb->setPrefix("$");

sb->setSuffix(" km");

Документация по функциям-членам

QSpinBox::QSpinBox(QWidget *parent = nullptr)

Конструирует спин-бокс с минимальным значением 0 и максимальным значением 99, значением шага 1. Значение изначально установлено в 0. Он подчиняется parent.

См. также setMinimum(), setMaximum() и setSingleStep().

[signal] void QSpinBox::textChanged(const QString &text)

Этот сигнал излучается всякий раз, когда текст спин-бокса изменяется. Новый текст передается в text с prefix() и suffix().

Эта функция была добавлена в Qt 5.14.

[signal] void QSpinBox::valueChanged(int i)

Этот сигнал излучается всякий раз, когда изменяется значение спин-бокса. Новое целое значение передается в i.

Примечание: Сигнал valueChanged перегружен в этом классе. Чтобы подключиться к этому сигналу, используя синтаксис указателя на функцию, Qt предоставляет удобную функцию для получения указателя на функцию, как показано в этом примере:

connect(spinBox, QOverload<int>::of(&QSpinBox::valueChanged),
    [=](int i){ /* ... */ });

Примечание: Сигнал уведомления для свойства value.

[virtual] QSpinBox::~QSpinBox()

Деструктор.

[override virtual protected] bool QSpinBox::event(QEvent *event)

Переопределяет: QAbstractSpinBox::event(QEvent *event).

[override virtual protected] void QSpinBox::fixup(QString &input) const

Переопределяет: QAbstractSpinBox::fixup(QString &input) const.

void QSpinBox::setRange(int minimum, int maximum)

Удобная функция для установки минимального и максимального значений с помощью одной функции.

setRange(minimum, maximum);

эквивалентно:

setMinimum(minimum);
setMaximum(maximum);

См. также minimum и maximum.

void QSpinBox::setStepType(QAbstractSpinBox::StepType stepType)

Устанавливает тип шага спин-бокса на stepType, который может быть единичным шагом или адаптивным десятичным шагом.

Адаптивный десятичный шаг означает, что размер шага будет непрерывно корректироваться до одной степени десяти ниже текущего значения. Таким образом, когда значение равно 1100, шаг устанавливается в 100, поэтому при увеличении на один шаг значение увеличивается до 1200. Для 1200 увеличение на один шаг приводит к значению 1300. Для отрицательных значений при уменьшении от -1100 значение изменяется на -1200.

Направление шага учитывается для обработки граничных случаев, поэтому при уменьшении от 100 значение изменяется на 99 вместо 90. Таким образом, увеличение на один шаг, за которым следует уменьшение на один шаг (или наоборот) всегда приводит к исходному значению; 99 -> 100 -> 99.

Установка этого параметра приведет к тому, что спин-бокс проигнорирует значение singleStep, хотя оно сохраняется, чтобы singleStep вступил в силу, если адаптивный десятичный шаг позже будет выключен.

Эта функция была представлена в Qt 5.12.

Примечание: Функция-сеттер для свойства stepType.

См. также stepType().

[virtual protected] QString QSpinBox::textFromValue(int value) const

Эта виртуальная функция используется спин-боксом всякий раз, когда ему нужно отобразить заданное значение value. По умолчанию реализация возвращает строку, содержащую value, напечатанное стандартным способом с использованием QWidget::locale().toString(), но с удаленным разделителем тысяч, если не установлено setGroupSeparatorShown(). Реализации могут возвращать что угодно. (См. пример в подробном описании.)

Примечание: QSpinBox не вызывает эту функцию для specialValueText(), и ни prefix(), ни suffix() не должны включаться в возвращаемое значение.

Если вы переопределяете эту функцию, вам также может потребоваться переопределить valueFromText() и validate()

См. также valueFromText(), validate() и QLocale::groupSeparator().

[override virtual protected] QValidator::State QSpinBox::validate(QString &text, int &pos) const

Переопределяет: QAbstractSpinBox::validate(QString &input, int &pos) const.

[virtual protected] int QSpinBox::valueFromText(const QString &text) const

Эта виртуальная функция используется спин-боксом всякий раз, когда ему нужно интерпретировать text, введенное пользователем, как значение.

Подклассы, которым необходимо отображать значения спин-бокса нечисловым способом, должны переопределить эту функцию.

Примечание: QSpinBox обрабатывает specialValueText() отдельно; эта функция касается только других значений.

См. также textFromValue() и validate().