aboutsummaryrefslogtreecommitdiff
path: root/doc/nxagent/README.keystrokes
blob: 96bc158d2cb42de1e0c9aaeea58a17792818fc61 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
Configurable keybindings in nxagent

Keybindings in the redistributed x2go version of nxagent can now be configured
by the user. This is done via a configuration file.

File location
-------------

nxagent parses the first available configuration file and ignores all others.

If nxagent is called without branding, it searches:
- in the location given by the '-keystrokefile' command line parameter
- in the location given by the NXAGENT_KEYSTROKEFILE environment variable
- in ~/.nx/config/keystrokes.cfg
- in /etc/nxagent/keystrokes.cfg

If nxagent is called with X2Go branding (i.e., as x2goagent), it searches:
- in the location given by the '-keystrokefile' command line parameter
- in the location given by the X2GO_KEYSTROKEFILE environment variable
- in ~/.x2go/config/keystrokes.cfg
- in /etc/x2go/keystrokes.cfg

If none of these files are accessible, the default configuration is used which
is the same as the old, traditional nxagent keybindings.

File format
-----------

The configuration file is XML with the following format:

<!DOCTYPE NXKeystroke>
<keystrokes>
<keystroke action="fullscreen" AltMeta="1" Control="1" key="b" />
<keystroke action="minimize" AltMeta="1" Control="1" key="space" />
<keystroke action="minimize" key="Escape" Shift="1" />
<keystroke action="close_session" key="F7" />
<keystroke action="fullscreen" key="F7" Mod1="1" />
<keystroke action="fullscreen" key="F6" Mod1="1" />
<keystroke action="force_synchronization" key="f" />
<keystroke action="fullscreen" key="space" Mod1="0" Mod2="0" Control="0" Shift="0" AltMeta="0" />
</keystrokes>

Each 'action' defines an action to be executed when receiving that keystroke. A
list of possible actions is given below. Some of those actions are only
available with debug builds of nxagent.

Keys are given as a combination of 'key' and (optionally) a number of
modifiers. The key attribute is evaluated into a X11 key via the usual
XStringToKeysym function. A list of possible keys can be found in
/usr/include/X11/keysymdef.h, the names are specified without the leading
'XK_'. Evaluation is case-sensitive, so, 'space' and 'Escape' will work while
'Space' and 'escape' won't.

Modifiers are given as boolean attributes, possible modifiers are Mod1, Mod2,
Mod3, Mod4, Mod5, Control, Shift, Lock. Sensible combinations strongly depend on your
keyboard configuration, but usually you will need Mod1 and Control. Boolean in
this context means '0', 'false' and an unspecified attribute are false, anything
else is considered true.

Everything in this file is case-sensitive. Unknown lines are ignored.
Keybindings are evaluated from top to bottom, so if a keybinding matches, other
keybindings further down will be ignored. The contents of the file replaces the
default keybindings, and only one file is read, no merging between different
configuration files is done. This also means that an empty or invalid configuration
file deactivates all keybindings.

If an attribute occurs more than once in a line the last one wins.

List of possible 'action' attributes:
-------------------------------------

close_session
  This terminates the session.
fullscreen
  Switches the client window into or out of fullscreen mode, using only the current head.
switch_all_screens
  Switches the client window into or out of fullscreen mode, using all available heads.
minimize
  This will minimize the client window (even for fullscreen sessions.)
left
up
right
down
resize
  This action switches between the auto-resize and viewport mode
  (static size). The default is auto-resize. In viewport mode one can
  use the 'viewport_move_up', 'viewport_move_down',
  'viewport_move_left' and 'viewport_move_right' actions to move
  within the image.
defer
  activate/deactivate deferred screen updates.
ignore
  Makes it possible to add 'ignore', as in nothing happens when certain keys are pressed.
viewport_move_left
  Moves the image viewport to the left.
viewport_move_up
  Moves the image viewport up.
viewport_move_right
  Moves the image viewport to the right.
viewport_move_down
  Moves the image viewport down.
reread_keystrokes
  forces nxagent to re-read the keystroke
  configuration. Useful to add/changes keystrokes for a running
  session.

Only in builds with certain debugging options enabled, ignored otherwise:
force_synchronization
  Forces the drawing of elements to be synchronized which can fix some visual bugs.
debug_tree
regions_on_screen
test_input
deactivate_input_devices_grab