Skip to content

Mobile app ‐ app webview API

Jump to bottom
Joshua Horton edited this page Aug 21, 2024 · 3 revisions

There are a number of internal API functions exposed by the app/webview build of Keyman Engine for Web designed to facilitate its (embedded) use within Keyman for Android and Keyman for iOS. These are not intended for general public use of Keyman Engine for Web; some of these components don't even exist within app/browser builds.

Raw list of API endpoints (as of 18.0.92 + 17.0-stable):

  • keyman.config
  • keyman.context
    • .setSelection
    • .setText
  • keyman.core.activeKeyboard.refreshLayouts()
  • keyman.core.languageProcessor.on('statechange')
  • keyman.core.languageProcessor.mayPredict, .mayCorrect
  • keyman.hardKeyboard.raiseKeyEvent(...)
  • keyman.osk.gestureParams
  • keyman.osk.bannerController.inactiveBanner
  • keyman.osk.bannerView.activeBannerHeight
  • keyman.osk.vkbd.currentLayer.globeKey.highlight()

keyman.config

A number of engine configuration options may be set during app/webview initialization on the configuration object passed into keyman.init.

Ones of note:

  • insertText - a method should be provided here that allows app/webview to actively update the host application whenever keyboard rules manipulate the active context.
  • spacebarText - a string-based 'enum' indicating what sort of label to generate for each keyboard on its spacebar keys. Legal values:
    • 'keyboard' - Displays only the keyboard name
    • 'language' - Displays only the language name
    • 'blank' - Does not add a keyboard-specific label to the spacebar
    • 'languageKeyboard' - Adds a label displaying both the language and keyboard name. Pattern: <language> - <keyboard>

Refer to:

keyman.context

keyman.context specifies and represents the active context used for keystroke processing. It should be kept synchronized with the host application's context at all times. If the app's context is changed, this object's methods should be used proactively to update app/webview's context to match.

keyman.context.setText() is used to synchronize the string contents of text, with the caret automatically moved to the end of the resulting context in app/webview. This should generally be followed up with a call to keyman.context.setSelection(), which is used to relocate the caret to the correct position within the context.

`keyman.context.setText(text: string)

Replaces the current app/webview context's content with text, relocating the caret to its end.

`keyman.context.setSelection(start: number, end?: number)

Relocates the caret (selection point) with the current app/webview context to the index indicated by start. If end is not specified, the selection will be of width zero - a standard caret. If end is specified, it will be interpreted as an end-index for the selection.

keyman.core.activeKeyboard.refreshLayouts()

🚧 Upon inspection, this appears to be deprecated as an internal API... but it is still present. 🚧

Intended for use whenever the host WebView is resized, which should also resize the keyboard. In such a case, we need to ensure that keyboard layouts are rebuilt / refreshed - a call here will erase the cached version of the layout so that it will be rebuilt.

keyman.core.languageProcessor.on('statechange', handler: (state: string) => void)

This event signals changes in the activation state for predictive text and the suggestion banner.

Valid states:

  • 'inactive' - no predictive-text model is loaded for the active keyboard
  • 'active' - a predictive-text model is either loaded or loading for the active keyboard
  • 'configured' - the predictive-text model is fully prepared and ready to generate suggestions; the OSK will also be showing a suggestion banner.

keyman.core.languageProcessor.mayPredict, .mayCorrect

These two properties control what parts of the predictive-text engine are available.

  • .mayCorrect - when false, no fat-finger data is utilized for predictive-text operations. Ideally, no text-correction whatsoever should occur.
  • .mayPredict - when false, predictive-text as a whole should be disabled, with no suggestions being generated.

keyman.hardKeyboard.raiseKeyEvent(code: number, shift: number, lstates: number)

This method is intended for processing keystrokes on a physical keyboard paired with the user's mobile device.

  • code - the numeric code for the key's identifier
  • shift - the code for the active shift-state
  • lstates - the code for the active lock-state

These are all defined within web/src/engine/keyboard/src/codes.ts. They are also published from @keymanapp/common-types as ModifierKeyConstants and USVirtualKeyCodes.

  • code - expected values may be found within Codes.keyCodes & USVirtualKeyCodes
  • shift - expected values may be found within Codes.modifierCodes & ModifierKeyConstants - all values 0x00FF and below; before the named constants CAPS / CAPITALFLAG
  • lstates - the remaining entries within Codes.modifierCodes & ModifierKeyConstants.

keyman.osk.gestureParams

Once the OSK has been initialized, the parameterization for touch-based gestures within the OSK may be found here. Changes to its values will apply immediately to any new gestures for the lifetime of the embedded app/webview instance (unless the keyman.osk instance itself is swapped out, a feature used by Developer's web-keyboard test-host page).

The parameterization structure is defined within Web's engine/osk child package here (permalinked): https://github.com/keymanapp/keyman/blob/84ede941b96e48d7ed08a776e24278efe0686db8/web/src/engine/osk/src/input/gestures/specsForLayout.ts#L112-L132. Documentation for the fields can be found earlier within the same file.

.longpress - all longpress-focused parameters

  • .flickDistStart - the minimum net distance required to match the start of a potential up-flick shortcut for quickly displaying the longpress menu.
  • .flickDistEnd - the minimum net distance required to complete the up-flick quick-display shortcut for longpresses
  • .noiseTolerance - the maximum distance that the touchpoint is allowed to travel before the press is no longer considered a 'press' instead of a 'move'. This is a part of modeling 'roaming touch' behaviors.
  • .waitLength - the amount of time that should elapse before the longpress subkey menu is displayed whenever the up-flick shortcut isn't used

.multitap - all multi-tap focused parameters

  • .waitLength - the maximum amount of time allowed between the end of one tap and the start of the tap following it.
  • .holdLength - the maximum amount of time a tap may be held before the ability to continue the multitap with additional future taps is disabled.

.flick - all flick-focused parameters

  • .startDist - the minimum net distance required to "lock in" a flick gesture, disabling all other gesture types aside from simple taps from consideration.
  • .dirLockDist - the minimum net distance required to lock in the direction of an in-progress flick and its animation.
  • .triggerDist - the minimum net distance required to complete a flick gesture.

keyman.osk.bannerController.inactiveBanner

This is the location that controls what banner is presented to users when the predictive-text engine is not active. As such, the Keyman-logo image banner (be it an actual image or instead an HTML element) are set in place here.

The different banner types suited for this role have constructors accessible from keyman.osk.bannerController:

  • new keyman.osk.bannerController.ImageBanner(imagePath: string)
  • new keyman.osk.bannerController.HTMLBanner(htmlContent: string)

keyman.osk.bannerView.activeBannerHeight

The height allocated to the banner is managed here; set this value to match what is typical for the user's device.

keyman.osk.vkbd.currentLayer.globeKey.highlight(false)

This deep-reference method may be called to forcibly clear the globe key's highlighting once the picker is dismissed.

Due to how the picker operates within the Android app, the embedded Web engine cannot properly detect when this occurs; this method allows the app to properly finalize the gesture in its stead.

Clone this wiki locally