qt_add_qml_plugin

Définit un plugin associé à un module QML.

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_add_qml_plugin(
    target
    [BACKING_TARGET backing_target]
    [STATIC | SHARED]
    [OUTPUT_DIRECTORY]
    [URI]
    [CLASS_NAME]
    [NO_GENERATE_PLUGIN_SOURCE]
    [NAMESPACE namespace]
)

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

Description

Cette commande crée la cible de plugin associée à un module QML. Elle est normalement appelée en interne par qt_add_qml_module() pour créer ou mettre à jour le plugin associé à sa cible sous-jacente. Vous ne devez pas appeler cette fonction directement, sauf dans des circonstances particulières vous obligeant à créer la cible d’une manière spécifique.

La documentation de qt_add_qml_module() décrit différents modèles structurels permettant d’organiser les cibles CMake associées à un module QML. Notez que même si le module QML ne dispose pas de cible de support distincte et que toutes les fonctionnalités sont implémentées directement dans le plugin (ce qui n’est pas la configuration recommandée), vous devez tout de même appeler `qt_add_qml_module() ` plutôt que ` qt_add_qml_plugin()`.

Arguments

target spécifie le nom de la cible à utiliser pour le plugin QML. Si celle-ci n’existe pas encore, elle sera créée.

BACKING_TARGET spécifie le nom de la cible sous-jacente à laquelle le plugin est associé. La cible de base peut être identique à la cible du plugin target; dans ce cas, il n’y a qu’une seule cible fusionnée, mais cette configuration n’est généralement pas recommandée (voir qt_add_qml_module() pour plus d’informations). BACKING_TARGET doit toujours être fourni, sauf dans des circonstances particulières nécessitant la création de la cible du plugin avant celle de la cible de base. Si BACKING_TARGET n’est pas fourni, l’option URI doit être spécifiée.

Par défaut, le plugin est créé avec un type compatible avec la cible de support. Si la cible de support est une bibliothèque statique, le plugin sera également créé en tant que bibliothèque statique. Si la cible de support est une bibliothèque partagée, le plugin sera créé en tant que bibliothèque de modules. Lorsqu’aucune cible sous-jacente n’est fournie ou que le plugin n’a pas de cible sous-jacente distincte, le type du plugin peut être spécifié à l’aide des mots-clés STATIC ou SHARED. Si le type du plugin n’est déterminé par aucune des conditions précédentes, un plugin statique sera créé si Qt a été compilé sous forme de bibliothèques statiques, ou un plugin de bibliothèque de module dans le cas contraire.

OUTPUT_DIRECTORY Spécifie le répertoire dans lequel la bibliothèque du plugin sera créée. Il doit toujours s’agir du même emplacement que celui indiqué dans le fichier `qmldir` du module QML. Lorsque ` OUTPUT_DIRECTORY ` n’est pas fourni, il sera obtenu à partir des informations stockées dans ` BACKING_TARGET`, si celles-ci sont disponibles. Notez que ce répertoire peut être différent de celui de la bibliothèque de la cible sous-jacente. Si aucun répertoire de sortie ne peut être obtenu à partir de la cible sous-jacente, l’ CMAKE_CURRENT_BINARY_DIR est utilisé par défaut.

URI Déclare l'identifiant du module QML auquel ce plugin est associé. L’identifiant du module est l’identifiant (en notation URI pointée) du module QML. Si URI n’est pas fourni, un BACKING_TARGET doit être fourni et l’URI de la cible sous-jacente doit y être enregistrée (généralement par un appel antérieur à qt_add_qml_module()).

Chaque plugin doit disposer d’une classe C++ qui enregistre le module auprès du moteur QML. Par défaut, qt_add_qml_plugin() génère automatiquement les sources de cette classe C++ et les ajoute à la liste des sources de l’ target. La classe de plugin générée répond aux exigences relatives au caractère facultatif du plugin (voir Fichiers qmldir de définition de module). Le nom de la classe est déterminé comme suit :

• Si l'option ` CLASS_NAME ` a été spécifiée, ce nom sera utilisé. Il doit correspondre au nom utilisé dans le fichier ` qmldir ` du module QML.
• Si CLASS_NAME n’a pas été fourni, mais que BACKING_TARGET l’a été, le nom de la classe C++ sera tiré des informations enregistrées sur cette cible de support. Ces informations sont généralement enregistrées lors d’un appel antérieur à qt_add_qml_module(), et elles correspondront au nom utilisé dans le fichier qmldir généré. C’est la méthode recommandée pour fournir le nom de la classe dans la plupart des cas.
• Si le nom de la classe ne peut toujours pas être déterminé, il est défini comme l’URI du module, les points étant remplacés par des traits de soulignement, et « Plugin » ajouté à la fin.

Si un espace de noms est spécifié avec le mot-clé « NAMESPACE », le code du plugin sera généré dans un espace de noms C++ portant ce nom.

Certains plugins peuvent nécessiter que la classe de plugin soit écrite manuellement. Par exemple, le plugin peut devoir effectuer une initialisation supplémentaire ou enregistrer des éléments non implémentés par la classe de plugin par défaut. Dans de tels cas, l’option « NO_GENERATE_PLUGIN_SOURCE » peut être spécifiée. Il vous incombe alors d’écrire votre propre classe de plugin en C++ et de l’ajouter à la liste des modules ( target). Notez que si vous devez écrire votre propre classe de plugin, il est très peu probable que le plugin puisse être facultatif. Cela signifie donc que le mot-clé « NO_PLUGIN_OPTIONAL » doit être inclus dans l’appel à `qt_add_qml_module()` lors de la définition du module QML, sans quoi le fichier ` qmldir ` généré sera incorrect. Assurez-vous que votre classe de plugin utilise le même nom de classe que celui déterminé selon la logique décrite ci-dessus.