304 lines
9.6 KiB
Plaintext
304 lines
9.6 KiB
Plaintext
~~Title: Ecore Events~~
|
|
{{page>index}}
|
|
----
|
|
===== Ecore Events =====
|
|
|
|
Ecore events are used for low-level handling of events such as key presses,
|
|
network connections, and communication with sub-processes.
|
|
|
|
The low-level handling of key presses is particularly useful for shortcuts:
|
|
instead of adding a signal handler to a specific graphical element, you can
|
|
add one globally. This guarantees that no matter which widget is currently
|
|
receiving events, the shortcut is caught.
|
|
|
|
Note that ecore events are also used to implement new graphical back-ends, but
|
|
they are low-level and not useful for most applications.
|
|
|
|
=== Table of Contents ===
|
|
|
|
* [[#Ecore_Events_Useful_for_Shortcuts|Ecore Events Useful for Shortcuts]]
|
|
* [[#Add_an_Event_Handler:_ecore_event_handler_add()|Add an Event Handler: ecore_event_handler_add()]]
|
|
* [[#Remove_an_Event_Handler:_ecore_event_handler_del()|Remove an Event Handler: ecore_event_handler_del()]]
|
|
* [[#Send_Events_to_the_Main_Loop_Yourself:_ecore_event_add()|Send Events to the Main Loop Yourself: ecore_event_add()]]
|
|
* [[#Create_Your_Own_Type_of_Events:_ecore_event_type_new()|Create Your Own Type of Events: ecore_event_type_new()]]
|
|
|
|
=== Related Info ===
|
|
|
|
* [[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Ecore__Event__Group.html|Ecore Event functions API]]
|
|
* [[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/ecore_event_example_01_c.html|Ecore Event Example]]
|
|
|
|
==== Ecore Events Useful for Shortcuts ====
|
|
|
|
There are eight ecore events for shortcuts:
|
|
|
|
<code c>
|
|
int ECORE_EVENT_KEY_DOWN;
|
|
int ECORE_EVENT_KEY_UP;
|
|
int ECORE_EVENT_MOUSE_BUTTON_DOWN;
|
|
int ECORE_EVENT_MOUSE_BUTTON_UP;
|
|
int ECORE_EVENT_MOUSE_MOVE;
|
|
int ECORE_EVENT_MOUSE_WHEEL;
|
|
int ECORE_EVENT_MOUSE_IN;
|
|
int ECORE_EVENT_MOUSE_OUT;
|
|
</code>
|
|
|
|
The callbacks receive additional data through a ''void *'' object, whose type
|
|
depends on the event that has been received.
|
|
|
|
* for ''ECORE_EVENT_KEY_DOWN'' and ''ECORE_EVENT_KEY_UP'':
|
|
|
|
<code c>
|
|
typedef struct _Ecore_Event_Key Ecore_Event_Key;
|
|
|
|
struct _Ecore_Event_Key
|
|
{
|
|
const char *keyname;
|
|
const char *key;
|
|
const char *string;
|
|
const char *compose;
|
|
Ecore_Window window;
|
|
Ecore_Window root_window;
|
|
Ecore_Window event_window;
|
|
|
|
unsigned int timestamp;
|
|
unsigned int modifiers;
|
|
|
|
int same_screen;
|
|
};
|
|
</code>
|
|
|
|
* for ''ECORE_EVENT_MOUSE_BUTTON_DOWN'' and ''ECORE_EVENT_MOUSE_BUTTON_UP'':
|
|
|
|
<code c>
|
|
typedef struct _Ecore_Event_Mouse_Button Ecore_Event_Mouse_Button;
|
|
|
|
struct _Ecore_Event_Mouse_Button
|
|
{
|
|
Ecore_Window window;
|
|
Ecore_Window root_window;
|
|
Ecore_Window event_window;
|
|
|
|
unsigned int timestamp;
|
|
unsigned int modifiers;
|
|
unsigned int buttons;
|
|
unsigned int double_click;
|
|
unsigned int triple_click;
|
|
int same_screen;
|
|
|
|
int x;
|
|
int y;
|
|
struct
|
|
{
|
|
int x;
|
|
int y;
|
|
} root;
|
|
|
|
struct
|
|
{
|
|
int device; // 0 if normal mouse, 1+ for other mouse-devices (eg multi-touch - other fingers)
|
|
double radius, radius_x, radius_y; // Radius of press point - radius_x and y if its an ellipse (radius is the average of the 2)
|
|
double pressure; // Pressure - 1.0 == normal, > 1.0 == more, 0.0 == none
|
|
double angle; // Angle relative to perpendicular (0.0 == perpendicular), in degrees
|
|
double x, y; // Same as x, y root.x, root.y, but with sub-pixel precision, if available
|
|
struct
|
|
{
|
|
double x;
|
|
double y;
|
|
} root;
|
|
} multi;
|
|
};
|
|
</code>
|
|
|
|
* for ''ECORE_EVENT_MOUSE_MOVE'' and ''ECORE_EVENT_MOUSE_WHEEL'':
|
|
|
|
<code c>
|
|
typedef struct _Ecore_Event_Mouse_Wheel Ecore_Event_Mouse_Wheel;
|
|
struct _Ecore_Event_Mouse_Wheel
|
|
{
|
|
Ecore_Window window;
|
|
Ecore_Window root_window;
|
|
Ecore_Window event_window;
|
|
|
|
unsigned int timestamp;
|
|
unsigned int modifiers;
|
|
|
|
int same_screen;
|
|
int direction;
|
|
int z;
|
|
|
|
int x;
|
|
int y;
|
|
struct
|
|
{
|
|
int x;
|
|
int y;
|
|
} root;
|
|
};
|
|
</code>
|
|
|
|
* for ''ECORE_EVENT_MOUSE_IN ''and ''ECORE_EVENT_MOUSE_OUT'':
|
|
|
|
<code c>
|
|
typedef struct _Ecore_Event_Mouse_Move Ecore_Event_Mouse_Move;
|
|
struct _Ecore_Event_Mouse_Move
|
|
{
|
|
Ecore_Window window;
|
|
Ecore_Window root_window;
|
|
Ecore_Window event_window;
|
|
|
|
unsigned int timestamp;
|
|
unsigned int modifiers;
|
|
|
|
int same_screen;
|
|
|
|
int x;
|
|
int y;
|
|
struct
|
|
{
|
|
int x;
|
|
int y;
|
|
} root;
|
|
|
|
struct
|
|
{
|
|
int device; // 0 if normal mouse, 1+ for other mouse-devices (eg multi-touch - other fingers)
|
|
double radius, radius_x, radius_y; // radius of press point - radius_x and y if it is an ellipse (radius is the average of the two)
|
|
double pressure; // pressure - 1.0 == normal, > 1.0 == more, 0.0 == none
|
|
double angle; // angle relative to perpendicular (0.0 == perpendicular), in degrees
|
|
double x, y; // same as x, y root.x, root.y, but with sub-pixel precision, if available
|
|
struct
|
|
{
|
|
double x, y;
|
|
} root;
|
|
} multi;
|
|
};
|
|
</code>
|
|
|
|
==== Add an Event Handler: ecore_event_handler_add() ====
|
|
|
|
The ''ecore_event_handler_add()'' function enables registering a callback for
|
|
the given event. Its prototype is:
|
|
|
|
<code c>
|
|
Ecore_Event_Handler* ecore_event_handler_add(int type,
|
|
Ecore_Event_Handler_Cb func,
|
|
const void* data
|
|
)
|
|
</code>
|
|
|
|
|
|
* ''type'' is an identifier for the event; for example, if you wish to receive notifications when keys are pressed, give ''ECORE_EVENT_KEY_DOWN''.
|
|
* ''func'' is the callback that is called when the event takes place.
|
|
* ''data'' is a pointer to additional data that is given as the argument to the callback; it is optional and ''NULL'' is an acceptable value.
|
|
* return value is a pointer to the event handler, which can be used later to uninstall the handler.
|
|
|
|
The type of the callback function is defined as follows.
|
|
|
|
<code c>
|
|
Eina_Bool (* Ecore_Event_Handler_Cb) (void *data, int type, void *event)
|
|
</code>
|
|
|
|
The callback function declaration is similar to:
|
|
|
|
<code c>
|
|
Eina_Bool some_ecore_event_cb(void *data, int type, void *event);
|
|
</code>
|
|
|
|
|
|
* ''data'' is the same as the ''data'' which was given as a parameter to ''ecore_event_handler_add()''.
|
|
* ''type'' is the same as the type which was given as a parameter to ''ecore_event_handler_add()''.
|
|
* ''event'' is an object whose actual type depends on the value of the ''type'' parameter and is one of ''Ecore_Event_Key'', ''Ecore_Event_Mouse_Button'', ''Ecore_Event_Mouse_Wheel'', ''Ecore_Event_Mouse_Move''.
|
|
* The return value is either ''ECORE_CALLBACK_PASS_ON'', to allow other callbacks for that event be called, or ''ECORE_CALLBACK_DONE'' to not call them.
|
|
|
|
|
|
|
|
The code below is a short example of how to set a global variable to
|
|
''EINA_TRUE'' when the Control key is pressed.
|
|
|
|
<code c>
|
|
Eina_Bool ctrl_pressed = EINA_FALSE;
|
|
|
|
static Eina_Bool
|
|
_key_down_cb(void *data __UNUSED__, int type __UNUSED__, void *ev)
|
|
{
|
|
// The callback is used with the ECORE_EVENT_KEY_DOWN signal: the
|
|
// parameter "void *ev" is therefore of the actual type Ecore_Event_Key
|
|
// The following renders its fields accessible
|
|
Ecore_Event_Key *event = ev;
|
|
|
|
// Test whether the key that is pressed is Ctrl.
|
|
if (!strcmp("Control_L", event->key))
|
|
{
|
|
// If it is, store that piece of information
|
|
ctrl_pressed = EINA_TRUE;
|
|
}
|
|
|
|
// Let the event continue to other callbacks which have not been called yet
|
|
return ECORE_CALLBACK_PASS_ON;
|
|
}
|
|
|
|
ecore_event_handler_add(ECORE_EVENT_KEY_DOWN, _key_down_cb, NULL);
|
|
</code>
|
|
|
|
==== Remove an Event Handler: ecore_event_handler_del() ====
|
|
|
|
To remove an event handler, use the ''ecore_event_handler_del()'' function.
|
|
The prototype is:
|
|
|
|
<code c>
|
|
void* ecore_event_handler_del(Ecore_Event_Handler *event_handler)
|
|
</code>
|
|
|
|
* event_handler is the value returned by ''ecore_event_handler_add()''.
|
|
* The return value is the data pointer that was used in the corresponding ''call to ecore_event_handler_add()''.
|
|
|
|
==== Send Events to the Main Loop Yourself: ecore_event_add() ====
|
|
|
|
You can send events to the main-loop, which helps to handle actions of various
|
|
origins through the same codepath. Note that this is a thread-safe operation.
|
|
|
|
To send an event, use the ''ecore_event_add()'' function. The prototype is
|
|
|
|
<code c>
|
|
Ecore_Event* ecore_event_add(int type,
|
|
void* ev,
|
|
Ecore_End_Cb func_free,
|
|
void* func_free_data
|
|
)
|
|
</code>
|
|
|
|
* ''type'' is the event type. For example, ECORE_EVENT_KEY_DOWN.
|
|
* ''ev'' is the event data. It is given as a parameter to the callback.
|
|
* ''func_free'' is a function to free ev after the callback is called. It is optional: ''NULL'' is an acceptable value.
|
|
* ''func_free_data'' is a pointer to additional data that is given as an argument to the ''func_free'' callback. It is optional: ''NULL'' is an acceptable value.
|
|
|
|
The type of the ''func_free'' function is defined as follows.
|
|
|
|
<code c>
|
|
void (* Ecore_End_Cb)(void *user_data, void *func_free_data)
|
|
</code>
|
|
|
|
The callback function declaration is thus similar to
|
|
|
|
<code c>
|
|
void some_func_free(void *user_data, void *func_free_data);
|
|
</code>
|
|
|
|
==== Create Your Own Type of Events: ecore_event_type_new() ====
|
|
|
|
You can create your own events. It also helps to use a single codepath.
|
|
|
|
The function for creating your own events is ''ecore_event_type_new()''. The
|
|
prototype is:
|
|
|
|
<code c>
|
|
int ecore_event_type_new(void);
|
|
</code>
|
|
|
|
It generates a new unique identifier, which you can use as ''type'' in the
|
|
functions described above.
|
|
|
|
\\
|
|
-----
|
|
{{page>index}}
|