Qt 4.0: The Qt Resource System

|  | Home · All Classes · Main Classes · Grouped Classes · Modules · Functions |

# The Qt Resource System

The Qt 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 don't want to run the risk of losing the files.

The resource system is based on tight cooperation between `qmake`, `rcc` (Qt's resource compiler), and QFile. It obsoletes Qt 3's `qembed` tool and the image collection mechanism.

## Resource Collection Files (`.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.

Here's an example `.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 files that are part of the application's source tree. Paths are relative to the directory where the `.qrc` file is located.

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 and Mac OS X, where the operating system provides native support for resources. This might change in a future Qt release.

By default, resources are accessible in the application under the same name as they have in the source tree, with a `:/` prefix. For example, the path `:/image/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, such as translation files and icons, many need to change based on the user's locale. This is possible using the `lang` attribute. 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` is used.

## 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::addResourceSearchPath() 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. For example:

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

Note: Once a QResource has been loaded into the Qt resource tree (either implicitly or via Q_INIT_RESOURCE) it will only be unloaded upon application termination. This means using resources in a plugin can cause some known errors, this restriction will be removed with Qt 4.1 QResource system.