Класс QAbstractScrollArea

Виджет QAbstractScrollArea предоставляет область прокрутки со скроллбарами по требованию. Подробнее...

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

Общие типы

Свойства

• horizontalScrollBarPolicy : Qt::ScrollBarPolicy
• sizeAdjustPolicy : SizeAdjustPolicy
• verticalScrollBarPolicy : Qt::ScrollBarPolicy

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

Реализованные публичные функции

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

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

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

QAbstractScrollArea — это низкоуровневая абстракция области прокрутки. Область предоставляет центральный виджет, называемый viewport, в котором содержимое области должно прокручиваться (т.е. видимые части содержимого рендерятся в viewport).

Рядом с областью просмотра находится вертикальная полоса прокрутки, а ниже — горизонтальная полоса прокрутки. Когда всё содержимое области помещается в область просмотра, каждая полоса прокрутки может быть либо видимой, либо скрытой в зависимости от Qt::ScrollBarPolicy полосы прокрутки. Когда полоса прокрутки скрыта, область просмотра расширяется, чтобы занять всё доступное пространство. Когда полоса прокрутки снова становится видимой, область просмотра уменьшается, чтобы освободить место для полосы прокрутки.

Можно зарезервировать область отступа вокруг области просмотра, см. setViewportMargins(). Эта функция в основном используется для размещения виджета QHeaderView над или рядом с областью прокрутки. Подклассы QAbstractScrollArea должны реализовывать отступы.

При наследовании от QAbstractScrollArea необходимо выполнить следующие действия:

• Управлять полосами прокрутки, задавая их диапазон, значение, шаг страницы и отслеживая их перемещения.
• Отображать содержимое области в области просмотра в соответствии со значениями полос прокрутки.
• Обрабатывать события, полученные областью просмотра в viewportEvent() — в частности, события изменения размера.
• Использовать viewport->update() для обновления содержимого области просмотра вместо update(), так как все операции рисования выполняются в области просмотра.

При политике прокрутки Qt::ScrollBarAsNeeded (по умолчанию) QAbstractScrollArea отображает полосы прокрутки, когда они предоставляют ненулевой диапазон прокрутки, и скрывает их в противном случае.

Полосы прокрутки и область просмотра должны обновляться всякий раз, когда область просмотра получает событие изменения размера или изменяется размер содержимого. Область просмотра также должна обновляться при изменении значений полос прокрутки. Начальные значения полос прокрутки часто устанавливаются при получении областью нового содержимого.

Мы приводим простой пример, в котором мы реализовали область прокрутки, которая может прокручивать любой QWidget. Мы делаем виджет дочерним элементом области просмотра; таким образом, нам не нужно рассчитывать, какую часть виджета отображать, а можно просто перемещать виджет с помощью QWidget::move(). Когда содержимое области или размер области просмотра изменяются, мы делаем следующее:

    QSize areaSize = viewport()->size();
    QSize  widgetSize = widget->size();

    verticalScrollBar()->setPageStep(areaSize.height());
    horizontalScrollBar()->setPageStep(areaSize.width());
    verticalScrollBar()->setRange(0, widgetSize.height() - areaSize.height());
    horizontalScrollBar()->setRange(0, widgetSize.width() - areaSize.width());
    updateWidgetPosition();

Когда изменяется значение полос прокрутки, нам нужно обновить положение виджета, то есть найти часть виджета, которая должна быть отображена в области просмотра:

    int hvalue = horizontalScrollBar()->value();
    int vvalue = verticalScrollBar()->value();
    QPoint topLeft = viewport()->rect().topLeft();

    widget->move(topLeft.x() - hvalue, topLeft.y() - vvalue);

Для отслеживания перемещений полос прокрутки переопределите виртуальную функцию scrollContentsBy(). Чтобы усовершенствовать поведение прокрутки, подключитесь к сигналу QAbstractSlider::actionTriggered() полосы прокрутки и настройте QAbstractSlider::sliderPosition по своему желанию.

Для удобства QAbstractScrollArea делает все события области просмотра доступными в обработчике виртуального события viewportEvent(). Специализированные обработчики QWidget переназначаются на события области просмотра в тех случаях, когда это имеет смысл. Переназначенные специализированные обработчики: paintEvent(), mousePressEvent(), mouseReleaseEvent(), mouseDoubleClickEvent(), mouseMoveEvent(), wheelEvent(), dragEnterEvent(), dragMoveEvent(), dragLeaveEvent(), dropEvent(), contextMenuEvent() и resizeEvent().

QScrollArea, который наследует QAbstractScrollArea, обеспечивает плавную прокрутку любого QWidget (то есть виджет прокручивается по пикселям). Вам нужно подклассировать QAbstractScrollArea только в том случае, если вам нужно более специализированное поведение. Это, например, верно, если всё содержимое области не подходит для отображения на QWidget, или если вы не хотите плавной прокрутки.

См. также QScrollArea.

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

enum QAbstractScrollArea::SizeAdjustPolicy

Этот перечисление определяет, как размер подсказки QAbstractScrollArea должен изменяться при изменении размера области просмотра.

Этот перечисление был введен или изменен в Qt 5.2.

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

QAbstractScrollArea::QAbstractScrollArea(QWidget *parent = nullptr)

Создаёт область просмотра.

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

[virtual] QAbstractScrollArea::~QAbstractScrollArea()

Удаляет область просмотра.

void QAbstractScrollArea::addScrollBarWidget(QWidget *widget, Qt::Alignment alignment)

Добавляет widget в качестве виджета полосы прокрутки в указанном расположении alignment.

Виджеты полос прокрутки отображаются рядом с горизонтальной или вертикальной полосой прокрутки и могут быть размещены по обе стороны от неё. Если вы хотите, чтобы виджеты полос прокрутки всегда отображались, установите политику полосы прокрутки для соответствующей полосы прокрутки в AlwaysOn.

alignment должен быть одним из Qt::Alignleft и Qt::AlignRight, что соответствует горизонтальной полосе прокрутки, или Qt::AlignTop и Qt::AlignBottom, что соответствует вертикальной полосе прокрутки.

Виджет полосы прокрутки может быть удалён путём переопределения родителя виджета или удаления виджета. Также можно скрыть виджет с помощью QWidget::hide()

Виджет полосы прокрутки будет изменён для соответствия геометрии полосы прокрутки для текущего стиля. Ниже описан случай для виджетов полос прокрутки на горизонтальной полосе прокрутки:

Высота виджета будет установлена для соответствия высоте полосы прокрутки. Для управления шириной виджета используйте QWidget::setMinimumWidth и QWidget::setMaximumWidth, или реализуйте QWidget::sizeHint() и установите горизонтальную политику размера. Если вам нужен квадратный виджет, вызовите QStyle::pixelMetric(QStyle::PM_ScrollBarExtent) и установите ширину в это значение.

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

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

[override virtual protected] void QAbstractScrollArea::contextMenuEvent(QContextMenuEvent *e)

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

Этот обработчик событий может быть переопределён в подклассе для получения событий контекстного меню для виджета viewport(). Событие передаётся в e.

См. также QWidget::contextMenuEvent().

QWidget *QAbstractScrollArea::cornerWidget() const

Возвращает виджет в углу между двумя полосами прокрутки.

По умолчанию виджет в углу отсутствует.

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

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

[override virtual protected] void QAbstractScrollArea::dragEnterEvent(QDragEnterEvent *event)

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

Обработчик этого события может быть переопределен в подклассе для получения событий входа перетаскивания (переданные в event) для виджета viewport().

См. также QWidget::dragEnterEvent().

[override virtual protected] void QAbstractScrollArea::dragLeaveEvent(QDragLeaveEvent *event)

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

Этот обработчик событий может быть переопределён в подклассе для получения событий выхода перетаскивания (переданные в event) для виджета viewport().

См. также QWidget::dragLeaveEvent().

[override virtual protected] void QAbstractScrollArea::dragMoveEvent(QDragMoveEvent *event)

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

Этот обработчик событий может быть переопределён в подклассе для получения событий перемещения перетаскивания (переданные в event) для виджета viewport().

См. также QWidget::dragMoveEvent().

[override virtual protected] void QAbstractScrollArea::dropEvent(QDropEvent *event)

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

Этот обработчик событий может быть переопределён в подклассе для получения событий падения (переданные в event) для виджета viewport().

См. также QWidget::dropEvent().

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

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

Это основной обработчик событий для виджета QAbstractScrollArea (а не области прокрутки viewport()). Указанное событие event — это общий объект события, который может потребоваться привести к соответствующему классу в зависимости от его типа.

См. также QEvent::type().

QScrollBar *QAbstractScrollArea::horizontalScrollBar() const

Возвращает горизонтальную полосу прокрутки.

См. также setHorizontalScrollBar(), horizontalScrollBarPolicy и verticalScrollBar().

[override virtual protected] void QAbstractScrollArea::keyPressEvent(QKeyEvent *e)

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

Этот метод вызывается с событием нажатия клавиши e, когда происходят нажатия клавиш. Он обрабатывает PageUp, PageDown, Up, Down, Left и Right, а все остальные нажатия клавиш игнорирует.

QSize QAbstractScrollArea::maximumViewportSize() const

Возвращает размер области просмотра, как если бы полосы прокрутки не имели допустимого диапазона прокрутки.

[override virtual] QSize QAbstractScrollArea::minimumSizeHint() const

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

[override virtual protected] void QAbstractScrollArea::mouseDoubleClickEvent(QMouseEvent *e)

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

Этот обработчик событий может быть переопределён в подклассе для получения событий двойного щелчка мышью для виджета viewport(). Событие передаётся в e.

См. также QWidget::mouseDoubleClickEvent().

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

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

Этот обработчик событий может быть переопределён в подклассе для получения событий перемещения мыши для виджета viewport(). Событие передаётся в e.

См. также QWidget::mouseMoveEvent().

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

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

Этот обработчик событий может быть переопределён в подклассе для получения событий нажатия мыши для виджета viewport(). Событие передаётся в e.

По умолчанию, реализация вызывает QWidget::mousePressEvent() для обработки всплывающих окон по умолчанию.

См. также QWidget::mousePressEvent().

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

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

Этот обработчик событий может быть переопределён в подклассе для получения событий отпускания мыши для виджета viewport(). Событие передаётся в e.

См. также QWidget::mouseReleaseEvent().

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

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

Этот обработчик событий может быть переопределён в подклассе для получения событий рисования (переданных в event) для виджета viewport().

Примечание: Если вы открываете painter, убедитесь, что открываете его в viewport().

См. также QWidget::paintEvent().

[override virtual protected] void QAbstractScrollArea::resizeEvent(QResizeEvent *event)

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

Этот обработчик событий может быть переопределён в подклассе для получения событий изменения размера (переданные в event) для виджета viewport().

Когда вызывается resizeEvent(), у области просмотра уже есть новая геометрия: её новый размер доступен через функцию QResizeEvent::size(), а старый размер — через QResizeEvent::oldSize().

См. также QWidget::resizeEvent().

QWidgetList QAbstractScrollArea::scrollBarWidgets(Qt::Alignment alignment)

Возвращает список текущих виджетов полос прокрутки. alignment может быть любой комбинацией четырёх флагов расположения.

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

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

[virtual protected] void QAbstractScrollArea::scrollContentsBy(int dx, int dy)

Этот виртуальный обработчик вызывается, когда полосы прокрутки сдвигаются на dx, dy, и, следовательно, содержимое области просмотра должно быть прокручено соответственно.

Реализация по умолчанию просто вызывает update() для всей viewport(), подклассы могут переопределить этот обработчик для оптимизации или — как QScrollArea — для перемещения виджета содержимого. Параметры dx и dy предназначены для удобства, чтобы класс знал, на сколько нужно прокрутить (полезно, например, при сдвиге пикселей). Вы также можете проигнорировать эти значения и прокрутить непосредственно до позиции, указанной полосами прокрутки.

Вызов этой функции для программированной прокрутки является ошибкой. Используйте полосы прокрутки вместо этого (например, вызвав QScrollBar::setValue() напрямую).

void QAbstractScrollArea::setCornerWidget(QWidget *widget)

Устанавливает виджет в углу между двумя полосами прокрутки в widget.

Вероятно, вы также захотите установить хотя бы один из режимов полос прокрутки в AlwaysOn.

Передача nullptr отображает в углу отсутствие виджета.

Любой предыдущий виджет угла скрывается.

Вы можете вызывать setCornerWidget() с одним и тем же виджетом в разные моменты времени.

Все виджеты, установленные здесь, будут удалены областью прокрутки при её уничтожении, если вы не переместите виджет в другое родительское окно отдельно после установки другого виджета угла (или nullptr).

Любой новый установленный виджет не должен иметь текущего родителя.

По умолчанию виджет в углу отсутствует.

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

См. также cornerWidget(), horizontalScrollBarPolicy и horizontalScrollBarPolicy.

void QAbstractScrollArea::setHorizontalScrollBar(QScrollBar *scrollBar)

Заменяет существующую горизонтальную полосу прокрутки на scrollBar и устанавливает все свойства ползунка бывшей полосы прокрутки на новую полосу прокрутки. Бывшая полоса прокрутки затем удаляется.

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

Функция была добавлена в Qt 4.2.

См. также horizontalScrollBar() и setVerticalScrollBar().

void QAbstractScrollArea::setVerticalScrollBar(QScrollBar *scrollBar)

Заменяет существующую вертикальную полосу прокрутки на scrollBar и устанавливает все свойства ползунка бывшей полосы прокрутки на новую полосу прокрутки. Бывшая полоса прокрутки затем удаляется.

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

Функция была добавлена в Qt 4.2.

См. также verticalScrollBar() и setHorizontalScrollBar().

void QAbstractScrollArea::setViewport(QWidget *widget)

Устанавливает область прокрутки в указанный widget. QAbstractScrollArea получит владение указанным widget.

Если widget равен nullptr, QAbstractScrollArea создаст новый экземпляр QWidget для области прокрутки.

Функция была добавлена в Qt 4.2.

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

[protected] void QAbstractScrollArea::setViewportMargins(int left, int top, int right, int bottom)

Устанавливает отступы вокруг области прокрутки до left, top, right и bottom. Это полезно для приложений, таких как табличные процессоры с «заблокированными» строками и столбцами. Отступы остаются пустыми; размещайте виджеты в неиспользуемой области.

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

По умолчанию все отступы равны нулю.

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

[protected] void QAbstractScrollArea::setViewportMargins(const QMargins &margins)

Устанавливает отступы margins вокруг области прокрутки. Это полезно для приложений, таких как табличные процессоры с «заблокированными» строками и столбцами. Отступы остаются пустыми; размещайте виджеты в неиспользуемой области.

По умолчанию все отступы равны нулю.

Функция была добавлена в Qt 4.6.

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

[virtual] void QAbstractScrollArea::setupViewport(QWidget *viewport)

Этот слот вызывается QAbstractScrollArea после вызова setViewport(viewport). Переопределите эту функцию в подклассе QAbstractScrollArea, чтобы инициализировать новый viewport перед его использованием.

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

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

Переопределяет: QFrame::sizeHint() const.

Возвращает свойство sizeHint области прокрутки. Размер определяется с помощью viewportSizeHint() плюс дополнительное пространство для полос прокрутки, если это необходимо.

QScrollBar *QAbstractScrollArea::verticalScrollBar() const

Возвращает вертикальную полосу прокрутки.

См. также setVerticalScrollBar(), verticalScrollBarPolicy и horizontalScrollBar().

QWidget *QAbstractScrollArea::viewport() const

Возвращает виджет области прокрутки.

Используйте функцию QScrollArea::widget(), чтобы получить содержимое виджета области прокрутки.

См. также setViewport() и QScrollArea::widget().

[virtual protected] bool QAbstractScrollArea::viewportEvent(QEvent *event)

Основной обработчик событий для области прокрутки (виджета viewport() ). Обрабатывает указанное событие event и может вызываться подклассами для предоставления разумного поведения по умолчанию.

Возвращает true для указания системе событий, что событие было обработано и больше не требует обработки; в противном случае возвращает false для указания того, что событие должно быть распространено дальше.

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

Специализированные обработчики событий области прокрутки: paintEvent(), mousePressEvent(), mouseReleaseEvent(), mouseDoubleClickEvent(), mouseMoveEvent(), wheelEvent(), dragEnterEvent(), dragMoveEvent(), dragLeaveEvent(), dropEvent(), contextMenuEvent() и resizeEvent().

[protected] QMargins QAbstractScrollArea::viewportMargins() const

Возвращает отступы вокруг области прокрутки. По умолчанию все отступы равны нулю.

Функция была добавлена в Qt 5.5.

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

[virtual protected] QSize QAbstractScrollArea::viewportSizeHint() const

Возвращает рекомендуемый размер для области прокрутки. Реализация по умолчанию возвращает viewport()->sizeHint(). Обратите внимание, что размер — это просто размер области прокрутки без видимых полос прокрутки.

Функция была добавлена в Qt 5.2.

[override virtual protected] void QAbstractScrollArea::wheelEvent(QWheelEvent *e)

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

Этот обработчик событий может быть переопределен в подклассе для получения событий прокрутки для виджета viewport(). Событие передается в e.

См. также QWidget::wheelEvent().