Référence API

Composant VirtualKeyboard

À instancier une seule fois par application dans votre Window ou ApplicationWindow racine.

import Ln.VirtualKeyboard 1.0
VirtualKeyboard { width: parent.width }

Propriétés

Propriété	Type	Défaut	Description
`maxWidth`	real	`-1`	Largeur maximale du clavier
`maxHeight`	real	`-1`	Hauteur maximale du clavier
`inputProfiles`	list<object>	(profils embarqués)	Optionnel ; omettre pour utiliser les 56 profils embarqués
`activeProfileIds`	list<string>	`["en-qwerty"]`	IDs de profils activés
`currentProfileId`	string	`"en-qwerty"`	ID du profil actif
`theme`	enum	Dark	`Lnvk.Dark` / `Lnvk.Light`
`numberRowEnabled`	bool	`false`	Rangée de chiffres persistante
`predictionEnabled`	bool	`true`	Prédiction de mots
`rememberLearning`	bool	`true`	Conserver les mots appris
`customPredictionMode`	enum	`Lnvk.Disabled`	Politique de prédiction personnalisée (`Lnvk.Disabled`, `Lnvk.Replace`, `Lnvk.Supersede`)
Surcharges de thème : voir Thèmes

Singleton Lnvk

Singleton global disponible après import Ln.VirtualKeyboard 1.0. Reflète l'état du clavier et expose les méthodes.

Propriétés

Propriété	Type	Défaut	Modifiable	Description
`visible`	bool	false	oui	Visibilité du clavier
`lastError`	object	(vide)	non	Dernière erreur API (`LnvkError` ; voir Gestion des erreurs)
`inputProfiles`	list<object>	(embarqués)	non	Liste complète des profils (utiliser `setInputProfiles()`)
`activeProfileIds`	list<string>	`["en-qwerty"]`	non	IDs de profils activés (utiliser `setActiveProfileIds()`)
`activeProfiles`	list<object>	(depuis les ids)	non	Objets de profils activés (`id`, `languageTag`, `layoutId`, `displayName`, `imeEngineId`)
`currentProfileId`	string	`"en-qwerty"`	non	ID du profil actif (utiliser `setCurrentProfileId()`)
`currentLanguage`	string	`"en"`	non	Tag BCP 47 du profil actif
`currentDisplayName`	string	`"English"`	non	Nom d'affichage du profil actif
`shiftState`	int	Off	non	`Off`, `Shifted` ou `CapsLock`
`layoutPage`	int	0	non	Page de disposition active
`inputMethodHints`	int	0	non	Hints du champ actif
`composingText`	string	`""`	non	Texte IME en cours
`keyboardHeight`	real	260	non	Hauteur calculée actuelle
`maxWidth`	real	600	oui	Largeur maximale
`maxHeight`	real	-1	non	Hauteur maximale
`theme`	enum	Dark	oui	`Lnvk.theme = Lnvk.Dark` (ou `Lnvk.Light`) ; utiliser `setTheme()` pour un résultat `bool`
`effectiveFontFamily`	string	—	non	Famille de rendu en lecture seule. Lier `font.family: Lnvk.effectiveFontFamily`
`numberRowEnabled`	bool	false	oui	Rangée de chiffres persistante
`predictionEnabled`	bool	true	oui	Prédiction de mots
`effectivePredictionEnabled`	bool	true	non	Prédiction après masque de hints (`inputMethodHints`)
`imeInteractionEnabled`	bool	true	non	Composition IME et suggestions post-commit après masque de hints
`rememberLearning`	bool	true	oui	Conserver les mots appris
`customPredictionMode`	enum	`Lnvk.Disabled`	oui	Politique de prédiction personnalisée

Méthodes

Méthode	Retour	Description
`setInputProfiles(list profiles)`	bool	Remplace la liste complète des profils
`setActiveProfileIds(list ids)`	bool	Définit les IDs de profils activés
`setCurrentProfileId(string id)`	bool	Définit le profil actif
`selectProfile(string id)`	bool	Bascule vers un profil par ID
`selectLanguage(string bcp47)`	bool	Premier profil actif avec ce tag de langue
`switchLayout(int page)`	bool	Change de page de disposition
`setTheme(enum theme)`	bool	Charge le thème sombre/clair embarqué
`setCustomPredictionDictionary(string languageTag, string predFilePath)`	bool	Définit un fichier `.pred` personnalisé
`clearCustomPredictionDictionary(string languageTag)`	bool	Efface le dictionnaire personnalisé d'une langue/tag
`clearError()`	—	Efface `lastError` après traitement par l'hôte
`profilesForLanguageTag(string languageTag)`	list	Tous les profils avec ce `languageTag` exact
`displayName(string bcp47)`	string	Nom d'affichage générique pour un tag de langue
`profileDisplayName(string id)`	string	Nom d'affichage pour un ID de profil
`clearCustomPredictionDictionaries()`	—	Efface tous les dictionnaires personnalisés
`hide()`	—	Masque le clavier

Gestion des erreurs

Les APIs de configuration, disposition, prédiction et thème signalent les échecs via un slot structuré sur Lnvk :

Champ	Type	Description
`Lnvk.lastError.category`	int	`LnvkErrors.LnvkErrorCategory.*` (`Config`, `Layout`, `Prediction`, `Theme`)
`Lnvk.lastError.code`	int	`LnvkErrors.LnvkErrorCode.*` (voir tableau ci-dessous)
`Lnvk.lastError.message`	string	Explication lisible
`Lnvk.lastError.context`	object	Détails machine (par ex. `requestedId`, `layoutId`, `path`)
`Lnvk.lastError.isValid`	bool	`true` lorsqu'une erreur est définie

Les méthodes mutantes retournent un bool : true si la requête est entièrement acceptée ; false si elle est rejetée ou assainie (ids invalides retirés, profil courant corrigé, etc.). Inspectez Lnvk.lastError lorsque la valeur est false.

if (!Lnvk.setActiveProfileIds(["en-qwerty", "bad-id"])) {
    console.warn(Lnvk.lastError.code, Lnvk.lastError.message, Lnvk.lastError.context)
}

Connections {
    target: Lnvk
    function onErrorOccurred(err) {
        console.warn("LNVK error", err.code, err.message)
    }
}

// Après traitement, effacer le slot pour débloquer le panneau
Lnvk.clearError()

Équivalent C++ :

auto *km = lnvk::qt::KeyboardManager::instance();
if (!km->setActiveProfileIds({QStringLiteral("bad-id")})) {
    const lnvk::qt::LnvkError err = km->lastError();
    qWarning() << static_cast<int>(err.errorCode()) << err.message() << err.context();
}
km->clearError();

Comportement du panneau : VirtualKeyboard masque la grille de touches pour les erreurs Config ou Layout et affiche lastError.message. Les erreurs Prediction et Theme sont journalisées ; le clavier reste utilisable.

Codes d'erreur courants

Code	Catégorie	Cause typique
`InvalidInputProfiles`	Config	Profil invalide (id manquant, disposition inconnue, `imeEngineId` invalide)
`InvalidActiveProfileIds`	Config	Id inconnu ou dupliqué dans `activeProfileIds`
`InvalidCurrentProfileId`	Config	`currentProfileId` absent de la liste active
`ProfileNotFound`	Config	`selectProfile()` : id manquant ou inactif
`LanguageNotFound`	Config	`selectLanguage()` : tag absent des profils actifs
`InvalidKeyboardRoot`	Config	`registerKeyboardRoot()` sans `QQuickItem`
`LayoutLoadFailed`	Layout	JSON de disposition manquant
`InvalidLayoutPage`	Layout	Index de page hors limites
`SwitchLayoutFailed`	Layout	Page indisponible pour `switchLayout()`
`InvalidPredictionPath`	Prediction	Chemin `.pred` manquant ou extension incorrecte
`ThemeLoadFailed`	Theme	Impossible de charger le JSON de thème embarqué

La configuration invalide est toujours assainie (repli gracieux vers les défauts) ; lastError indique ce qui a été corrigé.

API C++

L'API C++ publique est exposée via un en-tête unique :

#include <lnvk>

Cela fournit lnvk::qt::FontPaths et lnvk::qt::KeyboardManager. Avec find_package(LNVK), ln_virtual_keyboard_deploy(myapp) ajoute le répertoire include/lnvk/ au chemin d'inclusion de votre cible.

Voir Langues pour les profils de saisie, Thème pour les polices et Configuration pour les dictionnaires de prédiction personnalisés.

← PrécédentConfiguration Suivant →Déploiement