# Virtual Keyboard Plugin

Allows you to open the virtual keyboard and enter data using the mouse.

It also allows you to set a series of buttons with hot keys, which will enter the character specified for them. Can be
used for languages that do not have a proper keyboard.

## Example

```html
<textarea id="editor1"></textarea>
<script>
	const editor = Jodit.make('#editor1', {
		buttons: [
			'keyboard',
			{
				group: 'custom',
				buttons: []
			}
		],
		keyboard: {
			extraKeyGroup: 'custom',
			extraKeyButtons: [
				{
					key: 'λ',
					hotkey: 'ctrl+1'
				},
				'β' // Will have hotkey alt+2
			]
		}
	});

	editor.execCommand('toggleKeyboard'); // Show virtual keyboard
	editor.execCommand('toggleKeyboard'); // Hide virtual keyboard
</script>
```

## Options

### layoutList

- Type: `IDictionary<ILayoutKeys>`
- Default: See config.ts for default layouts (en, es, de, ru, tr, iw, tata)

Dictionary of language keyboard layouts of the form:

```ts
interface ILayoutKeys {
	title: string;
	keys: string[][];
}
```

Where characters are separated by a space:
- First character by default
- The second one when you press the Shift button
- Third when you click the Options button

#### Example

```html
<textarea id="editor2"></textarea>
<script>
	const editor = Jodit.make('#editor2', {
		keyboard: {
			defaultLayoutSet: 'ru',
			layoutList: {
				tata: {
					title: 'Russian language',
					// prettier-ignore
					keys: [
						['` ~ ±', '1 ! §', '2 @ "', '3 # :', '4 $ <', '5 % >', '6 ^', '7 &', '8 *', '9 (', '0 )', '- _', '= +', 'Backspace'],
						['Tab', 'й Й', 'ц Ц', 'у У', 'к К', 'е Е', 'н Н', 'г Г', 'ш Ш', 'щ Щ', 'з З', 'х Х [', 'ъ ] {', '\\ | }'],
						['Caps', 'ф Ф', 'ы Ы', 'в В', 'а А', 'п П', 'р Р', 'о О', 'л Л', 'д Д', 'ж Ж ;', 'э Э \'', 'Enter'],
						['Shift', 'я Я', 'ч Ч', 'с С', 'м М', 'и И', 'т Т', 'ь Ь', 'б Б ,', 'ю Ю .', '/ ?', 'Shift'],
						['Options', 'Space', 'Options'],
					]
					// prettier-ignore-end
				}
			}
		}
	});
</script>
```

### defaultLayoutSet

- Type: `string`
- Default: `'en'`

Set layout language by default.

#### Example

```html
<textarea id="editor2"></textarea>
<script>
	const editor = Jodit.make('#editor2', {
		keyboard: {
			defaultLayoutSet: 'ru'
		}
	});
</script>
```

### showLayoutSwitcher

- Type: `boolean`
- Default: `true`

Show keyboard layout selection buttons in the header of the virtual keyboard.

### layoutSwitchList

- Type: `string[]`
- Default: `['en', 'es', 'de', 'ru', 'tr', 'iw', 'tata']`

List of layouts to show in the layout switcher.

#### Example

```html
<textarea id="editor3"></textarea>
<script>
	const editor = Jodit.make('#editor3', {
		keyboard: {
			layoutSwitchList: ['ru', 'tata'],
			defaultLayoutSet: 'tata'
		}
	});
</script>
```

### extraKeyButtons

- Type: `Array<IKeys | string>`
- Default: `[]`

Additional buttons to add to the keyboard. Can be used to add special characters or symbols.

```ts
interface IKeys {
	key: string;
	hotkey?: string;
}
```

#### Example

```js
const editor = Jodit.make('#editor', {
	keyboard: {
		extraKeyButtons: [
			{
				key: 'λ',
				hotkey: 'ctrl+1'
			},
			'β', // Will have hotkey alt+2
			'γ'  // Will have hotkey alt+3
		]
	}
});
```

### extraKeyGroup

- Type: `ButtonGroup`
- Default: `'other'`

The toolbar group where the extra key buttons will be added.

#### Example

```js
const editor = Jodit.make('#editor', {
	buttons: [
		'keyboard',
		{
			group: 'symbols',
			buttons: []
		}
	],
	keyboard: {
		extraKeyGroup: 'symbols',
		extraKeyButtons: ['λ', 'β', 'γ']
	}
});
```

### keySize

- Type: `number`
- Default: `32`

The size of keyboard keys in pixels.

#### Example

```js
const editor = Jodit.make('#editor', {
	keyboard: {
		keySize: 40 // Larger keys
	}
});
```

### layout

- Type: `number[][]`
- Default:
```js
[
	[1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2],
	[1.5, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1.5],
	[1.8, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2.2],
	[2.5, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2.5],
	[3.5, 9, 3.5]
]
```

The layout of the keyboard, where each number represents the relative width of a key. This allows you to create a keyboard layout that matches standard keyboard proportions.

#### Example

```js
const editor = Jodit.make('#editor', {
	keyboard: {
		// Custom layout with equal-sized keys
		layout: [
			[1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
			[1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
			[1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
			[1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
			[1, 10, 1]
		]
	}
});
```

### delayKeyRepeat

- Type: `number`
- Default: `350`

The delay in milliseconds before key repeat starts when a key is held down.

#### Example

```js
const editor = Jodit.make('#editor', {
	keyboard: {
		delayKeyRepeat: 500 // Longer delay before key repeat starts
	}
});
```

### periodKeyRepeat

- Type: `number`
- Default: `100`

The interval in milliseconds between key repeats when a key is held down.

#### Example

```js
const editor = Jodit.make('#editor', {
	keyboard: {
		periodKeyRepeat: 50 // Faster key repeat rate
	}
});
```

## Advanced Examples

### Creating a Custom Keyboard with Special Characters

```js
const editor = Jodit.make('#editor', {
	buttons: [
		'keyboard',
		{
			group: 'math',
			buttons: []
		}
	],
	keyboard: {
		extraKeyGroup: 'math',
		extraKeyButtons: [
			{
				key: '±',
				hotkey: 'ctrl+shift+p'
			},
			{
				key: '∑',
				hotkey: 'ctrl+shift+s'
			},
			{
				key: '∫',
				hotkey: 'ctrl+shift+i'
			},
			{
				key: '√',
				hotkey: 'ctrl+shift+r'
			},
			{
				key: '∞',
				hotkey: 'ctrl+shift+8'
			}
		],
		// Custom layout with fewer keys for a specialized keyboard
		layoutList: {
			math: {
				title: 'Math Symbols',
				keys: [
					['π', 'θ', 'φ', 'λ', 'Ω', 'δ', 'Δ', '∇', '∂', '∀', '∃', '∄', '∈', 'Backspace'],
					['Tab', '⊂', '⊃', '∩', '∪', '⊆', '⊇', '≡', '≤', '≥', '≠', '≈', '≅', '≜'],
					['Caps', '×', '÷', '−', '+', '±', '⋅', '∗', '∝', '∞', '!', '′', 'Enter'],
					['Shift', '∑', '∏', '∫', '∬', '∭', '∮', '∯', '∰', '∇', '√', 'Shift'],
					['Options', 'Space', 'Options']
				]
			}
		},
		defaultLayoutSet: 'math',
		layoutSwitchList: ['en', 'math']
	}
});
```

### Creating a Compact Keyboard for Mobile Devices

```js
const editor = Jodit.make('#editor', {
	buttons: ['keyboard'],
	keyboard: {
		keySize: 24, // Smaller keys for mobile
		// Simplified layout with fewer keys
		layoutList: {
			mobile: {
				title: 'Mobile',
				keys: [
					['1', '2', '3', '4', '5', '6', '7', '8', '9', '0', 'Backspace'],
					['q', 'w', 'e', 'r', 't', 'y', 'u', 'i', 'o', 'p'],
					['a', 's', 'd', 'f', 'g', 'h', 'j', 'k', 'l', 'Enter'],
					['Shift', 'z', 'x', 'c', 'v', 'b', 'n', 'm', ',', '.', 'Shift'],
					['@', 'Space', '.com']
				]
			}
		},
		layout: [
			[1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2],
			[1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
			[1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
			[1.5, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1.5],
			[2, 6, 2]
		],
		defaultLayoutSet: 'mobile',
		layoutSwitchList: ['mobile']
	}
});
```

## API Reference

### Configuration Interface

The keyboard plugin extends the Jodit configuration with the following interface:

```typescript
interface Config {
    keyboard: {
        keySize: number;
        layout: number[][];
        extraKeyButtons: Array<IKeys | string>;
        extraKeyGroup: ButtonGroup;
        layoutList: IDictionary<ILayoutKeys>;
        defaultLayoutSet: string;
        showLayoutSwitcher: boolean;
        layoutSwitchList: string[];
        delayKeyRepeat: number;
        periodKeyRepeat: number;
    };
}
```

### Interface Definitions

#### IKeys

Interface for defining custom keyboard buttons:

```typescript
interface IKeys {
    key: string;
    hotkeys?: string[];
}
```

**Properties:**
- `key: string` - The character or text to insert when the button is pressed
- `hotkeys?: string[]` - Optional array of keyboard shortcuts to trigger this key

#### ILayoutKeys

Interface for defining keyboard layouts:

```typescript
interface ILayoutKeys {
    title: string;
    keys: string[][];
}
```

**Properties:**
- `title: string` - Display name for the layout (shown in layout switcher)
- `keys: string[][]` - 2D array representing the keyboard layout, where each inner array represents a row of keys

### Control Configuration

The plugin registers a control with the following interface:

```typescript
interface KeyboardControl extends IControlType {
    tooltip: 'Keyboard';
    icon: string;
    isActive: (editor: IViewBased) => boolean;
    command: 'toggleKeyboard';
}
```

### Commands

#### toggleKeyboard

Toggles the virtual keyboard visibility:

```js
// Show virtual keyboard
editor.execCommand('toggleKeyboard');

// Hide virtual keyboard (if visible)
editor.execCommand('toggleKeyboard');
```

### Events

#### isKeyboardOpened

Returns whether the virtual keyboard is currently open:

```js
// Check if keyboard is open
const isOpen = editor.events.fire('isKeyboardOpened');
console.log('Keyboard is open:', isOpen);
```

### Default Configuration

```typescript
const defaultConfig = {
    defaultLayoutSet: 'en',
    showLayoutSwitcher: true,
    extraKeyGroup: 'other',
    extraKeyButtons: [],
    delayKeyRepeat: 350,
    periodKeyRepeat: 100,
    layoutSwitchList: ['en', 'es', 'de', 'ru', 'tr', 'iw', 'tata'],
    keySize: 32,
    layout: [
        [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2],
        [1.5, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1.5],
        [1.8, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2.2],
        [2.5, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2.5],
        [3.5, 9, 3.5]
    ],
    layoutList: {
        en: { title: 'English', keys: [...] },
        es: { title: 'Español', keys: [...] },
        de: { title: 'Deutsch', keys: [...] },
        ru: { title: 'Русский', keys: [...] },
        tr: { title: 'Türkçe', keys: [...] },
        iw: { title: 'Hebrew', keys: [...] },
        tata: { title: 'Tata', keys: [...] }
    }
};
```

### Key Layout Format

Keys in the layout are defined as strings with space-separated characters:

- **First character**: Default character (normal press)
- **Second character**: Shift character (when Shift is active)
- **Third character**: Options character (when Options is active)

**Special keys:**
- `'Backspace'` - Backspace key
- `'Tab'` - Tab key
- `'Caps'` - Caps Lock key
- `'Shift'` - Shift key
- `'Enter'` - Enter key
- `'Space'` - Space bar
- `'Options'` - Options/Alt key

**Example key definitions:**
```typescript
'a A @'  // Normal: 'a', Shift: 'A', Options: '@'
'1 ! §'  // Normal: '1', Shift: '!', Options: '§'
'Backspace' // Special backspace key
```

### Layout Proportions

The `layout` array defines the relative widths of keys in each row:

```typescript
layout: [
    [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2], // Numbers row: normal keys + wider backspace
    [1.5, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1.5], // QWERTY row: wider tab keys
    [1.8, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2.2], // ASDF row: caps lock + enter
    [2.5, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2.5], // ZXCV row: wider shift keys
    [3.5, 9, 3.5] // Bottom row: options + wide space + options
]
```