1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the documentation of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** GNU Free Documentation License
10 ** Alternatively, this file may be used under the terms of the GNU Free
11 ** Documentation License version 1.3 as published by the Free Software
12 ** Foundation and appearing in the file included in the packaging of
16 ** Alternatively, this file may be used in accordance with the terms
17 ** and conditions contained in a signed written agreement between you
26 ****************************************************************************/
30 \title Input/Output and Networking
33 \brief Classes providing file input and output along with directory and
36 These classes are used to handle input and output to and from external
37 devices, processes, files etc. as well as manipulating files and directories.
42 \title The Qt Resource System
44 \brief A platform-independent mechanism for storing binary files in an application.
46 \keyword resource system
48 The Qt resource system is a platform-independent mechanism for
49 storing binary files in the application's executable. This is
50 useful if your application always needs a certain set of files
51 (icons, translation files, etc.) and you don't want to run the
52 risk of losing the files.
54 The resource system is based on tight cooperation between \l qmake,
55 \l rcc (Qt's resource compiler), and QFile. It obsoletes Qt 3's
56 \c qembed tool and the
57 \l{http://qt.nokia.com/doc/qq/qq05-iconography.html#imagestorage}{image
58 collection} mechanism.
60 \section1 Resource Collection Files (\c{.qrc})
62 The resources associated with an application are specified in a
63 \c .qrc file, an XML-based file format that lists files on the
64 disk and optionally assigns them a resource name that the
65 application must use to access the resource.
67 Here's an example \c .qrc file:
69 \quotefile mainwindows/application/application.qrc
71 The resource files listed in the \c .qrc file are files that are
72 part of the application's source tree. The specified paths are
73 relative to the directory containing the \c .qrc file. Note that
74 the listed resource files must be located in the same directory as
75 the \c .qrc file, or one of its subdirectories.
77 Resource data can either be compiled into the binary and thus accessed
78 immediately in application code, or a binary resource can be created
79 and at a later point in application code registered with the resource
82 By default, resources are accessible in the application under the
83 same file name as they have in the source tree, with a \c :/ prefix,
84 or by a \link QUrl URL\endlink with a \c qrc scheme.
86 For example, the file path \c :/images/cut.png or the URL
87 \c qrc:///images/cut.png would give access to the
88 \c cut.png file, whose location in the application's source tree
89 is \c images/cut.png. This can be changed using the \c file tag's
92 \snippet doc/src/snippets/code/doc_src_resources.qdoc 0
94 The file is then accessible as \c :/cut-img.png from the
95 application. It is also possible to specify a path prefix for all
96 files in the \c .qrc file using the \c qresource tag's \c prefix
99 \snippet doc/src/snippets/code/doc_src_resources.qdoc 1
101 In this case, the file is accessible as \c
102 :/myresources/cut-img.png.
104 Some resources need to change based on the user's locale,
105 such as translation files or icons. This is done by adding a \c lang
106 attribute to the \c qresource tag, specifying a suitable locale
109 \snippet doc/src/snippets/code/doc_src_resources.qdoc 2
111 If the user's locale is French (i.e., QLocale::system().name() returns
112 "fr_FR"), \c :/cut.jpg becomes a reference to the \c cut_fr.jpg
113 image. For other locales, \c cut.jpg is used.
115 See the QLocale documentation for a description of the format to use
119 \section2 External Binary Resources
121 For an external binary resource to be created you must create the resource
122 data (commonly given the \c .rcc extension) by passing the -binary switch to
123 \l rcc. Once the binary resource is created you can register the resource
124 with the QResource API.
126 For example, a set of resource data specified in a \c .qrc file can be
127 compiled in the following way:
129 \snippet doc/src/snippets/code/doc_src_resources.qdoc 3
131 In the application, this resource would be registered with code like this:
133 \snippet doc/src/snippets/code/doc_src_resources.cpp 4
135 \section2 Compiled-In Resources
137 For a resource to be compiled into the binary the \c .qrc file must be
138 mentioned in the application's \c .pro file so that \c qmake knows
139 about it. For example:
141 \snippet examples/mainwindows/application/application.pro 0
143 \c qmake will produce make rules to generate a file called \c
144 qrc_application.cpp that is linked into the application. This
145 file contains all the data for the images and other resources as
146 static C++ arrays of compressed binary data. The \c
147 qrc_application.cpp file is automatically regenerated whenever
148 the \c .qrc file changes or one of the files that it refers to
149 changes. If you don't use \c .pro files, you can either invoke
150 \c rcc manually or add build rules to your build system.
152 \image resources.png Building resources into an application
154 Currently, Qt always stores the data directly in the executable,
155 even on Windows and Mac OS X, where the operating system provides
156 native support for resources. This might change in a future Qt
159 \section1 Compression
161 Resources are compressed by default (in the \c ZIP format). It is
162 possible to turn off compression. This can be useful if your
163 resources already contain a compressed format, such as \c .png
164 files. You do this by giving the \c {-no-compress} command line
168 rcc -no-compress myresources.qrc
171 \c rcc also gives you some control over the compression. You can
172 specify the compression level and the threshold level to consider
173 while compressing files, for example:
176 rcc -compress 2 -threshold 3 myresources.qrc
179 \section1 Using Resources in the Application
181 In the application, resource paths can be used in most places
182 instead of ordinary file system paths. In particular, you can
183 pass a resource path instead of a file name to the QIcon, QImage,
184 or QPixmap constructor:
186 \snippet examples/mainwindows/application/mainwindow.cpp 21
188 See the \l{mainwindows/application}{Application} example for an
189 actual application that uses Qt's resource system to store its
192 In memory, resources are represented by a tree of resource
193 objects. The tree is automatically built at startup and used by
194 QFile for resolving paths to resources. You can use a QDir initialized
195 with ":/" to navigate through the resource tree from the root.
197 Qt's resources support the concept of a search path list. If you then
198 refer to a resource with \c : instead of \c :/ as the prefix, the
199 resource will be looked up using the search path list. The search
200 path list is empty at startup; call QDir::addSearchPath() to
203 If you have resources in a static library, you might need to
204 force initialization of your resources by calling \l
205 Q_INIT_RESOURCE() with the base name of the \c .qrc file. For
208 \snippet doc/src/snippets/code/doc_src_resources.cpp 5
210 Similarly, if you must unload a set of resources explicitly
211 (because a plugin is being unloaded or the resources are not valid
212 any longer), you can force removal of your resources by calling
213 Q_CLEANUP_RESOURCE() with the same base name as above.