[elementary] Docs. for the progress bar widget.
[framework/uifw/elementary.git] / doc / examples.dox
1 /**
2  * @page Examples Examples
3  *
4  * Here is a page with Elementary examples.
5  *
6  * @ref bg_01_example_page
7  *
8  * @ref bg_02_example_page
9  *
10  * @ref bg_03_example_page
11  *
12  * @ref actionslider_example_page
13  *
14  * @ref elm_animator_example_page_01
15  *
16  * @ref transit_example_01_explained
17  *
18  * @ref transit_example_02_explained
19  *
20  * @ref general_functions_example_page
21  *
22  * @ref calendar_example_01
23  *
24  * @ref calendar_example_02
25  *
26  * @ref calendar_example_03
27  *
28  * @ref calendar_example_04
29  *
30  * @ref calendar_example_05
31  *
32  * @ref calendar_example_06
33  *
34  * @ref spinner_example
35  *
36  * @ref clock_example
37  *
38  * @ref diskselector_example_01
39  *
40  * @ref diskselector_example_02
41  *
42  * @ref list_example_01
43  *
44  * @ref list_example_02
45  *
46  * @ref list_example_03
47  *
48  * @ref flipselector_example
49  *
50  * @ref fileselector_example
51  *
52  * @ref fileselector_button_example
53  *
54  * @ref fileselector_entry_example
55  *
56  * @ref index_example_01
57  *
58  * @ref index_example_02
59  *
60  * @ref gengrid_example
61  *
62  * @ref genlist_example_01
63  *
64  * @ref genlist_example_02
65  *
66  * @ref progressbar_example
67  */
68
69 /**
70  * @page bg_01_example_page elm_bg - Plain color background.
71  * @dontinclude bg_example_01.c
72  *
73  * The full code for this example can be found at @ref bg_example_01_c,
74  * in the function @c test_bg_plain. It's part of the @c elementar_test
75  * suite, and thus has the code for the three examples referenced by this
76  * documentation.
77  *
78  * This first example just sets a default background with a plain color. The
79  * first part consists of creating an Elementary window. It's the common
80  * piece of code that you'll see everywhere in Elementary: @skip elm_main
81  * @until autodel_set
82  *
83  * Now we really create our background object, using the window object as
84  * its parent:
85  *
86  * @skipline bg_add
87  *
88  * Then we set the size hints of the background object so that it will use
89  * all space available for it, and then add it as a resize object to the
90  * window, making it visible in the end:
91  *
92  * @skip size_hint_weight_set
93  * @until resize_object_add
94  *
95  * See @ref evas_object_size_hint_weight_set and elm_win_resize_object_add()
96  * for more detailed info about these functions.
97  *
98  * The end of the example is quite simple, just setting the minimum and
99  * maximum size of the background, so the Elementary window knows that it
100  * has to have at least the minimum size. The background also won't scale to
101  * a size above its maximum. Then we resize the window and show it in the
102  * end:
103  *
104  * @skip set size hints
105  * @until }
106  *
107  * And here we finish our very simple background object usage example.
108  */
109
110 /**
111  * @page bg_02_example_page elm_bg - Image background.
112  * @dontinclude bg_example_02.c
113  *
114  * The full code for this example can be found at @ref bg_example_02_c,
115  * in the function @c test_bg_image. It's part of the @c elementar_test
116  * suite, and thus has the code for the three examples referenced by this
117  * documentation.
118  *
119  * This is the second example, and shows how to use the Elementary
120  * background object to set an image as background of your application.
121  *
122  * We start this example exactly in the same way as the previous one, even
123  * when creating the background object:
124  *
125  * @skip elm_main
126  * @until bg_add
127  *
128  * Now it's the different part.
129  *
130  * Our background will have an image, that will be displayed over the
131  * background color. Before loading the image, we set the load size of the
132  * image. The load size is a hint about the size that we want the image
133  * displayed in the screen. It's not the exact size that the image will have,
134  * but usually a bit bigger. The background object can still be scaled to a
135  * size bigger than the one set here. Setting the image load size to
136  * something smaller than its real size will reduce the memory used to keep
137  * the pixmap representation of the image, and the time to load it. Here we
138  * set the load size to 20x20 pixels, but the image is loaded with a size
139  * bigger than that (since it's just a hint):
140  *
141  * @skipline load_size_set
142  *
143  * And set our background image to be centered, instead of stretched or
144  * scaled, so the effect of the elm_bg_load_size_set() can be easily
145  * understood:
146  *
147  * @skipline option_set
148  *
149  * We need a filename to set, so we get one from the previous installed
150  * images in the @c PACKAGE_DATA_DIR, and write its full path to a buffer.
151  * Then we use this buffer to set the filename in the background object:
152  *
153  * @skip snprintf
154  * @until bg_file_set
155  *
156  * Notice that the third argument of the elm_bg_file_set() function is @c
157  * NULL, since we are setting an image to this background. This function
158  * also supports setting an edje group as background, in which case the @c
159  * group parameter wouldn't be @c NULL, but be the name of the group
160  * instead.
161  *
162  * Finally, we can set the size hints, add the background as a resize
163  * object, and resize the window, exactly the same thing we do in the @ref
164  * bg_01_example_page example:
165  *
166  * @skip size_hint
167  * @until }
168  *
169  * And this is the end of this example.
170  *
171  * This example will look like this:
172  *
173  * @image html screenshots/bg_01.png
174  * @image latex screenshots/bg_01.eps width=\textwidth
175  */
176
177 /**
178  * @page bg_03_example_page elm_bg - Background properties.
179  * @dontinclude bg_example_03.c
180  *
181  * The full code for this example can be found at @ref bg_example_03_c, in the
182  * function @c test_bg_options, with the callbacks @c _cb_overlay_changed, @c
183  * _cb_color_changed and @c _cb_radio_changed defined in the beginning of the
184  * file. It's part of the @c elementar_test suite, and thus has the code for
185  * the three examples referenced by this documentation.
186  *
187  * This example will show the properties available for the background object,
188  * and will use of some more widgets to set them.
189  *
190  * In order to do this, we will set some callbacks for these widgets. The
191  * first is for the radio buttons that will be used to choose the option
192  * passed as argument to elm_bg_option_set():
193  *
194  * @skip _cb_radio_changed
195  * @until }
196  *
197  * The next callback will be used when setting the overlay (using
198  * elm_bg_overlay_set()):
199  *
200  * @skip _cb_overlay_changed
201  * @until }
202  * @until }
203  *
204  * And the last one, used to set the color (with elm_bg_color_set()):
205  *
206  * @skip _cb_color_changed
207  * @until }
208  *
209  * We will get back to what these functions do soon. If you want to know more
210  * about how to set these callbacks and what these widgets are, look for:
211  * @li elm_radio_add()
212  * @li elm_check_add()
213  * @li elm_spinner_add()
214  *
215  * Now going to the main function, @c test_bg_options, we have the common
216  * code with the other examples:
217  *
218  * @skip bg-options
219  * @until autodel_set
220  *
221  * We add a plain background to this window, so it will have the default
222  * background color behind everything:
223  *
224  * @skip bg = elm_bg_add
225  * @until evas_object_show(bg)
226  *
227  * Then we add a vertical box (elm_box_add()) that will hold the background
228  * object that we are going to play with, as well as a horizontal box that
229  * will hold widgets:
230  *
231  * @skip elm_box_add
232  * @until evas_object_show
233  *
234  * Now we add the background object that is going to be of use for our
235  * example. It is an image background, as used in @ref bg_02_example_page ,
236  * so the code should be familiar:
237  *
238  * @skip elm_bg_add
239  * @until evas_object_show
240  *
241  * Notice the call to elm_box_pack_end(): it will pack the background object
242  * in the end of the Elementary box declared above. Just refer to that
243  * documentation for more info.
244  *
245  * Since this Elementary background is already an image background, we are
246  * going to play with its other properties. We will change its option
247  * (CENTER, SCALE, STRETCH, TILE), its color (RGB), and add an overlay to it.
248  * For all of these properties, we are going to add widgets that will
249  * configure them.
250  *
251  * First, lets add the horizontal box that will hold these widgets:
252  * @skip hbox
253  * @until align_set
254  *
255  * For now, just consider this @c hbox as a rectangle that will contain the
256  * widgets, and will distribute them horizontally inside its content. Then we
257  * add radio buttons that will allow us to choose the property to use with
258  * this background:
259  *
260  * @skip radio_add
261  * @until evas_object_show
262  *
263  * Again, I won't give details about the use of these widgets, just look for
264  * their documentation if necessary. It's enough to know for now that we are
265  * packing them in the @c hbox, setting a label for them, and the most
266  * important parts: setting its value to @c ELM_BG_OPTION_CENTER and its
267  * callback to @c _cb_radio_changed (the function defined in the beginning of
268  * this example). We do this for the next 3 radio buttons added after this
269  * one, each of them with a different value.
270  *
271  * Now taking a look at the code of the callback @c _cb_radio_changed again,
272  * it will call elm_bg_option_set() with the value set from the checked radio
273  * button, thus setting the option for this background. The background is
274  * passed as argument to the @p data parameter of this callback, and is
275  * referenced here as @c o_bg.
276  *
277  * Later we set the default value for this radio button:
278  *
279  * @skipline elm_radio_value_set
280  *
281  * Then we add a checkbox for the elm_bg_overlay_set() function:
282  *
283  * @skip check_add
284  * @until evas_object_show
285  *
286  * Now look at the code of the @c _cb_overlay_changed again. If the checkbox
287  * state is checked, an overlay will be added to the background. It's done by
288  * creating an Edje object, and setting it with elm_bg_overlay_set() to the
289  * background object. For information about what are and how to set Edje
290  * object, look at the Edje documentation.
291  *
292  * Finally we add a spinner object (elm_spinner_add()) to be used to select
293  * the color of our background. In its callback it's possible to see the call
294  * to elm_bg_color_set(), which will change the color of this background.
295  * This color is used by the background to fill areas where the image doesn't
296  * cover (in this case, where we have an image background). The spinner is
297  * also packed into the @c hbox :
298  *
299  * @skip elm_spinner_add
300  * @until evas_object_show
301  *
302  * Then we just have to pack the @c hbox inside the @c box, set some size
303  * hints, and show our window:
304  *
305  * @skip pack_end
306  * @until }
307  *
308  * Now to see this code in action, open elementary_test, and go to the "Bg
309  * Options" test. It should demonstrate what was implemented here.
310  */
311
312 /**
313  * @page actionslider_example_page Actionslider usage
314  * @dontinclude actionslider_example_01.c
315  *
316  * For this example we are going to assume knowledge of evas smart callbacks
317  * and some basic evas object functions. Elementary is not meant to be used
318  * without evas, if you're not yet familiar with evas it probably is worth
319  * checking that out.
320  *
321  * And now to the example, when using Elementary we start by including
322  * Elementary.h:
323  * @skipline #include
324  *
325  * Next we define some callbacks, they all share the same signature because
326  * they are all to be used with evas_object_smart_callback_add().
327  * The first one just prints the selected label(in two different ways):
328  * @until }
329  *
330  * This next callback is a little more interesting, it makes the selected
331  * label magnetic(except if it's the center label):
332  * @until }
333  *
334  * This callback enables or disables the magnetic propertty of the center
335  * label:
336  * @until }
337  *
338  * And finally a callback to stop the main loop when the window is closed:
339  * @until }
340  *
341  * To be able to create our actionsliders we need to do some setup, but this
342  * isn't really relevant here, so if you want to know about that go @ref
343  * Win "here".
344  *
345  * With all that boring stuff out of the way we can proceed to creating some
346  * actionsliders.@n
347  * All actionsliders are created the same way:
348  * @skipline actionslider_add
349  * Next we must choose where the indicator starts, and for this one we choose
350  * the right, and set the right as magnetic:
351  * @skipline indicator_pos_set
352  * @until magnet_pos_set
353  *
354  * We then set the labels for the left and right, passing NULL as an argument
355  * to any of the labels makes that position have no label.
356  * @until Stop
357  *
358  * Furthermore we mark both left and right as enabled positions, if we didn't
359  * do this all three positions would be enabled:
360  * @until RIGHT
361  *
362  * Having the the enabled positions we now add a smart callback to change
363  * which position is magnetic, so that only the last selected position is
364  * magnetic:
365  * @until NULL
366  *
367  * And finally we set our printing callback and show the actionslider:
368  * @until object_show
369  * @skip pack_end
370  *
371  * For our next actionslider we are going to do much as we did for the
372  * previous except we are going to have the center as the magnet(and not
373  * change it):
374  * @skipline actionslider_add
375  * @skipline indicator_pos_set
376  * @until object_show
377  *
378  * And another actionslider, in this one the indicator starts on the left.
379  * It has labels only in the center and right, and both bositions are
380  * magnetic. Because the left doesn't have a label and is not magnetic once
381  * the indicator leaves it can't return:
382  * @skipline actionslider_add
383  * @skipline indicator_pos_set
384  * @until object_show
385  * @note The greyed out area is a @ref Styles "style".
386  *
387  * And now an actionslider with a label in the indicator, and whose magnet
388  * properties change based on what was last selected:
389  * @skipline actionslider_add
390  * @skipline indicator_pos_set
391  * @until object_show
392  * @note The greyed out area is a @ref Styles "style".
393  *
394  * We are almost done, this next one is just an actionslider with all
395  * positions magnetized and having every possible label:
396  * @skipline actionslider_add
397  * @skipline indicator_pos_set
398  * @until object_show
399  *
400  * And for our last actionslider we have one that turns the magnetic property
401  * on and off:
402  * @skipline actionslider_add
403  * @skipline indicator_pos_set
404  * @until object_show
405  *
406  * The example will look like this:
407  *
408  * @image html screenshots/actionslider_01.png
409  * @image latex screenshots/actionslider_01.eps width=\textwidth
410  *
411  * See the full source code @ref actionslider_example_01 "here"
412  */
413
414 /**
415  * @page elm_animator_example_page_01 Animator usage
416  * @dontinclude animator_example_01.c
417  *
418  * For this example we will be using a bit of evas, you could animate a
419  * elementary widget in much the same way, but to keep things simple we use
420  * an evas_object_rectangle.
421  *
422  * As every other example we start with our include and a simple callback to
423  * exit the app when the window is closed:
424  * @skipline #include
425  * @until }
426  *
427  * This next callback is the one that actually creates our animation, it
428  * changes the size, position and color of a rectangle given to it in @a
429  * data:
430  * @until }
431  *
432  * Next we have a callback that prints a string, nothing special:
433  * @until }
434  *
435  * This next callback is a little more interesting, it has a state variable
436  * to know if the animation is currently paused or running, and it toogles
437  * the state of the animation accordingly:
438  * @until }
439  * @until }
440  * @until }
441  *
442  * Finally we have a callback to stop the animation:
443  * @until }
444  *
445  * As with every example we need to do a bit of setup before we can actually
446  * use an animation, but for the purposes of this example that's not relevant
447  * so let's just skip to the good stuff, creating an animator:
448  * @skipline animator_add
449  * @note Since elm_animator is not a widget we can give it a NULL parent.
450  *
451  * Now that we have an elm_animator we set it's duration to 1 second:
452  * @line duration_set
453  *
454  * We would also like our animation to be reversible, so:
455  * @line reverse_set
456  *
457  * We also set our animation to repeat as many times as possible, which will
458  * mean that _end_cb will only be called after UINT_MAX * 2 seconds(UINT_MAX
459  * for the animation running forward and UNIT_MAX for the animation running
460  * backwards):
461  * @line repeat_set
462  *
463  * To add some fun to our animation we will use the IN_OUT curve style:
464  * @line curve_style
465  *
466  * To actually animate anything we need an operation callback:
467  * @line operation_callback
468  *
469  * Even though we set our animation to repeat for a very long time we are
470  * going to set a end callback to it:
471  * @line completion_callback
472  * @note Notice that stoping the animation with the stop button will not make
473  * _end_cb be called.
474  *
475  * Now that we have fully set up our animator we can tell it to start
476  * animating:
477  * @line animate
478  *
479  * There's a bit more of code that doesn't really matter to use so we skip
480  * right down to our last interesting point:
481  * @skipline animator_del
482  * @note Because we created our animator with no parent we need to delete it
483  * ourselves.
484  *
485  * The example should look like this:
486  *
487  * @image html screenshots/animator_example_01.png
488  * @image latex screenshots/animator_example_01.eps width=\textwidth
489  * @n
490  * @image html screenshots/animator_example_02.png
491  * @image latex screenshots/animator_example_02.eps width=\textwidth
492  * @n
493  * @image html screenshots/animator_example_03.png
494  * @image latex screenshots/animator_example_03.eps width=\textwidth
495  *
496  * The full source code for this example can be found @ref
497  * animator_example_01_c "here"
498  */
499
500 /**
501  * @page transit_example_03_c elm_transit - Combined effects and options.
502  *
503  * This example shows how to apply the following transition effects:
504  * @li translation
505  * @li color
506  * @li rotation
507  * @li wipe
508  * @li zoom
509  * @li resizing
510  *
511  * It allows you to apply more than one effect at once, and also allows to
512  * set properties like event_enabled, auto_reverse, repeat_times and
513  * tween_mode.
514  *
515  * @include transit_example_03.c
516  */
517
518 /**
519  * @page transit_example_04_c elm_transit - Combined effects over two objects.
520  *
521  * This example shows how to apply the transition effects:
522  * @li flip
523  * @li resizable_flip
524  * @li fade
525  * @li blend
526  * over two objects. This kind of transition effect is used to make one
527  * object disappear and another one appear on its place.
528  *
529  * You can mix more than one effect of this type on the same objects, and the
530  * transition will apply both.
531  *
532  * @include transit_example_04.c
533  */
534
535 /**
536  * @page transit_example_01_explained elm_transit - Basic transit usage.
537  * @dontinclude transit_example_01.c
538  *
539  * The full code for this example can be found at @ref transit_example_01_c.
540  *
541  * This example shows the simplest way of creating a transition and applying
542  * it to an object. Similarly to every other elementary example, we create a
543  * window, set its title, size, autodel property, and setup a callback to
544  * exit the program when finished:
545  *
546  * @skip on_done
547  * @until evas_object_resize
548  *
549  * We also add a resizeable white background to use behind our animation:
550  *
551  * @skip bg_add
552  * @until evas_object_show
553  *
554  * And then we add a button that we will use to demonstrate the effects of
555  * our animation:
556  *
557  * @skip button_add
558  * @until evas_object_show(win)
559  *
560  * Notice that we are not adding the button with elm_win_resize_object_add()
561  * because we don't want the window to control the size of the button. We
562  * will use the transition to change the button size, so it could conflict
563  * with something else trying to control that size.
564  *
565  * Now, the simplest code possible to create the resize animation:
566  *
567  * @skip transit_add
568  * @until transit_go
569  *
570  * As you can see, this code is very easy to understand. First, we create the
571  * transition itself with elm_transit_add(). Then we add the button to this
572  * transition with elm_transit_object_add(), which means that the transition
573  * will operate over this button. The effect that we want now is changing the
574  * object size from 100x50 to 300x150, and can be achieved by adding the
575  * resize effect with elm_transit_effect_resizing_add().
576  *
577  * Finally, we set the transition time to 5 seconds and start the transition
578  * with elm_transit_go(). If we wanted more effects applied to this
579  * button, we could add them to the same transition. See the
580  * @ref transit_example_03_c to watch many transitions being applied to an
581  * object.
582  */
583
584 /**
585  * @page transit_example_02_explained elm_transit - Chained transitions.
586  * @dontinclude transit_example_02.c
587  *
588  * The full code for this example can be found at @ref transit_example_02_c.
589  *
590  * This example shows how to implement a chain of transitions. This chain is
591  * used to start a transition just after another transition ended. Similarly
592  * to every other elementary example, we create a window, set its title,
593  * size, autodel property, and setup a callback to exit the program when
594  * finished:
595  *
596  * @skip on_done
597  * @until evas_object_resize
598  *
599  * We also add a resizeable white background to use behind our animation:
600  *
601  * @skip bg_add
602  * @until evas_object_show
603  *
604  * This example will have a chain of 4 transitions, each of them applied to
605  * one button. Thus we create 4 different buttons:
606  *
607  * @skip button_add
608  * @until evas_object_show(bt4)
609  *
610  * Now we create a simple translation transition that will be started as soon
611  * as the program loads. It will be our first transition, and the other
612  * transitions will be started just after this transition ends:
613  *
614  * @skip transit_add
615  * @until transit_go
616  *
617  * The code displayed until now has nothing different from what you have
618  * already seen in @ref transit_example_01_explained, but now comes the new
619  * part: instead of creating a second transition that will start later using
620  * a timer, we create the it normally, and use
621  * elm_transit_chain_transit_add() instead of elm_transit_go. Since we are
622  * adding it in a chain after the first transition, it will start as soon as
623  * the first transition ends:
624  *
625  * @skip transit_add
626  * @until transit_chain_transit_add
627  *
628  * Finally we add the 2 other transitions to the chain, and run our program.
629  * It will make one transition start after the other finish, and there is the
630  * transition chain.
631  */
632
633 /**
634  * @page general_functions_example_page General (top-level) functions example
635  * @dontinclude general_funcs_example.c
636  *
637  * As told in their documentation blocks, the
638  * elm_app_compile_*_dir_set() family of functions have to be called
639  * before elm_app_info_set():
640  * @skip tell elm about
641  * @until elm_app_info_set
642  *
643  * We are here setting the fallback paths to the compiling time target
644  * paths, naturally. If you're building the example out of the
645  * project's build system, we're assuming they are the canonical ones.
646  *
647  * After the program starts, elm_app_info_set() will actually run and
648  * then you'll see an intrincasy: Elementary does the prefix lookup @b
649  * twice. This is so because of the quicklaunch infrastructure in
650  * Elementary (@ref Start), which will register a predefined prefix
651  * for possible users of the launch schema. We're not hooking into a
652  * quick launch, so this first call can't be avoided.
653  *
654  * If you ran this example from your "bindir" installation
655  * directiory, no output will emerge from these both attempts -- it
656  * will find the "magic" file there registered and set the prefixes
657  * silently. Otherwise, you could get something like:
658  @verbatim
659  WARNING: Could not determine its installed prefix for 'ELM'
660        so am falling back on the compiled in default:
661          usr
662        implied by the following:
663          bindir    = usr/lib
664          libdir    = usr/lib
665          datadir   = usr/share/elementary
666          localedir = usr/share/locale
667        Try setting the following environment variables:
668          ELM_PREFIX     - points to the base prefix of install
669        or the next 4 variables
670          ELM_BIN_DIR    - provide a specific binary directory
671          ELM_LIB_DIR    - provide a specific library directory
672          ELM_DATA_DIR   - provide a specific data directory
673          ELM_LOCALE_DIR - provide a specific locale directory
674  @endverbatim
675  * if you also didn't change those environment variables (remember
676  * they are also a valid way of communicating your prefix to the
677  * binary) - this is the scenario where it fallbacks to the paths set
678  * for compile time.
679  *
680  * Then, you can check the prefixes set on the standard output:
681  * @skip prefix was set to
682  * @until locale directory is
683  *
684  * In the fragment
685  * @skip by using this policy
686  * @until elm_win_autodel_set
687  * we demonstrate the use of Elementary policies. The policy defining
688  * under which circunstances our application should quit automatically
689  * is set to when its last window is closed (this one has just one
690  * window, though). This will save us from having to set a callback
691  * ourselves on the window, like done in @ref bg_example_01_c "this"
692  * example. Note that we need to tell the window to delete itself's
693  * object on a request to destroy the canvas coming, with
694  * elm_win_autodel_set().
695  *
696  * What follows is some boilerplate code, creating a frame with a @b
697  * button, our object of interest, and, below, widgets to change the
698  * button's behavior and exemplify the group of functions in question.
699  *
700  * @dontinclude general_funcs_example.c
701  * We enabled the focus highlight object for this window, so that you
702  * can keep track of the current focused object better:
703  * @skip elm_win_focus_highlight_enabled_set
704  * @until evas_object_show
705  * Use the tab key to navigate through the focus chain.
706  *
707  * @dontinclude general_funcs_example.c
708  * While creating the button, we exemplify how to use Elementary's
709  * finger size information to scale our UI:
710  * @skip fprintf(stdout, "Elementary
711  * @until evas_object_show
712  *
713  * @dontinclude general_funcs_example.c
714  * The first checkbox's callback is:
715  * @skip static void
716  * @until }
717  * When unsetting the checkbox, we disable the button, which will get a new
718  * decoration (greyed out) and stop receiving events. The focus chain
719  * will also ignore it.
720  *
721  * Following, there are 2 more buttons whose actions are focus/unfocus
722  * the top button, respectively:
723  * @skip focus callback
724  * @until }
725  * and
726  * @skip unfocus callback
727  * @until }
728  * Note the situations in which they won't take effect:
729  * - the button is not allowed to get focus or
730  * - the button is disabled
731  *
732  * The first restriction above you'll get by a second checkbox, whose
733  * callback is:
734  * @skip focus allow callback
735  * @until }
736  * Note that the button will still get mouse events, though.
737  *
738  * Next, there's a slider controlling the button's scale:
739  * @skip scaling callback
740  * @until }
741  *
742  * Experiment with it, so you understand the effect better. If you
743  * change its value, it will mess with the button's original size,
744  * naturally.
745  *
746  * The full code for this example can be found
747  * @ref general_functions_example_c "here".
748  */
749
750 /**
751  * @page theme_example_01 Theme - Using extensions
752  *
753  * @dontinclude theme_example_01.c
754  *
755  * Using extensions is extremely easy, discarding the part where you have to
756  * write the theme for them.
757  *
758  * In the following example we'll be creating two buttons, one to load or
759  * unload our extension theme and one to cycle around three possible styles,
760  * one of which we created.
761  *
762  * After including our one and only header we'll jump to the callback for
763  * the buttons. First one takes care of loading or unloading our extension
764  * file, relative to the default theme set (thus the @c NULL in the
765  * functions first parameter).
766  * @skipline Elementary.h
767  * @skip static void
768  * @until }
769  * @until }
770  * @until }
771  *
772  * The second button, as we said before, will just switch around different
773  * styles. In this case we have three of them. The first one is our custom
774  * style, named after something very unlikely to find in the default theme.
775  * The other two styles are the standard and one more, anchor, which exists
776  * in the default and is similar to the default, except the button vanishes
777  * when the mouse is not over it.
778  * @skip static void
779  * @until }
780  * @until }
781  *
782  * So what happens if the style switches to our custom one when the
783  * extension is loaded? Elementary falls back to the default for the
784  * widget.
785  *
786  * And the main function, simply enough, will create the window, set the
787  * buttons and their callbacks, and just to begin with our button styled
788  * we're also loading our extension at the beginning.
789  * @skip int
790  * @until ELM_MAIN
791  *
792  * In this case we wanted to easily remove extensions, but all adding an
793  * extension does is tell Elementary where else it should look for themes
794  * when it can't find them in the default theme. Another way to do this
795  * is to set the theme search order using elm_theme_set(), but this requires
796  * that the developer is careful not to override any user configuration.
797  * That can be helped by adding our theme to the end of whatver is already
798  * set, like in the following snippet.
799  * @code
800  * char buf[4096];
801  * snprintf(buf, sizeof(buf), "%s:./theme_example.edj", elme_theme_get(NULL);
802  * elm_theme_set(NULL, buf);
803  * @endcode
804  *
805  * If we were using overlays instead of extensions, the same thing applies,
806  * but the custom theme must be added to the front of the search path.
807  *
808  * In the end, we should be looking at something like this:
809  *
810  * @image html screenshots/theme_example_01.png
811  * @image latex screenshots/theme_example_01.eps width=\textwidth
812  *
813  * That's all. Boringly simple, and the full code in one piece can be found
814  * @ref theme_example_01.c "here".
815  *
816  * And the code for our extension is @ref theme_example.edc "here".
817  *
818  * @example theme_example_01.c
819  * @example theme_example.edc
820  */
821
822 /**
823  * @page theme_example_02 Theme - Using overlays
824  *
825  * @dontinclude theme_example_02.c
826  *
827  * Overlays are like extensions in that you tell Elementary that some other
828  * theme contains the styles you need for your program. The difference is that
829  * they will be look in first, so they can override the default style of any
830  * widget.
831  *
832  * There's not much to say about them that hasn't been said in our previous
833  * example about @ref theme_example_01 "extensions", so going quickly through
834  * the code we have a function to load or unload the theme, which will be
835  * called when we click any button.
836  * @skipline Elementary.h
837  * @skip static void
838  * @until }
839  *
840  * And the main function, creating the window and adding some buttons to it.
841  * We load our theme as an overlay and nothing else. Notice there's no style
842  * set for any button there, which means they should be using the default
843  * that we override.
844  * @skip int
845  * @until ELM_MAIN
846  *
847  * That's pretty much it. The full code is @ref theme_example_02.c "here" and
848  * the definition of the theme is the same as before, and can be found in
849  * @ref theme_example.edc "here".
850  *
851  * @example theme_example_02.c
852  */
853
854  /**
855   * @page button_example_01 Button - Complete example
856   *
857   * @dontinclude button_example_01.c
858   *
859   * A button is simple, you click on it and something happens. That said,
860   * we'll go through an example to show in detail the button API less
861   * commonly used.
862   *
863   * In the end, we'll be presented with something that looks like this:
864   *
865   * @image html screenshots/button_01.png
866   * @image latex screenshots/button_01.eps width=\textwidth
867   *
868   * The full code of the example is @ref button_example_01.c "here" and we
869   * will follow here with a rundown of it.
870   *
871   * @skip Elementary.h
872   * @until Elementary.h
873   * @skip struct
874   * @until App_Data
875   *
876   * We have several buttons to set different times for the autorepeat timeouts
877   * of the buttons that use it and a few more that we keep track of in our
878   * data struct. The mid button doesn't do much, just moves around according
879   * to what other buttons the user presses. Then four more buttons to move the
880   * central one, and we're also keeping track of the icon set in the middle
881   * button, since when this one moves, we change the icon, and when movement
882   * is finished (by releasing one of the four arrow buttons), we set back the
883   * normal icon.
884   * @skip static void
885   * @until }
886   *
887   * Keeping any of those four buttons pressed will trigger their autorepeat
888   * callback, where we move the button doing some size hint magic. To
889   * understand how that works better, refer to the @ref Box documentation.
890   * Also, the first time the function is called, we change the icon in the
891   * middle button, using elm_button_icon_unset() first to keep the reference
892   * to the previous one, so we don't need to recreate it when we are done
893   * moving it.
894   * @skip static void
895   * @until }
896   * @until size_hint_align_set
897   * @until }
898   *
899   * One more callback for the option buttons, that just sets the timeouts for
900   * the different autorepeat options.
901   *
902   * @skip static void
903   * @until }
904   * @until }
905   * @until }
906   *
907   * And the main function, which does some setting up of the buttons in boxes
908   * to make things work. Here we'll go through some snippets only.
909   *
910   * For the option buttons, it's just the button with its label and callback.
911   * @skip elm_button_add
912   * @until smart_callback_add
913   *
914   * For the ones that move the central button, we have no labels. There are
915   * icons instead, and the autorepeat option is toggled.
916   * @skip Gap: 1.0
917   * @skip elm_button_add
918   * @until data.cursors.up
919   *
920   * And just to show the mid button, which doesn't have anything special.
921   * @skip data.cursors.left
922   * @skip elm_button_add
923   * @until data.mid
924   *
925   * And we are done.
926   *
927   * @example button_example_01.c
928   */
929
930 /**
931  * @page bubble_01_example_page elm_bubble - Simple use.
932  * @dontinclude bubble_example_01.c
933  *
934  * This example shows a bubble with all fields set(label, info, content and
935  * icon) and the selected corner changing when the bubble is clicked. To be
936  * able use a bubble we need to do some setup and create a window, for this
937  * example we are going to ignore that part of the code since it isn't
938  * relevant to the bubble.
939  *
940  * To have the selected corner change in a clockwise motion we are going to
941  * use the following callback:
942  * @skip static
943  * @until }
944  * @until }
945  *
946  * Here we are creating an elm_label that is going to be used as the content
947  * for our bubble:
948  * @skipline elm_label
949  * @until show
950  * @note You could use any evas_object for this, we are using an elm_label
951  * for simplicity.
952  *
953  * Despite it's name the bubble's icon doesn't have to be an icon, it can be
954  * any evas_object. For this example we are going to make the icon a simple
955  * blue rectangle:
956  * @until show
957  *
958  * And finally we have the actual bubble creation and the setting of it's
959  * label, info and content:
960  * @until content
961  * @skipline show
962  * @note Because we didn't set a corner, the default("top_left") will be
963  * used.
964  *
965  * Now that we have our bubble all that is left is connecting the "clicked"
966  * signals to our callback:
967  * @line smart_callback
968  *
969  * This last bubble we created was very complete, so it's pertinent to show
970  * that most of that stuff is optional a bubble can be created with nothing
971  * but content:
972  * @until content
973  * @skipline show
974  *
975  * Our example will look like this:
976  *
977  * @image html screenshots/bubble_example_01.png
978  * @image latex screenshots/bubble_example_01.eps width=\textwidth
979  *
980  * See the full source code @ref bubble_example_01.c here.
981  * @example bubble_example_01.c
982  */
983
984 /**
985  * @page box_example_01 Box - Basic API
986  *
987  * @dontinclude button_example_01.c
988  *
989  * As a special guest tonight, we have the @ref button_example_01 "simple
990  * button example". There are plenty of boxes in it, and to make the cursor
991  * buttons that moved a central one around when pressed, we had to use a
992  * variety of values for their hints.
993  *
994  * To start, let's take a look at the handling of the central button when
995  * we were moving it around. To achieve this effect without falling back to
996  * a complete manual positioning of the @c Evas_Object in our canvas, we just
997  * put it in a box and played with its alignment within it, as seen in the
998  * following snippet of the callback for the pressed buttons.
999  * @skip evas_object_size_hint_align_get
1000  * @until evas_object_size_hint_align_set
1001  *
1002  * Not much to it. We get the current alignment of the object and change it
1003  * by just a little, depending on which button was pressed, then set it
1004  * again, making sure we stay within the 0.0-1.0 range so the button moves
1005  * inside the space it has, instead of disappearing under the other objects.
1006  *
1007  * But as useful as an example as that may have been, the usual case with boxes
1008  * is to set everything at the moment they are created, like we did for
1009  * everything else in our main function.
1010  *
1011  * The entire layout of our program is made with boxes. We have one set as the
1012  * resize object for the window, which means it will always be resized with
1013  * the window. The weight hints set to @c EVAS_HINT_EXPAND will tell the
1014  * window that the box can grow past it's minimum size, which allows resizing
1015  * of it.
1016  * @skip elm_main
1017  * @skip elm_box_add
1018  * @until evas_object_show
1019  *
1020  * Two more boxes, set to horizontal, hold the buttons to change the autorepeat
1021  * configuration used by the buttons. We create each to take over all the
1022  * available space horizontally, but we don't want them to grow vertically,
1023  * so we keep that axis of the weight with 0.0. Then it gets packed in the
1024  * main box.
1025  * @skip box2
1026  * @until evas_object_show
1027  *
1028  * The buttons in each of those boxes have nothing special, they are just packed
1029  * in with their default values and the box will use their minimum size, as set
1030  * by Elementary itself based on the label, icon, finger size and theme.
1031  *
1032  * But the buttons used to move the central one have a special disposition.
1033  * The top one first, is placed right into the main box like our other smaller
1034  * boxes. Set to expand horizontally and not vertically, and in this case we
1035  * also tell it to fill that space, so it gets resized to take the entire
1036  * width of the window.
1037  * @skip Gap: 1.0
1038  * @skip elm_button_add
1039  * @until evas_object_show
1040  *
1041  * The bottom one will be the same, but for the other two we need to use a
1042  * second box set to take as much space as we have, so we can place our side
1043  * buttons in place and have the big empty space where the central button will
1044  * move.
1045  * @skip elm_box_add
1046  * @until evas_object_show
1047  *
1048  * Then the buttons will have their hints inverted to the other top and bottom
1049  * ones, to expand and fill vertically and keep their minimum size horizontally.
1050  * @skip elm_button_add
1051  * @until evas_object_show
1052  *
1053  * The central button takes every thing else. It will ask to be expanded in
1054  * both directions, but without filling its cell. Changing its alignment by
1055  * pressing the buttons will make it move around.
1056  * @skip elm_button_add
1057  * @until evas_object_show
1058  *
1059  * To end, the rightmost button is packed in the smaller box after the central
1060  * one, and back to the main box we have the bottom button at the end.
1061  */
1062
1063 /**
1064  * @page box_example_02 Box - Layout transitions
1065  *
1066  * @dontinclude box_example_02.c
1067  *
1068  * Setting a customized layout for a box is simple once you have the layout
1069  * function, which is just like the layout function for @c Evas_Box. The new
1070  * and fancier thing we can do with Elementary is animate the transition from
1071  * one layout to the next. We'll see now how to do that through a simple
1072  * example, while also taking a look at some of the API that was left
1073  * untouched in our @ref box_example_01 "previous example".
1074  *
1075  * @image html screenshots/box_example_02.png
1076  * @image latex screenshots/box_example_02.eps width=\textwidth
1077  *
1078  * @skipline Elementary.h
1079  *
1080  * Our application data consists of a list of layout functions, given by
1081  * @c transitions. We'll be animating through them throughout the entire run.
1082  * The box with the stuff to move around and the last layout that was set to
1083  * make things easier in the code.
1084  * @skip typedef
1085  * @until Transitions_Data
1086  *
1087  * The box starts with three buttons, clicking on any of them will take it
1088  * out of the box without deleting the object. There are also two more buttons
1089  * outside, one to add an object to the box and the other to clear it.
1090  * This is all to show how you can interact with the items in the box, add
1091  * things and even remove them, while the transitions occur.
1092  *
1093  * One of the callback we'll be using creates a new button, asks the box for
1094  * the list of its children and if it's not empty, we add the new object after
1095  * the first one, otherwise just place at the end as it will not make any
1096  * difference.
1097  * @skip static void
1098  * @until }
1099  * @until }
1100  *
1101  * The clear button is even simpler. Everything in the box will be deleted,
1102  * leaving it empty and ready to fill it up with more stuff.
1103  * @skip static void
1104  * @until }
1105  *
1106  * And a little function to remove buttons from the box without deleting them.
1107  * This one is set for the @c clicked callback of the original buttons,
1108  * unpacking them when clicked and placing it somewhere in the screen where
1109  * they will not disturb. Once we do this, the box no longer has any control
1110  * of it, so it will be left untouched until the program ends.
1111  * @skip static void
1112  * @until }
1113  *
1114  * If we wanted, we could just call @c evas_object_del() on the object to
1115  * destroy it. In this case, no unpack is really necessary, as the box would
1116  * be notified of a child being deleted and adjust its calculations accordingly.
1117  *
1118  * The core of the program is the following function. It takes whatever
1119  * function is first on our list of layouts and together with the
1120  * @c last_layout, it creates an ::Elm_Box_Transition to use with
1121  * elm_box_layout_transition(). In here, we tell it to start from whatever
1122  * layout we last set, end with the one that was at the top of the list and
1123  * when everything is finished, call us back so we can create another
1124  * transition. Finally, move the new layout to the end of the list so we
1125  * can continue running through them until the program ends.
1126  * @skip static void
1127  * @until }
1128  *
1129  * The main function doesn't have antyhing special. Creation of box, initial
1130  * buttons and some callback setting. The only part worth mentioning is the
1131  * initialization of our application data.
1132  * @skip tdata.box
1133  * @until evas_object_box_layout_stack
1134  *
1135  * We have a simple static variable, set the box, the first layout we are
1136  * using as last and create the list with the different functions to go
1137  * through.
1138  *
1139  * And in the end, we set the first layout and call the same function we went
1140  * through before to start the run of transitions.
1141  * @until _test_box_transition_change
1142  *
1143  * For the full code, follow @ref box_example_02.c "here".
1144  *
1145  * @example box_example_02.c
1146  */
1147
1148 /**
1149  * @page calendar_example_01 Calendar - Simple creation.
1150  * @dontinclude calendar_example_01.c
1151  *
1152  * As a first example, let's just display a calendar in our window,
1153  * explaining all steps required to do so.
1154  *
1155  * First you should declare objects we intend to use:
1156  * @skipline Evas_Object
1157  *
1158  * Then a window is created, a title is set and its set to be autodeleted.
1159  * More details can be found on windows examples:
1160  * @until elm_win_autodel
1161  *
1162  * Next a simple background is placed on our windows. More details on
1163  * @ref bg_01_example_page:
1164  * @until evas_object_show(bg)
1165  *
1166  * Now, the exciting part, let's add the calendar with elm_calendar_add(),
1167  * passing our window object as parent.
1168  * @until evas_object_show(cal);
1169  *
1170  * To conclude our example, we should show the window and run elm mainloop:
1171  * @until ELM_MAIN
1172  *
1173  * Our example will look like this:
1174  *
1175  * @image html screenshots/calendar_example_01.png
1176  * @image latex screenshots/calendar_example_01.eps width=\textwidth
1177  *
1178  * See the full source code @ref calendar_example_01.c here.
1179  * @example calendar_example_01.c
1180  */
1181
1182 /**
1183  * @page calendar_example_02 Calendar - Layout strings formatting.
1184  * @dontinclude calendar_example_02.c
1185  *
1186  * In this simple example, we'll explain how to format the label displaying
1187  * month and year, and also set weekday names.
1188  *
1189  * To format month and year label, we need to create a callback function
1190  * to create a string given the selected time, declared under a
1191  * <tt> struct tm </tt>.
1192  *
1193  * <tt> struct tm </tt>, declared on @c time.h, is a structure composed by
1194  * nine integers:
1195  * @li tm_sec   seconds [0,59]
1196  * @li tm_min   minutes [0,59]
1197  * @li tm_hour  hour [0,23]
1198  * @li tm_mday  day of month [1,31]
1199  * @li tm_mon   month of year [0,11]
1200  * @li tm_year  years since 1900
1201  * @li tm_wday  day of week [0,6] (Sunday = 0)
1202  * @li tm_yday  day of year [0,365]
1203  * @li tm_isdst daylight savings flag
1204  * @note glib version has 2 additional fields.
1205  *
1206  * For our function, only stuff that matters are tm_mon and tm_year.
1207  * But we don't need to access it directly, since there are nice functions
1208  * to format date and time, as @c strftime.
1209  * We will get abbreviated month (%b) and year (%y) (check strftime manpage
1210  * for more) in our example:
1211  * @skipline static char
1212  * @until }
1213  *
1214  * We need to alloc the string to be returned, and calendar widget will
1215  * free it when it's not needed, what is done by @c strdup.
1216  * So let's register our callback to calendar object:
1217  * @skipline elm_calendar_format_function_set
1218  *
1219  * To set weekday names, we should declare them as an array of strings:
1220  * @dontinclude calendar_example_02.c
1221  * @skipline weekdays
1222  * @until }
1223  *
1224  * And finally set them to calendar:
1225  * skipline weekdays_names_set
1226  *
1227  * Our example will look like this:
1228  *
1229  * @image html screenshots/calendar_example_02.png
1230  * @image latex screenshots/calendar_example_02.eps width=\textwidth
1231  *
1232  * See the full source code @ref calendar_example_02.c here.
1233  * @example calendar_example_02.c
1234  */
1235
1236 /**
1237  * @page calendar_example_03 Calendar - Years restrictions.
1238  * @dontinclude calendar_example_03.c
1239  *
1240  * This example explains how to set max and min year to be displayed
1241  * by a calendar object. This means that user won't be able to
1242  * see or select a date before and after selected years.
1243  * By default, limits are 1902 and maximun value will depends
1244  * on platform architecture (year 2037 for 32 bits); You can
1245  * read more about time functions on @c ctime manpage.
1246  *
1247  * Straigh to the point, to set it is enough to call
1248  * elm_calendar_min_max_year_set(). First value is minimun year, second
1249  * is maximum. If first value is negative, it won't apply limit for min
1250  * year, if the second one is negative, won't apply for max year.
1251  * Setting both to negative value will clear limits (default state):
1252  * @skipline elm_calendar_min_max_year_set
1253  *
1254  * Our example will look like this:
1255  *
1256  * @image html screenshots/calendar_example_03.png
1257  * @image latex screenshots/calendar_example_03.eps width=\textwidth
1258  *
1259  * See the full source code @ref calendar_example_03.c here.
1260  * @example calendar_example_03.c
1261  */
1262
1263 /**
1264  * @page calendar_example_04 Calendar - Days selection.
1265  * @dontinclude calendar_example_04.c
1266  *
1267  * It's possible to disable date selection and to select a date
1268  * from your program, and that's what we'll see on this example.
1269  *
1270  * If isn't required that users could select a day on calendar,
1271  * only interacting going through months, disabling days selection
1272  * could be a good idea to avoid confusion. For that:
1273  * @skipline elm_calendar_day_selection_enabled_set
1274  *
1275  * Also, regarding days selection, you could be interested to set a
1276  * date to be highlighted on calendar from your code, maybe when
1277  * a specific event happens, or after calendar creation. Let's select
1278  * two days from current day:
1279  * @dontinclude calendar_example_04.c
1280  * @skipline SECS_DAY
1281  * @skipline current_time
1282  * @until elm_calendar_selected_time_set
1283  *
1284  * Our example will look like this:
1285  *
1286  * @image html screenshots/calendar_example_04.png
1287  * @image latex screenshots/calendar_example_04.eps width=\textwidth
1288  *
1289  * See the full source code @ref calendar_example_04.c here.
1290  * @example calendar_example_04.c
1291  */
1292
1293 /**
1294  * @page calendar_example_05 Calendar - Signal callback and getters.
1295  * @dontinclude calendar_example_05.c
1296  *
1297  * Most of setters explained on previous examples have associated getters.
1298  * That's the subject of this example. We'll add a callback to display
1299  * all calendar information every time user interacts with the calendar.
1300  *
1301  * Let's check our callback function:
1302  * @skipline static void
1303  * @until double interval;
1304  *
1305  * To get selected day, we need to call elm_calendar_selected_time_get(),
1306  * but to assure nothing wrong happened, we must check for function return.
1307  * It'll return @c EINA_FALSE if fail. Otherwise we can use time set to
1308  * our structure @p stime.
1309  * @skipline elm_calendar_selected_time_get
1310  * @until return
1311  *
1312  * Next we'll get information from calendar and place on declared vars:
1313  * @skipline interval
1314  * @until elm_calendar_weekdays_names_get
1315  *
1316  * The only tricky part is that last line gets an array of strings
1317  * (char arrays), one for each weekday.
1318  *
1319  * Then we can simple print that to stdin:
1320  * @skipline printf
1321  * @until }
1322  *
1323  * <tt> struct tm </tt> is declared on @c time.h. You can check @c ctime
1324  * manpage to read about it.
1325  *
1326  * To register this callback, that will be called every time user selects
1327  * a day or goes to next or previous month, just add a callback for signal
1328  * @b changed.
1329  * @skipline evas_object_smart_callback_add
1330  *
1331  * Our example will look like this:
1332  *
1333  * @image html screenshots/calendar_example_05.png
1334  * @image latex screenshots/calendar_example_05.eps width=\textwidth
1335  *
1336  * See the full source code @ref calendar_example_05.c here.
1337  * @example calendar_example_05.c
1338  */
1339
1340 /**
1341  * @page calendar_example_06 Calendar - Calendar marks.
1342  * @dontinclude calendar_example_06.c
1343  *
1344  * On this example marks management will be explained. Functions
1345  * elm_calendar_mark_add(), elm_calendar_mark_del() and
1346  * elm_calendar_marks_clear() will be covered.
1347  *
1348  * To add a mark, will be required to choose three things:
1349  * @li mark style
1350  * @li mark date, or start date if it will be repeated
1351  * @li mark periodicity
1352  *
1353  * Style defines the kind of mark will be displayed over marked day,
1354  * on caledar. Default theme supports @b holiday and @b checked.
1355  * If more is required, is possible to set a new theme to calendar
1356  * widget using elm_object_style_set(), and use
1357  * the signal that will be used by such marks.
1358  *
1359  * Date is a <tt> struct tm </tt>, as defined by @c time.h. More can
1360  * be read on @c ctime manpage.
1361  * If a date relative from current is required, this struct can be set
1362  * as:
1363  * @skipline current_time
1364  * @until localtime_r
1365  *
1366  * Or if it's an absolute date, you can just declare the struct like:
1367  * @dontinclude calendar_example_06.c
1368  * @skipline sunday
1369  * @until christmas.tm_mon
1370  *
1371  * Periodicity is how frequently the mark will be displayed over the
1372  * calendar.  Can be a unique mark (that don't repeat), or it can repeat
1373  * daily, weekly, monthly or annually. It's enumerated by
1374  * @c Elm_Calendar_Mark_Repeat.
1375  *
1376  * So let's add some marks to our calendar. We will add christmas holiday,
1377  * set Sundays as holidays, and check current day and day after that.
1378  * @dontinclude calendar_example_06.c
1379  * @skipline sunday
1380  * @until christmas.tm_mon
1381  * @skipline current_time
1382  * @until ELM_CALENDAR_WEEKLY
1383  *
1384  * We kept the return of first mark add, because we don't really won't it
1385  * to be checked, so let's remove it:
1386  * @skipline elm_calendar_mark_del
1387  *
1388  * After all marks are added and removed, is required to draw them:
1389  * @skipline elm_calendar_marks_draw
1390  *
1391  * Finally, to clear all marks, let's set a callback for our button:
1392  * @skipline elm_button_add
1393  * @until evas_object_show(bt);
1394  *
1395  * This callback will receive our calendar object, and should clear it:
1396  * @dontinclude calendar_example_06.c
1397  * @skipline static
1398  * @until }
1399  * @note Remember to draw marks after clear the calendar.
1400  *
1401  * Our example will look like this:
1402  *
1403  * @image html screenshots/calendar_example_06.png
1404  * @image latex screenshots/calendar_example_06.eps width=\textwidth
1405  *
1406  * See the full source code @ref calendar_example_06.c here.
1407  * @example calendar_example_06.c
1408  */
1409
1410 /**
1411  * @page spinner_example Spinner widget example
1412  *
1413  * This code places seven Elementary spinner widgets on a window, each of
1414  * them exemplifying a part of the widget's API.
1415  *
1416  * The first of them is the default spinner:
1417  * @dontinclude spinner_example.c
1418  * @skipline elm_spinner_add
1419  * @until evas_object_show
1420  * As you see, the defaults for a spinner are:
1421  * @li no wrap
1422  * @li min value set to 0
1423  * @li max value set to 100
1424  * @li step value set to 1
1425  * @li label format set to "%0.f"
1426  *
1427  * If another format is required, see the second spinner. It will put a text
1428  * before and after the value, and also format value to display two decimals:
1429  * @skipline format_set
1430  *
1431  * The third one will use a customized step, define new minimum and maximum
1432  * values and enable wrap, so when value reaches minimum it jumps to maximum,
1433  * or jumps to minimum after maximum value is reached. Format is set to display
1434  * a decimal:
1435  * @skipline elm_spinner_add
1436  * @until evas_object_show
1437  *
1438  * The fourth uses @c vertical style, so instead of left and right arrows,
1439  * top and bottom are displayed. Also the change interval is reduced, so
1440  * user can change value faster.
1441  * @skipline style
1442  * @skipline interval
1443  *
1444  * In the fifth the user won't be allowed to set value directly, i.e., will
1445  * be obligate change value only using arrows:
1446  * @skipline editable
1447  *
1448  * The sixth widget will receive a lot of special values, so
1449  * instead of reading numeric values, user will see labels for each one.
1450  * Also direct edition is disabled, otherwise users would see the numeric
1451  * value on edition mode. User will be able to select a month in this widget:
1452  * @skipline elm_spinner_add
1453  * @until evas_object_show
1454  *
1455  * Finally the last widget will exemplify how to listen to widget's signals,
1456  * <tt> changed </tt> and <tt> delay,changed </tt>. First we need to
1457  * implement callback functions that will simply print spinner's value:
1458  * @dontinclude spinner_example.c
1459  * @skip static
1460  * @skip }
1461  * @skipline static
1462  * @until }
1463  * @until }
1464  *
1465  * The first callback function should be called everytime value changes,
1466  * the second one only after user stops to increment or decrement. Try
1467  * to keep arrows pressed and check the difference.
1468  * @skip smart_callback
1469  * @skipline smart_callback
1470  * @skipline smart_callback
1471  *
1472  * See the full @ref spinner_example.c "example", whose window should
1473  * look like this picture:
1474  *
1475  * @image html screenshots/spinner_example.png
1476  * @image latex screenshots/spinner_example.eps width=\textwidth
1477  *
1478  * See the full @ref spinner_example_c "source code" for this example.
1479  *
1480  * @example spinner_example.c
1481  */
1482
1483 /**
1484  * @page clock_example Clock widget example
1485  *
1486  * This code places five Elementary clock widgets on a window, each of
1487  * them exemplifying a part of the widget's API.
1488  *
1489  * The first of them is the pristine clock:
1490  * @dontinclude clock_example.c
1491  * @skip pristine
1492  * @until evas_object_show
1493  * As you see, the defaults for a clock are:
1494  * - military time
1495  * - no seconds shown
1496  *
1497  * For am/pm time, see the second clock:
1498  * @dontinclude clock_example.c
1499  * @skip am/pm
1500  * @until evas_object_show
1501  *
1502  * The third one will show the seconds digits, which will flip in
1503  * synchrony with system time. Note, besides, that the time itself is
1504  * @b different from the system's -- it was customly set with
1505  * elm_clock_time_set():
1506  * @dontinclude clock_example.c
1507  * @skip with seconds
1508  * @until evas_object_show
1509  *
1510  * In both fourth and fifth ones, we turn on the <b>edition
1511  * mode</b>. See how you can change each of the sheets on it, and be
1512  * sure to try holding the mouse pressed over one of the sheet
1513  * arrows. The forth one also starts with a custom time set:
1514  * @dontinclude clock_example.c
1515  * @skip in edition
1516  * @until evas_object_show
1517  *
1518  * The fifth, besides editable, has only the time @b units editable,
1519  * for hours, minutes and seconds. This exemplifies
1520  * elm_clock_digit_edit_set():
1521  * @dontinclude clock_example.c
1522  * @skip but only
1523  * @until evas_object_show
1524  *
1525  * See the full @ref clock_example.c "example", whose window should
1526  * look like this picture:
1527  *
1528  * @image html screenshots/clock_example.png
1529  * @image latex screenshots/clock_example.eps width=\textwidth
1530  *
1531  * See the full @ref clock_example_c "source code" for this example.
1532  *
1533  * @example clock_example.c
1534  */
1535
1536 /**
1537  * @page diskselector_example_01 Diskselector widget example
1538  *
1539  * This code places 4 Elementary diskselector widgets on a window, each of
1540  * them exemplifying a part of the widget's API.
1541  *
1542  * All of them will have weekdays as items, since we won't focus
1543  * on items management on this example. For an example about this subject,
1544  * check @ref diskselector_example_02.
1545  *
1546  * The first of them is a default diskselector.
1547  * @dontinclude diskselector_example_01.c
1548  * @skipline lbl
1549  * @until }
1550  * @skipline elm_diskselector_add
1551  * @until evas_object_show
1552  *
1553  * We are just adding the diskselector, so as you can see, defaults for it are:
1554  * @li Only 3 items visible each time.
1555  * @li Only 3 characters are displayed for labels on side positions.
1556  * @li The first added item remains centeres, i.e., it's the selected item.
1557  *
1558  * To add items, we are just appending it on a loop, using function
1559  * elm_diskselector_item_append(), that will be better exaplained on
1560  * items management example.
1561  *
1562  * For a circular diskselector, check the second widget. A circular
1563  * diskselector will display first item after last, and last previous to
1564  * the first one. So, as you can see, @b Sa will appears on left side
1565  * of selected @b Sunday. This property is set with
1566  * elm_diskselector_round_set().
1567  *
1568  * Also, we decide to display only 2 character for side labels, instead of 3.
1569  * For this we call elm_diskselector_side_label_length_set(). As result,
1570  * we'll see @b Mo displayed instead of @b Mon, when @b Monday is on a
1571  * side position.
1572  *
1573  * @skipline elm_diskselector_add
1574  * @until evas_object_show
1575  *
1576  * But so far, we are only displaying 3 items at once. If more are wanted,
1577  * is enough to call elm_diskselector_display_item_num_set(), as you can
1578  * see here:
1579  * @skipline elm_diskselector_add
1580  * @until evas_object_show
1581  *
1582  * @note You can't set less than 3 items to be displayed.
1583  *
1584  * Finally, if a bounce effect is required, or you would like to see
1585  * scrollbars, it is possible. But, for default theme, diskselector
1586  * scrollbars will be invisible anyway.
1587  * @skipline elm_diskselector_add
1588  * @until evas_object_show
1589  *
1590  * See the full @ref diskselector_example_01.c "diskselector_example_01.c"
1591  * code, whose window should look like this picture:
1592  *
1593  * @image html screenshots/diskselector_example_01.png
1594  * @image latex screenshots/diskselector_example_01.eps width=\textwidth
1595  *
1596  * @example diskselector_example_01.c
1597  */
1598
1599 /**
1600  * @page diskselector_example_02 Diskselector - Items management
1601  *
1602  * This code places a Elementary diskselector widgets on a window,
1603  * along with some buttons trigerring actions on it (though its API).
1604  * It covers most of Elm_Diskselector_Item functions.
1605  *
1606  * On our @c main function, we are adding a default diskselector with
1607  * 3 items. We are only setting their labels (second parameter of function
1608  * elm_diskselector_item_append):
1609  * @dontinclude diskselector_example_02.c
1610  * @skipline elm_diskselector_add
1611  * @until Item 2
1612  *
1613  * Next we are adding lots of buttons, each one for a callback function
1614  * that will realize a task covering part of diskselector items API.
1615  * Lets check the first one:
1616  * @skipline elm_button_add
1617  * @until evas_object_show
1618  *
1619  * We are labeling the button with a task description with
1620  * elm_object_text_set() and setting a callback
1621  * function evas_object_smart_callback_add().
1622  * Each callback function will have the signature:
1623  * <tt> static void _task_cb(void *data, Evas_Object *obj,
1624  * void *event_info)</tt> with the function name varying for each task.
1625  *
1626  * Now let's cover all of them.
1627  *
1628  * <b> Appending an item: </b>
1629  * @dontinclude diskselector_example_02.c
1630  * @skipline _add_cb
1631  * @until }
1632  *
1633  * All items are included on diskselector after last one. You @b can't
1634  * preprend items.
1635  *
1636  * The first parameter of elm_diskselector_item_append() is the diskselector
1637  * object, that we are receiving as data on our callback function.
1638  * The second one is a label, the string that will be placed in the center
1639  * of our item. As we don't wan't icons or callback functions, we can
1640  * send NULL as third, fourth and fifth parameters.
1641  *
1642  * <b> Appending an item with icon: </b>
1643  * @dontinclude diskselector_example_02.c
1644  * @skipline _add_ic_cb
1645  * @until }
1646  *
1647  * If an icon is required, you can pass it as third paramenter on our
1648  * elm_diskselector_item_append() function. It will be place on the
1649  * left side of item's label, that will be shifted to right a bit.
1650  *
1651  * For more details about how to create icons, look for elm_icon examples.
1652  *
1653  * <b> Appending an item with callback function for selected: </b>
1654  * @dontinclude diskselector_example_02.c
1655  * @skipline _sel_cb
1656  * @until }
1657  * @until }
1658  *
1659  * To set a callback function that will be called every time an item is
1660  * selected, i.e., everytime the diskselector stops with this item in
1661  * center position, just pass the function as fourth paramenter.
1662  *
1663  * <b> Appending an item with callback function for selected with data: </b>
1664  * @dontinclude diskselector_example_02.c
1665  * @skipline _sel_data_cb
1666  * @until }
1667  * @until }
1668  * @until }
1669  * @until }
1670  *
1671  * If the callback function request an extra data, it can be attached to our
1672  * item passing a pointer for data as fifth parameter.
1673  * Our function _sel_data_cb will receive it as <tt> void *data </tt>.
1674  *
1675  * If you want to free this data, or handle that the way you need when the
1676  * item is deleted, set a callback function for that, with
1677  * elm_diskselector_item_del_cb_set().
1678  *
1679  * As you can see we check if @c it is not @c NULL after appending it.
1680  * If an error happens, we won't try to set a function for it.
1681  *
1682  * <b> Deleting an item: </b>
1683  * @dontinclude diskselector_example_02.c
1684  * @skip _del_cb
1685  * @skipline _del_cb
1686  * @until }
1687  *
1688  * To delete an item we simple need to call elm_diskselector_item_del() with
1689  * a pointer for such item.
1690  *
1691  * If you need, you can get selected item with
1692  * elm_diskselector_selected_item_get(), that will return a pointer for it.
1693  *
1694  * <b> Unselecting an item: </b>
1695  * @dontinclude diskselector_example_02.c
1696  * @skipline _unselect_cb
1697  * @until }
1698  *
1699  * To select an item, you should call elm_diskselector_item_selected_set()
1700  * passing @c EINA_TRUE, and to unselect it, @c EINA_FALSE.
1701  *
1702  * If you unselect the selected item, diskselector will automatically select
1703  * the first item.
1704  *
1705  * <b> Printing all items: </b>
1706  * @dontinclude diskselector_example_02.c
1707  * @skipline _print_cb
1708  * @until }
1709  *
1710  * <b> Clearing the diskselector: </b>
1711  * @dontinclude diskselector_example_02.c
1712  * @skipline _clear_cb
1713  * @until }
1714  *
1715  * <b> Selecting the first item: </b>
1716  * @dontinclude diskselector_example_02.c
1717  * @skipline _select_first_cb
1718  * @until }
1719  *
1720  * <b> Selecting the last item: </b>
1721  * @dontinclude diskselector_example_02.c
1722  * @skipline _select_last_cb
1723  * @until }
1724  *
1725  * <b> Selecting the next item: </b>
1726  * @dontinclude diskselector_example_02.c
1727  * @skipline _select_next_cb
1728  * @until }
1729  *
1730  * <b> Selecting the previous item: </b>
1731  * @dontinclude diskselector_example_02.c
1732  * @skipline _select_prev_cb
1733  * @until }
1734  *
1735  * See the full @ref diskselector_example_02.c "diskselector_example_02.c"
1736  * code, whose window should look like this picture:
1737  *
1738  * @image html screenshots/diskselector_example_02.png
1739  * @image latex screenshots/diskselector_example_02.eps width=\textwidth
1740  *
1741  * @example diskselector_example_02.c
1742  */
1743
1744 /**
1745  * @page list_example_01 List widget example
1746  *
1747  * This code places a single Elementary list widgets on a window, just
1748  * to exemplify the more simple and common use case: a list will be created
1749  * and populated with a few items.
1750  *
1751  * To keep it simple, we won't show how to customize the list, for this check
1752  * @ref list_example_02. Also, we won't focus
1753  * on items management on this example. For an example about this subject,
1754  * check @ref list_example_03.
1755  *
1756  * To add a list widget.
1757  * @dontinclude list_example_01.c
1758  * @skipline elm_list_add
1759  *
1760  * We are just adding the list, so as you can see, defaults for it are:
1761  * @li Items are displayed vertically.
1762  * @li Only one item can be selected.
1763  * @li The list doesn't bouce.
1764  *
1765  * To add items, we are just appending it on a loop, using function
1766  * elm_list_item_append(), that will be better exaplained on
1767  * items management example.
1768  * @dontinclude list_example_01.c
1769  * @skipline lbl[]
1770  * @until };
1771  * @skipline for
1772  * @skipline elm_list_item_append
1773  *
1774  * After we just want to show the list. But first we need to start the widget.
1775  * It was done this way to improve widget's performance. So, always remember
1776  * that:
1777  * @warning Call elm_list_go before showing the object
1778  * @skipline elm_list_go
1779  * @skipline show
1780  *
1781  * See the full @ref list_example_01.c "list_example_01.c"
1782  * code, whose window should look like this picture:
1783  *
1784  * @image html screenshots/list_example_01.png
1785  * @image latex screenshots/list_example_01.eps width=\textwidth
1786  *
1787  * @example list_example_01.c
1788  */
1789
1790 /**
1791  * @page list_example_02 List widget example
1792  *
1793  * This code places a single Elementary list widgets on a window,
1794  * exemplifying a part of the widget's API.
1795  *
1796  * First, we will just create a simple list, as done on @ref list_example_01 :
1797  * @dontinclude list_example_02.c
1798  * @skipline lbl
1799  * @until }
1800  * @skipline elm_list_add
1801  * @until elm_list_item_append
1802  *
1803  * Now, let's customize this list a bit. First we will display items
1804  * horizontally:
1805  * @skipline horizontal_set
1806  *
1807  * Then we will choose another list mode. There are four of them, and
1808  * the default #Elm_List_Mode is #ELM_LIST_SCROLL. Let's set compress mode:
1809  * @skipline mode_set
1810  *
1811  * To enable multiple items selection, we need to enable it, since only one
1812  * selected item is allowed by default:
1813  * @skipline elm_list_multi_select_set
1814  *
1815  * We are not adding items with callback functions here,
1816  * since we'll explain it better on  @ref list_example_03. But if the callback
1817  * need to be called everytime user clicks an item, even if already selected,
1818  * it's required to enable this behavior:
1819  * @skipline elm_list_always_select_mode_set
1820  *
1821  * Finally, if a bounce effect is required, or you would like to see
1822  * scrollbars, it is possible. But, for default theme, list
1823  * scrollbars will be invisible anyway.
1824  * @skipline bounce_set
1825  * @until SCROLLER_POLICY_ON
1826  *
1827  * See the full @ref list_example_02.c "list_example_02.c"
1828  * code, whose window should look like this picture:
1829  *
1830  * @image html screenshots/list_example_02.png
1831  * @image latex screenshots/list_example_02.eps width=\textwidth
1832  *
1833  * @example list_example_02.c
1834  */
1835
1836 /**
1837  * @page list_example_03 List - Items management
1838  *
1839  * This code places a Elementary list widgets on a window,
1840  * along with some buttons trigerring actions on it (though its API).
1841  * It covers most of Elm_List_Item functions.
1842  *
1843  * On our @c main function, we are adding a default list with
1844  * 3 items. We are only setting their labels (second parameter of function
1845  * elm_list_item_append):
1846  * @dontinclude list_example_03.c
1847  * @skipline elm_list_add
1848  * @until Item 2
1849  *
1850  * Next we are adding lots of buttons, each one for a callback function
1851  * that will realize a task covering part of list items API.
1852  * Lets check the first one:
1853  * @skipline elm_button_add
1854  * @until evas_object_show
1855  *
1856  * We are labeling the button with a task description with
1857  * elm_object_text_set() and setting a callback
1858  * function evas_object_smart_callback_add().
1859  * Each callback function will have the signature:
1860  * <tt> static void _task_cb(void *data, Evas_Object *obj,
1861  * void *event_info)</tt> with the function name varying for each task.
1862  *
1863  * Now let's cover all of them.
1864  *
1865  * <b> Prepending an item: </b>
1866  * @dontinclude list_example_03.c
1867  * @skipline _prepend_cb
1868  * @until }
1869  *
1870  * The item will be placed on the begining of the list,
1871  * i.e. it will be the first one.
1872  *
1873  * The first parameter of elm_list_item_prepend() is the list
1874  * object, that we are receiving as data on our callback function.
1875  * The second one is a label, the string that will be placed in the center
1876  * of our item. As we don't wan't icons or callback functions, we can
1877  * send NULL as third, fourth, fifth and sixth parameters.
1878  *
1879  * <b> Appending an item: </b>
1880  * @dontinclude list_example_03.c
1881  * @skipline _add_cb
1882  * @until }
1883  *
1884  * Items included with append will be inserted inserted after the last one.
1885  *
1886  * <b> Appending an item with icon: </b>
1887  * @dontinclude list_example_03.c
1888  * @skipline _add_ic_cb
1889  * @until }
1890  *
1891  * If an icon is required, you can pass it as third paramenter on our
1892  * elm_list_item_append() function. It will be place on the
1893  * left side of item's label. If an icon is wanted on the right side,
1894  * it should be passed as fourth parameter.
1895  *
1896  * For more details about how to create icons, look for elm_icon examples
1897  * @ref tutorial_icon.
1898  *
1899  * <b> Appending an item with callback function for selected: </b>
1900  * @dontinclude list_example_03.c
1901  * @skipline _sel_cb
1902  * @until }
1903  * @until }
1904  *
1905  * To set a callback function that will be called every time an item is
1906  * selected, i.e., everytime the list stops with this item in
1907  * center position, just pass the function as fifth paramenter.
1908  *
1909  * <b> Appending an item with callback function for selected with data: </b>
1910  * @dontinclude list_example_03.c
1911  * @skipline _sel_data_cb
1912  * @until }
1913  * @until }
1914  * @until }
1915  * @until }
1916  *
1917  * If the callback function request an extra data, it can be attached to our
1918  * item passing a pointer for data as sixth parameter.
1919  * Our function _sel_data_cb will receive it as <tt> void *data </tt>.
1920  *
1921  * If you want to free this data, or handle that the way you need when the
1922  * item is deleted, set a callback function for that, with
1923  * elm_list_item_del_cb_set().
1924  *
1925  * As you can see we check if @c it is not @c NULL after appending it.
1926  * If an error happens, we won't try to set a function for it.
1927  *
1928  * <b> Deleting an item: </b>
1929  * @dontinclude list_example_03.c
1930  * @skipline _del_cb(
1931  * @until }
1932  *
1933  * To delete an item we simple need to call elm_list_item_del() with
1934  * a pointer for such item.
1935  *
1936  * If you need, you can get selected item with
1937  * elm_list_selected_item_get(), that will return a pointer for it.
1938  *
1939  * <b> Unselecting an item: </b>
1940  * @dontinclude list_example_03.c
1941  * @skipline _unselect_cb
1942  * @until }
1943  *
1944  * To select an item, you should call elm_list_item_selected_set()
1945  * passing @c EINA_TRUE, and to unselect it, @c EINA_FALSE.
1946  *
1947  * <b> Printing all items: </b>
1948  * @dontinclude list_example_03.c
1949  * @skipline _print_cb
1950  * @until }
1951  *
1952  * <b> Clearing the list: </b>
1953  * @dontinclude list_example_03.c
1954  * @skipline _clear_cb
1955  * @until }
1956  *
1957  * <b> Selecting the next item: </b>
1958  * @dontinclude list_example_03.c
1959  * @skipline _select_next_cb
1960  * @until }
1961  *
1962  * <b> Inserting after an item: </b>
1963  * @dontinclude list_example_03.c
1964  * @skipline _insert_after_cb
1965  * @until }
1966  *
1967  * <b> Selecting the previous item: </b>
1968  * @dontinclude list_example_03.c
1969  * @skipline _select_prev_cb
1970  * @until }
1971  *
1972  * <b> Inserting before an item: </b>
1973  * @dontinclude list_example_03.c
1974  * @skipline _insert_before_cb
1975  * @until }
1976  *
1977  * If a separator is required, just set an item as such:
1978  * @dontinclude list_example_03.c
1979  * @skipline _set_separator_cb
1980  * @until }
1981  *
1982  * Also an item can be disabled, and the user won't be allowed to (un)select it:
1983  * @dontinclude list_example_03.c
1984  * @skipline _disable_cb
1985  * @until }
1986  *
1987  * See the full @ref list_example_03.c "list_example_03.c"
1988  * code, whose window should look like this picture:
1989  *
1990  * @image html screenshots/list_example_03.png
1991  * @image latex screenshots/list_example_03.eps width=\textwidth
1992  *
1993  * @example list_example_03.c
1994  */
1995
1996 /**
1997  * @page flipselector_example Flip selector widget example
1998  *
1999  * This code places an Elementary flip selector widget on a window,
2000  * along with two buttons trigerring actions on it (though its API).
2001  *
2002  * The selector is being populated with the following items:
2003  * @dontinclude flipselector_example.c
2004  * @skip lbl[]
2005  * @until ;
2006  *
2007  * Next, we create it, populating it with those items and registering
2008  * two (smart) callbacks on it:
2009  * @dontinclude flipselector_example.c
2010  * @skip fp = elm_flipselector_add
2011  * @until object_show
2012  *
2013  * Those two callbacks will take place whenever one of those smart
2014  * events occur, and they will just print something to @c stdout:
2015  * @dontinclude flipselector_example.c
2016  * @skip underflow callback
2017  * @until static void
2018  * Flip the sheets on the widget while looking at the items list, in
2019  * the source code, and you'll get the idea of those events.
2020  *
2021  * The two buttons below the flip selector will take the actions
2022  * described in their labels:
2023  * @dontinclude flipselector_example.c
2024  * @skip bt = elm_button_add
2025  * @until callback_add(win
2026  *
2027  * @dontinclude flipselector_example.c
2028  * @skip unselect the item
2029  * @until underflow
2030  *
2031  * Click on them to exercise those flip selector API calls. To
2032  * interact with the other parts of this API, there's a command line
2033  * interface, whose help string can be asked for with the 'h' key:
2034  * @dontinclude flipselector_example.c
2035  * @skip commands
2036  * @until ;
2037  *
2038  * The 'n' and 'p' keys will exemplify elm_flipselector_flip_next()
2039  * and elm_flipselector_flip_prev(), respectively. 'f' and 'l' account
2040  * for elm_flipselector_first_item_get() and
2041  * elm_flipselector_last_item_get(), respectively. Finally, 's' will
2042  * issue elm_flipselector_selected_item_get() on our example flip
2043  * selector widget.
2044  *
2045  * See the full @ref flipselector_example.c "example", whose window should
2046  * look like this picture:
2047  *
2048  * @image html screenshots/flipselector_example.png
2049  * @image latex screenshots/flipselector_example.eps width=\textwidth
2050  *
2051  * See the full @ref flipselector_example_c "source code" for this example.
2052  *
2053  * @example flipselector_example.c
2054  */
2055
2056 /**
2057  * @page fileselector_example File selector widget example
2058  *
2059  * This code places two Elementary file selector widgets on a window.
2060  * The one on the left is layouting file system items in a @b list,
2061  * while the the other is layouting them in a @b grid.
2062  *
2063  * The one having the majority of hooks of interest is on the left,
2064  * which we create as follows:
2065  * @dontinclude fileselector_example.c
2066  * @skip first file selector
2067  * @until object_show
2068  *
2069  * Note that we enable custom edition of file/directory selection, via
2070  * the text entry it has on its bottom, via
2071  * elm_fileselector_is_save_set(). It starts with the list view, which
2072  * is the default, and we make it not expandable in place
2073  * (elm_fileselector_expandable_set()), so that it replaces its view's
2074  * contents with the current directory's entries each time one
2075  * navigates to a different folder.  For both of file selectors we are
2076  * starting to list the contents found in the @c "/tmp" directory
2077  * (elm_fileselector_path_set()).
2078  *
2079  * Note the code setting it to "grid mode" and observe the differences
2080  * in the file selector's views, in the example. We also hide the
2081  * second file selector's Ok/Cancel buttons -- since it's there just
2082  * to show the grid view (and navigation) -- via
2083  * elm_fileselector_buttons_ok_cancel_set().
2084  *
2085  * The @c "done" event, which triggers the callback below
2086  * @dontinclude fileselector_example.c
2087  * @skip 'done' cb
2088  * @until }
2089  * will be called at the time one clicks the "Ok"/"Cancel" buttons of
2090  * the file selector (on the left). Note that it will print the path
2091  * to the current selection, if any.
2092  *
2093  * The @c "selected" event, which triggers the callback below
2094  * @dontinclude fileselector_example.c
2095  * @skip bt = 'selected' cb
2096  * @until }
2097  * takes place when one selects a file (if the file selector is @b not
2098  * under folders-only mode) or when one selects a folder (when in
2099  * folders-only mode). Experiment it by selecting different file
2100  * system entries.
2101  *
2102  * What comes next is the code creating the three check boxes and two
2103  * buttons below the file selector in the right. They will exercise a
2104  * bunch of functions on the file selector's API, for the instance on
2105  * the left. Experiment with them, specially the buttons, to get the
2106  * difference between elm_fileselector_path_get() and
2107  * elm_fileselector_selected_get().
2108  *
2109  * Finally, there's the code adding the second file selector, on the
2110  * right:
2111  * @dontinclude fileselector_example.c
2112  * @skip second file selector
2113  * @until object_show
2114  *
2115  * Pay attention to the code setting it to "grid mode" and observe the
2116  * differences in the file selector's views, in the example. We also
2117  * hide the second file selector's Ok/Cancel buttons -- since it's
2118  * there just to show the grid view (and navigation) -- via
2119  * elm_fileselector_buttons_ok_cancel_set().
2120  *
2121  * See the full @ref fileselector_example.c "example", whose window
2122  * should look like this picture:
2123  *
2124  * @image html screenshots/fileselector_example.png
2125  * @image latex screenshots/fileselector_example.eps width=\textwidth
2126  *
2127  * See the full @ref fileselector_example_c "source code" for this example.
2128  *
2129  * @example fileselector_example.c
2130  */
2131
2132 /**
2133  * @page fileselector_button_example File selector button widget example
2134  *
2135  * This code places an Elementary file selector button widget on a
2136  * window, along with some other checkboxes and a text entry. Those
2137  * are there just as knobs on the file selector button's state and to
2138  * display information from it.
2139  *
2140  * Here's how we instantiate it:
2141  * @dontinclude fileselector_button_example.c
2142  * @skip ic = elm_icon_add
2143  * @until evas_object_show
2144  *
2145  * Note that we set on it both icon and label decorations. It's set to
2146  * list the contents of the @c "/tmp" directory, too, with
2147  * elm_fileselector_button_path_set(). What follows are checkboxes to
2148  * exercise some of its API funtions:
2149  * @dontinclude fileselector_button_example.c
2150  * @skip ck = elm_check_add
2151  * @until evas_object_show(en)
2152  *
2153  * The checkboxes will toggle whether the file selector button's
2154  * internal file selector:
2155  * - must have an editable text entry for file names (thus, be in
2156  *   "save dialog mode")
2157  * - is to be raised as an "inner window" (note it's the default
2158  *   behavior) or as a dedicated window
2159  * - is to populate its view with folders only
2160  * - is to expand its folders, in its view, <b>in place</b>, and not
2161  *   repainting it entirely just with the contents of a sole
2162  *   directory.
2163  *
2164  * The entry labeled @c "Last selection" will exercise the @c
2165  * "file,chosen" smart event coming from the file selector button:
2166  * @dontinclude fileselector_button_example.c
2167  * @skip hook on the
2168  * @until toggle inwin
2169  *
2170  * Whenever you dismiss or acknowledges the file selector, after it's
2171  * raised, the @c event_info string will contain the last selection on
2172  * it (if any was made).
2173  *
2174  * This is how the example, just after called, should look like:
2175  *
2176  * @image html screenshots/fileselector_button_example_00.png
2177  * @image latex screenshots/fileselector_button_example_00.eps width=\textwidth
2178  *
2179  * Click on the file selector button to raise its internal file
2180  * selector, which will be contained on an <b>"inner window"</b>:
2181  *
2182  * @image html screenshots/fileselector_button_example_01.png
2183  * @image latex screenshots/fileselector_button_example_01.eps width=\textwidth
2184  *
2185  * Toggle the "inwin mode" switch off and, if you click on the file
2186  * selector button again, you'll get @b two windows, the original one
2187  * (note the last selection there!)
2188  *
2189  * @image html screenshots/fileselector_button_example_02.png
2190  * @image latex screenshots/fileselector_button_example_02.eps width=\textwidth
2191  *
2192  * and the file selector's new one
2193  *
2194  * @image html screenshots/fileselector_button_example_03.png
2195  * @image latex screenshots/fileselector_button_example_03.eps width=\textwidth
2196  *
2197  * Play with the checkboxes to get the behavior changes on the file
2198  * selector button. The respective API calls on the widget coming from
2199  * those knobs where shown in the code already.
2200  *
2201  * See the full @ref fileselector_button_example_c "source code" for
2202  * this example.
2203  *
2204  * @example fileselector_button_example.c
2205  */
2206
2207 /**
2208  * @page fileselector_entry_example File selector entry widget example
2209  *
2210  * This code places an Elementary file selector entry widget on a
2211  * window, along with some other checkboxes. Those are there just as
2212  * knobs on the file selector entry's state.
2213  *
2214  * Here's how we instantiate it:
2215  * @dontinclude fileselector_entry_example.c
2216  * @skip ic = elm_icon_add
2217  * @until evas_object_show
2218  *
2219  * Note that we set on it's button both icon and label
2220  * decorations. It's set to exhibit the path of (and list the contents
2221  * of, when internal file selector is launched) the @c "/tmp"
2222  * directory, also, with elm_fileselector_entry_path_set(). What
2223  * follows are checkboxes to exercise some of its API funtions:
2224  * @dontinclude fileselector_entry_example.c
2225  * @skip ck = elm_check_add
2226  * @until callback_add(fs_entry
2227  *
2228  * The checkboxes will toggle whether the file selector entry's
2229  * internal file selector:
2230  * - must have an editable text entry for file names (thus, be in
2231  *   "save dialog mode")
2232  * - is to be raised as an "inner window" (note it's the default
2233  *   behavior) or as a dedicated window
2234  * - is to populate its view with folders only
2235  * - is to expand its folders, in its view, <b>in place</b>, and not
2236  *   repainting it entirely just with the contents of a sole
2237  *   directory.
2238  *
2239  * Observe how the entry's text will match the string coming from the
2240  * @c "file,chosen" smart event:
2241  * @dontinclude fileselector_entry_example.c
2242  * @skip hook on the
2243  * @until }
2244  * Whenever you dismiss or acknowledges the file selector, after it's
2245  * raised, the @c event_info string will contain the last selection on
2246  * it (if any was made).
2247  *
2248  * Try, also, to type in a valid system path and, then, open the file
2249  * selector's window: it will start the file browsing there, for you.
2250  *
2251  * This is how the example, just after called, should look like:
2252  *
2253  * @image html screenshots/fileselector_entry_example_00.png
2254  * @image latex screenshots/fileselector_entry_example_00.eps width=\textwidth
2255  *
2256  * Click on the file selector entry to raise its internal file
2257  * selector, which will be contained on an <b>"inner window"</b>:
2258  *
2259  * @image html screenshots/fileselector_entry_example_01.png
2260  * @image latex screenshots/fileselector_entry_example_01.eps width=\textwidth
2261  *
2262  * Toggle the "inwin mode" switch off and, if you click on the file
2263  * selector entry again, you'll get @b two windows, the original one
2264  * (note the last selection there!)
2265  *
2266  * @image html screenshots/fileselector_entry_example_02.png
2267  * @image latex screenshots/fileselector_entry_example_02.eps width=\textwidth
2268  *
2269  * and the file selector's new one
2270  *
2271  * @image html screenshots/fileselector_entry_example_03.png
2272  * @image latex screenshots/fileselector_entry_example_03.eps width=\textwidth
2273  *
2274  * Play with the checkboxes to get the behavior changes on the file
2275  * selector entry. The respective API calls on the widget coming from
2276  * those knobs where shown in the code already.
2277  *
2278  * See the full @ref fileselector_entry_example_c "source code" for
2279  * this example.
2280  *
2281  * @example fileselector_entry_example.c
2282  */
2283
2284 /**
2285  * @page layout_example_01 Layout - Content, Table and Box
2286  *
2287  * This example shows how one can use the @ref Layout widget to create a
2288  * customized distribution of widgets on the screen, controled by an Edje theme.
2289  * The full source code for this example can be found at @ref
2290  * layout_example_01_c.
2291  *
2292  * Our custom layout is defined by a file, @ref layout_example_edc, which is an
2293  * Edje theme file. Look for the Edje documentation to understand it. For now,
2294  * it's enough to know that we describe some specific parts on this layout
2295  * theme:
2296  * @li a title text field;
2297  * @li a box container;
2298  * @li a table container;
2299  * @li and a content container.
2300  *
2301  * Going straight to the code, the following snippet instantiates the layout
2302  * widget:
2303  *
2304  * @dontinclude layout_example_01.c
2305  * @skip elm_layout_add
2306  * @until evas_object_show(layout)
2307  *
2308  * As any other widget, we set some properties for the size calculation. But
2309  * notice on this piece of code the call to the function elm_layout_file_set().
2310  * Here is where the theme file is loaded, and particularly the specific group
2311  * from this theme file. Also notice that the theme file here is referenced as
2312  * an .edj, which is a .edc theme file compiled to its binary form. Again, look
2313  * for the Edje documentation for more information about theme files.
2314  *
2315  * Next, we fetch from our theme a data string referenced by the key "title".
2316  * This data was defined in the theme, and can be used as parameters which the
2317  * program get from the specific theme that it is using. In this case, we store
2318  * the title of this window and program in the theme, as a "data" entry, just
2319  * for demonstration purposes:
2320  *
2321  * @until }
2322  *
2323  * This call elm_layout_data_get() is used to fetch the string based on the key,
2324  * and elm_object_text_part_set() will set the part defined in the theme as
2325  * "example/title" to contain this string. This key "example/title" has nothing
2326  * special. It's just an arbitrary convention that we are using in this example.
2327  * Every string in this example referencing a part of this theme will be of the
2328  * form "example/<something>".
2329  *
2330  * Now let's start using our layout to distribute things on the window space.
2331  * Since the layout was added as a resize object to the elementary window, it
2332  * will always occupy the entire space available for this window.
2333  *
2334  * The theme already has a title, and it also defines a table element which is
2335  * positioned approximately between 50% and 70% of the height of this window,
2336  * and has 100% of the width. We create some widgets (two icons, a clock and a
2337  * button) and pack them inside the table, in a distribution similar to a HTML
2338  * table:
2339  *
2340  * @until evas_object_show(bt)
2341  *
2342  * Notice that we just set size hints for every object, and call the function
2343  * elm_layout_table_pack(), which does all the work. It will place the elements
2344  * in the specified row/column, with row and column span if required, and then
2345  * the object's size and position will be controled by the layout widget. It
2346  * will also respect size hints, alignments and weight properties set to these
2347  * widgets. The resulting distribution on the screen depends on the table
2348  * properties (described in the theme), the size hints set on each widget, and
2349  * on the cells of the table that are being used.
2350  *
2351  * For instance, we add the two icons and the clock on the first, second and
2352  * third cells of the first row, and add the button the second row, making it
2353  * span for 3 columns (thus having the size of the entire table width). This
2354  * will result in a table that has 2 rows and 3 columns.
2355  *
2356  * Now let's add some widgets to the box area of our layout. This box is around
2357  * 20% and 50% of the vertical size of the layout, and 100% of its width. The
2358  * theme defines that it will use an "horizontal flow" distribution to its
2359  * elements. Unlike the table, a box will distribute elements without knowing
2360  * about rows and columns, and the distribution function selected will take care
2361  * of putting them in row, column, both, or any other available layout. This is
2362  * also described in the Edje documentation.
2363  *
2364  * This box area is similar to the @ref Box widget of elementary, with the
2365  * difference that its position and properties are controled by the theme of the
2366  * layout. It also contains more than one API to add items to it, since the
2367  * items position now is defined in terms of a list of items, not a matrix.
2368  * There's the first position (can have items added to it with
2369  * elm_layout_box_prepend()), the last position (elm_layout_box_append()), the
2370  * nth position (elm_layout_box_insert_at()) and the position right before an
2371  * element (elm_layout_box_insert_before()). We use insert_at and prepend
2372  * functions to add the first two buttons to this box, and insert_before on the
2373  * callback of each button. The callback code will be shown later, but it
2374  * basically adds a button just before the clicked button using the
2375  * elm_layout_box_insert_before() function. Here's the code for adding the first
2376  * 2 buttons:
2377  *
2378  * @until evas_object_show(item)
2379  * @until evas_object_show(item)
2380  *
2381  * Finally, we have an area in this layout theme, in the bottom part of it,
2382  * reserved for adding an specific widget. Differently from the 2 parts
2383  * described until now, this one can only receive one widget with the call
2384  * elm_layout_content_set(). If there was already an item on this specific part,
2385  * it will be deleted (one can use elm_layout_content_unset() in order to remove
2386  * it without deleting). An example of removing it without deleting, but
2387  * manually deleting this widget just after that, can be seen on the callback
2388  * for this button. Actually, the callback defined for this button will clean
2389  * the two other parts (deleting all of their elements) and then remove and
2390  * delete this button.
2391  *
2392  * @until _swallow_btn_cb
2393  *
2394  * Also notice that, for this last added button, we don't have to call
2395  * evas_object_show() on it. This is a particularity of the theme for layouts,
2396  * that will have total control over the properties like size, position,
2397  * visibility and clipping of a widget added with elm_layout_content_set().
2398  * Again, read the Edje documentation to understand this better.
2399  *
2400  * Now we just put the code for the different callbacks specified for each kind
2401  * of button and make simple comments about them:
2402  *
2403  * @dontinclude layout_example_01.c
2404  * @skip static void
2405  * @until evas_object_del(item)
2406  * @until }
2407  *
2408  * The first callback is used for the button in the table, and will just remove
2409  * itself from the table with elm_layout_table_unpack(), which remove items
2410  * without deleting them, and then calling evas_object_del() on itself.
2411  *
2412  * The second callback is for buttons added to the box. When clicked, these
2413  * buttons will create a new button, and add them to the same box, in the
2414  * position just before the clicked button.
2415  *
2416  * And the last callback is for the button added to the "content" area. It will
2417  * clear both the table and the box, passing @c EINA_TRUE to their respective @c
2418  * clear parameters, which will imply on the items of these containers being
2419  * deleted.
2420  *
2421  * A screenshot of this example can be seen on:
2422  *
2423  * @image html screenshots/layout_example_01.png
2424  * @image latex screenshots/layout_example_01.eps width=\textwidth
2425  *
2426  */
2427
2428 /**
2429  * @page layout_example_02 Layout - Predefined Layout
2430  *
2431  * This example shows how one can use the @ref Layout with a predefined theme
2432  * layout to add a back and next button to a simple window. The full source code
2433  * for this example can be found at @ref layout_example_02_c.
2434  *
2435  * After setting up the window and background, we add the layout widget to the
2436  * window. But instead of using elm_layout_file_set() to load its theme from a
2437  * custom theme file, we can use elm_layout_theme_set() to load one of the
2438  * predefined layouts that come with elementary. Particularly on this example,
2439  * we load the them of class "layout", group "application" and style
2440  * "content-back-next" (since we want the back and next buttons).
2441  *
2442  * @dontinclude layout_example_02.c
2443  * @skip elm_layout_add
2444  * @until evas_object_show(layout)
2445  *
2446  * This default theme contains only a "content" area named
2447  * "elm.swallow.content", where we can add any widget (it can be even a
2448  * container widget, like a box, frame, list, or even another layout). Since we
2449  * just want to show the resulting layout, we add a simple icon to it:
2450  *
2451  * @until layout_content_set
2452  *
2453  * This default layout also provides some signals when the next and prev buttons
2454  * are clicked. We can register callbacks to them with the
2455  * elm_object_signal_callback_add() function:
2456  *
2457  * @until elm,action,next
2458  *
2459  * In the @ref layout_example_03 you can see how to send signals to the layout with
2460  * elm_object_signal_emit().
2461  *
2462  * Now our callback just changes the picture being displayed when one of the
2463  * buttons are clicked:
2464  *
2465  * @dontinclude layout_example_02.c
2466  * @skip images
2467  * @until standard_set
2468  * @until }
2469  *
2470  * It's possible to see that it gets the name of the image being shown from the
2471  * array of image names, going forward on this array when "next" is clicked and
2472  * backward when "back" is clicked.
2473  *
2474  * A screenshot of this example can be seen on:
2475  *
2476  * @image html screenshots/layout_example_02.png
2477  * @image latex screenshots/layout_example_02.eps width=\textwidth
2478  */
2479
2480 /**
2481  * @page layout_example_03 Layout - Signals and Size Changed
2482  *
2483  * This example shows how one can send and receive signals to/from the layout,
2484  * and what to do when the layout theme has its size changed. The full source
2485  * code for this example can be found at @ref layout_example_03_c.
2486  *
2487  * In this exmaple we will use another group from the same layout theme file
2488  * used in @ref layout_example_01. Its instanciation and loading happens in the
2489  * following lines:
2490  *
2491  * @dontinclude layout_example_03.c
2492  * @skip elm_layout_add
2493  * @until evas_object_show
2494  *
2495  * This time we register a callback to be called whenever we receive a signal
2496  * after the end of the animation that happens in this layout:
2497  *
2498  * @until signal_callback_add
2499  *
2500  * We also add a button that will send signals to the layout:
2501  *
2502  * @until callback_add
2503  *
2504  * The callback for this button will check what type of signal it should send,
2505  * and then emit it. The code for this callback follows:
2506  *
2507  * @dontinclude layout_exmaple_03.c
2508  * @skip static Eina_Bool
2509  * @until Enlarge
2510  * @until }
2511  * @until }
2512  *
2513  * As we said before, we are receiving a signal whenever the animation started
2514  * by the button click ends. This is the callback for that signal:
2515  *
2516  * @until }
2517  *
2518  * Notice from this callback that the elm_layout_sizing_eval() function must be
2519  * called if we want our widget to update its size after the layout theme having
2520  * changed its minimum size. This happens because the animation specified in the
2521  * theme increases the size of the content area to a value higher than the
2522  * widget size, thus requiring more space. But the elementary layout widget
2523  * has no way to know this, thus needing the elm_layout_sizing_eval() to
2524  * be called on the layout, informing that this size has changed.
2525  *
2526  * A screenshot of this example can be seen on:
2527  *
2528  * @image html screenshots/layout_example_03.png
2529  * @image latex screenshots/layout_example_03.eps width=\textwidth
2530  */
2531
2532 /**
2533  * @page tutorial_hover Hover example
2534  * @dontinclude hover_example_01.c
2535  *
2536  * On this example we are going to have a button that when clicked will show our
2537  * hover widget, this hover will have content set on it's left, top, right and
2538  * middle positions. In the middle position we are placing a button that when
2539  * clicked will hide the hover. We are also going to use a non-default theme
2540  * for our hover. We won't explain the functioning of button for that see @ref
2541  * Button.
2542  *
2543  * We start our example with a couple of callbacks that show and hide the data
2544  * they're given(which we'll see later on is the hover widget):
2545  * @skip static
2546  * @until }
2547  * @until }
2548  *
2549  * In our main function we'll do some initialization and then create 3
2550  * rectangles, one red, one green and one blue to use in our hover. We'll also
2551  * create the 2 buttons that will show and hide the hover:
2552  * @until show(bt2)
2553  *
2554  * With all of that squared away we can now get to the heart of the matter,
2555  * creating our hover widget, which is easy as pie:
2556  * @until hover
2557  *
2558  * Having created our hover we now need to set the parent and target. Which if
2559  * you recall from the function documentations are going to tell the hover which
2560  * area it should cover and where it should be centered:
2561  * @until bt
2562  *
2563  * Now we set the theme for our hover. We're using the popout theme which gives
2564  * our contents a white background and causes their appearance to be animated:
2565  * @until popout
2566  *
2567  * And finally we set the content for our positions:
2568  * @until bt2
2569  *
2570  * So far so good? Great 'cause that's all there is too it, what is left now is
2571  * just connecting our buttons to the callbacks we defined at the beginning of
2572  * the example and run the main loop:
2573  * @until ELM_MAIN
2574  *
2575  * Our example will initially look like this:
2576  *
2577  * @image html screenshots/hover_example_01.png
2578  * @image latex screenshots/hover_example_01.eps width=\textwidth
2579  *
2580  * And after you click the "Show hover" button it will look like this:
2581  *
2582  * @image html screenshots/hover_example_01_a.png
2583  * @image latex screenshots/hover_example_01_a.eps width=\textwidth
2584  *
2585  * @example hover_example_01.c
2586  */
2587
2588 /**
2589   * @page tutorial_flip Flip example
2590   * @dontinclude flip_example_01.c
2591   *
2592   * This example will show a flip with two rectangles on it(one blue, one
2593   * green). Our example will allow the user to choose the animation the flip
2594   * uses and to interact with it. To allow the user to choose the interaction
2595   * mode we use radio buttons, we will however not explain them, if you would
2596   * like to know more about radio buttons see @ref radio.
2597   *
2598   * We start our example with the usual setup and then create the 2 rectangles
2599   * we will use in our flip:
2600   * @until show(rect2)
2601   *
2602   * The next thing to do is to create our flip and set it's front and back
2603   * content:
2604   * @until show
2605   *
2606   * The next thing we do is set the interaction mode(which the user can later
2607   * change) to the page animation:
2608   * @until PAGE
2609   *
2610   * Setting a interaction mode however is not sufficient, we also need to
2611   * choose which directions we allow interaction from, for this example we
2612   * will use all of them:
2613   * @until RIGHT
2614   *
2615   * We are also going to set the hitsize to the entire flip(in all directions)
2616   * to make our flip very easy to interact with:
2617   * @until RIGHT
2618   *
2619   * After that we create our radio buttons and start the main loop:
2620   * @until ELM_MAIN()
2621   *
2622   * When the user clicks a radio button a function that changes the
2623   * interaction mode and animates the flip is called:
2624   * @until }
2625   * @note The elm_flip_go() call here serves no purpose other than to
2626   * ilustrate that it's possible to animate the flip programmatically.
2627   *
2628   * Our example will look like this:
2629   *
2630   * @image html screenshots/flip_example_01.png
2631   * @image latex screenshots/flip_example_01.eps width=\textwidth
2632   *
2633   * @note Since this is an animated example the screenshot doesn't do it
2634   * justice, it is a good idea to compile it and see the animations.
2635   *
2636   * @example flip_example_01.c
2637   */
2638
2639  /**
2640   * @page tutorial_label Label example
2641   * @dontinclude label_example_01.c
2642   *
2643   * In this example we are going to create 6 labels, set some properties on
2644   * them and see what changes in appearance those properties cause.
2645   *
2646   * We start with the setup code that by now you should be familiar with:
2647   * @until show(bg)
2648   *
2649   * For our first label we have a moderately long text(that doesn't fit in the
2650   * label's width) so we will make it a sliding label. Since the text isn't
2651   * too long we don't need the animation to be very long, 3 seconds should
2652   * give us a nice speed:
2653   * @until show(label
2654   *
2655   * For our second label we have the same text, but this time we aren't going
2656   * to have it slide, we're going to ellipsize it. Because we ask our label
2657   * widget to ellipsize the text it will first diminsh the fontsize so that it
2658   * can show as much of the text as possible:
2659   * @until show(label
2660   *
2661   * For the third label we are going to ellipsize the text again, however this
2662   * time to make sure the fontsize isn't diminshed we will set a line wrap.
2663   * The wrap won't actually cause a line break because we set the label to
2664   * ellipsize:
2665   * @until show(label
2666   *
2667   * For our fourth label we will set line wrapping but won't set ellipsis, so
2668   * that our text will indeed be wrapped instead of ellipsized. For this label
2669   * we choose character wrap:
2670   * @until show(label
2671   *
2672   * Just two more, for our fifth label we do the same as for the fourth
2673   * except we set the wrap to word:
2674   * @until show(label
2675   *
2676   * And last but not least for our sixth label we set the style to "marker" and
2677   * the color to red(the default color is white which would be hard to see on
2678   * our white background):
2679   * @until show(label
2680   *
2681   * Our example will look like this:
2682   *
2683   * @image html screenshots/label_example_01.png
2684   * @image latex screenshots/label_example_01.eps width=\textwidth
2685   *
2686   * @example label_example_01.c
2687   */
2688
2689  /**
2690   * @page tutorial_image Image example
2691   * @dontinclude image_example_01.c
2692   *
2693   * This example is as simple as possible. An image object will be added to the
2694   * window over a white background, and set to be resizeable together with the
2695   * window. All the options set through the example will affect the behavior of
2696   * this image.
2697   *
2698   * We start with the code for creating a window and its background, and also
2699   * add the code to write the path to the image that will be loaded:
2700   *
2701   * @skip int
2702   * @until snprintf
2703   *
2704   * Now we create the image object, and set that file to be loaded:
2705   *
2706   * @until }
2707   *
2708   * We can now go setting our options.
2709   *
2710   * elm_image_no_scale_set() is used just to set this value to true (we
2711   * don't want to scale our image anyway, just resize it).
2712   *
2713   * elm_image_scale_set() is used to allow the image to be resized to a size
2714   * smaller than the original one, but not to a size bigger than it.
2715   *
2716   * elm_elm_image_smooth_set() will disable the smooth scaling, so the scale
2717   * algorithm used to scale the image to the new object size is going to be
2718   * faster, but with a lower quality.
2719   *
2720   * elm_image_orient_set() is used to flip the image around the (1, 0) (0, 1)
2721   * diagonal.
2722   *
2723   * elm_image_aspect_ratio_retained_set() is used to keep the original aspect
2724   * ratio of the image, even when the window is resized to another aspect ratio.
2725   *
2726   * elm_image_fill_outside_set() is used to ensure that the image will fill the
2727   * entire area available to it, even if keeping the aspect ratio. The image
2728   * will overflow its width or height (any of them that is necessary) to the
2729   * object area, instead of resizing the image down until it can fit entirely in
2730   * this area.
2731   *
2732   * elm_image_editable_set() is used just to cover the API, but won't affect
2733   * this example since we are not using any copy & paste property.
2734   *
2735   * This is the code for setting these options:
2736   *
2737   * @until editable
2738   *
2739   * Now some last touches in our object size hints, window and background, to
2740   * display this image properly:
2741   *
2742   * @until ELM_MAIN
2743   *
2744   * This example will look like this:
2745   *
2746   * @image html screenshots/image_example_01.png
2747   * @image latex screenshots/image_example_01.eps width=\textwidth
2748   *
2749   * @example image_example_01.c
2750   */
2751
2752  /**
2753   * @page tutorial_icon Icon example
2754   * @dontinclude icon_example_01.c
2755   *
2756   * This example is as simple as possible. An icon object will be added to the
2757   * window over a white background, and set to be resizeable together with the
2758   * window. All the options set through the example will affect the behavior of
2759   * this icon.
2760   *
2761   * We start with the code for creating a window and its background:
2762   *
2763   * @skip int
2764   * @until show(bg)
2765   *
2766   * Now we create the icon object, and set lookup order of the icon, and choose
2767   * the "home" icon:
2768   *
2769   * @until home
2770   *
2771   * An intersting thing is that after setting this, it's possible to check where
2772   * in the filesystem is the theme used by this icon, and the name of the group
2773   * used:
2774   *
2775   * @until printf
2776   *
2777   * We can now go setting our options.
2778   *
2779   * elm_icon_no_scale_set() is used just to set this value to true (we
2780   * don't want to scale our icon anyway, just resize it).
2781   *
2782   * elm_icon_scale_set() is used to allow the icon to be resized to a size
2783   * smaller than the original one, but not to a size bigger than it.
2784   *
2785   * elm_elm_icon_smooth_set() will disable the smooth scaling, so the scale
2786   * algorithm used to scale the icon to the new object size is going to be
2787   * faster, but with a lower quality.
2788   *
2789   * elm_icon_fill_outside_set() is used to ensure that the icon will fill the
2790   * entire area available to it, even if keeping the aspect ratio. The icon
2791   * will overflow its width or height (any of them that is necessary) to the
2792   * object area, instead of resizing the icon down until it can fit entirely in
2793   * this area.
2794   *
2795   * This is the code for setting these options:
2796   *
2797   * @until fill_outside
2798   *
2799   * However, if you try this example you may notice that this image is not being
2800   * affected by all of these options. This happens because the used icon will be
2801   * from elementary theme, and thus it has its own set of options like smooth
2802   * scaling and fill_outside options. You can change the "home" icon to use some
2803   * image (from your system) and see that then those options will be respected.
2804   *
2805   * Now some last touches in our object size hints, window and background, to
2806   * display this icon properly:
2807   *
2808   * @until ELM_MAIN
2809   *
2810   * This example will look like this:
2811   *
2812   * @image html screenshots/icon_example_01.png
2813   * @image latex screenshots/icon_example_01.eps width=\textwidth
2814   *
2815   * @example icon_example_01.c
2816   */
2817
2818 /**
2819  * @page tutorial_hoversel Hoversel example
2820  * @dontinclude hoversel_example_01.c
2821  *
2822  * In this example we will create a hoversel with 3 items, one with a label but
2823  * no icon and two with both a label and an icon. Every item that is clicked
2824  * will be deleted, but everytime the hoversel is activated we will also add an
2825  * item. In addition our first item will print all items when clicked and our
2826  * third item will clear all items in the hoversel.
2827  *
2828  * We will start with the normal creation of window stuff:
2829  * @until show(bg)
2830  *
2831  * Next we will create a red rectangle to use as the icon of our hoversel:
2832  * @until show
2833  *
2834  * And now we create our hoversel and set some of it's properties. We set @p win
2835  * as its parent, ask it to not be horizontal(be vertical) and give it a label
2836  * and icon:
2837  * @until icon_set
2838  *
2839  * Next we will add our three items, setting a callback to be called for the
2840  * first and third:
2841  * @until _rm_items
2842  *
2843  * We also set a pair of callbacks to be called whenever any item is selected or
2844  * when the hoversel is activated:
2845  * @until clicked
2846  *
2847  * And then ask that our hoversel be shown and run the main loop:
2848  * @until ELM_MAIN
2849  *
2850  * We now have the callback for our first item which prints all items in the
2851  * hoversel:
2852  * @until }
2853  *
2854  * Next we have the callback for our third item which removes all items from the
2855  * hoversel:
2856  * @until }
2857  *
2858  * Next we have the callback that is called whenever an item is clicked and
2859  * deletes that item:
2860  * @until }
2861  *
2862  * And the callback that is called when the hoversel is activated and adds an
2863  * item to the hoversel. Note that since we allocate memory for the item we need
2864  * to know when the item dies so we can free that memory:
2865  * @until }
2866  *
2867  * And finally the callback that frees the memory we allocated for items created
2868  * in the @p _add_item callback:
2869  * @until }
2870  *
2871  * Our example will initially look like this:
2872  *
2873  * @image html screenshots/hoversel_example_01.png
2874  * @image latex screenshots/hoversel_example_01.eps width=\textwidth
2875  *
2876  * And when the hoversel is clicked it will look like this:
2877  *
2878  * @image html screenshots/hoversel_example_01_a.png
2879  * @image latex screenshots/hoversel_example_01_a.eps width=\textwidth
2880  *
2881  * @example hoversel_example_01.c
2882  */
2883
2884 /**
2885  * @page conformant_example Conformant Example.
2886  *
2887  * In this example we'll explain how to create applications to work
2888  * with illume, considering space required for virtual keyboards, indicator
2889  * and softkeys.
2890  *
2891  * Illume is a module for Enlightenment that modifies the user interface
2892  * to work cleanly and nicely on a mobile device. It has support for
2893  * virtual keyboard, among other nice features.
2894  *
2895  * Let's start creating a very simple window with a vertical box
2896  * with multi-line entry between two buttons.
2897  * This entry will expand filling all space on window not used by buttons.
2898  *
2899  * @dontinclude conformant_example_01.c
2900  * @skipline elm_main
2901  * @until }
2902  *
2903  * For information about how to create windows, boxes, buttons or entries,
2904  * look for documentation for these widgets.
2905  *
2906  * It will looks fine when you don't need a virtual keyboard, as you
2907  * can see on the following image:
2908  *
2909  * @image html screenshots/conformant_example_01.png
2910  * @image latex screenshots/conformant_example_01.eps width=\textwidth
2911  *
2912  * But if you call a virtual keyboard, the window will resize, changing
2913  * widgets size and position. All the content will shrink.
2914  *
2915  * If you don't want such behaviour, you
2916  * will need a conformant to account for space taken up by the indicator,
2917  * virtual keyboard and softkey.
2918  *
2919  * In this case, using the conformant in a proper way, you will have
2920  * a window like the following:
2921  *
2922  * @image html screenshots/conformant_example_02.png
2923  * @image latex screenshots/conformant_example_02.eps width=\textwidth
2924  *
2925  * As you can see, it guess the space that will be required by the keyboard,
2926  * indicator and softkey bars.
2927  *
2928  * So, let's study each step required to transform our initial example on
2929  * the second one.
2930  *
2931  * First of all, we need to set the window as an illume conformant window:
2932  * @dontinclude conformant_example_02.c
2933  * @skipline elm_win_conformant_set
2934  *
2935  * Next, we'll add a conformant widget, and set it to resize with the window,
2936  * instead of the box.
2937  * @skipline conform
2938  * @until evas_object_show
2939  *
2940  * Finally, we'll set the box as conformant's content, just like this:
2941  * @skipline elm_conformant_content_set
2942  *
2943  * Compare both examples code:
2944  * @ref conformant_example_01.c "conformant_example_01.c"
2945  * @ref conformant_example_02.c "conformant_example_02.c"
2946  *
2947  * @example conformant_example_01.c
2948  * @example conformant_example_02.c
2949  */
2950
2951 /**
2952  * @page index_example_01 Index widget example 1
2953  *
2954  * This code places an Elementary index widget on a window, which also
2955  * has a very long list of arbitrary strings on it.  The list is
2956  * sorted alphabetically and the index will be used to index the first
2957  * items of each set of strings beginning with an alphabet letter.
2958  *
2959  * Below the list are some buttons, which are there just to exercise
2960  * some index widget's API.
2961  *
2962  * Here's how we instantiate it:
2963  * @dontinclude index_example_01.c
2964  * @skip elm_list_add
2965  * @until evas_object_show(d.index)
2966  * where we're showing also the list being created. Note that we issue
2967  * elm_win_resize_object_add() on the index, so that it's set to have
2968  * the whole window as its container. Then, we have to populate both
2969  * list and index widgets:
2970  * @dontinclude index_example_01.c
2971  * @skip for (i = 0; i < (sizeof(dict) / sizeof(dict[0])); i++)
2972  * @until }
2973  * @until }
2974  *
2975  * The strings populating the list come from a file
2976  * @dontinclude index_example_01.c
2977  * @skip static const char *dict
2978  * @until }
2979  *
2980  * We use the @c curr char variable to hold the last initial letter
2981  * seen on that ordered list of strings, so that we're able to have an
2982  * index item pointing to each list item starting a new letter
2983  * "section". Note that our index item data pointers will be the list
2984  * item handles. We are also setting a callback function to index
2985  * items deletion events:
2986  * @dontinclude index_example_01.c
2987  * @skip static void
2988  * @until }
2989  *
2990  * There, we show you that the @c event_info pointer will contain the
2991  * item in question's data, i.e., a given list item's pointer. Because
2992  * item data is also returned in the @c data argument on
2993  * @c Evas_Smart_Cb functions, those two pointers must have the same
2994  * values. On this deletion callback, we're deleting the referred list
2995  * item too, just to exemplify that anything could be done there.
2996  *
2997  * Next, we hook to two smart events of the index object:
2998  * @dontinclude index_example_01.c
2999  * @skip smart_callback_add(d.index
3000  * @until _index_selected
3001  * @dontinclude index_example_01.c
3002  * @skip "delay,changed" hook
3003  * @until }
3004  * @until }
3005  *
3006  * Check that, whenever one holds the mouse pressed over a given index
3007  * letter for some time, the list beneath it will roll down to the
3008  * item pointed to by that index item. When one releases the mouse
3009  * button, the second callback takes place. There, we check that the
3010  * reported item data, on @c event_info, is the same reported by
3011  * elm_index_item_selected_get(), which gives the last selection's
3012  * data on the index widget.
3013  *
3014  * The first of the three buttons that follow will call
3015  * elm_index_active_set(), thus showing the index automatically for
3016  * you, if it's not already visible, what is checked with
3017  * elm_index_active_get(). The second button will exercise @b deletion
3018  * of index item objects, by the following code:
3019  * @dontinclude index_example_01.c
3020  * @skip delete an index item
3021  * @until }
3022  *
3023  * It will get the last index item selected's data and find the
3024  * respective #Elm_Index_Item handle with elm_index_item_find(). We
3025  * need the latter to query the indexing letter string from, with
3026  * elm_index_item_letter_get(). Next, comes the delition, itself,
3027  * which will also trigger the @c _index_item_del callback function,
3028  * as said above.
3029  *
3030  * The third button, finally, will exercise elm_index_item_clear(),
3031  * which will delete @b all of the index's items.
3032  *
3033  * This is how the example program's window looks like with the index
3034  * widget hidden:
3035  * @image html screenshots/index_example_00.png
3036  * @image latex screenshots/index_example_00.eps
3037  *
3038  * When it's shown, it's like the following figure:
3039  * @image html screenshots/index_example_01.png
3040  * @image latex screenshots/index_example_01.eps
3041  *
3042  * See the full @ref index_example_01_c "source code" for
3043  * this example.
3044  *
3045  * @example index_example_01.c
3046  */
3047
3048 /**
3049  * @page index_example_02 Index widget example 2
3050  *
3051  * This code places an Elementary index widget on a window, indexing
3052  * grid items. The items are placed so that their labels @b don't
3053  * follow any order, but the index itself is ordered (through
3054  * elm_index_item_sorted_insert()). This is a complement to to @ref
3055  * index_example_01 "the first example on indexes".
3056  *
3057  * Here's the list of item labels to be used on the grid (in that
3058  * order):
3059  * @dontinclude index_example_02.c
3060  * @skip static const char *items
3061  * @until };
3062  *
3063  * In the interesting part of the code, here, we first instantiate the
3064  * grid (more on grids on their examples) and, after creating our
3065  * index, for each grid item we also create an index one to reference
3066  * it:
3067  * @dontinclude index_example_02.c
3068  * @skip grid = elm_gengrid_add
3069  * @until }
3070  * @until smart_callback_add
3071  *
3072  * The order in which they'll appear in the index, though, is @b
3073  * alphabetical, becase of elm_index_item_sorted_insert() usage
3074  * together with the comparing function, where we take the letters of
3075  * each index item to base our ordering on. The parameters on
3076  * @c _index_cmp have to be declared as void pointers because of the
3077  * @c Eina_Compare_Cb prototype requisition, but in this case we know
3078  * they'll be #Elm_Index_Item's:
3079  * @dontinclude index_example_02.c
3080  * @skip ordering alphabetically
3081  * @until }
3082  *
3083  * The last interesting bit is the callback in the @c "delay,changed"
3084  * smart event, which will bring the given grid item to the grid's
3085  * visible area:
3086  * @dontinclude index_example_02.c
3087  * @skip static void
3088  * @until }
3089  *
3090  * Note how the grid will move kind of randomly while you move your
3091  * mouse pointer held over the index from top to bottom -- that's
3092  * because of the the random order the items have in the grid itself.
3093  *
3094  * This is how the example program's window looks like:
3095  * @image html screenshots/index_example_03.png
3096  * @image latex screenshots/index_example_03.eps
3097  *
3098  * See the full @ref index_example_c "source code" for
3099  * this example.
3100  *
3101  * @example index_example_02.c
3102  */
3103
3104 /**
3105  * @page tutorial_ctxpopup Ctxpopup example
3106  * @dontinclude ctxpopup_example_01.c
3107  *
3108  * In this example we have a list with two items, when either item is clicked
3109  * a ctxpopup for it will be shown. Our two ctxpopups are quite different, the
3110  * one for the first item is a vertical and it's items contain both labels and
3111  * icons, the one for the second item is horizontal and it's items have icons
3112  * but not labels.
3113  *
3114  * We will begin examining our example code by looking at the callback we'll use
3115  * when items in the ctxpopup are clicked. It's very simple, all it does is
3116  * print the label present in the ctxpopup item:
3117  * @until }
3118  *
3119  * Next we examine a function that creates ctxpopup items, it was created to
3120  * avoid repeating the same code whenever we needed to add an item to our
3121  * ctxpopup. Our function creates an icon from the standard set of icons, and
3122  * then creates the item, with the label received as an argument. We also set
3123  * the callback to be called when the item is clicked:
3124  * @until }
3125  *
3126  * Finally we have the function that will create the ctxpopup for the first item
3127  * in our list. This one is somewhat more complex though, so let's go through it
3128  * in parts. First we declare our variable and add the ctxpopup:
3129  * @until ctxpopup_add
3130  *
3131  * Next we create a bunch of items for our ctxpopup, marking two of them as
3132  * disabled just so we can see what that will look like:
3133  * @until disabled_set
3134  * @until disabled_set
3135  *
3136  * Then we ask evas where the mouse pointer was so that we can have our ctxpopup
3137  * appear in the right place, set a maximum size for the ctxpopup, move it and
3138  * show it:
3139  * @until show
3140  *
3141  * And last we mark the list item as not selected:
3142  * @until }
3143  *
3144  * Our next function is the callback that will create the ctxpopup for the
3145  * second list item, it is very similar to the previous function. A couple of
3146  * interesting things to note is that we ask our ctxpopup to be horizontal, and
3147  * that we pass NULL as the label for every item:
3148  * @until }
3149  *
3150  * And with all of that in place we can now get to our main function where we
3151  * create the window, the list, the list items and run the main loop:
3152  * @until ELM_MAIN()
3153  *
3154  * The example will initially look like this:
3155  *
3156  * @image html screenshots/ctxpopup_example_01.png
3157  * @image latex screenshots/ctxpopup_example_01.eps width=\textwidth
3158  *
3159  * @note This doesn't show the ctxpopup tough, since it will only appear when
3160  * we click one of the list items.
3161  *
3162  * Here is what our first ctxpopup will look like:
3163  *
3164  * @image html screenshots/ctxpopup_example_01_a.png
3165  * @image latex screenshots/ctxpopup_example_01_a.eps width=\textwidth
3166  *
3167  * And here the second ctxpopup:
3168  *
3169  * @image html screenshots/ctxpopup_example_01_b.png
3170  * @image latex screenshots/ctxpopup_example_01_b.eps width=\textwidth
3171  *
3172  * @example ctxpopup_example_01.c
3173  */
3174
3175 /**
3176  * @page tutorial_pager
3177  * @dontinclude pager_example_01.c
3178  *
3179  * In this example we'll have a pager with 3 rectangles on it, one blue, one
3180  * green and one blue, we'll also have 1 button for each rectangle. Pressing a
3181  * button will bring the associated rectangle to the front of the pager(promote
3182  * it).
3183  *
3184  * We start our example with some run of the mill code that you've seen in other
3185  * examples:
3186  * @until show
3187  *
3188  * And then we get right to creating our pager, setting a style and some basic
3189  * properties to it:
3190  * @until show
3191  *
3192  * Well a pager without any content is not of much use, so let's create the
3193  * first of our rectangles, add it to the pager and create the button for it:
3194  * @until smart_callback
3195  * @note The only line of above code that directly relates to our pager is the
3196  * call to elm_pager_content_push().
3197  *
3198  * And now we will do the same thing again twice for our next two rectangles:
3199  * @until smart_callback
3200  * @until smart_callback
3201  *
3202  * Now that we haver our widgets create we can get to running the main loop:
3203  * @until ELM_MAIN
3204  *
3205  * We also have the callback that is called when any of the buttons is pressed,
3206  * this callback is receiving the rectangle in it's @p data argument, so we
3207  * check if it's already on top and if not move it there:
3208  * @until }
3209  *
3210  * Our example will look like this:
3211  *
3212  * @image html screenshots/pager_example_01.png
3213  * @image latex screenshots/pager_example_01.eps width=\textwidth
3214  * @note Like all examples that involve animations the screenshot doesn't do it
3215  * justice, seeing it in action is a must.
3216  *
3217  * @example pager_example_01.c
3218  */
3219
3220 /**
3221  * @page tutorial_separator Separator example
3222  * @dontinclude separator_example_01.c
3223  *
3224  * In this example we are going to pack two rectangles in a box, and have a
3225  * separator in the middle.
3226  *
3227  * So we start we the window, background, box and rectangle creation, all pretty
3228  * normal stuff:
3229  * @until pack_end
3230  *
3231  * Once we have our first rectangle in the box we create and add our separator:
3232  * @until pack_end
3233  * @note Since our box is in horizontal mode it's a good idea to set the
3234  * separator to be horizontal too.
3235  *
3236  * And now we add our second rectangle and run the main loop:
3237  * @until ELM_MAIN
3238  *
3239  * This example will look like this:
3240  *
3241  * @image html screenshots/separator_example_01.png
3242  * @image eps screenshots/separator_example_01.eps width=\textwidth
3243  *
3244  * @example separator_example_01.c
3245  */
3246
3247 /**
3248  * @page tutorial_radio Radio example
3249  * @dontinclude radio_example_01.c
3250  *
3251  * In this example we will create 4 radio buttons, three of them in a group and
3252  * another one not in the group. We will also have the radios in the group
3253  * change the value of a variable directly and have then print it when the value
3254  * changes. The fourth button is in the example just to make clear that radios
3255  * outside the group don't affect the group.
3256  *
3257  * We'll start with the usual includes:
3258  * @until #endif
3259  *
3260  * And move right to declaring a static variable(the one whose value the radios
3261  * will change):
3262  * @until static
3263  *
3264  * We now need to have a window and all that good stuff to be able to place our
3265  * radios in:
3266  * @until show(bx)
3267  *
3268  * And now we create a radio button, since this is the first button in our group
3269  * we set the group to be the radio(so we can set the other radios in the same
3270  * group). We also set the state value of this radio to 1 and the value pointer
3271  * to @p val, since val is @p 1 this has the additional effect of setting the
3272  * radio value to @p 1. For this radio we choose the default home icon:
3273  * @until show
3274  *
3275  * To check that our radio buttons are working we'll add a callback to the
3276  * "changed" signal of the radio:
3277  * @until smart_callback
3278  *
3279  * The creation of our second radio button is almost identical, the 2
3280  * differences worth noting are, the value of this radio 2 and that we add this
3281  * radio to the group of the first radio:
3282  * @until smart_callback
3283  *
3284  * For our third callback we'll omit the icon and set the value to 3, we'll also
3285  * add it to the group of the first radio:
3286  * @until smart_callback
3287  *
3288  * Our fourth callback has a value of 4, no icon and most relevantly is not a
3289  * member of the same group as the other radios:
3290  * @until show
3291  *
3292  * We finally run the main loop:
3293  * @until ELM_MAIN
3294  *
3295  * And the last detail in our example is the callback that prints @p val so that
3296  * we can see that the radios are indeed changing its value:
3297  * @until }
3298  *
3299  * The example will look like this:
3300  *
3301  * @image html screenshots/radio_example_01.png
3302  * @image latex screenshots/radio_example_01.epx width=\textwidth
3303  *
3304  * @example radio_example_01.c
3305  */
3306
3307 /**
3308  * @page tutorial_toggle Toggle example
3309  * @dontinclude toggle_example_01.c
3310  *
3311  * In this example we'll create 2 toggle widgets. The first will have an icon
3312  * and the state names will be the default "on"/"off", it will also change the
3313  * value of a variable directly. The second won't have a icon, the state names
3314  * will be "Enabled"/"Disabled", it will  start "Enabled" and it won't set the
3315  * value of a variable.
3316  *
3317  * We start with the usual includes and prototype for callback which will be
3318  * implemented and detailed later on:
3319  * @until _cb2
3320  *
3321  * We then declare a static global variable(the one whose value will be changed
3322  * by the first toggle):
3323  * @until static
3324  *
3325  * We now have to create our window and all that usual stuff:
3326  * @until show(bx)
3327  *
3328  * The creation of a toggle is no more complicated than that of any other
3329  * widget:
3330  * @until add
3331  *
3332  * For our first toggle we don't set the states labels so they will stay the
3333  * default, however we do set a label for the toggle, an icon and the variable
3334  * whose value it should change:
3335  * @until show
3336  *
3337  * We also set the callback that will be called when the toggles value changes:
3338  * @until smart_callback
3339  *
3340  * For our second toggle it important to note that we set the states labels,
3341  * don't set an icon or variable, but set the initial state to
3342  * EINA_TRUE("Enabled"):
3343  * @until show
3344  *
3345  * For the second toggle we will use a different callback:
3346  * @until smart_callback
3347  *
3348  * We then ask the main loop to start:
3349  * @until ELM_MAIN
3350  *
3351  * The callback for our first toggle will look the value of @p val and print it:
3352  * @until }
3353  *
3354  * For our second callback we need to do a little bit more, since the second
3355  * toggle doesn't change the value of a variable we have to ask it what its
3356  * state is:
3357  * @until }
3358  *
3359  * This example will look like this:
3360  *
3361  * @image html screenshots/toggle_example_01.png
3362  * @image latex screenshots/toggle_example_01.eps width=\textwidth
3363  *
3364  * @example toggle_example_01.c
3365  */
3366
3367 /**
3368  * @page tutorial_panel Panel example
3369  * @dontinclude panel_example_01.c
3370  *
3371  * In this example will have 3 panels, one for each possible orientation. Two of
3372  * our panels will start out hidden, the third will start out expanded. For each
3373  * of the panels we will use a label as the content, it's however possible to
3374  * have any widget(including containers) as the content of panels.
3375  *
3376  * We start by doing some setup, code you should be familiar with from other
3377  * examples:
3378  * @until show(bx)
3379  *
3380  * And move right to creating our first panel, for this panel we are going to
3381  * choose the orientation as TOP and toggle it(tell it to hide itself):
3382  * @until pack_end
3383  *
3384  * For the second panel we choose the RIGHT orientation and explicitly set the
3385  * state as hidden:
3386  * @until pack_end
3387  *
3388  * For our third and last panel we won't set the orientation(which means it will
3389  * use the default: LEFT):
3390  * @until pack_end
3391  *
3392  * All that is left is running the main loop:
3393  * @until ELM_MAIN
3394  *
3395  * This example will look like this;
3396  *
3397  * @image html screenshots/panel_example_01.png
3398  * @image latex screenshots/panel_example_01.epx width=\textwidth
3399  * @note The buttons with arrow allow the user to hide/show the panels.
3400  *
3401  * @example panel_example_01.c
3402  */
3403
3404 /**
3405  * @page gengrid_example Gengrid widget example
3406  *
3407  * This application is a thorough exercise on the gengrid widget's
3408  * API. We place an Elementary gengrid widget on a window, with
3409  * various knobs below its viewport, each one acting on it somehow.
3410  *
3411  * The code's relevant part begins at the grid's creation. After
3412  * instantiating it, we set its items sizes, so that we don't end with
3413  * items one finger size wide, only. We're setting them to fat, 150
3414  * pixel wide ones, for this example. We give it some size hints, not
3415  * to be discussed in this context and, than, we register a callback
3416  * on one of its smart events -- the one coming each time an item gets
3417  * doubly clicked. There, we just print the item handle's value.
3418  * @dontinclude gengrid_example.c
3419  * @skip grid = elm_gengrid_add
3420  * @until evas_object_sho
3421  * @dontinclude gengrid_example.c
3422  * @skip item double click callback
3423  * @until }
3424  *
3425  * Before we actually start to deal with the items API, let's show
3426  * some things items will be using throughout all the code. The first
3427  * of them is a struct to be used as item data, for all of them:
3428  * @dontinclude gengrid_example.c
3429  * @skip typedef struct
3430  * @until Item;
3431  *
3432  * That path will be used to index an image, to be swallowed into one
3433  * of the item's icon spots. The imagens themselves are distributed
3434  * with Elementary:
3435  * @dontinclude gengrid_example.c
3436  * @skip static const char *imgs
3437  * @until ;
3438  *
3439  * We also have an (unique) gengrid item class we'll be using for
3440  * items in the example:
3441  * @dontinclude gengrid_example.c
3442  * @skip static Elm_Gengrid_Item_Class
3443  * @until static Elm_Gengrid_Item_Class
3444  * @dontinclude gengrid_example.c
3445  * @skip item_style =
3446  * @until _grid_del
3447  *
3448  * As you see, our items will follow the default theme on gengrid
3449  * items. For the label fetching code, we return a string composed of
3450  * the item's image path:
3451  * @dontinclude gengrid_example.c
3452  * @skip label fetching callback
3453  * @until }
3454  *
3455  * For item icons, we'll be populating the item default theme's two
3456  * icon spots, @c "elm.swallow.icon" and @c "elm.swallow.end". The
3457  * former will receive one of the images in our list (in the form of
3458  * a @ref bg_02_example_page "background"), while the latter will be
3459  * a check widget. Note that we prevent the check to propagate click
3460  * events, so that the user can toggle its state without messing with
3461  * the respective item's selection in the grid:
3462  * @dontinclude gengrid_example.c
3463  * @skip icon fetching callback
3464  * @until return NULL
3465  * @until }
3466  *
3467  * As the default gengrid item's theme does not have parts
3468  * implementing item states, we'll be just returning false for every
3469  * item state:
3470  * @dontinclude gengrid_example.c
3471  * @skip state fetching callback
3472  * @until }
3473  *
3474  * Finally, the deletion callback on gengrid items takes care of
3475  * freeing the item's label string and its data struct:
3476  * @dontinclude gengrid_example.c
3477  * @skip deletion callback
3478  * @until }
3479  *
3480  * Let's move to item insertion/deletion knobs, them. They are four
3481  * buttons, above the grid's viewport, namely
3482  * - "Append" (to append an item to the grid),
3483  * - "Prepend" (to prepend an item to the grid),
3484  * - "Insert before" (to insert an item before the selection, on the
3485  *   grid),
3486  * - "Insert after" (to insert an item after the selection, on the
3487  *   grid),
3488  * - "Clear" (to delete all items in the grid),
3489  * - "Bring in 1st" (to make the 1st item visible, by scrolling),
3490  * - "Show last" (to directly show the last item),
3491  * .
3492  * which are displaced and declared in that order. We're not dealing
3493  * with the buttons' creation code (see @ref button_example_01
3494  * "a button example", for more details on it), but with their @c
3495  * "clicked" registered callbacks.  For all of them, the grid's handle
3496  * is passed as @c data. The ones creating new items use a common
3497  * code, which just gives a new @c Example_Item struct, with @c path
3498  * filled with a random image in our images list:
3499  * @dontinclude gengrid_example.c
3500  * @skip new item with random path
3501  * @until }
3502  *
3503  * Moreover, that ones will set a common function to be issued on the
3504  * selection of the items. There, we print the item handle's value,
3505  * along with the callback function data. The latter will be @c NULL,
3506  * always, because it's what we pass when adding all icons. By using
3507  * elm_gengrid_item_data_get(), we can have the item data back and,
3508  * with that, we're priting the item's path string. Finally, we
3509  * exemplify elm_gengrid_item_pos_get(), printing the item's position
3510  * in the grid:
3511  * @dontinclude gengrid_example.c
3512  * @skip item selection callback
3513  * @until }
3514  *
3515  * The appending button will exercise elm_gengrid_item_append(), simply:
3516  * @dontinclude gengrid_example.c
3517  * @skip append an item
3518  * @until }
3519  *
3520  * The prepending, naturally, is analogous, but exercising
3521  * elm_gengrid_item_prepend(), on its turn. The "Insert before" one
3522  * will expect an item to be selected in the grid, so that it will
3523  * insert a new item just before it:
3524  * @dontinclude gengrid_example.c
3525  * @skip "insert before" callback
3526  * @until }
3527  *
3528  * The "Insert after" is analogous, just using
3529  * elm_gengrid_item_insert_after(), instead. The "Clear" button will,
3530  * as expected, just issue elm_gengrid_clear():
3531  * @dontinclude gengrid_example.c
3532  * @skip delete items
3533  * @until }
3534  *
3535  * The "Bring in 1st" button is there exercise two gengrid functions
3536  * -- elm_gengrid_first_item_get() and elm_gengrid_item_bring_in().
3537  * With the former, we get a handle to the first item and, with the
3538  * latter, you'll see that the widget animatedly scrolls its view
3539  * until we can see that item:
3540  * @dontinclude gengrid_example.c
3541  * @skip bring in 1st item
3542  * @until }
3543  *
3544  * The "Show last", in its turn, will use elm_gengrid_last_item_get()
3545  * and elm_gengrid_item_show(). The latter differs from
3546  * elm_gengrid_item_bring_in() in that it immediately replaces the
3547  * contents of the grid's viewport with the region containing the item
3548  * in question:
3549  * @dontinclude gengrid_example.c
3550  * @skip show last item
3551  * @until }
3552  *
3553  * To change the grid's cell (items) size, we've placed a spinner,
3554  * which has the following @c "changed" smart callback:
3555  * @dontinclude gengrid_example.c
3556  * @skip change items' size
3557  * @until }
3558  *
3559  * Experiment with it and see how the items are affected. The "Disable
3560  * item" button will, as the name says, disable the currently selected
3561  * item:
3562  * @dontinclude gengrid_example.c
3563  * @skip disable selected item
3564  * @until }
3565  * Note that we also make use of elm_gengrid_item_selected_set(),
3566  * there, thus making the item unselected before we actually disable
3567  * it.
3568  *
3569  * To toggle between horizontal and vertical layouting modes on the
3570  * grid, use the "Horizontal mode" check, which will call the
3571  * respective API function on the grid:
3572  * @dontinclude gengrid_example.c
3573  * @skip change layouting mode
3574  * @until }
3575  *
3576  * If you toggle the check right after that one, "Always select",
3577  * you'll notice all subsequent clicks on the @b same grid item will
3578  * still issue the selection callback on it, what is different from
3579  * when it's not checked. This is the
3580  * elm_gengrid_always_select_mode_set() behavior:
3581  * @dontinclude gengrid_example.c
3582  * @skip "always select" callback
3583  * @until }
3584  *
3585  * One more check follows, "Bouncing", which will turn on/off the
3586  * bouncing animations on the grid, when one scrolls past its
3587  * borders. Experiment with scrolling the grid to get the idea, having
3588  * it turned on and off:
3589  * @dontinclude gengrid_example.c
3590  * @skip "bouncing mode" callback
3591  * @until }
3592  *
3593  * The next two checks will affect items selection on the grid. The
3594  * first, "Multi-selection", will make it possible to select more the
3595  * one item on the grid. Because it wouldn't make sense to fetch for
3596  * an unique selected item on this case, we also disable two of the
3597  * buttons, which insert items relatively, if multi-selection is on:
3598  * @dontinclude gengrid_example.c
3599  * @skip multi-selection callback
3600  * @until }
3601  *
3602  * Note that we also @b unselect all items in the grid, when returning
3603  * from multi-selection mode, making use of
3604  * elm_gengrid_item_selected_set().
3605  *
3606  * The second check acting on selection, "No selection", is just what
3607  * its name depicts -- no selection will be allowed anymore, on the
3608  * grid, while it's on. Check it out for yourself, interacting with
3609  * the program:
3610  * @dontinclude gengrid_example.c
3611  * @skip no selection callback
3612  * @until }
3613  *
3614  * We have, finally, one more line of knobs, now sliders, to change
3615  * the grids behavior. The two first will change the horizontal @b
3616  * alignment of the whole actual grid of items within the gengrid's
3617  * viewport:
3618  * @dontinclude gengrid_example.c
3619  * @skip items grid horizontal alignment change
3620  * @until }
3621  *
3622  * Naturally, the vertical counterpart just issues
3623  * elm_gengrid_align_set() changing the second alignment component,
3624  * instead.
3625  *
3626  * The last slider will change the grid's <b>page size</b>, relative
3627  * to its own one. Try to change those values and, one manner of
3628  * observing the paging behavior, is to scroll softly and release the
3629  * mouse button, with different page sizes, at different grid
3630  * positions, while having lots of items in it -- you'll see it
3631  * snapping to page boundaries differenty, for each configuration:
3632  * @dontinclude gengrid_example.c
3633  * @skip page relative size change
3634  * @until }
3635  *
3636  * This is how the example program's window looks like:
3637  * @image html screenshots/gengrid_example.png
3638  * @image latex screenshots/gengrid_example.eps width=\textwidth
3639  *
3640  * Note that it starts with three items which we included at will:
3641  * @dontinclude gengrid_example.c
3642  * @skip _clicked(grid,
3643  * @until _clicked(grid,
3644  * @until _clicked(grid,
3645  * @until _clicked(grid,
3646  *
3647  * See the full @ref gengrid_example_c "source code" for
3648  * this example.
3649  *
3650  * @example gengrid_example.c
3651  */
3652 /**
3653  * @page entry_example_01 Entry - Example of simple editing
3654  *
3655  * As a general overview of @ref Entry we are going to write an, albeit simple,
3656  * functional editor. Although intended to show how elm_entry works, this
3657  * example also makes extensive use of several other widgets. The full code
3658  * can be found in @ref entry_example.c "entry_example.c" and in the following
3659  * lines we'll go through the parts especific to the @ref Entry widget.
3660  *
3661  * The program itself is a simple editor, with a file already set to it, that
3662  * can be set to autosave or not and allows insertion of emoticons and some
3663  * formatted text. As of this writing, the capabilities of format edition in
3664  * the entry are very limited, so a lot of manual work is required to change
3665  * the current text.
3666  *
3667  * In any case, the program allows some changes by using the buttons on the
3668  * top of the window and returning focus back to the main entry afterwards.
3669  *
3670  * @image html screenshots/entry_example.png
3671  * @image latex screenshots/entry_example.eps width=\textwidth
3672  *
3673  * We'll begin by showing a few structures used throught the program. First,
3674  * the application owns data that holds the main window and the main entry
3675  * where the editting happens. Then, an auxiliar structure we'll use later
3676  * when inserting icons in our text.
3677  * @dontinclude entry_example.c
3678  * @skip typedef
3679  * @until App_Inwin_Data
3680  *
3681  * A little convenience function will insert whatever text we need in the
3682  * buffer at the current cursor's position and set focus back to this entry.
3683  * This is done mostly because clicking on any button will make them steal
3684  * focus, which makes writing text more cumbersome.
3685  * @skip static void
3686  * @until }
3687  *
3688  * One of the buttons on the top will trigger an @ref Inwin to open and show
3689  * us several icons we can insert into the text. We'll jump over most of these
3690  * functions, but when all the options are chosen, we insert the special
3691  * markup text that will show the chosen icon in place.
3692  * @skip edje_file_collection_list_free(emos)
3693  * @skip static void
3694  * @until evas_object_del
3695  * @until }
3696  *
3697  * As can be seen in that function, the program lets us add icons to our entry
3698  * using all the possible configurations for them. That should help to
3699  * clarify how the different combinations work out by actually seeing them
3700  * in action.
3701  *
3702  * The same popup window has a page to set the settings of the chosen icon,
3703  * that is, the size and how the item will be placed within the line.
3704  *
3705  * The size is done with two entries, limitted to accept numbers and a fixed
3706  * size of characters. Changing the value in this entries will update the icon
3707  * size in our struct as seen in the next two callbacks.
3708  * @skip static void
3709  * @until }
3710  * @until }
3711  *
3712  * The rest of the options are handled with radio buttons, since only one type
3713  * of size can be used (@c size, @c absize or @c relsize) and for the vertical
3714  * sizing it needs to choose between @c ascent and @c full. Depending on which
3715  * is chosen, the @c item tag is formed accordingly as seen before.
3716  * @skip static Evas_Object
3717  * @until evas_object_show(rvascent)
3718  *
3719  * The first of our entries is here. There's something worth mentioning about
3720  * the way we'll create this one. Normally, any entry regardless of whether is
3721  * single line or not, will be set to scrollable, but in this case, since we
3722  * are limitting how many characters can fit in them and we know we don't need
3723  * scrolling, we are not setting this flag. This makes the entry have virtually
3724  * no appearance on screen, other than its text. This is because an entry is
3725  * just that, a box that holds text, and in order to have some frame around it
3726  * or a background color, another widget needs to provide this. When an entry
3727  * is scrollable, the same scroller used internally does this.
3728  * We are using @ref Frame "frames" here to provide some decoration around,
3729  * then creating our entries, set them to single line, add our two filters and
3730  * the callback for when their value change.
3731  * @until _height_changed_cb
3732  *
3733  * This function ends with the button that will finally call the item
3734  * into our editting string.
3735  * @until }
3736  *
3737  * Then we get to the format edition. Here we can add the @c bold and
3738  * @c emphasis tags to parts of our text. There's a lot of manual work to
3739  * know what to do here, since we are not implementing an entire state manager
3740  * and the entry itself doesn't, yet, support all the needed capabilities to
3741  * make this simpler. We begin by getting the format we are using in our
3742  * function from the button pressed.
3743  * @skip aid->pager = pager;
3744  * @until sizeof(fmt_close)
3745  *
3746  * Next we need to find out if we need to insert an opening or a closing tag.
3747  * For this, we store the current cursor position and create a selection
3748  * from this point until the beginning of our text, and then get the selected
3749  * text to look for any existing format tags in it. This is currently the only
3750  * way in which we can find out what formats is being used in the entry.
3751  * @until }
3752  * @until }
3753  *
3754  * Once we know what tag to insert, we need a second check in the case it was
3755  * a closing tag. This is because any other closing tag that comes after would
3756  * be left dangling alone, so we need to remove it to keep the text consistent.
3757  * @until }
3758  * @until }
3759  * Finally, we clear our fake selections and return the cursor back to the
3760  * position it had at first, since there is where we want to insert our format.
3761  * @until cursor_pos_set
3762  *
3763  * And finish by calling our convenience function from before, to insert the
3764  * text at the current cursor and give focus back to the entry.
3765  * @until }
3766  *
3767  * A checkbox on the top of our program tells us if the text we are editing
3768  * will autosave or not. In it's @c "changed" callback we get the value from
3769  * the checkbox and call the elm_entry_autosave_set() function with it. If
3770  * autosave is set, we also call elm_entry_file_save(). This is so the internal
3771  * timer used to periodically store to disk our changes is started.
3772  * @skip static void
3773  * @until }
3774  *
3775  * Two more functions to show some cursor playing. Whenever we double click
3776  * anywhere on our entry, we'll find what word is the cursor placed at and
3777  * select it. Likewise, for triple clicking, we select the entire line.
3778  * @skip static void
3779  * @until _edit_tplclick_cb
3780  * @until }
3781  *
3782  * And finally, the main window of the program contains the entry where we
3783  * do all the edition and some helping widgets to change format, add icons
3784  * or change the autosave flag.
3785  * @skip elm_exit
3786  * @skip int
3787  * @until _image_insert_cb
3788  *
3789  * And the main entry of the program. Set to scroll, by default we disable
3790  * autosave and we'll begin with a file set to it because no file selector
3791  * is being used here. The file is loaded with #ELM_TEXT_FORMAT_MARKUP_UTF8
3792  * so that any format contained in it is interpreted, otherwise the entry
3793  * would load it as just text, escaping any tags found and no format or icons
3794  * would be shown. Then we connect to the double and triple click signals
3795  * and set focus on the entry so we can start typing right away.
3796  * @until ELM_MAIN
3797  *
3798  * @example entry_example.c
3799  */
3800
3801 /**
3802  * @page genlist_example_01
3803  *
3804  * This example creates a simple genlist with a small number of items and
3805  * a callback that is called whenever an item is selected. All the properties of
3806  * this genlist are the default ones. The full code for this example can be seen
3807  * at @ref genlist_example_01_c.
3808  *
3809  * For the simplest list that you plan to create, it's necessary to define some
3810  * of the basic functions that are used for creating each list item, and
3811  * associating them with the "item class" for that list. The item class is just
3812  * an struct that contains pointers to the specific list item functions that are
3813  * common to all the items of the list.
3814  *
3815  * Let's show it by example. Our item class is declared globally and static as
3816  * it will be the only item class that we need (we are just creating one list):
3817  *
3818  * @dontinclude genlist_example_01.c
3819  * @skip static Elm_Genlist
3820  * @until static Elm_Genlist
3821  *
3822  * This item class will be used for every item that we create. The only
3823  * functions that we are going to set are @c label_get and @c icon_get. As the
3824  * name suggests, they are used by the genlist to generate the label for the
3825  * respective item, and to generate icon(s) to it too. Both the label and icon
3826  * get functions can be called more than once for each item, with different @c
3827  * part parameters, which represent where in the theme of the item that label or
3828  * icon is going to be set.
3829  *
3830  * The default theme for the genlist contains only one area for label, and two
3831  * areas for icon ("elm.swallow.icon" and "elm.swallow.end"). Since we just want
3832  * to set the first icon (that will be at the left side of the label), we
3833  * compare the part name given with "elm.swallow.icon". Notice that the
3834  * @c label_get function must return a strduped string, that will be freed later
3835  * automatically by the list. Here's the code for @c label_get and @c icon_get:
3836  *
3837  * @until static void
3838  *
3839  * We will also provide a function that will be called whenever an item is
3840  * selected in the genlist. However, this function is not part of the item
3841  * class, it will be passed for each item being added to the genlist explicitly.
3842  * Notice the similarity of the function signature with those used by @c
3843  * evas_object_smart_callback_add:
3844  *
3845  * @until }
3846  *
3847  * Now let's show the code used for really creating the list. Skipping
3848  * boilerplate code used for creating a window and background, the first piece
3849  * of code specific to our genlist example is setting the pointer functions of
3850  * the item class to our above defined functions:
3851  *
3852  * @skip _itc
3853  * @until func.del
3854  *
3855  * Notice that we also choose to use the "default" style for our genlist items.
3856  * Another interesting point is that @c state_get and @c del are set to @c NULL,
3857  * since we don't need these functions now. @c del doesn't need to be used
3858  * because we don't add any data that must be freed to our items, and @c
3859  * state_get is also not used since all of our items are the same and don't need
3860  * to have different states to be used for each item. Finally we create our
3861  * list:
3862  *
3863  * @until genlist_add
3864  *
3865  * Now we append several items to the list, and for all of them we need to give
3866  * the list pointer, a pointer to the item class, the data that will be used
3867  * with that item, a pointer to the parent of this item if it is in a group type
3868  * list (this is not the case so we pass @c NULL), possible flags for this item,
3869  * the callback for when the item is selected, and the data pointer that will be
3870  * given to the selected callback.
3871  *
3872  * @until }
3873  *
3874  * The rest of the code is also common to all the other examples, so it will be
3875  * omitted here (look at the full source code link above if you need it).
3876  *
3877  * You can try to play with this example, and see the selected callback being
3878  * called whenever an item is clicked. It also already has some features enabled
3879  * by default, like vertical bounce animation when reaching the end of the list,
3880  * automatically visible/invisible scrollbar, etc. Look at the @ref
3881  * genlist_example_02 to see an example of setting these properties to the list.
3882  *
3883  * The current example will look like this when running:
3884  *
3885  * @image html screenshots/genlist_example_01.png
3886  * @image latex screenshots/genlistexample_01.eps width=\textwidth
3887  */
3888
3889 /**
3890  * @page genlist_example_02
3891  *
3892  * This example is very similar to the @ref genlist_example_01, but it fetch
3893  * most of the properties of the genlist and displays them on startup (thus
3894  * getting the default value for them) and then set them to some other values,
3895  * to show how to use that API. The full source code is at @ref
3896  * genlist_example_02_c.
3897  *
3898  * Considering that the base code for instantiating a genlist was already
3899  * described in the previous example, we are going to focus on the new code.
3900  *
3901  * Just a small difference for the @c _item_label_get function, we are going to
3902  * store the time that this function was called. This is the "realized" time,
3903  * the time when the visual representation of this item was created. This is the
3904  * code for the @c label_get function:
3905  *
3906  * @dontinclude genlist_example_02.c
3907  * @skip static char
3908  * @until return strdup
3909  *
3910  * Now let's go to the list creation and setup. First, just after creating the
3911  * list, we get most of the default properties from it, and print them on the
3912  * console:
3913  *
3914  * @skip genlist_add
3915  * @until printf("\n")
3916  *
3917  * We are going to change some of the properties of our list.
3918  *
3919  * There's no need to call the selected callback at every click, just when the
3920  * selected item changes, thus we call elm_genlist_always_select_mode_set() with
3921  * false.
3922  *
3923  * For this list we don't want bounce animations at all, so we set both the
3924  * horizontal bounce and the vertical bounce to false with
3925  * elm_genlist_bounce_set().
3926  *
3927  * We also want our list to compress items if they are wider than the list
3928  * width (thus we call elm_genlist_compress_mode_set().
3929  *
3930  * The items have different width, so they are not homogeneous:
3931  * elm_genlist_homogeneous_set() is set to false.
3932  *
3933  * Since the compress mode is active, the call to
3934  * elm_genlist_horizontal_mode_set() doesn't make difference, but the current
3935  * option would make the list to have at least the width of the largest item.
3936  *
3937  * This list will support multiple selection, so we call
3938  * elm_genlist_multi_select_set() on it.
3939  *
3940  * The option elm_genlist_height_for_width_mode_set() would allow text block to
3941  * wrap lines if the Edje part is configured with "text.min: 0 1", for example.
3942  * But since we are compressing the elements to the width of the list, this
3943  * option wouldn't take any effect.
3944  *
3945  * We want the vertical scrollbar to be always displayed, and the orizontal one
3946  * to never be displayed, and set this with elm_genlist_scroller_policy_set().
3947  *
3948  * The timeout to consider a longpress is set to half of a second with
3949  * elm_genlist_longpress_timeout_set().
3950  *
3951  * We also change the block count to a smaller value, but that should have not
3952  * impact on performance since the number of visible items is too small. We just
3953  * increase the granularity of the block count (setting it to have at most 4
3954  * items).
3955  *
3956  * @until block_count_set
3957  *
3958  * Now let's add elements to the list:
3959  *
3960  * @until item_append
3961  * @until }
3962  *
3963  * It's exactly the same as the previous example. The difference is on the
3964  * behavior of the list, if you try to scroll, select items and so.
3965  *
3966  * In this example we also need two buttons. One of them, when clicked, will
3967  * display several status info about the current selection, the "realized"
3968  * items, the item in the middle of the screen, and the current mode and active
3969  * item of that mode for the genlist.
3970  *
3971  * The other button will ask the genlist to "realize" again the items already
3972  * "realized", so their respective label_get and icon_get functions will be
3973  * called again.
3974  *
3975  * These are the callbacks for both of these buttons:
3976  *
3977  * @dontinclude genlist_example_02.c
3978  * @skip item_sel_cb
3979  * @skip static
3980  * @until }
3981  * @until }
3982  *
3983  * Try to scroll, select some items and click on the "Show status" button.
3984  * You'll notice that not all items of the list are "realized", thus consuming
3985  * just a small amount of memory. The selected items are listed in the order
3986  * that they were selected, and the current selected item printed using
3987  * elm_genlist_selected_item_get() is the first selected item of the multiple
3988  * selection.
3989  *
3990  * Now resize the window so that you can see the "realized time" of some items.
3991  * This is the time of when the label_get function was called. If you click on
3992  * the "Realize" button, all the already realized items will be rebuilt, so the
3993  * time will be updated for all of them.
3994  *
3995  * The current example will look like this when running:
3996  *
3997  * @image html screenshots/genlist_example_02.png
3998  * @image latex screenshots/genlistexample_02.eps width=\textwidth
3999  */
4000
4001 /**
4002  * @page progressbar_example Progress bar widget example
4003  *
4004  * This application is a thorough example of the progress bar widget,
4005  * consisting of a window with varios progress bars, each with a given
4006  * look/style one can give to those widgets. With two auxiliary
4007  * buttons, one can start or stop a timer which will fill in the bars
4008  * in synchrony, simulating an underlying task being completed.
4009  *
4010  * We create @b seven progress bars, being three of them horizontal,
4011  * three vertical and a final one under the "wheel" alternate style.
4012  *
4013  * For the first one, we add a progress bar on total pristine state,
4014  * with no other call than the elm_progressbar_add() one:
4015  * @dontinclude progressbar_example.c
4016  * @skip pb with no label
4017  * @until pb1
4018  * See, than, that the defaults of a progress bar are:
4019  * - no primary label shown,
4020  * - unit label set to @c "%.0f %%",
4021  * - no icon set
4022  *
4023  * The second progress bar is given a primary label, <c>"Infinite
4024  * bounce"</c>, and, besides, it's set to @b pulse. See how, after one
4025  * starts the progress timer, with the "Start" button, it animates
4026  * differently than the previous one. It won't account for the
4027  * progress, itself, and just dumbly animate a small bar within its
4028  * bar region.
4029  * @dontinclude progressbar_example.c
4030  * @skip pb with label
4031  * @until pb2
4032  *
4033  * Next, comes a progress bar with an @b icon, a primary label and a
4034  * @b custom unit label set. It's also made to grow its bar in an
4035  * @b inverted manner, so check that out during the timer's progression:
4036  * @dontinclude progressbar_example.c
4037  * @skip ic1 =
4038  * @until pb3
4039  * Another important thing in this one is the call to
4040  * elm_progressbar_span_size_set() -- this is how we forcefully set a
4041  * minimum horizontal size to our whole window! We're not resizing it
4042  * manually, as you can see in the @ref progressbar_example_c
4043  * "complete code".
4044  *
4045  * The next three progress bars are just variants on the ones already
4046  * shown, but now all being @b vertical. Another time we use one of
4047  * than to give the window a minimum vertical size, with
4048  * elm_progressbar_span_size_set().  To demonstrate this trick once
4049  * more, the fifth one, which is also set to pulse, has a smaller
4050  * hardcoded span size:
4051  * @dontinclude progressbar_example.c
4052  * @skip vertical pb, with pulse
4053  * @until pb5
4054  *
4055  * We end the widget demonstration by showing a progress bar with the
4056  * special @b "wheel" progress bar style. One does @b not need to set
4057  * it to pulse, with elm_progressbar_pulse_set(), explicitly, because
4058  * its theme does not take it in account:
4059  * @dontinclude progressbar_example.c
4060  * @skip "wheel"
4061  * @until pb7
4062  *
4063  * The two buttons exercising the bars, the facto, follow:
4064  * @dontinclude progressbar_example.c
4065  * @skip elm_button_add
4066  * @until evas_object_show(bt)
4067  * @until evas_object_show(bt)
4068  *
4069  * The first of the callbacks will, for the progress bars set to
4070  * pulse, start the pulsing animation at that time. For the others, a
4071  * timer callback will take care of updating the values:
4072  * @dontinclude progressbar_example.c
4073  * @skip static Eina_Bool
4074  * @until }
4075  * @until }
4076  * @until }
4077  *
4078  * Finally, the callback to stop the progress timer will stop the
4079  * pulsing on the pulsing progress bars and, for the others, to delete
4080  * the timer which was acting on their values:
4081  * @dontinclude progressbar_example.c
4082  * @skip end of show
4083  * @until }
4084  * @until }
4085  *
4086  * This is how the example program's window looks like:
4087  * @image html screenshots/progressbar_example.png
4088  * @image latex screenshots/progressbar_example.eps width=\textwidth
4089  *
4090  * See the full @ref progressbar_example_c "source code" for
4091  * this example.
4092  *
4093  * @example progressbar_example.c
4094  */
4095
4096 /**
4097  * @page bg_example_01_c bg_example_01.c
4098  * @include bg_example_01.c
4099  * @example bg_example_01.c
4100  */
4101
4102 /**
4103  * @page bg_example_02_c bg_example_02.c
4104  * @include bg_example_02.c
4105  * @example bg_example_02.c
4106  */
4107
4108 /**
4109  * @page bg_example_03_c bg_example_03.c
4110  * @include bg_example_03.c
4111  * @example bg_example_03.c
4112  */
4113
4114 /**
4115  * @page actionslider_example_01 Actionslider example
4116  * @include actionslider_example_01.c
4117  * @example actionslider_example_01.c
4118  */
4119
4120 /**
4121  * @page animator_example_01_c Animator example 01
4122  * @include animator_example_01.c
4123  * @example animator_example_01.c
4124  */
4125
4126 /**
4127  * @page transit_example_01_c Transit example 1
4128  * @include transit_example_01.c
4129  * @example transit_example_01.c
4130  */
4131
4132 /**
4133  * @page transit_example_02_c Transit example 2
4134  * @include transit_example_02.c
4135  * @example transit_example_02.c
4136  */
4137
4138 /**
4139  * @page general_functions_example_c General (top-level) functions example
4140  * @include general_funcs_example.c
4141  * @example general_funcs_example.c
4142  */
4143
4144 /**
4145  * @page clock_example_c Clock example
4146  * @include clock_example.c
4147  * @example clock_example.c
4148  */
4149
4150 /**
4151  * @page flipselector_example_c Flipselector example
4152  * @include flipselector_example.c
4153  * @example flipselector_example.c
4154  */
4155
4156 /**
4157  * @page fileselector_example_c Fileselector example
4158  * @include fileselector_example.c
4159  * @example fileselector_example.c
4160  */
4161
4162 /**
4163  * @page fileselector_button_example_c Fileselector button example
4164  * @include fileselector_button_example.c
4165  * @example fileselector_button_example.c
4166  */
4167
4168 /**
4169  * @page fileselector_entry_example_c Fileselector entry example
4170  * @include fileselector_entry_example.c
4171  * @example fileselector_entry_example.c
4172  */
4173
4174 /**
4175  * @page index_example_01_c Index example
4176  * @include index_example_01.c
4177  * @example index_example_01.c
4178  */
4179
4180 /**
4181  * @page index_example_02_c Index example
4182  * @include index_example_02.c
4183  * @example index_example_02.c
4184  */
4185
4186 /**
4187  * @page layout_example_01_c layout_example_01.c
4188  * @include layout_example_01.c
4189  * @example layout_example_01.c
4190  */
4191
4192 /**
4193  * @page layout_example_02_c layout_example_02.c
4194  * @include layout_example_02.c
4195  * @example layout_example_02.c
4196  */
4197
4198 /**
4199  * @page layout_example_03_c layout_example_03.c
4200  * @include layout_example_03.c
4201  * @example layout_example_03.c
4202  */
4203
4204 /**
4205  * @page layout_example_edc An example of layout theme file
4206  *
4207  * This theme file contains two groups. Each of them is a different theme, and
4208  * can be used by an Elementary Layout widget. A theme can be used more than
4209  * once by many different Elementary Layout widgets too.
4210  *
4211  * @include layout_example.edc
4212  * @example layout_example.edc
4213
4214 /**
4215  * @page gengrid_example_c Gengrid example
4216  * @include gengrid_example.c
4217  * @example gengrid_example.c
4218  */
4219
4220 /**
4221  * @page genlist_example_01_c genlist_example_01.c
4222  * @include genlist_example_01.c
4223  * @example genlist_example_01.c
4224  */
4225
4226 /**
4227  * @page genlist_example_02_c genlist_example_02.c
4228  * @include genlist_example_02.c
4229  * @example genlist_example_02.c
4230  */
4231
4232 /**
4233  * @page progressbar_example_c Progress bar example
4234  * @include progressbar_example.c
4235  * @example progressbar_example.c
4236  */