Installation
============

GNU autotools are used for building and installing xchainkeys:

    $ ./configure --prefix=/usr
    $ make
    $ sudo make install

This README file and an example configuration file will be installed
to $PREFIX/share/doc/xchainkeys/.

The standard DESTDIR variable can be used for a staged install.

Description
===========

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

Invocation
==========

xchainkeys [options]
  
  -k, --keys    : Show valid keyspecs
  -d, --debug   : Enable debug messages
  -h, --help    : Print this help text
  -v, --version : Print version information

To autostart xchainkeys on X startup, add the following command to
your ~/.xinitrc:

   xchainkeys &

Alternatively use your WM/DE's autostart mechanism to start xchainkeys
as a background process.

Configuration
=============

Create the file ~/.config/xchainkeys/xchainkeys.conf or copy the
example config file $PREFIX/share/doc/xchainkeys/example.conf to the
above location.

Global Options
==============

The following global options are recognized:

timeout <msec> (default: 3000)
    
    A key chain will time out if no key is hit in the specified
    time. A value of 0 will disable timeout.
    	
delay <msec> (default: 1000)
    
    Delay before showing the popup window that displays the current
    chain prefix.
    
font <font> (default: fixed)

    The X11 font to use for the popup window.
 
foreground <color> (default: black)
background <color> (default: white)

    The foreground and background colors to use for the popup
    window. Colors can be specified using the default X11 color names
    or a hexadecimal color notation in the form #rrggbb.

Keybindings and keychains
=========================

Keybindings and keychains can be defined using the following syntax:

    <keyspec> [<keyspec>...] <action> [<arguments>...]

A <keyspec> consists of one or more optional modifiers, followed by a
symbolic key name, each separated by "-".

Note that only the first key of a keychain will be grabbed
individually by using XGrabKey(3) and will thus exist alongside any
other global key bindings from your WM/DE. Once a chain is entered,
the keyboard will be grabbed exclusively, temporarily disabling all
WM/DE bindings until the chain is left.

Modifier names
==============

The following modifier names are recognized:

    "S"         ->  Shift key
    "C"         ->  Control key
    "A" or "M"  ->  Alt key
    "W" or "H"  ->  Super key (usually the "windows" key)

The generic modifier names "shift", "lock", "control",
"mod1", "mod2", "mod3", "mod4" and "mod5" can also be used.

Key names
=========

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

Use xchainkeys -k to find the <keyspec> for a certain modifier/key
combination.

Actions
=======

The following actions can be bound to keys:

    :enter 
      
      Enter a keychain. The keyboard will be exclusively grabbed until
      another key is hit or the chain times out. If the key is bound
      within this chain, its action will be invoked, otherwise the
      user will be notified that an unbound key has been hit.

    :escape

      Send the key combination that was used to enter this chain to
      the currently focused application. This is implemented using
      XSendEvent(3).  Applications may refuse to accept synthetic
      events generated by XSendEvent(3).

    :abort

      Abort this keychain, releasing any previous grab on the keyboard.

    :exec <argument>

      Execute <argument> as a shell command using /bin/sh.

Examples
========

Here's an explicit example to create a keychain prefixed with Control-t:

    C-t :enter                   # C-t enters the keychain
    C-t C-t :escape              # C-t C-t sends C-t
    C-t C-g :abort               # C-t C-g aborts the chain
    C-t Return :exec xterm       # C-t Return executes xterm

Please note:

A key that appears at the beginning of a chained keybinding is
implictly bound to the :enter action if it hasn't been bound to :enter
before. Thus the first line in the example above is superfluous.

If the :escape action is not explicitly bound in a toplevel keychain,
it will be bound to the prefix key by default. This means that
pressing the prefix key twice will send it to the focused application
by default. The second line in the example above is thus also
superfluous.

If the :abort action is not explicitly bound in a toplevel keychain,
it will be bound to "C-g" by default. Thus the third line above is
superfluous again.

In conclusion, the above example is equivalent to

     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". 
