From de7f31f067031ce8e63c67989c3139b88625e92f Mon Sep 17 00:00:00 2001 From: Daiki Ueno Date: Tue, 22 Jun 2010 13:00:47 +0900 Subject: [PATCH] Refine "Usage Overview". --- docs/reference/eek/eek-overview.xml | 46 +++++++++++++++++++---------- 1 file changed, 30 insertions(+), 16 deletions(-) diff --git a/docs/reference/eek/eek-overview.xml b/docs/reference/eek/eek-overview.xml index 89742468..462ff95b 100644 --- a/docs/reference/eek/eek-overview.xml +++ b/docs/reference/eek/eek-overview.xml @@ -4,23 +4,25 @@ libeek is a library to create keyboard-like user interface. Since it is designed as simple as possible, it provides only two - kinds of objects. One is keyboard element - (derived from #EekElement) and another is keyboard - layout engine (which implements the #EekLayout - interface). + 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 be - converted into a UI widget (#ClutterActor, #GtkDrawingArea, + 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 creates a keyboard-like #ClutterActor using the system keyboard layout using libxklavier: - + 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: EekKeyboard *keyboard; @@ -40,14 +42,26 @@ clutter_group_add (CLUTTER_GROUP(stage), - One of the most interesting features of libeek is that UI - backends can be switched easily. 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(). + 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(). - There is logical represention (model) of keyboard distinct from the UI widget (view). More precisely, 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 can be event source when user events on the UI widget occurs. For example, with the following code, when a user pushed a key widget with keycode 0x38 assigned, on_a_pressed will be called. + To achieve the portability between 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 can relay + events when user taps on the UI widget. + + Here is another sample code which demonstrates logical events on + #EekElement: + /* Find a key element in the logical keyboard. */ @@ -55,6 +69,6 @@ EekKey *key = eek_keyboard_find_key_by_keycode (keyboard, 0x38); g_signal_connect (key, "pressed", on_a_pressed); - In this way, application developers do not need to know the differences between the underlying UI widgets after creation. + When user pushed a widget which looks like "a" key (i.e. keycode 0x38), on_a_pressed will be called.