qt_add_qml_plugin

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

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

Description de la commande

Cette commande crée la cible du 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 de soutien. Vous ne devriez pas appeler cette fonction directement, sauf si vous avez des circonstances particulières qui vous obligent à créer la cible d'une manière spéciale.

La documentation de qt_add_qml_module() décrit différents modèles structurels pour la façon dont les cibles CMake associées à un module QML peuvent être arrangées. Notez que même si le module QML n'a pas de cible de support séparée et que toutes les fonctionnalités sont implémentées directement dans le greffon (ce qui n'est pas l'arrangement recommandé), vous devriez toujours 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 elle n'existe pas encore, elle sera créée.

BACKING_TARGET spécifie le nom de la cible d'appui à laquelle le plugin est associé. La cible d'appui peut être la même que celle du greffon target, auquel cas il n'y a qu'une seule cible fusionnée, mais cela n'est pas recommandé (voir qt_add_qml_module() pour plus d'informations). BACKING_TARGET doit toujours être fourni à moins qu'il y ait des circonstances particulières qui exigent que la cible du greffon soit créée avant la cible d'appui. Si BACKING_TARGET n'est pas fourni, une option URI doit être fournie.

Par défaut, le plugin est créé avec un type compatible avec la cible de référence. Si la cible de référence est une bibliothèque statique, le plugin sera également créé en tant que bibliothèque statique. Si la cible de référence est une bibliothèque partagée, le plugin sera créé en tant que bibliothèque de module. Si aucune cible de référence n'est fournie ou si le plugin n'a pas de cible de référence distincte, le type de plugin peut être spécifié à l'aide des mots-clés STATIC ou SHARED. Si le type de plugin n'est pas déterminé par l'une des conditions précédentes, un plugin statique sera créé si Qt a été construit en tant que bibliothèque statique, 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 se trouver au même endroit que le fichier qmldir du module QML. Si OUTPUT_DIRECTORY n'est pas indiqué, il sera obtenu à partir des informations stockées sur BACKING_TARGET, si elles sont disponibles. Notez qu'il peut s'agir d'un répertoire différent de celui de la bibliothèque de la cible d'appui. Si un répertoire de sortie ne peut pas être obtenu de la cible d'appui, le répertoire 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 (notation URI pointée) du module QML. Si URI n'est pas donné, un BACKING_TARGET doit être fourni et la cible d'appui doit avoir son URI enregistré (typiquement par un appel antérieur à qt_add_qml_module()).

Chaque plugin doit avoir une classe C++ qui enregistre le module avec le 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 target. La classe de plugin générée répond aux exigences de l'optionnalité du plugin (voir Définition du module Fichiers qmldir). Le nom de la classe est déterminé comme suit :

• Si CLASS_NAME a été donné, il sera utilisé. Il doit correspondre au nom utilisé dans le fichier qmldir du module QML.
• Si CLASS_NAME n'a pas été indiqué, mais que BACKING_TARGET l'a été, le nom de la classe C++ sera tiré des détails enregistrés sur cette cible d'appui. Ces détails sont généralement enregistrés par un appel antérieur à qt_add_qml_module(), et ils correspondront au nom utilisé dans le fichier qmldir généré. C'est la façon recommandée de fournir le nom de la classe dans la plupart des scénarios.
• Si le nom de la classe ne peut toujours pas être déterminé, il est défini comme l'URI du module avec les points remplacés par des underscores, et Plugin ajouté.

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

Certains plugins peuvent nécessiter l'écriture manuelle de la classe du plugin. Par exemple, le plugin peut avoir besoin d'effectuer une initialisation supplémentaire ou d'enregistrer des éléments qui ne sont pas implémentés par la classe de plugin par défaut. Dans ce cas, l'option NO_GENERATE_PLUGIN_SOURCE peut être donnée. Il vous incombe alors d'écrire votre propre classe de plugin C++ et de l'ajouter à l'adresse target. Notez que si vous devez écrire votre propre classe de plugin, il est très peu probable que le plugin puisse être optionnel. Cela signifie 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, sinon 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é par la logique ci-dessus.