QTabWidget Class
The QTabWidget class provides a stack of tabbed widgets. More...
| Header: | #include <QTabWidget> |
| qmake: | QT += widgets |
| Inherits: | QWidget |
Public Types
| enum | TabPosition { North, South, West, East } |
| enum | TabShape { Rounded, Triangular } |
Properties
|
|
Public Functions
| int | count() const |
| int | currentIndex() const |
| bool | documentMode() const |
| Qt::TextElideMode | elideMode() const |
| QSize | iconSize() const |
| bool | isMovable() const |
| void | setDocumentMode(bool set) |
| void | setElideMode(Qt::TextElideMode mode) |
| void | setIconSize(const QSize &size) |
| void | setMovable(bool movable) |
| void | setTabBarAutoHide(bool enabled) |
| void | setTabPosition(QTabWidget::TabPosition position) |
| void | setTabShape(QTabWidget::TabShape s) |
| void | setTabsClosable(bool closeable) |
| void | setUsesScrollButtons(bool useButtons) |
| bool | tabBarAutoHide() const |
| QTabWidget::TabPosition | tabPosition() const |
| QTabWidget::TabShape | tabShape() const |
| bool | tabsClosable() const |
| bool | usesScrollButtons() const |
Public Slots
| void | setCurrentIndex(int index) |
Signals
| void | currentChanged(int index) |
Detailed Description
A tab widget provides a tab bar (see QTabBar) and a "page area" that is used to display pages related to each tab. By default, the tab bar is shown above the page area, but different configurations are available (see TabPosition). Each tab is associated with a different widget (called a page). Only the current page is shown in the page area; all the other pages are hidden. The user can show a different page by clicking on its tab or by pressing its Alt+letter shortcut if it has one.
The normal way to use QTabWidget is to do the following:
- Create a QTabWidget.
- Create a QWidget for each of the pages in the tab dialog, but do not specify parent widgets for them.
- Insert child widgets into the page widget, using layouts to position them as normal.
- Call addTab() or insertTab() to put the page widgets into the tab widget, giving each tab a suitable label with an optional keyboard shortcut.
The position of the tabs is defined by tabPosition, their shape by tabShape.
The signal currentChanged() is emitted when the user selects a page.
The current page index is available as currentIndex(), the current page widget with currentWidget(). You can retrieve a pointer to a page widget with a given index using widget(), and can find the index position of a widget with indexOf(). Use setCurrentWidget() or setCurrentIndex() to show a particular page.
You can change a tab's text and icon using setTabText() or setTabIcon(). A tab and its associated page can be removed with removeTab().
Each tab is either enabled or disabled at any given time (see setTabEnabled()). If a tab is enabled, the tab text is drawn normally and the user can select that tab. If it is disabled, the tab is drawn in a different way and the user cannot select that tab. Note that even if a tab is disabled, the page can still be visible, for example if all of the tabs happen to be disabled.
Tab widgets can be a very good way to split up a complex dialog. An alternative is to use a QStackedWidget for which you provide some means of navigating between pages, for example, a QToolBar or a QListWidget.
Most of the functionality in QTabWidget is provided by a QTabBar (at the top, providing the tabs) and a QStackedWidget (most of the area, organizing the individual pages).
See also QTabBar, QStackedWidget, QToolBox, and Tab Dialog Example.
Member Type Documentation
enum QTabWidget::TabPosition
This enum type defines where QTabWidget draws the tab row:
| Constant | Value | Description |
|---|---|---|
QTabWidget::North | 0 | The tabs are drawn above the pages. |
QTabWidget::South | 1 | The tabs are drawn below the pages. |
QTabWidget::West | 2 | The tabs are drawn to the left of the pages. |
QTabWidget::East | 3 | The tabs are drawn to the right of the pages. |
enum QTabWidget::TabShape
This enum type defines the shape of the tabs:
| Constant | Value | Description |
|---|---|---|
QTabWidget::Rounded | 0 | The tabs are drawn with a rounded look. This is the default shape. |
QTabWidget::Triangular | 1 | The tabs are drawn with a triangular look. |
Property Documentation
count : const int
This property holds the number of tabs in the tab bar
By default, this property contains a value of 0.
Access functions:
| int | count() const |
currentIndex : int
This property holds the index position of the current tab page
The current index is -1 if there is no current widget.
By default, this property contains a value of -1 because there are initially no tabs in the widget.
Access functions:
| int | currentIndex() const |
| void | setCurrentIndex(int index) |
Notifier signal:
| void | currentChanged(int index) |
documentMode : bool
This property holds whether or not the tab widget is rendered in a mode suitable for document pages. This is the same as document mode on macOS.
When this property is set the tab widget frame is not rendered. This mode is useful for showing document-type pages where the page covers most of the tab widget area.
This property was introduced in Qt 4.5.
Access functions:
| bool | documentMode() const |
| void | setDocumentMode(bool set) |
See also elideMode, QTabBar::documentMode, QTabBar::usesScrollButtons, and QStyle::SH_TabBar_PreferNoArrows.
elideMode : Qt::TextElideMode
how to elide text in the tab bar
This property controls how items are elided when there is not enough space to show them for a given tab bar size.
By default the value is style dependent.
This property was introduced in Qt 4.2.
Access functions:
| Qt::TextElideMode | elideMode() const |
| void | setElideMode(Qt::TextElideMode mode) |
See also QTabBar::elideMode, usesScrollButtons, and QStyle::SH_TabBar_ElideMode.
iconSize : QSize
This property holds the size for icons in the tab bar
The default value is style-dependent. This is the maximum size that the icons will have. Icons are not scaled up if they are of smaller size.
This property was introduced in Qt 4.2.
Access functions:
| QSize | iconSize() const |
| void | setIconSize(const QSize &size) |
See also QTabBar::iconSize.
movable : bool
This property holds whether the user can move the tabs within the tabbar area.
By default, this property is false;
This property was introduced in Qt 4.5.
Access functions:
| bool | isMovable() const |
| void | setMovable(bool movable) |
tabBarAutoHide : bool
If true, the tab bar is automatically hidden when it contains less than 2 tabs.
By default, this property is false.
This property was introduced in Qt 5.4.
Access functions:
| bool | tabBarAutoHide() const |
| void | setTabBarAutoHide(bool enabled) |
See also QWidget::visible.
tabPosition : TabPosition
This property holds the position of the tabs in this tab widget
Possible values for this property are described by the TabPosition enum.
By default, this property is set to North.
Access functions:
| QTabWidget::TabPosition | tabPosition() const |
| void | setTabPosition(QTabWidget::TabPosition position) |
See also TabPosition.
tabShape : TabShape
This property holds the shape of the tabs in this tab widget
Possible values for this property are QTabWidget::Rounded (default) or QTabWidget::Triangular.
Access functions:
| QTabWidget::TabShape | tabShape() const |
| void | setTabShape(QTabWidget::TabShape s) |
See also TabShape.
tabsClosable : bool
This property holds whether close buttons are automatically added to each tab.
This property was introduced in Qt 4.5.
Access functions:
| bool | tabsClosable() const |
| void | setTabsClosable(bool closeable) |
See also QTabBar::tabsClosable().
usesScrollButtons : bool
This property holds whether or not a tab bar should use buttons to scroll tabs when it has many tabs.
When there are too many tabs in a tab bar for its size, the tab bar can either choose to expand its size or to add buttons that allow you to scroll through the tabs.
By default the value is style dependent.
This property was introduced in Qt 4.2.
Access functions:
| bool | usesScrollButtons() const |
| void | setUsesScrollButtons(bool useButtons) |
See also elideMode, QTabBar::usesScrollButtons, and QStyle::SH_TabBar_PreferNoArrows.