Back to Qt.io
Contact Us Blog Download Qt

QScrollArea Class

Die Klasse QScrollArea bietet eine scrollende Ansicht auf ein anderes Widget. Mehr...

Kopfzeile: #include <QScrollArea>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
Vererbungen: QAbstractScrollArea

Eigenschaften

Öffentliche Funktionen

QScrollArea(QWidget *parent = nullptr)
virtual ~QScrollArea()
Qt::Alignment alignment() const
void ensureVisible(int x, int y, int xmargin = 50, int ymargin = 50)
void ensureWidgetVisible(QWidget *childWidget, int xmargin = 50, int ymargin = 50)
void setAlignment(Qt::Alignment)
void setWidget(QWidget *widget)
void setWidgetResizable(bool resizable)
QWidget *takeWidget()
QWidget *widget() const
bool widgetResizable() const

Reimplementierte öffentliche Funktionen

virtual bool focusNextPrevChild(bool next) override
virtual QSize sizeHint() const override

Reimplementierte geschützte Funktionen

virtual bool event(QEvent *e) override
virtual bool eventFilter(QObject *o, QEvent *e) override
virtual void resizeEvent(QResizeEvent *) override
virtual void scrollContentsBy(int dx, int dy) override
virtual QSize viewportSizeHint() const override

Detaillierte Beschreibung

Ein Bildlaufbereich wird verwendet, um den Inhalt eines untergeordneten Widgets innerhalb eines Rahmens anzuzeigen. Wenn das Widget die Größe des Frames überschreitet, kann die Ansicht Bildlaufleisten bereitstellen, so dass der gesamte Bereich des untergeordneten Widgets angezeigt werden kann. Das untergeordnete Widget muss mit setWidget() angegeben werden. Ein Beispiel:

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

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

Der obige Code erstellt einen Bildlaufbereich (wie in den Bildern unten gezeigt), der eine Bildbeschriftung enthält. Wenn das Bild skaliert wird, kann der Bildlaufbereich die erforderlichen Bildlaufleisten bereitstellen:

Das Aussehen der Bildlaufleisten hängt von der aktuell eingestellten scroll bar policies ab. Sie können das Aussehen der Bildlaufleisten mit Hilfe der von QAbstractScrollArea geerbten Funktionalität steuern.

Sie können zum Beispiel die Eigenschaften QAbstractScrollArea::horizontalScrollBarPolicy und QAbstractScrollArea::verticalScrollBarPolicy einstellen. Wenn Sie möchten, dass sich die Bildlaufleisten dynamisch anpassen, wenn sich der Inhalt des Bildlaufbereichs ändert, können Sie die Funktionen horizontalScrollBar() und verticalScrollBar() verwenden (mit denen Sie auf die Bildlaufleisten zugreifen können) und die Werte der Bildlaufleisten mit der Funktion QScrollBar::setValue() einstellen, wenn sich der Inhalt des Bildlaufbereichs ändert.

Sie können das Child-Widget mit der Funktion widget() abrufen. Die Ansicht kann mit der Funktion setWidgetResizable() in der Größe verändert werden. Die Ausrichtung des Widgets kann mit setAlignment() festgelegt werden.

Zwei Komfortfunktionen ensureVisible() und ensureWidgetVisible() sorgen dafür, dass ein bestimmter Bereich des Inhalts innerhalb des Ansichtsfensters sichtbar ist, indem sie den Inhalt bei Bedarf scrollen.

Größenhinweise und Layouts

Wenn Sie einen Scrollbereich verwenden, um den Inhalt eines benutzerdefinierten Widgets anzuzeigen, ist es wichtig sicherzustellen, dass size hint des Kind-Widgets auf einen geeigneten Wert eingestellt ist. Wenn ein Standard QWidget für das untergeordnete Widget verwendet wird, kann es notwendig sein, QWidget::setMinimumSize() aufzurufen, um sicherzustellen, dass der Inhalt des Widgets innerhalb des Rollbereichs korrekt angezeigt wird.

Wenn ein Bildlaufbereich verwendet wird, um den Inhalt eines Widgets anzuzeigen, das in einem Layout angeordnete untergeordnete Widgets enthält, ist es wichtig zu wissen, dass die Größenrichtlinie des Layouts auch die Größe des Widgets bestimmt. Dies ist vor allem dann wichtig zu wissen, wenn Sie beabsichtigen, den Inhalt des Layouts dynamisch zu ändern. Wenn Sie in solchen Fällen die Eigenschaft size constraint des Layouts auf eine Eigenschaft setzen, die Beschränkungen für die minimale und/oder maximale Größe des Layouts enthält (z. B. QLayout::SetMinAndMaxSize), wird die Größe des Bildlaufbereichs aktualisiert, sobald sich der Inhalt des Layouts ändert.

Siehe auch QAbstractScrollArea und QScrollBar.

Dokumentation der Eigenschaft

alignment : Qt::Alignment

Diese Eigenschaft enthält die Ausrichtung des Widgets des Bildlaufbereichs

Eine gültige Ausrichtung ist eine Kombination aus den folgenden Flags:

  • Qt::AlignLeft
  • Qt::AlignHCenter
  • Qt::AlignRight
  • Qt::AlignTop
  • Qt::AlignVCenter
  • Qt::AlignBottom

Standardmäßig bleibt das Widget in der linken oberen Ecke des Bildlaufbereichs verankert.

Zugriffsfunktionen:

Qt::Alignment alignment() const
void setAlignment(Qt::Alignment)

widgetResizable : bool

Diese Eigenschaft legt fest, ob der Bildlaufbereich die Größe des Ansichtswidgets anpassen soll.

Wenn diese Eigenschaft auf false (Standard) gesetzt ist, behält der Bildlaufbereich die Größe seines Widgets bei. Unabhängig von dieser Eigenschaft können Sie die Größe des Widgets mit widget()->resize() programmatisch ändern, und der Bildlaufbereich passt sich automatisch an die neue Größe an.

Wenn diese Eigenschaft auf true gesetzt ist, passt der Bildlaufbereich die Größe des Widgets automatisch an, um Bildlaufleisten zu vermeiden, wo sie vermieden werden können, oder um zusätzlichen Platz zu nutzen.

Zugriff auf Funktionen:

bool widgetResizable() const
void setWidgetResizable(bool resizable)

Dokumentation der Mitgliedsfunktionen

[explicit] QScrollArea::QScrollArea(QWidget *parent = nullptr)

Konstruiert einen leeren Bildlaufbereich mit dem angegebenen parent.

Siehe auch setWidget().

[virtual noexcept] QScrollArea::~QScrollArea()

Zerstört den Bildlaufbereich und sein untergeordnetes Widget.

Siehe auch setWidget().

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

Rollt den Inhalt des Bildlaufbereichs so, dass der Punkt (x, y) innerhalb des Bereichs des Ansichtsfensters mit den durch xmargin und ymargin angegebenen Rändern in Pixeln sichtbar ist. Wenn der angegebene Punkt nicht erreicht werden kann, wird der Inhalt an die nächstgelegene gültige Position gerollt. Der Standardwert für beide Ränder beträgt 50 Pixel.

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

Verschiebt den Inhalt des Bildlaufbereichs so, dass childWidget von QScrollArea::widget() innerhalb des Ansichtsfensters mit den durch xmargin und ymargin angegebenen Rändern in Pixeln sichtbar ist. Wenn der angegebene Punkt nicht erreicht werden kann, wird der Inhalt an die nächstgelegene gültige Position verschoben. Der Standardwert für beide Ränder beträgt 50 Pixel.

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

Reimplements: QAbstractScrollArea::event(QEvent *Event).

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

Reimplements: QObject::eventFilter(QObject *watched, QEvent *event).

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

Reimplements: QWidget::focusNextPrevChild(bool next).

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

Reimplements: QAbstractScrollArea::resizeEvent(QResizeEvent *event).

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

Reimplements: QAbstractScrollArea::scrollContentsBy(int dx, int dy).

void QScrollArea::setWidget(QWidget *widget)

Legt den widget des Bildlaufbereichs fest.

widget wird ein untergeordnetes Element des Bildlaufbereichs und wird zerstört, wenn der Bildlaufbereich gelöscht oder ein neues Widget festgelegt wird.

Die Eigenschaft autoFillBackground des Widgets wird auf true gesetzt.

Wenn der Bildlaufbereich sichtbar ist, wenn widget hinzugefügt wird, müssen Sie ihn explizit show().

Beachten Sie, dass Sie das Layout von widget hinzufügen müssen, bevor Sie diese Funktion aufrufen; wenn Sie es später hinzufügen, wird widget nicht sichtbar sein - unabhängig davon, wann Sie show() den Bildlaufbereich hinzufügen. In diesem Fall können Sie auch nicht show() die widget später hinzufügen.

Siehe auch widget().

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

Reimplements: QAbstractScrollArea::sizeHint() const.

QWidget *QScrollArea::takeWidget()

Entfernt das Widget des Bildlaufbereichs und übergibt den Besitz des Widgets an den Aufrufer.

Siehe auch widget().

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

Reimplements: QAbstractScrollArea::viewportSizeHint() const.

QWidget *QScrollArea::widget() const

Gibt das Widget des Bildlaufbereichs zurück, oder nullptr, wenn es keines gibt.

Siehe auch setWidget().

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.