Functions
Input Events Feeding Functions

Functions to tell Evas that input events happened and should be processed. More...

Functions

Evas_Deviceevas_device_add (Evas *e)
 Add a new device type. More...
 
void evas_device_del (Evas_Device *dev)
 Delete a new device type. More...
 
void evas_device_push (Evas *e, Evas_Device *dev)
 Push the current context device onto the device stack. More...
 
void evas_device_pop (Evas *e)
 This pops the top of the device stack for the canvas. More...
 
const Eina_Listevas_device_list (Evas *e, const Evas_Device *dev)
 List all current devices attached to the given canvas and/or device. More...
 
void evas_device_name_set (Evas_Device *dev, const char *name)
 Set the name of a device as a string. More...
 
const char * evas_device_name_get (const Evas_Device *dev)
 Get the name of a device. More...
 
void evas_device_description_set (Evas_Device *dev, const char *desc)
 Set the description of a device as a string. More...
 
const char * evas_device_description_get (const Evas_Device *dev)
 Get the description of a device. More...
 
void evas_device_parent_set (Evas_Device *dev, Evas_Device *parent)
 Set the parent of a device. More...
 
const Evas_Deviceevas_device_parent_get (const Evas_Device *dev)
 Get the parent of a device. More...
 
void evas_device_class_set (Evas_Device *dev, Evas_Device_Class clas)
 Set the major class of device. More...
 
Evas_Device_Class evas_device_class_get (const Evas_Device *dev)
 Get the major class of a device. More...
 
void evas_device_subclass_set (Evas_Device *dev, Evas_Device_Subclass clas)
 Set the sub-class of a device. More...
 
Evas_Device_Subclass evas_device_subclass_get (const Evas_Device *dev)
 Get the device sub-class. More...
 
void evas_device_emulation_source_set (Evas_Device *dev, Evas_Device *src)
 Set the emulation source device. More...
 
const Evas_Deviceevas_device_emulation_source_get (const Evas_Device *dev)
 Get the emulation source device. More...
 
void evas_event_freeze (Evas *e)
 Freeze all input events processing. More...
 
void evas_event_thaw (Evas *e)
 Thaw a canvas out after freezing (for input events). More...
 
int evas_event_freeze_get (const Evas *e)
 Return the freeze count on input events of a given canvas. More...
 
void evas_event_thaw_eval (Evas *e)
 After thaw of a canvas, re-evaluate the state of objects and call callbacks. More...
 

Detailed Description

Functions to tell Evas that input events happened and should be processed.

Warning
Most of the time these functions are not what you're looking for. These functions should only be used if you're not working with ecore evas(or another input handling system). If you're not using ecore evas please consider using it, in most situation it will make life a lot easier.

As explained in intro_not_evas, Evas does not know how to poll for input events, so the developer should do it and then feed such events to the canvas to be processed. This is only required if operating Evas directly. Modules such as Ecore_Evas do that for you.

Some of the functions in this group are exemplified here.

Function Documentation

Evas_Device* evas_device_add ( Evas e)

Add a new device type.

Parameters
eThe canvas to create the device node for.

Adds a new device node to the given canvas e. All devices created as part of the canvas e will automatically be deleted when the canvas is freed.

Returns
the device node created or NULL if an error occurred.
See also
evas_device_del
Since
1.8

References eina_list_append(), eo_data_scope_get(), and EVAS_CALLBACK_DEVICE_CHANGED.

void evas_device_del ( Evas_Device dev)

Delete a new device type.

Parameters
devThe device node you want to delete.
See also
evas_device_add
evas_device_push
evas_device_pop
Since
1.8

References EINA_LIST_FREE, and evas_device_del().

Referenced by evas_device_del(), and evas_device_emulation_source_get().

void evas_device_push ( Evas e,
Evas_Device dev 
)

Push the current context device onto the device stack.

Parameters
eThe canvas to push the device on to
devThe device to push.

This pushes the given device dev onto the stack for the canvas e resulting in the dev pointer in all events that get fed to the canvas being the device at the top of the device stack for that canvas.

If a device is pushed onto the device stack, it will not be deleted until a canvas free OR until it has been popped from the stack even if evas_device_del() is called.

The device dev must have been created as a device for the canvas it is pushed onto (and not another canvas).

Example:

1 evas_device_push(canvas, dev);
2 evas_event_feed_mouse_move(canvas, 20, 30, 0, NULL);
3 evas_device_pop(canvas);
See also
evas_device_pop
Since
1.8

References eina_array_new(), eina_array_push(), and eo_data_scope_get().

void evas_device_pop ( Evas e)

This pops the top of the device stack for the canvas.

Parameters
eThe canvas to pop the device stack from

This pops the top of the device stack making the current device context used for device events being what is now at the top of the stack after popping.

See also
evas_device_push
Since
1.8

References eina_array_pop(), and eo_data_scope_get().

const Eina_List* evas_device_list ( Evas e,
const Evas_Device dev 
)

List all current devices attached to the given canvas and/or device.

Parameters
eThe canvas to query for a device list
devA specific device inside the canvas to query for child devices or NULL if just querying the base canvas devices
Returns
An internal list of Evas_Device pointers, or NULL if no devices are found

This will list all devices belonging to a specific evas canvas e, at the top-level in the device tree if dev passed in is NULL. If dev is a valid device for the given canvas e, then a list of child devices of dev will be returned, allowing you to walk the device tree.

The list returned is only valid so long as no changes are made to the device tree in the given canvas e. If there are no devices or children then NULL is returned.

See also
evas_device_parent_get
evas_device_name_get
evas_device_description_get
evas_device_class_get
evas_device_subclass_get
evas_device_emulation_source_get
Since
1.8

References eo_data_scope_get().

void evas_device_name_set ( Evas_Device dev,
const char *  name 
)

Set the name of a device as a string.

dev The device to set the name of name The name string as a readable C UTF8 string

Since
1.8

References EVAS_CALLBACK_DEVICE_CHANGED.

const char* evas_device_name_get ( const Evas_Device dev)

Get the name of a device.

dev The device to query

Returns
The device name string or NULL if none is set

This gets the name set by evas_device_name_set(). This is a readable UTF8 C string, or NULL if no name is set.

The name should be a short name like "Wireless Mouse", "Joystick", "Finger", "Keyboard" or "Numberpad" etc.

Since
1.8

Referenced by ecore_imf_evas_event_key_down_wrap(), and ecore_imf_evas_event_key_up_wrap().

void evas_device_description_set ( Evas_Device dev,
const char *  desc 
)

Set the description of a device as a string.

dev The device to set the description of name The description string as a readable C UTF8 string

Since
1.8

References EVAS_CALLBACK_DEVICE_CHANGED.

const char* evas_device_description_get ( const Evas_Device dev)

Get the description of a device.

dev The device to query

Returns
The device description string or NULL if none is set

This gets the description set by evas_device_description_set(). This is a readable UTF8 C string, or NULL if no description is set.

A description is meant to be a longer string describing the device so a human may make sense of it. For example "Wireless 6 button mouse in Black with red buttons" would be a good description, so a user may identify precisely which device is being talked about.

Since
1.8
void evas_device_parent_set ( Evas_Device dev,
Evas_Device parent 
)

Set the parent of a device.

dev The device to set the parent of parent The new parent device

This sets the parent of a device dev to the parent given by parent. If the device already has a parent, it is removed from that parent's list. If parent is NULL then the device is unparented and placed back as a root device in the canvas.

When a device is deleted with evas_device_del(), all children are also deleted along with it.

See also
evas_device_del
evas_device_parent_get
evas_device_list
Since
1.8

References eina_list_append(), eina_list_remove(), eo_data_scope_get(), EVAS_CALLBACK_DEVICE_CHANGED, and efl::eo::parent.

const Evas_Device* evas_device_parent_get ( const Evas_Device dev)

Get the parent of a device.

Parameters
devThe device to query
Returns
The parent device or NULL if it is a toplevel

This returns the parent device of any given device entry, or NULL if no parent device exists (is a toplevel device).

Since
1.8
void evas_device_class_set ( Evas_Device dev,
Evas_Device_Class  clas 
)

Set the major class of device.

Parameters
devThe device whose class to set
clasThe class to set it to

This sets the "primary" class of device (a broad thing like mouse, keyboard, touch, pen etc.).

Since
1.8

References EVAS_CALLBACK_DEVICE_CHANGED.

Evas_Device_Class evas_device_class_get ( const Evas_Device dev)

Get the major class of a device.

Parameters
devThe devise to query
Returns
The device class to set

This sets the device class set by evas_device_class_set().

Since
1.8

References EVAS_DEVICE_CLASS_NONE.

Referenced by ecore_imf_evas_event_key_down_wrap(), and ecore_imf_evas_event_key_up_wrap().

void evas_device_subclass_set ( Evas_Device dev,
Evas_Device_Subclass  clas 
)

Set the sub-class of a device.

Parameters
devThe device to modify
clasThe sub-class to set

This sets the sub-class of a device which gives much more detailed usage within a broader category.

Since
1.8

References EVAS_CALLBACK_DEVICE_CHANGED.

Evas_Device_Subclass evas_device_subclass_get ( const Evas_Device dev)

Get the device sub-class.

Parameters
devThe device to query
Returns
The device sub-class set by evas_device_subclass_set().
Since
1.8

References EVAS_DEVICE_SUBCLASS_NONE.

Referenced by ecore_imf_evas_event_key_down_wrap(), and ecore_imf_evas_event_key_up_wrap().

void evas_device_emulation_source_set ( Evas_Device dev,
Evas_Device src 
)

Set the emulation source device.

Parameters
devThe device being emulated
srcThe primary source device producing events in the emulated device

Devices may not be real, but may be emulated by listening to input on other devices and modifying or interpeting it to generate output on an emulated device (example a fingeron a touchscreen will often emulate a mouse when it presses). This allows you to set which device primarily emulates dev so the user can choose to ignore events from emulated devices if they also pay attention to source device events for example.

Since
1.8

References EVAS_CALLBACK_DEVICE_CHANGED.

const Evas_Device* evas_device_emulation_source_get ( const Evas_Device dev)

Get the emulation source device.

Parameters
devThe device to query
Returns
The source emulation device set by evas_device_emulation_source_set().
Since
1.8

References eina_array_count(), eina_array_data_get(), eina_array_free(), eina_array_pop(), EINA_LIST_FREE, eina_stringshare_del(), eo_data_scope_get(), and evas_device_del().

void evas_event_freeze ( Evas e)

Freeze all input events processing.

Parameters
eThe canvas to freeze input events processing on.

This function will indicate to Evas that the canvas e is to have all input event processing frozen until a matching evas_event_thaw() function is called on the same canvas. All events of this kind during the freeze will get discarded. Every freeze call must be matched by a thaw call in order to completely thaw out a canvas (i.e. these calls may be nested). The most common use is when you don't want the user to interact with your user interface when you're populating a view or changing the layout.

Example:

1  "\tf - freeze input for 3 seconds\n"
2  "\tp - toggle precise point collision detection on image\n"
3  "\tControl + o - add an obscured rectangle\n"
4  "\th - print help\n";
5 
6 struct test_data
7 {
8  Ecore_Evas *ee;
9  Evas *canvas;
10  Evas_Object *img, *bg;
11  Ecore_Timer *resize_timer, *freeze_timer;
12  Eina_Bool obscured, focus;
13 };
1 /* let's have our events back */
2 static Eina_Bool
3 _thaw_cb(void *data EINA_UNUSED)
4 {
5  fprintf(stdout, "Canvas was frozen %d times, now thawing.\n",
6  evas_event_freeze_get(d.canvas));
7  evas_event_thaw(d.canvas);
8  return EINA_FALSE; /* do not re-issue the timer */
9 }

See the full example.

If you run that example, you'll see the canvas ignoring all input events for 3 seconds, when the "f" key is pressed. In a more realistic code we would be freezing while a toolkit or Edje was doing some UI changes, thawing it back afterwards.

Referenced by edje_file_data_get(), evas_object_smart_callback_call(), and evas_object_table_add().

void evas_event_thaw ( Evas e)

Thaw a canvas out after freezing (for input events).

Parameters
eThe canvas to thaw out.

This will thaw out a canvas after a matching evas_event_freeze() call. If this call completely thaws out a canvas, i.e., there's no other unbalanced call to evas_event_freeze(), events will start to be processed again, but any "missed" events will not be evaluated.

See evas_event_freeze() for an example.

Examples:
evas-events.c.

References EINA_FALSE, EINA_INLIST_FOREACH, EINA_INLIST_GET, and EINA_TRUE.

Referenced by edje_file_data_get(), evas_object_smart_callback_call(), and evas_object_table_add().

int evas_event_freeze_get ( const Evas e)

Return the freeze count on input events of a given canvas.

Parameters
eThe canvas to fetch the freeze count from.

This returns the number of times the canvas has been told to freeze input events. It is possible to call evas_event_freeze() multiple times, and these must be matched by evas_event_thaw() calls. This call allows the program to discover just how many times things have been frozen in case it may want to break out of a deep freeze state where the count is high.

Example:

1 extern Evas *evas;
2 
3 while (evas_event_freeze_get(evas) > 0) evas_event_thaw(evas);
Examples:
evas-events.c.

Referenced by evas_event_thaw_eval().

void evas_event_thaw_eval ( Evas e)

After thaw of a canvas, re-evaluate the state of objects and call callbacks.

Parameters
eThe canvas to evaluate after a thaw

This is normally called after evas_event_thaw() to re-evaluate mouse containment and other states and thus also call callbacks for mouse in and out on new objects if the state change demands it.

References _Evas_Event_Mouse_Down::button, _Evas_Event_Mouse_Up::button, _Evas_Event_Mouse_In::buttons, _Evas_Event_Mouse_Out::buttons, _Evas_Event_Mouse_Move::buttons, _Evas_Position::canvas, _Evas_Precision_Position::canvas, _Evas_Event_Mouse_Down::canvas, _Evas_Event_Mouse_Up::canvas, _Evas_Event_Mouse_In::canvas, _Evas_Event_Mouse_Out::canvas, _Evas_Event_Mouse_Wheel::canvas, _Evas_Event_Key_Down::compose, _Evas_Event_Key_Up::compose, _Evas_Event_Mouse_Move::cur, _Eina_List::data, _Evas_Event_Multi_Down::device, _Evas_Event_Multi_Up::device, _Evas_Event_Multi_Move::device, EINA_FALSE, EINA_INLIST_GET, eina_list_append(), eina_list_data_find(), eina_list_data_get(), EINA_LIST_FOREACH, EINA_LIST_FOREACH_SAFE, eina_list_free(), eina_list_next(), eina_list_remove(), EINA_TRUE, eo_data_scope_get(), ERR, EVAS_CALLBACK_AXIS_UPDATE, EVAS_CALLBACK_HOLD, EVAS_CALLBACK_KEY_DOWN, EVAS_CALLBACK_KEY_UP, EVAS_CALLBACK_MOUSE_DOWN, EVAS_CALLBACK_MOUSE_MOVE, EVAS_CALLBACK_MOUSE_UP, EVAS_CALLBACK_MOUSE_WHEEL, EVAS_CALLBACK_MULTI_DOWN, EVAS_CALLBACK_MULTI_MOVE, EVAS_CALLBACK_MULTI_UP, evas_event_default_flags_get(), evas_event_default_flags_set(), evas_event_feed_axis_update(), evas_event_feed_key_down(), evas_event_feed_key_up(), evas_event_feed_mouse_down(), evas_event_feed_mouse_in(), evas_event_feed_mouse_move(), evas_event_feed_mouse_out(), evas_event_feed_mouse_up(), evas_event_feed_mouse_wheel(), EVAS_EVENT_FLAG_ON_HOLD, evas_event_freeze_get(), evas_object_below_get(), EVAS_OBJECT_POINTER_MODE_NOGRAB, EVAS_OBJECT_POINTER_MODE_NOGRAB_NO_REPEAT_UPDOWN, EVAS_TOUCH_POINT_MOVE, EVAS_TOUCH_POINT_STILL, EVAS_TOUCH_POINT_UP, _Evas_Event_Mouse_Down::flags, _Evas_Event_Mouse_Up::flags, _Evas_Event_Multi_Down::flags, _Evas_Event_Multi_Up::flags, _Evas_Event_Hold::hold, INF, _Evas_Event_Key_Down::key, _Evas_Event_Key_Up::key, _Evas_Event_Key_Down::keycode, _Evas_Event_Key_Up::keycode, _Evas_Event_Key_Down::keyname, _Evas_Event_Key_Up::keyname, _Evas_Event_Mouse_Down::modifiers, _Evas_Event_Mouse_Up::modifiers, _Evas_Event_Mouse_In::modifiers, _Evas_Event_Mouse_Out::modifiers, _Evas_Event_Mouse_Move::modifiers, _Evas_Event_Mouse_Wheel::modifiers, _Evas_Event_Multi_Down::modifiers, _Evas_Event_Multi_Up::modifiers, _Evas_Event_Multi_Move::modifiers, _Evas_Event_Key_Down::modifiers, _Evas_Event_Key_Up::modifiers, _Eina_List::next, _Evas_Position::output, _Evas_Precision_Position::output, _Evas_Event_Mouse_Down::output, _Evas_Event_Mouse_Up::output, _Evas_Event_Mouse_In::output, _Evas_Event_Mouse_Out::output, _Evas_Event_Mouse_Wheel::output, _Evas_Event_Mouse_Move::prev, _Evas_Event_Key_Down::string, _Evas_Event_Key_Up::string, _Evas_Coord_Point::x, _Evas_Coord_Precision_Point::x, _Evas_Point::x, _Evas_Coord_Precision_Point::xsub, _Evas_Coord_Point::y, _Evas_Coord_Precision_Point::y, _Evas_Point::y, and _Evas_Coord_Precision_Point::ysub.

Referenced by edje_file_data_get(), and evas_object_smart_callback_call().