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 qu'ils poss�dent dans l'arbre source, avec le pr�fixe :/. Par exemple, le chemin :/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.

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 !