QTabWidget 类

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

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

公共类型

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

特性

公共函数

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 )

tabBarAutoHide : bool

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

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

访问函数:

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 .

成员函数文档编制

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

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

[virtual noexcept] 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 ().

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

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

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

另请参阅 currentWidget () 和 currentIndex .

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 ().

bool QTabWidget:: isTabVisible ( int index ) const

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

另请参阅 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 ().

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

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

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

[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 ().

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

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

另请参阅 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 ().

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

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

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

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

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

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

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

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

另请参阅 setTabsClosable ().

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 超出范围。