Benutzerdefiniertes Widget-Plugin

In diesem Beispiel basiert das verwendete benutzerdefinierte Widget auf dem Beispiel „Analog Clock“ und stellt keine benutzerdefinierten Signale oder Slots bereit.

Vorbereitung

Um ein benutzerdefiniertes Widget bereitzustellen, das mit dem „ Qt Widgets “ Designer verwendet werden kann, müssen wir eine in sich geschlossene Implementierung bereitstellen und eine Plugin-Schnittstelle bereitstellen. In diesem Beispiel verwenden wir der Einfachheit halber das Beispiel „Analog Clock“ wieder.

Projektdateien

CMake

In den Projektdateien muss angegeben werden, dass ein Plugin erstellt werden soll, das mit den Bibliotheken von „ Qt Widgets Designer“ verknüpft ist:

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
)

Die Liste der zu verknüpfenden Bibliotheken gibt „ Qt::UiPlugin “ an. Dies bedeutet, dass das Plugin ausschließlich die abstrakten Schnittstellen „ QDesignerCustomWidgetInterface “ und „ QDesignerCustomWidgetCollectionInterface “ verwendet und keine Verknüpfung zu den „ Qt Widgets Designer“-Bibliotheken aufweist. Beim Zugriff auf andere Schnittstellen von „ Qt Widgets Designer“, die eine Verknüpfung erfordern, sollte stattdessen „ Designer “ verwendet werden; dies stellt sicher, dass das Plugin dynamisch mit den „ Qt Widgets Designer“-Bibliotheken verknüpft wird und eine Laufzeitabhängigkeit von diesen aufweist.

Das folgende Beispiel zeigt, wie die Header- und Quelldateien des Widgets hinzugefügt werden:

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

Wir stellen eine Implementierung der Plugin-Schnittstelle bereit, damit „ Qt Widgets Designer“ das benutzerdefinierte Widget verwenden kann.

Es ist außerdem wichtig sicherzustellen, dass das Plugin an einem Ort installiert wird, der vom „ Qt Widgets -Designer“ durchsucht wird. Dazu geben wir einen Zielpfad für das Projekt an und fügen ihn der Liste der zu installierenden Elemente hinzu:

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

Das benutzerdefinierte Widget wird als Bibliothek erstellt. Es wird bei der Installation des Projekts (über „ ninja install “ oder ein gleichwertiges Installationsverfahren) zusammen mit den anderen Plugins für den „ Qt Widgets “ Designer installiert.

Weitere Informationen zu Plugins finden Sie in der Dokumentation „How to Create Qt Plugins “.

qmake

Das folgende Beispiel zeigt, wie ein Plugin mit den Bibliotheken des „ Qt Widgets Designer“ verknüpft wird:

CONFIG      += plugin
TEMPLATE    = lib

QT          += widgets uiplugin

Die Variable „ QT “ enthält das Schlüsselwort „ uiplugin “, das der Bibliothek „ Qt::UiPlugin “ entspricht.

Das folgende Beispiel zeigt, wie die Header- und Quelldateien des Widgets hinzugefügt werden:

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

Das folgende Beispiel zeigt, wie ein Plugin im Plugin-Pfad des „ Qt Widgets “-Designers installiert wird:

TARGET = $$qtLibraryTarget($$TARGET)

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

Definition und Implementierung der Klasse „AnalogClock“

Die Klasse „ AnalogClock “ wird genau so definiert und implementiert, wie im Beispiel „Analog Clock“ beschrieben. Da die Klasse in sich geschlossen ist und keine externe Konfiguration erfordert, kann sie ohne Änderungen als benutzerdefiniertes Widget im „ Qt Widgets Designer“ verwendet werden.

Definition der Klasse „AnalogClockPlugin“

Die Klasse „ AnalogClock “ wird dem „ Qt Widgets Designer“ über die Klasse „ AnalogClockPlugin “ zur Verfügung gestellt. Diese Klasse erbt sowohl von „ QObject “ als auch von der Klasse „ QDesignerCustomWidgetInterface “ und implementiert eine Schnittstelle, die durch „ QDesignerCustomWidgetInterface “ definiert ist.

Um sicherzustellen, dass Qt das Widget als Plugin erkennt, exportieren Sie relevante Informationen über das Widget, indem Sie das Makro „ Q_PLUGIN_METADATA() “ hinzufügen:

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;
};

Die Funktionen liefern Informationen über das Widget, die der „ Qt Widgets Designer“ im Widget-Feld verwenden kann. Die private Membervariable „ initialized “ dient dazu, festzuhalten, ob das Plugin vom „ Qt Widgets Designer“ initialisiert wurde.

Beachten Sie, dass der Klassenname der einzige Teil der Klassendefinition ist, der für dieses spezielle benutzerdefinierte Widget spezifisch ist.

Implementierung von „AnalogClockPlugin“

Der Klassenkonstruktor ruft lediglich den Konstruktor der Basisklasse „ QObject “ auf und setzt die Variable „ initialized “ auf „ false “.

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

Qt Widgets Der Designer initialisiert das Plugin bei Bedarf durch Aufruf der Funktion ` initialize() `:

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

    initialized = true;
}

In diesem Beispiel wird die private Variable ` initialized ` geprüft und nur dann auf ` true ` gesetzt, wenn das Plugin noch nicht initialisiert ist. Obwohl dieses Plugin bei der Initialisierung keinen speziellen Code ausführen muss, könnten wir solchen Code nach der Initialisierungsprüfung einfügen.

Die Funktion „ isInitialized() “ teilt dem „ Qt Widgets Designer“ mit, ob das Plugin einsatzbereit ist:

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

Instanzen des benutzerdefinierten Widgets werden von der Funktion ` createWidget() ` bereitgestellt. Die Implementierung für die Analoguhr ist unkompliziert:

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

In diesem Fall muss für das benutzerdefinierte Widget lediglich ein ` parent ` angegeben werden. Sollten dem Widget weitere Argumente übergeben werden müssen, können diese hier eingeführt werden.

Die folgenden Funktionen stellen Informationen bereit, die der „ Qt Widgets Designer“ zur Darstellung des Widgets in der Widget-Box verwendet. Die Funktion „ name() “ gibt den Namen der Klasse zurück, die das benutzerdefinierte Widget bereitstellt:

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

Die Funktion „ group() “ wird verwendet, um den Typ des Widgets zu beschreiben, zu dem das benutzerdefinierte Widget gehört:

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

Das Widget-Plugin wird in einem Abschnitt platziert, der durch seinen Gruppennamen in der Widget-Box des „ Qt Widgets Designer“ gekennzeichnet ist. Das Symbol, das zur Darstellung des Widgets in der Widget-Box verwendet wird, wird von der Funktion „ icon() “ zurückgegeben:

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

In diesem Fall geben wir ein Null-Symbol zurück, um anzuzeigen, dass wir kein Symbol haben, das zur Darstellung des Widgets verwendet werden kann.

Für den Eintrag des benutzerdefinierten Widgets in der Widget-Box können ein Tooltip und eine „Was ist das?“-Hilfe bereitgestellt werden. Die Funktion ` toolTip() ` sollte eine kurze Beschreibung des Widgets zurückgeben:

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

Die Funktion ` whatsThis() ` kann eine längere Beschreibung zurückgeben:

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

Die Funktion ` isContainer() ` teilt dem „ Qt Widgets “-Designer mit, ob das Widget als Container für andere Widgets dienen soll. Ist dies nicht der Fall, lässt der „ Qt Widgets “-Designer nicht zu, dass der Benutzer Widgets darin platziert.

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

Die meisten Widgets in Qt können untergeordnete Widgets enthalten, doch im „ Qt Widgets Designer“ ist es sinnvoll, hierfür spezielle Container-Widgets zu verwenden. Durch die Rückgabe von „ false “ geben wir an, dass das benutzerdefinierte Widget keine anderen Widgets enthalten kann; würden wir „true“ zurückgeben, würde der „ Qt Widgets Designer“ zulassen, dass andere Widgets innerhalb der Analoguhr platziert und ein Layout definiert werden.

Die Funktion ` domXml() ` bietet die Möglichkeit, Standardeinstellungen für das Widget im von „ Qt Widgets Designer“ verwendeten Standard-XML-Format anzugeben. In diesem Fall legen wir lediglich die Geometrie des Widgets fest:

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;
}

Wenn das Widget einen sinnvollen Größenhinweis liefert, ist es nicht notwendig, diesen hier zu definieren. Außerdem weist die Rückgabe einer leeren Zeichenkette anstelle eines „ <widget> “-Elements den „ Qt Widgets Designer“ an, das Widget nicht in die Widget-Box einzubinden.

Damit das Analoguhr-Widget von Anwendungen genutzt werden kann, implementieren wir die Funktion „ includeFile() “ so, dass sie den Namen der Header-Datei zurückgibt, die die Definition der benutzerdefinierten Widget-Klasse enthält:

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

Beispielprojekt @ code.qt.io