[556] | 1 | /****************************************************************************
|
---|
| 2 | **
|
---|
[846] | 3 | ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
|
---|
[556] | 4 | ** All rights reserved.
|
---|
| 5 | ** Contact: Nokia Corporation ([email protected])
|
---|
| 6 | **
|
---|
| 7 | ** This file is part of the documentation of the Qt Toolkit.
|
---|
| 8 | **
|
---|
[846] | 9 | ** $QT_BEGIN_LICENSE:FDL$
|
---|
[556] | 10 | ** Commercial Usage
|
---|
| 11 | ** Licensees holding valid Qt Commercial licenses may use this file in
|
---|
| 12 | ** accordance with the Qt Commercial License Agreement provided with the
|
---|
[846] | 13 | ** Software or, alternatively, in accordance with the terms contained in a
|
---|
| 14 | ** written agreement between you and Nokia.
|
---|
[556] | 15 | **
|
---|
[846] | 16 | ** GNU Free Documentation License
|
---|
| 17 | ** Alternatively, this file may be used under the terms of the GNU Free
|
---|
| 18 | ** Documentation License version 1.3 as published by the Free Software
|
---|
| 19 | ** Foundation and appearing in the file included in the packaging of this
|
---|
| 20 | ** file.
|
---|
[556] | 21 | **
|
---|
| 22 | ** If you have questions regarding the use of this file, please contact
|
---|
| 23 | ** Nokia at [email protected].
|
---|
| 24 | ** $QT_END_LICENSE$
|
---|
| 25 | **
|
---|
| 26 | ****************************************************************************/
|
---|
| 27 |
|
---|
| 28 | /*!
|
---|
| 29 | \group io
|
---|
| 30 | \title Input/Output and Networking
|
---|
| 31 | \ingroup groups
|
---|
| 32 |
|
---|
| 33 | \brief Classes providing file input and output along with directory and
|
---|
| 34 | network handling.
|
---|
| 35 |
|
---|
| 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.
|
---|
| 38 | */
|
---|
| 39 |
|
---|
| 40 | /*!
|
---|
| 41 | \page resources.html
|
---|
| 42 | \title The Qt Resource System
|
---|
[846] | 43 | \ingroup qt-network
|
---|
| 44 | \brief A platform-independent mechanism for storing binary files in an application.
|
---|
[556] | 45 |
|
---|
| 46 | \keyword resource system
|
---|
| 47 |
|
---|
| 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.
|
---|
| 53 |
|
---|
| 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.
|
---|
| 59 |
|
---|
| 60 | \section1 Resource Collection Files (\c{.qrc})
|
---|
| 61 |
|
---|
| 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.
|
---|
| 66 |
|
---|
| 67 | Here's an example \c .qrc file:
|
---|
| 68 |
|
---|
| 69 | \quotefile mainwindows/application/application.qrc
|
---|
| 70 |
|
---|
| 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.
|
---|
| 76 |
|
---|
| 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
|
---|
| 80 | system.
|
---|
| 81 |
|
---|
| 82 | By default, resources are accessible in the application under the
|
---|
[846] | 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.
|
---|
| 85 |
|
---|
| 86 | For example, the file path \c :/images/cut.png or the URL
|
---|
| 87 | \c qrc:///images/cut.png would give access to the
|
---|
[556] | 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
|
---|
| 90 | \c alias attribute:
|
---|
| 91 |
|
---|
| 92 | \snippet doc/src/snippets/code/doc_src_resources.qdoc 0
|
---|
| 93 |
|
---|
| 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
|
---|
| 97 | attribute:
|
---|
| 98 |
|
---|
| 99 | \snippet doc/src/snippets/code/doc_src_resources.qdoc 1
|
---|
| 100 |
|
---|
| 101 | In this case, the file is accessible as \c
|
---|
| 102 | :/myresources/cut-img.png.
|
---|
| 103 |
|
---|
| 104 | Some resources, such as translation files and icons, many need to
|
---|
| 105 | change based on the user's locale. This is done by adding a \c lang
|
---|
| 106 | attribute to the \c qresource tag, specifying a suitable locale
|
---|
| 107 | string. For example:
|
---|
| 108 |
|
---|
| 109 | \snippet doc/src/snippets/code/doc_src_resources.qdoc 2
|
---|
| 110 |
|
---|
| 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.
|
---|
| 114 |
|
---|
| 115 | See the QLocale documentation for a description of the format to use
|
---|
| 116 | for locale strings.
|
---|
| 117 |
|
---|
| 118 |
|
---|
| 119 | \section2 External Binary Resources
|
---|
| 120 |
|
---|
| 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.
|
---|
| 125 |
|
---|
| 126 | For example, a set of resource data specified in a \c .qrc file can be
|
---|
| 127 | compiled in the following way:
|
---|
| 128 |
|
---|
| 129 | \snippet doc/src/snippets/code/doc_src_resources.qdoc 3
|
---|
| 130 |
|
---|
| 131 | In the application, this resource would be registered with code like this:
|
---|
| 132 |
|
---|
| 133 | \snippet doc/src/snippets/code/doc_src_resources.qdoc 4
|
---|
| 134 |
|
---|
| 135 | \section2 Compiled-In Resources
|
---|
| 136 |
|
---|
| 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:
|
---|
| 140 |
|
---|
| 141 | \snippet examples/mainwindows/application/application.pro 0
|
---|
| 142 |
|
---|
| 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.
|
---|
| 151 |
|
---|
| 152 | \image resources.png Building resources into an application
|
---|
| 153 |
|
---|
| 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
|
---|
| 157 | release.
|
---|
| 158 |
|
---|
[846] | 159 | \section1 Compression
|
---|
| 160 |
|
---|
| 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
|
---|
| 165 | argument.
|
---|
| 166 |
|
---|
| 167 | \code
|
---|
| 168 | rcc -no-compress myresources.qrc
|
---|
| 169 | \endcode
|
---|
| 170 |
|
---|
| 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:
|
---|
| 174 |
|
---|
| 175 | \code
|
---|
| 176 | rcc -compress 2 -threshold 3 myresources.qrc
|
---|
| 177 | \endcode
|
---|
| 178 |
|
---|
[556] | 179 | \section1 Using Resources in the Application
|
---|
| 180 |
|
---|
| 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:
|
---|
| 185 |
|
---|
| 186 | \snippet examples/mainwindows/application/mainwindow.cpp 21
|
---|
| 187 |
|
---|
| 188 | See the \l{mainwindows/application}{Application} example for an
|
---|
| 189 | actual application that uses Qt's resource system to store its
|
---|
| 190 | icons.
|
---|
| 191 |
|
---|
| 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.
|
---|
| 196 |
|
---|
| 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
|
---|
| 201 | add paths to it.
|
---|
| 202 |
|
---|
| 203 | If you have resources in a static library, you might need to
|
---|
| |
---|