Qt Virtual Keyboard Présentation

Fonctionnalités

Les principales fonctionnalités de l'Qt Virtual Keyboard, sont les suivantes :

• Des dispositions et des styles de clavier personnalisables avec changement dynamique.
• Saisie de texte prédictive avec sélection des mots.
• Aperçu des caractères et affichage des caractères alternatifs.
• Mise en majuscule et insertion d’espaces automatiques.
• Adaptabilité à différentes résolutions.
• Prise en charge de différents jeux de caractères (latin, chinois simplifié/traditionnel, hindi, japonais, arabe, hébreu, coréen et autres).
• Prise en charge des langues de saisie les plus courantes, avec possibilité d'étendre facilement la prise en charge linguistique.
• Saisie de gauche à droite et de droite à gauche.
• Prise en charge des touches matérielles pour la navigation à 2 et 5 directions.
• Prise en charge de l'écriture manuscrite, avec des gestes pour la saisie en plein écran.
• Retour audio.
• Fonctionnalité multiplateforme.
• Prise en charge des applications «Qt Quick » et « Qt Widgets ».

Langues prises en charge

Le clavier virtuel prend en charge les langues suivantes :

Pour ajouter la prise en charge d'une langue supplémentaire, consultez la section « Ajouter de nouvelles dispositions de clavier ».

Plug-ins tiers

L'Qt Virtual Keyboard e prend en charge les plugins tiers des fournisseurs suivants :

• Saisie avancéeCerence XT9.
• Saisie de textemanuscrite Cerence.
• Reconnaissance de l'écriture manuscriteMyScript Text

Le document «Building Qt Virtual Keyboard » décrit comment intégrer ces plugins dans l'Qt Virtual Keyboard.

Concepts de base

Le projet Qt Virtual Keyboard est un plugin de contexte de saisie Qt qui implémente les interfaces QPlatformInputContextPlugin et QPlatformInputContext. Ces interfaces permettent d’utiliser le plugin en tant que plugin de contexte de saisie de la plateforme dans les applications Qt.

Le plugin lui-même fournit un framework d’entrée prenant en charge plusieurs méthodes de saisie ainsi qu’une interface utilisateur QML pour le clavier virtuel. Le framework d’entrée est extensible via une interface de plugin, ce qui permet de charger des méthodes de saisie et des dispositions de clavier tierces lors de l’exécution.

Le framework d’entrée fournit les interfaces principales suivantes :

• QVirtualKeyboardInputContext: fournit des informations contextuelles pour le clavier virtuel et d’autres composants de saisie. Sert d’interface avec le composant de saisie de texte sous-jacent.
• QVirtualKeyboardInputEngine: expose une API permettant d’intégrer les événements de saisie utilisateur (appuis sur les touches, etc.) et sert d’hôte aux méthodes de saisie.
• QVirtualKeyboardAbstractInputMethod: un type de base pour les méthodes de saisie basées sur C++. La méthode de saisie gère généralement les événements de touche, mais peut également gérer les événements de souris et de saisie tactile.
• InputMethod: un type de base pour les méthodes de saisie basées sur QML. La méthode de saisie gère généralement les événements de touche, mais peut également gérer les événements de souris et de saisie tactile.

Contexte de saisie

Le contexte de saisie est utilisé par le clavier ainsi que par les méthodes de saisie concrètes. ` InputContext ` est une instance singleton hébergée par QML. Une application ne doit pas interagir directement avec le contexte de saisie.

Informations contextuelles

Le contexte de saisie donne accès à des informations contextuelles provenant de l’application. Ces informations comprennent, sans s’y limiter :

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

Paramètres régionaux

Le moteur de clavier virtuel génère la liste des paramètres régionaux pris en charge à partir des répertoires de disposition spécifiques à chaque paramètre régional situés dans layouts/. Chaque répertoire de disposition doit contenir une définition ou une solution de secours pour les types de disposition suivants : pavé numérique, chiffres, écriture manuscrite, disposition principale, nombres et symboles. Les définitions sont implémentées dans des fichiers .qml, tandis que les solutions de secours sont définies par un fichier de remplacement portant l’extension .fallback. Le répertoire layouts/ doit contenir un sous-répertoire fallback/ contenant les définitions pour chaque type de disposition.

Chaque répertoire de disposition peut contenir la définition d’un ou plusieurs types de disposition. Si la disposition spécifique à la locale est identique à celle de la locale de secours, vous pouvez ajouter un fichier de remplacement pour cette disposition, nommé <layout type>.fallback. Cela indique au clavier virtuel d’utiliser la disposition de secours à la place.

Par exemple : vous pouvez ajouter une disposition spécifique à la locale finnoise, qui définit le type de disposition principal dans ` main.qml`. Pour les autres types de disposition, vous optez pour le mécanisme de repli. Votre arborescence ` layouts/ ` ressemblera à ceci :

.
├── 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

Il est impératif que le répertoire layouts/fallback contienne toujours un ensemble complet de fichiers d’implémentation.

L’application peut spécifier la disposition initiale en modifiant la locale par défaut. Cependant, cela doit être effectué avant que l’application n’initialise et ne charge le plugin de méthode de saisie. Si aucune modification n’est apportée à la locale par défaut, la locale système actuelle est utilisée.

La correspondance avec les paramètres régionaux du clavier suit la séquence suivante :

• layouts/<language>_<country>
• layouts/<language>_*
• layouts/fallback – la disposition par défaut ici est en_GB.

Tout d’abord, la locale est comparée au nom complet de la locale. S’il n’y a pas de correspondance exacte, seule la langue de la locale est prise en compte. Enfin, le contenu de ` layouts/fallback ` sert de solution de secours lorsqu’il n’y a pas non plus de correspondance partielle.

Une fois la sélection de la locale effectuée, le clavier met à jour la locale de saisie et le sens de saisie pour qu’ils correspondent à la disposition actuelle. L’application peut recevoir ces informations via l’interface QInputMethod.

En interne, la locale de saisie actuelle est également mise à jour dans QVirtualKeyboardInputEngine et dans les instances de méthode de saisie actuelles.

Moteur de saisie

L’objet moteur de saisie appartient à ` InputContext`. À l’instar de l’ InputContext, il n’existe qu’une seule instance de l’ QVirtualKeyboardInputEngine. Le moteur de saisie contient des fonctions API que le clavier utilise pour mapper les interactions de l’utilisateur, telles que les événements d’appui et de relâchement des touches, vers la méthode de saisie.

Par exemple, les événements liés aux touches du clavier virtuel sont mappés via les méthodes suivantes :

• QVirtualKeyboardInputEngine::virtualKeyPress
• QVirtualKeyboardInputEngine::virtualKeyRelease

Les méthodes susmentionnées sont destinées à l’intégration du clavier virtuel, d’où le terme « virtual » dans leurs noms. Cela signifie également que ces méthodes ne conviennent pas au mappage des frappes physiques. Cela s’explique par le fait que l’action effective n’est exécutée qu’au moment où la touche est relâchée.

Si l’appui sur la touche est interrompu avant l’événement de relâchement de la touche, le clavier appelle la méthode ` QVirtualKeyboardInputEngine::virtualKeyCancel `.

Méthode de saisie

La méthode de saisie est une implémentation concrète du gestionnaire de pression de touche. Sa fonction principale est de gérer les événements de pression de touche et de conserver les informations d’état relatives aux entrées de l’utilisateur. Elle interagit avec l’éditeur de texte via ` QVirtualKeyboardInputContext ` à travers des événements de texte pré-édité ou de touche.

L’instance de la méthode de saisie peut être créée de différentes manières, selon le cas d’utilisation :

• KeyboardLayout::inputMethod: la disposition de clavier peut créer une instance de méthode de saisie dédiée exclusivement à cette disposition. Il convient de noter que cette instance sera détruite lorsque la disposition de clavier changera. Par conséquent, cette méthode est généralement limitée à des cas d’utilisation très restreints.
• KeyboardLayout::createInputMethod(): la disposition de clavier peut créer dynamiquement une méthode de saisie pouvant être utilisée avec cette disposition ainsi qu’avec l’ shared layouts (par exemple, la disposition des symboles). C’est la méthode privilégiée pour créer des méthodes de saisie spécialisées, telles que celles impliquant des langues complexes ou l’écriture manuscrite.
• DefaultInputMethod: le clavier virtuel tente de créer ce type de méthode de saisie au démarrage. Cette instance sera utilisée comme méthode de saisie par défaut pour toutes les dispositions de clavier, sauf si la disposition de clavier utilise une méthode de saisie personnalisée. Cette instance subsiste au-delà des changements de disposition de clavier d’une langue à l’autre et constitue la méthode privilégiée pour créer et remplacer la méthode de saisie par défaut.

Plug-ins du clavier virtuel

Le répertoire src/plugins du clavier virtuel contient les plugins existants pour le clavier virtuel. Ces plugins sont des modules QML standard chargés implicitement par le module QML QtQuick.VirtualKeyboard.Plugins.

Un plugin peut fournir des dispositions de clavier et des méthodes de saisie (généralement les deux). La méthode de saisie utilisée par le clavier virtuel dépend de la disposition de clavier en cours d’utilisation. La disposition de clavier peut fournir une instance d’une méthode de saisie personnalisée via la fonction ` KeyboardLayout.createInputMethod()`. Sinon, la méthode de saisie par défaut (DefaultInputMethod) créée par le clavier virtuel est utilisée.

Ajout de dispositions de clavier

Le plugin peut ajouter des dispositions de clavier pour le clavier virtuel en incluant les fichiers de disposition dans les ressources Qt du binaire du plugin.

Le Qt Virtual Keyboard recherche les dispositions de clavier (par langue) à partir d’un chemin d’accès spécifique : /qt-project.org/imports/QtQuick/VirtualKeyboard/Layouts/<LANGUAGE_COUNTRY>; il est donc essentiel d’utiliser exactement ce chemin d’accès dans le plugin. Les chemins d’accès aux ressources Qt peuvent se chevaucher, ce qui signifie que le plugin peut remplacer les dispositions existantes sur le clavier virtuel.

Il est également possible de remplacer les dispositions de clavier intégrées en les chargeant directement depuis le système de fichiers à l’aide de la variable d’environnement QT_VIRTUALKEYBOARD_LAYOUT_PATH.

Ajout d’une méthode de saisie

Le plugin peut enregistrer une méthode de saisie que d’autres dispositions de clavier peuvent utiliser par défaut (comme DefaultInputMethod) ou une méthode de saisie utilisée en interne par le plugin (en fournissant également une disposition de clavier personnalisée, qui crée la méthode de saisie).

La méthode de saisie doit implémenter une interface QVirtualKeyboardAbstractInputMethod (C++) ou InputMethod (QML) et doit être enregistrée en tant que type QML (QML_NAMED_ELEMENT) par le plugin.

Implémentation d’une méthode de saisie personnalisée

L’implémentation des méthodes de saisie commence par le choix de l’interface à utiliser : QML ou C++. Dans cet exemple, l’interface QML est utilisée. La même logique et les mêmes interfaces s’appliquent à l’interface C++ QVirtualKeyboardAbstractInputMethod. Dans ce cas, le plugin doit être lié au module VirtualKeyboard.

L’exemple suivant illustre les fonctionnalités minimales requises pour une méthode de saisie :

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

import QtQuick
import QtQuick.VirtualKeyboard as VKB

// file: CustomInputMethod.qml

VKB.InputMethod {
    function inputModes(locale) {
        return [VKB.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;
    }
}

La méthode InputMethod::inputModes() est appelée par le moteur de saisie avant la définition d’un mode de saisie. La méthode renvoie une liste des modes de saisie disponibles dans la locale donnée.

Une méthode de saisie est initialisée dans la méthode InputMethod::setInputMode() avec une locale et un mode de saisie. Une fois la locale et le mode de saisie définis, la méthode de saisie devrait être prête à l’emploi.

InputMethod::reset() est appelée lorsqu’une méthode de saisie doit être réinitialisée. La réinitialisation ne doit concerner que l’état interne de la méthode de saisie, et non le texte saisi par l’utilisateur.

InputMethod::update() est appelée lorsque le contexte de saisie est mis à jour et que l’état de saisie est éventuellement désynchronisé. La méthode de saisie doit valider le texte actuel.

Les événements de frappe sont gérés dans la méthode ` InputMethod::keyEvent()`. Cette méthode traite un seul événement de frappe et renvoie ` true ` si l’événement a été traité. Sinon, la frappe est gérée par la méthode de saisie par défaut.

Listes de sélection

Les listes de sélection constituent une fonctionnalité optionnelle pouvant être intégrée à la méthode de saisie. L’infrastructure de saisie prend en charge divers types de listes, telles que la liste de candidats de mots. Les responsabilités liées à la mise en œuvre des listes sont réparties de telle sorte que la méthode de saisie est chargée du contenu et des actions, telles que le comportement au clic. Le framework de saisie est chargé de la gestion du modèle de liste et de sa transmission à l’interface utilisateur.

Allocation des listes de sélection

Les listes de sélection sont allouées lorsque la méthode de saisie est activée. La méthode InputMethod::selectionLists() renvoie une liste des types de listes de sélection requis :

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

Dans l’exemple ci-dessus, la méthode de saisie alloue la liste de candidats pour son utilisation.

Mise à jour des listes de sélection

Lorsque la méthode de saisie demande à l’interface utilisateur de mettre à jour le contenu d’une liste de sélection, elle émet le signal ` InputMethod::selectionListChanged `. De même, si la méthode de saisie demande à l’interface utilisateur de mettre en surbrillance un élément de la liste, elle émet le signal ` InputMethod::selectionListActiveItemChanged `.

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

Remplissage des éléments des listes de sélection

Les éléments sont renseignés à l’aide de callbacks de méthode qui fournissent le nombre d’éléments d’une liste ainsi que les données relatives à chaque élément.

La fonction de rappel ` InputMethod::selectionListItemCount ` demande le nombre d’éléments dans la liste identifiée par le type donné.

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

La fonction de rappel ` InputMethod::selectionListData ` demande les données relatives aux éléments.

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
}

Le paramètre role identifie les données demandées pour un élément. Par exemple, SelectionListModel.Role.Display demande les données de texte d’affichage.

Réponse aux actions de l’utilisateur

Lorsque l’utilisateur sélectionne un élément de la liste, la méthode de saisie répond à l’événement via la fonction de rappel de la méthode ` InputMethod::selectionListItemSelected `.

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

Intégration de la reconnaissance de l'écriture manuscrite

Une méthode de saisie peut également utiliser les données provenant d’un écran tactile ou d’autres périphériques de saisie.

Lorsque la saisie commence, le clavier virtuel appelle la fonction de la méthode de saisie traceBegin , qui renvoie un nouvel objet Trace dans lequel la saisie est collectée pour le compte de la méthode de saisie. De même, lorsque le doigt ou le stylet est retiré, l’événement est terminé par l’appel traceEnd . La méthode de saisie traite les données collectées et génère du texte à l’aide de l’interface InputContext.

Il existe des dispositions de clavier prédéfinies pour l’écriture manuscrite. Cependant, elles ne sont pas incluses par défaut, et le plugin d’écriture manuscrite doit les intégrer dans ses propres ressources. Pour des exemples illustrant cette procédure, consultez les plugins d’écriture manuscrite existants de MyScript ou Cerence.

Modèle de données pour la saisie manuscrite

Le clavier virtuel collecte les données d’écriture manuscrite dans un modèle de données spécifique QVirtualKeyboardTrace. Chaque trace représente un ensemble de données échantillonnées à partir d’un toucher (par exemple, un glissement sur l’écran). Il y aura autant d’instances de ` QVirtualKeyboardTrace ` qu’il y a de touches sur la zone de saisie manuscrite.

Par définition, une trace est un ensemble de données échantillonnées à partir d’un seul toucher. Outre les données de points de base, elle peut également inclure d’autres types de données, telles que l’heure de chaque point. La méthode de saisie peut définir les canaux de saisie souhaités au début d’un événement de trace.

La méthode de saisie ne participe pas à la collecte proprement dite des données de trace. Cependant, elle exerce un contrôle total sur la saisie puisqu’elle peut accepter ou rejeter une « QVirtualKeyboardTrace » (par exemple s’il y a trop d’instances à traiter). Cela permet également de contrôler avec précision le nombre de doigts pouvant être utilisés simultanément.

La méthode d’entrée peut collecter autant de traces qu’elle le juge nécessaire et peut commencer à les traiter lorsque cela s’avère nécessaire. Le traitement peut même être effectué en parallèle pendant l’échantillonnage des données, bien que cela ne soit pas recommandé en raison des problèmes de performances potentiels. La méthode recommandée consiste à lancer le traitement dans un thread d’arrière-plan après un délai approprié suivant la dernière saisie, afin que le traitement n’ait pas d’impact négatif sur l’interface utilisateur.

API de traces pour les méthodes de saisie

L’API de trace se compose des méthodes virtuelles suivantes, que la méthode de saisie doit implémenter afin de recevoir et de traiter les données de trace.

• patternRecognitionModes
• traceBegin
• traceEnd

En implémentant ces méthodes, la méthode de saisie peut recevoir et traiter des données provenant de diverses sources de saisie (par exemple, une disposition de clavier ou un mode plein écran).

La méthode `patternRecognitionModes` renvoie une liste des modes de reconnaissance de motifs pris en charge par la méthode de saisie. Un mode de reconnaissance de motifs, tel que ` Handwriting `, définit la méthode par laquelle la méthode de saisie traite les données.

L’interaction de trace démarre lorsqu’une source de saisie détecte un nouveau point de contact et appelle la méthode `traceBegin` pour créer un nouvel objet de trace. Si la méthode de saisie accepte l’interaction, elle crée un nouvel objet de trace et le renvoie à l’appelant. À partir de ce moment, les données de trace sont collectées jusqu’à ce que la méthode `traceEnd` soit appelée.

Lorsque la méthode `traceEnd` est appelée, la méthode d’entrée peut commencer à traiter les données contenues dans l’objet de trace. Après avoir traité les données, la méthode d’entrée doit détruire l’objet. Cela supprime également la trace affichée à l’écran.

Configurations de clavier

Les dispositions de clavier se trouvent dans le répertoire src/layouts/builtin. Chaque sous-répertoire du répertoire « layout » correspond à une locale. Le nom du répertoire de locale est une chaîne de caractères de la forme « langue_pays », où « langue » est un code de langue ISO 639 à deux lettres en minuscules, et « pays » est un code de pays ISO 3166 à deux ou trois lettres en majuscules.

Types de dispositions

Différents types de dispositions de clavier sont utilisés selon les modes de saisie. La disposition par défaut, utilisée pour la saisie de texte classique, est appelée disposition « main ». Le type de disposition est déterminé par le nom du fichier de disposition. Ainsi, le fichier de disposition « main » s’appelle « main.qml ».

Liste des types de disposition pris en charge :

• main La disposition principale pour la saisie de texte normale
• symbols Disposition « Symboles » pour les caractères spéciaux, etc. (activée à partir de la disposition principale)
• numbers Disposition numérique pour les nombres formatés (activée par Qt::ImhFormattedNumbersOnly)
• digits Mise en page « chiffres uniquement » (activée par Qt::ImhDigitsOnly)
• dialpad Disposition « clavier téléphonique » pour la saisie de numéros de téléphone (activée par Qt::ImhDialableCharactersOnly)
• handwriting Disposition « Écriture manuscrite » pour la reconnaissance de l'écriture manuscrite (activée à partir de la disposition principale)

Ajout de nouvelles dispositions de clavier

L'élément de disposition de clavier doit être basé sur le type QML KeyboardLayout. Ce type définit l'élément racine de la disposition. L'élément racine possède les propriétés facultatives suivantes, qui peuvent être définies si nécessaire :

De nouvelles lignes sont ajoutées à la disposition du clavier à l’aide du type « KeyboardRow ». L’élément « KeyboardRow » peut également spécifier le poids de touche par défaut de ses éléments enfants. Sinon, le poids de touche est hérité de son élément parent.

De nouvelles touches sont ajoutées à la ligne du clavier à l’aide du type « Key » ou de l’un des types de touches spécialisés. Vous trouverez ci-dessous la liste de tous les types de touches :

Par exemple, pour ajouter une touche standard qui envoie un événement de touche à la méthode de saisie :

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

Calcul de la taille des touches

Les dispositions de clavier sont modulables, ce qui signifie qu’aucune taille fixe ne peut être définie pour les éléments de la disposition. À la place, la largeur des touches est calculée à partir de leur poids relatif les unes par rapport aux autres, et leur hauteur en répartissant l’espace de manière égale entre les lignes du clavier.

Dans l’exemple ci-dessus, la taille des touches est héritée des éléments parents dans l’ordre suivant :

Touche > KeyboardRow > KeyboardLayout

La valeur effective du poids de la touche sera de 160. À titre d’exemple, nous ajoutons une autre touche qui spécifie un poids personnalisé :

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

Désormais, le poids total des touches d’une ligne est de 160 + 200 = 360. Lorsque la disposition du clavier est activée, la largeur d’une touche individuelle est calculée comme suit :

largeur de la touche en pixels = poids de la touche / SOMME(poids des touches d’une ligne) * largeur de la ligne en pixels

Cela signifie que le clavier peut être redimensionné à n'importe quelle taille, tandis que les tailles relatives des touches restent identiques.

Touches alternatives

Une touche peut spécifier une propriété `alternativeKeys`, qui fait apparaître une fenêtre contextuelle répertoriant les touches alternatives lorsque l’utilisateur appuie sur la touche et la maintient enfoncée. La propriété `alternativeKeys` peut spécifier soit une chaîne de caractères, soit une liste de chaînes. Si `alternativeKeys` est une chaîne de caractères, l’utilisateur peut choisir parmi les caractères qu’elle contient.

Styles et dispositions

Les dispositions de clavier ne peuvent spécifier aucun élément visuel. C’est le style du clavier qui permet de visualiser la disposition. En revanche, le style du clavier n’a aucune incidence sur la taille de la disposition du clavier.

Dispositions de clavier comportant plusieurs pages de touches

Certaines dispositions de clavier, telles que les dispositions de symboles, peuvent contenir plus de touches qu’il n’est possible d’en afficher sur une seule disposition de clavier. Une solution consiste à intégrer plusieurs dispositions de clavier dans le même contexte à l’aide de l’ KeyboardLayoutLoader.

Lorsque l’élément ` KeyboardLayoutLoader ` est utilisé comme élément racine d’une disposition de clavier, les dispositions de clavier proprement dites sont encapsulées dans des éléments `Component`. La disposition de clavier est activée en attribuant l’identifiant d’un composant actif à la propriété `sourceComponent`.

Par exemple :

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

Disposition de clavier pour l’écriture manuscrite

Chaque langue prenant en charge la reconnaissance de l’écriture manuscrite doit fournir une disposition de clavier spécifique nommée handwriting.qml.

Ce type de disposition de clavier doit répondre aux exigences suivantes :

• contenir un élément « TraceInputKey » dans la configuration de clavier
• fournir une instance de HandwritingInputMethod comme méthode de saisie.

La disposition « écriture manuscrite » peut également inclure des éléments « ChangeLanguageKey ». À cette fin, il est important d’utiliser l’attribut « customLayoutsOnly », qui filtrera les langues n’utilisant pas l’écriture manuscrite.

Les dispositions principale et d'écriture manuscrite doivent toutes deux contenir une touche permettant d'activer et de désactiver le mode de saisie manuscrite. Pour ce faire, il suffit d'ajouter une « HandwritingModeKey » à la disposition.

Ajout de dispositions personnalisées

Le système de dispositions de clavier virtuel prend en charge aussi bien les dispositions intégrées que les dispositions personnalisées. Les dispositions intégrées sont incorporées sous forme de ressources Qt dans le binaire du plugin. Les dispositions personnalisées se trouvent dans le système de fichiers, ce qui permet de les installer sans avoir à recompiler le clavier virtuel lui-même ; elles peuvent également être situées dans un fichier de ressources.

La sélection des dispositions lors de l’exécution est déterminée par la variable d’environnement ` QT_VIRTUALKEYBOARD_LAYOUT_PATH `.

Si cette variable d’environnement n’est pas définie ou contient un répertoire invalide, le clavier virtuel utilise alors les dispositions intégrées par défaut.

Pour empêcher l’intégration des dispositions intégrées dans le plugin du clavier virtuel lorsque vous utilisez des dispositions personnalisées, ajoutez l’option ` -no-vkb-layouts ` au script ` configure `. Pour plus d’informations, consultez la section Options de configuration.

Styles de clavier

Le système de styles du clavier virtuel prend en charge aussi bien les styles intégrés que les styles personnalisés. Les styles intégrés sont incorporés sous forme de ressources Qt dans le binaire du plugin, tandis que les styles personnalisés se trouvent dans le système de fichiers et peuvent être installés sans recompiler le clavier virtuel lui-même.

Le choix du style à l'exécution est déterminé par une variable d'environnement, QT_VIRTUALKEYBOARD_STYLE, qui peut être définie sur le nom d'un style intégré, par exemple « retro », ou sur l'un des styles personnalisés installés dans le répertoire Styles :

$$[QT_INSTALL_QML]/QtQuick/VirtualKeyboard/Styles

Si la variable d’environnement n’est pas définie ou contient un nom de style non valide, le clavier virtuel utilise par défaut le style intégré.

Ajout de styles personnalisés

La création d’un nouveau style commence par la création d’un nouveau sous-répertoire dédié à ce style dans un chemin d’importation QML, au sein de la structure de répertoires basée sur l’URL QtQuick/VirtualKeyboard/Styles/. Voir Chemin d’importation QML pour plus d’informations sur les chemins d’importation QML. Le nom du répertoire ne peut pas contenir d’espaces ni de caractères spéciaux autres que le trait de soulignement. De plus, le nom du répertoire ne peut pas être identique à celui d’un style intégré, qui comprend actuellement « default » et « retro ».

Pour créer un nouveau style, il est conseillé de commencer par utiliser un style intégré existant comme modèle et de le modifier. Vous trouverez les styles intégrés dans le répertoire des sources du clavier virtuel, à l'emplacement src/styles/builtin. Copiez l'un des répertoires contenant un style intégré dans le répertoire Styles et renommez-le « test ». La structure du répertoire devrait désormais se présenter comme suit :

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

Le fichier de configuration QRC, qui n’est pas nécessaire dans ce cas, peut être supprimé sans risque.

Ensuite, ouvrez le fichier style.qml dans votre éditeur préféré et définissez la propriété resourcePrefix sur une chaîne vide. Le préfixe de ressource n’est pas nécessaire, car les ressources se trouvent dans le même répertoire que le fichier style.qml.

De plus, pour voir plus clairement que le style personnalisé est bien chargé et utilisé, définissez une couleur différente pour l’arrière-plan du clavier :

keyboardBackground: Rectangle {
    color: "gray"
}

La dernière étape consiste à exécuter l'application d'exemple avec votre style personnalisé :

QT_VIRTUALKEYBOARD_STYLE=test virtualkeyboard

Utilisation de « Qt Virtual Keyboard » avec QQuickWidget

Lorsque vous utilisez Qt Virtual Keyboard dans une application « QQuickWidget » sur un appareil tactile, il est nécessaire de définir l’attribut « Qt::WA_AcceptTouchEvents » via ` QWidget::setAttribute()`. Si cet attribut n’est pas défini, les événements provenant d’un appareil tactile seront convertis en événements souris synthétisés.