Le système de ressources de Qt

Le système de ressources de Qt est un mécanisme indépendant de la plateforme de stockage de fichiers binaires, dans l'exécutable de l'application. Ce système vous sera très utile si votre application nécessite en permanence un ensemble de fichiers (icônes, fichiers de traduction, etc.), pour lesquels vous ne souhaitez pas courir le risque de perdre l'un d'entre eux.

Introduction

Le système de ressources est basé sur une forte coopération entre qmake, le rcc (le compilateur de ressources de Qt) et QFile. Il rend obsolète l'outil qembed de Qt 3 et le mécanisme de stockage d'images.

Les ressources associées à une application sont spécifiées dans un fichier

.qrc

, un format de fichier basé sur le XML qui liste les fichiers sur le disque et leur assigne optionnellement un nom de ressource, que l'application doit obligatoirement utiliser pour accéder à la ressource.

Voici un exemple de fichier .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>

Les ressources listées dans le fichier .qrc correspondent à des fichiers qui sont des parties de l'arbre des sources de l'application. Les chemins spécifiés sont relatifs au répertoire le contenant. Notez que les fichiers de ressources listées doivent être logés dans le même répertoire que celui du fichier .qrc, ou dans l'un de ses sous-répertoires.

Les données de ressources peuvent soit être compilées dans le binaire et par conséquent accéder immédiatement au code de l'application, ou bien une ressource binaire peut être créée et être enregistrée à un point postérieur du code de l'application, ou être enregistrée avec le système de ressources.

Par défaut, les ressources sont accessibles dans l'application sous le même nom de fichier qu'ils possèdent dans l'arbre source, avec le préfixe :/, ou par une URL avec le schèma qrc.

Par exemple, le chemin :/images/cut.png ou l'URL qrc:///images/cut.png donnerait un accès au fichier cut.png, dont l'emplacement dans l'arbre source de l'application est images/cut.png. Cela peut être changé par l'utilisation de l'attribut alias du tag file :

<file alias="cut-img.png">images/cut.png</file>

Le fichier est alors accessible depuis l'application par :/cut-img.png. Il est aussi possible de spécifier un préfixe de chemin pour tous les fichiers du .qrc par l'utilisation de l'attribut prefix du tag qresource :

<qresource prefix="/myresources">
     <file alias="cut-img.png">images/cut.png</file>
</qresource>

Dans ce cas, le fichier est accessible par :/myresources/cut-img.png.

Quelques ressources, comme les fichiers de traduction et les icônes, peuvent avoir besoin de changer en fonction de la position géographique de l'utilisateur. Cela peut être fait par l'ajout de l'attribut lang au tag qresource, en spécifiant une chaine de caractères appropriée. Par exemple :

<qresource>
     <file>cut.jpg</file>
</qresource>
<qresource lang="fr">
     <file alias="cut.jpg">cut_fr.jpg</file>
</qresource>

Si l'utilisateur est situé dans un pays francophone (donc si QLocal::system().name() retourne « fr_FR », « fr_CA », « fr_BE », en fonction du pays), :/cut.jpg devient une référence à l'image cut_fr.jpg. Pour les autres lieux, cut.jpg est utilisé.

Voir la documentation de QLocale pour une description du format à utiliser pour les chaînes de caractères de lieu.

Ressources binaires externes

Pour qu'une ressource binaire externe soit créée, vous devez créer les données de ressources (communément par un fichier d'extension .rcc) en passant le drapeau -binary à rcc. Une fois la ressource binaire créée, vous pouvez l'enregistrer avec l'API QResource.

Par exemple, un ensemble de données de ressource spécifié dans un fichier .qrc peut être compilé de la manière suivante :

rcc -binary myresource.qrc -o myresource.rcc

Dans l'application, cette ressource se voudrait être enregistrée avec un code tel que celui-ci :

QResource::registerResource("/path/to/myresource.rcc");

Ressources internes compilées

Pour qu'une ressource soit compilée dans le binaire, le fichier .qrc doit obligatoirement être mentionné dans le fichier .pro de l'application pour que qmake prenne connaissance de son existence. Par exemple :

RESOURCES     = application.qrc

qmake produira des règles de compilation pour générer un fichier appelé qrc_application.cpp, lié dans l'application.

Ce fichier contiendra toutes les informations des images et des autres ressources telles que des groupes statiques de données binaires compressées. Le fichier qrc_application.cpp est généré automatiquement à chaque fois que le fichier .qrc ou l'un des fichiers auquel il réfère change. Si vous ne vous servez pas de fichiers .pro, vous pouvez soit faire appel à rcc manuellement, soit ajouter des règles de compilation à votre système de compilation.

Actuellement et à chaque fois, Qt stocke directement les données dans l'exécutable, même sous Windows ou sous Mac OS X, où le système d'exploitation fournit un support natif aux ressources. Cela peut changer dans une version future de Qt.

Compression

Les ressources sont compressées par défaut (dans le format ZIP). Il est possible de désactiver la compression en fournissant -no-compress comme argument à la ligne de commande. Cela peut être utile si vos ressources contiennent déjà un format de compression tels que des fichiers .png.

 rcc -no-compress myresources.qrc

rcc vous donne également un certain contrôle sur la compression. Vous pouvez spécifier le niveau de compression et le seuil à considérer lors de la compression de fichiers, par exemple :

 rcc -compress 2 -threshold 3 myresources.qrc

L'utilisation des ressources dans l'application

Dans l'application, les chemins des ressources peuvent être utilisés dans la plupart des endroits à la place de chemins ordinaires de fichiers du système. En particulier, vous pouvez passer un chemin de ressource au lieu d'un nom de fichier au constructeur de QIcon, QImage ou QPixmap :

cutAct = new QAction(QIcon(":/images/cut.png"), tr("Cu&t"), this);

Regardez l'exemple Application pour une application actuelle qui utilise le système de ressources pour stocker ses icônes.

En mémoire, les ressources sont représentées par un arbre d'objets de ressources. L'arbre est automatiquement généré au lancement et utilisé par QFile pour résoudre les chemins vers les ressources. Vous pouvez utiliser un QDir initialisé avec  »:/ » pour naviguer à travers l'arbre de ressources depuis la racine.

Les ressources de Qt supportent le concept de liste de chemins de recherche. Si vous référez une ressource avec : au lieu de :/ comme le préfixe, la ressource sera verrouillée en utilisant la liste de chemins. La liste de chemins de recherche est vide au démarrage ; appelez QDir::addSearchPath() pour lui ajouter un chemin.

Si vous possédez des ressources dans une bibliothèque statique, il est possible que vous ayez besoin de forcer l'initialisation de vos ressources par l'appel de Q_INIT_RESOURCE() avec le nom de base du fichier .qrc. Par exemple :

int main(int argc, char *argv[])
{
     QApplication app(argc, argv);
     Q_INIT_RESOURCE(graphlib);
     ...
     return app.exec();
}

D'une manière similaire, si vous devez décharger un ensemble de ressources explicitement (car un plugin est en train d'être déchargé ou bien parce que les ressources ne sont pas valides plus longtemps), vous pouvez forcer la suppression de vos ressources par l'appel de Q_CLEANUP_RESOURCE() avec le même nom de base que celui qui est présent ci-dessus.

Remerciements

Merci à Louis du Verdier pour la traduction ainsi qu'à Thibaut Cuvelier et à Maxime Sannier pour leur relecture !