Keyman Core Desktop API

Overview

Keyman Core Desktop 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 Windows, macOS and Linux. As of writing, Keyman for Linux, Keyman for Windows, and Keyman Developer use Keyman Core.

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

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 Keyboard Processor 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 hold 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 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 keyboardprocessor_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.