1Keyboard mapping
2================
3This release of rdesktop uses a new, portable keyboard mapping
4implementation. It should hopefully work on all X11 systems. This new
5implementation only looks at X11 keysyms: Not on (nonportable)
6keycodes or modifier status. This means that rdesktop will obey your
7local keyboard configuration. For example, if you have swapped
8CapsLock and Control, rdesktop will use this mapping.
9
10XKB is currently not used. It seems like a good idea to me, but since
11some X servers (like Xvnc) does not support XKB, we still need to use
12the plain old interface as well, at least.
13
14There 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
21Composing/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
30Keymap files
31============
32The names of the keymaps follows RFC1766.
33
34(You can find a translation from Windows keyboard layout numbers to
35keymap names by looking at
36HKEY_LOCAL_MACHINE\SOFTWARE\Classes\MIME\Database\RFC1766 in the
37registry.)
38
39
40Contents of keymap files
41========================
42The keymaps are line based. There are four different types of lines:
43
441) include lines
45Syntax:
46include <another-map-file>
47
48Example:
49include common
50
51
522) map lines
53Syntax:
54map <hex-number>
55
56Example:
57map 0x41d
58
59Map-lines specifies how the remote RDP server should interpret the
60sent scancodes.
61
62
633) Translation lines
64Syntax:
65<keysym-name> <scancode> [flags..]
66
67Example:
68onehalf 0x29 shift
69
70The scancode can be found in scancodes.h. Note: The scancode value for
71extended keys can be calculated by OR:ing with 0x80. Example: The
72Delete key have the scancode sequence 0xe0, 0x52. You can get the
73scancode value to put into the map file by running:
74
75python -c "print hex(0x80 | 0x52)"
76
77If flags are "altgr", "shift", the scancode sent for this keysym will
78be prefixed with AltGr, or Shift.
79
80If flags includes "addupper", a translation for this keysyms uppercase
81name will be added as well, in addition to the non-uppercase
82name. Example:
83
84x 2d addupper
85
86...will add an translation for "X" automatically, just like if you
87would specify:
88
89X 2d shift
90
91If flags include "localstate", the modifier to send will be determined
92by the local modifier state.
93
94If flags is "inhibit", nothing will be sent to the server.
95
96If flags is "numlock", rdesktop will make sure that the remote NumLock
97state is on before generating the key event. Otherwise, it will make
98sure NumLock is off.
99
100
1014) enable_compose
102
103If any line starts with the keyword "enable_compose", rdesktop will
104enable local Compose/Multi_key handling. Enabling this will often make
105it impossible to compose characters with dead keys (on the remote
106side). This is because when local compose support is enabled, dead
107keys will not be sent to the remote side.
108
109
1105) sequence lines
111Syntax:
112sequence <event-keysym-name> <keysym-name1> <keysym-name2> ...
113
114Examples:
115sequence eacute dead_acute e
116sequence F12 f o o at e x a m p l e period c o m
117
118Sequence lines allows you to specify that multiple scancodes should be
119sent to the RDP server, in response to one X11 keyboard event. Note:
120The sequence is sent at the X11 KeyPress event. Nothing is sent at
121KeyRelease.
122
123
1246) keyboard_type lines
125Syntax:
126keyboard_type <hex-number>
127
128keyboard_type lines specifies the keyboard type. Default value is 0x4
129(en-us 101/104 keys keyboard).
130
131
1327) keyboard_subtype lines
133Syntax:
134keyboard_subtype <hex-number>
135
136keyboard_subtype lines specifies the keyboard subtype. Default value
137is 0x0 (en-us 101/104 keys keyboard).
138
139
1408) keyboard_functionkeys lines
141Syntax:
142keyboard_functionkeys <hex-number>
143
144keyboard_functionkeys specifies the number of keyboard function
145keys. Default value is 0xc (12, for standard 101/104 keys keyboard).
146
147
148
149
150Suggested X11 keysym mapping on PCs
151===================================
152Unfortunately, there is no standard for which keysyms a given key
153should generate. If you have a PC-keyboard with Windows keys, I suggest this mapping:
154
155Keyboard keys:
156CtrlLeft WinLeft AltLeft Space AltGr WinRight Menu CtrlRight
157
158...should generate keysyms:
159Control_L Super_L Alt_L space Mode_switch Super_R Menu Control_R
160
161Additionally:
162Shift-Alt should produce Meta_L
163Shift-AltGr should produce Multi_Key.
164
165Use a modifier-map like this:
166
167shift       Shift_L (0x32),  Shift_R (0x3e)
168lock        Caps_Lock (0x25)
169control     Control_L (0x42),  Control_R (0x6d)
170mod1        Alt_L (0x40)
171mod2        Num_Lock (0x4d)
172mod3        Mode_switch (0x71)
173mod4        Super_L (0x73),  Super_R (0x74)
174mod5        Scroll_Lock (0x4e)
175
176
177Updating / writing keymap files
178===============================
179When writing new or updating keymap files, please use comments and
180blanks, to increase readability. The "sv" keymap is a good template.
181
182When 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
197Special 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
208Links
209=====
210http://www.win.tue.nl/~aeb/linux/kbd/scancodes.html
211
212
213Test cases
214==========
215When changing the keyboard code, make sure all these tests in Notepad
216works:
217
2181. Ctrl+f should bring up Find dialog, with CapsLock both on and off.
219
2202. Ctrl+Shift+arrows should mark text, with CapsLock both on and off.
221
2223. Test a sequence, like egrave.
223
2244. Test a char generated with AltGr, such as @ on a swedish keyboard.
225
2265. Test Ctrl-Alt-Delete.
227
2286. Ctrl-Alt-Enter should toggle fullscreen.
229
2307. 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
2348. Test the Windows keys, standalone as well as in combination with,
235   say, E.
236
2379. Make sure the system menu (via Alt-space) cannot be accessed in
238   single app mode.
239
24010. Make sure keymaps can be loaded from ~/.rdesktop/keymaps,
241    KEYMAP_PATH, $CWD/keymaps, and from an absolute path.
242
243
244