From 6aa497cb88b0716e82204f070df5d35370e2bca7 Mon Sep 17 00:00:00 2001 From: "Jonas M. Gastal" Date: Tue, 13 Mar 2012 18:29:31 +0000 Subject: [PATCH] Better ecore event docs. SVN revision: 69299 --- legacy/ecore/src/lib/ecore/Ecore.h | 67 ++++++++++++++--------- legacy/ecore/src/lib/ecore/ecore_events.c | 23 ++++---- 2 files changed, 52 insertions(+), 38 deletions(-) diff --git a/legacy/ecore/src/lib/ecore/Ecore.h b/legacy/ecore/src/lib/ecore/Ecore.h index 1ed0d1156a..a6d1f9f6e8 100644 --- a/legacy/ecore/src/lib/ecore/Ecore.h +++ b/legacy/ecore/src/lib/ecore/Ecore.h @@ -522,34 +522,51 @@ EAPI int ecore_thread_main_loop_end(void); /** * @defgroup Ecore_Event_Group Ecore Event functions * - * Ecore events are used to wake up the Ecore main loop to warn - * about state changes, tasks completed, data available for reading - * or writing, etc. They are the base of the event oriented - * programming. + * Ecore events provide two main features that are of use to those using ecore: + * creating events and being notified of events. Those two will usually be used + * in different contexts, creating events is mainly done by libraries wrapping + * some system functionality while being notified of events is mainly a + * necessity of applications. * - * The idea is to write many functions (callbacks) that will be - * registered to specific events, and called when these events - * happen. This way, when the system state changes (a mouse click is - * detected, a key is pressed, or the content of a file changes, for - * example), the respective callbacks will be called with some - * information about that event. Usually the function/callback will - * have a data pointer to the event info (the position in the screen - * where the mouse was clicked, the name of the key that was - * pressed, or the name of the file that has changed). + * For a program to be notified of events it's interested in it needs to have a + * function to process the event and to register that function as the callback + * to the event, that's all: + * @code + * ecore_event_handler_add(EVENT_TYPE, _my_event_handler, some_data); + * ... + * static Eina_Bool + * _my_event_handler(void *data, int type, void *event) + * { + * //data is some_data + * //event is provided by whoever created the event + * //Do really cool stuff with event + * } + * @endcode * - * The basic usage, when one needs to watch for an existing event, - * is to register a callback to it using ecore_event_add(). Of - * course it's necessary to know beforehand what are the types of - * events that the system/library will emmit. This should be - * available with the documentation from that system/library. + * One very important thing to note here is the @c EVENT_TYPE, to register a + * handler for an event you must know it's type before hand. This information + * can be found on the documentation of the library emitting the signal, so, + * for example, for events related to windowing one would look in @ref + * Ecore_Evas_Group. * - * When writing a library or group of functions that need to inform - * about something, and you already are running on top of a main - * loop, it is usually a good approach to use events. This way you - * allow others to register as many callbacks as necessary to this - * event, and don't have to care about who is registering to it. The - * functions ecore_event_type_new() and ecore_event_add() are - * available for this purpose. + * Examples of libraries that integrate into ecore's main loop by providing + * events are @ref Ecore_Con_Group, @ref Ecore_Evas_Group and @ref + * Ecore_Exe_Group amongst others. This usage can be divided into two parts, + * setup and adding events. The setup is very simple, all that needs doing is + * getting a type id for the event: + * @code + * int MY_EV_TYPE = ecore_event_type_new(); + * @endcode + * @note This variable should be declared in the header since it'll be needed by + * anyone wishing to register a handler to your event. + * + * The complexity of adding of an event to the queue depends on whether that + * event sends uses @c event, if it doesn't it a one-liner: + * @code + * ecore_event_add(MY_EV_TYPE, NULL, NULL, NULL); + * @endcode + * The usage when an @c event is needed is not that much more complex and can be + * seen in @ref ecore_event_add. * * Example that deals with events: * diff --git a/legacy/ecore/src/lib/ecore/ecore_events.c b/legacy/ecore/src/lib/ecore/ecore_events.c index be2b5e283f..e181248a5d 100644 --- a/legacy/ecore/src/lib/ecore/ecore_events.c +++ b/legacy/ecore/src/lib/ecore/ecore_events.c @@ -242,22 +242,19 @@ _ecore_event_generic_free(void *data __UNUSED__, } /** - * Add an event to the event queue. + * @brief Add an event to the event queue. * @param type The event type to add to the end of the event queue - * @param ev The private data structure for this event type - * @param func_free The function to be called to free this private structure + * @param ev The data structure passed as @c event to event handlers + * @param func_free The function to be called to free @a ev * @param data The data pointer to be passed to the free function - * @return A Handle for that event + * @return A Handle for that event on success, otherwise NULL * - * On success this function returns a handle to an event on the event queue, or - * NULL if it fails. If it succeeds, an event of type @p type will be added - * to the queue for processing by event handlers added by - * ecore_event_handler_add(). The @p ev parameter will be a pointer to the event - * private data that is specific to that event type. When the event is no - * longer needed, @p func_free will be called and passed the private structure - * pointer for cleaning up. If @p func_free is NULL, free() will be called - * with the private structure pointer. - * func_free is passed @p data as its data parameter. + * If it succeeds, an event of type @a type will be added to the queue for + * processing by event handlers added by ecore_event_handler_add(). The @a ev + * parameter will be passed as the @c event parameter of the handler. When the + * event is no longer needed, @a func_free will be called and passed @a ev for + * cleaning up. If @p func_free is NULL, free() will be called with the private + * structure pointer. */ EAPI Ecore_Event * ecore_event_add(int type,