En esta página

QTabBar Class

La clase QTabBar proporciona una barra de pestañas, por ejemplo, para su uso en cuadros de diálogo con pestañas. Más...

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

Tipos públicos

enum ButtonPosition { LeftSide, RightSide }
enum SelectionBehavior { SelectLeftTab, SelectRightTab, SelectPreviousTab }
enum Shape { RoundedNorth, RoundedSouth, RoundedWest, RoundedEast, TriangularNorth, …, TriangularEast }

Propiedades

Funciones públicas

QTabBar(QWidget *parent = nullptr)
virtual ~QTabBar()
QString accessibleTabName(int index) const
int addTab(const QString &text)
int addTab(const QIcon &icon, const QString &text)
bool autoHide() const
bool changeCurrentOnDrag() const
int count() const
int currentIndex() const
bool documentMode() const
bool drawBase() const
Qt::TextElideMode elideMode() const
bool expanding() const
QSize iconSize() const
int insertTab(int index, const QString &text)
int insertTab(int index, const QIcon &icon, const QString &text)
bool isMovable() const
bool isTabEnabled(int index) const
bool isTabVisible(int index) const
void moveTab(int from, int to)
void removeTab(int index)
QTabBar::SelectionBehavior selectionBehaviorOnRemove() const
void setAccessibleTabName(int index, const QString &name)
void setAutoHide(bool hide)
void setChangeCurrentOnDrag(bool change)
void setDocumentMode(bool set)
void setDrawBase(bool drawTheBase)
void setElideMode(Qt::TextElideMode mode)
void setExpanding(bool enabled)
void setIconSize(const QSize &size)
void setMovable(bool movable)
void setSelectionBehaviorOnRemove(QTabBar::SelectionBehavior behavior)
void setShape(QTabBar::Shape shape)
void setTabButton(int index, QTabBar::ButtonPosition position, QWidget *widget)
void setTabData(int index, const QVariant &data)
void setTabEnabled(int index, bool enabled)
void setTabIcon(int index, const QIcon &icon)
void setTabText(int index, const QString &text)
void setTabTextColor(int index, const QColor &color)
void setTabToolTip(int index, const QString &tip)
void setTabVisible(int index, bool visible)
void setTabWhatsThis(int index, const QString &text)
void setTabsClosable(bool closable)
void setUsesScrollButtons(bool useButtons)
QTabBar::Shape shape() const
int tabAt(const QPoint &position) const
QWidget *tabButton(int index, QTabBar::ButtonPosition position) const
QVariant tabData(int index) const
QIcon tabIcon(int index) const
QRect tabRect(int index) const
QString tabText(int index) const
QColor tabTextColor(int index) const
QString tabToolTip(int index) const
QString tabWhatsThis(int index) const
bool tabsClosable() const
bool usesScrollButtons() const

Funciones públicas reimplementadas

virtual QSize minimumSizeHint() const override
virtual QSize sizeHint() const override

Ranuras públicas

void setCurrentIndex(int index)

Señales

void currentChanged(int index)
void tabBarClicked(int index)
void tabBarDoubleClicked(int index)
void tabCloseRequested(int index)
void tabMoved(int from, int to)

Funciones protegidas

virtual void initStyleOption(QStyleOptionTab *option, int tabIndex) const
virtual QSize minimumTabSizeHint(int index) const
virtual void tabInserted(int index)
virtual void tabLayoutChange()
virtual void tabRemoved(int index)
virtual QSize tabSizeHint(int index) const

Funciones protegidas reimplementadas

virtual void changeEvent(QEvent *event) override
virtual bool event(QEvent *event) override
virtual void hideEvent(QHideEvent *) override
virtual void keyPressEvent(QKeyEvent *event) override
virtual void mouseDoubleClickEvent(QMouseEvent *event) override
virtual void mouseMoveEvent(QMouseEvent *event) override
virtual void mousePressEvent(QMouseEvent *event) override
virtual void mouseReleaseEvent(QMouseEvent *event) override
virtual void paintEvent(QPaintEvent *) override
virtual void resizeEvent(QResizeEvent *) override
virtual void showEvent(QShowEvent *) override
virtual void timerEvent(QTimerEvent *event) override
virtual void wheelEvent(QWheelEvent *event) override

Descripción Detallada

QTabBar es simple de usar; dibuja las pestañas usando una de las predefinidas shapes, y emite una señal cuando una pestaña es seleccionada. Puede ser subclasificada para adaptar su apariencia. Qt también proporciona un QTabWidget ya preparado.

Cada pestaña tiene un tabText(), un tabIcon() opcional, un tabToolTip() opcional, un tabWhatsThis() opcional y un tabData() opcional. Los atributos de las pestañas pueden modificarse con setTabText(), setTabIcon(), setTabToolTip(), setTabWhatsThis y setTabData(). Cada pestaña puede activarse o desactivarse individualmente con setTabEnabled().

Cada pestaña puede mostrar texto en un color distinto. El color actual del texto de una pestaña puede consultarse con la función tabTextColor(). Establezca el color del texto de una pestaña concreta con setTabTextColor().

Las pestañas se añaden con addTab(), o se insertan en posiciones determinadas con insertTab(). El número total de pestañas viene dado por count(). Las pestañas pueden eliminarse de la barra de pestañas con removeTab(). La combinación de removeTab() y insertTab() permite mover las pestañas a diferentes posiciones.

La propiedad shape define la apariencia de las pestañas. La elección de la forma es cuestión de gustos, aunque los cuadros de diálogo de pestañas (para preferencias y similares) utilizan invariablemente RoundedNorth. Los controles de pestañas en ventanas que no sean diálogos casi siempre utilizan RoundedSouth o TriangularSouth. Muchas hojas de cálculo y otros controles de pestañas en los que todas las páginas son esencialmente similares utilizan TriangularSouth, mientras que RoundedSouth se utiliza sobre todo cuando las páginas son diferentes (por ejemplo, una paleta de herramientas multipágina). El valor por defecto en QTabBar es RoundedNorth.

La parte más importante de la API de QTabBar es la señal currentChanged(). Esta es emitida cada vez que la pestaña actual cambia (incluso al inicio, cuando la pestaña actual cambia de 'none'). También hay una ranura, setCurrentIndex(), que se puede utilizar para seleccionar una pestaña mediante programación. La función currentIndex() devuelve el índice de la pestaña actual, count contiene el número de pestañas.

QTabBar crea teclas mnemotécnicas automáticas a la manera de QAbstractButton; por ejemplo, si la etiqueta de una pestaña es "&Graphics", Alt+G se convierte en una tecla de acceso directo para cambiar a esa pestaña.

Puede que sea necesario volver a implementar las siguientes funciones virtuales para adaptar el aspecto o almacenar datos adicionales con cada pestaña:

Para las subclases, también puede necesitar las funciones tabRect() que devuelve la geometría visual de una sola pestaña.

Barra de pestañas con tres pestañasUna barra de pestañas mostrada en el estilo del widget Fusion.
Barra de pestañas truncadaUna barra de pestañas truncada mostrada en el estilo del widget Fusion.

Véase también QTabWidget.

Documentación de tipos de miembros

enum QTabBar::ButtonPosition

Este tipo enum lista la ubicación del widget en una pestaña.

ConstanteValorDescripción
QTabBar::LeftSide0Lado izquierdo de la pestaña.
QTabBar::RightSide1Lado derecho de la pestaña.

enum QTabBar::SelectionBehavior

Este tipo enum enumera el comportamiento de QTabBar cuando se elimina una pestaña y la pestaña que se elimina es también la pestaña actual.

ConstanteValorDescripción
QTabBar::SelectLeftTab0Selecciona la pestaña a la izquierda de la que se está eliminando.
QTabBar::SelectRightTab1Selecciona la pestaña a la derecha de la que se está eliminando.
QTabBar::SelectPreviousTab2Seleccione la pestaña seleccionada anteriormente.

enum QTabBar::Shape

Este tipo enum enumera las formas incorporadas que admite QTabBar. Trátelos como sugerencias, ya que algunos estilos pueden no mostrar algunas de las formas. Sin embargo, debe respetarse la posición.

ConstanteValorDescripción
QTabBar::RoundedNorth0El aspecto redondeado normal por encima de las páginas
QTabBar::RoundedSouth1El aspecto redondeado normal debajo de las páginas
QTabBar::RoundedWest2El aspecto redondeado normal a la izquierda de las páginas
QTabBar::RoundedEast3El aspecto redondeado normal en el lado derecho de las páginas
QTabBar::TriangularNorth4Pestañas triangulares encima de las páginas.
QTabBar::TriangularSouth5Pestañas triangulares similares a las utilizadas en la hoja de cálculo Excel, por ejemplo
QTabBar::TriangularWest6Pestañas triangulares a la izquierda de las páginas.
QTabBar::TriangularEast7Pestañas triangulares a la derecha de las páginas.

Documentación de propiedades

autoHide : bool

Si 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 acceso:

bool autoHide() const
void setAutoHide(bool hide)

Véase también QWidget::visible.

changeCurrentOnDrag : bool

Si es true, la pestaña actual se cambia automáticamente al arrastrar sobre la barra de pestañas.

Nota: También debe establecer la propiedad acceptDrops a true para que esta característica funcione.

Por defecto, esta propiedad es false.

Funciones de acceso:

bool changeCurrentOnDrag() const
void setChangeCurrentOnDrag(bool change)

[read-only] count : int

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

Funciones de acceso:

int count() const

currentIndex : int

Esta propiedad contiene el índice de la pestaña visible de la barra de pestañas

El índice actual es -1 si no hay pestaña actual.

Funciones de acceso:

int currentIndex() const
void setCurrentIndex(int index)

Señal del notificador:

void currentChanged(int index)

documentMode : bool

Esta propiedad indica si la barra de pestañas se muestra o no en un modo adecuado para la ventana principal.

Esta propiedad se utiliza como una sugerencia para que los estilos dibujen las pestañas de una manera diferente a como se verían normalmente en un widget de pestañas. En macOS tendrá un aspecto similar al de las pestañas de Safari o Terminal.app de Sierra.

Funciones de acceso:

bool documentMode() const
void setDocumentMode(bool set)

Véase también QTabWidget::documentMode.

drawBase : bool

define si la barra de pestañas debe o no dibujar su base.

Si es true entonces QTabBar dibuja una base en relación a la superposición de estilos. En caso contrario, sólo se dibujan las pestañas.

Funciones de acceso:

bool drawBase() const
void setDrawBase(bool drawTheBase)

Véase también QStyle::pixelMetric(), QStyle::PM_TabBarBaseOverlap, y QStyleOptionTabBarBase.

elideMode : Qt::TextElideMode

cómo elidir texto en la barra de pestañas

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

Por defecto, el valor depende del estilo.

Funciones de acceso:

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

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

expanding : bool

Cuando expandir es true QTabBar expandirá las pestañas para usar el espacio vacío.

Por defecto el valor es true.

Funciones de acceso:

bool expanding() const
void setExpanding(bool enabled)

Véase también QTabWidget::documentMode.

iconSize : QSize

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

El valor por defecto depende del estilo. iconSize es un tamaño máximo; los iconos que son más pequeños no se escalan.

Funciones de acceso:

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

Véase también QTabWidget::iconSize.

movable : bool

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

Por defecto, esta propiedad es false;

Funciones de acceso:

bool isMovable() const
void setMovable(bool movable)

selectionBehaviorOnRemove : SelectionBehavior

Qué pestaña debe establecerse como actual cuando se llama a removeTab si la pestaña eliminada es también la pestaña actual.

Por defecto el valor es SelectRightTab.

Funciones de acceso:

QTabBar::SelectionBehavior selectionBehaviorOnRemove() const
void setSelectionBehaviorOnRemove(QTabBar::SelectionBehavior behavior)

Véase también removeTab().

shape : Shape

Esta propiedad contiene la forma de las pestañas en la barra de pestañas.

Los posibles valores de esta propiedad se describen en el enum Shape.

Funciones de acceso:

QTabBar::Shape shape() const
void setShape(QTabBar::Shape shape)

tabsClosable : bool

Esta propiedad establece si una barra de pestañas debe o no colocar botones de cierre en cada pestaña.

Cuando tabsClosable está establecido a true un botón de cierre aparecerá en la pestaña a la izquierda o a la derecha dependiendo del estilo. Cuando se pulsa el botón directamente, o se recibe un clic del ratón en cualquier parte de la pestaña, se emite la señal tabCloseRequested.

Por defecto el valor es false.

Funciones de acceso:

bool tabsClosable() const
void setTabsClosable(bool closable)

Véase también setTabButton() y tabRemoved().

usesScrollButtons : bool

Esta propiedad establece si una barra de pestañas debe o no utilizar botones para desplazarse por las pestañas cuando tiene muchas pestañas.

Cuando hay demasiadas pestañas en una barra de pestañas para su tamaño, la barra de pestañas puede elegir expandir su tamaño o 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, QTabWidget::usesScrollButtons, y QStyle::SH_TabBar_PreferNoArrows.

Documentación de las funciones miembro

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

Crea una nueva barra de pestañas con la dirección parent.

[virtual noexcept] QTabBar::~QTabBar()

Destruye la barra de pestañas.

QString QTabBar::accessibleTabName(int index) const

Devuelve el nombre accesible de la pestaña en la posición index, o una cadena vacía si index está fuera de rango.

Véase también setAccessibleTabName().

int QTabBar::addTab(const QString &text)

Añade una nueva pestaña con el texto text. Devuelve el índice de la nueva pestaña.

int QTabBar::addTab(const QIcon &icon, const QString &text)

Añade una nueva pestaña con el icono icon y el texto text. Devuelve el índice de la nueva pestaña.

Se trata de una función sobrecargada.

[override virtual protected] void QTabBar::changeEvent(QEvent *event)

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

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

Esta señal se emite cuando cambia la pestaña actual de la barra de pestañas. La nueva actual tiene el valor dado index, o -1 si no hay una nueva (por ejemplo, si no hay ninguna pestaña en QTabBar).

Nota: Señal notificadora para la propiedad currentIndex.

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

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

[override virtual protected] void QTabBar::hideEvent(QHideEvent *)

Reimplementa: QWidget::hideEvent(QHideEvent *event).

[virtual protected] void QTabBar::initStyleOption(QStyleOptionTab *option, int tabIndex) const

Inicializa option con los valores de la ficha en tabIndex. Este método es útil para subclases cuando necesitan un QStyleOptionTab, pero no quieren rellenar toda la información ellos mismos.

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

int QTabBar::insertTab(int index, const QString &text)

Inserta una nueva pestaña con el texto text en la posición index. Si index está fuera de rango, se añade la nueva pestaña. Devuelve el índice de la nueva pestaña.

int QTabBar::insertTab(int index, const QIcon &icon, const QString &text)

Inserta una nueva pestaña con el icono icon y el texto text en la posición index. Si index está fuera de rango, se añade la nueva pestaña. Devuelve el índice de la nueva pestaña.

Si QTabBar estaba vacío antes de llamar a esta función, la pestaña insertada se convierte en la pestaña actual.

Insertar una nueva pestaña en un índice menor o igual al índice actual incrementará el índice actual, pero mantendrá la pestaña actual.

Esta función está sobrecargada.

bool QTabBar::isTabEnabled(int index) const

Devuelve true si la pestaña en la posición index está activada; en caso contrario devuelve false.

bool QTabBar::isTabVisible(int index) const

Devuelve true si la pestaña en la posición index es visible; en caso contrario devuelve false.

[override virtual protected] void QTabBar::keyPressEvent(QKeyEvent *event)

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

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

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

[virtual protected] QSize QTabBar::minimumTabSizeHint(int index) const

Devuelve la sugerencia de tamaño de tabulación mínimo para la tabulación en la posición index.

[override virtual protected] void QTabBar::mouseDoubleClickEvent(QMouseEvent *event)

Reimplementa: QWidget::mouseDoubleClickEvent(QMouseEvent *event).

[override virtual protected] void QTabBar::mouseMoveEvent(QMouseEvent *event)

Reimplementa: QWidget::mouseMoveEvent(QMouseEvent *event).

[override virtual protected] void QTabBar::mousePressEvent(QMouseEvent *event)

Reimplementa: QWidget::mousePressEvent(QMouseEvent *event).

[override virtual protected] void QTabBar::mouseReleaseEvent(QMouseEvent *event)

Reimplementa: QWidget::mouseReleaseEvent(QMouseEvent *event).

void QTabBar::moveTab(int from, int to)

Mueve el elemento en la posición de índice from a la posición de índice to.

Véase también tabMoved() y tabLayoutChange().

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

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

void QTabBar::removeTab(int index)

Elimina la pestaña en la posición index.

Véase también SelectionBehavior.

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

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

void QTabBar::setAccessibleTabName(int index, const QString &name)

Establece el nombre accesible de la pestaña en la posición index a name.

Véase también accessibleTabName().

void QTabBar::setTabButton(int index, QTabBar::ButtonPosition position, QWidget *widget)

Establece widget en la pestaña index. El widget se coloca a la izquierda o a la derecha en función de position.

Cualquier widget configurado previamente en position se oculta. Establecer widget en nullptr ocultará el widget actual en position.

La barra de pestañas asumirá la propiedad del widget, por lo que todos los widgets establecidos aquí serán eliminados por la barra de pestañas cuando se destruya, a menos que vuelva a asignar el widget por separado después de establecer algún otro widget (o nullptr).

Véase también tabButton() y tabsClosable().

void QTabBar::setTabData(int index, const QVariant &data)

Establece los datos de la pestaña en la posición index a data.

Véase también tabData().

void QTabBar::setTabEnabled(int index, bool enabled)

Si enabled es verdadero, se activa la pestaña en la posición index; en caso contrario, se desactiva el elemento en la posición index.

Véase también isTabEnabled().

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

Establece el icono de la pestaña en la posición index a icon.

Véase también tabIcon().

void QTabBar::setTabText(int index, const QString &text)

Establece el texto de la pestaña en la posición index a text.

Véase también tabText().

void QTabBar::setTabTextColor(int index, const QColor &color)

Establece el color del texto de la pestaña con el index dado al color especificado.

Si se especifica un color no válido, la pestaña utilizará en su lugar el papel de primer plano QTabBar.

Véase también tabTextColor().

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

Establece la punta de la herramienta de la pestaña en la posición index a tip.

Véase también tabToolTip().

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

Si visible es verdadero, hace visible la pestaña en la posición index, en caso contrario la oculta.

Véase también isTabVisible().

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

Establece el texto de ayuda What's This de la pestaña en la posición index a text.

Véase también tabWhatsThis().

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

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

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

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

int QTabBar::tabAt(const QPoint &position) const

Devuelve el índice de la pestaña que cubre position o -1 si ninguna pestaña cubre position;

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

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

index es el índice de una pestaña pulsada, o -1 si no hay ninguna pestaña bajo el cursor.

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

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

index se refiere a la pestaña pulsada, o -1 si no hay ninguna pestaña bajo el cursor.

QWidget *QTabBar::tabButton(int index, QTabBar::ButtonPosition position) const

Devuelve el widget establecido una pestaña index y position o nullptr si no hay ninguna establecida.

Véase también setTabButton().

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

Esta señal se emite cuando se pulsa el botón de cierre de una pestaña. El index es el índice que debe ser eliminado.

Véase también setTabsClosable().

QVariant QTabBar::tabData(int index) const

Devuelve los datos de la pestaña en la posición index, o una variante nula si index está fuera de rango.

Véase también setTabData().

QIcon QTabBar::tabIcon(int index) const

Devuelve el icono de la pestaña en la posición index, o un icono nulo si index está fuera de rango.

Véase también setTabIcon().

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

Este manejador virtual es llamado después de que una nueva pestaña fue añadida o insertada en la posición index.

Véase también tabRemoved().

[virtual protected] void QTabBar::tabLayoutChange()

Este manejador virtual es llamado cada vez que cambia el diseño de la pestaña.

Véase también tabRect().

[signal] void QTabBar::tabMoved(int from, int to)

Esta señal se emite cuando la barra de pestañas ha movido la pestaña en la posición de índice from a la posición de índice to.

nota: QTabWidget moverá automáticamente la página cuando se emita esta señal desde su barra de pestañas.

Véase también moveTab().

QRect QTabBar::tabRect(int index) const

Devuelve el rectángulo visual de la pestaña en la posición index, o un rectángulo nulo si index está oculto, o fuera de rango.

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

Este manejador virtual es llamado después de que una pestaña fue removida de la posición index.

Véase también tabInserted().

[virtual protected] QSize QTabBar::tabSizeHint(int index) const

Devuelve la sugerencia de tamaño para la pestaña en la posición index.

QString QTabBar::tabText(int index) const

Devuelve el texto del tabulador en la posición index, o una cadena vacía si index está fuera de rango.

Véase también setTabText().

QColor QTabBar::tabTextColor(int index) const

Devuelve el color del texto de la pestaña con el valor dado index, o un color no válido si index está fuera de rango.

Véase también setTabTextColor().

QString QTabBar::tabToolTip(int index) const

Devuelve el tool tip de la pestaña en la posición index, o una cadena vacía si index está fuera de rango.

Véase también setTabToolTip().

QString QTabBar::tabWhatsThis(int index) const

Devuelve el texto de ayuda What's This de la pestaña en la posición index, o una cadena vacía si index está fuera de rango.

Véase también setTabWhatsThis().

[override virtual protected] void QTabBar::timerEvent(QTimerEvent *event)

Reimplementa: QObject::timerEvent(QTimerEvent *event).

[override virtual protected] void QTabBar::wheelEvent(QWheelEvent *event)

Reimplementa: QWidget::wheelEvent(QWheelEvent *event).

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