QResource Class
La classe QResource fournit une interface permettant de lire directement les ressources. Plus d'informations...
| En-tête : | #include <QResource> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake : | QT += core |
- Liste de tous les membres, y compris les membres hérités
- QResource fait partie de Entrées/Sorties et Réseaux.
Remarque : toutes les fonctions de cette classe sont réentrantes.
Types publics
| enum | Compression { NoCompression, ZlibCompression, ZstdCompression } |
Fonctions publiques
| QResource(const QString &file = QString(), const QLocale &locale = QLocale()) | |
| ~QResource() | |
| QString | absoluteFilePath() const |
| QResource::Compression | compressionAlgorithm() const |
| const uchar * | data() const |
| QString | fileName() const |
| bool | isValid() const |
| QDateTime | lastModified() const |
| QLocale | locale() const |
| void | setFileName(const QString &file) |
| void | setLocale(const QLocale &locale) |
| qint64 | size() const |
| QByteArray | uncompressedData() const |
| qint64 | uncompressedSize() const |
Membres publics statiques
| bool | registerResource(const QString &rccFileName, const QString &mapRoot = QString()) |
| bool | registerResource(const uchar *rccData, const QString &mapRoot = QString()) |
| bool | unregisterResource(const QString &rccFileName, const QString &mapRoot = QString()) |
| bool | unregisterResource(const uchar *rccData, const QString &mapRoot = QString()) |
Fonctions protégées
Description détaillée
QResource est un objet qui représente un ensemble de données (et éventuellement d'enfants) relatives à une seule entité ressource. QResource donne un accès direct aux octets dans leur format brut. L'accès direct permet ainsi de lire des données sans copie de tampon ni indirection. L'indirection est souvent utile pour interagir avec l'entité ressource comme s'il s'agissait d'un fichier, ce qui peut être réalisé à l'aide de QFile. Les données et les enfants d'une QResource sont normalement compilés dans une application/bibliothèque, mais il est également possible de charger une ressource au moment de l'exécution. Lorsqu'il est chargé au moment de l'exécution, le fichier de la ressource est chargé comme un grand ensemble de données, puis distribué par morceaux via des références dans l'arborescence de la ressource.
Une QResource peut être chargée avec un chemin d'accès absolu, traité comme un système de fichiers dont la racine est un caractère /, ou en notation de ressource dont la racine est un caractère :. Une ressource relative peut également être ouverte et sera trouvée dans la liste des chemins retournés par QDir::searchPaths().
Une QResource qui représente un fichier aura des données à l'appui, ces données peuvent éventuellement être compressées, auquel cas qUncompress() doit être utilisé pour accéder aux vraies données ; cela se produit implicitement lorsqu'on y accède par l'intermédiaire de QFile. Une QResource qui représente un répertoire n'aura que des enfants et pas de données.
Chargement dynamique des ressources
Une ressource peut être exclue du binaire d'une application et chargée lorsqu'elle est nécessaire au moment de l'exécution en utilisant la fonction registerResource(). Le fichier de ressources transmis à registerResource() doit être une ressource binaire telle que créée par rcc. De plus amples informations sur les ressources binaires peuvent être trouvées dans la documentation du système de ressources Qt.
Cela peut souvent être utile lors du chargement d'un grand ensemble d'icônes d'application qui peuvent changer en fonction d'un paramètre, ou qui peuvent être modifiées par un utilisateur et recréées par la suite. La ressource est immédiatement chargée en mémoire, soit à la suite d'une opération de lecture d'un seul fichier, soit sous la forme d'un fichier mappé en mémoire.
Cette approche peut s'avérer être un gain de performance significatif car un seul fichier sera chargé et les données seront distribuées via le chemin d'accès demandé dans setFileName().
La fonction unregisterResource() supprime une référence à un fichier particulier. Si des objets QResource font actuellement référence à des ressources liées au fichier non enregistré, ils continueront d'être valides, mais le fichier de ressource lui-même sera supprimé des racines de ressources, et aucune autre QResource ne pourra donc être créée pour pointer vers ces données de ressources. La ressource elle-même sera supprimée de la mémoire lorsque la dernière QResource qui pointe vers elle sera détruite.
Corruption et sécurité
La classe QResource effectue quelques vérifications sur le fichier transmis afin de déterminer s'il est pris en charge par la version actuelle de Qt. Ces tests servent uniquement à vérifier que l'en-tête du fichier ne demande pas des fonctionnalités (comme la décompression Zstandard) qui n'ont pas été compilées ou que le fichier n'est pas d'une version future de Qt. Ils ne confirment pas la validité de l'ensemble du fichier.
QResource ne doit pas être utilisé pour des fichiers dont la provenance n'est pas fiable. Les applications doivent être conçues pour tenter de charger uniquement des fichiers de ressources dont la provenance est au moins aussi fiable que celle de l'application elle-même ou de ses plugins.
Voir aussi Le système de ressources Qt, QFile, QDir, et QFileInfo.
Documentation sur les types de membres
enum QResource::Compression
Cette énumération est utilisée par compressionAlgorithm() pour indiquer l'algorithme utilisé par l'outil RCC pour compresser la charge utile.
| Constante | Valeur | Description |
|---|---|---|
QResource::NoCompression | 0 | Le contenu n'est pas compressé |
QResource::ZlibCompression | 1 | Le contenu est compressé à l'aide de zlib et peut être décompressé à l'aide de la fonction qUncompress(). |
QResource::ZstdCompression | 2 | Le contenu est compressé à l'aide de zstd. Pour décompresser, utilisez la fonction ZSTD_decompress de la bibliothèque zstd. |
Voir aussi compressionAlgorithm().
Documentation des fonctions membres
QResource::QResource(const QString &file = QString(), const QLocale &locale = QLocale())
Construit une QResource pointant vers file. locale est utilisé pour charger une localisation spécifique des données d'une ressource.
Voir aussi QFileInfo, QDir::searchPaths(), setFileName(), et setLocale().
[noexcept] QResource::~QResource()
Libère les ressources de l'objet QResource.
QString QResource::absoluteFilePath() const
Renvoie le chemin réel que représente ce QResource, si la ressource a été trouvée via QDir::searchPaths(), cela sera indiqué dans le chemin.
Voir aussi fileName().
[protected] QStringList QResource::children() const
Renvoie une liste de toutes les ressources de ce répertoire. Si la ressource représente un fichier, la liste sera vide.
Voir aussi isDir().
QResource::Compression QResource::compressionAlgorithm() const
Renvoie le type de compression avec lequel cette ressource est compressée, le cas échéant. Si elle n'est pas compressée, cette fonction renvoie QResource::NoCompression.
Si cette fonction renvoie QResource::ZlibCompression, vous pouvez décompresser les données à l'aide de la fonction qUncompress(). Jusqu'à Qt 5.13, c'était le seul algorithme de compression possible.
Si cette fonction renvoie QResource::ZstdCompression, vous devez utiliser les fonctions de la bibliothèque Zstandard (en-tête<zstd.h> ). Qt ne fournit pas de wrapper.
Voir le manuel Zstandard.
Voir aussi data() et isFile().
const uchar *QResource::data() const
Renvoie un accès direct à un segment de données en lecture seule, que cette ressource représente. Si la ressource est compressée, les données renvoyées le sont également. L'appelant doit alors décompresser les données ou utiliser uncompressedData(). Si la ressource est un répertoire, nullptr est renvoyé.
Voir aussi uncompressedData(), size() et isFile().
QString QResource::fileName() const
Renvoie le chemin d'accès complet au fichier que représente ce QResource tel qu'il a été transmis.
Voir aussi setFileName() et absoluteFilePath().
[protected] bool QResource::isDir() const
Renvoie true si la ressource représente un répertoire et peut donc contenir children(), false si elle représente un fichier.
Voir aussi isFile().
[protected] bool QResource::isFile() const
Renvoie true si la ressource représente un fichier et a donc des données à l'appui, false si elle représente un répertoire.
Voir aussi isDir().
bool QResource::isValid() const
Renvoie true si la ressource existe réellement dans la hiérarchie des ressources, false sinon.
QDateTime QResource::lastModified() const
Renvoie la date et l'heure auxquelles le fichier a été modifié pour la dernière fois avant d'être empaqueté dans une ressource.
QLocale QResource::locale() const
Renvoie la locale utilisée pour localiser les données de QResource.
Voir aussi setLocale().
[static] bool QResource::registerResource(const QString &rccFileName, const QString &mapRoot = QString())
Enregistre la ressource avec l'adresse rccFileName à l'emplacement dans l'arborescence des ressources spécifié par mapRoot, et renvoie true si le fichier est ouvert avec succès ; sinon, renvoie false.
Voir aussi unregisterResource().
[static] bool QResource::registerResource(const uchar *rccData, const QString &mapRoot = QString())
Enregistre la ressource avec l'adresse rccData à l'emplacement dans l'arborescence des ressources spécifié par mapRoot, et renvoie true si le fichier est ouvert avec succès ; sinon, renvoie false.
Attention : Les données doivent rester valides pendant toute la durée de vie de QFile qui peut faire référence aux données de la ressource.
Voir aussi unregisterResource().
void QResource::setFileName(const QString &file)
Configure un QResource pour qu'il pointe vers file. file peut être absolu, auquel cas il est ouvert directement, s'il est relatif, le fichier sera recherché dans QDir::searchPaths().
Voir aussi fileName() et absoluteFilePath().
void QResource::setLocale(const QLocale &locale)
Configure un site QResource pour qu'il ne charge que la localisation de la ressource pour locale. Si une ressource pour la locale spécifique n'est pas trouvée, la locale C est utilisée.
Voir aussi locale() et setFileName().
qint64 QResource::size() const
Renvoie la taille des données stockées dans la ressource.
Si la ressource est compressée, cette fonction renvoie la taille des données compressées. Voir uncompressedSize() pour la taille non compressée.
Voir aussi data(), uncompressedSize() et isFile().
QByteArray QResource::uncompressedData() const
Renvoie les données de la ressource, en les décompressant d'abord, si les données ont été stockées sous forme compressée. Si la ressource est un répertoire ou si une erreur se produit lors de la décompression, une adresse QByteArray nulle est renvoyée.
Remarque : si les données ont été compressées, cette fonction les décompressera à chaque fois qu'elle sera appelée. Le résultat n'est pas mis en cache entre les appels.
Voir aussi uncompressedSize(), size(), compressionAlgorithm() et isFile().
qint64 QResource::uncompressedSize() const
Renvoie la taille des données contenues dans cette ressource. Si les données n'ont pas été compressées, cette fonction renvoie la même chose que size(). Dans le cas contraire, cette fonction extrait la taille des données originales non compressées du flux stocké.
Voir également size(), uncompressedData() et isFile().
[static] bool QResource::unregisterResource(const QString &rccFileName, const QString &mapRoot = QString())
Désenregistre la ressource avec l'adresse rccFileName à l'emplacement dans l'arbre des ressources spécifié par mapRoot, et renvoie true si la ressource a été déchargée avec succès et qu'aucune référence n'existe pour la ressource ; sinon, renvoie false.
Voir aussi registerResource().
[static] bool QResource::unregisterResource(const uchar *rccData, const QString &mapRoot = QString())
Désenregistre la ressource avec l'adresse rccData à l'emplacement dans l'arbre des ressources spécifié par mapRoot, et renvoie true si la ressource a été déchargée avec succès et qu'aucune référence n'existe dans la ressource ; sinon, renvoie false.
Voir aussi registerResource().
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
