Класс QResource

Класс QResource предоставляет интерфейс для прямого чтения из ресурсов. Подробнее...

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются многопоточными.

Типы публичного доступа

Функции публичного доступа

Статические функции публичного доступа

Защищенные функции

Подробное описание

QResource — объект, представляющий набор данных (и, возможно, дочерние элементы) относящиеся к одному ресурсу. QResource предоставляет прямой доступ к байтам в их исходном формате. Таким образом, прямой доступ позволяет читать данные без копирования буфера или косвенного обращения. Косвенное обращение часто бывает полезным при взаимодействии с ресурсом, как если бы он был файлом; это можно достичь с помощью QFile. Данные и дочерние элементы QResource обычно компилируются в приложение/библиотеку, но также возможно загрузить ресурс во время выполнения. При загрузке во время выполнения ресурсный файл будет загружен как один большой набор данных, а затем выдаваться частями через ссылки в дереве ресурсов.

QResource может быть загружен с абсолютным путем, интерпретируемым как корень файловой системы с символом / или в формате ресурсов с символом :. Также можно открыть относительный ресурс, который будет найден в списке путей, возвращаемых QDir::searchPaths().

QResource, представляющий файл, будет иметь данные, которые могут быть сжаты. В этом случае для доступа к реальным данным необходимо использовать qUncompress(); это происходит неявно при доступе через QFile. QResource, представляющий директорию, будет иметь только дочерние элементы и не будет иметь данных.

Динамическая загрузка ресурсов

Ресурс может быть исключен из двоичного файла приложения и загружен по мере необходимости во время выполнения, используя функцию registerResource(). Ресурсный файл, переданный в registerResource(), должен быть двоичным ресурсом, созданным инструментом rcc. Дополнительную информацию о двоичных ресурсах можно найти в документации Системы ресурсов Qt.

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

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

Функция unregisterResource() удаляет ссылку на определенный файл. Если есть объекты QResource, которые в настоящее время ссылаются на ресурсы, связанные с незарегистрированным файлом, они останутся действительными, но сам ресурсный файл будет удален из корней ресурсов, и таким образом больше нельзя создать QResource, указывающий на эти данные. Ресурс будет размапирован из памяти, когда будет уничтожен последний QResource, указывающий на него.

См. также Систему ресурсов Qt, QFile, QDir и QFileInfo.

Документация по типам членов

[since 5.13] Перечисление QResource::Compression

Это перечисление используется функцией compressionAlgorithm() для указания алгоритма, используемого инструментом RCC для сжатия полезной нагрузки.

Это перечисление было введено или изменено в Qt 5.13.

См. также compressionAlgorithm().

Документация по функциям-членам

QResource::QResource(const QString &file = QString(), const QLocale &locale = QLocale())

Конструирует QResource, указывающий на file. locale используется для загрузки конкретной локализации данных ресурса.

См. также QFileInfo, QDir::searchPaths(), setFileName() и setLocale().

QResource::~QResource()

Освобождает ресурсы объекта QResource.

QString QResource::absoluteFilePath() const

Возвращает фактический путь, который представляет этот QResource, если ресурс был найден с помощью QDir::searchPaths(), он будет указан в пути.

См. также fileName().

QStringList QResource::children() const

Возвращает список всех ресурсов в этой директории. Если ресурс представляет собой файл, список будет пустым.

См. также isDir().

[since 5.13] QResource::Compression QResource::compressionAlgorithm() const

Возвращает тип сжатия, с которым сжат этот ресурс, если таковой имеется. Если он не сжат, эта функция возвращает QResource::NoCompression.

Если эта функция возвращает QResource::ZlibCompression, вы можете распаковать данные с помощью функции qUncompress(). До Qt 5.13 это был единственный возможный алгоритм сжатия.

Если эта функция возвращает QResource::ZstdCompression, вам нужно использовать функции библиотеки Zstandard (<zstd.h> header). Qt does not provide a wrapper. See \l{http://facebook.github.io/zstd/zstd_manual.html}{Zstandard manual}. \sa data(), isFile()

Эта функция была добавлена в Qt 5.13.

const uchar *QResource::data() const

Возвращает прямой доступ к сегменту данных только для чтения, которые представляет этот ресурс. Если ресурс сжат, возвращаемые данные также сжаты. Затем вызывающий код должен распаковать данные или использовать uncompressedData(). Если ресурс является каталогом, nullptr возвращается.

См. также uncompressedData(), size() и isFile().

QString QResource::fileName() const

Возвращает полный путь к файлу, который представляет QResource, как он был передан.

См. также setFileName() и absoluteFilePath().

[protected] bool QResource::isDir() const

Возвращает true, если ресурс представляет собой каталог и, следовательно, может иметь children() внутри, false, если он представляет собой файл.

См. также isFile().

[protected] bool QResource::isFile() const

Возвращает true, если ресурс представляет собой файл и, следовательно, имеет данные, false, если он представляет собой каталог.

См. также isDir().

bool QResource::isValid() const

Возвращает true, если ресурс действительно существует в иерархии ресурсов, в противном случае false.

[since 5.8] QDateTime QResource::lastModified() const

Возвращает дату и время последнего изменения файла перед упаковкой в ресурс.

Эта функция была добавлена в Qt 5.8.

QLocale QResource::locale() const

Возвращает локаль, используемую для поиска данных для QResource.

См. также setLocale().

[static] bool QResource::registerResource(const QString &rccFileName, const QString &mapRoot = QString())

Регистрирует ресурс с заданным rccFileName в указанном расположении в дереве ресурсов mapRoot и возвращает true, если файл успешно открыт; в противном случае возвращает false.

См. также unregisterResource().

[static] bool QResource::registerResource(const uchar *rccData, const QString &mapRoot = QString())

Регистрирует ресурс с заданными rccData в указанном расположении в дереве ресурсов mapRoot и возвращает true, если файл успешно открыт; в противном случае возвращает false.

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

См. также unregisterResource().

void QResource::setFileName(const QString &file)

Устанавливает QResource для указания на file. file может быть абсолютным, в таком случае он открывается напрямую, если относительный, то файл будет пытаться найти в QDir::searchPaths().

См. также fileName() и absoluteFilePath().

void QResource::setLocale(const QLocale &locale)

Устанавливает QResource для загрузки локализации ресурса только для locale. Если ресурс для конкретной локали не найден, используется локаль C.

См. также locale() и setFileName().

qint64 QResource::size() const

Возвращает размер хранимых данных, поддерживающих ресурс.

Если ресурс сжат, эта функция возвращает размер сжатых данных. См. uncompressedSize() для размера не сжатых данных.

См. также data(), uncompressedSize() и isFile().

[since 5.15] QByteArray QResource::uncompressedData() const

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

Примечание: Если данные были сжаты, эта функция будет распаковывать их каждый раз при вызове. Результат не кешируется между вызовами.

Эта функция была добавлена в Qt 5.15.

См. также uncompressedSize(), size(), compressionAlgorithm() и isFile().

[since 5.15] qint64 QResource::uncompressedSize() const

Возвращает размер данных в этом ресурсе. Если данные не сжаты, эта функция возвращает то же значение, что и size(). Если они сжаты, эта функция извлекает размер исходных не сжатых данных из сохраненного потока.

Эта функция была добавлена в Qt 5.15.

См. также size(), uncompressedData() и isFile().

[static] bool QResource::unregisterResource(const QString &rccFileName, const QString &mapRoot = QString())

Удаляет регистрацию ресурса с заданным rccFileName в указанном расположении в дереве ресурсов mapRoot и возвращает true, если ресурс успешно загружен и для него не существует ссылок; в противном случае возвращает false.

См. также registerResource().

[static] bool QResource::unregisterResource(const uchar *rccData, const QString &mapRoot = QString())

Удаляет регистрацию ресурса с заданными rccData в указанном расположении в дереве ресурсов mapRoot и возвращает true, если ресурс успешно загружен и нет ссылок на ресурс; в противном случае возвращает false.

См. также registerResource().