source: trunk/doc/src/resources.qdoc@ 321

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Qt Software Information ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** 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.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page resources.html
    \title The Qt Resource System
    \ingroup buildsystem

    \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://doc.trolltech.com/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