Tizen Native API
Functions | Typedefs | Defines
Ecore Event functions
Ecore main loop

Functions

Ecore_Event_Handler * ecore_event_handler_add (int type, Ecore_Event_Handler_Cb func, const void *data)
 Add an event handler.
void * ecore_event_handler_del (Ecore_Event_Handler *event_handler)
 Delete an event handler.
Ecore_Event * ecore_event_add (int type, void *ev, Ecore_End_Cb func_free, void *data)
 Add an event to the event queue.
void * ecore_event_del (Ecore_Event *event)
 Delete an event from the queue.
void * ecore_event_handler_data_get (Ecore_Event_Handler *eh)
 Get the data associated with an Ecore_Event_Handler.
void * ecore_event_handler_data_set (Ecore_Event_Handler *eh, const void *data)
 Set the data associated with an Ecore_Event_Handler.
int ecore_event_type_new (void)
 Allocate a new event type id sensibly and return 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)
 Add a filter the current event queue.
void * ecore_event_filter_del (Ecore_Event_Filter *ef)
 Delete an event filter.
int ecore_event_current_type_get (void)
 Return the current event type being handled.
void * ecore_event_current_event_get (void)
 Return the current event type pointer handled.

Typedefs

typedef struct _Ecore_Event_Handler Ecore_Event_Handler
typedef struct _Ecore_Event_Filter Ecore_Event_Filter
typedef struct _Ecore_Event Ecore_Event
typedef struct
_Ecore_Event_Signal_User 		Ecore_Event_Signal_User
typedef struct
_Ecore_Event_Signal_Hup 		Ecore_Event_Signal_Hup
typedef struct
_Ecore_Event_Signal_Exit 		Ecore_Event_Signal_Exit
typedef struct
_Ecore_Event_Signal_Power 		Ecore_Event_Signal_Power
typedef struct
_Ecore_Event_Signal_Realtime 		Ecore_Event_Signal_Realtime
typedef Eina_Bool(* Ecore_Filter_Cb )(void *data, void *loop_data, int type, void *event)
typedef void(* Ecore_End_Cb )(void *user_data, void *func_data)
typedef Eina_Bool(* Ecore_Event_Handler_Cb )(void *data, int type, void *event)

Defines

#define ECORE_EVENT_NONE   0
#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
#define ECORE_EVENT_MEMORY_STATE   6
#define ECORE_EVENT_POWER_STATE   7
#define ECORE_EVENT_LOCALE_CHANGED   8
#define ECORE_EVENT_HOSTNAME_CHANGED   9
#define ECORE_EVENT_SYSTEM_TIMEDATE_CHANGED   10
#define ECORE_EVENT_COUNT   11

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.

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 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 which are emitted in response to POSIX signals(https://en.wikipedia.org/wiki/Signal_%28computing%29):

  • ECORE_EVENT_SIGNAL_USER
  • ECORE_EVENT_SIGNAL_HUP
  • ECORE_EVENT_SIGNAL_POWER
  • ECORE_EVENT_SIGNAL_EXIT
Warning:
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 for 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, so, for example, for events related to windowing one would look in Ecore_Evas_Group.

Examples of libraries that integrate into ecore's main loop by providing events are Ecore_Con_Group, Ecore_Evas_Group and 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: 

 int MY_EV_TYPE = ecore_event_type_new();
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 event, if it doesn't it a one-liner: 

 ecore_event_add(MY_EV_TYPE, NULL, NULL, NULL);

The usage when an event is needed is not that much more complex and can be seen in ecore_event_add.

Examples that deals with events:

Define Documentation

#define ECORE_EVENT_COUNT   11

Number of events

#define ECORE_EVENT_HOSTNAME_CHANGED   9

Hostname changed

#define ECORE_EVENT_LOCALE_CHANGED   8

Locale changed

#define ECORE_EVENT_MEMORY_STATE   6

Memory state changed

#define ECORE_EVENT_NONE   0

None event

#define ECORE_EVENT_POWER_STATE   7

Power state changed

#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

#define ECORE_EVENT_SYSTEM_TIMEDATE_CHANGED   10

Time or Date changed

Typedef Documentation

Ecore_End_Cb Ecore_End_Cb

This is the callback which is called at the end of a function, usually for cleanup purposes.

typedef struct _Ecore_Event Ecore_Event

A handle for an event

typedef struct _Ecore_Event_Filter Ecore_Event_Filter

A handle for an event filter

typedef struct _Ecore_Event_Handler Ecore_Event_Handler

A handle for an event handler

Ecore_Event_Handler_Cb Ecore_Event_Handler_Cb

A callback used by the main loop to handle events of a specified type.

typedef struct _Ecore_Event_Signal_Exit Ecore_Event_Signal_Exit

Exit signal event

typedef struct _Ecore_Event_Signal_Hup Ecore_Event_Signal_Hup

Hup 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 struct _Ecore_Event_Signal_User Ecore_Event_Signal_User

User signal event

Ecore_Filter_Cb

A callback used for filtering events from the main loop.

Function Documentation

Ecore_Event* ecore_event_add ( int  type,
void *  ev,
Ecore_End_Cb  func_free,
void *  data 
)

Add an event to the event queue.

Since :
2.3
Parameters:
[in]typeThe event type to add to the end of the event queue
[in]evThe data structure passed as event to event handlers
[in]func_freeThe function to be called to free ev
[in]dataThe data pointer to be passed to the free function
Returns:
A Handle for that event on success, otherwise NULL
Remarks:
If it succeeds, an event of type type will be added to the queue for processing by event handlers added by ecore_event_handler_add(). The ev parameter will be passed as the event parameter of the handler. When the event is no longer needed, func_free will be called and passed ev for cleaning up. If func_free is NULL, free() will be called with the private structure pointer.
void* ecore_event_current_event_get ( void  )

Return the current event type pointer handled.

Since :
2.3
Returns:
The current event pointer being handled if inside a handler callback, NULL otherwise.
Remarks:
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.
int ecore_event_current_type_get ( void  )

Return the current event type being handled.

Since :
2.3
Returns:
The current event type being handled if inside a handler callback, ECORE_EVENT_NONE otherwise
Remarks:
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.
void* ecore_event_del ( Ecore_Event *  event)

Delete an event from the queue.

Since :
2.3
Parameters:
[in]eventThe event handle to delete
Returns:
The data pointer originally set for the event free function
Remarks:
This deletes the event event from the event queue, and returns the 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.
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 
)

Add a filter the current event queue.

Since :
2.3
Parameters:
[in]func_startFunction to call just before filtering and return data
[in]func_filterFunction to call on each event
[in]func_endFunction to call after the queue has been filtered
[in]dataData to pass to the filter functions
Returns:
A filter handle on success, NULL otherwise.
Remarks:
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 func_start is called and passed the data pointer, the return value of this functions is passed to func_filter as loop_data. func_filter is also passed data and the event type and 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.
void* ecore_event_filter_del ( Ecore_Event_Filter *  ef)

Delete an event filter.

Since :
2.3
Parameters:
[in]efThe event filter handle
Returns:
The data set for the filter on success, NULL otherwise.
Remarks:
Delete a filter that has been added by its ef handle.
Ecore_Event_Handler* ecore_event_handler_add ( int  type,
Ecore_Event_Handler_Cb  func,
const void *  data 
)

Add an event handler.

Since :
2.3
Parameters:
[in]typeThe type of the event this handler will get called for
[in]funcThe function to call when the event is found in the queue
[in]dataA data pointer to pass to the called function func
Returns:
A new Event handler, or NULL on failure.
Remarks:
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 type parameter is the integer of the event type that will trigger this callback to be called. The callback 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 data parameter.
When the callback 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.
void* ecore_event_handler_data_get ( Ecore_Event_Handler *  eh)

Get the data associated with an Ecore_Event_Handler.

Since :
2.3
Parameters:
[in]ehThe event handler
Returns:
The data
Remarks:
This function returns the data previously associated with eh by ecore_event_handler_add().
void* ecore_event_handler_data_set ( Ecore_Event_Handler *  eh,
const void *  data 
)

Set the data associated with an Ecore_Event_Handler.

Since :
2.3
Parameters:
[in]ehThe event handler
[in]dataThe data to associate
Returns:
The previous data
Remarks:
This function sets data to eh and returns the old data pointer which was previously associated with eh by ecore_event_handler_add().
void* ecore_event_handler_del ( Ecore_Event_Handler *  event_handler)

Delete an event handler.

Since :
2.3
Parameters:
[in]event_handlerEvent handler handle to delete
Returns:
Data passed to handler
Remarks:
Delete a specified event handler from the handler list. On success this will delete the event handler and return the pointer passed as 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.
int ecore_event_type_new ( void  )

Allocate a new event type id sensibly and return the new id.

Since :
2.3
Returns:
A new event type id.
Remarks:
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.