-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathxxkb.man
260 lines (260 loc) · 10.6 KB
/
xxkb.man
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
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
.\" Copyright (c) 1999-2003 Ivan Pascal
.\" Copyright (c) 2002-2007 Alexander Pohoyda
.\"
.TH XXKB 1 "29 Jun 2007" "XXKB"
.SH NAME
xxkb \- Keyboard Layout Indicator and Switcher for the X Window System
.SH SYNOPSIS
.B xxkb
.SH DESCRIPTION
\fBxxkb\fR is a keyboard layout indicator and switcher for the X
Window System. It displays a small window with an image or a text
label identifing the active keyboard layout (an XKB group) and allows
you to switch the layout with a mouse click. The program also
remembers the keyboard layout for each managed window and changes the
keyboard state accordingly when the window gets a focus. \fBxxkb\fR
can be configured to show either one global indicator for all windows
and/or many small indicator on each window separately. If the
keyboard map has more than two layouts, \fBxxkb\fR can simplify
switching between them using a \fItwo_state\fR mode: the user is given
a possibility to define a primary and a secondary layouts and then
switch the keyboard state between them only. \fBxxkb\fR behavior can
be customized for specific windows identified by some window
properties. The \fBxxkb\fR works (is supposed to, anyway) with most
window managers.
.SH USAGE
As an indicator, \fBxxkb\fR consists either of a single window (called
\fImainwindow\fR) and/or, optionally, many smaller windows (called
\fIbuttons\fR, one for every managed window) with pre-defined images
or text labels of keyboard layouts. Both \fImainwindow\fR and
\fIbuttons\fR can be clicked any time with a mouse to change the
keyboard layout.
.TP 4
.B MouseButton1
The primary mouse button is used to switch the keyboard layout. If
the \fBtwo_state\fR mode is active, the button click alternates
between primary and secondary layouts (XKB groups). Otherwise, it
cycles between all system-defined layouts.
.TP 4
.B MouseButton2
The second (middle) button action depends on where you click. The
click on the \fImainwindow\fR terminates the \fBxxkb\fR. The click on
a \fIbutton\fR simply removes it from the title bar and excludes that
application from a set of managed applications for future \fBxxkb\fR
sessions. If the \fBControl\fR key was pressed during the button
click, the application will be added to the \fBwm_class_class\fR list.
If the \fBShift\fR key was pressed -- \fBwm_name\fR list and if both
\fBControl\fR and \fBShift\fR keys were pressed during the button
click, the application will be added to the \fBwm_class_name\fR list.
In all cases the updated lists will be immediately saved into a user
configuration file \fI~/.xxkbrc\fR. See \fBApplications lists
options\fR for more details.
.TP 4
.B MouseButton3
When the \fBtwo_state\fR mode is active, this button allows you to
choose an alternative layout. It selects all possible layouts in
cycle and the layout you stop on becomes the alternative one. When
the \fBtwo_state\fR mode is disabled, this button works just like the
primary button.
.SH OPTIONS
The \fBxxkb\fR reads all configuration options from two files:
\fIapp\-defaults/XXkb\fR and \fI~/.xxkbrc\fR.
.SH Common options
.TP 4
.B XXkb.xpm.path
deprecated, please use the `XXkb.image.path' option instead.
.B XXkb.image.path (was XXkb.xpm.path before)
a directory where images are expected to be found.
.SH MainWindow-specific options
.TP 4
.B XXkb.mainwindow.enable
switches on and off the \fImainwindow\fR (yes by default). If a
\fIbuttons\fR are enabled, some users prefer to hide the main window.
.TP 4
.B XXkb.mainwindow.appicon
deprecated, please use `XXkb.mainwindow.type: wmaker' instead.
.TP 4
.B XXkb.mainwindow.type
allow to dock the mainwindow into a system tray. Supported values
are: wmaker, tray, top, normal.
.TP 4
.B XXkb.mainwindow.geometry
the geometry of the mainwindow in WIDTHxHEIGHT[{+-}XOFF{+-}YOFF]
format. Please read the \fBGEOMETRY SPECIFICATIONS\fR section of X(7)
for more details.
.B XXkb.mainwindow.gravity
this option is obsolete, please specify the gravity in the
`XXkb.mainwindow.geometry' option instead.
.TP 4
.B XXkb.mainwindow.border.color
a color used to draw a window border.
.TP 4
.B XXkb.mainwindow.border.width
border width in pixels.
.TP 4
.B XXkb.mainwindow.xpm.N
deprecated, please use `XXkb.mainwindow.image.N' options instead.
.B XXkb.mainwindow.image.N
pixmap filenames for each indicated group N [1 to 4]. If your symbols
map has less than four groups, the unused group icons can be omitted.
If the filename begins with '/', it is taken as an absolute path.
Otherwise it is relative to the directory specified in the
`XXkb.image.path' option.
.TP 4
.B XXkb.mainwindow.label.enable
enable text labels to be displayed instead of images. XKB Group
descriptions will be used if not overwritten by
`XXkb.mainwindow.label.text.N' options.
.TP 4
.B XXkb.mainwindow.label.text.N
label for the specified group N.
.TP 4
.B XXkb.mainwindow.label.background
label background color.
.TP 4
.B XXkb.mainwindow.label.foreground
label text color.
.TP 4
.B XXkb.mainwindow.label.font
label text font.
.SH Button-specific options
.TP 4
.B XXkb.button.enable
if turned on (default), the \fBxxkb\fR adds an additional button to a
title bar of each managed window which is the indicator and the layout
switcher for that particular window. These buttons are not usual
window manager buttons but windows (with a pixmap) owned by the
\fBxxkb\fR itself. This means that in some cases a user may need to
tune the button size and the position for the button look like a
window manager decoration element.
.TP 4
.B XXkb.button.geometry
.TP 4
.B XXkb.button.gravity
.TP 4
.B XXkb.button.image.N
.TP 4
.B XXkb.button.label.enable
.TP 4
.B XXkb.button.label.text.N
.TP 4
.B XXkb.button.label.background
.TP 4
.B XXkb.button.label.foreground
.TP 4
.B XXkb.button.label.font
.TP 4
.B XXkb.button.border.color
.TP 4
.B XXkb.button.border.width
see description of their \fBmain window\fR counterparts.
.SH Operation mode options
Since the \fBxxkb\fR can keep the keyboard state for each application
and restore the state when the focus is changed there is a group of
options which controls how the \fBxxkb\fR finds the application
windows.
.TP 4
.B XXkb.controls.add_when_start
If this mode is turned on (default) the \fBxxkb\fR at startup time
tries to find all application to be managed.
.TP 4
.B XXkb.controls.add_when_create
In this mode the \fBxxkb\fR gets a new application window at time when the
application creates it. It is the base mode but I can't guaranty it works
with all window managers.
.TP 4
.B XXkb.controls.add_when_change
In this mode the \fBxxkb\fR doesn't catch the windows at their creation
but adds windows to the managed windows list if the keyboard state changes
when the window is focused. It's an additional mode (not recommended) and
may be useful only if the \fBadd_when_create\fR mode for some reason
doesn't work.
.TP 4
.B XXkb.controls.focusout
It makes the \fBxxkb\fR reset the keyboard group when the focus leaves
the window. The mode makes sense with the \fBadd_when_change\fR mode only.
.TP 4
.B XXkb.controls.button_delete
This mode (enabled by default) allows a user to remove the per window
button using a middle mouse button click. Although the \fBxxkb\fR
tries to ignore windows where the keyboard layout switching doesn't
make sense, such cases may still occur.
.TP 4
.B XXkb.controls.button_delete_and_forget
This mode in addition to the previous one makes \fBxxkb\fR to forget
the window which button is deleted. It means the \fBxxkb\fR will not
remember the keyboard state changes in this window and restore this
state when the window will be focused.
.TP 4
.B XXkb.controls.mainwindow_delete
Terminate the application.
.TP 4
.B XXkb.controls.two_state
Switching between two chosen keyboard layouts only. If the XKB
symbols map has more than two groups and not all of them are needed
for each application the \fBxxkb\fR allows to skip unneeded layouts at
the layout switching. You can select one group as a base group and
another one as an alternative group and then switch between these two
groups only. The base group is common for all applications (usually
it contains ASCII) but the alternative group can be chosen for each
application window separately. In this mode, the right mouse button
selects the alternative group and the left mouse button as well as the
key which configured as the layout switcher change the current state
between two selected layouts only. This mode uses two additional
config options:
.TP 4
.B XXkb.group.base
the primary (base) group (integer 1-4).
.TP 4
.B XXkb.group.alt
the default alternative group (integer 1-4).
.SH Bell options
.TP 4
.B XXkb.bell.enable
enables the keyboard bell when the layout changes.
.TP 4
.B XXkb.bell.percent
an argument value for the XBell call.
.SH Key Mask options
.TP 4
.B XXkb.keymask.cycle
set the keyboard key modifer for cycle layout changes. Usefull when there is more
then two layouts. Can be "none", "shift", "lock", "control", "ctrl", "alt", "mod1", "mod2", "mod3", "mod4", "mod5".
.SH Applications lists options
The \fBxxkb\fR allows to specify lists of applications that require a
special handling. Applications can be specified using their
\fBWM_CLASS\fR or \fBWM_NAME\fR properties. A common form of such an
option is:
.br
\fBXXkb.app_list.\fIproperty\fB.\fIaction\fB: \fIapp1 app2... appN\fR
.PP
The \fIaction\fR here can be one of \fBignore\fR, \fBstart_alt\fR or
\fBalt_groupN\fR. The \fBignore\fR action means that applications
from this list must be ignored by the \fBxxkb\fR. The \fBstart_alt\fR
action means that the \fBxxkb\fR must set the keyboard state to the
alternative layout when the application starts. The \fBalt_groupN\fR
(where N=1..4) actions define alternative layouts for applications if
these layouts should be different from the common alternative layout
specified by the \fBXXkb.group.alt\fR option. The \fIproperty\fR can
be either \fBwm_class_class\fR, \fBwm_class_name\fR or \fBwm_name\fR.
The \fBxxkb\fR can identify applications using their \fBWM_CLASS\fR
and \fBWM_NAME\fR window properties. The \fBWM_CLASS\fR property
actually consists of two parts - a \fBres_class\fR and a
\fBres_name\fR. Thus, the \fIproperty\fR field specifies what
property or part of property should be considered for the application
identification. By default all these lists are empty. A non- empty
list is a sequence of words separated by space/tab characters. The
\fBxxkb\fR accepts an asterisk as a part of a word. Long lists can be
continued on the next line using a backslash as the last character of
the line, e.g:
.br
XXkb.app_list.wm_name.ignore: Fvwm* *clock \\
.br
Xman
.TP 4
.B XXkb.ignore.reverse
This option reverses a meaning of the `XXkb.*.ignore' lists. If this
option is enabled, ignore lists define applications which should be
managed by \fBxxkb\fR.
.SH AUTHOR
Ivan Pascal, Alexander Pohoyda