Evas_Smart_Group(3)

NAME
Evas_Smart_Group - Smart Functions

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

SYNOPSIS

  Data Structures
struct _Evas_Smart_Class
A smart object's base class definition.
struct _Evas_Smart_Interface
A smart object's base interface definition.
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.

  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) {name, 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 name and version.
#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}
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) {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.
#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) evas_smart_class_inherit_full(sc, (Evas_Smart_Class *)parent_sc, sizeof(*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

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

  #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

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

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

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

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

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

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

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

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

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

Typedef Documentation

  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

Function Documentation

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

Author

Generated automatically by Doxygen for EFL from the source code.