Programmer's Guide - Keyboard Options
Introduction
Keyman 8 introduced support for dynamic keyboard options, which can be utilized in many different ways. Some applications of the use of keyboard options are:
Selection of alternate keyboard mappings, such as entering vowel modifiers before or after the vowel characters.
User control of whether to use CTRL or ALT etc. as a modifier key.
In languages where text is usually entered without word breaks, a user may choose whether or not to insert visible or invisible breaks at syllable boundaries.
A keyboard option setting can be changed temporarily during use of a keyboard, or saved (in the Windows registry) so that the same setting is used by default whenever the keyboard is used. Default option settings can be selected using Keyman Configuration. Keyboard options are implemented by allowing the contents of a store to be changed during use of the keyboard. (In earlier versions of Keyman, store contents are fixed during keyboard compilation and never changed during keyboard use.) Any number of options may be defined for a keyboard.
Keyboard Option Keywords
Four new keywords have been added to allow store content to be changed and tested. Stores used for keyboard options may be used in the context or output sections of a rule, but not to match the key section of a rule. A store referred to in an option keyword must have its default content defined with a store(...) statement somewhere in the keyboard source.
if
The if keyword allows any rule to be applied conditionally, according to whether or not the specified condition is true when the rule is to be used. The content of the store being used as a keyboard option can be compared with either a fixed string, or the content of another store. Note that since the match and nomatch keywords refer to all matched rules in a group, the if condition can be used in a match or nomatch rule.
The if keyword may be used in many different ways, such as:
-
to provide alternate output for particular keystrokes:
store(opt1) '0' if(opt1='1') + '$' > '£' -
to conditionally branch to different rule groups, for example to process pending context in different ways when the spacebar is pressed:
store(opt2) '0' if(opt2 ='1') + " " > use(ruleGroup1) if(opt2!='1') + " " > use(ruleGroup2) -
to set or change option values depending on the value of an option, or toggle between option settings:
store(opt3) '0' if(opt3 ='1') + [CTRL ALT "\"] > set(opt3='0') if(opt3!='1') + [CTRL ALT "\"] > set(opt3='1')
set
The set keyword used on the right hand side of a rule allows the content of a store to be defined dynamically, as a result of an entered key sequence. The set keyword does not change the option permanantly, and if Keyman is restarted, or Keyman Configuration modified, then the default option value will be restored.
Changing an option with the set keyword while using one application will change it for all applications if the "Select keyboard layout for all applications" Keyman Configuration option is set.
store(opt1) '0' + [CTRL ALT "1"] > set(opt1='1') + [CTRL ALT "2"] > set(opt1='2')
save
The save command saves a current option value in the Windows registry, to become the default option value for future use. The save command will often be used following a set command to make a change permanent, as in the following example, which will, in effect, permanently change the content of store opt1 from '0' to '1'.
store(opt1) '0' + [CTRL ALT "1"] > set(opt1='1') save(opt1)
reset
The reset command is used to restore an option to the current default value, either the value in the Windows registry from a previously matched rule using a save command, or else the store content as initialized in the keyboard source file.
+ [CTRL ALT "\"] > reset(opt1)
Setting Options with Keyman Configuration
In many situations, it is better to set an option using Keyman Configuration instead of dynamically with a rule being matched. For example, if a keyboard allows two different sequences to be used to get a particular result, most users would not want or need to change the option while the keyboard is being used, but simply select the appropriate option during keyboard installation and configuration. Including an Options Configuration file (options.htm) in the keyboard package allows keyboard options to be set during Keyboard Configuration, by selecting the Keyboard Options entry from the menu displayed by the Options button for the keyboard.
Typically, the Options Configuration file will contain a heading, a form with radio buttons, or some other way of entering an option value, and the javascript needed to load the settings. A sample Option Configuration file is shown here:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<html>
<head>
<title>S'gaw Karen Keyboard Options</title>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<style type='text/css'>
html, body { padding: 0; margin: 0; overflow: hidden }
#size { padding: 12px; border: solid 1px black; background: #ffffff }
p, label { font: 10pt Tahoma }
h1 { font: bold 16pt Tahoma; margin-top: 4px; }
#ok_button, #cancel_button { width: 100px }
#buttons { text-align: right; }
#formopt { padding: 2px 24px }
</style>
</head>
<body>
<div id='size'>
<h1>S'gaw Karen Keyboard Options</h1>
<form method='get' action='keyman:ok'>
<div id='formopt'>
<fieldset>
<label>Select how to type modifier:</label>
<p>
<input type='radio' value='' name='option_order' id='option_order_logical' checked='checked' /><label for='option_order_logical'> Logical order</label> (type modifier after the consonant)<br />
<input type='radio' value='visual' name='option_order' id='option_order_visual' /><label for='option_order_visual'> Visual order</label> (type modifier before the consonant)<br />
</p>
</fieldset>
<fieldset>
<label>Select syllable boundary behaviour:</label>
<p>
<input type='radio' value='' name='option_zwsp' id='option_zwsp_none' checked='checked' /><label for='option_zwsp_none'> Do not insert Zero Width Space (ZWSP)</label><br />
<input type='radio' value='zwsp' name='option_zwsp' id='option_zwsp_insert' /><label for='option_zwsp_insert'> Insert Zero Width Space (ZWSP)</label><br />
<input type='radio' value='test' name='option_zwsp' id='option_zwsp_test' /><label for='option_zwsp_test'> Test syllable boundaries</label> (insert "|" instead of ZWSP)<br />
</p>
</fieldset>
</div>
<p id='buttons'><input id='ok_button' type='submit' value='OK' /> <input id='cancel_button' type='reset' onclick='location.href="keyman:cancel"; return false;' value='Cancel' /></p>
</form>
</div>
<script type='text/javascript'>
(function() {
var loc = window.location.search.substr(1).split('&');
for(var i = 0; i < loc.length; i++)
{
var param = loc[i].split('=');
var key = decodeURIComponent(param[0]);
var val = decodeURIComponent(param[1]);
var elem = document.forms[0].elements[key];
if(elem)
{
if(typeof elem !== 'object' || typeof elem.length !== 'number') elem = [elem];
for(var j = 0; j < elem.length; j++)
if(elem[j].type == 'checkbox' || elem[j].type == 'radio')
elem[j].checked = elem[j].value == val;
else
elem[j].value = val;
}
}
})();
</script>
</body>
</html>
Two option store names used by the keyboard, option_order and option_zwsp, are set using this configuration file. User selection is then made from the following dialog, presented when Keyboard Options are selected during Keyman Configuration:
