QCoreApplication Class

成员函数

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

构造一个Qt内核程序. 内核程序是没有图形用户界面的程序. 这样的程序使用控制台, 或者是作为服务进程运行.

argc 和 argv 参数将会被应用程序处理, 将其转换为一种更加便捷的形式, 调用 arguments() 函数获取.

警告: argc and argv 所指向的内存必须在整个 QCoreApplication 生命周期内有效. 另外, argc 必须要大于0, argv 必须至少包含一个合法的字符串.

QCoreApplication::~QCoreApplication()

Destroys the QCoreApplication object.

[signal] void QCoreApplication::aboutToQuit()

当程序即将退出主消息循环时发出这个信号, 如. 消息循环嵌套层数降为0. 它可能发生在应用程序中调用 quit(), 或用户关闭整个桌面会话时.

当你的应用程序必须有些最后的清理工作, 这个信号特别有用. 注意在这个状态, 不能有用户界面.

注意: 这是一个私有信号. 它能够被连接, 但是用户无法发出它.

参见 quit().

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

将 path 添加到库路径开头, 保证它先会被库搜索到. 如果 path 为空或者已经存在于路径列表, 那么路径列表保持不变.

默认的路径列表只包含一个路径, 即插件安装路径. 默认的插件安装路径是 INSTALL/plugins, 其中 INSTALL 是Qt安装路径.

QCoreApplication 销毁后, 这些库路径将会被重设为默认值.

参见 removeLibraryPath(), libraryPaths(), setLibraryPaths().

[static] QString QCoreApplication::applicationDirPath()

返回包含可执行文件的目录.

例如, 如果你已经将 Qt 安装在 C:\Qt 目录下, 你运行 regexp 时, 那么这个函数返回 "C:/Qt/examples/tools/regexp".

在 macOS 和 iOS 上, 它会指向实际包含可执行文件的目录, 这个目录可能在一个应用程序包内 (如果是以应用程序包形式存在).

警告: 在Linux上, 这个函数尝试从 /proc 获取文件目录. 如果失败, 那么它假设 argv[0] 包含了可执行文件的绝对路径. 此函数同样也假设应用程序不会改变当前路径.

参见 applicationFilePath().

[static] QString QCoreApplication::applicationFilePath()

返回包含可执行文件的文件路径.

例如, 如果你已经将 Qt 安装在 /usr/local/qt 目录下, 你运行 regexp 时, 那么这个函数返回 "/usr/local/qt/examples/tools/regexp/regexp".

警告: 在Linux上, 这个函数尝试从 /proc 获取文件目录. 如果失败, 那么它假设 argv[0] contains the absolute 包含了可执行文件的绝对路径. 此函数同样也假设应用程序不会改变当前路径.

参见 applicationDirPath().

[static] qint64 QCoreApplication::applicationPid()

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

这个函数自 4.4 引入.

[static] QStringList QCoreApplication::arguments()

返回命令行参数列表.

一般情况下, arguments().at(0) 表示可执行文件名, arguments().at(1) 是第一个参数, arguments().last() 是最后一个参数. 参见下面关于 Windows 的注释.

调用这个函数需要花费很多时间——你应该在解析命令行时, 将结果缓存起来.

警告: 在Unix下, 这个参数列表由 main() 函数中的 argc 和 argv 参数生成. argv中的字符串数据调用QString::fromLocal8Bit()解析, 因此, 在 Latin1 的区域环境下, 是不可能来传递日语的命令行的, 其他情况以此类推. 大部分现代 Unix 系统没有此限制, 因为它们是基于 Unicode.

在Windows下, 这个参数列表只有在构造函数中传入了修改的argc和argv时, 才会从这个argc和argv中解析. 这种情况下, 可能出现编码问题.

除此之外, arguments()会从GetCommandLine()中构造. 此时arguments().at(0)在Windows下未必是可执行文件名, 而是取决于程序是如何被启动的.

这个函数自 Qt 4.1 引入.

参见 applicationFilePath() and QCommandLineParser.

[static] bool QCoreApplication::closingDown()

如果application对象正在被销毁, 则返回 true; 否则返回 false.

参见 startingUp().

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

重新实现 QObject::event().

[static] QAbstractEventDispatcher *QCoreApplication::eventDispatcher()

返回指向主线程事件派发器的指针. 如果线程中没有事件派发器, 则返回 nullptr.

参见 setEventDispatcher().

[static] int QCoreApplication::exec()

进入主消息循环, 直到 exit() 被调用. 返回值是 exit() 的传入参数 (如果调用 quit(), 则等价于调用exit(0) ).

调用这个函数开始事件循环是很有必要的. 主线程事件循环将从窗口系统接收事件, 并派发给应用程序下的widget.

为了能让你的程序在空闲时处理事件 (在没有待处理的事件时, 调用一个特殊的函数), 你可以使用一个超时为 0 的QTimer. 你可以使用 processEvents() 进一步处理空闲事件.

我们建议你连接 aboutToQuit() 信号来做一些清理工作, 而不是将它们放在 main() 函数中, 因为在某些平台下, exec() 可能不会返回. 例如, 在 Windows 下, 当用户注销时, 系统将在Qt关闭所有顶层窗口后才终止进程. 因此, 不能保证程序有时间退出其消息循环来执行 main() 函数中 exec() 之后的代码.

参见 quit(), exit(), processEvents(), QApplication::exec().

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

告诉程序需要退出, 并传入一个返回值.

在此函数被调用后, 程序将离开主消息循环, 并且从 exec() 中返回. exec() 的返回值是 returnCode. 如果消息循环没有运行, 那么此方法什么都不做.

一般而言, returnCode 是 0 表示成功, 非 0 表示产生了一个错误.

Note that unlike the C library function of the same name, this function does return to the caller -- it is event processing that stops.

参见 quit() and exec().

void QCoreApplication::installNativeEventFilter(QAbstractNativeEventFilter *filterObj)

在主线程中, 为应用程序所能接收到的原生事件安装一个事件过滤器 filterObj.

事件过滤器 filterObj 通过 nativeEventFilter() 接收事件, 它可以接收到主线程所有的原生事件.

如果某个原生事件需要被过滤或被屏蔽, 那么 QAbstractNativeEventFilter::nativeEventFilter() 应该返回true, 即. 停止. 如果它需要使用Qt默认处理流程, 则返回 false: 那么接下来这个原生事件则会被翻译为一个 QEvent, 并且由Qt的标准事件过滤器 event 处理, 如. QObject::installEventFilter().

如果有多个事件过滤器被安装, 那么最后安装的过滤器将会被最先调用.

注意: 此处设置的过滤器功能接收原生事件, 即. MSG 或 XCB 事件结构.

注意: 如果设置 Qt::AA_PluginApplication 属性, 那么原生事件过滤器将被屏蔽.

为了最大可能保持可移植性, 你应该总是尽可能使用 QEvent 和 QObject::installEventFilter().

This function was introduced in Qt 5.0.

参见 QObject::installEventFilter().

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

将 translationFile 添加到翻译文件列表, 它将会被用于翻译.

你可以安装多个翻译文件. 这些翻译文件将会按照安装顺序的逆序被搜索到, 因此最近添加的翻译文件会首先被搜索到, 第一个安装的搜索文件会最后被搜索. 一旦翻译文件中匹配了一个字符串, 那么搜索就会终止.

安装或移除一个 QTranslator, 或者更改一个已经安装的 QTranslator 将会为 QCoreApplication 实例产生一个LanguageChange 事件. 一个 QGuiApplication 会将这个事件派发到所有的顶层窗体, 使用 tr() 来传递用户可见的字符串到对应的属性设置器, 通过这种方式来重新实现 changeEvent 则可以重新翻译用户的界面. 通过 Qt Designer 生成的窗体类提供了一个 retranslateUi() 可以实现上述效果.

函数若执行成功, 则返回 true, 否则返回 false.

参见 removeTranslator(), translate(), QTranslator::load(), Dynamic Translation.

[static] QCoreApplication *QCoreApplication::instance()

返回程序的 QCoreApplication (或 QGuiApplication/QApplication) 实例的指针.

若没有创建实例, 返回 nullptr.

[static] bool QCoreApplication::isSetuidAllowed()

如果在UNIX平台中, 允许应用程序使用 setuid, 则返回 true.

This function was introduced in Qt 5.3.

参见 QCoreApplication::setSetuidAllowed().

[static] QStringList QCoreApplication::libraryPaths()

返回一个路径列表, 其中的路径表示动态加载链接库时的搜索路径.

此函数的返回值也许会在 QCoreApplication 创建之后改变. 因此不建议在 QCoreApplication 创建之前调用. 如果应用程序所在的路径 (非 工作路径) 是已知的, 那么它会被放入列表中. 为了能知道这个路径, QCoreApplication 必须要在创建时使用 argv[0] 表示此路径.

Qt 提供默认的库搜索路径, 但是它们同样也可以通过 qt.conf 文件配置. 在此文件中所指定的路径会覆盖默认路径. 注意如果 qt.conf 文件存在于应用程序所在的文件夹目录下, 那么直到 QCoreApplication 被创建时它才可以被发现. 如果它没有被发现, 那么调用此函数仍然返回默认搜索路径.

如果插件存在, 那么这个列表会包含插件安装目录 (默认的插件安装目录是 INSTALL/plugins, 其中 INSTALL 是Qt所安装的目录). 用分号分隔的 QT_PLUGIN_PATH 环境变量中的路径一定会被添加到列表. 插件安装目录 (以及它存在) 在应用程序目录已知时可能会被更改.

如果你想遍历列表, 可以使用 foreach 伪关键字:

  foreach (const QString &path, app.libraryPaths())
      do_something(path);

参见 setLibraryPaths(), addLibraryPath(), removeLibraryPath(), QLibrary, How to Create Qt Plugins.

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

发送 event 给 receiver: receiver->event(event). 返回值为接受者的事件处理器的返回值. 注意这个函数将会在任意线程中调用, 并将事件转发给任意对象.

对于一些特定的事件 (如. 鼠标和键盘事件), 如果事件处理器不处理此事件 (即., 它返回 false), 那么事件会被逐级派发到对象的父对象, 一直派发到顶层对象.

处理事件有5种不同的方式; 重写虚函数只是其中一种. 所有的五种途径如下所示:

1. 重写 paintEvent(), mousePressEvent() 等. 这个是最通用, 最简单但最不强大的一种方法.
2. 重写此函数. 这非常强大, 提供了完全控制; 但是一次只能激活一个子类.
3. 在 QCoreApplication::instance() 安装一个事件过滤器. 这样的一个事件过滤器可以处理所有窗体的所有事件，就像是重写 notify() 函数一样强大; 此外, 你还可以提供多个应用级别全局的事件过滤器. 全局事件过滤器甚至可以接收到那些 disabled widgets 的鼠标事件. 注意程序的事件过滤器仅能响应主线程中的对象.
4. 重写 QObject::event() (就像 QWidget 那样). 如果你是这样做的, 你可以接收到Tab按键, 及你可以在任何特定窗体的事件过滤器被调用之前接收到事件.
5. 在对象上安装事件过滤器. 这样的事件过滤器将可以收到所有事件, 包括 Tab 和 Shift + Tab 事件, 只要它们不更改窗体的焦点.

未来规划: 在Qt 6中, 这个函数不会响应主线程之外的对象. 需要该功能的应用程序应同时为其事件检查需求找到其他解决方案. 这个更改可能会扩展到主线程, 因此不建议使用此功能.

注意: 如果你重写此函数, 在你的应用程序开始析构之前, 你必须保证所有正在处理事件的线程停止处理事件. 这包括你可能在用的其他库所创建的线程, 但是不适用于Qt自己的线程.

参见 QObject::event() 和 installNativeEventFilter().

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

添加一个 event 事件, 其中 receiver 表示事件的接收方, 事件被添加到消息队列, 并立即返回.

被添加的事件必须被分配在堆上, 这样消息队列才能接管此事件, 并在它被投送之后删除它. 当它被投递之后, 再来访问此事件是 不安全 的.

当程序流程返回到了主事件循环时, 所有的队列中的事件会通过 notify() 发送.

队列中的事件按照 priority 降序排列, 即. 高优先级 的事件将排列于 低优先级 之前. 优先级 可以是任何整数, 即. 值的取值范围在 INT_MAX 和 INT_MIN 之间, 闭区间; 详见 Qt::EventPriority. 优先级 相同的事件按照投送顺序处理.

注意: 这个函数是 线程安全的

This function was introduced in Qt 4.3.

参见 sendEvent(), notify(), sendPostedEvents(), and Qt::EventPriority.

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

根据 flags 处理调用线程的所有待处理事件, 直到没有事件需要处理.

在程序中, 你可以在处理长时间操作的时候偶尔调用这个函数 (如. 复制文件).

如果你在一个本地循环中持续调用这个函数，而不是在消息循环中, 那么 DeferredDelete 事件不会被处理. 这会影响到一些窗体的行为, 如. QToolTip, 它依赖 DeferredDelete 事件, 以使其正常运行. 一种替代方法是从该本地循环中调用 sendPostedEvents().

此函数只处理调用线程的事件, 当所有可处理事件处理完毕之后返回. 可用事件是在函数调用之前排队的事件. 这意味着在函数运行时投送的事件将会排队到下一轮事件处理为止.

注意: 这个函数是 线程安全的

参见 exec(), QTimer, QEventLoop::processEvents(), flush(), sendPostedEvents().

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

重写 processEvents().

这个函数将用 maxtime 毫秒为调用线程处理待处理的事件, 或者直到没有更多事件需要处理.

在程序中, 你可以在处理长时间操作的时候偶尔调用这个函数 (如. 复制文件).

此函数只处理调用线程的事件.

注意: 这个函数是 线程安全的

参见 exec(), QTimer, QEventLoop::processEvents().

[static slot] void QCoreApplication::quit()

告知程序以返回值 0 退出. 等效于调用 QCoreApplication::exit(0).

一般我们将 quit() 槽连接到 QGuiApplication::lastWindowClosed(), 你也可以将此槽连接到其他信号上. 如. QAbstractButton::clicked() 或 QAction, QMenu, or QMenuBar 上的信号.

示例:

  QPushButton *quitButton = new QPushButton("Quit");
  connect(quitButton, SIGNAL(clicked()), &app, SLOT(quit()));

参见 exit(), aboutToQuit(), QGuiApplication::lastWindowClosed().

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

从库的搜索路径列表中移除 path. 如果 path 是空的, 或者不存在于列表, 则列表不会改变.

QCoreApplication 被析构时, 此列表会被还原.

参见 addLibraryPath(), libraryPaths(), setLibraryPaths().

void QCoreApplication::removeNativeEventFilter(QAbstractNativeEventFilter *filterObject)

从此实例中移除 filterObject 事件过滤器. 如果这个事件过滤器没有被安装, 则什么也不做.

当此实例被销毁时, 所有的事件过滤器都会自动被移除.

任何时候, 甚至正在事件过滤被激活时 (i.e. 在 nativeEventFilter() 函数中), 移除一个事件过滤器都是安全的.

This function was introduced in Qt 5.0.

参见 installNativeEventFilter().

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

移除所指定的 eventType 类型且由 postEvent() 为 receiver 所添加的事件.

这些事件不会被派发, 而是直接从队列中移除. 你从来都不需要调用此方法. 如果你确实调用了它, 那么请注意杀掉事件可能会影响 receiver 的不变性.

如果 receiver 是 null, 那么所有对象将会移除 eventType 所指定的所有事件. 如果 eventType 是 0, 那么 receiver 的所有事件将会被移除. 自始自终, 你都不应将 0 传递给 eventType. 如果你确实调用了它, 那么请注意杀掉事件可能会影响 receiver 的不变性.

注意: 这个函数是 线程安全的

This function was introduced in Qt 4.3.

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

从此应用程序使用的翻译文件列表中删除翻译文件 translationFile. (这个函数不会在文件系统中删除此翻译文件.)

该函数成功时返回 true, 失败时返回 false.

参见 installTranslator(), translate(), QObject::tr().

[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 = Q_NULLPTR, int event_type = 0)

立刻分派所有先前通过 QCoreApplication::postEvent() 进入队列的事件. 这些事件是针对 receiver , 且事件类型为 event_type.

Events from the window system are not dispatched by this function, but by processEvents().

如果 receiver 是 null, event_type 的所有事件将分派到所有对象. 如果 event_type 是 0, 所有事件将发送到接收对象 receiver.

注意: 该方法必须由receiver 所在线程调用.

参见 flush() and 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)

将加载库时要搜索的目录列表设置为 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 实例之前将其设置.

注意: 强烈建议不要打开此选项, 它会带来安全风险.

This function was introduced in Qt 5.3.

参见 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 = Q_NULLPTR, int n = -1)

搜索最近到首次安装的翻译文件, 查询翻译文件中 sourceText对应的翻译内容, 返回其结果.

QObject::tr() 作用相同且使用更便捷.

context 通常为类名 (如., "MyDialog"), sourceText 则是英文文本或简短的识别文本.

disambiguation 为一段识别字符串, 用于同一上下文中不同角色使用相同的 sourceText. 它的默认值为 null.

有关上下文、消除歧义和注释的更多信息, 详见 QTranslator 和 QObject::tr().

n 和 %n 一并使用以便支持复数形式. 详见 QObject::tr().

如果没有任何翻译文件包含 context 中的 sourceText, 该函数则返回 sourceText.

此函数不是虚函数. 你可以子类化 QTranslator 来使用其他翻译技术.

Warning: This method is reentrant only if all translators are installed before calling this method. Installing or removing translators while performing translations is not supported. Doing so will most likely result in crashes or other undesirable behavior.

注意: 这个函数是reentrant

参见 QObject::tr() and installTranslator().

  static int *global_ptr = 0;

  static void cleanup_ptr()
  {
      delete [] global_ptr;
      global_ptr = 0;
  }

  void init_ptr()
  {
      global_ptr = new int[100];      // allocate data
      qAddPostRoutine(cleanup_ptr);   // delete later
  }

  class MyPrivateInitStuff : public QObject
  {
  public:
      static MyPrivateInitStuff *initStuff(QObject *parent)
      {
          if (!p)
              p = new MyPrivateInitStuff(parent);
          return p;
      }

      ~MyPrivateInitStuff()
      {
          // cleanup goes here
      }

  private:
      MyPrivateInitStuff(QObject *parent)
          : QObject(parent)
      {
          // initialization goes here
      }

      MyPrivateInitStuff *p;
  };

  // Called once QCoreApplication exists
  static void preRoutineMyDebugTool()
  {
      MyDebugTool* tool = new MyDebugTool(QCoreApplication::instance());
      QCoreApplication::instance()->installEventFilter(tool);
  }

  Q_COREAPP_STARTUP_FUNCTION(preRoutineMyDebugTool)

  static inline QString tr(const char *sourceText,
                           const char *comment = 0);
  static inline QString trUtf8(const char *sourceText,
                               const char *comment = 0);

  class MyMfcView : public CView
  {
      Q_DECLARE_TR_FUNCTIONS(MyMfcView)

  public:
      MyMfcView();
      ...
  };