Part I. Usage Overview

libeek is a library to create keyboard-like user interface. Since it is designed as simple as possible, it provides only two kind of objects. One is keyboard element (objects derived from EekElement) and another is keyboard layout engine (objects which implements the EekLayout interface).

A keyboard element represents either a keyboard (EekKeyboard), a section (EekSection), or a key (EekKey). Each element implements the Builder design pattern so that it can map itself to different UI widgets (ClutterActor, GtkDrawingArea, aso).

A layout engine arranges keyboard elements using information from external configuration mechanisms (libxklavier, XKB, matchbox-keyboard layouts in XML, aso)

Here is a sample code which demonstrates (1) keyboard elements are arranged with the system keyboard layout using libxklavier and (2) keyboard elements are mapped into ClutterActor:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
EekKeyboard *keyboard;
EekLayout *layout;

/* Create a keyboard layout using libxklavier configuration. */
layout = eek_xkl_layout_new ();

/* Create a keyboard implemented as ClutterActor. */
keyboard = eek_clutter_keyboard_new ();

/* Apply the layout to the keyboard. */
eek_keyboard_set_layout (keyboard, layout);

clutter_group_add (CLUTTER_GROUP(stage),
                   eek_clutter_keyboard_get_actor (EEK_CLUTTER_KEYBOARD(keyboard)));

The most interesting feature of libeek is that developer can choose arbitrary combination of UI toolkits and layout engine supported by libeek. For example, to create a keyboard-like GtkWidget instead of ClutterActor, all you need is to replace eek_clutter_keyboard_new() with eek_gtk_keyboard_new() and eek_clutter_keyboard_get_actor() with eek_gtk_keyboard_get_widget(). Similarly, if you want to use XKB configuration directly (without libxklavier), you will only need to replace eek_xkl_layout_new() with eek_xkb_layout_new().

To achieve portability across different UI toolkits, there is a seperate represention of keyboard elements apart from the actual UI widgets. For example, a keyboard is represented as a tree of EekElement -- EekKeyboard contains one or more EekSection's and EekSection contains one or more EekKey's. Each element may emit events when user pushes the corresponding UI widget.

Here is another sample code which demonstrates logical events on EekElement:

1
2
3
/* Find a key element in the logical keyboard. */
EekKey *key = eek_keyboard_find_key_by_keycode (keyboard, 0x38);
g_signal_connect (key, "pressed", on_a_pressed);

When user pushed a widget which looks like "a" key (i.e. keycode 0x38), on_a_pressed will be called.