内容

• 公共类型
• 特性
• 公共函数
• 重实现公共函数
• 公共槽
• 信号
• 保护函数
• 重实现保护函数
• 详细描述

QTabWidget 类

QTabWidget 类提供选项卡式 Widget 堆栈。 更多...

头：	#include <QTabWidget>
CMake:	find_package(Qt6 COMPONENTS Widgets REQUIRED) target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake:	QT += widgets
继承：	QWidget

• 所有成员列表，包括继承成员

公共类型

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

特性

count : const int currentIndex : int documentMode : bool elideMode : Qt::TextElideMode iconSize : QSize movable : bool

tabBarAutoHide : bool tabPosition : TabPosition tabShape : TabShape tabsClosable : bool usesScrollButtons : bool

公共函数

	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

重实现公共函数

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

公共槽

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

信号

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

保护函数

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

重实现保护函数

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

详细描述

选项卡小部件提供选项卡栏 (见 QTabBar ) 和页面区域用于显示每选项卡相关页面。默认情况下，选项卡栏展示在页面区域上方，但有不同可用配置 (见 TabPosition )。每选项卡关联不同 Widget (称为页面)。页面区域仅展示当前页面。所有其它页面被隐藏。用户可以展示不同页面通过点击其选项卡或按下其 Alt+ letter 快捷键若有的话。

平常方式使用 QTabWidget 是做以下：

1. 创建 QTabWidget。
2. 创建 QWidget 对于每选项卡对话框页面，但不要为它们指定父级小部件。
3. 将子级 Widget 插入页面小部件，使用布局正常安放它们。
4. 调用 addTab () 或 insertTab () 将页面 Widget 放入选项卡小部件，为每选项卡赋予适合标签采用可选键盘快捷键。

选项卡位置的定义通过 tabPosition ，它们的形状通过 tabShape .

信号 currentChanged () 被发射当用户选择页面时。

当前页面索引可用作 currentIndex ()，当前页面 Widget 采用 currentWidget ()。可以检索具有给定索引的页面小部件指针使用 widget ()，和可以查找小部件的位置索引采用 indexOf ()。使用 setCurrentWidget () 或 setCurrentIndex () 以展示特定页面。

可以更改选项卡的文本和图标使用 setTabText () 或 setTabIcon ()。可以移除选项卡及其关联页面采用 removeTab ().

可以随时启用或禁用每选项卡 (见 setTabEnabled ())。若选项卡被启用，将正常绘制选项卡文本且用户可以选择该选项卡。若被禁用，将以不同方式绘制选项卡且用户无法选择该选项卡。注意，即使选项卡被禁用，页面仍可见 (例如：若所有选项卡被禁用)。

选项卡小部件可以是拆分复杂对话框的很好方式。另一方式是使用 QStackedWidget 提供在页面之间导航的一些手段，例如 QToolBar 或 QListWidget .

大多数功能在 QTabWidget 的提供是通过 QTabBar (在顶部，提供选项卡) 和 QStackedWidget (大部分区域，组织各个页面)。

另请参阅 QTabBar , QStackedWidget , QToolBox ，和 选项卡对话框范例 .

成员类型文档编制

enum QTabWidget:: TabPosition

此枚举类型定义在哪里 QTabWidget 绘制选项卡行：

常量	值	描述
QTabWidget::North	0	选项卡绘制在页面上方。
QTabWidget::South	1	选项卡绘制在页面下方。
QTabWidget::West	2	选项卡绘制在页面左侧。
QTabWidget::East	3	选项卡绘制在页面右侧。

enum QTabWidget:: TabShape

此枚举类型定义选项卡的形状：

常量	值	描述
QTabWidget::Rounded	0	选项卡采用圆角外观绘制。这是默认形状。
QTabWidget::Triangular	1	选项卡采用三角形外观绘制。

特性文档编制

[read-only] count : const int

此特性保持选项卡栏的选项卡数

默认情况下，此特性包含 0 值。

访问函数：

int	count () const

currentIndex : int

此特性保持当前选项卡页面的索引位置

当前索引为 -1，若没有当前 Widget。

默认情况下，此特性包含 -1 值，因为小部件最初没有选项卡。

访问函数：

int	currentIndex () const
void	setCurrentIndex (int index )

通知程序信号：

void	currentChanged (int index )

documentMode : bool

此特性保持选项卡 Widget 是否以适于文档页面的模式进行渲染。这如同 macOS 文档模式。

当设置此特性时，不渲染选项卡小部件框架。此模式用于展示文档类型页面 (页面涵盖大部分选项卡小部件区域)。

访问函数：

bool	documentMode () const
void	setDocumentMode (bool set )

另请参阅 elideMode , QTabBar::documentMode , QTabBar::usesScrollButtons ，和 QStyle::SH_TabBar_PreferNoArrows .

elideMode : Qt::TextElideMode

如何省略标签栏文本

此特性控制如何省略项，当没有足够空间展示它们 (对于给定选项卡栏尺寸) 时。

默认情况下，值从属样式。

访问函数：

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

另请参阅 QTabBar::elideMode , usesScrollButtons ，和 QStyle::SH_TabBar_ElideMode .

iconSize : QSize

此特性保持选项卡栏的图标尺寸

默认值从属样式。这是图标将拥有的最大尺寸。不会按比例放大图标，若尺寸较小。

访问函数：

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

另请参阅 QTabBar::iconSize .

movable : bool

此特性保持用户是否可以在选项卡栏区域内，移动选项卡。

默认情况下，此特性为 false ;

访问函数：

bool	isMovable () const
void	setMovable (bool movable )

[since 5.4] tabBarAutoHide : bool

若为 true，自动隐藏选项卡栏，当包含少于 2 个选项卡时。

默认情况下，此特性为 false。

该特性在 Qt 5.4 引入。

访问函数：

bool	tabBarAutoHide () const
void	setTabBarAutoHide (bool enabled )

另请参阅 QWidget::visible .

tabPosition : TabPosition

此特性保持此选项卡小部件中选项卡的位置

此特性的可能值，描述通过 TabPosition 枚举。

默认情况下，此特性被设为 North .

访问函数：

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

另请参阅 TabPosition .

tabShape : TabShape

此特性保持此选项卡小部件中选项卡的形状

此特性的可能值， QTabWidget::Rounded (默认) 或 QTabWidget::Triangular .

访问函数：

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

另请参阅 TabShape .

tabsClosable : bool

此特性保持是否将关闭按钮自动添加到每个选项卡。

访问函数：

bool	tabsClosable () const
void	setTabsClosable (bool closeable )

另请参阅 QTabBar::tabsClosable ().

usesScrollButtons : bool

此特性保持选项卡栏是否应使用卷动按钮，当包含多个选项卡时。

当选项卡栏选项卡太多时 (对于其大小)，选项卡栏可以选择展开其大小，或添加按钮以允许卷动选项卡。

默认情况下，值从属样式。

访问函数：

bool	usesScrollButtons () const
void	setUsesScrollButtons (bool useButtons )

另请参阅 elideMode , QTabBar::usesScrollButtons ，和 QStyle::SH_TabBar_PreferNoArrows .

成员函数文档编制

QTabWidget:: QTabWidget ( QWidget * parent = nullptr)

构造选项卡式 Widget 采用父级 parent .

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

此信号被发射每当当前页面索引改变时。参数是新的当前页面 index 位置或 -1，若没有新的 (例如：若没有 Widget 在 QTabWidget )

注意： 通知程序信号对于特性 currentIndex .

另请参阅 currentWidget () 和 currentIndex .

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

使 widget 当前小部件。 widget 使用的必须是此选项卡小部件的页面。

另请参阅 addTab (), setCurrentIndex ()，和 currentWidget ().

[signal, since 5.2] void QTabWidget:: tabBarClicked ( int index )

此信号会被发射，当用户点击选项卡在 index .

index 引用选项卡点击，或 -1 若光标下没有选项卡。

该函数在 Qt 5.2 引入。

[signal, since 5.2] void QTabWidget:: tabBarDoubleClicked ( int index )

此信号被发射，当用户双击的选项卡在 index .

index 是点击选项卡索引，或 -1 若光标下没有选项卡。

该函数在 Qt 5.2 引入。

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

此信号被发射当点击选项卡关闭按钮时。 index 是应被移除的索引。

另请参阅 setTabsClosable ().

[虚拟] QTabWidget:: ~QTabWidget ()

销毁选项卡式 Widget。

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

添加选项卡采用给定 page and label 到选项卡 Widget，并返回选项卡在选项卡栏中的索引。所有权为 page 被传递给 QTabWidget .

若选项卡的 label 包含 & 和号，紧跟和号后的字母将用作选项卡快捷方式，如：若标签为 Bro&wse，则 Alt+W 将变为快捷方式 (聚焦移至此选项卡)。

注意： 若调用 addTab() 后于 show ()，布局系统将试着调节其小部件层次结构改变，且可能导致闪烁。为防止这种情况，可以设置 QWidget::updatesEnabled 特性为 false 在改变前；记得设置特性为 true 当改变完成后，使小部件再次接收描绘事件。

另请参阅 insertTab ().

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

这是重载函数。

添加选项卡采用给定 page , icon ，和 label 到选项卡 Widget，并返回选项卡在选项卡栏中的索引。所有权为 page 被传递给 QTabWidget .

此函数如同 addTab()，但带有额外 icon .

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

重实现： QWidget::changeEvent (QEvent *event).

void QTabWidget:: clear ()

移除所有页面，但不删除它们。调用此函数相当于调用 removeTab () 直到选项卡 Widget 为空。

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

返回 Widget 展示在 corner 对于选项卡小部件或 nullptr .

另请参阅 setCornerWidget ().

QWidget *QTabWidget:: currentWidget () const

返回由选项卡对话框所显示的目前页面指针。选项卡对话框会尽力确保此值从不为 0 (但若足够努力，可以)。

另请参阅 currentIndex () 和 setCurrentWidget ().

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

重实现： QWidget::event (QEvent *event).

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

重实现： QWidget::hasHeightForWidth () const.

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

重实现： QWidget::heightForWidth (int w) const.

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

返回页面占据的索引位置由 Widget w ，或 -1 若找不到 Widget。

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

初始化 option 采用值来自此 QTabWidget 。此方法对子类是有用的，当需要 QStyleOptionTabWidgetFrame ，但不希望自己填充所有信息。

另请参阅 QStyleOption::initFrom () 和 QTabBar::initStyleOption ().

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

插入选项卡采用给定 label and page 到选项卡小部件在指定 index ，并返回选项卡栏中的插入选项卡索引。所有权对于 page 被传递给 QTabWidget .

标签显示在选项卡中且外观可能有所不同，从属选项卡小部件配置。

若选项卡的 label 包含 & 和号，紧跟和号后的字母将用作选项卡快捷方式，如：若标签为 Bro&wse，则 Alt+W 将变为快捷方式 (聚焦移至此选项卡)。

若 index 超出范围，只需追加选项卡。否则，将其插入在指定位置。

若 QTabWidget 为空在调用此函数之前，新页面变为当前页面。在 <= 当前索引的索引处插入新选项卡将递增当前索引，但保持当前页面。

注意： 若之后调用 insertTab() 在 show ()，布局系统将试着调节其小部件层次结构改变，且可能导致闪烁。为防止这种情况，可以设置 QWidget::updatesEnabled 特性为 false 在改变前；记得设置特性为 true 当改变完成后，使小部件再次接收描绘事件。

另请参阅 addTab ().

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

这是重载函数。

插入选项卡采用给定 label , page ，和 icon 到选项卡小部件在指定 index ，并返回选项卡栏中的插入选项卡索引。所有权对于 page 被传递给 QTabWidget .

此函数如同 insertTab()，但带有额外 icon .

bool QTabWidget:: isTabEnabled ( int index ) const

返回 true 若页面在位置 index 被启用；否则返回 false .

另请参阅 setTabEnabled () 和 QWidget::isEnabled ().

[since 5.15] bool QTabWidget:: isTabVisible ( int index ) const

返回 true 若页面在位置 index 可见；否则返回 false。

该函数在 Qt 5.15 引入。

另请参阅 setTabVisible ().

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

重实现： QWidget::keyPressEvent (QKeyEvent *event).

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

重实现访问函数为特性： QWidget::minimumSizeHint .

返回选项卡 Widget 的适用最小尺寸。

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

重实现： QWidget::paintEvent (QPaintEvent *event).

描绘选项卡 Widget 的选项卡栏为响应描绘 event .

void QTabWidget:: removeTab ( int index )

移除选项卡，在位置 index 从此 Widget 堆栈。页面 Widget 本身未被删除。

另请参阅 addTab () 和 insertTab ().

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

重实现： QWidget::resizeEvent (QResizeEvent *event).

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

设置给定 widget 以展示在指定 corner 对于选项卡小部件。小部件几何体的确定是基于 Widget 的 sizeHint () 和 style ().

仅水平元素的 corner 会被使用。

传递 nullptr 不展示角落 Widget。

任何先前设置的角落 Widget 均被隐藏。

选项卡小部件会删除此处设置的所有 Widget 当销毁它时，除非单独重设小部件父级先于设置一些其它角落小部件 (或 nullptr ).

注意：角落小部件被设计为 North and South 选项卡位置；其它已知取向工作不正确。

另请参阅 cornerWidget () 和 setTabPosition ().

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

替换对话框的 QTabBar 头采用选项卡栏 tb 。注意，这必须被调用 before 任何选项卡被添加，或行为不确定。

另请参阅 tabBar ().

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

若 enable 为 true，页面在位置 index 被启用；否则页面在位置 index 被禁用。页面选项卡被适当重新绘制。

QTabWidget 使用 QWidget::setEnabled () 在内部，而不是保持单独标志。

注意，即使选项卡/页面被禁用也可能可见。若页面已经可见， QTabWidget 不会隐藏它；若所有页面被禁用， QTabWidget 将展示它们之一。

另请参阅 isTabEnabled () 和 QWidget::setEnabled ().

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

设置 icon 为选项卡在位置 index .

另请参阅 tabIcon ().

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

定义新的 label 为页面，在位置 index 的选项卡。

若提供的文本包含 & 和号字符，会为它自动创建快捷方式。紧跟 & 之后的字符将被用作快捷键。任何先前快捷方式会被覆写或清零，若文本尚未定义快捷方式。见 QShortcut 文档编制了解细节 (要显示实际和号，使用 &&)。

另请参阅 tabText ().

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

设置选项卡工具提示为页面，在位置 index to tip .

另请参阅 tabToolTip ().

[since 5.15] void QTabWidget:: setTabVisible ( int index , bool visible )

若 visible 为 true，页面在位置 index 是可见的；否则页面在位置 index 被隐藏。页面选项卡被适当重新绘制。

该函数在 Qt 5.15 引入。

另请参阅 isTabVisible ().

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

设置 What's This 帮助文本为页面，在位置 index to text .

另请参阅 tabWhatsThis ().

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

重实现： QWidget::showEvent (QShowEvent *event).

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

重实现访问函数为特性： QWidget::sizeHint .

QTabBar *QTabWidget:: tabBar () const

返回当前 QTabBar .

另请参阅 setTabBar ().

QIcon QTabWidget:: tabIcon ( int index ) const

返回页面选项卡图标，在位置 index .

另请参阅 setTabIcon ().

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

调用此虚拟处理程序，在添加或插入新选项卡后于位置 index .

另请参阅 tabRemoved ().

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

调用此虚拟处理程序在移除选项卡后从位置 index .

另请参阅 tabInserted ().

QString QTabWidget:: tabText ( int index ) const

返回页面选项卡标签文本在位置 index .

另请参阅 setTabText ().

QString QTabWidget:: tabToolTip ( int index ) const

返回页面选项卡工具提示在位置 index 或空字符串若未设置工具提示。

另请参阅 setTabToolTip ().

QString QTabWidget:: tabWhatsThis ( int index ) const

返回页面 What's This 帮助文本在位置 index ，或空字符串若未设置帮助文本。

另请参阅 setTabWhatsThis ().

QWidget *QTabWidget:: widget ( int index ) const

返回选项卡页面在索引位置 index or nullptr 若 index 超出范围。