Класс QScrollArea

Класс QScrollArea предоставляет область прокрутки для другого виджета. Подробнее...

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

Свойства

• alignment : Qt::Alignment
• widgetResizable : bool

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

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

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

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

Область прокрутки используется для отображения содержимого дочернего виджета в рамке. Если виджет превышает размер рамки, просмотр может предоставить полосы прокрутки, чтобы можно было просмотреть всю область дочернего виджета. Дочерний виджет должен быть указан с помощью setWidget(). Например:

QLabel *imageLabel = new QLabel;
QImage image("happyguy.png");
imageLabel->setPixmap(QPixmap::fromImage(image));

scrollArea = new QScrollArea;
scrollArea->setBackgroundRole(QPalette::Dark);
scrollArea->setWidget(imageLabel);

Приведённый выше код создаёт область прокрутки (показанную на изображениях ниже), содержащую метку изображения. При масштабировании изображения область прокрутки может предоставить необходимые полосы прокрутки:

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

Например, вы можете установить свойства QAbstractScrollArea::horizontalScrollBarPolicy и QAbstractScrollArea::verticalScrollBarPolicy. Или, если вы хотите, чтобы полосы прокрутки динамически настраивались при изменении содержимого области прокрутки, вы можете использовать функции horizontalScrollBar() и verticalScrollBar() (которые позволяют получить доступ к полосам прокрутки) и устанавливать значения полос прокрутки всякий раз, когда содержимое области прокрутки изменяется, используя функцию QScrollBar::setValue().

Вы можете получить доступ к дочернему виджету с помощью функции widget(). Область просмотра можно сделать масштабируемой с помощью функции setWidgetResizable(). Выравнивание виджета можно указать с помощью setAlignment().

Две вспомогательные функции ensureVisible() и ensureWidgetVisible() гарантируют видимость определённого региона содержимого в области просмотра, прокручивая содержимое при необходимости.

Рекомендованные размеры и макеты

При использовании области прокрутки для отображения содержимого пользовательского виджета важно убедиться, что рекомендованные размеры дочернего виджета установлены в подходящее значение. Если для дочернего виджета используется стандартный QWidget, может потребоваться вызвать QWidget::setMinimumSize(), чтобы гарантировать правильное отображение содержимого виджета в области прокрутки.

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

Полный пример использования класса QScrollArea см. в примере Image Viewer. В примере показано, как объединить QLabel и QScrollArea для отображения изображения.

См. также QAbstractScrollArea, QScrollBar и Пример Image Viewer.

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

QScrollArea::QScrollArea(QWidget *parent = nullptr)

Конструктор пустой области прокрутки с указанным parent.

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

[virtual] QScrollArea::~QScrollArea()

Удаляет область прокрутки и её дочерний виджет.

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

void QScrollArea::ensureVisible(int x, int y, int xmargin = 50, int ymargin = 50)

Прокручивает содержимое области прокрутки таким образом, чтобы точка (x, y) была видна внутри области просмотра с отступами, заданными в пикселях параметрами xmargin и ymargin. Если заданную точку нельзя достичь, содержимое прокручивается до ближайшей допустимой позиции. Значение по умолчанию для обоих отступов составляет 50 пикселей.

void QScrollArea::ensureWidgetVisible(QWidget *childWidget, int xmargin = 50, int ymargin = 50)

Прокручивает содержимое области прокрутки так, чтобы childWidget объекта QScrollArea::widget() был виден внутри области просмотра с отступами, заданными в пикселях параметрами xmargin и ymargin. Если заданную точку нельзя достичь, содержимое прокручивается до ближайшей допустимой позиции. Значение по умолчанию для обоих отступов составляет 50 пикселей.

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

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

[override virtual protected] bool QScrollArea::eventFilter(QObject *o, QEvent *e)

Переопределяет: QObject::eventFilter(QObject *watched, QEvent *event).

[override virtual] bool QScrollArea::focusNextPrevChild(bool next)

Переопределяет: QWidget::focusNextPrevChild(bool next).

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

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

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

Переопределяет: QAbstractScrollArea::scrollContentsBy(int dx, int dy).

void QScrollArea::setWidget(QWidget *widget)

Устанавливает виджет области прокрутки.

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

Свойство autoFillBackground виджета будет установлено в true.

Если область прокрутки видна при добавлении widget, необходимо явно вызвать show() для него.

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

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

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

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

QWidget *QScrollArea::takeWidget()

Удаляет виджет области прокрутки и передает владение им вызывающему коду.

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

[override virtual protected] QSize QScrollArea::viewportSizeHint() const

Переопределяет: QAbstractScrollArea::viewportSizeHint() const.

QWidget *QScrollArea::widget() const

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

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