doc/src/network/files-and-resources/resources.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   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
  13 ** this file.
  14 **
  15 ** Other Usage
  16 ** Alternatively, this file may be used in accordance with the terms
  17 ** and conditions contained in a signed written agreement between you
  18 ** and Nokia.
  19 **
  20 **
  21 **
  22 **
  23 **
  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
  43     \ingroup qt-network
  44     \brief A platform-independent mechanism for storing binary files in an application.
  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
  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
  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.cpp 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
 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
 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
 204     force initialization of your resources by calling \l
 205     Q_INIT_RESOURCE() with the base name of the \c .qrc file. For
 206     example:
 207
 208     \snippet doc/src/snippets/code/doc_src_resources.cpp 5
 209
 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.
 214 */