forked from enlightenment/efl
Ecore event functions docs improvements.
Moved docs to header file. Fixed some typos. Added @brief. Add failure information to @return. Other random improvements. SVN revision: 69337
This commit is contained in:
parent
3d819068c6
commit
c001712874
|
@ -664,16 +664,156 @@ struct _Ecore_Event_Signal_Realtime /** Realtime event */
|
||||||
#endif
|
#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);
|
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);
|
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);
|
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);
|
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);
|
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);
|
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);
|
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);
|
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);
|
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);
|
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);
|
EAPI void *ecore_event_current_event_get(void);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
|
|
@ -72,35 +72,6 @@ static void *ecore_raw_event_event = NULL;
|
||||||
static void _ecore_event_purge_deleted(void);
|
static void _ecore_event_purge_deleted(void);
|
||||||
static void *_ecore_event_del(Ecore_Event *event);
|
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 *
|
EAPI Ecore_Event_Handler *
|
||||||
ecore_event_handler_add(int type,
|
ecore_event_handler_add(int type,
|
||||||
Ecore_Event_Handler_Cb func,
|
Ecore_Event_Handler_Cb func,
|
||||||
|
@ -151,16 +122,6 @@ unlock:
|
||||||
return eh;
|
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 *
|
EAPI void *
|
||||||
ecore_event_handler_del(Ecore_Event_Handler *event_handler)
|
ecore_event_handler_del(Ecore_Event_Handler *event_handler)
|
||||||
{
|
{
|
||||||
|
@ -180,14 +141,6 @@ unlock:
|
||||||
return data;
|
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 *
|
EAPI void *
|
||||||
ecore_event_handler_data_get(Ecore_Event_Handler *eh)
|
ecore_event_handler_data_get(Ecore_Event_Handler *eh)
|
||||||
{
|
{
|
||||||
|
@ -205,15 +158,6 @@ unlock:
|
||||||
return data;
|
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 *
|
EAPI void *
|
||||||
ecore_event_handler_data_set(Ecore_Event_Handler *eh,
|
ecore_event_handler_data_set(Ecore_Event_Handler *eh,
|
||||||
const void *data)
|
const void *data)
|
||||||
|
@ -241,21 +185,6 @@ _ecore_event_generic_free(void *data __UNUSED__,
|
||||||
free(event);
|
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 *
|
EAPI Ecore_Event *
|
||||||
ecore_event_add(int type,
|
ecore_event_add(int type,
|
||||||
void *ev,
|
void *ev,
|
||||||
|
@ -276,17 +205,6 @@ unlock:
|
||||||
return event;
|
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 *
|
EAPI void *
|
||||||
ecore_event_del(Ecore_Event *event)
|
ecore_event_del(Ecore_Event *event)
|
||||||
{
|
{
|
||||||
|
@ -306,16 +224,6 @@ unlock:
|
||||||
return data;
|
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
|
EAPI int
|
||||||
ecore_event_type_new(void)
|
ecore_event_type_new(void)
|
||||||
{
|
{
|
||||||
|
@ -328,26 +236,6 @@ ecore_event_type_new(void)
|
||||||
return id;
|
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 *
|
EAPI Ecore_Event_Filter *
|
||||||
ecore_event_filter_add(Ecore_Data_Cb func_start,
|
ecore_event_filter_add(Ecore_Data_Cb func_start,
|
||||||
Ecore_Filter_Cb func_filter,
|
Ecore_Filter_Cb func_filter,
|
||||||
|
@ -371,15 +259,6 @@ unlock:
|
||||||
return ef;
|
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 *
|
EAPI void *
|
||||||
ecore_event_filter_del(Ecore_Event_Filter *ef)
|
ecore_event_filter_del(Ecore_Event_Filter *ef)
|
||||||
{
|
{
|
||||||
|
@ -401,50 +280,18 @@ unlock:
|
||||||
return data;
|
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
|
EAPI int
|
||||||
ecore_event_current_type_get(void)
|
ecore_event_current_type_get(void)
|
||||||
{
|
{
|
||||||
return ecore_raw_event_type;
|
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 *
|
EAPI void *
|
||||||
ecore_event_current_event_get(void)
|
ecore_event_current_event_get(void)
|
||||||
{
|
{
|
||||||
return ecore_raw_event_event;
|
return ecore_raw_event_event;
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
|
||||||
* @}
|
|
||||||
*/
|
|
||||||
|
|
||||||
EAPI void *
|
EAPI void *
|
||||||
_ecore_event_handler_del(Ecore_Event_Handler *event_handler)
|
_ecore_event_handler_del(Ecore_Event_Handler *event_handler)
|
||||||
{
|
{
|
||||||
|
|
Loading…
Reference in New Issue