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

Qt Widgets L'architecture basée sur des plugins de Qt Designer permet de modifier les widgets personnalisés définis par l'utilisateur et ceux de tiers, exactement comme vous le feriez avec des widgets Qt standard. Toutes les fonctionnalités des widgets personnalisés sont mises à la disposition d'Qt Widgets Designer, y compris les propriétés, les signaux et les slots des widgets. Étant donné qu'Qt Widgets Designer utilise de véritables widgets lors du processus de conception des formulaires, les widgets personnalisés s'afficheront exactement comme lors de leur 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é dans Qt Widgets Designer, vous devez disposer d'une description adaptée au widget et d'un fichier de projet approprié.

Fournir une description de l'interface

Pour indiquer à Qt Widgets Designer le type de widget que vous souhaitez fournir, créez une sous-classe de ` QDesignerCustomWidgetInterface ` qui décrit les différentes propriétés exposées par votre widget. La plupart d’entre elles sont fournies par des fonctions pures 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 :

Remarques sur la fonction domXml()

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

Depuis Qt 4.4, la boîte de dialogue des widgets Qt Widgets Designer permet d’utiliser un fichier d’interface utilisateur complet pour décrire un widget personnalisé. Ce fichier d’interface utilisateur peut être chargé à l’aide de la balise <ui>. La spécification de la balise <UI> permet d’ajouter l’élément <CUSTOMWIDGET> qui contient des informations supplémentaires pour les widgets personnalisés. La balise <widget> suffit 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 fichier 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 autre fonctionnalité de la fonction ` domXml() ` est que, si elle renvoie une chaîne vide, le widget ne sera pas installé dans la boîte de widgets d’ Qt Widgets Designer. Il pourra toutefois toujours être utilisé par d’autres widgets du formulaire. Cette fonctionnalité sert à masquer les widgets qui ne doivent pas être créés explicitement 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 notamment les conteneurs qui ne sont pas des sous-classes des conteneurs fournis dans Qt Widgets Designer, mais qui reposent sur la notion de « Page actuelle ». De plus, vous devez fournir une extension de conteneur pour ceux-ci.

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 lorsque l’on survole la propriété. Le nom de la propriété est indiqué dans l’attribut name et le texte de l’élément correspond à l’info-bulle. Cette fonctionnalité a été ajoutée dans Qt 5.6.

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

Valeurs de l'attribut « type » de la propriété de chaîne :

Configuration requise pour les plugins

Pour que les plug-ins fonctionnent correctement sur toutes les plateformes, vous devez vous assurer qu’ils exportent les symboles requis par Qt Widgets Designer.

Tout d’abord, la classe du plugin doit être exportée pour que celui-ci puisse être chargé par Qt Widgets Designer. Pour ce faire, utilisez la macro Q_PLUGIN_METADATA(). De plus, la macro QDESIGNER_WIDGET_EXPORT doit être utilisée pour définir chaque classe de widget personnalisée au sein d’un plugin, que Qt Widgets Designer instanciera.

Création de widgets fonctionnant correctement

Certains widgets personnalisés possèdent des fonctionnalités d’interface utilisateur spécifiques qui peuvent les amener à se comporter différemment de la plupart des widgets standard disponibles dans le Designer d’ Qt Widgets. Plus précisément, si un widget personnalisé accapare le clavier à la suite d’un appel à QWidget::grabKeyboard(), le fonctionnement du Designer d’ Qt Widgets s’en trouvera affecté.

Pour attribuer un comportement spécifique aux widgets personnalisés dans Qt Widgets Designer, fournissez une implémentation de la fonction `initialize()` afin de configurer le processus de construction du widget en fonction du comportement spécifique à Qt Widgets Designer. Cette fonction sera appelée pour la première fois avant tout appel à `createWidget()` et pourra éventuellement définir un indicateur interne qui pourra être vérifié ultérieurement lorsque Qt Widgets Designer appellera la fonction `createWidget()` du plugin.

Compilation et installation du plugin

Un plugin simple

Le plugin « Custom Widget » est un exemple de plugin simple créé à l'aide d'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. En règle générale, ce fichier doit simplement indiquer que le projet du plugin sera compilé sous forme de bibliothèque, mais avec une prise en charge spécifique d’ Qt Widgets Designer. Pour CMake, cela s’effectue à l’aide des 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 liaison spécifie Qt::UiPlugin. Cela indique que le plugin utilise uniquement les interfaces abstraites QDesignerCustomWidgetInterface et QDesignerCustomWidgetCollectionInterface et qu’il n’a aucun lien avec les bibliothèques du Designer d’ Qt Widgets. Lors de l’accès à d’autres interfaces du Designer d’ Qt Widgets qui comportent des liens, il convient d’utiliser Designer à la place ; cela garantit que le plugin établit une liaison dynamique avec les bibliothèques du Designer d’ Qt Widgets et qu’il en dépend en temps d’exécution.

Il est également nécessaire de s’assurer que le plugin est installé en même temps que les autres plugins de widgets d’ 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 est également nécessaire de s'assurer que le plugin est installé avec les autres plugins de widgets Qt Widgets Designer :

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

La variable ` $[QT_INSTALL_PLUGINS] ` sert de variable de remplacement pour l'emplacement des plugins Qt installés. Vous pouvez configurer Qt Widgets Designer pour qu'il recherche les plugins à d'autres emplacements en définissant la variable d'environnement ` QT_PLUGIN_PATH ` avant de lancer l'application.

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

Si les plugins sont compilés dans un mode incompatible avec Qt Widgets Designer, ils ne seront ni chargés ni installés. Pour plus d’informations sur les plugins, consultez le document « Plugins HOWTO ».

Décomposition du plugin

L’approche simple expliquée ci-dessus pose un problème, en particulier lors de l’utilisation des autres interfaces d’ Qt Widgets Designer qui comportent des liaisons : l’application utilisant le widget personnalisé dépendra alors des en-têtes et des bibliothèques d’ 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.

Liaison du 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 serait ensuite inclus par le fichier ` .pro ` du plugin et de l'application :

include(customwidget.pri)

Lorsque vous utilisez ` CMake`, les fichiers source du widget peuvent également être ajoutés au projet de l'application.

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

Une autre approche consiste à placer le widget dans une bibliothèque liée à la fois au plugin Qt Widgets Designer et à l'application. Il est recommandé d'utiliser des bibliothèques statiques afin d'éviter tout problème 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 plug-in avec QUiLoader

La meilleure façon d'ajouter des widgets personnalisés à QUiLoader consiste à créer une sous-classe de cette classe en réimplémentant la méthode QUiLoader::createWidget().

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

Exemples associés

Qt Widgets Pour plus d’informations sur l’utilisation des widgets personnalisés dans le Designer d’ Qt Widgets, consultez les exemples « Custom Widget Plugin » et « Task Menu Extension ». Vous pouvez également utiliser la classe QDesignerCustomWidgetCollectionInterface pour regrouper plusieurs widgets personnalisés dans une seule bibliothèque.