1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- resources.qdoc -->
<title>Qt 4.8: The Qt Resource System</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="content">
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
</div>
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li>The Qt Resource System</li>
</ul>
</div>
</div>
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#resource-collection-files">Resource Collection Files (<tt>.qrc</tt>)</a></li>
<li class="level2"><a href="#external-binary-resources">External Binary Resources</a></li>
<li class="level2"><a href="#compiled-in-resources">Compiled-In Resources</a></li>
<li class="level1"><a href="#compression">Compression</a></li>
<li class="level1"><a href="#using-resources-in-the-application">Using Resources in the Application</a></li>
</ul>
</div>
<h1 class="title">The Qt Resource System</h1>
<span class="subtitle"></span>
<!-- $$$resources.html-description -->
<div class="descr"> <a name="details"></a>
<a name="resource-system"></a><p>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.</p>
<p>The resource system is based on tight cooperation between <a href="qmake-manual.html#qmake">qmake</a>, <a href="rcc.html#rcc">rcc</a> (Qt's resource compiler), and <a href="qfile.html">QFile</a>. It obsoletes Qt 3's <tt>qembed</tt> tool and the <a href="http://qt.nokia.com/doc/qq/qq05-iconography.html#imagestorage">image collection</a> mechanism.</p>
<a name="resource-collection-files"></a>
<h2>Resource Collection Files (<tt>.qrc</tt>)</h2>
<p>The resources associated with an application are specified in a <tt>.qrc</tt> 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.</p>
<p>Here's an example <tt>.qrc</tt> file:</p>
<pre class="cpp"> <!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></pre>
<p>The resource files listed in the <tt>.qrc</tt> file are files that are part of the application's source tree. The specified paths are relative to the directory containing the <tt>.qrc</tt> file. Note that the listed resource files must be located in the same directory as the <tt>.qrc</tt> file, or one of its subdirectories.</p>
<p>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.</p>
<p>By default, resources are accessible in the application under the same file name as they have in the source tree, with a <tt>:/</tt> prefix, or by a <a href="qurl.html">URL</a> with a <tt>qrc</tt> scheme.</p>
<p>For example, the file path <tt>:/images/cut.png</tt> or the URL <tt>qrc:///images/cut.png</tt> would give access to the <tt>cut.png</tt> file, whose location in the application's source tree is <tt>images/cut.png</tt>. This can be changed using the <tt>file</tt> tag's <tt>alias</tt> attribute:</p>
<pre class="cpp"> <file alias="cut-img.png">images/cut.png</file></pre>
<p>The file is then accessible as <tt>:/cut-img.png</tt> from the application. It is also possible to specify a path prefix for all files in the <tt>.qrc</tt> file using the <tt>qresource</tt> tag's <tt>prefix</tt> attribute:</p>
<pre class="cpp"> <qresource prefix="/myresources">
<file alias="cut-img.png">images/cut.png</file>
</qresource></pre>
<p>In this case, the file is accessible as <tt>:/myresources/cut-img.png</tt>.</p>
<p>Some resources need to change based on the user's locale, such as translation files or icons. This is done by adding a <tt>lang</tt> attribute to the <tt>qresource</tt> tag, specifying a suitable locale string. For example:</p>
<pre class="cpp"> <qresource>
<file>cut.jpg</file>
</qresource>
<qresource lang="fr">
<file alias="cut.jpg">cut_fr.jpg</file>
</qresource></pre>
<p>If the user's locale is French (i.e., <a href="qlocale.html#system">QLocale::system</a>().name() returns "fr_FR"), <tt>:/cut.jpg</tt> becomes a reference to the <tt>cut_fr.jpg</tt> image. For other locales, <tt>cut.jpg</tt> is used.</p>
<p>See the <a href="qlocale.html">QLocale</a> documentation for a description of the format to use for locale strings.</p>
<a name="external-binary-resources"></a>
<h3>External Binary Resources</h3>
<p>For an external binary resource to be created you must create the resource data (commonly given the <tt>.rcc</tt> extension) by passing the -binary switch to <a href="rcc.html#rcc">rcc</a>. Once the binary resource is created you can register the resource with the <a href="qresource.html">QResource</a> API.</p>
<p>For example, a set of resource data specified in a <tt>.qrc</tt> file can be compiled in the following way:</p>
<pre class="cpp"> rcc -binary myresource.qrc -o myresource.rcc</pre>
<p>In the application, this resource would be registered with code like this:</p>
<pre class="cpp"> <span class="type"><a href="qresource.html">QResource</a></span><span class="operator">::</span>registerResource(<span class="string">"/path/to/myresource.rcc"</span>);</pre>
<a name="compiled-in-resources"></a>
<h3>Compiled-In Resources</h3>
<p>For a resource to be compiled into the binary the <tt>.qrc</tt> file must be mentioned in the application's <tt>.pro</tt> file so that <tt>qmake</tt> knows about it. For example:</p>
<pre class="cpp"> RESOURCES = application.qrc</pre>
<p><tt>qmake</tt> will produce make rules to generate a file called <tt>qrc_application.cpp</tt> 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 <tt>qrc_application.cpp</tt> file is automatically regenerated whenever the <tt>.qrc</tt> file changes or one of the files that it refers to changes. If you don't use <tt>.pro</tt> files, you can either invoke <tt>rcc</tt> manually or add build rules to your build system.</p>
<p class="centerAlign"><img src="images/resources.png" alt="Building resources into an application" /></p><p>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.</p>
<a name="compression"></a>
<h2>Compression</h2>
<p>Resources are compressed by default (in the <tt>ZIP</tt> format). It is possible to turn off compression. This can be useful if your resources already contain a compressed format, such as <tt>.png</tt> files. You do this by giving the <tt>-no-compress</tt> command line argument.</p>
<pre class="cpp"> rcc <span class="operator">-</span>no<span class="operator">-</span>compress myresources<span class="operator">.</span>qrc</pre>
<p><tt>rcc</tt> also gives you some control over the compression. You can specify the compression level and the threshold level to consider while compressing files, for example:</p>
<pre class="cpp"> rcc <span class="operator">-</span>compress <span class="number">2</span> <span class="operator">-</span>threshold <span class="number">3</span> myresources<span class="operator">.</span>qrc</pre>
<a name="using-resources-in-the-application"></a>
<h2>Using Resources in the Application</h2>
<p>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 <a href="qicon.html">QIcon</a>, <a href="qimage.html">QImage</a>, or <a href="qpixmap.html">QPixmap</a> constructor:</p>
<pre class="cpp"> cutAct <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qaction.html">QAction</a></span>(<span class="type"><a href="qicon.html">QIcon</a></span>(<span class="string">":/images/cut.png"</span>)<span class="operator">,</span> tr(<span class="string">"Cu&t"</span>)<span class="operator">,</span> <span class="keyword">this</span>);</pre>
<p>See the <a href="mainwindows-application.html">Application</a> example for an actual application that uses Qt's resource system to store its icons.</p>
<p>In memory, resources are represented by a tree of resource objects. The tree is automatically built at startup and used by <a href="qfile.html">QFile</a> for resolving paths to resources. You can use a <a href="qdir.html">QDir</a> initialized with ":/" to navigate through the resource tree from the root.</p>
<p>Qt's resources support the concept of a search path list. If you then refer to a resource with <tt>:</tt> instead of <tt>:/</tt> as the prefix, the resource will be looked up using the search path list. The search path list is empty at startup; call <a href="qdir.html#addSearchPath">QDir::addSearchPath</a>() to add paths to it.</p>
<p>If you have resources in a static library, you might need to force initialization of your resources by calling <a href="qdir.html#Q_INIT_RESOURCE">Q_INIT_RESOURCE</a>() with the base name of the <tt>.qrc</tt> file. For example:</p>
<pre class="cpp"> <span class="type">int</span> main(<span class="type">int</span> argc<span class="operator">,</span> <span class="type">char</span> <span class="operator">*</span>argv<span class="operator">[</span><span class="operator">]</span>)
{
<span class="type"><a href="qapplication.html">QApplication</a></span> app(argc<span class="operator">,</span> argv);
Q_INIT_RESOURCE(graphlib);
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
<span class="keyword">return</span> app<span class="operator">.</span>exec();
}</pre>
<p>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 <a href="qdir.html#Q_CLEANUP_RESOURCE">Q_CLEANUP_RESOURCE</a>() with the same base name as above.</p>
</div>
<!-- @@@resources.html -->
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2012 Nokia Corporation and/or its
subsidiaries. Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Nokia, Qt and their respective logos are trademarks of Nokia Corporation
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
</body>
</html>
|
