/****************************************************************************

**

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

** All rights reserved.

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

**

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

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

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

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

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

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

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

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

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

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

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

**

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

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

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

**

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

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

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

/*!

    \group io

    \title Input/Output and Networking

    \ingroup groups

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

    network handling.

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

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

*/

/*!

    \page resources.html

    \title The Qt Resource System

    \keyword resource system

    The Qt resource system is a platform-independent mechanism for

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

    useful if your application always needs a certain set of files

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

    risk of losing the files.

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

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

    \c qembed tool and the

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

    collection} mechanism.

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

    The resources associated with an application are specified in a

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

    disk and optionally assigns them a resource name that the

    application must use to access the resource.

    Here's an example \c .qrc file:

    \quotefile mainwindows/application/application.qrc

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

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

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

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

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

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

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

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

    system.

    By default, resources are accessible in the application under the

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

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

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

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

    \c alias attribute:

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

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

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

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

    attribute:

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

    In this case, the file is accessible as \c

    :/myresources/cut-img.png.

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

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

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

    string. For example:

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

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

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

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

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

    for locale strings.

    \section2 External Binary Resources

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

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

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

    with the QResource API.

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

    compiled in the following way:

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

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

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

    \section2 Compiled-In Resources

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

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

    about it. For example:

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

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

    qrc_application.cpp that is linked into the application. This

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

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

    qrc_application.cpp file is automatically regenerated whenever

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

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

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

    \image resources.png Building resources into an application

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

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

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

    release.

    \section1 Using Resources in the Application

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

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

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

    or QPixmap constructor:

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

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

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

    icons.

    In memory, resources are represented by a tree of resource

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

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

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

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

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

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

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

    add paths to it.

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

    force initialization of your resources by calling \l

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

    example:

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

    Similarly, if you must unload a set of resources explicitly

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

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

    Q_CLEANUP_RESOURCE() with the same base name as above.

*/