aboutsummaryrefslogtreecommitdiffstats
path: root/doc/ecore_examples.dox
blob: bf25fa3804d8a28d41a7403b786660f5038e5ed4 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
/**
 * @page ecore_examples Ecore Examples
 *
 * Here is a page with some Ecore examples explained:
 *
 * @li @ref ecore_time_functions_example_c
 * @li @ref ecore_timer_example_c
 * @li @ref ecore_idler_example_c
 * @li @ref ecore_job_example_c
 * @li @ref ecore_event_example_01_c
 * @li @ref ecore_event_example_02_c
 * @li @ref ecore_fd_handler_example_c
 * @li @ref ecore_poller_example_c
 * @li @ref ecore_con_lookup_example_c
 * @li @ref ecore_con_url_download_example_c
 * @li @ref ecore_con_server_simple_example_c
 * @li @ref ecore_con_client_simple_example_c
 * @li @ref ecore_evas_callbacks_example_c
 * @li @ref ecore_evas_object_example_c
 * @li @ref ecore_evas_basics_example_c
 * @li @ref Ecore_Evas_Window_Sizes_Example_c
 * @li @ref Ecore_Evas_Buffer_Example_01_c
 * @li @ref Ecore_Evas_Buffer_Example_02_c
 * @li @ref Ecore_exe_simple_example_c
 * @li @ref ecore_imf_example_c
 */

/**
 * @page ecore_time_functions_example_c ecore_time - Differences between time functions
 *
 * This example shows the difference between calling ecore_time_get(),
 * ecore_loop_time_get() and ecore_time_unix_get().
 *
 * It initializes ecore, then sets a timer with a callback that, when called,
 * will retrieve the system time using these 3 different functions. After
 * displaying the time, it sleeps for 1 second, then call display the time
 * again using the 3 functions.
 *
 * Since everything occurs inside the same main loop iteration, the internal
 * ecore time variable will not be updated, and calling ecore_loop_time_get()
 * before and after the sleep() call will return the same result.
 *
 * The two other functions will return a difference of 1 second, as expected.
 * But ecore_time_unix_get() returns the number of seconds since 00:00:00 1st
 * January 1970, while ecore_time_get() will return the time since a
 * unspecified point, but that never goes back in time, even when the timezone
 * of the machine changes.
 *
 * @note The usage of ecore_loop_time_get() should be preferred against the
 * two other functions, for most time calculations, since it won't produce a
 * system call to get the current time. Use ecore_time_unix_get() when you need
 * to know the current time and date, and ecore_time_get() when you need a
 * monotonic and more precise time than ecore_loop_time_get().
 *
 * @include ecore_time_functions_example.c
 */

/**
 * @page ecore_timer_example_c ecore timers - Scheduled events
 * @dontinclude ecore_timer_example.c
 *
 * This example shows how to setup timer callbacks. It starts a timer that will
 * tick (expire) every 1 second, and then setup other timers that will expire
 * only once, but each of them will affect the first timer still executing with
 * a different API, to demonstrate its usage. To see the full code for this
 * example, click @ref ecore_timer_example.c "here".
 *
 * To demonstrate this, let's define some constants that will determine at which
 * time each timer will expire:
 *
 * @until INTERVAL1
 *
 * These constants should tell by themselves what will be the behavior of the
 * program, but I'll explain it anyway. The first timer is set to tick every 1
 * second, but all the other timers until the 6th one will be started
 * concurrently at the beginning of the program. Each of them will expire at the
 * specified time in these constants:
 *
 * @li The timer2, after 3 seconds of the program being executed, will add a delay
 * of 3 seconds to timer1;
 * @li The timer3 will pause timer1 at 8.2 seconds;
 * @li timer4 will resume timer1 at 11.0 seconds;
 * @li timer5 will will change the interval of timer1 to 2 seconds;
 * @li timer6 will stop timer1 and start timer7 and timer8, with 1.1 and 1.2
 * seconds of interval, respectively; it also sets the precision to 0.2 seconds;
 * @li timer7 and timer8 will just print their expiration time.
 *
 * @until ecore_time_get
 * @until }
 *
 * As almost all the other examples, we create a context structure to pass to
 * our callbacks, so they can have access to the other timers. We also store the
 * time of the program start in @c _initial_time, and use the function
 * @c _get_current_time to retrieve the current time relative to that time. This
 * will help demonstrate what is going on.
 *
 * Now, the behavior and relationship between the timers that was described
 * above is dictated by the following timer callbacks:
 *
 * @until _timer6_cb
 * @until }
 *
 * It's possible to see the same behavior as other Ecore callbacks here,
 * returning @ref ECORE_CALLBACK_RENEW when the timer needs to continue ticking,
 * and @ref ECORE_CALLBACK_CANCEL when it needs to stop its execution. Also
 * notice that later on our program we are checking for the timers pointers in
 * the context to see if they are still executing before deleting them, so we
 * need to set these timer pointers to @c NULL when we are returning @ref
 * ECORE_CALLBACK_CANCEL. Otherwise the pointer would still be not @c NULL, but
 * pointing to something that is invalid, since the timer would have already
 * expired without renewing.
 *
 * Now the main code, which will start the timers:
 *
 * @until ecore_shutdown
 * @until }
 *
 * This code is very simple. Just after starting the library, it will save the
 * current time to @c _initial_time, start all timers from 1 to 6, and begin the
 * main loop. Everything should be running right now, displaying the time which
 * each timer is expiring, and what it is doing to affect the other timers.
 *
 * After returning from the main loop, every timer is checked to see if it's
 * still alive and, in that case, deleted, before finalizing the library. This
 * is not really necessary, since ecore_shutdown() will already delete them for
 * you, but it's good practice if you have other things going on after this
 * point that could restart the main loop.
 *
 */

/**
 * @page ecore_idler_example_c ecore idle state - Idlers, enterers and exiters
 *
 * This example demonstrates how to manage the idle state of the main loop. Once
 * a program knows that the main loop is going to enter in idle state, it could
 * start doing some processing until getting out of this state.
 *
 * To exemplify this, we also add events and a timer to this program, so we can
 * see the idle exiter callback being called before processing the event and/or
 * timer, the event/timer callback being called (processed), then the idle
 * enterer being called before entering in idle state again. Once in idle, the
 * main loop keeps calling the idler callback continuously until a new event or
 * timer is received.
 *
 * First, we declare a struct that will be used as context to be passed to
 * every callback. It's not useful everywhere, since this example is very
 * simple and doesn't do anything other than printing messages, but using this
 * context will make it a little bit more real. Our context will be used to
 * delete the timer, idler, idle enterer and exiter, and the event handler, and
 * also to count how many times the idler was called.
 *
 * Then we start declaring callbacks for the idle enterer, idle exiter and the
 * idler itself. Idle enterer and exiter callbacks just print a message saying
 * that they were called, while the idler, in addition to printing a message
 * too, also sends an event every 10 times that it is called, incrementing the
 * context count variable. This event will be used to make the main loop exit
 * the idle state and call the event callback.
 *
 * These callbacks return @ref ECORE_CALLBACK_RENEW, since we want them to keep
 * being called every time the main loop changes to/from idle state. Otherwise,
 * if we didn't want them to be called again, they should return @ref
 * ECORE_CALLBACK_CANCEL.
 *
 * The next function declared is the event callback @c _event_handler_cb. It
 * will check if the idler was called more than 100 times already @c
 * (ctxt->count > 100), and will delete the idler, idle enterer and exiter, the
 * timer (if it still exists), and request that the main loop stop running. Then
 * it returns @ref ECORE_CALLBACK_DONE to indicate that the event shouldn't be
 * handled by any other callback.
 *
 * Finally, we add a callback to the timer, that will just print a message when
 * it is called, and this will happen only once (@ref ECORE_CALLBACK_CANCEL is
 * being returned). This timer callback is just here to show that the main loop
 * gets out of idle state when processing timers too.
 *
 * The @b main function is simple, just creates a new type of event that we will
 * use to demonstrate the event handling together with the idle state, adds the
 * callbacks that we declared so far, fill the context struct, and starts
 * running the main loop.
 *
 * @note We use timer and event callbacks to demonstrate the idle state
 * changing, but it also happens for file descriptor handlers, pipe handlers,
 * etc.
 *
 * @include ecore_idler_example.c
 */

/**
 * @page ecore_job_example_c ecore_job - Queuing tasks
 *
 * This example shows how an @ref Ecore_Job can be added, how it can be
 * deleted, and that they always execute in the added order.
 *
 * First, 2 callback functions are declared, one that prints strings passed to
 * it in the @c data pointer, and another one that quits the main loop. In the
 * @c main function, 3 jobs are added using the first callback, and another one
 * is added using the second one.
 *
 * Then the second added job is deleted just to demonstrate the usage of
 * ecore_job_del(), and the main loop is finally started. Run this example to
 * see that @c job1, @c job3 and @c job_quit are ran, in this order.
 *
 * @include ecore_job_example.c
 */

/**
 * @page ecore_event_example_01_c Handling events example
 * This example shows the simplest possible way to register a handler for an
 * ecore event, this way we can focus on the important aspects. The example will
 * start the main loop and quit it when it receives the ECORE_EVENT_SIGNAL_EXIT
 * event. This event is triggered by a SIGTERM(pressing ctrl+c).
 *
 * So let's start with the function we want called when we receive the event,
 * instead of just stopping the main loop we'll also print a message, that's
 * just so it's clear that it got called:
 * @dontinclude ecore_event_example_01.c
 * @skip static
 * @until }
 * @note We return ECORE_CALLBACK_DONE because we don't want any other handlers
 * for this event to be called, the program is quitting after all.
 *
 * We then have our main function and the obligatory initialization of ecore:
 * @until ecore_init
 *
 * We then get to the one line of our example that makes everything work, the
 * registering of the callback:
 * @until handler_add
 * @note The @c NULL there is because there is no need to pass data to the
 * callback.
 *
 * And the all that is left to do is start the main loop:
 * @until }
 *
 * Full source code for this example: @ref ecore_event_example_01.c.
 */

/**
 * @page ecore_event_example_02_c ecore events and handlers - Setup and use
 * This example shows how to create a new type of event, setup some event
 * handlers to it, fire the event and have the callbacks called. After
 * finishing, we delete the event handlers so no memory will leak.
 *
 * See the full source code for this example @ref ecore_event_example_02.c
 * "here".
 *
 * Let's start the example from the beginning:
 *
 * @dontinclude ecore_event_example_02.c
 * @until _event_type
 *
 * First thing is to declare a struct that will be passed as context to the
 * event handlers. In this structure we will store the event handler pointers,
 * and two strings that will be used by the first event handler. We also will
 * use a global integer to store the event type used for our event. It is
 * initialized with 0 in the beginning because the event wasn't created yet.
 * Later, in the main function we will use ecore_event_type_new() to associate
 * another value to it. Now the event handler callbacks:
 *
 * @until }
 *
 * This is the first event handler callback. It prints the event data received
 * by the event, and the data passed to this handler when it was added.  Notice
 * that this callback already knows that the event data is an integer pointer,
 * and that the handler data is a string. It knows about the first one because
 * this is based on the type of event that is going to be handled, and the
 * second because it was passed to the ecore_event_handler_add() function when
 * registering the event handler.
 *
 * Another interesting point about this callback is that it returns @ref
 * ECORE_CALLBACK_DONE (0) if the event data is even, swallowing the event and
 * don't allowing any other callback to be called after this one for this event.
 * Otherwise it returns @ref ECORE_CALLBACK_PASS_ON, allowing the event to be
 * handled by other event handlers registered for this event. This makes the
 * second event handler be called just for "odd" events.
 *
 * @until ECORE_CALLBACK_DONE
 * @until }
 *
 * The second event handler will check if the event data is equal to 5, and if
 * that's the case, it will change the event handler data of the first event
 * handler to another string. Then it checks if the event data is higher than
 * 10, and if so, it will request the main loop to quit.
 *
 * An interesting point of this example is that although the second event
 * handler requests the main loop to finish after the 11th event being received,
 * it will process all the events that were already fired, and call their
 * respective event handlers, before the main loop stops. If we didn't want
 * these event handlers to be called after the 11th event, we would need to
 * unregister them with ecore_event_handler_del() at this point.
 *
 * Now some basic initialization of the context, and the Ecore library itself:
 *
 * @until type_new
 *
 * This last line is interesting. It creates a new type of event and returns a
 * unique ID for this event inside Ecore. This ID can be used anywhere else in
 * your program to reference this specific type of event, and to add callbacks
 * to it.
 *
 * It's common if you are implementing a library that declares new types of
 * events to export their respective types as extern in the header files. This
 * way, when the library is initialized and the new type is created, it will be
 * available through the header file to an application using it add some
 * callbacks to it. Since our example is self-contained, we are just putting it
 * as a global variable.
 *
 * Now we add some callbacks:
 *
 * @until ctxt);
 *
 * This is very simple. Just need to call ecore_event_handler_add() with the
 * respective event type, the callback function to be called, and a data pointer
 * that will be passed to the callback when it is called by the event.
 *
 * Then we start firing events:
 *
 * @until }
 *
 * This @c for will fire 16 events of this type. Notice that the events will be
 * fired consecutively, but any callback will be called yet. They are just
 * called by the main loop, and since it wasn't even started, nothing happens
 * yet. For each event fired, we allocate an integer that will hold the number
 * of the event (we are arbitrarily creating these numbers just for
 * demonstration purposes). It's up to the event creator to decide which type of
 * information it wants to give to the event handler, and the event handler must
 * know what is the event info structure for that type of event.
 *
 * Since we are not allocating any complex structure, just a simple integer, we
 * don't need to pass any special free function to ecore_event_add(), and it
 * will use a simple @c free on our data. That's the default behavior.
 *
 * Now finishing our example:
 *
 * @until }
 *
 * We just start the main loop and watch things happen, waiting to shutdown
 * Ecore when the main loop exits and return.
 */

/**
 * @page ecore_fd_handler_example_c ecore fd handlers - Monitoring file descriptors
 * @dontinclude ecore_fd_handler_example.c
 *
 * This is a very simple example where we will start monitoring the stdin of the
 * program and, whenever there's something to be read, we call our callback that
 * will read it.
 *
 * Check the full code for this example @ref ecore_fd_handler_example.c "here".
 *
 * This seems to be stupid, since a similar result could be achieved by the
 * following code:
 *
 * @code
 * while (nbytes = read(STDIN_FILENO, buf, sizeof(buf)))
 *   {
 *      buf[nbytes - 1] = '\0';
 *      printf("Read %zd bytes from input: \"%s\"\n", nbytes - 1, buf);
 *   }
 * @endcode
 *
 * However, the above code is blocking, and won't allow you to do anything else
 * other than reading the input. Of course there are other methods to do a
 * non-blocking reading, like setting the file descriptor to non-blocking and
 * keep looping always checking if there's something to be read, and do other
 * things otherwise. Or use a @c select call to watch for more than one file
 * descriptor at the same time.
 *
 * The advantage of using an @ref Ecore_Fd_Handler is that you can monitor a
 * file descriptor, while still iterating on the Ecore main loop. It will allow
 * you to have timers working and expiring, events still being processed when
 * received, idlers doing its work when there's nothing happening, and whenever
 * there's something to be read from the file descriptor, your callback will be
 * called. And it's everything monitored in the same main loop, no threads are
 * needed, thus reducing the complexity of the program and any overhead caused
 * by the use of threads.
 *
 * Now let's start our program. First we just declare a context structure that
 * will be passed to our callback, with pointers to our handler and to a timer
 * that will be used later:
 *
 * @until };
 *
 * Then we will declare a prepare_callback that is called before any fd_handler
 * set in the program, and before the main loop select function is called. Just
 * use one if you really know that you need it. We are just putting it here to
 * exemplify its usage:
 *
 * @until }
 *
 * Now, our fd handler. In its arguments, the @c data pointer will have any data
 * passed to it when it was registered, and the @c handler pointer will contain
 * the fd handler returned by the ecore_main_fd_handler_add() call. It can be
 * used, for example, to retrieve which file descriptor triggered this callback,
 * since it could be added to more than one file descriptor, or to check what
 * type of activity there's in the file descriptor.
 *
 * The code is very simple: we first check if the type of activity was an error.
 * It probably won't happen with the default input, but could be the case of a
 * network socket detecting a disconnection. Next, we get the file descriptor
 * from this handler (as said before, the callback could be added to more than
 * one file descriptor), and read it since we know that it shouldn't block,
 * because our fd handler told us that there's some activity on it. If the
 * result of the read was 0 bytes, we know that it's an end of file (EOF), so we
 * can finish reading the input. Otherwise we just print the content read from
 * it:
 *
 * @until }
 *
 * Also notice that this callback returns @ref ECORE_CALLBACK_RENEW to keep
 * being called, as almost all other Ecore callbacks, otherwise if it returns
 * @ref ECORE_CALLBACK_CANCEL then the file handler would be deleted.
 *
 * Just to demonstrate that our program isn't blocking in the input read but
 * still can process other Ecore events, we are going to setup an @ref
 * Ecore_Timer. This is its callback:
 *
 * @until }
 *
 * Now in the main code we are going to initialize the library, and setup
 * callbacks for the file descriptor, the prepare callback, and the timer:
 *
 * @until timer_add
 *
 * Notice that the use of ecore_main_fd_handler_add() specifies what kind of
 * activity we are monitoring. In this case, we want to monitor for read (since
 * it's the standard input) and for errors. This is done by the flags @ref
 * ECORE_FD_READ and @ref ECORE_FD_ERROR. For the three callbacks we are also
 * giving a pointer to our context structure, which has pointers to the handlers
 * added.
 *
 * Then we can start the main loop and see everything happening:
 *
 * @until }
 *
 * In the end we are just deleting the fd handler and the timer to demonstrate
 * the API usage, since Ecore would already do it for us on its shutdown.
 */

/**
 * @page ecore_poller_example_c ecore poller - Repetitive polling tasks
 * @dontinclude ecore_poller_example.c
 *
 * This example shows how to setup, and explains how an @ref Ecore_Poller is
 * called. You can @ref ecore_poller_example.c "see the full source code here".
 *
 * In this example we store the initial time of the program just to use as
 * comparison to the time when the poller callbacks are called. It will be
 * stored in @c _initial_time :
 *
 * @until initial_time
 *
 * Then next step is to define the poller callback. This callback assumes that a
 * @c data pointer is passed to it on creation, and is a string just used to
 * identify the poller. The callback prints this string and the time since the
 * program started, and returns @ref ECORE_CALLBACK_RENEW to keep being called.
 *
 * @until }
 *
 * Now in the main function we initialize Ecore, and save the initial time of
 * the program, so we can compare it later with the time that the pollers are
 * being called:
 *
 * @until initial_time
 *
 * Then we change the poll interval to 0.3 seconds (the default is 0.125
 * seconds) just to show the API usage.
 *
 * Finally, we create two pollers, one that will be called every 4 ticks, and
 * another one that will be called every 8 ticks. This means the the first
 * poller interval will be around 1.2 seconds, and the second one will be
 * around 2.4 seconds. But the most important point is: since the second poller
 * interval is a multiple of the first one, they will be always synchronized.
 * Ecore calls pollers that are in the "same tick" together. It doesn't go back
 * to the main loop and check if there's another poller to execute at this
 * time, but instead it calls all the pollers registered to this "tick" at the
 * same time.  See the description of ecore_poller_add() for more details. This
 * is easy to see in the time printed by both of them.
 *
 * If instead of two synchronized pollers, we were using two different timers,
 * one with interval of 1.2 seconds and another one with an interval of 2.4
 * seconds, there would be no guarantee that they would be totally in sync. Some
 * delay in the execution of another task, or even in the task called in the
 * callback, could make them get out of sync, forcing Ecore's main loop to wake
 * up more than necessary.
 *
 * Well, this is the code that create these two pollers and set the poll
 * interval, then starts the main loop:
 *
 * @until ecore_main_loop_begin
 *
 * If you hit CTRL-C during the execution of the program, the main loop will
 * quit, since there are some signal handlers already set by default to do this.
 * So after the main loop begin call, we change the second poller's interval to
 * 16 ticks, so it will happen each 4.8 seconds (or each 4 times that the first
 * poller is called).
 *
 * This means: the program is started, the first poller is called each 4 ticks
 * and the second is called each 8 ticks. After CTRL-C is used, the second
 * poller will be called each 16 ticks.
 *
 * @until }
 *
 * The rest of the program is just deleting the pollers and shutting down the
 * library.
 */

/**
 * @page ecore_con_lookup_example_c Ecore_Con - DNS lookup
 *
 * This is a very simple example that shows how to make a simple DNS lookup
 * using ecore_con_lookup().
 *
 * It's possible to see in the beginning of the main function that we are using
 * the arguments passed via command line. This is the address that we are going
 * to make the DNS lookup on.
 *
 * The next step is to initialize the libraries, and just call
 * ecore_con_lookup(). This function will get the string that contains the
 * address to be resolved as first parameter, then a callback that will be
 * called when the resolve stage is done, and finally a data pointer that will
 * be passed to the callback.
 *
 * This function is asynchronous, and the callback will be called only on
 * success. If there was an error during the resolve stage, there's no way to
 * know about that. It's only possible to know about errors when setting up the
 * lookup, by looking at the return code of the ecore_con_lookup() function.
 *
 * The callback @c _lookup_done_cb passed as argument to ecore_con_lookup() just
 * prints the resolved canonical name, IP, address of the sockaddr structure,
 * and the length of the socket address (in bytes).
 *
 * Finally, we start the main loop, and after that we finalize the libraries and
 * exit.
 *
 * This is the code for this simple example:
 *
 * @include ecore_con_lookup_example.c
 */

/**
 * @page ecore_con_url_download_example_c Ecore_Con_Url - downloading a file
 *
 * This is a simple example that shows how to download a file using @ref
 * Ecore_Con_Url. The full source code for this example can be found at @ref
 * ecore_con_url_download_example.c.
 *
 * First we are setting some callbacks for events that will be sent when data
 * arrives in our connection (the data is the content of the file being
 * downloaded), and when the download is completed. The @c _url_progress_cb and
 * @c _url_complete_cb are these callbacks:
 *
 * @dontinclude ecore_con_url_download_example.c
 * @skip struct
 * @until main_loop_quit
 * @until }
 *
 * Notice that we also declared a struct that will hold how many bytes were
 * downloaded through this object. It will be set in the @c main function using
 * ecore_con_url_data_set().
 *
 * In the next step, on the @c main function, we open a file where we are going
 * to save the content being downloaded:
 *
 * @until open(
 * @until }
 *
 * With the file successfully open, let's create our @ref Ecore_Con_Url object.
 * For this, we initialize the libraries and create the object:
 *
 * @until }
 *
 * Then we allocate and set the data struct to the connection object, and set a
 * file descriptor from our previously open file to it. We also add the event
 * handlers (callbacks) to the events that will be emitted on data being
 * received and download complete:
 *
 * @until complete_cb
 *
 * Finally we start our request, and run the main loop:
 *
 * @until return 0
 * @until }
 *
 * The rest of this code was just freeing resources, with some labels to be used
 * for error handling.
 */

/**
 * @page ecore_con_url_cookies_example_c Ecore_Con_Url - Managing cookies
 *
 * This example shows how to use an @ref Ecore_Con_Url and enable it to
 * receive/send cookies. These cookies can be set by the server, saved to a
 * file, loaded later from this file and sent again to the server. The complete
 * example can be found at @ref ecore_con_url_cookies_example.c
 * "ecore_con_url_cookies_example.c"
 *
 * First we are setting some callbacks for events that will be sent when data
 * arrives in our connection (the data is the content of the file being
 * downloaded), and when the download is completed. The @c _url_data_cb and
 * @c _url_complete_cb are these callbacks:
 *
 * @dontinclude ecore_con_url_download_example.c
 * @skip Eina_Bool
 * @until main_loop_quit
 * @until }
 *
 * In the @c main function we parse some parameter from the command line. These
 * parameters are the url that we are connecting to, and cookie use policy.
 *
 * After that we initialize the libraries and create a handler to our request
 * using the given url:
 *
 * @until goto end
 * @until }
 *
 * We also set the event handlers for this request and add a header to it, that
 * will inform our custom user agent:
 *
 * @until User-Agent
 *
 * Now we start playing with cookies. First, let's call
 * ecore_con_url_cookies_init() to inform that we want cookies enabled. We also
 * set a file from which we are loading previously set (old) cookies, in case
 * that we don't want to clear old cookies or old session cookies.
 *
 * After that we set the file where we are going to save all valid cookies in
 * the @ref Ecore_Con_Url object. This includes previously loaded cookies (that
 * weren't cleared) and new cookies set by the response header "Set-Cookie" that
 * comes with the response to our request:
 *
 * @until jar_file_set
 *
 * And finally, before performing the request, we check the command passed as
 * argument in the command line and use it to choose between clearing old
 * cookies, clearing just old session cookies, or ignoring old session cookies.
 *
 * After that we just finish our code as expected:
 *
 * @until return
 * @until }
 *
 * Notice that in this code, if we want to clear old cookies, we also don't load
 * them from the file. This is a bit confusing and the API isn't clear, but
 * ecore_con_url_cookies_file_add() will load cookies from the specified files
 * just when the operation is really performed (i.e. ecore_con_url_get() is
 * called). So if ecore_con_url_cookies_clear() is called before
 * ecore_con_url_get(), the old cookies may not have been loaded yet, so they
 * are not cleared. To avoid having old cookies loaded, don't add any cookie
 * file with ecore_con_url_cookies_file_add().
 *
 * The function ecore_con_url_cookies_clear() is just useful to clear cookies
 * that are already loaded/valid in the @ref Ecore_Con_Url object (from a
 * previous request, for example).
 */

/**
 * @page ecore_con_url_headers_example_c Ecore_Con_Url - customizing a request
 *
 * This is a simple example that shows how to make a custom request using @ref
 * Ecore_Con_Url. The full source code for this example can be found at @ref
 * ecore_con_url_headers_example.c.
 *
 * The first part of the example is setting the callbacks to be called when an
 * #ECORE_CON_EVENT_URL_DATA or #ECORE_CON_EVENT_URL_COMPLETE event is received.
 * These are the callbacks that are going to be used with this:
 *
 * @dontinclude ecore_con_url_headers_example.c
 * @skip static
 * @until main_loop_quit
 * @until }
 *
 * The @c main code is as simple as the @ref Ecore_Con_Url example. It contains
 * some checks for the arguments to see if a GET or POST request is required:
 *
 * @until GET
 * @until }
 *
 * Then we start our required libraries and configure a global option to use
 * pipelined requests:
 *
 * @until pipeline_set
 *
 * Now we create our request object, but using ecore_con_url_custom_new() to use
 * a POST or GET method depending on the command line arguments. And we also add
 * the event handlers for our callbacks:
 *
 * @until complete_cb
 *
 * In order to demonstrate our API, some options are set to this request before
 * actually performing it:
 *
 * @until url_time
 *
 * Depending on what kind of request was asked (GET or POST), we use one of the
 * specific functions to perform it:
 *
 * @until url_post
 *
 * After that, we just check for errors, start the main loop, free resources and
 * finally exit:
 *
 * @until return
 * @until }
 */

/**
 * @page ecore_con_server_simple_example_c Ecore_Con - Creating a server
 *
 * In this example we are going to create a server that listens for connections
 * from clients through a TCP port. You can get the full source code at @ref
 * ecore_con_server_simple_example.c.
 *
 * We begin our example in the main function, to demonstrate how to setup
 * things, and then go to the callbacks that are needed for it to run properly.
 *
 * In the @c main function, after initializing the libraries, we use
 * ecore_con_server_add() to startup the server. Look at the reference
 * documentation of this function: it supports many types of server, and we are
 * going to use #ECORE_CON_REMOTE_TCP (a TCP based server). Other arguments to
 * this function are the address where we are listening on, the port, and a data
 * pointer that will associate that data with the server:
 *
 * @dontinclude ecore_con_server_simple_example.c
 * @skip main(void)
 * @until exit
 *
 * Notice that we are listening only on 127.0.0.1, which is the internal
 * loopback interface. If the server needs to listening on all of its ips, use
 * 0.0.0.0 instead.
 *
 * We also need to set event handlers to be called when we receive any data from
 * the clients, when a new client connects to our server, or when a client
 * disconnects. These callbacks are:
 *
 * @until CLIENT_DATA
 *
 * More details about what these callbacks do will be given later.
 *
 * Now, before running the main loop, we also want to set some limits to our
 * server. To avoid it to be overloaded with too many connections to handle, we
 * are going to set a maximum of 3 clients connected at the same time. This
 * number is used just to demonstrate the API. A good number to be used here
 * would need to be determined by tests done on the server, to check the load
 * supported by it.
 *
 * Any other client trying to connect to this server, after the limit is
 * reached, will wait until one of the connected clients disconnect and the
 * server accepts the new connection.
 *
 * Another important thing to do is setting a timeout, to avoid that a client
 * hold a connection for too long without doing anything. This timeout will
 * disconnect the idle client, allowing that other clients that may be waiting
 * to connect finally can do it.
 *
 * Then we just start the main loop:
 *
 * @until main_loop_begin
 *
 * After exiting the main loop, we print the list of connected clients, and also
 * free the data associated with each respective client. This data was
 * previously associated using ecore_con_client_data_set():
 *
 * @until }
 *
 * Then before exiting we show the total uptime of the server:
 *
 * @until uptime
 *
 * Now let's go back to the used callbacks.
 *
 * The first callback, @c _add, is registered to the event
 * #ECORE_CON_EVENT_CLIENT_ADD, which will be called whenever a client connects
 * to the server.
 *
 * This callback will associate a data structure to this client, that will be
 * used to count how many bytes were received from it. It also prints some info
 * about the client, and send a welcome string to it. ecore_con_client_flush()
 * is used to ensure that the string is sent immediately, instead of being
 * buffered.
 *
 * A timeout for idle specific for this client is also set, to demonstrate that
 * it is independent of the general timeout of the server.
 *
 * Before exiting, the callback will display a list of all clients still
 * connected to this server. The code for this callback follows:
 *
 * @dontinclude ecore_con_server_simple_example.c
 * @skip Eina_Bool
 * @until CALLBACK_RENEW
 * @until }
 *
 * The second callback is @c _del. It is associated with
 * #ECORE_CON_EVENT_CLIENT_DEL, and is called whenever a client disconnects from
 * this server.
 *
 * It will just print some information about the client, free the associated
 * data structure, and call ecore_con_client_del() on it before exiting the
 * callback. Here's its code:
 *
 * @until CALLBACK_RENEW
 * @until }
 *
 * The last callback will print any data received by this server from its
 * clients. It also increments the "bytes received" counter, sdata, in the
 * data structure associated with this client. The callback code follows:
 *
 * @until CALLBACK_RENEW
 * @until }
 *
 * The important parts of this example were described above. If you need to see
 * the full source code for it, there's a link to the code in the beginning of
 * this page.
 *
 * This example will start a server and start accepting connections from clients, as
 * demonstrated in the following diagram:
 * @htmlonly
 * <img src="ecore_con-client-server-example.png" style="max-width: 400px"/>
 * <a href="ecore_con-client-server-example.png">Full size</a>
 * @endhtmlonly
 *
 * @image rtf ecore_con-client-server-example.png
 * @image latex ecore_con-client-server-example.eps width=\textwidth
 *
 * @note This example contains a serious security flaw: it doesn't check for the
 * size of data being received, thus allowing to the string to be exploited in
 * some way. However, it is left like this to make the code simpler and just
 * demonstrate the API usage.
 */

/**
 * @page ecore_con_client_simple_example_c Ecore_Con - Creating a client
 *
 * Following the same idea as the @ref ecore_con_server_simple_example_c , this
 * example will demonstrate how to create a client that connects to a specified
 * server through a TCP port. You can see the full source code at @ref
 * ecore_con_client_simple_example.c.
 *
 * Starting from the @c main function, after reading the command line argument
 * list and initializing the libraries, we try to connect to the server:
 *
 * @dontinclude ecore_con_client_simple_example.c
 * @skip main(
 * @until exit(2)
 * @until }
 *
 * After doing this, everything else in @c main is setting up callbacks for the
 * client events, starting the main loop and shutting down the libraries after
 * it.
 *
 * Now let's go to the callbacks. These callbacks are very similar to the server
 * callbacks (our implementation for this example is very simple). On the
 * @c _add callback, we just set a data structure to the server, print some
 * information about the server, and send a welcome message to it:
 *
 * @dontinclude ecore_con_client_simple_example.c
 * @skip Eina_Bool
 * @until CALLBACK_RENEW
 * @until }
 *
 * The @c _del callback is as simple as the previous one. We free the data
 * associated with the server, print the uptime of this client, and quit the
 * main loop (since there's nothing to do once we disconnect):
 *
 * @until CALLBACK_RENEW
 * @until }
 *
 * The @c _data callback is also similar to the server data callback. it will
 * print any received data, and increase the data counter in the structure
 * associated with this server:
 *
 * @skip Eina_Bool
 * @until CALLBACK_RENEW
 * @until }
 *
 * You can see the server counterpart functions of the ones used in this example
 * in the @ref ecore_con_server_simple_example_c.
 *
 * This example will connect to the server and start comunicating with it, as
 * demonstrated in the following diagram:
 * @htmlonly
 * <img src="ecore_con-client-server-example2.png" style="max-width: 400px"/>
 * <a href="ecore_con-client-server-example2.png">Full size</a>
 * @endhtmlonly
 *
 * @image rtf ecore_con-client-server-example2.png
 * @image latex ecore_con-client-server-example2.eps width=\textwidth
 *
 * @note This example contains a serious security flaw: it doesn't check for the
 * size of data being received, thus allowing to the string to be exploited in
 * some way. However, it is left like this to make the code simpler and just
 * demonstrate the API usage.
 */

/**
 * @example ecore_idler_example.c
 * This example shows when @ref Ecore_Idler, @ref Ecore_Idle_Enterer and @ref
 * Ecore_Idle_Exiter are called. See
 * @ref ecore_idler_example_c "the explanation here".
 */

/**
 * @example ecore_job_example.c
 * This example shows how to use an @ref Ecore_Job. See
 * @ref ecore_job_example_c "the explanation here".
 */

/**
 * @example ecore_time_functions_example.c
 * Shows the difference between the three time functions. See @ref
 * ecore_time_functions_example_c "the example explained".
 */

/**
 * @example ecore_timer_example.c
 * This example shows how to use timers to have timed events inside ecore.
 * See @ref ecore_timer_example_c "the example explained".
 */

/**
 * @example ecore_exe_example_child.c
 * This is a child process used to receive messages and send it back
 * to its father.
 * Check the @ref Ecore_exe_simple_example_c "Full tutorial"
 */

/**
 * @example ecore_exe_example.c
 * This is a process that will send messages to a child and it will stop
 * when it receives "quit".
 * Check the @ref Ecore_exe_simple_example_c "Full tutorial"
 */

/**
 * @example ecore_fd_handler_example.c
 * This example shows how to setup and use an fd_handler. See
 * @ref ecore_fd_handler_example_c "the explanation here".
 */

/**
 * @example ecore_poller_example.c
 * This example shows how to setup and use a poller. See
 * @ref ecore_poller_example_c "the explanation here".
 */

/**
 * @example ecore_event_example_01.c
 * This example shows how to create an event handler. Explanation: @ref
 * ecore_event_example_01_c
 */

/**
 * @example ecore_event_example_02.c
 * This example shows how to setup, change, and delete event handlers. See
 * @ref ecore_event_example_02_c "the explanation here".
 */

/**
 * @example ecore_fd_handler_gnutls_example.c
 * Shows how to use fd handlers.
 */

/**
 * @example ecore_con_lookup_example.c
 * Shows how to make a simple DNS lookup. See the complete example description
 * at @ref ecore_con_lookup_example_c
 */

/**
 * @example ecore_con_url_download_example.c
 * Shows how to download a file using an @ref Ecore_Con_Url object. See the
 * complete example description at @ref ecore_con_url_download_example_c
 */

/**
 * @example ecore_con_url_cookies_example.c
 * Shows how to manage cookies on a @ref Ecore_Con_Url object. See the complete
 * example description at @ref ecore_con_url_cookies_example_c.
 */

/**
 * @example ecore_con_server_simple_example.c
 * Shows how to setup a simple server that accepts client connections and sends
 * a "hello" string to them. See the complete example description at @ref
 * ecore_con_server_simple_example_c
 */

/**
 * @example ecore_con_client_simple_example.c
 * Shows how to setup a simple client that connects to a server and sends a
 * "hello" string to it. See the complete example description at @ref
 * ecore_con_client_simple_example_c
 */

/**
 * @example ecore_con_url_headers_example.c
 * Shows how to make GET or POST requests using an @ref Ecore_Con_Url object,
 * and make use of most of its API.  See the complete example description at
 * @ref ecore_con_url_headers_example_c
 */

/**
 * @page tutorial_ecore_pipe_gstreamer_example
 *
 * Here is an example that uses the pipe wrapper with a Gstreamer
 * pipeline. For each decoded frame in the Gstreamer thread, a handle
 * is called in the ecore thread.
 *
 * @include ecore_pipe_gstreamer_example.c
 * @example ecore_pipe_gstreamer_example.c
 */

/**
 * @page tutorial_ecore_pipe_simple_example
 * @dontinclude ecore_pipe_simple_example.c
 *
 * This example shows some simple usage of ecore_pipe. We are going to create a
 * pipe, fork our process, and then the child is going to communicate to the
 * parent the result of its processing through the pipe.
 *
 * As always we start with our includes, nothing special:
 * @skip #include
 * @until Ecore.h
 *
 * The first thing we are going to define in our example is the function we are
 * going to run on the child process, which, as mentioned, will do some
 * processing and then will write the result to the pipe:
 * @until }
 * @until }
 * @note The sleep was added so the parent process would think the child process
 * was doing something interesting...
 *
 * Next up is our function for handling data arriving in the pipe. It copies the
 * data to another buffer, adds a terminating NULL and prints it. Also if it
 * receives a certain string it stops the main loop(effectively ending the
 * program):
 * @until }
 * @until }
 *
 * And now on to our main function, we start by declaring some variables and
 * initializing ecore:
 * @until ecore_init
 *
 * And since we are talking about pipes let's create one:
 * @until pipe_add
 *
 * Now we are going to fork:
 * @until fork
 * @note duh...
 *
 * The child process is going to do the our fancy processing:
 * @until }
 * @note It's very important to call ecore_pipe_read_close() here so that the
 * child process won't read what it is writing to the pipe itself.
 *
 * And the parent is going to run ecore's main loop waiting for some data:
 * @until }
 * @note Calling ecore_pipe_write_close() here isn't important but since we
 * aren't going to write in the pipe it is good practice.
 *
 * And finally when done processing(the child) or done receiving(the parent) we
 * delete the pipe and shutdown ecore:
 * @until }
 *
 * @example ecore_pipe_simple_example.c
 */

/**
 * @page tutorial_ecore_animator Ecore animator example
 * @dontinclude ecore_animator_example.c
 *
 * For this example we are going to animate a rectangle growing, moving and
 * changing color, and then move it back to it's initial state with a
 * different animation. We are also going to have a second rectangle moving
 * along the bottom of the screen. To do this we are going to use ecore_evas,
 * but since that is not the focus here we won't going into detail about it.
 *
 * @skip #include
 * @until evas_object_show
 * @until evas_object_show
 * All of this is just setup, not what we're interested in right now.
 *
 * Now we are going to set the frametime for our animation to one fiftieth of
 * a second, this will make our program consume more resources but should make
 * our animation extra smooth:
 * @until frametime
 *
 * And now we get right to the business of creating our ecore_animator:
 * @until timeline
 * @note We are telling our animation to last 10 second and to call
 * _advance_frame with rect as data.
 *
 * So far we setup the first and second animations, the third one however is a
 * bit different, this time we won't use a timeline animation, that's because we
 * don't want our animation to stop:
 * @until animator_add
 *
 * Next we set a few timers to execute _start_second_anim, _freeze_third_anim
 * and _thaw_thir_anim in 10, 5 and 10 seconds respectively:
 * @until thaw
 *
 * And now we tell ecore to begin the main loop and free some resources once
 * it leaves the main loop:
 * @until }
 *
 * Here we have the callback function for our first animation, which first
 * takes @p pos(where in the timeline we are), maps it to a SPRING curve that
 * which will wobble 15 times and will decay by a factor of 1.2:
 * @until pos_map
 *
 * Now that we have the frame we can adjust the rectangle to its appropriate
 * state:
 * @until }
 *
 * And now the callback that will run 10 seconds after the program starts(5
 * seconds after the first animation finishes) and starts our second
 * animation:
 * @until }
 * @note For this animation we made the frametime much larger which means our
 * animation might get "jerky".
 *
 * The callback for our second animation, our savvy reader no doubt noted that
 * it's very similar to the callback for the first animation. What we change for
 * this one is the type of animation to BOUNCE and the number of times it will
 * bounce to 50:
 * @until }
 *
 * And for our last animation callback something simpler, we just move our
 * rectangle right by one pixel until it reaches the end of the screen and then
 * start at the beginning again:
 * @until }
 *
 * Our next two functions respectively freezes and thaw our third animation, so
 * that it won't happen for the 5 seconds after the first animation ends and the
 * second animation begins:
 * @until }
 * @until }
 *
 * @example ecore_animator_example.c
 */

/**
 * @page ecore_thread_example_c Ecore_Thread - API overview
 *
 * Working with threads is hard. Ecore helps to do so a bit easier, but as
 * the example in @ref ecore_thread_example.c "ecore_thread_example.c" shows,
 * there's a lot to consider even when doing the most simple things.
 *
 * We'll be going through this thorough example now, showing how the differents
 * aspects of @ref Ecore_Thread are used, but users are encourage to avoid
 * threads unless it's really the only option, as they always add more
 * complexity than the program usually requires.
 *
 * Ecore Threads come in two flavors, short jobs and feedback jobs. Short jobs
 * just run the given function and are more commonly used for small tasks
 * where the main loop does not need to know how the work is going in between.
 * The short job in our example is so short we had to artificially enlarge it
 * with @c sleep(). Other than that, it also uses threads local data to keep
 * the data we are working with persistent across different jobs ran by the
 * same system thread. This data will be freed when the no more jobs are
 * pending and the thread is terminated. If the data doesn't exist in the
 * thread's storage, we create it and save it there for future jobs to find
 * it. If creation fails, we cancel ourselves, so the main loop knows that
 * we didn't just exit normally, meaning the job could not be done. The main
 * part of the function checks in each iteration if it was canceled by the
 * main loop, and if it was, it stops processing and clears the data from the
 * storage (we assume @c cancel means no one else will need this, but this is
 * really application dependent).
 * @dontinclude ecore_thread_example.c
 * @skip static void
 * @until sleep(1)
 * @until }
 * @until }
 *
 * Feedback jobs, on the other hand, run tasks that will inform back to the
 * main loop its progress, send partial data as is processed, just ping saying
 * it's still alive and processing, or anything that needs the thread to talk
 * back to the main loop.
 * @skip static void
 * @until the_end
 * @until }
 *
 * Finally, one more feedback job, but this one will be running outside of
 * Ecore's pool, so we can use the pool for real work and keep this very
 * light function unchecked. All it does is check if some condition is met
 * and send a message to the main loop telling it it's time to close.
 * @skip static void
 * @until }
 * @until }
 * @until }
 *
 * Every now and then the program prints its status, counting threads running
 * and pending jobs.
 * @skip static void
 * @until }
 *
 * In our main loop, we'll be receiving messages from our feedback jobs using
 * the same callback for both of them.
 * @skip static void
 * @until char *str
 *
 * The light job running out of the pool will let us know when we can exit our
 * program.
 * @until }
 *
 * Next comes the handling of data sent from the actual worker threads, always
 * remembering that the data belongs to us now, and not the thread, so it's
 * our responsibility to free it.
 * @until }
 * @until }
 *
 * Last, the condition to exit is given by how many messages we want to handle,
 * so we need to count them and inform the condition checking thread that the
 * value changed.
 * @until }
 *
 * When a thread finishes its job or gets canceled, the main loop is notified
 * through the callbacks set when creating the task. In this case, we just
 * print what happen and keep track of one of them used to exemplify canceling.
 * Here we are pretending one of our short jobs has a timeout, so if it doesn't
 * finish before a timer is triggered, it will be canceled.
 * @skip static void
 * @until _cancel_timer_cb
 * @until }
 *
 * The main function does some setup that includes reading parameters from
 * the command line to change its behaviour and test different results.
 * These are:
 * @li -t \<some_num\> maximum number of threads to run at the same time.
 * @li -p \<some_path\> adds @c some_path to the list used by the feedback jobs.
 * This parameter can be used multiple times.
 * @li -m \<some_num\> the number of messages to process before the program is
 * signalled to exit.
 *
 * Skipping some bits, we init Ecore and our application data.
 * @skip ecore_init
 * @until appdata.max_msgs
 *
 * If any paths for the feedback jobs were given, we use them, otherwise we
 * fallback to some defaults. Always initializing the proper mutexes used by the
 * threaded job.
 * @skip path_list
 * @until EINA_LIST_FREE
 * @until }
 * @until }
 *
 * Initialize the mutex needed for the condition checking thread
 * @skip appdata.mutex
 * @until appdata.condition
 *
 * And start our tasks.
 * @until appdata.thread_3
 * @until EINA_FALSE
 *
 * To finalize, set a timer to cancel one of the tasks if it doesn't end
 * before the timeout, one more timer for status report and get into the main
 * loop. Once we are out, destroy our mutexes and finish the program.
 * @until _status_timer_cb
 * @until }
 *
 * @example ecore_thread_example.c
 */

/**
 * @page ecore_evas_callbacks_example_c Ecore Evas Callbacks
 * @dontinclude ecore_evas_callbacks.c
 *
 * Our example is remarkably simple, all it does is create an Ecore_Evas and
 * register a callback for a bunch of events. What's interesting here is
 * knowing when each of these callbacks will be called, however since that
 * depends on the underlying windowing system there are no guarantees that all
 * of the callbacks will be called for your windowing system. To know which
 * callbacks will be called for your windowing system run the example and
 * redirect the output to a file, and take a look at it.
 *
 * @note Make sure you minimize, resize, give and remove focus to see more
 * callbacks called.
 *
 * The example is constituted of two main parts, first is the implementation of
 * callbacks that will be called for each event(all our callbacks do is print
 * their own name) and the second is the main function where we register the
 * event callbacks and run the main loop:
 * @include ecore_evas_callbacks.c
 * @example ecore_evas_callbacks.c
 */

/**
 * @page Ecore_Evas_Window_Sizes_Example_c Ecore_Evas window size hints
 *
 * On this example, we show you how to deal with @c Ecore_Evas window
 * size hints, which are implemented <b>per Evas engine</b>.
 *
 * We start by defining an initial size for our window and, after
 * creating it, adding a background white rectangle and a text object
 * to it, to be used to display the current window's sizes, at any
 * given time:
 * @dontinclude ecore_evas_window_sizes_example.c
 * @skip define WIDTH
 * @until define
 * @until define
 * @dontinclude ecore_evas_window_sizes_example.c
 * @skip evas_init
 * @until show(bg)
 * @dontinclude ecore_evas_window_sizes_example.c
 * @skip text =
 * @until main_loop_begin
 * @dontinclude ecore_evas_window_sizes_example.c
 * @skip to inform
 * @until }
 *
 * The program has a command line interface, responding to the
 * following keys:
 * @dontinclude ecore_evas_window_sizes_example.c
 * @skip commands
 * @until ;
 *
 * Use the @c 'm' key to impose a minimum size of half the initial
 * ones on our window. Test it by trying to resize it to smaller sizes
 * than that:
 * @dontinclude ecore_evas_window_sizes_example.c
 * @skip key, "m"
 * @until }
 * @until }
 * @until }
 *
 * The @c 'x' key will, in turn, set a maximum size on our window --
 * to two times our initial size. Test it by trying to resize the
 * window to bigger sizes than that:
 * @dontinclude ecore_evas_window_sizes_example.c
 * @skip key, "x"
 * @until }
 * @until }
 * @until }
 *
 * Window base sizes will override any minimum sizes set, so try it
 * with the @c 'b' key. It will set a base size of two times the
 * initial one:
 * @dontinclude ecore_evas_window_sizes_example.c
 * @skip key, "b"
 * @until }
 * @until }
 * @until }
 *
 * Finally, there's a key to impose a "step size" on our window, of 40
 * pixels.  With than on (@c 's' key), you'll see the window will
 * always be bound to @b multiples of that size, for dimensions on
 * both axis:
 * @skip key, "s"
 * @until }
 * @until }
 * @until }
 *
 * The full example follows.
 *
 * @include ecore_evas_window_sizes_example.c
 * @example ecore_evas_window_sizes_example.c
 */

/**
 * @page ecore_evas_object_example_c Ecore Evas Object example
 * @dontinclude ecore_evas_object_example.c
 *
 * This example creates an Ecore_Evas(a window) and associates a background and
 * a custom cursor for it.
 *
 * We'll start looking at the association, which is quite simple. We choose to
 * associate using ECORE_EVAS_OBJECT_ASSOCIATE_BASE to have it be resized with
 * the window, since for a background that is what's most useful:
 * @skipline ecore_evas_object_associate
 * @note If we didn't associate the background we'd need to listen to resize of
 * Ecore_Evas and manually resize the background or have artifacts on our
 * window.
 *
 * We then check that the association worked:
 * @until printf
 *
 * Next we are going to set a custom cursor, for our cursor we are going to use
 * a small green rectangle. Our cursor is going to be on layer 0(any lower and
 * it would be below the background and thus invisible) and clicks will be
 * computed as happening on pixel 1, 1 of the image:
 * @until cursor_set
 *
 * We then check every one of those parameters:
 * @until printf
 *
 * Here you have the full-source of the code:
 * @include ecore_evas_object_example.c
 * @example ecore_evas_object_example.c
 */

/**
 * @page ecore_evas_basics_example_c Ecore Evas basics example
 * @dontinclude ecore_evas_basics_example.c
 *
 * This example will illustrates the usage of some basic Ecore_Evas functions.
 * This example will list the available evas engines, check which one we used to
 * create our window and set some data on our Ecore_Evas. It also allows you to
 * hide/show all windows in this process(we only have one, but if there were
 * more they would be hidden), to hide the windows type 'h' and hit return, to
 * show them, type 's' and hit return.
 *
 * The very first thing we'll do is initialize ecore_evas:
 * @skipline evas_init
 * @until return 1
 *
 * Once inited we query which engines are available:
 * @until ecore_evas_engines_free
 *
 * We then create an Ecore_Evas(window) with the first available engine, on
 * position 0,0 with size 200,200 and no especial flags, set it's title and show
 * it:
 * @until evas_show
 *
 * We now add some important data to our Ecore_Evas:
 * @until data_set
 *
 * And since our data is dynamically allocated we'll need to free it when the
 * Ecore_Evas dies:
 * @until delete_request
 * @dontinclude ecore_evas_basics_example.c
 * @skip static void
 * @until }
 * @skip printf("Using
 *
 * We now print which Evas engine is being used for our example:
 * @until printf
 *
 * We are going to add a background to our window but before we can do that
 * we'll need to get the canvas(Evas) on which to draw it:
 * @until canvas
 *
 * We then do a sanity check, verifying if the Ecore_Evas of the Evas is the
 * Ecore_Evas from which we got the Evas:
 * @until printf
 *
 * Now we can actually add the background:
 * @until ecore_evas_object_associate
 *
 * To hide and show the windows of this process when the user presses 'h' and
 * 's' respectively we need to know when the user types something, so we
 * register a callback for when we can read something from @c stdin:
 * @until )
 *
 * The callback that actually does the hiding and showing is pretty simple, it
 * does a @c scanf(which we know won't block since there is something to read on
 * @c stdin) and if the character is an 'h' we iterate over all windows calling
 * @c ecore_evas_hide on them, if the character is an 's' we call @c
 * ecore_evas_show instead:
 * @dontinclude ecore_evas_basics_example.c
 * @skip static Eina_Bool
 * @until }
 * @skip ecore_main_loop_begin
 *
 * Once all is done we run our main loop, and when that is done(application is
 * exiting) we free our Ecore_Evas and shutdown the ecore_evas subsystem:
 * @until shutdown
 *
 * Here you have the full-source of the code:
 * @include ecore_evas_basics_example.c
 * @example ecore_evas_basics_example.c
 */

/**
 * @page Ecore_Evas_Buffer_Example_01_c Ecore_Evas buffer example
 *
 * Between the Evas examples, there is one in which one creates a
 * canvas bound to the Evas @b buffer engine and uses its pixel
 * contents to create an PPM image on disk. There, one does that by
 * creating the canvas "by hand", with @c evas_new(), @c
 * evas_engine_info_set(), etc.
 *
 * On this example, we accomplish the very same task, but by using the
 * @c Ecore_Evas helper wrapper functions on a buffer engine
 * canvas. If you compare both codes, you'll see how much code one is
 * saved from by using the @c Ecore_Evas wrapper functions.
 *
 * The code is simple as it can be. After instantianting our canvas
 * window, with ecore_evas_buffer_new(), we grab its canvas pointer
 * and create the desired objects scene on it, which in this case is
 * formed by 3 rectangles over the top left corner of a white
 * background:
 * @dontinclude ecore_evas_buffer_example_01.c
 * @skip main(void)
 * @until show(r3)
 *
 * Since it's a buffer canvas and we're using it to only save its
 * contents on a file, we even needn't ecore_evas_show() it. We make
 * it render itself, forcefully, without the aid of Ecore's main loop,
 * with ecore_evas_manual_render():
 * @dontinclude ecore_evas_buffer_example_01.c
 * @skip manual_render
 * @until manual_render
 *
 * And we're ready to save the window's shiny rendered contents as a
 * simple PPM image. We do so by grabbing the pixels of the @c
 * Ecore_Evas' internal canvas, with ecore_evas_buffer_pixels_get():
 * @dontinclude ecore_evas_buffer_example_01.c
 * @skip _scene_save
 * @until }
 * @dontinclude ecore_evas_buffer_example_01.c
 * @skip support function
 * @until }
 * @until }
 * @until }
 *
 * Check that destination file for the result. The full example
 * follows.
 *
 * @include ecore_evas_buffer_example_01.c
 * @example ecore_evas_buffer_example_01.c
 */

/**
 * @page Ecore_Evas_Buffer_Example_02_c Ecore_Evas (image) buffer example
 *
 * In this example, we'll demonstrate the use of
 * ecore_evas_object_image_new().  The idea is to have the same scene
 * created for @ref Ecore_Evas_Buffer_Example_01_c as the contents of
 * an image object.
 *
 * The canvas receiving this image object will have a white
 * background, a red border image to delimit this image's boundaries
 * and the image itself.  After we create the special image, we set
 * its "fill" property, place and resize it as we want. We have also
 * to resize its underlying @c Ecore_Evas too, to the same dimensions:
 * @dontinclude ecore_evas_buffer_example_02.c
 * @skip object_image_new
 * @until resize(sub_ee
 *
 * Now, we re-create the scene we cited, using the sub-canvas of our
 * image to parent the objects in question. Because image objects are
 * created with the alpha channel enabled, by default, we'll be seeing
 * our white rectangle beneath the scene:
 * @dontinclude ecore_evas_buffer_example_02.c
 * @skip rectangle_add(sub_canvas
 * @until loop_begin
 *
 * And that's all. The contents of our image could be updated as one
 * wished, and they would always be mirrored in the image's area.
 *
 * Check that destination file for the result. The full example
 * follows.
 *
 * @include ecore_evas_buffer_example_02.c
 * @example ecore_evas_buffer_example_02.c
 */

/**
 * @page Ecore_exe_simple_example_c Ecore_exe
 * Creating a processes and IPC (Inter process communication)
 *
 * In this example we will show how to create a new process and communicate
 * with it in a portable way using the Ecore_exe module.
 *
 * In this example we will have two process and both will communicate with each
 * other using messages. A father process will start a child process and it will
 * keep sending messages to the child until it receives a message to quit.
 * To see the full source use the links:
 * @li @ref ecore_exe_example.c "Father"
 * @li @ref ecore_exe_example_child.c "Child"
 *
 * Let's start the tutorial. The implementation of the child it's pretty simple.
 * We just read strings from stdin and write a message in the stdout. But you
 * should be asking yourself right know. "If I'm receiving data from an other
 * process why I'm reading and writing in stdin/stdout?". That's because, when
 * you spawn a process using the Ecore_Exe module it will create a pipe between
 * the father and the child process and the stdin/stdout of the child process
 * will be redirected to the pipe. So when the child wants to receive or send
 * data to the father, just use the stdin/stdout.
 * However the steps to send data from the father to the child is quite
 * different, but we will get there.
 *
 * The child will register a fd handler to monitor the stdin.
 * So we start registering the ecore FD handler:
 * @dontinclude ecore_exe_example_child.c
 * @skip ecore_main_fd_handler_add
 * @until ;
 *
 * If you don't remenber the parameters of @ref ecore_main_fd_handler_add,
 * please check its documentation.
 *
 * Now that we have our handler registered we will start the ecore's main loop:
 * @skipline ecore_main_loop_begin
 *
 * Now let's take a look in the callback function. Its a simple function
 * that will read from stdin 3 times and at the third time will say
 * to the father: "quit".
 * @dontinclude ecore_exe_example_child.c
 * @skip static Eina_Bool
 * @until }
 * @until }
 * @until }
 * @until }
 *
 * You may notice that we are sending the messages to stdout, and our father
 * will receive it. Also our string must have a "\n" because the string will
 * be buffered in the pipe until it finds EOF or a "newline" in our case we
 * won't have a EOF unless we close the pipe, so we use the "\n" char.
 *
 * One more thing, we use fflush(stdout) because probably our message won't
 * fill our entire buffer and the father would never receive the message. So we
 * use this function to flush the buffer and the father can receive as fast as
 * possible.
 *
 * Now that we have our child ready, let's start our work in the father's source
 * code.
 *
 * We start creating the child process like this:
 * @dontinclude ecore_exe_example.c
 * @skip childHandle = ecore_exe_pipe_run
 * @until ;
 *
 * With the command above we are creating our child process, the first
 * parameter is the command to be executed, the second are the pipe flags and
 * in our case we will write and read in the pipe so we must say what we are
 * doing in the pipe. You may notice the flag ECORE_EXE_PIPE_READ_LINE_BUFFERED,
 * this means that reads are buffered until I find a newline. And the third
 * parameter is data that we would like to send to the process in its creating.
 * This case we are sending nothing, so just use NULL.
 *
 * Then we check if the process was created:
 * @skip if
 * @until }
 *
 * After this we get the PID of the child process and just print it in the screen.
 * The PID stands for Process identification. This is just an internal
 * identifier of your process:
 *
 * @skip childPid
 * @until fprintf
 * @until fprintf
 *
 * The way that Ecore_exe works is: when we want to read data sent from
 * our child we must use an ecore event.
 * So let's start register our event listener:
 * @skipline ecore_event_handler_add
 *
 * Now to send messages to our child we will use a timer, so every 1 second we
 * will send a message to the child.
 * @skipline ecore_timer_add
 *
 * After all this we start the main loop. Now let's pass to the callback
 * functions.
 *
 * Now we will see how we actually send the data and receive it.
 * Let's start with _sendMessage:
 * @dontinclude ecore_exe_example.c
 * @skip _sendMessage(void *data)
 * @until }
 *
 * We use ecore_exe_send to send data to the child process, it's pretty simple.
 * To know what the parameters stands for, check the docs.
 *
 * @note The function @b ecore_exe_send will never block your program, also
 * there is no partial send of the data. This means either the function will
 * send all the data or it will fail.
 *
 * Now let's take a look in our event callback and see how we retrieve the
 * messages.
 * @dontinclude ecore_exe_example.c
 * @skip static Eina_Bool
 * @until }
 * @until }
 *
 * It's just like an normal event, we get a reference to Ecore_Exe_Event_Data,
 * extract the data and then show it in the screen.
 *
 * And that's it, after all it's not complicated to create a process and
 * communicate with it.
 *
 */

/**
 * @page ecore_imf_example_c ecore_imf - How to handle preedit and commit string from Input Method Framework
 *
 * This example demonstrates how to connect input method framework and handle preedit and commit string from input method framework.
 *
 * To input Chinese, Japanese, Korean and other complex languages, the editor should be connected with input method framework.
 * 
 * How to initialize and shutdown ecore imf module
 * @li ecore_imf_init() should be called to initialize and load immodule.
 * @li ecore_imf_shutdown() is used for shutdowning and unloading immodule.
 *
 * How to create input context and register pre-edit and commit event handler
 *
 * Each entry should have each input context to connect with input service framework. 
 * Key event is processed by input method engine. 
 * The result is notified to application through ECORE_IMF_CALLBACK_PREEDIT_CHANGED and ECORE_IMF_CALLBACK_COMMIT event.
 *
 * The full example follows. 
 *
 * @include ecore_imf_example.c
 */