QScrollArea Class
La classe QScrollArea permet de faire défiler une vue sur un autre widget. Plus d'informations...
| En-tête : | #include <QScrollArea> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS Widgets)target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake : | QT += widgets |
| Héritages : | 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 est utilisée pour afficher le contenu d'un widget enfant dans un cadre. Si le widget dépasse la taille du cadre, la vue peut fournir des barres de défilement afin que la totalité de la zone du widget enfant puisse être visualisée. Le widget enfant doit être spécifié à l'aide de setWidget(). Par exemple, le code ci-dessus crée une zone de défilement :
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. Lors de la mise à l'échelle de l'image, la zone de défilement peut fournir les barres de défilement nécessaires :
 |  |  |
L'apparence des barres de défilement dépend de la configuration actuelle de scroll bar policies. Vous pouvez contrôler l'apparence des barres de défilement en utilisant la fonctionnalité héritée de QAbstractScrollArea.
Par exemple, vous pouvez définir les propriétés QAbstractScrollArea::horizontalScrollBarPolicy et QAbstractScrollArea::verticalScrollBarPolicy. 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 lorsque 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 redimensionnée à l'aide de la fonction setWidgetResizable(). L'alignement du widget peut être spécifié à l'aide de la fonction setAlignment().
Deux fonctions de commodité, ensureVisible() et ensureWidgetVisible(), permettent de s'assurer qu'une certaine partie du contenu est visible à l'intérieur de la fenêtre de visualisation, en faisant défiler le contenu si nécessaire.
Conseils sur la taille et les dispositions
Lorsque l'on utilise une zone de défilement pour afficher le contenu d'un widget personnalisé, il est important de s'assurer que l'adresse size hint du widget enfant est réglée sur une valeur appropriée. Si un QWidget standard est utilisé pour le widget enfant, il peut être nécessaire d'appeler QWidget::setMinimumSize() pour s'assurer que le contenu du widget est affiché correctement dans la zone de défilement.
Si une zone de défilement est utilisée pour afficher le contenu d'un widget qui contient des widgets enfants disposés dans une disposition, il est important de savoir que la politique de taille de la disposition déterminera également la taille du widget. Il est particulièrement utile de le savoir si vous avez l'intention de modifier dynamiquement le contenu de la présentation. Dans ce cas, le fait de définir la propriété size constraint de la mise en page sur une propriété qui impose 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 drapeaux 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é indique si la zone de défilement doit redimensionner le widget de la vue
Si cette propriété vaut false (valeur par défaut), la zone de défilement respecte la taille de son widget. Indépendamment de cette propriété, vous pouvez redimensionner le widget par programmation en utilisant widget()->resize(), et la zone de défilement s'ajustera 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 les barres de défilement lorsqu'elles peuvent être évitées, ou pour tirer parti de l'espace supplémentaire.
Accéder aux fonctions :
| bool | widgetResizable() const |
| void | setWidgetResizable(bool resizable) |
Documentation des fonctions membres
[explicit] QScrollArea::QScrollArea(QWidget *parent = nullptr)
Construit une zone de défilement vide avec l'adresse parent.
Voir aussi setWidget().
[virtual noexcept] QScrollArea::~QScrollArea()
Détruit 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 à l'intérieur de la région de la fenêtre avec des marges spécifiées en pixels par xmargin et ymargin. Si le point spécifié ne peut pas être atteint, le contenu est défilé jusqu'à 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 le site childWidget de QScrollArea::widget() soit visible à l'intérieur de la fenêtre de visualisation avec des marges spécifiées en pixels par xmargin et ymargin. Si le point spécifié ne peut pas être atteint, le contenu est défilé jusqu'à la position valide la plus proche. La valeur par défaut des 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 le widget de la zone de défilement.
L'adresse widget devient un enfant de la zone de défilement et sera détruite 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 lors de l'ajout de widget, vous devez show() la définir explicitement.
Notez que vous devez ajouter la disposition de widget avant d'appeler cette fonction ; si vous l'ajoutez plus tard, widget ne sera pas visible - quel que soit le moment où vous show() la zone de défilement. Dans ce cas, vous pouvez également ne pas ajouter show() à 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 transmet la propriété du widget à l'appelant.
Voir aussi 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 également 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.
