qt_target_qml_sources

Ajoute des fichiers et des ressources QML à 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 paquetage Qt6, qui peut être chargé comme suit :

find_package(Qt6 REQUIRED COMPONENTS Qml)

Synopsis

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 qt6_target_qml_sources() à la place. Elle prend en charge le même ensemble d'arguments que cette commande.

Description de la commande

qt_target_qml_sources() La commande qt_add_qml_module () permet d'ajouter des fichiers à un module QML après que qt_add_qml_module() ait été appelée. Typiquement, vous passez l'ensemble des fichiers et ressources .qml à qt_add_qml_module( ) directement, mais dans certains cas, il peut être souhaitable, ou même nécessaire, d'ajouter des fichiers après que qt_add_qml_module() ait été appelée. Par exemple, vous pouvez souhaiter ajouter des fichiers de manière conditionnelle sur la base d'une expression de l'instruction if, ou à partir de sous-répertoires qui ne seront ajoutés que si certains critères sont remplis. Vous pourriez vouloir ajouter un ensemble de fichiers avec des caractéristiques différentes des autres, comme un préfixe de ressource différent, ou avec le linting et la compilation du bytecode désactivés. La commande qt_target_qml_sources() permet de réaliser ces scénarios.

Arguments

Le site target doit être la cible de référence d'un module QML ou, si le module QML n'a pas de cible de référence distincte, il doit s'agir de la cible du 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 qt_add_qml_module(). Elles désactivent la compilation du bytecode et le traitement lint pour les fichiers listés avec QML_FILES. Ce comportement peut également être spécifié pour des fichiers individuels en utilisant les propriétés du fichier source.

NO_QMLDIR_TYPES empêche l'ajout de 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 à target en tant que ressources ordinaires. Ces fichiers sont généralement 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(). Ceci peut être surchargé en fournissant un emplacement différent avec l'option PREFIX. La valeur qui suit le mot-clé PREFIX sera utilisée directement, sans ajouter de chemin cible. Le chemin de ressource final de chaque fichier sera le préfixe, plus le chemin du fichier situé sous le mot-clé CMAKE_CURRENT_SOURCE_DIR. La propriété QT_RESOURCE_ALIAS du fichier source peut également être utilisée pour remplacer 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 auront 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 pour qt_add_qml_module(). Utilisez-la pour spécifier le nom d'une variable dans laquelle stocker toutes les cibles supplémentaires créées pour les constructions statiques. Si le site target est installé, ces cibles supplémentaires devront également être installées pour satisfaire les exigences de liaison.

Propriétés du fichier source

Un certain nombre de propriétés du fichier source peuvent être utilisées pour influencer la manière dont chaque fichier .qml est traité à différents moments du traitement du module QML. Ces propriétés remplacent toutes les options de plus haut niveau spécifiées 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 avec l'une ou l'autre de ces deux commandes.

QT_QML_SKIP_QMLLINT peut être défini à TRUE sur un fichier source pour éviter qu'il ne soit inclus dans le traitement automatique de qmllint. Par défaut, tous les fichiers .qml seront inclus dans le traitement lint de la cible, mais cette option peut être utilisée pour exclure des fichiers spécifiques.

QT_QML_SKIP_CACHEGEN fait la même chose, en empêchant un fichier source d'être compilé en code octet lorsque cette propriété est définie sur TRUE. Notez que le fichier sera toujours ajouté à target en tant que ressource sous forme non compilée (voir Mise en cache des sources QML compilées).

Définir la propriété du fichier source QT_QML_SKIP_QMLDIR_ENTRY à 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 méthode est normalement utilisée pour un fichier qui n'expose pas de type public, comme un fichier JavaScript privé. Pour les fichiers JavaScript avec des noms en majuscules 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 sera générée pour chaque fichier .qml qui fournit un type. Un numéro de version lui sera attribué : X.0, où X est la version majeure du module QML. Si le module QML possède un ensemble PAST_MAJOR_VERSIONS, le même schéma sera appliqué à ces ensembles, en ajoutant X.0 pour chaque version majeure antérieure X. Dans les cas où un fichier doit fournir des entrées de type pour un ensemble différent de versions (par exemple, il a été ajouté pour la première fois dans une version corrective mineure après la publication 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, attribuez à sa propriété QT_QML_SINGLETON_TYPE la valeur TRUE. De même, la propriété QT_QML_INTERNAL_TYPE source du fichier peut être attribuée à TRUE pour indiquer que le type fourni est un type interne. Le nom du type lui-même peut également être modifié à l'aide de la propriété QT_QML_SOURCE_TYPENAME. Ces trois éléments seront reflétés 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 de créer le module auquel le singleton appartient.

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. Le point de base correspond par défaut à la concaténation du préfixe de la ressource du module QML et de son chemin cible, mais ces paramètres peuvent être remplacés par l'argument PREFIX. Le chemin relatif est par défaut le chemin du fichier relatif à la propriété target's SOURCE_DIR target. Ce chemin relatif peut être remplacé en définissant la propriété QT_RESOURCE_ALIAS sur le fichier source. Cette méthode est couramment utilisée pour rassembler des fichiers provenant de différents répertoires et les faire apparaître dans les ressources à 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 est encore 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 l'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 auront 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 {}