Canvas Events
Evas » Canvas Functions

Functions relating to canvas events that report on changes of its internal states (an object got focused, the rendering is updated, etc). More...

## Topics

| Input Events Freezing Functions
| Functions that deal with the freezing of input event processing of an Evas canvas.
| Input Events Feeding Functions
| Functions to tell Evas that input events happened and should be processed.

## Data Structures

struct | _Evas_Event_Mouse_Down
| Mouse button press event. More...
struct | _Evas_Event_Mouse_Up
| Mouse button release event. More...
struct | _Evas_Event_Mouse_In
| Mouse enter event. More...
struct | _Evas_Event_Mouse_Out
| Mouse leave event. More...
struct | _Evas_Event_Mouse_Move
| Mouse move event. More...
struct | _Evas_Event_Mouse_Wheel
| Wheel event. More...
struct | _Evas_Event_Multi_Down
| Multi button press event. More...
struct | _Evas_Event_Multi_Up
| Multi button release event. More...
struct | _Evas_Event_Multi_Move
| Multi button down event. More...
struct | _Evas_Event_Key_Down
| Key press event. More...
struct | _Evas_Event_Key_Up
| Key release event. More...
struct | _Evas_Event_Hold
| Hold change event. More...
struct | _Evas_Axis
struct | _Evas_Event_Axis_Update

## Typedefs

typedef struct _Evas_Event_Mouse_Down | Evas_Event_Mouse_Down
| Event structure for EVAS_CALLBACK_MOUSE_DOWN event callbacks.
typedef struct _Evas_Event_Mouse_Up | Evas_Event_Mouse_Up
| Event structure for EVAS_CALLBACK_MOUSE_UP event callbacks.
typedef struct _Evas_Event_Mouse_In | Evas_Event_Mouse_In
| Event structure for EVAS_CALLBACK_MOUSE_IN event callbacks.
typedef struct _Evas_Event_Mouse_Out | Evas_Event_Mouse_Out
| Event structure for EVAS_CALLBACK_MOUSE_OUT event callbacks.
typedef struct _Evas_Event_Mouse_Move | Evas_Event_Mouse_Move
| Event structure for EVAS_CALLBACK_MOUSE_MOVE event callbacks.
typedef struct _Evas_Event_Mouse_Wheel | Evas_Event_Mouse_Wheel
| Event structure for EVAS_CALLBACK_MOUSE_WHEEL event callbacks.
typedef struct _Evas_Event_Multi_Down | Evas_Event_Multi_Down
| Event structure for EVAS_CALLBACK_MULTI_DOWN event callbacks.
typedef struct _Evas_Event_Multi_Up | Evas_Event_Multi_Up
| Event structure for EVAS_CALLBACK_MULTI_UP event callbacks.
typedef struct _Evas_Event_Multi_Move | Evas_Event_Multi_Move
| Event structure for EVAS_CALLBACK_MULTI_MOVE event callbacks.
typedef struct _Evas_Event_Key_Down | Evas_Event_Key_Down
| Event structure for EVAS_CALLBACK_KEY_DOWN event callbacks.
typedef struct _Evas_Event_Key_Up | Evas_Event_Key_Up
| Event structure for EVAS_CALLBACK_KEY_UP event callbacks.
typedef struct _Evas_Event_Hold | Evas_Event_Hold
| Event structure for EVAS_CALLBACK_HOLD event callbacks.
typedef struct _Evas_Event_Axis_Update | Evas_Event_Axis_Update
| Event structure for EVAS_CALLBACK_AXIS_UPDATE event callbacks.
typedef enum _Evas_Axis_Label | Evas_Axis_Label
| Types of recognized device axes.
typedef struct _Evas_Axis | Evas_Axis

## Enumerations

enum

_Evas_Axis_Label {
EVAS_AXIS_LABEL_UNKNOWN ,
EVAS_AXIS_LABEL_X ,
EVAS_AXIS_LABEL_Y ,
EVAS_AXIS_LABEL_PRESSURE ,
EVAS_AXIS_LABEL_DISTANCE ,
EVAS_AXIS_LABEL_AZIMUTH ,
EVAS_AXIS_LABEL_TILT ,
EVAS_AXIS_LABEL_TWIST ,
EVAS_AXIS_LABEL_TOUCH_WIDTH_MAJOR ,
EVAS_AXIS_LABEL_TOUCH_WIDTH_MINOR ,
EVAS_AXIS_LABEL_TOOL_WIDTH_MAJOR ,
EVAS_AXIS_LABEL_TOOL_WIDTH_MINOR ,
EVAS_AXIS_LABEL_WINDOW_X ,
EVAS_AXIS_LABEL_WINDOW_Y ,
EVAS_AXIS_LABEL_NORMAL_X ,
EVAS_AXIS_LABEL_NORMAL_Y
}

## Functions

EVAS_API void | evas_event_callback_add (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data)
| Add (register) a callback function to a given canvas event.
EVAS_API void | evas_event_callback_priority_add (Evas *e, Evas_Callback_Type type, Evas_Callback_Priority priority, Evas_Event_Cb func, const void *data)
| Add (register) a callback function to a given canvas event with a non-default priority set.
EVAS_API void * | evas_event_callback_del (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func)
| Delete a callback function from the canvas.
EVAS_API void * | evas_event_callback_del_full (Evas *e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data)
| Delete (unregister) a callback function registered to a given canvas event.
EVAS_API void | evas_post_event_callback_push (Evas *e, Evas_Object_Event_Post_Cb func, const void *data)
| Push a callback on the post-event callback stack.
EVAS_API void | evas_post_event_callback_remove (Evas *e, Evas_Object_Event_Post_Cb func)
| Remove a callback from the post-event callback stack.
EVAS_API void | evas_post_event_callback_remove_full (Evas *e, Evas_Object_Event_Post_Cb func, const void *data)
| Remove a callback from the post-event callback stack.

## Detailed Description

Functions relating to canvas events that report on changes of its internal states (an object got focused, the rendering is updated, etc).

Some of the functions in this group are exemplified here.

## Typedef Documentation

## Evas_Event_Axis_Update

typedef struct _Evas_Event_Axis_Update Evas_Event_Axis_Update

Event structure for EVAS_CALLBACK_AXIS_UPDATE event callbacks.

Since
  1.13

## Evas_Axis_Label

typedef enum _Evas_Axis_Label Evas_Axis_Label

Types of recognized device axes.

Since
  1.13

## Enumeration Type Documentation

## _Evas_Axis_Label

enum _Evas_Axis_Label

Enumerator

EVAS_AXIS_LABEL_UNKNOWN

Axis containing unknown (or not yet representable) data.

Range: Unbounded. Unit: Undefined.

Since
  1.13

EVAS_AXIS_LABEL_X

Position along physical X axis; not window relative.

Range: Unbounded. Unit: Undefined.

Since
  1.13

EVAS_AXIS_LABEL_Y

Position along physical Y axis; not window relative.

Range: Unbounded. Unit: Undefined.

Since
  1.13

EVAS_AXIS_LABEL_PRESSURE

Force applied to tool tip.

Range: [0.0, 1.0]. Unit: Unitless.

Since
  1.13

EVAS_AXIS_LABEL_DISTANCE

Relative distance along physical Z axis.

Range: [0.0, 1.0]. Unit: Unitless

Since
  1.13

EVAS_AXIS_LABEL_AZIMUTH

Angle of tool about the Z axis from positive X axis.

Range: [-PI, PI]. Unit: Radians.

Since
  1.13

EVAS_AXIS_LABEL_TILT

Angle of tool about plane of sensor from positive Z axis.

Range: [0.0, PI]. Unit: Radians.

Since
  1.13

EVAS_AXIS_LABEL_TWIST

Rotation of tool about its major axis from its "natural" position.

Range: [-PI, PI] Unit: Radians.

Since
  1.13

EVAS_AXIS_LABEL_TOUCH_WIDTH_MAJOR

Length of contact ellipse along AZIMUTH.

Range: Unbounded: Unit: Same as EVAS_AXIS_LABEL_{X,Y}.

Since
  1.13

EVAS_AXIS_LABEL_TOUCH_WIDTH_MINOR

Length of contact ellipse perpendicular to AZIMUTH.

Range: Unbounded. Unit: Same as EVAS_AXIS_LABEL_{X,Y}.

Since
  1.13

EVAS_AXIS_LABEL_TOOL_WIDTH_MAJOR

Length of tool ellipse along AZIMUTH.

Range: Unbounded. Unit: Same as EVAS_AXIS_LABEL_{X,Y}.

Since
  1.13

EVAS_AXIS_LABEL_TOOL_WIDTH_MINOR

Length of tool ellipse perpendicular to AZIMUTH.

Range: Unbounded. Unit: Same as EVAS_AXIS_LABEL_{X,Y}.

Since
  1.13

EVAS_AXIS_LABEL_WINDOW_X

X coordinate mapped to the window.

Since
  1.19

EVAS_AXIS_LABEL_WINDOW_Y

Y coordinate mapped to the window.

Since
  1.19

EVAS_AXIS_LABEL_NORMAL_X

X normalized to the [0, 1] range.

Since
  1.19

EVAS_AXIS_LABEL_NORMAL_Y

Y normalized to the [0, 1] range.

Since
  1.19

## Function Documentation

## evas_event_callback_add()

EVAS_API void evas_event_callback_add | ( | Evas * | e,
|  | Evas_Callback_Type | type,
|  | Evas_Event_Cb | func,
|  | const void * | data )

Add (register) a callback function to a given canvas event.

Parameters

  e | Canvas to attach a callback to
  type | The type of event that will trigger the callback
  func | The (callback) function to be called when the event is triggered
  data | The data pointer to be passed to `func`

This function adds a function callback to the canvas `e` when the event of type `type` occurs on it. The function pointer is `func`.

In the event of a memory allocation error during the addition of the callback to the canvas, evas_alloc_error() should be used to determine the nature of the error, if any, and the program should sensibly try and recover.

A callback function must have the Evas_Event_Cb prototype definition. The first parameter (`data`) in this definition will have the same value passed to evas_event_callback_add() as the `data` parameter, at runtime. The second parameter `e` is the canvas pointer on which the event occurred. The third parameter `event_info` is a pointer to a data structure that may or may not be passed to the callback, depending on the event type that triggered the callback. This is so because some events don't carry extra context with them, but others do.

The event type `type` to trigger the function may be one of EVAS_CALLBACK_RENDER_FLUSH_PRE, EVAS_CALLBACK_RENDER_FLUSH_POST, EVAS_CALLBACK_CANVAS_FOCUS_IN, EVAS_CALLBACK_CANVAS_FOCUS_OUT, EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN and EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_OUT. This determines the kind of event that will trigger the callback to be called. Only the last two of the event types listed here provide useful event information data – a pointer to the recently focused Evas object. For the others the `event_info` pointer is going to be `NULL`.

Example:

evas_event_callback_add(d.canvas, EVAS_CALLBACK_RENDER_FLUSH_PRE,
_render_flush_cb, NULL);
if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE)
{
fprintf(stderr, "ERROR: Callback registering failed! Aborting.\n");
goto panic;
}
evas_event_callback_add(d.canvas, EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN,
_object_focus_in_cb, NULL);
if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE)
{
fprintf(stderr, "ERROR: Callback registering failed! Aborting.\n");
goto panic;
} /* two canvas event callbacks */
EVAS_ALLOC_ERROR_NONE
@ EVAS_ALLOC_ERROR_NONE
No allocation error.
Definition Evas_Common.h:270
EVAS_CALLBACK_RENDER_FLUSH_PRE
@ EVAS_CALLBACK_RENDER_FLUSH_PRE
Called after render update regions have been calculated, but only if update regions exist.
Definition Evas_Common.h:445
EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN
@ EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN
Canvas object got focus.
Definition Evas_Common.h:450
evas_event_callback_add
EVAS_API void evas_event_callback_add(Evas *eo_e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data)
Add (register) a callback function to a given canvas event.
Definition evas_callbacks.c:573
evas_alloc_error
EVAS_API Evas_Alloc_Error evas_alloc_error(void)
Get the error status of the most recent memory allocation call.
Definition main.c:17

Looking to the callbacks registered above,

/* called when our rectangle gets focus */
static void
_object_focus_in_cb(void *data EINA_UNUSED,
Evas *e,
void *event_info)
{
printf("An object got focused: %s\n",
evas_object_name_get(event_info));
printf("Let's recheck it: %s\n",
evas_object_name_get(evas_focus_get(e)));
printf("And again: %s\n", evas_object_focus_get(event_info) ?
"OK!" : "Oops, something is bad.");
}
/* render flush callback */
static void
_render_flush_cb(void *data EINA_UNUSED,
Evas *e EINA_UNUSED,
void *event_info EINA_UNUSED)
{
printf("Canvas is about to flush its rendering pipeline!\n");
}
/* put some action in the canvas */
static Eina_Bool
_resize_cb(void *data EINA_UNUSED)
{
int w, h, cw, ch;
evas_object_geometry_get(d.img, NULL, NULL, &w, &h);
ecore_evas_geometry_get(d.ee, NULL, NULL, &cw, &ch);
if (w < cw)
evas_object_resize(d.img, cw, ch);
else
evas_object_resize(d.img, cw / 2, ch / 2);
return EINA_TRUE; /* re-issue the timer */
}
/* let's have our events back */
ecore_evas_geometry_get
EAPI void ecore_evas_geometry_get(const Ecore_Evas *ee, int *x, int *y, int *w, int *h)
Gets the geometry of an Ecore_Evas.
Definition ecore_evas.c:1376
EINA_TRUE
#define EINA_TRUE
boolean value TRUE (numerical value 1)
Definition eina_types.h:539
Eina_Bool
unsigned char Eina_Bool
Type to mimic a boolean.
Definition eina_types.h:527
EINA_UNUSED
#define EINA_UNUSED
Used to indicate that a function parameter is purposely unused.
Definition eina_types.h:339
Evas
Eo Evas
An opaque handle to an Evas canvas.
Definition Evas_Common.h:163
evas_focus_get
EVAS_API Efl_Canvas_Object * evas_focus_get(const Evas_Canvas *obj)
Retrieve the object focused by the default seat.
Definition evas_canvas_eo.legacy.c:51
evas_object_name_get
EVAS_API const char * evas_object_name_get(const Evas_Object *eo_obj)
Retrieves the name of the given Evas object.
Definition evas_name.c:26
evas_object_geometry_get
EVAS_API void evas_object_geometry_get(const Evas_Object *eo_obj, Evas_Coord *x, Evas_Coord *y, Evas_Coord *w, Evas_Coord *h)
Retrieves the position and (rectangular) size of the given Evas object.
Definition evas_object_main.c:1335
evas_object_focus_get
EVAS_API Eina_Bool evas_object_focus_get(const Efl_Canvas_Object *obj)
Indicates that this object is the keyboard event receiver on its canvas.
Definition efl_canvas_object_eo.legacy.c:45
evas_object_resize
EVAS_API void evas_object_resize(Evas_Object *obj, Evas_Coord w, Evas_Coord h)
Changes the size of the given Evas object.
Definition evas_object_main.c:1236

we see that the canvas flushes its rendering pipeline (EVAS_CALLBACK_RENDER_FLUSH_PRE) whenever the `_resize_cb` routine takes place: it has to redraw that image at a different size. Also, the callback on an object being focused comes just after we focus it explicitly, on code.

See the full example.

Note
  Be careful not to add the same callback multiple times, if that's not what you want, because Evas won't check if a callback existed before exactly as the one being registered (and thus, call it more than once on the event, in this case). This would make sense if you passed different functions and/or callback data, only.

References EVAS_CALLBACK_PRIORITY_DEFAULT, and evas_event_callback_priority_add().

Referenced by ecore_evas_object_image_new().

## evas_event_callback_priority_add()

EVAS_API void evas_event_callback_priority_add | ( | Evas * | e,
|  | Evas_Callback_Type | type,
|  | Evas_Callback_Priority | priority,
|  | Evas_Event_Cb | func,
|  | const void * | data )

Add (register) a callback function to a given canvas event with a non-default priority set.

Except for the priority field, it's exactly the same as evas_event_callback_add

Parameters

  e | Canvas to attach a callback to
  type | The type of event that will trigger the callback
  priority | The priority of the callback, lower values called first.
  func | The (callback) function to be called when the event is triggered
  data | The data pointer to be passed to `func`

See also
  evas_event_callback_add

Since
  1.1

References eina_inlist_append(), EINA_INLIST_GET, EINA_SAFETY_ON_NULL_RETURN, EINA_SAFETY_ON_TRUE_RETURN, EVAS_CALLBACK_RENDER_POST, and EVAS_CANVAS_CLASS.

Referenced by evas_event_callback_add().

## evas_event_callback_del()

EVAS_API void * evas_event_callback_del | ( | Evas * | e,
|  | Evas_Callback_Type | type,
|  | Evas_Event_Cb | func )

Delete a callback function from the canvas.

Parameters

  e | Canvas to remove a callback from
  type | The type of event that was triggering the callback
  func | The function that was to be called when the event was triggered

Returns
  The data pointer that was to be passed to the callback

This function removes the most recently added callback from the canvas `e` which was triggered by the event type `type` and was calling the function `func` when triggered. If the removal is successful it will also return the data pointer that was passed to evas_event_callback_add() when the callback was added to the canvas. If not successful `NULL` will be returned.

Example:

extern Evas *e;
void *my_data;
void focus_in_callback(void *data, Evas *e, void *event_info);
my_data = evas_event_callback_del(ebject, EVAS_CALLBACK_CANVAS_FOCUS_IN, focus_in_callback);
EVAS_CALLBACK_CANVAS_FOCUS_IN
@ EVAS_CALLBACK_CANVAS_FOCUS_IN
Canvas got focus as a whole.
Definition Evas_Common.h:443
evas_event_callback_del
EVAS_API void * evas_event_callback_del(Evas *eo_e, Evas_Callback_Type type, Evas_Event_Cb func)
Delete a callback function from the canvas.
Definition evas_callbacks.c:634

References EINA_INLIST_GET, eina_inlist_remove(), EINA_INLIST_REVERSE_FOREACH, EINA_SAFETY_ON_NULL_RETURN_VAL, EVAS_CALLBACK_RENDER_POST, and EVAS_CANVAS_CLASS.

## evas_event_callback_del_full()

EVAS_API void * evas_event_callback_del_full | ( | Evas * | e,
|  | Evas_Callback_Type | type,
|  | Evas_Event_Cb | func,
|  | const void * | data )

Delete (unregister) a callback function registered to a given canvas event.

Parameters

  e | Canvas to remove an event callback from
  type | The type of event that was triggering the callback
  func | The function that was to be called when the event was triggered
  data | The data pointer that was to be passed to the callback

Returns
  The data pointer that was to be passed to the callback

This function removes the first added callback from the canvas `e` matching the event type `type`, the registered function pointer `func` and the callback data pointer `data`. If the removal is successful it will also return the data pointer that was passed to evas_event_callback_add() (that will be the same as the parameter) when the callback(s) was(were) added to the canvas. If not successful `NULL` will be returned. A common use would be to remove an exact match of a callback.

Example:

evas_event_callback_del_full(evas, EVAS_CALLBACK_RENDER_FLUSH_PRE,
_render_flush_cb, NULL);
evas_event_callback_del_full(
evas, EVAS_CALLBACK_CANVAS_OBJECT_FOCUS_IN,
_object_focus_in_cb, NULL);
evas_event_callback_del_full
EVAS_API void * evas_event_callback_del_full(Evas *eo_e, Evas_Callback_Type type, Evas_Event_Cb func, const void *data)
Delete (unregister) a callback function registered to a given canvas event.
Definition evas_callbacks.c:678

See the full example.

Note
  For deletion of canvas events callbacks filtering by just type and function pointer, user evas_event_callback_del().

References EINA_INLIST_FOREACH, EINA_INLIST_GET, eina_inlist_remove(), EINA_INLIST_REVERSE_FOREACH, EINA_SAFETY_ON_NULL_RETURN_VAL, EVAS_CALLBACK_RENDER_POST, and EVAS_CANVAS_CLASS.

## evas_post_event_callback_push()

EVAS_API void evas_post_event_callback_push | ( | Evas * | e,
|  | Evas_Object_Event_Post_Cb | func,
|  | const void * | data )

Push a callback on the post-event callback stack.

Parameters

  e | Canvas to push the callback on
  func | The function that to be called when the stack is unwound
  data | The data pointer to be passed to the callback

Evas has a stack of callbacks that get called after all the callbacks for an event have triggered (all the objects it triggers on and all the callbacks in each object triggered). When all these have been called, the stack is unwound from most recently to least recently pushed item and removed from the stack calling the callback set for it.

This is intended for doing reverse logic-like processing, example - when a child object that happens to get the event later is meant to be able to "steal" functions from a parent and thus on unwind of this stack have its function called first, thus being able to set flags, or return 0 from the post-callback that stops all other post-callbacks in the current stack from being called (thus basically allowing a child to take control, if the event callback prepares information ready for taking action, but the post callback actually does the action).

This function should only be called from inside an evas input event callback. The event_info data may be kept up until `func` is called, in order to check the state of the "on-hold" flag for instance. Do not modify the canvas or otherwise trigger or feed a events to the canvas from inside `func`. Use jobs to safely modify the canvas.

Warning
  Only use this function if you know exactly what you are doing!

References eina_list_prepend(), EINA_SAFETY_ON_NULL_RETURN, EINA_SAFETY_ON_TRUE_RETURN, ERR, EVAS_CALLBACK_LAST, and EVAS_CANVAS_CLASS.

## evas_post_event_callback_remove()

EVAS_API void evas_post_event_callback_remove | ( | Evas * | e,
|  | Evas_Object_Event_Post_Cb | func )

Remove a callback from the post-event callback stack.

Parameters

  e | Canvas to push the callback on
  func | The function that to be called when the stack is unwound

This removes a callback from the stack added with evas_post_event_callback_push(). The first instance of the function in the callback stack is removed from being executed when the stack is unwound. Further instances may still be run on unwind.

References EINA_LIST_FOREACH, EINA_SAFETY_ON_NULL_RETURN, and EVAS_CANVAS_CLASS.

## evas_post_event_callback_remove_full()

EVAS_API void evas_post_event_callback_remove_full | ( | Evas * | e,
|  | Evas_Object_Event_Post_Cb | func,
|  | const void * | data )

Remove a callback from the post-event callback stack.

Parameters

  e | Canvas to push the callback on
  func | The function that to be called when the stack is unwound
  data | The data pointer to be passed to the callback

This removes a callback from the stack added with evas_post_event_callback_push(). The first instance of the function and data in the callback stack is removed from being executed when the stack is unwound. Further instances may still be run on unwind.

References EINA_LIST_FOREACH, EINA_SAFETY_ON_NULL_RETURN, and EVAS_CANVAS_CLASS.