1. Purpose
-----------------------------------------------------------------------

XKBSwitch is a simple piece of software to overcome the annoying
limitation of XKB, which allows only four keyboard groups to be used
at a time. It is possible to get over the limitation by using
self-made composite keyboard layouts or special input methods, but
standard national layouts are better. XKBSwitch consists of the
daemon, which listens on D-Bus and performs layout reloads (if
necessary) and group locks. It tries to minimize the reloads by
tracking layouts usage. Layout switch requests are performed through
the trivial D-Bus interface (only one method), exported by the daemon,
by very simple client program. The client program is implemented in C
to minimize start-up time and uses only low-level D-Bus facilities.

2. Build and Installation
-----------------------------------------------------------------------

Dependencies are:
 * Python >=2.5;
 * dbus >=1.2;
 * dbus-python >=0.83;
 * libxklavier >=3.9.

Build dependencies are:
 * C compiler;
 * SCons.

Just use SCons to build:

$ scons

Installation is optional. System wide installation could be done like
this:

$ PREFIX=/usr/local/ scons install-ext install-bin

Default value for installation prefix is /usr/local. To install into
certain user's directory just copy these files:

 * _xkbswitch.so
 * xkbswitch-dbus-client
 * xkbswitch-dbus-daemon
 * xkbswitch.py

For example:

$ cp _xkbswitch.so xkbswitch-dbus-client xkbswitch-dbus-daemon \
 xkbswitch.py /home/nathalie/.local/bin

3. Usage
-----------------------------------------------------------------------

XKBSwitch daemon has to be started on running X session:

$ xkbswitch-dbus-daemon &

After this the XKBSwitch client program may be used to switch keyboard
layouts:

$ xkbswitch-dbus-client 'gr(bare)'
$ xkbswitch-dbus-client epo
$ xkbswitch-dbus-client 'ru(typewriter)'
$ xkbswitch-dbus-client es
$ xkbswitch-dbus-client no_such_layout
Couldn't activate layout
$ xkbswitch-dbus-client ru
$ xkbswitch-dbus-client us

It is really convenient to define some hot-keys. For example:

<Alt+Shift+e>   execute "xkbswitch-dbus-client epo"
<Alt+Shift+g>   execute "xkbswitch-dbus-client 'gr(bare)'"
<Alt+Shift+i>   execute "xkbswitch-dbus-client is"
<Alt+Shift+r>   execute "xkbswitch-dbus-client 'ru(typewriter)'"
<Alt+Shift+s>   execute "xkbswitch-dbus-client sr"

4. Bugs and Problems
-----------------------------------------------------------------------

 * Nobody cares about this software 'cause nobody really needs more
   than four XKB groups.

5. TODO
-----------------------------------------------------------------------

 * Dump extension module and use ctypes?
 * Dump extension module and use python-xklavier?

6. Contacts
-----------------------------------------------------------------------

Questions, corrections, suggestions, patches, blames, thanks or
whatever else mail to arn@users.berlios.de.