[ecore_evas][ecore_x] Added per-window profile to support multi-head display.

[framework/uifw/ecore.git] / doc / examples.dox

/**
 * @page Examples Examples
 *
 * Here is a page with some Ecore examples explained:
 *
 * @li @ref ecore_time_functions_example_c
 * @li @ref ecore_timer_example_c
 * @li @ref ecore_idler_example_c
 * @li @ref ecore_job_example_c
 * @li @ref ecore_event_example_01_c
 * @li @ref ecore_event_example_02_c
 * @li @ref ecore_fd_handler_example_c
 * @li @ref ecore_poller_example_c
 * @li @ref ecore_con_lookup_example_c
 * @li @ref ecore_con_url_download_example_c
 * @li @ref ecore_con_server_simple_example_c
 * @li @ref ecore_con_client_simple_example_c
 * @li @ref ecore_evas_callbacks_example_c
 * @li @ref ecore_evas_object_example_c
 * @li @ref ecore_evas_basics_example_c
 * @li @ref Ecore_Evas_Window_Sizes_Example_c
 * @li @ref Ecore_Evas_Buffer_Example_01_c
 * @li @ref Ecore_Evas_Buffer_Example_02_c
 */

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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