PySide6.QtWidgets.QMainWindow

class QMainWindow

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

PySide6.QtWidgets.QMainWindow 的继承图

概要

属性

方法

虚拟方法

插槽

信号

注意

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

详细描述

警告

本节包含从C++自动翻译到Python的代码片段,可能包含错误。

Qt 主窗口框架

主窗口为构建应用程序的用户界面提供了一个框架。Qt 提供了 QMainWindow 及其 相关类 用于主窗口管理。QMainWindow 有自己的布局,您可以向其中添加 QToolBarQDockWidgetQMenuBarQStatusBar。该布局有一个中心区域,可以被任何类型的小部件占据。您可以在下面看到布局的图像。

../../_images/mainwindowlayout.png

创建主窗口组件

中心部件通常是一个标准的Qt部件,例如QTextEditQGraphicsView。自定义部件也可以用于高级应用程序。您可以使用setCentralWidget()来设置中心部件。

主窗口可以具有单文档界面(SDI)或多文档界面(MDI)。在Qt中,您可以通过使用QMdiArea作为中心小部件来创建MDI应用程序。

我们现在将检查可以添加到主窗口的其他小部件。我们提供了如何创建和添加它们的示例。

创建菜单

Qt 在 QMenu 中实现了菜单,而 QMainWindow 将它们保存在 QMenuBar 中。QActions 被添加到菜单中,菜单将它们显示为菜单项。

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

QMainWindow 自带一个默认的菜单栏,但你也可以使用 setMenuBar() 自己设置一个。如果你想实现一个自定义的菜单栏(即不使用 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)

创建Dock小部件

Dock小部件在QDockWidget类中实现。Dock小部件是一个可以停靠到主窗口的窗口。您可以使用addDockWidget()将Dock小部件添加到主窗口中。

有四个停靠部件区域,由Qt::DockWidgetArea枚举给出:左、右、上、下。您可以使用setCorner()指定哪个停靠部件区域应占据区域重叠的角落。默认情况下,每个区域只能包含一行(垂直或水平)的停靠部件,但如果您使用setDockNestingEnabled()启用嵌套,则可以在任一方向上添加停靠部件。

两个停靠窗口部件也可以堆叠在一起。然后使用QTabBar来选择应该显示哪个窗口部件。

我们给出一个如何创建并将停靠部件添加到主窗口的示例:

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

状态栏

你可以使用setStatusBar()设置一个状态栏,但在第一次调用statusBar()(返回主窗口的状态栏)时会创建一个。有关如何使用它的信息,请参见QStatusBar

存储状态

QMainWindow 可以使用 saveState() 存储其布局的状态;稍后可以使用 restoreState() 恢复该状态。存储的是工具栏和停靠小部件的位置和大小(相对于主窗口的大小)。

另请参阅

QMenuBar QToolBar QStatusBar QDockWidget 菜单示例

class DockOption

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

常量

描述

QMainWindow.AnimatedDocks

animated属性相同。

QMainWindow.AllowNestedDocks

dockNestingEnabled属性相同。

QMainWindow.AllowTabbedDocks

用户可以将一个停靠小部件“放在”另一个小部件的顶部。两个小部件会堆叠在一起,并出现一个标签栏用于选择哪个小部件可见。

QMainWindow.ForceTabbedDocks

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

QMainWindow.VerticalTabs

主窗口两侧的两个垂直停靠区域垂直显示其标签。如果未设置此选项,所有停靠区域将在底部显示其标签。隐含AllowTabbedDocks。另请参见setTabPosition()

QMainWindow.GroupedDragging

当拖动停靠窗口的标题栏时,所有与其标签化的标签页都将被拖动。隐含允许标签化停靠。如果某些QDockWidgets在允许的区域上有限制,则效果不佳。(此枚举值在Qt 5.6中添加。)

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

注意

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

property animatedᅟ: bool

此属性控制是否对操作停靠窗口部件和工具栏进行动画处理。

当停靠窗口部件或工具栏在主窗口上拖动时,主窗口会调整其内容以指示如果放下停靠窗口部件或工具栏,它将被停靠的位置。设置此属性会导致QMainWindow以平滑的动画移动其内容。清除此属性会导致内容立即跳转到新位置。

默认情况下,此属性已设置。如果主窗口包含在调整大小或重新绘制自身时较慢的小部件,则可以清除此属性。

设置此属性与使用setDockOptions()设置AnimatedDocks选项相同。

Access functions:
property dockNestingEnabledᅟ: bool

此属性控制是否可以嵌套停靠窗口。

如果此属性为false,则停靠区域只能包含单行(水平或垂直)的停靠小部件。如果此属性为true,则停靠小部件占用的区域可以在任一方向上分割以包含更多的停靠小部件。

Dock嵌套仅在包含大量dock小部件的应用程序中是必要的。它为用户在组织主窗口时提供了更大的自由度。然而,当dock小部件在主窗口上拖动时,dock嵌套会导致更复杂(且不太直观)的行为,因为被放置的dock小部件在dock区域中有更多的放置方式。

设置此属性与使用setDockOptions()设置AllowNestedDocks选项相同。

Access functions:
property dockOptionsᅟ: Combination of QMainWindow.DockOption

此属性控制QMainWindow的停靠行为。

默认值为 AnimatedDocks | AllowTabbedDocks

Access functions:
property documentModeᅟ: bool

此属性保存选项卡式停靠小部件的选项卡栏是否设置为文档模式。

默认值为 false。

另请参阅

documentMode

Access functions:
property iconSizeᅟ: QSize

此属性保存此主窗口中工具栏图标的大小。

默认值是GUI样式的默认工具栏图标大小。请注意,使用的图标必须至少为此大小,因为图标只会缩小。

Access functions:
property tabShapeᅟ: QTabWidget.TabShape

此属性用于选项卡式停靠小部件的选项卡形状。

默认是Rounded

另请参阅

setTabPosition()

Access functions:
property toolButtonStyleᅟ: Qt.ToolButtonStyle

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

要使工具按钮的样式遵循系统设置,请将此属性设置为Qt::ToolButtonFollowStyle。在Unix上,将使用桌面环境的用户设置。在其他平台上,Qt::ToolButtonFollowStyle表示仅显示图标。

默认是Qt::ToolButtonIconOnly。

Access functions:
property unifiedTitleAndToolBarOnMacᅟ: bool

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

请注意,与Qt 4相比,Qt 5的实现有几个限制:

  • 不支持在带有OpenGL内容的Windows中使用。这包括QOpenGLWidget。

  • 使用可停靠或可移动的工具栏可能会导致绘制错误,因此不推荐使用

Access functions:
__init__([parent=None[, flags=Qt.WindowFlags()]])
Parameters:

使用给定的parent和指定的窗口部件flags构造一个QMainWindow

QMainWindow 自己设置了 Qt::Window 标志,因此将始终作为顶级小部件创建。

addDockWidget(area, dockwidget)
Parameters:

将给定的 dockwidget 添加到指定的 area

addDockWidget(area, dockwidget, orientation)
Parameters:

dockwidget添加到指定的area中,方向由orientation指定。

addToolBar(toolbar)
Parameters:

工具栏QToolBar

这是一个重载函数。

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

addToolBar(title)
Parameters:

标题 – str

Return type:

QToolBar

这是一个重载函数。

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

另请参阅

setWindowTitle()

addToolBar(area, toolbar)
Parameters:

toolbar添加到此主窗口的指定area中。toolbar被放置在当前工具栏块(即行)的末尾。如果主窗口已经管理toolbar,则只会将工具栏移动到area

addToolBarBreak([area=Qt.TopToolBarArea])
Parameters:

区域ToolBarArea

在所有其他存在的对象之后,向给定的area添加一个工具栏分隔符。

centralWidget()
Return type:

QWidget

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

另请参阅

setCentralWidget()

corner(corner)
Parameters:

角落Corner

Return type:

DockWidgetArea

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

另请参阅

setCorner()

createPopupMenu()
Return type:

QMenu

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

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

如果你想创建一个自定义的弹出菜单,重新实现这个函数并返回一个新创建的弹出菜单。弹出菜单的所有权将转移给调用者。

dockOptions()
Return type:

DockOption的组合

另请参阅

setDockOptions()

属性 dockOptionsᅟ 的获取器。

dockWidgetArea(dockwidget)
Parameters:

dockwidgetQDockWidget

Return type:

DockWidgetArea

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

另请参阅

addDockWidget() splitDockWidget() DockWidgetArea

documentMode()
Return type:

布尔

另请参阅

setDocumentMode()

属性 documentModeᅟ 的获取器。

iconSize()
Return type:

QSize

另请参阅

setIconSize()

属性 iconSizeᅟ 的获取器。

iconSizeChanged(iconSize)
Parameters:

iconSizeQSize

当窗口中使用的图标大小发生变化时,会发出此信号。新的图标大小通过iconSize传递。

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

另请参阅

setIconSize()

insertToolBar(before, toolbar)
Parameters:

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

insertToolBarBreak(before)
Parameters:

之前QToolBar

在由before指定的工具栏之前插入一个工具栏分隔符。

isAnimated()
Return type:

布尔

属性 animatedᅟ 的获取器。

isDockNestingEnabled()
Return type:

布尔

属性 dockNestingEnabledᅟ 的获取器。

isSeparator(pos)
Parameters:

posQPoint

Return type:

布尔

menuBar()
Return type:

QMenuBar

警告

本节包含从C++自动翻译到Python的代码片段,可能包含错误。

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

如果你想让Mac应用程序中的所有窗口共享一个菜单栏,不要使用这个函数来创建它,因为这里创建的菜单栏会将QMainWindow作为其父对象。相反,你必须创建一个没有父对象的菜单栏,然后你可以在所有Mac窗口之间共享它。通过以下方式创建一个没有父对象的菜单栏:

menuBar = QMenuBar(None)

另请参阅

setMenuBar()

menuWidget()
Return type:

QWidget

返回主窗口的菜单栏。如果尚未构建菜单栏,此函数返回 null。

另请参阅

setMenuWidget()

removeDockWidget(dockwidget)
Parameters:

dockwidgetQDockWidget

从主窗口布局中移除dockwidget并隐藏它。请注意,dockwidget没有被删除。

removeToolBar(toolbar)
Parameters:

工具栏QToolBar

从主窗口布局中移除toolbar并隐藏它。请注意,toolbar没有被删除。

removeToolBarBreak(before)
Parameters:

之前QToolBar

移除先前在由before指定的工具栏之前插入的工具栏分隔符。

resizeDocks(docks, sizes, orientation)
Parameters:
  • docks – QDockWidget 的列表

  • sizes – .整数列表

  • orientationOrientation

警告

本节包含从C++自动翻译到Python的代码片段,可能包含错误。

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

示例:

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

如果蓝色和黄色的小部件嵌套在同一层级,它们将被调整大小,使得黄色小部件的大小是蓝色小部件的两倍

如果一些小部件被分组在标签中,每组只应指定一个小部件。不在列表中的小部件可能会被更改以遵守约束条件。

restoreDockWidget(dockwidget)
Parameters:

dockwidgetQDockWidget

Return type:

布尔

如果在调用restoreState()之后创建了dockwidget,则恢复其状态。如果状态已恢复,则返回true;否则返回false

restoreState(state[, version=0])
Parameters:
Return type:

布尔

警告

本节包含从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([version=0])
Parameters:

版本 – int

Return type:

QByteArray

警告

本节包含从C++自动翻译到Python的代码片段,可能包含错误。

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

objectName属性用于标识每个QToolBarQDockWidget。你应该确保这个属性对于你添加到QMainWindow中的每个QToolBarQDockWidget都是唯一的。

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

要在窗口关闭时保存几何形状,您可以像这样实现一个关闭事件:

def closeEvent(self, event):

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

enabled – 布尔值

另请参阅

isAnimated()

属性 animatedᅟ 的设置器。

setCentralWidget(widget)
Parameters:

widgetQWidget

将给定的 widget 设置为主窗口的中央部件。

注意:QMainWindow 拥有 widget 指针的所有权,并在适当的时候删除它。

另请参阅

centralWidget()

setCorner(corner, area)
Parameters:

将给定的停靠小部件 area 设置为占据指定的 corner

另请参阅

corner()

setDockNestingEnabled(enabled)
Parameters:

enabled – 布尔值

另请参阅

isDockNestingEnabled()

属性 dockNestingEnabledᅟ 的设置器。

setDockOptions(options)
Parameters:

optionsDockOption 的组合

另请参阅

dockOptions()

属性 dockOptionsᅟ 的设置器。

setDocumentMode(enabled)
Parameters:

enabled – 布尔值

另请参阅

documentMode()

属性 documentModeᅟ 的设置器。

setIconSize(iconSize)
Parameters:

iconSizeQSize

另请参阅

iconSize()

属性 iconSizeᅟ 的设置器。

setMenuBar(menubar)
Parameters:

菜单栏QMenuBar

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

注意:QMainWindow 拥有 menuBar 指针的所有权,并在适当的时候删除它。

另请参阅

menuBar()

setMenuWidget(menubar)
Parameters:

菜单栏QWidget

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

QMainWindow 拥有 menuBar 指针的所有权,并在适当的时候删除它。

另请参阅

menuWidget()

setStatusBar(statusbar)
Parameters:

状态栏QStatusBar

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

将状态栏设置为None会将其从主窗口中移除。请注意,QMainWindow会接管statusbar指针的所有权,并在适当的时候删除它。

另请参阅

statusBar()

setTabPosition(areas, tabPosition)
Parameters:

为给定的停靠小部件 areas 设置标签位置为指定的 tabPosition。默认情况下,所有停靠区域的标签显示在底部。

注意

VerticalTabs 停靠选项会覆盖此方法设置的标签位置。

setTabShape(tabShape)
Parameters:

tabShapeTabShape

另请参阅

tabShape()

属性 tabShapeᅟ 的设置器。

setToolButtonStyle(toolButtonStyle)
Parameters:

toolButtonStyleToolButtonStyle

另请参阅

toolButtonStyle()

属性 toolButtonStyleᅟ 的设置器。

setUnifiedTitleAndToolBarOnMac(set)
Parameters:

set – 布尔值

属性 unifiedTitleAndToolBarOnMacᅟ 的设置器。

splitDockWidget(after, dockwidget, orientation)
Parameters:

first停靠小部件覆盖的空间分成两部分,将first停靠小部件移动到第一部分,并将second停靠小部件移动到第二部分。

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

注意: 如果 first 当前位于一个标签页停靠区域中,second 将作为一个新标签页添加,而不是作为 first 的邻居。这是因为一个标签页只能包含一个停靠小部件。

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

statusBar()
Return type:

QStatusBar

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

另请参阅

setStatusBar()

tabPosition(area)
Parameters:

区域DockWidgetArea

Return type:

TabPosition

返回area的标签位置。

注意

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

tabShape()
Return type:

TabShape

另请参阅

setTabShape()

属性 tabShapeᅟ 的获取器。

tabifiedDockWidgetActivated(dockWidget)
Parameters:

dockWidgetQDockWidget

当通过选择选项卡激活选项卡化的停靠小部件时,会发出此信号。激活的停靠小部件在dockWidget中传递。

tabifiedDockWidgets(dockwidget)
Parameters:

dockwidgetQDockWidget

Return type:

QDockWidget的列表

返回与dockwidget一起标签化的停靠小部件。

另请参阅

tabifyDockWidget()

tabifyDockWidget(first, second)
Parameters:

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

另请参阅

tabifiedDockWidgets()

takeCentralWidget()
Return type:

QWidget

从此主窗口中移除中央小部件。

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

toolBarArea(toolbar)
Parameters:

工具栏QToolBar

Return type:

ToolBarArea

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

另请参阅

addToolBar() addToolBarBreak() ToolBarArea

toolBarBreak(toolbar)
Parameters:

工具栏QToolBar

Return type:

布尔

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

toolButtonStyle()
Return type:

ToolButtonStyle

另请参阅

setToolButtonStyle()

属性 toolButtonStyleᅟ 的获取器。

toolButtonStyleChanged(toolButtonStyle)
Parameters:

toolButtonStyleToolButtonStyle

当窗口中用于工具按钮的样式更改时,会发出此信号。新样式在toolButtonStyle中传递。

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

另请参阅

setToolButtonStyle()

unifiedTitleAndToolBarOnMac()
Return type:

布尔

属性 unifiedTitleAndToolBarOnMacᅟ 的获取器。