examples: Flesh out the evas-object-manipulation example

Summary:
This is one of the basic examples that introduces Ecore-Evas, so needs
to be more detailed in commentary than other examples.  It also points
out the use of the legacy API and directs the reader to the Eo example
where appropriate.

Reviewers: cedric

Subscribers: jpeg

Differential Revision: https://phab.enlightenment.org/D5008

1 files changed, 56 insertions, 13 deletions

diff --git a/src/examples/evas/evas-object-manipulation.c b/src/examples/evas/evas-object-manipulation.c
index 3e6728373b..c1735ba941 100644
--- a/src/examples/evas/evas-object-manipulation.c
+++ b/src/examples/evas/evas-object-manipulation.c
@@ -1,6 +1,16 @@
 /**
  * Example of basic object manipulation in Evas.
  *
+ * The evas-buffer-simple.c example shows how to manually create and
+ * manage buffers, but mentioned that real code would use higher level
+ * functionality from Ecore's Ecore-Evas submodule.  This example
+ * shows the use of that submodule to create an Evas canvas and
+ * manipulate the objects within it.
+ *
+ * Please note that this example uses Evas' legacy API.  Compare this
+ * implementation with evas-object-manipulation-eo.c to learn how the
+ * new Eo API is used.
+ *
  * You'll need at least one engine built for it (excluding the buffer
  * one) and the png image loader also built. See stdout/stderr for
  * output.
@@ -47,6 +57,9 @@ _canvas_resize_cb(Ecore_Evas *ee)
    evas_object_resize(d.bg, w, h);
 }
 
+/* Keyboard event callback routine, to enable the user to toggle various
+ * object properties on the clipper object.
+ */
 static void
 _on_keydown(void        *data EINA_UNUSED,
             Evas        *evas EINA_UNUSED,
@@ -55,8 +68,9 @@ _on_keydown(void        *data EINA_UNUSED,
 {
    Evas_Event_Key_Down *ev = einfo;
 
-   if (strcmp(ev->key, "h") == 0) /* print help */
+   if (strcmp(ev->key, "h") == 0)
      {
+        /* h - print help */
         printf("commands are:\n"
                "\to - change clipper's opacity\n"
                "\tr - toggle clipper's color between red and white\n"
@@ -65,8 +79,9 @@ _on_keydown(void        *data EINA_UNUSED,
         return;
      }
 
-   if (strcmp(ev->key, "o") == 0) /* change clipper's opacity */
+   if (strcmp(ev->key, "o") == 0)
      {
+        /* o - Change clipper's opacity */
         int alpha, r, g, b;
 
         evas_object_color_get(d.clipper, &r, &g, &b, &alpha);
@@ -84,9 +99,9 @@ _on_keydown(void        *data EINA_UNUSED,
         return;
      }
 
-   if (strcmp(ev->key, "r") == 0) /* toggle clipper's color
-                                       * between red and white */
+   if (strcmp(ev->key, "r") == 0)
      {
+        /* r - Toggle clipper's color between red and white */
         int alpha, r, g, b;
 
         printf("Changing clipper's color to");
@@ -110,8 +125,9 @@ _on_keydown(void        *data EINA_UNUSED,
         return;
      }
 
-   if (strcmp(ev->key, "c") == 0) /* toggle clipper's clipping function */
+   if (strcmp(ev->key, "c") == 0)
      {
+        /* o - Toggle clipper's clipping function */
         printf("Toggling clipping ");
 
         if (evas_object_clip_get(d.img) == d.clipper)
@@ -127,8 +143,9 @@ _on_keydown(void        *data EINA_UNUSED,
         return;
      }
 
-   if (strcmp(ev->key, "v") == 0) /* toggle clipper's visibility */
+   if (strcmp(ev->key, "v") == 0)
      {
+        /* v - Toggle clipper's visibility */
         printf("Clipper is now ");
 
         if (evas_object_visible_get(d.clipper))
@@ -150,21 +167,38 @@ main(void)
 {
    int err;
 
+   /* In other examples, evas_init() has been used to turn Evas on.  In this
+    * example we're using Ecore-Evas' init routine, which takes care of
+    * bringing up Evas.
+    */
    if (!ecore_evas_init())
      return EXIT_FAILURE;
 
-   /* this will give you a window with an Evas canvas under the first
-    * engine available */
+   /* In the evas-buffer-simple.c example, we coded our own
+    * create_canvas() routine.  Here we make use of Ecore-Evas's
+    * ecore_evas_new() routine to do it.  The first argument of this
+    * function is used to specify the name of an engine we wish to use;
+    * by passing NULL instead, we are requesting a window with an Evas
+    * canvas using the first engine available.
+    */
    d.ee = ecore_evas_new(NULL, 10, 10, WIDTH, HEIGHT, NULL);
    if (!d.ee)
      goto error;
 
+   /* Like other windowing systems, Ecore-Evas provides hooks for a
+    * number of different events.  We can register our own functions to
+    * be called when the events occur in our window.
+    */
    ecore_evas_callback_resize_set(d.ee, _canvas_resize_cb);
    ecore_evas_show(d.ee);
 
-   /* the canvas pointer, de facto */
+   /* Retrieve a pointer to the canvas we created. */
    d.canvas = ecore_evas_get(d.ee);
 
+   /* Create background.  As mentioned earlier, the evas_object_*
+    * routines are part of the legacy Evas API; with the new API
+    * you should use code as shown in evas-object-manipulation-eo.c.
+    */
    d.bg = evas_object_rectangle_add(d.canvas);
    evas_object_name_set(d.bg, "background rectangle");
    evas_object_color_set(d.bg, 255, 255, 255, 255); /* white bg */
@@ -172,10 +206,17 @@ main(void)
    evas_object_resize(d.bg, WIDTH, HEIGHT); /* covers full canvas */
    evas_object_show(d.bg);
 
+   /* Callbacks can also be set on Evas objects.  We'll add a keyboard
+    * handler routine to the background rectangle, for processing user
+    * key hits.
+    */
    evas_object_focus_set(d.bg, EINA_TRUE);
    evas_object_event_callback_add(
      d.bg, EVAS_CALLBACK_KEY_DOWN, _on_keydown, NULL);
 
+   /* Load enlightenment.png as an image object, then make it fill the
+    * whole canvas area.
+    */
    d.img = evas_object_image_filled_add(d.canvas);
    evas_object_image_file_set(d.img, img_path, NULL);
    err = evas_object_image_load_error_get(d.img);
@@ -193,7 +234,9 @@ main(void)
                 evas_object_type_get(d.img));
      }
 
-   /* border on the image's clipper, here just to emphasize its position */
+   /* Add a second image to the canvas - a red square this time.  It
+    * will be given a border to emphasize its position.
+    */
    d.clipper_border = evas_object_image_filled_add(d.canvas);
    evas_object_image_file_set(d.clipper_border, border_img_path, NULL);
    err = evas_object_image_load_error_get(d.clipper_border);
@@ -212,9 +255,9 @@ main(void)
         evas_object_show(d.clipper_border);
      }
 
-   /* solid white clipper (note that it's the default color for a
-    * rectangle) - it won't change clippees' colors, then (multiplying
-    * by 255) */
+   /* Lastly, add a rectangle.  It will be white (the default color for
+    * rectangles) and so won't change the color of anything it clips.
+    */
    d.clipper = evas_object_rectangle_add(d.canvas);
    evas_object_move(d.clipper, WIDTH / 4, HEIGHT / 4);
    evas_object_resize(d.clipper, WIDTH / 2, HEIGHT / 2);