rdesktop/doc/keymapping.txt

Keyboard mapping
================
This release of rdesktop uses a new, portable keyboard mapping
implementation. It should hopefully work on all X11 systems. This new
implementation only looks at X11 keysyms: Not on (nonportable)
keycodes or modifier status. This means that rdesktop will obey your
local keyboard configuration. For example, if you have swapped
CapsLock and Control, rdesktop will use this mapping. 

XKB is currently not used. It seems like a good idea to me, but since
some X servers (like Xvnc) does not support XKB, we still need to use
the plain old interface as well, at least. 

There are still some small problems.

* CapsLock: CapsLock changes are never sent to the RDP
  server. rdesktop does not know which keys that are modified by
  CapsLock and which are not. So, the CapsLock indicator in Wordpad
  etc will always be off.

Composing/Multi_key is supported. For more information, see:

  MIT:              $SRC/xc/nls/X11/locale/Compose/iso8859-1
  XFree86:          /usr/X11R6/lib/X11/locale/*/Compose
  Solaris' Openwin: /usr/openwin/include/X11/Suncompose.h
                    /usr/openwin/lib/locale/*/Compose
  Irix6:            compose(5)


Keymap files
============
The names of the keymaps follows RFC1766. 

(You can find a translation from Windows keyboard layout numbers to
keymap names by looking at
HKEY_LOCAL_MACHINE\SOFTWARE\Classes\MIME\Database\RFC1766 in the
registry.)


Contents of keymap files
========================
The keymaps are line based. There are four different types of lines:

1) include lines
Syntax:
include <another-map-file>

Example:
include common


2) map lines
Syntax:
map <hex-number>

Example:
map 0x41d

Map-lines specifies how the remote RDP server should interpret the
sent scancodes. 


3) Translation lines
Syntax:
<keysym-name> <scancode> [flags..]

Example:
onehalf 0x29 shift

The scancode can be found in scancodes.h. Note: The scancode value for
extended keys can be calculated by OR:ing with 0x80. Example: The
Delete key have the scancode sequence 0xe0, 0x52. You can get the
scancode value to put into the map file by running:

python -c "print hex(0x80 | 0x52)"

If flags are "altgr", "shift", the scancode sent for this keysym will
be prefixed with AltGr, or Shift.

If flags includes "addupper", a translation for this keysyms uppercase
name will be added as well, in addition to the non-uppercase
name. Example:

x 2d addupper

...will add an translation for "X" automatically, just like if you
would specify:

X 2d shift

If flags include "localstate", the modifier to send will be determined
by the local modifier state. 

If flags is "inhibit", nothing will be sent to the server. 

If flags is "numlock", rdesktop will make sure that the remote NumLock
state is on before generating the key event. Otherwise, it will make
sure NumLock is off.


4) enable_compose

If any line starts with the keyword "enable_compose", rdesktop will
enable local Compose/Multi_key handling. Enabling this will often make
it impossible to compose characters with dead keys (on the remote
side). This is because when local compose support is enabled, dead
keys will not be sent to the remote side. 


5) sequence lines
Syntax:
sequence <event-keysym-name> <keysym-name1> <keysym-name2> ...

Examples:
sequence eacute dead_acute e
sequence F12 f o o at e x a m p l e period c o m

Sequence lines allows you to specify that multiple scancodes should be
sent to the RDP server, in response to one X11 keyboard event. Note:
The sequence is sent at the X11 KeyPress event. Nothing is sent at
KeyRelease.


6) keyboard_type lines
Syntax:
keyboard_type <hex-number>
 
keyboard_type lines specifies the keyboard type. Default value is 0x4
(en-us 101/104 keys keyboard).


7) keyboard_subtype lines
Syntax:
keyboard_subtype <hex-number>

keyboard_subtype lines specifies the keyboard subtype. Default value
is 0x0 (en-us 101/104 keys keyboard).


8) keyboard_functionkeys lines
Syntax:
keyboard_functionkeys <hex-number>

keyboard_functionkeys specifies the number of keyboard function
keys. Default value is 0xc (12, for standard 101/104 keys keyboard).


Suggested X11 keysym mapping on PCs
===================================
Unfortunately, there is no standard for which keysyms a given key
should generate. If you have a PC-keyboard with Windows keys, I suggest this mapping:

Keyboard keys:
CtrlLeft WinLeft AltLeft Space AltGr WinRight Menu CtrlRight

...should generate keysyms:
Control_L Super_L Alt_L space Mode_switch Super_R Menu Control_R

Additionally:
Shift-Alt should produce Meta_L
Shift-AltGr should produce Multi_Key. 

Use a modifier-map like this:

shift       Shift_L (0x32),  Shift_R (0x3e)
lock        Caps_Lock (0x25)
control     Control_L (0x42),  Control_R (0x6d)
mod1        Alt_L (0x40)
mod2        Num_Lock (0x4d)
mod3        Mode_switch (0x71)
mod4        Super_L (0x73),  Super_R (0x74)
mod5        Scroll_Lock (0x4e)


Updating / writing keymap files
===============================
When writing new or updating keymap files, please use comments and
blanks, to increase readability. The "sv" keymap is a good template. 

When you need to add a translation to a keymap file, do:

    1. Get the "key number" for this key, by looking at keynums.png. 

    2. Take a look at scancodes.h, and look for
    SCANCODE_KEY_<my-key-number>. The scancode value is at the end of
    the line. If the line contains (SCANCODE_EXTENDED | 0xsomething),
    then you should OR 0x80 to this value. For example, you can do:
    
    python -c "print hex(0x80 | 0xsomething)"

    3. Put the scancode (from step 2) and keysym name (found in the
    error message) into the keymap file. 


Special keys
============

* The combination Ctrl-Alt-Enter toggles between fullscreen and
  non-fullscreen mode. 

* Meta, Hyper and Super are treated as windows keys. RDP4 does not
  support the windows keys though, so if you are running RDP4, these
  keys will translate to Ctrl-Esc. 


Links
=====
http://www.win.tue.nl/~aeb/linux/kbd/scancodes.html


Test cases
==========
When changing the keyboard code, make sure all these tests in Notepad
works:

1. Ctrl+f should bring up Find dialog, with CapsLock both on and off. 

2. Ctrl+Shift+arrows should mark text, with CapsLock both on and off. 

3. Test a sequence, like egrave. 

4. Test a char generated with AltGr, such as @ on a swedish keyboard. 

5. Test Ctrl-Alt-Delete. 

6. Ctrl-Alt-Enter should toggle fullscreen. 

7. Test NumLock synchronization using the -N option. Excel is able to
   indicate the current NumLock state. Verify that the status is
   updated correctly on reconnects. 

8. Test the Windows keys, standalone as well as in combination with,
   say, E.

9. Make sure the system menu (via Alt-space) cannot be accessed in
   single app mode.

10. Make sure keymaps can be loaded from ~/.rdesktop/keymaps,
    KEYMAP_PATH, $CWD/keymaps, and from an absolute path. 

11. Press Shift, then press a key modified by shift, the release
    shift, then release the other key.  Do this in a speedy fasion.
    Make sure the shift state is not stuck down.

12. Test all numpad keys, when not using the -N option. 

13. Map a single, un-shifted key (such as F1) to XK_A:
    xmodmap -e "keycode 67 = A A"

    Perform in Notepad:
    * Write some text
    * Press F1
    * Press b
    * Release b
    * Release F1

    Verify that shift is not stuck down, by clicking on the text. 
1	astrand	104	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	astrand	543	* 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	astrand	104
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	astrand	167	Keymap files
31	astrand	272	============
32			The names of the keymaps follows RFC1766.
33	astrand	167
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	astrand	166	The keymaps are line based. There are four different types of lines:
43	astrand	104
44	astrand	949	1) include lines
45	astrand	104	Syntax:
46			include <another-map-file>
47
48	astrand	949	Example:
49			include common
50	astrand	104
51	astrand	949
52			2) map lines
53	astrand	104	Syntax:
54			map <hex-number>
55
56	astrand	949	Example:
57			map 0x41d
58
59	astrand	104	Map-lines specifies how the remote RDP server should interpret the
60			sent scancodes.
61
62
63	astrand	949	3) Translation lines
64	astrand	104	Syntax:
65			<keysym-name> <scancode> [flags..]
66
67	astrand	949	Example:
68			onehalf 0x29 shift
69
70	astrand	104	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	astrand	949	If flags are "altgr", "shift", the scancode sent for this keysym will
78			be prefixed with AltGr, or Shift.
79	astrand	104
80	astrand	949	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	astrand	104
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	astrand	116	If flags is "inhibit", nothing will be sent to the server.
95	astrand	104
96	astrand	1216	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	astrand	116
100	astrand	1216
101	astrand	104	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	astrand	949	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	astrand	964	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	astrand	104	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	astrand	752	Control_L Super_L Alt_L space Mode_switch Super_R Menu Control_R
160	astrand	104
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	astrand	752	mod4 Super_L (0x73), Super_R (0x74)
174	astrand	104	mod5 Scroll_Lock (0x4e)
175	astrand	272
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	astrand	434
196
197	astrand	454	Special keys
198			============
199
200			* The combination Ctrl-Alt-Enter toggles between fullscreen and
201			non-fullscreen mode.
202
203	astrand	455	* Meta, Hyper and Super are treated as windows keys. RDP4 does not
204	astrand	454	support the windows keys though, so if you are running RDP4, these
205			keys will translate to Ctrl-Esc.
206
207
208	astrand	434	Links
209			=====
210			http://www.win.tue.nl/~aeb/linux/kbd/scancodes.html
211	astrand	1220
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	jsorg71	1406	11. Press Shift, then press a key modified by shift, the release
244			shift, then release the other key. Do this in a speedy fasion.
245			Make sure the shift state is not stuck down.
246	astrand	1419
247			12. Test all numpad keys, when not using the -N option.
248
249			13. Map a single, un-shifted key (such as F1) to XK_A:
250			xmodmap -e "keycode 67 = A A"
251
252			Perform in Notepad:
253			* Write some text
254			* Press F1
255			* Press b
256			* Release b
257			* Release F1
258
259			Verify that shift is not stuck down, by clicking on the text.