QResource Class
La classe QResource offre une interface permettant de lire directement à partir des ressources. En savoir plus...
| 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 la catégorie « Entrée/Sortie et réseau ».
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 des enfants) relatives à une seule entité de ressource. QResource donne un accès direct aux octets dans leur format brut. Cet accès direct permet ainsi de lire les données sans copie dans une mémoire tampon ni indirection. L'indirection est souvent utile lorsqu'on interagit avec l'entité de ressource comme s'il s'agissait d'un fichier ; cela peut être réalisé à l'aide de ` QFile`. Les données et les éléments enfants associés à un `QResource` sont normalement compilés dans une application ou une bibliothèque, mais il est également possible de charger une ressource au moment de l'exécution. Lorsqu’elle est chargée à l’exécution, la ressource est chargée sous la forme d’un seul grand ensemble de données, puis distribuée par morceaux via des références dans l’arborescence des ressources.
Une QResource peut être chargée soit avec un chemin absolu, soit traitée comme un système de fichiers dont la racine est le caractère « / », soit en notation de ressource dont la racine est le caractère « : ». Il est également possible d’ouvrir une ressource relative qui figurera dans la liste des chemins renvoyée par la fonction QDir::searchPaths().
Une QResource représentant un fichier contient des données sous-jacentes ; celles-ci peuvent être compressées, auquel cas la fonction qUncompress() doit être utilisée pour accéder aux données réelles ; cela se produit implicitement lorsqu’on y accède via un QFile. Une QResource représentant un répertoire ne contient que des éléments enfants et aucune donnée.
Chargement dynamique des ressources
Une ressource peut être exclue du binaire d’une application et chargée au moment voulu lors de l’exécution à l’aide de la fonction registerResource(). Le fichier de ressources passé à registerResource() doit être une ressource binaire telle que créée par rcc. Vous trouverez de plus amples informations sur les ressources binaires dans la documentation du système de ressources Qt.
Cette approche s’avère souvent utile lors du chargement d’un grand ensemble d’icônes d’application susceptibles de changer en fonction d’un paramètre, ou pouvant être modifiées par un utilisateur puis recréées ultérieurement. La ressource est immédiatement chargée en mémoire, soit à la suite d’une simple opération de lecture de fichier, soit sous la forme d’un fichier mappé en mémoire.
Cette approche peut se révéler être un gain de performances significatif, car un seul fichier sera chargé et les données seront fournies via le chemin demandé dans ` setFileName()`.
La fonction unregisterResource() supprime une référence à un fichier particulier. S’il existe des objets QResource qui font actuellement référence à des ressources liées au fichier désenregistré, ceux-ci resteront valides, mais le fichier de ressources lui-même sera supprimé des racines de ressources ; par conséquent, aucun autre objet QResource ne pourra être créé pointant vers ces données de ressources. La ressource elle-même sera déchargée de la mémoire lorsque le dernier objet QResource qui y fait référence sera détruit.
Corruption et sécurité
La classe QResource effectue certaines vérifications sur le fichier transmis afin de déterminer s’il est pris en charge par la version actuelle de Qt. Ces tests visent uniquement à vérifier que l’en-tête du fichier ne demande pas de fonctionnalités (telles que la décompression Zstandard) qui n’ont pas été intégrées lors de la compilation, ou que le fichier ne provient pas d’une future version de Qt. Ils ne garantissent pas la validité de l’intégralité du fichier.
QResource ne doit pas être utilisé avec des fichiers dont la provenance n’est pas fiable. Les applications doivent être conçues pour ne tenter de charger que 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 également « 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 la méthode compressionAlgorithm() pour indiquer quel algorithme l'outil RCC a utilisé 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 le 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())
Crée une ressource QResource pointant vers file. locale permet de charger une localisation spécifique des données d’une ressource.
Voir également QFileInfo, QDir::searchPaths(), setFileName() et setLocale().
[noexcept] QResource::~QResource()
Libère les ressources de l'objet « QResource ».
QString QResource::absoluteFilePath() const
Renvoie le chemin d'accès réel représenté par cette QResource. Si la ressource a été trouvée via la fonction QDir::searchPaths(), cela sera indiqué dans le chemin d'accès.
Voir également fileName().
[protected] QStringList QResource::children() const
Renvoie une liste de toutes les ressources présentes dans ce répertoire ; si la ressource correspond à un fichier, la liste sera vide.
Voir aussi isDir().
QResource::Compression QResource::compressionAlgorithm() const
Renvoie le type de compression utilisé pour cette ressource, le cas échéant. Si celle-ci 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 d’enveloppe.
Consultez le manuel de Zstandard.
Voir également data() et isFile().
const uchar *QResource::data() const
Renvoie un accès direct à un segment de données en lecture seule représenté par cette ressource. 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 la fonction uncompressedData(). Si la ressource est un répertoire, la fonction nullptr est renvoyée.
Voir également uncompressedData(), size() et isFile().
QString QResource::fileName() const
Renvoie le chemin d'accès complet du fichier représenté par cet objet ` QResource `, tel qu'il a été transmis.
Voir également setFileName() et absoluteFilePath().
[protected] bool QResource::isDir() const
Renvoie ` true ` si la ressource correspond à un répertoire et peut donc contenir des éléments de type ` children()` ; renvoie `false` si elle correspond à un fichier.
Voir également isFile().
[protected] bool QResource::isFile() const
Renvoie ` true ` si la ressource correspond à un fichier et contient donc des données, et `false` si elle correspond à un répertoire.
Voir également isDir().
bool QResource::isValid() const
Renvoie « true » si la ressource existe bel et bien dans la hiérarchie des ressources, sinon « false ».
QDateTime QResource::lastModified() const
Renvoie la date et l'heure de la dernière modification du fichier avant son intégration dans une ressource.
QLocale QResource::locale() const
Renvoie les paramètres régionaux utilisés pour localiser les données de l'QResource.
Voir aussi setLocale().
[static] bool QResource::registerResource(const QString &rccFileName, const QString &mapRoot = QString())
Enregistre la ressource avec l'rccFileName fournie à l'emplacement de l'arborescence des ressources spécifié par mapRoot, et renvoie true si le fichier s'ouvre correctement ; sinon, renvoie false.
Voir également unregisterResource().
[static] bool QResource::registerResource(const uchar *rccData, const QString &mapRoot = QString())
Enregistre la ressource avec l'rccData e indiquée à l'emplacement de l'arborescence des ressources spécifié par mapRoot, et renvoie true si le fichier s'ouvre correctement ; sinon, renvoie false.
Avertissement : les données doivent rester valides pendant toute la durée de vie de tout QFile susceptible de faire référence aux données de la ressource.
Voir également unregisterResource().
void QResource::setFileName(const QString &file)
Définit un objet ` QResource ` pour qu'il pointe vers ` file`. ` file ` peut être une adresse absolue, auquel cas le fichier est ouvert directement ; s'il s'agit d'une adresse relative, le système tentera de localiser le fichier via la fonction ` QDir::searchPaths()`.
Voir également fileName() et absoluteFilePath().
void QResource::setLocale(const QLocale &locale)
Définit une QResource permettant de ne charger que la localisation de la ressource pour locale. Si aucune ressource correspondant à la locale spécifiée n'est trouvée, c'est la locale C qui est utilisée.
Voir également locale() et setFileName().
qint64 QResource::size() const
Renvoie la taille des données stockées associées à 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 également data(), uncompressedSize() et isFile().
QByteArray QResource::uncompressedData() const
Renvoie les données de la ressource après les avoir décompressées, si celles-ci étaient stockées sous forme compressée. Si la ressource est un répertoire ou si une erreur survient lors de la décompression, une valeur nulle QByteArray est renvoyée.
Remarque : si les données étaient compressées, cette fonction les décompressera à chaque appel. Le résultat n’est pas mis en cache entre les appels.
Voir également 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 valeur que size(). Si elles l’ont été, cette fonction extrait la taille des données d’origine non compressées à partir du flux stocké.
Voir également size(), uncompressedData() et isFile().
[static] bool QResource::unregisterResource(const QString &rccFileName, const QString &mapRoot = QString())
Désenregistre la ressource associée à l'rccFileName indiquée à l'emplacement de l'arborescence des ressources spécifié par mapRoot, et renvoie true si la ressource a été déchargée avec succès et qu'il n'existe aucune référence à celle-ci ; sinon, renvoie false.
Voir également registerResource().
[static] bool QResource::unregisterResource(const uchar *rccData, const QString &mapRoot = QString())
Désenregistre la ressource associée à l'rccData indiquée à l'emplacement de l'arborescence des ressources spécifié par mapRoot, et renvoie true si la ressource a été déchargée avec succès et qu'il n'existe aucune référence vers celle-ci ; sinon, renvoie false.
Voir également 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.
