From cb66b9c5400e14ce029f72b7550748cc9bc7cda1 Mon Sep 17 00:00:00 2001 From: glima Date: Thu, 9 Jun 2011 17:01:21 +0000 Subject: [PATCH] [evas] Reorganizing evas events documenting blocks. git-svn-id: http://svn.enlightenment.org/svn/e/trunk/evas@60144 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- src/lib/Evas.h | 380 ++++++++++++++++++++++++++++++--------------------------- 1 file changed, 199 insertions(+), 181 deletions(-) diff --git a/src/lib/Evas.h b/src/lib/Evas.h index 9749317..9d12854 100644 --- a/src/lib/Evas.h +++ b/src/lib/Evas.h @@ -1881,12 +1881,196 @@ EAPI Eina_Bool evas_pointer_inside_get (const Evas *e) EINA_WA EAPI void evas_sync(Evas *e) EINA_ARG_NONNULL(1); /** + * @defgroup Evas_Canvas_Events Canvas Events + * + * Canvas generates some events + * + * @ingroup Evas_Canvas + */ + +/** + * @addtogroup Evas_Canvas_Events + * @{ + */ + +/** + * Add a callback function to the canvas. + * + * @param e Canvas to attach a callback to + * @param type The type of event that will trigger the callback + * @param func The function to be called when the event is triggered + * @param data The data pointer to be passed to @p func + * + * This function adds a function callback to the canvas when the event + * of type @p type occurs on canvas @p e. The function is @p func. + * + * In the event of a memory allocation error during addition of the + * callback to the canvas, evas_alloc_error() should be used to + * determine the nature of the error, if any, and the program should + * sensibly try and recover. + * + * The function will be passed the pointer @p data when it is + * called. A callback function must look like this: + * + * @code + * void callback (void *data, Evas *e, void *event_info); + * @endcode + * + * The first parameter @p data in this function will be the same value + * passed to evas_event_callback_add() as the @p data parameter. The + * second parameter @p e is the canvas handle on which the event + * occurred. The third parameter @p event_info is a pointer to a data + * structure that may or may not be passed to the callback, depending + * on the event type that triggered the callback. + * + * The event type @p type to trigger the function may be one of + * #EVAS_CALLBACK_RENDER_FLUSH_PRE, #EVAS_CALLBACK_RENDER_FLUSH_POST, + * #EVAS_CALLBACK_CANVAS_FOCUS_IN, #EVAS_CALLBACK_CANVAS_FOCUS_OUT. + * This determines the kind of event that will trigger the callback to + * be called. So far none of the event types provide useful data, so + * in all of them @p event_info pointer is @c NULL. + * + * Example: + * @code + * extern Evas *e; + * extern void *my_data; + * void focus_in_callback(void *data, Evas *e, void *event_info); + * void focus_out_callback(void *data, Evas *e, void *event_info); + * + * evas_event_callback_add(e, EVAS_CALLBACK_CANVAS_FOCUS_IN, focus_in_callback, my_data); + * if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE) + * { + * fprintf(stderr, "ERROR: Callback registering failed! Abort!\n"); + * exit(-1); + * } + * evas_event_callback_add(e, EVAS_CALLBACK_CANVAS_FOCUS_OUT, focus_out_callback, my_data); + * if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE) + * { + * fprintf(stderr, "ERROR: Callback registering failed! Abort!\n"); + * exit(-1); + * } + * @endcode + */ +EAPI void evas_event_callback_add (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3); + +/** + * Delete a callback function from the canvas. + * + * @param e Canvas to remove a callback from + * @param type The type of event that was triggering the callback + * @param func The function that was to be called when the event was triggered + * @return The data pointer that was to be passed to the callback + * + * This function removes the most recently added callback from the + * canvas @p e which was triggered by the event type @p type and was + * calling the function @p func when triggered. If the removal is + * successful it will also return the data pointer that was passed to + * evas_event_callback_add() when the callback was added to the + * canvas. If not successful NULL will be returned. + * + * Example: + * @code + * extern Evas *e; + * void *my_data; + * void focus_in_callback(void *data, Evas *e, void *event_info); + * + * my_data = evas_event_callback_del(ebject, EVAS_CALLBACK_CANVAS_FOCUS_IN, focus_in_callback); + * @endcode + */ +EAPI void *evas_event_callback_del (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func) EINA_ARG_NONNULL(1, 3); + +/** + * Delete a callback function from the canvas. + * + * @param e Canvas to remove a callback from + * @param type The type of event that was triggering the callback + * @param func The function that was to be called when the event was triggered + * @param data The data pointer that was to be passed to the callback + * @return The data pointer that was to be passed to the callback + * + * This function removes the most recently added callback from the + * canvas @p e which was triggered by the event type @p type and was + * calling the function @p func with data @p data when triggered. If + * the removal is successful it will also return the data pointer that + * was passed to evas_event_callback_add() (that will be the same as + * the parameter) when the callback was added to the canvas. If not + * successful NULL will be returned. + * + * Example: + * @code + * extern Evas *e; + * void *my_data; + * void focus_in_callback(void *data, Evas *e, void *event_info); + * + * my_data = evas_event_callback_del_full(ebject, EVAS_CALLBACK_CANVAS_FOCUS_IN, focus_in_callback, my_data); + * @endcode + */ +EAPI void *evas_event_callback_del_full (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3); + +/** + * Push a callback on the post-event callback stack + * + * @param e Canvas to push the callback on + * @param func The function that to be called when the stack is unwound + * @param data The data pointer to be passed to the callback + * + * Evas has a stack of callbacks that get called after all the callbacks for + * an event have triggered (all the objects it triggers on and al the callbacks + * in each object triggered). When all these have been called, the stack is + * unwond from most recently to least recently pushed item and removed from the + * stack calling the callback set for it. + * + * This is intended for doing reverse logic-like processing, example - when a + * child object that happens to get the event later is meant to be able to + * "steal" functions from a parent and thus on unwind of this stack hav its + * function called first, thus being able to set flags, or return 0 from the + * post-callback that stops all other post-callbacks in the current stack from + * being called (thus basically allowing a child to take control, if the event + * callback prepares information ready for taking action, but the post callback + * actually does the action). + * + */ +EAPI void evas_post_event_callback_push (Evas *e, Evas_Object_Event_Post_Cb func, const void *data); + +/** + * Remove a callback from the post-event callback stack + * + * @param e Canvas to push the callback on + * @param func The function that to be called when the stack is unwound + * + * This removes a callback from the stack added with + * evas_post_event_callback_push(). The first instance of the function in + * the callback stack is removed from being executed when the stack is + * unwound. Further instances may still be run on unwind. + */ +EAPI void evas_post_event_callback_remove (Evas *e, Evas_Object_Event_Post_Cb func); + +/** + * Remove a callback from the post-event callback stack + * + * @param e Canvas to push the callback on + * @param func The function that to be called when the stack is unwound + * @param data The data pointer to be passed to the callback + * + * This removes a callback from the stack added with + * evas_post_event_callback_push(). The first instance of the function and data + * in the callback stack is removed from being executed when the stack is + * unwound. Further instances may still be run on unwind. + */ +EAPI void evas_post_event_callback_remove_full (Evas *e, Evas_Object_Event_Post_Cb func, const void *data); + +/** * @defgroup Evas_Event_Freezing_Group Event Freezing Functions * * Functions that deal with the freezing of event processing of an * evas. * - * @ingroup Evas_Canvas + * @ingroup Evas_Canvas_Events + */ + +/** + * @addtogroup Evas_Event_Freezing_Group + * @{ */ /** @@ -1948,15 +2132,19 @@ EAPI int evas_event_freeze_get (const Evas *e) EINA_WA /** * After thaw of a canvas, re-evaluate the state of objects and call callbacks - * + * * @param e The canvas to evaluate after a thaw - * + * * This is normally called after evas_event_thaw() to re-evaluate mouse * containment and other states and thus also call callbacks for mouse in and * out on new objects if the state change demands it. */ EAPI void evas_event_thaw_eval (Evas *e) EINA_ARG_NONNULL(1); - + +/** + * @} + */ + /** * @defgroup Evas_Event_Feeding_Group Event Feeding Functions * @@ -1968,7 +2156,12 @@ EAPI void evas_event_thaw_eval (Evas *e) EINA_ARG_NONN * to the canvas to be processed. This is only required if operating * Evas directly as modules such as Ecore_Evas does that for you. * - * @ingroup Evas_Canvas + * @ingroup Evas_Canvas_Events + */ + +/** + * @addtogroup Evas_Event_Feeding_Group + * @{ */ /** @@ -2129,183 +2322,8 @@ EAPI void evas_event_feed_key_up (Evas *e, const char *k EAPI void evas_event_feed_hold (Evas *e, int hold, unsigned int timestamp, const void *data) EINA_ARG_NONNULL(1); /** - * @defgroup Evas_Canvas_Events Canvas Events - * - * Canvas generates some events - * - * @ingroup Evas_Canvas - */ - -/** - * @addtogroup Evas_Canvas_Events - * @{ - */ - -/** - * Add a callback function to the canvas. - * - * @param e Canvas to attach a callback to - * @param type The type of event that will trigger the callback - * @param func The function to be called when the event is triggered - * @param data The data pointer to be passed to @p func - * - * This function adds a function callback to the canvas when the event - * of type @p type occurs on canvas @p e. The function is @p func. - * - * In the event of a memory allocation error during addition of the - * callback to the canvas, evas_alloc_error() should be used to - * determine the nature of the error, if any, and the program should - * sensibly try and recover. - * - * The function will be passed the pointer @p data when it is - * called. A callback function must look like this: - * - * @code - * void callback (void *data, Evas *e, void *event_info); - * @endcode - * - * The first parameter @p data in this function will be the same value - * passed to evas_event_callback_add() as the @p data parameter. The - * second parameter @p e is the canvas handle on which the event - * occurred. The third parameter @p event_info is a pointer to a data - * structure that may or may not be passed to the callback, depending - * on the event type that triggered the callback. - * - * The event type @p type to trigger the function may be one of - * #EVAS_CALLBACK_RENDER_FLUSH_PRE, #EVAS_CALLBACK_RENDER_FLUSH_POST, - * #EVAS_CALLBACK_CANVAS_FOCUS_IN, #EVAS_CALLBACK_CANVAS_FOCUS_OUT. - * This determines the kind of event that will trigger the callback to - * be called. So far none of the event types provide useful data, so - * in all of them @p event_info pointer is @c NULL. - * - * Example: - * @code - * extern Evas *e; - * extern void *my_data; - * void focus_in_callback(void *data, Evas *e, void *event_info); - * void focus_out_callback(void *data, Evas *e, void *event_info); - * - * evas_event_callback_add(e, EVAS_CALLBACK_CANVAS_FOCUS_IN, focus_in_callback, my_data); - * if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE) - * { - * fprintf(stderr, "ERROR: Callback registering failed! Abort!\n"); - * exit(-1); - * } - * evas_event_callback_add(e, EVAS_CALLBACK_CANVAS_FOCUS_OUT, focus_out_callback, my_data); - * if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE) - * { - * fprintf(stderr, "ERROR: Callback registering failed! Abort!\n"); - * exit(-1); - * } - * @endcode - */ -EAPI void evas_event_callback_add (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3); - -/** - * Delete a callback function from the canvas. - * - * @param e Canvas to remove a callback from - * @param type The type of event that was triggering the callback - * @param func The function that was to be called when the event was triggered - * @return The data pointer that was to be passed to the callback - * - * This function removes the most recently added callback from the - * canvas @p e which was triggered by the event type @p type and was - * calling the function @p func when triggered. If the removal is - * successful it will also return the data pointer that was passed to - * evas_event_callback_add() when the callback was added to the - * canvas. If not successful NULL will be returned. - * - * Example: - * @code - * extern Evas *e; - * void *my_data; - * void focus_in_callback(void *data, Evas *e, void *event_info); - * - * my_data = evas_event_callback_del(ebject, EVAS_CALLBACK_CANVAS_FOCUS_IN, focus_in_callback); - * @endcode - */ -EAPI void *evas_event_callback_del (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func) EINA_ARG_NONNULL(1, 3); - -/** - * Delete a callback function from the canvas. - * - * @param e Canvas to remove a callback from - * @param type The type of event that was triggering the callback - * @param func The function that was to be called when the event was triggered - * @param data The data pointer that was to be passed to the callback - * @return The data pointer that was to be passed to the callback - * - * This function removes the most recently added callback from the - * canvas @p e which was triggered by the event type @p type and was - * calling the function @p func with data @p data when triggered. If - * the removal is successful it will also return the data pointer that - * was passed to evas_event_callback_add() (that will be the same as - * the parameter) when the callback was added to the canvas. If not - * successful NULL will be returned. - * - * Example: - * @code - * extern Evas *e; - * void *my_data; - * void focus_in_callback(void *data, Evas *e, void *event_info); - * - * my_data = evas_event_callback_del_full(ebject, EVAS_CALLBACK_CANVAS_FOCUS_IN, focus_in_callback, my_data); - * @endcode - */ -EAPI void *evas_event_callback_del_full (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data) EINA_ARG_NONNULL(1, 3); - -/** - * Push a callback on the post-event callback stack - * - * @param e Canvas to push the callback on - * @param func The function that to be called when the stack is unwound - * @param data The data pointer to be passed to the callback - * - * Evas has a stack of callbacks that get called after all the callbacks for - * an event have triggered (all the objects it triggers on and al the callbacks - * in each object triggered). When all these have been called, the stack is - * unwond from most recently to least recently pushed item and removed from the - * stack calling the callback set for it. - * - * This is intended for doing reverse logic-like processing, example - when a - * child object that happens to get the event later is meant to be able to - * "steal" functions from a parent and thus on unwind of this stack hav its - * function called first, thus being able to set flags, or return 0 from the - * post-callback that stops all other post-callbacks in the current stack from - * being called (thus basically allowing a child to take control, if the event - * callback prepares information ready for taking action, but the post callback - * actually does the action). - * - */ -EAPI void evas_post_event_callback_push (Evas *e, Evas_Object_Event_Post_Cb func, const void *data); - -/** - * Remove a callback from the post-event callback stack - * - * @param e Canvas to push the callback on - * @param func The function that to be called when the stack is unwound - * - * This removes a callback from the stack added with - * evas_post_event_callback_push(). The first instance of the function in - * the callback stack is removed from being executed when the stack is - * unwound. Further instances may still be run on unwind. - */ -EAPI void evas_post_event_callback_remove (Evas *e, Evas_Object_Event_Post_Cb func); - -/** - * Remove a callback from the post-event callback stack - * - * @param e Canvas to push the callback on - * @param func The function that to be called when the stack is unwound - * @param data The data pointer to be passed to the callback - * - * This removes a callback from the stack added with - * evas_post_event_callback_push(). The first instance of the function and data - * in the callback stack is removed from being executed when the stack is - * unwound. Further instances may still be run on unwind. + * @} */ -EAPI void evas_post_event_callback_remove_full (Evas *e, Evas_Object_Event_Post_Cb func, const void *data); /** * @} -- 2.7.4