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 the bundled 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) |
panelBlocked | bool | (derived) | Read-only. true when a Config or Layout error hides the key grid (see Error handling) |
languagePopup | LnLanguagePopup | (internal alias) | Alias to the built-in language picker popup. Exposes the private Ln.VirtualKeyboard.Private type; prefer the long-press space bar behavior unless you need to call show() programmatically |
| Theme overrides: see Theming | |||
maxWidth / maxHeight default to -1 (full parent width / unconstrained height). The Lnvk singleton defaults maxWidth to 600 when set directly; set VirtualKeyboard.maxWidth explicitly when you rely on the component wrapper.
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, predictionEnabled, nextWordEnabled) |
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 | yes | 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 the current profile's predictionEnabled and the 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 (property assignment uses the same path; check lastError on failure) |
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 (see Languages — Finding profiles) |
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 | Unknown layoutId or missing layout data |
InvalidLayoutPage | Layout | Page index out of range |
SwitchLayoutFailed | Layout | switchLayout() page unavailable |
InvalidPredictionPath | Prediction | Custom .pred path missing or wrong extension |
ThemeLoadFailed | Theme | Bundled themes.lntheme missing, corrupt, or record not found for the requested theme |
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.
The QML plugin library exports exactly this API (FontPaths, KeyboardManager, LnvkError, VirtualKeyboardPlugin) plus the Qt plugin entry points; everything else inside it is hidden. To call the API, link your application against the plugin and let the dynamic loader find the same file the QML engine loads (Linux shown):
target_link_libraries(myapp PRIVATE "${LNVK_QML_DIR}/Ln/VirtualKeyboard/liblnvirtualkeyboardplugin.so")
# Relocatable dist layout (ln_virtual_keyboard_deploy: bin/ next to qml/):
set_target_properties(myapp PROPERTIES INSTALL_RPATH "$ORIGIN/../qml/Ln/VirtualKeyboard")
The $ORIGIN form only fits that relocatable layout. On a Yocto image (meta-lnvk) the plugin lives in ${libdir}/qml/Ln/VirtualKeyboard, so the application needs an absolute RPATH to that directory: /usr/lib/qml/Ln/VirtualKeyboard with the default OE paths. The headers (include/lnvk/) ship only in the separate SDK archive; the Yocto layer installs no headers.
The QML engine then reuses the already loaded library, so C++ calls and Lnvk in QML act on one instance. For the same reason the SDK ships no static lnvk_qt archive: a second copy next to the loaded plugin would duplicate every singleton.
See Languages for input profiles, Theming for fonts, and Configuration for custom prediction dictionaries.