Tizen Native API
Functions | Typedefs
Object Events
Generic Object Functions

This group provides functions for object events.

Remarks:
Objects generate events when they are moved, resized, when their visibility change, when they are deleted and so on. These methods allow you to be notified about and to handle such events.
Objects also generate events on input (keyboard and mouse), if they accept them (are visible, focused, and so on).
For each of those events, Evas provides a way for one to register callback functions to be issued just after they happen.
The following figure illustrates some Evas (event) callbacks:
evas-callbacks.png
Remarks:
These events have their values in the Evas_Callback_Type enumeration, which also has the happening on the canvas level (see Canvas Events ).

Functions

void evas_object_event_callback_add (Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func, const void *data)
 Adds or registers a callback function to a given Evas object event.
void evas_object_event_callback_priority_add (Evas_Object *obj, Evas_Callback_Type type, Evas_Callback_Priority priority, Evas_Object_Event_Cb func, const void *data)
 Adds or registers a callback function to a given Evas object event with a non-default priority set. Except for the priority field, it is exactly the same as evas_object_event_callback_add.
void * evas_object_event_callback_del (Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func)
 Deletes a callback function from an object.
void * evas_object_event_callback_del_full (Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func, const void *data)
 Deletes or unregisters a callback function registered to a given Evas object event.
void evas_object_pass_events_set (Evas_Object *obj, Eina_Bool pass)
 Sets whether an Evas object is to pass (ignore) events.
Eina_Bool evas_object_pass_events_get (const Evas_Object *obj)
 Checks whether an object is set to pass (ignore) events.
void evas_object_repeat_events_set (Evas_Object *obj, Eina_Bool repeat)
 Sets whether an Evas object is to repeat events.
Eina_Bool evas_object_repeat_events_get (const Evas_Object *obj)
 Checks whether an object is set to repeat events.
void evas_object_propagate_events_set (Evas_Object *obj, Eina_Bool prop)
 Sets whether events on a smart object's member should get propagated up to its parent.
Eina_Bool evas_object_propagate_events_get (const Evas_Object *obj)
 Checks whether an Evas object is set to propagate events.
void evas_object_freeze_events_set (Evas_Object *obj, Eina_Bool freeze)
 Sets whether an Evas object is to freeze (discard) events.
Eina_Bool evas_object_freeze_events_get (const Evas_Object *obj)
 Checks whether an object is set to freeze (discard) events.

Typedefs

typedef void(* Evas_Object_Event_Cb )(void *data, Evas *e, Evas_Object *obj, void *event_info)
 Evas object event callback function signature.

Typedef Documentation

typedef void(* Evas_Object_Event_Cb)(void *data, Evas *e, Evas_Object *obj, void *event_info)

Evas object event callback function signature.

Since :
2.3.1

Function Documentation

void evas_object_event_callback_add ( Evas_Object *  obj,
Evas_Callback_Type  type,
Evas_Object_Event_Cb  func,
const void *  data 
)

Adds or registers a callback function to a given Evas object event.

This function adds a function callback to an object when the event of type type occurs on object obj. The function is func.

Since :
2.3.1
Remarks:
In the event of a memory allocation error during addition of the callback to the object.
A callback function must have the Evas_Object_Event_Cb prototype definition. The first parameter (data) in this definition has the same value passed to evas_object_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 is a pointer to the object on which event occurred. Finally, the fourth 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 do not carry extra context with them, but others do.
The valid event type type to trigger the function are EVAS_CALLBACK_MOUSE_IN, EVAS_CALLBACK_MOUSE_OUT, EVAS_CALLBACK_MOUSE_DOWN, EVAS_CALLBACK_MOUSE_UP, EVAS_CALLBACK_MOUSE_MOVE, EVAS_CALLBACK_MOUSE_WHEEL, EVAS_CALLBACK_MULTI_DOWN, EVAS_CALLBACK_MULTI_UP, EVAS_CALLBACK_MULTI_MOVE, EVAS_CALLBACK_FREE, EVAS_CALLBACK_KEY_DOWN, EVAS_CALLBACK_KEY_UP, EVAS_CALLBACK_FOCUS_IN, EVAS_CALLBACK_FOCUS_OUT, EVAS_CALLBACK_SHOW, EVAS_CALLBACK_HIDE, EVAS_CALLBACK_MOVE, EVAS_CALLBACK_RESIZE, EVAS_CALLBACK_RESTACK, EVAS_CALLBACK_DEL, EVAS_CALLBACK_HOLD, EVAS_CALLBACK_CHANGED_SIZE_HINTS, EVAS_CALLBACK_IMAGE_PRELOADED or EVAS_CALLBACK_IMAGE_UNLOADED.
This determines the kind of event that triggers the callback. The event types are explained below along with their associated event_info pointers:
- EVAS_CALLBACK_MOUSE_IN: event_info is a pointer to an Evas_Event_Mouse_In struct

This event is triggered when the mouse pointer enters the area (not shaded by other objects) of the object obj. This may occur by the mouse pointer being moved or by the object being shown, raised, moved, resized, or other objects being moved out of the way, hidden or lowered, whatever may cause the mouse pointer to get on top of obj, having been on top of another object previously.
  • EVAS_CALLBACK_MOUSE_OUT: event_info is a pointer to an Evas_Event_Mouse_Out struct

    This event is triggered exactly like EVAS_CALLBACK_MOUSE_IN is, but it occurs when the mouse pointer exits an object's area. Note that no mouse out events are reported if the mouse pointer is implicitly grabbed to an object (mouse buttons are down, having been pressed while the pointer is over that object). In these cases, mouse out events are reported once all buttons are released, if the mouse pointer has left the object's area. The indirect ways of taking off the mouse pointer from an object, like cited above, for EVAS_CALLBACK_MOUSE_IN, also apply here, naturally.
  • EVAS_CALLBACK_MOUSE_DOWN: event_info is a pointer to an Evas_Event_Mouse_Down struct

    This event is triggered by a mouse button being pressed while the mouse pointer is over an object. If the pointer mode for Evas is EVAS_OBJECT_POINTER_MODE_AUTOGRAB (default), this causes this object to passively grab the mouse until all mouse buttons have been released: all future mouse events are reported to only this object until no buttons are down. That includes mouse move events, mouse in and mouse out events, and further button presses. When all buttons are released, event propagation occurs as normal (see Evas_Object_Pointer_Mode).
  • EVAS_CALLBACK_MOUSE_UP: event_info is a pointer to an Evas_Event_Mouse_Up struct

    This event is triggered by a mouse button being released while the mouse pointer is over an object's area (or when passively grabbed to an object).
  • EVAS_CALLBACK_FREE: event_info is NULL

    This event is triggered just before Evas is about to free all memory used by an object and remove all references to it. This is useful for programs to use if they attached data to an object and want to free it when the object is deleted. The object is still valid when this callback is called, but after it returns, there is no guarantee on the object's validity.
  • EVAS_CALLBACK_KEY_DOWN: event_info is a pointer to an Evas_Event_Key_Down struct

    This callback is called when a key is pressed and the focus is on the object, or a key has been grabbed to a particular object which wants to intercept the key press regardless of what object has the focus.
  • EVAS_CALLBACK_KEY_UP: event_info is a pointer to an Evas_Event_Key_Up struct

    This callback is called when a key is released and the focus is on the object, or a key has been grabbed to a particular object which wants to intercept the key release regardless of what object has the focus.
  • EVAS_CALLBACK_FOCUS_IN: event_info is NULL

    This event is called when an object gains the focus. When it is called the object has already gained the focus.
  • EVAS_CALLBACK_FOCUS_OUT: event_info is NULL

    This event is triggered when an object loses the focus. When it is called the object has already lost the focus.
  • EVAS_CALLBACK_MOVE: event_info is NULL

    This event is triggered by an object being moved. evas_object_move() can trigger this, as can any object-specific manipulations that would mean the object's origin could move.
  • EVAS_CALLBACK_RESIZE: event_info is NULL

    This event is triggered by an object being resized. Resizes can be triggered by evas_object_resize() or by any object-specific calls that may cause the object to resize.
Remarks:
Be careful not to add the same callback multiple times, if that is not what you want, because Evas does not 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.
Parameters:
[in]objThe object to attach a callback to
[in]typeThe type of event that triggers the callback
[in]funcThe function to be called when the event is triggered
[in]dataThe data pointer to be passed to func
void* evas_object_event_callback_del ( Evas_Object *  obj,
Evas_Callback_Type  type,
Evas_Object_Event_Cb  func 
)

Deletes a callback function from an object.

This function removes the most recently added callback from the object obj which is triggered by the event type type and is calling the function func when triggered. If the removal is successful it also returns the data pointer that is passed to evas_object_event_callback_add() when the callback is added to the object. If not successful NULL is returned.

Since :
2.3.1
Remarks:
The following is an example: 
 extern Evas_Object *object;
 void *my_data;
 void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);

 my_data = evas_object_event_callback_del(object, EVAS_CALLBACK_MOUSE_UP, up_callback);
Parameters:
[in]objThe object to remove a callback from
[in]typeThe type of event triggering the callback
[in]funcThe function to be called when the event is triggered
Returns:
The data pointer to be passed to the callback
void* evas_object_event_callback_del_full ( Evas_Object *  obj,
Evas_Callback_Type  type,
Evas_Object_Event_Cb  func,
const void *  data 
)

Deletes or unregisters a callback function registered to a given Evas object event.

This function removes the most recently added callback from the object obj, which is triggered by the event type type and is calling the function func with data data, when triggered. If the removal is successful it also returns the data pointer that is passed to evas_object_event_callback_add() (that is the same as the parameter) when the callback is added to the object. In case of errors, NULL is returned.

Since :
2.3.1
Remarks:
For deletion of Evas object events callbacks filtering by just type and function pointer, use evas_object_event_callback_del().
The following is an example: 
 extern Evas_Object *object;
 void *my_data;
 void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info);

 my_data = evas_object_event_callback_del_full(object, EVAS_CALLBACK_MOUSE_UP, up_callback, data);
Parameters:
[in]objThe object to remove a callback from
[in]typeThe type of event triggering the callback
[in]funcThe function to be called when the event is triggered
[in]dataThe data pointer to be passed to the callback
Returns:
The data pointer to be passed to the callback
void evas_object_event_callback_priority_add ( Evas_Object *  obj,
Evas_Callback_Type  type,
Evas_Callback_Priority  priority,
Evas_Object_Event_Cb  func,
const void *  data 
)

Adds or registers a callback function to a given Evas object event with a non-default priority set. Except for the priority field, it is exactly the same as evas_object_event_callback_add.

Since (EFL) :
1.1
Since :
2.3.1
Parameters:
[in]objThe object to attach a callback to
[in]typeThe type of event that triggers the callback
[in]priorityThe priority of the callback
Lower values are called first.
[in]funcThe function to be called when the event is triggered
[in]dataThe data pointer to be passed to func
See also:
evas_object_event_callback_add
Eina_Bool evas_object_freeze_events_get ( const Evas_Object *  obj)

Checks whether an object is set to freeze (discard) events.

Since (EFL) :
1.1
Since :
2.3.1
Parameters:
[in]objThe Evas object to get information from
Returns:
EINA_TRUE if obj is set to freeze events,
otherwise EINA_FALSE if it is not set to freeze events
See also:
evas_object_freeze_events_set()
evas_object_pass_events_get()
evas_object_repeat_events_get()
evas_object_propagate_events_get()
void evas_object_freeze_events_set ( Evas_Object *  obj,
Eina_Bool  freeze 
)

Sets whether an Evas object is to freeze (discard) events.

Since (EFL) :
1.1
Since :
2.3.1
Remarks:
If freeze is EINA_TRUE, it makes events on obj to be discarded. Unlike evas_object_pass_events_set(), events are not passed to next lower object. This API can be used for blocking events while obj is on transiting.
If freeze is EINA_FALSE, events are processed on that object as normal.
Parameters:
[in]objThe Evas object to operate on
[in]freezeSet EINA_TRUE for obj to freeze events,
otherwise EINA_FALSE not to freeze events
See also:
evas_object_freeze_events_get()
evas_object_pass_events_set()
evas_object_repeat_events_set()
evas_object_propagate_events_set()
Eina_Bool evas_object_pass_events_get ( const Evas_Object *  obj)

Checks whether an object is set to pass (ignore) events.

Since :
2.3.1
Parameters:
[in]objThe Evas object to get information from
Returns:
EINA_TRUE if obj is set to pass events,
otherwise EINA_FALSE if it is not set to pass events
See also:
evas_object_pass_events_set()
evas_object_repeat_events_get()
evas_object_propagate_events_get()
evas_object_freeze_events_get()
void evas_object_pass_events_set ( Evas_Object *  obj,
Eina_Bool  pass 
)

Sets whether an Evas object is to pass (ignore) events.

Since :
2.3.1
Remarks:
If pass is EINA_TRUE, it makes events on obj to be ignored. They instead are triggered on the next lower object that is not set to pass events. See evas_object_below_get().
If pass is EINA_FALSE, events are processed on that object as normal.
Parameters:
[in]objThe Evas object to operate on
[in]passSet EINA_TRUE for obj to pass events,
otherwise EINA_FALSE not to pass events
See also:
evas_object_pass_events_get() for an example
evas_object_repeat_events_set()
evas_object_propagate_events_set()
evas_object_freeze_events_set()
Eina_Bool evas_object_propagate_events_get ( const Evas_Object *  obj)

Checks whether an Evas object is set to propagate events.

Since :
2.3.1
Parameters:
[in]objThe given Evas object pointer
Returns:
EINA_TRUE if obj is set to propagate events,
otherwise EINA_FALSE it is not set to propagate events
See also:
evas_object_propagate_events_set()
evas_object_repeat_events_get()
evas_object_pass_events_get()
evas_object_freeze_events_get()
void evas_object_propagate_events_set ( Evas_Object *  obj,
Eina_Bool  prop 
)

Sets whether events on a smart object's member should get propagated up to its parent.

This function has no effect if obj is not a member of a smart object.

Since :
2.3.1
Remarks:
If prop is EINA_TRUE, events occurring on this object is propagated on to the smart object of which obj is a member. If prop is EINA_FALSE, events occurring on this object is not propagated on to the smart object of which obj is a member. The default value is EINA_TRUE.
Parameters:
[in]objThe smart object's child to operate on
[in]propSet EINA_TRUE to propagate events,
otherwise EINA_FALSE to not propagate events
See also:
evas_object_propagate_events_get()
evas_object_repeat_events_set()
evas_object_pass_events_set()
evas_object_freeze_events_set()
Eina_Bool evas_object_repeat_events_get ( const Evas_Object *  obj)

Checks whether an object is set to repeat events.

Since :
2.3.1
Parameters:
[in]objThe given Evas object pointer
Returns:
EINA_TRUE if obj is set to repeat events, otherwise EINA_FALSE if it is not set to repeat events
See also:
evas_object_repeat_events_set() for an example
evas_object_pass_events_get()
evas_object_propagate_events_get()
evas_object_freeze_events_get()
void evas_object_repeat_events_set ( Evas_Object *  obj,
Eina_Bool  repeat 
)

Sets whether an Evas object is to repeat events.

Since :
2.3.1
Remarks:
If repeat is EINA_TRUE, it makes events on obj to also be repeated for the next lower object in the objects' stack. See evas_object_below_get().
If repeat is EINA_FALSE, events occurring on obj are processed only on it.
Parameters:
[in]objThe Evas object to operate on
[in]repeatSet EINA_TRUE for obj to repeat events,
otherwise set EINA_FALSE
See also:
evas_object_repeat_events_get()
evas_object_pass_events_set()
evas_object_propagate_events_set()
evas_object_freeze_events_set()