1 | /****************************************************************************
|
---|
2 | **
|
---|
3 | ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
|
---|
4 | ** Contact: Qt Software Information ([email protected])
|
---|
5 | **
|
---|
6 | ** This file is part of the documentation of the Qt Toolkit.
|
---|
7 | **
|
---|
8 | ** $QT_BEGIN_LICENSE:LGPL$
|
---|
9 | ** Commercial Usage
|
---|
10 | ** Licensees holding valid Qt Commercial licenses may use this file in
|
---|
11 | ** accordance with the Qt Commercial License Agreement provided with the
|
---|
12 | ** Software or, alternatively, in accordance with the terms contained in
|
---|
13 | ** a written agreement between you and Nokia.
|
---|
14 | **
|
---|
15 | ** GNU Lesser General Public License Usage
|
---|
16 | ** Alternatively, this file may be used under the terms of the GNU Lesser
|
---|
17 | ** General Public License version 2.1 as published by the Free Software
|
---|
18 | ** Foundation and appearing in the file LICENSE.LGPL included in the
|
---|
19 | ** packaging of this file. Please review the following information to
|
---|
20 | ** ensure the GNU Lesser General Public License version 2.1 requirements
|
---|
21 | ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
|
---|
22 | **
|
---|
23 | ** In addition, as a special exception, Nokia gives you certain
|
---|
24 | ** additional rights. These rights are described in the Nokia Qt LGPL
|
---|
25 | ** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
|
---|
26 | ** package.
|
---|
27 | **
|
---|
28 | ** GNU General Public License Usage
|
---|
29 | ** Alternatively, this file may be used under the terms of the GNU
|
---|
30 | ** General Public License version 3.0 as published by the Free Software
|
---|
31 | ** Foundation and appearing in the file LICENSE.GPL included in the
|
---|
32 | ** packaging of this file. Please review the following information to
|
---|
33 | ** ensure the GNU General Public License version 3.0 requirements will be
|
---|
34 | ** met: http://www.gnu.org/copyleft/gpl.html.
|
---|
35 | **
|
---|
36 | ** If you are unsure which license is appropriate for your use, please
|
---|
37 | ** contact the sales department at [email protected].
|
---|
38 | ** $QT_END_LICENSE$
|
---|
39 | **
|
---|
40 | ****************************************************************************/
|
---|
41 |
|
---|
42 | /*!
|
---|
43 | \page resources.html
|
---|
44 | \title The Qt Resource System
|
---|
45 | \ingroup buildsystem
|
---|
46 |
|
---|
47 | \keyword resource system
|
---|
48 |
|
---|
49 | The Qt resource system is a platform-independent mechanism for
|
---|
50 | storing binary files in the application's executable. This is
|
---|
51 | useful if your application always needs a certain set of files
|
---|
52 | (icons, translation files, etc.) and you don't want to run the
|
---|
53 | risk of losing the files.
|
---|
54 |
|
---|
55 | The resource system is based on tight cooperation between \l qmake,
|
---|
56 | \l rcc (Qt's resource compiler), and QFile. It obsoletes Qt 3's
|
---|
57 | \c qembed tool and the
|
---|
58 | \l{http://doc.trolltech.com/qq/qq05-iconography.html#imagestorage}{image
|
---|
59 | collection} mechanism.
|
---|
60 |
|
---|
61 | \section1 Resource Collection Files (\c{.qrc})
|
---|
62 |
|
---|
63 | The resources associated with an application are specified in a
|
---|
64 | \c .qrc file, an XML-based file format that lists files on the
|
---|
65 | disk and optionally assigns them a resource name that the
|
---|
66 | application must use to access the resource.
|
---|
67 |
|
---|
68 | Here's an example \c .qrc file:
|
---|
69 |
|
---|
70 | \quotefile mainwindows/application/application.qrc
|
---|
71 |
|
---|
72 | The resource files listed in the \c .qrc file are files that are
|
---|
73 | part of the application's source tree. The specified paths are
|
---|
74 | relative to the directory containing the \c .qrc file. Note that
|
---|
75 | the listed resource files must be located in the same directory as
|
---|
76 | the \c .qrc file, or one of its subdirectories.
|
---|
77 |
|
---|
78 | Resource data can either be compiled into the binary and thus accessed
|
---|
79 | immediately in application code, or a binary resource can be created
|
---|
80 | and at a later point in application code registered with the resource
|
---|
81 | system.
|
---|
82 |
|
---|
83 | By default, resources are accessible in the application under the
|
---|
84 | same name as they have in the source tree, with a \c :/ prefix.
|
---|
85 | For example, the path \c :/images/cut.png would give access to the
|
---|
86 | \c cut.png file, whose location in the application's source tree
|
---|
87 | is \c images/cut.png. This can be changed using the \c file tag's
|
---|
88 | \c alias attribute:
|
---|
89 |
|
---|
90 | \snippet doc/src/snippets/code/doc_src_resources.qdoc 0
|
---|
91 |
|
---|
92 | The file is then accessible as \c :/cut-img.png from the
|
---|
93 | application. It is also possible to specify a path prefix for all
|
---|
94 | files in the \c .qrc file using the \c qresource tag's \c prefix
|
---|
95 | attribute:
|
---|
96 |
|
---|
97 | \snippet doc/src/snippets/code/doc_src_resources.qdoc 1
|
---|
98 |
|
---|
99 | In this case, the file is accessible as \c
|
---|
100 | :/myresources/cut-img.png.
|
---|
101 |
|
---|
102 | Some resources, such as translation files and icons, many need to
|
---|
103 | change based on the user's locale. This is done by adding a \c lang
|
---|
104 | attribute to the \c qresource tag, specifying a suitable locale
|
---|
105 | string. For example:
|
---|
106 |
|
---|
107 | \snippet doc/src/snippets/code/doc_src_resources.qdoc 2
|
---|
108 |
|
---|
109 | If the user's locale is French (i.e., QLocale::system().name() returns
|
---|
110 | "fr_FR"), \c :/cut.jpg becomes a reference to the \c cut_fr.jpg
|
---|
111 | image. For other locales, \c cut.jpg is used.
|
---|
112 |
|
---|
113 | See the QLocale documentation for a description of the format to use
|
---|
114 | for locale strings.
|
---|
115 |
|
---|
116 |
|
---|
117 | \section2 External Binary Resources
|
---|
118 |
|
---|
119 | For an external binary resource to be created you must create the resource
|
---|
120 | data (commonly given the \c .rcc extension) by passing the -binary switch to
|
---|
121 | \l rcc. Once the binary resource is created you can register the resource
|
---|
122 | with the QResource API.
|
---|
123 |
|
---|
124 | For example, a set of resource data specified in a \c .qrc file can be
|
---|
125 | compiled in the following way:
|
---|
126 |
|
---|
127 | \snippet doc/src/snippets/code/doc_src_resources.qdoc 3
|
---|
128 |
|
---|
129 | In the application, this resource would be registered with code like this:
|
---|
130 |
|
---|
131 | \snippet doc/src/snippets/code/doc_src_resources.qdoc 4
|
---|
132 |
|
---|
133 | \section2 Compiled-In Resources
|
---|
134 |
|
---|
135 | For a resource to be compiled into the binary the \c .qrc file must be
|
---|
136 | mentioned in the application's \c .pro file so that \c qmake knows
|
---|
137 | about it. For example:
|
---|
138 |
|
---|
139 | \snippet examples/mainwindows/application/application.pro 0
|
---|
140 |
|
---|
141 | \c qmake will produce make rules to generate a file called \c
|
---|
142 | qrc_application.cpp that is linked into the application. This
|
---|
143 | file contains all the data for the images and other resources as
|
---|
144 | static C++ arrays of compressed binary data. The \c
|
---|
145 | qrc_application.cpp file is automatically regenerated whenever
|
---|
146 | the \c .qrc file changes or one of the files that it refers to
|
---|
147 | changes. If you don't use \c .pro files, you can either invoke
|
---|
148 | \c rcc manually or add build rules to your build system.
|
---|
149 |
|
---|
150 | \image resources.png Building resources into an application
|
---|
151 |
|
---|
152 | Currently, Qt always stores the data directly in the executable,
|
---|
153 | even on Windows and Mac OS X, where the operating system provides
|
---|
154 | native support for resources. This might change in a future Qt
|
---|
155 | release.
|
---|
156 |
|
---|
157 | \section1 Using Resources in the Application
|
---|
158 |
|
---|
159 | In the application, resource paths can be used in most places
|
---|
160 | instead of ordinary file system paths. In particular, you can
|
---|
161 | pass a resource path instead of a file name to the QIcon, QImage,
|
---|
162 | or QPixmap constructor:
|
---|
163 |
|
---|
164 | \snippet examples/mainwindows/application/mainwindow.cpp 21
|
---|
165 |
|
---|
166 | See the \l{mainwindows/application}{Application} example for an
|
---|
167 | actual application that uses Qt's resource system to store its
|
---|
168 | icons.
|
---|
169 |
|
---|
170 | In memory, resources are represented by a tree of resource
|
---|
171 | objects. The tree is automatically built at startup and used by
|
---|
172 | QFile for resolving paths to resources. You can use a QDir initialized
|
---|
173 | with ":/" to navigate through the resource tree from the root.
|
---|
174 |
|
---|
175 | Qt's resources support the concept of a search path list. If you then
|
---|
176 | refer to a resource with \c : instead of \c :/ as the prefix, the
|
---|
177 | resource will be looked up using the search path list. The search
|
---|
178 | path list is empty at startup; call QDir::addResourceSearchPath() to
|
---|
179 | add paths to it.
|
---|
180 |
|
---|
181 | If you have resources in a static library, you might need to
|
---|
182 | force initialization of your resources by calling \l
|
---|
183 | Q_INIT_RESOURCE() with the base name of the \c .qrc file. For
|
---|
184 | example:
|
---|
185 |
|
---|
186 | \snippet doc/src/snippets/code/doc_src_resources.qdoc 5
|
---|
187 |
|
---|
188 | Similarly, if you must unload a set of resources explicitly
|
---|
189 | (because a plugin is being unloaded or the resources are not valid
|
---|
190 | any longer), you can force removal of your resources by calling
|
---|
191 | Q_CLEANUP_RESOURCE() with the same base name as above.
|
---|
192 | */
|
---|