Ein Buch über Qt5.¶

Worauf sich Qt 5 fokussiert¶

Qt 5 ist eine komplette Überarbeitung der schon sehr erfolgreichen Qt 4 Veröffentlichung. Mit Qt 4.8, das Qt 4 Release ist fast 7 Jahre alt. Zeit um die beeindruckende Werkzeugsammlung noch beeindruckender zu machen. Qt 5 fokussiert sich auf folgendes:

• Herausragende Grafik: Qt Quick 2 basiert auf OpenGL (ES) und nutzt eine scene graph Implementierung. Der Grafikstack erlaubt ein neues Level an Grafikeffekten, die zusammen mit der einfachen Nutzung bisland unerreicht sind.

• Developer Productivity: QML und JavaScript werden als die Hauptwerkzeuge für die UI Erstellung gesehen. Das Backend wird in C++ realisiert. Die Trennung zwischen JavaScript und C++ erlaubt schnellere Zyklen sowohl Fronend-Entwickler, die sich auf hübsche Userinterfaces, als auch für Backend-Entwickler, die sich auf Stabilität, Performanz und das Laufzeitverhalten konzentrieren.

• Cross-Plattform Portabilität: Über die konsolidiert Qt Plattform Abstraktion ist es jetzt möglich, Qt auf eine größere Anzahl an Plattformen zu portieren. Qt 5 ist um das Konzept von Qt Essentials und Qt Add-ons strukturiert, welches Betriebssystementwicklern erlaubt sich auf die notwendigen Module zu konzentrieren, was dann zu einer schnelleren Laufzeit führt.

• Open Development: Qt ist jetzt ein wirklich open-governance Projekt, das unter qt.io gehostet wird. Die Entwicklung steht offen und wird von einer Community vorangebracht.

Qt Quick¶

Qt Quick ist der Überbegriff für die Benutzerschnittstellentechnologie (oft Userinterface oder kurz UI genannt) in Qt 5. Qt Quick selbst ist eine Sammlung mehrerer Technologien:

• QML - Die Auszeichnungssprache für die Userinterfaces

• JavaScript - Die dynamische Skriptsprache

• Qt C++ - eine hoch portable erweiterte C++ Bibliothek

Genau wie HTML ist QML eine Auszeichnungssprache. Sie besteht aus “Tags”, die in Qt Quick “Elemente” in genannt werden und deren Eigenschaften durch geschweifte Klammern umschlossen werden Item { }. Es wurde von Grund auf für die Erstellung von Userinterfaces, Geschwindigkeit und einfacher Lesbarkeit für die Entwickler konzipiert. Das Userinterface kann dann durch JavaScript Code verbessert werden. Qt Quick ist zudem durch Qt C++ einfach mit nativer, eigener Funktionalität erweiterbar. Kurzum, das beschreibende UI wird das Frontend genannt und die nativen Teile werden Backend genannt. Das erlaubt es, rechenintensive und systemspezifische Operationen deiner Anwendung von der Benutzerschnittstellt zu trennen.

In einem typischen Projekt wird das Frontend mit QML/JavaSCript entwickelt und der Backend Code, welcher mit dem System interoperiert und die rechenintensiven Dinge macht wird mit Qt C++ entwickelt. Das erlaubt es eine natürliche Trennung zwischen den eher Design-orientierten Entwicklern und den funktionalen Entwicklern zu machen. Typischerweise wird das Backend mit Qt-eigenen Testframeworks getestet und dann für die Frontend-Entwickler zur Verfügung gestellt.

Wir wagen uns an ein Userinterface¶

Erstellen wir ein einfaches Userinterface mit Qt Quick, welches ein paar Eigenschaften der QML Sprache präsentieren soll. Am Ende haben wir eine Papierwindmühle mit sich drehenden Rotorblättern.

Wir starten mit einem leeren Dokument, das wir main.qml nennen. Alle QML-Dateien bekommen die Endung .qml. Als Auszeichnungssprache (ebenso wie HTML) braucht ein QML-Dokument genau ein Wurzelelement, welches in unserem Beispiel das Image-Element mit einer Breite und einer Höhe sein wird, die auf der Geometrie des als Hintergrund verwendeten Bildes basiert:

import QtQuick 2.5

Image {
    id: root
    source: "images/background.png"
}

Weil QML keine Einschränkungen macht, welches Element die Wurzel darstellt, verwenden wir das Image-Element als Wurzel, für das wir die source-Eigenschaft auf das Hintergrundbild setzen.

Die Elemente Stab und Windrad im Vordergrund unseres Userintefaces werde als eigene Bilder platziert.

Der Stab muss horizontal mittig unten platziert werden und das Windrad kann in der Bildmitte des Hintergrunds erscheinen.

Normalerweise besteht dein Userinterface aus vielen verschiedenen Elementtypen und nicht nur aus image-Elementen wie in diesem Beispiel.

Image {
    id: root
    ...
    Image {
        id: pole
        anchors.horizontalCenter: parent.horizontalCenter
        anchors.bottom: parent.bottom
        source: "images/pole.png"
    }

    Image {
        id: wheel
        anchors.centerIn: parent
        source: "images/pinwheel.png"
    }
    ...
}

Um das Windrad mittig zu plazieren verwenden wir eine komplexe Eigenschaft mit dem Namen anchor (“Anker”). Das Verankern erlaubt dir eine geometrische Beziehung zwischen Eltern- und Geschwisterobjekten festzulegen. Beispielsweise bedeutet anchors.centerIn: parent “plaziere mich im Zentrum des Elternelements. Es gibt die Beziehungen “left”, “right”, “top”, “bottom”, “centerIn”, “fill”, “verticalCenter” und “horizontalCenter” auf beiden Seiten. Natürlich müssen diese zusammenpassen. Es ergibt keinen Sinn meine linke Seite an der Oberseite eines anderen Elements zu verankern.

So setzen wir das Windrad mittig auf den Hintergrund des Elternelements.

Um dieses Beispielprojekt ein bisschen interessanter zu gestalten, wollen wir die Szene interaktiv machen. Die Idee ist, dass das Rad sich dreht, wenn der Benutzer mit der Maus irgendwo in der Szene klickt.

Wir verwenden das MouseArea Element und machen es so groß wie unser Wurzelelement.

Image {
    id: root
    ...
    MouseArea {
        anchors.fill: parent
        onClicked: wheel.rotation += 90
    }
    ...
}

Die Mausfläche sendet ein Signal sobald der Benutzer innerhalb der bedeckten Fläche klickt. Man kann sich in dieses Signal einklinken, indem man die onClicked Funktion überschreibt. In diesem Fall binden daran das Bild des Rades und ändern dessen Drehung um +90 Grad.

Jetzt wird sich das Rad drehen, aber das funktioniert noch nicht flüssig. Die Drehung ändert sich sofort. Wir hätten aber lieber, dass sich die Eigenschaft mit der Zeit um 90 Grad ändert. Hier kommen Animationen ins Spiel. Eine Animation definiert wie sich eine Eigenschaft ändert über eine gewisse Zeitspanne. Dafür verwenden wir einen Animationstyp mit dem Namen Behaviour`. Dieses Verhalten einer Eigenschaft gibt genau an, wie die zugehörige Eigenschaft animiert werden soll, wenn eine Änderung für diese Eigenschaft ansteht. Kurz gesagt, sobald sich die Eigenschaft ändert, läuft die Animation los. Das ist nur eine von mehreren Möglichkeiten, eine Animation in QML zu definieren.

Image {
    id: root
    Image {
        id: wheel
        Behavior on rotation {
            NumberAnimation {
                duration: 250
            }
        }
    }
}

Immer wenn sich die Drehungseigenschaft des Rades ändert, wird dies über NumberAnimation animiert mit einer Dauer von 250ms, also wird jede 90 Grad-Drehung 250ms dauern.

Jetzt sieht das Rad viel besser aus. Ich hoffe, dieses Beispiel hat dir ein bisschen geholfen, die Programmierung mit Qt Quick zu verstehen.

Qt Module¶

Die “Qt Essentials” Module sind notwendig für eine auf Qt basierende Plattform. Sie bieten die Grundlage um eine moderne Qt 5 Anwendung mit Hilfe von Qt Quick 2 zu entwickeln.

Die “Core-Essential” Module

Eine minimale Sammlung von Qt 5 Modulen um mit QML zu programmieren.

Qt Addon Module

Neben den wichtigen Modulen bietet Qt zusätzliche Module für Softwareentwickler, die nicht Teil der Veröffentlichung sind. Hier ist eine kurze Liste von verfügbaren Addon Modulen.

• Qt 3D - Eine Menge von APIs um graphische 3D Programmierung einfach und beschreibend zu machen.

• Qt Bluetooth - C++ und QML APIs für Plattformen, die Bluetooth Technologie verwenden.

• Qt Contacts - C++ und QML APIs um Adressbücher und Kontaktdatenbanken anzusprechen.

• Qt Location - Erlaubt die Posititionierung, Kartierung, Navigation und Ortssuche über QML und eine C++ Schnittstelle. Es wird ein NMEA backend für die Positionierung verwendet.

• Qt Organizer - C++ und QML APIs um auf eine persönliche Informationsverwaltung (Organizer, Todos, Veranstaltungen, etc.) zuzugreifen.

• Qt Publish and Subscribe

• Qt Sensors - Zugriff auf Sensoren über ein QML und C++ Interface.

• Qt Service Framework - Anwendungen sollen Zugriff auf Änderungsnachrichten lesbar, navigierbar und abonnierbar haben.

• Qt System Info - Entdecke systembezogene Informationen und Fähigkeiten.

• Qt Versit - Unterstützung für vCard und iCalender Formate.

• Qt Wayland - Nur unter Linux. Enthält eine Qt Compositor API (server) und Wayland Plattform Plugins (clients).

• Qt Feedback - Fühlbare und Audio-Rückkopplung auf Benutzeraktionen.

• Qt JSON DB - Ein no-SQL Objektspeicher für Qt.

Unterstützte Plattformen¶

Qt unterstützt eine Reihe von Plattformen. Alle größeren Desktops und eingebettete Systeme werde unterstützt. Über die Abstraktion einer Qt Anwendung ist es heutzutage einfacher wenn nötig eine Qt auf deine eigene Plattform zu portieren.

Das Testen von Qt 5 auf einer Plattform ist zeitraubend. Eine Untermenge wurde vom Qt Projekt ausgesucht und bildet die Menge an Referenzplattformen. Diese Referenzplattformen wurden ausgiebig getestet um beste Qualität zu garantieren. Aber Vorsicht: kein Code ist fehlerfrei.

Console Application¶

A console application does not provide any graphical user interface and will normally be called as part of a system service or from the command line. Qt 5 comes with a series of ready-made components which help you to create console cross platform applications very efficiently. For example the networking file APIs. Also string handling and, since Qt 5.1, efficient command line parser. As Qt is a high-level API on top of C++, you get programming speed paired with execution speed. Don’t think of Qt as being just a UI toolkit – it has so much more to offer.

String Handling

In the first example we demonstrate how someone could very simply add 2 constant strings. This is not a very useful application but it gives you an idea of what a native C++ application, without an event loop, could look like.

// module or class includes
#include <QtCore>

// text stream is text-codec aware
QTextStream cout(stdout, QIODevice::WriteOnly);

int main(int argc, char** argv)
{
    // avoid compiler warnings
    Q_UNUSED(argc)
    Q_UNUSED(argv)
    QString s1("Paris");
    QString s2("London");
    // string concatenation
    QString s = s1 + " " + s2 + "!";
    cout << s << endl;
}

Container Classes

This example adds a list and list iteration to the application. Qt comes with a large collections of container classes which are easy to use and use the same API paradigms as the rest of Qt classes.

QString s1("Hello");
QString s2("Qt");
QList<QString> list;
// stream into containers
list <<  s1 << s2;
// Java and STL like iterators
QListIterator<QString> iter(list);
while(iter.hasNext()) {
    cout << iter.next();
    if(iter.hasNext()) {
        cout << " ";
    }
}
cout << "!" << endl;

Here we show some advanced list function, which allow you to join a list of strings into one string. This is very handy when you need to proceed line based text input. The inverse (string to string-list) is also possible using QString::split() function.

QString s1("Hello");
QString s2("Qt");
// convenient container classes
QStringList list;
list <<  s1 << s2;
// join strings
QString s = list.join(" ") + "!";
cout << s << endl;

File IO

In the next snippet we read a CSV file from the local directory and loop over the rows to extract the cells from each row. Doing this we get the table data from the CSV file in ca. 20 lines of code. File reading gives us just a byte stream, to be able to convert it into a valid Unicode text we need to use the text stream and pass in the file as a lower-level stream. For writing CSV files you would just need to open the file in the write mode and pipe the lines into the text stream.

QList<QStringList> data;
// file operations
QFile file("sample.csv");
if(file.open(QIODevice::ReadOnly)) {
    QTextStream stream(&file);
    // loop forever macro
    forever {
        QString line = stream.readLine();
        // test for null string 'String()'
        if(line.isNull()) {
            break;
        }
        // test for empty string 'QString("")'
        if(line.isEmpty()) {
            continue;
        }
        QStringList row;
        // for each loop to iterate over containers
        foreach(const QString& cell, line.split(",")) {
            row.append(cell.trimmed());
        }
        data.append(row);
    }
}
// No cleanup necessary.

This concludes our section about console based application with Qt.

Widget Application¶

Console based applications are very handy but sometimes you need to have a UI to show. In addition, UI-based applications will likely need a back-end to read/write files, communicate over the network, or keep data in a container.

In this first snippet for widget-based applications we do as little as needed to create a window and show it. A widget without a parent in the Qt world is a window. We use the scoped pointer to ensure the widget is deleted when the scoped pointer goes out of scope. The application object encapsulates the Qt runtime and with the exec() call we start the event loop. From there on the application reacts only on events triggered by mouse or keyboard or other event providers like networking or file IO. The application will only exit when the event loop is exited. This is done by calling quit() on the application or by closing the window.

When you run the code you will see a window with the size of 240 x 120 pixel. That’s all.

#include <QtGui>

int main(int argc, char** argv)
{
    QApplication app(argc, argv);
    QScopedPointer<QWidget> widget(new CustomWidget());
    widget->resize(240, 120);
    widget->show();
    return app.exec();
}

Custom Widgets

When you work on user interfaces, you will need to create custom made widgets. Typically a widget is a window area filled with painting calls. Additional the widget has internal knowledge of how to handle keyboard or mouse input and how to react to external triggers. To do this in Qt we need to derive from QWidget and overwrite several functions for painting and event handling.

#ifndef CUSTOMWIDGET_H
#define CUSTOMWIDGET_H

#include <QtWidgets>

class CustomWidget : public QWidget
{
    Q_OBJECT
public:
    explicit CustomWidget(QWidget *parent = 0);
    void paintEvent(QPaintEvent *event);
    void mousePressEvent(QMouseEvent *event);
    void mouseMoveEvent(QMouseEvent *event);
private:
    QPoint m_lastPos;
};

#endif // CUSTOMWIDGET_H

In the implementation, we draw a small border on our widget and a small rectangle on the last mouse position. This is very typical for a low-level custom widget. Mouse or keyboard events change the internal state of the widget and trigger a painting update. We don’t want to go into to much detail into this code, but it is good to know that you have the ability. Qt comes with a large set of ready-made desktop widgets, so that the probability is high that you don’t have to do this.

#include "customwidget.h"

CustomWidget::CustomWidget(QWidget *parent) :
    QWidget(parent)
{
}

void CustomWidget::paintEvent(QPaintEvent *)
{
    QPainter painter(this);
    QRect r1 = rect().adjusted(10,10,-10,-10);
    painter.setPen(QColor("#33B5E5"));
    painter.drawRect(r1);

    QRect r2(QPoint(0,0),QSize(40,40));
    if(m_lastPos.isNull()) {
        r2.moveCenter(r1.center());
    } else {
        r2.moveCenter(m_lastPos);
    }
    painter.fillRect(r2, QColor("#FFBB33"));
}

void CustomWidget::mousePressEvent(QMouseEvent *event)
{
    m_lastPos = event->pos();
    update();
}

void CustomWidget::mouseMoveEvent(QMouseEvent *event)
{
    m_lastPos = event->pos();
    update();
}

Desktop Widgets

The Qt developers have done all of this for you already and provide a set of desktop widgets, which will look native on different operating systems. Your job is then to arrange these different widgets in a widget container into larger panels. A widget in Qt can also be a container for other widgets. This is accomplished by the parent-child relationship. This mean we need to make our ready-made widgets like buttons, check boxes, radio button but also lists and grids a child of another widget. One way to accomplish this is displayed below.

Here is the header file for a so called widget container.

class CustomWidget : public QWidget
{
    Q_OBJECT
public:
    explicit CustomWidget(QWidget *parent = 0);
private slots:
    void itemClicked(QListWidgetItem* item);
    void updateItem();
private:
    QListWidget *m_widget;
    QLineEdit *m_edit;
    QPushButton *m_button;
};

In the implementation, we use layouts to better arrange our widgets. Layout managers re-layout the widgets according to some size policies when the container widget is re-sized. In this example we have a list, a line edit, and a button arranged vertically to allow to edit a list of cities. We use Qt’s signal and slots to connect sender and receiver objects.

CustomWidget::CustomWidget(QWidget *parent) :
    QWidget(parent)
{
    QVBoxLayout *layout = new QVBoxLayout(this);
    m_widget = new QListWidget(this);
    layout->addWidget(m_widget);

    m_edit = new QLineEdit(this);
    layout->addWidget(m_edit);

    m_button = new QPushButton("Quit", this);
    layout->addWidget(m_button);
    setLayout(layout);

    QStringList cities;
    cities << "Paris" << "London" << "Munich";
    foreach(const QString& city, cities) {
        m_widget->addItem(city);
    }

    connect(m_widget, SIGNAL(itemClicked(QListWidgetItem*)), this, SLOT(itemClicked(QListWidgetItem*)));
    connect(m_edit, SIGNAL(editingFinished()), this, SLOT(updateItem()));
    connect(m_button, SIGNAL(clicked()), qApp, SLOT(quit()));
}

void CustomWidget::itemClicked(QListWidgetItem *item)
{
    Q_ASSERT(item);
    m_edit->setText(item->text());
}

void CustomWidget::updateItem()
{
    QListWidgetItem* item = m_widget->currentItem();
    if(item) {
        item->setText(m_edit->text());
    }
}

Drawing Shapes

Some problems are better visualized. If the problem at hand looks faintly like geometrical objects, qt graphics view is a good candidate. A graphics view arranges simple geometrical shapes on a scene. The user can interact with these shapes or they are positioned using an algorithm. To populate a graphics view you need a graphics view and a graphics scene. The scene is attached to the view and populates with graphics items. Here is a short example. First the header file with the declaration of the view and scene.

class CustomWidgetV2 : public QWidget
{
    Q_OBJECT
public:
    explicit CustomWidgetV2(QWidget *parent = 0);
private:
    QGraphicsView *m_view;
    QGraphicsScene *m_scene;

};

In the implementation the scene gets attached to the view first. The view is a widget and get arranged in our container widget. At the end we add a small rectangle to the scene, which then is rendered on the view.

#include "customwidgetv2.h"

CustomWidget::CustomWidget(QWidget *parent) :
    QWidget(parent)
{
    m_view = new QGraphicsView(this);
    m_scene = new QGraphicsScene(this);
    m_view->setScene(m_scene);

    QVBoxLayout *layout = new QVBoxLayout(this);
    layout->setMargin(0);
    layout->addWidget(m_view);
    setLayout(layout);

    QGraphicsItem* rect1 = m_scene->addRect(0,0, 40, 40, Qt::NoPen, QColor("#FFBB33"));
    rect1->setFlags(QGraphicsItem::ItemIsFocusable|QGraphicsItem::ItemIsMovable);
}

Adapting Data¶

Up to now we have mostly covered basic data types and how to use widgets and graphic views. Often in your application you will need larger amount of structured data, which also has to be persistently stored. The data also needs to be displayed. For this Qt uses models. A simple model is the string list model, which gets filled with strings and then attached to a list view.

m_view = new QListView(this);
m_model = new QStringListModel(this);
view->setModel(m_model);

QList<QString> cities;
cities << "Munich" << "Paris" << "London";
model->setStringList(cities);

Another popular way to store or retrieve data is SQL. Qt comes with SQLite embedded and also has support for other database engines (MySQL, PostgresSQL, ...). First you need to create your database using a schema, like this:

CREATE TABLE city (name TEXT, country TEXT);
INSERT INTO city value ("Munich", "Germany");
INSERT INTO city value ("Paris", "France");
INSERT INTO city value ("London", "United Kingdom");

To use sql we need to add the sql module to our .pro file

QT += sql

And then we can open our database using C++. First we need to retrieve a new database object for the specified database engine. With this database object we open the database. For SQLite it’s enough to specify the path to the database file. Qt provides some high-level database model, one of them is the table model, which uses a table identifier and an option where clause to select the data. The resulting model can be attached to a list view as the other model before.

QSqlDatabase db = QSqlDatabase::addDatabase("QSQLITE");
db.setDatabaseName('cities.db');
if(!db.open()) {
    qFatal("unable to open database");
}

m_model = QSqlTableModel(this);
m_model->setTable("city");
m_model->setHeaderData(0, Qt::Horizontal, "City");
m_model->setHeaderData(1, Qt::Horizontal, "Country");

view->setModel(m_model);
m_model->select();

For higher level of model operations Qt provides a sort file proxy model, which allows you in the basic form to sort and filter another model.

QSortFilterProxyModel* proxy = new QSortFilterProxyModel(this);
proxy->setSourceModel(m_model);
view->setModel(proxy);
view->setSortingEnabled(true);

Filtering is done based on the column to be filters and a string as filter argument.

proxy->setFilterKeyColumn(0);
proxy->setFilterCaseSensitive(Qt::CaseInsensitive);
proxy->setFilterFixedString(QString)

The filter proxy model is much more powerful than demonstrated here. For now it is enough to remember its exists.

Qt Quick Application¶

There is an inherent conflict in modern software development. The user interface is moving much faster than our back-end services. In a traditional technology you develop the so called front-end at the same pace as the back-end. This results in conflicts when customers want to change the user interface during a project, or develop the idea of an user interface during the project. Agile projects, require agile methods.

Qt Quick provides a declarative environment where your user interface (the front-end) is declared like HTML and your back-end is in native C++ code. This allows you to get the best of both worlds.

This is a simple Qt Quick UI below

import QtQuick 2.5

Rectangle {
    width: 240; height: 1230
    Rectangle {
        width: 40; height: 40
        anchors.centerIn: parent
        color: '#FFBB33'
    }
}

The declaration language is called QML and it needs a runtime to execute in. Qt provides a standard runtime called qmlscene but it’s also not so difficult to write a custom runtime. For this we need a quick view and set the main QML document as source. The only thing left is to show the user interface.

QQuickView* view = new QQuickView();
QUrl source = QUrl::fromLocalFile("main.qml");
view->setSource(source);
view.show();

Coming back to our earlier examples. In one example we used a C++ city model. It would be great if we could use this model inside our declarative QML code.

To enable this, we first code our front-end to see how we would want to use a city model. In this case the front-end expects a object named cityModel which we can use inside a list view.

import QtQuick 2.5

Rectangle {
    width: 240; height: 120
    ListView {
        width: 180; height: 120
        anchors.centerIn: parent
        model: cityModel
        delegate: Text { text: model.city }
    }
}

To enable the cityModel we can mostly re-use our previous model and add a context property to our root context (the root context is the other root-element in the main document)

m_model = QSqlTableModel(this);
... // some magic code
QHash<int, QByteArray> roles;
roles[Qt::UserRole+1] = "city";
roles[Qt::UserRole+2] = "country";
m_model->setRoleNames(roles);
view->rootContext()->setContextProperty("cityModel", m_model);

Eigenschaften¶

Elemente werden über deren Elementname deklariert, aber erst die Benutzung der Eigenschaften oder durch selbst erstellte Eigenschaften sind Elemente richtig definiert. Eine Eigenschaft ist eine einfaches Schlüssel-Wert Paar, z.B. width : 100, text: 'Hallo' oder color: '#FF0000'. Eine Eigenschaft hat einen wohldefinierten Datentyp und kann einen Initialwert zugewiesen bekommen (Im Beispiel jeweils die rechte Seite).

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

Schauen wir uns die verschiedenen Eigenheiten von Eigenschaften an:

1. id ist ein sehr spezieller Wert mit dem man innerhalb einer QML-Datei (“document”) genau ein Element ansteuern (“referenzieren”) kann. Die id ist nicht vom Typ einer Zeichenkette sondern ein Bezeichner und Teil der QML Syntax. Eine id muss einmalig in einem Dokument sein und ihm kann nicht ein anderer Wert zugewiesen werden, noch kann nach ihm gesucht werden. (Es benimmt sich eher wie ein Zeiger aus der C++-Welt).

2. Eine Eigenschaft kann auf einen Wert gesetzt werden, abhängig von seinem Datentyp. Wenn kein Wert für eine Eigenschaft vergeben wurde, wird vom System ein erstmaliger Wert gewählt. Man muss die Dokumentation des jeweiligen Elements anschauen um diesen Initialwert herauszubekommen.

3. Eine Eigenschaft kann von einer oder vielen anderen Eigenschaften abhängen. Das nennt man binding (“Bindung”). Eine gebundene Eigenschaft wird immer aktualisiert wenn sich die andere Eigenschaft (von der der Wert abhängt) ändert. Man kann es sich wie einen Vertrag vorstellen, in diesem Beispiel ist die Höhe height immer zwei mal der Breite width.

4. Eigene Eigenschaft kann man zu einem Element hinzufügen in dem man den Bezeichner property gefolgt von dem Datentyp, dem Namen der Eigenschaft und - wenn man will - einem initialen Wert verwendet (property <type> <name> : <value>). Falls kein Wert angegeben wird, wählt das System einen.

   Bemerkung

   You can also declare one property to be the default property if no property name is given by prepending the property declaration with the default keyword. This is used for example when you add child elements, the child elements are added automatically to the default property children of type list if they are visible elements.

5. Eine weitere Möglichkeit, Eigenschaften zu definieren ist über das Schlüsselwort alias (property alias <name> : <reference>). Das alias Schlüsselwort erlaubt uns eine Eigenschaft eines anderen Elements oder ein Element selbst weiterzuleiten, d.h. hier verwendbar zu machen. Wir werden diese Technik später nutzen, wenn wir Komponenten definiteren, die innere Eigenschaften besitzen, die wir aber im Wurzelelement verwenden wollen. Ein property alias braucht keinen Typ, denn es verwendet den Typ der Referenzeigenschaft oder des Referenzelements.

6. Die text-Eigenschaft hängt hier von der erfundenen Eigenschaft times ab, welche vom Typ int (Ganzzahl) ist. Der int-Wert wird dann automatisch in einen string-Typ konvertiert. Der Ausdruck ist ein Beispiel einer Bindung und hat zur Folge, dass immer automatisch wenn times sich ändert, der Text geändert wird.

7. Einige Eigenschaften können gruppiert werden. Dieses Feature wird verwendet, wenn eine Eigenschaft strukturiert werden soll und verwandte Eigenschaften gruppiert werden sollen. Gruppen von Eigenschaften kann man auch so schreiben: font { family:  "Ubuntu"; pixelSize: 24 }.

8. Einige Eigenschaften sind an ein Element geheftetet. Das macht man für globale Elemente, die nur einmalig in der Applikation vorkommen (z.B: Tastatureingaben). Die Syntax dazu ist <Element>.<property>: <value>.

9. Für jede Eigenschaft kann man signal handler zur Verfügung stellen. Diese Funktion wird dann aufgerufen, sobald die Eigenschaft sich ändert. Hier beispielsweise wird man über die eingebaute Funktion console.log immer dann informiert, wenn sich de Höhe ändert.

Mit Skripten programmieren¶

QML und JavaScript (eigentlich offiziell “ECMAScript”) passen bestens zusammen. Im Kapitel JavaScript werden wir zu dieser Symbiose mehr ins Detail gehen. An dieser Stelle wollen wir bloß mal auf diese Beziehung aufmerksam machen.

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

1. Der Handler, der bei Textänderungen aufgerufen wird, onTextChanged gibt den aktuellen Text jedes Mal dann aus, wenn der Text durch ein Betätigen der Leertaste geändert wurde.

2. Immer wenn das Textelement die Leertaste empfängt (weil der Benutzer eben die Tastatur bedient hat) rufen wir die JavaScript funktion increment() auf.

3. Die Definition der JavaScript Funktion in der Form function () { ... }, die unseren Zähler spacePressed erhöht. Jedes Mal wenn spacePressed erhöht wird, werden auch die angebundenen Eigenschaften aktualisiert.

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

Das Item Element¶

Item ist das Basiselement für alle visuellen Elemente weil alle anderen visuellen Elemente von ihm abstammen. Es zeichnet zunächst nichts selbst auf den Schirm, aber es definiert Eigenschaften, die für alle visuellen Elemente gelten:

Um die verschiedenen Eigenschaften besser zu verstehen, werden wir sie im Zusammenhang mit einem Element genauer vorstellen. Merke dir, dass dieses Basiseigenschaften in jedem sichtbaren Element vorhanden sind und überall dort gleich funktionieren.

Das Rectangle Element¶

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
    }

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.

Das Text Element¶

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.

Das Image-Element¶

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
    }

Das MouseArea Element¶

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
    }

TextInput¶

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

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.

FocusScope¶

A focus scope declares that the last child element with focus:true receives the focus if the focus scope receives the focus. So it’s forward the focus to the last focus requesting child element. We will create a 2nd version of our TLineEdit component called TLineEditV2 using the focus scope as root element.

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

Our example will now look like this:

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

Pressing the tab key now successfully switches the focus between the 2 components and the correct child element inside the component is focused.

TextEdit¶

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¶

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

    }
}

Animation Elements¶

There are several types of animation elements, each optimized for a specific use case. Here is a list of the most prominent animations:

• PropertyAnimation - Animates changes in property values
• NumberAnimation - Animates changes in qreal-type values
• ColorAnimation - Animates changes in color values
• RotationAnimation - Animates changes in rotation values

Besides these basic and widely used animation elements, Qt Quick provides also more specialized animations for specific use cases:

• PauseAnimation - Provides a pause for an animation
• SequentialAnimation - Allows animations to be run sequentially
• ParallelAnimation - Allows animations to be run in parallel
• AnchorAnimation - Animates changes in anchor values
• ParentAnimation - Animates changes in parent values
• SmoothedAnimation - Allows a property to smoothly track a value
• SpringAnimation - Allows a property to track a value in a spring-like motion
• PathAnimation - Animates an item along a path
• Vector3dAnimation - Animates changes in QVector3d values

We will learn later how to create a sequence of animations. While working on more complex animations there comes up the need to change a property or to run a script during an an ongoing animation. For this Qt Quick offers the action elements, which can be used everywhere where the other animation elements can be used:

• PropertyAction - Specifies immediate property changes during animation
• ScriptAction - Defines scripts to be run during an animation

The major animation types will be discussed during this chapter using small focused examples.

Applying Animations¶

Animation can be applied in several ways:

• Animation on property - runs automatically after element is fully loaded
• Behavior on property - runs automatically when the property value changes
• Standalone Animation - runs when animation is explicitly started using start() or running is set to true (e.g. by a property binding)

Later we see also how animations can be used inside state transitions.

// ClickableImageV2.qml
// Simple image which can be clicked

import QtQuick 2.5

Item {
    id: root
    width: container.childrenRect.width
    height: container.childrenRect.height
    property alias text: label.text
    property alias source: image.source
    signal clicked

    Column {
        id: container
        Image {
            id: image
        }
        Text {
            id: label
            width: image.width
            horizontalAlignment: Text.AlignHCenter
            wrapMode: Text.WordWrap
            color: "#ececec"
        }
    }

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

The objects ascending.

The three objects are all at the same y-position (y=200). They need to travel all to y=40. Each of them using a different method with different side-effects and features.

    ClickableImageV2 {
        id: greenBox
        x: 40; y: root.height-height
        source: "assets/box_green.png"
        text: "animation on property"
        NumberAnimation on y {
            to: 40; duration: 4000
        }
    }

1st object

The 1st object travels using the Animation on <property> strategy. The animation starts immediately. When an object is clicked their y-position is reset to the start position, this applies to all objects. On the 1st object the reset does not have any effect as long as the animation is running. It’s even disturbing as the y-position is set for a fraction of a second to a new value before the animation starts. Such competing property changes should be avoided.

    ClickableImageV2 {
        id: blueBox
        x: (root.width-width)/2; y: root.height-height
        source: "assets/box_blue.png"
        text: "behavior on property"
        Behavior on y {
            NumberAnimation { duration: 4000 }
        }

        onClicked: y = 40
        // random y on each click
//        onClicked: y = 40+Math.random()*(205-40)
    }

2nd object

The 2nd object travels using a behavior on animation. This behavior tells the property, every time the property value changes, it changes through this animation. The behavior can be disabled by enabled : false on the Behavior element. The object will start traveling when you click it (y-position is then set to 40). Another click has no influence as the position is already set. You could try to use a random value (e.g. 40+(Math.random()*(205-40)) for the y-position. You will see that the object will always animate to the new position and adapt its speed to match the 4 seconds to the destination defined by the animations duration.

    ClickableImageV2 {
        id: redBox
        x: root.width-width-40; y: root.height-height
        source: "assets/box_red.png"
        onClicked: anim.start()
//        onClicked: anim.restart()

        text: "standalone animation"

        NumberAnimation {
            id: anim
            target: redBox
            properties: "y"
            to: 40
            duration: 4000
        }
    }

3rd object

The 3rd object uses a standalone animation. The animation is defined as its own element and could be everywhere in the document. The click will start the animation using the animations function start(). Each animation has a start(), stop(), resume(), restart() function. The animation itself contains much more information then the other animation types earlier. We need to define the target and properties to declare the target element to be animated and which properties we want to animate. We need to define a to value and in this case we define also a from value to allow a re-start of the animation.

A click on the background will reset all objects to their initial position. The 1st object can’t be restarted except by re-starting the program which triggers the re-loading of the element.

NumberAnimation {
    ...
    // animation runs when mouse is pressed
    running: area.pressed
}
MouseArea {
    id: area
}

Easing Curves¶

The value change of a property can be controlled by an animation. Easing attributes allows influencing the interpolation curve of a property change. All animations we have defined by now use a linear interpolation because the initial easing type of an animation is Easing.Linear. It’s best visualized with a small plot, where the y-axis is the property to be animated and the x-axis is the time (duration). A linear interpolation would draw a straight line from the from value at the start of the animation to the to value at the end of the animation. So the easing type defines the curve of change. Easing types are carefully chosen to support a natural fit for a moving object, for example when a page slides out. Initially the page should slide out slowly and then gaining the speed to finally slide out on high speed, similar to turning the page of a book.

In the next example we will try some easing curves. Each easing curve is displayed by a click-able image and, when clicked, will set a new easing type on the square animation and then trigger a restart() to run the animation with the new curve.

The code for this example was made a little bit more complicated.We first create a grid of EasingTypes and a Box which is controlled by the easing types. A easing type just displays the curve which the box shall use for its animation. When the user clicks on an easing curve the box moves in a direction according to the easing curve. The animation itself is a standalone-animation with the target set to the box and configured for x-property animation with a duration of 2 secs.

// EasingCurves.qml

import QtQuick 2.5
import QtQuick.Layouts 1.2

Rectangle {
    id: root
    width: childrenRect.width
    height: childrenRect.height

    color: '#4a4a4a'
    gradient: Gradient {
        GradientStop { position: 0.0; color: root.color }
        GradientStop { position: 1.0; color: Qt.lighter(root.color, 1.2) }
    }

    ColumnLayout {

        Grid {
            spacing: 8
            columns: 5
            EasingType {
                easingType: Easing.Linear
                title: 'Linear'
                onClicked: {
                    animation.easing.type = easingType
                    box.toggle = !box.toggle
                }
            }
            EasingType {
                easingType: Easing.InExpo
                title: "InExpo"
                onClicked: {
                    animation.easing.type = easingType
                    box.toggle = !box.toggle
                }
            }
            EasingType {
                easingType: Easing.OutExpo
                title: "OutExpo"
                onClicked: {
                    animation.easing.type = easingType
                    box.toggle = !box.toggle
                }
            }
            EasingType {
                easingType: Easing.InOutExpo
                title: "InOutExpo"
                onClicked: {
                    animation.easing.type = easingType
                    box.toggle = !box.toggle
                }
            }
            EasingType {
                easingType: Easing.InOutCubic
                title: "InOutCubic"
                onClicked: {
                    animation.easing.type = easingType
                    box.toggle = !box.toggle
                }
            }
            EasingType {
                easingType: Easing.SineCurve
                title: "SineCurve"
                onClicked: {
                    animation.easing.type = easingType
                    box.toggle = !box.toggle
                }
            }
            EasingType {
                easingType: Easing.InOutCirc
                title: "InOutCirc"
                onClicked: {
                    animation.easing.type = easingType
                    box.toggle = !box.toggle
                }
            }
            EasingType {
                easingType: Easing.InOutElastic
                title: "InOutElastic"
                onClicked: {
                    animation.easing.type = easingType
                    box.toggle = !box.toggle
                }
            }
            EasingType {
                easingType: Easing.InOutBack
                title: "InOutBack"
                onClicked: {
                    animation.easing.type = easingType
                    box.toggle = !box.toggle
                }
            }
            EasingType {
                easingType: Easing.InOutBounce
                title: "InOutBounce"
                onClicked: {
                    animation.easing.type = easingType
                    box.toggle = !box.toggle
                }
            }
        }
        Item {
            height: 80
            Layout.fillWidth: true
            Box {
                id: box
                property bool toggle
                x: toggle?20:root.width-width-20
                anchors.verticalCenter: parent.verticalCenter
                gradient: Gradient {
                    GradientStop { position: 0.0; color: "#2ed5fa" }
                    GradientStop { position: 1.0; color: "#2467ec" }
                }
                Behavior on x {
                    NumberAnimation {
                        id: animation
                        duration: 500
                    }
                }
            }
        }
    }
}

A you play with it, please observe the change of speed during an animation. Some animations feel more natural for the object and some feel irritating.

Besides the duration and easing.type you are able to fine tune animations. For example the general PropertyAnimation where most animation inherit from additionally supports an easing.amplitude, easing.overshoot and easing.period property which allows you to fine-tune the behavior of particular easing curves. Not all easing curves support these parameters. Please consult the easing table from the PropertyAnimation documentation to check if an easing parameter has influence on an easing curve.

Grouped Animations¶

Often animations will be more complex then just animating one property. You might want to run several animations at the same time or one after another or even execute a script between two animations. For this, the grouped animation offer you a possibility. As the named suggests it’s possible to group animations. Grouping can be done in two ways: parallel or sequential. You can use the SequentialAnimation or the ParallelAnimation element, which act as animation containers for other animation elements. These grouped animations are animations themselves and can be used exactly as such.

All direct child animations of a parallel animation will run in parallel, when started. This allows you to animate different properties at the same time.

// parallelanimation.qml
import QtQuick 2.5

BrightSquare {
    id: root
    width: 600
    height: 400
    property int duration: 3000
    property Item ufo: ufo

    Image {
        anchors.fill: parent
        source: "assets/ufo_background.png"
    }


    ClickableImageV3 {
        id: ufo
        x: 20; y: root.height-height
        text: 'ufo'
        source: "assets/ufo.png"
        onClicked: anim.restart()
    }

    ParallelAnimation {
        id: anim
        NumberAnimation {
            target: ufo
            properties: "y"
            to: 20
            duration: root.duration
        }
        NumberAnimation {
            target: ufo
            properties: "x"
            to: 160
            duration: root.duration
        }
    }
}

A sequential animation will first run the first child animation and then continue from there.

// sequentialanimation.qml
import QtQuick 2.5

BrightSquare {
    id: root
    width: 600
    height: 400
    property int duration: 3000

    property Item ufo: ufo

    Image {
        anchors.fill: parent
        source: "assets/ufo_background.png"
    }

    ClickableImageV3 {
        id: ufo
        x: 20; y: root.height-height
        text: 'rocket'
        source: "assets/ufo.png"
        onClicked: anim.restart()
    }

    SequentialAnimation {
        id: anim
        NumberAnimation {
            target: ufo
            properties: "y"
            to: 20
            // 60% of time to travel up
            duration: root.duration*0.6
        }
        NumberAnimation {
            target: ufo
            properties: "x"
            to: 400
            // 40% of time to travel sideways
            duration: root.duration*0.4
        }
    }
}

Grouped animation can also be nested, for example a sequential animation can have two parallel animations as child animations, and so on. We can visualize this with a soccer ball example. The idea is to throw a ball from left to right an animate its behavior.

To understand the animation we need to dissect it into the integral transformations of the object. We need to remember animation do animate property changes. Here are the different transformations:

• An x-translation from left-to-right (X1)
• An y-translation from down to up (Y1) followed by a translation from up to down (Y2) with some bouncing
• A rotation over 360 over the whole animation duration (ROT1)

The whole duration of the animation should take three seconds.

We start with an empty item as root element of the width of 480 and height of 300.

import QtQuick 2.5

Item {
    id: root
    width: 480
    height: 300
    property int duration: 3000

    ...
}

We have defined our total animation duration as reference to better synchronize the animation parts.

The next step would be to add the background, which in our case are 2 rectangles with a green and blue gradients.

    Rectangle {
        id: sky
        width: parent.width
        height: 200
        gradient: Gradient {
            GradientStop { position: 0.0; color: "#0080FF" }
            GradientStop { position: 1.0; color: "#66CCFF" }
        }
    }
    Rectangle {
        id: ground
        anchors.top: sky.bottom
        anchors.bottom: root.bottom
        width: parent.width
        gradient: Gradient {
            GradientStop { position: 0.0; color: "#00FF00" }
            GradientStop { position: 1.0; color: "#00803F" }
        }
    }

The upper blue rectangle takes 200 pixel of the height and the lower one is anchored to the top on the sky and to the bottom on the root element.

Let’s bring the soccer ball onto the green. The ball is an image, stored under “assets/soccer_ball.png”. For the beginning we would like to position it in the lower left corner, near the edge.

    Image {
        id: ball
        x: 0; y: root.height-height
        source: "assets/soccer_ball.png"

        MouseArea {
            anchors.fill: parent
            onClicked: {
                ball.x = 0;
                ball.y = root.height-ball.height;
                ball.rotation = 0;
                anim.restart()
            }
        }
    }

The image has a mouse area attached to it. If the ball is clicked the position of the ball will reset and the animation restarted.

Let’s start with an sequential animation for the two y translations first.

SequentialAnimation {
    id: anim
    NumberAnimation {
        target: ball
        properties: "y"
        to: 20
        duration: root.duration * 0.4
    }
    NumberAnimation {
        target: ball
        properties: "y"
        to: 240
        duration: root.duration * 0.6
    }
}

This specifies that 40% of the total animation duration is the up animation and 60% the down animation. One animation after another as a sequence. The transformations are animated on a linear path but there is no curve currently. Curves will be added later using the easing curves, at the moment we’re concentrating on getting the transformations animated.

Next, we need to add the x-translation. The x-translation shall run in parallel with the y-translation so we need to encapsulate the sequence of y-translations into a parallel animation together with the x-translation.

ParallelAnimation {
    id: anim
    SequentialAnimation {
        // ... our Y1, Y2 animation
    }
    NumberAnimation { // X1 animation
        target: ball
        properties: "x"
        to: 400
        duration: root.duration
    }
}

At the end we would like the ball to be rotating. For this we need to add another animation to the parallel animation. We choose the RotationAnimation as it’s specialized for rotation.

ParallelAnimation {
    id: anim
    SequentialAnimation {
        // ... our Y1, Y2 animation
    }
    NumberAnimation { // X1 animation
        // X1 animation
    }
    RotationAnimation {
        target: ball
        properties: "rotation"
        to: 720
        duration: root.duration
    }
}

That’s the whole animation sequence. The one thing left is to provide the correct easing curves for the movements of the ball. For the Y1 animation I use a Easing.OutCirc curve as this should look more like a circular movement. Y2 is enhanced using an Easing.OutBounce as the ball should bounce and the bouncing should happen at the end (try an Easing.InBounce and you see the bouncing will start right away). The X1 and ROT1 animation are left as is with a linear curve.

Here is the final animation code for your reference:

    ParallelAnimation {
        id: anim
        SequentialAnimation {
            NumberAnimation {
                target: ball
                properties: "y"
                to: 20
                duration: root.duration * 0.4
                easing.type: Easing.OutCirc
            }
            NumberAnimation {
                target: ball
                properties: "y"
                to: root.height-ball.height
                duration: root.duration * 0.6
                easing.type: Easing.OutBounce
            }
        }
        NumberAnimation {
            target: ball
            properties: "x"
            to: root.width-ball.width
            duration: root.duration
        }
        RotationAnimation {
            target: ball
            properties: "rotation"
            to: 720
            duration: root.duration
        }
    }

States¶

You define states in QML with the State element, which needs to be bound to the states array of any item element. A state is identified through a state name and consist, in its simplest form, of a series of property changes on elements. The default state is defined by the initial properties of the element and is named "" (the empty string).

Item {
    id: root
    states: [
        State {
            name: "go"
            PropertyChanges { ... }
        },
        State {
            name: "stop"
            PropertyChanges { ... }
        }
    ]
}

A state is changed by assigning a new state name to the state property of the element with the states defined.

Item {
    id: root
    states: [
        ...
    ]

    Button {
        id: goButton
        ...
        onClicked: root.state = "go"
    }
}

For example, a traffic light might have two signaling lights. The upper one signaling stop with a red color and the lower one signaling go with a green color. In this example both lights should not shine at the same time. Let’s have a look at the state chart diagram.

When the system is switched on it goes automatically into the stop mode as default state. The stop state changes the light1 to red and light2 to black (off). An external event can now trigger a state switch to the "go" state. In the go state we change the color properties from light1 to black (off) and light2 to green to indicate the passers may walk now.

To realize this scenario we start sketching our user interface for the 2 lights. For simplicity we use 2 rectangles with the radius set to the half of the width (and the width is the same as the height, which means it’s a square).

    Rectangle {
        id: light1
        x: 25; y: 15
        width: 100; height: width
        radius: width/2
        color: root.black
        border.color: Qt.lighter(color, 1.1)
    }

    Rectangle {
        id: light2
        x: 25; y: 135
        width: 100; height: width
        radius: width/2
        color: root.black
        border.color: Qt.lighter(color, 1.1)
    }

As defined in the state chart we want to have two states one the "go" state and the other the "stop" state, where each of them changes the traffic lights respective to red or green. We set the state property to stop to ensure the initial state of our traffic light is the stop state.

    state: "stop"

    states: [
        State {
            name: "stop"
            PropertyChanges { target: light1; color: root.red }
            PropertyChanges { target: light2; color: root.black }
        },
        State {
            name: "go"
            PropertyChanges { target: light1; color: root.black }
            PropertyChanges { target: light2; color: root.green }
        }
    ]

Using PropertyChanges { target: light2; color: "black" } is not really required in this examples as the initial color of light2 is already black. In a state it’s only necessary to describe how the properties shall change from their default state (and not from the previous state).

A state change is triggered using a mouse area which covers the whole traffic light and toggles between the go and stop state when clicked.

    MouseArea {
        anchors.fill: parent
        onClicked: parent.state = (parent.state == "stop"? "go" : "stop")
    }

We are now able to successfully change the state of the traffic lamp. To make the UI more appealing and look natural we should add some transitions with animation effects. A transition can be triggered by a state change.

Transitions¶

A series of transitions can be added to every item. A transition is executed by a state change. You can define on which state change a particular transition can be applied using the from: and to: properties. These two properties act like a filter, when the filter is true the transition will be applied. You can also use the wild-cast “*” which means “any state”. For example from:"*"; to:"*" means from any state to any other state and is the default value for from and to, which means the transition is applied to every state switch.

For this example we would like to animate the color changes when switching state from “go” to “stop”. For the other reversed state change (“stop” to “go”) we want to keep an immediate color change and don’t apply a transition. We restrict the transition with the from and to properties to filter only the state change from “go” to “stop”. Inside the transition we add two color animations for each light, which shall animate the property changes defined in the state description.

    transitions: [
        Transition {
            from: "stop"; to: "go"
//            from: "*"; to: "*"
            ColorAnimation { target: light1; properties: "color"; duration: 2000 }
            ColorAnimation { target: light2; properties: "color"; duration: 2000 }
        }
    ]

You can change the state though clicking the UI. The state is applied immediately and will also change the state while a transition is running. So try to click the UI while the state is in transition from “stop” to “go”. You will see the change will happen immediately.

You could play around with this UI by, for example, scaling the inactive light down to highlight the active light. For this you would need to add another property change for scaling to the states and also handle the animation for the scaling property in the transition. Another option would be to add an “attention” state where the lights are blinking yellow. For this, you would need to add a sequential animation to the transition for one second going to yellow (“to” property of the animation and one sec going to “black”). Maybe you would also want to change the easing curve to make it more visually appealing.

Hoch- oder Querformat¶

Die ListView-Ansicht erlaubt neben vertikaler Anzeige und Scrollen auch horizontales Scrollen, welches genauso nützlich sein kann. Die Ausrichtung der ListView-Ansicht wird von der Eigenschaft orientation gesteuert. Es kann entweder den Standardwert ListView.Vertical oder den Wert ListView.Horizontal bekommen. Im folgenden sieht man letzteres.

import QtQuick 2.5
import "../common"

Background {
    width: 480
    height: 80

    ListView {
        anchors.fill: parent
        anchors.margins: 20
        spacing: 4
        clip: true
        model: 100
        orientation: ListView.Horizontal
        delegate: numberDelegate
    }

    Component {
        id: numberDelegate

        GreenBox {
            width: 40
            height: 40
            text: index
        }
    }
}

Wie man sich vorstellen kann geht die Richtung der horizontalen Darstellung von links nach rechts. Über die Eigenschaft layoutDirection kann man mit Qt.LeftToRight oder mit Qt.RightToLeft die Darstellungsrichtung beeinflussen.

Tastennavigation und Highlighting¶

Wenn man eine ListView-Ansicht mit einem touch-fähigen Gerät verwendet, reicht die Darstellung aus. Wenn man aber mit einer Tastatur oder sogar nur mit Pfeiltasten ein Element auswählen soll, braucht man ein Verfahren um das momentan ausgewählte Element hervorzuheben. In QML nennt man das “highlighting”.

Die Ansichten wie ListView in QML erlauben es eines der gezeigten Delegaten hervorheben zu können. Man kann es als zusätzlichen Delegaten ansehen, nur dass dieser eben nur einmal erzeugt wird und an der Stelle des momentanen Elements angezeigt wird.

Im folgenden Beispiel wird das demonstriert. Man muss zwei Attribute dafür verwenden. Erstens, die focus-Eigenschaft muss auf true gesetzt werden, so bekommt die Tastatur von der ListView-Ansicht den Fokus. Zweitens muss die highlight-Eigenschaft auf den hervorzuhebenden Delegaten gesetzt sein. Der hervorgehobene Delegat bekommt die x, y und die height-Werte des aktuellen Elements. Wenn der width-Wert nicht angegeben wird, dann wird auch die Breite des aktuellen Elements verwendet.

Im Beispiel wird die angebundene Eigenschaft ListView.view.width für die Breite verwendet. Gebundene Eigenschaften, die für Delegaten verfügbar sind werden im Abschnitt zu Delegaten dieses Kapitels diskutiert, aber es ist schon jetzt gut zu wissen, dass die gleichen Eigenschaften auch hervorgehobenen Delegaten zur Verfügung stehen.

import QtQuick 2.5
import "../common"

Background {
    width: 240
    height: 300

    ListView {
        id: view
        anchors.fill: parent
        anchors.margins: 20

        clip: true

        model: 100

        delegate: numberDelegate
        spacing: 5

        highlight: highlightComponent
        focus: true
    }

    Component {
        id: highlightComponent

        GreenBox {
            width: ListView.view.width
        }
    }

    Component {
        id: numberDelegate

        Item {
            width: ListView.view.width
            height: 40

            Text {
                anchors.centerIn: parent

                font.pixelSize: 10

                text: index
            }
        }
    }
}

When using a highlight in conjunction with a ListView, a number of properties can be used to control its behavior. The highlightRangeMode controls how the highlight is affected by what is shown in the view. The default setting, ListView.NoHighlightRange means that the highlight and the visible range of items in the view not are related at all.

The value ListView.StrictlyEnforceRange ensures that the highlight is always visible. If an action attempts to move the highlight outside the visible part of the view, the current item will change accordingly, so that the highlight remains visible.

The middle ground is the ListView.ApplyRange value. It attempts to keep the highlight visible, but does not alter the current item to enforce this. Instead, the highlight is allowed to move out of view if necessary.

In the default configuration, the view is responsible for moving the highlight into position. The speed of the movement and resizing can be controlled, either as a speed or as a duration. The properties involved are highlightMoveSpeed, highlightMoveDuration, highlightResizeSpeed and highlightResizeDuration. By default, the speed is set to 400 pixels per second, and the duration is set to -1, indicating that the speed and distance control the duration. If both a speed and a duration is set, the one that results in the quickest animation is chosen.

To control the movement of the highlight more in detail, the highlightFollowCurrentItem property can be set to false. This means that the view is no longer responsible for the movement of the highlight delegate. Instead, the movement can be controlled through a Behavior or an animation.

In the example below, the y property of the highlight delegate is bound to the ListView.view.currentItem.y attached property. This ensures that the highlight follows the current item. However, as we do not let the view move the highlight, we can control how the element is moved. This is done through the Behavior on y. In the example below, the movement is divided into three steps: fading out, moving, before fading in. Notice how SequentialAnimation and PropertyAnimation elements can be used in combination with the NumberAnimation to create a more complex movement.

    Component {
        id: highlightComponent

        Item {
            width: ListView.view.width
            height: ListView.view.currentItem.height

            y: ListView.view.currentItem.y

            Behavior on y {
                SequentialAnimation {
                    PropertyAnimation { target: highlightRectangle; property: "opacity"; to: 0; duration: 200 }
                    NumberAnimation { duration: 1 }
                    PropertyAnimation { target: highlightRectangle; property: "opacity"; to: 1; duration: 200 }
                }
            }

            GreenBox {
                id: highlightRectangle
                anchors.fill: parent
            }
        }
    }

Header and Footer¶

At the end of the ListView contents, a header and a footer element can be inserted. These can be considered special delegates places at the beginning or end of the list. For a horizontal list, these will not appear at the head or foot, but rather at then beginning or end, depending on the layoutDirection used.

The example below illustrates how an header and footer can be used to enhance the perception of the beginning and end of a list. There are other uses for these special list elements. For instance, they can be used to keep buttons to load more contents.

import QtQuick 2.5
import "../common"

Background {
    width: 240
    height: 300

    ListView {
        anchors.fill: parent
        anchors.margins: 20

        clip: true

        model: 4

        delegate: numberDelegate
        spacing: 2

        header: headerComponent
        footer: footerComponent
    }

    Component {
        id: headerComponent

        YellowBox {
            width: ListView.view.width
            height: 20
            text: 'Header'

        }
    }

    Component {
        id: footerComponent

        YellowBox {
            width: ListView.view.width
            height: 20
            text: 'Footer'
        }
    }

    Component {
        id: numberDelegate

        GreenBox {
            width: ListView.view.width
            height: 40
            text: 'Item #' + index
        }
    }
}

The GridView¶

Using a GridView is very similar to using a ListView. The only real difference is that the grid view places the delegates in a two dimensional grid instead of in a linear list.

Compared to a list view, the grid view does not rely on spacing and the size of its delegates. Instead, it uses the cellWidth and cellHeight properties to control the dimensions of the contents delegates. Each delegate item is then places in the top left corner of each such cell.

import QtQuick 2.5
import "../common"

Background {
    width: 220
    height: 300

    GridView {
        id: view
        anchors.fill: parent
        anchors.margins: 20

        clip: true

        model: 100

        cellWidth: 45
        cellHeight: 45

        delegate: numberDelegate
    }

    Component {
        id: numberDelegate

        GreenBox {
            width: 40
            height: 40
            text: index
        }
    }
}

A GridView contains headers and footers, can use a highlight delegate and supports snap modes as well as various bounds behaviors. It can also be orientated in different directions and orientations.

The orientation is controlled using the flow property. It can be set to either GridView.LeftToRight or GridView.TopToBottom. The former value fills a grid from the left to the right, adding rows from the top to the bottom. The view is scrollable in the vertical direction. The latter value adds items from the top to the bottom, filling the view from left to right. The scrolling direction is horizontal in this case.

In addition to the flow property, the layoutDirection property can adapt the direction of the grid to left-to-right or right-to-left languages, depending on the value used.

Animating Added and Removed Items¶

In some cases, the contents shown in a view changes over time. Items are added and removed as the underlaying data model is altered. In these cases, it is often a good idea to employ visual ques to give the user a sense of direction and to help the user understand what data is added or removed.

Conveniently enough, QML views attaches two signals, onAdd and onRemove, to each item delegate. By connecting animations to these, it is easy to create the movement necessary to aid the user in identifying what is taking place.

The example below demonstrates this through the use of a dynamically populated ListModel. At the bottom of the screen, a button for adding new items is shown. When it is clicked, a new item is added to the model using the append method. This triggers the creation of a new delegate in the view, and the emission of the GridView.onAdd signal. The SequentialAnimation attached to the signal causes the item to zoom into view by animating the scale property of the delegate.

When a delegate in the view is clicked, the item is removed from the model through a call to the remove method. This causes the GridView.onRemove signal to be emitted, triggering another SequentialAnimation. This time, however, the destruction of the delegate must be delayed until the animation has completed. To do this, PropertyAction element are used to set the GridView.delayRemove property to true before the animation, and false after. This ensures that the animation is allowed to complete before the delegate item is removed.

import QtQuick 2.5

Rectangle {
    width: 480
    height: 300

    gradient: Gradient {
        GradientStop { position: 0.0; color: "#dbddde" }
        GradientStop { position: 1.0; color: "#5fc9f8" }
    }

    ListModel {
        id: theModel

        ListElement { number: 0 }
        ListElement { number: 1 }
        ListElement { number: 2 }
        ListElement { number: 3 }
        ListElement { number: 4 }
        ListElement { number: 5 }
        ListElement { number: 6 }
        ListElement { number: 7 }
        ListElement { number: 8 }
        ListElement { number: 9 }
    }

    Rectangle {
        anchors.left: parent.left
        anchors.right: parent.right
        anchors.bottom: parent.bottom
        anchors.margins: 20

        height: 40

        color: "#53d769"
        border.color: Qt.lighter(color, 1.1)

        Text {
            anchors.centerIn: parent

            text: "Add item!"
        }

        MouseArea {
            anchors.fill: parent

            onClicked: {
                theModel.append({"number": ++parent.count});
            }
        }

        property int count: 9
    }

    GridView {
        anchors.fill: parent
        anchors.margins: 20
        anchors.bottomMargin: 80

        clip: true

        model: theModel

        cellWidth: 45
        cellHeight: 45

        delegate: numberDelegate
    }

    Component {
        id: numberDelegate

        Rectangle {
            id: wrapper

            width: 40
            height: 40

            gradient: Gradient {
                GradientStop { position: 0.0; color: "#f8306a" }
                GradientStop { position: 1.0; color: "#fb5b40" }
            }

            Text {
                anchors.centerIn: parent

                font.pixelSize: 10

                text: number
            }

            MouseArea {
                anchors.fill: parent

                onClicked: {
                    theModel.remove(index);
                }
            }

            GridView.onRemove: SequentialAnimation {
                PropertyAction { target: wrapper; property: "GridView.delayRemove"; value: true }
                NumberAnimation { target: wrapper; property: "scale"; to: 0; duration: 250; easing.type: Easing.InOutQuad }
                PropertyAction { target: wrapper; property: "GridView.delayRemove"; value: false }
            }

            GridView.onAdd: SequentialAnimation {
                NumberAnimation { target: wrapper; property: "scale"; from: 0; to: 1; duration: 250; easing.type: Easing.InOutQuad }
            }
        }
    }
}