QTabWidget Class
La clase QTabWidget proporciona una pila de widgets con pestañas. Más...
| Cabecera: | #include <QTabWidget> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets)target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Hereda: | 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
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 existen diferentes configuraciones (véase TabPosition). Cada pestaña está asociada a un widget diferente (llamado página). Sólo la página actual se muestra en el área de la página; todas las demás páginas están ocultas. El usuario puede mostrar una página diferente haciendo clic en su pestaña o pulsando su método abreviado Alt+letra si dispone de uno.
La forma normal de utilizar QTabWidget es hacer lo siguiente:
- Crear un QTabWidget.
- Cree un QWidget para cada una de las páginas del diálogo de pestañas, pero no especifique widgets padre para ellas.
- Inserta los widgets hijos en el widget de página, usando layouts para posicionarlos normalmente.
- Llama a addTab() o insertTab() para colocar los widgets de página en el widget de pestaña, dando a cada pestaña una etiqueta adecuada con un atajo de teclado opcional.
La posición de las pestañas se define mediante tabPosition, su forma mediante tabShape.
La señal currentChanged() se emite cuando el usuario selecciona una página.
El índice de la página actual está disponible como currentIndex(), el widget de la página actual con currentWidget(). Puedes recuperar un puntero a un widget de página con un índice dado utilizando widget(), y puedes encontrar la posición del índice de un widget con indexOf(). Utilice setCurrentWidget() o setCurrentIndex() para mostrar una página determinada.
Puede cambiar el texto y el icono de una pestaña utilizando setTabText() o setTabIcon(). Una pestaña y su página asociada pueden eliminarse con removeTab().
Cada pestaña está activada o desactivada en un momento dado (véase setTabEnabled()). Si una pestaña está activada, el texto de la pestaña se dibuja normalmente y el usuario puede seleccionar esa pestaña. Si está desactivada, la pestaña se dibuja de forma diferente y el usuario no puede seleccionarla. Ten en cuenta que aunque una pestaña esté deshabilitada, la página puede seguir siendo visible, por ejemplo si todas las pestañas están deshabilitadas.
Los widgets de pestañas pueden ser una muy buena forma de dividir un diálogo complejo. Una alternativa es utilizar un QStackedWidget para el que se proporciona algún medio de navegación entre páginas, por ejemplo, un QToolBar o un QListWidget.
La mayor parte de la funcionalidad en QTabWidget es proporcionada por un QTabBar (en la parte superior, proporcionando las pestañas) y un QStackedWidget (la mayor parte del área, organizando las páginas individuales).
Ver también QTabBar, QStackedWidget, QToolBox, y Tab Dialog Example.
Documentación de tipos de miembros
enum QTabWidget::TabPosition
Este tipo enum define dónde QTabWidget dibuja la fila de tabulación:
| Constante | Valor | Descripción |
|---|---|---|
QTabWidget::North | 0 | Las pestañas se dibujan por encima de las páginas. |
QTabWidget::South | 1 | Las pestañas se dibujan debajo de las páginas. |
QTabWidget::West | 2 | Las pestañas se dibujan a la izquierda de las páginas. |
QTabWidget::East | 3 | Las pestañas se dibujan a la derecha de las páginas. |
enum QTabWidget::TabShape
Este tipo enum define la forma de las pestañas:
| Constante | Valor | Descripción |
|---|---|---|
QTabWidget::Rounded | 0 | Las pestañas se dibujan con un aspecto redondeado. Esta es la forma por defecto. |
QTabWidget::Triangular | 1 | Las pestañas se dibujan con un aspecto triangular. |
Documentación de la propiedad
[read-only] count : int
Esta propiedad contiene el número de pestañas en la barra de pestañas.
Por defecto, esta propiedad contiene un valor de 0.
Funciones de acceso:
| int | count() const |
currentIndex : int
Esta propiedad contiene la posición del índice de la etiqueta actual
El índice actual es -1 si no hay widget actual.
Por defecto, esta propiedad contiene un valor de -1 porque inicialmente no hay pestañas en el widget.
Funciones de acceso:
| int | currentIndex() const |
| void | setCurrentIndex(int index) |
Señal del notificador:
| void | currentChanged(int index) |
documentMode : bool
Esta propiedad indica si el widget de pestaña se muestra o no en un modo adecuado para páginas de documentos. Esto es lo mismo que el modo documento en macOS.
Cuando esta propiedad está activada, el marco del widget de pestaña no se muestra. Este modo es útil para mostrar páginas tipo documento donde la página cubre la mayor parte del área del widget de pestaña.
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 elidir texto en la barra de pestañas
Esta propiedad controla cómo se eliden los elementos cuando no hay suficiente espacio 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 QTabBar::elideMode, usesScrollButtons, y QStyle::SH_TabBar_ElideMode.
iconSize : QSize
Esta propiedad contiene 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 escalan si tienen un tamaño menor.
Funciones de acceso:
| QSize | iconSize() const |
| void | setIconSize(const QSize &size) |
Véase también QTabBar::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) |
tabBarAutoHide : 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 | tabBarAutoHide() const |
| void | setTabBarAutoHide(bool enabled) |
Véase también QWidget::visible.
tabPosition : TabPosition
Esta propiedad contiene la posición de las pestañas en este widget de pestañas
Los posibles valores de esta propiedad se describen en el enum TabPosition.
Por defecto, esta propiedad tiene el valor North.
Funciones de acceso:
| QTabWidget::TabPosition | tabPosition() const |
| void | setTabPosition(QTabWidget::TabPosition position) |
Véase también TabPosition.
tabShape : TabShape
Esta propiedad contiene 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 indica si los botones de cierre se añaden automáticamente a cada pestaña.
Funciones de acceso:
| bool | tabsClosable() const |
| void | setTabsClosable(bool closeable) |
Véase también QTabBar::tabsClosable().
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, QTabBar::usesScrollButtons, y QStyle::SH_TabBar_PreferNoArrows.
Documentación de las funciones miembro
[explicit] QTabWidget::QTabWidget(QWidget *parent = nullptr)
Construye un widget de pestañas con el padre parent.
[virtual noexcept] QTabWidget::~QTabWidget()
Destruye el widget de pestañas.
int QTabWidget::addTab(QWidget *page, const QString &label)
Añade una pestaña con los datos page 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 pasa a QTabWidget.
Si el label de la pestaña contiene un ampersand, la letra que sigue al ampersand 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 moverá el foco a esta pestaña.
Nota: Si llama a addTab() después de show(), el sistema de maquetación intentará ajustarse a los cambios en su jerarquía de widgets y puede causar parpadeos. Para prevenir esto, puedes establecer la propiedad QWidget::updatesEnabled a false antes de los cambios; recuerda establecer la propiedad a true cuando los cambios hayan terminado, haciendo que el widget vuelva a recibir eventos paint.
Véase también insertTab().
int QTabWidget::addTab(QWidget *page, const QIcon &icon, const QString &label)
Añade una pestaña con los datos 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 pasa a QTabWidget.
Esta función es la misma que addTab(), pero con un icon adicional.
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 esté vacío.
QWidget *QTabWidget::cornerWidget(Qt::Corner corner = Qt::TopRightCorner) const
Devuelve el widget mostrado en corner del widget de pestaña o 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 ninguna nueva (por ejemplo, si no hay widgets en la QTabWidget).
Nota: Señal notificadora para la propiedad currentIndex.
Véase también currentWidget() y currentIndex.
QWidget *QTabWidget::currentWidget() const
Devuelve un puntero a la página que está mostrando actualmente el diálogo de pestañas. El diálogo de pestañas hace todo lo posible para asegurarse de que este valor nunca sea 0 (pero si se esfuerza lo suficiente, puede 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 del índice de la página ocupada por 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 QTabWidget. Este método es útil para subclases cuando necesitan un QStyleOptionTabWidgetFrame, pero no quieren rellenar toda la información ellos mismos.
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 campos label y page en el widget de pestañas en el campo index y devuelve el índice de la pestaña insertada en la barra de pestañas. La propiedad de page se pasa a QTabWidget.
La etiqueta se muestra en la pestaña y puede variar de aspecto en función de la configuración del widget de pestaña.
Si label de la pestaña contiene un ampersand, la letra que sigue al ampersand 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 moverá el foco a esta pestaña.
Si index está fuera de rango, la pestaña simplemente se añade. 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. Insertar una nueva pestaña en un índice menor o igual al índice actual incrementará el índice actual, pero mantendrá la página actual.
Nota: Si llama a insertTab() después de show(), el sistema de maquetación intentará ajustarse a los cambios en su jerarquía de widgets y puede provocar parpadeos. Para prevenir esto, puedes establecer la propiedad QWidget::updatesEnabled a false antes de los cambios; recuerda establecer la propiedad a true cuando los cambios hayan terminado, haciendo que el widget vuelva a recibir eventos paint.
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 label, page, y icon en el widget de pestañas en el valor index especificado, y devuelve el índice de la pestaña insertada en la barra de pestañas. La propiedad de page se pasa a QTabWidget.
Esta función es la misma que 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 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 en la posición index es 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).
Pinta la barra de pestañas del widget de pestañas en respuesta al evento paint event.
void QTabWidget::removeTab(int index)
Elimina la pestaña 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 el widget dado para que se muestre en el corner especificado del widget de pestaña. La geometría del widget se determina en función de sizeHint() y style() del widget.
Sólo se utilizará el elemento horizontal del corner.
Pasando nullptr no se muestra ningún widget en la esquina.
Cualquier widget de esquina previamente establecido se oculta.
Todos los widgets establecidos aquí serán eliminados por el widget de pestaña cuando se destruya, a menos que vuelva a asignar el widget por separado después de 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)
Hace que widget sea el widget actual. El widget utilizado debe ser una página en este widget de pestaña.
Véase también addTab(), setCurrentIndex(), y currentWidget().
[protected] void QTabWidget::setTabBar(QTabBar *tb)
Sustituye el encabezado del diálogo QTabBar por la barra de pestañas tb. Tenga en cuenta que esto debe ser llamado antes de que cualquier pestaña haya sido añadida, o el comportamiento será indefinido.
Véase también tabBar().
void QTabWidget::setTabEnabled(int index, bool enable)
Si enable es verdadero, se habilita la página en la posición index; en caso contrario, se deshabilita la página en la posición index. La pestaña de la página se redibuja apropiadamente.
QTabWidget utiliza QWidget::setEnabled() internamente, en lugar de mantener una bandera separada.
Ten en cuenta que incluso una pestaña/página desactivada puede ser visible. Si la página ya está visible, QTabWidget no la ocultará; si todas las páginas están deshabilitadas, QTabWidget mostrará una de ellas.
Véase también isTabEnabled() y QWidget::setEnabled().
void QTabWidget::setTabIcon(int index, const QIcon &icon)
Establece el icon para la pestaña en la posición index.
Véase también tabIcon().
void QTabWidget::setTabText(int index, const QString &label)
Define un nuevo label para la página en la posición index's tab.
Si el texto proporcionado contiene un carácter ampersand ('&'), se creará automáticamente un atajo para él. El carácter que sigue al '&' se utilizará como tecla de acceso directo. Cualquier acceso directo anterior se sobrescribirá, o se borrará si el texto no define ningún acceso directo. Consulte la documentación de QShortcut para más detalles (para mostrar un ampersand real, utilice '&&').
Véase también tabText().
void QTabWidget::setTabToolTip(int index, const QString &tip)
Establece la punta de la herramienta de tabulación para la página en la posición index a tip.
Véase también tabToolTip().
void QTabWidget::setTabVisible(int index, bool visible)
Si visible es verdadero, la página en la posición index es visible; en caso contrario, la página en la posición index se oculta. La pestaña de la página se redibuja adecuadamente.
Véase también isTabVisible().
void QTabWidget::setTabWhatsThis(int index, const QString &text)
Establece el texto de ayuda What's This para la página en la posición index a 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 la dirección actual 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 se refiere a la pestaña pulsada, 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 una pestaña pulsada, o -1 si no hay ninguna pestaña bajo el cursor.
[signal] void QTabWidget::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().
QIcon QTabWidget::tabIcon(int index) const
Devuelve el icono de la pestaña de la página en la posición index.
Véase también setTabIcon().
[virtual protected] void QTabWidget::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 QTabWidget::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().
QString QTabWidget::tabText(int index) const
Devuelve el texto de la etiqueta de la pestaña de la página en la posición index.
Véase también setTabText().
QString QTabWidget::tabToolTip(int index) const
Devuelve el tool tip de tabulación para la página en la posición index o una cadena vacía si no se ha establecido ningún tool tip.
Véase también setTabToolTip().
QString QTabWidget::tabWhatsThis(int index) const
Devuelve el texto de ayuda What's This para la página 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 etiqueta en la posición de índice index o nullptr si 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.
