Sur cette page

QStackedWidget Class

La classe QStackedWidget permet de créer une pile de widgets dont un seul est visible à la fois. En savoir plus...

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

Propriétés

Fonctions publiques

QStackedWidget(QWidget *parent = nullptr)
virtual ~QStackedWidget()
int addWidget(QWidget *widget)
int count() const
int currentIndex() const
QWidget *currentWidget() const
int indexOf(const QWidget *widget) const
int insertWidget(int index, QWidget *widget)
void removeWidget(QWidget *widget)
QWidget *widget(int index) const

Emplacements publics

void setCurrentIndex(int index)
void setCurrentWidget(QWidget *widget)

Signaux

void currentChanged(int index)
(since 6.9) void widgetAdded(int index)
void widgetRemoved(int index)

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

virtual bool event(QEvent *e) override

Description détaillée

QStackedWidget permet de créer une interface utilisateur similaire à celle fournie par QTabWidget. Il s'agit d'un widget de mise en page pratique, construit à partir de la classe QStackedLayout.

Tout comme QStackedLayout, QStackedWidget peut être instancié et rempli d’un certain nombre de widgets enfants (« pages ») :

QWidget *firstPageWidget = new QWidget;
QWidget *secondPageWidget = new QWidget;
QWidget *thirdPageWidget = new QWidget;

QStackedWidget *stackedWidget = new QStackedWidget;
stackedWidget->addWidget(firstPageWidget);
stackedWidget->addWidget(secondPageWidget);
stackedWidget->addWidget(thirdPageWidget);

QVBoxLayout *layout = new QVBoxLayout;
layout->addWidget(stackedWidget);
setLayout(layout);

QStackedWidget ne fournit aucun moyen intrinsèque permettant à l'utilisateur de changer de page. Cela se fait généralement via un QComboBox ou un QListWidget qui stocke les titres des pages du QStackedWidget. Par exemple :

QComboBox *pageComboBox = new QComboBox;
pageComboBox->addItem(tr("Page 1"));
pageComboBox->addItem(tr("Page 2"));
pageComboBox->addItem(tr("Page 3"));
connect(pageComboBox, &QComboBox::activated,
        stackedWidget, &QStackedWidget::setCurrentIndex);

Lors du remplissage d’un widget empilé, les widgets sont ajoutés à une liste interne. La fonction indexOf() renvoie l’index d’un widget dans cette liste. Les widgets peuvent soit être ajoutés à la fin de la liste à l'aide de la fonction addWidget(), soit être insérés à un index donné à l'aide de la fonction insertWidget(). La fonction removeWidget() supprime un widget du widget empilé. Le nombre de widgets contenus dans le widget empilé peut être obtenu à l'aide de la fonction count().

La fonction ` widget()` renvoie le widget situé à un index donné. L’index du widget affiché à l’écran est fourni par ` currentIndex()` et peut être modifié à l’aide de ` setCurrentIndex()`. De la même manière, le widget actuellement affiché peut être récupéré à l’aide de la fonction ` currentWidget()` et modifié à l’aide de la fonction ` setCurrentWidget()`.

Chaque fois que le widget actif de la pile de widgets change ou qu’un widget est supprimé de la pile, les signaux currentChanged() et widgetRemoved() sont respectivement émis.

Voir également QStackedLayout et QTabWidget.

Documentation sur les propriétés

[read-only] count : int

Cette propriété indique le nombre de widgets contenus dans ce widget empilé

Par défaut, cette propriété a pour valeur 0.

Fonctions d'accès :

int count() const

Voir également currentIndex() et widget().

currentIndex : int

Cette propriété contient l'index du widget actuellement visible

L'index actuel est -1 s'il n'y a pas de widget actif.

Par défaut, cette propriété prend la valeur -1, car la pile est initialement vide.

Fonctions d'accès :

int currentIndex() const
void setCurrentIndex(int index)

Signal de notification :

void currentChanged(int index)

Voir également currentWidget() et indexOf().

Documentation des fonctions membres

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

Crée un QStackedWidget à partir de l'parent fourni.

Voir également addWidget() et insertWidget().

[virtual noexcept] QStackedWidget::~QStackedWidget()

Supprime ce widget empilé et libère toutes les ressources allouées.

int QStackedWidget::addWidget(QWidget *widget)

Ajoute l'widget on indiquée à l'QStackedWidget et renvoie sa position d'index. La propriété de widget est transférée à QStackedWidget.

Si ` QStackedWidget ` est vide avant l’appel de cette fonction, ` widget ` devient le widget actif.

Voir également insertWidget(), removeWidget() et setCurrentWidget().

[signal] void QStackedWidget::currentChanged(int index)

Ce signal est émis chaque fois que le widget actuel change.

Le paramètre contient l'index du nouveau widget actuel, ou -1 s'il n'y en a pas de nouveau (par exemple, s'il n'y a pas de widgets dans l'QStackedWidget).

Remarque : signalde notification pour la propriété ` currentIndex`.

Voir également currentWidget() et setCurrentWidget().

QWidget *QStackedWidget::currentWidget() const

Renvoie le widget actuel, ou ` nullptr ` s'il n'y a pas de widgets enfants.

Voir également currentIndex() et setCurrentWidget().

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

Réimplémentation de : QFrame::event(QEvent *e).

int QStackedWidget::indexOf(const QWidget *widget) const

Renvoie l'index de l'widget donné, ou -1 si l'widget donné n'est pas un enfant de l'QStackedWidget.

Voir également currentIndex() et widget().

int QStackedWidget::insertWidget(int index, QWidget *widget)

Insère l'widget donné à l'index donné dans l'QStackedWidget. La propriété de widget est transférée à l'QStackedWidget. Si index est hors limites, l'widget est ajouté à la fin (auquel cas c'est l'index réel de l'widget qui est renvoyé).

Si le paramètre « QStackedWidget » était vide avant l’appel de cette fonction, le « widget » fourni devient le widget actuel.

L’insertion d’un nouveau widget à un index inférieur ou égal à l’index actuel incrémentera l’index actuel, mais conservera le widget actuel.

Voir également addWidget(), removeWidget() et setCurrentWidget().

void QStackedWidget::removeWidget(QWidget *widget)

Supprime widget de QStackedWidget. Autrement dit, widget n' est pas supprimé, mais simplement retiré de la disposition empilée, ce qui le rend invisible.

Remarque : l’objetparent et le widget parent de widget resteront QStackedWidget. Si l’application souhaite réutiliser l’élément widget supprimé, il est recommandé de lui attribuer un nouveau parent.

Voir également addWidget(), insertWidget() et currentWidget().

[slot] void QStackedWidget::setCurrentWidget(QWidget *widget)

Définit le widget actif sur le widget spécifié widget. Le nouveau widget actif doit déjà faire partie de ce widget empilé.

Voir également currentWidget() et setCurrentIndex().

QWidget *QStackedWidget::widget(int index) const

Renvoie le widget situé à l'adresse index, ou nullptr s'il n'existe aucun widget correspondant.

Voir également currentWidget() et indexOf().

[signal, since 6.9] void QStackedWidget::widgetAdded(int index)

Ce signal est émis chaque fois qu'un widget est ajouté ou inséré. L'index e du widget est transmise en paramètre.

Cette fonction a été introduite dans Qt 6.9.

Voir également ` addWidget()` et ` insertWidget()`.

[signal] void QStackedWidget::widgetRemoved(int index)

Ce signal est émis chaque fois qu'un widget est supprimé. L'index du widget est transmise en paramètre.

Voir également removeWidget().

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