summaryrefslogtreecommitdiff
path: root/doc/evas_examples.dox
diff options
context:
space:
mode:
authorJonas M. Gastal <jgastal@profusion.mobi>2012-12-18 16:13:03 +0000
committerJonas M. Gastal <jgastal@profusion.mobi>2012-12-18 16:13:03 +0000
commit0809af70fb0e762a748b5d72ed353971d88bae9b (patch)
treebaf0f67fb24cc8487fa8e2c3f8a5f69a4ce61b04 /doc/evas_examples.dox
parent6ecaa33f2265b7ba0060ffcdc93e96366a49e886 (diff)
efl: Adding *.dox files from various libs.
SVN revision: 81274
Diffstat (limited to 'doc/evas_examples.dox')
-rw-r--r--doc/evas_examples.dox1073
1 files changed, 1073 insertions, 0 deletions
diff --git a/doc/evas_examples.dox b/doc/evas_examples.dox
new file mode 100644
index 0000000000..65dd513409
--- /dev/null
+++ b/doc/evas_examples.dox
@@ -0,0 +1,1073 @@
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_Text
11 *
12 * @ref Example_Evas_Images
13 *
14 * @ref Example_Evas_Images_2
15 *
16 * @ref Example_Evas_Events
17 *
18 * @ref Example_Evas_Object_Manipulation
19 *
20 * @ref Example_Evas_Aspect_Hints
21 *
22 * @ref Example_Evas_Size_Hints
23 *
24 * @ref Example_Evas_Stacking
25 *
26 * @ref Example_Evas_Smart_Objects
27 *
28 * @ref Example_Evas_Box Evas box
29 */
30
31/**
32 * @page Example_Evas_Buffer_Simple Simple Evas canvas example
33 *
34 * The canvas will here use the buffer engine.
35 *
36 * @include evas-buffer-simple.c
37 * @example evas-buffer-simple.c
38 */
39
40/**
41 * @page Example_Evas_Init_Shutdown Evas' init/shutdown routines example
42 *
43 * @include evas-init-shutdown.c
44 * @example evas-init-shutdown.c
45 */
46
47/**
48 * @page Example_Evas_Images Some image object functions examples
49 * @dontinclude evas-images.c
50 *
51 * In this example, we add two images to a canvas, each one having a
52 * quarter of the canvas' size, positioned on the top left and bottom
53 * right corners, respectively:
54 * @skip img1 = evas_object_image_add(d.evas);
55 * @until ecore_main_loop_begin
56 * See there is a border image around the top left one, <b>which is
57 * the one that should be displayed</b>. The other one will (on
58 * purpose) fail to load, because we set a wrong file path as image
59 * source on it:
60 * @dontinclude evas-images.c
61 * @skip valid_path
62 * @until bogus_path
63 * This is how one is supposed to test for success when binding source
64 * images to image objects: evas_object_image_load_error_get(),
65 * followed by evas_load_error_str(), if one wants to pretty print/log
66 * the error. We'll talk about the border image further.
67 *
68 * To interact with the program, there's a command line interface.
69 * A help string can be asked for with the 'h' key:
70 * @dontinclude evas-images.c
71 * @skip commands
72 * @until ;
73 * The first four commands will change the top left images's @b fill property
74 * values, which dictate how the source image (Enlightenment's logo)
75 * is to be displayed through the image object's area. Experiment with
76 * those switches until you get the idea of evas_object_fill_set().
77 *
78 * The 'f' command will toggle that image's "filled" property, which
79 * is whether it should track its size and set the fill one to fit the
80 * object's boundaries perfectly (stretching). Note that this command
81 * and the four above it will conflict: in real usage one would use
82 * one or other ways of setting an image object's viewport with regard
83 * to its image source.
84 *
85 * There are four commands which deal with the border image. This red
86 * frame is there to illustrate <b>image borders</b>. The image source
87 * for the border is a solid red rectangle, with a transparent @b
88 * rectangular area in its middle. See how we use it to get a 3 pixel
89 * wide frame with <code>evas_object_image_border_set(d.border, 3, 3,
90 * 3, 3)</code>. To finish the effect of showing it as a border, we
91 * issue <code>evas_object_image_border_center_fill_set(d.border,
92 * EVAS_BORDER_FILL_NONE)</code>.
93 *
94 * Use 't' to change the border's thickness. 'b' will change the
95 * border image's center region rendering schema: either a hole (no
96 * rendering), blending (see the original transparent area, in this
97 * case) or solid (the transparent area gets filled). Finally, 'c'
98 * will change the border's scaling factor.
99 *
100 * While you have the border in 'blending mode', test the command 'm':
101 * it will set whether to use or not smooth scaling on the border's
102 * source image. Since the image is small originally (30 x 30), we're
103 * obviously up-scaling it (except the border pixels, do you
104 * remember?). With this last switch, you'll either see the
105 * transparent shape in the middle flat (no smoothing) or blurry
106 * (smoothed).
107 *
108 * The full example follows.
109 *
110 * @include evas-images.c
111 * @example evas-images.c
112 */
113
114/**
115 * @page Example_Evas_Images_2 Some more image object functions examples (2nd block)
116 * @dontinclude evas-images2.c
117 *
118 * In this example, we have three images on the canvas, but one of
119 * them is special -- we're using it as a <b>proxy image
120 * object</b>. It will mirror the contents of the other two images
121 * (which are the ones on the top of the canvas), one at a time:
122 * @skip d.proxy_img = evas_object_image_filled_add(d.evas);
123 * @until evas_object_show(d.proxy_img);
124 * As in other examples, we have a command line interface on it.
125 * @dontinclude evas-images2.c
126 * @skip commands
127 * @until ;
128 * The 'p' one will change the source of the proxy image to one of the
129 * other two, as seem above.
130 * @skip if (strcmp(ev->keyname, "p") == 0)
131 * @until }
132 * Note the top right image, the smaller one:
133 * @dontinclude evas-images2.c
134 * @skip noise_img =
135 * @until show
136 * Since we are creating the data for its pixel buffer ourselves, we
137 * have to set its size with evas_object_image_size_set(), first. We
138 * set our data with the function evas_object_image_data_set(), where
139 * the second argument is a buffer with random data. There's a last
140 * command to print it's @b stride value. Since its created with one
141 * quarter of the canvas's original width
142 * @dontinclude evas-images2.c
143 * @skip define WIDTH
144 * @until define HEIGHT
145 * you can check this value.
146 *
147 * The image on the top left also has a subtlety: it is @b pre-loaded
148 * on this example.
149 * @dontinclude evas-images2.c
150 * @skip d.logo =
151 * @until show
152 * On real use cases we wouldn't be just printing something like this
153 * @dontinclude evas-images2.c
154 * @skip static void
155 * @until }
156 * naturally.
157 *
158 * The 's' command will save one of the images on the disk, in the png
159 * format:
160 * @dontinclude evas-images2.c
161 * @skip if (strcmp(ev->keyname, "a") == 0)
162 * @until }
163 *
164 * The full example follows.
165 *
166 * @include evas-images2.c
167 * @example evas-images2.c
168 */
169
170/**
171 * @page Example_Evas_Events Evas events (canvas and object ones) and some canvas operations example
172 * @dontinclude evas-events.c
173 *
174 * In this example we illustrate how to interact with canvas' (and its
175 * objects') events, including the key input ones. We also demonstrate
176 * precise point collision on objects and canvas "obscured regions",
177 * here.
178 *
179 * The example application consists of a window with a white
180 * background and an image -- the Enlightenment logo. The application
181 * begins with this image switching back and forth into two sizes: the
182 * exact canvas' size and one quarter of it (when it's placed on the
183 * top left quadrant). Thus, we'll have an @b animation going on,
184 * with image states set to change each 2 elapsed seconds.
185 *
186 * There's a global variable to aid accessing our desired context
187 * variables from anywhere in the code:
188 * @dontinclude evas-events.c
189 * @skip test_data
190 * @until {0}
191 *
192 * What interests us there are the @c canvas pointer, our image handle
193 * -- @c img -- and the background one, @c bg.
194 *
195 * The first interesting thing on the example is the registration of a
196 * callback on each canvas resizing event, where we put our canvas'
197 * size and the background rectangle's one in synchrony, so that we
198 * don't get bogus content on rendering with canvas resizes:
199 * @dontinclude evas-events.c
200 * @skip resize_set
201 * @until resize_set
202 * @dontinclude evas-events.c
203 * @skip here to keep
204 * @until }
205 *
206 * Than, after grabbing our canvas pointer from the Ecore Evas helper
207 * infrastructure, we registrate an event callbacks on it:
208 * @skip evas_event_callback_add(d.canvas, EVAS_CALLBACK_RENDER_FLUSH_PRE,
209 * @until two canvas event callbacks
210 * @dontinclude evas-events.c
211 * @skip render flush callback
212 * @until }
213 * It will be called whenever our canvas has to flush its rendering
214 * pipeline. In this example, two ways of observing that message
215 * which is printed in the cited callback are:
216 * - to resize the example's window (thus resizing the canvas' viewport)
217 * - let the animation run
218 *
219 * When one resizes the canvas, there's at least one operation it has
220 * to do which will require new calculation for rendering: the
221 * resizing of the background rectangle, in a callback we already
222 * shown you.
223 *
224 * The creation of our background rectangle is so that we give it a @b name,
225 * via evas_object_name_set() and we give it the canvas @b focus:
226 * @dontinclude evas-events.c
227 * @skip bg = evas_object_rectangle_add
228 * @until focus_set
229 *
230 * Still exemplifying events and callbacks, we register a callback on
231 * the canvas event of an object being focused:
232 * @dontinclude evas-events.c
233 * @skip add(d.canvas, EVAS_CALLBACK_CANVAS_OBJECT_FOCUS
234 * @until }
235 * @dontinclude evas-events.c
236 * @skip called when
237 * @until }
238 *
239 * In that call, @c event_info is going to be the focused object's
240 * handle, in this case our background rectangle. We print its name,
241 * so you can check it's the same. We check that pointer is the same
242 * reported by Evas' API with regard to the newest focused
243 * object. Finally, we check whether that object is really flagged as
244 * focused, now using an Evas object API function.
245 *
246 * The animation we talked about comes from a timer we register just
247 * before we start the example's main loop. As we said, the resizing
248 * of the image will also force the canvas to repaint itself, thus
249 * flushing the rendering pipeline whenever the timer ticks:
250 * @dontinclude evas-events.c
251 * @skip d.resize_timer = ecore
252 * @until d.resize_timer = ecore
253 * @dontinclude evas-events.c
254 * @skip put some action
255 * @until }
256 * When you start this example, this animation will be
257 * running, by default. To interact with the program, there's a
258 * command line interface. A help string can be asked for with the
259 * 'h' key:
260 * @dontinclude evas-events.c
261 * @skip static const char *commands
262 * @until ;
263 * These are the commands the example will accept at any time, except
264 * when one triggers the 'f' one. This command will exemplify
265 * evas_event_freeze(), which interrupts @b all input events
266 * processing for the canvas (in the example, just for 3 seconds). Try
267 * to issue events for it during that freeze time:
268 * @dontinclude evas-events.c
269 * @skip if (strcmp(ev->keyname, "f") == 0)
270 * @until }
271 * The 'd' command will unregister those two canvas callbacks for you,
272 * so you won't see the messages about the focused object and the
273 * rendering process anymore:
274 * @dontinclude evas-events.c
275 * @skip if (strcmp(ev->keyname, "d") == 0)
276 * @until }
277 * In this example, we start using a focused object to handle the input
278 * events -- the background rectangle. We register a callback on an key input
279 * event occurring on it, so that we can act on each key stroke:
280 * @skip object_event_callback_add
281 * @until }
282 * @dontinclude evas-events.c
283 * @skip examine the keys pressed
284 * @until key grab
285 * We do so by examining the @c ev->keyname string (remember the event
286 * information struct for key down events is the #Evas_Event_Key_Down
287 * one). There's one more trick for grabbing input events on this
288 * example -- evas_object_key_grab(). The 'c' command will, when
289 * firstly used, @b unfocus the background rectangle. Unfocused
290 * objects on an Evas canvas will @b never receive key events. We
291 * grab, then, the keys we're interested at to the object forcefully:
292 * @skip if (d.focus)
293 * @until got here by key grabs
294 * This shows how one can handle input not depending on focus issues
295 * -- you can grab them globally. Switch back and forth focus and
296 * forced key grabbing with the 'c' key, and observe the messages
297 * printed about the focused object. Observe, also, that we register
298 * two more @b object callbacks, this time on the image object
299 * (Enlightenment logo), where we just print messages telling the mouse
300 * pointer has entered or exited it area:
301 * @skip evas_object_show(d.img);
302 * @until mouse_out, NULL
303 * @dontinclude evas-events.c
304 * @skip mouse enters the object's area
305 * @until mouse exits the object's area
306 * Experiment with moving the mouse pointer over the image, letting it
307 * enter and exit its area (stop the animation with 'a', for a better
308 * experience). When you start the example, Evas will consider this
309 * area by being the whole boundary rectangle around the picture. If
310 * you issue the 'p' command, though, you get a demonstration of Evas'
311 * precise point collision detection on objects. With
312 * evas_object_precise_is_inside_get(), one can make Evas consider the
313 * transparent areas of an object (the middle of the logo's E letter,
314 * in the case) as not belonging to it when calculating mouse
315 * in/out/up/down events:
316 * @dontinclude evas-events.c
317 * @skip if (strcmp(ev->keyname, "p") == 0)
318 * @until }
319 * To finish the example, try the command bound to Control + 'o',
320 * which exemplifies Evas' <b>obscured regions</b>. When firstly
321 * pressed, you'll get the same contents, in a region in the middle of
322 * the canvas, at the time the key was pressed, until you toggle the
323 * effect off again (make sure the animation is running on to get the
324 * idea better). When you toggle this effect off, we also demonstrate
325 * the use of evas_render_updates(), which will force immediate
326 * updates on the canvas rendering, bringing back the obscured
327 * region's contents to normal.
328 * @skip mods = evas_key_modifier_get(evas);
329 * @until end of obscured region command
330 *
331 * What follows is the complete code for this example.
332 *
333 * @include evas-events.c
334 * @example evas-events.c
335 */
336
337/**
338 * @page Example_Evas_Object_Manipulation Evas objects basic manipulation example
339 *
340 * @include evas-object-manipulation.c
341 * @example evas-object-manipulation.c
342 */
343
344/**
345 * @page Example_Evas_Aspect_Hints Evas aspect hints example
346 *
347 * @include evas-aspect-hints.c
348 * @example evas-aspect-hints.c
349 */
350
351/**
352 * @page Example_Evas_Size_Hints Evas alignment, minimum size, maximum size, padding and weight hints example
353 *
354 * In this code, we place a (vertical) box with two rectangles as
355 * child elements. It has a command line interface with which to act
356 * on those rectangles' <b>size hints</b>:
357 * @dontinclude evas-hints.c
358 * @skip static const char commands
359 * @until ;
360 *
361 * That should be self explanatory. Change those values (possibly
362 * resizing the box, which will resize together with the example's
363 * window) to get how size hints are honored by a container object,
364 * which in this case is the Evas box.
365 *
366 * More on this smart object can be found on @ref Example_Evas_Box.
367 * The full code for this example follows.
368 *
369 * @include evas-hints.c
370 * @example evas-hints.c
371 */
372
373/**
374 * @page Example_Evas_Box Evas box example
375 *
376 * In this example, we demonstrate the use of Evas box objects. We
377 * cover changing boxes' layouts (with a custom layout, besides the
378 * ones provided by Evas), box padding and alignment influence on the
379 * layouts, insertion and removal of box items.
380 *
381 * The interesting part of the code starts, naturally, when we add a
382 * box object to the canvas. Just after it, we place five rectangles,
383 * with random colors, inside of it. Those rectangles get a minimum
384 * size hint of 50 pixels on each axis, which will be respected by
385 * most of the box's possible layouts:
386 * @dontinclude evas-box.c
387 * @skip evas_object_box_add
388 * @until }
389 * @until }
390 *
391 * Just like in other Evas examples, we have a white background on the
392 * canvas and a red border around the container object of interest,
393 * the box, to mark its boundaries. Resizing of the canvas will keep
394 * the box's proportion with regard to the whole canvas', so that you
395 * can experiment with different sizes of the box to accomodate its
396 * children:
397 * @dontinclude evas-box.c
398 * @skip adjust canvas' contents on resizes
399 * @until }
400 *
401 * Again, one interacts with this program by means of key commands:
402 * @dontinclude evas-box.c
403 * @skip static const char *commands
404 * @until ;
405 *
406 * Let's start with the @b numeric ones, each of which will impose a
407 * different layout on the box object.
408 *
409 * The initial layout the box starts at is the one triggered by the
410 * key @c '1' -- the horizontal layout. Thus, the initial appearance
411 * of this program, demonstrating this layout, is something like:
412 *
413 * @image html evas-box-example-00.png
414 * @image rtf evas-box-example-00.png
415 * @image latex evas-box-example-00.eps
416 *
417 * The vertical layout (@c '2' key) is very similar, but just
418 * disposing the items vertically:
419 *
420 * @image html evas-box-example-01.png
421 * @image rtf evas-box-example-01.png
422 * @image latex evas-box-example-01.eps
423 *
424 * Note the influence of the (default) @c 0.5 box alignment property,
425 * which will let the children line in the middle of the box's
426 * area. Also, because the space required by them extrapolates the
427 * box's height (we resized it to be smaller), they'll be drawn out if
428 * its bounds.
429 *
430 * Next, comes the horizontal @b homogeneous layout (@c '3' key). See
431 * how it reserves an equal amount of space for each child to take:
432 *
433 * @image html evas-box-example-02.png
434 * @image rtf evas-box-example-02.png
435 * @image latex evas-box-example-02.eps
436 *
437 * Its vertical equivalent can be triggered by the @c '4' key. The
438 * next different layout of interest is the horizontal maximum size
439 * homogeneous (@c '5' key). It will reserve cells to children sized
440 * equally to the dimensions of the child with bigger size (or minimum
441 * size hints). For this example, all cells would be just the size of
442 * our rectangles' minimum size hints and, to prove that, insert a new
443 * (smaller) rectangle at position 3, say, with @c Ctrl and @c 3 keys
444 * together:
445 *
446 * @image html evas-box-example-03.png
447 * @image rtf evas-box-example-03.png
448 * @image latex evas-box-example-03.eps
449 *
450 * The code for the commands inserting and deleting box items is:
451 * @dontinclude evas-box.c
452 * @skip mods, "Shift"
453 * @until }
454 * @until }
455 * @dontinclude evas-box.c
456 * @skip new rectangle to be put in the box
457 * @until }
458 * In that code, we exemplify evas_object_box_children_get(), to fetch
459 * a child element at an exact position. After the element removal
460 * from the box (leaving it unparented again), we delete it and free
461 * that list. The code inserting a new rectangle, there, is
462 * straightforward.
463 *
464 * Try the @c '6' key for the vertical equivalent of the last shown
465 * layout. Then, comes the @b flow layout, triggered by the @c '7'
466 * key. We make our box small to demonstrate the effect on the items
467 * layouting:
468 *
469 * @image html evas-box-example-04.png
470 * @image rtf evas-box-example-04.png
471 * @image latex evas-box-example-04.eps
472 *
473 * The next two numerical commands are for the vertical equivalent of
474 * the last and the stack one, respectively. Try them out to get their
475 * looks.
476 *
477 * The last numerical key, @c '0', shows the effect of a @b custom
478 * layout on the box. We wrote one that would split the width and
479 * height of the box equally and, then, place the items in the cells
480 * in the diagonal:
481 * @dontinclude evas-box.c
482 * @skip keyname, "0"
483 * @until }
484 * @dontinclude evas-box.c
485 * @skip custom 'diagonal' layout
486 * @until }
487 * @until }
488 *
489 * @image html evas-box-example-05.png
490 * @image rtf evas-box-example-05.png
491 * @image latex evas-box-example-05.eps
492 *
493 * Finally, the @c 'a' and @c 'p' commands will change the box's
494 * alignment and padding property values, respectively. For each of
495 * the layouts above, see the effects they make by setting different
496 * values on those properties.
497 *
498 * The full code for this example follows. For an exercise on <b>the
499 * effect of children box elements' size hints on a box layout</b>,
500 * try the @ref Example_Evas_Size_Hints.
501 *
502 * @include evas-box.c
503 * @example evas-box.c
504 */
505
506/**
507 * @page Example_Evas_Stacking Evas object stacking functions (and some event handling)
508 * @dontinclude evas-stacking.c
509 *
510 * In this example, we illustrate how to stack objects in a custom
511 * manner and how to deal with layers.
512 *
513 * We have three objects of interest in it -- white background, red
514 * rectangle, green rectangle and blue rectangle.
515 * @skip d.bg = evas_object_rectangle_add(d.canvas);
516 * @until evas_object_resize(d.bg, WIDTH, HEIGHT);
517 * @skip d.rects[2] = evas_object_rectangle_add(d.canvas);
518 * @until evas_object_show(d.rects[0]);
519 * @dontinclude evas-stacking.c
520 * Like in other Evas examples, one interacts with it by means of key
521 * commands:
522 * @skip static const char *commands
523 * @until ;
524 * At any given point, like seem above, you'll be operating one rectangle only.
525 * You may stacking it below an adjacent object with "b":
526 * @skip evas_object_stack_below(d.rects[d.cur_rect], neighbour);
527 * @until evas_object_stack_below(d.rects[d.cur_rect], neighbour);
528 * @dontinclude evas-stacking.c
529 * "a" will do the opposite:
530 * @skip evas_object_stack_above(d.rects[d.cur_rect], neighbour);
531 * @until evas_object_stack_above(d.rects[d.cur_rect], neighbour);
532 * To bring it directly to the top/bottom, use "t"/"m", respectively:
533 * @dontinclude evas-stacking.c
534 * @skip evas_object_raise(d.rects[d.cur_rect]);
535 * @until evas_object_raise(d.rects[d.cur_rect]);
536 * @skip evas_object_lower(d.rects[d.cur_rect]);
537 * @until evas_object_lower(d.rects[d.cur_rect]);
538 * At any time, use the "s" command to see the status of the
539 * ordering. It will show the background's ordering too. Note that it
540 * also shows the @b layer for this object. It starts at a @b
541 * different layer than the others. Use "l" to change its layer
542 * (higher layer numbers mean higher layers). If the background is on
543 * the same layer as the others (0), you'll see it interact with them
544 * on the ordering. If it's in the layer above, no matter what you do,
545 * you'll see nothing but the white rectangle: it covers the other
546 * layers. For the initial layer (-1), it will never mess nor occlude
547 * the others.
548 *
549 * Let's make some tests with those commands. The rectangle which starts
550 * selected and which will receive our commands is the @b red one. It
551 * starts stacked above all the others, like seem above:
552 *
553 * @image html evas-stacking-example-00.png
554 * @image rtf evas-stacking-example-00.png
555 * @image latex evas-stacking-example-00.eps
556 *
557 * Stack it one level below, with 'b', and you'll get:
558 *
559 * @image html evas-stacking-example-01.png
560 * @image rtf evas-stacking-example-01.png
561 * @image latex evas-stacking-example-01.eps
562 * Note how the rectangle which laid above it, the green one, is now
563 * on top of it. Now change the rectangle to operate on to the blue
564 * one, with two consecutive 'c' commands. Note that it's the lowest
565 * one on the stack of rectangles. Issue the 'a' command for it, thus
566 * re-stacking it one level above:
567 *
568 * @image html evas-stacking-example-02.png
569 * @image rtf evas-stacking-example-02.png
570 * @image latex evas-stacking-example-02.eps
571 * You can send it to the top of its layer directly with the 't' command:
572 *
573 * @image html evas-stacking-example-03.png
574 * @image rtf evas-stacking-example-03.png
575 * @image latex evas-stacking-example-03.eps
576 * Now put it back to the bottom of that layer with 'm':
577 *
578 * @image html evas-stacking-example-04.png
579 * @image rtf evas-stacking-example-04.png
580 * @image latex evas-stacking-example-04.eps
581 * Like said above, we have two layers used at the beginning of the
582 * example: the default one (0) and the one immediately below it (-1),
583 * for the white background. Let's change this setup by issuing the
584 * 'l' command, which will change the background's layer to 1, i.e., a
585 * layer @b above the one holding the other rectangles:
586 *
587 * @image html evas-stacking-example-05.png
588 * @image rtf evas-stacking-example-05.png
589 * @image latex evas-stacking-example-05.eps
590 * See how it now covers everything else. Press 'l' again, taking it
591 * now to layer 0. It's still covering everything because it lands the
592 * layer as the highest one on the objects stack. As we have the blue
593 * rectangle as the one receiving stacking commands, hit 't' and
594 * you'll see it again:
595 *
596 * @image html evas-stacking-example-06.png
597 * @image rtf evas-stacking-example-06.png
598 * @image latex evas-stacking-example-06.eps
599 * By bringing the background back to layer -1 ('l'), you'll get:
600 *
601 * @image html evas-stacking-example-07.png
602 * @image rtf evas-stacking-example-07.png
603 * @image latex evas-stacking-example-07.eps
604 *
605 * The last two commands available are "p" and "r", which will make
606 * the target rectangle to @b pass (ignore) and @b repeat the mouse
607 * events occurring on it (the commands will cycle through on and off
608 * states). This is demonstrated with the following
609 * #EVAS_CALLBACK_MOUSE_DOWN callback, registered on each of the
610 * colored rectangles:
611 * @dontinclude evas-stacking.c
612 * @skip static void
613 * @until }
614 * Try to change these properties on the three rectangles while
615 * experimenting with mouse clicks on their intersection region.
616 *
617 * The full example follows.
618 *
619 * @include evas-stacking.c
620 * @example evas-stacking.c
621 */
622
623/**
624 * @page Example_Evas_Map_Overview Evas Map - Overview
625 * @dontinclude evas-map-utils.c
626 *
627 * Down to the very bottom, Map is simple: it takes an object and transforms
628 * the way it will be shown on screen. But using it properly can be a bit
629 * troublesome.
630 *
631 * For the most common operations there are utility functions that help in
632 * setting up the map to achieve the desired effects. Now we'll go through
633 * an overview of the map API and some of the things that can be done with
634 * it.
635 *
636 * The full code can be found @ref evas-map-utils.c "here".
637 *
638 * To show how some functions work, this example listens to keys pressed to
639 * toggle several options.
640 * @skip typedef
641 * @until App_Data
642 * @until ;
643 *
644 * In this program, we divide the window in four quadrants, each holding an
645 * object that will have different map configurations applied to them in each
646 * call to an animator function.
647 * @skip static Eina_Bool
648 * @until evas_output_size_get
649 *
650 * Let's first create a map and set some of our options to it. Only four
651 * points maps are supported, so we'll stick to that magic number. We can
652 * set a color for each vertex or apply one for all of them at once
653 * @until evas_map_util_points_color_set
654 *
655 * For the first object, we'll have a plain rectangle. At its creation, this
656 * rectangle was set to be semi-transparent, but whether its own alpha is
657 * used will be defined by the map's alpha setting. If the map's alpha is
658 * disabled, then the object will be completely opaque. The map's own color,
659 * however, will use any alpha set to it.
660 *
661 * So we get our object, initialize our map geometry to match the rectangle
662 * and make it rotate around its own center, then apply the map to the
663 * object so it takes effect.
664 * @until evas_object_map_enable_set
665 *
666 * The second object is an image. Here we don't have any color set for the
667 * object, but the image itself contains an alpha channel that will not be
668 * affected by the map settings, so even with alpha set to be off, the image
669 * will still be transparent. Color applied to the map will tint it though.
670 * Since setting a map copies it into the object, we can reuse the same one
671 * we created before. We initialize it to the new object while all other
672 * options are kept the same. Notice that no rotation will be done here, as
673 * that's just an utility function that takes the coordinates set for each
674 * point of the map and transforms it accordingly.
675 * @until evas_map_util_points_populate_from_object_full
676 *
677 * This time the object is a bit farther into the screen, by using a @c z
678 * value higher than 0 to init the map. We also need to map the image used
679 * by the object, so Evas knows how to transform it properly. For this we
680 * use the evas_map_point_image_uv_set() to tell the map what coordinate
681 * within the image corresponds to each point of the map.
682 * @until evas_map_point_image_uv_set(m, 3
683 *
684 * This object will also be rotated, but in all three axis and around some
685 * other point, not its center, chosen mostly at random. If enabled, lighting
686 * will be applied to, from a light source at the center of the window.
687 * @until evas_object_map_enable_set
688 *
689 * For the third object we are doing, once more, a 3D rotation, but this time
690 * perspective will be applied to our map to make it look more realistic.
691 * The lighting source also follows the mouse cursor and it's possible to
692 * toggle backface culling, so that the object is hidden whenever we are
693 * not seeing its front face.
694 * @until evas_object_map_enable_set
695 *
696 * And we free this map, since since we messed too much with it and for the
697 * last object we want something cleaner.
698 * @until evas_map_free
699 *
700 * The last object is actually two. One image, with an image set to it, and
701 * one image proxying the first one with evas_object_image_source_set(). This
702 * way, the second object will show whatever content its source has.
703 * This time we'll be using a map more manually to simulate a simple reflection
704 * of the original image.
705 *
706 * We know that the reflection object is placed just like the original, so
707 * we take a shortcut by just getting the geometry of our to-be-mapped object.
708 * We also need to get the image size of the source.
709 * @until evas_object_image_size_get
710 *
711 * For this we'll create a map shaped so that it begins at the base of our
712 * image and it expands horizontally as it grows (downwards) in height.
713 * @until evas_map_point_coord_set(m, 3
714 *
715 * Since the reflection should show the image inverted, we need to map it
716 * this way. The first point of the map (top-left) will be mapped to the
717 * mapped to the first pixel of the last row. There's no horizontal reflection
718 * and we want the full width of the image, but as we map its upper side ww
719 * will only take two thirds of the image.
720 * @until evas_map_point_image_uv_set(m, 3
721 *
722 * Finally, to fade out our reflection we set the colors for each point in
723 * the map. The two at the top need to be visible, but we'll tone them down
724 * a bit and make them a bit translucent. The other two will go straight to
725 * full transparency. Evas interpolates the colors from one point to the next,
726 * so this will make them fade out.
727 * @until evas_object_map_enable_set
728 *
729 * Close up by freeing the map and do some other things needed to keep stuff
730 * moving in our animations and we are done.
731 * @until }
732 *
733 * The rest of the program is setup and listening to key events. Nothing that
734 * matters within the scope of this example, so we are going to skip it.
735 * Refer to it @ref evas-map-utils.c "here" however to see how everything
736 * fits together.
737 *
738 * @example evas-map-utils.c
739 */
740
741/**
742 * @page Example_Evas_Smart_Objects Evas object smart objects
743 * @dontinclude evas-smart-object.c
744 *
745 * In this example, we illustrate how to create and handle Evas smart objects.
746 *
747 * A smart object is one that provides custom functions to handle
748 * clipping, hiding, moving, resizing, color setting and more on @b
749 * child elements, automatically, for the smart object's user. They
750 * could be as simple as a group of objects that move together (see
751 * @ref Evas_Smart_Object_Clipped) or implementations of whole complex
752 * UI widgets, providing some intelligence (thus the name) and
753 * extension to simple Evas objects.
754 *
755 * Here, we create one as an example. What it does is to control (at
756 * maximum) 2 child objects, with regard to their geometries and
757 * colors. There can be a "left" child and a "right" one. The former
758 * will always occupy the top left quadrant of the smart object's
759 * area, while the latter will occupy the bottom right. The smart
760 * object will also contain an @b internal decorative border object,
761 * which will also be controlled by it, naturally.
762 *
763 * Here is where we add it to the canvas:
764 * @skip d.smt = evas_smart_example_add(d.evas);
765 * @until show
766 *
767 * The magic starts to happen in the @c evas_smart_example_add()
768 * function, which is one in the example smart object's defined @b
769 * interface. These should be the functions you would export to the
770 * users of your smart object. We made three for this one:
771 * - @c evas_smart_example_add(): add a new instance of the example
772 * smart object to a canvas
773 * - @c evas_smart_example_remove(): remove a given child of the smart
774 * object from it
775 * - @c evas_smart_example_set_left(): set the left child of the smart
776 * object
777 * - @c evas_smart_example_set_right(): set the right child of the
778 * smart object
779 *
780 * The object's creation takes place as:
781 * @dontinclude evas-smart-object.c
782 * @skip add a new example smart object to a canvas
783 * @until }
784 *
785 * Smart objects are defined by <b>smart classes</b>, which are structs
786 * defining their interfaces, or <b>smart functions</b> (see
787 * #Evas_Smart_Class, the base class for any smart object). As you
788 * see, one has to use the evas_object_smart_add() function to
789 * instantiate smart objects. Its second parameter is what matters --
790 * an #Evas_Smart struct, which contains all the smart class
791 * definitions (smart functions, smart callbacks, and the like). Note,
792 * however, that @c _evas_smart_example_smart_class_new() seems not to
793 * be defined in our example's code. That's because it came from a very
794 * handy <b>helper macro</b>:
795 * @dontinclude evas-smart-object.c
796 * @skip EVAS_SMART_SUBCLASS_NEW
797 * @until _smart_callbacks
798 * What it does is to @b subclass a given existing smart class, thus
799 * specializing it. This is very common and useful in Evas. There is a
800 * built-in smart object, the "clipped smart object", which implements
801 * a behavior mostly desired by many other smart object implementors:
802 * it will clip its children to its area and move them along with it,
803 * on evas_object_move() calls. Then, our example smart object will
804 * get that behavior for free.
805 *
806 * The first argument to the macro,
807 * @dontinclude evas-smart-object.c
808 * @skip _evas_smart_example_type
809 * @until _evas_smart_example_type
810 * will define the new smart class' name. The second tells the macro
811 * what is the @b prefix of the function it will be declaring with a @c
812 * _smart_set_user() suffix. On this function, we may override/extend
813 * any desired method from our parent smart class:
814 * @dontinclude evas-smart-object.c
815 * @skip setting our smart interface
816 * @until }
817 *
818 * The first function pointer's code will take place at an example
819 * smart object's @b creation time:
820 * @dontinclude evas-smart-object.c
821 * @skip create and setup
822 * @until }
823 *
824 * The #EVAS_SMART_DATA_ALLOC macro will take care of allocating our
825 * smart object data, which will be available on other contexts for us
826 * (mainly in our interface functions):
827 * @dontinclude evas-smart-object.c
828 * @skip typedef struct _Evas_Smart_Example_Data
829 * @until };
830 *
831 * See that, as we're inheriting from the clipped smart object's
832 * class, we @b must have their data struct as our first member. Other
833 * data of interest for us is a child members array and the border
834 * object's handle. The latter is what is created in the last
835 * mentioned function. Note how to tell Evas the border will be
836 * managed by our smart object from that time on:
837 * <code>evas_object_smart_member_add(priv->border, o);</code>.
838 * The counterpart of this function is exemplified on the smart
839 * object's interface function to remove children:
840 * @skip remove a child element
841 * @until set to
842 *
843 * At the end of that function we make use of an constant defined by
844 * the #EVAS_SMART_SUBCLASS_NEW: @c _evas_smart_example_parent_sc. It
845 * has the same prefix we passed to the macro, as you can see, and it
846 * holds a pointer to our @b parent smart class. Then, we can call the
847 * specialized method, itself, after our code. The @c del, @c hide, @c
848 * show and @c resize specializations are straightforward, we let the
849 * reader take a look at them below to check their behavior. What's
850 * interesting is the @c calculate one:
851 * @dontinclude evas-smart-object.c
852 * @skip act on child objects' properties
853 * @until setting
854 *
855 * This code will take place whenever the smart object itself is
856 * flagged "dirty", i.e., must be recalculated for rendering (that
857 * could come from changes on its clipper, resizing, moving,
858 * etc). There, we make sure the decorative border lies on the edges of
859 * the smart object and the children, if any, lie on their respective
860 * quadrants.
861 *
862 * After instantiating our smart object, we do some checks to exemplify
863 * some of the API on smart objects:
864 * @dontinclude evas-smart-object.c
865 * @skip ret = evas_object_smart_type_check
866 * @until "no"
867 * The evas_object_smart_type_check() one will assure we have the
868 * string naming our smart class really set to the live object. The
869 * evas_object_smart_clipped_clipper_get() exemplifies usage of
870 * "static clippers" -- clipped smart objects have their global
871 * clippers flagged static.
872 *
873 * Other important things we also exemplify here are <b>smart
874 * callbacks</b> and smart callback @b introspection:
875 * @dontinclude evas-smart-object.c
876 * @skip EVT_CHILDREN_NUMBER_CHANGED
877 * @until ;
878 *
879 * Here we declare our array of smart callback descriptions, which has
880 * one element only, in this case. That callback will take place, as
881 * the name indicates, whenever the number of member objects in our
882 * smart object example instance changes. That global array variable
883 * must be the last argument to #EVAS_SMART_SUBCLASS_NEW, so that it's
884 * registered as the <b>smart class</b>'s callbacks description.
885 *
886 * After we instantiate the smart object, we take a look on those
887 * descriptions and register a callback on that unique smart event:
888 * @dontinclude evas-smart-object.c
889 * @skip for (;
890 * @until focus_set
891 *
892 * The code of the callback will just print how many member objects we
893 * have, which is an integer argument of the callback itself, as
894 * flagged by its description:
895 * @dontinclude evas-smart-object.c
896 * @skip callback on number of member objects changed
897 * @until }
898 *
899 * One of the points at which we issue that callback is inside the @c
900 * evas_smart_example_remove(), code that was already shown.
901 *
902 * As in other examples, to interact with this one there's a command
903 * line interface. A help string can be asked for with the 'h' key:
904 * @dontinclude evas-smart-object.c
905 * @skip static const char *commands =
906 * @until ;
907 * Use 'l' and 'r' keys, to create new rectangles and place them on
908 * the left (@c evas_smart_example_set_left()) or right (@c
909 * evas_smart_example_set_right()) spots of our smart object,
910 * respectively. The 'w' command will remove all member objects from
911 * the smart object and delete them. The keyboard arrows will move the
912 * smart object along the canvas. See how it takes any child objects
913 * with it during its movement. The 'd' and 'i' keys will increase or
914 * decrease the smart object's size -- see how it affects the
915 * children's sizes, too. Finally, 'c' will change the color of the
916 * smart object's clipper (which is the exact internal clipper coming
917 * from a clipped smart object):
918 * @dontinclude evas-smart-object.c
919 * @skip d.clipper =
920 * @until .a);
921 *
922 * "Real life" examples of smart objects are Edje and Emotion objects:
923 * they both have independent libraries implementing their
924 * behavior. The full example follows.
925 *
926 * @include evas-smart-object.c
927 * @example evas-smart-object.c
928 */
929
930/**
931 * @page Example_Evas_Smart_Interfaces Evas object smart interfaces
932 * @dontinclude evas-smart-interface.c
933 *
934 * In this example, we illustrate how to create and handle Evas smart
935 * @b interfaces. Note that we use the same code base of the @ref
936 * Example_Evas_Smart_Objects example, here. We just augment it with
937 * an interfaces demonstration.
938 *
939 * A smart interface is just a functions interface a given smart
940 * objcet is declaring to support and or use. In Evas, interfaces are
941 * very simple: no interface inheritance, no interface
942 * overriding. Their purpose is to extend an object's capabilities and
943 * behaviour beyound the sub-classing schema.
944 *
945 * Here, together with a custom smart object, we create and declare
946 * the object as using an Evas interface. It'll have a custom
947 * function, too, besides the @c add() and del() obligatory ones. To
948 * demonstrate interface data, which is bound to object @b instances,
949 * we'll have a string as this data.
950 *
951 * Here is where we declare our interface:
952 * @skip static const char iface1_data[]
953 * @until (Evas_Smart_Interface *)&iface1, NULL
954 * @until };
955 *
956 * Note that there's error checking for interfaces creation, by means of
957 * the @c add() method's return value (@c _iface1_add(), here).
958 *
959 * Now note that here we are filling in the interface's fields dinamically.
960 * Let's move on to that code region:
961 *
962 * @dontinclude evas-smart-interface.c
963 * @skip iface = (Evas_Smart_Example_Interface *)&iface1;
964 * @until d.smt = evas_smart_example_add(d.evas);
965 *
966 * As important as setting the function pointers, is declaring the @c
967 * private_size as to match exactly the size of the data blob we want
968 * to have allocated for us by Evas. This will happen automatically
969 * inside @c evas_smart_example_add(). Later, on this code, we deal
970 * exactly with that data blob, more specifically writing on it (as
971 * it's not done inside @c _iface1_add(), here:
972 *
973 * @dontinclude evas-smart-interface.c
974 * @skip iface = (Evas_Smart_Example_Interface *)evas_object_smart_interface_get
975 * @until }
976 *
977 * Before accessing the interface data, we exercise the interface
978 * fetching call evas_object_smart_interface_get(), with the name
979 * string we used to be interface's name. With that handle in hands,
980 * we issue evas_object_smart_interface_data_get() and write the
981 * string we want as data on that memory region. That will make up for
982 * the string you get on @c _iface1_del().
983 *
984 * The full example follows.
985 *
986 * @include evas-smart-interface.c
987 * @example evas-smart-interface.c
988 */
989
990/**
991 * @page Example_Evas_Text Evas text object example
992 *
993 * In this example, we illustrate how to use text objects in various
994 * manners.
995 *
996 * We place, in the canvas, a text object along with a border image to
997 * delimit its geometry. After we instantiate the text object, we set
998 * lots of properties on it to the initial ones from a preset list,
999 * which has the following declaration:
1000 * @dontinclude evas-text.c
1001 * @skip init values
1002 * @until };
1003 *
1004 * Then, we set the text string itself, on it, with
1005 * evas_object_text_text_set(). We set an explicit size of 30 points
1006 * for our font, as you could see, what we check back with the
1007 * getter evas_object_text_font_get().
1008 *
1009 * Look at how it translates to code:
1010 * @dontinclude evas-text.c
1011 * @skip evas_object_text_add
1012 * @until fprintf
1013 *
1014 * Like in other Evas examples, one interacts with it by means of key
1015 * commands:
1016 * @dontinclude evas-text.c
1017 * @skip static const char *commands
1018 * @until ;
1019 *
1020 * Use the 't' key to exercise the evas_object_text_style_set()
1021 * function on the text -- it will cycle through all styles on
1022 * #Evas_Text_Style_Type (note we start on #EVAS_TEXT_STYLE_PLAIN,
1023 * thus with no effects on it) and, with other keys, you'll be able to
1024 * set properties applicable to individual styles on the text object.
1025 *
1026 * The 'z' key will change the text's @b size, keeping the font family
1027 * for it. Use 'f' to change the font, keeping the last size
1028 * set. There are three font families the example will cycle through:
1029 *
1030 * The 'b' command shows us that evas_object_color_set(), on a given
1031 * text object, will change the text's @b base color. Experiment with
1032 * it, which will cycle through the colors in the <c>.text</c> list in
1033 * @c init_data.
1034 *
1035 * The 's', 'o', 'w' and 'g' keys will make the text object to cycle
1036 * to the preset values on colors for shadow, outline, glow and 'glow
1037 * 2' effects, respectively. Naturally, they will only take effect on
1038 * the text styles which resemble them.
1039 *
1040 * The full example follows.
1041 *
1042 * @include evas-text.c
1043 * @example evas-text.c
1044 */
1045
1046/**
1047 * @page tutorial_table Table Smart Object example
1048 *
1049 * This example will arrange rectangles of different sizes(and colors) in a
1050 * table. While it's possible to create the same layout we are doing here by
1051 * positioning each rectangle independently, using a table makes it a lot
1052 * easier, since the table will control layout of all the objects, allowing you
1053 * to move, resize or hide the entire table.
1054 *
1055 * We'll start with creating the table, setting it to
1056 * EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE to have maximum flexibility and setting
1057 * its padding to 0:
1058 * @dontinclude evas-table.c
1059 * @skip object_table
1060 * @until show
1061 *
1062 * We then create each rectangle and add it to the table:
1063 * @until table_pack
1064 * @until table_pack
1065 * @until table_pack
1066 * @until table_pack
1067 * @note Each rectangle has a different minimum size based on how many rows and
1068 * columns it will occupy.
1069 *
1070 * The full source for this example follow:
1071 * @include evas-table.c
1072 * @example evas-table.c
1073 */