Ecore Event functions
Ecore » Ecore main loop

Ecore events provide two main features that are of use to those using ecore: creating events and being notified of events. More...

## Topics

| System Events
| Ecore is aware of some system events that one may be interested, they are described below:

## Data Structures

struct | _Ecore_Event_Signal_User
| A structure that stores information of a User signal event. More...
struct | _Ecore_Event_Signal_Hup
| A structure that stores information of a Hup signal event. More...
struct | _Ecore_Event_Signal_Exit
| A structure that stores information of an Exit request event. More...
struct | _Ecore_Event_Signal_Power
| A structure that stores information of a Power event. More...
struct | _Ecore_Event_Signal_Realtime
| A structure that stores information of a Realtime event. More...

## Macros

#define | ECORE_EVENT_NONE 0
| None event.
#define | ECORE_EVENT_SIGNAL_USER 1
| User signal event.
#define | ECORE_EVENT_SIGNAL_HUP 2
| Hup signal event.
#define | ECORE_EVENT_SIGNAL_EXIT 3
| Exit signal event.
#define | ECORE_EVENT_SIGNAL_POWER 4
| Power signal event.
#define | ECORE_EVENT_SIGNAL_REALTIME 5
| Realtime signal event.
#define | ECORE_EVENT_MEMORY_STATE 6
| Memory state changed, see ecore_memory_state_get().
#define | ECORE_EVENT_POWER_STATE 7
| Power state changed, see ecore_power_state_get().
#define | ECORE_EVENT_LOCALE_CHANGED 8
| Locale changed.
#define | ECORE_EVENT_HOSTNAME_CHANGED 9
| Hostname changed.
#define | ECORE_EVENT_SYSTEM_TIMEDATE_CHANGED 10
| Time or Date changed.
#define | ECORE_EVENT_COUNT 11
| Number of events.
#define | ecore_event_type_flush(...)
| Forcefully flush all pending type without processing them.

## Typedefs

typedef struct _Ecore_Win32_Handler | Ecore_Win32_Handler
| A handle for HANDLE handlers on Windows.
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)
| A callback used for filtering events from the main loop.
typedef void(* | Ecore_End_Cb) (void *user_data, void *func_data)
| This is the callback which is called at the end of a function, usually for cleanup purposes.
typedef Eina_Bool(* | Ecore_Event_Handler_Cb) (void *data, int type, void *event)
| A callback used by the main loop to handle events of a specified type.

## Functions

Ecore_Event_Handler * | ecore_event_handler_add (int type, Ecore_Event_Handler_Cb func, const void *data)
| Adds an event handler.
Ecore_Event_Handler * | ecore_event_handler_prepend (int type, Ecore_Event_Handler_Cb func, const void *data)
| Adds an event handler to the beginning of the handler list.
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.
void | ecore_event_type_flush_internal (int type,...)
| Forcefully flush all pending type without processing them.
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 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.

## Detailed Description

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
}
ecore_event_handler_add
Ecore_Event_Handler * ecore_event_handler_add(int type, Ecore_Event_Handler_Cb func, const void *data)
Adds an event handler.
Definition ecore_events.c:13
Eina_Bool
unsigned char Eina_Bool
Type to mimic a boolean.
Definition eina_types.h:527

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 wrapper/helper set of functions.

Examples of libraries that integrate into ecore's main loop by providing events are Ecore_Con - Connection functions, Ecore_Evas wrapper/helper set of functions and Process Spawning Functions, 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();
ecore_event_type_new
int ecore_event_type_new(void)
Allocates a new event type id sensibly and returns the new id.
Definition ecore_events.c:80

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);
ecore_event_add
Ecore_Event * ecore_event_add(int type, void *ev, Ecore_End_Cb func_free, void *data)
Adds an event to the event queue.
Definition ecore_events.c:52

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:

- Handling events example
- ecore events and handlers - Setup and use

## Macro Definition Documentation

## ecore_event_type_flush

#define ecore_event_type_flush | ( |  | ... | ) |

Value:
ecore_event_type_flush_internal(__VA_ARGS__, ECORE_EVENT_NONE);
ecore_event_type_flush_internal
void ecore_event_type_flush_internal(int type,...)
Forcefully flush all pending type without processing them.
Definition ecore_events.c:196
ECORE_EVENT_NONE
#define ECORE_EVENT_NONE
None event.
Definition Ecore_Common.h:562

Forcefully flush all pending type without processing them.

Parameters

  ... | Serie of Ecore_Event.

This function is to be called before calling ecore_shutdown() if any event has still a chance to be in the ecore event queue.

Referenced by ecore_con_url_shutdown(), ecore_drm_shutdown(), ecore_event_shutdown(), ecore_imf_shutdown(), ecore_ipc_shutdown(), ecore_sdl_shutdown(), ecore_win32_shutdown(), ecore_wl2_shutdown(), elm_quicklaunch_shutdown(), and elput_shutdown().

## Function Documentation

## ecore_event_handler_add()

Ecore_Event_Handler * ecore_event_handler_add | ( | int | type,
|  | Ecore_Event_Handler_Cb | func,
|  | const void * | data )

Adds an event handler.

Parameters

  type | The type of the event this handler will get called for
  func | The function to call when the event is found in the queue
  data | A data pointer to pass to the called function `func`

Returns
  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 `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.

Examples
  ecore_con_client_example.c, ecore_con_client_simple_example.c, ecore_con_server_example.c, ecore_con_server_simple_example.c, ecore_con_url_cookies_example.c, ecore_con_url_download_example.c, ecore_con_url_headers_example.c, ecore_event_example_01.c, ecore_event_example_02.c, ecore_exe_example.c, ecore_idler_example.c, emotion_test_main.c, and win_example.c.

Referenced by ecore_drm2_device_open(), ecore_drm_tty_open(), elm_icon_thumb_set(), elm_init(), elm_quicklaunch_init(), and elput_manager_open().

## ecore_event_handler_prepend()

Ecore_Event_Handler * ecore_event_handler_prepend | ( | int | type,
|  | Ecore_Event_Handler_Cb | func,
|  | const void * | data )

Adds an event handler to the beginning of the handler list.

Parameters

  type | The type of the event this handler will get called for
  func | The function to call when the event is found in the queue
  data | A data pointer to pass to the called function `func`

Returns
  A new Event handler, or `NULL` on failure.

This function is identical to ecore_event_handler_add() except that it creates the handler at the start of the list. Do not use this function.

Since
  1.21

## ecore_event_handler_del()

void * ecore_event_handler_del | ( | Ecore_Event_Handler * | event_handler | ) |

Deletes an event handler.

Parameters

  event_handler | Event handler handle to delete

Returns
  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 `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.

Referenced by ecore_drm2_device_close(), ecore_drm_tty_close(), elm_quicklaunch_shutdown(), elm_shutdown(), and elput_manager_close().

## ecore_event_add()

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

Adds an event to the event queue.

Parameters

  type | The event type to add to the end of the event queue
  ev | The data structure passed as `event` to event handlers
  func_free | The function to be called to free ev
  data | The data pointer to be passed to the free function

Returns
  A Handle for that event on success, otherwise NULL

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.

Examples
  ecore_event_example_02.c, and ecore_idler_example.c.

References ECORE_EVENT_NONE.

Referenced by ecore_imf_context_commit_event_add(), ecore_imf_context_delete_surrounding_event_add(), ecore_imf_context_preedit_changed_event_add(), ecore_imf_context_preedit_end_event_add(), ecore_imf_context_preedit_start_event_add(), ecore_job_add(), ecore_memory_state_set(), ecore_power_state_set(), ecore_sdl_feed_events(), ecore_wl2_dnd_drag_end(), ecore_wl_dnd_drag_end(), and elm_policy_set().

## ecore_event_del()

void * ecore_event_del | ( | Ecore_Event * | event | ) |

Deletes an event from the queue.

Parameters

  event | The event handle to delete

Returns
  The data pointer originally set for the event free function

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.

Referenced by ecore_job_del().

## ecore_event_handler_data_get()

void * ecore_event_handler_data_get | ( | Ecore_Event_Handler * | eh | ) |

Gets the data associated with an Ecore_Event_Handler.

Parameters

  eh | The event handler

Returns
  The data

This function returns the data previously associated with `eh` by ecore_event_handler_add().

## ecore_event_handler_data_set()

void * ecore_event_handler_data_set | ( | Ecore_Event_Handler * | eh,
|  | const void * | data )

Sets the data associated with an Ecore_Event_Handler.

Parameters

  eh | The event handler
  data | The data to associate

Returns
  The previous data

This function sets `data` to `eh` and returns the old data pointer which was previously associated with `eh` by ecore_event_handler_add().

Examples
  ecore_event_example_02.c.

## ecore_event_type_new()

int ecore_event_type_new | ( | void |  | ) |

Allocates a new event type id sensibly and returns the new id.

Returns
  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.

Examples
  ecore_event_example_02.c, and ecore_idler_example.c.

Referenced by ecore_con_url_init(), ecore_drm2_init(), ecore_drm_init(), ecore_event_init(), ecore_imf_init(), ecore_ipc_init(), ecore_sdl_init(), ecore_win32_init(), ecore_wl2_init(), ecore_wl_init(), elm_init(), elm_need_ethumb(), elm_quicklaunch_init(), and elput_init().

## ecore_event_type_flush_internal()

void ecore_event_type_flush_internal | ( | int | type,
|  |  | ... )

Forcefully flush all pending type without processing them.

Parameters

  type | Ecore_Event.
  ... | Serie of Ecore_Event finished by ECORE_EVENT_NONE.

This function is to be called before calling ecore_shutdown() if any event has still a chance to be in the ecore event queue.

References ECORE_EVENT_NONE.

## ecore_event_filter_add()

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 the current event queue.

Parameters

  func_start | Function to call just before filtering and return data
  func_filter | Function to call on each event
  func_end | Function to call after the queue has been filtered
  data | Data to pass to the filter functions

Returns
  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 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.

## ecore_event_filter_del()

void * ecore_event_filter_del | ( | Ecore_Event_Filter * | ef | ) |

Deletes an event filter.

Parameters

  ef | The event filter handle

Returns
  The data set for the filter on success, `NULL` otherwise.

Delete a filter that has been added by its `ef` handle.

## ecore_event_current_type_get()

int ecore_event_current_type_get | ( | void |  | ) |

Returns the current event type being handled.

Returns
  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.

## ecore_event_current_event_get()

void * ecore_event_current_event_get | ( | void |  | ) |

Returns the current event type pointer handled.

Returns
  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.