QGuiApplication Class

成员函数文档

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

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

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

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

支持的命令行选项

所有 Qt 程序都自动支持一组命令行选项，允许修改 Qt 与窗口系统交互的方式。如果应用程序可以启动图形用户界面子进程或其他应用程序（子进程将继承环境变量），环境变量是首选形式。如有疑问，请使用环境变量。

目前支持的选项如下：

• -platform platformName[:选项]，指定Qt 平台抽象（QPA）插件。

  覆盖QT_QPA_PLATFORM 环境变量。

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

  覆盖QT_QPA_PLATFORM_PLUGIN_PATH 环境变量。

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

  覆盖QT_QPA_PLATFORMTHEME 环境变量。

• -plugin platformTheme，指定平台主题。该参数可出现多次。

  与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 会话，从较早的会话恢复应用程序。

下列标准命令行选项可用于 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]在 Qt 6.8 中，"... "控制本地菜单的使用。

  本地菜单使用 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() 设置的值（如果exit() 通过quit() 被调用，则返回值为 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()

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

模式窗口是指其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（"小用户界面"）还是 2x（"大用户界面"）。有关所有选项的完整列表，请参见Qt::HighDpiScaleFactorRoundingPolicy 枚举。

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

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

另请参见 highDpiScaleFactorRoundingPolicy()。

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

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

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

在调用restoreOverrideCursor() 或另一个 setOverrideCursor() 之前，该游标将显示在应用程序的所有部件中。

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

每个 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() 清空 Qts 事件，然后平台插件将与窗口系统同步，最后通过再次调用QCoreApplication::processEvents() 释放 Qts 事件；

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

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

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

[static] QWindowList QGuiApplication::topLevelWindows()

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

另请参阅 allWindows()。