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. 


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
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
97	4) enable_compose
98
99	If any line starts with the keyword "enable_compose", rdesktop will
100	enable local Compose/Multi_key handling. Enabling this will often make
101	it impossible to compose characters with dead keys (on the remote
102	side). This is because when local compose support is enabled, dead
103	keys will not be sent to the remote side.
104
105
106	5) sequence lines
107	Syntax:
108	sequence <event-keysym-name> <keysym-name1> <keysym-name2> ...
109
110	Examples:
111	sequence eacute dead_acute e
112	sequence F12 f o o at e x a m p l e period c o m
113
114	Sequence lines allows you to specify that multiple scancodes should be
115	sent to the RDP server, in response to one X11 keyboard event. Note:
116	The sequence is sent at the X11 KeyPress event. Nothing is sent at
117	KeyRelease.
118
119
120	6) keyboard_type lines
121	Syntax:
122	keyboard_type <hex-number>
123
124	keyboard_type lines specifies the keyboard type. Default value is 0x4
125	(en-us 101/104 keys keyboard).
126
127
128	7) keyboard_subtype lines
129	Syntax:
130	keyboard_subtype <hex-number>
131
132	keyboard_subtype lines specifies the keyboard subtype. Default value
133	is 0x0 (en-us 101/104 keys keyboard).
134
135
136	8) keyboard_functionkeys lines
137	Syntax:
138	keyboard_functionkeys <hex-number>
139
140	keyboard_functionkeys specifies the number of keyboard function
141	keys. Default value is 0xc (12, for standard 101/104 keys keyboard).
142
143
144
145
146	Suggested X11 keysym mapping on PCs
147	===================================
148	Unfortunately, there is no standard for which keysyms a given key
149	should generate. If you have a PC-keyboard with Windows keys, I suggest this mapping:
150
151	Keyboard keys:
152	CtrlLeft WinLeft AltLeft Space AltGr WinRight Menu CtrlRight
153
154	...should generate keysyms:
155	Control_L Super_L Alt_L space Mode_switch Super_R Menu Control_R
156
157	Additionally:
158	Shift-Alt should produce Meta_L
159	Shift-AltGr should produce Multi_Key.
160
161	Use a modifier-map like this:
162
163	shift Shift_L (0x32), Shift_R (0x3e)
164	lock Caps_Lock (0x25)
165	control Control_L (0x42), Control_R (0x6d)
166	mod1 Alt_L (0x40)
167	mod2 Num_Lock (0x4d)
168	mod3 Mode_switch (0x71)
169	mod4 Super_L (0x73), Super_R (0x74)
170	mod5 Scroll_Lock (0x4e)
171
172
173	Updating / writing keymap files
174	===============================
175	When writing new or updating keymap files, please use comments and
176	blanks, to increase readability. The "sv" keymap is a good template.
177
178	When you need to add a translation to a keymap file, do:
179
180	1. Get the "key number" for this key, by looking at keynums.png.
181
182	2. Take a look at scancodes.h, and look for
183	SCANCODE_KEY_<my-key-number>. The scancode value is at the end of
184	the line. If the line contains (SCANCODE_EXTENDED \| 0xsomething),
185	then you should OR 0x80 to this value. For example, you can do:
186
187	python -c "print hex(0x80 \| 0xsomething)"
188
189	3. Put the scancode (from step 2) and keysym name (found in the
190	error message) into the keymap file.
191
192
193	Special keys
194	============
195
196	* The combination Ctrl-Alt-Enter toggles between fullscreen and
197	non-fullscreen mode.
198
199	* Meta, Hyper and Super are treated as windows keys. RDP4 does not
200	support the windows keys though, so if you are running RDP4, these
201	keys will translate to Ctrl-Esc.
202
203
204	Links
205	=====
206	http://www.win.tue.nl/~aeb/linux/kbd/scancodes.html