The Qt Resource System

Qt资源系统是一种独立于平台的机制, 将二进制文件存储在应用程序的可执行程序中. 如果你的应用程序总需要一组特定的文件(图标, 翻译文件...), 且你不想承担丢失这些文件的风险.

资源系统基于 qmake, rcc (Qt资源编译器), QFile.

Resource Collection Files (.qrc)

应用程序关联的资源在 .qrc 文件指定, 这是一种基于XML的文件格式, 列出磁盘上的文件, 并分配应用程序访问资源的名称.

下面是 .qrc 文件示例:

  <!DOCTYPE RCC><RCC version="1.0">
  <qresource>
      <file>images/copy.png</file>
      <file>images/cut.png</file>
      <file>images/new.png</file>
      <file>images/open.png</file>
      <file>images/paste.png</file>
      <file>images/save.png</file>
  </qresource>
  </RCC>

.qrc 文件列出的资源文件是应用程序的一部分. 文件路径是相对 .qrc 文件目录的相对路径. 注意: 资源文件必须与 .qrc 文件目录同级或其子目录.

资源数据可以被编译成二进制, 在应用程序立即访问; 也可以创建二进制资源, 然后在应用程序中使用代码将其注册到资源系统.

默认情况下, 应用程序的资源可以使用与源代码的文件相同的文件名, 使用前缀 :/, 或qrc中的 URL.

例如, 文件路径 :/images/cut.png 或 qrc:///images/cut.png 都可以访问 cut.png 文件, 这个文件在应用程序的位置是 images/cut.png. 文件路径可以使用 alias 属性更改:

  <file alias="cut-img.png">images/cut.png</file>

应用程序可以使用 :/cut-img.png 访问这个文件. 你也可以使用prefix属性给.qrc 文件中的所有文件指定路径前缀:

  <qresource prefix="/myresources">
      <file alias="cut-img.png">images/cut.png</file>
  </qresource>

这个示例中, 文件的访问路径是 :/myresources/cut-img.png.

根据用户区域的不同, 一些资源可能需要更改, 如翻译文件或图标. 这个可以向 qresource 标签的添加 lang 属性, 并指定一个合适的区域字符串. 例如:

  <qresource>
      <file>cut.jpg</file>
  </qresource>
  <qresource lang="fr">
      <file alias="cut.jpg">cut_fr.jpg</file>
  </qresource>

如果用户位于法国 (即., QLocale::system().name() 返回 "fr_FR"), :/cut.jpg 变成引用 cut_fr.jpg. 其他地区, 依然使用 cut.jpg.

参考 QLocale 文档了解区域字符串的格式.

参考 QFileSelector 文档了解如何为特定区域添加选择机制, 及针对OS和其他特征添加选择机制.

外部二进制资源

对于外部二进制资源, 你必须使用rcc工具, 参数-binary创建资源数据. 创建二进制资源后, 你可以调用QResource API注册资源.

例如, 在 .qrc 文件中指定的一组资源数据可通过下列方式编译:

  rcc -binary myresource.qrc -o myresource.rcc

在应用程序中, 资源通过如下方式注册:

  QResource::registerResource("/path/to/myresource.rcc");

Compiled-In Resources

For a resource to be compiled into the binary the .qrc file must be mentioned in the application's .pro file so that qmake knows about it. For example:

  RESOURCES     = application.qrc

qmake will produce make rules to generate a file called qrc_application.cpp that is linked into the application. This file contains all the data for the images and other resources as static C++ arrays of compressed binary data. The qrc_application.cpp file is automatically regenerated whenever the .qrc file changes or one of the files that it refers to changes. If you don't use .pro files, you can either invoke rcc manually or add build rules to your build system.

Currently, Qt always stores the data directly in the executable, even on Windows, macOS, and iOS, where the operating system provides native support for resources. This might change in a future Qt release.

Compression

Resources are compressed by default (in the ZIP format). It is possible to turn off compression. This can be useful if your resources already contain a compressed format, such as .png files. You do this by giving the -no-compress command line argument.

  rcc -no-compress myresources.qrc

rcc also gives you some control over the compression. You can specify the compression level and the threshold level to consider while compressing files, for example:

  rcc -compress 2 -threshold 3 myresources.qrc

Using Resources in the Application

In the application, resource paths can be used in most places instead of ordinary file system paths. In particular, you can pass a resource path instead of a file name to the QIcon, QImage, or QPixmap constructor:

      cutAct = new QAction(QIcon(":/images/cut.png"), tr("Cu&t"), this);

See the Application example for an actual application that uses Qt's resource system to store its icons.

In memory, resources are represented by a tree of resource objects. The tree is automatically built at startup and used by QFile for resolving paths to resources. You can use a QDir initialized with ":/" to navigate through the resource tree from the root.

Qt's resources support the concept of a search path list. If you then refer to a resource with : instead of :/ as the prefix, the resource will be looked up using the search path list. The search path list is empty at startup; call QDir::addSearchPath() to add paths to it.

Using Resources in a Library

If you have resources in a library, you need to force initialization of your resources by calling Q_INIT_RESOURCE() with the base name of the .qrc file. For example:

  MyClass::MyClass() : BaseClass()
  {
      Q_INIT_RESOURCE(resources);

      QFile file(":/myfile.dat");
      ...
  }

This ensures that the resources are linked into the final application binary in the case of static linking. You should put the initialization code close to where the resources are used in your library, so that clients of your library will only link in the resources if they use the feature of the library that depends on them.

Note: As the resource initializers generated by rcc are declared in the global namespace, your calls to Q_INIT_RESOURCE() also need to be done outside of any namespace.

If the library includes resources that are not used internally, but instead exposed to clients of the library, the initialization needs to happen in the application code. For example:

  int main(int argc, char *argv[])
  {
      QApplication app(argc, argv);
      Q_INIT_RESOURCE(graphlib);

      QFile file(":/graph.png");
      ...
      return app.exec();
  }

As before, this ensures that the resources are linked into the final application binary in the case of static linking, but also triggers loading of the library in the case of dynamic linking, such as plugins.

Similarly, if you must unload a set of resources explicitly (because a plugin is being unloaded or the resources are not valid any longer), you can force removal of your resources by calling Q_CLEANUP_RESOURCE() with the same base name as above.

Note: The use of Q_INIT_RESOURCE() and Q_CLEANUP_RESOURCE() is not necessary when the resource is built as part of the application.