Evas_Smart_Group

Langue: en

Autres versions - même langue

Version: 380871 (fedora - 01/12/10)

Section: 3 (Bibliothèques de fonctions)

Sommaire

NAME

Smart Functions -

Functions that deal with Evas_Smart's, 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.

Data Structures


struct _Evas_Smart_Class
a smart object class
struct _Evas_Smart_Cb_Description
Describes a callback used by a smart class evas_object_smart_callback_call(), particularly useful to explain to user and its code (ie: introspection) what the parameter event_info will contain.

Defines


#define EVAS_SMART_CLASS_VERSION 4
The version you have to put into the version field in the 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}
Initializer 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}
Initializer 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}
Initializer 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}
Initializer 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}
Initializer 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 Smart Class.
#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, 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 base class.
typedef struct _Evas_Smart_Cb_Description Evas_Smart_Cb_Description
A smart object callback description, used to provide introspection.

Functions


EAPI Evas_Smart * evas_smart_new (const char *name, void(*func_add)(Evas_Object *o), void(*func_del)(Evas_Object *o), void(*func_layer_set)(Evas_Object *o, int l) __UNUSED__, void(*func_raise)(Evas_Object *o) __UNUSED__, void(*func_lower)(Evas_Object *o) __UNUSED__, void(*func_stack_above)(Evas_Object *o, Evas_Object *above) __UNUSED__, void(*func_stack_below)(Evas_Object *o, Evas_Object *below) __UNUSED__, void(*func_move)(Evas_Object *o, Evas_Coord x, Evas_Coord y), void(*func_resize)(Evas_Object *o, Evas_Coord w, Evas_Coord h), void(*func_show)(Evas_Object *o), void(*func_hide)(Evas_Object *o), void(*func_color_set)(Evas_Object *o, int r, int g, int b, int a), void(*func_clip_set)(Evas_Object *o, Evas_Object *clip), void(*func_clip_unset)(Evas_Object *o), const void *data)
Create an Evas_Smart, which can be used to instantiate new smart objects.
EAPI void evas_smart_free (Evas_Smart *s)
Free an Evas_Smart.
EAPI Evas_Smart * evas_smart_class_new (const Evas_Smart_Class *sc)
Creates an Evas_Smart from an Evas_Smart_Class.
EAPI const Evas_Smart_Class * evas_smart_class_get (const Evas_Smart *s)
Get the Evas_Smart_Class of an Evas_Smart.
EAPI void * evas_smart_data_get (const Evas_Smart *s)
Get the data pointer set on an Evas_Smart.
EAPI const Evas_Smart_Cb_Description ** evas_smart_callbacks_descriptions_get (const Evas_Smart *s, unsigned int *count)
Get the callbacks known by this Evas_Smart.
EAPI const Evas_Smart_Cb_Description * evas_smart_callback_description_find (const Evas_Smart *s, const char *name)
Find callback description for callback called name.
EAPI 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.

Detailed Description

Functions that deal with Evas_Smart's, 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 couple of existent smart objects in Evas itself, see Box (Sequence) Smart Object., Table Smart Object. and Clipped Smart Object.

Define Documentation

#define evas_smart_class_inherit(sc, parent_sc) evas_smart_class_inherit_full(sc, 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

Referenced by evas_object_smart_clipped_class_get().

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

Parameters:

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

#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, (const Evas_Smart_Class *)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 Smart Class. This macro saves some typing when writing a Smart Class derived from another one. In order to work, the user needs to provide some functions adhering to the following guidelines.

*
<prefix>_smart_set_user(): the internal _smart_set function 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.
*
<prefix>_parent_sc: pointer to the smart class of the parent. 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, should be called by the public _add() function.
*
If this new class should be subclassable as well, a public _smart_set() function is desirable to fill 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.

Parameters:

smart_name The name used for the Smart Class. e.g: 'Evas_Object_Box'.
prefix Prefix used for all variables and functions defined.
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.

Function Documentation

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

Find callback description for callback called name. Parameters:

s the Evas_Smart.
name name of desired callback, must not be NULL. The search have 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:

reference to description if found, NULL if not found.

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

Get the callbacks known by this Evas_Smart. This is likely different from Evas_Smart_Class::callbacks as it will contain the callbacks of all 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 reference to original values given to evas_smart_new() as Evas_Smart_Class::callbacks.

The array is sorted by name. The last array element is the NULL pointer and is not counted in count. Loop iterations can check any of these cases.

Parameters:

s the Evas_Smart.
count returns the number of elements in returned array.

Returns:

the array with callback descriptions known by this class, its size is returned in count parameter. It should not be modified anyhow. If no callbacks are known, NULL is returned. The array is sorted by name and elements refer to the original value given to evas_smart_new().

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

EAPI const Evas_Smart_Class* evas_smart_class_get (const Evas_Smart * s)

Get the Evas_Smart_Class of an Evas_Smart. Parameters:

s the Evas_Smart

Returns:

the Evas_Smart_Class

EAPI 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 EVAS_SMART_CLASS_VERSION, and _Evas_Smart_Class::parent.

EAPI Evas_Smart* evas_smart_class_new (const Evas_Smart_Class * sc)

Creates an Evas_Smart from an Evas_Smart_Class. Parameters:

sc the smart class definition

Returns:

an Evas_Smart

References EVAS_SMART_CLASS_VERSION.

EAPI void* evas_smart_data_get (const Evas_Smart * s)

Get the data pointer set on an Evas_Smart. Parameters:

s Evas_Smart

This data pointer is set either as the final parameter to evas_smart_new or as the data field in the Evas_Smart_Class passed in to evas_smart_class_new

EAPI void evas_smart_free (Evas_Smart * s)

Free an Evas_Smart. If this smart was created using evas_smart_class_new(), the associated Evas_Smart_Class will not be freed.

Parameters:

s the Evas_Smart to free

EAPI Evas_Smart* evas_smart_new (const char * name, void(*)(Evas_Object *o) func_add, void(*)(Evas_Object *o) func_del, void(*)(Evas_Object *o, int l) __UNUSED__ func_layer_set, void(*)(Evas_Object *o) __UNUSED__ func_raise, void(*)(Evas_Object *o) __UNUSED__ func_lower, void(*)(Evas_Object *o, Evas_Object *above) __UNUSED__ func_stack_above, void(*)(Evas_Object *o, Evas_Object *below) __UNUSED__ func_stack_below, void(*)(Evas_Object *o, Evas_Coord x, Evas_Coord y) func_move, void(*)(Evas_Object *o, Evas_Coord w, Evas_Coord h) func_resize, void(*)(Evas_Object *o) func_show, void(*)(Evas_Object *o) func_hide, void(*)(Evas_Object *o, int r, int g, int b, int a) func_color_set, void(*)(Evas_Object *o, Evas_Object *clip) func_clip_set, void(*)(Evas_Object *o) func_clip_unset, const void * data)

Create an Evas_Smart, which can be used to instantiate new smart objects. This function internally creates an Evas_Smart_Class and sets the provided callbacks. Callbacks that are unneeded (or marked DEPRECATED below) should be set to NULL.

Alternatively you can create an Evas_Smart_Class yourself and use evas_smart_class_new().

Parameters:

name a unique name for the smart
func_add callback called when smart object is added
func_del callback called when smart object is deleted
func_layer_set DEPRECATED
func_raise DEPRECATED
func_lower DEPRECATED
func_stack_above DEPRECATED
func_stack_below DEPRECATED
func_move callback called when smart object is moved
func_resize callback called when smart object is resized
func_show callback called when smart object is shown
func_hide callback called when smart object is hidden
func_color_set callback called when smart object has its color set
func_clip_set callback called when smart object has its clip set
func_clip_unset callback called when smart object has its clip unset
data a pointer to user data for the smart

Returns:

an Evas_Smart

References _Evas_Smart_Class::name.

Author

Generated automatically by Doxygen for Evas from the source code.