Functions that deal with #Evas_Smart structs, creating definition (classes) of objects that will have customized behavior for methods like evas_object_move(), evas_object_resize(), evas_object_clip_set() and others.

These objects will accept the generic methods defined in Generic Object Functions and the extensions defined in Smart Object Functions. There are a couple of existent smart objects in Evas itself (see Box Smart Object, Table Smart Object. and Clipped Smart Object).

See also some examples of this group of functions.

Functions
void	evas_smart_free (Evas_Smart *s)
Evas_Smart *	evas_smart_class_new (const Evas_Smart_Class *sc)
const Evas_Smart_Class *	evas_smart_class_get (const Evas_Smart *s)
void *	evas_smart_data_get (const Evas_Smart *s)
	Get the data pointer set on an #Evas_Smart struct.
const Evas_Smart_Cb_Description **	evas_smart_callbacks_descriptions_get (const Evas_Smart s, unsigned int count)
const Evas_Smart_Cb_Description *	evas_smart_callback_description_find (const Evas_Smart s, const char name)
Eina_Bool	evas_smart_class_inherit_full (Evas_Smart_Class sc, const Evas_Smart_Class parent_sc, unsigned int parent_sc_size)
int	evas_smart_usage_get (const Evas_Smart *s)
Typedefs
typedef struct _Evas_Smart_Class	Evas_Smart_Class
typedef struct _Evas_Smart_Interface	Evas_Smart_Interface
typedef struct _Evas_Smart_Cb_Description	Evas_Smart_Cb_Description
Defines
#define	EVAS_SMART_CLASS_VERSION 4
#define	EVAS_SMART_CLASS_INIT_NULL {NULL, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
#define	EVAS_SMART_CLASS_INIT_VERSION {NULL, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
#define	EVAS_SMART_CLASS_INIT_NAME_VERSION(name) {name, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
#define	EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT(name, parent) {name, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, parent, NULL, NULL}
#define	EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS(name, parent, callbacks) {name, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, parent, callbacks, NULL}
#define	EVAS_SMART_SUBCLASS_NEW(smart_name, prefix, api_type, parent_type, parent_func, cb_desc)
#define	EVAS_SMART_SUBCLASS_IFACE_NEW(smart_name,prefix,api_type,parent_type,parent_func,cb_desc,ifaces)
#define	EVAS_SMART_DATA_ALLOC(o, priv_type)
#define	evas_smart_class_inherit(sc, parent_sc) evas_smart_class_inherit_full(sc, (Evas_Smart_Class )parent_sc, sizeof(parent_sc))

Define Documentation

#define evas_smart_class_inherit	(	sc,
		parent_sc
	)	evas_smart_class_inherit_full(sc, (Evas_Smart_Class )parent_sc, sizeof(parent_sc))

Easy to use version of evas_smart_class_inherit_full().

This version will use sizeof(parent_sc), copying everything.

Parameters:

sc	child class, will have methods copied from parent_sc
parent_sc	parent class, will provide contents to be copied.

Returns:: 1 on success, 0 on failure.

#define EVAS_SMART_CLASS_INIT_NAME_VERSION ( name ) {name, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}

Initializer to zero a whole Evas_Smart_Class structure and set name and version.

Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to latest EVAS_SMART_CLASS_VERSION and name to the specified value.

It will keep a reference to name field as a "const char *", that is, name must be available while the structure is used (hint: static or global!) and will not be modified.

See also:: EVAS_SMART_CLASS_INIT_NULL; EVAS_SMART_CLASS_INIT_VERSION; EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT; EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS

#define EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT	(	name,
		parent
	)	{name, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, parent, NULL, NULL}

Initializer to zero a whole Evas_Smart_Class structure and set name, version and parent class.

Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to latest EVAS_SMART_CLASS_VERSION, name to the specified value and parent class.

It will keep a reference to name field as a "const char *", that is, name must be available while the structure is used (hint: static or global!) and will not be modified. Similarly, parent reference will be kept.

See also:: EVAS_SMART_CLASS_INIT_NULL; EVAS_SMART_CLASS_INIT_VERSION; EVAS_SMART_CLASS_INIT_NAME_VERSION; EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS

#define EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS	(	name,
		parent,
		callbacks
	)	{name, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, parent, callbacks, NULL}

Initializer to zero a whole Evas_Smart_Class structure and set name, version, parent class and callbacks definition.

Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to latest EVAS_SMART_CLASS_VERSION, name to the specified value, parent class and callbacks at this level.

It will keep a reference to name field as a "const char *", that is, name must be available while the structure is used (hint: static or global!) and will not be modified. Similarly, parent and callbacks reference will be kept.

See also:: EVAS_SMART_CLASS_INIT_NULL; EVAS_SMART_CLASS_INIT_VERSION; EVAS_SMART_CLASS_INIT_NAME_VERSION; EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT

#define EVAS_SMART_CLASS_INIT_NULL {NULL, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}

Initializer to zero a whole Evas_Smart_Class structure.

See also:: EVAS_SMART_CLASS_INIT_VERSION; EVAS_SMART_CLASS_INIT_NAME_VERSION; EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT; EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS

#define EVAS_SMART_CLASS_INIT_VERSION {NULL, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}

Initializer to zero a whole Evas_Smart_Class structure and set version.

Similar to EVAS_SMART_CLASS_INIT_NULL, but will set version field to latest EVAS_SMART_CLASS_VERSION.

See also:: EVAS_SMART_CLASS_INIT_NULL; EVAS_SMART_CLASS_INIT_NAME_VERSION; EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT; EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS

#define EVAS_SMART_CLASS_VERSION 4

The version you have to put into the version field in the Evas_Smart_Class struct. Used to safeguard from binaries with old smart object intefaces running with newer ones.

#define EVAS_SMART_DATA_ALLOC	(	o,
		priv_type
	)

Value:

priv_type * priv;                                      \
  priv = evas_object_smart_data_get(o);                  \
  if (!priv) {                                           \
       priv = (priv_type *)calloc(1, sizeof(priv_type)); \
       if (!priv) return;                                \
       evas_object_smart_data_set(o, priv);              \
    }

Convenience macro to allocate smart data only if needed.

When writing a subclassable smart object, the .add() function will need to check if the smart private data was already allocated by some child object or not. This macro makes it easier to do it.

Note:: This is an idiom used when one calls the parent's .add() after the specialized code. Naturally, the parent's base smart data has to be contemplated as the specialized one's first member, for things to work.

Parameters:

o	Evas object passed to the .add() function
priv_type	The type of the data to allocate

Examples:: evas-smart-interface.c, and evas-smart-object.c.

#define EVAS_SMART_SUBCLASS_IFACE_NEW	(	smart_name,
		prefix,
		api_type,
		parent_type,
		parent_func,
		cb_desc,
		ifaces
	)

Value:

static const parent_type * prefix##_parent_sc = NULL;    \
  static void prefix##_smart_set_user(api_type * api);     \
  static void prefix##_smart_set(api_type * api)           \
  {                                                        \
     Evas_Smart_Class *sc;                                 \
     if (!(sc = (Evas_Smart_Class *)api))                  \
       return;                                             \
     if (!prefix##_parent_sc)                              \
       prefix##_parent_sc = parent_func();                 \
     evas_smart_class_inherit(sc, prefix##_parent_sc);     \
     prefix##_smart_set_user(api);                         \
  }                                                        \
  static Evas_Smart *prefix##_smart_class_new(void)        \
  {                                                        \
     static Evas_Smart *smart = NULL;                      \
     static api_type api;                                  \
     if (!smart)                                           \
       {                                                   \
          Evas_Smart_Class *sc = (Evas_Smart_Class *)&api; \
          memset(&api, 0, sizeof(api_type));               \
          sc->version = EVAS_SMART_CLASS_VERSION;          \
          sc->name = smart_name;                           \
          sc->callbacks = cb_desc;                         \
          sc->interfaces = ifaces;                         \
          prefix##_smart_set(&api);                        \
          smart = evas_smart_class_new(sc);                \
       }                                                   \
     return smart;                                         \
  }

Since (EFL) :: 1.7

Convenience macro to subclass a given Evas smart class. This is the same as EVAS_SMART_SUBCLASS_NEW, but now declaring smart interfaces besides the smart callbacks.

Parameters:

smart_name	The name used for the smart class. e.g: `"Evas_Object_Box"`.
prefix	Prefix used for all variables and functions defined and referenced by this macro.
api_type	Type of the structure used as API for the smart class. Either Evas_Smart_Class or something derived from it.
parent_type	Type of the parent class API.
parent_func	Function that gets the parent class. e.g: evas_object_box_smart_class_get().
cb_desc	Array of smart callback descriptions for this smart class.
ifaces	Array of Evas smart interafaces for this smart class.

This macro saves some typing when writing a smart class derived from another one. In order to work, the user must provide some functions adhering to the following guidelines:

<prefix>_smart_set_user(): the internal _smart_set function (defined by this macro) will call this one, provided by the user, after inheriting everything from the parent, which should take care of setting the right member functions for the class, both overrides and extensions, if any.
If this new class should be subclassable as well, a public _smart_set() function is desirable to fill in the class used as parent by the children. It's up to the user to provide this interface, which will most likely call <prefix>_smart_set() to get the job done.

After the macro's usage, the following will be defined for use:

<prefix>_parent_sc: A pointer to the parent smart class. When calling parent functions from overloaded ones, use this global variable.
<prefix>_smart_class_new(): this function returns the #Evas_Smart needed to create smart objects with this class, which should be passed to evas_object_smart_add().

Warning:: smart_name has to be a pointer to a globally available string! The smart class created here will just have a pointer set to that, and all object instances will depend on it for smart class name lookup.

Examples:: evas-smart-interface.c.

#define EVAS_SMART_SUBCLASS_NEW	(	smart_name,
		prefix,
		api_type,
		parent_type,
		parent_func,
		cb_desc
	)

Value:

static const parent_type * prefix##_parent_sc = NULL;                                          \
  static void prefix##_smart_set_user(api_type * api);                                           \
  static void prefix##_smart_set(api_type * api)                                                 \
  {                                                                                              \
     Evas_Smart_Class *sc;                                                                       \
     if (!(sc = (Evas_Smart_Class *)api))                                                        \
       return;                                                                                   \
     if (!prefix##_parent_sc)                                                                    \
       prefix##_parent_sc = parent_func();                                                       \
     evas_smart_class_inherit(sc, prefix##_parent_sc);                                           \
     prefix##_smart_set_user(api);                                                               \
  }                                                                                              \
  static Evas_Smart *prefix##_smart_class_new(void)                                              \
  {                                                                                              \
     static Evas_Smart *smart = NULL;                                                            \
     static api_type api;                                                                        \
     if (!smart)                                                                                 \
       {                                                                                         \
          Evas_Smart_Class *sc = (Evas_Smart_Class *)&api;                                       \
          memset(&api, 0, sizeof(api_type));                                                     \
          sc->version = EVAS_SMART_CLASS_VERSION;                                                \
          sc->name = smart_name;                                                                 \
          sc->callbacks = cb_desc;                                                               \
          prefix##_smart_set(&api);                                                              \
          smart = evas_smart_class_new(sc);                                                      \
       }                                                                                         \
     return smart;                                                                               \
  }

Convenience macro to subclass a given Evas smart class.

Parameters:

smart_name	The name used for the smart class. e.g: `"Evas_Object_Box"`.
prefix	Prefix used for all variables and functions defined and referenced by this macro.
api_type	Type of the structure used as API for the smart class. Either Evas_Smart_Class or something derived from it.
parent_type	Type of the parent class API.
parent_func	Function that gets the parent class. e.g: evas_object_box_smart_class_get().
cb_desc	Array of callback descriptions for this smart class.

This macro saves some typing when writing a smart class derived from another one. In order to work, the user must provide some functions adhering to the following guidelines:

<prefix>_smart_set_user(): the internal _smart_set function (defined by this macro) will call this one, provided by the user, after inheriting everything from the parent, which should take care of setting the right member functions for the class, both overrides and extensions, if any.
If this new class should be subclassable as well, a public _smart_set() function is desirable to fill in the class used as parent by the children. It's up to the user to provide this interface, which will most likely call <prefix>_smart_set() to get the job done.

After the macro's usage, the following will be defined for use:

<prefix>_parent_sc: A pointer to the parent smart class. When calling parent functions from overloaded ones, use this global variable.
<prefix>_smart_class_new(): this function returns the #Evas_Smart needed to create smart objects with this class, which should be passed to evas_object_smart_add().

Warning:: smart_name has to be a pointer to a globally available string! The smart class created here will just have a pointer set to that, and all object instances will depend on it for smart class name lookup.

Examples:: evas-smart-object.c.

Typedef Documentation

Evas_Smart_Cb_Description

A smart object callback description, used to provide introspection

Evas_Smart_Class

A smart object's base class definition

Evas_Smart_Interface

A smart object's base interface definition

An Evas interface is exactly like the OO-concept: an 'contract' or API a given object is declared to support. A smart object may have more than one interface, thus extending the behavior it gets from sub-classing.

Since (EFL) :: 1.7

Function Documentation

const Evas_Smart_Cb_Description* evas_smart_callback_description_find	(	const Evas_Smart *	s,
		const char *	name
	)

Find a callback description for the callback named name.

Parameters:

s	The #Evas_Smart where to search for class registered smart event callbacks.
name	Name of the desired callback, which must not be `NULL`. The search has a special case for name being the same pointer as registered with Evas_Smart_Cb_Description. One can use it to avoid excessive use of strcmp().

Returns:: A reference to the description if found, or NULL, otherwise

See also:: evas_smart_callbacks_descriptions_get()

Since :: 3.0

const Evas_Smart_Cb_Description** evas_smart_callbacks_descriptions_get	(	const Evas_Smart *	s,
		unsigned int *	count
	)

Get the smart callbacks known by this #Evas_Smart handle's smart class hierarchy.

Parameters:

	s	A valid #Evas_Smart handle.
[out]	count	Returns the number of elements in the returned array.

Returns:: The array with callback descriptions known by this smart class, with its size returned in count parameter. It should not be modified in any way. If no callbacks are known, NULL is returned. The array is sorted by event names and elements refer to the original values given to evas_smart_class_new()'s Evas_Smart_Class::callbacks (pointer to them).

This is likely different from evas_object_smart_callbacks_descriptions_get() as it will contain the callbacks of all this class hierarchy sorted, while the direct smart class member refers only to that specific class and should not include parent's.

If no callbacks are known, this function returns NULL.

The array elements and thus their contents will be references to original values given to evas_smart_class_new() as Evas_Smart_Class::callbacks.

The array is sorted by Evas_Smart_Cb_Description::name. The last array element is a NULL pointer and is not accounted for in count. Loop iterations can check any of these size indicators.

Note:: objects may provide per-instance callbacks, use evas_object_smart_callbacks_descriptions_get() to get those as well.

See also:: evas_object_smart_callbacks_descriptions_get()

Since :: 3.0

const Evas_Smart_Class* evas_smart_class_get ( const Evas_Smart * s )

Get the Evas_Smart_Class handle of an #Evas_Smart struct

Parameters:

s	a valid #Evas_Smart pointer

Returns:: the Evas_Smart_Class in it

Since :: 3.0

Eina_Bool evas_smart_class_inherit_full	(	Evas_Smart_Class *	sc,
		const Evas_Smart_Class *	parent_sc,
		unsigned int	parent_sc_size
	)

Sets one class to inherit from the other.

Copy all function pointers, set parent to parent_sc and copy everything after sizeof(Evas_Smart_Class) present in parent_sc, using parent_sc_size as reference.

This is recommended instead of a single memcpy() since it will take care to not modify sc name, version, callbacks and possible other members.

Parameters:

sc	child class.
parent_sc	parent class, will provide attributes.
parent_sc_size	size of parent_sc structure, child should be at least this size. Everything after `Evas_Smart_Class` size is copied using regular memcpy().

Since :: 3.0

Evas_Smart* evas_smart_class_new ( const Evas_Smart_Class * sc )

Creates a new #Evas_Smart from a given Evas_Smart_Class struct

Parameters:

sc	the smart class definition

Returns:: a new #Evas_Smart pointer

#Evas_Smart handles are necessary to create new instances of smart objects belonging to the class described by sc. That handle will contain, besides the smart class interface definition, all its smart callbacks infrastructure set, too.

Note:: If you are willing to subclass a given smart class to construct yours, consider using the EVAS_SMART_SUBCLASS_NEW macro, which will make use of this function automatically for you.

Since :: 3.0

void* evas_smart_data_get ( const Evas_Smart * s )

Get the data pointer set on an #Evas_Smart struct.

Parameters:

s	a valid #Evas_Smart handle

This data pointer is set as the data field in the Evas_Smart_Class passed in to evas_smart_class_new().

Since :: 3.0

void evas_smart_free ( Evas_Smart * s )

Free an #Evas_Smart struct

Parameters:

s	the #Evas_Smart struct to free

Warning:: If this smart handle was created using evas_smart_class_new(), the associated Evas_Smart_Class will not be freed.

Note:: If you're using the EVAS_SMART_SUBCLASS_NEW schema to create your smart object, note that an #Evas_Smart handle will be shared amongst all instances of the given smart class, through a static variable. Evas will internally count references on #Evas_Smart handles and free them when they are not referenced anymore. Thus, this function is of no use for Evas users, most probably.

Since :: 3.0

int evas_smart_usage_get ( const Evas_Smart * s )

Get the number of users of the smart instance

Parameters:

s	The Evas_Smart to get the usage count of

Returns:: The number of uses of the smart instance

This function tells you how many more uses of the smart instance are in existence. This should be used before freeing/clearing any of the Evas_Smart_Class that was used to create the smart instance. The smart instance will refer to data in the Evas_Smart_Class used to create it and thus you cannot remove the original data until all users of it are gone. When the usage count goes to 0, you can evas_smart_free() the smart instance s and remove from memory any of the Evas_Smart_Class that was used to create the smart instance, if you desire. Removing it from memory without doing this will cause problems (crashes, undefined behavior etc. etc.), so either never remove the original Evas_Smart_Class data from memory (have it be a constant structure and data), or use this API call and be very careful.

Since :: 3.0

Functions

Typedefs

Defines

Define Documentation

Typedef Documentation

Function Documentation