XCHAINKEYS(1)

📦
version 0.11 · 2 versions
, in nixos 26.05

🎀 XCHAINKEYS(1) 🎀

okay bestie, so this is the manual page for xchainkeys — yes it's section 1, we love that for it 💅 — and honestly? it's giving main character energy for your keyboard. let's get into it.

✨ NAME ✨

xchainkeys — chained keybindings for X11. that's it. that's the vibe. 🦋

✨ SYNOPSIS ✨

xchainkeys [options]

✨ DESCRIPTION ✨

so xchainkeys is a standalone X11 program that lets you create chained key bindings — like the ones you already simp for in the ratpoison(1) window manager or the screen(1) terminal multiplexer. no cap, it just does that. 🔥

✨ OPTIONS ✨

  • -f, --file <filename> — load an alternative configuration file. (yes, you can have more than one. we stan options 💖)
  • -k, --keys — interactively show valid keyspecs for key combinations. basically a little keyspec oracle, use it, fr fr.
  • -d, --debug — show debug messages on stdout. for when you're in your detective era 🕵️
  • -h, --help — show usage information. classic. iconic. never misses.
  • -v, --version — show version information. 💫

🌸 CONFIGURATION 🌸

your config file lives at

~/.config/xchainkeys/xchainkeys.conf

and the XDG_CONFIG_HOME environment variable will be respected, in compliance with the XDG Base Directory Specification (see REFERENCES below, bestie, it's all linked up 🫶).

an example configuration file has been installed to

/nix/store/bx08n3ddbz4b40z7ymwhrvdxymmqaal7-xchainkeys-0.11/share/doc/xchainkeys/example.conf

yes that whole path. copy it exactly. it's not a typo, it's just Nix being Nix 😭

Syntax

every line may contain either a global setting or a keybinding definition. empty lines and lines starting with a numbersign (#) are ignored. so go ahead and comment your heart out, queen 💅

Global Settings

global settings are defined as key-value pairs, separated by whitespace. simple, clean, slay.

  • 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, iykyk ⏳
  • feedback <on|off> (default: on) — show feedback in a small popup window. a literal little popup, adorable.
  • 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. (yes, it inherits. nepotism but make it config 💀)
  • 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. go ahead, place it anywhere, be free 🌈
  • font <fontstring> (default: fixed) — the X11 font to use for text in the feedback window. make it cute if you want idc.
  • 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. aesthetic is customizable, thank god 🎨

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, bestie, here's the cheat sheet 📋:

  • 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. so many names, all valid, we love a flexible icon ✨

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. math girlies rise 🧮

you can use xchainkeys -k to find the proper keyspec for key combinations. genuinely such a lifesaver, ngl.

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. (rude of them but okay 🙈)

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. the panic button, but make it chic 💅
  • :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. yeah. that's a real caveat, don't come for me, it's in the source 🫠

  • :exec [abort=auto] <command> — asynchronously execute command as a shell command. if abort=auto is given, this binding will always abort the current chain after executing the command, even if the chain was entered with abort=manual. (overachiever behavior, honestly 😌)
  • :wait <command> — ungrabs the keyboard, executes command as a shell command, waits until the command has completed and grabs the keyboard again if necessary. use this action to run commands that also grab the keyboard (e.g. scrot --select). sharing is caring 🫶
  • :group ["<name>"] [abort=auto] <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.

if abort=auto is given for particular binding within a group, this binding will always abort the current chain after executing the command, effectively overriding the implied abort=manual option.

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". it's giving legacy code, we still love her though 🕯️
  • :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. refresh, restart, rebrand ✨

🔥 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". typing out a whole word as a shortcut, we love an extra queen 👑

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. it's giving seamless transitions, we're obsessed 🦋

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. efficiency slay 💅

💀 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. the audacity, honestly 😭

in general, binding the same key combinations in xchainkeys and other programs should be avoided. just don't do it bestie, it's not worth the drama.

💀 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. we're listening 🫶

Copyright (C) 2010-2012 Henning Bekel <h.bekel@googlemail.com>

📜 LICENSE 📜

xchainkeys is licensed under the GNU General Public License v3, see http://www.gnu.org/licenses/gpl.html. legal queen behavior, we respect it ⚖️

🔗 REFERENCES 🔗

👀 SEE ALSO 👀

Xorg(1) screen(1) ratpoison(1) musca(1)

okay that's the whole thing bestie, go forth and chain your keys 🌈✨

lowkey this page is from the Linux manual set, dated 2010-09-16 — vintage but still iconic, like a good pair of jeans. mwah 💋 🦋 🎀
📦 where this page comes from