From 4414d8d5134c9c3f232c788367d656b3b5fce161 Mon Sep 17 00:00:00 2001 From: gastal Date: Wed, 14 Mar 2012 13:22:20 +0000 Subject: [PATCH] Ecore event functions docs improvements. Moved docs to header file. Fixed some typos. Added @brief. Add failure information to @return. Other random improvements. git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/ecore@69337 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- src/lib/ecore/Ecore.h | 140 +++++++++++++++++++++++++++++++++++++++ src/lib/ecore/ecore_events.c | 153 ------------------------------------------- 2 files changed, 140 insertions(+), 153 deletions(-) diff --git a/src/lib/ecore/Ecore.h b/src/lib/ecore/Ecore.h index a6d1f9f..f656d67 100644 --- a/src/lib/ecore/Ecore.h +++ b/src/lib/ecore/Ecore.h @@ -664,16 +664,156 @@ struct _Ecore_Event_Signal_Realtime /** Realtime event */ #endif }; +/** + * @brief Add an event handler. + * @param type The type of the event this handler will get called for + * @param func The function to call when the event is found in the queue + * @param data A data pointer to pass to the called function @p func + * @return A new Event handler, or NULL on failure + * + * Add an event handler to the list of handlers. This will, on success, return + * a handle to the event handler object that was created, that can be used + * later to remove the handler using ecore_event_handler_del(). The @p type + * parameter is the integer of the event type that will trigger this callback + * to be called. The callback @p func is called when this event is processed + * and will be passed the event type, a pointer to the private event + * structure that is specific to that event type, and a data pointer that is + * provided in this call as the @p data parameter. + * + * When the callback @p func is called, it must return 1 or 0. If it returns + * 1 (or ECORE_CALLBACK_PASS_ON), It will keep being called as per normal, for + * each handler set up for that event type. If it returns 0 (or + * ECORE_CALLBACK_DONE), it will cease processing handlers for that particular + * event, so all handler set to handle that event type that have not already + * been called, will not be. + */ EAPI Ecore_Event_Handler *ecore_event_handler_add(int type, Ecore_Event_Handler_Cb func, const void *data); +/** + * @brief Delete an event handler. + * @param event_handler Event handler handle to delete + * @return Data passed to handler + * + * Delete a specified event handler from the handler list. On success this will + * delete the event handler and return the pointer passed as @p data when the + * handler was added by ecore_event_handler_add(). On failure NULL will be + * returned. Once a handler is deleted it will no longer be called. + */ EAPI void *ecore_event_handler_del(Ecore_Event_Handler *event_handler); +/** + * @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 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 on success, otherwise NULL + * + * 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, void *ev, Ecore_End_Cb func_free, void *data); +/** + * @brief Delete an event from the queue. + * @param event The event handle to delete + * @return The data pointer originally set for the event free function + * + * This deletes the event @p event from the event queue, and returns the + * @p data parameter originally set when adding it with ecore_event_add(). This + * does not immediately call the free function, and it may be called later on + * cleanup, and so if the free function depends on the data pointer to work, + * you should defer cleaning of this till the free function is called later. + */ EAPI void *ecore_event_del(Ecore_Event *event); +/** + * @brief Get the data associated with an #Ecore_Event_Handler + * @param eh The event handler + * @return The data + * + * This function returns the data previously associated with @p eh by + * ecore_event_handler_add(). + */ EAPI void *ecore_event_handler_data_get(Ecore_Event_Handler *eh); +/** + * @brief Set the data associated with an #Ecore_Event_Handler + * @param eh The event handler + * @param data The data to associate + * @return The previous data + * + * This function sets @p data to @p eh and returns the old data pointer + * which was previously associated with @p eh by ecore_event_handler_add(). + */ EAPI void *ecore_event_handler_data_set(Ecore_Event_Handler *eh, const void *data); +/** + * @brief Allocate a new event type id sensibly and return the new id. + * @return A new event type id. + * + * This function allocates a new event type id and returns it. Once an event + * type has been allocated it can never be de-allocated during the life of + * the program. There is no guarantee of the contents of this event ID, or how + * it is calculated, except that the ID will be unique to the current instance + * of the process. + */ EAPI int ecore_event_type_new(void); +/** + * @brief Add a filter the current event queue. + * + * @param func_start Function to call just before filtering and return data + * @param func_filter Function to call on each event + * @param func_end Function to call after the queue has been filtered + * @param data Data to pass to the filter functions + * @return A filter handle on success, NULL otherwise + * + * Adds a callback to filter events from the event queue. Filters are called on + * the queue just before Event handler processing to try and remove redundant + * events. Just as processing is about to start @a func_start is called and + * passed the @a data pointer, the return value of this functions is passed to + * @a func_filter as loop_data. @a func_filter is also passed @a data and the + * event type and event structure. If this @a func_filter returns #EINA_FALSE, + * the event is removed from the queue, if it returns #EINA_TRUE, the event is + * kept. When processing is finished @p func_end is called and is passed the + * loop_data(returned by @c func_start) and @p data pointer to clean up. + */ EAPI Ecore_Event_Filter *ecore_event_filter_add(Ecore_Data_Cb func_start, Ecore_Filter_Cb func_filter, Ecore_End_Cb func_end, const void *data); +/** + * @brief Delete an event filter. + * @param ef The event filter handle + * @return The data set for the filter on success, NULL otherwise + * + * Delete a filter that has been added by its @p ef handle. + */ EAPI void *ecore_event_filter_del(Ecore_Event_Filter *ef); +/** + * @brief Return the current event type being handled. + * @return The current event type being handled if inside a handler callback, + * ECORE_EVENT_NONE otherwise + * + * If the program is currently inside an Ecore event handler callback this + * will return the type of the current event being processed. + * + * This is useful when certain Ecore modules such as Ecore_Evas "swallow" + * events and not all the original information is passed on. In special cases + * this extra information may be useful or needed and using this call can let + * the program know if the event type being handled is one it wants to get more + * information about. + */ EAPI int ecore_event_current_type_get(void); +/** + * @brief Return the current event type pointer handled. + * @return The current event pointer being handled if inside a handler callback, + * NULL otherwise + * + * If the program is currently inside an Ecore event handler callback this + * will return the pointer of the current event being processed. + * + * This is useful when certain Ecore modules such as Ecore_Evas "swallow" + * events and not all the original information is passed on. In special cases + * this extra information may be useful or needed and using this call can let + * the program access the event data if the type of the event is handled by + * the program. + */ EAPI void *ecore_event_current_event_get(void); /** diff --git a/src/lib/ecore/ecore_events.c b/src/lib/ecore/ecore_events.c index e181248..500cf74 100644 --- a/src/lib/ecore/ecore_events.c +++ b/src/lib/ecore/ecore_events.c @@ -72,35 +72,6 @@ static void *ecore_raw_event_event = NULL; static void _ecore_event_purge_deleted(void); static void *_ecore_event_del(Ecore_Event *event); -/** - * @addtogroup Ecore_Event_Group - * - * @{ - */ - -/** - * Add an event handler. - * @param type The type of the event this handler will get called for - * @param func The function to call when the event is found in the queue - * @param data A data pointer to pass to the called function @p func - * @return A new Event handler, or NULL on failure - * - * Add an event handler to the list of handlers. This will, on success, return - * a handle to the event handler object that was created, that can be used - * later to remove the handler using ecore_event_handler_del(). The @p type - * parameter is the integer of the event type that will trigger this callback - * to be called. The callback @p func is called when this event is processed - * and will be passed the event type, a pointer to the private event - * structure that is specific to that event type, and a data pointer that is - * provided in this call as the @p data parameter. - * - * When the callback @p func is called, it must return 1 or 0. If it returns - * 1 (or ECORE_CALLBACK_PASS_ON), It will keep being called as per normal, for - * each handler set up for that event type. If it returns 0 (or - * ECORE_CALLBACK_DONE), it will cease processing handlers for that particular - * event, so all handler set to handle that event type that have not already - * been called, will not be. - */ EAPI Ecore_Event_Handler * ecore_event_handler_add(int type, Ecore_Event_Handler_Cb func, @@ -151,16 +122,6 @@ unlock: return eh; } -/** - * Delete an event handler. - * @param event_handler Event handler handle to delete - * @return Data passed to handler - * - * Delete a specified event handler from the handler list. On success this will - * delete the event handler and return the pointer passed as @p data when the - * handler was added by ecore_event_handler_add(). On failure NULL will be - * returned. Once a handler is deleted it will no longer be called. - */ EAPI void * ecore_event_handler_del(Ecore_Event_Handler *event_handler) { @@ -180,14 +141,6 @@ unlock: return data; } -/** - * @brief Get the data associated with an #Ecore_Event_Handler - * @param eh The event handler - * @return The data - * - * This function returns the data previously associated with @p eh by - * ecore_event_handler_add(). - */ EAPI void * ecore_event_handler_data_get(Ecore_Event_Handler *eh) { @@ -205,15 +158,6 @@ unlock: return data; } -/** - * @brief Set the data associated with an #Ecore_Event_Handler - * @param eh The event handler - * @param data The data to associate - * @return The previous data - * - * This function sets @p data to @p eh and returns the old data pointer - * which was previously associated with @p eh by ecore_event_handler_add(). - */ EAPI void * ecore_event_handler_data_set(Ecore_Event_Handler *eh, const void *data) @@ -241,21 +185,6 @@ _ecore_event_generic_free(void *data __UNUSED__, free(event); } -/** - * @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 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 on success, otherwise NULL - * - * 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, void *ev, @@ -276,17 +205,6 @@ unlock: return event; } -/** - * Delete an event from the queue. - * @param event The event handle to delete - * @return The data pointer originally set for the event free function - * - * This deletes the event @p event from the event queue, and returns the - * @p data parameer originally set when adding it with ecore_event_add(). This - * does not immediately call the free function, and it may be called later on - * cleanup, and so if the free function depends on the data pointer to work, - * you should defer cleaning of this till the free function is called later. - */ EAPI void * ecore_event_del(Ecore_Event *event) { @@ -306,16 +224,6 @@ unlock: return data; } -/** - * Allocate a new event type id sensibly and return the new id. - * @return A new event type id. - * - * This function allocates a new event type id and returns it. Once an event - * type has been allocated it can never be de-allocated during the life of - * the program. There is no guarantee of the contents of this event ID, or how - * it is calculated, except that the ID will be unique to the current instance - * of the process. - */ EAPI int ecore_event_type_new(void) { @@ -328,26 +236,6 @@ ecore_event_type_new(void) return id; } -/** - * Add a filter the current event queue. - * @param func_start Function to call just before filtering and return data - * @param func_filter Function to call on each event - * @param func_end Function to call after the queu has been filtered - * @param data Data to pass to the filter functions - * @return A filter handle - * - * This adds a filter to call callbacks to loop through the event queue and - * filter events out of the queue. On failure NULL is returned. On success a - * Filter handle is returned. Filters are called on the queue just before - * Event handler processing to try and remove redundant events. Just as - * processing starts @p func_start is called and passed the @p data pointer. - * This function returns a pointer that is used as loop_data that is now passed to - * @p func_filter as loop_data. @p func_filter is also passed @p data and the - * event type and private event structure. If this callback returns 0, the - * event is removed from the queue. If it returns 1, the event is kept. When - * processing is finished @p func_end is called and is passed the loop_data - * and @p data pointer to clean up. - */ EAPI Ecore_Event_Filter * ecore_event_filter_add(Ecore_Data_Cb func_start, Ecore_Filter_Cb func_filter, @@ -371,15 +259,6 @@ unlock: return ef; } -/** - * Delete an event filter. - * @param ef The event filter handle - * @return The data set for the filter - * - * Delete a filter that has been added by its @p ef handle. On success this - * will return the data pointer set when this filter was added. On failure - * NULL is returned. - */ EAPI void * ecore_event_filter_del(Ecore_Event_Filter *ef) { @@ -401,50 +280,18 @@ unlock: return data; } -/** - * Return the current event type being handled. - * @return The current event type being handled if inside a handler callback - * - * If the program is currently inside an Ecore event handler callback this - * will return the type of the current event being processed. If Ecore is - * not inside an event handler, ECORE_EVENT_NONE is returned. - * - * This is useful when certain Ecore modules such as Ecore_Evas "swallow" - * events and not all the original information is passed on. In special cases - * this extra information may be useful or needed and using this call can let - * the program know if the event type being handled is one it wants to get more - * information about. - */ EAPI int ecore_event_current_type_get(void) { return ecore_raw_event_type; } -/** - * Return the current event type pointer handled. - * @return The current event pointer being handled if inside a handler callback - * - * If the program is currently inside an Ecore event handler callback this - * will return the pointer of the current event being processed. If Ecore is - * not inside an event handler, NULL will be returned. - * - * This is useful when certain Ecore modules such as Ecore_Evas "swallow" - * events and not all the original information is passed on. In special cases - * this extra information may be useful or needed and using this call can let - * the program access the event data if the type of the event is handled by - * the program. - */ EAPI void * ecore_event_current_event_get(void) { return ecore_raw_event_event; } -/** - * @} - */ - EAPI void * _ecore_event_handler_del(Ecore_Event_Handler *event_handler) { -- 2.7.4