qt_target_qml_sources

Ajoute des fichiers QML et des ressources à une cible de module QML existante.

Cette commande a été introduite dans Qt 6.2.

La commande est définie dans le composant « Qml » du paquet « Qt6 », qui peut être chargé comme suit :

find_package(Qt6 REQUIRED COMPONENTS Qml)

Syntaxe

qt_target_qml_sources(
    target
    [QML_FILES ...]
    [RESOURCES ...]
    [PREFIX resource_path]
    [OUTPUT_TARGETS out_targets_var]
    [NO_LINT]
    [NO_CACHEGEN]
    [NO_QMLDIR_TYPES]
)

Si les commandes sans version sont désactivées, utilisez plutôt qt6_target_qml_sources(). Elle prend en charge les mêmes arguments que cette commande.

Description

qt_target_qml_sources() Permet d'ajouter des fichiers supplémentaires à un module QML après l'appel de la fonction qt_add_qml_module(). En règle générale, on transmet directement l'ensemble des fichiers d'.qml s et des ressources à qt_add_qml_module(), mais dans certains cas, il peut être souhaitable, voire nécessaire, d'ajouter des fichiers après l'appel de qt_add_qml_module(). Par exemple, vous pouvez souhaiter ajouter des fichiers de manière conditionnelle en fonction d’une expression de la directive ` if `, ou à partir de sous-répertoires qui ne seront ajoutés que si certains critères sont remplis. Vous pouvez vouloir ajouter un ensemble de fichiers présentant des caractéristiques différentes des autres, comme un préfixe de ressource différent, ou pour lesquels la vérification lint et la compilation en bytecode sont désactivées. La commande ` qt_target_qml_sources() ` permet de gérer ces scénarios.

Arguments

L’ target e doit être la cible de base d’un module QML ou, si le module QML ne dispose pas de cible de base distincte, il doit s’agir de la cible « plugin » du module.

QML_FILES est une liste de fichiers ` .qml`, ` .js ` et ` .mjs ` à ajouter au module QML. Cette option a exactement le même effet que l’option ` QML_FILES ` de la commande `qt_add_qml_module()`, y compris la compilation automatique en bytecode et le traitement lint.

Les options « NO_CACHEGEN » et « NO_LINT » ont également le même effet que pour la commande `qt_add_qml_module()`. Elles désactivent la compilation en bytecode et le traitement lint pour les fichiers répertoriés avec ` QML_FILES`. Ce comportement peut également être spécifié pour des fichiers individuels à l’aide des propriétés des fichiers source.

NO_QMLDIR_TYPES empêche l’ajout des ` QML_FILES ` en tant que types dans le fichier ` qmldir ` généré.

RESOURCES a exactement le même effet que l’option ` RESOURCES ` de la commande ` qt_add_qml_module()`. Elle fournit une liste de fichiers à ajouter au ` target ` en tant que ressources ordinaires. Ces fichiers sont généralement des éléments tels que des images, des shaders, etc., auxquels le code QML fait référence d’une manière ou d’une autre.

Les fichiers ajoutés au module via ` QML_FILES ` ou ` RESOURCES ` seront placés sous le même préfixe de ressource et le même chemin cible que s’ils avaient été ajoutés par la commande `qt_add_qml_module()`. Il est possible de contourner ce comportement en spécifiant un emplacement différent avec l’option ` PREFIX `. La valeur suivant le mot-clé ` PREFIX ` sera utilisée directement, sans ajout de chemin cible. Le chemin d’accès final de chaque fichier sera constitué du préfixe, suivi du chemin d’accès du fichier sous CMAKE_CURRENT_SOURCE_DIR. La propriété du fichier source QT_RESOURCE_ALIAS peut également être utilisée pour redéfinir ce chemin relatif.

qt_add_qml_module(backing
    URI Example
    VERSION 1.0
    RESOURCE_PREFIX /my.company.com/imports
)

qt_target_qml_sources(backing
    QML_FILES special/First.qml
    RESOURCES icons/logo.png
)

qt_target_qml_sources(backing
    PREFIX /other.company.com/debugging
    QML_FILES Inspector.qml
)

Dans l’exemple ci-dessus, les ressources de la cible « backing » présenteront finalement le contenu suivant :

• /my.company.com/imports/Example/special/First.qml
• /my.company.com/imports/Example/icons/logo.png
• /other.company.com/debugging/Inspector.qml

OUTPUT_TARGETS est également analogue à la même option de `qt_add_qml_module()`. Utilisez-la pour spécifier le nom d’une variable dans laquelle stocker les cibles supplémentaires créées pour les compilations statiques. Si l’ target est installée, ces cibles supplémentaires devront également être installées pour répondre aux exigences de liaison.

Propriétés des fichiers source

Un certain nombre de propriétés de fichiers source peuvent être utilisées pour influencer la manière dont chaque fichier d’ .qml est traité à différentes étapes du traitement du module QML. Celles-ci prévalent sur toute option de niveau supérieur spécifiée dans les appels à ` qt_target_qml_sources() ` ou `qt_add_qml_module()`. Toutes ces propriétés doivent être définies avant que les fichiers ne soient ajoutés à l’aide de l’une de ces deux commandes.

QT_QML_SKIP_QMLLINT La propriété « TRUE » peut être définie sur un fichier source pour l'empêcher d'être inclus dans le traitement automatique par qmllint. Par défaut, tous les fichiers .qml sont inclus dans l'exécution de lint de la cible, mais cette option permet d'exclure des fichiers spécifiques.

QT_QML_SKIP_CACHEGEN a un effet similaire : elle empêche un fichier source d’être compilé en byte code lorsque cette propriété est définie sur « TRUE ». Notez que le fichier sera tout de même ajouté à l’ target en tant que ressource sous forme non compilée (voir Mise en cache des sources QML compilées).

Définissez la propriété « QT_QML_SKIP_QMLDIR_ENTRY » du fichier source sur « TRUE » pour empêcher que ce fichier QML ou JavaScript ne soit ajouté en tant que type au fichier « qmldir » du module QML (voir Génération automatique des fichiers « qmldir » et « typeinfo »). Cette option est généralement utilisée pour un fichier qui n’expose pas de type public, tel qu’un fichier JavaScript privé. Pour les fichiers JavaScript dont le nom commence par une majuscule et qui ne sont ni des modules ECMAScript ni déclarés comme bibliothèques sans état via .pragma library, vous devriez envisager cette option. Si vous les incluez dans le fichier qmldir, ils sont réévalués dans la portée de chaque document QML qui importe explicitement ou implicitement le module auquel ils appartiennent.

Par défaut, lors de la génération du fichier ` qmldir `, une seule entrée de type est générée pour chaque fichier ` .qml ` fournissant un type. Elle se voit attribuer un numéro de version de la forme ` X.0 `, où ` X ` correspond à la version majeure du module QML. Si le module QML dispose de fichiers ` PAST_MAJOR_VERSIONS `, le même schéma s’applique également à ceux-ci, en ajoutant ` X.0 ` pour chaque version majeure antérieure de la forme ` X`. Dans les cas où un fichier doit fournir des entrées de type pour un ensemble différent de versions (par exemple, s'il a été ajouté pour la première fois dans une version de correctif mineure après la sortie de .0 ), spécifiez ces versions dans la propriété QT_QML_SOURCE_VERSIONS du fichier source. Une entrée de type sera créée pour chaque version.

Si le type fourni par un fichier ` .qml ` est un singleton, définissez sa propriété ` QT_QML_SINGLETON_TYPE ` sur ` TRUE`. De même, la propriété source ` QT_QML_INTERNAL_TYPE ` du fichier peut être définie sur ` TRUE ` pour indiquer que le type qu’il fournit est interne. Le nom du type lui-même peut également être redéfini à l’aide de la propriété « QT_QML_SOURCE_TYPENAME ». Ces trois éléments seront pris en compte dans les entrées de type du fichier dans le fichier « qmldir » généré. Les propriétés « source » doivent être définies avant la création du module auquel appartient le singleton.

Tous les fichiers répertoriés avec « QML_FILES » ou « RESOURCES » seront ajoutés aux ressources de « target ». Leur emplacement dans les ressources se compose d’un point de base et d’un chemin relatif. Par défaut, le point de base correspond à la concaténation du préfixe de ressource du module QML et de son chemin cible, mais ceux-ci peuvent être redéfinis à l’aide de l’argument « PREFIX ». Le chemin relatif correspond par défaut au chemin du fichier par rapport à la propriété cible « SOURCE_DIR » de l’ target. Ce chemin relatif peut être redéfini en définissant la propriété « QT_RESOURCE_ALIAS » sur le fichier source. Cette fonctionnalité est couramment utilisée pour regrouper des fichiers provenant de différents répertoires et les faire apparaître dans les ressources sous un emplacement commun. Cependant, depuis Qt 6.8, l’activation de QTP0004 est souvent une meilleure option si l’objectif est que tous les fichiers du module Qml puissent être trouvés dans l’importation implicite. Dans les cas où une telle configuration manuelle reste nécessaire, il est conseillé de passer ` NO_GENERATE_EXTRA_QMLDIRS ` à ` qt_add_qml_module`, car les `qmldirs` supplémentaires ne prennent pas en compte les alias des fichiers de ressources.

set_source_files_properties(nested/way/down/File.qml PROPERTIES
    QT_RESOURCE_ALIAS File.qml
)
set_source_files_properties(TemplateFile.qml PROPERTIES
    QT_RESOURCE_ALIAS templates/File.qml
    QT_QML_SKIP_QMLDIR_ENTRY TRUE
    QT_QML_SKIP_QMLLINT TRUE
    QT_QML_SKIP_CACHEGEN TRUE
)
set_source_files_properties(FunnySingleton.qml PROPERTIES
    QT_QML_SINGLETON_TYPE TRUE
)
qt_add_qml_module(qt_target_qml_sources_example
    URI Example
    VERSION 2.3
    RESOURCE_PREFIX /my.company.com/imports
    NO_GENERATE_EXTRA_QMLDIRS
    QML_FILES
        nested/way/down/File.qml
        TemplateFile.qml
        FunnySingleton.qml
)

set_source_files_properties(some_old_thing.qml PROPERTIES
    QT_QML_SOURCE_VERSIONS "1.1;2.0"
    QT_QML_SOURCE_TYPENAME OldThing
)
set_source_files_properties(../../../images/button-types.png PROPERTIES
    QT_RESOURCE_ALIAS button-types.png
)
qt_target_qml_sources(qt_target_qml_sources_example
    QML_FILES some_old_thing.qml
    RESOURCES
        ../../../images/button-types.png
        doc/README.txt
)

Dans l’exemple ci-dessus, les ressources de la cible « qt_target_qml_sources_example » présenteront finalement le contenu suivant :

• /my.company.com/imports/Example/File.qml
• /my.company.com/imports/Example/FunnySingleton.qml
• /my.company.com/imports/Example/templates/File.qml
• /my.company.com/imports/Example/some_old_thing.qml
• /my.company.com/imports/Example/button-types.png
• /my.company.com/imports/Example/doc/README.txt

Le fichier « qmldir » généré contiendra les entrées de type suivantes :

File 2.0 File.qml
singleton FunnySingleton 2.0 FunnySingleton.qml
OldThing 1.1 some_old_thing.qml
OldThing 2.0 some_old_thing.qml

pragma Singleton
import QtQml

QtObject {}