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
- alignment : Qt::Alignment
- widgetResizable : bool
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 :
![]() | ![]() | ![]() |
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::AlignLeftQt::AlignHCenterQt::AlignRightQt::AlignTopQt::AlignVCenterQt::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.


