base/applications/tsclient/rdesktop/doc/keymapping.txt

   1 Keyboard mapping
   2 ================
   3 This release of rdesktop uses a new, portable keyboard mapping
   4 implementation. It should hopefully work on all X11 systems. This new
   5 implementation only looks at X11 keysyms: Not on (nonportable)
   6 keycodes or modifier status. This means that rdesktop will obey your
   7 local keyboard configuration. For example, if you have swapped
   8 CapsLock and Control, rdesktop will use this mapping.
   9
  10 XKB is currently not used. It seems like a good idea to me, but since
  11 some X servers (like Xvnc) does not support XKB, we still need to use
  12 the plain old interface as well, at least.
  13
  14 There are still some small problems.
  15
  16 * CapsLock: CapsLock changes are never sent to the RDP
  17   server. rdesktop does not know which keys that are modified by
  18   CapsLock and which are not. So, the CapsLock indicator in Wordpad
  19   etc will always be off.
  20
  21 Composing/Multi_key is supported. For more information, see:
  22
  23   MIT:              $SRC/xc/nls/X11/locale/Compose/iso8859-1
  24   XFree86:          /usr/X11R6/lib/X11/locale/*/Compose
  25   Solaris' Openwin: /usr/openwin/include/X11/Suncompose.h
  26                     /usr/openwin/lib/locale/*/Compose
  27   Irix6:            compose(5)
  28
  29
  30 Keymap files
  31 ============
  32 The names of the keymaps follows RFC1766.
  33
  34 (You can find a translation from Windows keyboard layout numbers to
  35 keymap names by looking at
  36 HKEY_LOCAL_MACHINE\SOFTWARE\Classes\MIME\Database\RFC1766 in the
  37 registry.)
  38
  39
  40 Contents of keymap files
  41 ========================
  42 The keymaps are line based. There are four different types of lines:
  43
  44 1) include lines
  45 Syntax:
  46 include <another-map-file>
  47
  48 Example:
  49 include common
  50
  51
  52 2) map lines
  53 Syntax:
  54 map <hex-number>
  55
  56 Example:
  57 map 0x41d
  58
  59 Map-lines specifies how the remote RDP server should interpret the
  60 sent scancodes.
  61
  62
  63 3) Translation lines
  64 Syntax:
  65 <keysym-name> <scancode> [flags..]
  66
  67 Example:
  68 onehalf 0x29 shift
  69
  70 The scancode can be found in scancodes.h. Note: The scancode value for
  71 extended keys can be calculated by OR:ing with 0x80. Example: The
  72 Delete key have the scancode sequence 0xe0, 0x52. You can get the
  73 scancode value to put into the map file by running:
  74
  75 python -c "print hex(0x80 | 0x52)"
  76
  77 If flags are "altgr", "shift", the scancode sent for this keysym will
  78 be prefixed with AltGr, or Shift.
  79
  80 If flags includes "addupper", a translation for this keysyms uppercase
  81 name will be added as well, in addition to the non-uppercase
  82 name. Example:
  83
  84 x 2d addupper
  85
  86 ...will add an translation for "X" automatically, just like if you
  87 would specify:
  88
  89 X 2d shift
  90
  91 If flags include "localstate", the modifier to send will be determined
  92 by the local modifier state.
  93
  94 If flags is "inhibit", nothing will be sent to the server.
  95
  96 If flags is "numlock", rdesktop will make sure that the remote NumLock
  97 state is on before generating the key event. Otherwise, it will make
  98 sure NumLock is off.
  99
 100
 101 4) enable_compose
 102
 103 If any line starts with the keyword "enable_compose", rdesktop will
 104 enable local Compose/Multi_key handling. Enabling this will often make
 105 it impossible to compose characters with dead keys (on the remote
 106 side). This is because when local compose support is enabled, dead
 107 keys will not be sent to the remote side.
 108
 109
 110 5) sequence lines
 111 Syntax:
 112 sequence <event-keysym-name> <keysym-name1> <keysym-name2> ...
 113
 114 Examples:
 115 sequence eacute dead_acute e
 116 sequence F12 f o o at e x a m p l e period c o m
 117
 118 Sequence lines allows you to specify that multiple scancodes should be
 119 sent to the RDP server, in response to one X11 keyboard event. Note:
 120 The sequence is sent at the X11 KeyPress event. Nothing is sent at
 121 KeyRelease.
 122
 123
 124 6) keyboard_type lines
 125 Syntax:
 126 keyboard_type <hex-number>
 127
 128 keyboard_type lines specifies the keyboard type. Default value is 0x4
 129 (en-us 101/104 keys keyboard).
 130
 131
 132 7) keyboard_subtype lines
 133 Syntax:
 134 keyboard_subtype <hex-number>
 135
 136 keyboard_subtype lines specifies the keyboard subtype. Default value
 137 is 0x0 (en-us 101/104 keys keyboard).
 138
 139
 140 8) keyboard_functionkeys lines
 141 Syntax:
 142 keyboard_functionkeys <hex-number>
 143
 144 keyboard_functionkeys specifies the number of keyboard function
 145 keys. Default value is 0xc (12, for standard 101/104 keys keyboard).
 146
 147
 148
 149
 150 Suggested X11 keysym mapping on PCs
 151 ===================================
 152 Unfortunately, there is no standard for which keysyms a given key
 153 should generate. If you have a PC-keyboard with Windows keys, I suggest this mapping:
 154
 155 Keyboard keys:
 156 CtrlLeft WinLeft AltLeft Space AltGr WinRight Menu CtrlRight
 157
 158 ...should generate keysyms:
 159 Control_L Super_L Alt_L space Mode_switch Super_R Menu Control_R
 160
 161 Additionally:
 162 Shift-Alt should produce Meta_L
 163 Shift-AltGr should produce Multi_Key.
 164
 165 Use a modifier-map like this:
 166
 167 shift       Shift_L (0x32),  Shift_R (0x3e)
 168 lock        Caps_Lock (0x25)
 169 control     Control_L (0x42),  Control_R (0x6d)
 170 mod1        Alt_L (0x40)
 171 mod2        Num_Lock (0x4d)
 172 mod3        Mode_switch (0x71)
 173 mod4        Super_L (0x73),  Super_R (0x74)
 174 mod5        Scroll_Lock (0x4e)
 175
 176
 177 Updating / writing keymap files
 178 ===============================
 179 When writing new or updating keymap files, please use comments and
 180 blanks, to increase readability. The "sv" keymap is a good template.
 181
 182 When you need to add a translation to a keymap file, do:
 183
 184     1. Get the "key number" for this key, by looking at keynums.png.
 185
 186     2. Take a look at scancodes.h, and look for
 187     SCANCODE_KEY_<my-key-number>. The scancode value is at the end of
 188     the line. If the line contains (SCANCODE_EXTENDED | 0xsomething),
 189     then you should OR 0x80 to this value. For example, you can do:
 190
 191     python -c "print hex(0x80 | 0xsomething)"
 192
 193     3. Put the scancode (from step 2) and keysym name (found in the
 194     error message) into the keymap file.
 195
 196
 197 Special keys
 198 ============
 199
 200 * The combination Ctrl-Alt-Enter toggles between fullscreen and
 201   non-fullscreen mode.
 202
 203 * Meta, Hyper and Super are treated as windows keys. RDP4 does not
 204   support the windows keys though, so if you are running RDP4, these
 205   keys will translate to Ctrl-Esc.
 206
 207
 208 Links
 209 =====
 210 http://www.win.tue.nl/~aeb/linux/kbd/scancodes.html
 211
 212
 213 Test cases
 214 ==========
 215 When changing the keyboard code, make sure all these tests in Notepad
 216 works:
 217
 218 1. Ctrl+f should bring up Find dialog, with CapsLock both on and off.
 219
 220 2. Ctrl+Shift+arrows should mark text, with CapsLock both on and off.
 221
 222 3. Test a sequence, like egrave.
 223
 224 4. Test a char generated with AltGr, such as @ on a swedish keyboard.
 225
 226 5. Test Ctrl-Alt-Delete.
 227
 228 6. Ctrl-Alt-Enter should toggle fullscreen.
 229
 230 7. Test NumLock synchronization using the -N option. Excel is able to
 231    indicate the current NumLock state. Verify that the status is
 232    updated correctly on reconnects.
 233
 234 8. Test the Windows keys, standalone as well as in combination with,
 235    say, E.
 236
 237 9. Make sure the system menu (via Alt-space) cannot be accessed in
 238    single app mode.
 239
 240 10. Make sure keymaps can be loaded from ~/.rdesktop/keymaps,
 241     KEYMAP_PATH, $CWD/keymaps, and from an absolute path.
 242
 243