--- name: "xkeysw" section: "1" platform: "linux" package: "xkeysw" version: "1.1-1.2" release: "Debian 3.1 (Sarge)" platforms: ["linux"] url: "https://new.carta.tech/xkeysw" --- # xkeysw(1) a keyboard layout switch for X Window System. ## NAME xkeysw - a keyboard layout switch for X Window System. ## SYNOPSIS **xkeysw** *\[-version\] \[-help\] \[-display displayname\] \[-config configfile\]* ## DESCRIPTION **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. ## OPTIONS - **-help, -h** Print the usage string. - **-version, -v** Show the version number. - **-display \, -d \** Specify the X server to contact. By default, **xkeysw** uses the environment variable **DISPLAY.** - **-config \, -c \** Specify the configuration file. The default configuration file *.xkeyswrc* is searched in the same locations as xmmfiles (see below). ## CONFIGURATION FILE 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 \** 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 \** 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 \[\+\]\\[(\)\] \** This parameter assigns a *\* to switch from this keyboard layout to a new one. *\* 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, *\* can be followed by a *\* , a KeySym in parentheses (without any space between them). *\* 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. *\* specifies the keyboard layout to which the *\* 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 *\* switches current keyboard layout to the default one and the same *\* switches all other keyboard layouts including the default layout to the current keyboard layout. Note: *\* should be unique for the keyboard layout and *\* assigned for **GLOBAL** layout should be unique for all keyboard layouts. ## EXAMPLES 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(NoSymbol) 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 ``` ## ENVIRONMENT - DISPLAY Specifies default host and display number. - XKEYSW\_DATAPATH Specifies the location of XMM files. ## BUGS *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. ## SEE ALSO [xmodmap(1)](/xmodmap/1.md) ## AUTHORS **xkeysw** was written by Dima Barsky \ and Igor Belyi \.