ktouch/keyboards/creating_keyboard_layouts.txt

   1 This is a short guide explaining the new keyboard layout files that will hopefully resolve all the problems with the last files.
   2 At first all keyboard files must be UTF-8 encoded, so that characters of other languages can be stored correctly.
   3
   4 A keyboad layout file is written in XML and contains three parts:
   5
   6 KeyboardFont -> Name of the Font to be used for the keyboard description
   7 KeyDefinitions -> Definition of the looks of the keyboard
   8 KeyAccess -> Definition of the characters and keys on the keyboard
   9
  10 The root element of the keyboard layout file is
  11
  12   <KeyboardLayout LanguageID="de" >
  13   </KeyboardLayout>
  14
  15 The language id attribute helps sorting the available keyboard layouts and also helps finding the correct keyboard layout depending on the systems keyboard setting.
  16
  17
  18 The KeyboardFont element definies which font should be used, several recommendations may be given, separated by | characters
  19 Example:
  20
  21 <KeyboardFont>Courier | Misc Console</KeyboardFont>
  22
  23
  24 The key definitions are used to draw the keyboard. First some examples:
  25
  26     <KeyDefinitions Options="ShowControlKeySymbols">
  27       <KeyDef Row="1" Slots="1" UpperChar="°" >^</KeyDef>
  28       <KeyDef Row="1" Slots="2" UpperChar="!" >1</KeyDef>
  29       <KeyDef Row="1" Slots="3" UpperChar="''" >2</KeyDef>
  30       <KeyDef Row="3" Slots="2" FingerKey="yes" >A</KeyDef>
  31       <KeyDef Row="3" Slots="3" FingerKey="yes" >S</KeyDef>
  32       <KeyDef Row="3" Slots="4" FingerKey="yes" >D</KeyDef>
  33       <KeyDef Row="3" Slots="5" FingerKey="yes" >F</KeyDef>
  34       <KeyDef Row="3" Slots="6" >G</KeyDef>
  35       <ControlKeyDef Row="4" Slots="1 2" UpperChar="Shift" >LeftShift</ControlKeyDef>
  36     </KeyDefinitions>
  37
  38 Please refer to the keyboard_grid.png file in ktouch/graphics where the key slots are defined.
  39 There are two kinds of key elements: KeyDef and ControlKeyDef.
  40 ControlKeyDef are keys that do not produce an actual character or are special characters (usually shift, control, alt, enter and space).
  41
  42 KeyDefs have the following attributes:
  43 Row - the row of the key
  44 Slots - one or more slots that are used by the key
  45 UpperChar - the character that is at the top left if two characters have to be printed on the key
  46 FingerKey - if set to yes, the key is marked as a key where the finger rests between typing.
  47
  48 The value of the KeyDef element has two meanings: it is the primary character that is printed on the key and also the reference character for the key access definitions (and thus must be unique in the keyboard layout).
  49
  50 ControlKeyDefs have the same attributes (no FingerKeys allowed here!), however the value is NOT to be translated, only the UpperChar attribute has to be translated in the appropriate language. The option "ShowControlKeySymbols" overrides the printing of the control key texts and causes KTouch to draw symbols for the keys instead. The values for the control keys are standardized and must be kept!!!
  51 Possible values are:
  52 LeftShift, RightShift, Tab, Backspace, CapsLock, Enter, LeftCtrl, LeftAlt, Space, RightAlt, RightCtrl, DummyKey
  53
  54
  55 Lastly the connection between a character and the corresponding key is made by KeyPressCombos, defined under KeyAccess:
  56
  57   <KeyAccess>
  58     <KeyPressCombo PressChar="^" KeyChar="^" />
  59     <KeyPressCombo PressChar="°" KeyChar="^" ControlKeyChar="RightShift" />
  60     <KeyPressCombo PressChar="a" KeyChar="A" />
  61     <KeyPressCombo PressChar="A" KeyChar="A" ControlKeyChar="RightShift" />
  62     <KeyPressCombo PressChar="s" KeyChar="S" />
  63     <KeyPressCombo PressChar="S" KeyChar="S" ControlKeyChar="RightShift" />
  64   </KeyAccess>
  65
  66  A keypress combo contains two character definitions, since the keyboard layouts are in UTF-8 it should not be a problem to store character definitions for any possible character table. The PressChar attribute defines the character that is generated by the keypresscombo, the KeyChar specifies which KeyDef has to be used. Since the normal characters are all written in capitals on the keyboard, but when pressed without shift a lower case character is created, the keyboard combos shown above are generated. Again, the keywords for the control keys must not be translated.
  67
  68
  69