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>


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

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)


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	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			1) include-lines
45			Syntax:
46			include <another-map-file>
47
48
49			2) map-lines
50			Syntax:
51			map <hex-number>
52
53			Map-lines specifies how the remote RDP server should interpret the
54			sent scancodes.
55
56
57			3) Translation-lines
58			Syntax:
59			<keysym-name> <scancode> [flags..]
60
61			The scancode can be found in scancodes.h. Note: The scancode value for
62			extended keys can be calculated by OR:ing with 0x80. Example: The
63			Delete key have the scancode sequence 0xe0, 0x52. You can get the
64			scancode value to put into the map file by running:
65
66			python -c "print hex(0x80 \| 0x52)"
67
68	astrand	543	If flags are "altgr", "shift", the scancode sent for this
69			keysym will be prefix with AltGr, or Shift.
70	astrand	104
71			If flags include "addupper", an translation for this keysyms uppercase
72			name will as well, in addition to the non-uppercase name. Example:
73
74			x 2d addupper
75
76			...will add an translation for "X" automatically, just like if you
77			would specify:
78
79			X 2d shift
80
81			If flags include "localstate", the modifier to send will be determined
82			by the local modifier state.
83
84	astrand	116	If flags is "inhibit", nothing will be sent to the server.
85	astrand	104
86	astrand	116
87	astrand	104	4) enable_compose
88
89			If any line starts with the keyword "enable_compose", rdesktop will
90			enable local Compose/Multi_key handling. Enabling this will often make
91			it impossible to compose characters with dead keys (on the remote
92			side). This is because when local compose support is enabled, dead
93			keys will not be sent to the remote side.
94
95
96			Suggested X11 keysym mapping on PCs
97			===================================
98			Unfortunately, there is no standard for which keysyms a given key
99			should generate. If you have a PC-keyboard with Windows keys, I suggest this mapping:
100
101			Keyboard keys:
102			CtrlLeft WinLeft AltLeft Space AltGr WinRight Menu CtrlRight
103
104			...should generate keysyms:
105			Control_L Hyper_L Alt_L space Mode_switch Hyper_R Menu Control_R
106
107			Additionally:
108			Shift-Alt should produce Meta_L
109			Shift-AltGr should produce Multi_Key.
110
111			Use a modifier-map like this:
112
113			shift Shift_L (0x32), Shift_R (0x3e)
114			lock Caps_Lock (0x25)
115			control Control_L (0x42), Control_R (0x6d)
116			mod1 Alt_L (0x40)
117			mod2 Num_Lock (0x4d)
118			mod3 Mode_switch (0x71)
119			mod4 Hyper_L (0x73), Hyper_R (0x74)
120			mod5 Scroll_Lock (0x4e)
121	astrand	272
122
123			Updating / writing keymap files
124			===============================
125			When writing new or updating keymap files, please use comments and
126			blanks, to increase readability. The "sv" keymap is a good template.
127
128			When you need to add a translation to a keymap file, do:
129
130			1. Get the "key number" for this key, by looking at keynums.png.
131
132			2. Take a look at scancodes.h, and look for
133			SCANCODE_KEY_<my-key-number>. The scancode value is at the end of
134			the line. If the line contains (SCANCODE_EXTENDED \| 0xsomething),
135			then you should OR 0x80 to this value. For example, you can do:
136
137			python -c "print hex(0x80 \| 0xsomething)"
138
139			3. Put the scancode (from step 2) and keysym name (found in the
140			error message) into the keymap file.
141	astrand	434
142
143	astrand	454	Special keys
144			============
145
146			* The combination Ctrl-Alt-Enter toggles between fullscreen and
147			non-fullscreen mode.
148
149	astrand	455	* Meta, Hyper and Super are treated as windows keys. RDP4 does not
150	astrand	454	support the windows keys though, so if you are running RDP4, these
151			keys will translate to Ctrl-Esc.
152
153
154	astrand	434	Links
155			=====
156			http://www.win.tue.nl/~aeb/linux/kbd/scancodes.html