API Reference

VirtualKeyboard component

Instantiate once per application inside your root Window or ApplicationWindow.

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

Properties

Property	Type	Default	Description
`maxWidth`	real	`-1`	Maximum keyboard width
`maxHeight`	real	`-1`	Maximum keyboard height
`inputProfiles`	list<object>	(bundled defaults)	Optional; omit to use all 56 embedded profiles
`activeProfileIds`	list<string>	`["en-qwerty"]`	Enabled profile IDs
`currentProfileId`	string	`"en-qwerty"`	Active profile ID
`theme`	enum	Dark	`Lnvk.Dark` / `Lnvk.Light`
`numberRowEnabled`	bool	`false`	Persistent number row
`predictionEnabled`	bool	`true`	Word prediction
`rememberLearning`	bool	`true`	Persist learned words
`customPredictionMode`	enum	`Lnvk.Disabled`	Custom prediction source policy (`Lnvk.Disabled`, `Lnvk.Replace`, `Lnvk.Supersede`)
Theme overrides: see Theming

Lnvk singleton

Global singleton automatically available after importing Ln.VirtualKeyboard 1.0. Reflects live keyboard state and exposes methods.

Properties

Property	Type	Default	Writable	Description
`visible`	bool	false	yes	Keyboard visibility
`lastError`	object	(empty)	no	Most recent API failure (`LnvkError`; see Error handling)
`inputProfiles`	list<object>	(bundled)	no	Full profile list (use `setInputProfiles()`)
`activeProfileIds`	list<string>	`["en-qwerty"]`	no	Enabled profile IDs (use `setActiveProfileIds()`)
`activeProfiles`	list<object>	(from ids)	no	Enabled profile objects (`id`, `languageTag`, `layoutId`, `displayName`, `imeEngineId`)
`currentProfileId`	string	`"en-qwerty"`	no	Active profile ID (use `setCurrentProfileId()`)
`currentLanguage`	string	`"en"`	no	BCP 47 tag of the active profile
`currentDisplayName`	string	`"English"`	no	Display name of the active profile
`shiftState`	int	Off	no	`Off`, `Shifted`, or `CapsLock`
`layoutPage`	int	0	no	Current layout page
`inputMethodHints`	int	0	no	Hints from focused field
`composingText`	string	`""`	no	In-progress IME text
`keyboardHeight`	real	260	no	Current computed height
`maxWidth`	real	600	yes	Maximum width
`maxHeight`	real	-1	no	Maximum height
`theme`	enum	Dark	yes	Assign `Lnvk.theme = Lnvk.Dark` (or `Lnvk.Light`); use `setTheme()` when you need a `bool` result
`effectiveFontFamily`	string	—	no	Read-only per-script rendering family from registered fonts. Bind as `font.family: Lnvk.effectiveFontFamily`
`numberRowEnabled`	bool	false	yes	Persistent number row
`predictionEnabled`	bool	true	yes	Word prediction
`effectivePredictionEnabled`	bool	true	no	Prediction after hint mask (`inputMethodHints`)
`imeInteractionEnabled`	bool	true	no	IME compose and post-commit suggestions after hint mask
`rememberLearning`	bool	true	yes	Persist learned words
`customPredictionMode`	enum	`Lnvk.Disabled`	yes	Custom prediction policy (`Lnvk.Disabled`, `Lnvk.Replace`, `Lnvk.Supersede`)

Methods

Method	Returns	Description
`setInputProfiles(list profiles)`	bool	Replace full profile list
`setActiveProfileIds(list ids)`	bool	Set enabled profile IDs
`setCurrentProfileId(string id)`	bool	Set active profile
`selectProfile(string id)`	bool	Switch to a profile by ID
`selectLanguage(string bcp47)`	bool	Switch to the first active profile with this language tag
`switchLayout(int page)`	bool	Switch layout page
`setTheme(enum theme)`	bool	Load bundled dark/light theme
`setCustomPredictionDictionary(string languageTag, string predFilePath)`	bool	Set custom `.pred` file for one language/tag
`clearCustomPredictionDictionary(string languageTag)`	bool	Clear one language/tag custom dictionary
`clearError()`	—	Clear `lastError` after the host has handled it
`profilesForLanguageTag(string languageTag)`	list	All configured profiles with this exact `languageTag`
`displayName(string bcp47)`	string	Generic display name for a language tag
`profileDisplayName(string id)`	string	Display name for a profile ID
`clearCustomPredictionDictionaries()`	—	Clear all custom dictionaries
`hide()`	—	Hide the keyboard

Error handling

Configuration, layout, prediction, and theme APIs report failures through a single structured slot on Lnvk:

Field	Type	Description
`Lnvk.lastError.category`	int	`LnvkErrors.LnvkErrorCategory.*` (`Config`, `Layout`, `Prediction`, `Theme`)
`Lnvk.lastError.code`	int	`LnvkErrors.LnvkErrorCode.*` (see table below)
`Lnvk.lastError.message`	string	Human-readable explanation
`Lnvk.lastError.context`	object	Machine-readable details (for example `requestedId`, `layoutId`, `path`)
`Lnvk.lastError.isValid`	bool	`true` when an error is set

Mutating methods return bool: true means the request was fully accepted; false means the call was rejected or sanitized (invalid profile ids dropped, unknown current profile corrected, etc.). Inspect Lnvk.lastError when the return value is 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)
    }
}

// After handling, clear the slot so the panel unblocks (Config/Layout errors hide the key grid)
Lnvk.clearError()

C++ equivalent:

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();

Panel behaviour: VirtualKeyboard hides the key grid when lastError is a Config or Layout error and shows lastError.message. Prediction and theme errors are logged but the keyboard stays usable.

Common error codes

Code	Category	Typical cause
`InvalidInputProfiles`	Config	Bad profile object (missing id, unknown layout, invalid `imeEngineId`)
`InvalidActiveProfileIds`	Config	Unknown or duplicate id in `activeProfileIds`
`InvalidCurrentProfileId`	Config	`currentProfileId` not in active list
`ProfileNotFound`	Config	`selectProfile()` id missing or inactive
`LanguageNotFound`	Config	`selectLanguage()` tag not among active profiles
`InvalidKeyboardRoot`	Config	`registerKeyboardRoot()` not given a `QQuickItem`
`LayoutLoadFailed`	Layout	Missing layout JSON
`InvalidLayoutPage`	Layout	Page index out of range
`SwitchLayoutFailed`	Layout	`switchLayout()` page unavailable
`InvalidPredictionPath`	Prediction	Custom `.pred` path missing or wrong extension
`ThemeLoadFailed`	Theme	Bundled theme JSON could not be loaded

Invalid configuration is still sanitized (graceful fallback to defaults); lastError explains what was corrected.

C++ API

The public C++ API is exposed through a single umbrella header:

#include <lnvk>

This provides lnvk::qt::FontPaths and lnvk::qt::KeyboardManager. With find_package(LNVK), ln_virtual_keyboard_deploy(myapp) adds the include/lnvk/ directory to your target's include path.

See Languages for input profiles, Theming for fonts, and Configuration for custom prediction dictionaries.

← PreviousConfiguration Next →Deployment