En esta página

QTabWidget Class

La clase QTabWidget proporciona una pila de widgets con pestañas. Más información...

Encabezado: #include <QTabWidget>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
Heredado de: QWidget

Tipos públicos

enum TabPosition { North, South, West, East }
enum TabShape { Rounded, Triangular }

Propiedades

Funciones públicas

QTabWidget(QWidget *parent = nullptr)
virtual ~QTabWidget()
int addTab(QWidget *page, const QString &label)
int addTab(QWidget *page, const QIcon &icon, const QString &label)
void clear()
QWidget *cornerWidget(Qt::Corner corner = Qt::TopRightCorner) const
int count() const
int currentIndex() const
QWidget *currentWidget() const
bool documentMode() const
Qt::TextElideMode elideMode() const
QSize iconSize() const
int indexOf(const QWidget *w) const
int insertTab(int index, QWidget *page, const QString &label)
int insertTab(int index, QWidget *page, const QIcon &icon, const QString &label)
bool isMovable() const
bool isTabEnabled(int index) const
bool isTabVisible(int index) const
void removeTab(int index)
void setCornerWidget(QWidget *widget, Qt::Corner corner = Qt::TopRightCorner)
void setDocumentMode(bool set)
void setElideMode(Qt::TextElideMode mode)
void setIconSize(const QSize &size)
void setMovable(bool movable)
void setTabBarAutoHide(bool enabled)
void setTabEnabled(int index, bool enable)
void setTabIcon(int index, const QIcon &icon)
void setTabPosition(QTabWidget::TabPosition position)
void setTabShape(QTabWidget::TabShape s)
void setTabText(int index, const QString &label)
void setTabToolTip(int index, const QString &tip)
void setTabVisible(int index, bool visible)
void setTabWhatsThis(int index, const QString &text)
void setTabsClosable(bool closeable)
void setUsesScrollButtons(bool useButtons)
QTabBar *tabBar() const
bool tabBarAutoHide() const
QIcon tabIcon(int index) const
QTabWidget::TabPosition tabPosition() const
QTabWidget::TabShape tabShape() const
QString tabText(int index) const
QString tabToolTip(int index) const
QString tabWhatsThis(int index) const
bool tabsClosable() const
bool usesScrollButtons() const
QWidget *widget(int index) const

Funciones públicas reimplementadas

virtual bool hasHeightForWidth() const override
virtual int heightForWidth(int width) const override
virtual QSize minimumSizeHint() const override
virtual QSize sizeHint() const override

Ranuras públicas

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

Señales

void currentChanged(int index)
void tabBarClicked(int index)
void tabBarDoubleClicked(int index)
void tabCloseRequested(int index)

Funciones protegidas

virtual void initStyleOption(QStyleOptionTabWidgetFrame *option) const
void setTabBar(QTabBar *tb)
virtual void tabInserted(int index)
virtual void tabRemoved(int index)

Funciones protegidas reimplementadas

virtual void changeEvent(QEvent *ev) override
virtual bool event(QEvent *ev) override
virtual void keyPressEvent(QKeyEvent *e) override
virtual void paintEvent(QPaintEvent *event) override
virtual void resizeEvent(QResizeEvent *e) override
virtual void showEvent(QShowEvent *) override

Descripción detallada

Widget de pestañas con dos pestañas

Un widget de pestañas proporciona una barra de pestañas (véase QTabBar) y un «área de página» que se utiliza para mostrar las páginas relacionadas con cada pestaña. Por defecto, la barra de pestañas se muestra encima del área de página, pero hay diferentes configuraciones disponibles (véase TabPosition). Cada pestaña está asociada a un widget diferente (denominado «página»). En el área de página solo se muestra la página actual; el resto de páginas permanecen ocultas. El usuario puede mostrar una página diferente haciendo clic en su pestaña o pulsando su atajo deteclado Alt+letra, si lo tiene.

La forma habitual de utilizar QTabWidget es la siguiente:

  1. Crear un QTabWidget.
  2. Crear un « QWidget » para cada una de las páginas del cuadro de diálogo de pestañas, pero sin especificar widgets padres para ellas.
  3. Inserta los widgets hijos en el widget de página, utilizando diseños para colocarlos como de costumbre.
  4. Llamar a ` addTab()` o a ` insertTab()` para colocar los widgets de página en el widget de pestañas, asignando a cada pestaña una etiqueta adecuada con un atajo de teclado opcional.

La posición de las pestañas viene definida por ` tabPosition`, y su forma, por ` tabShape`.

La señal currentChanged() se emite cuando el usuario selecciona una página.

El índice de la página actual está disponible mediante ` currentIndex()`, y el widget de la página actual mediante ` currentWidget()`. Puedes obtener un puntero a un widget de página con un índice determinado utilizando ` widget()`, y puedes averiguar la posición en el índice de un widget con ` indexOf()`. Utiliza ` setCurrentWidget()` o ` setCurrentIndex()` para mostrar una página concreta.

Puede modificar el texto y el icono de una pestaña mediante setTabText() o setTabIcon(). Una pestaña y su página asociada pueden eliminarse con removeTab().

Cada pestaña puede estar habilitada o deshabilitada en un momento dado (véase setTabEnabled()). Si una pestaña está habilitada, su texto se muestra con normalidad y el usuario puede seleccionarla. Si está deshabilitada, la pestaña se muestra de forma diferente y el usuario no puede seleccionarla. Ten en cuenta que, aunque una pestaña esté desactivada, la página puede seguir siendo visible, por ejemplo, si todas las pestañas están desactivadas.

Los widgets de pestañas pueden ser una forma muy buena de dividir un cuadro de diálogo complejo. Una alternativa es utilizar un QStackedWidget al que se le proporcione algún medio para navegar entre páginas, por ejemplo, un QToolBar o un QListWidget.

La mayor parte de la funcionalidad de QTabWidget la proporcionan un QTabBar (en la parte superior, que proporciona las pestañas) y un QStackedWidget (que ocupa la mayor parte del área y organiza las páginas individuales).

Véase también QTabBar, QStackedWidget, QToolBox y Ejemplo de cuadro de diálogo con pestañas.

Documentación sobre los tipos de miembro

enum QTabWidget::TabPosition

Este tipo de enumeración define dónde di QTabWidget a dibujar la fila de pestañas:

ConstanteValorDescripción
QTabWidget::North0Las pestañas se dibujan encima de las páginas.
QTabWidget::South1Las pestañas se dibujan debajo de las páginas.
QTabWidget::West2Las pestañas se dibujan a la izquierda de las páginas.
QTabWidget::East3Las pestañas se dibujan a la derecha de las páginas.

enum QTabWidget::TabShape

Este tipo de enumeración define la forma de las pestañas:

ConstanteValorDescripción
QTabWidget::Rounded0Las pestañas se dibujan con un aspecto redondeado. Esta es la forma predeterminada.
QTabWidget::Triangular1Las pestañas se dibujan con un aspecto triangular.

Documentación de la propiedad

[read-only] count : int

Esta propiedad indica el número de pestañas de la barra de pestañas

Por defecto, esta propiedad tiene un valor de 0.

Funciones de acceso:

int count() const

currentIndex : int

Esta propiedad contiene la posición en el índice de la pestaña actual

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

Por defecto, esta propiedad contiene el valor -1, ya que inicialmente no hay pestañas en el widget.

Funciones de acceso:

int currentIndex() const
void setCurrentIndex(int index)

Señal de notificación:

void currentChanged(int index)

documentMode : bool

Esta propiedad determina si el widget de pestañas se representa o no en un modo adecuado para páginas de documento. Es equivalente al «modo documento» de macOS.

Cuando se establece esta propiedad, no se representa el marco del widget de pestañas. Este modo resulta útil para mostrar páginas de tipo documento en las que la página ocupa la mayor parte del área del widget de pestañas.

Funciones de acceso:

bool documentMode() const
void setDocumentMode(bool set)

Véase también elideMode, QTabBar::documentMode, QTabBar::usesScrollButtons y QStyle::SH_TabBar_PreferNoArrows.

elideMode : Qt::TextElideMode

Cómo omitir texto en la barra de pestañas

Esta propiedad controla cómo se omiten los elementos cuando no hay espacio suficiente para mostrarlos en una barra de pestañas de un tamaño determinado.

Por defecto, el valor depende del estilo.

Funciones de Access:

Qt::TextElideMode elideMode() const
void setElideMode(Qt::TextElideMode mode)

Véase también QTabBar::elideMode, usesScrollButtons y QStyle::SH_TabBar_ElideMode.

iconSize : QSize

Esta propiedad establece el tamaño de los iconos de la barra de pestañas

El valor por defecto depende del estilo. Este es el tamaño máximo que tendrán los iconos. Los iconos no se amplían si su tamaño es inferior.

Funciones de acceso:

QSize iconSize() const
void setIconSize(const QSize &size)

Véase también QTabBar::iconSize.

movable : bool

Esta propiedad determina si el usuario puede mover las pestañas dentro del área de la barra de pestañas.

Por defecto, esta propiedad tiene el valor « false »;

Funciones de Access:

bool isMovable() const
void setMovable(bool movable)

tabBarAutoHide : bool

Si el valor es «true», la barra de pestañas se oculta automáticamente cuando contiene menos de 2 pestañas.

Por defecto, esta propiedad es «false».

Funciones de Access:

bool tabBarAutoHide() const
void setTabBarAutoHide(bool enabled)

Véase también QWidget::visible.

tabPosition : TabPosition

Esta propiedad define la posición de las pestañas en este widget de pestañas

Los valores posibles para esta propiedad se describen en la enumeración « TabPosition ».

Por defecto, esta propiedad está establecida en « North ».

Funciones de acceso:

QTabWidget::TabPosition tabPosition() const
void setTabPosition(QTabWidget::TabPosition position)

Véase también « TabPosition ».

tabShape : TabShape

Esta propiedad define la forma de las pestañas en este widget de pestañas

Los valores posibles para esta propiedad son « QTabWidget::Rounded » (por defecto) o « QTabWidget::Triangular ».

Funciones de acceso:

QTabWidget::TabShape tabShape() const
void setTabShape(QTabWidget::TabShape s)

Véase también « TabShape ».

tabsClosable : bool

Esta propiedad determina si se añaden automáticamente botones de cierre a cada pestaña.

Funciones de Access:

bool tabsClosable() const
void setTabsClosable(bool closeable)

Véase también QTabBar::tabsClosable().

usesScrollButtons : bool

Esta propiedad determina si una barra de pestañas debe utilizar botones para desplazarse por las pestañas cuando hay muchas de ellas.

Cuando hay demasiadas pestañas en una barra de pestañas para su tamaño, la barra de pestañas puede optar por ampliar su tamaño o por añadir botones que permitan desplazarse por las pestañas.

Por defecto, el valor depende del estilo.

Funciones de acceso:

bool usesScrollButtons() const
void setUsesScrollButtons(bool useButtons)

Véase también elideMode, QTabBar::usesScrollButtons y QStyle::SH_TabBar_PreferNoArrows.

Documentación de funciones de miembro

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

Crea un widget con pestañas cuyo elemento padre es parent.

[virtual noexcept] QTabWidget::~QTabWidget()

Elimina el widget de pestañas.

int QTabWidget::addTab(QWidget *page, const QString &label)

Añade una pestaña con los valores « page » y « label » especificados al widget de pestañas y devuelve el índice de la pestaña en la barra de pestañas. La propiedad de « page » se transfiere a « QTabWidget ».

Si la etiqueta label de la pestaña contiene un símbolo «&», la letra que sigue a dicho símbolo se utiliza como atajo para la pestaña; por ejemplo, si la etiqueta es «Bro&wse», la combinación Alt+W se convierte en un atajo que desplazará el foco a esta pestaña.

Nota: Si se llama a addTab() después de show(), el sistema de diseño intentará adaptarse a los cambios en su jerarquía de widgets y esto puede provocar parpadeos. Para evitarlo, se puede establecer la propiedad QWidget::updatesEnabled en false antes de realizar los cambios; recuerda establecer la propiedad en true cuando los cambios hayan finalizado, para que el widget vuelva a recibir eventos de dibujo.

Véase también ` insertTab()`.

int QTabWidget::addTab(QWidget *page, const QIcon &icon, const QString &label)

Añade una pestaña con los valores indicados en « page », « icon » y « label » al widget de pestañas, y devuelve el índice de la pestaña en la barra de pestañas. La propiedad de « page » se transfiere a « QTabWidget ».

Esta función es idéntica a addTab(), pero incluye un parámetro adicional: icon.

Se trata de una función sobrecargada.

[override virtual protected] void QTabWidget::changeEvent(QEvent *ev)

Reimplementa: ` QWidget::changeEvent(QEvent *event)`.

void QTabWidget::clear()

Elimina todas las páginas, pero no las borra. Llamar a esta función equivale a llamar a ` removeTab()` hasta que el widget de pestañas quede vacío.

QWidget *QTabWidget::cornerWidget(Qt::Corner corner = Qt::TopRightCorner) const

Devuelve el widget que se muestra en la propiedad « corner » del widget de pestaña o en « nullptr ».

Véase también setCornerWidget().

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

Esta señal se emite cada vez que cambia el índice de la página actual. El parámetro es la nueva posición de la página actual index, o -1 si no hay una nueva (por ejemplo, si no hay widgets en QTabWidget)

Nota: Señalde notificación para la propiedad currentIndex.

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

QWidget *QTabWidget::currentWidget() const

Devuelve un puntero a la página que muestra actualmente el cuadro de diálogo de pestañas. El cuadro de diálogo de pestañas hace todo lo posible para garantizar que este valor nunca sea 0 (aunque, si te esfuerzas lo suficiente, puede llegar a serlo).

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

[override virtual protected] bool QTabWidget::event(QEvent *ev)

Reimplementa: ` QWidget::event(QEvent *event)`.

[override virtual] bool QTabWidget::hasHeightForWidth() const

Reimplementa: ` QWidget::hasHeightForWidth()` const.

[override virtual] int QTabWidget::heightForWidth(int width) const

Reimplementa: ` QWidget::heightForWidth(int w) const`.

int QTabWidget::indexOf(const QWidget *w) const

Devuelve la posición en el índice de la página que ocupa el widget w, o -1 si no se encuentra el widget.

[virtual protected] void QTabWidget::initStyleOption(QStyleOptionTabWidgetFrame *option) const

Inicializa ` option ` con los valores de este enlace: QTabWidget. Este método resulta útil para las subclases cuando necesitan un ` QStyleOptionTabWidgetFrame`, pero no quieren rellenar toda la información ellas mismas.

Véase también QStyleOption::initFrom() y QTabBar::initStyleOption().

int QTabWidget::insertTab(int index, QWidget *page, const QString &label)

Inserta una pestaña con los valores « label » y « page » en el widget de pestañas en la ubicación especificada « index », y devuelve el índice de la pestaña insertada en la barra de pestañas. La propiedad de « page » se transfiere a « QTabWidget ».

La etiqueta se muestra en la pestaña y su aspecto puede variar en función de la configuración del widget de pestañas.

Si la etiqueta de la pestaña label contiene un símbolo «&», la letra que sigue a dicho símbolo se utiliza como atajo para la pestaña; por ejemplo, si la etiqueta es «Bro&wse», entonces Alt+W se convierte en un atajo que desplazará el foco a esta pestaña.

Si ` index ` está fuera de rango, la pestaña simplemente se añade al final. En caso contrario, se inserta en la posición especificada.

Si QTabWidget estaba vacío antes de llamar a esta función, la nueva página se convierte en la página actual. Al insertar una nueva pestaña en un índice menor o igual que el índice actual, este se incrementará, pero se mantendrá la página actual.

Nota: Si se llama a insertTab() después de show(), el sistema de maquetación intentará adaptarse a los cambios en su jerarquía de widgets y esto puede provocar parpadeos. Para evitarlo, se puede establecer la propiedad QWidget::updatesEnabled en false antes de realizar los cambios; recuerda establecer la propiedad en true cuando los cambios hayan finalizado, para que el widget vuelva a recibir eventos de dibujo.

Véase también ` addTab()`.

int QTabWidget::insertTab(int index, QWidget *page, const QIcon &icon, const QString &label)

Inserta una pestaña con los valores indicados en label, page y icon en el widget de pestaña situado en la dirección especificada index, y devuelve el índice de la pestaña insertada en la barra de pestañas. La propiedad de page se transfiere a QTabWidget.

Esta función es idéntica a insertTab(), pero con un icon adicional.

Se trata de una función sobrecargada.

bool QTabWidget::isTabEnabled(int index) const

Devuelve « true » si la página situada en la posición index está habilitada; en caso contrario, devuelve « false ».

Véase también setTabEnabled() y QWidget::isEnabled().

bool QTabWidget::isTabVisible(int index) const

Devuelve «true» si la página situada en la dirección index está visible; en caso contrario, devuelve «false».

Véase también setTabVisible().

[override virtual protected] void QTabWidget::keyPressEvent(QKeyEvent *e)

Reimplementa: ` QWidget::keyPressEvent(QKeyEvent *event)`.

[override virtual] QSize QTabWidget::minimumSizeHint() const

Reimplementa una función de acceso para la propiedad: QWidget::minimumSizeHint.

Devuelve un tamaño mínimo adecuado para el widget de pestaña.

[override virtual protected] void QTabWidget::paintEvent(QPaintEvent *event)

Reimplementa: QWidget::paintEvent(QPaintEvent *event).

Dibuja la barra de pestañas del widget de pestañas en respuesta al evento de dibujo event.

void QTabWidget::removeTab(int index)

Elimina la pestaña situada en la posición index de esta pila de widgets. El widget de página en sí no se elimina.

Véase también addTab() y insertTab().

[override virtual protected] void QTabWidget::resizeEvent(QResizeEvent *e)

Reimplementa: QWidget::resizeEvent(QResizeEvent *event).

void QTabWidget::setCornerWidget(QWidget *widget, Qt::Corner corner = Qt::TopRightCorner)

Establece que el elemento « widget » indicado se muestre en el « corner » especificado del widget de pestañas. La geometría del widget se determina en función de los métodos « sizeHint()» y « style()» del widget.

Solo se utilizará el elemento horizontal de corner.

Si se pasa nullptr, no se muestra ningún widget en la esquina.

Cualquier widget de esquina establecido previamente queda oculto.

Todos los widgets establecidos aquí serán eliminados por el widget de pestaña cuando este se destruya, a menos que se vuelva a vincular el widget por separado tras establecer algún otro widget de esquina (o nullptr).

Nota: Los widgets de esquina están diseñados para las posiciones de pestaña North y South; se sabe que otras orientaciones no funcionan correctamente.

Véase también cornerWidget() y setTabPosition().

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

Establece widget como el widget actual. La URL widget utilizada debe ser una página de este widget de pestañas.

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

[protected] void QTabWidget::setTabBar(QTabBar *tb)

Sustituye el encabezado « QTabBar » del cuadro de diálogo por la barra de pestañas « tb ». Ten en cuenta que esta función debe llamarse antes de que se haya añadido ninguna pestaña; de lo contrario, el comportamiento es indefinido.

Véase también tabBar().

void QTabWidget::setTabEnabled(int index, bool enable)

Si enable es verdadero, se habilita la página situada en la posición index; en caso contrario, se deshabilita la página situada en la posición index. La pestaña de la página se actualiza en consecuencia.

QTabWidget Utiliza QWidget::setEnabled() internamente, en lugar de mantener un indicador independiente.

Ten en cuenta que incluso una pestaña o página desactivada puede estar visible. Si la página ya está visible, QTabWidget no la ocultará; si todas las páginas están desactivadas, QTabWidget mostrará una de ellas.

Véanse también isTabEnabled() y QWidget::setEnabled().

void QTabWidget::setTabIcon(int index, const QIcon &icon)

Establece el valor de « icon » para la pestaña situada en la posición index.

Véase también tabIcon().

void QTabWidget::setTabText(int index, const QString &label)

Define un nuevo atajo de teclado ( label ) para la pestaña de la página situada en la posición index.

Si el texto proporcionado contiene el carácter «&», se crea automáticamente un atajo para él. El carácter que siga al «&» se utilizará como tecla de atajo. Cualquier atajo anterior se sobrescribirá o se borrará si el texto no define ningún atajo. Consulta la documentación de QShortcut para obtener más detalles (para mostrar un símbolo «&» real, utiliza «&&»).

Véase también tabText().

void QTabWidget::setTabToolTip(int index, const QString &tip)

Establece la descripción emergente de la pestaña de la página situada en la posición index en tip.

Véase también tabToolTip().

void QTabWidget::setTabVisible(int index, bool visible)

Si visible es verdadero, la página situada en index está visible; en caso contrario, la página situada en index está oculta. La pestaña de la página se actualiza en consecuencia.

Véase también isTabVisible().

void QTabWidget::setTabWhatsThis(int index, const QString &text)

Establece el texto de ayuda «¿Qué es esto?» de la página en la posición index en text.

Véase también tabWhatsThis().

[override virtual protected] void QTabWidget::showEvent(QShowEvent *)

Reimplementa: ` QWidget::showEvent(QShowEvent *event)`.

[override virtual] QSize QTabWidget::sizeHint() const

Reimplementa una función de acceso para la propiedad: QWidget::sizeHint.

QTabBar *QTabWidget::tabBar() const

Devuelve el valor actual de ` QTabBar`.

Véase también setTabBar().

[signal] void QTabWidget::tabBarClicked(int index)

Esta señal se emite cuando el usuario hace clic en una pestaña en index.

index Indica la pestaña en la que se ha hecho clic, o -1 si no hay ninguna pestaña bajo el cursor.

[signal] void QTabWidget::tabBarDoubleClicked(int index)

Esta señal se emite cuando el usuario hace doble clic en una pestaña en index.

index es el índice de la pestaña en la que se ha hecho clic, o -1 si no hay ninguna pestaña bajo el cursor.

[signal] void QTabWidget::tabCloseRequested(int index)

Esta señal se emite al hacer clic en el botón de cierre de una pestaña. El objeto ` index ` es el índice que debe eliminarse.

Véase también setTabsClosable().

QIcon QTabWidget::tabIcon(int index) const

Devuelve el icono de la pestaña de la página situada en la posición index.

Véase también setTabIcon().

[virtual protected] void QTabWidget::tabInserted(int index)

Este controlador virtual se activa después de que se haya añadido o insertado una nueva pestaña en la posición index.

Véase también tabRemoved().

[virtual protected] void QTabWidget::tabRemoved(int index)

Este controlador virtual se activa después de que se haya eliminado una tabulación de la posición index.

Véase también tabInserted().

QString QTabWidget::tabText(int index) const

Devuelve el texto de la etiqueta de la pestaña de la página situada en la posición index.

Véase también setTabText().

QString QTabWidget::tabToolTip(int index) const

Devuelve la descripción emergente de la pestaña correspondiente a la página en la posición index o una cadena vacía si no se ha establecido ninguna descripción emergente.

Véase también setTabToolTip().

QString QTabWidget::tabWhatsThis(int index) const

Devuelve el texto de ayuda «¿Qué es esto?» correspondiente a la página situada en la posición index, o una cadena vacía si no se ha establecido ningún texto de ayuda.

Véase también setTabWhatsThis().

QWidget *QTabWidget::widget(int index) const

Devuelve la pestaña situada en la posición de índice index o nullptr si el index está fuera de rango.

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