diff options
Diffstat (limited to 'src/corelib/doc/src/resource-system.qdoc')
| -rw-r--r-- | src/corelib/doc/src/resource-system.qdoc | 82 |
1 files changed, 35 insertions, 47 deletions
diff --git a/src/corelib/doc/src/resource-system.qdoc b/src/corelib/doc/src/resource-system.qdoc index 6e22757857..7c7613c9b8 100644 --- a/src/corelib/doc/src/resource-system.qdoc +++ b/src/corelib/doc/src/resource-system.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2021 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2021 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page resources.html @@ -41,7 +17,7 @@ Most commonly, the resource files are embedded into your application executable, or in libraries and plugins that are loaded by the application executable. Alternatively, the resource files can also be stored in an - \l{External Resource Files}{exernal resource file}. + \l{External Resource Files}{external resource file}. The resource system is based on tight cooperation between Qt's \l rcc resource compiler, the build system, and the Qt runtime API. @@ -83,8 +59,8 @@ the \c .qrc file. The path is also used by default to identify the file's content at runtime. - That is, the file \c copy.png will be available in the resource system as - \c{:/images/copy.png} or \c{qrc:/images/copy.png}. + That is, the file \c titlebarLeft.png will be available in the resource system as + \c{:/res/titlebarLeft.png} or \c{qrc:/res/titlebarLeft.png}. To override this default run-time name, see \l{Prefixes} and \l{Aliases}. \e{Qt Creator}, \e{Qt Design Studio}, \QD, and \e{Qt Visual Studio Tools} @@ -126,13 +102,16 @@ variable. If you add a \c .qrc file path to the variable, the listed resource files will be embedded into the generated library or executable: - \snippet resource-system/application.pro 0 + \snippet resource-system/application.pro qrc - For simple applications, it is also possible to let qmake generate the - \c .qrc file for you, avoiding the need for an additional file to be - maintained: + This creates a resource of several \c{.png} files, that are addressable + like this: \c{":/res/titlebarLeft.png"}. - \snippet resource-system/application.pro 1 + If the directory layout of the files you want to embed into the resource + doesn't match the expectations of the application, you can specify + \c{resources.base}. \c base is a path prefix that denotes the root point of + the file's alias. In the example above, if \c{resources.base} is set to + \c{"res"}, then \c{titlebarLeft.png} is addressable as \c{":/titlebarLeft.png"}. \section1 Runtime API @@ -151,9 +130,6 @@ \snippet resource-system/main.cpp url - See the \l{mainwindows/application}{Application} example for an actual - application that uses Qt's resource system to store its icons. - \section1 Advanced Topics \section2 Prefixes @@ -181,6 +157,25 @@ The file is from the application then only accessible as \c :/cut-img.png or \c{qrc:/cut-img.png}. + \section2 Discarding the file contents + + Sometimes you want to add a file node to the resource file system but + don't actually want to add the file contents. \c .qrc files allow this + by setting the \c empty attribute to \c{true}. + + \snippet code/doc_src_resources.qdoc 4 + + The resulting file is then still accessible from the application, but + its contents are empty. + + This is useful to strip QML source code from an application binary. + + \note If you omit the QML source code from the binary, the QML engine has to + rely on the compilation units created by \l{qmlcachegen} or \l{qmlsc}. + Those are tied to the specific version of Qt they were built with. If you + change the version of Qt your application uses, they can't be loaded + anymore. + \section2 Language Selectors Some resources need to change based on the user's locale, such as @@ -212,14 +207,7 @@ resource file's content and metadata is then done after the compilation and linking phase, through another rcc call. - For qmake, this is enabled by adding \c resources_big to the \c CONFIG - variable: - - \snippet resource-system/application.pro 2 - - For CMake, you need to use the \l{qt_add_big_resources} function: - - \snippet resource-system/CMakeLists.txt qt_add_big_resources + For CMake, you need to use the \l{qt_add_big_resources} function. \section2 External Resource Files @@ -247,13 +235,13 @@ resource compiler \l rcc: \code - rcc -g python application.qrc > application_rc.py + rcc -g python mainwindow.qrc > mainwindow_rc.py \endcode The module can then be imported in the application: \code - import application_rc.py + import mainwindow_rc.py \endcode \section2 Compression |