efl/legacy/ecore/doc/examples.dox

/**
 * @page Examples Examples
 *
 * Here is a page with some Ecore examples explained:
 *
 * @li @ref ecore_time_example_c
 * @li @ref ecore_idler_example_c
 * @li @ref ecore_job_example_c
 * @li @ref ecore_event_example_c
 *
 */

/**
 * @page ecore_time_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 mainloop 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_example.c
 */

/**
 * @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_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.c "here".
 *
 * Let's start the example from the beginning:
 *
 * @dontinclude ecore_event_example.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.
 */

/**
 * @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_example.c
 * Shows the difference between the three time functions. See @ref
 * ecore_time_example_c "the example explained".
 */

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

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