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
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
|
/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\group io
\title Input/Output and Networking
\ingroup groups
\brief Classes providing file input and output along with directory and
network handling.
These classes are used to handle input and output to and from external
devices, processes, files etc. as well as manipulating files and directories.
*/
/*!
\page resources.html
\title The Qt Resource System
\ingroup qt-network
\brief A platform-independent mechanism for storing binary files in an application.
\keyword 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 \l qmake,
\l rcc (Qt's resource compiler), and QFile. It obsoletes Qt 3's
\c qembed tool and the
\l{http://qt.nokia.com/doc/qq/qq05-iconography.html#imagestorage}{image
collection} mechanism.
\section1 Resource Collection Files (\c{.qrc})
The resources associated with an application are specified in a
\c .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 \c .qrc file:
\quotefile mainwindows/application/application.qrc
The resource files listed in the \c .qrc file are files that are
part of the application's source tree. The specified paths are
relative to the directory containing the \c .qrc file. Note that
the listed resource files must be located in the same directory as
the \c .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 \c :/ prefix,
or by a \link QUrl URL\endlink with a \c qrc scheme.
For example, the file path \c :/images/cut.png or the URL
\c qrc:///images/cut.png would give access to the
\c cut.png file, whose location in the application's source tree
is \c images/cut.png. This can be changed using the \c file tag's
\c alias attribute:
\snippet doc/src/snippets/code/doc_src_resources.qdoc 0
The file is then accessible as \c :/cut-img.png from the
application. It is also possible to specify a path prefix for all
files in the \c .qrc file using the \c qresource tag's \c prefix
attribute:
\snippet doc/src/snippets/code/doc_src_resources.qdoc 1
In this case, the file is accessible as \c
:/myresources/cut-img.png.
Some resources, such as translation files and icons, many need to
change based on the user's locale. This is done by adding a \c lang
attribute to the \c qresource tag, specifying a suitable locale
string. For example:
\snippet doc/src/snippets/code/doc_src_resources.qdoc 2
If the user's locale is French (i.e., QLocale::system().name() returns
"fr_FR"), \c :/cut.jpg becomes a reference to the \c cut_fr.jpg
image. For other locales, \c cut.jpg is used.
See the QLocale documentation for a description of the format to use
for locale strings.
\section2 External Binary Resources
For an external binary resource to be created you must create the resource
data (commonly given the \c .rcc extension) by passing the -binary switch to
\l 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 \c .qrc file can be
compiled in the following way:
\snippet doc/src/snippets/code/doc_src_resources.qdoc 3
In the application, this resource would be registered with code like this:
\snippet doc/src/snippets/code/doc_src_resources.qdoc 4
\section2 Compiled-In Resources
For a resource to be compiled into the binary the \c .qrc file must be
mentioned in the application's \c .pro file so that \c qmake knows
about it. For example:
\snippet examples/mainwindows/application/application.pro 0
\c qmake will produce make rules to generate a file called \c
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 \c
qrc_application.cpp file is automatically regenerated whenever
the \c .qrc file changes or one of the files that it refers to
changes. If you don't use \c .pro files, you can either invoke
\c rcc manually or add build rules to your build system.
\image resources.png Building resources into an application
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.
\section1 Compression
Resources are compressed by default (in the \c ZIP format). It is
possible to turn off compression. This can be useful if your
resources already contain a compressed format, such as \c .png
files. You do this by giving the \c {-no-compress} command line
argument.
\code
rcc -no-compress myresources.qrc
\endcode
\c rcc 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:
\code
rcc -compress 2 -threshold 3 myresources.qrc
\endcode
\section1 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:
\snippet examples/mainwindows/application/mainwindow.cpp 21
See the \l{mainwindows/application}{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 \c : instead of \c :/ 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 \l
Q_INIT_RESOURCE() with the base name of the \c .qrc file. For
example:
\snippet doc/src/snippets/code/doc_src_resources.qdoc 5
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.
*/
|
