En esta página

QStackedWidget Class

La clase QStackedWidget ofrece una pila de widgets en la que solo se ve uno a la vez. Más información...

Encabezado: #include <QStackedWidget>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
Heredado de: 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 que ofrece QTabWidget. Se trata de un widget de diseño práctico basado en la clase QStackedLayout.

Al igual que QStackedLayout, QStackedWidget puede crearse y rellenarse con varios 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 suele hacer mediante 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);

Al rellenar un widget apilado, los widgets se añaden a una lista interna. La función indexOf() devuelve el índice de un widget en dicha lista. Los widgets pueden añadirse al final de la lista mediante la función addWidget(), o bien insertarse en un índice determinado mediante la función insertWidget(). La función removeWidget() elimina un widget del widget apilado. El número de widgets que contiene el widget apilado puede obtenerse mediante la función count().

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

Cada vez que cambia el widget actual del conjunto de widgets apilados o se elimina un widget de dicho conjunto, 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 indica el número de widgets que contiene este widget apilado

Por defecto, esta propiedad tiene 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 en el índice del widget que está visible

El índice actual es -1 si no hay ningún widget activo.

Por defecto, esta propiedad contiene el valor -1, ya que la pila está vacía inicialmente.

Funciones de acceso:

int currentIndex() const
void setCurrentIndex(int index)

Señal de notificador:

void currentChanged(int index)

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

Documentación de funciones de miembro

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

Crea un QStackedWidget con el parent especificado.

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

[virtual noexcept] QStackedWidget::~QStackedWidget()

Destruye este widget apilado y libera todos los recursos asignados.

int QStackedWidget::addWidget(QWidget *widget)

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

Si el QStackedWidget está vacío antes de que se llame 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 la propiedad ` index ` del nuevo widget actual, o -1 si no hay ninguno nuevo (por ejemplo, si no hay widgets en ` QStackedWidget`).

Nota: Señalde notificación 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 secundarios.

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` indicado, o -1 si el ` widget ` indicado no es un elemento secundario del ` QStackedWidget`.

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

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

Inserta el « widget » indicado en el « index » especificado en el « QStackedWidget ». La propiedad de « widget » se transfiere al « QStackedWidget ». Si « index » está fuera de rango, se añade « widget » (en cuyo caso se devuelve el índice real de « widget »).

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

Al insertar un nuevo widget en un índice menor o igual que el índice actual, este se incrementará, pero se mantendrá el widget actual.

Véanse 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, lo que hace que quede oculto.

Nota: El objetopadre y el widget padre de ` widget ` seguirán siendo ` QStackedWidget`. Si la aplicación desea reutilizar el elemento ` widget` que se ha eliminado, se recomienda volver a asignarle un padre.

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

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

Establece el widget actual como el especificado en widget. El nuevo widget actual debe estar ya incluido en este widget apilado.

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

QWidget *QStackedWidget::widget(int index) const

Devuelve el widget situado en la dirección especificada index, o nullptr si no existe dicho 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 se inserta un widget. Se pasa como parámetro la propiedad « index » del widget.

Esta función se introdujo en Qt 6.9.

Véanse también « addWidget()» y « insertWidget()».

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

Esta señal se emite cada vez que se elimina un widget. Se pasa como parámetro el ` index ` del widget.

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.