diff options
Diffstat (limited to 'doc/src/files-and-resources/resources.qdoc')
| -rw-r--r-- | doc/src/files-and-resources/resources.qdoc | 203 |
1 files changed, 203 insertions, 0 deletions
diff --git a/doc/src/files-and-resources/resources.qdoc b/doc/src/files-and-resources/resources.qdoc new file mode 100644 index 0000000..a799646 --- /dev/null +++ b/doc/src/files-and-resources/resources.qdoc @@ -0,0 +1,203 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** 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 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 http://qt.nokia.com/contact. +** $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. +*/ |