Erstellen benutzerdefinierter Widgets für den „ Qt Widgets “-Designer

Qt Widgets Die Plugin-basierte Architektur des Designers ermöglicht es, benutzerdefinierte Widgets sowie Widgets von Drittanbietern genauso zu bearbeiten wie Standard-Qt-Widgets. Alle Funktionen des benutzerdefinierten Widgets stehen dem „ Qt Widgets “-Designer zur Verfügung, einschließlich Widget-Eigenschaften, Signale und Slots. Da der „ Qt Widgets “-Designer beim Formularentwurf echte Widgets verwendet, werden benutzerdefinierte Widgets genauso angezeigt wie in der Vorschau.

Das Modul „ QtDesigner “ bietet Ihnen die Möglichkeit, benutzerdefinierte Widgets im „ Qt Widgets Designer“ zu erstellen.

Erste Schritte

Um ein benutzerdefiniertes Widget in den „ Qt Widgets “-Designer zu integrieren, benötigen Sie eine geeignete Beschreibung für das Widget und eine entsprechende Projektdatei.

Bereitstellung einer Schnittstellenbeschreibung

Um dem „ Qt Widgets -Designer“ mitzuteilen, um welchen Widget-Typ es sich handelt, erstellen Sie eine Unterklasse von ` QDesignerCustomWidgetInterface `, die die verschiedenen Eigenschaften Ihres Widgets beschreibt. Die meisten davon werden durch Funktionen bereitgestellt, die in der Basisklasse rein virtuell sind, da nur der Autor des Plugins diese Informationen bereitstellen kann.

Zwei weitere virtuelle Funktionen können ebenfalls neu implementiert werden:

Hinweise zur Funktion „ domXml() “

Die Funktion „ domXml() “ gibt einen Ausschnitt aus einer UI-Datei zurück, der von der Widget-Factory des „ Qt Widgets Designer“ verwendet wird, um ein benutzerdefiniertes Widget und dessen entsprechende Eigenschaften zu erstellen.

Seit Qt 4.4 ermöglicht die Widget-Box des „ Qt Widgets “-Designers die Verwendung einer vollständigen UI-Datei zur Beschreibung eines benutzerdefinierten Widgets. Die UI-Datei kann mithilfe des Tags „ <ui> “ geladen werden. Durch die Angabe des Tags „<UI>“ kann das Element „<CUSTOMWIDGET>“ hinzugefügt werden, das zusätzliche Informationen für benutzerdefinierte Widgets enthält. Das Tag „ <widget> “ ist ausreichend, wenn keine zusätzlichen Informationen erforderlich sind.

Wenn das benutzerdefinierte Widget keinen angemessenen Größenhinweis liefert, muss in der von der Funktion ` domXml() ` in Ihrer Unterklasse zurückgegebenen Zeichenkette eine Standardgeometrie angegeben werden. Beispielsweise definiert die vom Beispiel „Custom Widget Plugin“ bereitgestellte Datei ` AnalogClockPlugin ` eine Standard-Widgetgeometrie wie folgt:

    ...
R"(
    <property name="geometry">
      <rect>
        <x>0</x>
        <y>0</y>
        <width>100</width>
        <height>100</height>
      </rect>
    </property>
")
    ...

Eine weitere Funktion der Funktion ` domXml() ` besteht darin, dass das Widget nicht in die Widget-Box des „ Qt Widgets Designer“ aufgenommen wird, wenn die Funktion eine leere Zeichenfolge zurückgibt. Es kann jedoch weiterhin von anderen Widgets im Formular verwendet werden. Diese Funktion wird genutzt, um Widgets auszublenden, die nicht explizit vom Benutzer erstellt werden sollen, aber von anderen Widgets benötigt werden.

Eine vollständige Spezifikation für ein benutzerdefiniertes Widget sieht wie folgt aus:

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

Attribute des Tags „ <ui> “:

Das Tag „ <addpagemethod> “ teilt dem „ Qt Widgets -Designer“ und „uic“ mit, welche Methode zum Hinzufügen von Seiten zu einem Container-Widget verwendet werden soll. Dies gilt für Container-Widgets, bei denen zum Hinzufügen eines untergeordneten Elements der Aufruf einer bestimmten Methode erforderlich ist, anstatt das untergeordnete Element durch Übergabe des übergeordneten Elements hinzuzufügen. Dies ist insbesondere für Container relevant, die keine Unterklasse der im „ Qt Widgets -Designer“ bereitgestellten Container sind, sondern auf dem Konzept der „Aktuellen Seite“ basieren. Darüber hinaus müssen Sie für diese eine Container-Erweiterung bereitstellen.

Das Element „ <propertyspecifications> “ kann eine Liste von Metainformationen zu Eigenschaften enthalten.

Das Tag „ <tooltip> “ kann verwendet werden, um einen Tooltip festzulegen, der im Eigenschafteneditor angezeigt wird, wenn der Mauszeiger über die Eigenschaft bewegt wird. Der Eigenschaftsname wird im Attribut „ name “ angegeben, und der Text des Elements ist der Tooltip. Diese Funktionalität wurde in Qt 5.6 hinzugefügt.

Für Eigenschaften vom Typ „Zeichenkette“ kann das Tag „ <stringpropertyspecification> “ verwendet werden. Dieses Tag verfügt über die folgenden Attribute:

Werte des Attributs „ type “ der Eigenschaft „string“:

Anforderungen an das Plugin

Damit Plugins auf allen Plattformen korrekt funktionieren, müssen Sie sicherstellen, dass sie die von „ Qt Widgets Designer“ benötigten Symbole exportieren.

Zunächst muss die Plugin-Klasse exportiert werden, damit das Plugin vom „ Qt Widgets -Designer“ geladen werden kann. Verwenden Sie dazu das Makro ` Q_PLUGIN_METADATA()`. Außerdem muss das Makro ` QDESIGNER_WIDGET_EXPORT ` verwendet werden, um jede benutzerdefinierte Widget-Klasse innerhalb eines Plugins zu definieren, die der „ Qt Widgets -Designer“ instanziieren wird.

Erstellen von „gut funktionierenden“ Widgets

Einige benutzerdefinierte Widgets verfügen über spezielle Benutzeroberflächenfunktionen, die dazu führen können, dass sie sich anders verhalten als viele der Standard-Widgets im „ Qt Widgets “-Designer. Insbesondere wenn ein benutzerdefiniertes Widget infolge eines Aufrufs von ` QWidget::grabKeyboard()` die Tastatureingabe blockiert, wird der Betrieb des „ Qt Widgets “-Designers beeinträchtigt.

Um benutzerdefinierten Widgets im „ Qt Widgets “ Designer ein spezielles Verhalten zuzuweisen, müssen Sie eine Implementierung der Funktion `initialize()` bereitstellen, um den Erstellungsprozess des Widgets für das spezifische Verhalten des „ Qt Widgets “ Designers zu konfigurieren. Diese Funktion wird zum ersten Mal vor allen Aufrufen von `createWidget()` aufgerufen und könnte möglicherweise ein internes Flag setzen, das später geprüft werden kann, wenn der „ Qt Widgets “ Designer die Funktion `createWidget()` des Plugins aufruft.

Erstellen und Installieren des Plugins

Ein einfaches Plugin

Das „Custom Widget“-Plugin veranschaulicht ein einfaches Plugin für den „ Qt Widgets Designer“.

Die Projektdatei für ein Plugin muss die Header- und Quelldateien sowohl für das benutzerdefinierte Widget als auch für die Plugin-Schnittstelle angeben. In der Regel muss in dieser Datei lediglich festgelegt werden, dass das Plugin-Projekt als Bibliothek erstellt wird, jedoch mit spezifischer Plugin-Unterstützung für den „ Qt Widgets Designer“. Für „ CMake “ erfolgt dies durch die folgenden Deklarationen:

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
)

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 Bibliotheken von „ Qt Widgets Designer“ aufweist. Beim Zugriff auf andere Schnittstellen von „ Qt Widgets Designer“, die eine Verknüpfung aufweisen, sollte stattdessen „ Designer “ verwendet werden; dies stellt sicher, dass das Plugin dynamisch mit den Bibliotheken von „ Qt Widgets Designer“ verknüpft wird und eine Laufzeitabhängigkeit von diesen hat.

Außerdem muss sichergestellt werden, dass das Plugin zusammen mit anderen Widget-Plugins für den „ Qt Widgets “-Designer installiert wird:

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

Für „ qmake “:

CONFIG      += plugin
TEMPLATE    = lib
HEADERS     = analogclock.h \
              customwidgetplugin.h
SOURCES     = analogclock.cpp \
              customwidgetplugin.cpp
OTHER_FILES += analogclock.json

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

Außerdem muss sichergestellt werden, dass das Plugin zusammen mit anderen Qt Widgets Designer-Widget-Plugins installiert wird:

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

Die Variable ` $[QT_INSTALL_PLUGINS] ` ist ein Platzhalter für den Speicherort der installierten Qt-Plugins. Sie können den „ Qt Widgets Designer“ so konfigurieren, dass er an anderen Speicherorten nach Plugins sucht, indem Sie vor dem Start der Anwendung die Umgebungsvariable ` QT_PLUGIN_PATH ` setzen.

Weitere Informationen zum Anpassen von Pfaden für Bibliotheken und Plugins bei Qt-Anwendungen finden Sie unter „ QCoreApplication::libraryPaths “ ().

Wenn Plugins in einem Modus erstellt wurden, der mit dem Qt Widgets Designer nicht kompatibel ist, werden sie nicht geladen und installiert. Weitere Informationen zu Plugins finden Sie im Plugins-HOWTO-Dokument.

Aufteilung des Plugins

Der oben beschriebene einfache Ansatz führt insbesondere bei der Verwendung anderer Schnittstellen des „ Qt Widgets “-Designers, die Verknüpfungen enthalten, zu einem Problem: Die Anwendung, die das benutzerdefinierte Widget verwendet, ist dann von den Header-Dateien und Bibliotheken des „ Qt Widgets “-Designers abhängig. In der Praxis ist dies nicht erwünscht.

In den folgenden Abschnitten wird beschrieben, wie dieses Problem gelöst werden kann.

Einbinden des Widgets in die Anwendung

Bei Verwendung von „ qmake “ können die Quell- und Header-Datei des benutzerdefinierten Widgets zwischen der Anwendung und dem „ Qt Widgets Designer“ gemeinsam genutzt werden, indem eine „ .pri “-Datei zur Einbindung erstellt wird:

INCLUDEPATH += $$PWD
HEADERS += $$PWD/analogclock.h
SOURCES += $$PWD/analogclock.cpp

Diese Datei würde dann von der ` .pro `-Datei des Plugins und der Anwendung eingebunden werden:

include(customwidget.pri)

Bei Verwendung von „ CMake “ können die Quelldateien des Widgets auf ähnliche Weise zum Anwendungsprojekt hinzugefügt werden.

Freigabe des Widgets mithilfe einer Bibliothek

Ein weiterer Ansatz besteht darin, das Widget in eine Bibliothek einzubinden, die sowohl mit dem „ Qt Widgets Designer“-Plugin als auch mit der Anwendung verknüpft ist. Es wird empfohlen, statische Bibliotheken zu verwenden, um Probleme beim Auffinden der Bibliothek zur Laufzeit zu vermeiden.

Informationen zu gemeinsam genutzten Bibliotheken finden Sie unter „Erstellen gemeinsam genutzter Bibliotheken“.

Verwendung des Plugins mit QUiLoader

Die empfohlene Vorgehensweise zum Hinzufügen benutzerdefinierter Widgets zu „ QUiLoader “ besteht darin, eine Unterklasse davon zu erstellen und die Methode ` QUiLoader::createWidget()` neu zu implementieren.

Es ist jedoch auch möglich, benutzerdefinierte Widget-Plugins für den „ Qt Widgets Designer“ zu verwenden (siehe „ QUiLoader::pluginPaths()“ und zugehörige Funktionen). Um zu vermeiden, dass die Bibliotheken des „ Qt Widgets Designer“ auf dem Zielgerät bereitgestellt werden müssen, sollten diese Plugins keine Verknüpfung zu den Bibliotheken des „ Qt Widgets Designer“ aufweisen (QT = uiplugin, siehe „Erstellen benutzerdefinierter Widgets für den „ Qt Widgets Designer“#ErstellenundInstallieren des Plugins“).

Verwandte Beispiele

Qt Widgets Weitere Informationen zur Verwendung benutzerdefinierter Widgets im „ Qt Widgets “-Designer finden Sie in den Beispielen „Custom Widget Plugin “ und „Task Menu Extension “. Außerdem können Sie die Klasse „ QDesignerCustomWidgetCollectionInterface “ verwenden, um mehrere benutzerdefinierte Widgets zu einer einzigen Bibliothek zusammenzufassen.