2
* @page evas_examples Evas Examples
4
* Here is a page with examples.
6
* @ref Example_Evas_Buffer_Simple
8
* @ref Example_Evas_Init_Shutdown
10
* @ref Example_Evas_Text
12
* @ref Example_Evas_Images
14
* @ref Example_Evas_Images_2
16
* @ref Example_Evas_Events
18
* @ref Example_Evas_Object_Manipulation
20
* @ref Example_Evas_Aspect_Hints
22
* @ref Example_Evas_Size_Hints
24
* @ref Example_Evas_Stacking
26
* @ref Example_Evas_Smart_Objects
28
* @ref Example_Evas_Box Evas box
32
* @page Example_Evas_Buffer_Simple Simple Evas canvas example
34
* The canvas will here use the buffer engine.
36
* @include evas-buffer-simple.c
37
* @example evas-buffer-simple.c
41
* @page Example_Evas_Init_Shutdown Evas' init/shutdown routines example
43
* @include evas-init-shutdown.c
44
* @example evas-init-shutdown.c
48
* @page Example_Evas_Images Some image object functions examples
49
* @dontinclude evas-images.c
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
60
* @dontinclude evas-images.c
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.
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
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().
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.
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>.
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.
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
108
* The full example follows.
110
* @include evas-images.c
111
* @example evas-images.c
115
* @page Example_Evas_Images_2 Some more image object functions examples (2nd block)
116
* @dontinclude evas-images2.c
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
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->key, "p") == 0)
132
* Note the top right image, the smaller one:
133
* @dontinclude evas-images2.c
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
144
* @until define HEIGHT
145
* you can check this value.
147
* The image on the top left also has a subtlety: it is @b pre-loaded
149
* @dontinclude evas-images2.c
152
* On real use cases we wouldn't be just printing something like this
153
* @dontinclude evas-images2.c
158
* The 's' command will save one of the images on the disk, in the png
160
* @dontinclude evas-images2.c
161
* @skip if (strcmp(ev->key, "a") == 0)
164
* The full example follows.
166
* @include evas-images2.c
167
* @example evas-images2.c
171
* @page Example_Evas_Events Evas events (canvas and object ones) and some canvas operations example
172
* @dontinclude evas-events.c
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",
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.
186
* There's a global variable to aid accessing our desired context
187
* variables from anywhere in the code:
188
* @dontinclude evas-events.c
192
* What interests us there are the @c canvas pointer, our image handle
193
* -- @c img -- and the background one, @c bg.
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
202
* @dontinclude evas-events.c
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
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
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
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
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
235
* @dontinclude evas-events.c
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.
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
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
260
* @dontinclude evas-events.c
261
* @skip static const char *commands
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->key, "f") == 0)
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->key, "d") == 0)
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
282
* @dontinclude evas-events.c
283
* @skip examine the keys pressed
285
* We do so by examining the @c ev->key 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:
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->key, "p") == 0)
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
331
* What follows is the complete code for this example.
333
* @include evas-events.c
334
* @example evas-events.c
338
* @page Example_Evas_Object_Manipulation Evas objects basic manipulation example
340
* @include evas-object-manipulation.c
341
* @example evas-object-manipulation.c
345
* @page Example_Evas_Aspect_Hints Evas aspect hints example
347
* @include evas-aspect-hints.c
348
* @example evas-aspect-hints.c
352
* @page Example_Evas_Size_Hints Evas alignment, minimum size, maximum size, padding and weight hints example
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
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.
366
* More on this smart object can be found on @ref Example_Evas_Box.
367
* The full code for this example follows.
369
* @include evas-hints.c
370
* @example evas-hints.c
374
* @page Example_Evas_Box Evas box example
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.
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
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 accommodate its
397
* @dontinclude evas-box.c
398
* @skip adjust canvas' contents on resizes
401
* Again, one interacts with this program by means of key commands:
402
* @dontinclude evas-box.c
403
* @skip static const char *commands
406
* Let's start with the @b numeric ones, each of which will impose a
407
* different layout on the box object.
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:
413
* @image html evas-box-example-00.png
414
* @image rtf evas-box-example-00.png
415
* @image latex evas-box-example-00.eps
417
* The vertical layout (@c '2' key) is very similar, but just
418
* disposing the items vertically:
420
* @image html evas-box-example-01.png
421
* @image rtf evas-box-example-01.png
422
* @image latex evas-box-example-01.eps
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
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:
433
* @image html evas-box-example-02.png
434
* @image rtf evas-box-example-02.png
435
* @image latex evas-box-example-02.eps
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
446
* @image html evas-box-example-03.png
447
* @image rtf evas-box-example-03.png
448
* @image latex evas-box-example-03.eps
450
* The code for the commands inserting and deleting box items is:
451
* @dontinclude evas-box.c
452
* @skip mods, "Shift"
455
* @dontinclude evas-box.c
456
* @skip new rectangle to be put in the box
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
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
469
* @image html evas-box-example-04.png
470
* @image rtf evas-box-example-04.png
471
* @image latex evas-box-example-04.eps
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
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
481
* @dontinclude evas-box.c
484
* @dontinclude evas-box.c
485
* @skip custom 'diagonal' layout
489
* @image html evas-box-example-05.png
490
* @image rtf evas-box-example-05.png
491
* @image latex evas-box-example-05.eps
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.
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.
502
* @include evas-box.c
503
* @example evas-box.c
507
* @page Example_Evas_Stacking Evas object stacking functions (and some event handling)
508
* @dontinclude evas-stacking.c
510
* In this example, we illustrate how to stack objects in a custom
511
* manner and how to deal with layers.
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
522
* @skip static const char *commands
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
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:
553
* @image html evas-stacking-example-00.png
554
* @image rtf evas-stacking-example-00.png
555
* @image latex evas-stacking-example-00.eps
557
* Stack it one level below, with 'b', and you'll get:
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:
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:
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':
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:
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:
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:601
* @image html evas-stacking-example-07.png
602
* @image rtf evas-stacking-example-07.png
603
* @image latex evas-stacking-example-07.eps
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
614
* Try to change these properties on the three rectangles while
615
* experimenting with mouse clicks on their intersection region.
617
* The full example follows.
619
* @include evas-stacking.c
620
* @example evas-stacking.c
624
* @page Example_Evas_Map_Overview Evas Map - Overview
625
* @dontinclude evas-map-utils.c
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
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
636
* The full code can be found @ref evas-map-utils.c "here".
638
* To show how some functions work, this example listens to keys pressed to
639
* toggle several options.
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
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
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.
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
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
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
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
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
696
* And we free this map, since we messed too much with it and for the
697
* last object we want something cleaner.
698
* @until evas_map_free
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.
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
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
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
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
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.
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
738
* @example evas-map-utils.c
742
* @page Example_Evas_Smart_Objects Evas object smart objects
743
* @dontinclude evas-smart-object.c
745
* In this example, we illustrate how to create and handle Evas smart objects.
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.
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.
763
* Here is where we add it to the canvas:
764
* @skip d.smt = evas_smart_example_add(d.evas);
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
775
* - @c evas_smart_example_set_left(): set the left child of the smart
777
* - @c evas_smart_example_set_right(): set the right child of the
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
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.
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
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
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
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
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
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
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
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.
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
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.
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
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
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.
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 =
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
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.
926
* @include evas-smart-object.c
927
* @example evas-smart-object.c
931
* @page Example_Evas_Smart_Interfaces Evas object smart interfaces
932
* @dontinclude evas-smart-interface.c
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.
939
* A smart interface is just a functions interface a given smart
940
* object 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
* behavior beyond the sub-classing schema.
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.
951
* Here is where we declare our interface:
952
* @skip static const char iface1_data[]
953
* @until (Evas_Smart_Interface *)&iface1, NULL
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).
959
* Now note that here we are filling in the interface's fields dynamically.
960
* Let's move on to that code region:
962
* @dontinclude evas-smart-interface.c
963
* @skip iface = (Evas_Smart_Example_Interface *)&iface1;
964
* @until d.smt = evas_smart_example_add(d.evas);
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:
973
* @dontinclude evas-smart-interface.c
974
* @skip iface = (Evas_Smart_Example_Interface *)evas_object_smart_interface_get
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().
984
* The full example follows.
986
* @include evas-smart-interface.c
987
* @example evas-smart-interface.c
991
* @page Example_Evas_Text Evas text object example
993
* In this example, we illustrate how to use text objects in various
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
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().
1009
* Look at how it translates to code:
1010
* @dontinclude evas-text.c
1011
* @skip evas_object_text_add
1014
* Like in other Evas examples, one interacts with it by means of key
1016
* @dontinclude evas-text.c
1017
* @skip static const char *commands
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.
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:
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
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.
1040
* The full example follows.
1042
* @include evas-text.c
1043
* @example evas-text.c
1047
* @page tutorial_table Table Smart Object example
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.
1055
* We'll start with creating the table, setting it to
1056
* EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE to have maximum flexibility and setting
1058
* @dontinclude evas-table.c
1059
* @skip object_table
1062
* We then create each rectangle and add it to the table:
1067
* @note Each rectangle has a different minimum size based on how many rows and
1068
* columns it will occupy.
1070
* The full source for this example follow:
1071
* @include evas-table.c
1072
* @example evas-table.c