class QGuiApplication#

QGuiApplication 类管理 GUI 应用程序的控制流和主要设置。 更多信息...

Inheritance diagram of PySide6.QtGui.QGuiApplication

继承自： QApplication

概要#

属性#

方法#

信号#

静态函数#

注：

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

详细描述#

QGuiApplication 包含主要的事件循环，其中处理并分发来自窗口系统和其他来源的所有事件。它还处理应用程序的初始化和终止，并提供会话管理。此外，QGuiApplication 处理系统中大多数和应用程序范围内的设置。

对于任何使用Qt的GUI应用程序，无论在任何给定时间是否有0，1，2个或更多窗口，“QGuiApplication”对象都只有一个。对于非GUI的Qt应用程序，请使用QCoreApplication，因为它不依赖于Qt GUI模块。对于基于QWidget的Qt应用程序，请使用QApplication，因为它提供创建QWidget实例所需的一些功能。

可以通过instance()函数访问QGuiApplication对象，该函数返回与全局qApp指针等效的指针。

QGuiApplication 主要职责包括：

  • 它使用用户的桌面设置初始化应用程序，例如palette()、font()和styleHints()。它跟踪这些属性，以防用户通过控制面板等 globally 改变这些设置。

  • 它进行事件处理，这意味着它从底层窗口系统接收事件并将它们分发给相关的小部件。您可以通过sendEvent()和postEvent()发送自己的事件到窗口。

  • 它解析常见的命令行参数，并相应地设置其内部状态。有关更多详细信息，请参阅下面的构造函数文档。

  • 它提供通过translate()可见给用户的字符串的本地化。

  • 它提供一些神奇的对象，如clipboard()。

  • 它了解应用程序的窗口。您可以使用topLevelAt() 询问特定位置的窗口，获取topLevelWindows() 的列表等。

  • 它管理应用程序光标的处理，请参见setOverrideCursor()。

  • 它支持复杂的会话管理。这使得应用程序在用户注销时能够优雅地终止，在无法终止时取消关闭进程，甚至可以保存整个应用程序的状态以供未来的会话使用。有关详细信息，请参阅 isSessionRestored() ， sessionId() 和 commitDataRequest() 以及 saveStateRequest()。

由于 QGuiApplication 对象进行了许多初始化，因此它 必须 在创建任何与用户界面相关的其他对象之前创建。 QGuiApplication 还处理常见的命令行参数。因此，在应用程序自身中对 argv 进行任何解释或修改之前创建它通常是一个好主意。

函数组

系统设置

desktopSettingsAware()，setDesktopSettingsAware()，styleHints()，palette()，setPalette()，font()，setFont()。

事件处理

exec()，processEvents()，exit()，quit()，sendEvent()，postEvent()，sendPostedEvents()，removePostedEvents()，notify()。

窗口

allWindows()，topLevelWindows()，focusWindow()，clipboard()，topLevelAt()。

高级光标处理

overrideCursor()，setOverrideCursor()，restoreOverrideCursor()。

会话管理

isSessionRestored()，sessionId()，commitDataRequest()，saveStateRequest()。

杂项

startingUp()，closingDown()。

另请参阅

QCoreApplicationQAbstractEventDispatcherQEventLoop

注：

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

property applicationDisplayName: str#

此属性包含此应用程序的用户可见名称。

此名称会显示给用户，例如在窗口标题中。如果需要，可以进行翻译。

如果没有设置，应用程序显示名称将默认为应用程序名称。

另请参阅

applicationName

访问函数
property desktopFileName: str#

此属性包含此应用程序的桌面条目的基本名称。

这是代表此应用程序的桌面条目的文件名，不包括完整路径或尾随的“.desktop”扩展名。根据 freedesktop 桌面条目规范。

此属性提供了精确的指示，表示哪个桌面条目代表应用程序，并且它被窗口系统用来检索此类信息，而无需求助于不精确的启发式方法。

可以在此处获得 freedesktop 桌面条目规范的最新版本here。

访问函数
property layoutDirection: Qt.LayoutDirection#

此属性包含此应用程序的默认布局方向。

在系统启动时，或者当方向被显式设置为 Qt::LayoutDirectionAuto 时，默认布局方向取决于应用程序的语言。

通知器信号是在 Qt 5.4 中引入的。

访问函数
属性 platformName: str#

此属性保存了底层平台插件的名称。

QPA平台插件位于qtbase\src\plugins\platforms。截至编写本文档时，支持以下平台插件名称：

  • android

  • cocoa是为macOS设计的平台插件。

  • directfb

  • eglfs是一个平台插件，可在没有实际窗口系统（例如X11或Wayland）的情况下运行Qt5应用程序（EGL和OpenGL ES 2.0）。有关更多信息，请参阅EGLFS。

  • ios（也用于tvOS）

  • linuxfb直接写入framebuffer。有关更多信息，请参阅LinuxFB。

  • minimal为希望编写自己的平台插件的开发者提供了示例。然而，您可以在此环境下使用插件运行GUI应用程序，如服务器等无GUI环境。

  • minimalegl是一个示例插件。

  • offscreen

  • qnx

  • windows

  • wayland是Wayland显示服务器协议的平台插件，用于某些Linux桌面和嵌入式系统。

  • xcb是用于X11窗口系统的插件，用于某些桌面Linux平台。

注：

如果未提供QGuiApplication，将调用此函数并返回默认平台名称（如果可用）。默认平台名称不受-platform命令行选项或QT_QPA_PLATFORM环境变量的影响。

有关嵌入式Linux设备的平台插件更多信息，请参阅Qt for Embedded Linux。

访问函数
属性 primaryScreen: QScreen#

此属性保存应用程序的主（或默认）屏幕。

除非明确指定，否则这将是QWindows最初显示的屏幕。

primaryScreenChanged信号是在Qt 5.6中引入的。

另请参阅

screens()

访问函数
属性 quitOnLastWindowClosed: bool#

此属性保存在最后一个窗口关闭时应用程序是否隐式退出。

默认设置为true。

如果此属性为true，则当最后一个可见的主窗口（即无瞬时父窗口的最高级窗口）关闭时，应用程序将退出。

另请参阅

close()

访问函数
属性windowIcon: QIcon#

此属性包含默认窗口图标。

另请参阅

setIcon 设置应用程序图标

访问函数
__init__(arg__1)#
参数：

arg__1 - 字符串列表

__init__()
静态allWindows()#
返回类型：

列表

返回应用中所有窗口的列表。

如果没有窗口，列表为空。

另请参阅

topLevelWindows

静态applicationDisplayName()#
返回类型：

str

另请参阅

setApplicationDisplayName()

获取 applicationDisplayName 属性的值。

applicationDisplayNameChanged()#

属性 applicationDisplayName 的通知信号。

静态applicationState()#
返回类型：

ApplicationState

返回应用程序的当前状态。

你可以对应用程序状态的改变做出反应，执行例如停止/恢复CPU密集型任务、释放/加载资源或保存/恢复应用程序数据等操作。

applicationStateChanged(state)#
参数：

state - ApplicationState

当应用程序的 state 发生改变时，将发出此信号。

另请参阅

applicationState

静态changeOverrideCursor(arg__1)#
参数：

arg__1 - QCursor

static clipboard()#
返回类型：

QClipboard

commitDataRequest(sessionManager)#
参数：

sessionManager – QSessionManager

此信号处理会话管理。当QSessionManager要求应用程序提交所有数据时，会发出。

通常这意味着在用户同意后保存所有打开的文件。此外，您可能还希望提供一种让用户能够取消关机的方式。

在此信号中，您不应该退出应用程序。相反，会话管理器可能在之后执行此操作，具体取决于上下文。

警告

在此信号中，除非您请求manager明确许可，否则无法进行用户交互。有关详细信息和使用示例，请参见allowsInteraction()和allowsErrorInteraction()。

注：

连接到此信号时，您应使用Qt::DirectConnection。

另请参阅

isSessionRestored() sessionId() saveStateRequest() 会话管理

static desktopFileName()#
返回类型：

str

另请参阅

setDesktopFileName()

属性desktopFileNameᅟ的获取器。

static desktopSettingsAware()#
返回类型：

bool

devicePixelRatio()#
返回类型：

float

返回系统上找到的最高屏幕设备像素比。这是物理像素和设备无关像素之间的比率。

当您不知道要针对哪个窗口时，请使用此函数。如果知道目标窗口，请使用devicePixelRatio()代替。

另请参阅

devicePixelRatio()

exec_()#
返回类型：

int

static focusObject()#
返回类型：

QObject

返回当前活动窗口中将在与焦点相关的事件（如按键事件）的最终接收者。

focusObjectChanged(focusObject)#
参数：

focusObject – QObject

当与焦点相关事件的最终接收者改变时，会触发此信号。focusObject 是新的接收者。

另请参阅

focusObject()

static focusWindow()#
返回类型：

QWindow

返回接收与焦点相关事件（如按键事件）的 QWindow。

另请参阅

requestActivate()

focusWindowChanged(focusWindow)#
参数：

focusWindow – QWindow

当焦点窗口改变时，会触发此信号。focusWindow 是新的焦点窗口。

另请参阅

focusWindow()

static font()#
返回类型：

QFont

fontChanged(font)#
参数：

font – QFont

注：

此函数已弃用。

处理 QEvent::ApplicationFontChange。

当应用程序的 font 改变时，会触发此信号。请使用 QEvent::ApplicationFontChanged。

另请参阅

font()

fontDatabaseChanged()#

当可用的字体发生改变时，会触发此信号。

这可能发生在应用程序字体被添加或删除，或者系统字体发生变化时。

静态

static highDpiScaleFactorRoundingPolicy()#
返回类型：

高DPI缩放因子舍入策略

static inputMethod()#
返回类型：

QInputMethod

static isLeftToRight()#
返回类型：

bool

如果应用程序的布局方向是 Qt::LeftToRight，则返回 true；否则返回 false。

static isRightToLeft()#
返回类型：

bool

如果应用程序的布局方向是 Qt::RightToLeft，则返回 true；否则返回 false。

isSavingSession()#
返回类型：

bool

如果应用程序正在保存会话，则返回 true；否则返回 false。

当 commitDataRequest() 和 saveStateRequest() 被触发时，这是 true，也当窗口通过会话管理关闭之后。

isSessionRestored()#
返回类型：

bool

如果应用程序已从早期会话恢复，则返回 true；否则返回 false。

静态 keyboardModifiers()#
返回类型：

PySide6.QtCore.Qt.KeyboardModifier的组合

返回键盘上修饰键的当前状态。当前状态会在事件队列中移除事件（这些事件会自发改变键盘状态，如QEvent::KeyPress和QEvent::KeyRelease事件）时同步更新。

需要注意的是，这不一定反映调用时输入设备上实际按下的键，而是反映在上述事件中最后报告的修饰键。如果没有键被按下，将返回Qt::NoModifier。

lastWindowClosed()#

当最后一个可见的主要窗口（即没有暂时父窗口的最高级窗口）关闭时，此信号从exec()发出。

默认情况下，当此信号发出后，PySide6.QtGui.QGuiApplication会退出。可以通过将quitOnLastWindowClosed设置为false来关闭此功能。

静态 layoutDirection()#
返回类型：

布局方向

另请参阅

setLayoutDirection()

layoutDirection属性的getter。

layoutDirectionChanged(direction)#
参数：

direction – PySide6.QtCore.Qt.LayoutDirection

layoutDirection属性的属性通知信号。

静态 modalWindow()#
返回类型：

QWindow

返回最近显示的模态窗口。如果没有可见的模态窗口，此函数返回零。

模态窗口是一种其 属性 设置为 Qt::WindowModal 或 Qt::ApplicationModal 的窗口。在使用程序的其他部分之前，必须先关闭模态窗口。

模态窗口组织在一个堆栈中。此函数返回堆栈顶部的模态窗口。

另请参阅

setModality()

静态 mouseButtons()#
返回类型：

鼠标按钮组合 MouseButton

返回鼠标按钮的当前状态。当前状态在事件队列清空时同步更新，此时将删除会自发改变鼠标状态的事件（QEvent::MouseButtonPress 和 QEvent::MouseButtonRelease 事件）。

需要注意的是，这可能不会反映调用时输入设备上实际按下的按钮，而是反映上述事件中最后报告的鼠标按钮。如果没有鼠标按钮被按下，则返回 Qt::NoButton。

另请参阅

keyboardModifiers()

nativeInterface()#
返回类型：

对象

静态 overrideCursor()#
返回类型：

QCursor

返回活动应用程序覆盖的光标。

如果未定义应用程序光标（即内部光标堆栈为空），则此函数返回 None。

静态 palette()#
返回类型：

QPalette

paletteChanged(pal)#
参数：

pal – QPalette

注：

此函数已弃用。

处理 QEvent::ApplicationPaletteChange。

当应用程序的 palette 发生变化时发出此信号。使用 QEvent::ApplicationPaletteChanged 代替。

另请参阅

palette()

静态 platformFunction(function)#
参数：

function – QByteArray

返回类型：

QFunctionPointer

静态 platformName()#
返回类型：

str

属性 platformNameᅟ 的获取器。

静态primaryScreen()#
返回类型：

QScreen

属性 primaryScreenᅟ 的获取器。

primaryScreenChanged(screen)#
参数：

screen - QScreen

属性 primaryScreenᅟ 的通知信号。

静态queryKeyboardModifiers()#
返回类型：

PySide6.QtCore.Qt.KeyboardModifier的组合

询问并返回键盘修饰键的状态。与 keyboardModifiers 不同，此方法返回在调用该方法时输入设备上实际按下的键。

它不依赖于是否有按键事件被此进程接收，这使得有可能在移动窗口时检查修饰符等。请注意，在大多数情况下，您应使用 keyboardModifiers() ，因为它更快更准确，因为它包含修饰的状态，就像当前处理的事件被接收时的状态一样。

另请参阅

keyboardModifiers()

静态quitOnLastWindowClosed()#
返回类型：

bool

另请参阅

setQuitOnLastWindowClosed

属性 quitOnLastWindowClosedᅟ 的获取器。

静态restoreOverrideCursor()#

撤销上一次 setOverrideCursor() 的操作。

如果 setOverrideCursor() 调用了两次，调用 restoreOverrideCursor() 将激活第一个设置的光标。再次调用此函数将恢复原始小部件的光标。

saveStateRequest(sessionManager)#
参数：

sessionManager – QSessionManager

该信号用于处理会话管理。当会话管理器希望应用程序保留其状态以供未来的会话使用时，会被调用。

例如，一个文本编辑器会创建一个临时文件，其中包含其编辑缓冲区的当前内容、光标位置以及当前编辑会话的其他方面。

在这个信号中，永远不应该退出应用程序。相反，会话管理器可能之后会执行此操作，具体取决于上下文。此外，大多数会话管理器很可能在应用程序启动后立即请求保存状态。这允许会话管理器了解应用程序的重启策略。

警告

在这个信号中，除非你请求管理器明确允许，否则将无法进行用户交互。有关详细信息，请参阅allowsInteraction()和allowsErrorInteraction()。

注：

连接到此信号时，您应使用Qt::DirectConnection。

另请参阅

isSessionRestored() sessionId() commitDataRequest() 会话管理

screenAdded(screen)#
参数：

screen - QScreen

当系统添加了新的屏幕screen时，会发射此信号。

static screenAt(point)#
参数：

point – QPoint

返回类型：

QScreen

返回位于point的屏幕，如果在该屏幕之外，则返回None。

该 point 与每组虚拟兄弟姐妹的 virtualGeometry() 有关。如果点映射到多个虚拟兄弟姐妹集，则返回第一个匹配项。如果您只想搜索已知屏幕（例如，您的应用程序窗口的屏幕的兄弟姐妹 QWidget::windowHandle()->screen()）的虚拟桌面兄弟姐妹，请使用 virtualSiblingAt()。

screenRemoved(screen)#
参数：

screen - QScreen

每当从系统中移除一个 screen 时，都会发出此信号。这提供了一个在 Qt 将窗口移动到主屏幕之前管理屏幕上的窗口的机会。

static screens()#
返回类型：

QScreen 对象列表

返回与应用程序连接的窗口系统相关联的所有屏幕的列表。

sessionId()#
返回类型：

str

返回当前会话的标识符。

如果应用程序从早期会话中恢复，则此标识符与该先前会话中的标识符相同。会话标识符在应用于不同应用程序以及同种应用程序的不同实例时均有保证是唯一的。

sessionKey()#
返回类型：

str

返回当前会话中的会话密钥。

如果应用程序从早期会话中恢复，则此密钥与先前会话结束时相同。

每次会话保存时，会话密钥都会更改。如果关闭程序时取消操作，再次关闭时将使用另一个会话密钥。

static setApplicationDisplayName(name)#
参数：

name – 字符串

另请参阅

applicationDisplayName()

设置属性 applicationDisplayName 的值。

setBadgeNumber(number)#
参数：

number – 整数

设置应用程序徽章为 number。

可用于向用户提供关于未读消息数量等信息的反馈。

徽章将叠加在 macOS 的 Dock 中应用程序的图标、iOS 主屏幕的图标或在 Windows 和 Linux 的任务栏上。

如果数字超出平台支持的范围，则数字将被夹到支持的范围。如果数字不适合徽章，则数字可能会在视觉上被省略。

将数字设置为 0 会清除徽章。

另请参阅

applicationName

static setDesktopFileName(name)#
参数：

name – 字符串

另请参阅

desktopFileName()

设置属性 desktopFileName 的值。

static setDesktopSettingsAware(on)#
参数：

on – 布尔型

static setFont(arg__1)#
参数：

arg__1 – QFont

static setHighDpiScaleFactorRoundingPolicy(policy)#
参数：

policy – HighDpiScaleFactorRoundingPolicy

static setLayoutDirection(direction)#
参数：

direction – PySide6.QtCore.Qt.LayoutDirection

另请参阅

layoutDirection()

设置属性 layoutDirection 的设置器。

static setOverrideCursor(arg__1)#
参数：

arg__1 - QCursor

返回类型：

QtGuiHelper::QOverrideCursorGuard*

警告

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

将应用程序覆盖光标设置为 cursor。

应用程序覆盖光标旨在向用户显示应用程序处于特殊状态，例如执行可能需要一些时间的操作期间。

直到调用 restoreOverrideCursor() 或另一个 setOverrideCursor()，此光标将在应用程序的所有小部件中显示。

应用程序光标存储在内置堆栈上。setOverrideCursor() 将光标推入堆栈，而 restoreOverrideCursor() 从堆栈中取出活动光标。changeOverrideCursor() 更改当前活动的应用程序覆盖光标。

每个 setOverrideCursor() 最终都必须由相应的 restoreOverrideCursor() 跟随，否则堆栈将永远不会清空。

示例

QGuiApplication.setOverrideCursor(QCursor(Qt.WaitCursor))
calculateHugeMandelbrot() # lunch time...
QGuiApplication.restoreOverrideCursor()

另请参阅

overrideCursor() restoreOverrideCursor() setCursor()

static setPalette(pal)#
参数：

pal – QPalette

static setQuitOnLastWindowClosed(quit)#
参数：

quit – bool

另请参阅

quitOnLastWindowClosed()

设置属性 quitOnLastWindowClosed 的设置器。

static setWindowIcon(icon)#
参数：

icon – QIcon

另请参阅

windowIcon

设置属性 windowIcon 的设置器。

静态 styleHints()#
返回类型：

QStyleHints

静态 sync()#
静态 topLevelAt(pos)#
参数：

pos – QPoint

返回类型：

QWindow

返回给定位置 pos 的顶层窗口，如果有。

静态 topLevelWindows()#
返回类型：

列表

返回应用程序中所有顶层窗口的列表。

另请参阅

allWindows()

静态 windowIcon()#
返回类型：

QIcon

另请参阅

setWindowIcon

属性 windowIcon属性 的获取器。