Création de widgets personnalisés pour Qt Widgets Designer

Qt Widgets DesignerL'architecture basée sur les plugins de Qt Widgets permet de modifier les widgets personnalisés définis par l'utilisateur et par des tiers, tout comme vous le faites avec les widgets Qt Widgets standard. Toutes les fonctionnalités du widget personnalisé sont mises à la disposition de Qt Widgets Designer, y compris les propriétés du widget, les signaux et les emplacements. Étant donné que Qt Widgets Designer utilise de vrais widgets au cours du processus de conception du formulaire, les widgets personnalisés apparaîtront tels quels lors de la prévisualisation.

Le module QtDesigner vous permet de créer des widgets personnalisés dans Qt Widgets Designer.

Pour commencer

Pour intégrer un widget personnalisé à Qt Widgets Designer, vous avez besoin d'une description appropriée pour le widget et d'un fichier de projet adéquat.

Fournir une description de l'interface

Pour informer Qt Widgets Designer du type de widget que vous souhaitez fournir, créez une sous-classe de QDesignerCustomWidgetInterface qui décrit les diverses propriétés exposées par votre widget. La plupart de ces propriétés sont fournies par des fonctions purement virtuelles dans la classe de base, car seul l'auteur du plugin peut fournir ces informations.

Deux autres fonctions virtuelles peuvent également être réimplémentées :

Notes sur la fonction domXml()

La fonction domXml() renvoie un extrait de fichier d'interface utilisateur qui est utilisé par la fabrique de widgets Qt Widgets Designer pour créer un widget personnalisé et ses propriétés applicables.

Depuis Qt Widgets 4.4, la boîte à widgets de Qt Widgets Designer permet à un fichier d'interface utilisateur complet de décrire un widget personnalisé. Le fichier d'interface utilisateur peut être chargé à l'aide de la balise <ui>. La balise <ui> permet d'ajouter l'élément <customwidget> qui contient des informations supplémentaires sur les widgets personnalisés. La balise <widget> est suffisante si aucune information supplémentaire n'est requise.

Si le widget personnalisé ne fournit pas d'indication de taille raisonnable, il est nécessaire de spécifier une géométrie par défaut dans la chaîne renvoyée par la fonction domXml() de votre sous-classe. Par exemple, le site AnalogClockPlugin fourni par l'exemple Custom Widget Plugin définit une géométrie de widget par défaut de la manière suivante :

    ...
R"(
    <property name="geometry">
      <rect>
        <x>0</x>
        <y>0</y>
        <width>100</width>
        <height>100</height>
      </rect>
    </property>
")
    ...

Une caractéristique supplémentaire de la fonction domXml() est que, si elle renvoie une chaîne vide, le widget ne sera pas installé dans la boîte à widgets de Qt Widgets Designer. Cependant, il peut toujours être utilisé par d'autres widgets dans le formulaire. Cette fonction est utilisée pour masquer les widgets qui ne doivent pas être explicitement créés par l'utilisateur, mais qui sont requis par d'autres widgets.

Une spécification complète de widget personnalisé se présente comme suit

<ui language="c++"> displayname="MyWidget">
    <widget class="widgets::MyWidget" name="mywidget"/>
    <customwidgets>
        <customwidget>
            <class>widgets::MyWidget</class>
            <addpagemethod>addPage</addpagemethod>
            <propertyspecifications>
                <stringpropertyspecification name="fileName" notr="true" type="singleline"/>
                <stringpropertyspecification name="text" type="richtext"/>
                <tooltip name="text">Explanatory text to be shown in Property Editor</tooltip>
            </propertyspecifications>
        </customwidget>
    </customwidgets>
</ui>

Attributs de la balise <ui>:

La balise <addpagemethod> indique à Qt Widgets Designer et uic quelle méthode doit être utilisée pour ajouter des pages à un widget conteneur. Cela s'applique aux widgets conteneurs qui nécessitent l'appel d'une méthode particulière pour ajouter un enfant plutôt que d'ajouter l'enfant en passant le parent. Cela concerne en particulier les conteneurs qui ne sont pas une sous-classe des conteneurs fournis dans Qt Widgets Designer, mais qui sont basés sur la notion de page courante. En outre, vous devez fournir une extension de conteneur pour ces conteneurs.

L'élément <propertyspecifications> peut contenir une liste de méta-informations sur les propriétés.

La balise <tooltip> peut être utilisée pour spécifier une info-bulle à afficher dans l'éditeur de propriétés lors du survol de la propriété. Le nom de la propriété est donné dans l'attribut name et le texte de l'élément est l'info-bulle. Cette fonctionnalité a été ajoutée dans Qt 5.6.

Pour les propriétés de type chaîne, la balise <stringpropertyspecification> peut être utilisée. Cette balise possède les attributs suivants :

Valeurs de l'attribut type de la propriété string :

Exigences du plugin

Pour que les plugins fonctionnent correctement sur toutes les plateformes, vous devez vous assurer qu'ils exportent les symboles nécessaires à Qt Widgets Designer.

Tout d'abord, la classe du plugin doit être exportée pour que le plugin soit chargé par Qt Widgets Designer. Pour ce faire, utilisez la macro Q_PLUGIN_METADATA(). De même, la macro QDESIGNER_WIDGET_EXPORT doit être utilisée pour définir chaque classe de widget personnalisé au sein d'un plugin, que Qt Widgets Designer instanciera.

Créer des widgets qui se comportent bien

Certains widgets personnalisés ont des caractéristiques d'interface utilisateur spéciales qui peuvent les amener à se comporter différemment de la plupart des widgets standard que l'on trouve sur Qt Widgets Designer. Plus précisément, si un widget personnalisé s'empare du clavier à la suite d'un appel à QWidget::grabKeyboard(), le fonctionnement de Qt Widgets Designer en sera affecté.

Pour donner aux widgets personnalisés un comportement spécial dans Qt Widgets Designer, fournissez une implémentation de la fonction initialize() pour configurer le processus de construction du widget pour un comportement spécifique à Qt Widgets Designer. Cette fonction sera appelée pour la première fois avant tout appel à createWidget() et pourrait peut-être définir un drapeau interne qui peut être testé plus tard lorsque Qt Widgets Designer appelle la fonction createWidget() du plugin.

Construction et installation du plugin

Un plugin simple

Le Custom Widget Plugin est un simple plugin Qt Widgets Designer.

Le fichier de projet d'un plugin doit spécifier les en-têtes et les sources du widget personnalisé et de l'interface du plugin. Généralement, ce fichier doit seulement spécifier que le projet du plugin sera construit comme une bibliothèque, mais avec un support de plugin spécifique pour Qt Widgets Designer. Pour CMake, cela se fait avec les déclarations suivantes :

find_package(Qt6 REQUIRED COMPONENTS Core Gui UiPlugin Widgets)

qt_add_plugin(customwidgetplugin)
target_sources(customwidgetplugin PRIVATE
    analogclock.cpp analogclock.h
    customwidgetplugin.cpp customwidgetplugin.h
)
target_link_libraries(customwidgetplugin PUBLIC
    Qt::Core
    Qt::Gui
    Qt::UiPlugin
    Qt::Widgets
)

La liste des bibliothèques de liens spécifie Qt::UiPlugin. Cela indique que le plugin utilise uniquement les interfaces abstraites QDesignerCustomWidgetInterface et QDesignerCustomWidgetCollectionInterface et qu'il n'a pas de lien avec les bibliothèques Qt Widgets Designer. Lors de l'accès à d'autres interfaces de Qt Widgets Designer qui ont des liens, Designer doit être utilisé à la place ; cela garantit que le plugin est dynamiquement lié aux bibliothèques Qt Widgets Designer et qu'il a une dépendance d'exécution sur elles.

Il est également nécessaire de s'assurer que le plugin est installé avec d'autres plugins de widgets Qt Widgets Designer:

   set(INSTALL_EXAMPLEDIR "${QT6_INSTALL_PREFIX}/${QT6_INSTALL_PLUGINS}/designer")
install(TARGETS customwidgetplugin
    RUNTIME DESTINATION "${INSTALL_EXAMPLEDIR}"
    BUNDLE DESTINATION "${INSTALL_EXAMPLEDIR}"
    LIBRARY DESTINATION "${INSTALL_EXAMPLEDIR}"
)

Pour qmake:

CONFIG      += plugin
TEMPLATE    = lib
HEADERS     = analogclock.h \
              customwidgetplugin.h
SOURCES     = analogclock.cpp \
              customwidgetplugin.cpp
OTHER_FILES += analogclock.json

La variable QT contient le mot-clé uiplugin, qui est l'équivalent de la bibliothèque Qt::UiPlugin.

Il faut également s'assurer que le plugin est installé avec d'autres plugins de widgets Qt Widgets Designer:

target.path = $$[QT_INSTALL_PLUGINS]/designer
INSTALLS += target

La variable $[QT_INSTALL_PLUGINS] est un espace réservé à l'emplacement des plugins Qt Location installés. Vous pouvez configurer Qt Widgets Designer pour qu'il recherche des plugins à d'autres emplacements en définissant la variable d'environnement QT_PLUGIN_PATH avant d'exécuter l'application.

Voir QCoreApplication::libraryPaths() pour plus d'informations sur la personnalisation des chemins d'accès aux bibliothèques et aux modules d'extension dans les applications Qt.

Si les greffons sont construits dans un mode incompatible avec Qt Widgets Designer, ils ne seront pas chargés ni installés. Pour plus d'informations sur les plugins, voir le document Plugins HOWTO.

Diviser le plugin

L'approche simple expliquée ci-dessus pose un problème, en particulier lorsque l'on utilise les autres interfaces de Qt Widgets Designer qui ont un lien : L'application utilisant le widget personnalisé dépendra alors des en-têtes et des bibliothèques de Qt Widgets Designer. Dans un scénario réel, cela n'est pas souhaitable.

Les sections suivantes décrivent comment résoudre ce problème.

Lier le widget à l'application

Lorsque vous utilisez qmake, le fichier source et le fichier d'en-tête du widget personnalisé peuvent être partagés entre l'application et Qt Widgets Designer en créant un fichier .pri à inclure :

INCLUDEPATH += $$PWD
HEADERS += $$PWD/analogclock.h
SOURCES += $$PWD/analogclock.cpp

Ce fichier sera ensuite inclus dans le fichier .pro du plugin et de l'application :

include(customwidget.pri)

Lors de l'utilisation de CMake, les fichiers sources du widget peuvent également être ajoutés au projet d'application.

Partage du widget à l'aide d'une bibliothèque

Une autre approche consiste à placer le widget dans une bibliothèque liée au plugin Qt Widgets Designer ainsi qu'à l'application. Il est recommandé d'utiliser des bibliothèques statiques pour éviter les problèmes de localisation de la bibliothèque au moment de l'exécution.

Pour les bibliothèques partagées, voir Création de bibliothèques partagées.

Utilisation du plugin avec QUiLoader

La meilleure façon d'ajouter des widgets personnalisés à QUiLoader est de le sous-classer en réimplémentant QUiLoader::createWidget().

Cependant, il est également possible d'utiliser les plugins de widgets personnalisés Qt Widgets Designer (voir QUiLoader::pluginPaths() et les fonctions associées). Pour éviter d'avoir à déployer les bibliothèques Qt Widgets Designer sur le dispositif cible, ces plugins ne doivent pas avoir de lien avec les bibliothèques Qt Widgets Designer (QT = uiplugin, voir Création de widgets personnalisés pour Qt Widgets Designer#BuildingandInstallingthePlugin).

Exemples connexes

Pour plus d'informations sur l'utilisation des widgets personnalisés dans Qt Widgets Designer, reportez-vous aux exemples Custom Widget Plugin et Task Menu Extension pour plus d'informations sur l'utilisation des widgets personnalisés dans Qt Widgets Designer. Vous pouvez également utiliser la classe QDesignerCustomWidgetCollectionInterface pour combiner plusieurs widgets personnalisés dans une seule bibliothèque.