xchainkeys(1)

XCHAINKEYS(1)

User manuals

XCHAINKEYS(1)

NAME

xchainkeys - chained keybindings for X11

SYNOPSIS

xchainkeys [options]

DESCRIPTION

xchainkeys is a standalone X11 program to create chained key bindings similar to those found in the ratpoison(1) window manager or the screen(1) terminal multiplexer.

OPTIONS

-f, --file <filename>: Load an alternative configuration file.
-k, --keys: Interactively show valid keyspecs for key combinations.
-d, --debug: Show debug messages on stdout.
-h, --help: Show usage information.
-v, --version: Show version information.

CONFIGURATION

The configuration file is located at

~/.config/xchainkeys/xchainkeys.conf

The XDG_CONFIG_HOME environment variable will be respected in compliance with the XDG Base Directory Specification (see REFERENCES below).

An example configuration file has been installed to

/usr/share/doc/xchainkeys/example.conf

Syntax

Each line may contain either a global setting or a keybinding definition. Empty lines and lines starting with a numbersign (#) are ignored.

Global Settings

Global settings are defined as key-value pairs, separated by whitespace.

timeout <n> (default: 3000): Wait n milliseconds for another key to be pressed before aborting an active keychain. A value of 0 will prevent automatic timeout. This value may be overridden by a timeout argument supplied to an :enter action, see Actions below.
feedback <on|off> (default: on): Show feedback in a small popup window.
delay <n> (default: 1000): Show current chain status after n milliseconds of inactivity in an active chain.
hold <n> (default: <delay>): Show error messages for n milliseconds after a chain has been aborted. If not set, the value of delay will be used.
position <x|offset|mouse|center> [<y>] (default: center): The position of the feedback window. An absolute position can be specified with the x and y arguments. A relative position can be specified using the offset portion of a standard X geometry string. The value mouse will cause the window to appear centered around the current mouse pointer position. The value center will center the window on the default screen.
font <fontstring> (default: fixed): The X11 font to use for text in the feedback window.
foreground <name|#rrggbb> (default: black): The foreground color of the text and the border of the feedback window.
background <name|#rrggbb> (default: white): The background color of the feedback window.

Keybindings

Keybindings are defined using the following syntax:

<keyspec> [<keyspec>...] :<action> ["<name>"] [<arguments>...]

A keyspec consists of one or more optional modifier names, followed by either a symbolic key name or a numeric keycode, each separated by a hyphen (-):

<mod>-[<mod>-...]<keyname|keycode>

Modifier names:

S, Shift = Shift key
C, Ctrl = Control key
A, M, Alt, Meta = Alt key
W, H, Super, Hyper, Windows = Super key

The generic modifier names Shift, Lock, Control, Mod1, Mod2, Mod3, Mod4 and Mod5 are recognized in addition to the above.

Key names correspond to the symbolic key names defined in /usr/include/X11/keysymdef.h (with their XK_ prefix removed).

Numeric keycodes may be supplied in decimal, hexadecimal or octal format, e.g. 16 (decimal) = 0x10 (hexadecimal) = 020 octal.

You can use xchainkeys -k to find the proper keyspec for key combinations.

Actions

:enter [timeout=<n>] [abort=<auto|manual>]

Enters a keychain. The keyboard will be grabbed exclusively until another keystroke has been processed, or until the chain times out after n milliseconds. If the key is bound within this chain, the associated action will be invoked, otherwise the user will be notified that an unbound key has been pressed.

If the abort argument is set to manual, the chain prefix will remain activated and further keystrokes will be processed until the chain is manually aborted with the :abort action. If set to auto (the default), the chain will abort immediately after the first keystroke has been processed.

If the timeout argument is omitted, the global timeout setting will apply. A value of 0 disables the timeout for this chain.

:abort

Abort the current keychain, releasing any previous grab on the keyboard. If not explicitly bound, :abort will be bound to prefix C-g by default.

:escape

Send the prefix key key of this chain to the currently focused window and abort the chain. If not explicitly bound, :escape will be bound to prefix prefix, e.g. for a chain prefixed with C-t the :escape action will be bound to C-t C-t by default.

This feature is implemented using XSendEvent(3). Note that applications may refuse to accept synthetic events generated with XSendEvent.

:exec <command>

Asynchronously execute command as a shell command.

:wait <command>

Ungrab the keyboard, execute command as a shell command, wait until the command has completed and grab the keyboard again if necessary. Use this action to run commands that also grab the keyboard (e.g. scrot --select).

:group ["<name>"] <command>

Associate a binding with a named group and asynchronously execute command as a shell command.

When a :group action is activated, timeout and automatic abort are disabled for the current chain prefix, and only bindings in the same group will be recognized for subsequent key presses. Any other keys will abort the chain and revert the above changes.

In addition, if the key used to abort the chain key is a toplevel chain prefix key, the corresponding chain will be entered immediately after this chain aborts. See EXAMPLES below for possible uses.

If no explicit name is given, the group name "default" is used.

:repeat <command>

Deprecated. Equivalent to :group "default".

:load [<filename>]

:reload [<filename>]

Clear the current bindings and (re)load the configuration file specified by filename. If no file is specified, the current configuration file is reloaded.

EXAMPLES

Bind the key sequence "Control-t Return" to run xterm:

C-t Return :exec xterm

This implies creating a default chain with the prefix key C-t, containing default bindings for the :abort and :escape actions, and is thus equivalent to

C-t :enter timeout=3000 abort=auto
C-t C-t :escape
C-t C-g :abort
C-t Return :exec xterm

Note that the number of keys in a keychain is not limited, e.g

C-t x c h a i n k e y s :exec xmessage "xchainkeys!"

can be invoked by pressing C-t and then typing "xchainkeys".

The following example creates a named :group of bindings to implement a dedicated frame resize mode for the musca(1) window manager:

C-w i :group "resize" musca -c 'resize up'
C-w k :group "resize" musca -c 'resize down'
C-w j :group "resize" musca -c 'resize left'
C-w l :group "resize" musca -c 'resize right'

C-w ... (other bindings for window management)

Invoke any of the above bindings (e.g. press C-w i) and then continue to press i, k, j or l to resize the current musca frame. Since timeout and automatic abort are disabled, you can continue resizing until you are satisfied with the result. Then simply press any other key to quit resize mode. If you want to invoke another window management command right away, you can use C-w to quit resize mode and immediately enter the C-w chain (or any other toplevel chain) again.

The benefit of using a named :group over a dedicated chain with timeout=0 and abort=manual is that you don't have to waste another prefix key. Instead you can temporarily redefine an existing chain to contain only a specific subset of keys, behaving in the desired manner.

KNOWN ISSUES

Some window managers assume that no other program has grabbed any global key combinations before them, and may fail with a fatal error when trying to grab a key that has already been grabbed as a prefix key by xchainkeys. This situation is likely to occur when xchainkeys is started before the window manager in ~/.xinitrc.

In general, binding the same key combinations in xchainkeys and other programs should be avoided.

BUGS

This software is currently in beta state. Please file bugs on the googlecode issue tracker.

http://code.google.com/p/xchainkeys/issues

Use the email address below for questions, feature requests and comments.

COPYRIGHT

LICENSE

xchainkeys is licensed under the GNU General Public License v3, see http://www.gnu.org/licenses/gpl.html.

REFERENCES

X11 key symbols: /usr/include/X11/keysymdef.h
XDG Base Directory Specification: http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html