QGuiApplication 类

成员函数文档

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

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

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

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

支持的命令行选项

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

当前支持的选项如下：

• -platform platformName[: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，从早期 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=directwrite，使用实验性的 DirectWrite 字体数据库，并默认使用 DirectWrite 字体引擎（否则仅用于某些字体类型或字体属性。）这会影响字体选择，旨在提供与其他平台更一致的字体命名，但不支持所有字体格式，例如 Postscript Type-1 或 Microsoft FNT 字体。
• menus=[native|none]，控制本地菜单的使用。

  本地菜单使用 Win32 API 实现，并且比基于 QMenu 的菜单更简单，例如，它们允许在它们上放置小部件或更改像字体这样的属性，并且不提供悬停信号。它们主要用于 Qt Quick。默认情况下，如果应用程序不是 QApplication 的实例或用于 Qt Quick Controls 2 应用程序（自 Qt 5.10 起使用），将使用它们。

• nocolorfonts 禁用 DirectWrite Color 字体（自 Qt 5.8 起使用）。
• nodirectwrite 禁用 DirectWrite 字体（自 Qt 5.8 起使用）。
• nomousefromtouch 忽略操作系统从触摸事件合成的鼠标事件。
• nowmpointer 从指针输入消息处理切换到传统鼠标处理（自 Qt 5.12 起使用）。
• reverse 启用从右向左的文本模式（实验性）。在从右向左的语言区域中（自Qt 5.13开始），窗口标题栏将相应显示。
• tabletabsoluterange=<value> 为WinTab平板电脑的鼠标模式检测设置一个值（继承，自Qt 5.3）。

以下参数在-platform cocoa（在macOS上）可用。

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

有关适用于嵌入式Linux平台的特定平台参数的更多信息，请参见Qt for Embedded Linux。

见 Also arguments() 和 QGuiApplication::platformName。

[虚拟 noexcept] QGuiApplication::~QGuiApplication()

销毁应用程序。

[静态] QWindowList QGuiApplication::allWindows()

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

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

见 Also topLevelWindows。

[静态] Qt::ApplicationState QGuiApplication::applicationState()

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

您可以响应应用程序状态的变化来执行诸如停止/继续CPU密集型任务、释放/加载资源或保存/恢复应用程序数据等操作。

[信号] void QGuiApplication::applicationStateChanged(Qt::ApplicationState state)

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

见 Also applicationState。

[静态] void QGuiApplication::changeOverridePalette(const QCursor &cursor)

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

如果未调用setOverrideCursor，则此函数不起作用。

见 Also setOverrideCursor、overrideCursor、restoreOverrideCursor 和 QWidget::setCursor。

[静态] QClipboard *QGuiApplication::clipboard()

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

[信号] void QGuiApplication::commitDataRequest(QSessionManager &manager)

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

通常这意味着在从用户那里获得许可后保存所有打开的文件。此外，您可能还想提供一种方法，用户可以通过该方法取消关闭。

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

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

[静态] bool QGuiApplication::desktopSettingsAware()

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

另请参阅 setDesktopSettingsAware()。

qreal QGuiApplication::devicePixelRatio() const

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

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

另请参阅 QWindow::devicePixelRatio。

[重写虚拟保护] bool QGuiApplication::event(QEvent *e)

重新实现：QCoreApplication::event(QEvent *e)。

[静态] int QGuiApplication::exec()

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

需要调用此函数以启动事件处理。主事件循环从窗口系统接收事件并将这些事件分发到应用程序小部件。

在调用exec()之前，通常无法发生用户交互。

要使您的应用程序执行空闲处理，例如，在没有任何挂起事件时执行特殊函数，请使用超时为0的QTimer。更高级的空闲处理方案可以使用processEvents实现。

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

另请参阅 quitOnLastWindowClosed，quit，exit，processEvents，和QCoreApplication::exec。

[静态] QObject *QGuiApplication::focusObject()

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

[信号] void QGuiApplication::focusObjectChanged(QObject *focusObject)

当焦点相关事件的最终接收者发生变化时，将发出此信号。focusObject是新接收者。

另请参阅 focusObject().

[静态] QWindow *QGuiApplication::focusWindow()

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

另请参阅 QWindow::requestActivate().

[信号] void QGuiApplication::focusWindowChanged(QWindow *focusWindow)

当焦点窗口发生变化时，将发出此信号。focusWindow是新焦点窗口。

另请参阅 focusWindow().

[静态] QFont QGuiApplication::font()

返回默认应用程序字体。

另请参阅 setFont().

[信号] void QGuiApplication::fontDatabaseChanged()

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

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

另请参阅 QFontDatabase::addApplicationFont()，QFontDatabase::addApplicationFontFromData()，QFontDatabase::removeAllApplicationFonts()和QFontDatabase::removeApplicationFont().

[静态] Qt::HighDpiScaleFactorRoundingPolicy QGuiApplication::highDpiScaleFactorRoundingPolicy()

返回高DPI缩放因子舍入策略。

另请参阅 setHighDpiScaleFactorRoundingPolicy().

[静态] QInputMethod *QGuiApplication::inputMethod()

返回输入法。

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

另请参阅 QInputMethod.

[静态] bool QGuiApplication::isLeftToRight()

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

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

[静态] bool QGuiApplication::isRightToLeft()

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

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

bool QGuiApplication::isSavingSession() const

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

当 commitDataRequest() 和 saveStateRequest() 被触发时为 true，此外当会话管理随后关闭窗口时也为 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。

[信号] void QGuiApplication::saveStateRequest(QSessionManager &manager)

此信号处理 会话管理。当会话管理器希望应用程序为未来的会话保留其状态时，会调用它。

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

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

见亦 isSessionRestored，sessionId，commitDataRequest，和 Session Management。

[信号] void QGuiApplication::screenAdded(QScreen *screen)

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

见亦 screens，primaryScreen，和 screenRemoved。

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

返回point处的屏幕，或如果位于任何屏幕之外，则返回nullptr。

point是相对于每一组虚拟同辈的virtualGeometry()的关系。如果点映射到多个虚拟同辈集，则返回第一个匹配项。如果你只想搜索已知屏幕（例如应用窗口的屏幕的同辈，例如 QWidget::windowHandle()->screen()）的虚拟桌面同辈，请使用 QScreen::virtualSiblingAt。

[信号] void QGuiApplication::screenRemoved(QScreen *screen)

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

见亦 screens，screenAdded，QObject::destroyed，和 QWindow::setScreen。

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

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

QString QGuiApplication::sessionId() const

返回当前 会话 的标识符。

如果应用程序是从早期会话中恢复的，则该标识符与之前会话中相同。会话标识符对于不同的应用程序以及同一应用程序的不同实例都是唯一的。

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

QString QGuiApplication::sessionKey() const

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

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

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

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

[槽，自 6.5 版起] void QGuiApplication::setBadgeNumber(qint64 number)

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

有助于向用户提供有关未读消息数量或其他类似信息的反馈。

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

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

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

此功能是在 Qt 6.5 中引入的。

另请参阅applicationName。

[静态] 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。

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

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

另请参阅font。

[静态] 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。

[静态] 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。

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

将应用程序调色板更改为pal。

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

另请参阅palette。

[静态] QStyleHints *QGuiApplication::styleHints()

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

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

提示可以实现与底层平台的更紧密集成。

另请参阅QStyleHints。

[静态] void QGuiApplication::sync()

可通过此函数将Qt状态与窗口系统状态同步。

此函数首先通过调用QCoreApplication::processEvents()清空Qt事件，然后平台插件将与windowsystem同步，最后通过另一个调用QCoreApplication::processEvents()将Qt事件交付。

此函数消耗时间，不建议使用。

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

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

[静态] QWindowList QGuiApplication::topLevelWindows()

返回包含应用程序中顶层窗口的列表。

另请参阅allWindows。