Kioboard
voidCallback function which function name matches the key name
Object.<string, Action>Object with Action callbacks
Array.<(string|Array.<string>)>The rows with keys like ["q w e", "a s d", ...]
Object.<string, LayerRows>Object with layer names (as keys) and rows as Array
Object.<string, string>ObjectfunctionCallback triggered on key press
functionCallback triggered on key release
Actions](#Actions)
* [.commonIcons](#Kioboard+commonIcons) : [Icons](#Icons)
* [.inputs[0]](#Kioboard+inputs[0]) : HTMLInputElement \| HTMLTextAreaElement
* [.scrollOptions](#Kioboard+scrollOptions) : ScrollIntoViewOptions
* [.load(layout, [callback])](#Kioboard+load) ⇒ [Kioboard](#Kioboard)
* [.setLayout(layout)](#Kioboard+setLayout) ⇒ [Kioboard](#Kioboard)
* [.setActions(actions)](#Kioboard+setActions) ⇒ [Kioboard](#Kioboard)
* [.setStyle(styles)](#Kioboard+setStyle) ⇒ [Kioboard](#Kioboard)
* [.on(keys, callback)](#Kioboard+on) ⇒ [Kioboard](#Kioboard)
* [.off(keys, callback)](#Kioboard+off) ⇒ [Kioboard](#Kioboard)
* [.playSound()](#Kioboard+playSound) ⇒ void
* [.playDefaultSound()](#Kioboard+playDefaultSound) ⇒ void
* [.setSound(enabled, [src])](#Kioboard+setSound) ⇒ [Kioboard](#Kioboard)
* [.emit(keys)](#Kioboard+emit) ⇒ [Kioboard](#Kioboard)
* [.sequence(keys, speed, callback)](#Kioboard+sequence) ⇒ function
* [.clearKioboard()](#Kioboard+clearKioboard) ⇒ [Kioboard](#Kioboard)
* [.draw()](#Kioboard+draw) ⇒ [Kioboard](#Kioboard)
* [.shift([state])](#Kioboard+shift) ⇒ [Kioboard](#Kioboard)
* [.changeLayer(layerName)](#Kioboard+changeLayer) ⇒ [Kioboard](#Kioboard)
* [.setTheme(theme)](#Kioboard+setTheme) ⇒ [Kioboard](#Kioboard)
* [.show([layerName])](#Kioboard+show) ⇒ [Kioboard](#Kioboard)
* [.hide()](#Kioboard+hide) ⇒ [Kioboard](#Kioboard)
* [.handleShow(evt)](#Kioboard+handleShow)
* [.handleHide()](#Kioboard+handleHide)
* [.handleKeyDown(evt)](#Kioboard+handleKeyDown)
* [.handleKeyUp(evt)](#Kioboard+handleKeyUp)
* [.hasSelection()](#Kioboard+hasSelection) ⇒ boolean
* [.setRange(val, from, to)](#Kioboard+setRange) ⇒ [Kioboard](#Kioboard)
* [.insert(val, from, to)](#Kioboard+insert)
* [._preventDefault(evt)](#Kioboard+_preventDefault)
* [.init()](#Kioboard+init) ⇒ [Kioboard](#Kioboard)
* [.destroy()](#Kioboard+destroy) ⇒ [Kioboard](#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 | HTMLInputElement \| HTMLTextAreaElement | 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](#Layout) \| undefined | | Current layout |
| options.theme | string | "default" | The theme to use. "default|flat|glass"-"light|dark" |
| 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.soundEnabled | boolean | false | Enable typing sound |
| options.soundSrc | string | | Custom audio file URL for typing sound |
| options.scrollOptions | ScrollIntoViewOptions | | 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](#KeyDownCallback) | | Callback when a key is pressed |
| options.onKeyUp | [KeyUpCallback](#KeyUpCallback) | | Callback when a key is released |
**Example**
```js
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](#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](#Kioboard)
**Properties**
| Name | Type | Description |
| --- | --- | --- |
| default | [Action](#Action) | Show "default" layer |
| shift | [Action](#Action) | Show "shift" layer |
| space | [Action](#Action) | Insert space character |
| enter | [Action](#Action) | Insert Newline (HTMLTextAreaElement) Submit the form (HTMLInputElement) |
| backspace | [Action](#Action) | Remove character or selection on the left of the caret |
| delete | [Action](#Action) | Remove character or selection on the right of the caret |
| arrowLeft | [Action](#Action) | Move caret to the left |
| arrowRight | [Action](#Action) | Move caret to the right |
| tab | [Action](#Action) | Insert tab character |
| close | [Action](#Action) | Close, hide Kioboard |
| drag | [Action](#Action) | Move the Kioboard |
### kioboard.commonIcons : [Icons](#Icons)
Beautifully crafted Kioboard icons.
The user can override any of those from their own layouts.
**Kind**: instance property of [Kioboard](#Kioboard)
### kioboard.inputs[0] : HTMLInputElement \| HTMLTextAreaElement
**Kind**: instance property of [Kioboard](#Kioboard)
### kioboard.scrollOptions : ScrollIntoViewOptions
**Kind**: instance property of [Kioboard](#Kioboard)
### kioboard.load(layout, [callback]) ⇒ [Kioboard](#Kioboard)
Loads a layout .js file from the layouts/ folder
**Kind**: instance method of [Kioboard](#Kioboard)
| Param | Type | Description |
| --- | --- | --- |
| layout | [Layout](#Layout) \| string | Layout Object, or path to layout file |
| [callback] | function | Passes as argument an object with the loaded layout data |
**Example**
```js
kio.load(myCustomLayout).show();
```
```js
kio.load("./layouts/en.js", (layout) => {
console.log(`Loaded: en.js layout`, layout);
kio.show();
});
```
### kioboard.setLayout(layout) ⇒ [Kioboard](#Kioboard)
Change the layout, set layers, actions, draw buttons
**Kind**: instance method of [Kioboard](#Kioboard)
| Param | Type |
| --- | --- |
| layout | [Layout](#Layout) |
**Example**
```js
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();
```
```js
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](#Kioboard)
Convert actions to Emitter events
**Kind**: instance method of [Kioboard](#Kioboard)
| Param | Type | Default |
| --- | --- | --- |
| actions | [Actions](#Actions) | {} |
**Example**
```js
kio.setActions({
Smile: () => console.log("😀"),
Sad: () => console.log("😞"),
});
```
After defining an action you can then use it in your Layout like:
```js
default: ["a b c", "d e f", "Smile Sad backspace enter"]
```
### kioboard.setStyle(styles) ⇒ [Kioboard](#Kioboard)
Set CSS styles
**Kind**: instance method of [Kioboard](#Kioboard)
| Param | Type |
| --- | --- |
| styles | Object |
**Example**
```js
kio.setStyle({
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](#Kioboard)
Add a custom action callback
**Kind**: instance method of [Kioboard](#Kioboard)
| Param | Type | Description |
| --- | --- | --- |
| keys | string \| Array.<string> | Space-delimited Key-action names i.e: "X x enter" or ["X", "x", "enter"] |
| callback | [Action](#Action) | Callback triggered on key down |
**Example**
```js
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:
```js
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](#Kioboard)
Off callbacks (or a specific one) from a set of keys
**Kind**: instance method of [Kioboard](#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](#Action) \| undefined | Optional, Callback to remove. If callback is not present all actions will be removed for that key |
**Example**
```js
// Remove all actions calbacks
kio.off("X");
```
```js
// Remove only a specific callback
kio.off("X", myXKeyCallback);
```
### kioboard.playSound() ⇒ void
Play typing sound if enabled
**Kind**: instance method of [Kioboard](#Kioboard)
### kioboard.playDefaultSound() ⇒ void
Play default click sound using Web Audio API
**Kind**: instance method of [Kioboard](#Kioboard)
### kioboard.setSound(enabled, [src]) ⇒ [Kioboard](#Kioboard)
Set typing sound options
**Kind**: instance method of [Kioboard](#Kioboard)
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| enabled | boolean | | Enable or disable typing sound |
| [src] | string | "default" | Optional custom audio file URL, or "default" for built-in sound |
**Example**
```js
kio.setSound(true); // Enable with default built-in sound
kio.setSound(true, "default"); // Same as above
kio.setSound(true, "/path/to/click.mp3"); // Enable with custom sound
kio.setSound(false); // Disable
```
### kioboard.emit(keys) ⇒ [Kioboard](#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](#Kioboard)
| Param | Type | Description |
| --- | --- | --- |
| keys | string \| Array.<string> | Space-delimited Key-action names i.e: "X x enter" or Array ["X", "x", "enter"] |
**Example**
```js
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](#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**
```js
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](#Kioboard)
Remove children elements
**Kind**: instance method of [Kioboard](#Kioboard)
**Example**
```js
kio.clearKioboard();
```
### kioboard.draw() ⇒ [Kioboard](#Kioboard)
Draw the keyboard buttons
Creates the kioboard buttons given the current layout's layer
**Kind**: instance method of [Kioboard](#Kioboard)
**Example**
```js
kio.draw()
```
### kioboard.shift([state]) ⇒ [Kioboard](#Kioboard)
Increment-loop or set shiftState
**Kind**: instance method of [Kioboard](#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](#Kioboard)
Set layer
Prepare a layer, draw buttons and set kioboard styles.
(Does not show the kioboard)
**Kind**: instance method of [Kioboard](#Kioboard)
| Param | Type | Description |
| --- | --- | --- |
| layerName | string | Default: this.layerNameInitial |
**Example**
```js
kio.changeLayer().show(); // Change to initial layer (initialization options)
kio.changeLayer("numpad").show();
```
### kioboard.setTheme(theme) ⇒ [Kioboard](#Kioboard)
Change theme styles as defined in CSS or that theme
**Kind**: instance method of [Kioboard](#Kioboard)
| Param | Type | Description |
| --- | --- | --- |
| theme | string | Theme name |
**Example**
```js
kio.setTheme("dark");
```
### kioboard.show([layerName]) ⇒ [Kioboard](#Kioboard)
Show the keyboard.
If layerName argument is provided, acts as a shorthand
for kio.changeLayer("someLayerName").show()
**Kind**: instance method of [Kioboard](#Kioboard)
| Param | Type | Description |
| --- | --- | --- |
| [layerName] | string | The layerName to show |
**Example**
```js
// 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](#Kioboard)
Hide the keyboard
**Kind**: instance method of [Kioboard](#Kioboard)
**Example**
```js
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](#Kioboard)
| Param | Type |
| --- | --- |
| evt | Event |
### kioboard.handleHide()
Event handler for hiding the keyboard
**Kind**: instance method of [Kioboard](#Kioboard)
### kioboard.handleKeyDown(evt)
Event handler for keyboard keydown events
for Kioboard buttons
**Kind**: instance method of [Kioboard](#Kioboard)
| Param | Type |
| --- | --- |
| evt | PointerEvent |
### kioboard.handleKeyUp(evt)
Event handler for keyboard keyup events
**Kind**: instance method of [Kioboard](#Kioboard)
| Param | Type |
| --- | --- |
| evt | PointerEvent |
### kioboard.hasSelection() ⇒ boolean
Check if input has a selection highlight
**Kind**: instance method of [Kioboard](#Kioboard)
**Example**
```js
const hasHighlghtedText = kio.hasSelection();
```
### kioboard.setRange(val, from, to) ⇒ [Kioboard](#Kioboard)
Set the caret position
**Kind**: instance method of [Kioboard](#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](#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**
```js
kio.insert(".com");
```
### kioboard.\_preventDefault(evt)
Prevent default event behavior
**Kind**: instance method of [Kioboard](#Kioboard)
| Param | Type |
| --- | --- |
| evt | Event |
### kioboard.init() ⇒ [Kioboard](#Kioboard)
Initializes kioboard and assign events
**Kind**: instance method of [Kioboard](#Kioboard)
**Example**
```js
kio.destroy();
kio.init();
```
### kioboard.destroy() ⇒ [Kioboard](#Kioboard)
Remove kioboard (from DOM) and its events
**Kind**: instance method of [Kioboard](#Kioboard)
**Example**
```js
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.<string>)>
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](#Layers) |
| actions | [Actions](#Actions) |
| icons | [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 |
___
© 2024-present — Roko C. Buljan