QCoreApplication 类

成员函数文档

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

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

通过 arguments() 函数处理 argc 和 argv 参数，并且以更方便的形式提供它们。

[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()。

[静态] QString QCoreApplication::applicationDirPath()

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

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

在macOS和iOS上，这将是实际包含可执行文件的目录，它可能位于应用程序包内（如果应用程序被打包）。

另请参阅 applicationFilePath()。

[静态] QString QCoreApplication::applicationFilePath()

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

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

另请参阅 applicationDirPath()。

[静态] qint64 QCoreApplication::applicationPid()

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

[静态] QStringList QCoreApplication::arguments()

返回命令行参数列表。

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

调用此函数会比较慢 - 解析命令行时，您应该将结果存储在变量中。

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

否则，从GetCommandLine()的返回值构建arguments()。因此，取决于应用程序的启动方式，arguments().at(0)提供的字符串可能在Windows上不是程序名称。

另请参阅 applicationFilePath() 和 QCommandLineParser()。

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

检查给定permission的状态。

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

该函数是在Qt 6.5版本中引入的。

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

[静态] bool QCoreApplication::closingDown()

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

另请参阅startingUp()。

[重写虚保护] bool QCoreApplication::event(QEvent *e)

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

[静态] QAbstractEventDispatcher *QCoreApplication::eventDispatcher()

返回指向主线程事件调度器的指针。如果对于此线程不存在事件调度器，则此函数返回 nullptr。

另请参阅setEventDispatcher()。

[静态] int QCoreApplication::exec()

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

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

要使您的应用程序执行空闲处理（通过在没有挂起的事件时执行一个特殊函数），请使用0超时的QTimer。更高级的空闲处理方案可以通过使用processEvents()来实现。

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

另请参阅quit，exit，processEvents和QApplication::exec。

[静态槽] void QCoreApplication::exit(int returnCode = 0)

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

在此函数被调用后，应用程序离开主事件循环并从到exec()的调用返回。该exec()函数返回returnCode。如果事件循环没有运行，此函数不做任何事情。

传统上，returnCode为0表示成功，任何非零值表示错误。

始终使用QueuedConnection将信号连接到槽是一个好习惯。如果连接（非队列的）到该槽的信号在控制进入主事件循环之前发出（例如在调用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，将生成一个LanguageChange事件，该事件针对的是QCoreApplication实例。一个QApplication实例会将事件传播到所有顶层小部件中，在可重写的changeEvent中，可以通过传递用户可见字符串并通过tr()函数传递给相应的属性设置器来重新翻译用户界面。由Qt Designer生成的用户界面类提供了一个可以调用的retranslateUi()函数。

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

另请参见：removeTranslator()，translate()，QTranslator::load()，以及动态语言更改准备。

[静态 noexcept] QCoreApplication *QCoreApplication::instance()

返回应用的QCoreApplication（或QGuiApplication和QApplication）实例的指针。

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

[静态] bool QCoreApplication::isSetuidAllowed()

如果应用被允许在UNIX平台上运行setuid，则返回TRUE。

另请参见：QCoreApplication::setSetuidAllowed。

[静态] 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插件。

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

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

对于某些类型的事件（例如鼠标和键盘事件），如果接收者对事件不感兴趣（即，它返回false），则事件将继续传播到接收者的父级，一直到顶级对象。

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

1. 重写paintEvent()、mousePressEvent()等。这是最常见、最简单且最不强大的方式。
2. 重写此函数。这非常强大，提供了完全控制；但一次只能有一个子类活跃。
3. 在QCoreApplication::instance上安装事件过滤器。这种事件过滤器能够处理所有小部件的事件，因此它和重写notify()一样强大。此外，可以安装多个全局事件过滤器。全局事件过滤器还可以看到禁用小部件的鼠标事件。请注意，应用事件过滤器只针对位于主线程的对象。
4. 以QWidget的方式重写QObject::event()。如果您这样做，您将得到Tab键的按键，并能够看到任何小部件特定事件过滤器之前的事件。
5. 在对象上安装事件过滤器。这种事件过滤器会获取所有事件，包括Tab键和Shift+Tab键的按键，只要它们不会更改焦点小部件。

未来方向：在Qt 7中，对于位于主线程之外的对象，此函数将不会被调用。需要在同时期查找其他解决方案来解决需要此功能的ólque的应用程序的事件检查需要。更改可能会扩展到主线程，导致此函数被弃用。

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

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

将事件event添加到事件队列中，并带有receiver作为事件接收者，然后立即返回。

事件必须在堆上分配，因为事件队列将接管事件，一旦事件被发布就会删除它。在发布后访问事件是不安全的。

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

事件按降序优先级排序，即具有高优先级的事件将排在前，而具有低优先级的事件排在后。优先级可以是任何整数，即从INT_MAX到INT_MIN，包括这两个值；有关更多详细信息，请参阅Qt::EventPriority。具有相同优先级的事件将按它们被发布的时间顺序进行处理。

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

另请参阅：sendEvent()，notify()，sendPostedEvents()，以及Qt::EventPriority。

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

根据指定的标志处理线程中的一些挂起的事件。

不鼓励使用此函数。相反，最好是把长时间操作从GUI线程移到一个辅助线程，并完全避免嵌套事件循环处理。如果事件处理确实是必要的，请考虑使用QEventLoop代替。

如果在运行本地循环时持续调用此函数，且没有事件循环，则不会处理DeferredDelete事件。这可能会影响依赖于DeferredDelete事件的控件的行为，例如QToolTip。作为替代方案，可以在该本地循环中调用sendPostedEvents()。

调用此函数仅处理调用线程的事件，并在所有可用事件都处理完后返回。可用事件是在函数调用之前入队的。这意味着，在函数运行期间发布的事件将排队，直到下一次事件处理的轮次。

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

另请参阅：exec()，QTimer，QEventLoop::processEvents()，以及sendPostedEvents。

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

这是一个重载函数。

对调用线程挂起的事件进行处理，直到ms毫秒或没有更多要处理的事件， whichever is shorter。

这相当于调用如下函数：

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

[静态，自6.7起] void QCoreApplication::processEvents(QEventLoop::ProcessEventsFlags flags, QDeadlineTimer deadline)

这是一个重载函数。

处理调用线程挂起事件，直到deadline过期，或直到没有更多事件要处理， whichever happens first。

不鼓励使用此函数。相反，最好是把长时间操作从GUI线程移到一个辅助线程，并完全避免嵌套事件循环处理。如果事件处理确实是必要的，请考虑使用QEventLoop代替。

调用此函数仅处理调用线程的事件。

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

此函数是在Qt 6.7中引入的。

另请参阅：exec()，QTimer，以及QEventLoop::processEvents。

[静态槽] void QCoreApplication::quit()

请求应用程序退出。

如果应用程序阻止退出，例如其中一个窗口无法关闭，请求可能被忽略。应用程序可以通过处理应用程序级别的QEvent::Quit事件或单个窗口的QEvent::Close事件来影响此行为。

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

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

始终使用QueuedConnection将信号连接到槽是一个好习惯。如果连接（非队列的）到该槽的信号在控制进入主事件循环之前发出（例如在调用exec()之前），则槽不起作用，应用程序永远不会退出。使用队列连接确保槽在控制进入主事件循环之后才会被调用。

示例

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

线程安全说明：此函数可以从任何线程调用以安全地导致当前运行的主应用程序循环退出。然而，如果同时销毁QCoreApplication对象，则不能保证线程安全。

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

另请参阅exit()和aboutToQuit

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

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

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

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

void QCoreApplication::removeNativeEventFilter(QAbstractNativeEventFilter *filterObject)

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

当此对象被销毁时，所有事件过滤器会自动被移除。

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

另请参阅installNativeEventFilter()。

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

删除为receiver使用postEvent()发布的所有给定eventType事件。

事件没有被分发，而是从队列中删除。您不需要调用此函数。如果确实调用它，请注意，删除事件可能会导致receiver破坏一个或多个不变性。

如果receiver是nullptr，则删除所有对象的eventType事件的eventType。如果eventType是0，则删除receiver的所有事件。您不应使用类型为0的eventType调用此函数。

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

[静态] bool QCoreApplication::removeTranslator(QTranslator *translationFile)

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

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

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

[自6.5起] 模板 <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() 和 应用程序权限。

[自6.5起] 模板 <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() 和 应用程序权限。

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

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

在发送事件后，事件不会被删除。通常，在堆栈上创建事件，例如

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

另请参阅：postEvent() 和 notify。

[静态] 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。

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

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

另请参阅：testAttribute()。

[静态] void QCoreApplication::setEventDispatcher(QAbstractEventDispatcher *eventDispatcher)

将主线程的事件调度器设置为 eventDispatcher。这只有在尚未安装事件调度器的情况下才可行。也就是说，在 QCoreApplication 实例化之前。此方法将获取对对象的控制权。

另请参阅：eventDispatcher()。

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

将使用 QLibrary 加载插件时搜索的目录列表设置为 paths。将删除所有现有路径，路径列表将由 paths 中提供的路径和应用程序的路径组成。

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

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

[静态] void QCoreApplication::setSetuidAllowed(bool allow)

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

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

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

另请参阅：isSetuidAllowed()。

[静态] bool QCoreApplication::startingUp()

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

另请参阅：closingDown()。

[静态] bool QCoreApplication::testAttribute(Qt::ApplicationAttribute attribute)

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

参见setAttribute。

[静态] 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 和 国际化与翻译。