Система ресурсов Qt

Система ресурсов Qt — это платформонезависимый механизм для поставки файлов ресурсов в приложение. Используйте её, если ваше приложение всегда нуждается в определённом наборе файлов (например, значки, файлы переводов, изображения), и вы не хотите использовать платформозависимые средства для упаковки и поиска этих ресурсов.

Чаще всего файлы ресурсов внедряются в исполняемый файл приложения или в библиотеки и плагины, загружаемые исполняемым файлом приложения. В качестве альтернативы, файлы ресурсов также могут храниться во внешнем файле ресурсов.

Система ресурсов основана на тесном сотрудничестве между компилятором ресурсов Qt (rcc), системой сборки и API времени выполнения Qt.

Компилятор ресурсов Qt (rcc)

Утилита командной строки Компилятор ресурсов (rcc) считывает файлы ресурсов и генерирует файл исходного кода C++ или Python или .rcc файл.

Список файлов и связанных метаданных передаётся в rcc в виде файла коллекции ресурсов Qt.

По умолчанию, rcc генерирует исходный код на C++, который затем компилируется как часть исполняемого файла или библиотеки. Опция -g python генерирует исходный код на Python вместо этого. Опция -binary генерирует двоичный архив, который по соглашению сохраняется в .rcc файле и может быть загружен во время выполнения.

Файл коллекции ресурсов Qt (.qrc)

Файл .qrc — это XML-документ, перечисляющий локальные файлы, которые должны быть включены как ресурсы времени выполнения. Он служит входными данными для rcc.

Вот пример .qrc файла:

<RCC>
    <qresource prefix="/">
        <file>images/copy.png</file>
        <file>images/cut.png</file>
        <file>images/new.png</file>
        <file>images/open.png</file>
        <file>images/paste.png</file>
        <file>images/save.png</file>
    </qresource>
</RCC>

Каждый <file> элемент в XML идентифицирует файл в дереве исходного кода приложения. Путь определяется относительно каталога, содержащего .qrc файл.

Путь также используется по умолчанию для идентификации содержимого файла во время выполнения. То есть, файл copy.png будет доступен в системе ресурсов как :/images/copy.png или qrc:/images/copy.png. Чтобы переопределить это имя по умолчанию для времени выполнения, см. Префиксы и Псевдонимы.

Qt Creator, Qt Design Studio, Qt Designer и Qt Visual Studio Tools позволяют создавать, просматривать и редактировать .qrc файлы через удобный пользовательский интерфейс. За исключением Qt Designer, они также предоставляют мастера для проектов, использующих систему ресурсов Qt.

Интеграция системы сборки

Обработка файлов ресурсов с помощью rcc обычно выполняется в момент сборки приложения. Несколько инструментов сборки имеют специальную поддержку этого, в том числе CMake и qmake.

CMake

Если CMAKE_AUTORCC включено, вы можете просто добавить .qrc файлы как исходные файлы для своего исполняемого файла или библиотеки. Ссылающиеся файлы ресурсов затем будут внедрены в двоичный файл:

set(CMAKE_AUTORCC ON)

qt_add_executable(my_app
    application.qrc
    main.cpp
)

См. документацию CMake по AUTORCC для получения более подробной информации об AUTORCC.

Альтернативой AUTORCC является использование функции CMake Qt6Core qt_add_resources, которая обеспечивает больший контроль над созданием ресурсов. Например, она позволяет вам указать содержимое ресурса непосредственно в файле проекта без предварительного написания .qrc файла:

qt_add_resources(my_app "app_images"
    PREFIX "/"
    FILES
        images/copy.png
        images/cut.png
        images/new.png
        images/open.png
        images/paste.png
        images/save.png
)

Наконец, qt_add_qml_module позволяет вам внедрять ресурсы Qt Quick в систему ресурсов вашего приложения. Функция определена в Qml компоненте Qt6 пакета CMake.

qmake

qmake поддерживает обработку ресурсов с помощью переменной RESOURCES. Если вы добавите путь к .qrc файлу в переменную, перечисленные файлы ресурсов будут внедрены в сгенерированную библиотеку или исполняемый файл:

RESOURCES = application.qrc

Для простых приложений также возможно позволить qmake сгенерировать .qrc файл за вас, избегая необходимости поддерживать дополнительный файл:

resources.files = \
    images/copy.png \
    images/cut.png \
    images/new.png \
    images/open.png \
    images/paste.png \
    images/save.png
resources.prefix = /

RESOURCES = resources

API времени выполнения

API Qt, которое работает с итерацией и чтением файлов, имеет встроенную поддержку системы ресурсов Qt. Вы можете передать путь к ресурсу вместо пути к локальному файлу в QFile и QDir, а также, например, в конструкторы QIcon, QImage и QPixmap:

    cutAct = new QAction(QIcon(":/images/cut.png"), tr("Cu&t"), this);

Префикс : делает явным, что "/images/cut.png" должен загружаться из системы ресурсов Qt.

Вы также можете сослаться на систему ресурсов Qt с помощью QUrl. В этом случае используйте схему qrc:

    QQmlApplicationEngine engine;
    engine.load(QUrl("qrc:/myapp/main.qml"));

См. пример приложения Application для практического приложения, использующего систему ресурсов Qt для хранения значков.

Расширенные темы

Префиксы

Файл .qrc может установить префикс, который будет добавлен к каждому имени локального файла, заданному в <file> элементе, чтобы получить имя, под которым файл будет известен в системе ресурсов.

Префиксы позволяют структурировать ресурсы, избегая конфликтов между файлами ресурсов, добавленными через различные .qrc файлы в разных библиотеках или плагинах.

Псевдонимы

Иногда удобно сделать файл ресурса доступным по другому пути во время выполнения. .qrc файлы позволяют это, устанавливая alias атрибут:

<file alias="cut-img.png">images/cut.png</file>

Затем файл доступен только по пути :/cut-img.png или qrc:/cut-img.png.

Селекторы языков

Некоторые ресурсы должны изменяться в зависимости от региональных настроек пользователя, например, файлы переводов или значки. Файлы коллекции ресурсов поддерживают это через lang атрибут тега qresource, определяющий строку региональных настроек. Например:

<qresource>
    <file>cut.jpg</file>
</qresource>
<qresource lang="fr">
    <file alias="cut.jpg">cut_fr.jpg</file>
</qresource>

Если региональные настройки пользователя — французский (т.е., QLocale::system().language() — французский), :/cut.jpg или qrc:/cut.jpg ссылается на изображение cut_fr.jpg. Для других региональных настроек используется cut.jpg.

См. документацию QLocale для описания формата, который нужно использовать для строк региональных настроек.

См. QFileSelector для дополнительного механизма выбора ресурсов, специфичных для региональных настроек.

Внедрение больших файлов

По умолчанию, rcc внедряет файлы ресурсов в исполняемые файлы в виде массивов C++. Это может быть проблематично, особенно для больших ресурсов.

Если компилятор работает слишком долго или даже терпит неудачу из-за переполнения памяти, вы можете выбрать специальный режим, в котором ресурсы внедряются в виде двухэтапного процесса. Компилятор C++ резервирует только необходимое пространство в целевом исполняемом файле или библиотеке для ресурсов. Фактическое внедрение содержимого и метаданных файла ресурса выполняется после компиляции и компоновки, через другой вызов rcc.

Для qmake это включено добавлением resources_big к переменной CONFIG:

CONFIG += resources_big

Для CMake необходимо использовать функцию qt_add_big_resources:

qt_add_big_resources(SOURCES application.qrc)
target_sources(my_app PRIVATE ${SOURCES})

Внешние файлы ресурсов

Альтернативой внедрению файлов ресурсов в двоичный файл является хранение их в отдельном .rcc файле. rcc позволяет это с помощью опции -binary. Такой .rcc файл затем необходимо загрузить во время выполнения с помощью QResource.

Например, набор данных ресурсов, указанных в .qrc файле, можно скомпилировать следующим образом:

rcc -binary myresource.qrc -o myresource.rcc

В приложении этот ресурс был бы зарегистрирован кодом такого типа:

QResource::registerResource("/path/to/myresource.rcc");

Если вы используете CMake, вы можете использовать функцию qt_add_binary_resources для планирования вышеупомянутого вызова rcc:

qt_add_binary_resources(resources application.qrc DESTINATION application.rcc)
add_dependencies(my_app resources)

Ресурсы в приложении Qt для Python

Файл коллекции ресурсов преобразуется в модуль Python с использованием компилятора ресурсов rcc:

rcc -g python application.qrc > application_rc.py

Затем модуль можно импортировать в приложение:

import application_rc.py

Сжатие

rcc пытается сжать содержимое, чтобы оптимизировать использование дискового пространства в конечных двоичных файлах. По умолчанию, он выполнит эвристическую проверку, чтобы определить, стоит ли сжимать, и сохранит содержимое нескомпрессированным, если сжатие не достаточно эффективно. Чтобы контролировать порог, можно использовать опцию -threshold, которая сообщает rcc о проценте исходного размера файла, который необходимо получить, чтобы он сохранил файл в сжатой форме.

rcc -threshold 25 myresources.qrc

Значение по умолчанию — "70", что указывает на то, что сжатый файл должен быть на 70% меньше исходного (не более 30% исходного размера файла).

Можно отключить сжатие, если это необходимо. Это может быть полезно, если ваши ресурсы уже содержат сжатый формат, например, .png файлы, и вы не хотите тратить ресурсы ЦП на проверку возможности сжатия во время сборки. Другая причина — если использование дискового пространства не проблема, и приложение предпочитает сохранять содержимое как чистые страницы памяти во время выполнения. Это делается путём предоставления аргумента командной строки -no-compress.

rcc -no-compress myresources.qrc

rcc также даёт вам некоторое управление уровнем сжатия и алгоритмом сжатия, например:

rcc -compress 2 -compress-algo zlib myresources.qrc

Также можно использовать threshold, compress, и compress-algo в качестве атрибутов в теге .qrc file.

<qresource>
    <file compress="1" compress-algo="zstd">data.txt</file>
</qresource>

Вышеуказанное выберет алгоритм zstd с уровнем сжатия 1.

rcc поддерживает следующие алгоритмы сжатия и уровни сжатия:

• best: используйте лучший алгоритм из перечисленных ниже с максимальным уровнем сжатия, чтобы добиться наибольшего сжатия за счёт значительного времени, затрачиваемого на компиляцию процессором. Это значение полезно в файле XML для указания файла, который должен быть максимально сжат, независимо от того, какие алгоритмы rcc поддерживает.
• zstd: используйте библиотеку Zstandard для сжатия содержимого. Действительные уровни сжатия колеблются от 1 до 19, причём 1 — наименьшее сжатие (наименьшее время работы процессора), а 19 — наибольшее сжатие (наибольшее время работы процессора). По умолчанию используется уровень 14. Специальное значение 0 сообщает библиотеке zstd выбрать определённый по реализации значение по умолчанию.
• zlib: используйте библиотеку zlib для сжатия содержимого. Действительные уровни сжатия колеблются от 1 до 9, причём 1 — наименьшее сжатие (наименьшее время работы процессора), а 9 — наибольшее сжатие (наибольшее время работы процессора). Специальное значение 0 означает «без сжатия» и не должно использоваться. По умолчанию используется реализационно-определенное значение, но обычно это уровень 6.
• none: без сжатия. Это то же самое, что и опция -no-compress.

Поддержка как Zstandard, так и zlib является необязательной. Если данная библиотека не была обнаружена во время компиляции, попытка передать -compress-algo для этой библиотеки приведёт к ошибке. Алгоритм сжатия по умолчанию — zstd , если он включён, и zlib , если нет.

Явное загрузка и выгрузка встроенных ресурсов

Встроенные ресурсы в исполняемом файле или библиотеке кода C++ автоматически регистрируются в системе ресурсов Qt в конструкторе внутренней глобальной переменной. Поскольку глобальные переменные инициализируются до запуска main(), ресурсы доступны при запуске программы.

При встраивании ресурсов в статические библиотеки, компоновщик C++ может удалить статические переменные, регистрирующие ресурсы. Поэтому, если вы встраиваете ресурсы в статическую библиотеку, вам необходимо явным образом зарегистрировать свои ресурсы, вызвав Q_INIT_RESOURCE() с базовым именем файла .qrc. Например:

MyClass::MyClass() : BaseClass()
{
    Q_INIT_RESOURCE(resources);

    QFile file(":/myfile.dat");
    ...
}

Вы также можете явным образом удалить зарегистрированные ресурсы из приложения, например, при разгрузке плагина. Для этого используйте Q_CLEANUP_RESOURCE().

Примечание: поскольку инициализаторы ресурсов, сгенерированные rcc, объявляются в глобальном пространстве имён, ваши вызовы Q_INIT_RESOURCE() и Q_CLEANUP_RESOURCE() должны выполняться вне любого пространства имён.