Plugin de widget personnalisé

Dans cet exemple, le widget personnalisé utilisé est basé sur l'exemple de l'horloge analogique et ne fournit pas de signaux ou d'emplacements personnalisés.

Préparation

Pour fournir un widget personnalisé qui peut être utilisé avec Qt Widgets Designer, nous devons fournir une implémentation autonome et une interface de plugin. Dans cet exemple, nous réutilisons l'exemple de l'horloge analogique pour des raisons de commodité.

Fichiers de projet

CMake

Les fichiers du projet doivent indiquer qu'un plugin liant les bibliothèques Qt Widgets Designer doit être construit :

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
)

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'est pas lié aux 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 lié dynamiquement aux bibliothèques Qt Widgets Designer et qu'il a une dépendance d'exécution sur elles.

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

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

Nous fournissons une implémentation de l'interface du plugin afin que Qt Widgets Designer puisse utiliser le widget personnalisé.

Il est également important de s'assurer que le plugin est installé à un emplacement qui peut être recherché 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éé en tant que bibliothèque. Il sera installé avec les autres plugins Qt Widgets Designer lors de l'installation du projet (à l'aide de ninja install ou d'une procédure d'installation équivalente).

Pour plus d'informations sur les plugins, voir la documentation How to Create Qt Plugins (Comment créer des plugins Qt ).

qmake

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

CONFIG      += plugin
TEMPLATE    = lib

QT          += widgets uiplugin

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

L'exemple suivant montre comment ajouter les fichiers d'en-tête et de 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 des plugins de Qt Widgets Designer:

TARGET = $$qtLibraryTarget($$TARGET)

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

Définition et mise en œuvre de la classe AnalogClock

La classe AnalogClock est définie et mise en œuvre exactement de la même manière que celle décrite dans l'exemple de l'horloge analogique. Étant donné que la classe est autonome et ne nécessite aucune configuration externe, elle peut être utilisée sans modification en tant que widget personnalisé dans Qt Widgets Designer.

Définition de la classe AnalogClockPlugin

La classe AnalogClock est exposée à Qt Widgets Designer par l'intermédiaire de la classe AnalogClockPlugin. Cette classe hérite à la fois de QObject et de la classe QDesignerCustomWidgetInterface, et met en œuvre une interface définie par QDesignerCustomWidgetInterface.

Pour que Qt Widgets reconnaisse le widget comme un plugin, exportez les informations pertinentes sur le widget 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;
};

Les fonctions fournissent des informations sur le widget que Qt Widgets Designer peut utiliser dans la boîte à widgets. La variable membre privée initialized est utilisée pour enregistrer si le plugin a été initialisé par Qt Widgets Designer.

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

Mise en œuvre de AnalogClockPlugin

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

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

Qt Widgets Designer Le constructeur de la classe privée initialisera le plugin lorsque cela sera nécessaire en appelant la fonction initialize():

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

    initialized = true;
}

Dans cet exemple, la variable privée initialized est testée et ne prend la valeur true que si le plugin n'est pas déjà initialisé. Bien que ce plugin ne nécessite pas l'exécution d'un code spécial lors de son initialisation, nous pourrions inclure un tel code après le test d'initialisation.

La fonction isInitialized() permet à Qt Widgets Designer de savoir 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 à Qt Widgets Designer 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() est utilisée pour décrire le type de widget auquel appartient le widget personnalisé :

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

Le plugin widget sera placé dans une section identifiée par son nom de groupe dans la boîte à widgets de 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 n'avons pas d'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 court message 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 à Qt Widgets Designer si le widget est censé être utilisé comme conteneur pour d'autres widgets. Si ce n'est pas le cas, Qt Widgets Designer ne permettra pas à l'utilisateur de placer des widgets à l'intérieur.

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

La plupart des widgets dans Qt Widgets peuvent contenir des widgets enfants, mais il n'est logique d'utiliser des widgets conteneurs dédiés à cette fin que dans Qt Widgets Designer. En renvoyant false, nous indiquons que le widget personnalisé ne peut pas contenir d'autres widgets ; si nous renvoyons true, Qt Widgets Designer permettrait à d'autres widgets d'être placés à l'intérieur de l'horloge analogique et à une mise en page d'être définie.

La fonction domXml() permet d'inclure des paramètres par défaut pour le widget dans le format XML standard utilisé par Qt Widgets Designer. Dans ce cas, nous ne spécifions que 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 un indice de taille raisonnable, il n'est pas nécessaire de le définir ici. En outre, le fait de renvoyer une chaîne vide au lieu d'un élément <widget> indiquera à Qt Widgets Designer de ne pas installer le widget dans la boîte à widgets.

Pour rendre le widget horloge analogique utilisable par des applications, nous implémentons la fonction includeFile() pour renvoyer 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