Система ресурсов 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 для описания формата строк локали.

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

Чтобы создать внешний двоичный ресурс, необходимо создать данные ресурса (обычно с расширением .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.

Сжатие

Ресурсы сжимаются по умолчанию (в формате ZIP). Возможно отключить сжатие. Это может быть полезно, если ваши ресурсы уже содержат сжатый формат, например, файлы .png. Для этого используйте параметр командной строки -no-compress.

rcc -no-compress myresources.qrc

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

rcc -compress 2 -threshold 3 myresources.qrc

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

В приложении пути к ресурсам можно использовать вместо обычных путей к файловой системе. В частности, вы можете передать путь к ресурсу вместо имени файла в конструктор 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() не требуется, когда ресурс включён в приложение.