For full details on any of the changes, see the appropriate reference page.

This language reference describes the keyboard programming language of Tavultesoft Keyboard Manager.

You can check for the latest version of this document at http://www.tavultesoft.com/keyman/docs/.

The layout of a keyboard file is organized in two distinct parts: the header, and the body of the code.

The header consists of statements that provide information about the keyboard: the name, version of Keyman it was created for, hotkeys, and title bar icons. The header must come at the start of the file. The statements should be entered uppercase so as to distinguish them from statements in the main body of the code; however, Keyman will recognize them anyway.

The body of the keyboard can contain stores and groups of rules.

Stores are used to keep a table of keys which can be referenced to a second table of output characters. Rules are the heart of a keyboard file. They describe the action Keyman should take when processing a key combination. They can be dependent on the context of characters before them and produce any characters that you wish.

Rules are placed in groups. Each group can contain one or more rules; a group is similar in many ways to a subroutine or procedure in Visual Basic. Most keyboards will not need multiple groups. See the use statement for more information about groups.

Stores are described in more detail in the store statement reference.

Each rule consists of three parts: the context, keystroke, and output. Either the context or the keystroke are optional in some situations. The context is what is compared to characters already on the screen. The keystroke is compared to the key you type, and the output is what will replace and supplement the context on the screen.

Keyman has a buffer for the screen characters of 64 bytes. The length of the context and the output is by default 16 bytes for each. These limits can be set in the [Advanced] section of KEYMAN.INI. See the Keyman User’s Manual for more information on KEYMAN.INI.

Rules can have an optional context. The base context is the characters that were output to the screen after Keyman translated them. The base context is usually 64 characters long and the rule context is usually 16 characters long, although both are modifiable. You can compare the rule context to the base context; if it matches (and the key too), that rule will be used in the output of the new string. The context, output and keystroke are specified in ExtendedString format.

The three parts of a rule (context, key, and output) are put together in a style similar to SIL CC:

Context + Key > Output

The '+' is an optional character; it is just supplied to make it easier to see the break between context and key. Note: The plus character ('+') may be required in later versions of Keyman. The simplest type of rule is simply one-to-one key mapping. The most complex can have a table of keys which can be referenced in many different ways to match the context.

The different types of variables/constants and the prefixes usually used when describing them are:

The ExtendedString and ExtendedChar formats are strings/characters that can be written as a quoted string and/or decimal/hexadecimal/octal codes. An extended string can be made up of any amount of these different codes. There are five ways of representing any character in the string; these are shown in the table below:

The extended string format can also include statements such as any and index that will be converted and/or expanded to the correct sequences in memory when the keyboard is loaded.

A comment can be inserted in a line by preceding it with a 'c' identifier. The identifier must be preceded and followed with a space character. The comment continues until the end of the line.

Windows 95 and NT have a standard definition for languages that Keyman 4 integrates with. Each language is given a code (shown in the table below), and dialects of this language are given sub-codes. The standard defined languages are shown below; for other, undefined languages, either use a new sub-langauge code in an existing, related language, or use the user-defined language codes x200 to x3ff and sub-language codes x20 through x3f.

If you decide to use a user-defined code, you can request a unique code for your language at http://www.tavultesoft.com/keyman/langcode/. Tavultesoft will then keep track of the languages by assigning codes to ensure that Keyman keyboards will not conflict with each other. If you do not plan to use the keyboard in conjunction with any others, or to distribute it to other people, it is safe to use any language code you wish.

LANGUAGE x2b, x01 c Laotian standard

LANGUAGE x0d, x04 c Hebrew standard

LANGUAGE x200, x20 c User-defined language

Keyman 4 keyboards have a provision to display a copyright message when they are installed. This statement is optional.

The HOTKEY statement specifies the hotkey that Keyman will use to turn the keyboard on. When this hotkey is pressed, any active keyboard will be turned off and the new keyboard will be turned on.

The hotkey can be any letter key, with any of the Shift,Control and/or Alt keys also held down. The specification of the HOTKEY statement follows the Microsoft standard for hotkeys in Windows. Inside a double-quoted string, you can combine the letter key with special characters to identify the shift state:

Starting with version 3.1, the hotkey can also be in Virtual Key format, so that you can use any key on the keyboard.

HOTKEY "^+A" c Ctrl+Shift+A

HOTKEY [Alt Shift K_PAUSE] c Alt+Shift+Pause

This is a generic message, such as a shareware notice that you can display when the keyboard is installed. This statement is optional.

The any statement will, in effect, return true if the character input is in the store snStore. The character input is implied. This statement is only valid on the left side of a rule; the index statement is used to output the results of an any in the output. If an any is used in the key, it will be expanded out to include one rule for each character in the store. The any statement remembers the offset in the store where the match for later use with the index statement.

snStore: The name of the store to check in

The beep statement produces a beep at the system speaker when the rule is matched. If you have a sound driver installed, beep will produce the sound specified by "Asterisk" in the Sounds option in Control Panel. When using the beep statement, remember that it can delete all that was matched on the left side of the rule if you don't precede it with context or appropriate characters. The beep statement is only valid in the output. The example given below will, if it receives a key that is in the key group, and the context ends with a cons character, ignore the key and leave the context alone.

The context statement simply reproduces the context stored from the rule match into the output. Use the context statement as much as possible as it is significantly faster than using the index statement.

The deadkey statement lets you program a deadkey in your keyboard. The deadkey will be the same as a normal character, but it won't come up on the screen. You can have up to 254 deadkeys, from 1 to 255.

nKey: A number from 1 to 255 that identifies the deadkey

+ '`' > deadkey(1)

deadkey(1) + 'e' > 'è'

group tells Keyman that a new group has started. There are two sorts of groups: key processing groups, and context processing groups. Key processing groups can include context checking, but context processing groups cannot include key checking. Keyman will use first the group specified in the begin statement, and move from there onto other groups. The keystroke received by Keyman is the same for all groups with key processing.

To tell Keyman that the group should include key processing, you should include the using keys section of the statement; it that is left out, Keyman assumes the group checks the context only. The keystroke will remain the same during processing; you can have many groups that each use using keys, and the keystroke will be the same for all of them. If you leave out the using keys bit, you have to also leave out the '+' and the keystroke, because if you leave them in, the keystroke will be regarded as part of the context.

gnGroup: The name of the new group.

group(main) using keys

group(syllablecheck)

The index statement gets the offset of the character from the left side of the rule at offset nOffset. The offset refers to the position, including other characters, to the any statement which has saved the offset which it found the character in. The index will output the character at that offset from the store snStore. If used carefully, the index and any combination can be very powerful. The index statement is only valid in the output.

snStore: The store to output from

nOffset: The offset in the input to retrieve the any information from.

In each group, if Keyman finds a match rule, it will use it when a rule in the group was matched. A match rule can include use, return, beep and normal characters.

esString: The extended string to output, including the statements mentioned above.

nomatch is similar to match, but instead of the rule being used when a rule was matched, it will be used when a rule isn't matched in the group. A nomatch rule can include use, return, beep and normal characters.

esString: The extended string to output, including the statements mentioned above.

The nul statement will delete the context and key on the left hand side of the rule from the output; it is equivalent to having an empty output (which is not allowed). The nul statement probably will not be used often, because there are not many times you would want to delete the context and keystroke. The nul command must be the only character or command on the right hand side of the rule

no parameters

The outs statement simply copies the store snStore into the position in which it has been inserted. Most of the time this is used only in stores but it can be used in the context and output as well.

snStore: The store to expand

return will tell Keyman to stop processing rules and wait for the next keystroke to come. Keyman will not return to process other groups that called the one with the return statement.

no parameters

The store statement lets you store a string of characters or keys in a buffer which can then be referenced with any and index. Proper use of store can reduce many keyboards down to a few rules. A store is terminated at the end of the line (or continuation lines).

snStore: The name of the store to use

xsData: The data to place into the store snStore

The use statement tells Keyman to switch processing to a new group; after Keyman has gone through the new group, and any other nested groups, it will return to the previous one. The use statement can be used with the match and nomatch rules; it will work the same way.

gnGroup: The name of the group to switch control to.