2 * @page Examples Examples
4 * Here is a page with examples.
6 * @ref Example_Evas_Buffer_Simple
8 * @ref Example_Evas_Init_Shutdown
10 * @ref Example_Evas_Images
12 * @ref Example_Evas_Images_2
14 * @ref Example_Evas_Events
16 * @ref Example_Evas_Object_Manipulation
18 * @ref Example_Evas_Aspect_Hints
20 * @ref Example_Evas_Size_Hints
22 * @ref Example_Evas_Stacking
26 * @page Example_Evas_Buffer_Simple Simple Evas canvas example
28 * The canvas will here use the buffer engine.
30 * @include evas-buffer-simple.c
31 * @example evas-buffer-simple.c
35 * @page Example_Evas_Init_Shutdown Evas' init/shutdown routines example
37 * @include evas-init-shutdown.c
38 * @example evas-init-shutdown.c
42 * @page Example_Evas_Images Some image object functions examples
43 * @dontinclude evas-images.c
45 * In this example, we add two images to a canvas, each one having a
46 * quarter of the canvas' size, positioned on the top left and bottom
47 * right corners, respectively:
48 * @skip img1 = evas_object_image_add(d.evas);
49 * @until ecore_main_loop_begin
50 * See there is a border image around the top left one, <b>which is
51 * the one that should be displayed</b>. The other one will (on
52 * purpose) fail to load, because we set a wrong file path as image
54 * @dontinclude evas-images.c
57 * This is how one is supposed to test for success when binding source
58 * images to image objects: evas_object_image_load_error_get(),
59 * followed by evas_load_error_str(), if one wants to pretty print/log
60 * the error. We'll talk about the border image further.
62 * To interact with the program, there's a command line interface,
63 * whose help string can be asked for with the 'h' key:
64 * @dontinclude evas-images.c
67 * The first four commands will change the top left images's @b fill property
68 * values, which dictate how the source image (Enlightenment's logo)
69 * is to be displayed through the image object's area. Experiment with
70 * those switches until you get the idea of evas_object_fill_set().
72 * The 'f' command will toggle that image's "filled" property, which
73 * is wheter it should track its size and set the fill one to fit the
74 * object's boundaries perfectly (stretching). Note that this command
75 * and the four above it will conflict: in real usage one would use
76 * one or other ways of setting an image object's viewport with regard
77 * to its image source.
79 * There are four commands which deal with the border image. This red
80 * frame is there to illustrate <b>image borders</b>. The image source
81 * for the border is a solid red rectangle, with a transparent @b
82 * rectangular area in its middle. See how we use it to get a 3 pixel
83 * wide frame with <code>evas_object_image_border_set(d.border, 3, 3,
84 * 3, 3)</code>. To finish the effect of showing it as a border, we
85 * issue <code>evas_object_image_border_center_fill_set(d.border,
86 * EVAS_BORDER_FILL_NONE)</code>.
88 * Use 't' to change the border's thickness. 'b' will change the
89 * border image's center region rendering schema: either a hole (no
90 * rendering), blending (see the original transparent area, in this
91 * case) or solid (the transparent area gets filled). Finally, 'c'
92 * will change the border's scaling factor.
94 * While you have the border in 'blending mode', test the command 'm':
95 * it will set whether to use or not smooth scaling on the border's
96 * source image. Since the image is small originallly (30 x 30), we're
97 * obviously up-scaling it (except the border pixels, do you
98 * remember?). With this last switch, you'll either see the
99 * transparent shape in the middle flat (no smoothing) or blurry
102 * The full example follows.
104 * @include evas-images.c
105 * @example evas-images.c
109 * @page Example_Evas_Images_2 Some more image object functions examples (2nd block)
110 * @dontinclude evas-images2.c
112 * In this example, we have three images on the canvas, but one of
113 * them is special -- we're using it as a <b>proxy image
114 * object</b>. It will mirror the contents of the other two images
115 * (which are the ones on the top of the canvas), one at a time:
116 * @skip d.proxy_img = evas_object_image_filled_add(d.evas);
117 * @until evas_object_show(d.proxy_img);
118 * As in other examples, we have a command line interface on it.
119 * @dontinclude evas-images2.c
122 * The 'p' one will change the source of the proxy image to one of the
123 * other two, as seem above.
124 * @skip if (strcmp(ev->keyname, "p") == 0)
126 * Note the top right image, the smaller one:
127 * @dontinclude evas-images2.c
130 * Since we are creating the data for its pixel buffer ourselves, we
131 * have to set its size with evas_object_image_size_set(), first. We
132 * set our data with the function evas_object_image_data_set(),
133 * whose second argument is a buffer with random data. There's a last
134 * command to print it's @b stride value. Since its created with one
135 * quarter of the canvas's original width
136 * @dontinclude evas-images2.c
138 * @until define HEIGHT
139 * you can check this value.
141 * The image on the top left also has a subtlety: it is @b pre-loaded
143 * @dontinclude evas-images2.c
146 * On real use cases we wouldn't be just printing something like this
147 * @dontinclude evas-images2.c
152 * The 's' command will save one of the images on the disk, in the png
154 * @dontinclude evas-images2.c
155 * @skip if (strcmp(ev->keyname, "a") == 0)
158 * The full example follows.
160 * @include evas-images2.c
161 * @example evas-images2.c
165 * @page Example_Evas_Events Evas events (canvas and object ones) and some canvas operations example
166 * @dontinclude evas-events.c
168 * In this example we illustrate how to interact with canvas' (and
169 * its objects') events and other canvas operations.
171 * After we grab our canvas pointer, we registrate two event callbacks on it:
172 * @skip evas_event_callback_add(d.canvas, EVAS_CALLBACK_RENDER_FLUSH_PRE,
173 * @until two canvas event callbacks
174 * The first of them, whose code is
175 * @dontinclude evas-events.c
176 * @skip render flush callback
178 * will be called whenever our canvas has to flush its rendering pipeline.
179 * In this example, two ways of observing that message which is printed in
180 * the cited callback are:
181 * - to resize the example's window (thus resizing the canvas' viewport)
182 * - let the animation run
184 * When one resizes the canvas, there's at least one operation it has
185 * to do which will require new calculation for rendering: the
186 * resizing of the background rectangle:
187 * @dontinclude evas-events.c
188 * @skip here just to keep
190 * The animation we talked about comes from a timer we register just before
191 * we start the example's main loop:
192 * @dontinclude evas-events.c
193 * @skip d.resize_timer = ecore
194 * @until d.resize_timer = ecore
195 * being the timer's callback what follows:
196 * @dontinclude evas-events.c
197 * @skip put some action
199 * As you see, the resizing of the image will also force the canvas to
200 * repaint itself, thus flushing the rendering pipeline whenever the
201 * timer ticks. When you start this example, this animation will be
202 * running, by default. To interact with the program, there's a
203 * command line interface, whose help string can be asked for with the
205 * @dontinclude evas-events.c
206 * @skip if (strcmp(ev->keyname, "h") == 0)
208 * These are the commands the example will accept at any time, except
209 * when one triggers the 'f' one:
210 * @skip if (strcmp(ev->keyname, "f") == 0)
212 * This command will exemplify evas_event_freeze(), which interrupts
213 * @b all input events processing for the canvas (in the example, just
214 * for 3 seconds). Try to issue events for it during that freeze time.
215 * The 'd' command will unregister those two canvas callbacks for you,
216 * so you won't see the messages about the focused object and the
217 * rendering process anymore:
218 * @dontinclude evas-events.c
219 * @skip if (strcmp(ev->keyname, "d") == 0)
221 * The second of those callbacks has the following code:
222 * @dontinclude evas-events.c
223 * @skip called when our rectangle gets focus
225 * It will take place whenever an object in the canvas receives
226 * focus. In this example, we use the focus to handle the input
228 * @skip so we get input events
230 * The background rectangle is the chosen object to receive the
231 * focus. This also illustrates the use of
232 * evas_object_event_callback_add(), which registers an event callback
233 * on an Evas @b object (in this case, the event of a key being
234 * pressed down). On this callback, we examine each key pressed and,
235 * if they match one between the expected, we take some actions:
236 * @dontinclude evas-events.c
237 * @skip examine the keys pressed
239 * We do so by examining the @c ev->keyname string (remember the event
240 * information struct for key down events is the #Evas_Event_Key_Down
241 * one). There's one more trick for grabbing input events on this
242 * example -- evas_object_key_grab(). The 'c' command will, when
243 * firstly used, @b unfocus the background rectangle. Unfocused
244 * objects on an Evas canvas will @b never receive key events. We
245 * grab, then, the keys we're interested at, to the object forcefully:
247 * @until got here by key grabs
248 * This shows how one can handle input not depending on focus issues
249 * -- you can grab them globally. Switch back and forth focus and
250 * forced key grabbing with the 'c' key, and observe the messages
251 * printed about the focused object. Observe, also, that we register
252 * two more @b object callbacks, this time on the image object
253 * (Enlightenment logo):
254 * @skip evas_object_show(d.img);
255 * @until mouse_out, NULL
256 * whose code blocks are
257 * @dontinclude evas-events.c
258 * @skip mouse enters the object's area
259 * @until mouse exits the object's area
260 * Experiment with moving the mouse pointer over the image, letting it
261 * enter and exit its area (stop the animation with 'a', for a better
262 * experience). When you start the example, Evas will consider this
263 * area by being the whole boundary rectangle around the picture. If
264 * you issue the 'p' command, though, you get a demonstration of Evas'
265 * precise point collision detection on objects:
266 * @dontinclude evas-events.c
267 * @skip if (strcmp(ev->keyname, "p") == 0)
269 * With evas_object_precise_is_inside_get(), one can make Evas
270 * consider the transparent areas of an object (the middle of the
271 * logo's E letter, in the case) as not belonging to it when
272 * calculating mouse in/out/up/down events. To finish the example, try
273 * the command bound to Cotrol + 'o':
274 * @skip mods = evas_key_modifier_get(evas);
275 * @until end of obscured region command
276 * It exemplifies Evas' <b>obscured regions</b>. When firstly pressed,
277 * you'll get the same contents, in a region in the middle of the
278 * canvas, at the time the key was pressed, until you toggle the
279 * effect off again (make sure the animation is running on to get the
280 * idea better). When you toggle this effect off, we also demonstrate
281 * the use of evas_render_updates(), which will force immediate
282 * updates on the canvas rendering, bringing back the obscured
283 * region's contents to normal.
285 * What follows is the complete code for this example.
287 * @include evas-events.c
288 * @example evas-events.c
292 * @page Example_Evas_Object_Manipulation Evas objects basic manipulation example
294 * @include evas-object-manipulation.c
295 * @example evas-object-manipulation.c
299 * @page Example_Evas_Aspect_Hints Evas aspect hints example
301 * @include evas-aspect-hints.c
302 * @example evas-aspect-hints.c
306 * @page Example_Evas_Size_Hints Evas alignment, minimum size, maximum size, padding and weight hints example
308 * @include evas-hints.c
309 * @example evas-hints.c
313 * @page Example_Evas_Stacking Evas object stacking functions (and some event handling)
314 * @dontinclude evas-stacking.c
316 * In this example, we illustrate how to stack objects in a custom
317 * manner and how to deal with layers.
319 * We have three objects of interest in it -- white background, red
320 * rectangle, green rectangle and blue rectangle.
321 * @skip d.bg = evas_object_rectangle_add(d.canvas);
322 * @until evas_object_resize(d.bg, WIDTH, HEIGHT);
323 * @skip d.rects[2] = evas_object_rectangle_add(d.canvas);
324 * @until evas_object_show(d.rects[0]);
325 * @dontinclude evas-stacking.c
326 * Like in other Evas examples, one interacts with it be means of key commands:
327 * @skip "commands are:\n"
328 * @until "\th - print help\n");
329 * At any given point, like seem above, you'll be operating one rectangle only.
330 * Try stacking it below an adjacent object with "b":
331 * @skip evas_object_stack_below(d.rects[d.cur_rect], neighbour);
332 * @until evas_object_stack_below(d.rects[d.cur_rect], neighbour);
333 * @dontinclude evas-stacking.c
334 * "a" will do the opposite:
335 * @skip evas_object_stack_above(d.rects[d.cur_rect], neighbour);
336 * @until evas_object_stack_above(d.rects[d.cur_rect], neighbour);
337 * To bring it directly to the top/bottom, use "t"/"m", respectively:
338 * @dontinclude evas-stacking.c
339 * @skip evas_object_raise(d.rects[d.cur_rect]);
340 * @until evas_object_raise(d.rects[d.cur_rect]);
341 * @skip evas_object_lower(d.rects[d.cur_rect]);
342 * @until evas_object_lower(d.rects[d.cur_rect]);
343 * At any time, use the "s" command to see the status of the
344 * ordering. It will show the background's ordering too. Note that it
345 * also shows the @b layer for this object. It starts at a @b
346 * different layer than the others. Use "l" to change its layer
347 * (higher layer numbers mean higher layers). If the background is on
348 * the same layer as the others (0), you'll see it interact with them
349 * on the ordering. If it's in the layer above, no matter what you do,
350 * you'll see nothing but the white rectangle: it covers the other
351 * layers. For the initial layer (-1), it will never mess nor occlude
354 * The last two commands available are "p" and "r", which will make
355 * the target rectangle to @b pass (ignore) and @b repeat the mouse
356 * events occurring on it (the commands will cycle through on and off
357 * states). This is demonstrated with the following
358 * #EVAS_CALLBACK_MOUSE_DOWN callback, registered on each of the
359 * colored rectangles:
360 * @dontinclude evas-stacking.c
363 * Try to change these properties on the three rectangles while
364 * experimenting with mouse clicks on their intersection region.
366 * The full example follows.
368 * @include evas-stacking.c
369 * @example evas-stacking.c
373 * @page Example_Evas_Map_Overview Evas Map - Overview
374 * @dontinclude evas-map-utils.c
376 * Down to the very bottom, Map is simple: it takes an object and transforms
377 * the way it will be shown on screen. But using it properly can be a bit
380 * For the most common operations there are utility functions that help in
381 * setting up the map to achieve the desired effects. Now we'll go through
382 * an overview of the map API and some of the things that can be done with
385 * The full code can be found @ref evas-map-utils.c "here".
387 * To show how some funtions work, this example listens to keys pressed to
388 * toggle several options.
393 * In this program, we divide the window in four quadrants, each holding an
394 * object that will have different map configurations applied to them in each
395 * call to an animator function.
396 * @skip static Eina_Bool
397 * @until evas_output_size_get
399 * Let's first create a map and set some of our options to it. Only four
400 * points maps are supported, so we'll stick to that magic number. We can
401 * set a color for each vertex or apply one for all of them at once
402 * @until evas_map_util_points_color_set
404 * For the first object, we'll have a plain rectangle. At its cration, this
405 * rectangle was set to be semi-transparent, but whether its own alpha is
406 * used will be defined by the map's alpha setting. If the map's alpha is
407 * disabled, then the object will be completely opaque. The map's own color,
408 * however, will use any alpha set to it.
410 * So we get our object, initialize our map geometry to match the rectangle
411 * and make it rotate around its own center, then apply the map to the
412 * object so it takes effect.
413 * @until evas_object_map_enable_set
415 * The second object is an image. Here we don't have any color set for the
416 * object, but the image itself contains an alpha channel that will not be
417 * affected by the map settings, so even with alpha set to be off, the image
418 * will still be transparent. Color applied to the map will tint it though.
419 * Since setting a map copies it into the object, we can reuse the same one
420 * we created before. We initialize it to the new object while all other
421 * options are kept the same. Notice that no rotation will be done here, as
422 * that's just an utility function that takes the coordinates set for each
423 * point of the map and transforms it accordingly.
424 * @until evas_map_util_points_populate_from_object_full
426 * This time the object is a bit farther into the screen, by using a @c z
427 * value higher than 0 to init the map. We also need to map the image used
428 * by the object, so Evas knows how to transform it properly. For this we
429 * use the evas_map_point_image_uv_set() to tell the map what coordinate
430 * within the image corresponds to each point of the map.
431 * @until evas_map_point_image_uv_set(m, 3
433 * This object will also be rotated, but in all three axis and around some
434 * other point, not its center, chosen mostly at random. If enabled, lighting
435 * will be applied to, from a light source at the center of the window.
436 * @until evas_object_map_enable_set
438 * For the third object we are doing, once more, a 3D rotation, but this time
439 * perspective will be applied to our map to make it look more realistic.
440 * The lighting source also follows the mouse cursor and it's possible to
441 * toggle backface culling, so that the object is hidden whenever we are
442 * not seeing its front face.
443 * @until evas_object_map_enable_set
445 * And we free this map, since since we messed too much with it and for the
446 * last object we want something cleaner.
447 * @until evas_map_free
449 * The last object is actually two. One image, with an image set to it, and
450 * one image proxying the first one with evas_object_image_source_set(). This
451 * way, the second object will show whatever content its source has.
452 * This time we'll be using a map more manually to simulate a simple reflection
453 * of the original image.
455 * We know that the reflection object is placed just like the original, so
456 * we take a shortcut by just getting the geometry of our to-be-mapped object.
457 * We also need to get the image size of the source.
458 * @until evas_object_image_size_get
460 * For this we'll create a map shaped so that it begins at the base of our
461 * image and it expands horizontally as it grows (downwards) in height.
462 * @until evas_map_point_coord_set(m, 3
464 * Since the reflection should show the image inverted, we need to map it
465 * this way. The first point of the map (top-left) will be mapped to the
466 * mapped to the first pixel of the last row. There's no horizontal reflection
467 * and we want the full width of the image, but as we map its upper side ww
468 * will only take two thirds of the image.
469 * @until evas_map_point_image_uv_set(m, 3
471 * Finally, to fade out our reflection we set the colors for each point in
472 * the map. The two at the top need to be visible, but we'll tone them down
473 * a bit and make them a bit translucent. The other two will go straight to
474 * full transparency. Evas interpolates the colors from one point to the next,
475 * so this will make them fade out.
476 * @until evas_object_map_enable_set
478 * Close up by freeing the map and do some other things needed to keep stuff
479 * moving in our animations and we are done.
482 * The rest of the program is setup and listening to key events. Nothing that
483 * matters within the scope of this example, so we are going to skip it.
484 * Refer to it @ref evas-map-utils.c "here" however to see how everything
487 * @example evas-map-utils.c