Класс QAbstractScrollArea

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

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

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

Свойства

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

• 6 свойств унаследовано от QFrame
• 59 свойств унаследовано от QWidget
• 1 свойство унаследовано от QObject

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

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

• 14 открытых функций унаследовано от QFrame
• 214 открытых функций унаследовано от QWidget
• 32 открытых функции унаследовано от QObject
• 14 открытых функций унаследовано от QPaintDevice

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

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

• 4 защищенных функции унаследованы от QFrame
• 35 защищенных функций унаследованы от QWidget
• 9 защищенных функций унаследованы от QObject
• 1 защищенная функция унаследована от QPaintDevice

Дополнительные унаследованные члены

• 19 публичных слотов унаследованы от QWidget
• 1 публичный слот унаследован от QObject
• 3 сигналов унаследованы от QWidget
• 2 сигнала унаследованы от QObject
• 5 статических публичных членов унаследованы от QWidget
• 11 статических публичных членов унаследованы от QObject
• 1 защищенный слот унаследован от QWidget

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

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

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(), событие нажатия мыши(), событие отпускания мыши(), двойной щелчок мыши(), событие движения мыши(), wheelEvent(), dragEnterEvent(), dragMoveEvent(), dragLeaveEvent(), dropEvent(), contextMenuEvent() и resizeEvent().

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

См. также QScrollArea.

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

enum QAbstractScrollArea::SizeAdjustPolicy

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

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

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

QAbstractScrollArea::QAbstractScrollArea(QWidget *parent = Q_NULLPTR)

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

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

QAbstractScrollArea::~QAbstractScrollArea()

Уничтожает область просмотра.

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) и установите ширину в это значение.

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

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

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

Переопределено из QWidget::contextMenuEvent().

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

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

QWidget *QAbstractScrollArea::cornerWidget() const

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

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

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

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

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

Переопределено из QWidget::dragEnterEvent().

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

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

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

Переопределено из QWidget::dragLeaveEvent().

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

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

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

Переопределено из QWidget::dragMoveEvent().

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

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

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

Переопределено из QWidget::dropEvent().

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

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

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

Переопределено из QObject::event().

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

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

QScrollBar *QAbstractScrollArea::horizontalScrollBar() const

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

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

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

Переопределено из QWidget::keyPressEvent().

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

QSize QAbstractScrollArea::maximumViewportSize() const

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

[virtual] QSize QAbstractScrollArea::minimumSizeHint() const

Переопределено из QWidget::minimumSizeHint().

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

Переопределено из QWidget::mouseDoubleClickEvent().

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

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

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

Переопределено из QWidget::mouseMoveEvent().

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

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

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

Переопределено из QWidget::mousePressEvent().

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

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

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

Переопределено из QWidget::mouseReleaseEvent().

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

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

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

Переопределено из QWidget::paintEvent().

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

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

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

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

Переопределено из QWidget::resizeEvent().

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

Когда вызывается resizeEvent(), у viewport уже есть новые геометрические параметры: его новый размер доступен через функцию 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, и, следовательно, содержимое viewport должно быть прокручено соответствующим образом.

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

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

void QAbstractScrollArea::setCornerWidget(QWidget *widget)

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

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

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

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

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

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

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

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

Эта функция была добавлена в 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)

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

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

Эта функция была добавлена в 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().

[virtual] QSize QAbstractScrollArea::sizeHint() const

Переопределено из QWidget::sizeHint().

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

QScrollBar *QAbstractScrollArea::verticalScrollBar() const

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

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

QWidget *QAbstractScrollArea::viewport() const

Возвращает виджет viewport.

Используйте функцию 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.

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

Переопределено из QWidget::wheelEvent().

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

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