QGuiApplication Class

成员函数文档

QGuiApplication::QGuiApplication(int &argc, char **argv)

初始化窗口系统，并根据argv 中argc 的命令行参数构建应用程序对象。

全局指针qApp 指向此应用程序对象。应仅创建一个应用程序对象。

必须在创建任何paint devices （包括像素图、位图等）之前，先构建此应用程序对象。

支持的命令行选项

所有 Qt 程序都会自动支持一组命令行选项，这些选项允许修改 Qt 与窗口系统交互的方式。其中一些选项也可通过环境变量访问；如果应用程序可以启动 GUI 子进程或其他应用程序，则建议使用环境变量（因为子进程会继承环境变量）。 如有疑问，请使用环境变量。

当前支持的选项如下：

• -platformplatformName[:options]，指定Qt 平台抽象（QPA）插件。

  覆盖QT_QPA_PLATFORM 环境变量。

• -platformpluginpath path，指定平台插件的路径。

  覆盖QT_QPA_PLATFORM_PLUGIN_PATH 环境变量。

• -platformtheme platformTheme，指定平台主题。

  覆盖QT_QPA_PLATFORMTHEME 环境变量。

• -plugin plugin，指定要加载的其他插件。该参数可以出现多次。

  与QT_QPA_GENERIC_PLUGINS 环境变量中的插件进行拼接。

• -qmljsdebugger=，用于通过指定端口启动 QML/JS 调试器。该值必须采用port:1234[,block] 的格式，其中block为可选参数，启用后应用程序将等待调试器与其建立连接。
• -qwindowgeometry geometry，使用 X11 语法指定主窗口的几何属性。例如：-qwindowgeometry 100x100+50+50
• -qwindowicon, 设置默认窗口图标
• -qwindowtitle, 设置第一个窗口的标题
• -reverse, 将应用程序的布局方向设置为Qt::RightToLeft 。此选项旨在辅助调试，不应在生产环境中使用。默认值会根据用户的区域设置自动检测（另请参阅QLocale::textDirection()）。
• -session session，从之前的会话中恢复应用程序。

X11 支持以下标准命令行选项：

• -display hostname:screen_number，在X11上切换显示器。

  覆盖DISPLAY 环境变量。

• -geometry geometry，与-qwindowgeometry 相同。

平台特定参数

您可以为-platform 选项指定平台特定参数。请将它们作为以逗号分隔的列表，置于平台插件名称后的冒号之后。例如：-platform windows:dialogs=xp,fontengine=freetype 。

-platform windows 支持以下参数：

• altgr, 将某些键盘上的AltGr 键识别为Qt::GroupSwitchModifier （自 Qt 5.12 起）。
• darkmode=[0|1|2] 控制 Qt 如何响应 Windows 10 1903 版本中引入的应用程序暗黑模式激活（自 Qt 5.15 起）。

  值为 0 时将禁用深色模式支持。

  值为 1 时，当应用程序深色模式被激活且未使用高对比度主题时，Qt 会将窗口边框切换为黑色。此设置适用于实现自定义主题的应用程序。

  值为 2 时，还将禁用 Windows Vista 样式，并在深色模式下切换为使用简化配色方案的 Windows 样式。此功能目前处于实验阶段，待能够正确适应深色模式的新样式推出后将予以调整。

  从 Qt 6.5 开始，默认值为 2；若要禁用深色模式支持，请将该值设为 0 或 1。

• dialogs=[xp|none]，xp 使用 XP 风格的原生对话框，而none 则禁用这些对话框。
• fontengine=freetype, 使用 FreeType 字体引擎。
• fontengine=gdi, 使用基于 GDI 的旧版字体数据库，并默认使用 GDI 字体引擎（该引擎通常仅用于某些字体类型或字体属性）。（自 Qt 6.8 起）。
• menus=[native|none], 控制原生菜单的使用。

  原生菜单通过 Win32 API 实现，与基于QMenu 的菜单相比更为简单——例如，它们允许在菜单上放置控件或更改字体等属性，但不提供悬停信号。 它们主要适用于Qt Quick 。默认情况下，如果应用程序不是QApplication 的实例，或者对于Qt Quick Controls 2应用程序，将使用原生菜单（自Qt 5.10起）。

• nocolorfonts 禁用 DirectWrite 彩色字体（自 Qt 5.8 起）。
• nodirectwrite 禁用 DirectWrite 字体（自 Qt 5.8 起）。这也会隐式地选择 GDI 字体引擎。
• nomousefromtouch 忽略由操作系统从触摸事件合成而来的鼠标事件。
• nowmpointer 从指针输入消息处理切换为传统鼠标处理（自 Qt 5.12 起）。
• reverse 启用从右到左模式（实验性功能）。在从右到左的区域设置中，Windows 标题栏将相应地显示（自 Qt 5.13 起）。
• tabletabsoluterange=<value> 为 WinTab 触控板的鼠标模式检测设置值（传统模式，自 Qt 5.3 起）。

-platform cocoa （在 macOS 上）提供以下参数：

• fontengine=freetype，使用 FreeType 字体引擎。

有关嵌入式 Linux 平台可用的平台特定参数的更多信息，请参阅《Qt for Embedded Linux》。

另请参阅 arguments() 和QGuiApplication::platformName 。

[virtual noexcept] QGuiApplication::~QGuiApplication()

销毁该应用程序。

[static] QWindowList QGuiApplication::allWindows()

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

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

另请参阅 topLevelWindows()。

[static] Qt::ApplicationState QGuiApplication::applicationState()

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

您可以根据应用程序状态的变化采取相应措施，例如停止/恢复占用大量 CPU 资源的任务、释放/加载资源，或保存/恢复应用程序数据。

[signal] void QGuiApplication::applicationStateChanged(Qt::ApplicationState state)

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

另请参阅 applicationState()。

[static] void QGuiApplication::changeOverrideCursor(const QCursor &cursor)

将当前活动应用程序的覆盖光标更改为cursor 。

如果未调用setOverrideCursor()，则此函数无效。

另请参阅 setOverrideCursor()、overrideCursor()、restoreOverrideCursor() 和QWidget::setCursor()。

[static] QClipboard *QGuiApplication::clipboard()

返回用于与剪贴板交互的对象。

[signal] void QGuiApplication::commitDataRequest(QSessionManager &manager)

该信号用于会话管理。当QSessionManager 希望应用程序提交其所有数据时，会发出该信号。

通常这意味着在获得用户许可后，保存所有打开的文件。此外，您可能需要提供一种机制，让用户能够取消关机操作。

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

另请参阅 isSessionRestored()、sessionId()、saveStateRequest() 以及“会话管理”。

[static] bool QGuiApplication::desktopSettingsAware()

如果 Qt 设置为使用系统的标准颜色、字体等，则返回true ；否则返回false 。默认值为true 。

另请参阅 setDesktopSettingsAware()。

qreal QGuiApplication::devicePixelRatio() const

返回系统中检测到的最高屏幕设备像素比例。这是物理像素与设备无关像素之间的比例。

仅当您不知道目标窗口时才应使用此函数。如果您已知目标窗口，请改用QWindow::devicePixelRatio()。

另请参阅 QWindow::devicePixelRatio()。

[override virtual protected] bool QGuiApplication::event(QEvent *e)

重写了：QCoreApplication::event(QEvent *e)。

[static] int QGuiApplication::exec()

进入主事件循环，并等待直到调用exit()，然后返回设置在exit()中的值（如果通过quit()调用exit()，则该值为0）。

必须调用此函数才能开始事件处理。主事件循环从窗口系统接收事件，并将这些事件分发给应用程序控件。

通常，在调用 `exec()` 之前，无法进行任何用户交互。

若要让应用程序执行空闲处理（例如，在没有待处理事件时执行某个特殊函数），请使用超时时间为 0ns 的QChronoTimer 。通过processEvents() 可以实现更高级的空闲处理方案。

我们建议您将清理代码连接到aboutToQuit()信号上，而不是将其放在应用程序的main() 函数中。这是因为在某些平台上，QApplication::exec()调用可能不会返回。

另请参阅 quitOnLastWindowClosed 、quit()、exit()、processEvents() 以及QCoreApplication::exec()。

[static] QObject *QGuiApplication::focusObject()

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

[signal] void QGuiApplication::focusObjectChanged(QObject *focusObject)

当与焦点关联的事件的最终接收器发生变化时，会触发此信号。focusObject 是新的接收器。

另请参阅 focusObject()。

[static] QWindow *QGuiApplication::focusWindow()

返回一个QWindow ，用于接收与焦点相关的事件，例如键盘事件。

另请参阅 QWindow::requestActivate()。

[signal] void QGuiApplication::focusWindowChanged(QWindow *focusWindow)

当获得焦点的窗口发生变化时，会触发此信号。focusWindow 表示新的获得焦点的窗口。

另请参阅 focusWindow()。

[static] QFont QGuiApplication::font()

返回应用程序的默认字体。

另请参阅 setFont()。

[signal] void QGuiApplication::fontDatabaseChanged()

当可用字体发生变化时，会发出此信号。

当应用程序字体被添加或移除，或者系统字体发生变化时，可能会触发此信号。

另请参阅 QFontDatabase::addApplicationFont()、QFontDatabase::addApplicationFontFromData()、QFontDatabase::removeAllApplicationFonts() 和QFontDatabase::removeApplicationFont()。

[static] Qt::HighDpiScaleFactorRoundingPolicy QGuiApplication::highDpiScaleFactorRoundingPolicy()

返回高DPI缩放系数的舍入策略。

另请参阅 setHighDpiScaleFactorRoundingPolicy()。

[static] QInputMethod *QGuiApplication::inputMethod()

返回输入法。

该输入方法返回有关虚拟键盘状态和位置的属性。它还提供有关当前获得焦点的输入元素位置的信息。

另请参阅 QInputMethod 。

[static] bool QGuiApplication::isLeftToRight()

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

另请参阅 layoutDirection() 和isRightToLeft()。

[static] bool QGuiApplication::isRightToLeft()

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

另请参阅 layoutDirection() 和isLeftToRight()。

bool QGuiApplication::isSavingSession() const

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

当发出commitDataRequest() 和saveStateRequest() 时，返回值为true ；此外，当会话管理随后关闭窗口时，返回值也是 。

另请参阅 sessionId()、commitDataRequest() 和saveStateRequest()。

bool QGuiApplication::isSessionRestored() const

如果应用程序是从较早的会话中恢复的，则返回true ；否则返回false 。

另请参阅 sessionId()、commitDataRequest() 和saveStateRequest()。

[static] Qt::KeyboardModifiers QGuiApplication::keyboardModifiers()

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

需要注意的是，这可能并不反映调用时输入设备上实际按下的键，而是反映上述事件中最后报告的修饰键状态。如果未按下任何键，则返回Qt::NoModifier 。

另请参阅 mouseButtons() 和queryKeyboardModifiers()。

[signal] void QGuiApplication::lastWindowClosed()

当最后一个可见的主窗口（即没有临时父窗口的顶级窗口）被关闭时，exec() 会发出此信号。

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

另请参阅 QWindow::close()、QWindow::isTopLevel() 和QWindow::transientParent()。

[static] QWindow *QGuiApplication::modalWindow()

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

模态窗口是指其modality 属性被设置为Qt::WindowModal 或Qt::ApplicationModal 的窗口。用户必须先关闭模态窗口，才能继续执行程序的其他部分。

模态窗口以栈的形式组织。该函数返回栈顶的模态窗口。

另请参阅 Qt::WindowModality 和QWindow::setModality()。

[static] Qt::MouseButtons QGuiApplication::mouseButtons()

返回鼠标按钮的当前状态。当前状态会随着事件队列中那些会自发改变鼠标状态的事件（QEvent::MouseButtonPress 和QEvent::MouseButtonRelease 事件）被清除而同步更新。

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

另请参阅 keyboardModifiers()。

template <typename QNativeInterface> QNativeInterface *QGuiApplication::nativeInterface() const

返回应用程序中指定类型的本机接口。

该函数提供了对QGuiApplication 中平台特定功能的访问，这些功能在QNativeInterface 命名空间中定义：

如果请求的接口不可用，则返回一个nullptr 。

[override virtual] bool QGuiApplication::notify(QObject *object, QEvent *event)

重写了：QCoreApplication::notify(QObject *receiver, QEvent *event)。

[static] QCursor *QGuiApplication::overrideCursor()

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

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

另请参阅 setOverrideCursor() 和restoreOverrideCursor()。

[static] QPalette QGuiApplication::palette()

返回当前应用程序的调色板。

未显式设置的角色将采用系统的平台主题。

另请参阅 setPalette()。

[static] Qt::KeyboardModifiers QGuiApplication::queryKeyboardModifiers()

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

它不依赖于该进程是否已接收键按事件，因此可以在移动窗口时检查修饰键状态。请注意，在大多数情况下，您应使用 `keyboardModifiers()`，因为它包含当前处理的事件被接收时修饰键的状态，因此速度更快、更准确。

另请参阅 keyboardModifiers()。

[static] void QGuiApplication::restoreOverrideCursor()

撤销上一次对 `setOverrideCursor()` 的调用。

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

另请参阅 setOverrideCursor() 和overrideCursor()。

[signal] void QGuiApplication::saveStateRequest(QSessionManager &manager)

该信号用于会话管理。当session manager 希望应用程序为未来的会话保留其状态时，会调用该信号。

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

切勿在此信号处理过程中退出应用程序。相反，会话管理器可能会在之后执行此操作，也可能不会，这取决于具体上下文。此外，大多数会话管理器极有可能在应用程序启动后立即请求保存状态。这使得会话管理器能够了解应用程序的重启策略。

另请参阅 isSessionRestored()、sessionId()、commitDataRequest() 以及“会话管理”。

[signal] void QGuiApplication::screenAdded(QScreen *screen)

每当系统中新增一个屏幕screen 时，都会发出此信号。

另请参阅 screens()、primaryScreen 以及screenRemoved()。

[static] QScreen *QGuiApplication::screenAt(const QPoint &point)

返回位于point 处的屏幕，若超出任何屏幕范围，则返回nullptr 。

point 是相对于每组虚拟同级元素的 virtualGeometry() 而言的。如果该点映射到多组虚拟同级元素，则返回第一个匹配项。若您只想搜索已知屏幕的虚拟桌面同级元素（例如，您应用程序窗口所在屏幕QWidget::windowHandle()->screen() 的同级元素），请使用QScreen::virtualSiblingAt()。

[signal] void QGuiApplication::screenRemoved(QScreen *screen)

每当系统中移除一个screen 时，都会触发此信号。它为管理屏幕上的窗口提供了机会，以免Qt默认将其移动到主屏幕。

另请参阅 screens()、screenAdded()、QObject::destroyed() 以及QWindow::setScreen()。

[static] QList<QScreen *> QGuiApplication::screens()

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

QString QGuiApplication::sessionId() const

返回当前会话的标识符。

如果应用程序是从较早的会话中恢复的，则该标识符与之前会话中的标识符相同。无论对于不同的应用程序，还是对于同一应用程序的不同实例，会话标识符均保证是唯一的。

另请参阅 isSessionRestored()、sessionKey()、commitDataRequest() 以及saveStateRequest()。

QString QGuiApplication::sessionKey() const

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

如果应用程序是从较早的会话中恢复的，则该密钥与前一次会话结束时的密钥相同。

每次保存会话时，会话密钥都会发生变化。如果关闭过程被取消，下次关闭时将使用另一个会话密钥。

另请参阅 isSessionRestored()、sessionId()、commitDataRequest() 和saveStateRequest()。

[slot, since 6.5] void QGuiApplication::setBadgeNumber(qint64 number)

将应用程序的徽章设置为number 。

这有助于向用户反馈未读消息的数量等信息。

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

如果数字超出了平台支持的范围，该数字将被限制在支持的范围内。如果数字无法完全显示在徽章中，可能会被视觉上省略。

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

此功能于 Qt 6.5 中引入。

另请参阅 applicationName 。

[static] void QGuiApplication::setDesktopSettingsAware(bool on)

用于设置 Qt 是否应使用系统的标准颜色、字体等，并将其传递给 `on`。默认情况下，该值为 `true`。

必须在创建 `QGuiApplication ` 对象之前调用此函数，如下所示：

int main(int argc, char *argv[])
{
    QApplication::setDesktopSettingsAware(false);
    QApplication app(argc, argv);
    // ...
    return app.exec();
}

另请参阅 desktopSettingsAware()。

[static] void QGuiApplication::setFont(const QFont &font)

将应用程序的默认字体更改为font 。

另请参阅 font()。

[static] void QGuiApplication::setHighDpiScaleFactorRoundingPolicy(Qt::HighDpiScaleFactorRoundingPolicy policy)

设置应用程序的高DPI缩放因子舍入策略。policy 决定如何处理非整数缩放因子（例如 Windows 150%）。

主要有两个选项：即小数部分的缩放因子是否应四舍五入为整数。保持缩放因子原样将使用户界面大小与操作系统设置完全一致，但可能会导致绘制错误，例如在 Windows 样式下。

如果需要进行四舍五入，则接下来应决定采用哪种四舍五入方式。 虽然支持数学上正确的舍入，但这可能无法提供最佳的视觉效果：请考虑您是希望将 1.5x 渲染为 1x（“小 UI”），还是渲染为 2x（“大 UI”）。有关所有选项的完整列表，请参阅Qt::HighDpiScaleFactorRoundingPolicy 枚举。

必须在创建应用程序对象之前调用此函数。如果已设置，则QGuiApplication::highDpiScaleFactorRoundingPolicy() 访问器将反映该环境。

默认值为Qt::HighDpiScaleFactorRoundingPolicy::PassThrough 。

另请参阅 highDpiScaleFactorRoundingPolicy()。

[static] void QGuiApplication::setOverrideCursor(const QCursor &cursor)

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

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

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

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

每次调用 setOverrideCursor() 之后，最终都必须跟一个相应的restoreOverrideCursor()，否则栈将永远无法清空。

示例：

QGuiApplication::setOverrideCursor(QCursor(Qt::WaitCursor));
calculateHugeMandelbrot();              // lunch time...
QGuiApplication::restoreOverrideCursor();

另请参阅 overrideCursor()、restoreOverrideCursor()、changeOverrideCursor() 和QWidget::setCursor()。

[static] void QGuiApplication::setPalette(const QPalette &pal)

将应用程序配色方案更改为pal 。

该调色板中的颜色角色将与系统的平台主题相结合，形成应用程序的最终调色板。

另请参阅 palette()。

[static] QStyleHints *QGuiApplication::styleHints()

返回应用程序的样式提示。

这些样式提示封装了一组与平台相关的属性，例如双击间隔、全宽选择等。

这些提示可用于与底层平台实现更紧密的集成。

另请参阅 QStyleHints 。

[static] void QGuiApplication::sync()

可用于将 Qt 状态与窗口系统状态同步的函数。

该函数将首先通过调用QCoreApplication::processEvents()清空Qt事件，随后平台插件将与窗口系统进行同步，最后通过再次调用QCoreApplication::processEvents()来分发Qt事件；

此函数耗时较长，不建议使用。

[static] QWindow *QGuiApplication::topLevelAt(const QPoint &pos)

返回位于指定位置pos 的顶级窗口（如有）。

[static] QWindowList QGuiApplication::topLevelWindows()

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

另请参阅 allWindows()。