Класс QAbstractScrollArea

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

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

Открытые типы

Свойства

• Политика горизонтальной полосы прокрутки : Qt::ScrollBarPolicy
• Политика изменения размера : Политика изменения размера
• Политика вертикальной полосы прокрутки : Qt::ScrollBarPolicy

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

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

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

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

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

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

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

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

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

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

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

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

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

    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();

При изменении значения полос прокрутки нам необходимо обновить позицию виджета, то есть найти часть виджета, которая должна быть отображена в viewport:

    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 делает все события viewport доступными в обработчике виртуальной функции viewportEvent(). Специализированные обработчики виджета QWidget перенаправляются на события viewport в тех случаях, когда это имеет смысл. Перенаправленные специализированные обработчики: paintEvent(), mousePressEvent(), mouseReleaseEvent(), mouseDoubleClickEvent(), mouseMoveEvent(), wheelEvent(), dragEnterEvent(), dragMoveEvent(), dragLeaveEvent(), dropEvent(), contextMenuEvent() и resizeEvent().

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

См. также QScrollArea.

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

[since 5.2] перечисление QAbstractScrollArea::SizeAdjustPolicy

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

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

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

QAbstractScrollArea::QAbstractScrollArea(QWidget *parent = nullptr)

Создаёт viewport.

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

[virtual] QAbstractScrollArea::~QAbstractScrollArea()

Удаляет viewport.

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

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

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

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

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

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

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

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

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

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

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

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

QWidget *QAbstractScrollArea::cornerWidget() const

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

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

См. также 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().

Примечание: Если вы открываете рисовальщик, убедитесь, что он открыт для 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 может быть любой комбинацией четырёх флагов расположения.

См. также 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).

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

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

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

void QAbstractScrollArea::setHorizontalScrollBar(QScrollBar *scrollBar)

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

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

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

void QAbstractScrollArea::setVerticalScrollBar(QScrollBar *scrollBar)

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

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

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

void QAbstractScrollArea::setViewport(QWidget *widget)

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

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

См. также 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 вокруг области прокрутки. Это полезно для приложений, таких как электронные таблицы с "заблокированными" строками и столбцами. Поля остаются пустыми; размещайте виджеты в неиспользуемых областях.

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

См. также 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, since 5.5] QMargins QAbstractScrollArea::viewportMargins() const

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

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

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

[virtual protected, since 5.2] 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().