En esta página

QStackedWidget Class

La clase QStackedWidget proporciona una pila de widgets donde sólo un widget es visible a la vez. Más...

Cabecera: #include <QStackedWidget>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
Hereda: QFrame

Propiedades

Funciones públicas

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

Ranuras públicas

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

Señales

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

Funciones protegidas reimplementadas

virtual bool event(QEvent *e) override

Descripción Detallada

QStackedWidget se puede utilizar para crear una interfaz de usuario similar a la proporcionada por QTabWidget. Es un widget de diseño de conveniencia construido sobre la clase QStackedLayout.

Al igual que QStackedLayout, QStackedWidget puede construirse y poblarse con un número de widgets hijos ("páginas"):

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 no proporciona ningún medio intrínseco para que el usuario cambie de página. Esto se hace típicamente a través de un QComboBox o un QListWidget que almacena los títulos de las páginas del QStackedWidget. Por ejemplo:

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);

Cuando se rellena un widget apilado, los widgets se añaden a una lista interna. La función indexOf() devuelve el índice de un widget en esa lista. Los widgets pueden añadirse al final de la lista utilizando la función addWidget(), o insertarse en un índice determinado utilizando la función insertWidget(). La función removeWidget() elimina un widget de la pila de widgets. El número de widgets contenidos en el widget apilado puede obtenerse utilizando la función count().

La función widget() devuelve el widget en una posición de índice dada. El índice del widget que se muestra en pantalla viene dado por currentIndex() y puede cambiarse utilizando setCurrentIndex(). De forma similar, el widget que se muestra actualmente puede recuperarse utilizando la función currentWidget(), y modificarse utilizando la función setCurrentWidget().

Cada vez que cambia el widget actual en el widget apilado o se elimina un widget del widget apilado, se emiten las señales currentChanged() y widgetRemoved() respectivamente.

Véase también QStackedLayout y QTabWidget.

Documentación de propiedades

[read-only] count : int

Esta propiedad contiene el número de widgets que contiene este widget apilado

Por defecto, esta propiedad contiene un valor de 0.

Funciones de acceso:

int count() const

Véase también currentIndex() y widget().

currentIndex : int

Esta propiedad contiene la posición del índice del widget que es visible

El índice actual es -1 si no hay widget actual.

Por defecto, esta propiedad contiene un valor de -1 porque la pila está inicialmente vacía.

Funciones de acceso:

int currentIndex() const
void setCurrentIndex(int index)

Señal del notificador:

void currentChanged(int index)

Véase también currentWidget() y indexOf().

Documentación de las funciones miembro

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

Construye un QStackedWidget con la dirección parent.

Véase también addWidget() y insertWidget().

[virtual noexcept] QStackedWidget::~QStackedWidget()

Destruye este widget apilado y libera los recursos asignados.

int QStackedWidget::addWidget(QWidget *widget)

Añade el widget dado al QStackedWidget y devuelve la posición del índice. La propiedad de widget pasa a QStackedWidget.

Si QStackedWidget está vacío antes de llamar a esta función, widget se convierte en el widget actual.

Véase también insertWidget(), removeWidget(), y setCurrentWidget().

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

Esta señal se emite cada vez que cambia el widget actual.

El parámetro contiene el index del nuevo widget actual, o -1 si no hay uno nuevo (por ejemplo, si no hay widgets en el QStackedWidget).

Nota: Señal notificadora para la propiedad currentIndex.

Véase también currentWidget() y setCurrentWidget().

QWidget *QStackedWidget::currentWidget() const

Devuelve el widget actual, o nullptr si no hay widgets hijos.

Véase también currentIndex() y setCurrentWidget().

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

Reimplementa: QFrame::event(QEvent *e).

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

Devuelve el índice del widget dado , o -1 si el widget dado no es hijo del QStackedWidget.

Véase también currentIndex() y widget().

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

Inserta el widget dado en el index dado en el QStackedWidget. La propiedad de widget se pasa al QStackedWidget. Si index está fuera de rango, se añade el widget (en cuyo caso es el índice actual del widget el que se devuelve).

Si el QStackedWidget estaba vacío antes de llamar a esta función, el widget dado se convierte en el widget actual.

La inserción de un nuevo widget en un índice menor o igual al índice actual incrementará el índice actual, pero mantendrá el widget actual.

Véase también addWidget(), removeWidget(), y setCurrentWidget().

void QStackedWidget::removeWidget(QWidget *widget)

Elimina widget de QStackedWidget. es decir, widget no se elimina, sino que simplemente se retira del diseño apilado, haciendo que se oculte.

Nota: El objeto padre y el widget padre de widget seguirán siendo QStackedWidget. Si la aplicación desea reutilizar el widget eliminado, se recomienda volver a colocarlo como padre.

Véase también addWidget(), insertWidget(), y currentWidget().

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

Establece que el widget actual sea el especificado widget. El nuevo widget actual debe estar ya contenido en este widget apilado.

Véase también currentWidget() y setCurrentIndex().

QWidget *QStackedWidget::widget(int index) const

Devuelve el widget en el index dado, o nullptr si no existe tal widget.

Véase también currentWidget() y indexOf().

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

Esta señal se emite cada vez que se añade o inserta un widget. El widget index se pasa como parámetro.

Esta función se introdujo en Qt 6.9.

Véase también addWidget() y insertWidget().

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

Esta señal se emite cada vez que se elimina un widget. El widget index se pasa como parámetro.

Véase también 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.