The resource system is a platform independent mechanism for storing binary files in the application's executable. This is useful if your application always needs a certain set of files (icons, translation files, etc.) and you do not want to run the risk of losing the files.

The resource system is based on tight cooperation between rcc (resource compiler) and QFile.

Resource Collection Files

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.

The following is an example of a .qrc file:

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. 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 with a 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:

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.

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.

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 is used.

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

External Binary Resources

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:

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

Compiled-In Resources

For a resource to be compiled into the binary, the .qrc file must be mentioned in your application build files.

Running make will generate a file called "qrc_application.cpp" which 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 it refers to changes.

CopperSpice stores the data directly in the executable, even on Windows and OS X, where the operating system provides native support for resources.

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.

The rcc application also gives some control over the compression. You can specify the compression level and the threshold level to consider while compressing files.

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.

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.

CopperSpice sources 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.

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

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.