QT's Resource system

Briefly

Qt's resource system is used to store executable binaries of the application, and it takes a platform-independent mechanism. This is useful when your program always needs a series of files (icons, translation files, etc.) and you don't want to risk losing certain files.

The resource system is based on close collaboration between Qmake, RCC (Qt Resource Compiler), and QFile.

• Briefly
• Resource Collection File QRC
• External binary Resources
• Internal compilation Resources
• Compression
• Using Resources in programs
• Using Resources in the library
• More references

Resource collection file (. qrc)

Program-related resources are specified in a. qrc file, their XML-based file format lists the files on disk, and they can be assigned a resource name that an application must use when accessing resources.

The following is an example of a. qrc file:

<! 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 part of the program code tree. The specified path is relative to the directory where the. qrc file resides. Note: The resource file listed must be in the same directory as the. qrc file or its subdirectory.

The resource data can be compiled into binary, which is immediately accessible in the program code, or a binary resource is created at a later time using the resource system to register the program code.

By default, programs can access resources with the same name as the code tree, with ":/" prefix, or a URL with QRC scheme.

For example:/images/cut.png or URL qrc:///images/cut.png can access cut.png files that are located in Images/cut.png in the program code tree. You can change the access name by using the alias attribute of the file tag:

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

After that, you can use:/cut-img.png to access this file in your program. You can also use the prefix property of the Qresource tag to specify the path prefix for all files listed in the. qrc file:

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

In this case, you can use:/myresources/cut-img.png to access the file.

Some resources may need to be changed as the user's local configuration, such as: Translating files, icons, can be done by adding a lang attribute to the Qresource tag and specifying an appropriate local string. For example:

< Qresource ;  <file ;  cut.jpg< Span class= "Hljs-tag" ></file ;  </qresource ;  <qresource  lang  = "fr" ;  <file  alias  =  "cut.jpg" ;  cut_fr.jpg</ file ;  </qresource ;   

If the user's language is French (that is: Qlocale::system (). Name () returns "Fr_fr"):/cut.jpg becomes a reference to the Cut_fr.jpg file. In other languages, Cut.jpg is still used.

You can refer to the Qlocale documentation for a description of the format of the language string.

External binary Resources

To create an external binary resource, you must create the resource data (usually using the. rcc extension) by passing-binary to RCC, and once the binary resource is created, you can register the resource with the Qresource API.

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

rcc -binary myresource.qrc -o myresource.rcc

In the program, you need to register the resource with the following code:

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

Internal compilation Resources

To compile a resource into a binary file, you must explicitly specify the. qrc file in. Pro so that the qmake can be handled correctly. For example:

RESOURCES     = application.qrc

Qmake generates a make rule to generate a file that is linked to the program named Qrc_application.cpp. This file contains the data for all the pictures and other resources in a static C + + compressed binary array. The file is automatically regenerated when the qrc_application.cpp itself or its referenced resource file changes. If you do not use the. Pro file, you can call RCC manually or add a build rule for the build system.

Currently, Qt always stores resource data in an executable file, even in an operating system such as Windows, Mac os X, and IOS, which natively support resource mechanisms. May change in the future version of Qt release.

Compression

By default, the resource is compressed (in ZIP format), or you can turn off compression. This might be useful if your resource already contains a compressed format (for example:. png files). You can pass-no-compress by the command line to specify:

-no-compress myresources.qrc

RCC also gives you some control over compression, when compressing a file, you can specify the compression level and threshold level, for example:

-compress2-threshold3 myresources.qrc

Using Resources in programs

In a program, a resource path can replace a generic file system path in most cases. In particular, you can use the resource path instead of the file name to pass to the Qicon, Qimage, or Qpixmap constructor:

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

You can refer to the application sample for more information about applications that use the QT resource system to store icons.

In memory, a resource is represented by a tree of resource objects. This tree is automatically generated when the program is started and is used by QFile to parse the path to the resource. You can use the ":/" The qdir of the prefix begins to traverse the tree from the root directory.

The QT resource system supports a list of search paths. If you use: Replace:/ As a prefix, the search path list is used to search for resources. The search path list is empty when the program starts, and you can add a path to it with Qdir::addsearchpath ().

If you have resources in a static library, you need to use the. qrc file name with no suffix to call Q_init_resource () to force the initialization of the resource system. For example:

Using Resources in the library

If you have a resource in a library, you need to force the initialization of the resource system by calling Q_init_resource () with a. qrc file name without a suffix. For example:

MyClass::MyClass() : BaseClass(){    Q_INIT_RESOURCE(resources);    QFile file(":/myfile.dat");    ...}

In the case of a static link, this ensures that the resource is linked to the binary file of the final application. The initialization code should be close to where the resources in the library are used, so that if the library's clients use the library's attributes, they will only link to the resource.

Note: Because RCC initialization resource generation is declared in the global namespace, you also need to call Q_init_resource () outside of any namespace.

If the library contains unused resources internally, but leaks to the library's clients, initialization needs to occur 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, in the case of a static link, the resource is linked to the binary file of the final application and also triggers the loading of the dynamic chain, for example: Plug-ins.

Similarly, you must explicitly unload an explicitly provisioned resource (because a plugin is unloaded or the resource is no longer valid), and you can force the deletion of the resource by calling Q_cleanup_resource () with the same base name as above.

Note: It is not necessary to use Q_init_resource () and Q_cleanup_resource () when a resource is built as part of an application.

More references

• The Qt Resource SYSTEM-QT assistant

QT's Resource system