xkeysw - a keyboard layout switch for X Window System.

xkeysw [-version] [-help] [-display displayname] [-config configfile]

xkeysw is an utility which assigns distinct keyboard layouts to individual windows. It keeps track of all X windows on the display and their associated layouts, and changes the global keyboard mapping whenever a window with a modified layout gets the input focus.

The set of layouts is defined in the configuration file, each layout having an independent set of hot keys for switching to other layouts. The current layout assigned to a window is indicated in the window title.

-help, -h

Print the usage string.

-version, -v

Show the version number.

-display <display name>, -d <display name>

Specify the X server to contact. By default, xkeysw uses the environment variable DISPLAY.

-config <config file>, -c <config file>

Specify the configuration file. The default configuration file .xkeyswrc is searched in the same locations as xmmfiles (see below).

Configuration file contains a number of records each specifying parameters of a particular layout. Parameter keywords and values are separated by any symbol from the following set: " \t\n;:=,<>". Each record starts with a keyword layout followed by the name of the layout and ends with the beginning of another record or with the end of the configuration file. Parameters specified before the first record are assigned to the default layout, i.e., layout present at the xkeysw start time and assigned to all windows by default. Only hotkey parameter (see below) can be specified for the default layout.

There are three parameters defined for a record:

xmmfile <file name>

This parameter specifies the keyboard layout itself. Namely, it defines a name of the file containing xmodmap commands for keyboard re-mapping. A number of such files is installed during xkeysw installation. If the file name is not a full path name, the file is searched in the following order: first in the current directory, then in the directory specified with XKEYSW_DATAPATH environment variable, then in the user's home directory, and finally in the directory /usr/share/xkeysw. Parameter xmmfile can be defined at most once per record. If it is omitted, the layout present during xkeysw start is used for this keyboard layout.

prefix <prefix string>

This is a string which is added to the beginning of the window's title. If the prefix string contains spaces it should be braced with double quotes. Prefix string can not contain double quotes. If prefix parameter is absent, the name used after layout is used as a prefix string.

hotkey [<modifier list>+]<hot key>[(<new keysym>)] <layout name>

This parameter assigns a <hot key> to switch from this keyboard layout to a new one. <Hot key> is a KeySym of a key which triggers the change of keyboard layout. It can be preceded by a list of modifiers joined by '+' symbols. Note that modifiers are not KeySyms. The legal values for modifiers are: "Shift", "Lock", "Control", "Mod1", "Mod2", "Mod3", "Mod4", "Mod5", "Button1", "Button2", "Button3", "Button4", and "Button5" (see Xlib documentation for details). Optionally, <hot key> can be followed by a <new keysym> , a KeySym in parentheses (without any space between them). <new keysym> specifies what KeySym is assigned to this key in this keyboard layout. Specifically, this feature was designed to allow a switching key to be set to NoSymbol and thus to cause no side effects except switching the keyboard layout.

<layout name> specifies the keyboard layout to which the <hot key> switches current layout. This is either a layout record name, a name specified after keyword layout , or one of the two predefined names ( DEFAULT or GLOBAL ). DEFAULT refers to the default keyboard layout. GLOBAL indicates that this <hot key> switches current keyboard layout to the default one and the same <hot key> switches all other keyboard layouts including the default layout to the current keyboard layout.

Note: <hot key> should be unique for the keyboard layout and <hot key> assigned for GLOBAL layout should be unique for all keyboard layouts.

The following configuration file makes CapsLock key switch between default keyboard layout and KOI8 encoding with yawerty key layout.

	layout KOI8
	       prefix = "koi8: "
	       xmmfile = "yawerty-koi8.xmm"
	       hotkey = Caps_Lock(N) GLOBAL

The following configuration file employs left Shift key for switching from default keyboard layout to cp866 encoding with jcuken key layout and right Shift key for switching back to the default keyboard layout.

	hotkey = Shift_L cp866
	layout CP866
	       prefix = "cp866: "
	       xmmfile = "jcuken-cp866.xmm"
	       hotkey = Shift_R DEFAULT

The configuration file below assigns to the left Alt and left Shift key combination a function of switching between default keyboard layout and cp1251 encoding with jcuken key layout. This is the way keyboard mapping is switched in MS Windows. The assumption here is that Alt_L KeySym is bound to Mod1 modifier and Shift_L - to Shift modifier, which is usually the case. The assignment of two hotkey ensures that layout is switched regardless of what key (Alt or Shift) is pressed first.

	layout Win
	       prefix = "win: "
	       xmmfile = "jcuken-cp1251.xmm"
	       hotkey = Mod1+Shift_L GLOBAL
	       hotkey = Shift+Alt_L GLOBAL

DISPLAY

Specifies default host and display number.

XKEYSW_DATAPATH

Specifies the location of XMM files.

Xkeysw should be started after all other programs which change the keyboard mapping. Xkeysw saves the original mapping at the start time, and restores it just before the exit. Therefore, if any other program makes any changes to the keyboard mapping, those changes are lost when xkeysw terminates.

Xkeysw is not recommended to use with a remote display on a slow connection. There is a chance that a user may press a key after the focus has been changed, but before the Xserver has changed the keyboard mapping. If this happens, the first one or two keys entered after the focus change will produce wrong characters. There is nothing we can do about it, this is the way X protocol works. If you have any suggestions how to fix this, please let the authors know.

xmodmap(1)

xkeysw was written by Dima Barsky <dima@debian.org> and Igor Belyi <ibelyi@yahoo.com>.