Boarded
=======


Version: 0.1beta1
Author:  Robert Schindler <robert-sch at gmx dot net>
License: GNU General Public License version 3
Website: http://boarded.sourceforge.net/


This is the Boarded virtual on-screen keyboard.


Building from source
--------------------

Requirements:
- Python >= 2.5 < 3.0
- PyGTK >= 2.0
- python-gobject
- python-virtkey >= 0.60
- gettext
- python-distutils-extra >= 2.12

Build with:
$ python setup.py build
and then install as root with:
$ python setup.py install

NOTE:
On debian systems it is better to use:
$ python setup.py install --install-layout=deb
because the Boarded package has to be installed into dist-packages
instead of site-packages there. Furthermore --install-layout=deb sets
/usr as install prefix.


Configuration
-------------
In /usr/share/doc/boarded/examples you can find config.example, a
documented example configuration. Follow the instructions in this file
to customize Boarded to your needs.


Usage
-----
Simply call
$ boarded
to start the on-screen keyboard.

If you click into the area outside of any key, the Boarded menu will
pop up. The menu is also accessible through the Boarded key, see
"Designing own keyboards" for more information about this.


Gestures and key behaviour
--------------------------
Boarded supports different gestures you can execute with a pointer device
(like a mouse) or a touch screen.

1. To press a normal key:
- Simply click on it.
- Hold it clicked as long as you want.
2. To latch one or more modifiers for ONE keypress:
- Click the modifier keys in the order they should be pressed.
- Then click onto a normal key.
- The modifiers will now be locked, then the non-modifier key will be
  pressed once. Afterwards the modifiers will be unlocked and are coloured
  as any other key again.
3. To lock a modifier for more then one key press:
- Act as in (2.) but with the exception that you click the modifier(s)
  two times instead of only once. They will then be shown as locked and
  survive multiple key presses.
4. To send a modifier key press to the system without pressing a
   non-modifier key:
- Click onto the modifier and drag the pointer outside of the key.
- When the modifier key is coloured as locked, the key down event is
  sent. Hold it as long as you want and then release the button to unlock
  the key.


Designing own keyboards
-----------------------
Boarded will search the following directories for keyboard XML files in
the shown order:
- /usr/share/boarded/keyboards
- ~/.boarded/keyboards
Keyboard files shipped with this Boarded installation can be found in
/usr/share/boarded/keyboards

Each XML file may contain one or more keyboards. In each keyboard,
there can be multiple keys.

A Key may have the following attributes:
- Required attributes:
  - size           | key size (width,height)
  - pos            | key position on the keyboard
  - label          | text to show on the key
- Optional attributes:
  - Key behaviour: | The following attributes control what happens
                     when the user presses the key. Each key may have
                     one of them defined.
    - mod          | modifiers (ctrl_l, ctrl_r, shift_l, shift_r,
                     capslock, alt, alt_gr, numlock, super_l, super_r)
    - action       | predefined actions
                     (escape, return, space, tab, insert, home, end,
                     delete, backspace, menu, page_up, page_down, left,
                     up, right, down, f1..12, print, scrolllock, pause)
    - keysym       | hexadecimal X keysym (0xffff, for instance)
    - unicode      | an arbitrary unicode character
    - keycode      | the keycode to press (for instance: 24 for the Q key,
                     25 for W or 65 for Space)
  - group          | All keys in the same group can be shown/hidden
                     together at runtime to save display space. Group
                     names are freely selectable.
  - press_after    | If set to "true", the key press event will be
                     sent when the user releases the mouse button instead
                     of when it is pressed down. This is needed for some
                     keys have a different behaviour when a mouse button
                     is down. The menu key, for example, only works if
                     no mouse is pressed. Keep in mind when using this
                     option it is not possible to hold a key pressed.

There are two special keys, the Boarded key and the window motion
key. They are used to open the Boarded menu and to drag the keyboard
window. You define them as follows:
<Key size="x,y" pos="x,y" label="Boarded" action="boarded_menu" />
<Key size="x,y" pos="x,y" label="Drag" action="window_motion" />

Key positions and sizes as specified here are not the real values in
pixels, for instance. But they are all multiplied by the same factor to
ensure a proportional in/decrease of all parts of the keyboard. This
allows the user to change the window size without destroying the
keyboards proportions.


Bugs
----
Please report bugs using the ticket system on Boarded's project page.
