InternationalKeyboard 0.50
==========================
This document describes version 0.50 of the International Keyboard module.
Version 0.50 is a significant break from previous versions in that:
1) All keyboard definitions are in terms of the Universal Character Set
(UCS).
2) Keyboards with two layers are supported.
3) All keyboards will work with any alphabet.
4) Keyboard definitions are now described textually.
5) Special keys like Caps Lock are now relocatable.
6) The module understands *Alphabet UTF8.
7) Unusual Caps Lock pairings are now possible (eg Swiss � key)
8) Dead key tables much fuller - for example it is now possible to
generate r-acute on the UK layout, if r-acute is in the current
alphabet.
From the user's point of view, the new module providing the UK layout should
be identical when the alphabet is Latin-1, but the difference will show when a
different alphabet is selected. The differences can be summarised by the following
table showing the codes inserted into the keyboard buffer for different key
sequences with different *Alphabet settings:
Previous UK keyboard driver:
Current Alphabet
Key sequence Latin1 Welsh UTF8
A 61 = a 61 = a 61 = a
F1 81 = F1 81 = F1 81 = F1
Shift-3 00 A3 = pound 00 A3 = pound 00 A3 = [illegal]
Shift-` 00 AC = not sign 00 AC = Y-grave 00 AC = [illegal]
Alt-' W 00 82 = w-circ 00 82 = [illegal] 00 82 = [illegal]
Alt-[ W 77 = w 77 = w 77 = w
Alt-keypad 1,8,9 00 BD = one-half 00 BD = W-diaeresis 00 BD = [illegal]
Alt-1,2,4,0,2 72 = r 72 = r 72 = r
New UK keyboard driver:
Current Alphabet
Key sequence Latin1 Welsh UTF8
A 61 = a 61 = a 61 = a
F1 81 = F1 81 = F1 81 = F1
Shift-3 00 A3 = pound 00 A3 = pound 00 C2 00 A3 = pound
Shift-` 00 AC = not sign no output 00 C2 00 AC = not sign
Alt-' W 00 82 = w-circ 00 F0 = w-circ 00 C5 00 B5 = w-circ
Alt-[ W 77 = w 00 BA = w-acute 00 E1 00 BA 00 83 = w-acute
Alt-keypad 1,8,9 00 BD = one-half 00 BD = W-diaeresis 00 C2 00 BD = one-half
Alt-1,2,4,0,2 72 = r 72 = r 00 E3 00 81 00 B2 = hiragana "hi"
The InternationalKeyboard module uses Service_International 8 to read the UCS mapping
for the current alphabet - if unable to find the UCS map for the current alphabet
it maps UCS codes 80-FF to 00 80 - 00 FF.
Layout files
============
Layouts are now described in a textual layout file.
Blank lines and lines beginning with # are ignored. The file is delimited by
directives beginning with $. The first directive should be $Country <n>. This may be
followed by multiple $Layer sections, and optionally a $Keypad section.
$Layer
======
A layer section begins with a $Layer <n> line, and is terminated by $EndLayer.
The primary layer is numbered 0, and a second layer (1) may be supplied. This layer
is used if OS_Byte 202 bit 5 is clear.
The layer section contains a series of key definitions, in any order. A key
definition consists of a 2-digit hex number on the first line, followed by eight
lines giving the character for each part of a key:
<key number> {replace}
<key>
<Shift+key>
<Ctrl+key>
<Ctrl+Shift+key>
<Alt+key>
<Alt+Shift+key>
<Alt+Ctrl+key>
<Alt+Ctrl+Shift+key>
To replace a previously defined character (which may be required when included
files are in use), you must add the word "replace" after the key number.
The 10 standard modifier keys (Left Shift, Right Shift, Left Ctrl, Right Ctrl,
Left Alt, Right Alt, Select, Menu, Adjust, Break) need not, and indeed cannot,
be specified in a layer. However, it is possible to override the behaviour
of any of these keys to act like a standard key.
Any pairs of characters may be tagged as a capital/lower case pair by placing
a bracket symbol in front of each character name. Bracket symbols are [], {},
<> and () - the opening bracket marks the lower-case character and the closing
bracket marks the upper-case character. Keys should be defined with the
characters as if Caps Lock is off - the bracket characters tell the key how
to behave if Caps Lock or Shift-Caps Lock is on.
A character name may take the form of
1) A UCS identifier, such as:
LATIN CAPITAL LETTER A (ie U+0041)
EURO SIGN (ie U+20AC)
CJK UNIFIED IDEOGRAPH-5F24 (ie U+5F24)
HANGUL SYLLABLE GGAS (ie U+AE5F)
2) A control code:
FUNCTION KEY CTRL-Q (ie &11)
FUNCTION KEY CTRL-? (ie &7F)
3) A function key specifier:
FUNCTION KEY F1 (ie &81)
FUNCTION KEY CTRL-UP (ie &AF)
FUNCTION KEY CTRL-SHIFT-ENTER (ie &0D)
FUNCTION KEY &FE (ie &FE)
Valid code names are:
08 BACKSPACE
0D ENTER
1B ESCAPE
1E HOME
7F DELETE
80 PRINT / F0
81 F1
82 F2
83 F3
84 F4
85 F5
86 F6
87 F7
88 F8
89 F9
8A BREAK
8B COPY / END
8C LEFT
8D RIGHT
8E DOWN
8F UP
9E PAGE DOWN
9F PAGE UP
C0 ACORN
C1 MENU
C2 WIDTH
C3 KANJI
C4 EISUU
C5 NO CONVERSION
C6 CONVERT
C7 KANA
C8 ALL CANDIDATES
C9 KANJI NUMBER
CA F10
CB F11
CC F12
CD INSERT
Any of these may be preceded by either of both of "CTRL-" or "SHIFT-"
(in that order). Under RISC OS, keys above &80 are exclusive ored
with &10 for Shift, and &20 for Ctrl, so CTRL-SHIFT-F10 is &FA.
Keys below &80 are not affected by Shift or Ctrl. However, it is
suggested that the SHIFT- and CTRL- suffixes be put in for future
compatibility. Likewise, "FUNCTION KEY ESCAPE" and "FUNCTION KEY CTRL-["
are totally equivalent at the moment, but might not always be - it
is probably better to use the higher-level description.
Note that there is normally no "FUNCTION KEY BREAK" - the Break key
is a hard-coded shifting key, and RISC OS inserts code &8A into the
keyboard buffer after a reset. The Wimp sets up Tab using OS_Byte 219
to produce code &8A.
Similarly, "FUNCTION KEY DELETE" gives traditional behaviour - there
is now a CMOS bit that determines whether Delete produces code &08
or &7F - use "SPECIAL KEY DELETE" to call the code that checks this bit.
4) A special key:
SPECIAL KEY SCROLL LOCK
Normally the special key will occupy all 8 shift/ctrl/alt variants, but
there are some exceptions. For example Caps Lock is only on the
shifted form of the key on a Japanese keyboard.
Special keys are those that require specific code to handle them. These
are:
CAPS LOCK
NUM LOCK
SCROLL LOCK
TAB
KANA LOCK
SHIFT-CAPS LOCK
DEFAULT KEYBOARD
CONFIGURED KEYBOARD
DIAL KEYBOARD
DELETE
Most keyboard layouts have the first four keys,
in their standard places. In these cases, you should not include
the keys in the layout file - this will save some memory. For each
key position &0E, &22, &26, &5D, if it is not mentioned in any
layer, it will perform its normal function in all layers. If it's
altered in any layer, it's function must be explicitly stated in
all layers.
TAB must be special because the code it generates can be altered using
OS_Byte 219.
SHIFT-CAPS LOCK toggles Shift-Caps on and off, irrespective of
the Shift key being held down. CAPS LOCK performs the normal
Caps Lock function, looking at the Shift key to determine whether
to toggle Caps Lock or enter Shift-Caps.
DEFAULT KEYBOARD selects the default (UK) keyboard. This is normally
assigned to Alt+Ctrl+F1.
CONFIGURED KEYBOARD selects the configured keyboard. This is normally
assigned to Alt+Ctrl+F2.
DIAL KEYBOARD allows the user to select a keyboard by entering the
appropriate international dialling code on the keypad while Alt remains
held down. This key must be in an Alt position, and is normally
assigned to Alt+Ctrl+F12.
DELETE produces either code &7F or &8B depending on the configuration.
5) A dead accent key:
DEAD KEY ACUTE ACCENT
DEAD KEY RING ABOVE
Valid dead keys are currently:
GRAVE ACCENT U+0300
ACUTE ACCENT U+0301
CIRCUMFLEX ACCENT U+0302
TILDE U+0303
MACRON U+0304
BREVE U+0306
DOT ABOVE U+0307
DIAERESIS / GREEK DIALYTIKA U+0308
RING ABOVE U+030A
DOUBLE ACUTE ACCENT U+030B
CARON U+030C
VERTICAL LINE ABOVE / GREEK TONOS U+030D
CEDILLA U+0327
OGONEK U+0328
GREEK DIALYTIKA TONOS U+0344
STROKE U+0335
Each entry shows the equivalent UCS code, although this is not
used internally.
These can easily be added to by extending the table generator and
Source.Accents, but once you get to 31 there will need to be
a code redesign.
6) Nothing:
-
$Keypad
=======
This section defines the 17 keypad keys, in order:
23 24 25
37 38 39 3A
48 49 4A 4B
5A 5B 5C ||
--65-- 66 67
If the section is omitted, the default keypad is used (saving memory):
$Keypad
SOLIDUS
ASTERISK
NUMBER SIGN
DIGIT SEVEN; FUNCTION KEY HOME
DIGIT EIGHT; FUNCTION KEY UP
DIGIT NINE; FUNCTION KEY PAGE UP
HYPHEN-MINUS
DIGIT FOUR; FUNCTION KEY LEFT
DIGIT FIVE; -
DIGIT SIX; FUNCTION KEY RIGHT
PLUS SIGN
DIGIT ONE; FUNCTION KEY END
DIGIT TWO; FUNCTION KEY DOWN
DIGIT THREE; FUNCTION KEY PAGE DOWN
DIGIT ZERO; FUNCTION KEY INSERT
FULL STOP; FUNCTION KEY DELETE
FUNCTION KEY ENTER
$EndKeypad
You need to supply seventeen lines, containing one or two key names
separated by a semicolon. The first is the character with Num Lock on,
the second with Num Lock off. If only one name is supplied, the key
is Num Lock invariant.
Note that it is currently only possible to put UCS codes 00-7F, RISC OS
function keys or nothing on the keypad.
$LeftAltLayerSwitch
===================
This directive, initially added for the Russian layout, enables the ISO
standard mechanism for switching between keyboard layers. If this directive
is included in a layout file, then the left-hand Alt key will can no longer
be used in conjunction with other keys to get extra characters. Instead, its
only function is to switch between the keyboard layers when pressed with
either Shift key.
In the future, if more than two layers are allowed, the left-hand Alt key
will cycle between the layers, in a direction determined by which Shift key
is pressed.
%Include
========
A simple facility for inclusion of other files is available - just
place "%Include <filename>" on any line. The magic filename "@ExtraKeys@"
is the value of the command line parameter "-extra". If no -extra
parameter was specified, the include directive is ignored. In the future,
the @..@ syntax may be extended to a full macro capability.