Qt Virtual Keyboard: Bildschirmtastatur für Embedded-Geräte richtig einsetzen

Kurz gesagt: Ein Embedded-Gerät mit Touch-Display braucht eine Bildschirmtastatur, sobald irgendwo ein Text eingegeben wird – ein WLAN-Passwort, ein Gerätename, ein Sollwert. Die Qt Virtual Keyboard liefert das fertig, inklusive Layouts, Sprachen und Anbindung an das Eingabesystem von Qt. Die technische Integration ist an einem Nachmittag erledigt. Die Frage, die man vorher klären sollte, ist die Lizenz: Dieses Modul steht nicht unter denselben Bedingungen wie der Großteil von Qt.

Zuerst die Lizenzfrage

Der Großteil der Qt-Module ist so lizenziert, dass sie sich in kommerziellen Produkten mit dynamischem Linken vergleichsweise unkompliziert einsetzen lassen. Die Qt Virtual Keyboard gehört zu den Modulen, für die das nicht pauschal gilt – ihre Open-Source-Variante steht unter strengeren Bedingungen, die für ein geschlossenes Produkt Folgen haben können.

Das ist kein Grund, das Modul zu meiden; es ist ein Grund, die Frage früh zu stellen. Die konkrete Antwort hängt an Ihrer Qt-Version, an Ihrem Vertriebsmodell und daran, ob Sie ohnehin eine kommerzielle Qt-Lizenz halten. Klären Sie das mit The Qt Company oder juristischem Rat, bevor die Tastatur fest in der Oberfläche verankert ist – ein späterer Austausch ist deutlich teurer als eine Entscheidung am Anfang. (Das hier ist eine technische Einordnung, keine Rechtsberatung.)

Wie die Integration funktioniert

Qt trennt Eingabemethoden von den Eingabefeldern. Ein TextField weiß nichts von einer Tastatur – es meldet nur, dass es den Fokus hat. Ein Input-Method-Modul entscheidet daraufhin, was passiert. Auf dem Desktop übernimmt das das Betriebssystem; auf einem Embedded-Gerät ohne Fenstersystem gibt es niemanden, der das täte – genau diese Rolle füllt die Qt Virtual Keyboard.

Aktiviert wird sie über eine Umgebungsvariable, die vor dem Erzeugen der Anwendung gesetzt sein muss:

int main(int argc, char *argv[])
{
    qputenv("QT_IM_MODULE", QByteArray("qtvirtualkeyboard"));
    QGuiApplication app(argc, argv);
    // …
}

Alternativ über die Umgebung des Dienstes, was für ein Systemd-basiertes Gerät oft sauberer ist:

export QT_IM_MODULE=qtvirtualkeyboard

In der QML-Szene braucht es dann ein InputPanel, das die Tastatur darstellt. Es wird typischerweise am unteren Rand verankert und blendet sich selbst ein, sobald ein Eingabefeld den Fokus bekommt:

import QtQuick
import QtQuick.VirtualKeyboard

Item {
    id: root

    TextField {
        id: nameField
        anchors.centerIn: parent
        placeholderText: qsTr("Gerätename")
    }

    InputPanel {
        id: inputPanel
        z: 99
        anchors.left: parent.left
        anchors.right: parent.right
        // Unterhalb des Bildschirms parken und nur bei Bedarf hereinfahren
        y: root.height - (active ? height : 0)

        Behavior on y {
            NumberAnimation { duration: 150; easing.type: Easing.InOutQuad }
        }
    }
}

Drei Details entscheiden darüber, ob das im Alltag trägt. Der z-Wert sorgt dafür, dass die Tastatur über der übrigen Oberfläche liegt – ohne ihn verschwindet sie hinter Hintergrundflächen. Die Verankerung am unteren Rand samt Animation ist das erwartete Verhalten; eine Tastatur, die einfach erscheint, wirkt abrupt. Und das Nachführen des Eingabefelds: Wenn die Tastatur die untere Bildschirmhälfte einnimmt, muss das aktive Feld sichtbar bleiben – sonst tippt der Nutzer blind.

Layouts, Sprachen und Größe

Die Tastatur bringt Layouts für viele Sprachen mit, dazu optional Handschrifterkennung. Für ein Gerät, das im Feld zwei Sprachen bedient, ist es sinnvoll, den Build auf genau diese zu beschränken – jedes zusätzliche Layout kostet Platz im Image und Zeit beim Start. Die Auswahl geschieht über Konfigurationsschalter beim Bau des Moduls; in einem Yocto-basierten Image gehört diese Entscheidung in das Rezept, nicht in ein nachträgliches Skript.

Umgekehrt gilt: Ein Gerät, das weltweit ausgeliefert wird und dessen Nutzer Namen in ihrer eigenen Schrift eingeben sollen, braucht die entsprechenden Layouts – und ein Konzept dafür, wie der Nutzer zwischen ihnen umschaltet, ohne sich zu verirren.

Ans eigene Design anpassen

Eine unveränderte Standardtastatur in einer sonst sorgfältig gestalteten Oberfläche fällt sofort auf. Das Modul bringt dafür ein eigenes Styling-System mit: Farben, Tastenformen, Schriftgrößen und Abstände lassen sich austauschen, ohne die Eingabelogik anzufassen. Das eigene Style wird über eine Umgebungsvariable ausgewählt und liegt als QML-Ressource im Anwendungs-Build.

Was dabei erfahrungsgemäß unterschätzt wird, ist die Tastengröße. Auf einem 7-Zoll-Display mit Handschuhbedienung sind die Standardmaße zu klein; das merkt man erst im Feldtest, wenn Bedienfehler auffallen. Diese Frage gehört an den Anfang, weil sie das Layout der gesamten Eingabemaske beeinflusst.

Wenn es nicht funktioniert

Symptom	Wahrscheinliche Ursache
Tastatur erscheint nie	QT_IM_MODULE nicht gesetzt oder zu spät gesetzt
Tastatur ist da, aber unsichtbar	Fehlender z-Wert, liegt hinter anderen Elementen
Eingabefeld wird verdeckt	Kein Nachführen der Ansicht bei aktiver Tastatur
Falsches Layout	Gewünschte Sprache nicht mit einkompiliert
Tasten reagieren träge	Zu viele Animationen oder fehlende Hardwarebeschleunigung
Tastatur startet mit, obwohl nie gebraucht	Modul wird eingebunden, ohne dass ein Feld existiert

Der letzte Punkt lohnt einen Blick, wenn die Boot-Zeit knapp ist: Ein Gerät, das nur bei der Erstinbetriebnahme eine Texteingabe braucht, muss die Tastatur nicht bei jedem Start bereithalten.

Fazit

Technisch ist die Qt Virtual Keyboard eine unaufgeregte Angelegenheit: Umgebungsvariable setzen, InputPanel platzieren, Fokus und Sichtbarkeit sauber behandeln. Die beiden Punkte, die Projekte tatsächlich aufhalten, liegen woanders – die Lizenzfrage, die vor der Integration gehört, und die Gestaltung, die früh genug entschieden sein will, weil sie das Layout der Eingabemasken prägt. Wie Qt-Oberflächen auf begrenzter Hardware insgesamt flüssig bleiben, haben wir im Beitrag Qt im Embedded-Umfeld beschrieben; die Grundlagen dazu vermitteln wir auch in unserer Qt- und QML-Schulung. Wenn Sie eine HMI planen und die Eingabewege noch offen sind, sprechen Sie uns an.