CopperSpice Overview  1.5.2
RCC

The resource system is a platform independent mechanism for storing binary files in the application's executable. This is useful when your application requires specific files. These files can be icons, translation files, images, etc.

The Resource Compiler is used to embed resources into a CopperSpice application during the build process. It works by generating a C++ source file containing data specified in a resource (.qrc) file.

RCC Usage

rcc [options] <inputs>

RCC accepts the following command line options:

Option Argument Description
-o file Write output to <file> instead of stdout
-name name Create an external initialization function with <name>
-threshold level Specifies a threshold <level> as a percentage to use when deciding whether to compress a file. If the reduction in the file size is greater than the threshold <level>, it is compressed. Otherwise, the uncompressed data is stored as is.

The default threshold level is 70%, which means the compressed files which are 30% or less of their original size are stored as compressed data.
-compress level Compress input files to the specified compression <level>
Level 1 does the least compression and is the fastest
Level 9 does the most compression and is the slowest
To turn off compression use {-no-compress}

The default value for <level> is -1, which means use zlib's default compression level
-no-compress Disable compression
-root path Prefix the resource name with path, the default is no prefix
-binary Output a binary file for use as a dynamic resource
-version Display version number
-help Display usage information

Resource Files

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

The files specified in the .qrc must be located in the same directory as the .qrc file, or one of its subdirectories. If a path is specified, it is relative to the directory containing the .qrc file.

Resources can be compiled into the binary and accessed immediately in application code. Alternatively, a binary resource can be created and registered with the resource system at run time.

For a sample .qrc refer to Sample Project

How to use a Resource

Resources are accessible in your application under the same file name as they appear in your source tree. These files can be specified with a prefix or as a URL.


(1) Given the file name <your_app>/images/cut.png, the resource is accessed by either of the following:

  • :/images/cut.png
  • qrc:///images/cut.png


(2) A resource can also be accessed using an alias. The following line goes in your .qrc file.

<file alias="cut_alias.png">images/cut.png</file>

The file is then accessible as :/cut_alias.png from the your application.


(3) A path prefix can be specified for all files in the .qrc file using the qresource prefix attribute.

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

In this case the file is accessible as :/myresources/cut_alias.png.


(4) 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 and 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, :/cut.jpg becomes a reference to the cut_fr.jpg image. The locale can be queried by calling QLocale::system().name(), which in this case will return "fr_FR".

For other locales cut.jpg will be displayed.

External Binary Resources

For an external binary resource you must create the resource data (commonly given the .rcc extension) by passing the -binary switch to rcc. Once the binary resource is created, 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 your application this resource file is registered using the following code:

QResource::registerResource("/your_app/myresource.rcc");

Compiled In Resources

For a resource to be compiled into your application the .qrc file must be listed in your Makefile.am file. For example:

RESOURCES = application.qrc

The .qrc 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.

Compression

Resources are compressed by default. Compression can be turned off if required. This can be useful if your resources already are compressed, such as .png files. This can be specified by supplying the -no-compress command line argument to rcc.

rcc -no-compress myresources.qrc

Rcc allows some control over the compression by specifying the compression level and the threshold level to consider while compressing files. For example:

rcc -compress 2 -threshold 3 myresources.qrc

Using Resources in your Application

Resources can be used instead of ordinary file name. A resource path can be passed to QIcon, QImage, or QPixmap constructor.

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

You can use QDir initialized with ":/" to navigate through the resource tree from the root.

If you 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 a path to the search path.

If you have resources in a static library call 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();
}

To unload a set of resources, call Q_CLEANUP_RESOURCE() with the same base name as above.