QGuiApplication类管理GUI应用程序的控制流和主设置。
头文件:
#include
cmake:
find_package(Qt6 COMPONENTS Gui REQUIRED) target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake:
QT += gui
cmake:
Qt 5.0
继承自:
QCoreApplication
继承者:
QApplication
QGuiApplication包含主事件循环,在该循环中,来自窗口系统和其他来源的所有事件都将被处理和调度。它还处理应用程序的初始化和完成,并提供会话管理。另外,QGuiApplication处理大多数系统范围和应用程序范围的设置。
对于任何使用Qt的GUI应用程序,无论该应用程序在任何给定时间有0、1、2或更多窗口,都存在一个精确的QGuiApplication对象。对于非GUI Qt应用程序,请改用QCoreApplication,因为它不依赖于Qt GUI模块。对于基于QWidget的Qt应用程序,请改用QApplication,因为它提供了创建QWidget实例所需的某些功能。
可通过instance()函数访问QGuiApplication对象,该函数返回一个等效于全局qApp指针的指针。
QGuiApplication的主要职责是:
由于QGuiApplication对象进行了大量初始化,因此必须在创建与用户界面相关的任何其他对象之前创建它。qgui应用程序还处理常见的命令行参数。因此,在应用程序本身中对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(). |
另请参见QCoreApplication,QAbstractEventDispatcher和QEventLoop。
此属性保存此应用程序的用户可见名称
该名称将显示给用户,例如在窗口标题中。如有必要,可以翻译。
如果未设置,则应用程序显示名称默认为应用程序名称。
此属性是在Qt 5.0中引入的。
另请参见:applicationName.
此属性保存此应用程序的桌面条目的基本名称
根据freedesktop桌面条目规范,这是代表该应用程序的桌面条目的文件名(不带完整路径)。
此属性可准确指示什么桌面项代表该应用程序,并且窗口系统需要它来检索此类信息,而无需求助于不精确的启发式方法。
您可以在此处获得freedesktop桌面条目规范的最新版本。
此属性保留此应用程序的默认布局方向
在系统启动时,默认的布局方向取决于应用程序的语言。
另请参见:QWidget::layoutDirection, isLeftToRight(), isRightToLeft().
只读
此属性保存基础平台插件的名称。
QPA平台插件位于中qtbase\src\plugins\platforms。在撰写本文时,支持以下平台插件名称:
有关嵌入式Linux设备的平台插件的更多信息,请参见Qt for Embedded Linux。
只读
此属性保存应用程序的主(或默认)屏幕。
除非另有说明,否则这将是qwindow最初显示的屏幕。
Qt 5.6中引入了primaryScreenChanged 信号。
另请参见:screens().
此属性保存应用程序是否在最后一个窗口关闭时隐式退出。
默认值为true。
如果此属性为true,则当最后一个可见的主窗口(即没有父窗口)关闭时,应用程序将退出。
另请参见: quit() 、QWindow::close().
另请参见:QWindow::setIcon() 、Setting the Application Icon.
QGuiApplication::QGuiApplication(int &argc, char
**
argv)
初始化窗口系统并在argv中使用argc命令行参数构造一个应用程序对象。
警告:argc和argv引用的数据必须在QGuiApplication对象的整个生命周期内保持有效。此外,argc必须大于0,argv必须包含至少一个有效字符串。
全局qApp指针引用这个应用程序对象。应该只创建一个应用程序对象。
此应用程序对象必须在绘制设备(包括像素图、位图等)之前构造。
注意:当Qt删除它识别的命令行参数时,argc和argv可能会被更改。
所有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-syntax为主窗口指定窗口几何。例如:-qwindowgeometry 100x100+50+50
qwindowicon,设置默认窗口图标
qwindowtitle,设置第一个窗口的标题
reverse,设置应用程序的布局方向为Qt:: righttleft。此选项旨在帮助调试,不应该在生产中使用。默认值会自动从用户的区域设置中检测到(参见QLocale::textDirection())。
session session,从以前的会话恢复应用。
以下标准命令行选项可用于X11:
您可以为该-platform选项指定特定于平台的参数。将它们放在平台插件名称之后,并用冒号作为逗号分隔列表。例如,-platform windows:dialogs=xp,fontengine=freetype。
以下参数可用于-platform windows:
[signal, since 5.2]
void QGuiApplication::applicationStateChanged(Qt::ApplicationState state)
当应用程序的状态改变时,会发出此信号。
这个函数是在qt5.2中引入的。
另请参见applicationState()。
QGuiApplication::QGuiApplication(int &argc, char
**
argv)
另请参见:arguments() 、QGuiApplication::platformName.
[signal, since 5.2]
void QGuiApplication::applicationStateChanged(Qt::ApplicationState state)
当应用程序的状态改变时,将发出此信号。
这个函数是在Qt 5.2中引入的。
另请参见:applicationState().
[signal]void QGuiApplication::commitDataRequest(QSessionManager &manager)
这个信号处理会话管理。当QSessionManager希望应用程序提交其所有数据时,就会触发它。
通常这意味着在获得用户的许可后保存所有打开的文件。此外,您可能希望提供一种方法,用户可以通过它取消关闭。
您不应该在此信号内退出应用程序。相反,会话管理器之后可能做也可能不做,这取决于上下文。
警告:在这个信号中,不可能有用户交互,除非您请求经理明确的许可。请参阅QSessionManager::allowsInteraction()和QSessionManager::allowsErrorInteraction()了解详细信息和示例用法。
注意:当连接到这个信号时,你应该使用Qt::DirectConnection。
另请参阅isessionrestored()、sessionId()、saveStateRequest()和会话管理。
*[signal]void QGuiApplication::focusObjectChanged(QObject focusObject)
当与焦点绑定的事件的最终接收者发生改变时,将发出此信号。focusObject是新的接收者。
参见focusObject()。
*[signal]void QGuiApplication::focusWindowChanged(QWindow focusWindow)
当聚焦窗口发生变化时,就会发出这个信号。focusWindow是新的聚焦窗口。
参见focusWindow()。
void QGuiApplication::fontDatabaseChanged()
当应用程序的字体被加载或删除时,这个信号被触发。
参见QFontDatabase::addApplicationFont(), QFontDatabase::addApplicationFontFromData(), QFontDatabase::removeAllApplicationFonts(),和QFontDatabase::removeApplicationFont()。
[signal]void QGuiApplication::lastWindowClosed()
这个信号是由exec()在最后一个可见的主窗口(即没有父窗口)关闭时发出的。
默认情况下,QGuiApplication在这个信号发出后退出。该特性可以通过将quitOnLastWindowClosed设置为false来关闭。
参见QWindow::close()和QWindow::isTopLevel()。
[signal]void QGuiApplication::saveStateRequest(QSessionManager &manager)
这个信号处理会话管理。当会话管理器希望应用程序为将来的会话保留其状态时,就会调用它。
例如,文本编辑器将创建一个临时文件,其中包括其编辑缓冲区的当前内容、光标的位置和当前编辑会话的其他方面。
永远不要在这个信号内退出应用程序。相反,会话管理器之后可能做也可能不做,这取决于上下文。此外,大多数会话管理器很可能会在应用程序启动后立即请求保存的状态。这允许会话管理器了解应用程序的重启策略。
警告:在这个信号中,不可能有用户交互,除非您请求经理明确的许可。详情请参阅QSessionManager::allowsInteraction()和QSessionManager::allowsErrorInteraction()。
注意:当连接到这个信号时,你应该使用Qt::DirectConnection。
参见isessionrestored()、sessionId()、commitDataRequest()和Session Management。
[signal]void QGuiApplication::screenAdded(QScreen
*
screen)
每当向系统添加新屏幕时,就会发出此信号。
另请参见screens()、primaryScreen和screenRemoved()。
[signal, since 5.4]void QGuiApplication::screenRemoved(QScreen
*
screen)
每当从系统中卸下屏幕时,就会发出此信号。它提供了一个在Qt退回到主屏幕之前管理屏幕上的窗口的机会。
这个函数是在qt5.4中引入的。
另请参见screens()、screenAdded()、QObject::destroyed()和QWindow::setScreen()。
[virtual]QGuiApplication::~QGuiApplication()
销毁
[static]QWindowList QGuiApplication::allWindows()
返回应用程序中所有窗口的列表。
如果没有窗口,则列表为空。
参见topLevelWindows()。
[static, since 5.2]Qt::ApplicationState QGuiApplication::applicationState()
返回应用程序的当前状态。
您可以对应用程序状态的变化作出反应,以执行诸如停止/恢复cpu密集型任务、释放/加载资源或保存/恢复应用程序数据等操作。
这个函数是在Qt 5.2中引入的。
[static]void QGuiApplication::changeOverrideCursor(const QCursor &cursor)
将当前活动的应用程序覆盖光标更改为光标。
如果未调用setOverrideCursor(),则此函数无效。
另请参见setOverrideCursor()、overrideCursor()、restoreOverrideCursor()和QWidget::setCursor()。
[static]QClipboard
*
QGuiApplication::clipboard()
返回与剪贴板交互的对象。
[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()之前不会发生用户交互。
为了让你的应用程序执行空闲处理,例如,在没有等待事件的时候执行一个特殊的函数,使用一个超时为0的QTimer。使用processEvents()可以实现更高级的空闲处理方案。
我们建议您将清理代码连接到aboutToQuit()信号,而不是将其放在应用程序的main()函数中。这是因为,在某些平台上,QApplication::exec()调用可能不会返回。
参见quitOnLastWindowClosed, quit(), exit(), processEvents()和QCoreApplication::exec()。
[static]QObject
*
QGuiApplication::focusObject()
返回当前活动窗口中的QObject,该QObject将是绑定到焦点的事件(如键事件)的最终接收者。
[static]QWindow
*
QGuiApplication::focusWindow()
返回接收与焦点相关的事件(如键事件)的QWindow。
[static]QFont QGuiApplication::font()
返回默认的应用程序字体。
参见setFont()。
[static, since 5.14]Qt::HighDpiScaleFactorRoundingPolicy QGuiApplication::highDpiScaleFactorRoundingPolicy()
返回高dpi比例因子舍入策略。
这个函数是在Qt 5.14中引入的。
参见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()。
[since 5.0]bool QGuiApplication::isSavingSession() const
如果应用程序当前正在保存会话,则返回true;否则返回false。
当发出commitDataRequest()和saveStateRequest()时是true,当会话管理之后关闭窗口时也是true。
这个函数是在Qt 5.0中引入的。
参见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()。
[static]QWindow
*
QGuiApplication::modalWindow()
返回最近显示的模态窗口。如果没有可见的模态窗口,这个函数返回0。
一个模态窗口是一个将其模态属性设置为Qt::WindowModal或Qt::ApplicationModal的窗口。在用户继续使用程序的其他部分之前,必须关闭模态窗口。
模态窗口组织在一个堆栈中。这个函数返回堆栈顶部的模态窗口。
参见Qt:: windowmodal()和QWindow:: setmodal()。
[static]Qt::MouseButtons QGuiApplication::mouseButtons()
返回鼠标上按钮的当前状态。当事件队列中自动改变鼠标状态的事件被清空时,当前状态同步更新(QEvent::MouseButtonPress和QEvent::MouseButtonRelease事件)。
需要注意的是,这可能不是调用时输入设备上的实际按钮,而是上述事件中最后报告的鼠标按钮。如果没有按住鼠标按钮,则返回Qt::NoButton。
参见keyboardModifiers()。
[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()
查询并返回键盘上修改键的状态。与keyboardmodifier不同,此方法返回调用该方法时在输入设备上保留的实际键。
它不依赖于此进程接收到的按键事件,例如,这使得在移动窗口时检查修改器成为可能。请注意,在大多数情况下,您应该使用keyboardModifiers(),这会更快更准确,因为它包含当前处理的事件接收时的修改器状态。
请参见keyboardModifiers()。
[static]void QGuiApplication::restoreOverrideCursor()
撤销最后一个setOverrideCursor()。
如果setOverrideCursor()被调用了两次,那么调用restoreOverrideCursor()将激活第一个游标集。第二次调用此函数将恢复原始小部件的游标。
参见setOverrideCursor()和overrideCursor()。
[static, since 5.10]QScreen
*
QGuiApplication::screenAt(const QPoint &point)
在点处返回屏幕,在任何屏幕之外返回nullptr。
这一点与每组虚拟兄弟的virtualGeometry()有关。如果点映射到多个虚拟兄弟节点,则返回第一个匹配项。如果你希望只搜索已知屏幕的虚拟桌面兄弟(例如你的应用程序窗口的兄弟QWidget::windowHandle()->screen()),使用QScreen::virtualSiblingAt()。
这个函数是在Qt 5.10中引入的。
[static]QList
*> QGuiApplication::screens()
返回与应用程序所连接的窗口系统相关联的所有屏幕的列表。
QString QGuiApplication::sessionId() const
返回当前会话的标识符。
如果应用程序已从以前的会话中恢复,则此标识符与前一个会话中的标识符相同。会话标识符对于不同的应用程序以及同一个应用程序的不同实例都保证是唯一的。
参见isSessionRestored(), sessionKey(), commitDataRequest(), saveStateRequest().
QString QGuiApplication::sessionKey() const
返回当前会话中的会话密钥。
如果应用程序已从以前的会话中恢复,则此键与前一个会话结束时的键相同。
每次保存会话时,会话密钥都会改变。如果关闭进程被取消,当再次关闭时将使用另一个会话密钥。
参见 isSessionRestored(), sessionId(), commitDataRequest(), saveStateRequest().
[static]void QGuiApplication::setDesktopSettingsAware(bool on)
设置Qt是否应该使用系统的标准颜色、字体等。默认情况下,这是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)
将应用程序的默认字体更改为字体。
参见字体()。
[static, since 5.14]void QGuiApplication::setHighDpiScaleFactorRoundingPolicy(Qt::HighDpiScaleFactorRoundingPolicy policy)
为应用程序设置高dpi比例因子舍入策略。策略决定如何处理非整数比例因子(如Windows 150%)。
两个主要的选项是分数比例因子是否应该四舍五入为整数。保持缩放系数不变将使用户界面大小与操作系统设置完全匹配,但可能会导致绘制错误,例如使用Windows风格时。
如果需要舍入,那么下一步应该决定哪种类型的舍入。支持数学上正确的四舍五入,但可能不会给出最好的视觉结果:考虑是否要将1.5倍渲染成1x(小UI)或2x(大UI)。查看Qt::HighDpiScaleFactorRoundingPolicy枚举以获得所有选项的完整列表。
必须在创建应用程序对象之前调用此函数。如果设置了,QGuiApplication::highDpiScaleFactorRoundingPolicy()访问器将反映环境。
默认值:Qt::HighDpiScaleFactorRoundingPolicy::PassThrough。
这个函数是在Qt 5.14中引入的。
参见highDpiScaleFactorRoundingPolicy()。
[static]void QGuiApplication::setOverrideCursor(const QCursor &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。
这个调色板中的颜色角色与系统的平台主题相结合,形成应用程序的最终调色板。
参见调色板()。
*[static]QStyleHints QGuiApplication::styleHints()
返回应用程序的样式提示。
样式提示封装了一组依赖于平台的属性,如双击间隔、全宽度选择等。
这些提示可以用于与底层平台更紧密地集成。
也看到QStyleHints。
[static, since 5.2]void QGuiApplication::sync()
可用于将Qt状态与窗口系统状态同步的函数。
此函数首先调用QCoreApplication::processEvents()清空Qts事件,然后平台插件与windows系统同步,最后再调用QCoreApplication::processEvents()传递Qts事件;
此函数非常耗时,不鼓励使用。
这个函数是在qt5.2中引入的。
[static]QWindow
*
QGuiApplication::topLevelAt(const QPoint &pos)
返回给定位置pos的顶层窗口(如果有的话)。
[static]QWindowList QGuiApplication::topLevelWindows()
返回应用程序中顶级窗口的列表。
另请参见:allWindows().
一个全局指针,指向唯一的应用程序对象。仅在该对象是QGuiApplication时有效。
参见QCoreApplication::instance()和qApp。