Plugin de widget personnalisé

Dans cet exemple, le widget personnalisé utilisé s'inspire de l'exemple « Analog Clock » et ne fournit aucun signal ni slot personnalisé.

Préparation

Pour fournir un widget personnalisé pouvant être utilisé avec Qt Widgets Designer, nous devons fournir une implémentation autonome et proposer une interface de plugin. Dans cet exemple, nous réutilisons l’exemple « Analog Clock » pour plus de simplicité.

Fichiers du projet

CMake

Les fichiers de projet doivent indiquer qu’un plugin lié aux bibliothèques d’ Qt Widgets Designer doit être compilé :

find_package(Qt6 REQUIRED COMPONENTS Core Gui UiPlugin Widgets)

qt_add_plugin(customwidgetplugin)

target_link_libraries(customwidgetplugin PUBLIC
    Qt::Core
    Qt::Gui
    Qt::UiPlugin
    Qt::Widgets
)

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 d’ Designer. Lors de l’accès à d’autres interfaces d’ Qt Widgets Designer qui comportent des liens, il convient d’utiliser ` Designer ` à la place ; cela garantit que le plugin se lie dynamiquement aux bibliothèques d’ Qt Widgets Designer et qu’il en dépend en temps d’exécution.

L'exemple suivant montre comment ajouter les fichiers d'en-tête et les fichiers source du widget :

target_sources(customwidgetplugin PRIVATE
    analogclock.cpp analogclock.h
    customwidgetplugin.cpp customwidgetplugin.h
)

Nous fournissons une implémentation de l'interface du plug-in afin qu’ Qt Widgets Designer puisse utiliser le widget personnalisé.

Il est également important de s’assurer que le plugin est installé à un emplacement pris en compte par Qt Widgets Designer. Pour ce faire, nous spécifions un chemin cible pour le projet et l’ajoutons à la liste des éléments à installer :

   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}"
)

Le widget personnalisé est créé sous forme de bibliothèque. Il sera installé aux côtés des autres plugins d’ Qt Widgets Designer lors de l’installation du projet (à l’aide d’ ninja install ou d’une procédure d’installation équivalente).

Pour plus d’informations sur les plug-ins, consultez la documentation « Comment créer des plug-ins Qt ».

qmake

L’exemple suivant montre comment lier un plugin aux bibliothèques d’ Qt Widgets Designer :

CONFIG      += plugin
TEMPLATE    = lib

QT          += widgets uiplugin

La variable ` QT ` contient le mot-clé ` uiplugin`, qui correspond à la bibliothèque ` Qt::UiPlugin `.

L'exemple suivant montre comment ajouter les fichiers d'en-tête et les fichiers source du widget :

HEADERS     = analogclock.h \
              customwidgetplugin.h
SOURCES     = analogclock.cpp \
              customwidgetplugin.cpp
OTHER_FILES += analogclock.json

L'exemple suivant montre comment installer un plugin dans le chemin d'accès aux plugins de l'Qt Widgets Designer :

TARGET = $$qtLibraryTarget($$TARGET)

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

Définition et implémentation de la classe `AnalogClock`

La classe ` AnalogClock ` est définie et implémentée exactement de la même manière que dans l’exemple de l’horloge analogique. Comme cette classe est autonome et ne nécessite aucune configuration externe, elle peut être utilisée telle quelle en tant que widget personnalisé dans Qt Widgets Designer.

Définition de la classe AnalogClockPlugin

La classe ` AnalogClock ` est exposée à l’ Qt Widgets Designer via la classe ` AnalogClockPlugin `. Cette classe hérite à la fois de ` QObject ` et de la classe ` QDesignerCustomWidgetInterface `, et implémente une interface définie par ` QDesignerCustomWidgetInterface`.

Pour que Qt reconnaisse le widget comme un plugin, exportez les informations pertinentes concernant ce dernier en ajoutant la macro Q_PLUGIN_METADATA():

class AnalogClockPlugin : public QObject, public QDesignerCustomWidgetInterface
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QDesignerCustomWidgetInterface")
    Q_INTERFACES(QDesignerCustomWidgetInterface)
public:
    explicit AnalogClockPlugin(QObject *parent = nullptr);

    bool isContainer() const override;
    bool isInitialized() const override;
    QIcon icon() const override;
    QString domXml() const override;
    QString group() const override;
    QString includeFile() const override;
    QString name() const override;
    QString toolTip() const override;
    QString whatsThis() const override;
    QWidget *createWidget(QWidget *parent) override;
    void initialize(QDesignerFormEditorInterface *core) override;

private:
    bool initialized = false;
};

Ces fonctions fournissent des informations sur le widget que Qt Widgets Designer peut utiliser dans la boîte de dialogue du widget. La variable membre privée initialized sert à indiquer si le plugin a été initialisé par Qt Widgets Designer.

Notez que la seule partie de la définition de classe spécifique à ce widget personnalisé est le nom de la classe.

Implémentation d’AnalogClockPlugin

Le constructeur de la classe appelle simplement le constructeur de la classe de base ` QObject ` et définit la variable ` initialized ` sur ` false`.

AnalogClockPlugin::AnalogClockPlugin(QObject *parent)
    : QObject(parent)
{
}

Qt Widgets Designer initialisera le plugin lorsqu’il sera requis en appelant la fonction ` initialize() ` :

void AnalogClockPlugin::initialize(QDesignerFormEditorInterface * /* core */)
{
    if (initialized)
        return;

    initialized = true;
}

Dans cet exemple, la variable privée ` initialized ` est vérifiée et n’est définie sur ` true ` que si le plugin n’est pas encore initialisé. Bien que ce plugin ne nécessite l’exécution d’aucun code particulier lors de son initialisation, nous pourrions inclure un tel code après la vérification de l’initialisation.

La fonction ` isInitialized() ` indique à Qt Widgets Designer si le plugin est prêt à être utilisé :

bool AnalogClockPlugin::isInitialized() const
{
    return initialized;
}

Les instances du widget personnalisé sont fournies par la fonction ` createWidget() `. L’implémentation de l’horloge analogique est simple :

QWidget *AnalogClockPlugin::createWidget(QWidget *parent)
{
    return new AnalogClock(parent);
}

Dans ce cas, le widget personnalisé ne nécessite que la spécification d’un ` parent `. Si d’autres arguments doivent être fournis au widget, ils peuvent être introduits ici.

Les fonctions suivantes fournissent des informations que le Designer d'Qt Widgets s utilise pour représenter le widget dans la boîte à widgets. La fonction ` name() ` renvoie le nom de la classe qui fournit le widget personnalisé :

QString AnalogClockPlugin::name() const
{
    return u"AnalogClock"_s;
}

La fonction ` group() ` sert à décrire le type de widget auquel appartient le widget personnalisé :

QString AnalogClockPlugin::group() const
{
    return u"Display Widgets [Examples]"_s;
}

Le plugin de widget sera placé dans une section identifiée par le nom de son groupe dans la boîte à widgets d’ Qt Widgets Designer. L’icône utilisée pour représenter le widget dans la boîte à widgets est renvoyée par la fonction ` icon() ` :

QIcon AnalogClockPlugin::icon() const
{
    return {};
}

Dans ce cas, nous renvoyons une icône nulle pour indiquer que nous ne disposons d’aucune icône pouvant être utilisée pour représenter le widget.

Une info-bulle et une aide « Qu'est-ce que c'est ? » peuvent être fournies pour l'entrée du widget personnalisé dans la boîte à widgets. La fonction ` toolTip() ` doit renvoyer un message court décrivant le widget :

QString AnalogClockPlugin::toolTip() const
{
    return {};
}

La fonction ` whatsThis() ` peut renvoyer une description plus longue :

QString AnalogClockPlugin::whatsThis() const
{
    return {};
}

La fonction isContainer() indique au concepteur d’ Qt Widgets si le widget est censé servir de conteneur pour d’autres widgets. Si ce n’est pas le cas, le concepteur d’ Qt Widgets n’autorisera pas l’utilisateur à y placer des widgets.

bool AnalogClockPlugin::isContainer() const
{
    return false;
}

La plupart des widgets de Qt peuvent contenir des widgets enfants, mais il est préférable d’utiliser des widgets conteneurs dédiés à cet effet dans Qt Widgets Designer. En renvoyant ` false`, nous indiquons que le widget personnalisé ne peut pas contenir d’autres widgets ; si nous renvoyions `true`, Qt Widgets Designer autoriserait le placement d’autres widgets à l’intérieur de l’horloge analogique et la définition d’une mise en page.

La fonction ` domXml() ` permet d’inclure les paramètres par défaut du widget au format XML standard utilisé par Qt Widgets Designer. Dans ce cas, nous spécifions uniquement la géométrie du widget :

QString AnalogClockPlugin::domXml() const
{
    return uR"(
<ui language="c++">
  <widget class="AnalogClock" name="analogClock">
)"
R"(
    <property name="geometry">
      <rect>
        <x>0</x>
        <y>0</y>
        <width>100</width>
        <height>100</height>
      </rect>
    </property>
")
R"(
    <property name="toolTip">
      <string>The current time</string>
    </property>
    <property name="whatsThis">
      <string>The analog clock widget displays the current time.</string>
    </property>
  </widget>
</ui>
)"_s;
}

Si le widget fournit une indication de taille raisonnable, il n’est pas nécessaire de la définir ici. De plus, le fait de renvoyer une chaîne vide à la place d’un élément ` <widget> ` indiquera à Qt Widgets Designer de ne pas installer le widget dans la zone de widgets.

Pour que le widget d’horloge analogique soit utilisable par les applications, nous implémentons la fonction ` includeFile() ` afin qu’elle renvoie le nom du fichier d’en-tête contenant la définition de la classe du widget personnalisé :

QString AnalogClockPlugin::includeFile() const
{
    return u"analogclock.h"_s;
}

Exemple de projet @ code.qt.io