1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \group io

    44     \title Input/Output and Networking

    45     \ingroup groups

    46 

    47     \brief Classes providing file input and output along with directory and

    48     network handling.

    49 

    50     These classes are used to handle input and output to and from external

    51     devices, processes, files etc. as well as manipulating files and directories.

    52 */

    53 

    54 /*!

    55     \page resources.html

    56     \title The Qt Resource System

    57 

    58     \keyword resource system

    59 

    60     The Qt resource system is a platform-independent mechanism for

    61     storing binary files in the application's executable. This is

    62     useful if your application always needs a certain set of files

    63     (icons, translation files, etc.) and you don't want to run the

    64     risk of losing the files.

    65 

    66     The resource system is based on tight cooperation between \l qmake,

    67     \l rcc (Qt's resource compiler), and QFile. It obsoletes Qt 3's

    68     \c qembed tool and the

    69     \l{http://qt.nokia.com/doc/qq/qq05-iconography.html#imagestorage}{image

    70     collection} mechanism.

    71 

    72     \section1 Resource Collection Files (\c{.qrc})

    73 

    74     The resources associated with an application are specified in a

    75     \c .qrc file, an XML-based file format that lists files on the

    76     disk and optionally assigns them a resource name that the

    77     application must use to access the resource.

    78 

    79     Here's an example \c .qrc file:

    80 

    81     \quotefile mainwindows/application/application.qrc

    82 

    83     The resource files listed in the \c .qrc file are files that are

    84     part of the application's source tree. The specified paths are

    85     relative to the directory containing the \c .qrc file. Note that

    86     the listed resource files must be located in the same directory as

    87     the \c .qrc file, or one of its subdirectories.

    88 

    89     Resource data can either be compiled into the binary and thus accessed

    90     immediately in application code, or a binary resource can be created

    91     and at a later point in application code registered with the resource

    92     system.

    93 

    94     By default, resources are accessible in the application under the

    95     same name as they have in the source tree, with a \c :/ prefix.

    96     For example, the path \c :/images/cut.png would give access to the

    97     \c cut.png file, whose location in the application's source tree

    98     is \c images/cut.png. This can be changed using the \c file tag's

    99     \c alias attribute:

   100 

   101     \snippet doc/src/snippets/code/doc_src_resources.qdoc 0

   102 

   103     The file is then accessible as \c :/cut-img.png from the

   104     application. It is also possible to specify a path prefix for all

   105     files in the \c .qrc file using the \c qresource tag's \c prefix

   106     attribute:

   107 

   108     \snippet doc/src/snippets/code/doc_src_resources.qdoc 1

   109 

   110     In this case, the file is accessible as \c

   111     :/myresources/cut-img.png.

   112 

   113     Some resources, such as translation files and icons, many need to

   114     change based on the user's locale. This is done by adding a \c lang

   115     attribute to the \c qresource tag, specifying a suitable locale

   116     string. For example:

   117 

   118     \snippet doc/src/snippets/code/doc_src_resources.qdoc 2

   119 

   120     If the user's locale is French (i.e., QLocale::system().name() returns

   121     "fr_FR"), \c :/cut.jpg becomes a reference to the \c cut_fr.jpg

   122     image. For other locales, \c cut.jpg is used.

   123 

   124     See the QLocale documentation for a description of the format to use

   125     for locale strings.

   126 

   127 

   128     \section2 External Binary Resources

   129 

   130     For an external binary resource to be created you must create the resource

   131     data (commonly given the \c .rcc extension) by passing the -binary switch to

   132     \l rcc. Once the binary resource is created you can register the resource

   133     with the QResource API.

   134 

   135     For example, a set of resource data specified in a \c .qrc file can be

   136     compiled in the following way:

   137 

   138     \snippet doc/src/snippets/code/doc_src_resources.qdoc 3

   139 

   140     In the application, this resource would be registered with code like this:

   141 

   142     \snippet doc/src/snippets/code/doc_src_resources.qdoc 4

   143 

   144     \section2 Compiled-In Resources

   145 

   146     For a resource to be compiled into the binary the \c .qrc file must be

   147     mentioned in the application's \c .pro file so that \c qmake knows

   148     about it. For example:

   149 

   150     \snippet examples/mainwindows/application/application.pro 0

   151 

   152     \c qmake will produce make rules to generate a file called \c

   153     qrc_application.cpp that is linked into the application. This

   154     file contains all the data for the images and other resources as

   155     static C++ arrays of compressed binary data. The \c

   156     qrc_application.cpp file is automatically regenerated whenever

   157     the \c .qrc file changes or one of the files that it refers to

   158     changes. If you don't use \c .pro files, you can either invoke

   159     \c rcc manually or add build rules to your build system.

   160 

   161     \image resources.png Building resources into an application

   162 

   163     Currently, Qt always stores the data directly in the executable,

   164     even on Windows and Mac OS X, where the operating system provides

   165     native support for resources. This might change in a future Qt

   166     release.

   167 

   168     \section1 Using Resources in the Application

   169 

   170     In the application, resource paths can be used in most places

   171     instead of ordinary file system paths. In particular, you can

   172     pass a resource path instead of a file name to the QIcon, QImage,

   173     or QPixmap constructor:

   174 

   175     \snippet examples/mainwindows/application/mainwindow.cpp 21

   176 

   177     See the \l{mainwindows/application}{Application} example for an

   178     actual application that uses Qt's resource system to store its

   179     icons.

   180 

   181     In memory, resources are represented by a tree of resource

   182     objects. The tree is automatically built at startup and used by

   183     QFile for resolving paths to resources. You can use a QDir initialized

   184     with ":/" to navigate through the resource tree from the root.

   185 

   186     Qt's resources support the concept of a search path list. If you then

   187     refer to a resource with \c : instead of \c :/ as the prefix, the

   188     resource will be looked up using the search path list. The search

   189     path list is empty at startup; call QDir::addSearchPath() to

   190     add paths to it.

   191 

   192     If you have resources in a static library, you might need to

   193     force initialization of your resources by calling \l

   194     Q_INIT_RESOURCE() with the base name of the \c .qrc file. For

   195     example:

   196 

   197     \snippet doc/src/snippets/code/doc_src_resources.qdoc 5

   198 

   199     Similarly, if you must unload a set of resources explicitly

   200     (because a plugin is being unloaded or the resources are not valid

   201     any longer), you can force removal of your resources by calling

   202     Q_CLEANUP_RESOURCE() with the same base name as above.

   203 */