[evas] More diagrams on docs.

SVN revision: 61374

legacy/evas/doc/examples.dox

@@ -326,10 +326,10 @@
  * @until evas_object_show(d.rects[0]);
  * @dontinclude evas-stacking.c
  * Like in other Evas examples, one interacts with it be means of key commands:
- * @skip "commands are:\n"
- * @until "\th - print help\n");
+ * @skip static const char *commands
+ * @until ;
  * At any given point, like seem above, you'll be operating one rectangle only.
- * Try stacking it below an adjacent object with "b":
+ * You may stacking it below an adjacent object with "b":
  * @skip evas_object_stack_below(d.rects[d.cur_rect], neighbour);
  * @until evas_object_stack_below(d.rects[d.cur_rect], neighbour);
  * @dontinclude evas-stacking.c
@@ -353,6 +353,54 @@
  * layers. For the initial layer (-1), it will never mess nor occlude
  * the others.
  *
+ * Let's make some tests with those commands. The rectangle which starts
+ * selected and which will receive our commands is the @b red one. It
+ * starts stacked above all the others, like seem above:
+ * @image html evas-stacking-example-00.png
+ * @image rtf evas-stacking-example-00.png
+ * @image latex evas-stacking-example-00.eps
+ *
+ * Stack it one level below, with 'b', and you'll get:
+ * @image html evas-stacking-example-01.png
+ * @image rtf evas-stacking-example-01.png
+ * @image latex evas-stacking-example-01.eps
+ * Note how the rectangle which laid above it, the green one, is now
+ * on top of it. Now change the rectangle to operate on to the blue
+ * one, with two consecutive 'c' commands. Note that it's the lowest
+ * one on the stack of rectangles. Issue the 'a' command for it, thus
+ * re-stacking it one level above:
+ * @image html evas-stacking-example-02.png
+ * @image rtf evas-stacking-example-02.png
+ * @image latex evas-stacking-example-02.eps
+ * You can send it to the top of its layer directly with the 't' command:
+ * @image html evas-stacking-example-03.png
+ * @image rtf evas-stacking-example-03.png
+ * @image latex evas-stacking-example-03.eps
+ * Now put it back to the bottom of that layer with 'm':
+ * @image html evas-stacking-example-04.png
+ * @image rtf evas-stacking-example-04.png
+ * @image latex evas-stacking-example-04.eps
+ * Like said above, we have two layers used at the beginning of the
+ * example: the default one (0) and the one imeddiately below it (-1),
+ * for the white background. Let's change this setup by issuing the
+ * 'l' command, which will change the background's layer to 1, i.e., a
+ * layer @b above the one holding the other rectangles:
+ * @image html evas-stacking-example-05.png
+ * @image rtf evas-stacking-example-05.png
+ * @image latex evas-stacking-example-05.eps
+ * See how it now covers everything else. Press 'l' again, taking it
+ * now to layer 0. It's still covering everything because it lands the
+ * layer as the highest one on the objects stack. As we have the blue
+ * rectangle as the one receiving stacking commands, hit 't' and
+ * you'll see it again:
+ * @image html evas-stacking-example-06.png
+ * @image rtf evas-stacking-example-06.png
+ * @image latex evas-stacking-example-06.eps
+ * By bringing the background back to layer -1 ('l'), you'll get:
+ * @image html evas-stacking-example-07.png
+ * @image rtf evas-stacking-example-07.png
+ * @image latex evas-stacking-example-07.eps
+ *
  * The last two commands available are "p" and "r", which will make
  * the target rectangle to @b pass (ignore) and @b repeat the mouse
  * events occurring on it (the commands will cycle through on and off

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

@@ -41,6 +41,19 @@ struct test_data
 
 static struct test_data d = {0};
 
+static const char *commands = \
+  "commands are:\n"
+  "\tc - change the target rectangle to operate on\n"
+  "\ta - stack target rectangle one level above\n"
+  "\tb - stack target rectangle one level below\n"
+  "\tt - stack target rectangle up to the top of its layer\n"
+  "\tm - stack target rectangle down to the bottom of its layer\n"
+  "\tp - toggle target rectangle's 'pass events' property\n"
+  "\tr - toggle target rectangle's 'repeat events' property\n"
+  "\ts - print current stacking information\n"
+  "\tl - change background rectangle's layer\n"
+  "\th - print help\n";
+
 static void
 _on_mouse_down(void        *data __UNUSED__,
                Evas        *evas __UNUSED__,
@@ -74,18 +87,7 @@ _on_keydown(void        *data __UNUSED__,
 
    if (strcmp(ev->keyname, "h") == 0)  /* print help */
      {
-        fprintf(stdout,
-                "commands are:\n"
-                "\tc - change the target rectangle to operate on\n"
-                "\ta - stack target rectangle one level above\n"
-                "\tb - stack target rectangle one level below\n"
-                "\tt - stack target rectangle up to the top of its layer\n"
-                "\tm - stack target rectangle down to the bottom of its layer\n"
-                "\tp - toggle target rectangle's 'pass events' property\n"
-                "\tr - toggle target rectangle's 'repeat events' property\n"
-                "\ts - print current stacking information\n"
-                "\tl - change background rectangle's layer\n"
-                "\th - print help\n");
+        fprintf(stdout, commands);
         return;
      }
 
@@ -314,6 +316,7 @@ main(void)
    evas_object_event_callback_add(
      d.rects[0], EVAS_CALLBACK_MOUSE_DOWN, _on_mouse_down, NULL);
 
+   fprintf(stdout, commands);
    ecore_main_loop_begin();
 
    ecore_evas_shutdown();

legacy/evas/src/lib/Evas.h

@@ -2764,6 +2764,11 @@ EAPI const Eina_List  *evas_font_path_list               (const Evas *e) EINA_WA
  * called, it gets implicitly removed from the old clipper's domain
  * and is made now to be clipped by its new clipper.
  *
+ * The following figure illustrates some clipping in Evas:
+ * @image html clipping.png
+ * @image rtf clipping.png
+ * @image latex clipping.eps
+ *
  * @note At the moment the <b>only objects that can validly be used to
  * clip other objects are rectangle objects</b>. All other object
  * types are invalid and the result of using them is undefined. The
@@ -3457,6 +3462,18 @@ EAPI Evas_Object      *evas_object_below_get             (const Evas_Object *obj
  * Objects also generate events on input (keyboard and mouse), if they
  * accept them (are visible, focused, etc).
  *
+ * For each of those events, Evas provides a way for one to register
+ * callback functions to be issued just after they happen.
+ *
+ * The following figure illustrates some Evas (event) callbacks:
+ * @image html evas-callbacks.png
+ * @image rtf evas-callbacks.png
+ * @image latex evas-callbacks.eps
+ *
+ * Thees events have their values in the #Evas_Callback_Type
+ * enumeration, which has also ones happening on the canvas level (se
+ * #Evas_Canvas_Events).
+ *
  * Examples on this group of functions can be found @ref
  * Example_Evas_Stacking "here" and @ref Example_Evas_Events "here".
  *
@@ -4719,11 +4736,22 @@ EAPI void              evas_object_size_hint_weight_get  (const Evas_Object *obj
  * Sets the hints for an object's weight.
  *
  * @param obj The given Evas object to query hints from.
- * @param x Double (@c 0.0-1.0) to use as horizontal weight hint.
- * @param y Double (@c 0.0-1.0) to use as vertical weight hint.
+ * @param x Nonnegative double value to use as horizontal weight hint.
+ * @param y Nonnegative double value to use as vertical weight hint.
  *
- * This is not a size enforcement in any way, it's just a hint that should
- * be used whenever appropriate.
+ * This is not a size enforcement in any way, it's just a hint that
+ * should be used whenever appropriate.
+ *
+ * This is a hint on how a container object should @b resize a given
+ * child within its area. Containers may adhere to the simpler logic
+ * of just expanding the child object's dimensions to fit its own (see
+ * the #EVAS_HINT_EXPAND helper weight macro) or the complete one of
+ * taking each child's weight hint as real @b weights to how much of
+ * its size to allocate for them in each axis. A container is supposed
+ * to, after @b normalizing the weights of its children (with weight
+ * hints), distribute the space it has to layout them by those factors
+ * -- most weighted children get larger in this process than the least
+ * ones.
  *
  * Example:
  * @dontinclude evas-hints.c