← Home

Docs

Classes

Kioboard: Kioboard

Typedefs

Action ⇒ void: Callback function which function name matches the key name
Actions : Object.<string, Action>: Object with Action callbacks
LayerRows : Array.<(string|Array)>: The rows with keys like ["q w e", "a s d", ...]
Layers : Object.<string, LayerRows>: Object with layer names (as keys) and rows as Array
Icons : Object.<string, string>
Layout : Object
KeyDownCallback : function: Callback triggered on key press
KeyUpCallback : function: Callback triggered on key release

Kioboard

Kind: global class

Kioboard
- new Kioboard(options)
- .commonActions : Actions
- .commonIcons : Icons
- .load(layout, [callback]) ⇒ Kioboard
- .setLayout(layout) ⇒ Kioboard
- .setActions(actions) ⇒ Kioboard
- .setStyle(styles) ⇒ Kioboard
- .on(keys, callback) ⇒ Kioboard
- .off(keys, callback) ⇒ Kioboard
- .emit(keys) ⇒ Kioboard
- .sequence(keys, speed, callback) ⇒ function
- .clearKioboard() ⇒ Kioboard
- .draw() ⇒ Kioboard
- .shift([state]) ⇒ Kioboard
- .changeLayer(layerName) ⇒ Kioboard
- .setTheme(theme) ⇒ Kioboard
- .show([layerName]) ⇒ Kioboard
- .hide() ⇒ Kioboard
- .handleShow(evt)
- .handleHide()
- .handleKeyDown(evt)
- .handleKeyUp(evt)
- .hasSelection() ⇒ boolean
- .setRange(val, from, to) ⇒ Kioboard
- .insert(val, from, to)
- .init() ⇒ Kioboard
- .destroy() ⇒ Kioboard

new Kioboard(options)

Param	Type	Default	Description
options	`Object`
options.parent	`string` \| `Element` \| `undefined`	`"body"`	Element to insert kioboard into
options.element	`HTMLElement`		Kioboard Element
options.inputs	`string` \| `NodeList` \| `HTMLElement` \| `HTMLCollection` \| `undefined`	`"[data-kioboard]"`	Selector string, Element or elements. The input(s) to bind to
options.input	`HTMLElement`	`options.inputs[0]`	The currently active input
options.layerNameInitial	`string`	`"default"`	Initial layer name
options.layerName	`string`	`"default"`	Current layer name
options.layerNameDefault	`string`	`"default"`	Name definition for "default" layout
options.layerNameShift	`string`	`"shift"`	Name definition for "shift" layout
options.layoutName	`string` \| `undefined`		The layout's name in use
options.layout	`Layout` \| `undefined`		Current layout
options.theme	`string`	`"default"`	The theme to use. "default
options.isEnterSubmit	`boolean`	`true`	Whether to submit on enter (only for HTMLInputElements)
options.classVisible	`string`	`"is-visible"`	Kioboard visible className
options.classShift	`string`	`"is-shift"`	Kioboard shift className
options.classCaps	`string`	`"is-caps"`	Kioboard caps className
options.isVisible	`boolean`	`false`	Whether kioboard is visible
options.isPermanent	`boolean`	`false`	Never hide kioboard
options.isScroll	`boolean`	`true`	Scroll input into view when focused
options.isOSK	`boolean`	`false`	Allow OS's default on-screen-keyboard
options.scrollOptions	`Object`		https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView
options.shiftState	`number`		Shift states: 0=Off 1=On 2=Caps-lock. When 0 the "default" layer will be used
options.key	`string`		The last pressed key
options.pointerId	`number`		The pointer ID(-1 when no pointer)
options.onInit	`function`		Callback after kioboard instance is initialized
options.onBeforeShow	`function`		Callback before kioboard is shown
options.onShow	`function`		Callback after kioboard is shown
options.onBeforeHide	`function`		Callback before kioboard is hidden
options.onHide	`function`		Callback after kioboard is hidden
options.onLoad	`function`		Callback after Layout file is loaded
options.onKeyDown	`KeyDownCallback`		Callback when a key is pressed
options.onKeyUp	`KeyUpCallback`		Callback when a key is released

Example

const kio = new Kioboard({
  parent: document.querySelector("#kioboardWrapper"),
  layoutName: "hr", // Init with Croatian layout (see available: layouts/ folder)
  theme: "flat-dark", // "default"|"default-dark"|"flat"|"flat-dark"
  onInit() {
    console.log("kioboard initialized!", this);
  },
  onKeyDown(key) {
    console.log("Pressed key", key);
  },
  onShow() {
    console.log("Kioboard shown!");
  },
  onHide() {
    console.log("Kioboard hidden!");
  },     
  onLoad() {
    console.log("Kioboard layout file loaded!");
    this.show("default");
  },       
});

kioboard.commonActions : `Actions`

Common actions Those are non-trivial to write and grasp, so every layout will inherit those actions. The user can override each of these in their own layout.

Kind: instance property of Kioboard
Properties

Name	Type	Description
default	`Action`	Show "default" layer
shift	`Action`	Show "shift" layer
space	`Action`	Insert space character
enter	`Action`	Insert Newline (HTMLTextAreaElement) Submit the form (HTMLInputElement)
backspace	`Action`	Remove character or selection on the left of the caret
delete	`Action`	Remove character or selection on the right of the caret
arrowLeft	`Action`	Move caret to the left
arrowRight	`Action`	Move caret to the right
tab	`Action`	Insert tab character
close	`Action`	Close, hide Kioboard
drag	`Action`	Move the Kioboard

kioboard.commonIcons : `Icons`

Beautifully crafted Kioboard icons. The user can override any of those from their own layouts.

Kind: instance property of Kioboard

kioboard.load(layout, [callback]) ⇒ `Kioboard`

Loads a layout .js file from the layouts/ folder

Kind: instance method of Kioboard

Param	Type	Description
layout	`Layout` \| `string`	Layout Object, or path to layout file
[callback]	`function`	Passes as argument an object with the loaded layout data

Example

kio.load(myCustomLayout).show();

kio.load("./layouts/en.js", (layout) => {
    console.log(`Loaded: en.js layout`, layout);
    kio.show();
});

kioboard.setLayout(layout) ⇒ `Kioboard`

Change the layout, set layers, actions, draw buttons

Kind: instance method of Kioboard

Param	Type
layout	`Layout`

Example

const customLayout = {
  name: "custom",
  layers: {
    default: ["1 2 3 4", "shift a b enter", "smile space"],
    shift: ["! ? . ,", "shift A B enter", "smile space"],
    smile: ["😀 🤓 🤭 😁", "🥰 🙂 😎 enter", "default space"],
  },
  icons: {
    smile: "😀",
  },
  actions: {
    smile() { this.show("smile"); },
  },
};

const kio = new Kioboard({
  theme: "flat-dark"
});
kio.setLayout(customLayout).show();

import myLayout from './layouts/myKioLayout.js';
import en from '@rbuljan/kioboard/dist/layouts/en.js';

const kio = new Kioboard({
  theme: "flat-dark"
});
kio.setLayout(myLayout).show();
// kio.setLayout(en).show();

kioboard.setActions(actions) ⇒ `Kioboard`

Convert actions to Emitter events

Kind: instance method of Kioboard

Param	Type	Default
actions	`Actions`	`{}`

Example

kio.setActions({
  Smile: () => console.log("😀"),
  Sad: () => console.log("😞"),
});

After defining an action you can then use it in your Layout like:

default: ["a b c", "d e f", "Smile Sad backspace enter"]

kioboard.setStyle(styles) ⇒ `Kioboard`

Set CSS styles

Kind: instance method of Kioboard

Param	Type
styles	`Object`

Example

kio.style({
  hue: 194,
  saturation: 94,
  lightness: 49,
  alpha: 1,
  radius: 0.3,
  gap: 0.3,
  size: 2,
  color: "currentColor",
  background: "hsl(0 0% 90% / 1)",
  backgroundBtn: "hsl(0 0% 100% / 1)",
  shadow: "inset 0 -1px 0 hsl(0 0% 0% / 0.3)",
});

kioboard.on(keys, callback) ⇒ `Kioboard`

Add a custom action callback

Kind: instance method of Kioboard

Param	Type	Description
keys	`string` \| `Array.<string>`	Space-delimited Key-action names i.e: "X x enter" or ["X", "x", "enter"]
callback	`Action`	Callback triggered on key down

Example

kio.on("enter", function (key) {
  // Does what enter key does (default action for "enter") but also:
  console.log(key, this);
});

// PS: anonymous functions (callbacks) cannot be off-ed. Use a function expression instead:

const logKey = function(key) {
  console.log(key, this); // Logs i.e: "A", Kioboard
};
kio.on(["a", "A"], logKey);
kio.off(["a", "A"], logKey); // Can be off-ed when necessary

kioboard.off(keys, callback) ⇒ `Kioboard`

Off callbacks (or a specific one) from a set of keys

Kind: instance method of Kioboard

Param	Type	Description
keys	`string` \| `Array.<string>`	Space-delimited Key-action names i.e: "X x enter" or Array ["X", "x", "enter"]
callback	`Action` \| `undefined`	Optional, Callback to remove. If callback is not present all actions will be removed for that key

Example

// Remove all actions calbacks
kio.off("X");

// Remove only a specific callback
kio.off("X", myXKeyCallback);

kioboard.emit(keys) ⇒ `Kioboard`

Trigger specific key-name action/s If a key-action exists it will trigger that action otherwise the key-name will be inserted at caret position inside the input element

Kind: instance method of Kioboard

Param	Type	Description
keys	`string` \| `Array.<string>`	Space-delimited Key-action names i.e: "X x enter" or Array ["X", "x", "enter"]

Example

kio.emit("X"); // Trigger the X key
kio.emit("X Y Z enter"); // Trigger multiple keys
kio.emit(["X", "enter"]); // Trigger multiple keys

kioboard.sequence(keys, speed, callback) ⇒ `function`

Automatically emit keys in a typing fashion / sequence

Kind: instance method of Kioboard
Returns: function - Call the returned function to stop the loop

Param	Type	Default	Description
keys	`string` \| `Array.<string>`
speed	`number`	`100`	Emitting speed in milliseconds
callback	`function`		Callback called on finish

Example

kio.sequence("X z Y"); // Trigger in succession every N ms
// Or: do someting on finish:
const stop = kio.sequence("X Y Z enter", 150, () => { console.log("Done!"); });
// stop(); // call the returned function to prematurely stop the sequencer loop.

kioboard.clearKioboard() ⇒ `Kioboard`

Remove children elements

Kind: instance method of Kioboard
Example

kio.clearKioboard();

kioboard.draw() ⇒ `Kioboard`

Draw the keyboard buttons Creates the kioboard buttons given the current layout's layer

Kind: instance method of Kioboard
Example

kio.draw()

kioboard.shift([state]) ⇒ `Kioboard`

Increment-loop or set shiftState

Kind: instance method of Kioboard

Param	Type	Default	Description
[state]	`number`	`Kioboard.shiftState`	Default: loop state. Defined: shift states (0=Off 1=On 2=Caps-lock)

kioboard.changeLayer(layerName) ⇒ `Kioboard`

Set layer Prepare a layer, draw buttons and set kioboard styles. (Does not show the kioboard)

Kind: instance method of Kioboard

Param	Type	Description
layerName	`string`	Default: this.layerNameInitial

Example

kio.changeLayer().show(); // Change to initial layer (initialization options)
kio.changeLayer("numpad").show();

kioboard.setTheme(theme) ⇒ `Kioboard`

Change theme styles as defined in CSS or that theme

Kind: instance method of Kioboard

Param	Type	Description
theme	`string`	Theme name

Example

kio.setTheme("dark");

kioboard.show([layerName]) ⇒ `Kioboard`

Show the keyboard. If layerName argument is provided, acts as a shorthand for kio.changeLayer("someLayerName").show()

Kind: instance method of Kioboard

Param	Type	Description
[layerName]	`string`	The layerName to show

Example

// Show kioboard
kio.show(); 
// Show kioboard with a specific layerName
kio.show("numpad");
// Set a layerName and show it
kio.changeLayer("default").show(); 
// Apply CapsLock and show the "shift" shift layer
this.shift(2).show("shift");

kioboard.hide() ⇒ `Kioboard`

Hide the keyboard

Kind: instance method of Kioboard
Example

kio.hide();

kioboard.handleShow(evt)

Event handler for showing the keyboard Does not show the keyboard if the input is disabled

Kind: instance method of Kioboard

Param	Type
evt	`Event`

kioboard.handleHide()

Event handler for hiding the keyboard

Kind: instance method of Kioboard

kioboard.handleKeyDown(evt)

Event handler for keyboard keydown events for Kioboard buttons

Kind: instance method of Kioboard

Param	Type
evt	`PointerEvent`

kioboard.handleKeyUp(evt)

Event handler for keyboard keyup events

Kind: instance method of Kioboard

Param	Type
evt	`PointerEvent`

kioboard.hasSelection() ⇒ `boolean`

Check if input has a selection highlight

Kind: instance method of Kioboard
Example

const hasHighlghtedText = kio.hasSelection();

kioboard.setRange(val, from, to) ⇒ `Kioboard`

Set the caret position

Kind: instance method of Kioboard

Param	Type
val	`string`
from	`number`
to	`number`

kioboard.insert(val, from, to)

Insert value at caret position. Respects also the input's maxlength.

Kind: instance method of Kioboard

Param	Type	Default	Description
val	`string`		Text to insert at caret position or highlighted section
from	`number`	`this.input.selectionStart`
to	`number`	`this.input.selectionEnd`

Example

kio.insert(".com");

kioboard.init() ⇒ `Kioboard`

Initializes kioboard and assign events

Kind: instance method of Kioboard
Example

kio.destroy();
kio.init();

kioboard.destroy() ⇒ `Kioboard`

Remove kioboard (from DOM) and its events

Kind: instance method of Kioboard
Example

kio.destroy();
kio.init();

Action ⇒ `void`

Callback function which function name matches the key name

Kind: global typedef
this: {Kioboard}

Param	Type	Description
key	`string`	the pressed key name

Actions : `Object.<string, Action>`

Object with Action callbacks

Kind: global typedef

LayerRows : `Array.<(string|Array)>`

The rows with keys like ["q w e", "a s d", ...]

Kind: global typedef

Layers : `Object.<string, LayerRows>`

Object with layer names (as keys) and rows as Array

Kind: global typedef

Icons : `Object.<string, string>`

Kind: global typedef

Layout : `Object`

Kind: global typedef
Properties

Name	Type
name	`string`
layers	`Layers`
actions	`Actions`
icons	`Icons`

KeyDownCallback : `function`

Callback triggered on key press

Kind: global typedef

Param	Type	Description
key	`string`	The pressed key-name

KeyUpCallback : `function`

Callback triggered on key release

Kind: global typedef

Param	Type	Description
key	`string`	The released key-name

Files

api.md

Latest commit

History

api.md

File metadata and controls

Docs

Classes

Typedefs

Kioboard

new Kioboard(options)

kioboard.commonActions : Actions

kioboard.commonIcons : Icons

kioboard.load(layout, [callback]) ⇒ Kioboard

kioboard.setLayout(layout) ⇒ Kioboard

kioboard.setActions(actions) ⇒ Kioboard

kioboard.setStyle(styles) ⇒ Kioboard

kioboard.on(keys, callback) ⇒ Kioboard

kioboard.off(keys, callback) ⇒ Kioboard

kioboard.emit(keys) ⇒ Kioboard

kioboard.sequence(keys, speed, callback) ⇒ function

kioboard.clearKioboard() ⇒ Kioboard

kioboard.draw() ⇒ Kioboard

kioboard.shift([state]) ⇒ Kioboard

kioboard.changeLayer(layerName) ⇒ Kioboard

kioboard.setTheme(theme) ⇒ Kioboard

kioboard.show([layerName]) ⇒ Kioboard

kioboard.hide() ⇒ Kioboard

kioboard.handleShow(evt)

kioboard.handleHide()

kioboard.handleKeyDown(evt)

kioboard.handleKeyUp(evt)

kioboard.hasSelection() ⇒ boolean

kioboard.setRange(val, from, to) ⇒ Kioboard

kioboard.insert(val, from, to)

kioboard.init() ⇒ Kioboard

kioboard.destroy() ⇒ Kioboard

Action ⇒ void

Actions : Object.<string, Action>

LayerRows : Array.<(string|Array)>

Layers : Object.<string, LayerRows>

Icons : Object.<string, string>

Layout : Object

KeyDownCallback : function

KeyUpCallback : function

kioboard.commonActions : `Actions`

kioboard.commonIcons : `Icons`

kioboard.load(layout, [callback]) ⇒ `Kioboard`

kioboard.setLayout(layout) ⇒ `Kioboard`

kioboard.setActions(actions) ⇒ `Kioboard`

kioboard.setStyle(styles) ⇒ `Kioboard`

kioboard.on(keys, callback) ⇒ `Kioboard`

kioboard.off(keys, callback) ⇒ `Kioboard`

kioboard.emit(keys) ⇒ `Kioboard`

kioboard.sequence(keys, speed, callback) ⇒ `function`

kioboard.clearKioboard() ⇒ `Kioboard`

kioboard.draw() ⇒ `Kioboard`

kioboard.shift([state]) ⇒ `Kioboard`

kioboard.changeLayer(layerName) ⇒ `Kioboard`

kioboard.setTheme(theme) ⇒ `Kioboard`

kioboard.show([layerName]) ⇒ `Kioboard`

kioboard.hide() ⇒ `Kioboard`

kioboard.hasSelection() ⇒ `boolean`

kioboard.setRange(val, from, to) ⇒ `Kioboard`

kioboard.init() ⇒ `Kioboard`

kioboard.destroy() ⇒ `Kioboard`

Action ⇒ `void`

Actions : `Object.<string, Action>`

LayerRows : `Array.<(string|Array)>`

Layers : `Object.<string, LayerRows>`

Icons : `Object.<string, string>`

Layout : `Object`

KeyDownCallback : `function`

KeyUpCallback : `function`