Tizen Native API
|
Functions | |
Ecore_Event_Handler * | ecore_event_handler_add (int type, Ecore_Event_Handler_Cb func, const void *data) |
Adds an event handler. | |
void * | ecore_event_handler_del (Ecore_Event_Handler *event_handler) |
Deletes an event handler. | |
Ecore_Event * | ecore_event_add (int type, void *ev, Ecore_End_Cb func_free, void *data) |
Adds an event to the event queue. | |
void * | ecore_event_del (Ecore_Event *event) |
Deletes an event from the queue. | |
void * | ecore_event_handler_data_get (Ecore_Event_Handler *eh) |
Gets the data associated with an Ecore_Event_Handler. | |
void * | ecore_event_handler_data_set (Ecore_Event_Handler *eh, const void *data) |
Sets the data associated with an Ecore_Event_Handler. | |
int | ecore_event_type_new (void) |
Allocates a new event type ID sensibly and returns the new ID. | |
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) |
Adds a filter to the current event queue. | |
void * | ecore_event_filter_del (Ecore_Event_Filter *ef) |
Deletes an event filter. | |
int | ecore_event_current_type_get (void) |
Returns the current event type being handled. | |
void * | ecore_event_current_event_get (void) |
Returns the current event type pointer handled. | |
Typedefs | |
typedef struct _Ecore_Event_Handler | Ecore_Event_Handler |
A handle for an event handler. | |
typedef struct _Ecore_Event_Filter | Ecore_Event_Filter |
A handle for an event filter. | |
typedef struct _Ecore_Event | Ecore_Event |
A handle for an event. | |
typedef struct _Ecore_Event_Signal_User | Ecore_Event_Signal_User |
User signal event. | |
typedef struct _Ecore_Event_Signal_Hup | Ecore_Event_Signal_Hup |
Hup signal event. | |
typedef struct _Ecore_Event_Signal_Exit | Ecore_Event_Signal_Exit |
Exit signal event. | |
typedef struct _Ecore_Event_Signal_Power | Ecore_Event_Signal_Power |
Power signal event. | |
typedef struct _Ecore_Event_Signal_Realtime | Ecore_Event_Signal_Realtime |
Realtime signal event. | |
typedef Eina_Bool(* | Ecore_Filter_Cb )(void *data, void *loop_data, int type, void *event) |
The boolean type for a callback used for filtering events from the main loop. | |
typedef void(* | Ecore_End_Cb )(void *user_data, void *func_data) |
Called at the end of a function, usually for cleanup purposes. | |
typedef Eina_Bool(* | Ecore_Event_Handler_Cb )(void *data, int type, void *event) |
The boolean type used by the main loop to handle events of a specified type. | |
Defines | |
#define | ECORE_EVENT_SIGNAL_USER 1 |
#define | ECORE_EVENT_SIGNAL_HUP 2 |
#define | ECORE_EVENT_SIGNAL_EXIT 3 |
#define | ECORE_EVENT_SIGNAL_POWER 4 |
#define | ECORE_EVENT_SIGNAL_REALTIME 5 |
Ecore event are a helper to create events are being notified of events.
Ecore events provide two main features that are of use to those using ecore: creating events and being notified of events. Those two are usually 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.
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:
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 the event }
One very important thing to note here is the EVENT_TYPE
. To register a handler for an event, you must know its type before hand. Ecore provides the following events that are emitted in response to POSIX signals(https://en.wikipedia.org/wiki/Signal_%28computing%29):
Don't override these using the signal
or sigaction
calls. These, however, aren't the only signals one can handle. Many libraries(including ecore modules) have their own signals that can be listened to and handled. To do that one only needs to know the type of the event. This information can be found on the documentation of the library emitting the signal.
This usage can be divided into two parts, setup and adding events. The setup is very simple, all that needs to be done is getting a type ID for the event:
int MY_EV_TYPE = ecore_event_type_new();
This variable should be declared in the header since it is needed by anyone wishing to register a handler to your event.
The complexity of adding an event to the queue depends on whether that event sends or uses event, if it doesn't it is a one-liner:
ecore_event_add(MY_EV_TYPE, NULL, NULL, NULL);
The usage when an event
is needed is not that complex and can be seen in ecore_event_add.
#define ECORE_EVENT_SIGNAL_EXIT 3 |
Exit signal event
#define ECORE_EVENT_SIGNAL_HUP 2 |
Hup signal event
#define ECORE_EVENT_SIGNAL_POWER 4 |
Power signal event
#define ECORE_EVENT_SIGNAL_REALTIME 5 |
Realtime signal event
#define ECORE_EVENT_SIGNAL_USER 1 |
User signal event
Ecore_Event* ecore_event_add | ( | int | type, |
void * | ev, | ||
Ecore_End_Cb | func_free, | ||
void * | data | ||
) |
Adds an event to the event queue.
NULL
, free() is called with the private structure pointer.[in] | type | The event type to add to the end of the event queue |
[in] | ev | The data structure passed as event to event handlers |
[in] | func_free | The function to be called to free ev |
[in] | data | The data pointer to be passed to the free function |
NULL
on failure void* ecore_event_current_event_get | ( | void | ) |
Returns the current event type pointer handled.
NULL
int ecore_event_current_type_get | ( | void | ) |
Returns the current event type being handled.
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 the one about which it wants to get more information.
ECORE_EVENT_NONE
void* ecore_event_del | ( | Ecore_Event * | event | ) |
Deletes an event from the queue.
This deletes the event event from the event queue, and returns the data parameter originally set when adding it using ecore_event_add(). This does not immediately call the free function, and it may be called later for 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.
[in] | event | The event handle to delete |
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 | ||
) |
Adds a filter to the current event queue.
This 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 when processing is about to start func_start is called and passed the data pointer. The return value of this function is passed to func_filter as loop_data. func_filter is also passed data, the event type, and the event structure. If this 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 func_end is called and is passed the loop_data(returned by func_start) and data pointer to clean up.
[in] | func_start | The function to call just before filtering and returning data |
[in] | func_filter | The function to call on each event |
[in] | func_end | The function to call after the queue has been filtered |
[in] | data | The data to pass to the filter functions |
NULL
on failure void* ecore_event_filter_del | ( | Ecore_Event_Filter * | ef | ) |
Deletes an event filter.
This deletes a filter that has been added by its ef handle.
[in] | ef | The event filter handle |
NULL
Ecore_Event_Handler* ecore_event_handler_add | ( | int | type, |
Ecore_Event_Handler_Cb | func, | ||
const void * | data | ||
) |
Adds an event handler.
This adds an event handler to the list of handlers. This, on success, returns a handle to the event handler object that is created, that can be used later to remove the handler using ecore_event_handler_del(). The type parameter is the integer of the event type that triggers this callback to be called. The callback func is called when this event is processed and is 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 data parameter.
1
or 0
. If it returns 1
(or ECORE_CALLBACK_PASS_ON
), it keeps being called as per normal, for each handler set up for that event type. If it returns 0
(or ECORE_CALLBACK_DONE
), it ceases processing handlers for that particular event, so all handlers set to handle that event type that have not already been called, are not called.[in] | type | The type of the event that this handler gets called for |
[in] | func | The function to call when the event is found in the queue |
[in] | data | A data pointer to pass to the called function func |
NULL
on failure void* ecore_event_handler_data_get | ( | Ecore_Event_Handler * | eh | ) |
Gets the data associated with an Ecore_Event_Handler.
This function returns the data previously associated with eh by ecore_event_handler_add().
[in] | eh | The event handler |
void* ecore_event_handler_data_set | ( | Ecore_Event_Handler * | eh, |
const void * | data | ||
) |
Sets the data associated with an Ecore_Event_Handler.
This function sets data to eh and returns the old data pointer that had been previously associated with eh by ecore_event_handler_add().
[in] | eh | The event handler |
[in] | data | The data to associate |
void* ecore_event_handler_del | ( | Ecore_Event_Handler * | event_handler | ) |
Deletes an event handler.
This deletes a specified event handler from the handler list. On success, this deletes the event handler and returns the pointer passed as data when the handler is added by ecore_event_handler_add(). On failure, NULL
is returned. Once a handler is deleted it is no longer called.
[in] | event_handler | The event handler handle to delete |
int ecore_event_type_new | ( | void | ) |
Allocates a new event type ID sensibly and returns the new 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 is unique to the current instance of the process.