Sur cette page

QScrollArea Class

La classe QScrollArea permet d'afficher un autre widget dans une vue défilante. En savoir plus...

En-tête : #include <QScrollArea>
CMake : find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake : QT += widgets
Hérite de : QAbstractScrollArea

Propriétés

Fonctions publiques

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

Fonctions publiques réimplémentées

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

Fonctions protégées réimplémentées

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

Description détaillée

Une zone de défilement sert à afficher le contenu d’un widget enfant au sein d’un cadre. Si le widget dépasse la taille du cadre, la vue peut afficher des barres de défilement afin que l’intégralité du widget enfant soit visible. Le widget enfant doit être spécifié à l’aide de la fonction ` setWidget()`. Par exemple :

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

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

Le code ci-dessus crée une zone de défilement (illustrée dans les images ci-dessous) contenant une étiquette d’image. Lorsque l’image est redimensionnée, la zone de défilement peut afficher les barres de défilement nécessaires :

Image sans barre de défilementImage avec une barre de défilement horizontaleImage comportant une barre de défilement horizontale et une barre de défilement verticale

L’apparence des barres de défilement dépend de la propriété ` scroll bar policies` actuellement définie. Vous pouvez contrôler l’apparence des barres de défilement à l’aide des fonctionnalités héritées de ` QAbstractScrollArea`.

Par exemple, vous pouvez définir les propriétés ` QAbstractScrollArea::horizontalScrollBarPolicy ` et ` QAbstractScrollArea::verticalScrollBarPolicy `. Ou bien, si vous souhaitez que les barres de défilement s'ajustent dynamiquement lorsque le contenu de la zone de défilement change, vous pouvez utiliser les fonctions ` horizontalScrollBar()` et ` verticalScrollBar()` (qui vous permettent d'accéder aux barres de défilement) et définir les valeurs des barres de défilement chaque fois que le contenu de la zone de défilement change, à l'aide de la fonction ` QScrollBar::setValue()`.

Vous pouvez récupérer le widget enfant à l’aide de la fonction widget(). La vue peut être rendue redimensionnable grâce à la fonction setWidgetResizable(). L’alignement du widget peut être spécifié avec setAlignment().

Deux fonctions pratiques, ensureVisible() et ensureWidgetVisible(), garantissent qu’une certaine partie du contenu reste visible dans la fenêtre d’affichage, en faisant défiler le contenu si nécessaire.

Conseils sur la taille et les mises en page

Lorsqu’on utilise une zone de défilement pour afficher le contenu d’un widget personnalisé, il est important de s’assurer que la propriété ` size hint ` du widget enfant est définie sur une valeur appropriée. Si une mise en page standard ` QWidget ` est utilisée pour le widget enfant, il peut être nécessaire d’appeler la fonction ` QWidget::setMinimumSize()` pour garantir que le contenu du widget s’affiche correctement dans la zone de défilement.

Si une zone de défilement est utilisée pour afficher le contenu d’un widget contenant des widgets enfants disposés dans une mise en page, il est important de savoir que la politique de taille de la mise en page déterminera également la taille du widget. Cela est particulièrement utile à savoir si vous avez l’intention de modifier dynamiquement le contenu de la mise en page. Dans de tels cas, définir la propriété ` size constraint ` de la mise en page sur une valeur imposant des contraintes sur la taille minimale et/ou maximale de la mise en page (par exemple, ` QLayout::SetMinAndMaxSize`) entraînera la mise à jour de la taille de la zone de défilement chaque fois que le contenu de la mise en page changera.

Voir également QAbstractScrollArea et QScrollBar.

Documentation sur les propriétés

alignment : Qt::Alignment

Cette propriété définit l'alignement du widget de la zone de défilement

Un alignement valide est une combinaison des indicateurs suivants :

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

Par défaut, le widget reste ancré dans le coin supérieur gauche de la zone de défilement.

Fonctions d'accès :

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

widgetResizable : bool

Cette propriété détermine si la zone de défilement doit redimensionner le widget d'affichage

Si cette propriété est définie sur « false » (valeur par défaut), la zone de défilement respecte la taille de son widget. Quelle que soit la valeur de cette propriété, vous pouvez redimensionner le widget par programmation à l’aide de ` widget()` -> `resize()`, et la zone de défilement s’adaptera automatiquement à la nouvelle taille.

Si cette propriété est définie sur « true », la zone de défilement redimensionnera automatiquement le widget afin d’éviter l’affichage de barres de défilement lorsque cela est possible, ou pour tirer parti de l’espace supplémentaire disponible.

Fonctions d'accès :

bool widgetResizable() const
void setWidgetResizable(bool resizable)

Documentation des fonctions membres

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

Crée une zone de défilement vide avec l'parent spécifiée.

Voir aussi setWidget().

[virtual noexcept] QScrollArea::~QScrollArea()

Supprime la zone de défilement et son widget enfant.

Voir également setWidget().

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

Fait défiler le contenu de la zone de défilement de manière à ce que le point (x, y) soit visible dans la zone de la fenêtre d'affichage dont les marges sont spécifiées en pixels par xmargin et ymargin. Si le point spécifié n'est pas accessible, le contenu est déplacé vers la position valide la plus proche. La valeur par défaut des deux marges est de 50 pixels.

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

Fait défiler le contenu de la zone de défilement de manière à ce que l'childWidget de QScrollArea::widget() soit visible dans la fenêtre d'affichage, en respectant les marges spécifiées en pixels par xmargin et ymargin. Si le point spécifié n'est pas accessible, le contenu est déplacé vers la position valide la plus proche. La valeur par défaut pour les deux marges est de 50 pixels.

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

Réimplémente : QAbstractScrollArea::event(QEvent *event).

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

Réimplémente : QObject::eventFilter(QObject *watched, QEvent *event).

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

Réimplémente : QWidget::focusNextPrevChild(bool next).

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

Réimplémente : QAbstractScrollArea::resizeEvent(QResizeEvent *event).

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

Réimplémente : QAbstractScrollArea::scrollContentsBy(int dx, int dy).

void QScrollArea::setWidget(QWidget *widget)

Définit l'widget de la zone de défilement.

L'widget devient un enfant de la zone de défilement et sera détruit lorsque la zone de défilement sera supprimée ou lorsqu'un nouveau widget sera défini.

La propriété ` autoFillBackground ` du widget sera définie sur ` true`.

Si la zone de défilement est visible lorsque l’ widget est ajouté, vous devez l’ show() explicitement.

Notez que vous devez ajouter la mise en page de ` widget ` avant d’appeler cette fonction ; si vous l’ajoutez plus tard, le ` widget ` ne sera pas visible, quel que soit le moment où vous appelez ` show()` sur la zone de défilement. Dans ce cas, vous ne pourrez pas non plus appeler ` show()` sur ` widget ` ultérieurement.

Voir également ` widget()`.

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

Réimplémente : QAbstractScrollArea::sizeHint() const.

QWidget *QScrollArea::takeWidget()

Supprime le widget de la zone de défilement et transfère la propriété de ce widget à l'appelant.

Voir également widget().

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

Réimplémente : QAbstractScrollArea::viewportSizeHint() const.

QWidget *QScrollArea::widget() const

Renvoie le widget de la zone de défilement, ou ` nullptr ` s'il n'y en a pas.

Voir aussi setWidget().

© 2026 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.