[evas] More love to a given example's text.

SVN revision: 61536

legacy/evas/doc/examples.dox

@@ -169,74 +169,114 @@
  * @page Example_Evas_Events Evas events (canvas and object ones) and some canvas operations example
  * @dontinclude evas-events.c
  *
- * In this example we illustrate how to interact with canvas' (and
+ * In this example we illustrate how to interact with canvas' (and its
- * its objects') events and other canvas operations.
+ * objects') events, including the key input ones. We also demonstrate
+ * precise point collision on objects and canvas "obscured regions",
+ * here.
  *
- * After we grab our canvas pointer, we registrate two event callbacks on it:
+ * The example application consists of a window with a white
+ * background and an image -- the Enlightenment logo. The application
+ * begins with this image switching back and forth into two sizes: the
+ * exact canvas' size and one quarter of it (when it's placed on the
+ * top left quadrant). Thus, we'll have an @b animation going on,
+ * with image states set to change each 2 elapsed seconds.
+ *
+ * There's a global variable to aid accessing our desired context
+ * variables from anywhere in the code:
+ * @dontinclude evas-events.c
+ * @skip test_data
+ * @until {0}
+ *
+ * What interests us there are the @c canvas pointer, our image handle
+ * -- @c img -- and the background one, @c bg.
+ *
+ * The first interesting thing on the example is the registration of a
+ * callback on each canvas resizing event, where we put our canvas'
+ * size and the background rectangle's one in synchrony, so that we
+ * don't get bogus content on rendering with canvas resizes:
+ * @dontinclude evas-events.c
+ * @skip resize_set
+ * @until resize_set
+ * @dontinclude evas-events.c
+ * @skip here to keep
+ * @until }
+ *
+ * Than, after grabbing our canvas pointer from the Ecore Evas helper
+ * infrastructure, we registrate an event callbacks on it:
  * @skip evas_event_callback_add(d.canvas, EVAS_CALLBACK_RENDER_FLUSH_PRE,
  * @until two canvas event callbacks
- * The first of them, which has the following code,
  * @dontinclude evas-events.c
  * @skip render flush callback
  * @until }
- * will be called whenever our canvas has to flush its rendering pipeline.
+ * It will be called whenever our canvas has to flush its rendering
- * In this example, two ways of observing that message which is printed in
+ * pipeline. In this example, two ways of observing that message
- * the cited callback are:
+ * which is printed in the cited callback are:
  * - to resize the example's window (thus resizing the canvas' viewport)
  * - let the animation run
  *
  * When one resizes the canvas, there's at least one operation it has
  * to do which will require new calculation for rendering: the
- * resizing of the background rectangle:
+ * resizing of the background rectangle, in a callback we already
+ * shown you.
+ *
+ * The creation of our background rectangle is so that we give it a @b name,
+ * via evas_object_name_set() and we give it the canvas @b focus:
  * @dontinclude evas-events.c
- * @skip here just to keep
+ * @skip bg = evas_object_rectangle_add
+ * @until focus_set
+ *
+ * Still exempliflying events and callbacks, we register a callback on
+ * the canvas event of an object being focused:
+ * @dontinclude evas-events.c
+ * @skip add(d.canvas, EVAS_CALLBACK_CANVAS_OBJECT_FOCUS
  * @until }
- * The animation we talked about comes from a timer we register just before
+ * @dontinclude evas-events.c
- * we start the example's main loop:
+ * @skip called when
+ * @until }
+ *
+ * In that call, @c event_info is going to be the focused object's
+ * handle, in this case our background rectangle. We print its name,
+ * so you can check it's the same. We check that pointer is the same
+ * reported by Evas' API with regard to the newest focused
+ * object. Finally, we check whether that object is really flagged as
+ * focused, now using an Evas object API function.
+ *
+ * The animation we talked about comes from a timer we register just
+ * before we start the example's main loop. As we said, the resizing
+ * of the image will also force the canvas to repaint itself, thus
+ * flushing the rendering pipeline whenever the timer ticks:
  * @dontinclude evas-events.c
  * @skip d.resize_timer = ecore
  * @until d.resize_timer = ecore
- * being the timer's callback what follows:
  * @dontinclude evas-events.c
  * @skip put some action
  * @until }
- * As you see, the resizing of the image will also force the canvas to
+ * When you start this example, this animation will be
- * repaint itself, thus flushing the rendering pipeline whenever the
- * timer ticks. When you start this example, this animation will be
  * running, by default. To interact with the program, there's a
  * command line interface. A help string can be asked for with the
  * 'h' key:
  * @dontinclude evas-events.c
- * @skip if (strcmp(ev->keyname, "h") == 0)
+ * @skip static const char *commands
- * @until }
+ * @until ;
  * These are the commands the example will accept at any time, except
- * when one triggers the 'f' one:
+ * when one triggers the 'f' one. This command will exemplify
+ * evas_event_freeze(), which interrupts @b all input events
+ * processing for the canvas (in the example, just for 3 seconds). Try
+ * to issue events for it during that freeze time:
+ * @dontinclude evas-events.c
  * @skip if (strcmp(ev->keyname, "f") == 0)
  * @until }
- * This command will exemplify evas_event_freeze(), which interrupts
- * @b all input events processing for the canvas (in the example, just
- * for 3 seconds). Try to issue events for it during that freeze time.
  * The 'd' command will unregister those two canvas callbacks for you,
  * so you won't see the messages about the focused object and the
  * rendering process anymore:
  * @dontinclude evas-events.c
  * @skip if (strcmp(ev->keyname, "d") == 0)
  * @until }
- * The second of those callbacks has the following code:
+ * In this example, we start using a focused object to handle the input
- * @dontinclude evas-events.c
+ * events -- the background rectangle. We register a callback on an key input
- * @skip called when our rectangle gets focus
+ * event occurring on it, so that we can act on each key stroke:
+ * @skip object_event_callback_add
  * @until }
- * It will take place whenever an object in the canvas receives
- * focus. In this example, we use the focus to handle the input
- * events:
- * @skip so we get input events
- * @until }
- * The background rectangle is the chosen object to receive the
- * focus. This also illustrates the use of
- * evas_object_event_callback_add(), which registers an event callback
- * on an Evas @b object (in this case, the event of a key being
- * pressed down). On this callback, we examine each key pressed and,
- * if they match one between the expected, we take some actions:
  * @dontinclude evas-events.c
  * @skip examine the keys pressed
  * @until key grab
@@ -246,7 +286,7 @@
  * example -- evas_object_key_grab(). The 'c' command will, when
  * firstly used, @b unfocus the background rectangle. Unfocused
  * objects on an Evas canvas will @b never receive key events. We
- * grab, then, the keys we're interested at, to the object forcefully:
+ * grab, then, the keys we're interested at to the object forcefully:
  * @skip if (d.focus)
  * @until got here by key grabs
  * This shows how one can handle input not depending on focus issues
@@ -254,10 +294,10 @@
  * forced key grabbing with the 'c' key, and observe the messages
  * printed about the focused object. Observe, also, that we register
  * two more @b object callbacks, this time on the image object
- * (Enlightenment logo):
+ * (Enlightenment logo), where we just print messages telling the mouse
+ * pointer has entered or exited it area:
  * @skip evas_object_show(d.img);
  * @until mouse_out, NULL
- * The code code blocks for those callbacks are
  * @dontinclude evas-events.c
  * @skip mouse enters the object's area
  * @until mouse exits the object's area
@@ -266,25 +306,25 @@
  * experience). When you start the example, Evas will consider this
  * area by being the whole boundary rectangle around the picture. If
  * you issue the 'p' command, though, you get a demonstration of Evas'
- * precise point collision detection on objects:
+ * precise point collision detection on objects. With
+ * evas_object_precise_is_inside_get(), one can make Evas consider the
+ * transparent areas of an object (the middle of the logo's E letter,
+ * in the case) as not belonging to it when calculating mouse
+ * in/out/up/down events:
  * @dontinclude evas-events.c
  * @skip if (strcmp(ev->keyname, "p") == 0)
  * @until }
- * With evas_object_precise_is_inside_get(), one can make Evas
+ * To finish the example, try the command bound to Control + 'o',
- * consider the transparent areas of an object (the middle of the
+ * which exemplifies Evas' <b>obscured regions</b>. When firstly
- * logo's E letter, in the case) as not belonging to it when
+ * pressed, you'll get the same contents, in a region in the middle of
- * calculating mouse in/out/up/down events. To finish the example, try
+ * the canvas, at the time the key was pressed, until you toggle the
- * the command bound to Cotrol + 'o':
- * @skip mods = evas_key_modifier_get(evas);
- * @until end of obscured region command
- * It exemplifies Evas' <b>obscured regions</b>. When firstly pressed,
- * you'll get the same contents, in a region in the middle of the
- * canvas, at the time the key was pressed, until you toggle the
  * effect off again (make sure the animation is running on to get the
  * idea better). When you toggle this effect off, we also demonstrate
  * the use of evas_render_updates(), which will force immediate
  * updates on the canvas rendering, bringing back the obscured
  * region's contents to normal.
+ * @skip mods = evas_key_modifier_get(evas);
+ * @until end of obscured region command
  *
  * What follows is the complete code for this example.
  *

legacy/evas/src/examples/evas-events.c

@@ -31,6 +31,16 @@
 
 static const char *img_path = PACKAGE_EXAMPLES_DIR "/enlightenment.png";
 
+static const char *commands = \
+  "commands are:\n"
+  "\ta - toggle animation timer\n"
+  "\tc - cycle between focus and key grabs for key input\n"
+  "\td - delete canvas callbacks\n"
+  "\tf - freeze input for 3 seconds\n"
+  "\tp - toggle precise point collision detection on image\n"
+  "\tControl + o - add an obscured rectangle\n"
+  "\th - print help\n";
+
 struct test_data
 {
    Ecore_Evas  *ee;
@@ -42,7 +52,7 @@ struct test_data
 
 static struct test_data d = {0};
 
-/* here just to keep our example's window size and background image's
+/* here to keep our example's window size and background image's
  * size in synchrony */
 static void
 _canvas_resize_cb(Ecore_Evas *ee)
@@ -69,7 +79,8 @@ _object_focus_in_cb(void *data __UNUSED__,
            "OK!" : "Oops, something is bad.");
 }
 
-static void /* render flush callback */
+/* render flush callback */
+static void
 _render_flush_cb(void *data __UNUSED__,
                  Evas *e __UNUSED__,
                  void *event_info __UNUSED__)
@@ -94,8 +105,8 @@ _resize_cb(void *data __UNUSED__)
    return EINA_TRUE; /* re-issue the timer */
 }
 
-static Eina_Bool
 /* let's have our events back */
+static Eina_Bool
 _thaw_cb(void *data __UNUSED__)
 {
    fprintf(stdout, "Canvas was frozen %d times, now thawing.\n",
@@ -104,7 +115,8 @@ _thaw_cb(void *data __UNUSED__)
    return EINA_FALSE; /* do not re-issue the timer */
 }
 
-static void /* mouse enters the object's area */
+/* mouse enters the object's area */
+static void
 _on_mouse_in(void        *data __UNUSED__,
              Evas        *evas __UNUSED__,
              Evas_Object *o __UNUSED__,
@@ -138,15 +150,7 @@ _on_keydown(void        *data __UNUSED__,
 
    if (strcmp(ev->keyname, "h") == 0) /* print help */
      {
-        fprintf(stdout,
+        fprintf(stdout, commands);
-                "commands are:\n"
-                "\ta - toggle animation timer\n"
-                "\tc - cycle between focus and key grabs for key input\n"
-                "\td - delete canvas callbacks\n"
-                "\tf - freeze input for 3 seconds\n"
-                "\tp - toggle precise point collision detection on image\n"
-                "\tControl + o - add an obscured rectangle\n\n"
-                "\th - print help\n");
         return;
      }
 
@@ -393,6 +397,7 @@ main(void)
 
    d.resize_timer = ecore_timer_add(2, _resize_cb, NULL);
 
+   fprintf(stdout, commands);
    ecore_main_loop_begin();
 
    ecore_evas_free(d.ee);