Класс QScrollBar

Виджет QScrollBar предоставляет полосу прокрутки по вертикали или горизонтали. Подробнее...

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

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

Переопределённые открытые функции

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

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

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

Полоса прокрутки — это элемент управления, позволяющий пользователю получить доступ к частям документа, которые больше, чем сам виджет для отображения. Она предоставляет визуальное представление текущего положения пользователя в документе и количества видимой части документа. Полосы прокрутки обычно оснащены другими элементами управления, которые обеспечивают более точную навигацию. Qt отображает полосы прокрутки способом, соответствующим каждой платформе.

Если вам нужно предоставить прокручиваемый вид на другой виджет, удобнее использовать класс QScrollArea, поскольку он предоставляет виджет области просмотра и полосы прокрутки. QScrollBar полезен, если вам нужно реализовать аналогичную функциональность для специализированных виджетов, использующих QAbstractScrollArea; например, если вы решили унаследовать от QAbstractItemView. В большинстве других ситуаций, когда используется элемент управления ползунком для получения значения в заданном диапазоне, класс QSlider может быть более подходящим для ваших нужд.

Каждая полоса прокрутки имеет значение, указывающее, насколько далеко ползунок находится от начала полосы прокрутки; это значение получается с помощью value() и устанавливается с помощью setValue(). Это значение всегда находится в диапазоне значений, определённых для полосы прокрутки, от minimum() до maximum() включительно. Диапазон допустимых значений можно задать с помощью setMinimum() и setMaximum(). При минимальном значении верхний край ползунка (для вертикальной полосы прокрутки) или левый край (для горизонтальной полосы прокрутки) будет вверху (или слева) полосы прокрутки. При максимальном значении нижний (или правый) край ползунка будет внизу (или справа) полосы прокрутки.

Длина ползунка обычно связана со значением шага страницы и, как правило, представляет собой долю области документа, отображаемой в прокручиваемом представлении. Шаг страницы — это величина изменения значения при нажатии пользователем клавиш Page Up и Page Down, и он устанавливается с помощью setPageStep(). Меньшие изменения значения, определяемые шагом строки, производятся с помощью клавиш со стрелками, и эта величина устанавливается с помощью setSingleStep().

Обратите внимание, что диапазон используемых значений независим от фактического размера виджета полосы прокрутки. Вам не нужно учитывать это при выборе значений для диапазона и шага страницы.

Диапазон значений, указанный для полосы прокрутки, часто определяется иначе, чем для QSlider, поскольку необходимо учитывать длину ползунка. Если у нас есть документ с 100 строками, и мы можем отобразить только 20 строк в виджете, мы можем захотеть создать полосу прокрутки с шагом страницы 20, минимальным значением 0 и максимальным значением 80. Это даст нам полосу прокрутки с пятью "страницами".

Связь между длиной документа, диапазоном значений, используемых в полосе прокрутки, и шагом страницы проста во многих распространённых ситуациях. Диапазон значений полосы прокрутки определяется вычитанием выбранного шага страницы из некоторого значения, представляющего длину документа. В таких случаях полезно следующее уравнение: длина документа = maximum() - minimum() + pageStep().

QScrollBar предоставляет только целочисленные диапазоны. Обратите внимание, что хотя QScrollBar обрабатывает очень большие числа, полосы прокрутки на современных экранах не могут полезно представлять диапазоны свыше примерно 100 000 пикселей. За пределами этого становится трудно пользователю управлять ползунком с помощью клавиатуры или мыши, а стрелки прокрутки будут иметь ограниченное применение.

ScrollBar наследует полный набор сигналов от QAbstractSlider:

• valueChanged() генерируется при изменении значения полосы прокрутки. Флаг отслеживания (tracking) определяет, генерируется ли этот сигнал во время взаимодействия пользователя.
• rangeChanged() генерируется при изменении диапазона значений полосы прокрутки.
• sliderPressed() генерируется при начале перетаскивания ползунка.
• sliderMoved() генерируется при перетаскивании ползунка.
• sliderReleased() генерируется при отпускании ползунка.
• actionTriggered() генерируется при изменении полосы прокрутки взаимодействием пользователя или функцией triggerAction().

Полосу прокрутки можно управлять с помощью клавиатуры, но она имеет значение по умолчанию focusPolicy() Qt::NoFocus. Используйте setFocusPolicy(), чтобы включить взаимодействие с полосой прокрутки с помощью клавиатуры:

• Клавиши влево/вправо перемещают горизонтальную полосу прокрутки на один шаг.
• Клавиши вверх/вниз перемещают вертикальную полосу прокрутки на один шаг.
• PageUp перемещает вверх на одну страницу.
• PageDown перемещает вниз на одну страницу.
• Home перемещает к началу (минимальному).
• End перемещает к концу (максимальному).

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

Большинство стилей графического интерфейса используют значение pageStep() для расчёта размера ползунка.

См. также QScrollArea, QSlider, QDial, QSpinBox, Руководство по проектированию графического интерфейса пользователя: Полоса прокрутки и Пример с ползунками.

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

QScrollBar::QScrollBar(Qt::Orientation orientation, QWidget *parent = nullptr)

Создаёт полосу прокрутки с заданной orientation.

Аргумент parent передаётся в конструктор QWidget.

Значение minimum по умолчанию 0, maximum 99, с размером singleStep 1 и pageStep 10, и начальным значением value 0.

QScrollBar::QScrollBar(QWidget *parent = nullptr)

Создаёт вертикальную полосу прокрутки.

Аргумент parent передаётся в конструктор QWidget.

Значение minimum по умолчанию 0, maximum 99, с размером singleStep 1 и pageStep 10, и начальным значением value 0.

[virtual] QScrollBar::~QScrollBar()

Уничтожает полосу прокрутки.

[override virtual protected] void QScrollBar::contextMenuEvent(QContextMenuEvent *event)

Переопределяет: QWidget::contextMenuEvent(QContextMenuEvent *event).

[override virtual] bool QScrollBar::event(QEvent *event)

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

[override virtual protected] void QScrollBar::hideEvent(QHideEvent *)

Переопределяет: QWidget::hideEvent(QHideEvent *event).

[virtual protected] void QScrollBar::initStyleOption(QStyleOptionSlider *option) const

Инициализирует option значениями из этой QScrollBar. Этот метод полезен для подклассов, когда им нужен QStyleOptionSlider, но они не хотят заполнять всю информацию сами.

См. также QStyleOption::initFrom().

[override virtual protected] void QScrollBar::mouseMoveEvent(QMouseEvent *e)

Переопределяет: QWidget::mouseMoveEvent(QMouseEvent *event).

[override virtual protected] void QScrollBar::mousePressEvent(QMouseEvent *e)

Переопределяет: QWidget::mousePressEvent(QMouseEvent *event).

[override virtual protected] void QScrollBar::mouseReleaseEvent(QMouseEvent *e)

Переопределяет: QWidget::mouseReleaseEvent(QMouseEvent *event).

[override virtual protected] void QScrollBar::paintEvent(QPaintEvent *)

Переопределяет: QWidget::paintEvent(QPaintEvent *event).

[override virtual] QSize QScrollBar::sizeHint() const

Переопределяет функцию доступа к свойству: QWidget::sizeHint.

[override virtual protected] void QScrollBar::sliderChange(QAbstractSlider::SliderChange change)

Переопределяет: QAbstractSlider::sliderChange(QAbstractSlider::SliderChange change).

[override virtual protected] void QScrollBar::wheelEvent(QWheelEvent *event)

Переопределяет: QAbstractSlider::wheelEvent(QWheelEvent *e).