Minor arrangement for gtk-doc.

docs/reference/eek/eek-docs.sgml

@@ -18,6 +18,7 @@
     <xi:include href="xml/eek-section.xml"/>
     <xi:include href="xml/eek-key.xml"/>
     <xi:include href="xml/eek-layout.xml"/>
+    <xi:include href="xml/eek-types.xml"/>
   </chapter>
   <chapter>
     <title>Clutter keyboard elements</title>

eek/eek-clutter-key.c

@@ -140,8 +140,8 @@ eek_clutter_key_real_set_bounds (EekKey *self, EekBounds *bounds)
     clutter_actor_set_anchor_point_from_gravity (CLUTTER_ACTOR(self),
                                                  CLUTTER_GRAVITY_CENTER);
     clutter_actor_set_position (CLUTTER_ACTOR(self),
-                                bounds->x + bounds->w / 2,
+                                bounds->x + bounds->width / 2,
-                                bounds->y + bounds->h / 2);
+                                bounds->y + bounds->height / 2);
 }
 
 static void
@@ -231,7 +231,7 @@ draw_key_on_layout (EekKey      *key,
     PangoRectangle logical_rect = { 0, };
     EekBounds bounds;
     guint keysym;
-    const gchar *label;
+    const gchar *label, *empty_label = "";
     gdouble scale_x, scale_y;
 
     eek_key_get_bounds (key, &bounds);
@@ -240,21 +240,23 @@ draw_key_on_layout (EekKey      *key,
         return;
     label = eek_keysym_to_string (keysym);
     if (!label)
-        label = "";
+        label = empty_label;
 
     /* Compute the layout extents. */
     buffer = pango_layout_copy (layout);
     draw_text_on_layout (buffer, label, 1.0);
     pango_layout_get_extents (buffer, NULL, &logical_rect);
     scale_x = scale_y = 1.0;
-    if (PANGO_PIXELS(logical_rect.width) > bounds.w)
+    if (PANGO_PIXELS(logical_rect.width) > bounds.width)
-        scale_x = bounds.w / PANGO_PIXELS(logical_rect.width);
+        scale_x = bounds.width / PANGO_PIXELS(logical_rect.width);
-    if (PANGO_PIXELS(logical_rect.height) > bounds.h)
+    if (PANGO_PIXELS(logical_rect.height) > bounds.height)
-        scale_y = bounds.h / PANGO_PIXELS(logical_rect.height);
+        scale_y = bounds.height / PANGO_PIXELS(logical_rect.height);
     g_object_unref (buffer);
 
     /* Actually draw on the layout */
     draw_text_on_layout (layout, label, scale_x < scale_y ? scale_x : scale_y);
+    if (label != empty_label)
+        g_free ((gpointer)label);
 }
 
 static void
@@ -301,25 +303,10 @@ eek_clutter_key_get_preferred_width (ClutterActor *self,
                                      gfloat       *natural_width_p)
 {
     PangoLayout *layout;
-    PangoFontDescription *font_desc;
-    PangoRectangle logical_rect = { 0, };
-    EekBounds bounds;
-    guint keysym;
-    const gchar *label;
-    gdouble scale = 1.0;
 
-    eek_key_get_bounds (EEK_KEY(self), &bounds);
+    /* Draw the label on the key - just to validate the glyph cache. */
-    keysym = eek_key_get_keysym (EEK_KEY(self));
-    g_return_if_fail (keysym != EEK_INVALID_KEYSYM);
-    label = eek_keysym_to_string (keysym);
-    if (!label)
-        label = "";
-
-    /* Draw the label on the key. */
     layout = clutter_actor_create_pango_layout (self, NULL);
     draw_key_on_layout (EEK_KEY(self), layout);
-    pango_layout_get_extents (layout, NULL, &logical_rect);
-
     cogl_pango_ensure_glyph_cache_for_layout (layout);
     g_object_unref (layout);
 
@@ -520,7 +507,7 @@ eek_clutter_key_create_texture (EekClutterKey *key)
     outline = eek_key_get_outline (EEK_KEY(key));
     eek_key_get_bounds (EEK_KEY(key), &bounds);
 
-    texture = clutter_cairo_texture_new (bounds.w, bounds.h);
+    texture = clutter_cairo_texture_new (bounds.width, bounds.height);
     cr = clutter_cairo_texture_create (CLUTTER_CAIRO_TEXTURE(texture));
     cairo_set_line_width (cr, 1);
     cairo_set_line_join (cr, CAIRO_LINE_JOIN_ROUND);

eek/eek-clutter-keyboard.c

@@ -65,7 +65,7 @@ eek_clutter_keyboard_real_set_bounds (EekKeyboard *self,
     g_return_if_fail (priv);
     eek_keyboard_set_bounds (EEK_KEYBOARD(priv->simple), bounds);
     clutter_actor_set_position (CLUTTER_ACTOR(self), bounds->x, bounds->y);
-    clutter_actor_set_size (CLUTTER_ACTOR(self), bounds->w, bounds->h);
+    clutter_actor_set_size (CLUTTER_ACTOR(self), bounds->width, bounds->height);
 }
 
 static void
@@ -250,7 +250,7 @@ eek_clutter_keyboard_new (gfloat width,
     EekBounds bounds;
 
     bounds.x = bounds.y = 0;
-    bounds.w = width;
+    bounds.width = width;
-    bounds.h = height;
+    bounds.height = height;
     return g_object_new (EEK_TYPE_CLUTTER_KEYBOARD, "bounds", &bounds, NULL);
 }

eek/eek-clutter-section.c

@@ -114,7 +114,7 @@ eek_clutter_section_real_set_bounds (EekSection *self,
     g_return_if_fail (priv);
     eek_section_set_bounds (EEK_SECTION(priv->simple), bounds);
     clutter_actor_set_position (CLUTTER_ACTOR(self), bounds->x, bounds->y);
-    clutter_actor_set_size (CLUTTER_ACTOR(self), bounds->w, bounds->h);
+    clutter_actor_set_size (CLUTTER_ACTOR(self), bounds->width, bounds->height);
 }
 
 static void

eek/eek-key.c

@@ -97,7 +97,7 @@ eek_key_base_init (gpointer g_iface)
          */
         /* Use pointer instead of boxed to avoid copy, since we can
            assume that only a few outline shapes are used in a whole
-           keyboard (unlike labels and bounds). */
+           keyboard (unlike keysyms and bounds). */
         pspec = g_param_spec_pointer ("outline",
                                       "Outline",
                                       "Pointer to outline shape of the key",
@@ -119,7 +119,7 @@ eek_key_base_init (gpointer g_iface)
         /**
          * EekKey:group:
          *
-         * The column index of #EekKey in the label matrix #EekKey:labels.
+         * The column index of #EekKey in the symbol matrix #EekKey:keysyms.
          */
         pspec = g_param_spec_int ("group",
                                   "Group",
@@ -131,7 +131,7 @@ eek_key_base_init (gpointer g_iface)
         /**
          * EekKey:level:
          *
-         * The row index of #EekKey in the label matrix #EekKey:labels.
+         * The row index of #EekKey in the symbol matrix #EekKey:keysyms.
          */
         pspec = g_param_spec_int ("level",
                                   "Level",
@@ -208,10 +208,9 @@ eek_key_get_groups  (EekKey *key)
  * eek_key_get_keysym:
  * @key: an #EekKey
  *
- * Get the current symbol of @key.  It is depend on the current group,
+ * Get the current symbol of @key.  It is depend on the current group
- * level, and the symbol matrix of @key.  They are set with
+ * and level, and the symbol matrix of @key.  They are set through
- * eek_key_set_group(), eek_key_set_level(), and eek_key_set_labels(),
+ * eek_key_set_keysym_index() and eek_key_set_keysyms(), respectively.
- * respectively.
  */
 guint
 eek_key_get_keysym (EekKey *key)

eek/eek-key.h

@@ -31,6 +31,7 @@ G_BEGIN_DECLS
 #define EEK_KEY_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), EEK_TYPE_KEY, EekKeyIface))
 
 typedef struct _EekKeyIface EekKeyIface;
+typedef struct _EekKey EekKey;
 
 struct _EekKeyIface
 {
@@ -40,8 +41,8 @@ struct _EekKeyIface
     /*< public >*/
     void        (* set_keysyms)      (EekKey     *self,
                                       guint      *keysyms,
-                                      gint        groups,
+                                      gint        num_groups,
-                                      gint        levels);
+                                      gint        num_levels);
     gint        (* get_groups)       (EekKey     *self);
     guint       (* get_keysym)       (EekKey     *self);
 
@@ -72,8 +73,8 @@ GType       eek_key_get_type         (void) G_GNUC_CONST;
 
 void        eek_key_set_keysyms      (EekKey     *key,
                                       guint      *keysyms,
-                                      gint        groups,
+                                      gint        num_groups,
-                                      gint        levels);
+                                      gint        num_levels);
 gint        eek_key_get_groups       (EekKey     *key);
 guint       eek_key_get_keysym       (EekKey     *key);
 

eek/eek-keyboard.c

@@ -163,10 +163,8 @@ eek_keyboard_foreach_section (EekKeyboard *keyboard,
  * @keyboard: a #EekKeyboard
  * @layout: a #EekLayout
  *
- * Set the layout of @keyboard to @layout.  For the user of EEK, it is
+ * Set the layout of @keyboard to @layout.  This actually turns
- * preferable to call this function rather than
+ * @keyboard to be ready to be drawn on the screen.
- * eek_layout_apply_to_keyboard(), while the implementation calls it
- * internally.
  */
 void
 eek_keyboard_set_layout (EekKeyboard *keyboard,

eek/eek-keysym.c

@@ -53,6 +53,12 @@ keysym_label_compare (const void *key0, const void *key1)
     return (gint)entry0->keysym - (gint)entry1->keysym;
 }
 
+/**
+ * eek_keysym_to_string:
+ * @keysym: keysym ID
+ *
+ * Return a string representation of @keysym.
+ */
 G_CONST_RETURN gchar *
 eek_keysym_to_string (guint keysym)
 {

eek/eek-section.c

@@ -248,15 +248,15 @@ eek_section_get_bounds (EekSection *section,
  * Create an #EekKey instance and attach it to @section.
  */
 EekKey *
-eek_section_create_key (EekSection   *section,
+eek_section_create_key (EekSection  *section,
-                        const gchar  *name,
+                        const gchar *name,
-                        guint  *keysyms,
+                        guint       *keysyms,
-                        gint          num_groups,
+                        gint         num_groups,
-                        gint          num_levels,
+                        gint         num_levels,
-                        gint          column,
+                        gint         column,
-                        gint          row,
+                        gint         row,
-                        EekOutline   *outline,
+                        EekOutline  *outline,
-                        EekBounds    *bounds)
+                        EekBounds   *bounds)
 {
     EekSectionIface *iface;
 

eek/eek-section.h

@@ -30,6 +30,7 @@ G_BEGIN_DECLS
 #define EEK_SECTION_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), EEK_TYPE_SECTION, EekSectionIface))
 
 typedef struct _EekSectionIface EekSectionIface;
+typedef struct _EekSection EekSection;
 
 struct _EekSectionIface
 {
@@ -86,7 +87,7 @@ void    eek_section_get_bounds     (EekSection  *section,
 
 EekKey *eek_section_create_key     (EekSection  *section,
                                     const gchar *name,
-                                    guint       *labels,
+                                    guint       *keysyms,
                                     gint         num_groups,
                                     gint         num_levels,
                                     gint         column,

eek/eek-types.h

@@ -24,6 +24,8 @@
 
 G_BEGIN_DECLS
 
+typedef struct _EekKeyboard EekKeyboard;
+
 /**
  * EekKeysymMatrix:
  * @data: array of keysyms
@@ -73,8 +75,8 @@ struct _EekBounds
 {
     gdouble x;
     gdouble y;
-    gdouble w;
+    gdouble width;
-    gdouble h;
+    gdouble height;
 };
 typedef struct _EekBounds EekBounds;
 
@@ -100,10 +102,5 @@ typedef struct _EekOutline EekOutline;
 #define EEK_TYPE_OUTLINE (eek_outline_get_type ())
 GType eek_outline_get_type (void) G_GNUC_CONST;
 
-/* dummy */
-typedef struct _EekKeyboard EekKeyboard;
-typedef struct _EekSection EekSection;
-typedef struct _EekKey EekKey;
-
 G_END_DECLS
 #endif  /* EEK_TYPES_H */

eek/eek-xkb-layout.c

@@ -175,8 +175,8 @@ create_key (EekXkbLayout *layout,
     xkbbounds = &xkbgeometry->shapes[xkbkey->shape_ndx].bounds;
     bounds.x = xkb_to_pixmap_coord(layout, xkbbounds->x1 + x);
     bounds.y = xkb_to_pixmap_coord(layout, xkbbounds->y1 + y);
-    bounds.w = xkb_to_pixmap_coord(layout, xkbbounds->x2 - xkbbounds->x1);
+    bounds.width = xkb_to_pixmap_coord(layout, xkbbounds->x2 - xkbbounds->x1);
-    bounds.h = xkb_to_pixmap_coord(layout, xkbbounds->y2 - xkbbounds->y1);
+    bounds.height = xkb_to_pixmap_coord(layout, xkbbounds->y2 - xkbbounds->y1);
 
     keycode = find_keycode (layout, name);
     if (keycode == INVALID_KEYCODE)
@@ -222,8 +222,8 @@ create_section (EekXkbLayout  *layout,
 
     bounds.x = xkb_to_pixmap_coord(layout, xkbsection->left);
     bounds.y = xkb_to_pixmap_coord(layout, xkbsection->top);
-    bounds.w = xkb_to_pixmap_coord(layout, xkbsection->width);
+    bounds.width = xkb_to_pixmap_coord(layout, xkbsection->width);
-    bounds.h = xkb_to_pixmap_coord(layout, xkbsection->height);
+    bounds.height = xkb_to_pixmap_coord(layout, xkbsection->height);
 
     priv = layout->priv;
     xkbgeometry = priv->xkb->geom;
@@ -282,11 +282,11 @@ create_keyboard (EekXkbLayout *layout, EekKeyboard *keyboard)
     xkbgeometry = priv->xkb->geom;
 
     eek_keyboard_get_bounds (keyboard, &bounds);
-    setup_scaling (EEK_XKB_LAYOUT(layout), bounds.w, bounds.h);
+    setup_scaling (EEK_XKB_LAYOUT(layout), bounds.width, bounds.height);
 
     bounds.x = bounds.y = 0;
-    bounds.w = xkb_to_pixmap_coord(layout, xkbgeometry->width_mm);
+    bounds.width = xkb_to_pixmap_coord(layout, xkbgeometry->width_mm);
-    bounds.h = xkb_to_pixmap_coord(layout, xkbgeometry->height_mm);
+    bounds.height = xkb_to_pixmap_coord(layout, xkbgeometry->height_mm);
     eek_keyboard_set_bounds (keyboard, &bounds);
 
     for (i = 0; i < xkbgeometry->num_sections; i++) {