class QMainWindow#

QMainWindow 类提供了一个主应用程序窗口。更多...

Inheritance diagram of PySide6.QtWidgets.QMainWindow

简介#

属性#

  • animatedᅟ - 是否动画处理档位小部件和工具栏

  • dockNestingEnabledᅟ - 是否可以嵌套档位

  • dockOptionsᅟ - QMainWindow 的停靠行为

  • documentModeᅟ - 是否将选项卡式档位工具栏设置为文档模式

  • iconSizeᅟ - 此主窗口中工具栏图标的大小

  • tabShapeᅟ - 用于选项卡式档位工具栏的选项卡形状

  • toolButtonStyleᅟ - 此主窗口中工具栏按钮的样式

  • unifiedTitleAndToolBarOnMacᅟ - 是否在 macOS 上使用统一的标题栏和工具栏外观

方法#

虚方法#

槽#

信号#

注意

本文档可能包含自动从 C++ 转换到 Python 的代码片段。我们始终欢迎对代码片段的翻译做出贡献。如果您对翻译有问题，也可以通过创建 https:/bugreports.qt.io/projects/PYSIDE 的工单来告知我们

详细描述#

警告

本节包含从 C++ 自动转换为 Python 的代码片段，可能包含错误。

Qt 主窗口框架#

主窗口提供了一个构建应用程序用户界面的框架。Qt 提供了用于主窗口管理的 QMainWindow 及其 相关类。 QMainWindow 有自己的布局，可以在其中添加 QToolBar，QDockWidget，一个 QMenuBar 和一个 QStatusBar。该布局有一个中心区域，可以由任何类型的控件占用。您可以在下面的布局图像中查看。

../../_images/mainwindowlayout.png

创建主窗口组件#

中心部件通常是一个标准 Qt 组件，如一个 QTextEdit 或一个 QGraphicsView . 对于高级应用程序，也可以使用自定义部件。您可以使用 setCentralWidget() 设置中心部件。

主窗口具有单个（SDI）或多重（MDI）文档界面。您在 Qt 中通过使用 QMdiArea 作为中心部件来创建 MDI 应用程序。

我们将现在检查可以添加到主窗口的所有其他部件。我们将给出如何创建和添加它们的示例。

创建菜单#

Qt 使用 QMenu 和 QMainWindow 将它们保存在 QMenuBar 中。QActions 添加到菜单中，它们显示为菜单项。

您可以通过调用 menuBar() 向主窗口的菜单栏添加新菜单，该函数返回窗口的 QMenuBar，然后使用 addMenu() 添加菜单。

QMainWindow 内置默认菜单栏，但您也可以使用 setMenuBar() 设置菜单栏。如果您希望实现自定义菜单栏（即在 notranslate class="xref py py-class"]QMenuBar 组件），可以使用 setMenuWidget() 设置。

以下是如何创建菜单的示例

def createMenus(self):

    fileMenu = menuBar().addMenu(tr("File"))
    fileMenu.addAction(newAct)
    fileMenu.addAction(openAct)
    fileMenu.addAction(saveAct)

createPopupMenu() 函数在主窗口接收到上下文菜单事件时创建弹出菜单。默认实现从浮动窗口部件和工具栏中生成了一个具有可检验操作的菜单。您可以重新实现 createPopupMenu() 以创建自定义菜单。

创建工具栏#

工具栏在 QToolBar 类中实现。您可以使用 addToolBar() 向主窗口添加工具栏。

您可以通过将它们分配给特定的 Qt::ToolBarArea 来控制工具栏的初始位置。您可以通过插入工具栏分隔符来分割一个区域，这可以想象成文本编辑中的行分隔符 - 使用 addToolBarBreak() 或 insertToolBarBreak()。您还可以使用 setAllowedAreas() 和 setMovable() 限制用户的位置。

可以通过 iconSize() 获取工具栏图标的大小。大小受平台依赖；您可以使用 setIconSize() 设置固定大小。您还可以使用 setToolButtonStyle() 改变工具栏中所有工具按钮的外观。

以下是一个创建工具栏的示例

def createToolBars(self):

    fileToolBar = addToolBar(tr("File"))
    fileToolBar.addAction(newAct)

创建浮动窗口组件#

浮动窗口组件在 QDockWidget 类中实现。一个浮动窗口组件是可以附加到主窗口的窗口。您可以使用 addDockWidget() 将浮动窗口组件添加到主窗口。

Qt::DockWidgetArea 枚举定义了四个浮动窗口组件区域：左、右、上和下。您可以使用 setCorner() 指定哪些浮动窗口组件区域应占据区域重叠的角落。默认情况下，每个区域只能包含一排（垂直或水平）的浮动窗口组件，但是如果您启用了嵌套 setDockNestingEnabled()，浮动窗口组件可以沿任意方向添加。

两个浮动窗口组件也可以堆叠在一起。此时将使用 QTabBar 来选择显示哪个小部件。

下面是一个创建并添加浮动窗口组件到主窗口的示例

dockWidget = QDockWidget(tr("Dock Widget"), self)
dockWidget.setAllowedAreas(Qt.LeftDockWidgetArea |
                            Qt.RightDockWidgetArea)
dockWidget.setWidget(dockWidgetContents)
addDockWidget(Qt.LeftDockWidgetArea, dockWidget)

状态栏#

您可以使用 setStatusBa_or 设置状态栏，但第一次调用 statusBar()（返回主窗口的状态栏）时就会创建一个状态栏。有关如何使用的更多信息，请参阅 QStatusBar。

保存状态#

QMainWindow 可以使用 saveState() 保存其布局的状态；它可以在稍后使用 restoreState() 恢复。它保存了工具栏和浮动窗口组件的位置和大小（相对于主窗口的大小）。

class DockOption#

(继承自 enum.Flag) 此枚举包含指定 QMainWindow 的停靠行为的标志。

常量

描述

QMainWindow.AnimatedDocks

等同于 animated 属性。

QMainWindow.AllowNestedDocks

等同于 dockNestingEnabled 属性。

QMainWindow.AllowTabbedDocks

用户可以将一个停靠小部件“放置”在另一个小部件的“顶部”。这两个小部件被堆叠，并出现一个标签栏来选择哪个是可见的。

QMainWindow.ForceTabbedDocks

每个停靠区域包含一个标签停靠小部件的单个堆栈。换句话说，停靠小部件不能在停靠区域内并排放置。如果设置了此选项，则 AllowNestedDocks 无效。

QMainWindow.VerticalTabs

主窗口两侧的两个垂直停靠区域以垂直方式显示其标签。如果没有设置此选项，所有停靠区域都将在底部显示其标签。隐式包含 AllowTabbedDocks。另请参阅 setTabPosition() 。

QMainWindow.GroupedDragging

当拖动停靠窗口的标题栏时，所有与它标签排列的标签也将被拖动。隐式包含 AllowTabbedDocks。如果一些 QDockWidgets 对它们的允许区域有限制，则不起作用。（此枚举值是在 Qt 5.6 中添加的。）

这些选项仅控制停靠小部件在 QMainWindow 中如何停靠。它们不会重新排列停靠小部件以满足指定选项。因此，应在将任何停靠小部件添加到主窗口之前设置。例外情况是 AnimatedDocks 和 VerticalTabs 选项，可以在任何时候设置。

注意

当使用 from __feature__ import true_property 时可以直接使用属性，否则通过访问器函数。

property animatedᅟ: bool#

此属性表示操作停靠小部件和工具栏是否动画。

当工具栏或停靠小部件被拖拽到主窗口上时，主窗口会调整其内容来指示停靠小部件或工具栏将在何处停靠，如果在对应位置释放。设置此属性将导致QMainWindow通过平滑动画移动其内容。清除此属性将使内容自动定位到新位置。

默认情况下，此属性已设置。如果主窗口包含调整大小或重绘速度较慢的小部件，则可能需要清除此属性。

设置此属性等同于使用setDockOptions()方法设置AnimatedDocks选项。

访问函数
属性 dockNestingEnabled : 布尔值#

此属性表示是否可以嵌套停靠。

如果此属性为false，停靠区域只能包含一行（水平或垂直）停靠小部件。如果此属性为true，则停靠小部件占据的区域可以分割，以容纳更多的小部件。

只有在包含大量停靠小部件的应用程序中，才需要停靠嵌套。它使用户能够更自由地组织主窗口。然而，当停靠小部件被拖拽到主窗口上时，由于可以有更多放置放置到停靠区域的方式，停靠嵌套会导致更复杂（且不够直观）的行为。

设置此属性等同于使用setDockOptions()方法设置AllowNestedDocks选项。

访问函数
属性 dockOptions : 组合 QMainWindow.DockOption#

此属性表示QMainWindow的停靠行为。

默认值为AnimatedDocks | AllowTabbedDocks。

访问函数
属性 documentMode : 布尔值#

此属性表示是否将选项卡化停靠小部件的选项卡栏设置为文档模式。

默认值为false。

另请参阅

documentMode

访问函数
属性 iconSize: QSize#

此属性存储此主窗口工具栏图标的尺寸。

默认值是GUI样式的默认工具栏图标尺寸。注意，所使用的图标必须至少为此尺寸，因为图标只能缩小。

访问函数
属性 tabShape: QTabWidget.TabShape#

此属性存储用于标签式停靠小部件的标签形状。

默认值为圆形。

另请参阅

setTabPosition()

访问函数
属性 toolButtonStyle: Qt.ToolButtonStyle#

此属性存储此主窗口工具栏按钮的样式。

要使工具按钮的样式符合系统设置，请将此属性设置为Qt::ToolButtonFollowStyle。在Unix上，将使用桌面环境的用户设置。在其他平台上，Qt::ToolButtonFollowStyle意味着仅图标。

默认值为Qt::ToolButtonIconOnly。

访问函数
属性 unifiedTitleAndToolBarOnMac: bool#

此属性表示窗口是否在macOS上使用统一的标题和工具栏外观。

请注意，与Qt 4相比，Qt 5的实现有一些限制。

  • 不支持在具有OpenGL内容的窗口中使用。这包括QOpenGLWidget。

  • 使用可停靠或可移动的工具栏可能导致绘画错误，不推荐使用。

访问函数
__init__([parent=None[, flags=Qt.WindowFlags()]])#
参数：

使用指定的 parent 和 flags 构造一个 QMainWindow。

QMainWindow会自己设置Qt::Window标志，因此总会作为一个顶层小部件创建。

addDockWidget(area, dockwidget)#
参数：

将指定的浮动工具窗口添加到指定的区域。

addDockWidget(area, dockwidget, orientation)
参数：

将浮动工具窗口添加到给定的区域中，按照方向指定的方向。

addToolBar(toolbar)#
参数：

工具栏 – QToolBar

这是一个重载函数。

相当于调用addToolBar (Qt::TopToolBarArea, toolbar)

addToolBar(area, toolbar)
参数：

将工具栏添加到主窗口中指定的区域。该工具栏被放置在当前工具栏块（即行）的末尾。如果主窗口已经管理了工具栏，则它将只将该工具栏移动到区域。

addToolBar(title)
参数：

标题 – str

返回类型：

QToolBar

这是一个重载函数。

创建一个 QToolBar 对象，将其窗口标题设置为 title，并将其插入到顶部工具栏区域。

另请参阅

setWindowTitle()

addToolBarBreak([area=Qt.TopToolBarArea])#
参数：

区域 – ToolBarArea

在指定的 area 中添加一个工具栏中断，在所有其他对象之后。

centralWidget()#
返回类型：

QWidget

返回主窗口的中心部件。如果中心部件尚未设置，此函数返回 None。

另请参阅

setCentralWidget()

corner(corner)#
参数：

corner – Corner

返回类型：

DockWidgetArea

返回占指定 corner 的停靠部件区域。

另请参阅

setCorner()

createPopupMenu()#
返回类型：

QMenu

返回一个弹出菜单，其中包含对主窗口中存在的工具栏和停靠部件的可选条目。如果没有可用的工具栏和停靠部件，则此函数返回 None。

默认情况下，当用户激活上下文菜单（通常通过在工具栏或停靠部件上右键单击）时，主窗口会调用此函数。

如果您想创建一个自定义弹出菜单，则重新实现此函数并返回一个新创建的弹出菜单。弹出菜单的所有权将转移到调用者。

dockOptions()#
返回类型：

DockOption 的组合

另请参阅

setDockOptions()

属性 dockOptionsᅟ 的获取器。

dockWidgetArea(dockwidget)#
参数：

浮动工具窗口 – QDockWidget

返回类型：

DockWidgetArea

返回 dockwidget 的 Qt::DockWidgetArea。如果 dockwidget 未添加到主窗口中，则此函数返回 Qt::NoDockWidgetArea。

另请参阅

addDockWidget() splitDockWidget() DockWidgetArea

documentMode()#
返回类型：

bool

另请参阅

setDocumentMode()

属性 documentMode 的获取器。

iconSize()#
返回类型：

QSize

另请参阅

setIconSize()

属性 iconSize 的获取器。

iconSizeChanged(iconSize)#
参数：

iconSize – QSize

当窗口中使用的图标尺寸发生更改时发出此信号。新的图标尺寸通过 iconSize 传递。

您可以将此信号连接到其他组件以帮助保持应用程序的一致外观。

另请参阅

setIconSize()

insertToolBar(before, toolbar)#
参数：

将 toolbar 插入由 before 工具栏占据的区域，使其出现在它之前。例如，在正常的从左到右布局操作中，这意味着在水平工具栏区域中，toolbar 将出现在由 before 指定的工具栏的左侧。

insertToolBarBreak(before)#
参数：

before – QToolBar

在由 before 指定的工具栏之前插入一个工具栏断点。

isAnimated()#
返回类型：

bool

属性 animatedᅟ 的获取器。

isDockNestingEnabled()#
返回类型：

bool

属性 dockNestingEnabledᅟ 的获取器。

isSeparator(pos)#
参数：

pos – QPoint

返回类型：

bool

menuBar()#
返回类型：

QMenuBar

警告

本节包含从 C++ 自动转换为 Python 的代码片段，可能包含错误。

返回主窗口的菜单栏。如果菜单栏不存在，此函数将创建并返回一个空的菜单栏。

如果你想要Mac应用程序中的所有窗口共享同一个菜单栏，不要使用此函数来创建它，因为在此创建的菜单栏将以 QMainWindow 作为其父类。相反，你必须创建一个没有父类的菜单栏，然后你可以在所有的Mac窗口中共享它。以下是如何创建一个没有父类的菜单栏：

menuBar = QMenuBar(None)

另请参阅

setMenuBar()

menuWidget()#
返回类型：

QWidget

返回主窗口的菜单栏。如果菜单栏尚未构造，此函数将返回null。

另请参阅

setMenuWidget()

removeDockWidget(dockwidget)#
参数：

浮动工具窗口 – QDockWidget

从主窗口布局中移除并隐藏 dockwidget。请注意，dockwidget 不会 被删除。

removeToolBar(toolbar)#
参数：

工具栏 – QToolBar

从主窗口布局中移除并隐藏 toolbar。请注意，toolbar 不会 被删除。

removeToolBarBreak(before)#
参数：

before – QToolBar

移除在由 before 指定的工具栏之前插入的工具栏中断。

resizeDocks(docks, sizes, orientation)#
参数：

  • 停靠 – QDockWidget 的列表

  • 大小 – 整数列表

  • 方向 – Orientation

警告

本节包含从 C++ 自动转换为 Python 的代码片段，可能包含错误。

将列表 docks 中的停靠小部件大小调整为其在列表 sizes 中对应的大小。如果 orientation 是 Qt::Horizontal，则调整宽度，否则调整停靠小部件的高度。大小将被调整，以确保最大和最小大小得到尊重，并且 QMainWindow 本身不会调整大小。任何额外或缺失的空间将根据大小的相对权重分配给小部件。

示例

resizeDocks({blueWidget, yellowWidget}, {20 , 40}, Qt.Horizontal)

如果蓝色和黄色小部件在相同级别嵌套，它们将被调整大小，使得 yellowWidget 是 blueWidget 的一半大

如果某些小部件在标签中分组，则每个组应指定一个小部件。列表中未包含的小部件可能会根据约束进行更改。

restoreDockWidget(dockwidget)#
参数：

浮动工具窗口 – QDockWidget

返回类型：

bool

如果 dockwidget 在调用 restoreState() 之后被创建，则恢复它的状态。如果状态已恢复，返回 true；否则返回 false。

restoreState(state[, version=0])#
参数：
返回类型：

bool

警告

本节包含从 C++ 自动转换为 Python 的代码片段，可能包含错误。

恢复主窗口工具栏和停靠小部件的 state。还会恢复角落设置。将 version 号码与存储在 state 中的号码进行比较。如果不匹配，则主窗口的状态将保持不变，并且此函数返回 false；否则，状态将得到恢复，并且此函数返回 true。

要恢复使用 QSettings 保存的几何形状，可以使用以下代码

def readSettings(self):

    settings = QSettings("MyCompany", "MyApp")
    restoreGeometry(settings.value("myWidget/geometry").toByteArray())
    restoreState(settings.value("myWidget/windowState").toByteArray())

另请参阅

saveState() saveGeometry() restoreGeometry() restoreDockWidget()

saveState([version=0])#
参数：

版本 – int

返回类型：

QByteArray

警告

本节包含从 C++ 自动转换为 Python 的代码片段，可能包含错误。

保存当前主窗口工具栏和停靠窗口的状态。这包括可以使用 setCorner() 设置的角设置。版本号作为数据的一部分存储。

objectName 属性用于识别每个 QToolBar 和 QDockWidget 。你应该确保每个添加到 QMainWindow 中的 QToolBar 和 QDockWidget 的此属性是唯一的。

要恢复保存的状态，将返回值和 version 号传递给 restoreState() 。

为了在窗口关闭时保存几何形状，您可以实现一个类似这样的关闭事件：

def closeEvent(self, event):

    settings = QSettings("MyCompany", "MyApp")
    settings.setValue("geometry", saveGeometry())
    settings.setValue("windowState", saveState())
    QMainWindow.closeEvent(event)

另请参阅

restoreState() saveGeometry() restoreGeometry()

setAnimated(enabled)#
参数：

enabled – bool

另请参阅

isAnimated()

设置属性 animated 的值。

setCentralWidget(widget)#
参数：

widget – QWidget

将指定的 widget 设置为主窗口的中央控件。

注意：QMainWindow 会在适当的时候接管 widget 指针并删除它。

另请参阅

centralWidget()

setCorner(corner, area)#
参数：

设置给定的停靠小部件 area 以占据指定的 corner。

另请参阅

cornerInMillis()

setDockNestingEnabled(enabled)#
参数：

enabled – bool

另请参阅

isDockNestingEnabled()

属性 dockNestingEnabled 的设置器。

setDockOptions(options)#
参数：

options – DockOption 的组合

另请参阅

dockOptions()

属性 dockOptions 的设置器。

setDocumentMode(enabled)#
参数：

enabled – bool

另请参阅

documentMode()

属性 documentMode 的设置器。

setIconSize(iconSize)#
参数：

iconSize – QSize

另请参阅

iconSize()

属性 iconSize 的设置器。

setMenuBar(menubar)#
参数：

menubar – QMenuBar

将主窗口的菜单栏设置为 menuBar。

注意：QMainWindow 将接管 menuBar 指针并在适当的时候删除它。

另请参阅

menuBar()

setMenuWidget(menubar)#
参数：

menubar – QWidget

将主窗口的菜单栏设置为 menuBar。

QMainWindow 将在适当的时候接管 menuBar 指针并删除它。

另请参阅

menuWidget()

setStatusBar(statusbar)#
参数：

状态栏 – QStatusBar

将主窗口的状态栏设置为 statusbar。

将状态栏设置为 None 将从主窗口中移除它。请注意，QMainWindow 撤走了 statusbar 指针的所有权，并在适当的时候删除它。

另请参阅

statusBar()

setTabPosition(areas, tabPosition)#
参数：

将指定的 areas 框件选项卡位置设置为指定的 tabPosition。默认情况下，所有框架区域在其底部显示其选项卡。

注意

VerticalTabs 框件选项会覆盖此方法设置的选项卡位置。

另请参阅

tabPosition() setTabShape()

setTabShape(tabShape)#
参数：

tabShape – TabShape

另请参阅

tabShape()

属性 tabShapeᅟ 的设置器。

setToolButtonStyle(toolButtonStyle)#
参数：

toolButtonStyle – ToolButtonStyle

另请参阅

toolButtonStyle()

属性 toolButtonStyleᅟ 的设置器。

setUnifiedTitleAndToolBarOnMac(set)#
参数：

set – bool

另请参阅

unifiedTitleAndToolBarOnMac()

属性 unifiedTitleAndToolBarOnMacᅟ 的设置器。

splitDockWidget(after, downdocument, orientation)#
参数：

将第一个停靠部件所覆盖的区域分为两部分，将第一个停靠部件移动到第一部分，将第二个停靠部件移动到第二部分。

orientation指定了空间的划分方式：Qt::Horizontal分割将第二个停靠部件放置在第一个停靠部件的右侧；Qt::Vertical分割将第二个停靠部件放置在第一个停靠部件下方。

注意：如果第一个停靠部件目前位于标签停靠区域内，第二个停靠部件将被添加为新标签，而不是作为第一个停靠部件的邻居。这是因为单个标签只能包含一个停靠部件。

注意：Qt::LayoutDirection会影响分割区域两部分中停靠部件的顺序。当启用了从右到左的布局方向时，停靠部件的放置顺序将会反转。

statusBar()#
返回类型：

QStatusBar

返回主窗口的状态栏。如果状态栏不存在，此函数将创建并返回一个空状态栏。

另请参阅

setStatusBar()

tabPosition(area)#
参数：

区域 – DockWidgetArea

返回类型：

TabPosition

返回区域area的标签位置。

注意

docker选项VerticalTabs会覆盖此函数返回的标签位置。

另请参阅

setTabPosition() tabShape()

tabShape()#
返回类型：

TabShape

另请参阅

setTabShape()

属性tabShape的获取器。

tabifiedDockWidgetActivated(downdocument)#
参数：

停靠小部件 – QDockWidget

当选中对齐的停靠小部件时，此信号被发出。激活的停靠小部件通过 dockWidget 传递。

tabifiedDockWidgets(dockwidget)#
参数：

浮动工具窗口 – QDockWidget

返回类型：

是一个 QDockWidget 列表

返回与 dockwidget 对齐的停靠小部件。

另请参阅

tabifyDockWidget()

tabifyDockWidget(first, second)#
参数：

将 second 停靠小部件移动到 first 停靠小部件的顶部，在主窗口中创建一个带有标签的停靠区域。

另请参阅

tabifiedDockWidgets()

takeCentralWidget()#
返回类型：

QWidget

从主窗口中删除中心小部件。

删除的小部件的所有权传递给调用者。

toolBarArea(toolbar)#
参数：

工具栏 – QToolBar

返回类型：

工具栏区域

返回 toolbar 的 Qt::ToolBarArea。如果 toolbar 尚未添加到主窗口中，则此函数返回 Qt::NoToolBarArea。

另请参阅

addToolBar() addToolBarBreak() ToolBarArea

toolBarBreak(toolbar)
参数：

工具栏 – QToolBar

返回类型：

bool

返回在 toolbar 之前是否有一个工具栏中断。

toolButtonStyle()#
返回类型：

ToolButtonStyle

另请参阅

setToolButtonStyle()

属性 toolButtonStyle 的获取器。

toolButtonStyleChanged(toolButtonStyle)#
参数：

toolButtonStyle – ToolButtonStyle

当窗口中工具按钮使用的设计风格变化时，会发射此信号。新的风格通过 toolButtonStyle 传递。

您可以将此信号连接到其他组件以帮助保持应用程序的一致外观。

另请参阅

setToolButtonStyle()

unifiedTitleAndToolBarOnMac()#
返回类型：

bool

另请参阅

setUnifiedTitleAndToolBarOnMac()

属性 unifiedTitleAndToolBarOnMac 的获取器。