QGuiApplication

一、描述

QGuiApplication 类继承自 QCoreApplication ，管理 GUI 应用程序的控制流和主要设置。

QGuiApplication 包含主事件循环，来自窗口系统和其他来源的所有事件都在其中被处理和调度。它还处理应用程序的初始化和终结，并提供会话管理。此外，QGuiApplication 处理大部分系统范围和应用程序范围的设置。

对于任何使用 Qt 的 GUI 应用程序，应用程序在任何时间都只有一个 QGuiApplication 对象。对于非 GUI Qt 应用程序，请改用 QCoreApplication，因为它不依赖于 Qt GUI 模块。对于基于 QWidget 的 Qt 应用程序，请改用 QApplication，因为它提供了创建 QWidget 实例所需的一些功能。

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

QGuiApplication 的主要职责范围是：

• 它使用用户的桌面设置初始化应用程序，例如 palette()、font() 和styleHints()。它会跟踪这些属性，以防用户全局更改桌面。
• 它执行事件处理，这意味着它从底层窗口系统接收事件并将它们分派给相关的小部件。
• 它解析常见的命令行参数并相应地设置其内部状态。
• 它通过 translate() 提供对用户可见的字符串的本地化。
• 它提供了一些神奇的对象，例如 clipboard()。
• 它知道应用程序的窗口。可以使用 topLevelAt() 询问哪个窗口在某个位置，获取 topLevelWindows() 列表等。
• 它管理应用程序的鼠标光标处理。
• 它为复杂的会话管理提供支持。这使得应用程序可以在用户注销时优雅地终止，如果无法终止，则可以取消关闭过程，甚至可以为将来的会话保留整个应用程序的状态。

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

二、属性成员

1、applicationDisplayName : QString

应用程序的用户可见名称。该名称显示给用户，例如在窗口标题中。 如有必要，可以翻译。

如果未设置，则应用程序显示名称默认为应用程序名称。

2、desktopFileName : QString

应用程序的桌面条目的基本名称。

3、layoutDirection : Qt::LayoutDirection

应用程序的默认布局方向。在系统启动时，默认布局方向取决于应用程序的语言。

4、【只读】platformName : const QString

底层平台插件的名称。

5、primaryScreen : QScreen* const

应用程序的主要（或默认）屏幕。这将是最初显示 QWindows 的屏幕。

6、quitOnLastWindowClosed : bool

当最后一个窗口关闭时应用程序是否隐式退出。默认值为 true。

如果此属性为真，则应用程序会在最后一个可见的主窗口（即没有父窗口的窗口）关闭时退出。

7、windowIcon : QIcon

默认窗口图标。

三、成员函数

1、QGuiApplication(int &argc, char **argv)

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

argc 和 argv 引用的数据必须在 QGuiApplication 对象的整个生命周期内保持有效。此外，argc 必须大于零，并且 argv 必须至少包含一个有效字符串。

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

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

2、【信号】void applicationStateChanged(Qt::ApplicationState state)

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

enum Qt::ApplicationState：此枚举类型用于指定应用程序的当前状态。

• Qt::ApplicationSuspended：应用程序即将挂起。进入此状态时，应用程序应保存其状态，停止所有活动，并为停止代码执行做好准备。在挂起时，应用程序可以在任何时候被终止，而不会发出进一步的警告（例如，当内存不足迫使操作系统清除挂起的应用程序时）。
• Qt::ApplicationHidden：应用程序被隐藏并在后台运行。这是需要进行后台处理的应用程序的正常状态，例如播放音乐，而用户与其他应用程序交互。进入此状态时，应用程序应释放所有图形资源。
• Qt::ApplicationInactive：应用程序可见，但未选择在前面。在桌面平台上，这通常意味着用户激活了另一个应用程序。在移动平台上，当操作系统中断用户时进入此状态更为常见，例如来电或短信。在此状态下，请考虑减少 CPU 密集型任务。
• Qt::ApplicationActive：应用程序可见并选择在前面。

      【static】Qt::ApplicationState applicationState()

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

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

3、【信号】void commitDataRequest(QSessionManager &manager)

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

注意：当连接到这个信号时，应该使用 Qt::DirectConnection。

        bool isSavingSession()

应用程序当前是否正在保存会话。

        bool isSessionRestored()

应用程序是否已从较早的会话中恢复。

        QString sessionId()

返回当前会话的标识符。

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

        QString sessionKey()

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

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

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

      【信号】void saveStateRequest(QSessionManager &manager)

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

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

大多数会话管理器很可能会在应用程序启动后立即请求保存状态。 这允许会话管理器了解应用程序的重新启动策略。

注意：当连接到这个信号时，应该使用 Qt::DirectConnection。

4、【信号】void focusObjectChanged(QObject *focusObject)

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

     【static】QObject *focusObject()

返回当前活动窗口中的 QObject，它将成为与焦点相关的事件的最终接收者，例如键事件。

5、【信号】void focusWindowChanged(QWindow *focusWindow)

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

      【static】QWindow * focusWindow()

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

6、【信号】void fontDatabaseChanged()

此信号在加载或删除应用程序字体时发出。

7、【信号】void lastWindowClosed()

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

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

8、【信号】void screenAdded(QScreen *screen)

每当向系统添加新的屏幕屏幕时，就会发出此信号。

    【信号】void screenRemoved(QScreen *screen)

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

9、【static】QWindowList allWindows()

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

10、【static】void changeOverrideCursor(const QCursor &cursor)

更改应用程序的覆盖光标。如果未调用 setOverrideCursor()，则此函数无效。

        【static】QCursor * overrideCursor()

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

如果没有定义应用程序游标（即内部游标堆栈为空），此函数返回 nullptr。

        【static】void restoreOverrideCursor()

撤消最后的 setOverrideCursor()。

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

        【static】void setOverrideCursor(const QCursor &cursor)

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

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

在调用 restoreOverrideCursor() 或再一次调用 setOverrideCursor() 之前，此光标将显示在所有应用程序的小部件中。

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

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

QGuiApplication::setOverrideCursor(QCursor(Qt::WaitCursor));
calculateHugeMandelbrot();              // 耗时操作...
QGuiApplication::restoreOverrideCursor();

11、【static】QClipboard * clipboard()

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

12、【static】bool desktopSettingsAware()

Qt 是否设置为使用系统的标准颜色、字体等。默认为 true。

       【static】void setDesktopSettingsAware(bool on)

将 Qt 是否应使用系统的标准颜色、字体等设置为 on。

此函数必须在创建 QGuiApplication 对象之前调用。

13、qreal devicePixelRatio()

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

仅当不知道要定位哪个窗口时才使用此功能。如果确实知道目标窗口，请改用 QWindow::devicePixelRatio()。

14、【static】int exec()

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

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

通常，在调用 exec() 之前不能进行任何用户交互。

要使的应用程序执行空闲操作（当没有正在排队等待执行的事件才会处理的操作）请使用具有 0 超时的 QTimer。使用 processEvents() 可以实现更高级的空闲处理方案。

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

15、【static】QFont font() / 【static】void setFont(const QFont &font)

默认的应用程序字体。

16、【static】Qt::HighDpiScaleFactorRoundingPolicy highDpiScaleFactorRoundingPolicy()

【static】void setHighDpiScaleFactorRoundingPolicy(Qt::HighDpiScaleFactorRoundingPolicy policy)

高 DPI 比例因子舍入策略。该策略决定如何处理非整数比例因子（例如 Windows 150%）。在创建应用程序对象之前调用。

enum class Qt::HighDpiScaleFactorRoundingPolicy：

• Qt::HighDpiScaleFactorRoundingPolicy::Round：向上舍入 0.5 及以上。
• Qt::HighDpiScaleFactorRoundingPolicy::Ceil：总是向上取整。
• Qt::HighDpiScaleFactorRoundingPolicy::Floor：总是向下舍入。
• Qt::HighDpiScaleFactorRoundingPolicy::RoundPreferFloor：向上舍入 0.75 及以上。
• Qt::HighDpiScaleFactorRoundingPolicy::PassThrough：不要舍入。默认值。

17、【static】QInputMethod * inputMethod()

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

18、【static】bool isLeftToRight()

应用程序的布局方向是否是 Qt::LeftToRight。

        【static】bool isRightToLeft()

应用程序的布局方向是否是 Qt::RightToLeft。

19、【static】Qt::KeyboardModifiers keyboardModifiers()

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

enum Qt::KeyboardModifier：这个枚举描述了修饰键。

• Qt::NoModifier：没有按下修饰键。
• Qt::ShiftModifier：按下键盘上的 Shift 键。
• Qt::ControlModifier：按下键盘上的 Ctrl 键。
• Qt::AltModifier：按下键盘上的 Alt 键。
• Qt::MetaModifier：按下键盘上的 Meta 键。
• Qt::KeypadModifier：键盘按钮被按下。
• Qt::GroupSwitchModifier：仅限 X11（除非在 Windows 上通过命令行参数激活）。 按下键盘上的 Mode_switch 键。

注意：在 macOS 上，ControlModifier 值对应于键盘上的 Command 键，MetaModifier 值对应于 Control 键。KeypadModifier 值也将在按下箭头键时设置，因为箭头键被视为键盘的一部分。

注意：在 Windows 键盘上，Qt::MetaModifier 和 Qt::Key_Meta 映射到 Windows 键。

       【static】Qt::KeyboardModifiers queryKeyboardModifiers()

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

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

20、【static】QWindow * modalWindow()

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

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

21、Qt::MouseButtons mouseButtons()

返回鼠标按钮的当前状态。当前状态同步更新，因为事件队列清空了会自发改变鼠标状态的事件（QEvent::MouseButtonPress 和 QEvent::MouseButtonRelease 事件）。

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

22、template <typename QNativeInterface> QNativeInterface * nativeInterface()

为应用程序返回给定类型的本机接口。

23、【static】QPalette palette() / 【static】void setPalette(const QPalette &pal)

应用程序调色板。

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

24、【static】QScreen * screenAt(const QPoint &point)

返回该点的屏幕，如果在任何屏幕之外，则返回 nullptr。

        【static】QList<QScreen *> screens()

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

25、【static】QStyleHints * styleHints()

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

26、【static】void sync()

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

该函数将首先通过调用 QCoreApplication::processEvents() 清空 Qt 事件，然后平台插件将与窗口系统同步，最后通过另一个调用 QCoreApplication::processEvents() 传递 Qts 事件；

此功能非常耗时，不鼓励使用。

27、【static】QWindow * topLevelAt(const QPoint &pos)

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

28、【static】QWindowList topLevelWindows()

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

四、宏成员

1、qGuiApp

指向唯一应用程序对象的全局指针。仅当该对象是 QGuiApplication 时才有效。