doc/examples.dox

   1 /**
   2  * @page Examples Examples
   3  *
   4  * Here is a page with examples.
   5  *
   6  * @ref Example_Evas_Buffer_Simple
   7  *
   8  * @ref Example_Evas_Init_Shutdown
   9  *
  10  * @ref Example_Evas_Load_Error_Str
  11  *
  12  * @ref Example_Evas_Events
  13  *
  14  * @ref Example_Evas_Object_Manipulation
  15  *
  16  * @ref Example_Evas_Aspect_Hints
  17  *
  18  * @ref Example_Evas_Size_Hints
  19  *
  20  * @ref Example_Evas_Stacking
  21  */
  22
  23 /**
  24  * @page Example_Evas_Buffer_Simple Simple Evas canvas example
  25  *
  26  * The canvas will here use the buffer engine.
  27  *
  28  * @include evas-buffer-simple.c
  29  * @example evas-buffer-simple.c
  30  */
  31
  32 /**
  33  * @page Example_Evas_Init_Shutdown Evas' init/shutdown routines example
  34  *
  35  * @include evas-init-shutdown.c
  36  * @example evas-init-shutdown.c
  37  */
  38
  39 /**
  40  * @page Example_Evas_Load_Error_Str Some image object functions and evas_load_error_str() example
  41  * @dontinclude evas-load-error-str.c
  42  *
  43  * In this example, we add two images to a canvas, each one having a
  44  * quarter of the canvas' size, positioned on the top left and bottom
  45  * right corners, respectively:
  46  * @skip img1 = evas_object_image_add(evas);
  47  * @until ecore_main_loop_begin
  48  * See there is a border image around the top left one, <b>which is
  49  * the one that should be displayed</b>. The other one will (on
  50  * purpose) fail to load, because we set a wrong file path as image
  51  * source on it:
  52  * @dontinclude evas-load-error-str.c
  53  * @skip valid_path
  54  * @until bogus_path
  55  * This is how one is supposed to test for success when binding source
  56  * images to image objects: evas_object_image_load_error_get(),
  57  * followed by evas_load_error_str(), if one wants to pretty print/log
  58  * the error.
  59  *
  60  * To interact with the program, there's a command line interface,
  61  * whose help string can be asked for with the 'h' key:
  62  * @dontinclude evas-events.c
  63  * @skip if (strcmp(ev->keyname, "h") == 0)
  64  * @until }
  65  * The first four commands will change the top left images's @b fill property
  66  * values, which dictate how the source image (Enlightenment's logo)
  67  * is to be displayed through the image object's area. Experiment with
  68  * those switches until you get the idea of evas_object_fill_set().
  69  *
  70  * The 'f' command will toggle that image's "filled" property, which
  71  * is wheter it should track its size and set the fill one to fit the
  72  * object's boundaries perfectly (stretching). Note that this command
  73  * and the four above it will conflict: in real usage one would use
  74  * one or other ways of setting an image object's viewport with regard
  75  * to its image source.
  76  *
  77  * The full example follows.
  78  *
  79  * @include evas-load-error-str.c
  80  * @example evas-load-error-str.c
  81  */
  82
  83 /**
  84  * @page Example_Evas_Events Evas events (canvas and object ones) and some canvas operations example
  85  * @dontinclude evas-events.c
  86  *
  87  * In this example we illustrate how to interact with canvas' (and
  88  * its objects') events and other canvas operations.
  89  *
  90  * After we grab our canvas pointer, we registrate two event callbacks on it:
  91  * @skip evas_event_callback_add(d.canvas, EVAS_CALLBACK_RENDER_FLUSH_PRE,
  92  * @until two canvas event callbacks
  93  * The first of them, whose code is
  94  * @dontinclude evas-events.c
  95  * @skip render flush callback
  96  * @until }
  97  * will be called whenever our canvas has to flush its rendering pipeline.
  98  * In this example, two ways of observing that message which is printed in
  99  * the cited callback are:
 100  * - to resize the example's window (thus resizing the canvas' viewport)
 101  * - let the animation run
 102  *
 103  * When one resizes the canvas, there's at least one operation it has
 104  * to do which will require new calculation for rendering: the
 105  * resizing of the background rectangle:
 106  * @dontinclude evas-events.c
 107  * @skip here just to keep
 108  * @until }
 109  * The animation we talked about comes from a timer we register just before
 110  * we start the example's main loop:
 111  * @dontinclude evas-events.c
 112  * @skip d.resize_timer = ecore
 113  * @until d.resize_timer = ecore
 114  * being the timer's callback what follows:
 115  * @dontinclude evas-events.c
 116  * @skip put some action
 117  * @until }
 118  * As you see, the resizing of the image will also force the canvas to
 119  * repaint itself, thus flushing the rendering pipeline whenever the
 120  * timer ticks. When you start this example, this animation will be
 121  * running, by default. To interact with the program, there's a
 122  * command line interface, whose help string can be asked for with the
 123  * 'h' key:
 124  * @dontinclude evas-events.c
 125  * @skip if (strcmp(ev->keyname, "h") == 0)
 126  * @until }
 127  * These are the commands the example will accept at any time, except
 128  * when one triggers the 'f' one:
 129  * @skip if (strcmp(ev->keyname, "f") == 0)
 130  * @until }
 131  * This command will exemplify evas_event_freeze(), which interrupts
 132  * @b all input events processing for the canvas (in the example, just
 133  * for 3 seconds). Try to issue events for it during that freeze time.
 134  * The 'd' command will unregister those two canvas callbacks for you,
 135  * so you won't see the messages about the focused object and the
 136  * rendering process anymore:
 137  * @dontinclude evas-events.c
 138  * @skip if (strcmp(ev->keyname, "d") == 0)
 139  * @until }
 140  * The second of those callbacks has the following code:
 141  * @dontinclude evas-events.c
 142  * @skip called when our rectangle gets focus
 143  * @until }
 144  * It will take place whenever an object in the canvas receives
 145  * focus. In this example, we use the focus to handle the input
 146  * events:
 147  * @skip so we get input events
 148  * @until }
 149  * The background rectangle is the chosen object to receive the
 150  * focus. This also illustrates the use of
 151  * evas_object_event_callback_add(), which registers an event callback
 152  * on an Evas @b object (in this case, the event of a key being
 153  * pressed down). On this callback, we examine each key pressed and,
 154  * if they match one between the expected, we take some actions:
 155  * @dontinclude evas-events.c
 156  * @skip examine the keys pressed
 157  * @until key grab
 158  * We do so by examining the @c ev->keyname string (remember the event
 159  * information struct for key down events is the #Evas_Event_Key_Down
 160  * one).  There's one more trick for grabbing input events on this
 161  * example -- evas_object_key_grab(). The 'c' command will, when
 162  * firstly used, @b unfocus the background rectangle. Unfocused
 163  * objects on an Evas canvas will @b never receive key events. We
 164  * grab, then, the keys we're interested at, to the object forcefully:
 165  * @skip if (d.focus)
 166  * @until got here by key grabs
 167  * This shows how one can handle input not depending on focus issues
 168  * -- you can grab them globally. Switch back and forth focus and
 169  * forced key grabbing with the 'c' key, and observe the messages
 170  * printed about the focused object.  Observe, also, that we register
 171  * two more @b object callbacks, this time on the image object
 172  * (Enlightenment logo):
 173  * @skip evas_object_show(d.img);
 174  * @until mouse_out, NULL
 175  * whose code blocks are
 176  * @dontinclude evas-events.c
 177  * @skip mouse enters the object's area
 178  * @until mouse exits the object's area
 179  * Experiment with moving the mouse pointer over the image, letting it
 180  * enter and exit its area (stop the animation with 'a', for a better
 181  * experience). When you start the example, Evas will consider this
 182  * area by being the whole boundary rectangle around the picture. If
 183  * you issue the 'p' command, though, you get a demonstration of Evas'
 184  * precise point collision detection on objects:
 185  * @dontinclude evas-events.c
 186  * @skip if (strcmp(ev->keyname, "p") == 0)
 187  * @until }
 188  * With evas_object_precise_is_inside_get(), one can make Evas
 189  * consider the transparent areas of an object (the middle of the
 190  * logo's E letter, in the case) as not belonging to it when
 191  * calculating mouse in/out/up/down events. To finish the example, try
 192  * the command bound to Cotrol + 'o':
 193  * @skip mods = evas_key_modifier_get(evas);
 194  * @until end of obscured region command
 195  * It exemplifies Evas' <b>obscured regions</b>. When firstly pressed,
 196  * you'll get the same contents, in a region in the middle of the
 197  * canvas, at the time the key was pressed, until you toggle the
 198  * effect off again (make sure the animation is running on to get the
 199  * idea better). When you toggle this effect off, we also demonstrate
 200  * the use of evas_render_updates(), which will force immediate
 201  * updates on the canvas rendering, bringing back the obscured
 202  * region's contents to normal.
 203  *
 204  * What follows is the complete code for this example.
 205  *
 206  * @include evas-events.c
 207  * @example evas-events.c
 208  */
 209
 210 /**
 211  * @page Example_Evas_Object_Manipulation Evas objects basic manipulation example
 212  *
 213  * @include evas-object-manipulation.c
 214  * @example evas-object-manipulation.c
 215  */
 216
 217 /**
 218  * @page Example_Evas_Aspect_Hints Evas aspect hints example
 219  *
 220  * @include evas-aspect-hints.c
 221  * @example evas-aspect-hints.c
 222  */
 223
 224 /**
 225  * @page Example_Evas_Size_Hints Evas alignment, minimum size, maximum size, padding and weight hints example
 226  *
 227  * @include evas-hints.c
 228  * @example evas-hints.c
 229  */
 230
 231 /**
 232  * @page Example_Evas_Stacking Evas object stacking functions (and some event handling)
 233  * @dontinclude evas-stacking.c
 234  *
 235  * In this example, we illustrate how to stack objects in a custom
 236  * manner and how to deal with layers.
 237  *
 238  * We have three objects of interest in it -- white background, red
 239  * rectangle, green rectangle and blue rectangle.
 240  * @skip d.bg = evas_object_rectangle_add(d.canvas);
 241  * @until evas_object_resize(d.bg, WIDTH, HEIGHT);
 242  * @skip d.rects[2] = evas_object_rectangle_add(d.canvas);
 243  * @until evas_object_show(d.rects[0]);
 244  * @dontinclude evas-stacking.c
 245  * Like in other Evas examples, one interacts with it be means of key commands:
 246  * @skip "commands are:\n"
 247  * @until "\th - print help\n");
 248  * At any given point, like seem above, you'll be operating one rectangle only.
 249  * Try stacking it below an adjacent object with "b":
 250  * @skip evas_object_stack_below(d.rects[d.cur_rect], neighbour);
 251  * @until evas_object_stack_below(d.rects[d.cur_rect], neighbour);
 252  * @dontinclude evas-stacking.c
 253  * "a" will do the opposite:
 254  * @skip evas_object_stack_above(d.rects[d.cur_rect], neighbour);
 255  * @until evas_object_stack_above(d.rects[d.cur_rect], neighbour);
 256  * To bring it directly to the top/bottom, use "t"/"m", respectively:
 257  * @dontinclude evas-stacking.c
 258  * @skip evas_object_raise(d.rects[d.cur_rect]);
 259  * @until evas_object_raise(d.rects[d.cur_rect]);
 260  * @skip evas_object_lower(d.rects[d.cur_rect]);
 261  * @until evas_object_lower(d.rects[d.cur_rect]);
 262  * At any time, use the "s" command to see the status of the
 263  * ordering. It will show the background's ordering too. Note that it
 264  * also shows the @b layer for this object. It starts at a @b
 265  * different layer than the others. Use "l" to change its layer
 266  * (higher layer numbers mean higher layers). If the background is on
 267  * the same layer as the others (0), you'll see it interact with them
 268  * on the ordering. If it's in the layer above, no matter what you do,
 269  * you'll see nothing but the white rectangle: it covers the other
 270  * layers. For the initial layer (-1), it will never mess nor occlude
 271  * the others.
 272  *
 273  * The last two commands available are "p" and "r", which will make
 274  * the target rectangle to @b pass (ignore) and @b repeat the mouse
 275  * events occurring on it (the commands will cycle through on and off
 276  * states). This is demonstrated with the following
 277  * #EVAS_CALLBACK_MOUSE_DOWN callback, registered on each of the
 278  * colored rectangles:
 279  * @dontinclude evas-stacking.c
 280  * @skip static void
 281  * @until }
 282  * Try to change these properties on the three rectangles while
 283  * experimenting with mouse clicks on their intersection region.
 284  *
 285  * The full example follows.
 286  *
 287  * @include evas-stacking.c
 288  * @example evas-stacking.c
 289  */