Ein Schneller Einstieg (teilweise dt.)¶

Die QML Syntax¶

QML ist eine Auszeichnungs- oder Beschreibungssprache mit deren Hilfe das Benutzerinterface deiner Anwendung beschrieben wird. Das Benutzerinterface wird durch kleine Elemente beschrieben, die in größere Komponenten zusammengefasst werden. QML beschreibt dabei das Aussehen und das Verhalten der Interfaceelemente. Das Benutzerinterface kann dann mit Hilfe von JavaScript Code erweitert werden um einfache oder komplexe Programmlogik hinzuzufügen. Diese Art und Weise folgt dem HTML-JavaScript Muster, aber QML ist im Gegensatz zu HTML von Grund auf darauf ausgelegt, Benutzerschnittstellen statt Text-Dokumente zu beschreiben.

In ihrer einfachsten Form ist QML eine Hierarchie von Elementen. Kinder-Elemente erben das Koordinatensystem von ihren Eltern. Eine x,y Koordinate ist immer relativ zum Elternelement.

Beginnen wir mit einem einfachen Beispiel einer QML-Datei um die zu HTML unterschiedliche Syntax zu erklären:

// RectangleExample.qml

import QtQuick 2.5

// The root element is the Rectangle
Rectangle {
    // name this element root
    id: root

    // properties: <name>: <value>
    width: 120; height: 240

    // color property
    color: "#4A4A4A"

    // Declare a nested element (child of root)
    Image {
        id: triangle

        // reference the parent
        x: (parent.width - width)/2; y: 40

        source: 'assets/triangle_red.png'
    }

    // Another child of root
    Text {
        // un-named element

        // reference element by id
        y: triangle.y + triangle.height + 20

        // reference root element
        width: root.width

        color: 'white'
        horizontalAlignment: Text.AlignHCenter
        text: 'Triangle'
    }
}

• Der import Befehl importiert ein Modul in einer speziellen Version. Grundsätzlich ist der Import von QtQuick 2.0 ein guter Start.

• Einzeilige Kommentare kann man mit Hilfe von // oder mehrzeilige mit Hilfe von /* */ eingeben, genau wir in C/C++ und JavaScript

• Jede QML-Datei benötigt genau ein Wurzelelement wie in HTML (hier: “Rectangle”)

• Ein Element wird über sein Typ gefolgt von { } definiert.

• Elemente können Eigenschaften haben, die in der Form name : value geschrieben werden.

• Beliebige Elemente innerhalb eines QML-Dokuments können über ihre id (ein Bezeichner ohne Anführungszeichen) angesprochen werden.

• Elemente können verschachtelt werden, was dann bedeutet, dass ein Elternelement Kindelemente hat. Die Elternelemente kann man über das Schlüsselwort parent ansprechen.

$ $QTDIR/bin/qmlscene RectangleExample.qml

    Text {
        // (1) identifier
        id: thisLabel

        // (2) set x- and y-position
        x: 24; y: 16

        // (3) bind height to 2 * width
        height: 2 * width

        // (4) custom property
        property int times: 24

        // (5) property alias
        property alias anotherTimes: thisLabel.times

        // (6) set text appended by value
        text: "Greetings " + times

        // (7) font is a grouped property
        font.family: "Ubuntu"
        font.pixelSize: 24

        // (8) KeyNavigation is an attached property
        KeyNavigation.tab: otherLabel

        // (9) signal handler for property changes
        onHeightChanged: console.log('height:', height)

        // focus is need to receive key events
        focus: true

        // change color based on focus value
        color: focus?"red":"black"
    }

    Text {
        id: label

        x: 24; y: 24

        // custom counter property for space presses
        property int spacePresses: 0

        text: "Space pressed: " + spacePresses + " times"

        // (1) handler for text changes
        onTextChanged: console.log("text changed to:", text)

        // need focus to receive key events
        focus: true

        // (2) handler with some JS
        Keys.onSpacePressed: {
            increment()
        }

        // clear the text on escape
        Keys.onEscapePressed: {
            label.text = ''
        }

        // (3) a JS function
        function increment() {
            spacePresses = spacePresses + 1
        }
    }

Keys.onEscapePressed: {
    label.text = ''
}

Basiselemente¶

Elemente kann man in visuelle und nicht-visuelle Elemente gruppieren. Ein visuelles Elemente (wie z.B. Rectangle) hat eine Geometrie und wird üblicherweise auf einem Gebiet des Bildschirms angezeigt. Ein nicht-visuelles Elemente (wie z.B. ein Timer) bringt allgemeine Funktionalität mit sich, die man oft verwendet um die visuellen Elemente zu manipulieren.

Wir fokussieren uns hier mal auf die fundamentalen visuellen Elemente, wie Item, Rectangle, Text, Image und MouseArea.

Das Rectangle Element¶

Issues: Create | View

Das Rechteckelement Rectangle beerbt und erweitert das Item Element und fügt eine Füllfarbe und Ränder hinzu über border.color and border.width. Für abgerundete Ecken ist die radius Eigenschaft zuständig.

    Rectangle {
        id: rect1
        x: 12; y: 12
        width: 76; height: 96
        color: "lightsteelblue"
    }
    Rectangle {
        id: rect2
        x: 112; y: 12
        width: 76; height: 96
        border.color: "lightsteelblue"
        border.width: 4
        radius: 8
    }

Bemerkung

Gültige Farbwerte sind Farben der SVG Farbnamen (siehe http://www.w3.org/TR/css3-color/#svg-color). Man kann Farben in QML auf verschiedene Weisen produzieren, der übliche Weg ist ein RGB-Farbwert (‘#FF4444’) oder über einen englischen Farbnamen (z.B. ‘white’).

Neben der Füllfarbe und einem Rand unterstützt ein Rechteck noch selbsterstellte Gradienten.

    Rectangle {
        id: rect1
        x: 12; y: 12
        width: 176; height: 96
        gradient: Gradient {
            GradientStop { position: 0.0; color: "lightsteelblue" }
            GradientStop { position: 1.0; color: "slategray" }
        }
        border.color: "slategray"
    }

Ein Gradient wird über eine Folge von Gradientenmarken GradientStop definiert. Jede Marke hat eine Position und eine Farbe. Die Position legt die Marke auf der y-Achse fest (0=oben, 1=unten) und color die Farbe an dieser Position.

Bemerkung

Ein Rechteck mit keiner Höhe/Breite wird nicht sichrbar sein. Das kann oft dann passieren, wenn man mehrere Rechtecksbreiten (-höhen) von einander abhängig definiert hat und irgendetwas in der Logik des Zusammenbaus schief ging.

Bemerkung

Man kann keinen schrägen Gradienten erzeugen. Dann ist es besser, vordefinierte Bilder zu verwenden. Man könnte zwar die Rechtecke mit Gradient drehen, aber dann stimmt die Geometrie des gedrehten Rechtecks wird nicht geändert und wird daher zu Verwirrung führen, weil die Geometrie des Elements dann nicht mehr mit der Geometrie der sichtbaren Fläche zusammenpasst. Der Autor meint, es sei besser, vordesignte Gradientenbilder zu verwenden.

Das Text Element¶

Issues: Create | View

Um Text anzuzeigen, ist das Text Element geeignet. Seine wichtigste Eigenschaft ist die text-Eigenschaft vom Datentyp string. Das Element berechnet seine Breite und Höhe erstmals aus dem anfangs gesetzten Text und der verwendeten Schriftart. Die Schriftart kann mit der Eigenschaftengruppe font beeinflusst werden (e.g. font.family, font.pixelSize, ...). Die Farbe des Textes wird mit der color-Eigenschaft geändert.

    Text {
        text: "The quick brown fox"
        color: "#303030"
        font.family: "Ubuntu"
        font.pixelSize: 28
    }

Text kann mit den Eigenschaften horizontalAlignment und verticalAlignment links-,unten-, rechts- oder obenbündig oder zentriert angeordnet werden. Um die Textgestaltung noch zu verbessern kann man style und styleColor-Eigenschaften verwenden, die den Text umrahmt, versunken oder erhöht darstellen. Für einen längeren Text möchte man ihn entweder verkürzt darstellen und Auslassungspunke A very ... long text mit der elide-Eigenschaft entweder auf links, rechts oder mittig festlegen. Alternativ kann man den gesamten Text umgebrochen anzeigen lassen mit Hilfe der wrapMode-Eigenschaft. Diese funktioniert aber nur, wenn die Breite explizit gesetzt wurde:

Text {
    width: 40; height: 120
    text: 'A very long text'
    // '...' shall appear in the middle
    elide: Text.ElideMiddle
    // red sunken text styling
    style: Text.Sunken
    styleColor: '#FF4444'
    // align text to the top
    verticalAlignment: Text.AlignTop
    // only sensible when no elide mode
    // wrapMode: Text.WordWrap
}

Ein Text-Element zeigt nur den angegebenen Text an. Es wird kein Hintergrund gestaltet. Außer dem gerenderten Text ist das Element transparent. Das darunterliegende Design ist verantwortlich einen sinnvollen Hintergrund für das Textelement zu bieten.

Bemerkung

Vorsicht bei der Anfangsbreite (und -höhe) eines Textelements. Sie hängt von der Zeichenkette und der Schriftgestaltung ab. Ein Text-Element ohne gesetzte Breite und ohne Textinhalt wird nicht sichtbar sein, weil die Anfangsbreite auf 0 gesetzt ist.

Bemerkung

Wenn man ein Text-Element in ein Layout einpasst muss man zwischen der Ausrichtung der Schrift innerhalb der Abgrenzungsbox des Text-Elements und der Ausrichtung der Abgrenzung selbst unterscheiden. Für erstere verwendet man die horizontalAlignment und verticalAlignment-Eigenschaften und im letzeren Fall sollte man die Elementgeometrie beeinflussen oder Anker verwenden.

Das Image-Element¶

Issues: Create | View

Ein Image-Element kann Bilder verschiedener Formate anzeigen (z.B. PNG, JPG, GIF, BMP, WEBP). Für eine vollständige Liste, konsultiere bitte die Qt Dokumentation. Neben der source-Eigenschaft die den URL des Bildes enthalten sollte, gibt es einen Modus fillMode, der das Verhalten bei Größenänderungen festlegt.

    Image {
        x: 12; y: 12
        // width: 72
        // height: 72
        source: "assets/triangle_red.png"
    }
    Image {
        x: 12+64+12; y: 12
        // width: 72
        height: 72/2
        source: "assets/triangle_red.png"
        fillMode: Image.PreserveAspectCrop
        clip: true
    }

Bemerkung

Ein URL kann ein lokaler Pfad mit Schrägstrichen (z.B. ”./images/home.png”) oder ein HTTP-Link (z.B. “http://example.org/home.png”).

Bemerkung

Image-Elemente die PreserveAspectCrop verwenden, sollten auch Abschneiden (clipping) verwenden, um zu vermeiden, dass das Bild außerhalb der Grenzen des Elements angezeigt wird. Standardmäßig ist Abschneiden ausgeschalten (clip : false), die muss man mit (clip : true) einschalten. Das gilt im Übrigen für jegliche sichtbare Elemente.

Tipp

Verwendest du C++, dann kannst du deine eigenen Bilder “on the fly” und auch multithreaded erstellen. Verwende dafür den Provider QQmlImageProviderBase.

Das MouseArea Element¶

Issues: Create | View

Um mit einem der bisherigen Elemente zu interagieren wird man oft ein MouseArea-Element verwenden. Das ist ein rechteckiges unsichtbares Objekt in dem man Maussignale auffangen kann. Dieses maussensitive Gebiet wird oft zusammen mit einem sichtbaren Element verwendet um Befehle auszuführen, wenn der Benutzer mit dem sichtbaren Teil interagieren will.

    Rectangle {
        id: rect1
        x: 12; y: 12
        width: 76; height: 96
        color: "lightsteelblue"
        MouseArea {
            id: area
            width: parent.width
            height: parent.height
            onClicked: rect2.visible = !rect2.visible
        }
    }

    Rectangle {
        id: rect2
        x: 112; y: 12
        width: 76; height: 96
        border.color: "lightsteelblue"
        border.width: 4
        radius: 8
    }

Bemerkung

Ein wichtiger Bestandteil von Qt Quick ist, dass die Verarbeitung von Eingaben von der visuellen Darstellung getrennt ist. Dadurch kann man dem Benutzer ein Element anzeigen, aber das Gebiet der Interaktion kann größer sein.

(Eigene) Komponenten¶

Eine Komponente ist ein wiederverwendbares Element und QML bietet mehrere Möglichkeiten, diese zu erzeugen. Hier schauen wir uns die einfachste Möglichkeit an - eine Komponente, die über eine Datei erzeugt wird. Dazu wird ein QML Element in einer Datei angelegt und der Datei den Elementnamen gegeben (z.B. Button.qml). Man kann die Komponente dann wie jedes andere Element aus den QtQuick Modulen verwenden, in unserem Fall würde man in seinem Code Button { ... } verwenden.

Lass’ uns beispielsweise ein Rechteck mit einem Textelement und einer “MouseArea”. Das erinnert an einen einfachen Knopf und muss für die Demonstrationszwecke nicht komplizierter sein.

    Rectangle { // our inlined button ui
        id: button
        x: 12; y: 12
        width: 116; height: 26
        color: "lightsteelblue"
        border.color: "slategrey"
        Text {
            anchors.centerIn: parent
            text: "Start"
        }
        MouseArea {
            anchors.fill: parent
            onClicked: {
                status.text = "Button clicked!"
            }
        }
    }

    Text { // text changes when button was clicked
        id: status
        x: 12; y: 76
        width: 116; height: 26
        text: "waiting ..."
        horizontalAlignment: Text.AlignHCenter
    }

Das Userinterface wird so oder ähnlich aussehen. Auf der linken Seite das Userinterface im Anfangszustand, auf der rechten Seite, nachdem die Schaltfläche geklickt wurde.

Unsere Aufgabe ist es jetzt dieses Userinterface der Schaltfläche in eine wiederverwendbare Komponente zu extrahieren. Daher denken wir mal kurz darübernach, welche mögliche API (welche Funktionalität) die Schaltfläche haben sollte. Am besten überlegt man sich, wie jemand anderes deine Schaltfläche verwenden sollte. Hier sind mal meine Ideen:

// minimal API for a button
Button {
    text: "Click Me"
    onClicked: { // do something }
}

Ich würde als Benutzer gerne den Text der Schaltfläche über eine text-Eigenschaft und meinen eigenen Handler für die Klickaktion festlegen können. Außerdem würde ich erwarten, dass die Schaltfläche eine sinnvolle Anfangsgröße besitzt, die ich aber überschreiben kann, z.B. mit width: 240.

Um das zu erreichen erstellen wir eine Datei Button.qml und kopieren unser Schaltflächen-UserInterface hinein. Zusätzlich müssen wir noch die Eigenschaften exportieren, die ein Benutzer auf unterster Ebene eben ändern können möchte.

// Button.qml

import QtQuick 2.5

Rectangle {
    id: root
    // export button properties
    property alias text: label.text
    signal clicked

    width: 116; height: 26
    color: "lightsteelblue"
    border.color: "slategrey"

    Text {
        id: label
        anchors.centerIn: parent
        text: "Start"
    }
    MouseArea {
        anchors.fill: parent
        onClicked: {
            root.clicked()
        }
    }
}

Wir haben jetzt den Text exporiert und eine Klick-Signal auf Wurzelebene. Typischerweise bennen wir unser Wurzelelement “root” um es mit dem Bezug auf unsere Kompontente einfacher zu haben. Wir verwenden dazu das alias Feature von QML als ein Weg die Eigenschaften von innerhalb des verschachtelten QML-Elements auf Wurzelebene zu haben und für die Außenwelt verfügbar zu machen, denn nur auf Eigenschaften auf Wurzelebene der Komponente können von außen zugegriffen werden.

Um unsere neue Schaltfläche als Element verwenden zu können, müssen wir es einfach nur in unserer Datei deklarieren. Auf diese Weise ist unsere ursprüngliches Beispiel ein bisschen übersichtlicher geworden.

    Button { // our Button component
        id: button
        x: 12; y: 12
        text: "Start"
        onClicked: {
            status.text = "Button clicked!"
        }
    }

    Text { // text changes when button was clicked
        id: status
        x: 12; y: 76
        width: 116; height: 26
        text: "waiting ..."
        horizontalAlignment: Text.AlignHCenter
    }

Jetzt kann man so viele Schaltflächen wie man will im Userinterface verwenden indem man einfach Button { ... } verwendet. Eine echte Schaltfläche würde etwas komplexer sein, z.B. etwas rückmelden wenn sie angeklickt wurde oder etwas schöner dekoriert sein.

Item {
    id: root
    width: 116; height: 26

    property alias text: label.text
    signal clicked

    Rectangle {
        anchors.fill parent
        color: "lightsteelblue"
        border.color: "slategrey"
    }
    ...
}

Mit Hilfe dieses Verfahrens ist es sehr einfach, eine eigene Serie von wiederverwendbaren Komponenten herzustellen.

Simple Transformations¶

A transformation manipulates the geometry of an object. QML Items can in general be translated, rotated and scaled. There is a simple form of these operations and a more advanced way.

Let’s start with the simple transformations. Here is our scene as our starting point.

A simple translation is done via changing the x,y position. A rotation is done using the rotation property. The value is provided in degrees (0 .. 360). A scaling is done using the scale property and a value <1 means the element is scaled down and >1 means the element is scaled up. The rotation and scaling does not change your geometry. The items x,y and width/height haven’t changed. Just the painting instructions are transformed.

Before we show off the example I would like to introduce a little helper: The ClickableImage element. The ClickableImage is just an image with a mouse area. This brings up a useful rule of thumb - if you have copied a chunk of code three times, extract it into a component.

// ClickableImage.qml

// Simple image which can be clicked

import QtQuick 2.5

Image {
    id: root
    signal clicked

    MouseArea {
        anchors.fill: parent
        onClicked: root.clicked()
    }
}

We use our clickable image to present three objects (box, circle, triangle). Each object performs a simple transformation when clicked. Clicking the background will reset the scene.

// transformation.qml


import QtQuick 2.5

Item {
    // set width based on given background
    width: bg.width
    height: bg.height

    Image { // nice background image
        id: bg
        source: "assets/background.png"
    }

    MouseArea {
        id: backgroundClicker
        // needs to be before the images as order matters
        // otherwise this mousearea would be before the other elements
        // and consume the mouse events
        anchors.fill: parent
        onClicked: {
            // reset our little scene
            circle.x = 84
            box.rotation = 0
            triangle.rotation = 0
            triangle.scale = 1.0
        }
    }

    ClickableImage {
        id: circle
        x: 84; y: 68
        source: "assets/circle_blue.png"
        antialiasing: true
        onClicked: {
            // increase the x-position on click
            x += 20
        }
    }

    ClickableImage {
        id: box
        x: 164; y: 68
        source: "assets/box_green.png"
        antialiasing: true
        onClicked: {
            // increase the rotation on click
            rotation += 15
        }
    }

    ClickableImage {
        id: triangle
        x: 248; y: 68
        source: "assets/triangle_red.png"
        antialiasing: true
        onClicked: {
            // several transformations
            rotation += 15
            scale += 0.05
        }
    }

    function _test_transformed() {
        circle.x += 20
        box.rotation = 15
        triangle.scale = 1.2
        triangle.rotation = -15
    }

    function _test_overlap() {
        circle.x += 40
        box.rotation = 15
        triangle.scale = 2.0
        triangle.rotation = 45
    }

}

The circle increments the x-position on each click and the box will rotate on each click. The triangle will rotate and scale the image down on each click, to demonstrate a combined transformation. For the scaling and rotation operation we set antialiasing: true to enable anti-aliasing, which is switched off (same as the clipping property clip) for performance reasons. In your own work, when you see some rasterized edges in your graphics, then you should probably switch smooth on.

The background MouseArea covers the whole background and resets the object values.

Bemerkung

Elements which appear earlier in the code have a lower stacking order (called z-order). If you click long enough on circle you will see it moves below box. The z-order can also be manipulated by the z-property of an Item.

This is because box appears later in the code. The same applies also to mouse areas. A mouse area later in the code will overlap (and thus grab the mouse events) of a mouse area earlier in the code.

Please remember: The order of elements in the document matters.

Positionierungselemente¶

Es gibt eine Reihe von QML Elementen, die man zur Positionierung von anderen Elementen verwendet. Diese nennt man “positioner” und die folgenden Row, Column, Grid und Flow sind in QtQuick enthalten. In der nächsten Illustration kann man deren Wirkung an der Darstellung desselben Inhalts erkennen.

// RedSquare.qml

import QtQuick 2.5

Rectangle {
    width: 48
    height: 48
    color: "#ea7025"
    border.color: Qt.lighter(color)
}

Das Column-Element arrangiert die Kindelemente vertikal übereinander in einer Spalte. Die Eigenschaft spacing setzt die Abstände der Kindelemente untereinander.

// column.qml

import QtQuick 2.5

DarkSquare {
    id: root
    width: 120
    height: 240

    Column {
        id: row
        anchors.centerIn: parent
        spacing: 8
        RedSquare { }
        GreenSquare { width: 96 }
        BlueSquare { }
    }
}

Das Row-Element setzt die Kindelemente horizontal nebeneinander entweder von links nach rechts oder umgekehrt, abhängig von der Eigenschaft layoutDirection. Wieder wird spacing für die Abstände verwendet.

// row.qml

import QtQuick 2.5

BrightSquare {
    id: root
    width: 400; height: 120

    Row {
        id: row
        anchors.centerIn: parent
        spacing: 20
        BlueSquare { }
        GreenSquare { }
        RedSquare { }
    }
}

Das Grid-Element arrangiert die Kiner in einer Tabelle. Über die Eigenschaften rows und columns können Zeilen- und Spaltenanzahlen eingeschränkt werden. Wenn eines der Eigenschaften nicht gesetzt wird, wird es jeweils von der Anzahl der Kindelemente errechnet. Setzt man die Zeilenanzahl beispielsweise auf 3 und fügt 6 Kindelemente hinzu, werden daraus 2 Spalten. Die Eigenschaften flow und layoutDirection werden verwendet um die Reihenfolge der hinzugefügten Elemente zu steuern, während spacing die Größe der Zwischenabstände steuert.

// grid.qml

import QtQuick 2.5

BrightSquare {
    id: root
    width: 160
    height: 160

    Grid {
        id: grid
        rows: 2
        columns: 2
        anchors.centerIn: parent
        spacing: 8
        RedSquare { }
        RedSquare { }
        RedSquare { }
        RedSquare { }
    }

}

Der letzte Positionierer ist Flow. Es fügt Kindelemente in einem Fluss hinzu. Die Richtung des Flusses wird über flow und layoutDirection gesteuert. Dies kann seitlich oder von oben nach unten erfolgen. Es kann auch von links nach rechts oder umgekehrt erfolgen. Während Elemente im Fluss hinzugefügt werden, werden sie umgebrochen um neue Zeilen oder Spalten zu erzeugen, je nachdem was gebraucht wird. Damit ein Fluss funktionieren kann benötigt es eine Breite oder eine Höhe. Dies kann entweder direkt oder über Anker-Layouts gesetzt werden.

// flow.qml

import QtQuick 2.5

BrightSquare {
    id: root
    width: 160
    height: 160

    Flow {
        anchors.fill: parent
        anchors.margins: 20
        spacing: 20
        RedSquare { }
        BlueSquare { }
        GreenSquare { }
    }
}

Ein Element, das oft in Verbindung mit den Positionierern verwendet wird ist Repeater. Das funktioniert wie eine for-Schleife und iteriert über ein “Datenmodell”. Im einfachsten Fall ist das Modell einfach ein Wert, das die Anzahl der Schleifenwiederholungen angibt.

// repeater.qml

import QtQuick 2.5

DarkSquare {
    id: root
    width: 252
    height: 252
    property variant colorArray: ["#00bde3", "#67c111", "#ea7025"]


    Grid{
        anchors.fill: parent
        anchors.margins: 8
        spacing: 4
        Repeater {
            model: 16
            Rectangle {
                width: 56; height: 56
                property int colorIndex: Math.floor(Math.random()*3)
                color: root.colorArray[colorIndex]
                border.color: Qt.lighter(color)
                Text {
                    anchors.centerIn: parent
                    color: "#f0f0f0"
                    text: "Cell " + index
                }
            }
        }
    }
}

In diesem Repeater-Beispiel verwenden wir etwas Neumagisches. Wir definieren unsere eigene Farbeigenschaft, die wir als ein Feld von Farben verwenden. Der Repeater erzeugt eine Reihe von Rechtecken (16, wie vom Modell vorgegeben). In jeder Schleife erstellt er ein Rechteck, wie es im Kindelement (eigentlich: im Delegat) des Repeaters vordefiniert wird. Im Rechteck wählen wir die Farbe über die JS Mathematik Funktionen Math.floor(Math.random()*3). Dies ergibt eine Zahl im Bereich von 0..2, welche wir dann verwenden um eine Farbe aus unserem Farbfeld auszuwählen. Wie früher schon erklärt ist JavaScript Kernbestandteil von Qt Quick, daher sind dessen Standardbibliotheken auch für uns verfügbar.

Ein Repeater fügt die index-Eigenschaft hinzu. Diese Eigenschaft enthält den aktuellen Schleifendurchlauf (0,1,..15). Wir können diesen Index für unsere Entscheidungen verwenden oder in unserem Fall einfach nur um ihn mit Hilfe des Text-Elementes darzustellen.

Layout Elemente¶

QML bietet eine flexible Möglichkeit Elemente mit Hilfe von Fixpunkten (anchor = Anker) festzulegen. Das Konzept der Fixpunkte ist Teil der Basiseigenschaften eines Item-Elements und für alle sichtbaren QML Elemente verfügbar. Ein Fixpunkt wirkt wie ein Vertrag und ist stärker als andere konkurrierende Geometrieänderungen. Fixpunkte sind Ausdrücke der relativen Beziehungen, man braucht immer ein Element an das man etwas fixiert.

Ein Element hat 6 hauptsächliche fixierende Achsen (“top”, “bottom”, “left”, “right”, “horizontalCenter”, “verticalCenter”). Zusätzlich gibt es eine Achse (“baseline”) für Text in Text-Elementen. Jede der fixierenden Achesn hat einen offset. Im Fall von “top”, “bottom”, “left” und “right” werden sie “margins” genannt. Für “horizontalCenter”, “verticalCenter” und “baseline” werden sie “offsets” genannt.

1. Ein Element füllt ein Elternelement aus.

           GreenSquare {
               BlueSquare {
                   width: 12
                   anchors.fill: parent
                   anchors.margins: 8
                   text: '(1)'
               }
           }
   

2. in Element wird linksbündig am Elternelement ausgerichtet.

           GreenSquare {
               BlueSquare {
                   width: 48
                   y: 8
                   anchors.left: parent.left
                   anchors.leftMargin: 8
                   text: '(2)'
               }
           }
   

3. Eines Elementes linke Seite wird an des Elternelements rechter Seite ausgerichtet.

           GreenSquare {
               BlueSquare {
                   width: 48
                   anchors.left: parent.right
                   text: '(3)'
               }
           }
   

4. Mittig ausgerichtete Elemente. blue1 wird horizontal bezüglich des Elternelements zentriert. blue2 wird auch horizontal zentriert aber bezüglich blue1 und die Oberseite von blue2 wird an der Unterseite von blue1 ausgerichtet.

           GreenSquare {
               BlueSquare {
                   id: blue1
                   width: 48; height: 24
                   y: 8
                   anchors.horizontalCenter: parent.horizontalCenter
               }
               BlueSquare {
                   id: blue2
                   width: 72; height: 24
                   anchors.top: blue1.bottom
                   anchors.topMargin: 4
                   anchors.horizontalCenter: blue1.horizontalCenter
                   text: '(4)'
               }
           }
   

5. Ein Element wird zentriert bezüglich des Elternelements.

           GreenSquare {
               BlueSquare {
                   width: 48
                   anchors.centerIn: parent
                   text: '(5)'
               }
           }
   

6. Ein Element wird zentriert mit einem linken offset bezüglich des Elternelements und verwendet dabei die horizontalen und vertikalen Achsen.

           GreenSquare {
               BlueSquare {
                   width: 48
                   anchors.horizontalCenter: parent.horizontalCenter
                   anchors.horizontalCenterOffset: -12
                   anchors.verticalCenter: parent.verticalCenter
                   text: '(6)'
               }
           }
   

Input Elements¶

We have already used the MouseArea as a mouse input element. Next, we’ll focus on keyboard input. We start off with the text editing elements: TextInput and TextEdit.

TextInput¶

Issues: Create | View

The TextInput allows the user to enter a line of text. The element supports input constraints such as validator, inputMask, and echoMode.

// textinput.qml

import QtQuick 2.5

Rectangle {
    width: 200
    height: 80
    color: "linen"

    TextInput {
        id: input1
        x: 8; y: 8
        width: 96; height: 20
        focus: true
        text: "Text Input 1"
    }

    TextInput {
        id: input2
        x: 8; y: 36
        width: 96; height: 20
        text: "Text Input 2"
    }
}

The user can click inside a TextInput to change the focus. To support switching the focus by keyboard, we can use the KeyNavigation attached property.

// textinput2.qml

import QtQuick 2.5

Rectangle {
    width: 200
    height: 80
    color: "linen"

    TextInput {
        id: input1
        x: 8; y: 8
        width: 96; height: 20
        focus: true
        text: "Text Input 1"
        KeyNavigation.tab: input2
    }

    TextInput {
        id: input2
        x: 8; y: 36
        width: 96; height: 20
        text: "Text Input 2"
        KeyNavigation.tab: input1
    }
}

The KeyNavigation attached property supports a preset of navigation keys where an element id is bound to switch focus on the given key press.

A text input element comes with no visual presentation besides a blinking cursor and the entered text. For the user to be able to recognize the element as an input element it needs some visual decoration, for example a simple rectangle. When placing the TextInput inside an element you need make sure you export the major properties you want others be able to access.

We move this piece of code into our own component called TLineEditV1 for reuse.

// TLineEditV1.qml

import QtQuick 2.5

Rectangle {
    width: 96; height: input.height + 8
    color: "lightsteelblue"
    border.color: "gray"

    property alias text: input.text
    property alias input: input

    TextInput {
        id: input
        anchors.fill: parent
        anchors.margins: 4
        focus: true
    }
}

Bemerkung

If you want to export the TextInput completely, you can export the element by using property alias input: input. The first input is the property name, where the 2nd input is the element id.

We rewrite our KeyNavigation example with the new TLineEditV1 component.

Rectangle {
    ...
    TLineEditV1 {
        id: input1
        ...
    }
    TLineEditV1 {
        id: input2
        ...
    }
}

And try the tab key for navigation. You will experience the focus does not change to input2. The simple use of focus:true is not sufficient. The problem arises, that the focus was transferred to the input2 element the top-level item inside the TlineEditV1 (our Rectangle) received focus and did not forward the focus to the TextInput. To prevent this QML offers the FocusScope.

// TLineEditV2.qml

import QtQuick 2.5

FocusScope {
    width: 96; height: input.height + 8
    Rectangle {
        anchors.fill: parent
        color: "lightsteelblue"
        border.color: "gray"

    }

    property alias text: input.text
    property alias input: input

    TextInput {
        id: input
        anchors.fill: parent
        anchors.margins: 4
        focus: true
    }
}

Rectangle {
    ...
    TLineEditV2 {
        id: input1
        ...
    }
    TLineEditV2 {
        id: input2
        ...
    }
}

TextEdit¶

Issues: Create | View

The TextEdit is very similar to TextInput and support a multi-line text edit field. It doesn’t have the text constraint properties as this depends on querying the painted size of the text (paintedHeight, paintedWidth). We also create our own component called TTextEdit to provide a edit background and use the focus scope for better focus forwarding.

// TTextEdit.qml

import QtQuick 2.5

FocusScope {
    width: 96; height: 96
    Rectangle {
        anchors.fill: parent
        color: "lightsteelblue"
        border.color: "gray"

    }

    property alias text: input.text
    property alias input: input

    TextEdit {
        id: input
        anchors.fill: parent
        anchors.margins: 4
        focus: true
    }
}

You can use it like the TLineEdit component

// textedit.qml

import QtQuick 2.5

Rectangle {
    width: 136
    height: 120
    color: "linen"

    TTextEdit {
        id: input
        x: 8; y: 8
        width: 120; height: 104
        focus: true
        text: "Text Edit"
    }
}

Keys Element¶

Issues: Create | View

The attached property Keys allows executing code based on certain key presses. For example to move a square around and scale we can hook into the up, down, left and right keys to translate the element and the plus, minus key to scale the element.

// keys.qml

import QtQuick 2.5

DarkSquare {
    width: 400; height: 200

    GreenSquare {
        id: square
        x: 8; y: 8
    }
    focus: true
    Keys.onLeftPressed: square.x -= 8
    Keys.onRightPressed: square.x += 8
    Keys.onUpPressed: square.y -= 8
    Keys.onDownPressed: square.y += 8
    Keys.onPressed: {
        switch(event.key) {
            case Qt.Key_Plus:
                square.scale += 0.2
                break;
            case Qt.Key_Minus:
                square.scale -= 0.2
                break;
        }

    }
}

Advanced Techniques¶