summaryrefslogtreecommitdiff
path: root/doc/ecore_examples.dox
diff options
context:
space:
mode:
authorJonas M. Gastal <jgastal@profusion.mobi>2012-12-18 16:13:03 +0000
committerJonas M. Gastal <jgastal@profusion.mobi>2012-12-18 16:13:03 +0000
commit0809af70fb0e762a748b5d72ed353971d88bae9b (patch)
treebaf0f67fb24cc8487fa8e2c3f8a5f69a4ce61b04 /doc/ecore_examples.dox
parent6ecaa33f2265b7ba0060ffcdc93e96366a49e886 (diff)
efl: Adding *.dox files from various libs.
SVN revision: 81274
Diffstat (limited to 'doc/ecore_examples.dox')
-rw-r--r--doc/ecore_examples.dox1692
1 files changed, 1692 insertions, 0 deletions
diff --git a/doc/ecore_examples.dox b/doc/ecore_examples.dox
new file mode 100644
index 0000000..cc7ec9d
--- /dev/null
+++ b/doc/ecore_examples.dox
@@ -0,0 +1,1692 @@
1/**
2 * @page Examples Examples
3 *
4 * Here is a page with some Ecore examples explained:
5 *
6 * @li @ref ecore_time_functions_example_c
7 * @li @ref ecore_timer_example_c
8 * @li @ref ecore_idler_example_c
9 * @li @ref ecore_job_example_c
10 * @li @ref ecore_event_example_01_c
11 * @li @ref ecore_event_example_02_c
12 * @li @ref ecore_fd_handler_example_c
13 * @li @ref ecore_poller_example_c
14 * @li @ref ecore_con_lookup_example_c
15 * @li @ref ecore_con_url_download_example_c
16 * @li @ref ecore_con_server_simple_example_c
17 * @li @ref ecore_con_client_simple_example_c
18 * @li @ref ecore_evas_callbacks_example_c
19 * @li @ref ecore_evas_object_example_c
20 * @li @ref ecore_evas_basics_example_c
21 * @li @ref Ecore_Evas_Window_Sizes_Example_c
22 * @li @ref Ecore_Evas_Buffer_Example_01_c
23 * @li @ref Ecore_Evas_Buffer_Example_02_c
24 * @li @ref Ecore_exe_simple_example_c
25 * @li @ref ecore_imf_example_c
26 */
27
28/**
29 * @page ecore_time_functions_example_c ecore_time - Differences between time functions
30 *
31 * This example shows the difference between calling ecore_time_get(),
32 * ecore_loop_time_get() and ecore_time_unix_get().
33 *
34 * It initializes ecore, then sets a timer with a callback that, when called,
35 * will retrieve the system time using these 3 different functions. After
36 * displaying the time, it sleeps for 1 second, then call display the time
37 * again using the 3 functions.
38 *
39 * Since everything occurs inside the same main loop iteration, the internal
40 * ecore time variable will not be updated, and calling ecore_loop_time_get()
41 * before and after the sleep() call will return the same result.
42 *
43 * The two other functions will return a difference of 1 second, as expected.
44 * But ecore_time_unix_get() returns the number of seconds since 00:00:00 1st
45 * January 1970, while ecore_time_get() will return the time since a
46 * unspecified point, but that never goes back in time, even when the timezone
47 * of the machine changes.
48 *
49 * @note The usage of ecore_loop_time_get() should be preferred against the
50 * two other functions, for most time calculations, since it won't produce a
51 * system call to get the current time. Use ecore_time_unix_get() when you need
52 * to know the current time and date, and ecore_time_get() when you need a
53 * monotonic and more precise time than ecore_loop_time_get().
54 *
55 * @include ecore_time_functions_example.c
56 */
57
58/**
59 * @page ecore_timer_example_c ecore timers - Scheduled events
60 * @dontinclude ecore_timer_example.c
61 *
62 * This example shows how to setup timer callbacks. It starts a timer that will
63 * tick (expire) every 1 second, and then setup other timers that will expire
64 * only once, but each of them will affect the first timer still executing with
65 * a different API, to demonstrate its usage. To see the full code for this
66 * example, click @ref ecore_timer_example.c "here".
67 *
68 * To demonstrate this, let's define some constants that will determine at which
69 * time each timer will expire:
70 *
71 * @until INTERVAL1
72 *
73 * These constants should tell by themselves what will be the behavior of the
74 * program, but I'll explain it anyway. The first timer is set to tick every 1
75 * second, but all the other timers until the 6th one will be started
76 * concurrently at the beginning of the program. Each of them will expire at the
77 * specified time in these constants:
78 *
79 * @li The timer2, after 3 seconds of the program being executed, will add a delay
80 * of 3 seconds to timer1;
81 * @li The timer3 will pause timer1 at 8.2 seconds;
82 * @li timer4 will resume timer1 at 11.0 seconds;
83 * @li timer5 will will change the interval of timer1 to 2 seconds;
84 * @li timer6 will stop timer1 and start timer7 and timer8, with 1.1 and 1.2
85 * seconds of interval, respectively; it also sets the precision to 0.2 seconds;
86 * @li timer7 and timer8 will just print their expiration time.
87 *
88 * @until ecore_time_get
89 * @until }
90 *
91 * As almost all the other examples, we create a context structure to pass to
92 * our callbacks, so they can have access to the other timers. We also store the
93 * time of the program start in @c _initial_time, and use the function
94 * @c _get_current_time to retrieve the current time relative to that time. This
95 * will help demonstrate what is going on.
96 *
97 * Now, the behavior and relationship between the timers that was described
98 * above is dictated by the following timer callbacks:
99 *
100 * @until _timer6_cb
101 * @until }
102 *
103 * It's possible to see the same behavior as other Ecore callbacks here,
104 * returning @ref ECORE_CALLBACK_RENEW when the timer needs to continue ticking,
105 * and @ref ECORE_CALLBACK_CANCEL when it needs to stop its execution. Also
106 * notice that later on our program we are checking for the timers pointers in
107 * the context to see if they are still executing before deleting them, so we
108 * need to set these timer pointers to @c NULL when we are returning @ref
109 * ECORE_CALLBACK_CANCEL. Otherwise the pointer would still be not @c NULL, but
110 * pointing to something that is invalid, since the timer would have already
111 * expired without renewing.
112 *
113 * Now the main code, which will start the timers:
114 *
115 * @until ecore_shutdown
116 * @until }
117 *
118 * This code is very simple. Just after starting the library, it will save the
119 * current time to @c _initial_time, start all timers from 1 to 6, and begin the
120 * main loop. Everything should be running right now, displaying the time which
121 * each timer is expiring, and what it is doing to affect the other timers.
122 *
123 * After returning from the main loop, every timer is checked to see if it's
124 * still alive and, in that case, deleted, before finalizing the library. This
125 * is not really necessary, since ecore_shutdown() will already delete them for
126 * you, but it's good practice if you have other things going on after this
127 * point that could restart the main loop.
128 *
129 */
130
131/**
132 * @page ecore_idler_example_c ecore idle state - Idlers, enterers and exiters
133 *
134 * This example demonstrates how to manage the idle state of the main loop. Once
135 * a program knows that the main loop is going to enter in idle state, it could
136 * start doing some processing until getting out of this state.
137 *
138 * To exemplify this, we also add events and a timer to this program, so we can
139 * see the idle exiter callback being called before processing the event and/or
140 * timer, the event/timer callback being called (processed), then the idle
141 * enterer being called before entering in idle state again. Once in idle, the
142 * main loop keeps calling the idler callback continuously until a new event or
143 * timer is received.
144 *
145 * First, we declare a struct that will be used as context to be passed to
146 * every callback. It's not useful everywhere, since this example is very
147 * simple and doesn't do anything other than printing messages, but using this
148 * context will make it a little bit more real. Our context will be used to
149 * delete the timer, idler, idle enterer and exiter, and the event handler, and
150 * also to count how many times the idler was called.
151 *
152 * Then we start declaring callbacks for the idle enterer, idle exiter and the
153 * idler itself. Idle enterer and exiter callbacks just print a message saying
154 * that they were called, while the idler, in addition to printing a message
155 * too, also sends an event every 10 times that it is called, incrementing the
156 * context count variable. This event will be used to make the main loop exit
157 * the idle state and call the event callback.
158 *
159 * These callbacks return @ref ECORE_CALLBACK_RENEW, since we want them to keep
160 * being called every time the main loop changes to/from idle state. Otherwise,
161 * if we didn't want them to be called again, they should return @ref
162 * ECORE_CALLBACK_CANCEL.
163 *
164 * The next function declared is the event callback @c _event_handler_cb. It
165 * will check if the idler was called more than 100 times already @c
166 * (ctxt->count > 100), and will delete the idler, idle enterer and exiter, the
167 * timer (if it still exists), and request that the main loop stop running. Then
168 * it returns @ref ECORE_CALLBACK_DONE to indicate that the event shouldn't be
169 * handled by any other callback.
170 *
171 * Finally, we add a callback to the timer, that will just print a message when
172 * it is called, and this will happen only once (@ref ECORE_CALLBACK_CANCEL is
173 * being returned). This timer callback is just here to show that the main loop
174 * gets out of idle state when processing timers too.
175 *
176 * The @b main function is simple, just creates a new type of event that we will
177 * use to demonstrate the event handling together with the idle state, adds the
178 * callbacks that we declared so far, fill the context struct, and starts
179 * running the main loop.
180 *
181 * @note We use timer and event callbacks to demonstrate the idle state
182 * changing, but it also happens for file descriptor handlers, pipe handlers,
183 * etc.
184 *
185 * @include ecore_idler_example.c
186 */
187
188/**
189 * @page ecore_job_example_c ecore_job - Queuing tasks
190 *
191 * This example shows how an @ref Ecore_Job can be added, how it can be
192 * deleted, and that they always execute in the added order.
193 *
194 * First, 2 callback functions are declared, one that prints strings passed to
195 * it in the @c data pointer, and another one that quits the main loop. In the
196 * @c main function, 3 jobs are added using the first callback, and another one
197 * is added using the second one.
198 *
199 * Then the second added job is deleted just to demonstrate the usage of
200 * ecore_job_del(), and the main loop is finally started. Run this example to
201 * see that @c job1, @c job3 and @c job_quit are ran, in this order.
202 *
203 * @include ecore_job_example.c
204 */
205
206/**
207 * @page ecore_event_example_01_c Handling events example
208 * This example shows the simplest possible way to register a handler for an
209 * ecore event, this way we can focus on the important aspects. The example will
210 * start the main loop and quit it when it receives the ECORE_EVENT_SIGNAL_EXIT
211 * event. This event is triggered by a SIGTERM(pressing ctrl+c).
212 *
213 * So let's start with the function we want called when we receive the event,
214 * instead of just stopping the main loop we'll also print a message, that's
215 * just so it's clear that it got called:
216 * @dontinclude ecore_event_example_01.c
217 * @skip static
218 * @until }
219 * @note We return ECORE_CALLBACK_DONE because we don't want any other handlers
220 * for this event to be called, the program is quitting after all.
221 *
222 * We then have our main function and the obligatory initialization of ecore:
223 * @until ecore_init
224 *
225 * We then get to the one line of our example that makes everything work, the
226 * registering of the callback:
227 * @until handler_add
228 * @note The @c NULL there is because there is no need to pass data to the
229 * callback.
230 *
231 * And the all that is left to do is start the main loop:
232 * @until }
233 *
234 * Full source code for this example: @ref ecore_event_example_01.c.
235 */
236
237/**
238 * @page ecore_event_example_02_c ecore events and handlers - Setup and use
239 * This example shows how to create a new type of event, setup some event
240 * handlers to it, fire the event and have the callbacks called. After
241 * finishing, we delete the event handlers so no memory will leak.
242 *
243 * See the full source code for this example @ref ecore_event_example_02.c
244 * "here".
245 *
246 * Let's start the example from the beginning:
247 *
248 * @dontinclude ecore_event_example_02.c
249 * @until _event_type
250 *
251 * First thing is to declare a struct that will be passed as context to the
252 * event handlers. In this structure we will store the event handler pointers,
253 * and two strings that will be used by the first event handler. We also will
254 * use a global integer to store the event type used for our event. It is
255 * initialized with 0 in the beginning because the event wasn't created yet.
256 * Later, in the main function we will use ecore_event_type_new() to associate
257 * another value to it. Now the event handler callbacks:
258 *
259 * @until }
260 *
261 * This is the first event handler callback. It prints the event data received
262 * by the event, and the data passed to this handler when it was added. Notice
263 * that this callback already knows that the event data is an integer pointer,
264 * and that the handler data is a string. It knows about the first one because
265 * this is based on the type of event that is going to be handled, and the
266 * second because it was passed to the ecore_event_handler_add() function when
267 * registering the event handler.
268 *
269 * Another interesting point about this callback is that it returns @ref
270 * ECORE_CALLBACK_DONE (0) if the event data is even, swallowing the event and
271 * don't allowing any other callback to be called after this one for this event.
272 * Otherwise it returns @ref ECORE_CALLBACK_PASS_ON, allowing the event to be
273 * handled by other event handlers registered for this event. This makes the
274 * second event handler be called just for "odd" events.
275 *
276 * @until ECORE_CALLBACK_DONE
277 * @until }
278 *
279 * The second event handler will check if the event data is equal to 5, and if
280 * that's the case, it will change the event handler data of the first event
281 * handler to another string. Then it checks if the event data is higher than
282 * 10, and if so, it will request the main loop to quit.
283 *
284 * An interesting point of this example is that although the second event
285 * handler requests the main loop to finish after the 11th event being received,
286 * it will process all the events that were already fired, and call their
287 * respective event handlers, before the main loop stops. If we didn't want
288 * these event handlers to be called after the 11th event, we would need to
289 * unregister them with ecore_event_handler_del() at this point.
290 *
291 * Now some basic initialization of the context, and the Ecore library itself:
292 *
293 * @until type_new
294 *
295 * This last line is interesting. It creates a new type of event and returns a
296 * unique ID for this event inside Ecore. This ID can be used anywhere else in
297 * your program to reference this specific type of event, and to add callbacks
298 * to it.
299 *
300 * It's common if you are implementing a library that declares new types of
301 * events to export their respective types as extern in the header files. This
302 * way, when the library is initialized and the new type is created, it will be
303 * available through the header file to an application using it add some
304 * callbacks to it. Since our example is self-contained, we are just putting it
305 * as a global variable.
306 *
307 * Now we add some callbacks:
308 *
309 * @until ctxt);
310 *
311 * This is very simple. Just need to call ecore_event_handler_add() with the
312 * respective event type, the callback function to be called, and a data pointer
313 * that will be passed to the callback when it is called by the event.
314 *
315 * Then we start firing events:
316 *
317 * @until }
318 *
319 * This @c for will fire 16 events of this type. Notice that the events will be
320 * fired consecutively, but any callback will be called yet. They are just
321 * called by the main loop, and since it wasn't even started, nothing happens
322 * yet. For each event fired, we allocate an integer that will hold the number
323 * of the event (we are arbitrarily creating these numbers just for
324 * demonstration purposes). It's up to the event creator to decide which type of
325 * information it wants to give to the event handler, and the event handler must
326 * know what is the event info structure for that type of event.
327 *
328 * Since we are not allocating any complex structure, just a simple integer, we
329 * don't need to pass any special free function to ecore_event_add(), and it
330 * will use a simple @c free on our data. That's the default behavior.
331 *
332 * Now finishing our example:
333 *
334 * @until }
335 *
336 * We just start the main loop and watch things happen, waiting to shutdown
337 * Ecore when the main loop exits and return.
338 */
339
340/**
341 * @page ecore_fd_handler_example_c ecore fd handlers - Monitoring file descriptors
342 * @dontinclude ecore_fd_handler_example.c
343 *
344 * This is a very simple example where we will start monitoring the stdin of the
345 * program and, whenever there's something to be read, we call our callback that
346 * will read it.
347 *
348 * Check the full code for this example @ref ecore_fd_handler_example.c "here".
349 *
350 * This seems to be stupid, since a similar result could be achieved by the
351 * following code:
352 *
353 * @code
354 * while (nbytes = read(STDIN_FILENO, buf, sizeof(buf)))
355 * {
356 * buf[nbytes - 1] = '\0';
357 * printf("Read %zd bytes from input: \"%s\"\n", nbytes - 1, buf);
358 * }
359 * @endcode
360 *
361 * However, the above code is blocking, and won't allow you to do anything else
362 * other than reading the input. Of course there are other methods to do a
363 * non-blocking reading, like setting the file descriptor to non-blocking and
364 * keep looping always checking if there's something to be read, and do other
365 * things otherwise. Or use a @c select call to watch for more than one file
366 * descriptor at the same time.
367 *
368 * The advantage of using an @ref Ecore_Fd_Handler is that you can monitor a
369 * file descriptor, while still iterating on the Ecore main loop. It will allow
370 * you to have timers working and expiring, events still being processed when
371 * received, idlers doing its work when there's nothing happening, and whenever
372 * there's something to be read from the file descriptor, your callback will be
373 * called. And it's everything monitored in the same main loop, no threads are
374 * needed, thus reducing the complexity of the program and any overhead caused
375 * by the use of threads.
376 *
377 * Now let's start our program. First we just declare a context structure that
378 * will be passed to our callback, with pointers to our handler and to a timer
379 * that will be used later:
380 *
381 * @until };
382 *
383 * Then we will declare a prepare_callback that is called before any fd_handler
384 * set in the program, and before the main loop select function is called. Just
385 * use one if you really know that you need it. We are just putting it here to
386 * exemplify its usage:
387 *
388 * @until }
389 *
390 * Now, our fd handler. In its arguments, the @c data pointer will have any data
391 * passed to it when it was registered, and the @c handler pointer will contain
392 * the fd handler returned by the ecore_main_fd_handler_add() call. It can be
393 * used, for example, to retrieve which file descriptor triggered this callback,
394 * since it could be added to more than one file descriptor, or to check what
395 * type of activity there's in the file descriptor.
396 *
397 * The code is very simple: we first check if the type of activity was an error.
398 * It probably won't happen with the default input, but could be the case of a
399 * network socket detecting a disconnection. Next, we get the file descriptor
400 * from this handler (as said before, the callback could be added to more than
401 * one file descriptor), and read it since we know that it shouldn't block,
402 * because our fd handler told us that there's some activity on it. If the
403 * result of the read was 0 bytes, we know that it's an end of file (EOF), so we
404 * can finish reading the input. Otherwise we just print the content read from
405 * it:
406 *
407 * @until }
408 *
409 * Also notice that this callback returns @ref ECORE_CALLBACK_RENEW to keep
410 * being called, as almost all other Ecore callbacks, otherwise if it returns
411 * @ref ECORE_CALLBACK_CANCEL then the file handler would be deleted.
412 *
413 * Just to demonstrate that our program isn't blocking in the input read but
414 * still can process other Ecore events, we are going to setup an @ref
415 * Ecore_Timer. This is its callback:
416 *
417 * @until }
418 *
419 * Now in the main code we are going to initialize the library, and setup
420 * callbacks for the file descriptor, the prepare callback, and the timer:
421 *
422 * @until timer_add
423 *
424 * Notice that the use of ecore_main_fd_handler_add() specifies what kind of
425 * activity we are monitoring. In this case, we want to monitor for read (since
426 * it's the standard input) and for errors. This is done by the flags @ref
427 * ECORE_FD_READ and @ref ECORE_FD_ERROR. For the three callbacks we are also
428 * giving a pointer to our context structure, which has pointers to the handlers
429 * added.
430 *
431 * Then we can start the main loop and see everything happening:
432 *
433 * @until }
434 *
435 * In the end we are just deleting the fd handler and the timer to demonstrate
436 * the API usage, since Ecore would already do it for us on its shutdown.
437 */
438
439/**
440 * @page ecore_poller_example_c ecore poller - Repetitive polling tasks
441 * @dontinclude ecore_poller_example.c
442 *
443 * This example show how to setup, and explains how an @ref Ecore_Poller is
444 * called. You can @ref ecore_poller_example.c "see the full source code here".
445 *
446 * In this example we store the initial time of the program just to use as
447 * comparison to the time when the poller callbacks are called. It will be
448 * stored in @c _initial_time :
449 *
450 * @until initial_time
451 *
452 * Then next step is to define the poller callback. This callback assumes that a
453 * @c data pointer is passed to it on creation, and is a string just used to
454 * identify the poller. The callback prints this string and the time since the
455 * program started, and returns @ref ECORE_CALLBACK_RENEW to keep being called.
456 *
457 * @until }
458 *
459 * Now in the main function we initialize Ecore, and save the initial time of
460 * the program, so we can compare it later with the time that the pollers are
461 * being called:
462 *
463 * @until initial_time
464 *
465 * Then we change the poll interval to 0.3 seconds (the default is 0.125
466 * seconds) just to show the API usage.
467 *
468 * Finally, we create two pollers, one that will be called every 4 ticks, and
469 * another one that will be called every 8 ticks. This means the the first
470 * poller interval will be around 1.2 seconds, and the second one will be
471 * around 2.4 seconds. But the most important point is: since the second poller
472 * interval is a multiple of the first one, they will be always synchronized.
473 * Ecore calls pollers that are in the "same tick" together. It doesn't go back
474 * to the main loop and check if there's another poller to execute at this
475 * time, but instead it calls all the pollers registered to this "tick" at the
476 * same time. See the description of ecore_poller_add() for more details. This
477 * is easy to see in the time printed by both of them.
478 *
479 * If instead of two synchronized pollers, we were using two different timers,
480 * one with interval of 1.2 seconds and another one with an interval of 2.4
481 * seconds, there would be no guarantee that they would be totally in sync. Some
482 * delay in the execution of another task, or even in the task called in the
483 * callback, could make them get out of sync, forcing Ecore's main loop to wake
484 * up more than necessary.
485 *
486 * Well, this is the code that create these two pollers and set the poll
487 * interval, then starts the main loop:
488 *
489 * @until ecore_main_loop_begin
490 *
491 * If you hit CTRL-C during the execution of the program, the main loop will
492 * quit, since there are some signal handlers already set by default to do this.
493 * So after the main loop begin call, we change the second poller's interval to
494 * 16 ticks, so it will happen each 4.8 seconds (or each 4 times that the first
495 * poller is called).
496 *
497 * This means: the program is started, the first poller is called each 4 ticks
498 * and the second is called each 8 ticks. After CTRL-C is used, the second
499 * poller will be called each 16 ticks.
500 *
501 * @until }
502 *
503 * The rest of the program is just deleting the pollers and shutting down the
504 * library.
505 */
506
507/**
508 * @page ecore_con_lookup_example_c Ecore_Con - DNS lookup
509 *
510 * This is a very simple example that shows how to make a simple DNS lookup
511 * using ecore_con_lookup().
512 *
513 * It's possible to see in the beginning of the main function that we are using
514 * the arguments passed via command line. This is the address that we are going
515 * to make the DNS lookup on.
516 *
517 * The next step is to initialize the libraries, and just call
518 * ecore_con_lookup(). This function will get the string that contains the
519 * address to be resolved as first parameter, then a callback that will be
520 * called when the resolve stage is done, and finally a data pointer that will
521 * be passed to the callback.
522 *
523 * This function is asynchronous, and the callback will be called only on
524 * success. If there was an error during the resolve stage, there's no way to
525 * know about that. It's only possible to know about errors when setting up the
526 * lookup, by looking at the return code of the ecore_con_lookup() function.
527 *
528 * The callback @c _lookup_done_cb passed as argument to ecore_con_lookup() just
529 * prints the resolved canonical name, IP, address of the sockaddr structure,
530 * and the length of the socket address (in bytes).
531 *
532 * Finally, we start the main loop, and after that we finalize the libraries and
533 * exit.
534 *
535 * This is the code for this simple example:
536 *
537 * @include ecore_con_lookup_example.c
538 */
539
540/**
541 * @page ecore_con_url_download_example_c Ecore_Con_Url - downloading a file
542 *
543 * This is a simple example that shows how to download a file using @ref
544 * Ecore_Con_Url. The full source code for this example can be found at @ref
545 * ecore_con_url_download_example.c.
546 *
547 * First we are setting some callbacks for events that will be sent when data
548 * arrives in our connection (the data is the content of the file being
549 * downloaded), and when the download is completed. The @c _url_progress_cb and
550 * @c _url_complete_cb are these callbacks:
551 *
552 * @dontinclude ecore_con_url_download_example.c
553 * @skip struct
554 * @until main_loop_quit
555 * @until }
556 *
557 * Notice that we also declared a struct that will hold how many bytes were
558 * downloaded through this object. It will be set in the @c main function using
559 * ecore_con_url_data_set().
560 *
561 * In the next step, on the @c main function, we open a file where we are going
562 * to save the content being downloaded:
563 *
564 * @until open(
565 * @until }
566 *
567 * With the file successfully open, let's create our @ref Ecore_Con_Url object.
568 * For this, we initialize the libraries and create the object:
569 *
570 * @until }
571 *
572 * Then we allocate and set the data struct to the connection object, and set a
573 * file descriptor from our previously open file to it. We also add the event
574 * handlers (callbacks) to the events that will be emitted on data being
575 * received and download complete:
576 *
577 * @until complete_cb
578 *
579 * Finally we start our request, and run the main loop:
580 *
581 * @until return 0
582 * @until }
583 *
584 * The rest of this code was just freeing resources, with some labels to be used
585 * for error handling.
586 */
587
588/**
589 * @page ecore_con_url_cookies_example_c Ecore_Con_Url - Managing cookies
590 *
591 * This example shows how to use an @ref Ecore_Con_Url and enable it to
592 * receive/send cookies. These cookies can be set by the server, saved to a
593 * file, loaded later from this file and sent again to the server. The complete
594 * example can be found at @ref ecore_con_url_cookies_example.c
595 * "ecore_con_url_cookies_example.c"
596 *
597 * First we are setting some callbacks for events that will be sent when data
598 * arrives in our connection (the data is the content of the file being
599 * downloaded), and when the download is completed. The @c _url_data_cb and
600 * @c _url_complete_cb are these callbacks:
601 *
602 * @dontinclude ecore_con_url_download_example.c
603 * @skip Eina_Bool
604 * @until main_loop_quit
605 * @until }
606 *
607 * In the @c main function we parse some parameter from the command line. These
608 * parameters are the url that we are connecting to, and cookie use policy.
609 *
610 * After that we initialize the libraries and create a handler to our request
611 * using the given url:
612 *
613 * @until goto end
614 * @until }
615 *
616 * We also set the event handlers for this request and add a header to it, that
617 * will inform our custom user agent:
618 *
619 * @until User-Agent
620 *
621 * Now we start playing with cookies. First, let's call
622 * ecore_con_url_cookies_init() to inform that we want cookies enabled. We also
623 * set a file from which we are loading previously set (old) cookies, in case
624 * that we don't want to clear old cookies or old session cookies.
625 *
626 * After that we set the file where we are going to save all valid cookies in
627 * the @ref Ecore_Con_Url object. This includes previously loaded cookies (that
628 * weren't cleared) and new cookies set by the response header "Set-Cookie" that
629 * comes with the response to our request:
630 *
631 * @until jar_file_set
632 *
633 * And finally, before performing the request, we check the command passed as
634 * argument in the command line and use it to choose between clearing old
635 * cookies, clearing just old session cookies, or ignoring old session cookies.
636 *
637 * After that we just finish our code as expected:
638 *
639 * @until return
640 * @until }
641 *
642 * Notice that in this code, if we want to clear old cookies, we also don't load
643 * them from the file. This is a bit confusing and the API isn't clear, but
644 * ecore_con_url_cookies_file_add() will load cookies from the specified files
645 * just when the operation is really performed (i.e. ecore_con_url_get() is
646 * called). So if ecore_con_url_cookies_clear() is called before
647 * ecore_con_url_get(), the old cookies may not have been loaded yet, so they
648 * are not cleared. To avoid having old cookies loaded, don't add any cookie
649 * file with ecore_con_url_cookies_file_add().
650 *
651 * The function ecore_con_url_cookies_clear() is just useful to clear cookies
652 * that are already loaded/valid in the @ref Ecore_Con_Url object (from a
653 * previous request, for example).
654 */
655
656/**
657 * @page ecore_con_url_headers_example_c Ecore_Con_Url - customizing a request
658 *
659 * This is a simple example that shows how to make a custom request using @ref
660 * Ecore_Con_Url. The full source code for this example can be found at @ref
661 * ecore_con_url_headers_example.c.
662 *
663 * The first part of the example is setting the callbacks to be called when an
664 * #ECORE_CON_EVENT_URL_DATA or #ECORE_CON_EVENT_URL_COMPLETE event is received.
665 * These are the callbacks that are going to be used with this:
666 *
667 * @dontinclude ecore_con_url_headers_example.c
668 * @skip static
669 * @until main_loop_quit
670 * @until }
671 *
672 * The @c main code is as simple as the @ref Ecore_Con_Url example. It contains
673 * some checks for the arguments to see if a GET or POST request is required:
674 *
675 * @until GET
676 * @until }
677 *
678 * Then we start our required libraries and configure a global option to use
679 * pipelined requests:
680 *
681 * @until pipeline_set
682 *
683 * Now we create our request object, but using ecore_con_url_custom_new() to use
684 * a POST or GET method depending on the command line arguments. And we also add
685 * the event handlers for our callbacks:
686 *
687 * @until complete_cb
688 *
689 * In order to demonstrate our API, some options are set to this request before
690 * actually performing it:
691 *
692 * @until url_time
693 *
694 * Depending on what kind of request was asked (GET or POST), we use one of the
695 * specific functions to perform it:
696 *
697 * @until url_post
698 *
699 * After that, we just check for errors, start the main loop, free resources and
700 * finally exit:
701 *
702 * @until return
703 * @until }
704 */
705
706/**
707 * @page ecore_con_server_simple_example_c Ecore_Con - Creating a server
708 *
709 * In this example we are going to create a server that listens for connections
710 * from clients through a TCP port. You can get the full source code at @ref
711 * ecore_con_server_simple_example.c.
712 *
713 * We begin our example in the main function, to demonstrate how to setup
714 * things, and then go to the callbacks that are needed for it to run properly.
715 *
716 * In the @c main function, after initializing the libraries, we use
717 * ecore_con_server_add() to startup the server. Look at the reference
718 * documentation of this function: it supports many types of server, and we are
719 * going to use #ECORE_CON_REMOTE_TCP (a TCP based server). Other arguments to
720 * this function are the address where we are listening on, the port, and a data
721 * pointer that will associate that data with the server:
722 *
723 * @dontinclude ecore_con_server_simple_example.c
724 * @skip main(void)
725 * @until exit
726 *
727 * Notice that we are listening only on 127.0.0.1, which is the internal
728 * loopback interface. If the server needs to listening on all of its ips, use
729 * 0.0.0.0 instead.
730 *
731 * We also need to set event handlers to be called when we receive any data from
732 * the clients, when a new client connects to our server, or when a client
733 * disconnects. These callbacks are:
734 *
735 * @until CLIENT_DATA
736 *
737 * More details about what these callbacks do will be given later.
738 *
739 * Now, before running the main loop, we also want to set some limits to our
740 * server. To avoid it to be overloaded with too many connections to handle, we
741 * are going to set a maximum of 3 clients connected at the same time. This
742 * number is used just to demonstrate the API. A good number to be used here
743 * would need to be determined by tests done on the server, to check the load
744 * supported by it.
745 *
746 * Any other client trying to connect to this server, after the limit is
747 * reached, will wait until one of the connected clients disconnect and the
748 * server accepts the new connection.
749 *
750 * Another important thing to do is setting a timeout, to avoid that a client
751 * hold a connection for too long without doing anything. This timeout will
752 * disconnect the idle client, allowing that other clients that may be waiting
753 * to connect finally can do it.
754 *
755 * Then we just start the main loop:
756 *
757 * @until main_loop_begin
758 *
759 * After exiting the main loop, we print the list of connected clients, and also
760 * free the data associated with each respective client. This data was
761 * previously associated using ecore_con_client_data_set():
762 *
763 * @until }
764 *
765 * Then before exiting we show the total uptime of the server:
766 *
767 * @until uptime
768 *
769 * Now let's go back to the used callbacks.
770 *
771 * The first callback, @c _add, is registered to the event
772 * #ECORE_CON_EVENT_CLIENT_ADD, which will be called whenever a client connects
773 * to the server.
774 *
775 * This callback will associate a data structure to this client, that will be
776 * used to count how many bytes were received from it. It also prints some info
777 * about the client, and send a welcome string to it. ecore_con_client_flush()
778 * is used to ensure that the string is sent immediately, instead of being
779 * buffered.
780 *
781 * A timeout for idle specific for this client is also set, to demonstrate that
782 * it is independent of the general timeout of the server.
783 *
784 * Before exiting, the callback will display a list of all clients still
785 * connected to this server. The code for this callback follows:
786 *
787 * @dontinclude ecore_con_server_simple_example.c
788 * @skip Eina_Bool
789 * @until CALLBACK_RENEW
790 * @until }
791 *
792 * The second callback is @c _del. It is associated with
793 * #ECORE_CON_EVENT_CLIENT_DEL, and is called whenever a client disconnects from
794 * this server.
795 *
796 * It will just print some information about the client, free the associated
797 * data structure, and call ecore_con_client_del() on it before exiting the
798 * callback. Here's its code:
799 *
800 * @until CALLBACK_RENEW
801 * @until }
802 *
803 * The last callback will print any data received by this server from its
804 * clients. It also increments the "bytes received" counter, sdata, in the
805 * data structure associated with this client. The callback code follows:
806 *
807 * @until CALLBACK_RENEW
808 * @until }
809 *
810 * The important parts of this example were described above. If you need to see
811 * the full source code for it, there's a link to the code in the beginning of
812 * this page.
813 *
814 * This example will start a server and start accepting connections from clients, as
815 * demonstrated in the following diagram:
816 * @htmlonly
817 * <img src="ecore_con-client-server-example.png" style="max-width: 400px"/>
818 * <a href="ecore_con-client-server-example.png">Full size</a>
819 * @endhtmlonly
820 *
821 * @image rtf ecore_con-client-server-example.png
822 * @image latex ecore_con-client-server-example.eps width=\textwidth
823 *
824 * @note This example contains a serious security flaw: it doesn't check for the
825 * size of data being received, thus allowing to the string to be exploited in
826 * some way. However, it is left like this to make the code simpler and just
827 * demonstrate the API usage.
828 */
829
830/**
831 * @page ecore_con_client_simple_example_c Ecore_Con - Creating a client
832 *
833 * Following the same idea as the @ref ecore_con_server_simple_example_c , this
834 * example will demonstrate how to create a client that connects to a specified
835 * server through a TCP port. You can see the full source code at @ref
836 * ecore_con_client_simple_example.c.
837 *
838 * Starting from the @c main function, after reading the command line argument
839 * list and initializing the libraries, we try to connect to the server:
840 *
841 * @dontinclude ecore_con_client_simple_example.c
842 * @skip main(
843 * @until exit(2)
844 * @until }
845 *
846 * After doing this, everything else in @c main is setting up callbacks for the
847 * client events, starting the main loop and shutting down the libraries after
848 * it.
849 *
850 * Now let's go to the callbacks. These callbacks are very similar to the server
851 * callbacks (our implementation for this example is very simple). On the
852 * @c _add callback, we just set a data structure to the server, print some
853 * information about the server, and send a welcome message to it:
854 *
855 * @dontinclude ecore_con_client_simple_example.c
856 * @skip Eina_Bool
857 * @until CALLBACK_RENEW
858 * @until }
859 *
860 * The @c _del callback is as simple as the previous one. We free the data
861 * associated with the server, print the uptime of this client, and quit the
862 * main loop (since there's nothing to do once we disconnect):
863 *
864 * @until CALLBACK_RENEW
865 * @until }
866 *
867 * The @c _data callback is also similar to the server data callback. it will
868 * print any received data, and increase the data counter in the structure
869 * associated with this server:
870 *
871 * @skip Eina_Bool
872 * @until CALLBACK_RENEW
873 * @until }
874 *
875 * You can see the server counterpart functions of the ones used in this example
876 * in the @ref ecore_con_server_simple_example_c.
877 *
878 * This example will connect to the server and start comunicating with it, as
879 * demonstrated in the following diagram:
880 * @htmlonly
881 * <img src="ecore_con-client-server-example2.png" style="max-width: 400px"/>
882 * <a href="ecore_con-client-server-example2.png">Full size</a>
883 * @endhtmlonly
884 *
885 * @image rtf ecore_con-client-server-example2.png
886 * @image latex ecore_con-client-server-example2.eps width=\textwidth
887 *
888 * @note This example contains a serious security flaw: it doesn't check for the
889 * size of data being received, thus allowing to the string to be exploited in
890 * some way. However, it is left like this to make the code simpler and just
891 * demonstrate the API usage.
892 */
893
894/**
895 * @example ecore_idler_example.c
896 * This example shows when @ref Ecore_Idler, @ref Ecore_Idle_Enterer and @ref
897 * Ecore_Idle_Exiter are called. See
898 * @ref ecore_idler_example_c "the explanation here".
899 */
900
901/**
902 * @example ecore_job_example.c
903 * This example shows how to use an @ref Ecore_Job. See
904 * @ref ecore_job_example_c "the explanation here".
905 */
906
907/**
908 * @example ecore_time_functions_example.c
909 * Shows the difference between the three time functions. See @ref
910 * ecore_time_functions_example_c "the example explained".
911 */
912
913/**
914 * @example ecore_timer_example.c
915 * This example show how to use timers to have timed events inside ecore.
916 * See @ref ecore_timer_example_c "the example explained".
917 */
918
919/**
920 * @example ecore_exe_example_child.c
921 * This is a child process used to receive messages and send it back
922 * to its father.
923 * Check the @ref Ecore_exe_simple_example_c "Full tutorial"
924 */
925
926/**
927 * @example ecore_exe_example.c
928 * This is a process that will send messages to a child and it will stop
929 * when it receives "quit".
930 * Check the @ref Ecore_exe_simple_example_c "Full tutorial"
931 */
932
933/**
934 * @example ecore_fd_handler_example.c
935 * This example shows how to setup and use an fd_handler. See
936 * @ref ecore_fd_handler_example_c "the explanation here".
937 */
938
939/**
940 * @example ecore_poller_example.c
941 * This example shows how to setup and use a poller. See
942 * @ref ecore_poller_example_c "the explanation here".
943 */
944
945/**
946 * @example ecore_event_example_01.c
947 * This example shows how to create an event handler. Explanation: @ref
948 * ecore_event_example_01_c
949 */
950
951/**
952 * @example ecore_event_example_02.c
953 * This example shows how to setup, change, and delete event handlers. See
954 * @ref ecore_event_example_02_c "the explanation here".
955 */
956
957/**
958 * @example ecore_fd_handler_gnutls_example.c
959 * Shows how to use fd handlers.
960 */
961
962/**
963 * @example ecore_con_lookup_example.c
964 * Shows how to make a simple DNS lookup. See the complete example description
965 * at @ref ecore_con_lookup_example_c
966 */
967
968/**
969 * @example ecore_con_url_download_example.c
970 * Shows how to download a file using an @ref Ecore_Con_Url object. See the
971 * complete example description at @ref ecore_con_url_download_example_c
972 */
973
974/**
975 * @example ecore_con_url_cookies_example.c
976 * Shows how to manage cookies on a @ref Ecore_Con_Url object. See the complete
977 * example description at @ref ecore_con_url_cookies_example_c.
978 */
979
980/**
981 * @example ecore_con_server_simple_example.c
982 * Shows how to setup a simple server that accepts client connections and sends
983 * a "hello" string to them. See the complete example description at @ref
984 * ecore_con_server_simple_example_c
985 */
986
987/**
988 * @example ecore_con_client_simple_example.c
989 * Shows how to setup a simple client that connects to a server and sends a
990 * "hello" string to it. See the complete example description at @ref
991 * ecore_con_client_simple_example_c
992 */
993
994/**
995 * @example ecore_con_url_headers_example.c
996 * Shows how to make GET or POST requests using an @ref Ecore_Con_Url object,
997 * and make use of most of its API. See the complete example description at
998 * @ref ecore_con_url_headers_example_c
999 */
1000
1001/**
1002 * @page tutorial_ecore_pipe_gstreamer_example
1003 *
1004 * Here is an example that uses the pipe wrapper with a Gstreamer
1005 * pipeline. For each decoded frame in the Gstreamer thread, a handle
1006 * is called in the ecore thread.
1007 *
1008 * @include ecore_pipe_gstreamer_example.c
1009 * @example ecore_pipe_gstreamer_example.c
1010 */
1011
1012/**
1013 * @page tutorial_ecore_pipe_simple_example
1014 * @dontinclude ecore_pipe_simple_example.c
1015 *
1016 * This example shows some simple usage of ecore_pipe. We are going to create a
1017 * pipe, fork our process, and then the child is going to communicate to the
1018 * parent the result of its processing through the pipe.
1019 *
1020 * As always we start with our includes, nothing special:
1021 * @skip #include
1022 * @until Ecore.h
1023 *
1024 * The first thing we are going to define in our example is the function we are
1025 * going to run on the child process, which, as mentioned, will do some
1026 * processing and then will write the result to the pipe:
1027 * @until }
1028 * @until }
1029 * @note The sleep was added so the parent process would think the child process
1030 * was doing something interesting...
1031 *
1032 * Next up is our function for handling data arriving in the pipe. It copies the
1033 * data to another buffer, adds a terminating NULL and prints it. Also if it
1034 * receives a certain string it stops the main loop(effectively ending the
1035 * program):
1036 * @until }
1037 * @until }
1038 *
1039 * And now on to our main function, we start by declaring some variables and
1040 * initializing ecore:
1041 * @until ecore_init
1042 *
1043 * And since we are talking about pipes let's create one:
1044 * @until pipe_add
1045 *
1046 * Now we are going to fork:
1047 * @until fork
1048 * @note duh...
1049 *
1050 * The child process is going to do the our fancy processing:
1051 * @until }
1052 * @note It's very important to call ecore_pipe_read_close() here so that the
1053 * child process won't read what it is writing to the pipe itself.
1054 *
1055 * And the parent is going to run ecore's main loop waiting for some data:
1056 * @until }
1057 * @note Calling ecore_pipe_write_close() here isn't important but since we
1058 * aren't going to write in the pipe it is good practice.
1059 *
1060 * And finally when done processing(the child) or done receiving(the parent) we
1061 * delete the pipe and shutdown ecore:
1062 * @until }
1063 *
1064 * @example ecore_pipe_simple_example.c
1065 */
1066
1067/**
1068 * @page tutorial_ecore_animator Ecore animator example
1069 * @dontinclude ecore_animator_example.c
1070 *
1071 * For this example we are going to animate a rectangle growing, moving and
1072 * changing color, and then move it back to it's initial state with a
1073 * different animation. We are also going to have a second rectangle moving
1074 * along the bottom of the screen. To do this we are going to use ecore_evas,
1075 * but since that is not the focus here we won't going into detail about it.
1076 *
1077 * @skip #include
1078 * @until evas_object_show
1079 * @until evas_object_show
1080 * All of this is just setup, not what we're interested in right now.
1081 *
1082 * Now we are going to set the frametime for our animation to one fiftieth of
1083 * a second, this will make our program consume more resources but should make
1084 * our animation extra smooth:
1085 * @until frametime
1086 *
1087 * And now we get right to the business of creating our ecore_animator:
1088 * @until timeline
1089 * @note We are telling our animation to last 10 second and to call
1090 * _advance_frame with rect as data.
1091 *
1092 * So far we setup the first and second animations, the third one however is a
1093 * bit different, this time we won't use a timeline animation, that's because we
1094 * don't want our animation to stop:
1095 * @until animator_add
1096 *
1097 * Next we set a few timers to execute _start_second_anim, _freeze_third_anim
1098 * and _thaw_thir_anim in 10, 5 and 10 seconds respectively:
1099 * @until thaw
1100 *
1101 * And now we tell ecore to begin the main loop and free some resources once
1102 * it leaves the main loop:
1103 * @until }
1104 *
1105 * Here we have the callback function for our first animation, which first
1106 * takes @p pos(where in the timeline we are), maps it to a SPRING curve that
1107 * which will wobble 15 times and will decay by a factor of 1.2:
1108 * @until pos_map
1109 *
1110 * Now that we have the frame we can adjust the rectangle to its appropriate
1111 * state:
1112 * @until }
1113 *
1114 * And now the callback that will run 10 seconds after the program starts(5
1115 * seconds after the first animation finishes) and starts our second
1116 * animation:
1117 * @until }
1118 * @note For this animation we made the frametime much larger which means our
1119 * animation might get "jerky".
1120 *
1121 * The callback for our second animation, our savvy reader no doubt noted that
1122 * it's very similar to the callback for the first animation. What we change for
1123 * this one is the type of animation to BOUNCE and the number of times it will
1124 * bounce to 50:
1125 * @until }
1126 *
1127 * And for our last animation callback something simpler, we just move our
1128 * rectangle right by one pixel until it reaches the end of the screen and then
1129 * start at the beginning again:
1130 * @until }
1131 *
1132 * Our next two functions respectively freezes and thaw our third animation, so
1133 * that it won't happen for the 5 seconds after the first animation ends and the
1134 * second animation begins:
1135 * @until }
1136 * @until }
1137 *
1138 * @example ecore_animator_example.c
1139 */
1140
1141/**
1142 * @page ecore_thread_example_c Ecore_Thread - API overview
1143 *
1144 * Working with threads is hard. Ecore helps to do so a bit easier, but as
1145 * the example in @ref ecore_thread_example.c "ecore_thread_example.c" shows,
1146 * there's a lot to consider even when doing the most simple things.
1147 *
1148 * We'll be going through this thorough example now, showing how the differents
1149 * aspects of @ref Ecore_Thread are used, but users are encourage to avoid
1150 * threads unless it's really the only option, as they always add more
1151 * complexity than the program usually requires.
1152 *
1153 * Ecore Threads come in two flavors, short jobs and feedback jobs. Short jobs
1154 * just run the given function and are more commonly used for small tasks
1155 * where the main loop does not need to know how the work is going in between.
1156 * The short job in our example is so short we had to artificially enlarge it
1157 * with @c sleep(). Other than that, it also uses threads local data to keep
1158 * the data we are working with persistent across different jobs ran by the
1159 * same system thread. This data will be freed when the no more jobs are
1160 * pending and the thread is terminated. If the data doesn't exist in the
1161 * thread's storage, we create it and save it there for future jobs to find
1162 * it. If creation fails, we cancel ourselves, so the main loop knows that
1163 * we didn't just exit normally, meaning the job could not be done. The main
1164 * part of the function checks in each iteration if it was canceled by the
1165 * main loop, and if it was, it stops processing and clears the data from the
1166 * storage (we assume @c cancel means no one else will need this, but this is
1167 * really application dependent).
1168 * @dontinclude ecore_thread_example.c
1169 * @skip static void
1170 * @until sleep(1)
1171 * @until }
1172 * @until }
1173 *
1174 * Feedback jobs, on the other hand, run tasks that will inform back to the
1175 * main loop its progress, send partial data as is processed, just ping saying
1176 * it's still alive and processing, or anything that needs the thread to talk
1177 * back to the main loop.
1178 * @skip static void
1179 * @until the_end
1180 * @until }
1181 *
1182 * Finally, one more feedback job, but this one will be running outside of
1183 * Ecore's pool, so we can use the pool for real work and keep this very
1184 * light function unchecked. All it does is check if some condition is met
1185 * and send a message to the main loop telling it it's time to close.
1186 * @skip static void
1187 * @until }
1188 * @until }
1189 * @until }
1190 *
1191 * Every now and then the program prints its status, counting threads running
1192 * and pending jobs.
1193 * @skip static void
1194 * @until }
1195 *
1196 * In our main loop, we'll be receiving messages from our feedback jobs using
1197 * the same callback for both of them.
1198 * @skip static void
1199 * @until char *str
1200 *
1201 * The light job running out of the pool will let us know when we can exit our
1202 * program.
1203 * @until }
1204 *
1205 * Next comes the handling of data sent from the actual worker threads, always
1206 * remembering that the data belongs to us now, and not the thread, so it's
1207 * our responsibility to free it.
1208 * @until }
1209 * @until }
1210 *
1211 * Last, the condition to exit is given by how many messages we want to handle,
1212 * so we need to count them and inform the condition checking thread that the
1213 * value changed.
1214 * @until }
1215 *
1216 * When a thread finishes its job or gets canceled, the main loop is notified
1217 * through the callbacks set when creating the task. In this case, we just
1218 * print what happen and keep track of one of them used to exemplify canceling.
1219 * Here we are pretending one of our short jobs has a timeout, so if it doesn't
1220 * finish before a timer is triggered, it will be canceled.
1221 * @skip static void
1222 * @until _cancel_timer_cb
1223 * @until }
1224 *
1225 * The main function does some setup that includes reading parameters from
1226 * the command line to change its behaviour and test different results.
1227 * These are:
1228 * @li -t \<some_num\> maximum number of threads to run at the same time.
1229 * @li -p \<some_path\> adds @c some_path to the list used by the feedback jobs.
1230 * This parameter can be used multiple times.
1231 * @li -m \<some_num\> the number of messages to process before the program is
1232 * signalled to exit.
1233 *
1234 * Skipping some bits, we init Ecore and our application data.
1235 * @skip ecore_init
1236 * @until appdata.max_msgs
1237 *
1238 * If any paths for the feedback jobs were given, we use them, otherwise we
1239 * fallback to some defaults. Always initializing the proper mutexes used by the
1240 * threaded job.
1241 * @skip path_list
1242 * @until EINA_LIST_FREE
1243 * @until }
1244 * @until }
1245 *
1246 * Initialize the mutex needed for the condition checking thread
1247 * @skip appdata.mutex
1248 * @until appdata.condition
1249 *
1250 * And start our tasks.
1251 * @until appdata.thread_3
1252 * @until EINA_FALSE
1253 *
1254 * To finalize, set a timer to cancel one of the tasks if it doesn't end
1255 * before the timeout, one more timer for status report and get into the main
1256 * loop. Once we are out, destroy our mutexes and finish the program.
1257 * @until _status_timer_cb
1258 * @until }
1259 *
1260 * @example ecore_thread_example.c
1261 */
1262
1263/**
1264 * @page ecore_evas_callbacks_example_c Ecore Evas Callbacks
1265 * @dontinclude ecore_evas_callbacks.c
1266 *
1267 * Our example is remarkably simple, all it does is create an Ecore_Evas and
1268 * register a callback for a bunch of events. What's interesting here is
1269 * knowing when each of these callbacks will be called, however since that
1270 * depends on the underlying windowing system there are no guarantees that all
1271 * of the callbacks will be called for your windowing system. To know which
1272 * callbacks will be called for your windowing system run the example and
1273 * redirect the output to a file, and take a look at it.
1274 *
1275 * @note Make sure you minimize, resize, give and remove focus to see more
1276 * callbacks called.
1277 *
1278 * The example is constituted of two main parts, first is the implementation of
1279 * callbacks that will be called for each event(all our callbacks do is print
1280 * their own name) and the second is the main function where we register the
1281 * event callbacks and run the main loop:
1282 * @include ecore_evas_callbacks.c
1283 * @example ecore_evas_callbacks.c
1284 */
1285
1286/**
1287 * @page Ecore_Evas_Window_Sizes_Example_c Ecore_Evas window size hints
1288 *
1289 * On this example, we show you how to deal with @c Ecore_Evas window
1290 * size hints, which are implemented <b>per Evas engine</b>.
1291 *
1292 * We start by defining an initial size for our window and, after
1293 * creating it, adding a background white rectangle and a text object
1294 * to it, to be used to display the current window's sizes, at any
1295 * given time:
1296 * @dontinclude ecore_evas_window_sizes_example.c
1297 * @skip define WIDTH
1298 * @until define
1299 * @until define
1300 * @dontinclude ecore_evas_window_sizes_example.c
1301 * @skip evas_init
1302 * @until show(bg)
1303 * @dontinclude ecore_evas_window_sizes_example.c
1304 * @skip text =
1305 * @until main_loop_begin
1306 * @dontinclude ecore_evas_window_sizes_example.c
1307 * @skip to inform
1308 * @until }
1309 *
1310 * The program has a command line interface, responding to the
1311 * following keys:
1312 * @dontinclude ecore_evas_window_sizes_example.c
1313 * @skip commands
1314 * @until ;
1315 *
1316 * Use the @c 'm' key to impose a minimum size of half the initial
1317 * ones on our window. Test it by trying to resize it to smaller sizes
1318 * than that:
1319 * @dontinclude ecore_evas_window_sizes_example.c
1320 * @skip keyname, "m"
1321 * @until }
1322 * @until }
1323 * @until }
1324 *
1325 * The @c 'x' key will, in turn, set a maximum size on our window --
1326 * to two times our initial size. Test it by trying to resize the
1327 * window to bigger sizes than that:
1328 * @dontinclude ecore_evas_window_sizes_example.c
1329 * @skip keyname, "x"
1330 * @until }
1331 * @until }
1332 * @until }
1333 *
1334 * Window base sizes will override any minimum sizes set, so try it
1335 * with the @c 'b' key. It will set a base size of two times the
1336 * initial one:
1337 * @dontinclude ecore_evas_window_sizes_example.c
1338 * @skip keyname, "b"
1339 * @until }
1340 * @until }
1341 * @until }
1342 *
1343 * Finally, there's a key to impose a "step size" on our window, of 40
1344 * pixels. With than on (@c 's' key), you'll see the window will
1345 * always be bound to @b multiples of that size, for dimensions on
1346 * both axis:
1347 * @skip keyname, "s"
1348 * @until }
1349 * @until }
1350 * @until }
1351 *
1352 * The full example follows.
1353 *
1354 * @include ecore_evas_window_sizes_example.c
1355 * @example ecore_evas_window_sizes_example.c
1356 */
1357
1358/**
1359 * @page ecore_evas_object_example_c Ecore Evas Object example
1360 * @dontinclude ecore_evas_object_example.c
1361 *
1362 * This example creates an Ecore_Evas(a window) and associates a background and
1363 * a custom cursor for it.
1364 *
1365 * We'll start looking at the association, which is quite simple. We choose to
1366 * associate using ECORE_EVAS_OBJECT_ASSOCIATE_BASE to have it be resized with
1367 * the window, since for a background that is what's most useful:
1368 * @skipline ecore_evas_object_associate
1369 * @note If we didn't associate the background we'd need to listen to resize of
1370 * Ecore_Evas and manually resize the background or have artifacts on our
1371 * window.
1372 *
1373 * We then check that the association worked:
1374 * @until printf
1375 *
1376 * Next we are going to set a custom cursor, for our cursor we are going to use
1377 * a small green rectangle. Our cursor is going to be on layer 0(any lower and
1378 * it would be below the background and thus invisible) and clicks will be
1379 * computed as happening on pixel 1, 1 of the image:
1380 * @until cursor_set
1381 *
1382 * We then check every one of those parameters:
1383 * @until printf
1384 *
1385 * Here you have the full-source of the code:
1386 * @include ecore_evas_object_example.c
1387 * @example ecore_evas_object_example.c
1388 */
1389
1390/**
1391 * @page ecore_evas_basics_example_c Ecore Evas basics example
1392 * @dontinclude ecore_evas_basics_example.c
1393 *
1394 * This example will illustrates the usage of some basic Ecore_Evas functions.
1395 * This example will list the available evas engines, check which one we used to
1396 * create our window and set some data on our Ecore_Evas. It also allows you to
1397 * hide/show all windows in this process(we only have one, but if there were
1398 * more they would be hidden), to hide the windows type 'h' and hit return, to
1399 * show them, type 's' and hit return.
1400 *
1401 * The very first thing we'll do is initialize ecore_evas:
1402 * @skipline evas_init
1403 * @until return 1
1404 *
1405 * Once inited we query which engines are available:
1406 * @until ecore_evas_engines_free
1407 *
1408 * We then create an Ecore_Evas(window) with the first available engine, on
1409 * position 0,0 with size 200,200 and no especial flags, set it's title and show
1410 * it:
1411 * @until evas_show
1412 *
1413 * We now add some important data to our Ecore_Evas:
1414 * @until data_set
1415 *
1416 * And since our data is dynamically allocated we'll need to free it when the
1417 * Ecore_Evas dies:
1418 * @until delete_request
1419 * @dontinclude ecore_evas_basics_example.c
1420 * @skip static void
1421 * @until }
1422 * @skip printf("Using
1423 *
1424 * We now print which Evas engine is being used for our example:
1425 * @until printf
1426 *
1427 * We are going to add a background to our window but before we can do that
1428 * we'll need to get the canvas(Evas) on which to draw it:
1429 * @until canvas
1430 *
1431 * We then do a sanity check, verifying if the Ecore_Evas of the Evas is the
1432 * Ecore_Evas from which we got the Evas:
1433 * @until printf
1434 *
1435 * Now we can actually add the background:
1436 * @until ecore_evas_object_associate
1437 *
1438 * To hide and show the windows of this process when the user presses 'h' and
1439 * 's' respectively we need to know when the user types something, so we
1440 * register a callback for when we can read something from @c stdin:
1441 * @until )
1442 *
1443 * The callback that actually does the hiding and showing is pretty simple, it
1444 * does a @c scanf(which we know won't block since there is something to read on
1445 * @c stdin) and if the character is an 'h' we iterate over all windows calling
1446 * @c ecore_evas_hide on them, if the character is an 's' we call @c
1447 * ecore_evas_show instead:
1448 * @dontinclude ecore_evas_basics_example.c
1449 * @skip static Eina_Bool
1450 * @until }
1451 * @skip ecore_main_loop_begin
1452 *
1453 * Once all is done we run our main loop, and when that is done(application is
1454 * exiting) we free our Ecore_Evas and shutdown the ecore_evas subsystem:
1455 * @until shutdown
1456 *
1457 * Here you have the full-source of the code:
1458 * @include ecore_evas_basics_example.c
1459 * @example ecore_evas_basics_example.c
1460 */
1461
1462/**
1463 * @page Ecore_Evas_Buffer_Example_01_c Ecore_Evas buffer example
1464 *
1465 * Between the Evas examples, there is one in which one creates a
1466 * canvas bound to the Evas @b buffer engine and uses its pixel
1467 * contents to create an PPM image on disk. There, one does that by
1468 * creating the canvas "by hand", with @c evas_new(), @c
1469 * evas_engine_info_set(), etc.
1470 *
1471 * On this example, we accomplish the very same task, but by using the
1472 * @c Ecore_Evas helper wrapper functions on a buffer engine
1473 * canvas. If you compare both codes, you'll see how much code one is
1474 * saved from by using the @c Ecore_Evas wrapper functions.
1475 *
1476 * The code is simple as it can be. After instantianting our canvas
1477 * window, with ecore_evas_buffer_new(), we grab its canvas pointer
1478 * and create the desired objects scene on it, which in this case is
1479 * formed by 3 rectangles over the top left corner of a white
1480 * background:
1481 * @dontinclude ecore_evas_buffer_example_01.c
1482 * @skip main(void)
1483 * @until show(r3)
1484 *
1485 * Since it's a buffer canvas and we're using it to only save its
1486 * contents on a file, we even needn't ecore_evas_show() it. We make
1487 * it render itself, forcefully, without the aid of Ecore's main loop,
1488 * with ecore_evas_manual_render():
1489 * @dontinclude ecore_evas_buffer_example_01.c
1490 * @skip manual_render
1491 * @until manual_render
1492 *
1493 * And we're ready to save the window's shiny rendered contents as a
1494 * simple PPM image. We do so by grabbing the pixels of the @c
1495 * Ecore_Evas' internal canvas, with ecore_evas_buffer_pixels_get():
1496 * @dontinclude ecore_evas_buffer_example_01.c
1497 * @skip _scene_save
1498 * @until }
1499 * @dontinclude ecore_evas_buffer_example_01.c
1500 * @skip support function
1501 * @until }
1502 * @until }
1503 * @until }
1504 *
1505 * Check that destination file for the result. The full example
1506 * follows.
1507 *
1508 * @include ecore_evas_buffer_example_01.c
1509 * @example ecore_evas_buffer_example_01.c
1510 */
1511
1512/**
1513 * @page Ecore_Evas_Buffer_Example_02_c Ecore_Evas (image) buffer example
1514 *
1515 * In this example, we'll demonstrate the use of
1516 * ecore_evas_object_image_new(). The idea is to have the same scene
1517 * created for @ref Ecore_Evas_Buffer_Example_01_c as the contents of
1518 * an image object.
1519 *
1520 * The canvas receiving this image object will have a white
1521 * background, a red border image to delimit this image's boundaries
1522 * and the image itself. After we create the special image, we set
1523 * its "fill" property, place and resize it as we want. We have also
1524 * to resize its underlying @c Ecore_Evas too, to the same dimensions:
1525 * @dontinclude ecore_evas_buffer_example_02.c
1526 * @skip object_image_new
1527 * @until resize(sub_ee
1528 *
1529 * Now, we re-create the scene we cited, using the sub-canvas of our
1530 * image to parent the objects in question. Because image objects are
1531 * created with the alpha channel enabled, by default, we'll be seeing
1532 * our white rectangle beneath the scene:
1533 * @dontinclude ecore_evas_buffer_example_02.c
1534 * @skip rectangle_add(sub_canvas
1535 * @until loop_begin
1536 *
1537 * And that's all. The contents of our image could be updated as one
1538 * wished, and they would always be mirrored in the image's area.
1539 *
1540 * Check that destination file for the result. The full example
1541 * follows.
1542 *
1543 * @include ecore_evas_buffer_example_02.c
1544 * @example ecore_evas_buffer_example_02.c
1545 */
1546
1547/**
1548 * @page Ecore_exe_simple_example_c Ecore_exe
1549 * Creating a processes and IPC (Inter process communication)
1550 *
1551 * In this example we will show how to create a new process and communicate
1552 * with it in a portable way using the Ecore_exe module.
1553 *
1554 * In this example we will have two process and both will communicate with each
1555 * other using messages. A father process will start a child process and it will
1556 * keep sending messages to the child until it receives a message to quit.
1557 * To see the full source use the links:
1558 * @li @ref ecore_exe_example.c "Father"
1559 * @li @ref ecore_exe_example_child.c "Child"
1560 *
1561 * Let's start the tutorial. The implementation of the child it's pretty simple.
1562 * We just read strings from stdin and write a message in the stdout. But you
1563 * should be asking yourself right know. "If I'm receiving data from an other
1564 * process why I'm reading and writing in stdin/stdout?". That's because, when
1565 * you spawn a process using the Ecore_Exe module it will create a pipe between
1566 * the father and the child process and the stdin/stdout of the child process
1567 * will be redirected to the pipe. So when the child wants to receive or send
1568 * data to the father, just use the stdin/stdout.
1569 * However the steps to send data from the father to the child is quite
1570 * different, but we will get there.
1571 *
1572 * The child will register a fd handler to monitor the stdin.
1573 * So we start registering the ecore FD handler:
1574 * @dontinclude ecore_exe_example_child.c
1575 * @skip ecore_main_fd_handler_add
1576 * @until ;
1577 *
1578 * If you don't remenber the parameters of @ref ecore_main_fd_handler_add,
1579 * please check its documentation.
1580 *
1581 * Now that we have our handler registered we will start the ecore's main loop:
1582 * @skipline ecore_main_loop_begin
1583 *
1584 * Now let's take a look in the callback function. Its a simple function
1585 * that will read from stdin 3 times and at the third time will say
1586 * to the father: "quit".
1587 * @dontinclude ecore_exe_example_child.c
1588 * @skip static Eina_Bool
1589 * @until }
1590 * @until }
1591 * @until }
1592 * @until }
1593 *
1594 * You may notice that we are sending the messages to stdout, and our father
1595 * will receive it. Also our string must have a "\n" because the string will
1596 * be buffered in the pipe until it finds EOF or a "newline" in our case we
1597 * won't have a EOF unless we close the pipe, so we use the "\n" char.
1598 *
1599 * One more thing, we use fflush(stdout) because probably our message won't
1600 * fill our entire buffer and the father would never receive the message. So we
1601 * use this function to flush the buffer and the father can receive as fast as
1602 * possible.
1603 *
1604 * Now that we have our child ready, let's start our work in the father's source
1605 * code.
1606 *
1607 * We start creating the child process like this:
1608 * @dontinclude ecore_exe_example.c
1609 * @skip childHandle = ecore_exe_pipe_run
1610 * @until ;
1611 *
1612 * With the command above we are creating our child process, the first
1613 * parameter is the command to be executed, the second are the pipe flags and
1614 * in our case we will write and read in the pipe so we must say what we are
1615 * doing in the pipe. You may notice the flag ECORE_EXE_PIPE_READ_LINE_BUFFERED,
1616 * this means that reads are buffered until I find a newline. And the third
1617 * parameter is data that we would like to send to the process in its creating.
1618 * This case we are sending nothing, so just use NULL.
1619 *
1620 * Then we check if the process was created:
1621 * @skip if
1622 * @until }
1623 *
1624 * After this we get the PID of the child process and just print it in the screen.
1625 * The PID stands for Process identification. This is just an internal
1626 * identifier of your process:
1627 *
1628 * @skip childPid
1629 * @until fprintf
1630 * @until fprintf
1631 *
1632 * The way that Ecore_exe works is: when we want to read data sent from
1633 * our child we must use an ecore event.
1634 * So let's start register our event listener:
1635 * @skipline ecore_event_handler_add
1636 *
1637 * Now to send messages to our child we will use a timer, so every 1 second we
1638 * will send a message to the child.
1639 * @skipline ecore_timer_add
1640 *
1641 * After all this we start the main loop. Now let's pass to the callback
1642 * functions.
1643 *
1644 * Now we will see how we actually send the data and receive it.
1645 * Let's start with _sendMessage:
1646 * @dontinclude ecore_exe_example.c
1647 * @skip _sendMessage(void *data)
1648 * @until }
1649 *
1650 * We use ecore_exe_send to send data to the child process, it's pretty simple.
1651 * To know what the parameters stands for, check the docs.
1652 *
1653 * @note The function @b ecore_exe_send will never block your program, also
1654 * there is no partial send of the data. This means either the function will
1655 * send all the data or it will fail.
1656 *
1657 * Now let's take a look in our event callback and see how we retrieve the
1658 * messages.
1659 * @dontinclude ecore_exe_example.c
1660 * @skip static Eina_Bool
1661 * @until }
1662 * @until }
1663 *
1664 * It's just like an normal event, we get a reference to Ecore_Exe_Event_Data,
1665 * extract the data and then show it in the screen.
1666 *
1667 * And that's it, after all it's not complicated to create a process and
1668 * communicate with it.
1669 *
1670 */
1671
1672/**
1673 * @page ecore_imf_example_c ecore_imf - How to handle preedit and commit string from Input Method Framework
1674 *
1675 * This example demonstrates how to connect input method framework and handle preedit and commit string from input method framework.
1676 *
1677 * To input Chinese, Japanese, Korean and other complex languages, the editor should be connected with input method framework.
1678 *
1679 * How to initialize and shutdown ecore imf module
1680 * @li ecore_imf_init() should be called to initialize and load immodule.
1681 * @li ecore_imf_shutdown() is used for shutdowning and unloading immodule.
1682 *
1683 * How to create input context and register pre-edit and commit event handler
1684 *
1685 * Each entry should have each input context to connect with input service framework.
1686 * Key event is processed by input method engine.
1687 * The result is notified to application through ECORE_IMF_CALLBACK_PREEDIT_CHANGED and ECORE_IMF_CALLBACK_COMMIT event.
1688 *
1689 * The full example follows.
1690 *
1691 * @include ecore_imf_example.c
1692 */