Xkbd - onscreen soft keyboard for X11
Matthew Allum 2002 Matthew Allum <mallum@handhelds.org>

xkbd was written by Matthew Allum <breakfast@10.am>.

Carl Worth <cworth@east.isi.edu> also helped with.
Xtest / XLib trickiness.

<morten@bogeskov.dk> supplied a number of cool patches.

Denis Kaganovich (Dzianis Kahanovich) <mahatma@eu.by> fork -
some fixes, docking, etc.



Introduction

Xkbd is a small highly configurable 'virtual' on-screen keyboard for X11. It
is designed primarily for use on a PDA, but will hopefully be of use
on other devices where a physical keyboard is not present.

Xkbd uses no widget set and is based purely on xlib. It also
optionally uses the xft library for anti aliased fonts.


Building and Installing xkbd

Xkbd uses autoconf, so building it should be straightforward:

	$aclocal && autoheader && libtoolize && automake -a
	$./configure
	$make
	# This next step might require root access
	$make install

See the INSTALL file for (standard) gory details regarding autoconf.

Configure currently supports the following options;

  --enable-debug    configure for a debug build
  --enable-xft    configure to use XFT library for anti-aliased fonts.
  --enable-xpm

Make also has an 'ipkg' target for building shiny ipkgs.

A prebuilt ipkg is included in the familiar linux distributions
unstable feed.


Using Xkbd

On launch xkbd will attempt to open its configuration file from
/etc/xkbdrc .

xkbd understands the following command switches;

   -display <display>
      Selects the display for xkbd to appear on.

   -geometry <geometry>
      Provide xkbd with a position and dimension parameters.
      For example 320x100+50+50 will make a 320x100 pixel keyboard 50
      pixels from the side and top of your display.

      NOTE: Its useful to use this option in overide redirect mode
      ( see below ) as xkbd by default will alway take up the smallest
      space possible for its current configuration, unless told
      differently by this option or the window manager.

   -fa <font name>[-<point size> ]
      Select the xft AA font for xkbd. Overrides whatever was defined
      in xkbdrc.

   -fn <font name>
      Select the X11 font for xkbd. Like -fa also overrides.

   -k  <config file>
      Select an alternate  keyboard definition file other than the
      default /etc/xkbdrc.

   -c
      Dock (Openbox, etc).

   -v
      Display the version.

   -h
      Display a breif help message.



Configuring Xkbd

The actual 'keyboard' xkbd uses is defined in a configuration
file. The defualt config file is /etc/xkbdrc, an alternate can be
specified with the -k switch on startup.


A configuration file for xkbd is split into 'tagged' sections;
A global section mainly for the keyboards overall appearance ,  And
row sections containing key definitions which defined the actual
keys.
See /etc/xkbdrc for an example.


The  section should appear first in the file and can contain
the following key/value pairs ( seperated by a space ) ;



xkbd config file options



Key
Value
Description




render
xft|normal
Set mode to 'xft' if you want to use anti aliased fonts.


font
font definition

      Defines the font used for the keyboard. For an xft font, specify
      the point size like -. Default font is fixed / mono.



col
color def

      Defines the color of keyboard background. Defaults to white.
      This as with all color definitions can be either an RGB colon
      seperated list of an X color name. Defaults to white.



down_col
color

      Defines the color of a held down active key. Defaults to black.




    txt_col
color

      Defines the color of the keyboard key text. Defaults to black.




    border_col
color


      Defines the color of the keys border. Defaults to black.




    width|height
pixel count

      Defines the keyboards width or height in pixels. Is overridden by
      the -geometry switch. Defaults to the smallest possible size for
      the defined keyboard.




    button_style
rounded|plain|square

      Sets the basic button visual 'style. Can be rounded ( default ),
      square or plain.




After the <global></global> definition, there then follows one of more
<row> sections which contain the definitions for each on that row. The
Rows go from top to and bottom and the keys left to right. Each row
should just contain  definitions, there are no key / value definitions
presently for rows.


Each key has 3 'states', a default state, a shifted state and a modded
state. Each state contains different key text and keysyms ( what is
actually sent to the focused window when a key is pressed )


Each <key> section can contain the following key / value pairs.

   default

     Defines the text which is displayed on a key when shift or a
     modifier ( ie alt ) is not pressed.

   default_ks

     Defines the actual keysym value that is sent by xkbd to the
     active window when the key is pressed. The keysym is the actual
     value thats sent to to active window. Keysyms are listed in
     /usr/X11R6/include/X11/keysymdef.h
     The is a special keysym '!Mod' which specifies the button is a
     'special' modifier button to access a 2nd alternate keysym for
     the key - see the mod section below.

   shift

     Defines the text which is diplayed on a key when a shift or CAPS
     key is held down. If not set the key will show the default text
     when shift is pressed.

   shift_ks

     Defines the keysym sent when shift or caps is held down.

   mod

     Defines a second alternative text string to be displayed. The mod option
     exists to make it easy to define smaller keyboards with more
     options per key.

   mod_ks

     The keysym to be sent when the 'mod' button is pressed.

   img

     Defines an xpm to be displayed on a key. With this set, no text
     will be displayed and the img currently is the same across of
     keyboard states.

   bg

     Defines the background color of a key, overiding what was set in
     .

   fg

     Defines the foreground color ( ie text ) of a key, overiding what
     was set in  .

   slide_up_ks

     Defines the keysym to be sent when a key is pressed, but the
     pointer is slid up before being released ( a 'slide' ). Other
     slide directions can also be defined ( see below ). defaults
     to the shifted keysym

   slide_down_ks

     defaults to sending a CTRL with the keysym

   slide_left_ks

     defaults to None.

   slide_right_ks

     defaults to None.

   width

     Forces the minimum width of a key to be this set value in pixels.
     Useful specifying a more exact layout.

   height

     Forces the minimum height of a key to be this set value in
     pixels.

   NOTE: If a key contains no keysym definitions its assumed to be an
         empty spacer.


FAQ


Xkbd runs ok, but dont send key presses !

There could be one of two things causing this;


xmodmap


How do I get xkbd to launch from the dock

 monolaunch provides this. Run monolaunch like this;

monolaunch /usr/share/xkbd/img/kbd.xpm xkbd
 Adding the '-k' switch to monolaunch will cause xkbd to completely disappear rather than minimise to a bar.




Embedding Xkbd in to other apps




License

Xkbd is free software released under the terms of the GNU General
Public License, (GPL). 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, or (at your option)
   any later version.


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


Credits
Xkbd is written by Matthew Allum. It uses the libvirtkeys lib by.


Be sure to check out other exciting software by me including; xkbd - a
xlib virtual on-screen keyboard, pikpak - a python gtk front end to
ipkg, gtksolo - a gtk module which turns held down left clicks into
right clicks on gtk apps and jabberpy - a Python library for the Jabber
instant messaging protocol.

Xkbd is copyright Matthew Allum 2002.


