QCoreApplication Class

成员函数文档

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

构造一个 Qt 核心应用程序。核心应用程序是没有图形用户界面的应用程序。此类应用程序用于控制台或作为服务器进程使用。

argc 和argv 参数由应用程序处理，并通过arguments() 函数以更方便的形式提供。

[virtual noexcept] QCoreApplication::~QCoreApplication()

销毁QCoreApplication 对象。

[private signal] void QCoreApplication::aboutToQuit()

当应用程序即将退出主事件循环时（例如，当事件循环级别降为零时），就会发出该信号。这种情况可能发生在应用程序内部调用quit() 之后，也可能发生在用户关闭整个桌面会话时。

如果您的应用程序需要进行最后一秒的清理工作，该信号尤其有用。请注意，在这种状态下，用户无法进行任何交互。

另请参见 quit().

[static] void QCoreApplication::addLibraryPath(const QString &path)

将path 添加到图书馆路径列表的开头，确保首先搜索图书馆。如果path 为空或已在路径列表中，路径列表不会更改。

默认路径列表由一个或两个条目组成。第一个是插件的安装目录，即INSTALL/plugins ，其中INSTALL 是安装 Qt XML 的目录。第二个是应用程序自己的目录（不是当前目录），但只有在QCoreApplication 对象实例化之后才会出现。

当QCoreApplication 实例析构时，库路径将重置为默认路径。

另请参阅 removeLibraryPath()、libraryPaths() 和setLibraryPaths()。

[static] QString QCoreApplication::applicationDirPath()

返回包含应用程序可执行文件的目录。

例如，如果将 Qt 安装在C:\Qt 目录中，并运行regexp 示例，该函数将返回 "C:/Qt/examples/tools/regexp"。

在 macOS 和 iOS 上，这将指向实际包含可执行文件的目录，该目录可能位于应用程序捆绑包内（如果应用程序捆绑）。

在 Android 上，这将指向实际包含可执行文件的目录，该目录可能位于应用程序 APK 内（如果该程序在构建时支持未压缩的库）。

另请参见 applicationFilePath()。

[static] QString QCoreApplication::applicationFilePath()

返回应用程序可执行文件的路径。

例如，如果在/usr/local/qt 目录中安装了 Qt，并运行regexp 示例，则此函数将返回"/usr/local/qt/examples/tools/regexp/regexp"。

另请参见 applicationDirPath()。

[static] qint64 QCoreApplication::applicationPid()

返回应用程序的当前进程 ID。

[static] QStringList QCoreApplication::arguments()

返回命令行参数列表。

通常，arguments().at(0) 是程序名称，arguments().at(1) 是第一个参数，arguments().last() 是最后一个参数。请参阅下文关于 Windows 的说明。

调用该函数的速度较慢，因此在解析命令行时应将结果存储在变量中。

在 Windows 系统中，只有在向构造函数传递修改过的 argv/argc 参数时，才会从 argc 和 argv 参数建立列表。在这种情况下，可能会出现编码问题。

否则，将根据GetCommandLine() 的返回值构建 arguments()。因此，在 Windows 环境下，arguments().at(0) 所给出的字符串可能不是程序名称，这取决于应用程序是如何启动的。

另请参阅 applicationFilePath() 和QCommandLineParser 。

[since 6.5] Qt::PermissionStatus QCoreApplication::checkPermission(const QPermission &permission)

检查给定permission

如果结果是Qt::PermissionStatus::Undetermined ，则应通过requestPermission() 申请权限，以确定用户的意图。

此函数在 Qt 6.5 中引入。

另请参阅 requestPermission() 和应用程序权限。

[static] bool QCoreApplication::closingDown()

如果应用程序对象正在被销毁，则返回true ；否则返回false 。

另请参阅 startingUp() 。

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

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

[static] QAbstractEventDispatcher *QCoreApplication::eventDispatcher()

返回指向主线程事件派发器对象的指针。如果该线程不存在事件派发器，该函数将返回nullptr 。

另请参见 setEventDispatcher()。

[static] int QCoreApplication::exec()

进入主事件循环，等待exit() 被调用。返回传递给exit() 的值（如果通过quit() 调用exit() 则返回 0）。

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

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

我们建议您将清理代码连接到aboutToQuit() 信号，而不是放在应用程序的main() 函数中，因为在某些平台上，exec() 调用可能不会返回。例如，在 Windows 平台上，当用户注销时，系统会在 Qt 关闭所有顶层窗口后终止进程。因此，无法保证应用程序有时间在执行 exec() 调用后退出事件循环并在main() 函数末尾执行代码。

另请参阅 quit()、exit()、processEvents() 和QApplication::exec()。

[static slot] void QCoreApplication::exit(int returnCode = 0)

告诉应用程序以返回代码退出。

调用该函数后，应用程序将离开主事件循环，并从调用exec() 返回。exec() 函数返回returnCode 。如果事件循环未运行，则该函数不会执行任何操作。

按照惯例，returnCode 为 0 表示成功，任何非零值都表示出错。

好的做法是始终使用QueuedConnection 将信号连接到该插槽。如果在控制进入主事件循环之前（例如在 "int main "调用exec() 之前），连接（非队列）到该插槽的信号发出，则该插槽不起作用，应用程序也不会退出。使用队列连接可以确保在控件进入主事件循环之前不会调用槽。

需要注意的是，与 C 库中的同名函数不同，该函数会返回调用者--停止的是事件处理。

还要注意的是，该函数不是线程安全的。只能从主线程（QCoreApplication 对象正在处理事件的线程）调用该函数。要要求应用程序从另一个线程退出，可以使用QCoreApplication::quit() 或使用 QMetaMethod::invokeMethod() 从主线程调用该函数。

另请参阅 quit() 和exec()。

void QCoreApplication::installNativeEventFilter(QAbstractNativeEventFilter *filterObj)

为应用程序在主线程中接收到的所有本地事件安装事件过滤器filterObj 。

事件过滤器filterObj 通过其nativeEventFilter() 函数接收事件，主线程中接收到的所有本地事件都会调用该函数。

如果事件应被过滤，即停止，则QAbstractNativeEventFilter::nativeEventFilter() 函数应返回 true。如果返回 false，则允许继续进行正常的 Qt 处理：然后将本地事件转换为QEvent ，并通过标准 Qtevent 过滤（如QObject::installEventFilter() ）进行处理。

如果安装了多个事件过滤器，则先激活最后安装的过滤器。

为获得最大的可移植性，应尽可能使用QEvent 和QObject::installEventFilter() 。

另请参阅 QObject::installEventFilter()。

[static] bool QCoreApplication::installTranslator(QTranslator *translationFile)

将翻译文件translationFile 添加到用于翻译的翻译文件列表中。

可安装多个翻译文件。搜索翻译文件的顺序与安装翻译文件的顺序相反，因此先搜索最近安装的翻译文件，后搜索第一个安装的翻译文件。一旦找到包含匹配字符串的翻译文件，搜索就会停止。

安装或删除QTranslator ，或更改已安装的QTranslator 会为QCoreApplication 实例生成LanguageChange 事件。QApplication 实例会将该事件传播到所有顶层部件，而 changeEvent 的重新实现可以通过tr() 函数将用户可见字符串传递给相应的属性设置器，从而重新翻译用户界面。由Qt Widgets Designer 生成的用户界面类提供了一个可调用的retranslateUi() 函数。

该函数成功时返回true ，失败时返回 false。

另请参阅 removeTranslator()、translate()、QTranslator::load() 和Prepare for Dynamic Language Changes。

[static noexcept] QCoreApplication *QCoreApplication::instance()

返回指向应用程序QCoreApplication （或QGuiApplication/QApplication ）实例的指针。

如果没有分配实例，则返回nullptr 。

[static] bool QCoreApplication::isSetuidAllowed()

如果允许应用程序在 UNIX 平台上运行 setuid，则返回 true。

另请参阅 QCoreApplication::setSetuidAllowed().

[static] QStringList QCoreApplication::libraryPaths()

返回应用程序动态加载库时要搜索的路径列表。

创建QCoreApplication 时，该函数的返回值可能会发生变化。不建议在创建QCoreApplication 之前调用该函数。如果已知应用程序可执行文件的目录（而非工作目录），该目录将是列表的一部分。为使其为人所知，必须构建一个QCoreApplication ，因为它将使用argv[0] 来查找它。

Qt 提供了默认的库路径，但也可以使用qt.conf文件进行设置。该文件中指定的路径将覆盖默认值。请注意，如果 qt.conf 文件位于应用程序可执行文件的目录中，则在创建QCoreApplication 之前可能找不到该文件。如果调用此函数时没有找到该文件，则将使用默认的库路径。

如果存在插件安装目录，该列表将包括该目录（插件的默认安装目录是INSTALL/plugins ，其中INSTALL 是安装 Qt 的目录）。QT_PLUGIN_PATH 环境变量中以冒号分隔的条目始终会被添加。当知道应用程序可执行文件的目录时，插件安装目录（及其存在）可能会发生变化。

另请参阅 setLibraryPaths(),addLibraryPath(),removeLibraryPath(),QLibrary, 以及如何创建 Qt XML 插件。

[virtual] bool QCoreApplication::notify(QObject *receiver, QEvent *event)

向receiver 发送event ：receiver->event(event)。返回接收方事件处理程序返回的值。请注意，在任何线程中向任何对象发送的所有事件都会调用此函数。

对于某些类型的事件（如鼠标和按键事件），如果接收者对事件不感兴趣，事件将传播到接收者的父对象，并依次传播到顶层对象（即返回false ）。

有五种不同的方法可以处理事件，重新实现这个虚拟函数只是其中之一。下面列出了所有五种方法：

1. 重新实现paintEvent(),mousePressEvent() 等。这是最常见、最简单、功能最弱的方法。
2. 重新实现该函数。这种方法非常强大，可以提供完全控制；但一次只能激活一个子类。
3. 在QCoreApplication::instance() 上安装事件过滤器。这样的事件过滤器可以处理所有部件的所有事件，因此与重新实现 notify() 功能一样强大；此外，还可以拥有多个应用程序全局事件过滤器。全局事件过滤器甚至可以查看disabled widgets 的鼠标事件。请注意，应用程序事件过滤器只调用主线程中的对象。
4. 重新实现QObject::event() （如QWidget 所做）。如果这样做，就能获得按 Tab 键的事件，并能在任何特定于 widget 的事件过滤器之前看到这些事件。
5. 在对象上安装事件过滤器。这样的事件过滤器可以获取所有事件，包括 Tab 键和 Shift+Tab 键按下事件，只要它们不改变焦点部件即可。

未来方向在 Qt 7 中，主线程之外的对象将不会调用此函数。在此期间，需要该功能的应用程序应为其事件检查需求寻找其他解决方案。这一变化可能会扩展到主线程，从而导致该函数被弃用。

另请参阅 QObject::event() 和installNativeEventFilter()。

[static] void QCoreApplication::postEvent(QObject *receiver, QEvent *event, int priority = Qt::NormalEventPriority)

将事件event 以及作为事件接收者的对象receiver 添加到事件队列并立即返回。

事件必须在堆上分配，因为后事件队列将拥有事件的所有权，并在事件发布后将其删除。在事件发布后访问事件是不安全的。

当控制返回主事件循环时，将使用notify() 函数发送队列中存储的所有事件。

事件按priority 降序排序，即priority 高的事件排在priority 低的事件之前。priority 可以是任何整数值，即在 INT_MAX 和 INT_MIN 之间（含 INT_MAX）；详情请参见Qt::EventPriority 。priority 相同的事件将按照发布的顺序处理。

注意：此函数是线程安全的。

另请参阅 sendEvent(),notify(),sendPostedEvents() 和Qt::EventPriority 。

[static] void QCoreApplication::processEvents(QEventLoop::ProcessEventsFlags flags = QEventLoop::AllEvents)

根据指定的flags 处理调用线程的某些待处理事件。

不建议使用该函数。相反，最好将长操作从 GUI 线程移到辅助线程中，并完全避免嵌套事件循环处理。如果确实需要进行事件处理，请考虑使用QEventLoop 。

如果运行的本地循环连续调用该函数，而没有事件循环，DeferredDelete 事件将不会得到处理。这可能会影响依赖DeferredDelete 事件才能正常运行的部件（如QToolTip ）的行为。另一种方法是在本地循环中调用sendPostedEvents() 。

调用该函数仅处理调用线程的事件，并在处理完所有可用事件后返回。可用事件是指在函数调用之前排队的事件。这意味着，在函数运行时发布的事件将排队等待下一轮事件处理。

注意：此函数是线程安全的。

另请参阅 exec(),QTimer,QChronoTimer,QEventLoop::processEvents() 和sendPostedEvents() 。

[static, since 6.7] void QCoreApplication::processEvents(QEventLoop::ProcessEventsFlags flags, QDeadlineTimer deadline)

这是一个重载函数。

处理调用线程的待处理事件，直到deadline 过期，或没有更多事件需要处理为止，以先发生者为准。

不建议使用此函数。相反，最好将长操作从图形用户界面线程移到辅助线程中，并完全避免嵌套事件循环处理。如果确实需要进行事件处理，请考虑使用QEventLoop 代替。

调用该函数只能为调用线程处理事件。

注：此函数是线程安全的。

此函数在 Qt 6.7 中引入。

另请参阅 exec(),QTimer,QChronoTimer, 和QEventLoop::processEvents() 。

[static] void QCoreApplication::processEvents(QEventLoop::ProcessEventsFlags flags, int ms)

这是一个重载函数。

在ms 毫秒内处理调用线程的待处理事件，或直到没有更多事件要处理为止，以时间较短者为准。

这相当于调用

QCoreApplication::processEvents(flags, QDeadlineTimer(ms));

[static slot] void QCoreApplication::quit()

要求应用程序退出。

如果应用程序阻止退出，例如其中一个窗口无法关闭，该请求可能会被忽略。应用程序可以通过处理程序级的QEvent::Quit 事件或单个窗口的QEvent::Close 事件来实现这一点。

如果退出未被中断，应用程序将以返回代码 0（成功）退出。

要想在不被中断的情况下退出应用程序，请直接调用exit() 。请注意，该方法不是线程安全的。

好的做法是始终使用QueuedConnection 将信号连接到此插槽。如果在控制进入主事件循环之前（例如在 "int main "调用exec() 之前），连接（非队列）到此插槽的信号被发出，则插槽不起作用，应用程序永远不会退出。使用队列连接可以确保在控制进入主事件循环之前不会调用槽。

举例说明

QPushButton *quitButton = new QPushButton("Quit");
connect(quitButton, &QPushButton::clicked, &app, &QCoreApplication::quit, Qt::QueuedConnection);

线程安全注意事项：可以从任何线程调用此函数，以线程安全的方式退出当前运行的主应用程序循环。但是，如果同时销毁QCoreApplication 对象，则无法保证线程安全。

注意：此函数是线程安全的。

另请参阅 exit() 和aboutToQuit()。

[static] void QCoreApplication::removeLibraryPath(const QString &path)

从库路径列表中删除path 。如果path 为空或不在路径列表中，则不会更改列表。

当QCoreApplication 的实例被销毁时，库路径将重置为默认值。

另请参阅 addLibraryPath()、libraryPaths() 和setLibraryPaths()。

void QCoreApplication::removeNativeEventFilter(QAbstractNativeEventFilter *filterObject)

从该对象中删除事件filterObject 。如果未安装此类事件过滤器，则该请求将被忽略。

该对象的所有事件过滤器都会在该对象被销毁时自动移除。

删除事件过滤器始终是安全的，即使是在事件过滤器激活期间（即从 nativeEventFilter() 函数中）。

另请参见 installNativeEventFilter()。

[static] void QCoreApplication::removePostedEvents(QObject *receiver, int eventType = 0)

删除给定eventType 的所有事件，这些事件已通过postEvent() 发布到receiver 。

这些事件不会被派发，而是从队列中移除。您不需要调用此函数。如果确实需要调用，请注意杀死事件可能会导致receiver 破坏一个或多个不变式。

如果receiver 为nullptr ，则会删除eventType 中所有对象的事件。如果eventType 为 0，则会删除receiver 的所有事件。切勿在eventType 为 0 时调用此函数。

注意：此函数是线程安全的。

[static] bool QCoreApplication::removeTranslator(QTranslator *translationFile)

从本程序使用的翻译文件列表中删除翻译文件translationFile 。(但不会从文件系统中删除翻译文件）。

函数成功时返回true ，失败时返回 false。

另请参阅 installTranslator()、translate() 和QObject::tr()。

[since 6.5] template <typename Functor> void QCoreApplication::requestPermission(const QPermission &permission, Functor &&functor)

请求给定的permission 。

当请求准备就绪时，functor 将作为functor(const QPermission &permission) 被调用，permission 描述请求的结果。

functor 可以是独立或静态的成员函数：

qApp->requestPermission(QCameraPermission{}, &permissionUpdated);

或 lambda：

qApp->requestPermission(QCameraPermission{}, [](const QPermission &permission) {
});

如果用户明确授予应用程序所请求的permission ，或已知permission 在给定平台上不需要用户授权，则状态为Qt::PermissionStatus::Granted 。

如果用户明确拒绝应用程序请求的permission ，或已知permission 在给定平台上无法访问或不适用于应用程序，则状态为Qt::PermissionStatus::Denied 。

请求的结果永远不会是Qt::PermissionStatus::Undetermined 。

此函数在 Qt 6.5 中引入。

另请参阅 checkPermission() 和应用程序权限。

[since 6.5] template <typename Functor> void QCoreApplication::requestPermission(const QPermission &permission, const QObject *context, Functor functor)

在context 的上下文中请求给定的permission 。

请求完成后，functor 将作为functor(const QPermission &permission) 被调用，permission 描述请求的结果。

functor 可以是独立成员函数，也可以是静态成员函数：

qApp->requestPermission(QCameraPermission{}, context, &permissionUpdated);

a lambda：

qApp->requestPermission(QCameraPermission{}, context, [](const QPermission &permission) {
});

或context 对象中的一个槽：

qApp->requestPermission(QCameraPermission{}, this, &CamerWidget::permissionUpdated);

functor 将在context 对象的线程中调用。如果context 在请求完成前被销毁，则不会调用functor 。

如果用户明确授予应用程序所请求的permission ，或已知permission 在给定平台上不需要用户授权，则状态为Qt::PermissionStatus::Granted 。

如果用户明确拒绝应用程序请求的permission ，或已知permission 在给定平台上无法访问或不适用于应用程序，则状态为Qt::PermissionStatus::Denied 。

请求的结果永远不会是Qt::PermissionStatus::Undetermined 。

这是一个重载函数。

该函数在 Qt 6.5 中引入。

另请参阅 checkPermission() 和应用程序权限。

[static] bool QCoreApplication::sendEvent(QObject *receiver, QEvent *event)

使用notify() 函数将事件event 直接发送给接收器receiver 。返回事件处理程序返回的值。

事件发送完毕后，事件不会被删除。通常的做法是在堆栈中创建事件：

QMouseEvent event(QEvent::MouseButtonPress, pos, 0, 0, 0);
QApplication::sendEvent(mainWindow, &event);

另请参见 postEvent() 和notify()。

[static] void QCoreApplication::sendPostedEvents(QObject *receiver = nullptr, int event_type = 0)

立即分派所有先前已用QCoreApplication::postEvent() 排好队列的事件，这些事件针对对象receiver 且事件类型为event_type 。

来自窗口系统的事件不是由该函数调度，而是由processEvents() 调度。

如果receiver 为nullptr ，则event_type 的事件将针对所有对象发送。如果event_type 为 0，则会为receiver 发送所有事件。

另请参阅 postEvent() 。

[static] void QCoreApplication::setAttribute(Qt::ApplicationAttribute attribute, bool on = true)

如果on 为 true，则设置属性attribute ；否则清除属性。

另请参阅 testAttribute()。

[static] void QCoreApplication::setEventDispatcher(QAbstractEventDispatcher *eventDispatcher)

将主线程的事件派发器设置为eventDispatcher 。只有在尚未安装事件派发器的情况下才有可能这样做。也就是说，在QCoreApplication 被实例化之前。该方法将获取对象的所有权。

另请参阅 eventDispatcher()。

[static] void QCoreApplication::setLibraryPaths(const QStringList &paths)

通过QLibrary 至paths 设置加载插件时要搜索的目录列表。所有现有路径将被删除，路径列表将由paths 中给出的路径和应用程序路径组成。

当QCoreApplication 实例被销毁时，库路径将重置为默认路径。

另请参阅 libraryPaths()、addLibraryPath()、removeLibraryPath() 和QLibrary 。

[static] void QCoreApplication::setSetuidAllowed(bool allow)

如果allow 为 true，则允许应用程序在 UNIX 平台上运行 setuid。

如果allow 为 false（默认值），且 Qt 检测到应用程序以不同于真实用户 ID 的有效用户 ID 运行，则在创建QCoreApplication 实例时将中止应用程序。

由于 Qt 的攻击面较大，因此它并不是setuid 程序的合适解决方案。但出于历史原因，某些应用程序可能需要以这种方式运行。该标记将防止 Qt 在检测到这种情况时中止应用程序，必须在创建QCoreApplication 实例之前设置该标记。

另请参阅 isSetuidAllowed().

[static] bool QCoreApplication::startingUp()

如果应用程序对象尚未创建，则返回true ；否则返回false 。

另请参阅 closingDown() 。

[static] bool QCoreApplication::testAttribute(Qt::ApplicationAttribute attribute)

如果属性attribute 已设置，则返回true ；否则返回false 。

另请参阅 setAttribute() 。

[static] QString QCoreApplication::translate(const char *context, const char *sourceText, const char *disambiguation = nullptr, int n = -1)

通过查询已安装的翻译文件，返回sourceText 的翻译文本。翻译文件将从最近安装的文件搜索到第一个安装的文件。

QObject::tr() 提供了更方便的功能。

context 是典型的类名（如 "MyDialog"）， 是英文文本或简短的标识文本。sourceText

disambiguation 是一个标识字符串，用于在同一上下文的不同角色中使用同一个 。默认情况下，它是 。sourceText nullptr

有关上下文、消歧和注释的更多信息，请参阅QTranslator 和QObject::tr() 文档。

n 与 结合使用，以支持复数形式。详见 () 。%n QObject::tr

如果在context 中没有任何翻译文件包含sourceText 的翻译，则此函数返回与sourceText 对应的QString 。

此函数不是虚拟函数。您可以通过子类化QTranslator 使用其他翻译技术。

注意：此函数是线程安全的。

另请参阅 QObject::tr()、installTranslator()、removeTranslator() 和Internationalization and Translations 。