Qt Virtual Keyboard Übersicht

Merkmale

Zu den wichtigsten Funktionen von Qt Virtual Keyboard gehören:

• Anpassbare Tastaturlayouts und -stile mit dynamischer Umschaltung.
• Prädiktive Texteingabe mit Wortauswahl.
• Zeichenvorschau und alternative Zeichenansicht.
• Automatische Großschreibung und Einfügen von Leerzeichen.
• Skalierbarkeit auf verschiedene Auflösungen.
• Unterstützung für verschiedene Zeichensätze (Latein, vereinfachtes/traditionelles Chinesisch, Hindi, Japanisch, Arabisch, Hebräisch, Koreanisch und andere).
• Unterstützung für die meisten gängigen Eingabesprachen, mit der Möglichkeit, die Sprachunterstützung einfach zu erweitern.
• Links-nach-Rechts- und Rechts-nach-Links-Eingabe.
• Unterstützung von Hardware-Tasten für 2-Wege- und 5-Wege-Navigation.
• Unterstützung der Handschrift mit Gesten für die Eingabe im Vollbildmodus.
• Audio-Rückmeldung.
• Plattformübergreifende Funktionalität.
• Unterstützt sowohl die AnwendungenQt Quick als auch Qt Widgets .

Unterstützte Sprachen

Die virtuelle Tastatur unterstützt die folgenden Sprachen:

Um Unterstützung für eine weitere Sprache hinzuzufügen, siehe Hinzufügen neuer Tastaturlayouts.

Plugins von Drittanbietern

Qt Virtual Keyboard unterstützt Plugins von Drittanbietern von den folgenden Herstellern:

• Cerence XT9 erweiterte Eingabe.
• Cerence Handwriting Texteingabe.
• MyScript Text Handschrifterkennung

Die Erstellung von Qt Virtual Keyboard beschreibt, wie diese Plugins in Qt Virtual Keyboard integriert werden können.

Grundlegende Konzepte

Das Projekt Qt Virtual Keyboard ist ein Qt-Eingabekontext-Plugin, das die Schnittstellen QPlatformInputContextPlugin und QPlatformInputContext implementiert. Diese Schnittstellen ermöglichen es dem Plugin, als Plattform-Eingabekontext-Plugin in Qt-Anwendungen verwendet zu werden.

Das Plugin selbst bietet ein Eingabe-Framework, das mehrere Eingabemethoden unterstützt, sowie eine QML-Benutzeroberfläche für die virtuelle Tastatur. Das Eingabe-Framework ist über eine Plugin-Schnittstelle erweiterbar, über die Eingabemethoden und Tastaturlayouts von Drittanbietern zur Laufzeit geladen werden können.

Das Eingabe-Framework bietet die folgenden Hauptschnittstellen:

• QVirtualKeyboardInputContextBereitstellung von Kontextinformationen für die virtuelle Tastatur und andere Eingabekomponenten. Dient als Schnittstelle zur zugrunde liegenden Texteingabekomponente.
• QVirtualKeyboardInputEngine: stellt eine API zur Integration von Benutzereingabeereignissen (Tastendruck usw.) zur Verfügung und fungiert als Host für Eingabemethoden.
• QVirtualKeyboardAbstractInputMethodC++: ein Basistyp für C++-basierte Eingabemethoden. Die Eingabemethode verarbeitet normalerweise Tastenereignisse, kann aber auch Maus- und Berührungseingabeereignisse verarbeiten.
• InputMethodQML: Ein Basistyp für QML-basierte Eingabemethoden. Die Eingabemethode verarbeitet in der Regel Tastenereignisse, kann aber auch Maus- und Berührungsereignisse verarbeiten.

Eingabekontext

Der Eingabekontext wird sowohl von der Tastatur als auch von konkreten Eingabemethoden verwendet. InputContext ist eine Singleton-Instanz, die von QML gehostet wird. Eine Anwendung sollte nicht direkt mit dem Eingabekontext interagieren.

Kontextbezogene Informationen

Der Eingabekontext ermöglicht den Zugriff auf Kontextinformationen, die von der Anwendung stammen. Diese Informationen beinhalten, sind aber nicht beschränkt auf

• InputContext::cursorPosition
• InputContext::cursorRectangle
• InputContext::inputMethodHints
• InputContext::preeditText
• InputContext::selectedText
• InputContext::surroundingText

Gebietsschema

Die Virtual Keyboard Engine generiert die Liste der unterstützten Gebietsschemata aus ortsspezifischen Layout-Verzeichnissen in layouts/. Jedes Layout-Verzeichnis muss eine Definition oder einen Fallback für die folgenden Layout-Typen enthalten: Dialpad, Ziffern, Handschrift, Haupt, Zahlen und Symbole. Definitionen werden in .qml-Dateien implementiert, Fallbacks werden durch eine Platzhalterdatei mit der Dateierweiterung .fallback definiert. Das Verzeichnis layouts/ muss ein Unterverzeichnis fallback/ enthalten, das die Definitionen für jeden Layouttyp enthält.

Jedes Layoutverzeichnis kann die Definition eines oder mehrerer Layouttypen enthalten. Wenn das ortsspezifische Layout mit dem des Ausweichgebietsschemas übereinstimmt, können Sie eine Platzhalterdatei für das Layout namens <layout type>.fallback hinzufügen. Dies weist die virtuelle Tastatur an, stattdessen das Fallback-Layout zu verwenden.

Ein Beispiel: Sie können ein lokalspezifisches Layout für Finnisch hinzufügen, das den Hauptlayouttyp in main.qml definiert. Für die anderen Layouttypen entscheiden Sie sich für den Fallback-Mechanismus. Ihr layouts/ Baum sieht dann so aus:

.
├── fallback
│   ├── dialpad.qml
│   ├── digits.qml
│   ├── handwriting.qml
│   ├── main.qml
│   ├── numbers.qml
│   └── symbols.qml
└── fi_FI
    ├── dialpad.fallback
    ├── digits.fallback
    ├── handwriting.fallback
    ├── main.qml
    ├── numbers.fallback
    └── symbols.fallback

Es ist zwingend erforderlich, dass das Verzeichnis layouts/fallback immer einen Satz vollständiger Implementierungsdateien enthält.

Die Anwendung kann das anfängliche Layout festlegen, indem sie das Standardgebietsschema ändert. Dies muss jedoch geschehen, bevor die Anwendung initialisiert und das Eingabemethoden-Plugin geladen wird. Wenn keine Änderungen am Standardgebietsschema vorgenommen werden, wird das aktuelle Systemgebietsschema verwendet.

Die Anpassung an das Tastaturlayout erfolgt in dieser Reihenfolge:

• layouts/<language>_<country>
• layouts/<language>_*
• layouts/fallback - Das Standardlayout ist hier en_GB.

Zunächst wird das Gebietsschema mit dem vollständigen Namen des Gebietsschemas abgeglichen. Wenn es keine vollständige Übereinstimmung gibt, wird nur die Sprache des Gebietsschemas abgeglichen. Schließlich wird der Inhalt von layouts/fallback als Fallback verwendet, wenn es auch keine teilweise Übereinstimmung gibt.

Nach der Auswahl des Gebietsschemas aktualisiert die Tastatur das Eingabegebietsschema und die Eingaberichtung, um dem aktuellen Layout zu entsprechen. Die Anwendung kann diese Informationen über die Schnittstelle QInputMethod erhalten.

Intern wird das aktuelle Eingabegebietsschema auch auf QVirtualKeyboardInputEngine und die aktuellen Eingabemethodeninstanzen aktualisiert.

Eingabemaschine

Das Input-Engine-Objekt ist Eigentum von InputContext. Wie InputContext gibt es nur eine Instanz von QVirtualKeyboardInputEngine. Die Eingabemaschine enthält API-Funktionen, die die Tastatur verwendet, um Benutzerinteraktionen, wie z. B. Tastendruck- und -freigabeereignisse, auf die Eingabemethode abzubilden.

So werden beispielsweise die Tastenereignisse der virtuellen Tastatur durch die folgenden Methoden abgebildet:

• QVirtualKeyboardInputEngine::virtualKeyPress
• QVirtualKeyboardInputEngine::virtualKeyRelease

Die oben genannten Methoden sind für die Integration der virtuellen Tastatur gedacht, daher das Wort "virtuell" im Namen der Methoden. Das bedeutet auch, dass die Methoden nicht für die Abbildung der physischen Tastenanschläge geeignet sind. Dies ist eine Folge der Tatsache, dass die eigentliche Aktion erst beim Loslassen der Taste ausgeführt wird.

Wird der Tastendruck vor dem Ereignis des Loslassens der Taste unterbrochen, ruft die Tastatur die Methode QVirtualKeyboardInputEngine::virtualKeyCancel auf.

Eingabe-Methode

Die Eingabemethode ist eine konkrete Implementierung des Tastendruck-Handlers. Ihre Hauptfunktion besteht darin, Tastendruck-Ereignisse zu verarbeiten und Statusinformationen für die Benutzereingabe zu erhalten. Sie interagiert mit dem Texteditor durch QVirtualKeyboardInputContext über Pre-Edit-Text oder Tastenereignisse.

Die Instanz der Eingabemethode kann je nach Anwendungsfall auf verschiedene Weise erstellt werden:

• KeyboardLayout::inputMethodDas Tastaturlayout kann eine Eingabemethodeninstanz nur für dieses Tastaturlayout erstellen. Es ist zu beachten, dass diese Instanz zerstört wird, wenn das Tastaturlayout geändert wird. Daher ist diese Methode normalerweise auf sehr enge Anwendungsfälle beschränkt.
• KeyboardLayout::createInputMethod(): Das Tastaturlayout kann dynamisch eine Eingabemethode erstellen, die sowohl mit diesem Layout als auch mit dem shared layouts (z. B. Symbol-Layout) verwendet werden kann. Dies ist der bevorzugte Weg, um spezialisierte Eingabemethoden zu erstellen, wie z.B. solche, die komplexe Sprachen oder Handschrift beinhalten.
• DefaultInputMethod: Die virtuelle Tastatur versucht, diese Art von Eingabemethode beim Start zu erstellen. Diese Instanz wird als Standard-Eingabemethode für alle Tastaturlayouts verwendet, es sei denn, das Tastaturlayout verwendet eine benutzerdefinierte Eingabemethode. Diese Instanz überdauert Änderungen des Tastaturlayouts in verschiedenen Sprachen und ist die bevorzugte Methode zum Erstellen und Überschreiben der Standardeingabemethode.

Virtuelle Tastatur Plugins

Das Verzeichnis src/plugins der virtuellen Tastatur enthält die vorhandenen Plugins für die virtuelle Tastatur. Bei diesen Plugins handelt es sich um Standard-QML-Module, die implizit durch das QML-Modul QtQuick.VirtualKeyboard.Plugins geladen werden.

Ein Plugin kann Tastaturlayouts und Eingabemethoden (normalerweise beides) bereitstellen. Die von der virtuellen Tastatur verwendete Eingabemethode hängt davon ab, welches Tastaturlayout gerade verwendet wird. Das Tastaturlayout kann eine Instanz einer benutzerdefinierten Eingabemethode mit der Funktion KeyboardLayout.createInputMethod() bereitstellen. Andernfalls wird die Standard-Eingabemethode (DefaultInputMethod) verwendet, die von der virtuellen Tastatur erstellt wurde.

Hinzufügen von Tastaturlayouts

Das Plugin kann Tastaturlayouts für die virtuelle Tastatur hinzufügen, indem es die Layoutdateien in die Qt-Ressourcen der Plugin-Binärdatei aufnimmt.

Die virtuelle Tastatur sucht nach den Tastaturlayouts (pro Sprache) in einem bestimmten Pfad /qt-project.org/imports/QtQuick/VirtualKeyboard/Layouts/<language_COUNTRY>, daher ist es wichtig, diesen Pfad auch im Plugin zu verwenden. Qt-Ressourcenpfade können sich überschneiden, was bedeutet, dass das Plugin bestehende Layouts auf der virtuellen Tastatur überschreiben kann.

Es ist auch möglich, die eingebauten Tastaturlayouts zu überschreiben, indem man sie direkt aus dem Dateisystem lädt, indem man die Umgebungsvariable QT_VIRTUALKEYBOARD_LAYOUT_PATH verwendet.

Hinzufügen einer Eingabemethode

Das Plugin kann eine Eingabemethode registrieren, die andere Tastaturlayouts standardmäßig verwenden können (z.B. DefaultInputMethod) oder eine Eingabemethode, die privat im Plugin verwendet wird (indem man auch ein benutzerdefiniertes Tastaturlayout bereitstellt, das die Eingabemethode erstellt).

Die Eingabemethode muss eine QVirtualKeyboardAbstractInputMethod (C++) oder InputMethod (QML) Schnittstelle implementieren und muss vom Plugin als QML-Typ (QML_NAMED_ELEMENT) registriert werden.

Implementierung einer benutzerdefinierten Eingabemethode

Die Implementierung von Eingabemethoden beginnt mit der Entscheidung, welche Schnittstelle verwendet wird, QML oder C++. In diesem Beispiel wird die QML-Schnittstelle verwendet. Die gleiche Logik und die gleichen Schnittstellen gelten für die C++-Schnittstelle QVirtualKeyboardAbstractInputMethod. In diesem Fall muss das Plugin mit dem VirtualKeyboard-Modul verknüpft werden.

Das folgende Beispiel zeigt die Mindestfunktionalität, die von einer Eingabemethode gefordert wird:

// Copyright (C) 2016 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause

import QtQuick
import QtQuick.VirtualKeyboard

// file: CustomInputMethod.qml

InputMethod {
    function inputModes(locale) {
        return [InputEngine.InputMode.Latin];
    }

    function setInputMode(locale, inputMode) {
        return true
    }

    function setTextCase(textCase) {
        return true
    }

    function reset() {
        // TODO: reset the input method without modifying input context
    }

    function update() {
        // TODO: commit current state and update the input method
    }

    function keyEvent(key, text, modifiers) {
        var accept = false
        // TODO: Handle key and set accept or fallback to default processing
        return accept;
    }
}

Die Methode InputMethod::inputModes() wird von der Eingabe-Engine aufgerufen, bevor ein Eingabemodus gesetzt wird. Die Methode gibt eine Liste der im angegebenen Gebietsschema verfügbaren Eingabemodi zurück.

Eine Eingabemethode wird in der Methode InputMethod::setInputMode() mit einem Gebietsschema und einem Eingabemodus initialisiert. Nach dem Setzen des Gebietsschemas und des Eingabemodus sollte die Eingabemethode einsatzbereit sein.

InputMethod::reset() wird aufgerufen, wenn eine Eingabemethode zurückgesetzt werden muss. Das Zurücksetzen darf nur den internen Zustand der Eingabemethode zurücksetzen, nicht aber den Benutzertext.

InputMethod::update() wird aufgerufen, wenn der Eingabekontext aktualisiert wird und der Eingabezustand möglicherweise nicht mehr synchron ist. Die Eingabemethode sollte den aktuellen Text übernehmen.

Die Tastendruckereignisse werden in InputMethod::keyEvent() behandelt. Diese Methode verarbeitet ein einzelnes Tastendruckereignis und gibt true zurück, wenn das Ereignis verarbeitet wurde. Andernfalls wird der Tastenanschlag von der Standard-Eingabemethode verarbeitet.

Auswahllisten

Auswahllisten sind eine optionale Funktion, die in die Eingabemethode integriert werden kann. Das Eingabeframework unterstützt verschiedene Arten von Listen, wie z.B. die Wortkandidatenliste. Die Zuständigkeiten bei der Implementierung der Listen werden so gehandhabt, dass die Eingabemethode für den Inhalt und die Aktivitäten, wie z. B. das Klickverhalten, verantwortlich ist. Das Input-Framework ist für die Pflege des Listenmodells und die Übergabe an die Benutzeroberfläche zuständig.

Zuweisung der Auswahllisten

Auswahllisten werden zugewiesen, wenn die Eingabemethode aktiviert wird. Die Methode InputMethod::selectionLists() gibt eine Liste der benötigten Auswahllistentypen zurück:

function selectionLists() {
    return [SelectionListModel.Type.WordCandidateList];
}

Im obigen Beispiel weist die Eingabemethode die Wortkandidatenliste für ihre Verwendung zu.

Aktualisieren der Auswahllisten

Wenn die Eingabemethode die Benutzeroberfläche auffordert, den Inhalt einer Auswahlliste zu aktualisieren, gibt sie das Signal InputMethod::selectionListChanged aus. Wenn die Eingabemethode die Benutzeroberfläche auffordert, ein Element in der Liste zu markieren, wird das Signal InputMethod::selectionListActiveItemChanged ausgegeben.

selectionListChanged(SelectionListModel.Type.WordCandidateList)
selectionListActiveItemChanged(SelectionListModel.Type.WordCandidateList, wordIndex)

Auffüllen der Einträge in den Auswahllisten

Die Elemente werden mit Methoden-Callbacks gefüllt, die sowohl die Anzahl der Elemente in einer Liste als auch die Daten für einzelne Elemente liefern.

Der InputMethod::selectionListItemCount Callback fragt die Anzahl der Elemente in der Liste ab, die durch den angegebenen Typ identifiziert wird.

function selectionListItemCount(type) {
    if (type == SelectionListModel.Type.WordCandidateList) {
        return wordList.length
    }
    return 0
}

Der InputMethod::selectionListData Callback fordert die Daten für die Elemente an.

function selectionListData(type, index, role) {
    var result = null
    if (type == SelectionListModel.Type.WordCandidateList) {
        switch (role) {
        case SelectionListModel.Role.Display:
            result = wordList[index]
            break
        default:
            break
        }
    }
    return result
}

Der Parameter role gibt an, welche Daten für ein Element angefordert werden. Zum Beispiel fordert SelectionListModel.Role.Display die Anzeigetextdaten an.

Reagieren auf Benutzeraktionen

Wenn der Benutzer ein Element in der Liste auswählt, antwortet die Eingabemethode auf das Ereignis im Callback der Methode InputMethod::selectionListItemSelected.

function selectionListItemSelected(type, index) {
    if (type == SelectionListModel.Type.WordCandidateList) {
        inputContext.commit(wordlist[index])
        update()
    }
}

Integration von Handschrifterkennung

Eine Eingabemethode kann auch Eingabedaten vom Touchscreen oder anderen Eingabegeräten verwenden.

Wenn die Eingabe beginnt, ruft die virtuelle Tastatur die Funktion traceBegin der Eingabemethode auf, die ein neues Trace Objekt zurückgibt, in dem die Eingabe im Namen der Eingabemethode gesammelt wird. Wenn der Finger oder der Stift angehoben wird, wird das Ereignis mit dem Aufruf traceEnd beendet. Die Eingabemethode verarbeitet die gesammelten Daten und gibt den Text über die Schnittstelle InputContext aus.

Es gibt vordefinierte Tastaturlayouts für die Handschrift. Sie sind jedoch nicht standardmäßig enthalten, und das Handschrift-Plugin sollte sie in seine eigenen Ressourcen aufnehmen. Beispiele dafür finden Sie in den vorhandenen Plugins für Handschrift von MyScript oder Cerence.

Datenmodell für handschriftliche Eingaben

Virtual Keyboard sammelt die Handschriftdaten in einem speziellen Datenmodell QVirtualKeyboardTrace. Jede Spur stellt eine Sammlung von Daten dar, die bei einer Berührung (z. B. einem Wischen über den Bildschirm) erfasst werden. Es gibt so viele Instanzen von QVirtualKeyboardTrace, wie es Berührungen auf dem handschriftlichen Eingabebereich gibt.

Definitionsgemäß ist eine Spur ein Satz von Daten, die von einer Berührung abgetastet werden. Zusätzlich zu den grundlegenden Punktdaten können sie auch andere Datentypen enthalten, wie z. B. die Zeit jedes Punktes. Die Eingabemethode kann die gewünschten Eingabekanäle zu Beginn eines Trace-Ereignisses definieren.

Die Eingabemethode ist nicht an der eigentlichen Erfassung der Trace-Daten beteiligt. Die Eingabemethode hat jedoch die volle Kontrolle über die Eingabe, da sie eine QVirtualKeyboardTrace entweder annehmen oder ablehnen kann (z. B. wenn zu viele Instanzen zu verarbeiten sind). Dies ermöglicht auch eine genaue Kontrolle darüber, wie viele Finger gleichzeitig verwendet werden können.

Die Eingabemethode kann so viele Spuren sammeln, wie sie für sinnvoll erachtet, und bei Bedarf mit deren Verarbeitung beginnen. Die Verarbeitung kann sogar parallel erfolgen, während die Daten abgetastet werden, obwohl dies wegen der möglichen Leistungsprobleme nicht empfohlen wird. Es wird empfohlen, die Verarbeitung in einem Hintergrund-Thread nach einer angemessenen Verzögerung nach der letzten Eingabe zu starten, damit die Verarbeitung die Benutzeroberfläche nicht negativ beeinflusst.

Trace-API für Eingabemethoden

Die Trace-API besteht aus den folgenden virtuellen Methoden, die die Eingabemethode implementieren muss, um Trace-Eingabedaten zu empfangen und zu verarbeiten.

• patternRecognitionModes
• traceBegin
• traceEnd

Durch die Implementierung dieser Methoden kann die Eingabemethode Daten aus einer Vielzahl von Eingabequellen (z. B. Tastaturlayout oder Vollbild) empfangen und verarbeiten.

Die Methode patternRecognitionModes gibt eine Liste von Mustererkennungsmodi zurück, die von der Eingabemethode unterstützt werden. Ein Mustererkennungsmodus, wie z. B. Handwriting , definiert die Methode, mit der die Eingabemethode die Daten verarbeitet.

Die Trace-Interaktion wird gestartet, wenn eine Eingabequelle einen neuen Kontaktpunkt erkennt und die Methode traceBegin für ein neues Trace-Objekt aufruft. Wenn die Eingabemethode die Interaktion akzeptiert, erstellt sie ein neues Trace-Objekt und gibt es an den Aufrufer zurück. Von diesem Zeitpunkt an werden Trace-Daten gesammelt, bis die traceEnd-Methode aufgerufen wird.

Wenn die traceEnd-Methode aufgerufen wird, kann die Eingabemethode mit der Verarbeitung der im Trace-Objekt enthaltenen Daten beginnen. Nach der Verarbeitung der Daten sollte die Eingabemethode das Objekt zerstören. Dadurch wird auch die auf dem Bildschirm dargestellte Spur entfernt.

Tastatur-Layouts

Tastaturlayouts befinden sich im Verzeichnis src/layouts/builtin. Jedes Unterverzeichnis des Layout-Verzeichnisses steht für ein Gebietsschema. Das Gebietsschema-Verzeichnis ist eine Zeichenkette der Form "language_country", wobei language ein kleingeschriebener, zweibuchstabiger ISO-639-Sprachcode und country ein großgeschriebener, zwei- oder dreibuchstabiger ISO-3166-Ländercode ist.

Layout-Typen

In verschiedenen Eingabemodi werden unterschiedliche Tastaturlayouts verwendet. Das Standardlayout, das für die reguläre Texteingabe verwendet wird, wird als "Hauptlayout" bezeichnet. Der Layouttyp wird durch den Namen der Layoutdatei bestimmt. Daher heißt die "main"-Layoutdatei "main.qml".

Liste der unterstützten Layouttypen:

• main Das Hauptlayout für normale Texteingabe
• symbols Symbol-Layout für Sonderzeichen usw. (wird vom Hauptlayout aus aktiviert)
• numbers Numerisches Layout für formatierte Zahlen (aktiviert durch Qt::ImhFormattedNumbersOnly)
• digits Nur-Ziffern-Layout (aktiviert durch Qt::ImhDigitsOnly)
• dialpad Wähltasten-Layout für die Rufnummerneingabe (aktiviert durch Qt::ImhDialableCharactersOnly)
• handwriting Handschrift-Layout für die Handschrifterkennung (aktiviert vom Hauptlayout aus)

Hinzufügen neuer Tastatur-Layouts

Das Tastaturlayout-Element muss auf dem QML-Typ KeyboardLayout basieren. Dieser Typ definiert das Wurzelelement des Layouts. Das Stammelement hat die folgenden optionalen Eigenschaften, die bei Bedarf festgelegt werden können:

Neue Zeilen werden der Tastaturbelegung mit dem Typ KeyboardRow hinzugefügt. Die KeyboardRow kann auch die Standardtastengewichtung für ihre untergeordneten Elemente festlegen. Andernfalls wird die Tastengewichtung von seinem übergeordneten Element geerbt.

Neue Tasten werden der Tastaturzeile mit dem Typ Key oder einem der speziellen Tastentypen hinzugefügt. Nachfolgend finden Sie eine Liste aller Tastentypen:

Zum Beispiel, um eine reguläre Taste hinzuzufügen, die ein Tastenereignis an die Eingabemethode sendet:

import QtQuick
import QtQuick.VirtualKeyboard
import QtQuick.VirtualKeyboard.Components

// file: en_GB/main.qml

KeyboardLayout {
    keyWeight: 160
    KeyboardRow {
        Key {
            key: Qt.Key_Q
            text: "q"
        }
    }
}

Berechnung der Tastengröße

Die Tastaturlayouts sind skalierbar, d. h., es können keine festen Größen für die Elemente im Layout festgelegt werden. Stattdessen werden die Tastenbreiten anhand des Tastengewichts im Verhältnis zueinander und der Höhe berechnet, indem der Platz gleichmäßig auf die Tastaturzeilen verteilt wird.

Im obigen Beispiel wird die Tastengröße von den übergeordneten Elementen in dieser Reihenfolge geerbt:

Taste > KeyboardRow > KeyboardLayout

Der effektive Wert für die Tastengröße beträgt 160. Für das Beispiel fügen wir eine weitere Taste hinzu, die eine benutzerdefinierte Tastengewichtung angibt:

import QtQuick
import QtQuick.VirtualKeyboard
import QtQuick.VirtualKeyboard.Components

// file: en_GB/main.qml

KeyboardLayout {
    keyWeight: 160
    KeyboardRow {
        Key {
            key: Qt.Key_Q
            text: "q"
        }
        Key {
            key: Qt.Key_W
            text: "w"
            keyWeight: 200
        }
    }
}

Jetzt beträgt die Gesamttastenlast einer Zeile 160 + 200 = 360. Wenn das Tastaturlayout aktiviert ist, wird die Breite einer einzelnen Taste wie folgt berechnet:

Tastenbreite in Pixel = Tastengewicht / SUM(Tastengewichte in einer Zeile) * Zeilenbreite in Pixel

Dies bedeutet, dass die Tastatur auf jede beliebige Größe skaliert werden kann, während die relativen Tastengrößen gleich bleiben.

Alternative Tasten

Key kann eine alternativeKeys-Eigenschaft angeben, die zu einem Popup führt, das alternative Tasten auflistet, wenn der Benutzer die Taste drückt und hält. Die Eigenschaft alternativeKeys kann entweder eine Zeichenkette oder eine Liste von Zeichenketten enthalten. Wenn alternativeKeys eine Zeichenkette ist, kann der Benutzer zwischen den Zeichen der Zeichenkette wählen.

Stile und Layouts

In den Tastaturlayouts können keine visuellen Elemente angegeben werden. Stattdessen wird das Layout durch den Tastaturstil visualisiert. Andererseits kann der Tastaturstil die Größe des Tastaturlayouts nicht beeinflussen.

Tastaturlayouts mit mehreren Tastenseiten

Einige Tastaturlayouts, wie z. B. Symbollayouts, können mehr Tasten enthalten, als in einem einzigen Tastaturlayout dargestellt werden können. Eine Lösung besteht darin, mehrere Tastaturlayouts in denselben Kontext einzubetten, indem die KeyboardLayoutLoader verwendet wird.

Wenn KeyboardLayoutLoader als Stammelement eines Tastaturlayouts verwendet wird, werden die eigentlichen Tastaturlayouts in Komponentenelemente verpackt. Das Tastaturlayout wird aktiviert, indem der Eigenschaft sourceComponent die ID einer aktiven Komponente zugewiesen wird.

Zum Beispiel:

import QtQuick
import QtQuick.VirtualKeyboard
import QtQuick.VirtualKeyboard.Components

// file: en_GB/symbols.qml

KeyboardLayoutLoader {
    property bool secondPage
    onVisibleChanged: if (!visible) secondPage = false
    sourceComponent: secondPage ? page2 : page1
    Component {
        id: page1
        KeyboardLayout {
            KeyboardRow {
                Key {
                    displayText: "1/2"
                    functionKey: true
                    onClicked: secondPage = !secondPage
                }
            }
        }
    }
    Component {
        id: page2
        KeyboardLayout {
            KeyboardRow {
                Key {
                    displayText: "2/2"
                    functionKey: true
                    onClicked: secondPage = !secondPage
                }
            }
        }
    }
}

Handschrift-Tastaturlayout

Jede Sprache, die Handschrifterkennung unterstützt, muss ein spezielles Tastaturlayout namens handwriting.qml bereitstellen.

Dieser Typ von Tastaturlayout muss die folgenden Anforderungen erfüllen:

• enthält eine TraceInputKey im Tastaturlayout
• bietet eine Instanz von HandwritingInputMethod als Eingabemethode.

Das Handschrift-Layout kann auch ChangeLanguageKey enthalten. Zu diesem Zweck ist es wichtig, das Attribut customLayoutsOnly zu verwenden, das Sprachen herausfiltert, die keine Handschrift verwenden.

Sowohl das Haupt- als auch das Handschrift-Layout sollten eine Taste zum Aktivieren und Deaktivieren des handschriftlichen Eingabemodus enthalten. Dies kann durch Hinzufügen eines HandwritingModeKey zum Layout erfolgen.

Hinzufügen eigener Layouts

Das System für virtuelle Tastaturlayouts unterstützt sowohl integrierte Layouts als auch benutzerdefinierte Layouts. Die eingebauten Layouts sind als Qt-Ressourcen in die Plugin-Binärdatei eingebettet. Benutzerdefinierte Layouts befinden sich im Dateisystem, so dass sie installiert werden können, ohne die virtuelle Tastatur selbst neu zu kompilieren, oder sie können in einer Ressourcendatei gespeichert werden.

Die Auswahl der Layouts zur Laufzeit wird durch die Umgebungsvariable QT_VIRTUALKEYBOARD_LAYOUT_PATH beeinflusst.

Falls die Umgebungsvariable nicht gesetzt ist oder ein ungültiges Verzeichnis enthält, greift die virtuelle Tastatur auf die standardmäßig eingebauten Layouts zurück.

Um zu verhindern, dass die eingebauten Layouts in das virtuelle Tastatur-Plugin eingebaut werden, wenn benutzerdefinierte Layouts verwendet werden, fügen Sie die Option -no-vkb-layouts zum Skript configure hinzu. Weitere Informationen finden Sie unter Konfigurationsoptionen.

Tastaturstile

Das Styling-System für die virtuelle Tastatur unterstützt sowohl eingebaute als auch benutzerdefinierte Stile. Die eingebauten Stile sind als Qt-Ressourcen in die Plugin-Binärdatei eingebettet und die benutzerdefinierten Stile befinden sich im Dateisystem und können installiert werden, ohne die virtuelle Tastatur selbst neu zu kompilieren.

Die Auswahl des Laufzeitstils wird durch eine Umgebungsvariable QT_VIRTUALKEYBOARD_STYLE beeinflusst, die auf den Namen des eingebauten Stils gesetzt werden kann, z.B. "retro", oder auf einen der benutzerdefinierten Stile, die im Styles-Verzeichnis installiert sind:

$$[QT_INSTALL_QML]/QtQuick/VirtualKeyboard/Styles

Falls die Umgebungsvariable nicht gesetzt ist oder einen ungültigen Stilnamen enthält, fällt die virtuelle Tastatur auf den eingebauten Standardstil zurück.

Hinzufügen von benutzerdefinierten Stilen

Die Erstellung eines neuen Styles beginnt mit der Erstellung eines neuen Unterverzeichnisses für den Style in einem QML-Importpfad unter der URL-basierten Verzeichnisstruktur QtQuick/VirtualKeyboard/Styles/. Informationen zu QML-Importpfaden finden Sie unter QML-Importpfad. Der Verzeichnisname darf keine Leerzeichen oder Sonderzeichen außer dem Unterstrich enthalten. Außerdem darf der Verzeichnisname nicht mit einem der integrierten Stile übereinstimmen, zu denen derzeit "default" und "retro" gehören.

Ein guter Ausgangspunkt für die Erstellung eines neuen Stils ist es, einen vorhandenen integrierten Stil als Vorlage zu verwenden und ihn zu bearbeiten. Sie finden die eingebauten Stile im Verzeichnis src/styles/builtin der virtuellen Tastaturquellen. Kopieren Sie eines der Verzeichnisse, die einen eingebauten Stil enthalten, in das Styles-Verzeichnis und benennen Sie es in "test" um. Die Verzeichnisstruktur sollte nun wie folgt aussehen:

test/default_style.qrc
test/style.qml
test/images
test/images/backspace.png
test/images/check.png
test/images/enter.png
test/images/globe.png
test/images/hidekeyboard.png
test/images/search.png
test/images/shift.png

Die QRC-Konfigurationsdatei, die in diesem Fall unnötig ist, kann sicher entfernt werden.

Als nächstes öffnen Sie die Datei style.qml in Ihrem bevorzugten Editor und setzen die Eigenschaft resourcePrefix auf eine leere Zeichenkette. Das Ressourcen-Präfix wird nicht benötigt, da sich die Ressourcen im gleichen Verzeichnis wie die Datei style.qml befinden.

Um besser erkennen zu können, dass der benutzerdefinierte Stil tatsächlich geladen und verwendet wird, setzen Sie den Tastaturhintergrund auf eine andere Farbe:

keyboardBackground: Rectangle {
    color: "gray"
}

Der letzte Schritt besteht darin, die Beispielanwendung mit Ihrem benutzerdefinierten Stil auszuführen:

QT_VIRTUALKEYBOARD_STYLE=test virtualkeyboard

Verwendung von Qt Virtual Keyboard mit QQuickWidget

Bei der Verwendung von Qt Virtual Keyboard in einem QQuickWidget auf einem Touch-Gerät ist es notwendig, das Attribut Qt::WA_AcceptTouchEvents über QWidget::setAttribute() zu setzen. Ohne dieses Attribut werden Ereignisse von einem Touch-Gerät in synthetische Mausereignisse umgewandelt.