Smart Functions
Evas

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. More...

## Data Structures

struct | _Evas_Smart_Class
| A smart object's base class definition. More...
struct | _Evas_Smart_Interface
| A smart object's base interface definition. More...
struct | _Evas_Smart_Cb_Description
| Describes a callback issued by a smart object (evas_object_smart_callback_call()), as defined in its smart object class. More...

## Macros

#define | EVAS_SMART_CLASS_VERSION 4
| The version you have to put into the version field in the Evas_Smart_Class struct.
#define | EVAS_SMART_CLASS_INIT_NULL {NULL, 0, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
| Initialize to zero a whole Evas_Smart_Class structure.
#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}
| Initialize to zero a whole Evas_Smart_Class structure and set version.
#define | EVAS_SMART_CLASS_INIT_NAME_VERSION(name)
| Initialize to zero a whole Evas_Smart_Class structure and set name and version.
#define | EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT(name, parent)
| Initialize to zero a whole Evas_Smart_Class structure and set name, version and parent class.
#define | EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS(name, parent, callbacks)
| Initialize to zero a whole Evas_Smart_Class structure and set name, version, parent class and callbacks definition.
#define | EVAS_SMART_SUBCLASS_NEW(smart_name, prefix, api_type, parent_type, parent_func, cb_desc)
| Convenience macro to subclass a given Evas smart class.
#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)
| Convenience macro to allocate smart data only if needed.
#define | evas_smart_class_inherit(sc, parent_sc)
| Easy to use version of evas_smart_class_inherit_full().

## Typedefs

typedef struct _Evas_Smart_Class | Evas_Smart_Class
| A smart object's base class definition.
typedef struct _Evas_Smart_Interface | Evas_Smart_Interface
| A smart object's base interface definition.
typedef struct _Evas_Smart_Cb_Description | Evas_Smart_Cb_Description
| A smart object callback description, used to provide introspection.

## Functions

EVAS_API void | evas_smart_free (Evas_Smart *s)
| Free an Evas_Smart struct.
EVAS_API Evas_Smart * | evas_smart_class_new (const Evas_Smart_Class *sc)
| Creates a new Evas_Smart from a given Evas_Smart_Class struct.
EVAS_API const Evas_Smart_Class * | evas_smart_class_get (const Evas_Smart *s)
| Get the Evas_Smart_Class handle of an Evas_Smart struct.
EVAS_API void * | evas_smart_data_get (const Evas_Smart *s)
| Get the data pointer set on an Evas_Smart struct.
EVAS_API 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.
EVAS_API 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.
EVAS_API 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.
EVAS_API int | evas_smart_usage_get (const Evas_Smart *s)
| Get the number of uses of the smart instance.

## Detailed Description

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 Evas_Object_Box, Table Smart Object. and Clipped Smart Object).

See also some examples of this group of functions.

## Macro Definition Documentation

## EVAS_SMART_CLASS_VERSION

#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.

Referenced by evas_smart_class_inherit_full(), and evas_smart_class_new().

## EVAS_SMART_CLASS_INIT_NULL

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

Initialize 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

## EVAS_SMART_CLASS_INIT_VERSION

#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}

Initialize 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

## EVAS_SMART_CLASS_INIT_NAME_VERSION

#define EVAS_SMART_CLASS_INIT_NAME_VERSION | ( |  | name | ) |

Value:
{name, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL}
EVAS_SMART_CLASS_VERSION
#define EVAS_SMART_CLASS_VERSION
The version you have to put into the version field in the Evas_Smart_Class struct.
Definition Evas_Common.h:1938

Initialize 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

Referenced by evas_object_smart_clipped_class_get().

## EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT

#define EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT | ( |  | name,
|  |  | parent )

Value:
{name, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, parent, NULL, NULL}

Initialize 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

## EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS

#define EVAS_SMART_CLASS_INIT_NAME_VERSION_PARENT_CALLBACKS | ( |  | name,
|  |  | parent,
|  |  | callbacks )

Value:
{name, EVAS_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, parent, callbacks, NULL}

Initialize 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

## EVAS_SMART_SUBCLASS_NEW

#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; \
}
Evas_Smart
struct _Evas_Smart Evas_Smart
An Evas Smart Object handle.
Definition Evas_Common.h:197
Evas_Smart_Class
struct _Evas_Smart_Class Evas_Smart_Class
A smart object's base class definition.
Definition Evas_Common.h:126
evas_smart_class_new
EVAS_API Evas_Smart * evas_smart_class_new(const Evas_Smart_Class *sc)
Creates a new Evas_Smart from a given Evas_Smart_Class struct.
Definition evas_smart.c:26
_Evas_Smart_Class::name
const char * name
the name string of the class
Definition Evas_Common.h:1949
_Evas_Smart_Class::callbacks
const Evas_Smart_Cb_Description * callbacks
callbacks at this level, NULL terminated
Definition Evas_Common.h:1965

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 for this 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.

## EVAS_SMART_SUBCLASS_IFACE_NEW

#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; \
}
_Evas_Smart_Class::interfaces
const Evas_Smart_Interface ** interfaces
Evas_Smart_Interface pointers array, NULL terminated.
Definition Evas_Common.h:1966

Since
  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 for this 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.

## EVAS_SMART_DATA_ALLOC

#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); \
}
evas_object_smart_data_get
EVAS_API void * evas_object_smart_data_get(const Evas_Object *eo_obj)
Retrieves the pointer to user data for a given smart object.
Definition evas_object_smart.c:149

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.

## evas_smart_class_inherit

#define evas_smart_class_inherit | ( |  | sc,
|  |  | parent_sc )

Value:
evas_smart_class_inherit_full(sc, (Evas_Smart_Class *)parent_sc, sizeof(*parent_sc))
evas_smart_class_inherit_full
EVAS_API 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.
Definition evas_smart.c:88

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.

## Typedef Documentation

## Evas_Smart_Interface

typedef struct _Evas_Smart_Interface Evas_Smart_Interface

A smart object's base interface definition.

An Evas interface is exactly like the OO-concept: a '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
  1.7

Examples
  evas-smart-interface.c.

## Function Documentation

## evas_smart_free()

EVAS_API 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.

## evas_smart_class_new()

EVAS_API 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.

References EVAS_SMART_CLASS_VERSION.

## evas_smart_class_get()

EVAS_API 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

## evas_smart_data_get()

EVAS_API 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().

## evas_smart_callbacks_descriptions_get()

EVAS_API 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()

## evas_smart_callback_description_find()

EVAS_API 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()

## evas_smart_class_inherit_full()

EVAS_API 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().

References EINA_FALSE, EINA_TRUE, EVAS_SMART_CLASS_VERSION, and _Evas_Smart_Class::parent.

## evas_smart_usage_get()

EVAS_API int evas_smart_usage_get | ( | const Evas_Smart * | s | ) |

Get the number of uses 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.), 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.