source: trunk/doc/src/resources.qdoc@ 109

Last change on this file since 109 was 2, checked in by Dmitry A. Kuminov, 16 years ago

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.

File size: 8.1 KB
Line 
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*/
Note: See TracBrowser for help on using the repository browser.