QCoreApplication Class

成员函数文档

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

构建一个 Qt Core 应用程序。Qt Core 应用程序是指没有图形用户界面的应用程序。此类应用程序可在控制台运行，或作为服务器进程使用。

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 的安装目录。第二个是应用程序本身的目录（而非当前目录），但仅在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()

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

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

另请参阅 applicationDirPath()。

[static noexcept] qint64 QCoreApplication::applicationPid()

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

[static] QStringList QCoreApplication::arguments()

返回命令行参数的列表。

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

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

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

否则，arguments() 将根据GetCommandLine() 的返回值进行构建。因此，在 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；若要允许 Qt 继续正常处理，则应返回 false：此时，本机事件将被转换为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() 以及《为动态语言变更做好准备》。

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

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

如果尚未分配任何实例，则返回nullptr 。

数据竞争注意事项：除非调用方代码是按 C++20 标准编译的，否则不应从辅助线程中使用此函数来检测QCoreApplication 实例是否存在。

[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 插件》。

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

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

对于某些类型的事件（例如鼠标和键盘事件），如果接收方对该事件不感兴趣（即返回false ），则该事件将传播到接收方的父对象，并依此类推直至顶级对象。

处理事件有五种不同的方式；重写此虚拟函数只是其中之一。以下列出了这五种方法：

1. 重写paintEvent()、mousePressEvent() 等方法。这是最常见、最简单但功能最弱的方式。
2. 重写此函数。这种方法功能非常强大，能够提供完全的控制权；但同一时间只能有一个子类处于活动状态。
3. 在 `QCoreApplication::instance()` 上安装一个事件过滤器。此类事件过滤器能够处理所有小部件的所有事件，因此其功能与重写 `notify()` 同样强大；此外，可以设置多个应用程序全局事件过滤器。 全局事件过滤器甚至能捕获disabled widgets 的鼠标事件。请注意，应用程序事件过滤器仅针对位于主线程中的对象被调用。
4. 重写QObject::event() 方法（如QWidget 所做的那样）。这样做可以捕获 Tab 键按下事件，并且能在任何小部件特定事件过滤器之前看到这些事件。
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之间（包含两端）；更多详细信息请参见Qt::EventPriority 。具有相同priority 的事件将按提交顺序进行处理。

QObject::connect(thread, &QThread::finished, worker, &QObject::deleteLater);

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

另请参阅 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 超时，或者直到没有更多事件需要处理，以先发生者为准。

不建议使用此函数。建议将耗时较长的操作从 GUI 线程移至辅助线程，并完全避免嵌套事件循环处理。如果确实需要处理事件，请考虑改用 `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");
QObject::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)

移除所有通过postEvent()为receiver 发布的、属于指定eventType 的事件。

这些事件不会被分发，而是直接从队列中移除。您通常无需调用此函数。若确实需要调用，请注意：强制终止事件可能会导致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(const QPermission &permission) 的形式调用functor ，其中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(const QPermission &permission) 的形式调用functor ，其中permission 描述了请求的结果。

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

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

一个 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, localPos, globalPos, Qt::LeftButton, Qt::LeftButton, Qt::NoModifier);
QCoreApplication::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 的翻译，则该函数返回QString ，其等效于sourceText 。

此函数不是虚函数。您可以通过继承QTranslator 类来使用其他翻译技术。

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

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