Object Events
[Generic Object Functions]
Objects generates events when they are moved, resized, when their visibility change, when they are deleted and so on. More...
Functions | |
EAPI void | evas_object_event_callback_add (Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func, const void *data) |
Add a callback function to an object. | |
EAPI void * | evas_object_event_callback_del (Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func) |
Delete a callback function from an object. | |
EAPI void * | evas_object_event_callback_del_full (Evas_Object *obj, Evas_Callback_Type type, Evas_Object_Event_Cb func, const void *data) |
Delete a callback function from an object. | |
EAPI void | evas_object_pass_events_set (Evas_Object *obj, Eina_Bool pass) |
Set an object's pass events state. | |
EAPI Eina_Bool | evas_object_pass_events_get (const Evas_Object *obj) |
Determine whether an object is set to pass events. | |
EAPI void | evas_object_repeat_events_set (Evas_Object *obj, Eina_Bool repeat) |
Set an object's repeat events state. | |
EAPI Eina_Bool | evas_object_repeat_events_get (const Evas_Object *obj) |
Determine whether an object is set to repeat events. | |
EAPI void | evas_object_propagate_events_set (Evas_Object *obj, Eina_Bool prop) |
Set whether events on a smart member object should propagate to its parent. | |
EAPI Eina_Bool | evas_object_propagate_events_get (const Evas_Object *obj) |
Determine whether an object is set to propagate events. |
Detailed Description
Objects generates events when they are moved, resized, when their visibility change, when they are deleted and so on.
These methods will allow one to handle such events.
The events can be those from keyboard and mouse, if the object accepts these events.
Function Documentation
EAPI void evas_object_event_callback_add | ( | Evas_Object * | obj, | |
Evas_Callback_Type | type, | |||
Evas_Object_Event_Cb | func, | |||
const void * | data | |||
) |
Add a callback function to an object.
- Parameters:
-
obj Object to attach a callback to type The type of event that will trigger the callback func The 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 an object when the event of type type
occurs on object obj
. The function is func
.
In the event of a memory allocation error during addition of the callback to the object, evas_alloc_error() should be used to determine the nature of the error, if any, and the program should sensibly try and recover.
The function will be passed the pointer data
when it is called. A callback function must look like this:
void callback (void *data, Evas *e, Evas_Object *obj, void *event_info);
The first parameter data
in this function will be the same value passed to evas_object_event_callback_add() as the data
parameter. The second parameter is a convenience for the programmer to know what evas canvas the event occurred on. The third parameter obj
is the Object handle on which the event occurred. The foruth 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.
The event type type
to trigger the function may be one of 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_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 or EVAS_CALLBACK_RESTACK. This determines the kind of event that will trigger the callback to be called. The event_info
pointer passed to the callback will be one of the following, depending on the event triggering it:
EVAS_CALLBACK_MOUSE_IN: event_info = pointer to Evas_Event_Mouse_In
This event is triggered when the mouse pointer enters the region of the object obj
. This may occur by the mouse pointer being moved by evas_event_feed_mouse_move() or evas_event_feed_mouse_move_data() calls, or by the object being shown, raised, moved, resized, or other objects being moved out of the way, hidden, lowered or moved out of the way.
EVAS_CALLBACK_MOUSE_OUT: event_info = pointer to Evas_Event_Mouse_Out
This event is triggered exactly like EVAS_CALLBACK_MOUSE_IN is, but occurs when the mouse pointer exits an object. Note that no out events will be reported if the mouse pointer is implicitly grabbed to an object (the mouse buttons are down at all and any were pressed on that object). An out event will be reported as soon as the mouse is no longer grabbed (no mouse buttons are depressed). Out events will be reported once all buttons are released, if the mouse has left the object.
EVAS_CALLBACK_MOUSE_DOWN: event_info = pointer to Evas_Event_Mouse_Down
This event is triggered by a mouse button being depressed while over an object. If pointermode is EVAS_OBJECT_POINTER_MODE_AUTOGRAB (default) this causes this object to passively grab the mouse until all mouse buttons have been released. That means if this mouse button is the first to be pressed, all future mouse events will be reported to only this object until no buttons are down. That includes mouse move events, in and out events, and further button presses. When all buttons are released, event propagation occurs as normal.
EVAS_CALLBACK_MOUSE_UP: event_info = pointer to Evas_Event_Mouse_Up
This event is triggered by a mouse button being released while over an object or when passively grabbed to an object. If this is the last mouse button to be raised on an object then the passive grab is released and event processing will continue as normal.
EVAS_CALLBACK_MOUSE_MOVE: event_info = pointer to Evas_Event_Mouse_Move
This event is triggered by the mouse pointer moving while over an object or passively grabbed to an object.
EVAS_CALLBACK_MOUSE_WHEEL: event_info = pointer to Evas_Event_Mouse_Wheel
This event is triggered by the mouse wheel being rolled while over an object or passively grabbed to an object.
EVAS_CALLBACK_FREE: event_info = 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 this callback returns, there is no guarantee on the object's validity.
EVAS_CALLBACK_KEY_DOWN: event_info = pointer to Evas_Event_Key_Down
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 = pointer to Evas_Event_Key_Up
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 = NULL
This event is called when an object gains the focus. When the callback is called the object has already gained the focus.
EVAS_CALLBACK_FOCUS_OUT: event_info = NULL
This event is triggered by an object losing the focus. When the callback is called the object has already lost the focus.
EVAS_CALLBACK_SHOW: event_info = NULL
This event is triggered by the object being shown by evas_object_show().
EVAS_CALLBACK_HIDE: event_info = NULL
This event is triggered by an object being hidden by evas_object_hide().
EVAS_CALLBACK_MOVE: event_info = 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 = 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.
Example:
extern Evas_Object *object; extern void *my_data; void down_callback(void *data, Evas *e, Evas_Object *obj, void *event_info); void up_callback(void *data, Evas *e, Evas_Object *obj, void *event_info); evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_UP, up_callback, my_data); if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE) { fprintf(stderr, "ERROR: Callback registering failed! Abort!\n"); exit(-1); } evas_object_event_callback_add(object, EVAS_CALLBACK_MOUSE_DOWN, down_callback, my_data); if (evas_alloc_error() != EVAS_ALLOC_ERROR_NONE) { fprintf(stderr, "ERROR: Callback registering failed! Abort!\n"); exit(-1); }
Referenced by evas_object_image_filled_set().
EAPI void* evas_object_event_callback_del | ( | Evas_Object * | obj, | |
Evas_Callback_Type | type, | |||
Evas_Object_Event_Cb | func | |||
) |
Delete a callback function from an object.
- Parameters:
-
obj Object 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 object obj
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_object_event_callback_add() when the callback was added to the object. If not successful NULL will be returned.
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);
Referenced by evas_object_image_filled_set().
EAPI void* evas_object_event_callback_del_full | ( | Evas_Object * | obj, | |
Evas_Callback_Type | type, | |||
Evas_Object_Event_Cb | func, | |||
const void * | data | |||
) |
Delete a callback function from an object.
- Parameters:
-
obj Object 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 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 most recently added callback from the object obj
which was triggered by the event type type
and was calling the function func
with data data
when triggered. If the removal is successful it will also return the data pointer that was passed to evas_object_event_callback_add() (that will be the same as the parameter) when the callback was added to the object. If not successful NULL will be returned.
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);
EAPI Eina_Bool evas_object_pass_events_get | ( | const Evas_Object * | obj | ) |
Determine whether an object is set to pass events.
- Parameters:
-
obj
- Returns:
- pass events state
EAPI void evas_object_pass_events_set | ( | Evas_Object * | obj, | |
Eina_Bool | pass | |||
) |
Set an object's pass events state.
- Parameters:
-
obj the evas object pass whether to pass events or not
If pass
is true, this will cause events on obj
to be ignored. They will be triggered on the next lower object (that is not set to pass events) instead.
If pass
is false, events will be processed as normal.
References evas_event_feed_mouse_move().
EAPI Eina_Bool evas_object_propagate_events_get | ( | const Evas_Object * | obj | ) |
Determine whether an object is set to propagate events.
- Parameters:
-
obj
- Returns:
- propagate events state
EAPI void evas_object_propagate_events_set | ( | Evas_Object * | obj, | |
Eina_Bool | prop | |||
) |
Set whether events on a smart member object should propagate to its parent.
- Parameters:
-
obj the smart member object prop wheter to propagate events or not
This function has no effect if obj
is not a member of a smart object.
If prop
is true, events occurring on this object will propagate on to the smart object of which obj
is a member.
If prop
is false, events for which callbacks are set on the member object, obj
, will not be passed on to the parent smart object.
The default value is true.
EAPI Eina_Bool evas_object_repeat_events_get | ( | const Evas_Object * | obj | ) |
Determine whether an object is set to repeat events.
- Parameters:
-
obj
- Returns:
- repeat events state
EAPI void evas_object_repeat_events_set | ( | Evas_Object * | obj, | |
Eina_Bool | repeat | |||
) |
Set an object's repeat events state.
- Parameters:
-
obj the object repeat wheter to repeat events or not
If repeat
is true, this will cause events on obj
to trigger callbacks, but also to be repeated on the next lower object in the stack.
If repeat
is false, events occurring on obj
will be processed normally.
References evas_event_feed_mouse_move().