Keyman Core API

---

Overview

Keyman Core is the component of Keyman Engine that implements keyboarding rules. It is platform independent and allows support for different keyboard formats to be implemented within Keyman Engine. Eventually, Keyman Core will be used in Keyman on all platforms. As of writing, Keyman for Linux, Keyman for Windows, Keyman for macOS, and Keyman Developer use Keyman Core.

This is an internal API intended for use only within Keyman Engine.

Reference

• Background
• Changes from earlier versions
• Keyboards
• Options
• Processor
• State and Actions
• JSON introspection Schema
• Building Keyman Core

Requirements

1. Cross platform.
2. Cross language.
3. Facilitate stateless operation of the Engine.
4. Keyboard format agnostic -- support both KMN and future LDML based keyboards.
5. Support querying Engine attributes.
6. Support querying Keyboard attributes.
7. Idempotent

Design decisions in support of requirements

• Use C or C99 types and calling convention for the interface, it has the broadest language FFI support. [1,2]
• Have client (Platform layer) code load keyboards, manage & pass state. [3,4,7]
• Provide query calls to return static attributes data for keyboards and engine [5,6]
• Provide get/set calls for client accessible keyboard state information [3,4]

Glossary

• Platform layer: The code that consumes the Keyman Core API, and provides the operating system-specific handling of keystroke events and integration with applications.
• Client Application: The application that has the focus and receives text events from the Platform layer.
• Context: Text preceding the insertion point
• Marker: Positional state that can be placed in the Context.
• Keyboard: A set of rules for execution by an Engine
• Option: A variable in a dynamic or static key value store.
• Processor: The component that implements this API and can parse and execute a particular keyboard.
• State: An object that holds internal state of the Processor for a given insertion point
• Action: A directive output by the processor detailing how the Platform layer should transform the Client Application's text buffer. There may be several items produced by a single keyboard event.
• Keyboard Event: A virtual key event and modifier map received from the Platform layer to be processed with the state object for this Client application.
• Virtual Key: A code based on the US English layout, with values matching the Windows virtual key codes. See keyman_core_api_vkeys.h for definitions.
• Modifier Key: The set of Control, Shift, Alt, Caps Lock keys. On some platforms these may have other names (e.g. Alt is called Option on macOS); other platform-specific modifiers such as Windows key are excluded from this set. Some modifiers are transient, such as Control, and others have long-lasting state, such as Caps Lock.