Класс 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().

[protected] 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> заголовок). Qt не предоставляет обёртку.

См. Руководство по Zstandard.

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

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

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.

См. также 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

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