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

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

Система ресурсов основана на тесном взаимодействии между qmake, rcc (компилятором ресурсов Qt) и QFile.

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

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

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

<!DOCTYPE RCC><RCC version="1.0">
<qresource>
    <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>

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

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

По умолчанию, к ресурсам в приложении можно получить доступ под тем же именем файла, что и в дереве исходных кодов, с префиксом :/ или с помощью URL со схемой qrc.

Например, путь к файлу :/images/cut.png или URL qrc:///images/cut.png обеспечивают доступ к cut.png файлу, чьё расположение в дереве исходных кодов приложения — images/cut.png. Это можно изменить, используя атрибут alias тега file.

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

Файл затем доступен как :/cut-img.png из приложения. Также можно указать префикс пути для всех файлов в .qrc файле, используя атрибут prefix тега qresource:

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

В этом случае файл доступен как :/myresources/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().name() возвращает "fr_FR"), :/cut.jpg становится ссылкой на cut_fr.jpg изображение. Для других региональных настроек используется cut.jpg.

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

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

Внешние двоичные ресурсы

Для создания внешнего двоичного ресурса необходимо создать данные ресурса (обычно с расширением .rcc), передав переключатель -binary в rcc. После создания двоичного ресурса вы можете зарегистрировать ресурс с помощью API QResource.

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

rcc -binary myresource.qrc -o myresource.rcc

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

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

Встроенные ресурсы

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

RESOURCES     = application.qrc

qmake сгенерирует правила make для создания файла под названием qrc_application.cpp, который будет связан с приложением. Этот файл содержит все данные для изображений и других ресурсов в виде статических массивов C++ сжатых двоичных данных. Файл qrc_application.cpp автоматически пересоздаётся всякий раз, когда изменяется файл .qrc или один из файлов, на которые он ссылается.

Если вы не используете .pro файлы, вы можете либо вручную вызвать rcc, либо добавить правила сборки в свою систему сборки.

В настоящее время Qt всегда хранит данные непосредственно в исполняемом файле, даже в Windows, macOS и iOS, где операционная система предоставляет встроенную поддержку ресурсов. Это может измениться в будущей версии Qt.

Сжатие

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

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 — в противном случае.

Использование ресурсов в приложении

В приложении пути к ресурсам можно использовать во многих местах вместо обычных путей к файлам. В частности, вы можете передать путь к ресурсу вместо имени файла в конструктор QIcon, QImage или QPixmap:

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

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

В памяти ресурсы представлены деревом объектов ресурсов. Дерево автоматически создаётся при запуске и используется QFile для разрешения путей к ресурсам. Вы можете использовать QDir, инициализированный с ":/", чтобы перемещаться по дереву ресурсов с корня.

Ресурсы Qt поддерживают понятие списка путей поиска. Если вы затем ссылаетесь на ресурс с : вместо :/ в качестве префикса, ресурс будет найден с помощью списка путей поиска. Список путей поиска пуст при запуске; используйте QDir::addSearchPath(), чтобы добавить в него пути.

Использование ресурсов в библиотеке

Если у вас есть ресурсы в библиотеке, вам необходимо заставить инициализировать ваши ресурсы, вызвав Q_INIT_RESOURCE() с базовым именем .qrc файла. Например:

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

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

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

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

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

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    Q_INIT_RESOURCE(graphlib);

    QFile file(":/graph.png");
    ...
    return app.exec();
}

Как и прежде, это гарантирует, что ресурсы будут связаны с конечным исполняемым файлом приложения в случае статической компоновки, а также вызовет загрузку библиотеки в случае динамической компоновки, такой как плагины.

Аналогично, если вам необходимо явно разгрузить набор ресурсов (потому что плагин разгружается или ресурсы больше не действительны), вы можете заставить удалить ваши ресурсы, вызвав Q_CLEANUP_RESOURCE() с тем же базовым именем, что и выше.

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