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.

* NumLock handling: NumLock is switched off when typing a non-numlock
  key. rdesktop does not know which keys are NumLock-dependent and
  not. When you type a numlock-dependent key again, NumLock is
  switched on on the server again. The only problem really is that the
  NumLock indicator in Wordpad etc switches on and off when you type. 

* CapsLock: CapsLock changes are never sent to the RDP server. This is
  a problem of the same type as NumLock: 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 keymaps are line based. There are three different types of lines:

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


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

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


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

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", "numlock", the scancode sent for this
keysym will be prefix with AltGr, Shift or Numlock. 

If flags include "addupper", an translation for this keysyms uppercase
name will 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. 


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. 


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 Hyper_L Alt_L space Mode_switch Hyper_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        Hyper_L (0x73),  Hyper_R (0x74)
mod5        Scroll_Lock (0x4e)
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	* NumLock handling: NumLock is switched off when typing a non-numlock
17	key. rdesktop does not know which keys are NumLock-dependent and
18	not. When you type a numlock-dependent key again, NumLock is
19	switched on on the server again. The only problem really is that the
20	NumLock indicator in Wordpad etc switches on and off when you type.
21
22	* CapsLock: CapsLock changes are never sent to the RDP server. This is
23	a problem of the same type as NumLock: rdesktop does not know which
24	keys that are modified by CapsLock and which are not. So, the
25	CapsLock indicator in Wordpad etc will always be off.
26
27	Composing/Multi_key is supported. For more information, see:
28
29	MIT: $SRC/xc/nls/X11/locale/Compose/iso8859-1
30	XFree86: /usr/X11R6/lib/X11/locale/*/Compose
31	Solaris' Openwin: /usr/openwin/include/X11/Suncompose.h
32	/usr/openwin/lib/locale/*/Compose
33	Irix6: compose(5)
34
35
36	Keymap-files
37	============
38	The keymaps are line based. There are three different types of lines:
39
40	1) include-lines
41	Syntax:
42	include <another-map-file>
43
44
45	2) map-lines
46	Syntax:
47	map <hex-number>
48
49	Map-lines specifies how the remote RDP server should interpret the
50	sent scancodes.
51
52
53	3) Translation-lines
54	Syntax:
55	<keysym-name> <scancode> [flags..]
56
57	The scancode can be found in scancodes.h. Note: The scancode value for
58	extended keys can be calculated by OR:ing with 0x80. Example: The
59	Delete key have the scancode sequence 0xe0, 0x52. You can get the
60	scancode value to put into the map file by running:
61
62	python -c "print hex(0x80 \| 0x52)"
63
64	If flags are "altgr", "shift", "numlock", the scancode sent for this
65	keysym will be prefix with AltGr, Shift or Numlock.
66
67	If flags include "addupper", an translation for this keysyms uppercase
68	name will as well, in addition to the non-uppercase name. Example:
69
70	x 2d addupper
71
72	...will add an translation for "X" automatically, just like if you
73	would specify:
74
75	X 2d shift
76
77	If flags include "localstate", the modifier to send will be determined
78	by the local modifier state.
79
80	If flags is "inhibit", nothing will be sent to the server.
81
82
83	4) enable_compose
84
85	If any line starts with the keyword "enable_compose", rdesktop will
86	enable local Compose/Multi_key handling. Enabling this will often make
87	it impossible to compose characters with dead keys (on the remote
88	side). This is because when local compose support is enabled, dead
89	keys will not be sent to the remote side.
90
91
92	Suggested X11 keysym mapping on PCs
93	===================================
94	Unfortunately, there is no standard for which keysyms a given key
95	should generate. If you have a PC-keyboard with Windows keys, I suggest this mapping:
96
97	Keyboard keys:
98	CtrlLeft WinLeft AltLeft Space AltGr WinRight Menu CtrlRight
99
100	...should generate keysyms:
101	Control_L Hyper_L Alt_L space Mode_switch Hyper_R Menu Control_R
102
103	Additionally:
104	Shift-Alt should produce Meta_L
105	Shift-AltGr should produce Multi_Key.
106
107	Use a modifier-map like this:
108
109	shift Shift_L (0x32), Shift_R (0x3e)
110	lock Caps_Lock (0x25)
111	control Control_L (0x42), Control_R (0x6d)
112	mod1 Alt_L (0x40)
113	mod2 Num_Lock (0x4d)
114	mod3 Mode_switch (0x71)
115	mod4 Hyper_L (0x73), Hyper_R (0x74)
116	mod5 Scroll_Lock (0x4e)