# 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
    15
    EekLayout *layout;
    EekKeyboard *keyboard;
    ClutterActor *actor;

    /* Create a layout engine based on libxklavier configuration. */
    layout = eek_xkl_layout_new ();

    /* Create a keyboard from the given layout. */
    keyboard = eek_keyboard_new (layout, initial_width, initial_height);

    /* Create a ClutterActor. */
    actor = eek_clutter_keyboard_new (eekboard->keyboard);

    /* Add the actor to a stage. */
    clutter_group_add (CLUTTER_GROUP(stage), actor);

libeek currently supports GTK+ and Clutter as UI toolkits. To create a keyboard-like GtkWidget instead of ClutterActor, replace `eek_clutter_keyboard_new()` with `eek_gtk_keyboard_new()`. 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()`.

In the above 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.