Offer Products Case Studies Expertises About us Contact Blog
FR EN

API Reference

VirtualKeyboard component

Instantiate once per application inside your root Window or ApplicationWindow.

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

Properties

PropertyTypeDefaultDescription
maxWidthreal-1Maximum keyboard width
maxHeightreal-1Maximum keyboard height
inputProfileslist<object>(bundled defaults)Optional; omit to use the bundled profiles
activeProfileIdslist<string>["en-qwerty"]Enabled profile IDs
currentProfileIdstring"en-qwerty"Active profile ID
themeenumDarkLnvk.Dark / Lnvk.Light
numberRowEnabledboolfalsePersistent number row
predictionEnabledbooltrueWord prediction
rememberLearningbooltruePersist learned words
customPredictionModeenumLnvk.DisabledCustom prediction source policy (Lnvk.Disabled, Lnvk.Replace, Lnvk.Supersede)
panelBlockedbool(derived)Read-only. true when a Config or Layout error hides the key grid (see Error handling)
languagePopupLnLanguagePopup(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

PropertyTypeDefaultWritableDescription
visibleboolfalseyesKeyboard visibility
lastErrorobject(empty)noMost recent API failure (LnvkError; see Error handling)
inputProfileslist<object>(bundled)noFull profile list (use setInputProfiles())
activeProfileIdslist<string>["en-qwerty"]noEnabled profile IDs (use setActiveProfileIds())
activeProfileslist<object>(from ids)noEnabled profile objects (id, languageTag, layoutId, displayName, imeEngineId, predictionEnabled, nextWordEnabled)
currentProfileIdstring"en-qwerty"noActive profile ID (use setCurrentProfileId())
currentLanguagestring"en"noBCP 47 tag of the active profile
currentDisplayNamestring"English"noDisplay name of the active profile
shiftStateintOffnoOff, Shifted, or CapsLock
layoutPageint0noCurrent layout page
inputMethodHintsint0noHints from focused field
composingTextstring""noIn-progress IME text
keyboardHeightreal260noCurrent computed height
maxWidthreal600yesMaximum width
maxHeightreal-1yesMaximum height
themeenumDarkyesAssign Lnvk.theme = Lnvk.Dark (or Lnvk.Light); use setTheme() when you need a bool result
effectiveFontFamilystring—noRead-only per-script rendering family from registered fonts. Bind as font.family: Lnvk.effectiveFontFamily
numberRowEnabledboolfalseyesPersistent number row
predictionEnabledbooltrueyesWord prediction
effectivePredictionEnabledbooltruenoPrediction after the current profile's predictionEnabled and the hint mask (inputMethodHints)
imeInteractionEnabledbooltruenoIME compose and post-commit suggestions after hint mask
rememberLearningbooltrueyesPersist learned words
customPredictionModeenumLnvk.DisabledyesCustom prediction policy (Lnvk.Disabled, Lnvk.Replace, Lnvk.Supersede)

Methods

MethodReturnsDescription
setInputProfiles(list profiles)boolReplace full profile list
setActiveProfileIds(list ids)boolSet enabled profile IDs
setCurrentProfileId(string id)boolSet active profile
selectProfile(string id)boolSwitch to a profile by ID
selectLanguage(string bcp47)boolSwitch to the first active profile with this language tag
switchLayout(int page)boolSwitch layout page
setTheme(enum theme)boolLoad bundled dark/light theme (property assignment uses the same path; check lastError on failure)
setCustomPredictionDictionary(string languageTag, string predFilePath)boolSet custom .pred file for one language/tag
clearCustomPredictionDictionary(string languageTag)boolClear one language/tag custom dictionary
clearError()—Clear lastError after the host has handled it
profilesForLanguageTag(string languageTag)listAll configured profiles with this exact languageTag (see Languages — Finding profiles)
displayName(string bcp47)stringGeneric display name for a language tag
profileDisplayName(string id)stringDisplay 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:

FieldTypeDescription
Lnvk.lastError.categoryintLnvkErrors.LnvkErrorCategory.* (Config, Layout, Prediction, Theme)
Lnvk.lastError.codeintLnvkErrors.LnvkErrorCode.* (see table below)
Lnvk.lastError.messagestringHuman-readable explanation
Lnvk.lastError.contextobjectMachine-readable details (for example requestedId, layoutId, path)
Lnvk.lastError.isValidbooltrue 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

CodeCategoryTypical cause
InvalidInputProfilesConfigBad profile object (missing id, unknown layout, invalid imeEngineId)
InvalidActiveProfileIdsConfigUnknown or duplicate id in activeProfileIds
InvalidCurrentProfileIdConfigcurrentProfileId not in active list
ProfileNotFoundConfigselectProfile() id missing or inactive
LanguageNotFoundConfigselectLanguage() tag not among active profiles
InvalidKeyboardRootConfigregisterKeyboardRoot() not given a QQuickItem
LayoutLoadFailedLayoutUnknown layoutId or missing layout data
InvalidLayoutPageLayoutPage index out of range
SwitchLayoutFailedLayoutswitchLayout() page unavailable
InvalidPredictionPathPredictionCustom .pred path missing or wrong extension
ThemeLoadFailedThemeBundled 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.