summaryrefslogtreecommitdiff
path: root/doc
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
parent6ecaa33f2265b7ba0060ffcdc93e96366a49e886 (diff)
efl: Adding *.dox files from various libs.
SVN revision: 81274
Diffstat (limited to 'doc')
-rw-r--r--doc/Doxyfile.in7
-rw-r--r--doc/ecore_examples.dox1692
-rw-r--r--doc/eet_examples.dox184
-rw-r--r--doc/eio.dox.in456
-rw-r--r--doc/evas_examples.dox1073
5 files changed, 3411 insertions, 1 deletions
diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
index c89b7de306..016ca76947 100644
--- a/doc/Doxyfile.in
+++ b/doc/Doxyfile.in
@@ -592,7 +592,12 @@ WARN_LOGFILE =
592# directories like "/usr/src/myproject". Separate the files or directories 592# directories like "/usr/src/myproject". Separate the files or directories
593# with spaces. 593# with spaces.
594 594
595INPUT = @top_srcdir@/src/lib @srcdir@/main.dox 595INPUT = @top_srcdir@/src/lib \
596 @srcdir@/main.dox \
597 @srcdir@/ecore_examples.dox \
598 @srcdir@/eet_examples.dox \
599 @srcdir@/evas_examples.dox \
600 @builddir@/eio.dox
596 601
597# This tag can be used to specify the character encoding of the source files 602# This tag can be used to specify the character encoding of the source files
598# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is 603# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
diff --git a/doc/ecore_examples.dox b/doc/ecore_examples.dox
new file mode 100644
index 0000000000..cc7ec9d0d5
--- /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 */
diff --git a/doc/eet_examples.dox b/doc/eet_examples.dox
new file mode 100644
index 0000000000..b842584466
--- /dev/null
+++ b/doc/eet_examples.dox
@@ -0,0 +1,184 @@
1/**
2 * @page Examples Examples
3 *
4 * Here is a page with examples.
5 *
6 * @ref Example_Eet_Data_Simple
7 *
8 * @ref Example_Eet_Data_Nested
9 *
10 * @ref Example_Eet_Data_File_Descriptor_01
11 *
12 * @ref Example_Eet_Data_File_Descriptor_02
13 *
14 * @ref Example_Eet_Data_Cipher_Decipher
15 *
16 * <a href="examples.html">List of examples</a>
17 */
18
19/**
20 * @page Example_Eet_Basic Very basic Eet example
21 *
22 * @includelineno eet-basic.c
23 * @example eet-basic.c
24 */
25
26/**
27 * @page Example_Eet_File Example of the various ways to interface with an Eet File
28 *
29 * @includelineno eet-file.c
30 * @example eet-file.c
31 */
32
33/**
34 * @page Example_Eet_Data_Simple Simple data example
35 *
36 * @includelineno eet-data-simple.c
37 * @example eet-data-simple.c
38 */
39
40/**
41 * @page Example_Eet_Data_Nested Nested data example
42 *
43 * @includelineno eet-data-nested.c
44 * @example eet-data-nested.c
45 */
46
47/**
48 * @page Example_Eet_Data_File_Descriptor_01 File descriptor data example
49 *
50 * @includelineno eet-data-file_descriptor_01.c
51 * @example eet-data-file_descriptor_01.c
52 */
53
54/**
55 * @page Example_Eet_Data_File_Descriptor_02 File descriptor data example, with Eet unions and variants
56 *
57 * This is an example much like the one shown in @ref
58 * eet_data_file_descriptor. The difference is that here we're
59 * attaining ourselves to two new data types to store in an Eet file
60 * -- @b unions and @b variants. We don't try to come with data
61 * mapping to real world use cases, here. Instead, we're defining
62 * 3 different simple structures to be used throughout the example:
63 * @dontinclude eet-data-file_descriptor_02.c
64 * @skip typedef struct _Example_Struct1
65 * @until typedef struct _Example_Struct3
66 * @skip struct _Example_Struct1
67 * @until int body
68 * @until };
69 *
70 * To identify, for both union and variant data cases, the type of
71 * each chunk of data, we're defining types to point to each of those
72 * structs:
73 * @dontinclude eet-data-file_descriptor_02.c
74 * @skip typedef enum _Example_Data_Type
75 * @until ;
76 * @skip enum _Example_Data_Type
77 * @until };
78 *
79 * We have also a mapping from those types to name strings, to be used
80 * in the Eet unions and variants @c type_get() and @c type_set() type
81 * identifying callbacks:
82 * @skip struct
83 * @until };
84 *
85 * In this example, we have no fancy hash to store our data into
86 * profiles/accounts, but just two lists for union and variant data
87 * nodes:
88 * @dontinclude eet-data-file_descriptor_02.c
89 * @skip typedef struct _Example_Lists
90 * @until typedef struct _Example_Lists
91 * @skip struct _Example_Lists
92 * @until };
93 *
94 * Let's begin with our unions, then, which look like:
95 * @dontinclude eet-data-file_descriptor_02.c
96 * @skip typedef struct _Example_Union
97 * @until typedef struct _Example_Union
98 * @skip struct _Example_Union
99 * @until };
100 *
101 * The first interesting part of the code is where we define our data
102 * descriptors for the main lists, the unions and all of structures
103 * upon which those two depend.
104 * @dontinclude eet-data-file_descriptor_02.c
105 * @skip declaring types
106 * @until _union_descriptor);
107 * The code for descriptors on @c Example_Struct1, @c Example_Struct2
108 * and @c Example_Struct3 is straightforward, a matter already covered
109 * on @ref eet_data_file_descriptor. What is new, here, are the two
110 * type matching functions for our unions. There, we must set the @c
111 * data pointer to its matching type, on @c _union_type_set and return
112 * the correct matching type, on @c _union_type_get:
113 * @dontinclude eet-data-file_descriptor_02.c
114 * @skip union type_get()
115 * @until _union_type_set
116 * @until _union_type_set
117 *
118 * With the #EET_DATA_DESCRIPTOR_ADD_MAPPING calls, which follow, we
119 * make the the link between our type names and their respective
120 * structs. The code handling actual data is pretty much the same as in
121 * @ref eet_data_file_descriptor -- one uses command line arguments to
122 * enter new data chunks (or just to visualize the contents of an Eet
123 * file), signalling if they are unions or variants. One must also
124 * pass the type of the data chuck to enter, with integers 1, 2 or
125 * 3. Then, come the fields for each type:
126 * @dontinclude eet-data-file_descriptor_02.c
127 * @skip Usage
128 * @until argv
129 *
130 * Variants are very similar to unions, except that data chunks need
131 * @b not contain previously allocated space for each of the possible
132 * types of data going in them:
133 * @dontinclude eet-data-file_descriptor_02.c
134 * @skip typedef struct _Example_Variant
135 * @until typedef struct _Example_Variant
136 * @skip struct _Example_Variant_Type
137 * @until };
138 * @until };
139 *
140 * The code declaring the data descriptors and handling the data is
141 * very similar to the unions part, and is left for the reader to
142 * check for him/herself. The complete code of the example follows.
143 *
144 * @includelineno eet-data-file_descriptor_02.c
145 * @example eet-data-file_descriptor_02.c
146 */
147
148/**
149 * @page Example_Eet_Data_Cipher_Decipher Eet data cipher/decipher example
150 *
151 * In this example, we exemplify the usage of eet_write_cipher() and
152 * eet_read_cipher(). For it to work, <b>make sure</b> to have your
153 * Eet installation with a ciphering backend enabled.
154 *
155 * We start by defining the information to record in an Eet file (@c
156 * buffer), the key to cipher that (@c key) and a dummy wrong key to
157 * try to access that information, later (@c key_bad).
158 * @dontinclude eet-data-cipher_decipher.c
159 * @skip buffer =
160 * @until bad =
161 *
162 * After opening our file, we simply use the first cited function to
163 * write our string ciphered:
164 * @dontinclude eet-data-cipher_decipher.c
165 * @skip eet_open
166 * @until eet_close
167 *
168 * Then, after closing it on purpose, we open it again, to retrieve
169 * the encrypted information back, in a readable format:
170 * @skip eet_open
171 * @until eet_close
172 * @until eet_close
173 *
174 * Note that we do it twice, being the last time with the wrong
175 * key. In this last case, if the information is read back and matches
176 * the original @c buffer, something wrong is going on (we made it to
177 * fail on purpose). The former access is OK, and must work.
178 *
179 * What we do in sequence is just to delete the file. The complete
180 * code of the example follows.
181 *
182 * @includelineno eet-data-cipher_decipher.c
183 * @example eet-data-cipher_decipher.c
184 */
diff --git a/doc/eio.dox.in b/doc/eio.dox.in
new file mode 100644
index 0000000000..de25ae6730
--- /dev/null
+++ b/doc/eio.dox.in
@@ -0,0 +1,456 @@
1/* EIO - EFL data type library
2 * Copyright (C) 2010 Enlightenment Developers:
3 * Cedric Bail <cedric.bail@free.fr>
4 * Vincent "caro" Torri <vtorri at univ-evry dot fr>
5 * Stephen "okra" Houston <unixtitan@gmail.com>
6 * Gustavo Sverzut Barbieri <barbieri@gmail.com>
7 *
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2.1 of the License, or (at your option) any later version.
12 *
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
17 *
18 * You should have received a copy of the GNU Lesser General Public
19 * License along with this library;
20 * if not, see <http://www.gnu.org/licenses/>.
21 */
22
23/**
24 * @page eio_main Eio
25 * @author Cedric Bail <cedric.bail@@free.fr>
26 * @author Stephen "okra" Houston <unixtitan@@gmail.com>
27 * @author Gustavo Sverzut Barbieri <barbieri@@gmail.com>
28 * @author Vincent "caro" Torri <vtorri at univ-evry dot fr>
29 * @author Guillaume "kuri" Friloux <guillaume.friloux@@asp64.com>
30 * @date 2010-2012
31 *
32 * @section eio_intro_sec Introduction
33 * @version @PACKAGE_VERSION@
34 *
35 * The Eio library is a library that implements an API for asynchronous
36 * input/output operation. Most operation are done in a separated thread
37 * to prevent lock. See @ref Eio_Group. Some helper to work on data
38 * received in Eio callback are also provided see @ref Eio_Helper.
39 * It is also possible to work asynchronously on Eina_File with @ref Eio_Map
40 * or on Eet_File with @ref Eio_Eet. It come with way to manipulate
41 * eXtended attribute assynchronously with @ref Eio_Xattr.
42 *
43 * This library is cross-platform and can be compiled and used on
44 * Linux, BSD, Opensolaris and Windows (XP and CE).
45 */
46
47/**
48 * @page tutorial_dir_copy eio_dir_copy() tutorial
49 *
50 * To use eio_dir_copy(), you basically need the source and
51 * destination files (or directories), and set three callbacks:
52 *
53 * @li The notification callback, which allows you to know if a file or
54 * a directory is copied, and the progress of the copy.
55 * @li The end callback, which is called when the copy is finished.
56 * @li The error callback, which is called if an error occured. You
57 * can then retrieve the error type as an errno error.
58 *
59 * @warning It is the user's duty to provide the "right target". It
60 * means that copying to '.' will copy the content directly inside '.'
61 * and not in a subdirectory.
62 *
63 * Here is a simple example:
64 *
65 * @code
66 * #include <Ecore.h>
67 * #include <Eio.h>
68 *
69 * static void
70 * _test_notify_cb(void *data, Eio_File *handler, const Eio_Progress *info)
71 * {
72 * switch (info->op)
73 * {
74 * case EIO_FILE_COPY:
75 * printf("[%s] %f%%\n", info->dest, info->percent);
76 * break;
77 * case EIO_DIR_COPY:
78 * printf("global [%li/%li] %f%%\n", info->current, info->max, info->percent);
79 * break;
80 * }
81 * }
82 *
83 * static void
84 * _test_done_cb(void *data, Eio_File *handler)
85 * {
86 * printf("copy done\n");
87 * ecore_main_loop_quit();
88 * }
89 *
90 * static void
91 * _test_error_cb(int error, Eio_File *handler, void *data)
92 * {
93 * fprintf(stderr, "error: [%s]\n", strerror(error));
94 * ecore_main_loop_quit();
95 * }
96 *
97 * int
98 * main(int argc, char **argv)
99 * {
100 * Eio_File *cp;
101 *
102 * if (argc != 3)
103 * {
104 * fprintf(stderr, "eio_cp source_file destination_file\n");
105 * return -1;
106 * }
107 *
108 * ecore_init();
109 * eio_init();
110 *
111 * cp = eio_dir_copy(argv[1], argv[2],
112 * _test_notify_cb,
113 * _test_done_cb,
114 * _test_error_cb,
115 * NULL);
116 *
117 * ecore_main_loop_begin();
118 *
119 * eio_shutdown();
120 * ecore_shutdown();
121 *
122 * return 0;
123 * }
124 * @endcode
125 */
126
127/**
128 * @page tutorial_dir_stat_ls eio_dir_stat_ls() tutorial
129 *
130 * @li The filter callback, which allow or not a file to be seen
131 * by the main loop handler. This callback run in a separated thread.
132 * @li The main callback, which receive in the main loop all the file
133 * that are allowed by the filter. If you are updating a user interface
134 * it make sense to delay the insertion a little, so you get a chance
135 * to update the canvas for a bunch of file instead of one by one.
136 * @li The end callback, which is called in the main loop when the
137 * content of the directory has been correctly scanned and all the
138 * file notified to the main loop.
139 * @li The error callback, which is called if an error occured or
140 * if the listing was cancelled during it's run. You can then retrieve
141 * the error type as an errno error.
142 *
143 * Here is a simple example that implement a stupidly simple replacement for find:
144 *
145 * @code
146 * #include <Ecore.h>
147 * #include <Eio.h>
148 *
149 * static Eina_Bool
150 * _test_filter_cb(void *data, Eio_File *handler, const Eina_File_Direct_Info *info)
151 * {
152 * fprintf(stderr, "ACCEPTING: %s\n", info->path);
153 * return EINA_TRUE;
154 * }
155 *
156 * static void
157 * _test_main_cb(void *data, Eio_File *handler, const Eina_File_Direct_Info *info)
158 * {
159 * fprintf(stderr, "PROCESS: %s\n", info->path);
160 * }
161 *
162 * static void
163 * _test_done_cb(void *data, Eio_File *handler)
164 * {
165 * printf("ls done\n");
166 * ecore_main_loop_quit();
167 * }
168 *
169 * static void
170 * _test_error_cb(void *data, Eio_File *handler, int error)
171 * {
172 * fprintf(stderr, "error: [%s]\n", strerror(error));
173 * ecore_main_loop_quit();
174 * }
175 *
176 * int
177 * main(int argc, char **argv)
178 * {
179 * Eio_File *cp;
180 *
181 * if (argc != 2)
182 * {
183 * fprintf(stderr, "eio_ls directory\n");
184 * return -1;
185 * }
186 *
187 * ecore_init();
188 * eio_init();
189 *
190 * cp = eio_dir_stat_ls(argv[1],
191 * _test_filter_cb,
192 * _test_main_cb,
193 * _test_done_cb,
194 * _test_error_cb,
195 * NULL);
196 *
197 * ecore_main_loop_begin();
198 *
199 * eio_shutdown();
200 * ecore_shutdown();
201 *
202 * return 0;
203 * }
204 *
205 * @endcode
206 */
207
208/**
209 * @page tutorial_file_ls eio_file_ls() tutorial
210 *
211 * To use eio_file_ls(), you just need to define four callbacks:
212 *
213 * @li The filter callback, which allow or not a file to be seen
214 * by the main loop handler. This callback run in a separated thread.
215 * @li The main callback, which receive in the main loop all the file
216 * that are allowed by the filter. If you are updating a user interface
217 * it make sense to delay the insertion a little, so you get a chance
218 * to update the canvas for a bunch of file instead of one by one.
219 * @li The end callback, which is called in the main loop when the
220 * content of the directory has been correctly scanned and all the
221 * file notified to the main loop.
222 * @li The error callback, which is called if an error occured or
223 * if the listing was cancelled during it's run. You can then retrieve
224 * the error type as an errno error.
225 *
226 * Here is a simple example:
227 *
228 * @code
229 * #include <Ecore.h>
230 * #include <Eio.h>
231 *
232 * static Eina_Bool
233 * _test_filter_cb(void *data, Eio_File *handler, const char *file)
234 * {
235 * fprintf(stderr, "ACCEPTING: %s\n", file);
236 * return EINA_TRUE;
237 * }
238 *
239 * static void
240 * _test_main_cb(void *data, Eio_File *handler, const char *file)
241 * {
242 * fprintf(stderr, "PROCESS: %s\n", file);
243 * }
244 *
245 * static void
246 * _test_done_cb(void *data, Eio_File *handler)
247 * {
248 * printf("ls done\n");
249 * ecore_main_loop_quit();
250 * }
251 *
252 * static void
253 * _test_error_cb(void *data, Eio_File *handler, int error)
254 * {
255 * fprintf(stderr, "error: [%s]\n", strerror(error));
256 * ecore_main_loop_quit();
257 * }
258 *
259 * int
260 * main(int argc, char **argv)
261 * {
262 * Eio_File *cp;
263 *
264 * if (argc != 2)
265 * {
266 * fprintf(stderr, "eio_ls directory\n");
267 * return -1;
268 * }
269 *
270 * ecore_init();
271 * eio_init();
272 *
273 * cp = eio_file_ls(argv[1],
274 * _test_filter_cb,
275 * _test_main_cb,
276 * _test_done_cb,
277 * _test_error_cb,
278 * NULL);
279 *
280 * ecore_main_loop_begin();
281 *
282 * eio_shutdown();
283 * ecore_shutdown();
284 *
285 * return 0;
286 * }
287 *
288 * @endcode
289 */
290
291/**
292 * @page tutorial_monitor_add eio_monitor_add() tutorial
293 *
294 * To use eio_monitor_add(), you have to define callbacks
295 * for events declared by eio.
296 * Available events are :
297 * - EIO_MONITOR_FILE_CREATED
298 * - EIO_MONITOR_FILE_DELETED
299 * - EIO_MONITOR_FILE_MODIFIED
300 * - EIO_MONITOR_FILE_CLOSED
301 * - EIO_MONITOR_DIRECTORY_CREATED
302 * - EIO_MONITOR_DIRECTORY_DELETED
303 * - EIO_MONITOR_DIRECTORY_CLOSED
304 * - EIO_MONITOR_SELF_RENAME
305 * - EIO_MONITOR_SELF_DELETED
306 *
307 * As nothing is worth an example, here it is :
308 * @code
309 * #include <Eina.h>
310 * #include <Ecore.h>
311 * #include <Eio.h>
312 *
313 * void file_modified(void *data, int type, void *event)
314 * {
315 * const char *filename = (const char *)data;
316 * printf("file %s ", filename);
317 * if( type == EIO_MONITOR_FILE_MODIFIED )
318 * printf("is being modified");
319 * else if( type == EIO_MONITOR_FILE_CLOSED )
320 * printf("is not more being modified");
321 * else printf("got unexpected changes");
322 * printf("\n");
323 * }
324 *
325 * int main(int argc, char **argv) {
326 * Eio_Monitor *monitor = NULL,
327 * *monitor2 = NULL;
328 * eio_init();
329 * const char *filename = eina_stringshare_add("/tmp/eio_notify_testfile");
330 *
331 * monitor = eio_monitor_add(filename);
332 * ecore_event_handler_add(EIO_MONITOR_FILE_MODIFIED, (Ecore_Event_Handler_Cb)file_modified, filename);
333 * ecore_event_handler_add(EIO_MONITOR_FILE_CLOSED, (Ecore_Event_Handler_Cb)file_modified, filename);
334 *
335 * ecore_main_loop_begin();
336 * eio_shutdown();
337 * eina_stringshare_del(filename);
338 * }
339 * @endcode
340 * Build the example doing :
341 * @verbatim gcc -o tutorial_monitor_add tutorial_monitor_add.c `pkg-config --libs --cflags eio ecore ecore-file eina`
342 * then create the file /tmp/eio_notify_testfile :
343 * touch /tmp/eio_notify_testfile
344 * and launch tutorial_monitor_add, and in another terminal, write into /tmp/eio_notify_testfile, doing for example :
345 * echo "test" >> /tmp/eio_notify_testfile
346 * @endverbatim
347 */
348
349/**
350 * @page tutorial_dir_direct_ls eio_dir_direct_ls() tutorial
351 *
352 * @li The filter callback, which allow or not a file to be seen
353 * by the main loop handler. This callback run in a separated thread.
354 * It also take care of getting a stat buffer needed by the main callback
355 * to display the file size.
356 * @li The main callback, which receive in the main loop all the file
357 * that are allowed by the filter. If you are updating a user interface
358 * it make sense to delay the insertion a little, so you get a chance
359 * to update the canvas for a bunch of file instead of one by one.
360 * @li The end callback, which is called in the main loop when the
361 * content of the directory has been correctly scanned and all the
362 * file notified to the main loop.
363 * @li The error callback, which is called if an error occured or
364 * if the listing was cancelled during it's run. You can then retrieve
365 * the error type as an errno error.
366 *
367 * Here is a simple example that implement a stupidly simple recursive ls that display file size:
368 *
369 * @code
370 * #include <Eina.h>
371 * #include <Ecore.h>
372 * #include <Eio.h>
373 *
374 * static Eina_Bool
375 * _test_filter_cb(void *data, Eio_File *handler, Eina_File_Direct_Info *info)
376 * {
377 * Eina_Stat *buffer;
378 * Eina_Bool isdir;
379 *
380 * isdir = info->type == EINA_FILE_DIR;
381 *
382 * buffer = malloc(sizeof (Eina_Stat));
383 * if (eina_file_statat(eio_file_container_get(handler), info, buffer))
384 * {
385 * free(buffer);
386 * return EINA_FALSE;
387 * }
388 *
389 * if (!isdir && info->type == EINA_FILE_DIR)
390 * {
391 * struct stat st;
392 * if (lstat(info->path, &st) == 0)
393 * {
394 * if (S_ISLNK(st.st_mode))
395 * info->type = EINA_FILE_LNK;
396 * }
397 * }
398 *
399 * eio_file_associate_direct_add(handler, "stat", buffer, free);
400 * fprintf(stdout, "ACCEPTING: %s\n", info->path);
401 * return EINA_TRUE;
402 * }
403 *
404 * static void
405 * _test_main_cb(void *data, Eio_File *handler, const Eina_File_Direct_Info *info)
406 * {
407 * struct stat *buffer;
408 *
409 * buffer = eio_file_associate_find(handler, "stat");
410 * fprintf(stdout, "PROCESS: %s of size %li\n", info->path, buffer->st_size);
411 * }
412 *
413 * static void
414 * _test_done_cb(void *data, Eio_File *handler)
415 * {
416 * printf("ls done\n");
417 * ecore_main_loop_quit();
418 * }
419 *
420 * static void
421 * _test_error_cb(void *data, Eio_File *handler, int error)
422 * {
423 * fprintf(stdout, "error: [%s]\n", strerror(error));
424 * ecore_main_loop_quit();
425 * }
426 *
427 * int
428 * main(int argc, char **argv)
429 * {
430 * Eio_File *cp;
431 *
432 * if (argc != 2)
433 * {
434 * fprintf(stdout, "eio_ls directory\n");
435 * return -1;
436 * }
437 *
438 * ecore_init();
439 * eio_init();
440 *
441 * cp = eio_dir_direct_ls(argv[1],
442 * _test_filter_cb,
443 * _test_main_cb,
444 * _test_done_cb,
445 * _test_error_cb,
446 * NULL);
447 *
448 * ecore_main_loop_begin();
449 *
450 * eio_shutdown();
451 * ecore_shutdown();
452 *
453 * return 0;
454 * }
455 * @endcode
456 */
diff --git a/doc/evas_examples.dox b/doc/evas_examples.dox
new file mode 100644
index 0000000000..65dd513409
--- /dev/null
+++ b/doc/evas_examples.dox
@@ -0,0 +1,1073 @@
1/**
2 * @page Examples Examples
3 *
4 * Here is a page with examples.
5 *
6 * @ref Example_Evas_Buffer_Simple
7 *
8 * @ref Example_Evas_Init_Shutdown
9 *
10 * @ref Example_Evas_Text
11 *
12 * @ref Example_Evas_Images
13 *
14 * @ref Example_Evas_Images_2
15 *
16 * @ref Example_Evas_Events
17 *
18 * @ref Example_Evas_Object_Manipulation
19 *
20 * @ref Example_Evas_Aspect_Hints
21 *
22 * @ref Example_Evas_Size_Hints
23 *
24 * @ref Example_Evas_Stacking
25 *
26 * @ref Example_Evas_Smart_Objects
27 *
28 * @ref Example_Evas_Box Evas box
29 */
30
31/**
32 * @page Example_Evas_Buffer_Simple Simple Evas canvas example
33 *
34 * The canvas will here use the buffer engine.
35 *
36 * @include evas-buffer-simple.c
37 * @example evas-buffer-simple.c
38 */
39
40/**
41 * @page Example_Evas_Init_Shutdown Evas' init/shutdown routines example
42 *
43 * @include evas-init-shutdown.c
44 * @example evas-init-shutdown.c
45 */
46
47/**
48 * @page Example_Evas_Images Some image object functions examples
49 * @dontinclude evas-images.c
50 *
51 * In this example, we add two images to a canvas, each one having a
52 * quarter of the canvas' size, positioned on the top left and bottom
53 * right corners, respectively:
54 * @skip img1 = evas_object_image_add(d.evas);
55 * @until ecore_main_loop_begin
56 * See there is a border image around the top left one, <b>which is
57 * the one that should be displayed</b>. The other one will (on
58 * purpose) fail to load, because we set a wrong file path as image
59 * source on it:
60 * @dontinclude evas-images.c
61 * @skip valid_path
62 * @until bogus_path
63 * This is how one is supposed to test for success when binding source
64 * images to image objects: evas_object_image_load_error_get(),
65 * followed by evas_load_error_str(), if one wants to pretty print/log
66 * the error. We'll talk about the border image further.
67 *
68 * To interact with the program, there's a command line interface.
69 * A help string can be asked for with the 'h' key:
70 * @dontinclude evas-images.c
71 * @skip commands
72 * @until ;
73 * The first four commands will change the top left images's @b fill property
74 * values, which dictate how the source image (Enlightenment's logo)
75 * is to be displayed through the image object's area. Experiment with
76 * those switches until you get the idea of evas_object_fill_set().
77 *
78 * The 'f' command will toggle that image's "filled" property, which
79 * is whether it should track its size and set the fill one to fit the
80 * object's boundaries perfectly (stretching). Note that this command
81 * and the four above it will conflict: in real usage one would use
82 * one or other ways of setting an image object's viewport with regard
83 * to its image source.
84 *
85 * There are four commands which deal with the border image. This red
86 * frame is there to illustrate <b>image borders</b>. The image source
87 * for the border is a solid red rectangle, with a transparent @b
88 * rectangular area in its middle. See how we use it to get a 3 pixel
89 * wide frame with <code>evas_object_image_border_set(d.border, 3, 3,
90 * 3, 3)</code>. To finish the effect of showing it as a border, we
91 * issue <code>evas_object_image_border_center_fill_set(d.border,
92 * EVAS_BORDER_FILL_NONE)</code>.
93 *
94 * Use 't' to change the border's thickness. 'b' will change the
95 * border image's center region rendering schema: either a hole (no
96 * rendering), blending (see the original transparent area, in this
97 * case) or solid (the transparent area gets filled). Finally, 'c'
98 * will change the border's scaling factor.
99 *
100 * While you have the border in 'blending mode', test the command 'm':
101 * it will set whether to use or not smooth scaling on the border's
102 * source image. Since the image is small originally (30 x 30), we're
103 * obviously up-scaling it (except the border pixels, do you
104 * remember?). With this last switch, you'll either see the
105 * transparent shape in the middle flat (no smoothing) or blurry
106 * (smoothed).
107 *
108 * The full example follows.
109 *
110 * @include evas-images.c
111 * @example evas-images.c
112 */
113
114/**
115 * @page Example_Evas_Images_2 Some more image object functions examples (2nd block)
116 * @dontinclude evas-images2.c
117 *
118 * In this example, we have three images on the canvas, but one of
119 * them is special -- we're using it as a <b>proxy image
120 * object</b>. It will mirror the contents of the other two images
121 * (which are the ones on the top of the canvas), one at a time:
122 * @skip d.proxy_img = evas_object_image_filled_add(d.evas);
123 * @until evas_object_show(d.proxy_img);
124 * As in other examples, we have a command line interface on it.
125 * @dontinclude evas-images2.c
126 * @skip commands
127 * @until ;
128 * The 'p' one will change the source of the proxy image to one of the
129 * other two, as seem above.
130 * @skip if (strcmp(ev->keyname, "p") == 0)
131 * @until }
132 * Note the top right image, the smaller one:
133 * @dontinclude evas-images2.c
134 * @skip noise_img =
135 * @until show
136 * Since we are creating the data for its pixel buffer ourselves, we
137 * have to set its size with evas_object_image_size_set(), first. We
138 * set our data with the function evas_object_image_data_set(), where
139 * the second argument is a buffer with random data. There's a last
140 * command to print it's @b stride value. Since its created with one
141 * quarter of the canvas's original width
142 * @dontinclude evas-images2.c
143 * @skip define WIDTH
144 * @until define HEIGHT
145 * you can check this value.
146 *
147 * The image on the top left also has a subtlety: it is @b pre-loaded
148 * on this example.
149 * @dontinclude evas-images2.c
150 * @skip d.logo =
151 * @until show
152 * On real use cases we wouldn't be just printing something like this
153 * @dontinclude evas-images2.c
154 * @skip static void
155 * @until }
156 * naturally.
157 *
158 * The 's' command will save one of the images on the disk, in the png
159 * format:
160 * @dontinclude evas-images2.c
161 * @skip if (strcmp(ev->keyname, "a") == 0)
162 * @until }
163 *
164 * The full example follows.
165 *
166 * @include evas-images2.c
167 * @example evas-images2.c
168 */
169
170/**
171 * @page Example_Evas_Events Evas events (canvas and object ones) and some canvas operations example
172 * @dontinclude evas-events.c
173 *
174 * In this example we illustrate how to interact with canvas' (and its
175 * objects') events, including the key input ones. We also demonstrate
176 * precise point collision on objects and canvas "obscured regions",
177 * here.
178 *
179 * The example application consists of a window with a white
180 * background and an image -- the Enlightenment logo. The application
181 * begins with this image switching back and forth into two sizes: the
182 * exact canvas' size and one quarter of it (when it's placed on the
183 * top left quadrant). Thus, we'll have an @b animation going on,
184 * with image states set to change each 2 elapsed seconds.
185 *
186 * There's a global variable to aid accessing our desired context
187 * variables from anywhere in the code:
188 * @dontinclude evas-events.c
189 * @skip test_data
190 * @until {0}
191 *
192 * What interests us there are the @c canvas pointer, our image handle
193 * -- @c img -- and the background one, @c bg.
194 *
195 * The first interesting thing on the example is the registration of a
196 * callback on each canvas resizing event, where we put our canvas'
197 * size and the background rectangle's one in synchrony, so that we
198 * don't get bogus content on rendering with canvas resizes:
199 * @dontinclude evas-events.c
200 * @skip resize_set
201 * @until resize_set
202 * @dontinclude evas-events.c
203 * @skip here to keep
204 * @until }
205 *
206 * Than, after grabbing our canvas pointer from the Ecore Evas helper
207 * infrastructure, we registrate an event callbacks on it:
208 * @skip evas_event_callback_add(d.canvas, EVAS_CALLBACK_RENDER_FLUSH_PRE,
209 * @until two canvas event callbacks
210 * @dontinclude evas-events.c
211 * @skip render flush callback
212 * @until }
213 * It will be called whenever our canvas has to flush its rendering
214 * pipeline. In this example, two ways of observing that message
215 * which is printed in the cited callback are:
216 * - to resize the example's window (thus resizing the canvas' viewport)
217 * - let the animation run
218 *
219 * When one resizes the canvas, there's at least one operation it has
220 * to do which will require new calculation for rendering: the
221 * resizing of the background rectangle, in a callback we already
222 * shown you.
223 *
224 * The creation of our background rectangle is so that we give it a @b name,
225 * via evas_object_name_set() and we give it the canvas @b focus:
226 * @dontinclude evas-events.c
227 * @skip bg = evas_object_rectangle_add
228 * @until focus_set
229 *
230 * Still exemplifying events and callbacks, we register a callback on
231 * the canvas event of an object being focused:
232 * @dontinclude evas-events.c
233 * @skip add(d.canvas, EVAS_CALLBACK_CANVAS_OBJECT_FOCUS
234 * @until }
235 * @dontinclude evas-events.c
236 * @skip called when
237 * @until }
238 *
239 * In that call, @c event_info is going to be the focused object's
240 * handle, in this case our background rectangle. We print its name,
241 * so you can check it's the same. We check that pointer is the same
242 * reported by Evas' API with regard to the newest focused
243 * object. Finally, we check whether that object is really flagged as
244 * focused, now using an Evas object API function.
245 *
246 * The animation we talked about comes from a timer we register just
247 * before we start the example's main loop. As we said, the resizing
248 * of the image will also force the canvas to repaint itself, thus
249 * flushing the rendering pipeline whenever the timer ticks:
250 * @dontinclude evas-events.c
251 * @skip d.resize_timer = ecore
252 * @until d.resize_timer = ecore
253 * @dontinclude evas-events.c
254 * @skip put some action
255 * @until }
256 * When you start this example, this animation will be
257 * running, by default. To interact with the program, there's a
258 * command line interface. A help string can be asked for with the
259 * 'h' key:
260 * @dontinclude evas-events.c
261 * @skip static const char *commands
262 * @until ;
263 * These are the commands the example will accept at any time, except
264 * when one triggers the 'f' one. This command will exemplify
265 * evas_event_freeze(), which interrupts @b all input events
266 * processing for the canvas (in the example, just for 3 seconds). Try
267 * to issue events for it during that freeze time:
268 * @dontinclude evas-events.c
269 * @skip if (strcmp(ev->keyname, "f") == 0)
270 * @until }
271 * The 'd' command will unregister those two canvas callbacks for you,
272 * so you won't see the messages about the focused object and the
273 * rendering process anymore:
274 * @dontinclude evas-events.c
275 * @skip if (strcmp(ev->keyname, "d") == 0)
276 * @until }
277 * In this example, we start using a focused object to handle the input
278 * events -- the background rectangle. We register a callback on an key input
279 * event occurring on it, so that we can act on each key stroke:
280 * @skip object_event_callback_add
281 * @until }
282 * @dontinclude evas-events.c
283 * @skip examine the keys pressed
284 * @until key grab
285 * We do so by examining the @c ev->keyname string (remember the event
286 * information struct for key down events is the #Evas_Event_Key_Down
287 * one). There's one more trick for grabbing input events on this
288 * example -- evas_object_key_grab(). The 'c' command will, when
289 * firstly used, @b unfocus the background rectangle. Unfocused
290 * objects on an Evas canvas will @b never receive key events. We
291 * grab, then, the keys we're interested at to the object forcefully:
292 * @skip if (d.focus)
293 * @until got here by key grabs
294 * This shows how one can handle input not depending on focus issues
295 * -- you can grab them globally. Switch back and forth focus and
296 * forced key grabbing with the 'c' key, and observe the messages
297 * printed about the focused object. Observe, also, that we register
298 * two more @b object callbacks, this time on the image object
299 * (Enlightenment logo), where we just print messages telling the mouse
300 * pointer has entered or exited it area:
301 * @skip evas_object_show(d.img);
302 * @until mouse_out, NULL
303 * @dontinclude evas-events.c
304 * @skip mouse enters the object's area
305 * @until mouse exits the object's area
306 * Experiment with moving the mouse pointer over the image, letting it
307 * enter and exit its area (stop the animation with 'a', for a better
308 * experience). When you start the example, Evas will consider this
309 * area by being the whole boundary rectangle around the picture. If
310 * you issue the 'p' command, though, you get a demonstration of Evas'
311 * precise point collision detection on objects. With
312 * evas_object_precise_is_inside_get(), one can make Evas consider the
313 * transparent areas of an object (the middle of the logo's E letter,
314 * in the case) as not belonging to it when calculating mouse
315 * in/out/up/down events:
316 * @dontinclude evas-events.c
317 * @skip if (strcmp(ev->keyname, "p") == 0)
318 * @until }
319 * To finish the example, try the command bound to Control + 'o',
320 * which exemplifies Evas' <b>obscured regions</b>. When firstly
321 * pressed, you'll get the same contents, in a region in the middle of
322 * the canvas, at the time the key was pressed, until you toggle the
323 * effect off again (make sure the animation is running on to get the
324 * idea better). When you toggle this effect off, we also demonstrate
325 * the use of evas_render_updates(), which will force immediate
326 * updates on the canvas rendering, bringing back the obscured
327 * region's contents to normal.
328 * @skip mods = evas_key_modifier_get(evas);
329 * @until end of obscured region command
330 *
331 * What follows is the complete code for this example.
332 *
333 * @include evas-events.c
334 * @example evas-events.c
335 */
336
337/**
338 * @page Example_Evas_Object_Manipulation Evas objects basic manipulation example
339 *
340 * @include evas-object-manipulation.c
341 * @example evas-object-manipulation.c
342 */
343
344/**
345 * @page Example_Evas_Aspect_Hints Evas aspect hints example
346 *
347 * @include evas-aspect-hints.c
348 * @example evas-aspect-hints.c
349 */
350
351/**
352 * @page Example_Evas_Size_Hints Evas alignment, minimum size, maximum size, padding and weight hints example
353 *
354 * In this code, we place a (vertical) box with two rectangles as
355 * child elements. It has a command line interface with which to act
356 * on those rectangles' <b>size hints</b>:
357 * @dontinclude evas-hints.c
358 * @skip static const char commands
359 * @until ;
360 *
361 * That should be self explanatory. Change those values (possibly
362 * resizing the box, which will resize together with the example's
363 * window) to get how size hints are honored by a container object,
364 * which in this case is the Evas box.
365 *
366 * More on this smart object can be found on @ref Example_Evas_Box.
367 * The full code for this example follows.
368 *
369 * @include evas-hints.c
370 * @example evas-hints.c
371 */
372
373/**
374 * @page Example_Evas_Box Evas box example
375 *
376 * In this example, we demonstrate the use of Evas box objects. We
377 * cover changing boxes' layouts (with a custom layout, besides the
378 * ones provided by Evas), box padding and alignment influence on the
379 * layouts, insertion and removal of box items.
380 *
381 * The interesting part of the code starts, naturally, when we add a
382 * box object to the canvas. Just after it, we place five rectangles,
383 * with random colors, inside of it. Those rectangles get a minimum
384 * size hint of 50 pixels on each axis, which will be respected by
385 * most of the box's possible layouts:
386 * @dontinclude evas-box.c
387 * @skip evas_object_box_add
388 * @until }
389 * @until }
390 *
391 * Just like in other Evas examples, we have a white background on the
392 * canvas and a red border around the container object of interest,
393 * the box, to mark its boundaries. Resizing of the canvas will keep
394 * the box's proportion with regard to the whole canvas', so that you
395 * can experiment with different sizes of the box to accomodate its
396 * children:
397 * @dontinclude evas-box.c
398 * @skip adjust canvas' contents on resizes
399 * @until }
400 *
401 * Again, one interacts with this program by means of key commands:
402 * @dontinclude evas-box.c
403 * @skip static const char *commands
404 * @until ;
405 *
406 * Let's start with the @b numeric ones, each of which will impose a
407 * different layout on the box object.
408 *
409 * The initial layout the box starts at is the one triggered by the
410 * key @c '1' -- the horizontal layout. Thus, the initial appearance
411 * of this program, demonstrating this layout, is something like:
412 *
413 * @image html evas-box-example-00.png
414 * @image rtf evas-box-example-00.png
415 * @image latex evas-box-example-00.eps
416 *
417 * The vertical layout (@c '2' key) is very similar, but just
418 * disposing the items vertically:
419 *
420 * @image html evas-box-example-01.png
421 * @image rtf evas-box-example-01.png
422 * @image latex evas-box-example-01.eps
423 *
424 * Note the influence of the (default) @c 0.5 box alignment property,
425 * which will let the children line in the middle of the box's
426 * area. Also, because the space required by them extrapolates the
427 * box's height (we resized it to be smaller), they'll be drawn out if
428 * its bounds.
429 *
430 * Next, comes the horizontal @b homogeneous layout (@c '3' key). See
431 * how it reserves an equal amount of space for each child to take:
432 *
433 * @image html evas-box-example-02.png
434 * @image rtf evas-box-example-02.png
435 * @image latex evas-box-example-02.eps
436 *
437 * Its vertical equivalent can be triggered by the @c '4' key. The
438 * next different layout of interest is the horizontal maximum size
439 * homogeneous (@c '5' key). It will reserve cells to children sized
440 * equally to the dimensions of the child with bigger size (or minimum
441 * size hints). For this example, all cells would be just the size of
442 * our rectangles' minimum size hints and, to prove that, insert a new
443 * (smaller) rectangle at position 3, say, with @c Ctrl and @c 3 keys
444 * together:
445 *
446 * @image html evas-box-example-03.png
447 * @image rtf evas-box-example-03.png
448 * @image latex evas-box-example-03.eps
449 *
450 * The code for the commands inserting and deleting box items is:
451 * @dontinclude evas-box.c
452 * @skip mods, "Shift"
453 * @until }
454 * @until }
455 * @dontinclude evas-box.c
456 * @skip new rectangle to be put in the box
457 * @until }
458 * In that code, we exemplify evas_object_box_children_get(), to fetch
459 * a child element at an exact position. After the element removal
460 * from the box (leaving it unparented again), we delete it and free
461 * that list. The code inserting a new rectangle, there, is
462 * straightforward.
463 *
464 * Try the @c '6' key for the vertical equivalent of the last shown
465 * layout. Then, comes the @b flow layout, triggered by the @c '7'
466 * key. We make our box small to demonstrate the effect on the items
467 * layouting:
468 *
469 * @image html evas-box-example-04.png
470 * @image rtf evas-box-example-04.png
471 * @image latex evas-box-example-04.eps
472 *
473 * The next two numerical commands are for the vertical equivalent of
474 * the last and the stack one, respectively. Try them out to get their
475 * looks.
476 *
477 * The last numerical key, @c '0', shows the effect of a @b custom
478 * layout on the box. We wrote one that would split the width and
479 * height of the box equally and, then, place the items in the cells
480 * in the diagonal:
481 * @dontinclude evas-box.c
482 * @skip keyname, "0"
483 * @until }
484 * @dontinclude evas-box.c
485 * @skip custom 'diagonal' layout
486 * @until }
487 * @until }
488 *
489 * @image html evas-box-example-05.png
490 * @image rtf evas-box-example-05.png
491 * @image latex evas-box-example-05.eps
492 *
493 * Finally, the @c 'a' and @c 'p' commands will change the box's
494 * alignment and padding property values, respectively. For each of
495 * the layouts above, see the effects they make by setting different
496 * values on those properties.
497 *
498 * The full code for this example follows. For an exercise on <b>the
499 * effect of children box elements' size hints on a box layout</b>,
500 * try the @ref Example_Evas_Size_Hints.
501 *
502 * @include evas-box.c
503 * @example evas-box.c
504 */
505
506/**
507 * @page Example_Evas_Stacking Evas object stacking functions (and some event handling)
508 * @dontinclude evas-stacking.c
509 *
510 * In this example, we illustrate how to stack objects in a custom
511 * manner and how to deal with layers.
512 *
513 * We have three objects of interest in it -- white background, red
514 * rectangle, green rectangle and blue rectangle.
515 * @skip d.bg = evas_object_rectangle_add(d.canvas);
516 * @until evas_object_resize(d.bg, WIDTH, HEIGHT);
517 * @skip d.rects[2] = evas_object_rectangle_add(d.canvas);
518 * @until evas_object_show(d.rects[0]);
519 * @dontinclude evas-stacking.c
520 * Like in other Evas examples, one interacts with it by means of key
521 * commands:
522 * @skip static const char *commands
523 * @until ;
524 * At any given point, like seem above, you'll be operating one rectangle only.
525 * You may stacking it below an adjacent object with "b":
526 * @skip evas_object_stack_below(d.rects[d.cur_rect], neighbour);
527 * @until evas_object_stack_below(d.rects[d.cur_rect], neighbour);
528 * @dontinclude evas-stacking.c
529 * "a" will do the opposite:
530 * @skip evas_object_stack_above(d.rects[d.cur_rect], neighbour);
531 * @until evas_object_stack_above(d.rects[d.cur_rect], neighbour);
532 * To bring it directly to the top/bottom, use "t"/"m", respectively:
533 * @dontinclude evas-stacking.c
534 * @skip evas_object_raise(d.rects[d.cur_rect]);
535 * @until evas_object_raise(d.rects[d.cur_rect]);
536 * @skip evas_object_lower(d.rects[d.cur_rect]);
537 * @until evas_object_lower(d.rects[d.cur_rect]);
538 * At any time, use the "s" command to see the status of the
539 * ordering. It will show the background's ordering too. Note that it
540 * also shows the @b layer for this object. It starts at a @b
541 * different layer than the others. Use "l" to change its layer
542 * (higher layer numbers mean higher layers). If the background is on
543 * the same layer as the others (0), you'll see it interact with them
544 * on the ordering. If it's in the layer above, no matter what you do,
545 * you'll see nothing but the white rectangle: it covers the other
546 * layers. For the initial layer (-1), it will never mess nor occlude
547 * the others.
548 *
549 * Let's make some tests with those commands. The rectangle which starts
550 * selected and which will receive our commands is the @b red one. It
551 * starts stacked above all the others, like seem above:
552 *
553 * @image html evas-stacking-example-00.png
554 * @image rtf evas-stacking-example-00.png
555 * @image latex evas-stacking-example-00.eps
556 *
557 * Stack it one level below, with 'b', and you'll get:
558 *
559 * @image html evas-stacking-example-01.png
560 * @image rtf evas-stacking-example-01.png
561 * @image latex evas-stacking-example-01.eps
562 * Note how the rectangle which laid above it, the green one, is now
563 * on top of it. Now change the rectangle to operate on to the blue
564 * one, with two consecutive 'c' commands. Note that it's the lowest
565 * one on the stack of rectangles. Issue the 'a' command for it, thus
566 * re-stacking it one level above:
567 *
568 * @image html evas-stacking-example-02.png
569 * @image rtf evas-stacking-example-02.png
570 * @image latex evas-stacking-example-02.eps
571 * You can send it to the top of its layer directly with the 't' command:
572 *
573 * @image html evas-stacking-example-03.png
574 * @image rtf evas-stacking-example-03.png
575 * @image latex evas-stacking-example-03.eps
576 * Now put it back to the bottom of that layer with 'm':
577 *
578 * @image html evas-stacking-example-04.png
579 * @image rtf evas-stacking-example-04.png
580 * @image latex evas-stacking-example-04.eps
581 * Like said above, we have two layers used at the beginning of the
582 * example: the default one (0) and the one immediately below it (-1),
583 * for the white background. Let's change this setup by issuing the
584 * 'l' command, which will change the background's layer to 1, i.e., a
585 * layer @b above the one holding the other rectangles:
586 *
587 * @image html evas-stacking-example-05.png
588 * @image rtf evas-stacking-example-05.png
589 * @image latex evas-stacking-example-05.eps
590 * See how it now covers everything else. Press 'l' again, taking it
591 * now to layer 0. It's still covering everything because it lands the
592 * layer as the highest one on the objects stack. As we have the blue
593 * rectangle as the one receiving stacking commands, hit 't' and
594 * you'll see it again:
595 *
596 * @image html evas-stacking-example-06.png
597 * @image rtf evas-stacking-example-06.png
598 * @image latex evas-stacking-example-06.eps
599 * By bringing the background back to layer -1 ('l'), you'll get:
600 *
601 * @image html evas-stacking-example-07.png
602 * @image rtf evas-stacking-example-07.png
603 * @image latex evas-stacking-example-07.eps
604 *
605 * The last two commands available are "p" and "r", which will make
606 * the target rectangle to @b pass (ignore) and @b repeat the mouse
607 * events occurring on it (the commands will cycle through on and off
608 * states). This is demonstrated with the following
609 * #EVAS_CALLBACK_MOUSE_DOWN callback, registered on each of the
610 * colored rectangles:
611 * @dontinclude evas-stacking.c
612 * @skip static void
613 * @until }
614 * Try to change these properties on the three rectangles while
615 * experimenting with mouse clicks on their intersection region.
616 *
617 * The full example follows.
618 *
619 * @include evas-stacking.c
620 * @example evas-stacking.c
621 */
622
623/**
624 * @page Example_Evas_Map_Overview Evas Map - Overview
625 * @dontinclude evas-map-utils.c
626 *
627 * Down to the very bottom, Map is simple: it takes an object and transforms
628 * the way it will be shown on screen. But using it properly can be a bit
629 * troublesome.
630 *
631 * For the most common operations there are utility functions that help in
632 * setting up the map to achieve the desired effects. Now we'll go through
633 * an overview of the map API and some of the things that can be done with
634 * it.
635 *
636 * The full code can be found @ref evas-map-utils.c "here".
637 *
638 * To show how some functions work, this example listens to keys pressed to
639 * toggle several options.
640 * @skip typedef
641 * @until App_Data
642 * @until ;
643 *
644 * In this program, we divide the window in four quadrants, each holding an
645 * object that will have different map configurations applied to them in each
646 * call to an animator function.
647 * @skip static Eina_Bool
648 * @until evas_output_size_get
649 *
650 * Let's first create a map and set some of our options to it. Only four
651 * points maps are supported, so we'll stick to that magic number. We can
652 * set a color for each vertex or apply one for all of them at once
653 * @until evas_map_util_points_color_set
654 *
655 * For the first object, we'll have a plain rectangle. At its creation, this
656 * rectangle was set to be semi-transparent, but whether its own alpha is
657 * used will be defined by the map's alpha setting. If the map's alpha is
658 * disabled, then the object will be completely opaque. The map's own color,
659 * however, will use any alpha set to it.
660 *
661 * So we get our object, initialize our map geometry to match the rectangle
662 * and make it rotate around its own center, then apply the map to the
663 * object so it takes effect.
664 * @until evas_object_map_enable_set
665 *
666 * The second object is an image. Here we don't have any color set for the
667 * object, but the image itself contains an alpha channel that will not be
668 * affected by the map settings, so even with alpha set to be off, the image
669 * will still be transparent. Color applied to the map will tint it though.
670 * Since setting a map copies it into the object, we can reuse the same one
671 * we created before. We initialize it to the new object while all other
672 * options are kept the same. Notice that no rotation will be done here, as
673 * that's just an utility function that takes the coordinates set for each
674 * point of the map and transforms it accordingly.
675 * @until evas_map_util_points_populate_from_object_full
676 *
677 * This time the object is a bit farther into the screen, by using a @c z
678 * value higher than 0 to init the map. We also need to map the image used
679 * by the object, so Evas knows how to transform it properly. For this we
680 * use the evas_map_point_image_uv_set() to tell the map what coordinate
681 * within the image corresponds to each point of the map.
682 * @until evas_map_point_image_uv_set(m, 3
683 *
684 * This object will also be rotated, but in all three axis and around some
685 * other point, not its center, chosen mostly at random. If enabled, lighting
686 * will be applied to, from a light source at the center of the window.
687 * @until evas_object_map_enable_set
688 *
689 * For the third object we are doing, once more, a 3D rotation, but this time
690 * perspective will be applied to our map to make it look more realistic.
691 * The lighting source also follows the mouse cursor and it's possible to
692 * toggle backface culling, so that the object is hidden whenever we are
693 * not seeing its front face.
694 * @until evas_object_map_enable_set
695 *
696 * And we free this map, since since we messed too much with it and for the
697 * last object we want something cleaner.
698 * @until evas_map_free
699 *
700 * The last object is actually two. One image, with an image set to it, and
701 * one image proxying the first one with evas_object_image_source_set(). This
702 * way, the second object will show whatever content its source has.
703 * This time we'll be using a map more manually to simulate a simple reflection
704 * of the original image.
705 *
706 * We know that the reflection object is placed just like the original, so
707 * we take a shortcut by just getting the geometry of our to-be-mapped object.
708 * We also need to get the image size of the source.
709 * @until evas_object_image_size_get
710 *
711 * For this we'll create a map shaped so that it begins at the base of our
712 * image and it expands horizontally as it grows (downwards) in height.
713 * @until evas_map_point_coord_set(m, 3
714 *
715 * Since the reflection should show the image inverted, we need to map it
716 * this way. The first point of the map (top-left) will be mapped to the
717 * mapped to the first pixel of the last row. There's no horizontal reflection
718 * and we want the full width of the image, but as we map its upper side ww
719 * will only take two thirds of the image.
720 * @until evas_map_point_image_uv_set(m, 3
721 *
722 * Finally, to fade out our reflection we set the colors for each point in
723 * the map. The two at the top need to be visible, but we'll tone them down
724 * a bit and make them a bit translucent. The other two will go straight to
725 * full transparency. Evas interpolates the colors from one point to the next,
726 * so this will make them fade out.
727 * @until evas_object_map_enable_set
728 *
729 * Close up by freeing the map and do some other things needed to keep stuff
730 * moving in our animations and we are done.
731 * @until }
732 *
733 * The rest of the program is setup and listening to key events. Nothing that
734 * matters within the scope of this example, so we are going to skip it.
735 * Refer to it @ref evas-map-utils.c "here" however to see how everything
736 * fits together.
737 *
738 * @example evas-map-utils.c
739 */
740
741/**
742 * @page Example_Evas_Smart_Objects Evas object smart objects
743 * @dontinclude evas-smart-object.c
744 *
745 * In this example, we illustrate how to create and handle Evas smart objects.
746 *
747 * A smart object is one that provides custom functions to handle
748 * clipping, hiding, moving, resizing, color setting and more on @b
749 * child elements, automatically, for the smart object's user. They
750 * could be as simple as a group of objects that move together (see
751 * @ref Evas_Smart_Object_Clipped) or implementations of whole complex
752 * UI widgets, providing some intelligence (thus the name) and
753 * extension to simple Evas objects.
754 *
755 * Here, we create one as an example. What it does is to control (at
756 * maximum) 2 child objects, with regard to their geometries and
757 * colors. There can be a "left" child and a "right" one. The former
758 * will always occupy the top left quadrant of the smart object's
759 * area, while the latter will occupy the bottom right. The smart
760 * object will also contain an @b internal decorative border object,
761 * which will also be controlled by it, naturally.
762 *
763 * Here is where we add it to the canvas:
764 * @skip d.smt = evas_smart_example_add(d.evas);
765 * @until show
766 *
767 * The magic starts to happen in the @c evas_smart_example_add()
768 * function, which is one in the example smart object's defined @b
769 * interface. These should be the functions you would export to the
770 * users of your smart object. We made three for this one:
771 * - @c evas_smart_example_add(): add a new instance of the example
772 * smart object to a canvas
773 * - @c evas_smart_example_remove(): remove a given child of the smart
774 * object from it
775 * - @c evas_smart_example_set_left(): set the left child of the smart
776 * object
777 * - @c evas_smart_example_set_right(): set the right child of the
778 * smart object
779 *
780 * The object's creation takes place as:
781 * @dontinclude evas-smart-object.c
782 * @skip add a new example smart object to a canvas
783 * @until }
784 *
785 * Smart objects are defined by <b>smart classes</b>, which are structs
786 * defining their interfaces, or <b>smart functions</b> (see
787 * #Evas_Smart_Class, the base class for any smart object). As you
788 * see, one has to use the evas_object_smart_add() function to
789 * instantiate smart objects. Its second parameter is what matters --
790 * an #Evas_Smart struct, which contains all the smart class
791 * definitions (smart functions, smart callbacks, and the like). Note,
792 * however, that @c _evas_smart_example_smart_class_new() seems not to
793 * be defined in our example's code. That's because it came from a very
794 * handy <b>helper macro</b>:
795 * @dontinclude evas-smart-object.c
796 * @skip EVAS_SMART_SUBCLASS_NEW
797 * @until _smart_callbacks
798 * What it does is to @b subclass a given existing smart class, thus
799 * specializing it. This is very common and useful in Evas. There is a
800 * built-in smart object, the "clipped smart object", which implements
801 * a behavior mostly desired by many other smart object implementors:
802 * it will clip its children to its area and move them along with it,
803 * on evas_object_move() calls. Then, our example smart object will
804 * get that behavior for free.
805 *
806 * The first argument to the macro,
807 * @dontinclude evas-smart-object.c
808 * @skip _evas_smart_example_type
809 * @until _evas_smart_example_type
810 * will define the new smart class' name. The second tells the macro
811 * what is the @b prefix of the function it will be declaring with a @c
812 * _smart_set_user() suffix. On this function, we may override/extend
813 * any desired method from our parent smart class:
814 * @dontinclude evas-smart-object.c
815 * @skip setting our smart interface
816 * @until }
817 *
818 * The first function pointer's code will take place at an example
819 * smart object's @b creation time:
820 * @dontinclude evas-smart-object.c
821 * @skip create and setup
822 * @until }
823 *
824 * The #EVAS_SMART_DATA_ALLOC macro will take care of allocating our
825 * smart object data, which will be available on other contexts for us
826 * (mainly in our interface functions):
827 * @dontinclude evas-smart-object.c
828 * @skip typedef struct _Evas_Smart_Example_Data
829 * @until };
830 *
831 * See that, as we're inheriting from the clipped smart object's
832 * class, we @b must have their data struct as our first member. Other
833 * data of interest for us is a child members array and the border
834 * object's handle. The latter is what is created in the last
835 * mentioned function. Note how to tell Evas the border will be
836 * managed by our smart object from that time on:
837 * <code>evas_object_smart_member_add(priv->border, o);</code>.
838 * The counterpart of this function is exemplified on the smart
839 * object's interface function to remove children:
840 * @skip remove a child element
841 * @until set to
842 *
843 * At the end of that function we make use of an constant defined by
844 * the #EVAS_SMART_SUBCLASS_NEW: @c _evas_smart_example_parent_sc. It
845 * has the same prefix we passed to the macro, as you can see, and it
846 * holds a pointer to our @b parent smart class. Then, we can call the
847 * specialized method, itself, after our code. The @c del, @c hide, @c
848 * show and @c resize specializations are straightforward, we let the
849 * reader take a look at them below to check their behavior. What's
850 * interesting is the @c calculate one:
851 * @dontinclude evas-smart-object.c
852 * @skip act on child objects' properties
853 * @until setting
854 *
855 * This code will take place whenever the smart object itself is
856 * flagged "dirty", i.e., must be recalculated for rendering (that
857 * could come from changes on its clipper, resizing, moving,
858 * etc). There, we make sure the decorative border lies on the edges of
859 * the smart object and the children, if any, lie on their respective
860 * quadrants.
861 *
862 * After instantiating our smart object, we do some checks to exemplify
863 * some of the API on smart objects:
864 * @dontinclude evas-smart-object.c
865 * @skip ret = evas_object_smart_type_check
866 * @until "no"
867 * The evas_object_smart_type_check() one will assure we have the
868 * string naming our smart class really set to the live object. The
869 * evas_object_smart_clipped_clipper_get() exemplifies usage of
870 * "static clippers" -- clipped smart objects have their global
871 * clippers flagged static.
872 *
873 * Other important things we also exemplify here are <b>smart
874 * callbacks</b> and smart callback @b introspection:
875 * @dontinclude evas-smart-object.c
876 * @skip EVT_CHILDREN_NUMBER_CHANGED
877 * @until ;
878 *
879 * Here we declare our array of smart callback descriptions, which has
880 * one element only, in this case. That callback will take place, as
881 * the name indicates, whenever the number of member objects in our
882 * smart object example instance changes. That global array variable
883 * must be the last argument to #EVAS_SMART_SUBCLASS_NEW, so that it's
884 * registered as the <b>smart class</b>'s callbacks description.
885 *
886 * After we instantiate the smart object, we take a look on those
887 * descriptions and register a callback on that unique smart event:
888 * @dontinclude evas-smart-object.c
889 * @skip for (;
890 * @until focus_set
891 *
892 * The code of the callback will just print how many member objects we
893 * have, which is an integer argument of the callback itself, as
894 * flagged by its description:
895 * @dontinclude evas-smart-object.c
896 * @skip callback on number of member objects changed
897 * @until }
898 *
899 * One of the points at which we issue that callback is inside the @c
900 * evas_smart_example_remove(), code that was already shown.
901 *
902 * As in other examples, to interact with this one there's a command
903 * line interface. A help string can be asked for with the 'h' key:
904 * @dontinclude evas-smart-object.c
905 * @skip static const char *commands =
906 * @until ;
907 * Use 'l' and 'r' keys, to create new rectangles and place them on
908 * the left (@c evas_smart_example_set_left()) or right (@c
909 * evas_smart_example_set_right()) spots of our smart object,
910 * respectively. The 'w' command will remove all member objects from
911 * the smart object and delete them. The keyboard arrows will move the
912 * smart object along the canvas. See how it takes any child objects
913 * with it during its movement. The 'd' and 'i' keys will increase or
914 * decrease the smart object's size -- see how it affects the
915 * children's sizes, too. Finally, 'c' will change the color of the
916 * smart object's clipper (which is the exact internal clipper coming
917 * from a clipped smart object):
918 * @dontinclude evas-smart-object.c
919 * @skip d.clipper =
920 * @until .a);
921 *
922 * "Real life" examples of smart objects are Edje and Emotion objects:
923 * they both have independent libraries implementing their
924 * behavior. The full example follows.
925 *
926 * @include evas-smart-object.c
927 * @example evas-smart-object.c
928 */
929
930/**
931 * @page Example_Evas_Smart_Interfaces Evas object smart interfaces
932 * @dontinclude evas-smart-interface.c
933 *
934 * In this example, we illustrate how to create and handle Evas smart
935 * @b interfaces. Note that we use the same code base of the @ref
936 * Example_Evas_Smart_Objects example, here. We just augment it with
937 * an interfaces demonstration.
938 *
939 * A smart interface is just a functions interface a given smart
940 * objcet is declaring to support and or use. In Evas, interfaces are
941 * very simple: no interface inheritance, no interface
942 * overriding. Their purpose is to extend an object's capabilities and
943 * behaviour beyound the sub-classing schema.
944 *
945 * Here, together with a custom smart object, we create and declare
946 * the object as using an Evas interface. It'll have a custom
947 * function, too, besides the @c add() and del() obligatory ones. To
948 * demonstrate interface data, which is bound to object @b instances,
949 * we'll have a string as this data.
950 *
951 * Here is where we declare our interface:
952 * @skip static const char iface1_data[]
953 * @until (Evas_Smart_Interface *)&iface1, NULL
954 * @until };
955 *
956 * Note that there's error checking for interfaces creation, by means of
957 * the @c add() method's return value (@c _iface1_add(), here).
958 *
959 * Now note that here we are filling in the interface's fields dinamically.
960 * Let's move on to that code region:
961 *
962 * @dontinclude evas-smart-interface.c
963 * @skip iface = (Evas_Smart_Example_Interface *)&iface1;
964 * @until d.smt = evas_smart_example_add(d.evas);
965 *
966 * As important as setting the function pointers, is declaring the @c
967 * private_size as to match exactly the size of the data blob we want
968 * to have allocated for us by Evas. This will happen automatically
969 * inside @c evas_smart_example_add(). Later, on this code, we deal
970 * exactly with that data blob, more specifically writing on it (as
971 * it's not done inside @c _iface1_add(), here:
972 *
973 * @dontinclude evas-smart-interface.c
974 * @skip iface = (Evas_Smart_Example_Interface *)evas_object_smart_interface_get
975 * @until }
976 *
977 * Before accessing the interface data, we exercise the interface
978 * fetching call evas_object_smart_interface_get(), with the name
979 * string we used to be interface's name. With that handle in hands,
980 * we issue evas_object_smart_interface_data_get() and write the
981 * string we want as data on that memory region. That will make up for
982 * the string you get on @c _iface1_del().
983 *
984 * The full example follows.
985 *
986 * @include evas-smart-interface.c
987 * @example evas-smart-interface.c
988 */
989
990/**
991 * @page Example_Evas_Text Evas text object example
992 *
993 * In this example, we illustrate how to use text objects in various
994 * manners.
995 *
996 * We place, in the canvas, a text object along with a border image to
997 * delimit its geometry. After we instantiate the text object, we set
998 * lots of properties on it to the initial ones from a preset list,
999 * which has the following declaration:
1000 * @dontinclude evas-text.c
1001 * @skip init values
1002 * @until };
1003 *
1004 * Then, we set the text string itself, on it, with
1005 * evas_object_text_text_set(). We set an explicit size of 30 points
1006 * for our font, as you could see, what we check back with the
1007 * getter evas_object_text_font_get().
1008 *
1009 * Look at how it translates to code:
1010 * @dontinclude evas-text.c
1011 * @skip evas_object_text_add
1012 * @until fprintf
1013 *
1014 * Like in other Evas examples, one interacts with it by means of key
1015 * commands:
1016 * @dontinclude evas-text.c
1017 * @skip static const char *commands
1018 * @until ;
1019 *
1020 * Use the 't' key to exercise the evas_object_text_style_set()
1021 * function on the text -- it will cycle through all styles on
1022 * #Evas_Text_Style_Type (note we start on #EVAS_TEXT_STYLE_PLAIN,
1023 * thus with no effects on it) and, with other keys, you'll be able to
1024 * set properties applicable to individual styles on the text object.
1025 *
1026 * The 'z' key will change the text's @b size, keeping the font family
1027 * for it. Use 'f' to change the font, keeping the last size
1028 * set. There are three font families the example will cycle through:
1029 *
1030 * The 'b' command shows us that evas_object_color_set(), on a given
1031 * text object, will change the text's @b base color. Experiment with
1032 * it, which will cycle through the colors in the <c>.text</c> list in
1033 * @c init_data.
1034 *
1035 * The 's', 'o', 'w' and 'g' keys will make the text object to cycle
1036 * to the preset values on colors for shadow, outline, glow and 'glow
1037 * 2' effects, respectively. Naturally, they will only take effect on
1038 * the text styles which resemble them.
1039 *
1040 * The full example follows.
1041 *
1042 * @include evas-text.c
1043 * @example evas-text.c
1044 */
1045
1046/**
1047 * @page tutorial_table Table Smart Object example
1048 *
1049 * This example will arrange rectangles of different sizes(and colors) in a
1050 * table. While it's possible to create the same layout we are doing here by
1051 * positioning each rectangle independently, using a table makes it a lot
1052 * easier, since the table will control layout of all the objects, allowing you
1053 * to move, resize or hide the entire table.
1054 *
1055 * We'll start with creating the table, setting it to
1056 * EVAS_OBJECT_TABLE_HOMOGENEOUS_NONE to have maximum flexibility and setting
1057 * its padding to 0:
1058 * @dontinclude evas-table.c
1059 * @skip object_table
1060 * @until show
1061 *
1062 * We then create each rectangle and add it to the table:
1063 * @until table_pack
1064 * @until table_pack
1065 * @until table_pack
1066 * @until table_pack
1067 * @note Each rectangle has a different minimum size based on how many rows and
1068 * columns it will occupy.
1069 *
1070 * The full source for this example follow:
1071 * @include evas-table.c
1072 * @example evas-table.c
1073 */