This group provides functions dealing with Evas smart objects (instances).

Smart objects are groupings of primitive Evas objects that behave as a cohesive group. For instance, a file manager icon may be a smart object composed of an image object, a text label, and two rectangles that appear behind the image and text when the icon is selected. As a smart object, the normal Evas object API could be used on the icon object.

Besides that, generally smart objects implement a specific API, so that users interact with its own custom features. The API takes the form of explicit exported functions one may call and smart callbacks.

Smart events and callbacks

Smart objects can elect events (smart events, from now on) occurring inside of them to be reported back to their users via callback functions (smart callbacks). This way, you can extend Evas' own object events. They are defined by an event string, which identifies them uniquely. There is also a function prototype definition for the callback functions: Evas_Smart_Cb.

When defining an Evas_Smart_Class, smart object implementors are strongly encouraged to properly set the Evas_Smart_Class::callbacks callbacks description array, so that the users of the smart object can have introspection on its events API at run time.

Functions
Evas_Object *	evas_object_smart_add (Evas e, Evas_Smart s)
	Instantiates a new smart object described by s.
void	evas_object_smart_member_add (Evas_Object obj, Evas_Object smart_obj)
	Sets an Evas object as a member of a given smart object.
void	evas_object_smart_member_del (Evas_Object *obj)
	Removes a member object from a given smart object.
Eina_List *	evas_object_smart_members_get (const Evas_Object *obj)
	Gets the list of the member objects of a given Evas smart object.
Evas_Object *	evas_object_smart_parent_get (const Evas_Object *obj)
	Gets the parent smart object of a given Evas object, if it has one.
Eina_Bool	evas_object_smart_type_check (const Evas_Object obj, const char type)
	Checks whether a given smart object or any of its smart object parents is of a given smart class.
void *	evas_object_smart_data_get (const Evas_Object *obj)
	Gets the user data stored on a given smart object.
void	evas_object_smart_data_set (Evas_Object obj, void data)
	Sets a pointer to the user data for a given smart object.
void	evas_object_smart_callback_add (Evas_Object obj, const char event, Evas_Smart_Cb func, const void *data)
	Adds or registers a callback function to the smart event specified by event on the smart object obj.
void *	evas_object_smart_callback_del (Evas_Object obj, const char event, Evas_Smart_Cb func)
	Deletes or unregisters a callback function from the smart event specified by event on the smart object obj.
void *	evas_object_smart_callback_del_full (Evas_Object obj, const char event, Evas_Smart_Cb func, const void *data)
	Deletes or unregisters a callback function from the smart event specified by event on the smart object obj.
void	evas_object_smart_callback_call (Evas_Object obj, const char event, void *event_info)
	Calls a given smart callback on the smart object obj.
Eina_Bool	evas_object_smart_callbacks_descriptions_set (Evas_Object obj, const Evas_Smart_Cb_Description descriptions)
	Sets an smart object instance's smart callbacks descriptions.
void	evas_object_smart_callbacks_descriptions_get (const Evas_Object obj, const Evas_Smart_Cb_Description *class_descriptions, unsigned int class_count, const Evas_Smart_Cb_Description **instance_descriptions, unsigned int instance_count)
	Gets a smart object's smart callback descriptions (both instance and class ones).
void	evas_object_smart_changed (Evas_Object *obj)
	Marks smart object as changed, dirty.
void	evas_smart_objects_calculate (Evas *e)
	Calls user-provided `calculate()` smart functions and unset the flag signalling that the object needs to get recalculated to all smart objects in the canvas.
int	evas_smart_objects_calculate_count_get (const Evas *e)
	Gets the internal counter that counts the number of smart calculations.
Typedefs
typedef void(*	Evas_Smart_Cb )(void data, Evas_Object obj, void *event_info)
	Evas smart objects' "smart callback" function signature.

Typedef Documentation

typedef void(* Evas_Smart_Cb)(void *data, Evas_Object *obj, void *event_info)

Evas smart objects' "smart callback" function signature.

Since :: 2.3.1

Function Documentation

Evas_Object* evas_object_smart_add	(	Evas *	e,
		Evas_Smart *	s
	)

Instantiates a new smart object described by s.

This is the function that you should use when defining the public function adding an instance of the new smart object to a given canvas.

Since :: 2.3.1

Parameters:

[in]	e	The canvas on which to add the object
[in]	s	The Evas_Smart describing the smart object

Returns:: A new Evas_Object handle

void evas_object_smart_callback_add	(	Evas_Object *	obj,
		const char *	event,
		Evas_Smart_Cb	func,
		const void *	data
	)

Adds or registers a callback function to the smart event specified by event on the smart object obj.

Since :: 2.3.1

Remarks:: Smart callbacks look very similar to Evas callbacks, but are implemented as smart object's custom ones.; This function adds a function callback to an smart object when the event named event occurs in it. The function is func.; In the event of a memory allocation error during addition of the callback to the object.; A smart callback function must have the Evas_Smart_Cb prototype definition. The first parameter (data) in this definition has the same value passed to evas_object_smart_callback_add() as the data parameter, at runtime. The second parameter obj is a handle to the object on which the event occurred. The third parameter, event_info, is a pointer to data which is totally dependent on the smart object's implementation and semantic for the given event.; There is an infrastructure for introspection on smart objects' events, but no internal smart objects on Evas implement them yet.; The event's name strings are implemented by each smart object. Please refer the documentation of a smart object which you are insterested in.

Parameters:

[in]	obj	A smart object
[in]	event	The event's name string
[in]	func	The callback function
[in]	data	The user data to be passed to the callback function

See also:: Smart events and callbacks for more details.; evas_object_smart_callback_del()

void evas_object_smart_callback_call	(	Evas_Object *	obj,
		const char *	event,
		void *	event_info
	)

Calls a given smart callback on the smart object obj.

This function should be called internally, from the smart object's own code, when some specific event has occurred and the implementor wants to listen to the object's events API (see Smart events and callbacks). The documentation for the smart object should include a list of possible events and what type of event_info to expect for each of them. Also, when defining an Evas_Smart_Class, smart object implementors are strongly encouraged to properly set the Evas_Smart_Class::callbacks callbacks description array, so that the users of the smart object can have introspection on its events API at run time.

Since :: 2.3.1

Parameters:

[in]	obj	The smart object
[in]	event	The event's name string
[in]	event_info	The pointer to an event specific struct or information to pass to the callback functions registered on this smart event

void* evas_object_smart_callback_del	(	Evas_Object *	obj,
		const char *	event,
		Evas_Smart_Cb	func
	)

Deletes or unregisters a callback function from the smart event specified by event on the smart object obj.

This function removes the first added smart callback on the object obj matching the event name event and the registered function pointer func. If the removal is successful it also returns the data pointer that is passed to evas_object_smart_callback_add() (that is the same as the parameter) when the callback(s) is(are) added to the canvas.

Since :: 2.3.1

Parameters:

[in]	obj	A smart object
[in]	event	The event's name string
[in]	func	The callback function

Returns:: The data pointer,
otherwise NULL if it is not successful

See also:: evas_object_smart_callback_add() for more details.

void* evas_object_smart_callback_del_full	(	Evas_Object *	obj,
		const char *	event,
		Evas_Smart_Cb	func,
		const void *	data
	)

Deletes or unregisters a callback function from the smart event specified by event on the smart object obj.

This function removes the first added smart callback on the object obj matching the event name event, the registered function pointer func and the callback data pointer data. If the removal is successful, it also returns the data pointer that is passed to evas_object_smart_callback_add() (that is the same as the parameter) when the callback(s) is(are) added to the canvas. If not successful NULL is returned. A common use would be to remove an exact match of a callback

Since (EFL) :: 1.2

Since :: 2.3.1

Remarks:: To delete all smart event callbacks which match type and func, use evas_object_smart_callback_del().

Parameters:

[in]	obj	A smart object
[in]	event	The event's name string
[in]	func	The callback function
[in]	data	The data pointer that is passed to the callback

Returns:: The data pointer

See also:: evas_object_smart_callback_add() for more details.

void evas_object_smart_callbacks_descriptions_get	(	const Evas_Object *	obj,
		const Evas_Smart_Cb_Description ***	class_descriptions,
		unsigned int *	class_count,
		const Evas_Smart_Cb_Description ***	instance_descriptions,
		unsigned int *	instance_count
	)

Gets a smart object's smart callback descriptions (both instance and class ones).

This function searches for registered callback descriptions for both instance and class of the given smart object. These arrays are sorted by Evas_Smart_Cb_Description::name and also NULL terminated, so both class_count and instance_count can be ignored, if the caller wishes so. The terminator NULL is not counted in these values.

Since :: 2.3.1

Remarks:: If just class descriptions are of interest.; Use NULL pointers on the descriptions or counters that you are not interested in: they are ignored by the function.

Parameters:

[in]	obj	The smart object to get callback descriptions from
[in]	class_descriptions	The class callbacks descriptions array, if any, that is returned If no descriptions are known, `NULL` is returned.
[in]	class_count	The number of class callbacks descriptions, that is returned
[in]	instance_descriptions	The instance callbacks descriptions array, if any, that is returned If no descriptions are known, `NULL` is returned.
[in]	instance_count	The number of instance callbacks descriptions, that is returned

Eina_Bool evas_object_smart_callbacks_descriptions_set	(	Evas_Object *	obj,
		const Evas_Smart_Cb_Description *	descriptions
	)

Sets an smart object instance's smart callbacks descriptions.

Since :: 2.3.1

Remarks:: These descriptions are hints to be used by introspection and are not enforced in any way.; It is not checked if instance callbacks descriptions have the same name as respective possibly registered in the smart object class. Both are kept in different arrays and users of evas_object_smart_callbacks_descriptions_get() should handle this case as they wish.; Because descriptions must be NULL terminated, and because a NULL name makes little sense, too, Evas_Smart_Cb_Description::name must not be NULL.; While instance callbacks descriptions are possible, they are not recommended. Use class callbacks descriptions instead as they make it easier for you to use smart objects and use less memory, as descriptions and arrays are shared among all instances.

Parameters:

[in]	obj	A smart object
[in]	descriptions	`NULL` terminated array with Evas_Smart_Cb_Description descriptions Array elements are not modified at run time, but references to them and their contents are made, so this array should be kept alive during the whole object's lifetime.

Returns:: EINA_TRUE if the descriptions are set successfully, otherwise EINA_FALSE on failure

void evas_object_smart_changed ( Evas_Object * obj )

Marks smart object as changed, dirty.

This function flags the given object as needing recalculation, forcefully. As an effect, on the next rendering cycle its calculate() (see Evas_Smart_Class) smart function is called.

Since :: 2.3.1

Parameters:

[in] obj The given Evas smart object

void* evas_object_smart_data_get ( const Evas_Object * obj )

Gets the user data stored on a given smart object.

Since :: 2.3.1

Parameters:

[in] obj The smart object's handle

Returns:: A pointer to data stored using evas_object_smart_data_set(),
otherwise NULL if none has been set

See also:: evas_object_smart_data_set()

void evas_object_smart_data_set	(	Evas_Object *	obj,
		void *	data
	)

Sets a pointer to the user data for a given smart object.

Since :: 2.3.1

Remarks:: This data is stored independently of the one set by evas_object_data_set(), naturally.

Parameters:

[in]	obj	The smart object's handle
[in]	data	A pointer to user data

See also:: evas_object_smart_data_get()

void evas_object_smart_member_add	(	Evas_Object *	obj,
		Evas_Object *	smart_obj
	)

Sets an Evas object as a member of a given smart object.

Since :: 2.3.1

Remarks:: Members are automatically stacked and layered together with the smart object. The various stacking functions operate on members relative to the other members instead of the entire canvas, since they now live on an exclusive layer (see evas_object_stack_above(), for more details).; Any smart_obj object's specific implementation of the member_add() smart function takes place too, naturally.

Parameters:

[in]	obj	The member object
[in]	smart_obj	The smart object

See also:: evas_object_smart_member_del(); evas_object_smart_members_get()

void evas_object_smart_member_del ( Evas_Object * obj )

Removes a member object from a given smart object.

This function removes a member object from a smart object, if it is added to any. The object is still on the canvas, but no longer associated with whichever smart object it is associated with.

Since :: 2.3.1

Parameters:

[in] obj The member object

See also:: evas_object_smart_member_add() for more details; evas_object_smart_members_get()

Eina_List* evas_object_smart_members_get ( const Evas_Object * obj )

Gets the list of the member objects of a given Evas smart object.

Since (EFL) :: 1.7

Since :: 2.3.1

Remarks:: The returned list should be freed with eina_list_free() when you no longer need it.

Parameters:

[in] obj The smart object to get members from

Returns:: The list of the member objects of obj,
otherwise NULL when a non-smart object is passed

See also:: evas_object_smart_member_add(); evas_object_smart_member_del()

Evas_Object* evas_object_smart_parent_get ( const Evas_Object * obj )

Gets the parent smart object of a given Evas object, if it has one.

Since :: 2.3.1

Parameters:

[in] obj The Evas object to get the parent smart object from

Returns:: The parent smart object of obj
otherwise NULL if obj is not a smart member of any Evas object

Eina_Bool evas_object_smart_type_check	(	const Evas_Object *	obj,
		const char *	type
	)

Checks whether a given smart object or any of its smart object parents is of a given smart class.

Since :: 2.3.1

Remarks:: If obj is not a smart object, this call fails immediately. Otherwise, make sure evas_smart_class_inherit() or its sibling functions were used correctly when creating the smart object's class, so it has a valid parent smart class pointer set.; The checks use smart classes names and string comparison. There is a version of this same check using pointer comparison, since a smart class' name is a single string in Evas.

Parameters:

[in]	obj	An Evas smart object to check the type of
[in]	type	The name (type) of the smart class to check for

Returns:: EINA_TRUE if obj or any of its parents is of type type,
otherwise EINA_FALSE

void evas_smart_objects_calculate ( Evas * e )

Calls user-provided calculate() smart functions and unset the flag signalling that the object needs to get recalculated to all smart objects in the canvas.

Since :: 2.3.1

Parameters:

[in] e The canvas to calculate all smart objects in

int evas_smart_objects_calculate_count_get ( const Evas * e )

Gets the internal counter that counts the number of smart calculations.

Since (EFL) :: 1.1

Since :: 2.3.1

Remarks:: Whenever evas performs smart object calculations on the whole canvas it increments a counter by 1. This is the smart object calculate counter that this function returns the value of. It starts at the value of 0 and increases (and eventually wrap around to negative values and so on) by 1 every time objects are calculated. You can use this counter to ensure that you do not re-do calculations within the same calculation generation or run if the calculations maybe cause self-feeding effects.

Parameters:

[in] e The canvas to get the calculate counter from

Returns:: The number of smart calculations

Smart events and callbacks

Functions

Typedefs

Typedef Documentation

Function Documentation