Création de widgets personnalisés pour Qt Widgets Designer
Qt Widgets L'architecture de Designer, basée sur des plugins, permet d'éditer des widgets personnalisés définis par l'utilisateur ou par des tiers, comme vous le feriez avec des 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 pendant le processus de conception du formulaire, les widgets personnalisés apparaîtront de la même manière que lorsqu'ils sont prévisualisés.
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 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.
| Fonction | Description de la valeur de retour |
|---|---|
name() | Le nom de la classe qui fournit le widget. |
group() | Le groupe auquel appartient le widget dans la boîte à widgets de Qt Widgets Designer. |
toolTip() | Une courte description pour aider les utilisateurs à identifier le widget dans Qt Widgets Designer. |
whatsThis() | Une description plus longue du widget pour les utilisateurs de Qt Widgets Designer. |
includeFile() | Le fichier d'en-tête qui doit être inclus dans les applications qui utilisent ce widget. Ces informations sont stockées dans les fichiers UI et seront utilisées par uic pour créer une déclaration #includes appropriée dans le code qu'il génère pour le formulaire contenant le widget personnalisé. |
icon() | Une icône qui peut être utilisée pour représenter le widget dans la boîte à widgets de Qt Widgets Designer. |
isContainer() | True si le widget sera utilisé pour contenir des widgets enfants ; false sinon. |
createWidget() | Un pointeur QWidget vers une instance du widget personnalisé, construit avec le parent fourni. Remarque : createWidget() est une fonction d'usine responsable de la création du widget uniquement. Les propriétés du widget personnalisé ne seront pas disponibles avant le retour de load(). |
domXml() | Une description des propriétés du widget, telles que son nom d'objet, son indice de taille et d'autres propriétés standard de QWidget. |
codeTemplate() | Cette fonction est réservée à une utilisation future par Qt Widgets Designer. |
Deux autres fonctions virtuelles peuvent également être réimplémentées :
initialize() | Configure des extensions et d'autres caractéristiques pour les widgets personnalisés. Les extensions de conteneurs personnalisés (voir QDesignerContainerExtension) et les extensions de menus de tâches (voir QDesignerTaskMenuExtension) doivent être configurées dans cette fonction. |
isInitialized() | Retourne true si le widget a été initialisé ; retourne false dans le cas contraire. Les réimplémentations vérifient généralement si la fonction initialize() a été appelée et renvoient le résultat de ce test. |
Notes sur la fonction domXml()
La fonction domXml() renvoie un extrait de fichier d'interface utilisateur utilisé par la fabrique de widgets de Qt Widgets Designer pour créer un widget personnalisé et ses propriétés applicables.
Depuis Qt Widgets Designer 4.4, la fabrique de widgets de Qt Widgets Designer permet de décrire un widget personnalisé à l'aide d'un fichier UI complet. 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é ressemble à ceci :
<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>:
| Attribut | Présence | Valeurs | Commentaire |
|---|---|---|---|
language | optionnel | "c++", "jambi" | Cet attribut spécifie la langue dans laquelle le widget personnalisé est destiné. Il sert principalement à empêcher les plugins C++ d'apparaître dans Qt Jambi. |
displayname | optionnel | Nom de la classe | La valeur de cet attribut apparaît dans la boîte du widget et peut être utilisée pour supprimer les espaces de noms. |
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 :
| Attribut | Présence | Valeurs | Commentaire |
|---|---|---|---|
name | obligatoire | Nom de la propriété | |
type | obligatoire | Voir le tableau ci-dessous | La valeur de l'attribut détermine la manière dont l'éditeur de propriétés les traitera. |
notr | optionnel | "true", "false" | Si la valeur de l'attribut est "true", la valeur n'est pas destinée à être traduite. |
Valeurs de l'attribut type de la propriété string :
| Valeur | Type de texte |
|---|---|
"richtext" | Texte enrichi. |
"multiline" | Texte brut sur plusieurs lignes. |
"singleline" | Texte brut sur une seule ligne. |
"stylesheet" | Une feuille de style CSS. |
"objectname" | Un nom d'objet (ensemble restreint de caractères valides). |
"url" | URL, nom de fichier. |
Exigences du plugin
Pour que les plugins fonctionnent correctement sur toutes les plates-formes, 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(). En outre, la macro QDESIGNER_WIDGET_EXPORT doit être utilisée pour définir chaque classe de widget personnalisé dans un plugin, que Qt Widgets Designer instanciera.
Création de widgets bien conçus
Certains widgets personnalisés ont des caractéristiques d'interface utilisateur spéciales qui peuvent les amener à se comporter différemment des widgets standard que l'on trouve dans Qt Widgets Designer. En particulier, 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 particulier 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 présente 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. En général, 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 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 un lien, 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 de 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.jsonLa 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 d'autres plugins Qt Widgets Designer widget :
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.
Remarque : Qt Widgets Designer recherchera un sous-répertoire designer dans chaque chemin fourni.
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 modules d'extension 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 des liens : 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 de Qt Widgets Designer (voir QUiLoader::pluginPaths() et les fonctions correspondantes). Pour éviter d'avoir à déployer les bibliothèques de Qt Widgets Designer sur le dispositif cible, ces plugins ne doivent pas être liés aux bibliothèques de Qt Widgets Designer (QT = uiplugin, voir Creating Custom Widgets for Qt Widgets Designer#BuildingandInstallingthePlugin).
Exemples connexes
Pour plus d'informations sur l'utilisation de 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 de 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.
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.