Bereitstellung von Attributen von C++-Typen für QML

QML lässt sich problemlos um Funktionen erweitern, die in C++-Code definiert sind. Aufgrund der engen Integration der QML-Engine mit dem Qt-Metaobjektsystem ist jede Funktion, die von einer von ` QObject` abgeleiteten Klasse oder einem ` Q_GADGET `-Typ entsprechend freigegeben wird, aus QML-Code heraus zugänglich. Dadurch können C++-Daten und -Funktionen direkt aus QML heraus aufgerufen werden, oft mit nur geringen oder gar keinen Anpassungen.

Die QML-Engine ist in der Lage, Instanzen von ` QObject ` über das Metaobjektsystem zu untersuchen. Das bedeutet, dass jeder QML-Code auf die folgenden Mitglieder einer Instanz einer von ` QObject` abgeleiteten Klasse zugreifen kann:

• Eigenschaften
• Methoden (sofern es sich um öffentliche Slots handelt oder diese mit ` Q_INVOKABLE` gekennzeichnet sind)
• Signale

(Darüber hinaus sind Enums verfügbar, sofern sie mit ` Q_ENUM` deklariert wurden. Weitere Details finden Sie unter „Datentypkonvertierung zwischen QML und C++ “.)

Im Allgemeinen sind diese von QML aus zugänglich, unabhängig davon, ob eine von ` QObject` abgeleitete Klasse beim QML-Typsystem registriert wurde. Soll eine Klasse jedoch so verwendet werden, dass die Engine auf zusätzliche Typinformationen zugreifen muss – beispielsweise, wenn die Klasse selbst als Methodenparameter oder Eigenschaft verwendet werden soll oder wenn einer ihrer Enum-Typen auf diese Weise verwendet werden soll –, dann muss die Klasse möglicherweise registriert werden. Die Registrierung wird für alle Typen empfohlen, die Sie in QML verwenden, da nur registrierte Typen zur Kompilierungszeit analysiert werden können.

Für „ Q_GADGET “-Typen ist die Registrierung erforderlich, da sie nicht von einer bekannten gemeinsamen Basis abgeleitet sind und nicht automatisch zur Verfügung gestellt werden können. Ohne Registrierung sind ihre Eigenschaften und Methoden nicht zugänglich.

Sie können C++-Typen aus einem anderen Modul in Ihrem eigenen Modul verfügbar machen, indem Sie Ihrem Aufruf von `qt_add_qml_module ` mithilfe der Option ` DEPENDENCIES ` eine Abhängigkeit hinzufügen. Möglicherweise möchten Sie beispielsweise eine Abhängigkeit zu „ QtQuick “ herstellen, damit Ihre über QML exponierten C++-Typen „ QColor “ als Methodenargumente und Rückgabewerte verwenden können. „ QtQuick “ exponiert „ QColor “ als Werttyp „color“. Solche Abhängigkeiten können zur Laufzeit automatisch abgeleitet werden, Sie sollten sich jedoch nicht darauf verlassen.

Beachten Sie außerdem, dass eine Reihe der in diesem Dokument behandelten wichtigen Konzepte im Tutorial „QML-Erweiterungen mit C++ schreiben “ veranschaulicht werden.

Weitere Informationen zu C++ und den verschiedenen Methoden zur QML-Integration finden Sie auf der Übersichtsseite zur C++- und QML-Integration.

Umgang mit Datentypen und Eigentumsverhältnisse

Alle Daten, die von C++ an QML übergeben werden – sei es als Eigenschaftswert, als Methodenparameter oder Rückgabewert oder als Signalparameterwert –, müssen einen Typ haben, der von der QML-Engine unterstützt wird.

Standardmäßig unterstützt die Engine eine Reihe von Qt-C++-Typen und kann diese bei der Verwendung in QML automatisch entsprechend konvertieren. Darüber hinaus können C++-Klassen, die im QML-Typsystem registriert sind, als Datentypen verwendet werden, ebenso wie ihre Enums, sofern diese entsprechend registriert sind. Weitere Informationen finden Sie unter „Datentypkonvertierung zwischen QML und C++ “.

Zudem werden bei der Datenübertragung von C++ nach QML die Regeln zur Dateneigentümerschaft berücksichtigt. Weitere Details finden Sie unter „Dateneigentümerschaft “.

Eigenschaften verfügbar machen

Für jede von ` QObject` abgeleitete Klasse kann mithilfe des Makros ` Q_PROPERTY()` eine Eigenschaft definiert werden. Eine Eigenschaft ist ein Klassen-Datenelement mit einer zugehörigen Lesefunktion und einer optionalen Schreibfunktion.

Auf alle Eigenschaften einer von ` QObject` abgeleiteten Klasse oder einer ` Q_GADGET `-Klasse kann von QML aus zugegriffen werden.

Im folgenden Beispiel ist eine von „ Message “ abgeleitete Klasse mit einer „ author “-Eigenschaft dargestellt. Wie durch den Makroaufruf „ Q_PROPERTY “ festgelegt, kann diese Eigenschaft über die Methode „ author() “ gelesen und über die Methode „ setAuthor() “ geschrieben werden:

Anstelle von:

using FooEnum = Foo::Enum;

class Bar : public QObject
{
    Q_OBJECT
    Q_PROPERTY(FooEnum enum READ enum WRITE setEnum NOTIFY enumChanged)
};

Verweise direkt auf den Typ:

class Bar : public QObject
{
    Q_OBJECT
    Q_PROPERTY(Foo::Enum enum READ enum WRITE setEnum NOTIFY enumChanged)
};

Um „ Message “ verfügbar zu machen, müssen Sie in C++ „ QML_ELEMENT “ und in CMake „qt_add_qml_module“ verwenden.

class Message : public QObject
{
    Q_OBJECT
    QML_ELEMENT
    Q_PROPERTY(QString author READ author WRITE setAuthor NOTIFY authorChanged)
public:
    void setAuthor(const QString &a)
    {
        if (a != m_author) {
            m_author = a;
            emit authorChanged();
        }
    }

    QString author() const
    {
        return m_author;
    }

signals:
    void authorChanged();

private:
    QString m_author;
};

Eine Instanz von ` Message ` kann als erforderliche Eigenschaft an eine Datei namens ` MyItem.qml ` übergeben werden, um sie verfügbar zu machen:

int main(int argc, char *argv[]) {
    QGuiApplication app(argc, argv);

    QQuickView view;
    Message msg;
    view.setInitialProperties({{"msg", &msg}});
    view.setSource(QUrl::fromLocalFile("MyItem.qml"));
    view.show();

    return app.exec();
}

Anschließend könnte die Eigenschaft „ author “ aus der Datei „ MyItem.qml “ ausgelesen werden:

// MyItem.qml
import QtQuick

Text {
    required property Message msg

    width: 100; height: 100
    text: msg.author    // invokes Message::author() to get this value

    Component.onCompleted: {
        msg.author = "Jonah"  // invokes Message::setAuthor()
    }
}

Um eine maximale Interoperabilität mit QML zu gewährleisten, sollte jede beschreibbare Eigenschaft über ein zugehöriges NOTIFY-Signal verfügen, das immer dann ausgelöst wird, wenn sich der Wert der Eigenschaft ändert. Dadurch kann die Eigenschaft mit der Eigenschaftsbindung verwendet werden – einer wesentlichen Funktion von QML, die Beziehungen zwischen Eigenschaften sicherstellt, indem sie eine Eigenschaft automatisch aktualisiert, sobald sich der Wert einer ihrer Abhängigkeiten ändert.

Im obigen Beispiel lautet das zugehörige NOTIFY-Signal für die Eigenschaft „ author “ „ authorChanged “, wie im Makroaufruf „ Q_PROPERTY()“ angegeben. Das bedeutet, dass jedes Mal, wenn das Signal ausgelöst wird – wie es der Fall ist, wenn der Autor in `Message::setAuthor()` geändert wird –, die QML-Engine darüber benachrichtigt wird, dass alle Bindungen, die die Eigenschaft ` author ` betreffen, aktualisiert werden müssen; daraufhin aktualisiert die Engine die Eigenschaft ` text `, indem sie erneut ` Message::author() ` aufruft.

Wäre die Eigenschaft „ author “ beschreibbar, hätte aber kein zugehöriges „NOTIFY“-Signal, würde der Wert von „ text “ mit dem von „ Message::author() “ zurückgegebenen Anfangswert initialisiert, aber bei späteren Änderungen an dieser Eigenschaft nicht aktualisiert werden. Außerdem würde jeder Versuch, die Eigenschaft von QML aus zu binden, eine Laufzeitwarnung der Engine auslösen.

Hinweise zur Verwendung von Notify-Signalen

Um Schleifen oder übermäßige Auswertungen zu vermeiden, sollten Entwickler sicherstellen, dass das Signal für die Eigenschaftsänderung nur dann ausgelöst wird, wenn sich der Wert der Eigenschaft tatsächlich geändert hat. Wenn eine Eigenschaft oder eine Gruppe von Eigenschaften nur selten verwendet wird, ist es zudem zulässig, dasselbe NOTIFY-Signal für mehrere Eigenschaften zu verwenden. Dies sollte mit Bedacht geschehen, um sicherzustellen, dass die Leistung nicht beeinträchtigt wird.

Das Vorhandensein eines NOTIFY-Signals verursacht einen geringen Overhead. Es gibt Fälle, in denen der Wert einer Eigenschaft bereits bei der Objekterstellung festgelegt wird und sich anschließend nicht mehr ändert. Der häufigste Fall hierfür ist eine schreibgeschützte Eigenschaft, die ein Unterobjekt enthält, auf das typischerweise über die Syntax für gruppierte Eigenschaften zugegriffen wird, wobei das Unterobjekt einmalig zugewiesen und erst freigegeben wird, wenn der Eigentümer gelöscht wird. In diesen Fällen kann anstelle eines NOTIFY-Signals das CONSTANT-Attribut zur Eigenschaftsdeklaration hinzugefügt werden.

Das CONSTANT-Attribut sollte nur für Eigenschaften verwendet werden, deren Wert ausschließlich im Klassenkonstruktor festgelegt und endgültig festgelegt wird. Alle anderen Eigenschaften, die in Bindungen verwendet werden sollen, sollten stattdessen ein NOTIFY-Signal aufweisen.

Eigenschaften mit Objekttypen

Auf Eigenschaften vom Objekttyp kann von QML aus zugegriffen werden, vorausgesetzt, der Objekttyp wurde ordnungsgemäß im QML-Typsystem registriert.

Beispielsweise könnte der Typ „ Message “ eine Eigenschaft „ body “ vom Typ „ MessageBody* “ haben:

class Message : public QObject
{
    Q_OBJECT
    Q_PROPERTY(MessageBody* body READ body WRITE setBody NOTIFY bodyChanged)
public:
    MessageBody* body() const;
    void setBody(MessageBody* body);
};

class MessageBody : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QString text READ text WRITE text NOTIFY textChanged)
// ...
}

Angenommen, der Typ „ Message “ wurde im QML-Typsystem registriert, sodass er im QML-Code als Objekttyp verwendet werden kann:

Message {
    // ...
}

Wäre der Typ „ MessageBody “ ebenfalls im Typsystem registriert, wäre es möglich, „ MessageBody “ der Eigenschaft „ body “ eines „ Message “ zuzuweisen – und zwar vollständig aus dem QML-Code heraus:

Message {
    body: MessageBody {
        text: "Hello, world!"
    }
}

Eigenschaften mit Objekt-Listen-Typen

Eigenschaften, die Listen von von ` QObject` abgeleiteten Typen enthalten, können ebenfalls für QML freigegeben werden. Zu diesem Zweck sollte man jedoch ` QQmlListProperty ` anstelle von ` QList<T>` als Eigenschaftstyp verwenden. Der Grund dafür ist, dass ` QList ` kein von ` QObject` abgeleiteter Typ ist und daher die erforderlichen QML-Eigenschaftseigenschaften nicht über das Qt-Metaobjektsystem bereitstellen kann, wie z. B. Signalbenachrichtigungen, wenn eine Liste geändert wird.

Beispielsweise verfügt die unten stehende Klasse „ MessageBoard “ über eine Eigenschaft „ messages “ vom Typ „ QQmlListProperty “, die eine Liste von „ Message “-Instanzen speichert:

class MessageBoard : public QObject
{
    Q_OBJECT
    Q_PROPERTY(QQmlListProperty<Message> messages READ messages)
public:
    QQmlListProperty<Message> messages();

private:
    static void append_message(QQmlListProperty<Message> *list, Message *msg);

    QList<Message *> m_messages;
};

Die Funktion `MessageBoard::messages()` erstellt lediglich ein ` QQmlListProperty ` anhand seines Mitglieds ` QList<T> m_messages ` und gibt dieses zurück, wobei sie die entsprechenden Funktionen zur Listenbearbeitung übergibt, wie vom Konstruktor von ` QQmlListProperty ` gefordert:

QQmlListProperty<Message> MessageBoard::messages()
{
    return QQmlListProperty<Message>(this, 0, &MessageBoard::append_message);
}

void MessageBoard::append_message(QQmlListProperty<Message> *list, Message *msg)
{
    MessageBoard *msgBoard = qobject_cast<MessageBoard *>(list->object);
    if (msg)
        msgBoard->m_messages.append(msg);
}

Beachten Sie, dass der Template-Klassentyp für die ` QQmlListProperty ` – in diesem Fall ` Message ` – im QML-Typsystem registriert sein muss.

Gruppierte Eigenschaften

Jede Eigenschaft, deren Typ eigene Untereigenschaften besitzt, kann mithilfe der Syntax für gruppierte Eigenschaften bearbeitet werden, unabhängig davon, ob es sich bei diesem Typ um einen Werttyp wie ` font ` oder um einen Objekttyp handelt. Gruppierte Eigenschaften sind nützlich, um eine Gruppe verwandter Eigenschaften offenzulegen, die eine Reihe von Attributen für einen Typ beschreiben.

Nehmen wir beispielsweise an, die Eigenschaft „ Message::author “ wäre vom Typ „ MessageAuthor “ statt einer einfachen Zeichenkette und hätte die Untereigenschaften „ name “ und „ email “:

class MessageAuthor : public QObject
{
    Q_PROPERTY(QString name READ name WRITE setName)
    Q_PROPERTY(QString email READ email WRITE setEmail)
public:
    ...
};

class Message : public QObject
{
    Q_OBJECT
    Q_PROPERTY(MessageAuthor* author READ author)
public:
    Message(QObject *parent)
        : QObject(parent), m_author(new MessageAuthor(this))
    {
    }
    MessageAuthor *author() const {
        return m_author;
    }
private:
    MessageAuthor *m_author;
};

Die Eigenschaft „ author “ könnte in QML mithilfe der Syntax für gruppierte Eigenschaften wie folgt geschrieben werden:

Message {
    author.name: "Alexandra"
    author.email: "alexandra@mail.com"
}

Da „ author “ eine Eigenschaft vom Typ „Objekt“ ist, wird durch die gruppierten Zuweisungen kein „ MessageAuthor “-Objekt erstellt. Sie werden in das Objekt geschrieben, das „ Message::author() “ zurückgibt. Dies hat einige Konsequenzen:

• Die Namen der Untereigenschaften werden anhand des deklarierten Typs der Eigenschaft – hier „ MessageAuthor “ – aufgelöst, nicht anhand des Typs des Objekts, das zur Laufzeit zufällig darin gespeichert ist. Verschiedene Instanziierungen von „ Message “ könnten „ author “-Objekte unterschiedlicher Typen erzeugen. Das Einzige, worauf wir uns beim Erstellen der QML-Komponente verlassen können, ist der deklarierte Typ.
• Das Objekt muss bereits existieren, wenn die gruppierten Zuweisungen angewendet werden. Andernfalls löst die Engine einen Fehler aus, der in etwa wie folgt lautet: „ Cannot set properties on author as it is null “. Das Erstellen des Objekts im Konstruktor des Eigentümers, wie oben beschrieben, ist der einfachste Weg, dies zu gewährleisten, aber ein Getter, der das Objekt beim ersten Zugriff erstellt, funktioniert genauso gut.
• Die Lebensdauer des Objekts richtet sich nach der C++-Implementierung. Die Syntax für gruppierte Eigenschaften erstellt oder löscht keine Objekte.

Die Deklaration von „ author “ als schreibgeschützt, wie im obigen Beispiel, verhindert zusätzlich, dass QML-Code das Objekt „ MessageAuthor “ ersetzt. Hätte „ author “ einen „ WRITE “-Zugriffsoperator, könnte man ihm ebenso gut ein neues Objekt zuweisen:

Message {
    author: MessageAuthor {
        name: "Alexandra"
        email: "alexandra@mail.com"
    }
}

Sie können die beiden Formen für dieselbe Eigenschaft nicht in derselben Objektdefinition kombinieren. Wenn Sie ein Objekt der ` author ` zuweisen und gleichzeitig ` author.name ` im selben ` Message ` schreiben, führt dies zu einem Fehler. Sie können dies umgehen, indem Sie die gruppierte Eigenschaft in einem anderen Gültigkeitsbereich platzieren. Dies führt jedoch zu verwirrenden Ergebnissen, da nun zwei Objekte vom Typ „ MessageAuthor “ vorhanden sind: das vom Konstruktor erstellte und das explizit zugewiesene. Ausschließlich die Reihenfolge der Bindungsauswertung bestimmt, auf welches der beiden die gruppierte Eigenschaft angewendet wird.

Das bedeutet, dass folgende Vorgehensweise empfehlenswert ist:

• Objekte, die als gruppierte Eigenschaften verwendet werden, sollten schreibgeschützt sein.
• Vermeiden Sie die Syntax für gruppierte Eigenschaften, wenn Sie auch die Basiseigenschaft der Gruppe selbst bearbeiten.

Bei einer Eigenschaft vom Werttyp wie „ font “ erfordern gruppierte Zuweisungen, dass die Eigenschaft beschreibbar ist, da die Engine den Wert liest, ihn ändert und wieder zurückschreibt. Die potenzielle Verwechslungsgefahr bleibt jedoch ein Problem. Wenn Sie die gesamte Eigenschaft „ font “ an derselben Stelle neu zuweisen und anschließend die Eigenschaft „ font.bold “ an einer anderen Stelle bearbeiten, bestimmt die Auswertungsreihenfolge der Bindungen, welche Operation zuerst ausgeführt wird und welcher Wert für „ bold “ sich daraus ergibt.

Methoden verfügbar machen (einschließlich Qt-Slots)

Jede Methode eines von ` QObject` abgeleiteten Typs ist aus dem QML-Code zugänglich, wenn sie:

• eine öffentliche Methode ist, die mit dem Makro ` Q_INVOKABLE()` gekennzeichnet ist
• Eine Methode, die ein öffentlicher Qt -Slot ist

Beispielsweise verfügt die unten stehende Klasse ` MessageBoard ` über eine Methode ` postMessage() `, die mit dem Makro ` Q_INVOKABLE ` gekennzeichnet wurde, sowie über eine Methode ` refresh() `, die ein öffentlicher Slot ist:

class MessageBoard : public QObject
{
    Q_OBJECT
    QML_ELEMENT

public:
    Q_INVOKABLE bool postMessage(const QString&msg) {
        qDebug() << "Called the C++ method with" << msg;
       return true;
    }

public slots:
    void refresh() {
        qDebug() << "Called the C++ slot";
    }
};

Wenn eine Instanz von ` MessageBoard ` als erforderliche Eigenschaft für eine Datei ` MyItem.qml` festgelegt wurde, könnte ` MyItem.qml ` die beiden Methoden wie in den folgenden Beispielen gezeigt aufrufen:

int main(int argc, char *argv[]) {
    QGuiApplication app(argc, argv);

    MessageBoard msgBoard;
    QQuickView view;
    view.setInitialProperties({{"msgBoard", &msgBoard}});
    view.setSource(QUrl::fromLocalFile("MyItem.qml"));
    view.show();

    return app.exec();
}

// MyItem.qml
import QtQuick 2.0

Item {
    required property MessageBoard msgBoard

    width: 100; height: 100

    MouseArea {
        anchors.fill: parent
        onClicked: {
            var result = msgBoard.postMessage("Hello from QML")
            console.log("Result of postMessage():", result)
            msgBoard.refresh();
        }
    }
}

Wenn eine C++-Methode einen Parameter vom Typ ` QObject* ` hat, kann der Parameterwert aus QML mithilfe eines Objekt id s oder eines JavaScript-Werts ` var ` übergeben werden, der auf das Objekt verweist.

QML unterstützt den Aufruf überladener C++-Funktionen. Wenn mehrere C++-Funktionen mit demselben Namen, aber unterschiedlichen Argumenten vorhanden sind, wird die richtige Funktion entsprechend der Anzahl und den Typen der übergebenen Argumente aufgerufen.

Von C++-Methoden zurückgegebene Werte werden in JavaScript-Werte konvertiert, wenn von JavaScript-Ausdrücken in QML darauf zugegriffen wird.

C++-Methoden und das „this“-Objekt

Möglicherweise möchten Sie eine C++-Methode von einem Objekt abrufen und sie auf einem anderen Objekt aufrufen. Betrachten Sie das folgende Beispiel in einem QML-Modul namens „ Example “:

class Invokable : public QObject
{
    Q_OBJECT
    QML_ELEMENT
public:
    Invokable(QObject *parent = nullptr) : QObject(parent) {}

    Q_INVOKABLE void invoke() { qDebug() << "invoked on " << objectName(); }
};

import QtQml
import Example

Invokable {
    objectName: "parent"
    property Invokable child: Invokable {}
    Component.onCompleted: child.invoke.call(this)
}

Wenn Sie den QML-Code aus einer entsprechenden `main.cpp` laden, sollte die Ausgabe „invoked on parent“ lauten. Aufgrund eines seit Langem bestehenden Fehlers ist dies jedoch nicht der Fall. Historisch gesehen ist das „this“-Objekt von C++-basierten Methoden untrennbar mit der Methode verbunden. Eine Änderung dieses Verhaltens bei bestehendem Code würde zu subtilen Fehlern führen, da das „this“-Objekt an vielen Stellen implizit verwendet wird. Seit Qt 6.5 können Sie das korrekte Verhalten explizit aktivieren und C++-Methoden die Annahme eines „this“-Objekts ermöglichen. Fügen Sie dazu die folgende Pragma-Anweisung in Ihre Qml-Dokumente ein:

pragma NativeMethodBehavior: AcceptThisObject

Wenn diese Zeile hinzugefügt wird, funktioniert das obige Beispiel wie erwartet.

Überschreiben von `toString()`

Wenn Sie eine Methode „ Q_INVOKABLE “ namens „toString“ (ohne Argumente) bereitstellen, wird diese Methode anstelle der nativen „toString“-Implementierung von JavaScript verwendet, um das Objekt in eine Zeichenkette zu konvertieren.

Signale verfügbar machen

Jedes öffentliche Signal eines von ` QObject` abgeleiteten Typs ist aus dem QML-Code heraus zugänglich.

Die QML-Engine erstellt automatisch einen Signal-Handler für jedes Signal eines von ` QObject` abgeleiteten Typs, das aus QML heraus verwendet wird. Signal-Handler werden stets als `on<Signal> ` benannt, wobei ` <Signal> ` der Name des Signals ist, dessen erster Buchstabe großgeschrieben wird. Alle vom Signal übergebenen Parameter stehen im Signal-Handler über die Parameternamen zur Verfügung.

Angenommen, die Klasse ` MessageBoard ` verfügt über ein Signal ` newMessagePosted() ` mit einem einzigen Parameter, ` subject`:

class MessageBoard : public QObject
{
    Q_OBJECT
public:
   // ...
signals:
   void newMessagePosted(const QString &subject);
};

Wäre der Typ „ MessageBoard “ im QML-Typsystem registriert, könnte ein in QML deklariertes „ MessageBoard “-Objekt das Signal „ newMessagePosted() “ mithilfe eines Signalhandlers namens „ onNewMessagePosted “ empfangen und den Wert des Parameters „ subject “ auswerten:

MessageBoard {
    onNewMessagePosted: (subject)=> console.log("New message received:", subject)
}

Wie bei Eigenschaftswerten und Methodenparametern muss ein Signalparameter einen Typ haben, der von der QML-Engine unterstützt wird; siehe Datentypkonvertierung zwischen QML und C++. (Die Verwendung eines nicht registrierten Typs führt zwar nicht zu einem Fehler, aber der Parameterwert ist vom Handler aus nicht zugänglich.)

Klassen können mehrere Signale mit demselben Namen haben, aber nur das letzte Signal ist als QML-Signal zugänglich. Beachten Sie, dass Signale mit demselben Namen, aber unterschiedlichen Parametern nicht voneinander unterschieden werden können.