examples: Move introduction to Ecore-Evas to evas-transparent.c

Summary:
The evas-transparent.c example is quite short, and so will allow for
more detailed explanation of setting up Ecore-Evas.  Then
evas-object-manipulation.c can focus more on the explanation of objects
in Ecore-Evas.

Reviewers: cedric

Subscribers: jpeg

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

3 files changed, 80 insertions, 29 deletions

diff --git a/src/examples/evas/README b/src/examples/evas/README
index 8bd00468ae..e32ad1ecd3 100644
--- a/src/examples/evas/README
+++ b/src/examples/evas/README
@@ -10,9 +10,9 @@ points to start from in learning more advanced topics.
 == Basic Evas ==
 
 evas-init-shutdown.c            - Introduction to Evas
-evas-buffer-simple.c            - Using the buffer engine
+evas-buffer-simple.c            - Using the Evas buffer engine
+evas-transparent.c              - Introduction to Ecore-Evas
 evas-object-manipulation.c      - Introduction to object manipulation
-evas-transparent.c              - Setting alpha transparency on objects
 
 
 == Event Handling ==
diff --git a/src/examples/evas/evas-object-manipulation.c b/src/examples/evas/evas-object-manipulation.c
index c1735ba941..e5be8c0aaf 100644
--- a/src/examples/evas/evas-object-manipulation.c
+++ b/src/examples/evas/evas-object-manipulation.c
@@ -1,11 +1,8 @@
 /**
  * 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.
+ * This example shows how to manipulate objects within an Ecore-Evas
+ * canvas.
  *
  * Please note that this example uses Evas' legacy API.  Compare this
  * implementation with evas-object-manipulation-eo.c to learn how the
@@ -28,6 +25,7 @@
 
 #include <Ecore.h>
 #include <Ecore_Evas.h>
+
 #include <stdio.h>
 #include <errno.h>
 #include "evas-common.h"
@@ -167,32 +165,16 @@ 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;
 
-   /* 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);
 
-   /* Retrieve a pointer to the canvas we created. */
    d.canvas = ecore_evas_get(d.ee);
 
    /* Create background.  As mentioned earlier, the evas_object_*
@@ -206,10 +188,6 @@ 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);
diff --git a/src/examples/evas/evas-transparent.c b/src/examples/evas/evas-transparent.c
index 4ea74866cf..1d4d67d210 100644
--- a/src/examples/evas/evas-transparent.c
+++ b/src/examples/evas/evas-transparent.c
@@ -1,5 +1,23 @@
 /**
- * Example of transparent windows in Evas.
+ * Example of basic usage of Ecore-Evas and transparent windows.
+ *
+ * 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 a simple Evas canvas.
+ *
+ * This example also demonstrates how to create transparent windows with
+ * Evas.  Like in most other graphics software, transparency and
+ * translucency is calculated using an integer parameter called an
+ * 'alpha channel'.  Support for alpha transparency is platform
+ * dependent, and even where it is supported it may not be needed,
+ * so Ecore-Evas provides a simple API to turn it on and off, which
+ * this example will demonstrate by allowing it to be toggled via
+ * the 'n' and 'm' keys on the keyboard.
+ *
+ * The keyboard input will introduce 'event handling' in Ecore-Evas, but
+ * only briefly - we'll be exploring event handling in later examples
+ * more deeply.
  *
  * @verbatim
  * gcc -o evas-transparent evas-transparent.c `pkg-config --libs --cflags evas ecore ecore-evas eina`
@@ -37,6 +55,9 @@ struct exemple_data
 
 static struct exemple_data d;
 
+/* Keyboard event callback routine, to enable toggling transparency on
+ * and off.
+ */
 static void
 _on_keydown(void        *data EINA_UNUSED,
             Evas        *evas EINA_UNUSED,
@@ -45,14 +66,16 @@ _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("%s",  commands);
         return;
      }
 
    if (strcmp(ev->key, "n") == 0)
      {
+        /* n - turn alpha transparency on */
         ecore_evas_alpha_set(d.ee, EINA_TRUE);
 
         printf("turn on alpha\n");
@@ -61,6 +84,7 @@ _on_keydown(void        *data EINA_UNUSED,
 
    if (strcmp(ev->key, "m") == 0)
      {
+        /* m - turn alpha transparency off */
         ecore_evas_alpha_set(d.ee, EINA_FALSE);
 
         printf("turn off alpha\n");
@@ -71,32 +95,81 @@ _on_keydown(void        *data EINA_UNUSED,
 static void
 _on_delete(Ecore_Evas *ee EINA_UNUSED)
 {
+   /* Communicate to ecore that the application is finished.  Calling
+    * this routine allows any pending events to get processed and allow
+    * the main loop to finish the current iteration.
+    */
    ecore_main_loop_quit();
 }
 
 int
 main(void)
 {
+   /* 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;
 
+   /* 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.
+    *
+    * The next arguments set the canvas's position to 0,0 and its
+    * height and width to our desired size.
+    *
+    * The last parameter for ecore_evas_new() allows setting extra
+    * options, but for this example we don't need anything special
+    * so just pass NULL.
+    */
    d.ee = ecore_evas_new(NULL, 0, 0, WIDTH, HEIGHT, NULL);
    if (!d.ee)
      goto panic;
 
+   /* 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.  Here we'll register
+    * a callback to be triggered when the window is closed.
+    */
    ecore_evas_callback_delete_request_set(d.ee, _on_delete);
+
+   /* As in evas-buffer-simple.c, we need to explicitly 'unhide' our
+    * Evas objects.  But here we'll use the Ecore-Evas API to do this,
+    * as it also manages some of the underlying device state.
+    */
    ecore_evas_show(d.ee);
 
+   /* Retrieve a pointer to the canvas we created. */
    d.evas = ecore_evas_get(d.ee);
 
+   /* Add a black background rectangle */
    d.bg = evas_object_rectangle_add(d.evas);
    evas_object_color_set(d.bg, 0, 0, 0, 0);
    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);
+
+   /* Run the application until ecore_main_loop_quit() gets called by
+    * our _on_delete() handler.  While this function is active, it will
+    * repeatedly call ecore_main_loop_iterate() to iterate through
+    * various internal processes, checking for keyboard input, updating
+    * the screen as needed, and so forth.
+    */
    ecore_main_loop_begin();
+
+   /* With the application finished, we now direct the Ecore and Evas
+    * libraries to perform final cleanup and terminate the system.
+    */
    ecore_evas_shutdown();
    return 0;