• the AutoHotkey community
• JSON

special thanks to brutus_skywalker, coco, GeekDude, fenchai, helgef, ixiko, jeeswg, ManiacDC, Rohwedder and Uberi

• Presentation
• Main features
• Deployment
• Sample example
• Namespace reservations
• vKeyboard (the visual keyboard object)
• Object members
• Available properties
• Available methods
• Event handling
• Customization
• Keyboard and joystick shortcuts
• Autocomplete lists
• Styling the keyboard
• Layout JSON representations
• The structure of keymaps
• The semantics of keymaps - key descriptors
• The built-in default callback
• 'F-functions'
• Built-in 'f-functions'
• keyWithVariantsProc
• setAltIndexProc
• altEntryModeProc
• setCaretPosProc
• toLayerProc

The library allows to create basic but nevertheless rather customizable visual keyboards, via an AutoHotkey programmable interface. Practically, the script enables you to invoke a visual keyboard whenever text entry is required - and as an alternative to type, enter text.

• The visual keyboard is endowed with an eAutocomplete control, which allows autocompletion. This latter enables you, as you are composing text, to rather quickly find, get info tips and select from a dynamic pre-populated list of suggestions and, by this means, to expand/replace partially entered strings into/by complete strings. The eAutocomplete component allows fuzzy search.
• The visual keyboard is designed to be easily handled using a 12keys-1POV-4axes PC game controller.
• Basic event handling.
• Customizable keyboard/joystick hotkeys, autocomplete lists, keyboard layouts and UI graphics.

An instance of vKeyboard (the visual keyboard object) will be from now on referred to as vk.

• Make sure you have a recent version of AutoHotkey (AutoHotkey v1.1.32.00+, preferably).
• Download the latest release and extract the content of the zip file to a location of your choice, for example into your project's folder hierarchy.
• Load the library (/lib/vKeyboard.ahk) by means of the #Include directive:

#NoEnv
#SingleInstance force
SetWorkingDir % A_ScriptDir
SendMode, Input
#Warn
; tested on Windows 10 (19041) 64 bit with Autohotkey v1.1.32.00 32-bit Unicode

#Include %A_ScriptDir%\..\..\lib\vKeyboard.ahk

eAutocomplete.setSourceFromFile("fr", A_ScriptDir . "\autocompletion\fr")

vk := new vKeyboard()
vk.autocomplete.source := "fr"
vKeyboard.defineLayout("français", A_ScriptDir . "\keymaps\français.json")
vk.setLayout("français")
vKeyboard.defineStyle("default", A_ScriptDir . "\styles\default.css")
vk.setStyle("default")
vk.autocomplete.bkColor := vk.backgroundColor
vk.autocomplete.fontColor := "FFFFFF"
vk.autocomplete.fontName := "Segoe UI"
vk.autocomplete.fontSize := 14
vk.autocomplete.listbox.bkColor := vk.backgroundColor
vk.autocomplete.listbox.fontColor := "666666"
vk.autocomplete.listbox.fontName := "Segoe UI"
vk.autocomplete.listbox.fontSize := 11
vk.setHotkeys({}, 1, "Joy5")
vk.showHide()
vk.fitContent(16, 5, true)
vk.onSubmit(Func("vk_onSubmit"))
OnExit, handleExit
return

vk_onSubmit(this, _hLastFoundControl, _input) {
	ToolTip % _hLastFoundControl "," _input
	if (_hLastFoundControl)
		ControlSend,, % "{Text}" . _input, % "ahk_id " . _hLastFoundControl
	else SendInput % "{Text}" . _input
}

handleExit:
	vk.dispose()
ExitApp

!x::ExitApp

you can find this sample script, commented, in the examples folder. see also: Keyboard and joystick shortcuts to start using the script!

The library sets the following class variables:

• JSON (by coco)
• eAutocomplete
• Hotkey [_HotkeyIt, _Hotkey, __Hotkey__, _Hk, _Context, _JoyButtonKeypressHandler, ObjBindTimedMethod]
• Joystick
• Keypad [_Keypad, _KeypadEvents, _KeypadGraphicsMapping, _KeypadAXObjectWrapper]
• KeypadInterface
• vKeyboard

you can find the tree structure of the library in the lib folder.

The #Warn directive can be used to show a warning for each assignment targeting a class variable.

Syntax description for creating a new object derived from vKeyboard, using the new keyword:

vk := new vKeyboard() ; create a new instance of the visual keyboard object and stores it in 'vk'

The constructor throws an exception on failure.

note: the following list may not be exhaustive.

note: the following list may not be exhaustive.

note: the following list may not be exhaustive.

• defineLayout
• defineStyle
• setHotkeys
• setStyle
• setLayout
• setLayer
• showHide
• fitContent
• expand
• shrink
• redraw
• dispose

vKeyboard.defineLayout(_name, _pathOrContent, _defaultObjectWrapper:="", _defaultCallback:="")

The method throws an exception upon failure (for instance, if the keyboard layout JSON representation is badly formatted).

; usage examples:
; 1
vKeyboard.defineLayout("english", A_ScriptDir . "\myLayouts\english.json")
; 2
vKeyboard.defineLayout("français", A_ScriptDir . "\myLayouts\français.json",, "myFunc")
; somewhere in your script:
myFunc(this, _keyDescriptor, _count) {
	; some stuff
}
; 3
vKeyboard.defineLayout("русский", A_ScriptDir . "\myLayouts\русский.json", myEventHandler, "defaultCb")
; somewhere in your script:
Class myEventHandler {
	defaultCb(_vKeyboardInst, _keyDescriptor, _count) {
		; some stuff
	}
	onStarPress(_vKeyboardInst, _keyDescriptor, _count) {
		; some stuff
	}
}
/* somewhere in your keyboard layout mapping:
	...
	{ ; key descriptor
		"caption": "★",
		"f": "onStarPress"
	}
	...
*/

see also: Layout JSON representations.

vKeyboard.defineStyle(_name, _pathOrContent)

; usage examples:
vKeyboard.defineStyle("myCustomStyle", A_ScriptDir . "\myStyles\myCustomStyle.css")
cascadingStyleSheet =
(Join`r`n
body {
	background-color: #000000;
}
button.key {
	background-color: #111111;
	font-family: Segoe UI;
	color: #EA72C0;
}
button.key:focus {
	background-color: #333333;
	outline: none;
}
button.key:hover {
	background-color: #222222;
}
)
vKeyboard.defineStyle("myCustomStyle", cascadingStyleSheet)

see also: Styling the keyboard.

vk.setHotkeys(_obj, _joystickPort:=1, _joyModifier:="Joy5")

The method throws an exception upon failure.

The _obj parameter must observe the following tree structure:

├── "autocomplete"
│   ├── "keyboard"
│   ├── ├──[AUTOCOMPLETE_HOTKEYS]
│   ├── "joystick"
│   ├── ├──[AUTOCOMPLETE_HOTKEYS]
├── "keypad"
│   ├── "keyboard"
│   ├── ├──[KEYPAD_HOTKEYS]
│   ├── "joystick"
│   ├── ├──[KEYPAD_HOTKEYS]
├── "window"
│   ├── "keyboard"
│   ├── ├──[WINDOW_HOTKEYS]
│   ├── "joystick"
│   ├── ├──[WINDOW_HOTKEYS]

• where [AUTOCOMPLETE_HOTKEYS], [KEYPAD_HOTKEYS] and [WINDOW_HOTKEYS] stand respectively for the following objects:

{"listboxDismiss": [HOTKEY_NAME]
, "listboxSelectUp": [HOTKEY_NAME]
, "listboxSelectDown": [HOTKEY_NAME]
, "dataLookUp1": [HOTKEY_NAME]
, "dataLookUp2": [HOTKEY_NAME]
, "complete1": [HOTKEY_NAME]
, "complete2": [HOTKEY_NAME]} ; [AUTOCOMPLETE_HOTKEYS]

{"pressKey": [SINGLE_KEY_NAME]
, "altReset": [SINGLE_KEY_NAME]
, "sendBackSpace": [HOTKEY_NAME]
, "sendSpace": [HOTKEY_NAME]
, "startNewLine": [HOTKEY_NAME]
, "submit": [HOTKEY_NAME]
, "switchLayer": [HOTKEY_NAME]
, "decreaseFontSize": [HOTKEY_NAME]
, "increaseFontSize": [HOTKEY_NAME]
, "clearContent": [HOTKEY_NAME]} ; [KEYPAD_HOTKEYS]

{"showHide": [AHK_KEY_NAME]} ; [WINDOW_HOTKEYS]

• where [HOTKEY_NAME] can be any hotkey's activation key name supported by the hotkey command while also allowing, for joystick buttons, a 'modifier' to be specified. In this case, it must be represented by a ! (that is, an exclamation mark) right before the key name (e.g. !Joy3) - so that you would hold down _joyModifier then press the second joystick button (here Joy3) to trigger the joystick hotkey.
• where [AHK_KEY_NAME] can be any hotkey's activation key name supported by the hotkey command.
• where [SINGLE_KEY_NAME] must consist in a single key - either it is a joystick button name or a non-modifier keyboard key (e.g. a, F1, NumpadEnter, Insert, Tab etc.).
• In any case, do not specify the joystick number prefix in front of the control name (e.g. 1Joy3): use the second parameter instead to set the joystick number.

; usage examples:
vk.setHotkeys({}, 0) ; use default values
vk.setHotkeys({autocomplete:{keyboard:{"listboxSelectUp": "!Up", "listboxSelectUp": "!Down"}}}, 1)
vk.setHotkeys({window:{keyboard:{"showHide": "F11"}}}, 1)
obj :=
(LTrim Join C
{
	window: {
		keyboard: {
			"showHide": "F11" ; [AHK_KEY_NAME]
		}
	},
	keypad: {
		joystick: {
			pressKey: "Joy1", ; [SINGLE_KEY_NAME]
			sendBackSpace: "!Joy4" ; [HOTKEY_NAME]
		},
		keyboard: {
			pressKey: "NumpadEnter",
			sendBackSpace: "!Backspace"
		}
	}
}
)
vk.setHotkeys(obj, 2, "Joy2")

see also: Keyboard and joystick shortcuts.

vk.setStyle(_style)

The method throws an exception on failure.

vk.setLayout(_layout, _layer:=1, _center:=false)

The method throws an exception on failure.

vk.setLayer(_layer)

return value: the method returns 0 upon failure and the index of the new visual keyboard layout's layer upon success.

vk.showHide()

vk.fitContent(_size:="", _padding:=2, _center:=true)

vk.expand()

vk.shrink()

vk.redraw()

vk.dispose()

The script is able to call a user-defined callback for the following events:

• onKeyPress (not yet implemented)
• onSubmit
• onShowHide

Note that the autocomplete vKeyboard's object member has also its own event handling you can take advantage of.

vk.onKeyPress(Func("myKeyPressEventMonitor"))

[NOT YET IMPLEMENTED] Executes a custom function each time a keyboard's key is pressed or clicked. It is executed before the key's own f-function is actually called. The function can prevent the key's default behaviour by returning a non-zero integer.
The function can optionally accept the following parameters:
preventDefault := myKeyPressEventMonitor(this, _x, _y, _count, _key)

vk.onShowHide(Func("myShowHideEventMonitor"))

Executes a user-defined function each time the keyboard is shown/hidden (by means of the showHide method).
The function can optionally accept the following parameters:
myShowHideEventMonitor(this, _isVisible)

; usage example:
; ...
vk.onShowHide(Func("vk_onShowHide"))
return
; ...
vk_onShowHide(this, _isVisible) {
	ToolTip % _isVisible
}

vk.onSubmit(Func("mySubmitEventMonitor"))

Executes a user-defined function each time the text entered so far is submitted.
The function can optionally accept the following parameters:
mySubmitEventMonitor(this, _hLastFoundControl, _input)

; usage example:
; ...
vk.onSubmit(Func("vk_onSubmit"))
return
; ...
vk_onSubmit(this, _hLastFoundControl, _input) {
	if (_hLastFoundControl)
		ControlSend,, % "{Text}" . _input, % "ahk_id " . _hLastFoundControl
	else SendInput % "{Text}" . _input
}

Hotkeys default to the following values:

The vast majority of these hotkeys are customizable. See also: setHotkeys.

Use eAutocomplete.setSourceFromFile or eAutocomplete.setSourceFromVar to create a new autocomplete dictionary, respectively from a file’s content or from an input string. Thus, you can thereafter use at any time the setter/getter vk.autocomplete.source to set the autocomplete list to use for the visual keyboard.

see also: eAutocomplete - Custom autocomplete lists.

So far, you can use the following setters/getters to style - using 6-digit RGB color values - the autocomplete control:

• vk.autocomplete.bkColor
• vk.autocomplete.fontName
• vk.autocomplete.fontSize
• vk.autocomplete.fontColor
• vk.autocomplete.listbox.bkColor
• vk.autocomplete.listbox.fontName
• vk.autocomplete.listbox.fontSize
• vk.autocomplete.listbox.fontColor

; usage examples:
vk := new vKeyboard()
; ...
vk.autocomplete.bkColor := "000000" ; black
vk.autocomplete.fontColor := "FFFFFF" ; white
vk.autocomplete.listbox.bkColor := "000000"
vk.autocomplete.listbox.fontColor := "FFFFFF"

Besides, the script offers a basic css interface that allows you to indicate how the visual keyboard's keys should be rendered. You can use both the button.key and button.variant css selectors in your custom css stylesheet - as an example:

body {
	background-color: #000000;
}
/* the 'key' class identifies all keys but
the 'variants' ones (see comment below) */
button.key {
	background-color: #111111;
	font-family: Segoe UI;
	color: #EA72C0;
}
button.key:focus {
	background-color: #333333;
	outline: none;
}
button.key:hover {
	background-color: #222222;
}
/* the 'variant' class identifies all keys displayed when
the visual keyboard enters alt mode and suggests key
variants (e.g. letters with diacritics) to select from */
button.variant {
	color: #EA72C0;
}
button.variant:focus {
	background-color: #555555;
	outline: none;
}
button.variant:hover {
	background-color: #444444;
}

You must call the defineStyle base method to define a style. Thus, you can thereafter use the setStyle method to set at any time the style used to render the visual keyboard graphics.

note: The following provides extensive details on the implementation. You can also run the keymapMaker if you don't need to know the ins and outs of this layout stuff: by means of this script, you can the WYSIWYG-way create keyboard layouts, export and save them as Layout JSON representations.

The vKeyboard interface uses JSON-formatted object descriptions in order to represent keyboard layouts. These descriptions help the script determine the structure (layers, rows, columns etc.) but also the semantic content (key captions, key's associated callback function etc.) of the keyboard layout.

We can model, map a keyboard layout as a tri-dimensional array. Actually, it can be seen as one or more layers (z-axis), only one of them being visible at a given time - in that way:

• A layer can be described as a two-dimensional array: an array of rows (y-axis).
• A row can be itself described as an array of keys (x-axis).
• A key can be a descriptor; it can be either a string (for simple keys) or an object (for semantically richer keys).

The following example describes a bare keyboard layout (one layer, one row, one key):

[
    [
        [
            null
        ]
    ]
]

The following layout object representation describes a keyboard layout with just one layer and one row (consisting itself in three keys: two complex ones and a simple one):

[ ; keymap
	[ ; first layer (3rd dimension -z)
		[ ; first row (2nd dimension -y)
			{ ; first key (1st dimension -x)
				"caption": "★",
				"f": "myCustomFunc",
				"myCustomKey": "myCustomValue"
			},
			{ ; second key
				"caption": "a",
				"f": "keyWithVariantsProc",
				"params": [
					"å","â","ä","ā","à","ã","æ","à"
				]
			},
			"z" ; third key
		]
	]
]

You can find some basic examples of such keyboard layouts representations in the keymaps directory (/examples/test/keymaps).

Key descriptors are the constitutive elements of a keyboard layout mapping (see above). By default, if the descriptor is not an object, press or click the key will simply send its caption right on the keyboard's text entry field each time it is pressed or clicked. Otherwise, if a given descriptor is an object, the following properties have a special meaning for the script and are processed accordingly by it:

note: in cases where your key descriptor lacks all its optional keys, you can merely specify the letter which is intended to be displayed on the visual keyboard as a shorthand for the key descriptor object:{"caption": "a"} - which does works, but amounts to specify "a".

If a key descriptor is not an object, press or click the key will simply send its caption right on the keyboard's text entry field each time it is pressed or clicked: the built-it default callback and its default procedure will be used as associated f-function for the keyboard's key. You can modify this behaviour by specifying a custom default callback for a specific keymap when calling defineLayout.

example:
/*
assuming at least one of the key in your keyboard layout consists in the following descriptor...
{ ; key descriptor
	"caption": "★",
	"f": "myCustomFunc",
	"myCustomKey": "MsgBox!"
}
*/
; somewhere in your script:
myCustomFunc(this, _keyDescriptor, _count) {
	_msgBoxOption := this.alwaysOnTop ? 4096 : 0
	GUI % this.hostWindow.HWND . ":+OwnDialogs"
	MsgBox, % _msgBoxOption
			, % _keyDescriptor.myCustomKey
			, % "You pressed on the " . _keyDescriptor.caption . " key "
				. ((_count = -1) ? "a long time" : _count . "time(s)") . "!"
; return 0
}

The f key in the key descriptor allows you to specify a function to execute each time the keyboard's key is pressed or clicked. In case it is a non-zero integer, the return value of the callback will be used to set the altIndex accordingly.
The function can optionally accept the following parameters (where this refers to the vKeyboard instance, not the key descriptor object):
altIndex := myCustomFunc(this, _keyDescriptor, _count)

Unless you specified a custom default object wrapper when calling defineLayout, you don't necessary have to define in your script functions in order to handle key presses and clicks on the visual keyboard. Instead, you can specify one of the built-in f-functions and the params key in your key descriptor.

note: the following list may not be exhaustive.

{
	"caption": "i",
	"f": "keyWithVariantsProc",
	"params": [
		"ī","î","ï","ì","į","í"
	]
} ; each time the keyboard's key is long pressed/clicked, the visual keyboard
; enters alt mode and all params will be suggested as variants to select from

{
	"caption": "^",
	"f": "setAltIndexProc",
	"params": [
		2
	]
} ; 2 will set alt index to 2 so that if you click this key on the
; keyboard and then click on a key with variants (see above) the second
; variant will be sent

{
	"caption": "abc",
	"f": "altEntryModeProc",
	"params": [
		"a",
		"b",
		"c"
	]
} ; the index of the letter that will be sent depends on the amount
; of clicks/presses

{
	"caption": "◀",
	"f": "setCaretPosProc",
	"params": [
		-1
	]
} ; -1 shifts from right to left the caret/insert position; conversely, 1
; would shift from left to right the caret/insert position

{
	"caption": "↑",
	"f": "toLayerProc",
	"params": [
		2
	]
} ; 2 is the index of layer to navigate to

Unlicence