Make your own free website on
 A docked / swallowed XKB groups indicator and switch

Version 1.2.2 June 2004



Introduction Customising. Controlling wmxkb at run time. Miscellaneous License


Where and Who.


XKB, key groups, and wmxkb

X Keyboard Extension (XKB)  has become an integral part of XFree86 and provides an easy and elegant way to customise your keyboard. This is especially important for the users of  a non-Latin alphabet. Since nowdays you can hardly imagine a computer capable of working without being able to enter Latin characters,  you typically have two or more alphabets, or , using XKB jargon, key groups.

XKB codes the groups according to the country or locale. A "classic" example is the difference between US and UK keyboard,  whith  # for US and  £ for UK,  while fr (French) and and fr_CH (Swiss French) are significantly different as AZERTY vs QWERTY.  Starting with XFree 86 v 4.3.0 you can mix up to four dirrerent groups in a XKB layout,  and this is not an "overkill" especially for multinational countries.

wmxkb provides a convenient way to  operate a multigroup layout: it indicates current group and allows switching groups with a single mouse click.  You can also use wmxkb to assign aditional (e.g. mutimedia) keys for switching between groups, or setting a particular group,  run a script whenever a particular group is activated (for changing locale,  font lookup directories etc).

The application is designed to be as much self-aware as possible. It should be able to figure out which key maps are being used, in particular you can get settings  unaffected by the XKB layout in use. Currently this feature is experimental (see Flexible groups section).

Typically wmxkb is used as a dockable/swallowed applet with Window Maker or any window manager that supports docking or swallowing, including  afterstep, blackbox and clones (incl. fluxbox), gnome v1, kde v1,  fvwm and clones.  If your window manager does not support swallowing,  you can run the applications as a "normal" window.

    V 1.0.0 and 1.1.0   October 2003
    v 1 2.0     December 2003             

Installation from a tarball

Your XFree86 configuration is assumed to support  X Keyboard extension  and multiple key groups. All the libraries used by the application (now libXpm as well!) are included in standard XFree86 distribution, and if a particular library is not found, just reinstall the necessary XFree86 related package (e.g. Xbin.tgz, XProg.tgz,  or RPM:    XFree86-lib   XFree86-lib-devel )

To compile wmxkb:
There are several ./configure -with options appearing at the end of ./configure --help  In particular you can enable using  XInput  in a (rather hypothetical) case of several keyboards connected to your computer. Shape extension is also disabled by default, if you wish to use your own background pixmap you might need to enable it. Finally you can disable silly images and save several Ks!

I recently upgraded autoconf.  The new package is so tricky that it might not work for you. In this case don't panic :), just try
cp Makefile.linux  Makefile
cp wmxkb_conf.h.linux wmxkb_conf.h
If compilation succeeds,  type
and see how it goes.

To install the binary and manual , log  in as root and enter
make install
Now you only need to get it docked or swallowed. See Running wmxkb as a docked / swallowed applet  for the hints.

Installation from RPM package

For a root it is as easy as
rpm -Uvh  wmxkb-1.2.2-1.i386.rpm

If you use a source distribution, just turn it into a binary with

rpm --rebuild wmxkb-1.2.2-1.src.rpm
the compiled (binary)  rpm is usually stored in /usr/src/redhat/RPM/i386.


wmxkb uses X Resource Manager (XRM) and  takes parameters from the following sources, listed in preference order form lowest to highest:
  1. Global resource file:  /usr/lib/X11/app-defaults/WMxkb or  /etc/X11/app-defaults/WMxkb
  2. User resource file:  .WMxkb (note leading dot) in user's home directory
  3. Command line arguments.
You can edit a resource file manually, or use -save  command line argument creating/updating  the resource files

As usually, command line keywords start with a hyphen(-).  You only need to enter as many characters as needed for unique recognition of the keyword. The value if needed)  is separated from the keyword by a space, e,g,

wmxkb -geom 64x64

where geom is a short word for geometry .

The description of configuration parameters follows.

Run-once command line arguments.

The following command line arguments are not stored in resource files,  and apply only to current run.

-display  <name>

 Specifies display name (e.g.,  default display is used is omitted.


Display list of command line arguments and quit. The list is sent to standard output file.
Help pages is also displayed in case of command line error, in which case it is followed by an error message.


The existing resource parameters are combined with command line arguments (which overwrite resource settings if necessary) and the combined set of  is stored as the user resource file.


 wmxkb -save  -bgcol "nave,red"  -fgcol "yellow,white"
Next time you just type wmxkb to run with specified colours.

Common settings

The following setings apply to the application as a whole  (i.e. not group specific)

-geometry  geometry       -nogeometry

wmxkb. geometry:  <geometry>

As is common for an X11 application, geometry specfifies size and/or position of the window in format:


-nogeometry disables geometry, specified as a resource. This implies size 54 x 54 and default window location.

The window size affects its appearence. Two background images size 54x54 and 44x44 are provided and  if image is required the application will choose the one which fits, or no image if width or height is less than 44.

xoffset and yoffset are interpreted as offsets  from left / top screen border, if positive, or from  right / bottom border , if negative. An offset is always evaluated from nearest window boundary.

Explicitly specified window location normally results  in suppressing window manager placement policy. This might be useful if a window manager is configured for manual (mouse) placement, especially with fvwm: GoodStuff will naively attempt mouse placement even for a swallowed
window ! Another example when explicit location is needed for a swallowed application is related to FvwmButtons module (used most often with fvwm2) : with some versions of FvwmButtons the application window will appear on the desktop for a short time during  FvwmButtons initialization. If that annoys you,  you just need to set  location "off-screen" (-geometry  48-2000-1500).

-tgeometry  geometry   -notgeometry

wmxkb. textGeometry:  <geometry>

Specifies position and size of of the text window:


As opposed to window geometry (or 'just' geometry) text coordinates (xoffset and yoffset) are given relative to application window. As in case of window geometry either or both xoffset and yoffset may be negative.

-notgeometry disables textGeometry, specified as a resource. This implies default text location location at the bottom of application window.

-wode <mode>  -docked  -wnd -iconic

wmxkb.windowMode:  <Docked, Window, Iconic, Guess>

 Window mode can be one of the following:

Run application as a window or as an icon.  Possible mode values are:

Run as a docked icon (main window is withdrawn). Suits WindowMaker, BlackBox and clones
Run in window mode (main window is mapped, icon is not created). Suits gnome, kde, fvwm, or in case docking/swallowing is not required.
Start with main window iconified. Normally used in combination with -ititle  argument
Guess (default)
The application will try to figure out which mode (Docked or Window) will be the best for your window manager.
-docked  -wnd  and -iconic  are equivalent to -wmode d , -wmode w ,  and -wmode i  respectively.

-ititle   -noititle

wmxkb.iconTitle:  <boolean>

Show current keyboard group information as icon name.  Some window managers (FluxBox,  fvwm) display icon names for iconified applications, so that you can see current group name, when the application runs as an icon. To start the application as an icon use -wmode  i.

-imgMode: <Variable, Fixed,  None>

wmxkb.imageMode:  <integer>

If the application was compiled with background image support,  you can specify one of the following modes:

V(variable) or 2  
Try to use a specific image for a group. The image name  is <symbolic_name><size>.xpm, where size is 54 or 44,  e.g.   de54.xpm  Germany, window size 54x54 or more,  de44.xpm  Germany, window size 44x44 or more, but less than 54x54. If this image is not found, the default background image is used. The application comes with flag images for some countries.
F(fixed) or 1
Use default background image with all groups
N(none) or 3
Don't display an image

Default - Variable.

-imageDir  directory

wmxkb.imageDir:  <directory>

If the application was compiled with background image support,  this parameter defines the directory containing background and all custom images. By default the directory specified by --with-imagedir argument for configure,  or $prefix/share/pixmaps/wmxkb is used .

-imgFile  file_name

wmxkb.imageFile:  <file_name>

If the application was compiled with background image support,  this parameter defines file name of default background image. If omitted, name
wmxkb_54.xpm, or wmxkb_44.xpm is used depending on window size.

-transient   -notransient

wmxkb.transient:  <boolean>

Apply/don't apply transient hint to the application window. This might affect window decoration. Some WM (like kwm v.1)  hide iconify button for a transient window  which allows seing the caption, some others (fvwm and clone) can be configured not to draw a caption for a transient window. Default: -notransient

-devorder <number>     -coredev

wmxkb.devOrder:  <number>

In case XInput extension is enabled and several keyboards are connected to your computer,  you may select the one you are interested in. The device order (as opposed to device ID) refers only to keyboard devices - default (core) keyboard usually has devorder  0,   second keyboard has devorder 1, etc.  The choice of keyboard also applies to function keys . Keyboard device lookup is done using XInput extension. If device order is  256,  which is same as  -coredev ,  or XInput support is excluded,  the appllication will avoid looking up device and use core keyboard  - this is probably what you usually want.

-shapes  -noshapes

wmxkb.devorder:  <number>

If yhe application is configured to use Shapes extension (with is not the default), you can disable / enable it.  This is left for purely nostalgic reasons - current background images don't need Shapes.

-tsource  <S, G, U>

wmxkb.titleSource:  < Code, Group, User>

The source used as group name:

S (Symbol)  or 0  - usually country code  ('us",  "ru", etc) this is the default
G (Group)  or  1  - group name ("US / ASII", "Russian", etc)
U (User)  or  2 - custom group name specified as name resources

Each mode has advantages and disadvantages. The symbol is normally a two letter word ( sometimes 5 letters:  fr_CH), which appears to be a right choice, however it might not always be retrieved correctly. Retrieving group names appears to be more straightforward, but ... they are not guaranteed to exist.  I noticed that Japanese group names missing  that required patching the problem in my code. Is Japanese is the only one having the problem ?.. At last, you can supply custom names,  in which case the names are not taken from the system and might be misleading...

-fwdSwitch  <scancode-modifier>

wmxkb.fwdSwitchKey:  <scancode-modifier>

Assign a key for switching to next key group.  See Function keys section.

-backSwitch  <scancode-modifier>

wmxkb.backSwitchKey:  <scancode-modifier>

Assign a key for switching to previous  key group. See Function keys section.

-flexy      -stiff

wmxkb.flexibleGroups  <boolean>

See Flexible groups  section.  Default is False ("stiff"  groups).

Group Settings

The following settings are group-specific. The application provides a shortcut facility where settings for all groups can be entered as a simgle command line argument  sepparated with commas or semicolons, e.g.

wmxkb  -fgcol  "yellow, white "   -bgcol  "navy"  -save
is equivalent to
wmxkb -fgcol1 yellow  -fgcol2 white  -bgcol1 navy  -save
and produces the following resources:
wmxkb.group1.fgcol:   yellow
wmxkb.group2.fgcol:   white
wmxkb.group1.bgcol:  navy

If  number of settings is less than number of groups, the settings are assumed to be repeated.  In particular, one value applies to all groups. In the example above  groups 1 and 3 will use 'yellow on navy",   groups 2 and  4 use "white on navy"

-name <name>  <name>  

Custom group name.  Used  if   title source is U.  

-code <name>

wmxkb.groupX.code:  <symbol>  

Used to to identify a "flexible" group.  See Flexible groups section.

-fgcol <colour_name> 

wmxkb.groupX.fgcol:  <colour>

Foreground colour used for drawing the group title.  A colour can be entered as a symbolic (from rgb.txt) or rgb value, e.g.

"red"  , "#ff0000",   "#ffff00000000"

-bgcol <colour_name>

wmxkb.groupX.bgcol:  <colour>

Text background colour. If image  is not displayed, this colour is used for paining the whole window

-frcol <colour_name> 

wmxkb.groupX.frcol:  <colour>

Frame colour.  Used to draw an area outside the image in case image size  is less than window size.
Ignored if no image is displayed.

-tfont  <font name>  

wmxkb.groupX.tfont:  <colour>

Font used for drawing the title,  given in HPCE  format (e.g. . " -*-fixed-medium-*-*--8-80-*-*-*-50-*-* ")  
or as an alias (e.g. "5x8").  If the font is not specified, the application will try  "6x13" and then " fixed ".
You may be able to print each group name in its native language by specifying appropriate fonts.

-setkey  <scancode-modifier>  

wmxkb.groupX.setKey:  <scancode-modifier>

A key used as a shortcut for switching to this group. See Function keys section.

-latchkey  <scancode-modifier>  

wmxkb.groupX.latchKey:  <scancode-modifier>

A key used as a shortcut for latching the group: the group will apply to next entered charecter only. See Function keys section.

-script  <script>

wmxkb.groupX.script:  <script>  

A command to run when the group become active.  This is typically a shell script, that may change the locale, change font lookup directory etc. .

Controlling wmxkb at run time.

Using mouse buttons

You can use mouse clicks in the following way:

Right mouse click - go to next group
Left  mouse click  - go to previous group
Midle mouse click, or  Ctrl+Right mouse click  - quit apllication   

The groups are wrapped: first group follows the last in forward sequence, and last group follows the first in backward sequence. In particular, in case of  two groups  left and right clicks are practically equivalent.  Avoid "Kill" where possible, use mouse clicks to quit.

Function keys

With wmxkb you can assign any key as a shortcut for changing groups or settings a particular group. Function keys assigned in this way work  in addition to the ones assigned for XKB.  Many recent keybords contain multimedia keys, and you can get these keys really rocking with xhkeys  coincidetally :) available from the same location where wmxkb!  I assume you have some spare key combinations left for XKB groups :)

You need a scan code and modifier (a combination of Shitf, Ctrl, and other if applicable).  An easy way of getting scan code and modifier for a key is provided by xhkconf utility distributed with xhkeys. According to wmxkb syntax, the modifier is separated from the scan code by a hyphen, and there is no need to show a zero midifier  (e.g.   "163 "   is  same as  "163-0")

The following parameters are used:
-fwdswitch   <key>
go to next group
-backswitch  <key>

go to previous group
-setkey <key1,key2,..>

set a particular group
-latchkey <key1,key2,..>

latch a particular group
As opposed to setkey (set  a group permanently),   latchkey  applies the group only to next entered character.

In the folowing example,  [163] and Shift+[163] are used for next and previous group resp,  keys [144] [164] [133] are used for setting group 1, 2 and 3 resp,  those keys  with Shit - for latching groups

wmxkb -fwdswitch  163  -backswitch "163-1" -setkey "144,164,133" -latchkey "144-1,164-1,133-1" -save

which creates the following resource lines:
wmxkb.fwdSwitchKey:    163
wmxkb.backSwitchKey:    163-1
wmxkb.group1.setKey:    144
wmxkb.group1.latchKey:    144-1
wmxkb.group2.setKey:    164
wmxkb.group2.latchKey:   164-1
wmxkb.group3.setKey:     133
wmxkb.group3.latchKey:  133-1


Flexible groups

Flexible groups  (-flexy  command line argument) allow to apply designated settings to a group without relation to its order in XKB layout.

Consider the following resource file:
# Common settings
wmxkb.titleSource:      User
wmxkb.fwdSwitchKey:     254-0
wmxkb.backSwitchKey:     254-1

#  English (US keyboard)      US
wmxkb.group1.bgcol:     navy
wmxkb.group1.fgcol:     yellow
wmxkb.group1.setKey:    253-0
wmxkb.group1.tfont:     6x13bold

#  Cyrillic (Russian keyboard)    Russian
wmxkb.group2.bgcol:     red
wmxkb.group2.fgcol:     white
wmxkb.group2.setKey:    163-0
wmxkb.group2.latchKey:    163-1
wmxkb.group2.tfont:      6x13bold
This works OK as long as the XkbLayout (in XF86Configure)  is  "us,ru".  If you change the layout to "ru,us"  you need to swap group descriptions.
It is possible to avoid the need to redefine the groups, by identifying the groups not by the order in XkbLayout, but by symbolic codes. To do that we set  flexibleGroups to true and enter code parameter for each group to make the identification possible:

# Common settings
wmxkb.flexibleGroups:   1
wmxkb.titleSource:      User
wmxkb.fwdSwitchKey:     254-0
wmxkb.backSwitchKey:     254-1

#  English (US keyboard)
wmxkb.group1.code:      us      US
wmxkb.group1.bgcol:     navy
wmxkb.group1.fgcol:     yellow
wmxkb.group1.setKey:    253-0
wmxkb.group1.tfont:     6x13bold

#  Cyrillic (Russian keyboard)
wmxkb.group2.code:      ru    Russian
wmxkb.group2.bgcol:     red
wmxkb.group2.fgcol:     white
wmxkb.group2.setKey:    163-0
wmxkb.group2.latchKey:    163-1
wmxkb.group2.tfont:      6x13bold

In "flexy" mode,  the application retrieves symbolic name of current group (us or  ru)  and scans group description for the match. If matching group is found,  its settings are applied, otherwise the group is choosed according to the XKB layout order.

With flexible groups you can store a description of up to 100 different key groups in the resource file and obviously not all of them need to participate in actual layout. A sample resource file containing a description of 6 "flexible" groups is supplied with the application, as WMxkb_flexy

Flexible groups is an experimental feature.  Try symbolic names with 'stiff' groups before using flexible groups !

Running wmxkb as a docked / swallowed applet.

Window Maker

In  xterm  type  wmxkb &   and drag application icon to the dock. Click the docked icon border with Right button and select Settings for the pop-up menu. Tick box "Start when WindowMaker is started", press OK. That's it !

BlackBox, FluxBox and clones

Just type   wmxkb &

If it doesn't go to slit, try    wmxkb -docked  &

To get wmxb started automatically with X, you need to add  the line to ~/.xinitrc  (I hope some clones can handle that in a neater way).


The panel size should not be less than 48 (i.e. medium, large, or more).

Right click on the panel.  and  select Panel/Add To Panel/Add Swallowed app.., which brings up 'Create swallowed applet' window.

In the window type:
wmxkb  -geom  54x54    (large panel size or more)
wmxkb  -geom  44x44    (medium panel size)
Width and height:  
60x60    (large panel size)
50x46    (medium panel size)
Press OK and hopefully the window appears.

I recently found a message on the Web that gnome 2 does not run swallowed applications. A bad influence of KDE ?  I wish to be wrong...

KDE (kwm + kpanel)  v 1

The following comments apply to KDE  v 1:

Right click on the desktop. In the popup menu select New|Application
In the  appearing window, select
    New Application:   wmxkb.kdelnk

In the appearing kfm form, select Execute tab and type a text similar to the following:

Execute  (on top)
    wmxkb -transient -geometry 54x54-0+5 -wnd

Swallowing on panel
    Execute:  wmxkb -geom 44x44  
    Window Title: wmxks

Run in terminal: NOT ticked.

Select OK to create a new icon on the desktop
Drag the icon to panel  and wait till the aplication start.

You can't control the applet in run time with the mouse, but you can use swallowed icon as a link: clicking it with left button starts the application in non-swallowed mode.

Unfortunately KDE 2 and 3  do not run swallowed applications. You can comfort yourself with kappdock available from .  Please, don't tell me that a third party application is not a real thing, post a message to KDE forum instead :)

FVWM and clones

If you still use fvwm with GoodStuff,  just add  to ~/.fvwmrc something similar to the following:

*GoodStuff wmxkb  None   Swallow "WMxkb" wmxkb -geom 44x44+0+0 &

If you use  fvwm2 or fvwm95 and  FvwmButtons module  with normal icon size (e.g.   Module FvwmButtons   appear in InitFunction list without MiniButtons parameter), add the following line to ~/.fvwm2rc ( ~/.fvwm95rc for fvwm95):

*FvwmButtons wmalms  NULL Swallow "WMxkb" Exec wmxkb -geometry 44x44+2000+1500

(The huge offset is needed in order to get the window offscreen. See comments regarding   -geometry   ).


This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the

Free Software Foundation, Inc.
675 Mass Ave, Cambridge, MA 02139, USA.


Thanks to Evgenij Baldin  (the author of new Cyrillic Howto), and  Ivan Pascan (the author of xxkb and XKB article) for useful information  and inspiration in work.

Where and Who.

wmxkb is available  from and

Please send comments (of any kind, but relevant to the sotware!)  to me (Michael Glickman): .


Check Web for my other GNU Linux and X11 applications: wmalms   xhkeys   ifrac    sadp   itetris .