Skip to main content

Keyboard API

API to select a system keyboad or define a custom keyboard built for your app.

Modeling a keyboard​

The keyboard API is used to define the layout of the keyboard and the transitions between different modes of the keyboard.

A mode is a layout represented by a multi-line string where each line is a row of keys. Rows do not need to be equal length. Each key is separated by a single space. Keys are strings of length 1 that represent what their input is, such as "a", "b", "1", etc. Keys can span multiple columns by using the ::key:: syntax. For example, a space key that spans 5 columns would be :::::space:::::. The trailing colons are optional, for example :::::space is equivalent. Keys can be nil or null to represent a non-navigable space. Other keys have special meaning, such as space which is transformed into " ".

Modes can be transitioned between by pressing a key. A transition is a tuple of values consisting of from_mode, to_mode and with_key. This assumes that to transition the mode, the "ok" button is pressed on the with_key. An optional transition key may be specified if it is different.

To handle ambiguity when transitioning away from a spanning key, an ambiguity rule can be set. The default is "last_visited", which is the behavior of most keyboards. Other valid values are "left" or "right".

The default focus of the keyboards will be the letter "g", but another key may be specified.

Usage​

The keyboard API is designed to be used with the control.enterText function to simulate typing on a keyboard, however, an object oriented API is also provided.

Example​

local kb = Keyboard.new()
:addMode("lower", [[
  null  1 2 3 4 5 6 7 8 9 0 - = delete
  tab  q w e r t y u i o p [ ]   caps  a s d f g h j k l ; ' submit
  shift z x c v b n m , . / shift
  ::::::::::::space::::::::::::
]])
:addMode("upper", [[
  null ! @ # $ % ^ & * ( ) _ + delete
  tab  Q W E R T Y U I O P { }   caps  A S D F G H J K L : " submit
  shift Z X C V B N M < > ? shift
  ::::::::::::space::::::::::::
]])
:addModeTransition("lower", "upper", "caps")
:addModeTransition("upper", "lower", "caps")
:setInitialFocus("g")
:setInitialMode("lower")
:setAmbiguityRule("last_visited")

Keyboard.enterText(kb, "Hello world!") -- enter text and stop
Keyboard.enterTextAndSubmit(kb, "Hello world!", "submit") -- hit "submit" after typing
Keyboard.addTransition(kb, "q", "p", "green") -- add an arbitrary transition between two keys, e.g. moves focus from q to p with the press of the "green" key

keyboard.addMode​

Signatures​

addMode(arg, mode, layout)

Description​

Adds a modes layout to a keyboard

keyboard.addModeTransition​

Signatures​

addModeTransition(arg, transition)

Description​

Adds a transition between two modes

keyboard.addTransition​

Signatures​

addTransition(arg, from, to, with)

Description​

Adds an arbitrary transition between two keys on a keyboard

keyboard.basic​

Signatures​

basic(table, focus \ nil, ambiguity_rule \ "last_visited")

Description​

Generate a basic single mode keyboard from a table. Creates a custom keyboard that does not have any modes (such as shift or caps lock). To create, pass a multi-line string where each line is a row of keys.

Example:

local kb = keyboard.basic([[
e h l
n m o
:::space:::
]],
"h", -- Sets "h" as the initial key. Will set the top left key by default
"left") -- Sets ambiguity rule to select the leftmost key when navigating away from the space bar

control.enterText(kb, "hello")

keyboard.createEmpty​

Signatures​

createEmpty()

Description​

Creates an empty keyboard userdata object

keyboard.destroy​

Signatures​

destroy(arg)

Description​

Frees the keyboard graph in memory. Keyboards are automatically freed when the script ends.

keyboard.setAmbiguityRule​

Signatures​

setAmbiguityRule(arg, ambiguity_rule)

Description​

Sets the ambiguity rule of a keyboard

keyboard.setFocus​

Signatures​

setFocus(arg, focus)

Description​

Sets the current focus of a keyboard

keyboard.setMode​

Signatures​

setMode(arg, mode)

Description​

Sets the current mode of a keyboard