Qt 资源系统

Qt 资源系统是独立于平台的机制,用于在应用程序的可执行文件中存储二进制文件。若应用程序始终需要某些特定文件 (如图标、翻译文件、等),且不想冒丢失文件的风险,这就很有用。

The resource system is based on tight cooperation between the build system, rcc (Qt 的资源编译器) 及 QFile .

资源集合文件 ( .qrc )

The resources associated with an application are specified in a .qrc file, an XML-based file format that lists files on the disk and optionally assigns them a resource name that the application must use to access the resource.

这里是范例 .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>
							

The resource files listed in the .qrc file are files that are part of the application's source tree. The specified paths are relative to the directory containing the .qrc file. Note that the listed resource files must be located in the same directory as the .qrc file, or one of its subdirectories.

Resource data can either be compiled into the binary and thus accessed immediately in application code, or a binary resource can be created and at a later point in application code registered with the resource system.

By default, resources are accessible in the application under the same file name as they have in the source tree, with a :/ prefix, or by a URL 采用 qrc scheme.

For example, the file path :/images/cut.png or the URL qrc:///images/cut.png would give access to the cut.png file, whose location in the application's source tree is images/cut.png . This can be changed using the file tag's alias attribute:

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

The file is then accessible as :/cut-img.png from the application. It is also possible to specify a path prefix for all files in the .qrc file using the qresource tag's prefix attribute:

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

In this case, the file is accessible as :/myresources/cut-img.png .

Some resources need to change based on the user's locale, such as translation files or icons. This is done by adding a lang attribute to the qresource tag, specifying a suitable locale string. For example:

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

If the user's locale is French (i.e., QLocale::system ().name() returns "fr_FR"), :/cut.jpg becomes a reference to the cut_fr.jpg image. For other locales, cut.jpg 被使用。

QLocale documentation for a description of the format to use for locale strings.

QFileSelector for an additional mechanism to select locale-specific resources, in addition to the ability to select OS-specific and other features.

外部二进制资源

For an external binary resource to be created you must create the resource data (commonly given the .rcc extension) by passing the -binary switch to rcc . Once the binary resource is created you can register the resource with the QResource API.

For example, a set of resource data specified in a .qrc file can be compiled in the following way:

rcc -binary myresource.qrc -o myresource.rcc
							

In the application, this resource would be registered with code like this:

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 project file so that the build tool knows about it.

In CMake projects, one can use CMake's built-in AUTORCC feature to add .qrc files directly as source files:

set(CMAKE_AUTORCC ON)
qt_add_executable(my_app
    application.qrc
    mainwindow.cpp)
							

CMake's AUTORCC documentation .

Qt's own CMake function qt_add_resources allows more control over the creation of resources. For example, it allows to specify the content of the resource directly in the project file without writing a .qrc file first:

qt_add_resources(my_app "app_images"
    PREFIX "/"
    FILES
        "images/copy.png"
        "images/cut.png"
        "images/new.png"
        "images/open.png"
        "images/paste.png"
        "images/save.png")
							

In qmake projects, assign the .qrc files to the RESOURCES 变量:

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.

Building resources into an application

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.

Resources in a Qt for Python application

The resource collection file is converted to a Python module by using the resource compiler rcc :

rcc -g python application.qrc > application_rc.py
							

The module needs to be imported in the application:

import application_rc.py
							

压缩

rcc attempts to compress the content to optimize disk space usage in the final binaries. By default, it will perform a heuristic check to determine whether compressing is worth it and will store the content uncompressed if it fails to sufficiently compress. To control the threshold, you can use the -threshold option, which tells rcc the percentage of the original file size that must be gained for it to store the file in compressed form.

rcc -threshold 25 myresources.qrc
							

The default value is "70", indicating that the compressed file must be 70% smaller than the original (no more than 30% of the original file size).

It is possible to turn off compression, if desired. This can be useful if your resources already contain a compressed format, such as .png files, and you do not want to incur the CPU cost at build time to confirm that it can't be compressed. Another reason is if disk usage is not a problem and the application would prefer to keep the content as clean memory pages at runtime. 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 level and compression algorithm, for example:

rcc -compress 2 -compress-algo zlib myresources.qrc
							

It is also possible to use threshold , compress ,和 compress-algo as attributes in a .qrc file tag.

<qresource>
    <file compress="1" compress-algo="zstd">data.txt</file>
</qresource>
							

The above will select the zstd algorithm with compression level 1.

rcc supports the following compression algorithms and compression levels:

  • best : use the best algorithm among the ones below, at its highest compression level, to achieve the most compression at the expense of using a lot of CPU time during compilation. This value is useful in the XML file to indicate a file should be most compressed, regardless of which algorithms rcc 支持。
  • zstd : use the Zstandard library to compress contents. Valid compression levels range from 1 to 19, 1 is least compression (least CPU time) and 19 is the most compression (most CPU time). The default level is 14. A special value of 0 tells the zstd library to choose an implementation-defined default.
  • zlib : use the zlib library to compress contents. Valid compression levels range from 1 to 9, with 1 applying the least compression (least CPU time) and 9 the most compression (most CPU time). The special value 0 means "no compression" and should not be used. The default is implementation-defined, but usually is level 6.
  • none : no compression. This is the same as the -no-compress 选项。

Support for both Zstandard and zlib are optional. If a given library was not detected at compile time, attempting to pass -compress-algo for that library will result in an error. The default compression algorithm is zstd if it is enabled, zlib if not.

在应用程序中使用资源

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 ,或 QPixmap 构造函数:

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

应用程序 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 : 而不是 :/ 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.

在库中使用资源

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.

注意: The use of Q_INIT_RESOURCE () 和 Q_CLEANUP_RESOURCE () is not necessary in the following cases:

  • When the resource is built as part of the application.
  • When the resource is built with CMake as part of a static library.