Le système de ressources Qt

Le système de ressources Qt est un mécanisme indépendant de la plate-forme permettant d’intégrer des fichiers de ressources dans une application. Utilisez-le si votre application a toujours besoin d’un ensemble spécifique de fichiers (tels que des icônes, des fichiers de traduction ou des images) et si vous ne souhaitez pas recourir à des moyens propres au système pour regrouper et localiser ces ressources.

Le plus souvent, les fichiers de ressources sont intégrés dans l'exécutable de votre application, ou dans des bibliothèques et des plugins chargés par l'exécutable de l'application. Les fichiers de ressources peuvent également être stockés dans un fichier de ressources externe.

Le système de ressources repose sur une étroite collaboration entre le Resource Compiler de Qt, le système de compilation et l'API d'exécution Qt.

Le compilateur de ressources Qt XML ( Resource Compiler, rcc)

L'outil en ligne de commande « Resource Compiler » (rcc) lit les fichiers de ressources et génère soit un fichier source C++ ou Python, soit un fichier « .rcc ».

La liste des fichiers et des métadonnées associées est transmise à rcc sous la forme d’un fichier de collection de ressources Qt.

Par défaut, rcc génère du code source C++ qui est ensuite compilé pour former un exécutable ou une bibliothèque. L’option ` -g python ` génère à la place du code source Python. L’option ` -binary ` génère une archive binaire qui, par convention, est enregistrée dans un fichier ` .rcc ` et peut être chargée lors de l’exécution.

Fichier de collection de ressources Qt (.qrc)

Un fichier « .qrc » est un document XML qui répertorie les fichiers locaux à inclure en tant que ressources d'exécution. Il sert de données d'entrée à la commande ` rcc`.

Voici un exemple de fichier ` .qrc ` :

<RCC>
    <qresource prefix="/">
        <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>

Chaque élément <file> du fichier XML identifie un fichier situé dans l’arborescence des sources de l’application. Le chemin d’accès est résolu par rapport au répertoire contenant le fichier .qrc.

Ce chemin est également utilisé par défaut pour identifier le contenu du fichier lors de l'exécution. Autrement dit, le fichier copy.png sera disponible dans le système de ressources sous le nom :/images/copy.png ou qrc:/images/copy.png. Pour remplacer ce nom par défaut lors de l'exécution, consultez la section Préfixes et alias.

Qt Creator, Qt Design Studio, Qt Widgets Designer, Qt Extension for Visual Studio Code, et Qt Visual Studio Tools vous permettent de créer, d’inspecter et de modifier des fichiers « .qrc » via une interface utilisateur pratique. À l’exception de l’éditeur « Qt Widgets », ils fournissent également des assistants pour les projets utilisant le système de ressources Qt.

Intégration au système de compilation

Le traitement des fichiers de ressources avec l’ rcc s’effectue généralement au moment de la compilation de l’application. Plusieurs outils de compilation prennent cela en charge, notamment CMake et qmake.

CMake

Si l'option « CMAKE_AUTORCC » est activée, il vous suffit d'ajouter des fichiers ` .qrc ` en tant que sources à votre exécutable ou à votre bibliothèque. Les fichiers de ressources référencés seront alors intégrés dans le binaire :

set(CMAKE_AUTORCC ON)

qt_add_executable(my_app
    application.qrc
    main.cpp
)

Consultez la documentation de CMake consacrée à AUTORCC pour plus de détails sur cette fonctionnalité.

Une alternative à AUTORCC consiste à utiliser la fonction CMake qt_add_resources de Qt6Core, qui offre un contrôle accru sur la création des ressources. Par exemple, elle vous permet de spécifier le contenu de la ressource directement dans le fichier de projet sans avoir à créer au préalable un fichier « .qrc » :

qt_add_resources(my_app "app_images"
    PREFIX "/"
    FILES
        images/copy.png
        images/cut.png
        images/new.png
        images/open.png
        images/paste.png
        images/save.png
)

Enfin, la fonction `qt_add_qml_module` vous permet d’intégrer des ressources ` Qt Quick ` dans le système de ressources de votre application. Cette fonction est définie dans le composant ` Qml ` du paquet CMake ` Qt6 `.

qmake

qmake prend en charge la gestion des ressources via la variable RESOURCES. Si vous ajoutez un chemin d'accès à un fichier .qrc à cette variable, les fichiers de ressources répertoriés seront intégrés dans la bibliothèque ou l'exécutable généré :

RESOURCES = application.qrc

Pour les applications simples, il est également possible de laisser qmake générer le fichier ` .qrc ` à votre place, ce qui vous évite d’avoir à gérer un fichier supplémentaire :

resources.files = \
    images/copy.png \
    images/cut.png \
    images/new.png \
    images/open.png \
    images/paste.png \
    images/save.png
resources.prefix = /

RESOURCES = resources

Cela crée une ressource composée de plusieurs fichiers ` .png `, accessibles de la manière suivante : ` ":/images/copy.png"`.

Si la structure des répertoires des fichiers que vous souhaitez intégrer à la ressource ne correspond pas aux attentes de l’application, vous pouvez spécifier resources.base. base est un préfixe de chemin qui désigne la racine de l’alias du fichier. Dans l’exemple ci-dessous, si resources.base est défini sur "images", alors copy.png est accessible sous la forme ":/copy.png".

API d'exécution

L’API Qt chargée de la lecture et de la parcouru des fichiers intègre une prise en charge native du système de ressources Qt. Vous pouvez transmettre un chemin de ressource à la place d’un chemin de fichier local aux méthodes ` QFile ` et ` QDir`, mais aussi, par exemple, aux constructeurs ` QIcon`, ` QImage` et ` QPixmap ` :

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

Le préfixe : indique explicitement que « /images/cut.png » doit être chargé à partir du système de ressources Qt.

Vous pouvez également référencer le système de ressources Qt via un QUrl. Utilisez dans ce cas le schéma qrc:

    QQmlApplicationEngine engine;
    engine.load(QUrl("qrc:/myapp/main.qml"));

Sujets avancés

Préfixes

Un fichier « .qrc » peut définir un préfixe à ajouter à chaque nom de fichier local, indiqué dans un élément « <file> », afin d’obtenir le nom sous lequel le fichier sera connu au sein du système de ressources.

Les préfixes vous permettent de structurer les ressources, en évitant les conflits entre les fichiers de ressources ajoutés via différents fichiers ` .qrc ` dans différentes bibliothèques ou différents plugins.

Alias

Il est parfois pratique de rendre un fichier de ressources accessible sous un autre chemin d’accès lors de l’exécution. Les fichiers .qrc permettent cela en définissant un attribut alias:

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

Le fichier n'est alors accessible depuis l'application que sous la forme :/cut-img.png ou qrc:/cut-img.png.

Ignorer le contenu du fichier

Il arrive parfois que l’on souhaite ajouter un nœud de fichier au système de fichiers de ressources sans pour autant ajouter le contenu du fichier. Les fichiers de type « .qrc » permettent cela en définissant l’attribut empty sur true.

<file empty="true">Button.qml</file>

Le fichier ainsi créé reste alors accessible depuis l'application, mais son contenu est vide.

Cela s’avère utile pour extraire le code source QML d’un binaire d’application.

Sélecteurs de langue

Certaines ressources doivent varier en fonction des paramètres régionaux de l’utilisateur, comme les fichiers de traduction ou les icônes. Les fichiers de collection de ressources prennent cela en charge grâce à l’attribut « lang » de la balise « qresource », qui permet de spécifier une chaîne de paramètres régionaux appropriée. Par exemple :

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

Si les paramètres régionaux de l’utilisateur sont le français (c’est-à-dire que QLocale::system().language() est « français »), :/cut.jpg ou qrc:/cut.jpg renvoie alors à l’image cut_fr.jpg. Pour les autres paramètres régionaux, on utilise cut.jpg.

Consultez la documentation QLocale pour obtenir une description du format à utiliser pour les chaînes de paramètres régionaux.

Consultez QFileSelector pour découvrir un mécanisme supplémentaire permettant de sélectionner des ressources spécifiques à une locale.

Intégration de fichiers volumineux

Par défaut, rcc intègre les fichiers de ressources dans les exécutables sous la forme de tableaux C++. Cela peut poser problème, en particulier pour les ressources volumineuses.

Si la compilation prend trop de temps, voire échoue en raison d’un débordement de mémoire, vous pouvez opter pour un mode spécial dans lequel les ressources sont intégrées au cours d’un processus en deux étapes. Le compilateur C++ se contente de réserver suffisamment d'espace dans l'exécutable ou la bibliothèque cible pour accueillir ces ressources. L'intégration effective du contenu et des métadonnées du fichier de ressources s'effectue ensuite, après la phase de compilation et de liaison, via un autre appel à la fonction rcc.

Pour qmake, cette fonctionnalité s’active en ajoutant « resources_big » à la variable « CONFIG » :

CONFIG += resources_big

Pour CMake, vous devez utiliser la fonction ` qt_add_big_resources `.

Fichiers de ressources externes

Au lieu d’intégrer les fichiers de ressources dans le binaire, il est possible de les stocker dans un fichier séparé de type « .rcc ». L’option ` -binary ` de ` rcc ` permet cette opération. Un tel fichier ` .rcc ` doit ensuite être chargé lors de l’exécution à l’aide de ` QResource`.

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

rcc -binary myresource.qrc -o myresource.rcc

Dans l’application, cette ressource serait enregistrée à l’aide d’un code similaire à celui-ci :

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

Si vous utilisez CMake, vous pouvez utiliser la fonction ` qt_add_binary_resources ` pour planifier l'appel ` rcc ` ci-dessus :

qt_add_binary_resources(resources application.qrc DESTINATION application.rcc)
add_dependencies(my_app resources)

Ressources dans une application Qt for Python

Le fichier de collecte des ressources est converti en module Python à l'aide du Resource Compiler rcc:

rcc -g python mainwindow.qrc > mainwindow_rc.py

Le module peut ensuite être importé dans l'application :

import mainwindow_rc.py

Compression

rcc tente de compresser le contenu afin d’optimiser l’utilisation de l’espace disque dans les binaires finaux. Par défaut, il effectue une vérification heuristique pour déterminer si la compression est utile et stocke le contenu sans le compresser s’il ne parvient pas à le compresser suffisamment. Pour contrôler ce seuil, vous pouvez utiliser l’option ` -threshold `, qui indique à rcc le pourcentage de la taille du fichier d’origine qui doit être gagné pour que le fichier soit stocké sous forme compressée.

rcc -threshold 25 myresources.qrc

La valeur par défaut est « 70 », ce qui signifie que le fichier compressé doit être 70 % plus petit que l’original (soit pas plus de 30 % de la taille du fichier d’origine).

Il est possible de désactiver la compression si vous le souhaitez. Cela peut s’avérer utile si vos ressources sont déjà au format compressé, comme les fichiers .png, et que vous ne souhaitez pas mobiliser de ressources CPU lors de la compilation pour vérifier qu’elles ne peuvent pas être compressées. Une autre raison peut être que l’utilisation du disque ne pose pas de problème et que l’application préfère conserver le contenu sous forme de pages mémoire vierges lors de l’exécution. Pour ce faire, vous devez passer l’argument de ligne de commande ` -no-compress `.

rcc -no-compress myresources.qrc

rcc Cela vous permet également de contrôler le niveau de compression et l'algorithme de compression, par exemple :

rcc -compress 2 -compress-algo zlib myresources.qrc

Il est également possible d’utiliser compress et threshold comme attributs dans une balise file du fichier .qrc. Pour sélectionner l’algorithme, définissez l’attribut compression-algorithm.

<qresource>
    <file compress="1" compression-algorithm="zstd">data.txt</file>
</qresource>

La configuration ci-dessus sélectionnera l’algorithme zstd avec un niveau de compression de 1.

rcc prend en charge les algorithmes de compression et niveaux de compression suivants :

• best: utilise le meilleur algorithme parmi ceux ci-dessous, à son niveau de compression le plus élevé, afin d’obtenir la compression maximale au prix d’une utilisation importante du temps CPU lors de la compilation. Cette valeur est utile dans le fichier XML pour indiquer qu’un fichier doit être compressé au maximum, quels que soient les algorithmes pris en charge par rcc.
• zstd: utilise la bibliothèque Zstandard pour compresser le contenu. Les niveaux de compression valides vont de 1 à 19, 1 correspondant à la compression la plus faible (temps CPU le plus court) et 19 à la compression la plus forte (temps CPU le plus long). Le niveau par défaut est 14. Une valeur spéciale de 0 indique à la bibliothèque zstd de choisir une valeur par défaut définie par l’implémentation.
• zlib: utilise la bibliothèque zlib pour compresser le contenu. Les niveaux de compression valides vont de 1 à 9, 1 correspondant à la compression la plus faible (temps CPU le plus court) et 9 à la compression la plus forte (temps CPU le plus long). La valeur spéciale 0 signifie « aucune compression » et ne doit pas être utilisée. La valeur par défaut est définie par l'implémentation, mais correspond généralement au niveau 6.
• none: aucune compression. Cela revient à l’option ` -no-compress `.

La prise en charge de Zstandard et de zlib est facultative. Si une bibliothèque donnée n’a pas été détectée lors de la compilation, toute tentative de passer l’option ` -compress-algo ` pour cette bibliothèque entraînera une erreur. L’algorithme de compression par défaut est ` zstd ` s’il est activé, et ` zlib ` dans le cas contraire.

Chargement et déchargement explicites des ressources intégrées

Les ressources intégrées dans le code exécutable ou dans une bibliothèque C++ sont automatiquement enregistrées dans le système de ressources Qt via le constructeur d’une variable globale interne. Comme les variables globales sont initialisées avant l’exécution de la fonction main(), les ressources sont disponibles dès le démarrage du programme.

Lors de l’intégration de ressources dans des bibliothèques statiques, l’éditeur de liens C++ peut supprimer les variables statiques qui enregistrent les ressources. Si vous intégrez des ressources dans une bibliothèque statique, vous devez donc enregistrer explicitement vos ressources en appelant ` Q_INIT_RESOURCE()` avec le nom de base du fichier ` .qrc `. Par exemple :

MyClass::MyClass() : BaseClass()
{
    Q_INIT_RESOURCE(resources);

    QFile file(":/myfile.dat");
    //...
}

Vous pouvez également supprimer explicitement des ressources enregistrées de l’application, par exemple lors du déchargement d’un plugin. Utilisez pour cela la fonction ` Q_CLEANUP_RESOURCE()`.

Remarque : les initialiseurs de ressources générés par rcc étant déclarés dans l’espace de noms global, vos appels à Q_INIT_RESOURCE() et Q_CLEANUP_RESOURCE() doivent être effectués en dehors de tout espace de noms.