Long live Qt 4.5!

1 files changed, 192 insertions, 0 deletions

diff --git a/doc/src/resources.qdoc b/doc/src/resources.qdoc
new file mode 100644
index 0000000..7997b9f
--- /dev/null
+++ b/doc/src/resources.qdoc
@@ -0,0 +1,192 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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 qt-sales@nokia.com.
+** $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
+    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::addResourceSearchPath() 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.
+*/