doc: add overview

docs/reference/eek/eek-docs.sgml

@@ -6,46 +6,69 @@
 ]>
 <book id="index">
   <bookinfo>
-    <title>eek Reference Manual</title>
+    <title>libeek Reference Manual</title>
     <releaseinfo>
-      for eek 0.0.0.
+      for libeek 0.0.0.
-   </releaseinfo>
+    </releaseinfo>
+    <copyright>
+      <year>2010</year>
+      <holder>Daiki Ueno</holder>
+    </copyright>
+
+    <copyright>
+      <year>2010</year>
+      <holder>Red Hat, Inc.</holder>
+    </copyright>
+
+    <legalnotice>
+      <para>
+	Permission is granted to copy, distribute and/or modify this
+	document under the terms of the GNU Free Documentation License,
+	Version 1.3 or any later version published by the Free Software
+	Foundation; with no Invariant Sections, no Front-Cover Texts and
+	no Back-Cover Texts.  A copy of the license is included in the
+	section entitled "GNU Free Documentation License".
+      </para>
+    </legalnotice>
   </bookinfo>
 
-  <chapter>
+  <xi:include href="xml/eek-overview.xml"/>
-    <title>Base classes and interfaces</title>
+  <part id="apireference">
-    <xi:include href="xml/eek-element.xml"/>
+    <title>API Manual</title>
-    <xi:include href="xml/eek-container.xml"/>
+    <chapter>
-    <xi:include href="xml/eek-keyboard.xml"/>
+      <title>Base Classes, Interfaces, and Utilities</title>
-    <xi:include href="xml/eek-section.xml"/>
+      <xi:include href="xml/eek-element.xml"/>
-    <xi:include href="xml/eek-key.xml"/>
+      <xi:include href="xml/eek-container.xml"/>
-    <xi:include href="xml/eek-layout.xml"/>
+      <xi:include href="xml/eek-keyboard.xml"/>
-    <xi:include href="xml/eek-types.xml"/>
+      <xi:include href="xml/eek-section.xml"/>
-  </chapter>
+      <xi:include href="xml/eek-key.xml"/>
-  <chapter>
+      <xi:include href="xml/eek-layout.xml"/>
-    <title>Clutter keyboard</title>
+      <xi:include href="xml/eek-types.xml"/>
-    <xi:include href="xml/eek-clutter-keyboard.xml"/>
+      <xi:include href="xml/eek-keysym.xml"/>
-  </chapter>
+    </chapter>
-  <chapter>
+    <chapter>
-    <title>GTK keyboard</title>
+      <title>Clutter Keyboard</title>
-    <xi:include href="xml/eek-gtk-keyboard.xml"/>
+      <xi:include href="xml/eek-clutter-keyboard.xml"/>
-  </chapter>
+    </chapter>
-  <chapter>
+    <chapter>
-    <title>XKB layout engine</title>
+      <title>GTK Keyboard</title>
-    <xi:include href="xml/eek-xkb-layout.xml"/>
+      <xi:include href="xml/eek-gtk-keyboard.xml"/>
-  </chapter>
+    </chapter>
-  <chapter>
+    <chapter>
-    <title>Libxklavier layout engine</title>
+      <title>Libxklavier Layout Engine</title>
-    <xi:include href="xml/eek-xkl-layout.xml"/>
+      <xi:include href="xml/eek-xkl-layout.xml"/>
-  </chapter>
+    </chapter>
-  <chapter id="object-tree">
+    <chapter>
-    <title>Object Hierarchy</title>
+      <title>XKB Layout Engine</title>
-     <xi:include href="xml/tree_index.sgml"/>
+      <xi:include href="xml/eek-xkb-layout.xml"/>
-  </chapter>
+    </chapter>
-  <index id="api-index-full">
+    <chapter id="object-tree">
-    <title>API Index</title>
+      <title>Object Hierarchy</title>
-    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+      <xi:include href="xml/tree_index.sgml"/>
-  </index>
+    </chapter>
-
+    <index id="api-index-full">
-  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+      <title>API Index</title>
+      <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+    </index>
+  </part>
 </book>

docs/reference/eek/eek-overview.xml

@@ -0,0 +1,59 @@
+<part id="eek-overview">
+  <title>Overview</title>
+  <partintro>
+
+    <para>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 <emphasis>keyboard element</emphasis>
+    (derived from #EekElement) and another is <emphasis>keyboard
+    layout engine</emphasis> (which implements the #EekLayout
+    interface).</para>
+
+    <para>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,
+    aso).</para>
+
+    <para>A layout engine arranges keyboard elements using information
+    from external configuration mechanisms (libxklavier, XKB,
+    matchbox-keyboard layouts in XML, aso)</para>
+
+    <para>Here is a sample code which creates a keyboard-like #ClutterActor using the system layout information from libxklavier:</para>
+
+    <informalexample>
+      <programlisting>
+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)));
+      </programlisting>
+    </informalexample>
+
+    <para>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().</para>
+
+    <para>Another interesting feature is that there is logical represention (model) of keyboard distinct from the UI widget (view).  More precisely, #EekKeyboard contains one or more #EekSection's and #EekSection contains one or more #EekKey's, and each element may send events when a user clicked on the UI widget.  For example, with the following code, when a user pushed a key widget with keycode 0x38 assigned, on_a_pressed will be called.</para>
+    <informalexample>
+      <programlisting>
+/* 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);
+      </programlisting>
+    </informalexample>
+  </partintro>
+</part>

docs/reference/eek/eek-sections.txt

@@ -0,0 +1,243 @@
+<SECTION>
+<FILE>eek-keyboard</FILE>
+<TITLE>EekKeyboard</TITLE>
+EekKeyboardClass
+EekKeyboardPrivate
+EekKeyboard
+eek_keyboard_set_keysym_index
+eek_keyboard_get_keysym_index
+eek_keyboard_create_section
+eek_keyboard_set_layout
+eek_keyboard_realize
+eek_keyboard_find_key_by_keycode
+<SUBSECTION Standard>
+EEK_KEYBOARD
+EEK_IS_KEYBOARD
+EEK_TYPE_KEYBOARD
+eek_keyboard_get_type
+EEK_KEYBOARD_CLASS
+EEK_IS_KEYBOARD_CLASS
+EEK_KEYBOARD_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>eek-layout</FILE>
+<TITLE>EekLayout</TITLE>
+EekLayoutIface
+EekLayout
+eek_layout_apply
+eek_layout_get_group
+<SUBSECTION Standard>
+EEK_LAYOUT
+EEK_IS_LAYOUT
+EEK_TYPE_LAYOUT
+eek_layout_get_type
+EEK_LAYOUT_GET_IFACE
+</SECTION>
+
+<SECTION>
+<FILE>eek-gtk-keyboard</FILE>
+<TITLE>EekGtkKeyboard</TITLE>
+EekGtkKeyboard
+EekGtkKeyboardClass
+EekGtkKeyboardPrivate
+eek_gtk_keyboard_new
+eek_gtk_keyboard_get_widget
+<SUBSECTION Standard>
+EEK_GTK_KEYBOARD
+EEK_IS_GTK_KEYBOARD
+EEK_TYPE_GTK_KEYBOARD
+eek_gtk_keyboard_get_type
+EEK_GTK_KEYBOARD_CLASS
+EEK_IS_GTK_KEYBOARD_CLASS
+EEK_GTK_KEYBOARD_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>eek-section</FILE>
+<TITLE>EekSection</TITLE>
+EekSectionClass
+EekSectionPrivate
+EekSection
+eek_section_set_angle
+eek_section_get_angle
+eek_section_get_n_rows
+eek_section_add_row
+eek_section_get_row
+eek_section_create_key
+eek_section_find_key_by_keycode
+<SUBSECTION Standard>
+EEK_SECTION
+EEK_IS_SECTION
+EEK_TYPE_SECTION
+eek_section_get_type
+EEK_SECTION_CLASS
+EEK_IS_SECTION_CLASS
+EEK_SECTION_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>eek-container</FILE>
+<TITLE>EekContainer</TITLE>
+EekContainerClass
+EekContainerPrivate
+EekCallback
+EekCompareFunc
+EekContainer
+eek_container_foreach_child
+eek_container_find
+eek_container_find_by_position
+<SUBSECTION Standard>
+EEK_CONTAINER
+EEK_IS_CONTAINER
+EEK_TYPE_CONTAINER
+eek_container_get_type
+EEK_CONTAINER_CLASS
+EEK_IS_CONTAINER_CLASS
+EEK_CONTAINER_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>eek-clutter-keyboard</FILE>
+<TITLE>EekClutterKeyboard</TITLE>
+EekClutterKeyboard
+EekClutterKeyboardClass
+EekClutterKeyboardPrivate
+eek_clutter_keyboard_new
+eek_clutter_keyboard_get_actor
+<SUBSECTION Standard>
+EEK_CLUTTER_KEYBOARD
+EEK_IS_CLUTTER_KEYBOARD
+EEK_TYPE_CLUTTER_KEYBOARD
+eek_clutter_keyboard_get_type
+EEK_CLUTTER_KEYBOARD_CLASS
+EEK_IS_CLUTTER_KEYBOARD_CLASS
+EEK_CLUTTER_KEYBOARD_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>eek-xkl-layout</FILE>
+<TITLE>EekXklLayout</TITLE>
+EekXklLayout
+EekXklLayoutClass
+EekXklLayoutPrivate
+eek_xkl_layout_new
+eek_xkl_layout_set_config
+eek_xkl_layout_set_model
+eek_xkl_layout_set_layouts
+eek_xkl_layout_set_variants
+eek_xkl_layout_set_options
+eek_xkl_layout_get_model
+eek_xkl_layout_get_layouts
+eek_xkl_layout_get_variants
+eek_xkl_layout_get_options
+<SUBSECTION Standard>
+EEK_XKL_LAYOUT
+EEK_IS_XKL_LAYOUT
+EEK_TYPE_XKL_LAYOUT
+eek_xkl_layout_get_type
+EEK_XKL_LAYOUT_CLASS
+EEK_IS_XKL_LAYOUT_CLASS
+EEK_XKL_LAYOUT_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>eek-xkb-layout</FILE>
+<TITLE>EekXkbLayout</TITLE>
+EekXkbLayout
+EekXkbLayoutClass
+EekXkbLayoutPrivate
+eek_xkb_layout_new
+eek_xkb_layout_set_names
+eek_xkb_layout_set_keycodes
+eek_xkb_layout_set_geometry
+eek_xkb_layout_set_symbols
+eek_xkb_layout_get_keycodes
+eek_xkb_layout_get_geometry
+eek_xkb_layout_get_symbols
+<SUBSECTION Standard>
+EEK_XKB_LAYOUT
+EEK_IS_XKB_LAYOUT
+EEK_TYPE_XKB_LAYOUT
+eek_xkb_layout_get_type
+EEK_XKB_LAYOUT_CLASS
+EEK_IS_XKB_LAYOUT_CLASS
+EEK_XKB_LAYOUT_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>eek-key</FILE>
+<TITLE>EekKey</TITLE>
+EekKeyClass
+EekKeyPrivate
+EekKey
+eek_key_set_keycode
+eek_key_get_keycode
+eek_key_set_keysyms
+eek_key_get_keysyms
+eek_key_get_keysym
+eek_key_set_index
+eek_key_get_index
+eek_key_set_outline
+eek_key_get_outline
+eek_key_set_keysym_index
+eek_key_get_keysym_index
+<SUBSECTION Standard>
+EEK_KEY
+EEK_IS_KEY
+EEK_TYPE_KEY
+eek_key_get_type
+EEK_KEY_CLASS
+EEK_IS_KEY_CLASS
+EEK_KEY_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>eek-element</FILE>
+<TITLE>EekElement</TITLE>
+EekElementClass
+EekElementPrivate
+EekElement
+eek_element_set_parent
+eek_element_get_parent
+eek_element_set_name
+eek_element_get_name
+eek_element_set_bounds
+eek_element_get_bounds
+eek_element_get_absolute_position
+<SUBSECTION Standard>
+EEK_ELEMENT
+EEK_IS_ELEMENT
+EEK_TYPE_ELEMENT
+eek_element_get_type
+EEK_ELEMENT_CLASS
+EEK_IS_ELEMENT_CLASS
+EEK_ELEMENT_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>eek-types</FILE>
+EekOrientation
+EekKeysymMatrix
+EEK_TYPE_KEYSYM_MATRIX
+eek_keysym_matrix_get_type
+EekPoint
+EEK_TYPE_POINT
+eek_point_get_type
+EekBounds
+EEK_TYPE_BOUNDS
+eek_bounds_get_type
+eek_bounds_long_side
+EekOutline
+EEK_TYPE_OUTLINE
+eek_outline_get_type
+</SECTION>
+
+<SECTION>
+<FILE>eek-keysym</FILE>
+EEK_INVALID_KEYSYM
+EEK_INVALID_KEYCODE
+EekKeysymCategory
+eek_keysym_to_string
+eek_keysym_get_category
+</SECTION>