Definition von Objekttypen über QML-Dokumente

Eine der Kernfunktionen von QML besteht darin, dass sich QML-Objekttypen auf einfache und ressourcenschonende Weise über QML-Dokumente definieren lassen, um den Anforderungen einzelner QML-Anwendungen gerecht zu werden. Das Standardmodul Qt Quick Modul stellt verschiedene Typen wie „ Rectangle “, „ Text “ und „ Image “ für die Erstellung einer QML-Anwendung bereit; darüber hinaus können Sie ganz einfach eigene QML-Typen definieren, die innerhalb Ihrer Anwendung wiederverwendet werden können. Diese Möglichkeit, eigene Typen zu erstellen, bildet die Bausteine jeder QML-Anwendung.

Definition eines Objekttyps mit einer QML-Datei

Benennung benutzerdefinierter QML-Objekttypen

Um einen Objekttyp zu erstellen, sollte ein QML-Dokument in einer Textdatei mit dem Namen <TypeName>.qml abgelegt werden, wobei <TypeName> der gewünschte Name des Typs ist. Der Typname muss folgende Anforderungen erfüllen:

• Er muss aus alphanumerischen Zeichen oder Unterstrichen bestehen.
• Er muss mit einem Großbuchstaben beginnen.

Dieses Dokument wird dann von der Engine automatisch als Definition eines QML-Typs erkannt. Zudem wird ein auf diese Weise definierter Typ automatisch für andere QML-Dateien im selben lokalen Verzeichnis verfügbar gemacht, da die Engine beim Auflösen von QML-Typnamen das unmittelbare Verzeichnis durchsucht.

Benutzerdefinierte QML-Typdefinition

Im Folgenden finden Sie beispielsweise ein Dokument, das einen „ Rectangle “ mit einem untergeordneten „ MouseArea “ deklariert. Das Dokument wurde unter dem Namen „ SquareButton.qml “ gespeichert:

// SquareButton.qml
import QtQuick 2.0

Rectangle {
    property int side: 100
    width: side; height: side
    color: "red"

    MouseArea {
        anchors.fill: parent
        onClicked: console.log("Button clicked!")
    }
}

Da die Datei den Namen „ SquareButton.qml “ trägt, kann dieser nun von jeder anderen QML-Datei im selben Verzeichnis als Typ „ SquareButton “ verwendet werden. Befände sich beispielsweise im selben Verzeichnis eine Datei namens „ myapplication.qml “, könnte diese auf den Typ „ SquareButton “ verweisen:

// myapplication.qml
import QtQuick 2.0

SquareButton {}

Dadurch wird ein roter „ Rectangle “ mit den Maßen 100 × 100 und einem inneren „ MouseArea “ erstellt, wie in „ SquareButton.qml “ definiert. Wenn dieses „ myapplication.qml “-Dokument von der Engine geladen wird, lädt sie das „SquareButton.qml“-Dokument als Komponente und instanziiert es, um ein „ SquareButton “-Objekt zu erstellen.

Der Typ „ SquareButton “ kapseln den Baum der in „ SquareButton.qml “ deklarierten QML-Objekte. Wenn die QML-Engine ein „ SquareButton “-Objekt aus diesem Typ instanziiert, instanziiert sie ein Objekt aus dem in „ SquareButton.qml “ deklarierten „ Rectangle “-Baum.

Inline-Komponenten

Manchmal kann es umständlich sein, eine neue Datei für einen Typ zu erstellen, beispielsweise wenn ein kleiner Delegat in mehreren Ansichten wiederverwendet wird. Wenn Sie den Typ nicht tatsächlich offenlegen müssen, sondern lediglich eine Instanz erstellen möchten, ist „ Component “ eine Option. Wenn Sie jedoch Eigenschaften mit den Komponententypen deklarieren oder die Komponente in mehreren Dateien verwenden möchten, kommt „ Component “ nicht in Frage. In diesem Fall können Sie Inline-Komponenten verwenden. Inline-Komponenten deklarieren eine neue Komponente innerhalb einer Datei. Die Syntax dafür lautet

component <component name> : BaseType {
    // declare properties and bindings here
}

Innerhalb der Datei, in der die Inline-Komponente deklariert wird, kann auf den Typ einfach über seinen Namen verwiesen werden.

// Images.qml
import QtQuick

Item {
    component LabeledImage: Column {
        property alias source: image.source
        property alias caption: text.text

        Image {
            id: image
            width: 50
            height: 50
        }
        Text {
            id: text
            font.bold: true
        }
    }

    Row {
        LabeledImage {
            id: before
            source: "before.png"
            caption: "Before"
        }
        LabeledImage {
            id: after
            source: "after.png"
            caption: "After"
        }
    }
    property LabeledImage selectedImage: before
}

In anderen Dateien muss dem Namen der Typ mit dem Namen der übergeordneten Komponente vorangestellt werden.

// LabeledImageBox.qml
import QtQuick

Rectangle {
    property alias caption: image.caption
    property alias source: image.source
    border.width: 2
    border.color: "black"
    Images.LabeledImage {
        id: image
    }
}

// A.qml
import QtQuick

Item {
    id: root
    property string message: "From A"
    component MyInlineComponent : Item {
        Component.onCompleted: console.log(root.message)
    }
}
// B.qml
import QtQuick

Item {
    A.MyInlineComponent {}
}

Importieren von Typen, die außerhalb des aktuellen Verzeichnisses definiert sind

Befände sich „ SquareButton.qml “ nicht im selben Verzeichnis wie „ myapplication.qml “, müsste der Typ „ SquareButton “ über eine Import anweisung in „ myapplication.qml “ explizit verfügbar gemacht werden. Er könnte über einen relativen Pfad im Dateisystem oder als installiertes Modul importiert werden; weitere Details finden Sie unter „Modul “.

Zugängliche Attribute benutzerdefinierter Typen

Die Definition des Stammobjekts in einer .qml-Datei legt fest, welche Attribute für einen QML-Typ verfügbar sind. Alle Eigenschaften, Signale und Methoden, die zu diesem Stammobjekt gehören – unabhängig davon, ob sie benutzerdefiniert sind oder vom QML-Typ des Stammobjekts stammen – sind von außen zugänglich und können für Objekte dieses Typs gelesen und geändert werden.

Beispielsweise ist der Stammobjekttyp in der obigen Datei „ SquareButton.qml “ „ Rectangle “. Das bedeutet, dass alle vom Typ „ Rectangle “ definierten Eigenschaften für ein „ SquareButton “-Objekt geändert werden können. Der folgende Code definiert drei „ SquareButton “-Objekte mit benutzerdefinierten Werten für einige der Eigenschaften des Stammobjekts „ Rectangle “ vom Typ „ SquareButton “:

// application.qml
import QtQuick 2.0

Column {
    SquareButton { side: 50 }
    SquareButton { x: 50; color: "blue" }
    SquareButton { radius: 10 }
}

Zu den Attributen, auf die Objekte des benutzerdefinierten QML-Typs zugreifen können, gehören alle benutzerdefinierten Eigenschaften, Methoden und Signale, die zusätzlich für ein Objekt definiert wurden. Angenommen, das ` Rectangle ` in ` SquareButton.qml ` wäre wie folgt mit zusätzlichen Eigenschaften, Methoden und Signalen definiert worden:

// SquareButton.qml
import QtQuick 2.0

Rectangle {
    id: root

    property bool pressed: mouseArea.pressed

    signal buttonClicked(real xPos, real yPos)

    function randomizeColor() {
        root.color = Qt.rgba(Math.random(), Math.random(), Math.random(), 1)
    }

    property int side: 100
    width: side; height: side
    color: "red"

    MouseArea {
        id: mouseArea
        anchors.fill: parent
        onClicked: (mouse)=> root.buttonClicked(mouse.x, mouse.y)
    }
}

Jedes „ SquareButton “-Objekt könnte die Eigenschaft „ pressed “, das Signal „ buttonClicked “ und die Methode „ randomizeColor() “ nutzen, die dem Stammobjekt „ Rectangle “ hinzugefügt wurden:

// application.qml
import QtQuick 2.0

SquareButton {
    id: squareButton

    onButtonClicked: (xPos, yPos)=> {
        console.log("Clicked", xPos, yPos)
        randomizeColor()
    }

    Text { text: squareButton.pressed ? "Down" : "Up" }
}

Beachten Sie, dass die in „ SquareButton.qml “ definierten „ id “-Werte für „ SquareButton “-Objekte nicht zugänglich sind, da auf „id“-Werte nur innerhalb des Komponentenbereichs zugegriffen werden kann, in dem eine Komponente deklariert ist. Die obige Objektdefinition „ SquareButton “ kann nicht auf „ mouseArea “ verweisen, um auf das untergeordnete Element „ MouseArea “ zu verweisen, und wenn sie einen „ id “ von „ root “ anstelle von „ squareButton “ hätte, würde dies keinen Konflikt mit dem „ id “ desselben Werts für das in „ SquareButton.qml “ definierte Stammobjekt darstellen, da beide innerhalb separater Gültigkeitsbereiche deklariert wären.