The Resource Compiler (RCC) is a CopperSpice executable which is used to embed files during the build process of your application. The input to RCC is a file in an XML format. The base name can be anything however the file extension must be qrc.

RCC will compile the *.qrc file into a qrc_*.cpp source file.

When your executable is created the files listed in the resource file are bundled into the executable. The original files, which are now embedded, do not need to be distributed with the binary. The most common type of files include images, text, icons, and translation files.

The files listed in the .qrc must be physically located in the same directory as the .qrc file or a subdirectory. If a path is specified in the <file> element it is relative to the directory containing the .qrc file.

Refer to our Sample CMake File and review the lines which reference the hellolunch qrc file.

For a complete example refer to the CopperSpice KitchenSink build files.

RCC Usage

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 size is greater than the threshold it is compressed. The default threshold 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

Using Resources in your Application

The following sections show different ways to access the contents of a Resource file.

(1) Image File

Files listed in the qrc file are embedded in your application and can be accessed as if the file existed in a virtual directory named : (colon).

The following code passes the name of a png image to the constructor of QIcon. The png file must be physically located in a directory called images when compiling your application. The images directory is relative to the location of the qrc file.

The following shows the contents of the corresponding qrc file.

(2) Traversing a Resource File

QDir can be used to walk through every file which was listed in a qrc file. Construct a QDir and pass ":/" as the first parameter, which is the initial path.

(3) Prefix

Using the qrc file shown below the image can be specified in your application with a prefix or a URL.

• :/images/plus.png

• qrc:///images/plus.png

(4) Alias

The <file> element can define an alias or alternative name. In your application the image can be accessed by using :/myImageName.png

(5) Prefix

A path prefix can be specified for a group of files using the qresource prefix attribute. In your application the file is accessible by using :/myFiles/images/paste.png

(6) Locale Specific

Using a particular file may depend on information about the current locale, which is only available at run time. In the following example a different text file will be used if the user's locale is set to German or French.

If the locale is German then :/words.txt will actually refer to the file words_de.txt.

If the locale is French then the words_fr.txt will used and for all other locales the default text file will be used.

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:

In your application this resource file is registered using the following code:

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 allows some control over the compression by specifying the compression level and the threshold level to consider while compressing files.