2011-06-22 08:01:55 -07:00
|
|
|
/**
|
|
|
|
* @page Examples Examples
|
|
|
|
*
|
|
|
|
* Here is a page with some Ecore examples explained:
|
|
|
|
*
|
|
|
|
* @li @ref ecore_time_example_c
|
2011-06-22 11:29:38 -07:00
|
|
|
* @li @ref ecore_idler_example_c
|
2011-06-27 12:42:28 -07:00
|
|
|
* @li @ref ecore_job_example_c
|
|
|
|
* @li @ref ecore_event_example_c
|
2011-06-22 08:01:55 -07:00
|
|
|
*
|
|
|
|
*/
|
|
|
|
|
|
|
|
/**
|
|
|
|
* @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
|
|
|
|
*/
|
|
|
|
|
2011-06-22 11:29:38 -07:00
|
|
|
/**
|
|
|
|
* @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
|
2011-06-22 15:56:36 -07:00
|
|
|
* it returns @ref ECORE_CALLBACK_DONE to indicate that the event shouldn't be
|
|
|
|
* handled by any other callback.
|
2011-06-22 11:29:38 -07:00
|
|
|
*
|
|
|
|
* 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
|
|
|
|
*/
|
|
|
|
|
2011-06-22 13:54:32 -07:00
|
|
|
/**
|
|
|
|
* @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
|
|
|
|
*/
|
|
|
|
|
2011-06-27 12:42:28 -07:00
|
|
|
/**
|
|
|
|
* @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.
|
|
|
|
*/
|
|
|
|
|
2011-06-22 11:29:38 -07:00
|
|
|
/**
|
|
|
|
* @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".
|
|
|
|
*/
|
|
|
|
|
2011-06-22 13:54:32 -07:00
|
|
|
/**
|
|
|
|
* @example ecore_job_example.c
|
|
|
|
* This example shows how to use an @ref Ecore_Job. See
|
|
|
|
* @ref ecore_job_example_c "the explanation here".
|
|
|
|
*/
|
|
|
|
|
2011-06-22 08:01:55 -07:00
|
|
|
/**
|
|
|
|
* @example ecore_time_example.c
|
|
|
|
* Shows the difference between the three time functions. See @ref
|
|
|
|
* ecore_time_example_c "the example explained".
|
|
|
|
*/
|
|
|
|
|
2011-06-27 12:42:28 -07:00
|
|
|
/**
|
|
|
|
* @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".
|
|
|
|
*/
|
|
|
|
|
2011-06-22 08:01:55 -07:00
|
|
|
/**
|
|
|
|
* @example ecore_fd_handler_example.c
|
|
|
|
* Shows how to use fd handlers.
|
|
|
|
*/
|
|
|
|
|