Update references to online documentation.
[qt:qt-ios-plaszma.git] / doc / src / resources.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: Nokia Corporation (qt-info@nokia.com)
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** No Commercial Usage
10 ** This file contains pre-release code and may not be distributed.
11 ** You may use this file in accordance with the terms and conditions
12 ** contained in the either Technology Preview License Agreement or the
13 ** Beta Release License Agreement.
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 http://qt.nokia.com/contact.
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://qt.nokia.com/doc/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::addSearchPath() 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 */