From: glima Date: Fri, 8 Jul 2011 16:54:00 +0000 (+0000) Subject: [evas] Documenting/exemplifying the following: X-Git-Tag: 2.0_alpha~240^2~347 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=a5bb83f5691e719321d1528bf2c88513da1a6629;p=framework%2Fuifw%2Fevas.git [evas] Documenting/exemplifying the following: - evas_object_smart_callback_add - evas_object_smart_callback_call - evas_object_smart_callback_del - evas_object_smart_callback_description_find - evas_object_smart_callbacks_descriptions_get - evas_object_smart_callbacks_descriptions_set git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/evas@61158 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- diff --git a/doc/examples.dox b/doc/examples.dox index e6d5367..5eeadda 100644 --- a/doc/examples.dox +++ b/doc/examples.dox @@ -545,7 +545,7 @@ * handy helper macro: * @dontinclude evas-smart-object.c * @skip EVAS_SMART_SUBCLASS_NEW - * @until _signals + * @until _smart_callbacks * What it does is to @b subclass a given existing smart class, thus * specializing it. This is very common and useful in Evas. There is a * built-in smart object, the "clipped smart object", whose behavior is @@ -621,22 +621,51 @@ * "static clippers" -- clipped smart objects have their global * clippers flagged static. * + * Other important things we also exemplify here are smart + * callbacks and smart callback @b introspection: + * @dontinclude evas-smart-object.c + * @skip EVT_CHILDREN_NUMBER_CHANGED + * @until ; + * + * Here we declare our array of smart callback descriptions, which has + * one element only, in this case. That callback will take place, as + * the name indicates, whenever the number of member objects in our + * smart object example instance changes. That global array variable + * must be the last argument to #EVAS_SMART_SUBCLASS_NEW, so that it's + * registered as the smart class's callbacks description. + * + * After we instantiate the smart object, we take a look on those + * descriptions and register a callback on that unique smart event: + * @dontinclude evas-smart-object.c + * @skip for (; + * @until focus_set + * + * The code of the callback will just print how many member objects we + * have, which is an integer argument of the callback itself, as + * flagged by its description: + * @dontinclude evas-smart-object.c + * @skip callback on number of member objects changed + * @until } + * + * One of the points at which we issue that callback is inside the @c + * evas_smart_example_remove(), whose code was already shown. + * * As in other examples, to interact with this one there's a command * line interface, whose help string can be asked for with the 'h' key: - * * @dontinclude evas-smart-object.c * @skip static const char *commands = * @until ; - * Use 'l' and 'r' keys, to create new rectangles and place them on the - * left (@c evas_smart_example_set_left()) or right - * (@c evas_smart_example_set_right()) spots of our smart object, - * respectively. The keyboard arrows will move the smart object along - * the canvas. See how it takes any child objects with it during its - * movement. The 'd' and 'i' keys will increase or decrease the smart - * object's size -- see how it affects the children's sizes, - * too. Finally, 'c' will change the color of the smart object's - * clipper (which is the exact internal clipper coming from a clipped - * smart object): + * Use 'l' and 'r' keys, to create new rectangles and place them on + * the left (@c evas_smart_example_set_left()) or right (@c + * evas_smart_example_set_right()) spots of our smart object, + * respectively. The 'w' command will remove all member objects from + * the smart object and delete them. The keyboard arrows will move the + * smart object along the canvas. See how it takes any child objects + * with it during its movement. The 'd' and 'i' keys will increase or + * decrease the smart object's size -- see how it affects the + * children's sizes, too. Finally, 'c' will change the color of the + * smart object's clipper (which is the exact internal clipper coming + * from a clipped smart object): * @dontinclude evas-smart-object.c * @skip d.clipper = * @until .a); diff --git a/src/examples/evas-smart-object.c b/src/examples/evas-smart-object.c index 792071e..8a36b62 100644 --- a/src/examples/evas-smart-object.c +++ b/src/examples/evas-smart-object.c @@ -31,6 +31,7 @@ static const char *commands = \ "commands are:\n" "\tl - insert child rectangle on the left\n" "\tr - insert child rectangle on the right\n" + "\tw - remove and delete all members from the smart object\n" "\tright arrow - move smart object to the right\n" "\tleft arrow - move smart object to the left\n" "\tup arrow - move smart object up\n" @@ -49,7 +50,7 @@ struct test_data { Ecore_Evas *ee; Evas *evas; - Evas_Object *smt, *bg, *clipper; + Evas_Object *smt, *bg, *clipper, *rects[2]; }; struct color_tuple @@ -83,14 +84,12 @@ _index_to_color(int i) static struct test_data d = {0}; static const char *border_img_path = PACKAGE_EXAMPLES_DIR "/red.png"; -#define _evas_smart_example_type "Evas_Smart_Example" -#define SIG_CHILD_ADDED "child,added" -#define SIG_CHILD_REMOVED "child,removed" +#define _evas_smart_example_type "Evas_Smart_Example" +#define EVT_CHILDREN_NUMBER_CHANGED "children,changed" -static const Evas_Smart_Cb_Description _signals[] = +static const Evas_Smart_Cb_Description _smart_callbacks[] = { - {SIG_CHILD_ADDED, ""}, - {SIG_CHILD_REMOVED, ""}, + {EVT_CHILDREN_NUMBER_CHANGED, "i"}, {NULL, NULL} }; @@ -104,6 +103,7 @@ struct _Evas_Smart_Example_Data { Evas_Object_Smart_Clipped_Data base; Evas_Object *children[2], *border; + int child_count; }; #define EVAS_SMART_EXAMPLE_DATA_GET(o, ptr) \ @@ -133,7 +133,7 @@ struct _Evas_Smart_Example_Data EVAS_SMART_SUBCLASS_NEW(_evas_smart_example_type, _evas_smart_example, Evas_Smart_Class, Evas_Smart_Class, - evas_object_smart_clipped_class_get, _signals); + evas_object_smart_clipped_class_get, _smart_callbacks); static void _on_destroy(Ecore_Evas *ee __UNUSED__) @@ -311,6 +311,17 @@ evas_smart_example_add(Evas *evas) return evas_object_smart_add(evas, _evas_smart_example_smart_class_new()); } +static void +_evas_smart_example_remove_do(Evas_Smart_Example_Data *priv, + Evas_Object *child, + int index) +{ + priv->children[index] = NULL; + priv->child_count--; + _evas_smart_example_child_callbacks_unregister(child); + evas_object_smart_member_del(child); +} + /* remove a child element, return its pointer (or NULL on errors) */ Evas_Object * evas_smart_example_remove(Evas_Object *o, @@ -330,11 +341,10 @@ evas_smart_example_remove(Evas_Object *o, index = (int)evas_object_data_get(child, "index"); index--; - priv->children[index] = NULL; + _evas_smart_example_remove_do(priv, child, index); - evas_object_smart_callback_call(o, SIG_CHILD_REMOVED, child); - _evas_smart_example_child_callbacks_unregister(child); - evas_object_smart_member_del(child); + evas_object_smart_callback_call( + o, EVT_CHILDREN_NUMBER_CHANGED, (void *)priv->child_count); evas_object_smart_changed(o); return child; @@ -362,17 +372,25 @@ evas_smart_example_set_left(Evas_Object *o, if (priv->children[0]) { if (priv->children[0] != child) - ret = evas_smart_example_remove(o, priv->children[0]); + { + ret = priv->children[0]; + _evas_smart_example_remove_do(priv, priv->children[0], 0); + } else return child; } priv->children[0] = child; - evas_object_smart_callback_call(o, SIG_CHILD_ADDED, child); - _evas_smart_example_child_callbacks_register(o, child, 0); evas_object_smart_member_add(child, o); evas_object_smart_changed(o); + priv->child_count++; + if (!ret) + { + evas_object_smart_callback_call( + o, EVT_CHILDREN_NUMBER_CHANGED, (void *)priv->child_count); + } + return ret; } @@ -398,17 +416,25 @@ evas_smart_example_set_right(Evas_Object *o, if (priv->children[1]) { if (priv->children[1] != child) - ret = evas_smart_example_remove(o, priv->children[1]); + { + ret = priv->children[1]; + _evas_smart_example_remove_do(priv, priv->children[1], 1); + } else return child; } priv->children[1] = child; - evas_object_smart_callback_call(o, SIG_CHILD_ADDED, child); - _evas_smart_example_child_callbacks_register(o, child, 1); evas_object_smart_member_add(child, o); evas_object_smart_changed(o); + priv->child_count++; + if (!ret) + { + evas_object_smart_callback_call( + o, EVT_CHILDREN_NUMBER_CHANGED, (void *)priv->child_count); + } + return ret; } @@ -428,6 +454,26 @@ _on_keydown(void *data __UNUSED__, return; } + if (strcmp(ev->keyname, "w") == 0) /* clear out smart object (WRT members) */ + { + if (d.rects[0]) + { + evas_smart_example_remove(d.smt, d.rects[0]); + evas_object_del(d.rects[0]); + } + if (d.rects[1]) + { + evas_smart_example_remove(d.smt, d.rects[1]); + evas_object_del(d.rects[1]); + } + + memset(d.rects, 0, sizeof(d.rects)); + + fprintf(stdout, "Deleting all members of the smart object.\n"); + + return; + } + if (strcmp(ev->keyname, "l") == 0) /* insert random colored * rectangle on the left */ { @@ -437,6 +483,8 @@ _on_keydown(void *data __UNUSED__, evas_object_show(rect); prev = evas_smart_example_set_left(d.smt, rect); + d.rects[0] = rect; + fprintf(stdout, "Setting smart object's left spot with a new" " rectangle.\n"); fprintf(stdout, "Checking its new smart object parent: %s\n", @@ -464,6 +512,8 @@ _on_keydown(void *data __UNUSED__, evas_object_show(rect); prev = evas_smart_example_set_right(d.smt, rect); + d.rects[1] = rect; + fprintf(stdout, "Setting smart object's right spot with a new" " rectangle.\n"); fprintf(stdout, "Checking its new smart object parent: %s\n", @@ -560,9 +610,20 @@ _on_keydown(void *data __UNUSED__, } } +static void /* callback on number of member objects changed */ +_on_example_smart_object_child_num_change(void *data __UNUSED__, + Evas_Object *obj __UNUSED__, + void *event_info) +{ + fprintf(stdout, "Number of child members on our example smart" + " object changed to %d\n", (int)event_info); +} + int main(void) { + const Evas_Smart_Cb_Description **descriptions; + unsigned int count; Eina_Bool ret; srand(time(NULL)); @@ -600,13 +661,34 @@ main(void) d.clipper = evas_object_smart_clipped_clipper_get(d.smt); fprintf(stdout, "Checking if clipped smart object's clipper is a " - "\"static\" one: %s\n", evas_object_static_clip_get(d.clipper) ? - "yes" : "no"); + "\"static\" one: %s\n", evas_object_static_clip_get( + d.clipper) ? "yes" : "no"); evas_object_color_set( d.clipper, clipper_colors[cur_color].r, clipper_colors[cur_color].g, clipper_colors[cur_color].b, clipper_colors[cur_color].a); + evas_object_smart_callbacks_descriptions_get( + d.smt, &descriptions, &count, NULL, NULL); + + for (; *descriptions; descriptions++) + { + fprintf(stdout, "We've found a smart callback on the smart object!" + "\n\tname: %s\n\ttype: %s\n", (*descriptions)->name, + (*descriptions)->type); + + if (strcmp((*descriptions)->type, "i")) continue; + /* we know we don't have other types of smart callbacks + * here, just playing with it */ + + /* for now, we know the only one callback is the one + * reporting number of member objects changed on the + * example smart object */ + evas_object_smart_callback_add( + d.smt, (*descriptions)->name, + _on_example_smart_object_child_num_change, NULL); + } + evas_object_focus_set(d.bg, EINA_TRUE); evas_object_event_callback_add( d.bg, EVAS_CALLBACK_KEY_DOWN, _on_keydown, NULL); diff --git a/src/lib/Evas.h b/src/lib/Evas.h index 9fd8fa1..6cab8af 100644 --- a/src/lib/Evas.h +++ b/src/lib/Evas.h @@ -493,26 +493,34 @@ typedef struct _Evas_Smart_Class Evas_Smart_Class; /** * @typedef Evas_Smart_Cb_Description + * * A smart object callback description, used to provide introspection + * * @ingroup Evas_Smart_Group */ typedef struct _Evas_Smart_Cb_Description Evas_Smart_Cb_Description; /** * @typedef Evas_Map + * * An opaque handle to map points + * * @see evas_map_new() * @see evas_map_free() * @see evas_map_dup() + * * @ingroup Evas_Object_Group_Map */ typedef struct _Evas_Map Evas_Map; /** * @typedef Evas + * * An opaque handle to an Evas canvas. + * * @see evas_new() * @see evas_free() + * * @ingroup Evas_Canvas */ typedef struct _Evas Evas; @@ -945,7 +953,7 @@ typedef enum _Evas_Object_Pointer_Mode EVAS_OBJECT_POINTER_MODE_NOGRAB /**< pointer always bound to the object right below it */ } Evas_Object_Pointer_Mode; /**< How the mouse pointer should be handled by Evas. */ -typedef void (*Evas_Smart_Cb) (void *data, Evas_Object *obj, void *event_info); +typedef void (*Evas_Smart_Cb) (void *data, Evas_Object *obj, void *event_info); /**< Evas smart objects' "smart callback" function signature */ typedef void (*Evas_Event_Cb) (void *data, Evas *e, void *event_info); /**< Evas event callback function signature */ typedef Eina_Bool (*Evas_Object_Event_Post_Cb) (void *data, Evas *e); typedef void (*Evas_Object_Event_Cb) (void *data, Evas *e, Evas_Object *obj, void *event_info); /**< Evas object event callback function signature */ @@ -8013,24 +8021,24 @@ struct _Evas_Smart_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 @c - * event_info will contain. + * Describes a callback issued by a smart object + * (evas_object_smart_callback_call()), as defined in its smart object + * class. This is particularly useful to explain to end users and + * their code (i.e., introspection) what the parameter @c event_info + * will point to. * * @ingroup Evas_Smart_Group */ struct _Evas_Smart_Cb_Description { - const char *name; /**< callback name, ie: "changed" */ + const char *name; /**< callback name ("changed", for example) */ /** - * @brief Hint type of @c event_info parameter of Evas_Smart_Cb. + * @brief Hint on the type of @c event_info parameter's contents on + * a #Evas_Smart_Cb callback. * * The type string uses the pattern similar to - * - * http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures - * + * http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-signatures, * but extended to optionally include variable names within * brackets preceding types. Example: * @@ -8047,9 +8055,9 @@ struct _Evas_Smart_Cb_Description * @c "[x]a(ii)" * * @note This type string is used as a hint and is @b not validated - * or enforced anyhow. Implementors should make the best use - * of it to help bindings, documentation and other users of - * introspection features. + * or enforced in any way. Implementors should make the best + * use of it to help bindings, documentation and other users + * of introspection features. */ const char *type; }; @@ -8303,30 +8311,35 @@ EAPI const Evas_Smart_Class *evas_smart_class_get (const EAPI void *evas_smart_data_get (const Evas_Smart *s) EINA_WARN_UNUSED_RESULT EINA_ARG_NONNULL(1) EINA_PURE; /** - * Get the callbacks known by this Evas_Smart. + * Get the smart callbacks known by this #Evas_Smart handle's smart + * class hierarchy. + * + * @param s A valid #Evas_Smart handle. + * @param[out] count Returns the number of elements in the returned + * array. + * @return The array with callback descriptions known by this smart + * class, with its size returned in @a count parameter. It + * should not be modified in any way. If no callbacks are + * known, @c 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_Smart_Class::callbacks as it - * will contain the callbacks of all class hierarchy sorted, while the + * This is likely different from + * evas_object_smart_callbacks_descriptions_get() as it will contain + * the callbacks of @b 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 @c NULL. * - * The array elements and thus their contents will be reference to - * original values given to evas_smart_new() as + * The array elements and thus their contents will be @b references to + * original values given to evas_smart_class_new() as * Evas_Smart_Class::callbacks. * - * The array is sorted by name. The last array element is the @c NULL - * pointer and is not counted in @a count. Loop iterations can check - * any of these cases. - * - * @param s the Evas_Smart. - * @param count returns the number of elements in returned array. - * @return the array with callback descriptions known by this class, - * its size is returned in @a count parameter. It should not - * be modified anyhow. If no callbacks are known, @c NULL is - * returned. The array is sorted by name and elements refer to - * the original value given to evas_smart_new(). + * The array is sorted by Evas_Smart_Cb_Description::name. The last + * array element is a @c NULL pointer and is not accounted for in @a + * 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 @@ -8337,14 +8350,17 @@ EAPI const Evas_Smart_Cb_Description **evas_smart_callbacks_descriptions_get(con /** - * Find callback description for callback called @a name. + * Find a callback description for the callback named @a name. * - * @param s the Evas_Smart. - * @param name name of desired callback, must @b not be @c NULL. The - * search have a special case for @a name being the same - * pointer as registered with Evas_Smart_Cb_Description, one - * can use it to avoid excessive use of strcmp(). - * @return reference to description if found, @c NULL if not found. + * @param s The #Evas_Smart where to search for class registered smart + * event callbacks. + * @param name Name of the desired callback, which must @b not be @c + * NULL. The search has a special case for @a name being the + * same pointer as registered with #Evas_Smart_Cb_Description. + * One can use it to avoid excessive use of strcmp(). + * @return A reference to the description if found, or @c NULL, otherwise + * + * @see evas_smart_callbacks_descriptions_get() */ EAPI const Evas_Smart_Cb_Description *evas_smart_callback_description_find(const Evas_Smart *s, const char *name) EINA_ARG_NONNULL(1, 2) EINA_PURE; @@ -8418,6 +8434,25 @@ EAPI int evas_smart_usage_get(const Evas_Smart *s); * 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 interect with its own custom features. The + * API takes form of explicit exported functions one may call and + * smart callbacks. + * + * @section Evas_Smart_Object_Group_Callbacks Smart events and callbacks + * + * Smart objects can elect events (smart events, from now on) ocurring + * 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's also a function prototype + * definition for the callback functions: #Evas_Smart_Cb. + * + * When defining an #Evas_Smart_Class, smart object implementors are + * strongly encorauged 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. + * * See some @ref Example_Evas_Smart_Objects "examples" of this group * of functions. * @@ -8592,39 +8627,86 @@ EAPI void *evas_object_smart_data_get (const Evas_Object *obj EAPI void evas_object_smart_data_set (Evas_Object *obj, void *data) EINA_ARG_NONNULL(1); /** - * Add a callback for the smart event specified by @p event. + * Add (register) a callback function to the smart event specified by + * @p event on the smart object @p obj. * * @param obj a smart object - * @param event the event name + * @param event the event's name string * @param func the callback function * @param data user data to be passed to the callback function + * + * 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 @p event occurs in it. The function is @p func. + * + * In the event of a memory allocation error during addition of the + * callback to the object, evas_alloc_error() should be used to + * determine the nature of the error, if any, and the program should + * sensibly try and recover. + * + * A smart callback function must have the ::Evas_Smart_Cb prototype + * definition. The first parameter (@p data) in this definition will + * have the same value passed to evas_object_smart_callback_add() as + * the @p data parameter, at runtime. The second parameter @p obj is a + * handle to the object on which the event occurred. The third + * parameter, @p 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 (see evas_smart_callbacks_descriptions_get()), but no + * internal smart objects on Evas implement them yet. + * + * @see @ref Evas_Smart_Object_Group_Callbacks for more details. + * + * @see evas_object_smart_callback_del() * @ingroup Evas_Smart_Object_Group */ EAPI void evas_object_smart_callback_add (Evas_Object *obj, const char *event, Evas_Smart_Cb func, const void *data) EINA_ARG_NONNULL(1, 2, 3); /** - * Remove a smart callback - * - * Removes a callback that was added by evas_object_smart_callback_add() + * Delete (unregister) a callback function from the smart event + * specified by @p event on the smart object @p obj. * * @param obj a smart object - * @param event the event name + * @param event the event's name string * @param func the callback function * @return the data pointer + * + * This function removes the first added smart callback on the + * object @p obj matching the event name @p event and the registered + * function pointer @p func. If the removal is successful it will also + * return the data pointer that was passed to + * evas_object_smart_callback_add() (that will be the same as the + * parameter) when the callback(s) was(were) added to the canvas. If + * not successful @c NULL will be returned. + * + * @see evas_object_smart_callback_add() for more details. + * * @ingroup Evas_Smart_Object_Group */ EAPI void *evas_object_smart_callback_del (Evas_Object *obj, const char *event, Evas_Smart_Cb func) EINA_ARG_NONNULL(1, 2, 3); /** - * Call any smart callbacks on @p obj for @p event. + * Call a given smart callback on the smart object @p obj. * * @param obj the smart object - * @param event the event name - * @param event_info an event specific struct of info to pass to the callback - * - * This should be called internally in the smart object when some specific - * event has occurred. The documentation for the smart object should include - * a list of possible events and what type of @p event_info to expect. + * @param event the event's name string + * @param event_info pointer to an event specific struct or information to + * pass to the callback functions registered on this smart event + * + * This should be called @b internally, from the smart object's own + * code, when some specific event has occurred and the implementor + * wants is to pertain to the object's events API (see @ref + * Evas_Smart_Object_Group_Callbacks). The documentation for the smart + * object should include a list of possible events and what type of @p + * event_info to expect for each of them. Also, when defining an + * #Evas_Smart_Class, smart object implementors are strongly + * encorauged 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. * * @ingroup Evas_Smart_Object_Group */ @@ -8632,58 +8714,70 @@ EAPI void evas_object_smart_callback_call (Evas_Object *obj, cons /** - * Set smart object instance callbacks descriptions. + * Set an smart object @b instance's smart callbacks descriptions. + * + * @param obj A smart object + * @param descriptions @c NULL terminated array with + * #Evas_Smart_Cb_Description descriptions. Array elements won't be + * modified at run time, but references to them and their contents + * will be made, so this array should be kept alive during the whole + * object's lifetime. + * @return @c EINA_TRUE on success, @c EINA_FALSE on failure. * * These descriptions are hints to be used by introspection and are * not enforced in any way. * * It will not be checked if instance callbacks descriptions have the - * same name as another in class. Both are kept in different arrays - * and users of evas_object_smart_callbacks_descriptions_get() should - * handle this case as they wish. - * - * @param obj The smart object - * @param descriptions NULL terminated (name != NULL) array with - * descriptions. Array elements will not be modified, but - * reference to them and their contents will be made, so this - * array should be kept alive during object lifetime. - * @return 1 on success, 0 on failure. - * @ingroup Evas_Smart_Object_Group + * same name as respective possibly registered in the smart object + * @b class. Both are kept in different arrays and users of + * evas_object_smart_callbacks_descriptions_get() should handle this + * case as they wish. + * + * @note Becase @p descriptions must be @c NULL terminated, and + * because a @c NULL name makes little sense, too, + * Evas_Smart_Cb_Description::name must @b not be @c NULL. + * + * @note While instance callbacks descriptions are possible, they are + * @b not recommended. Use @b class callbacks descriptions + * instead as they make you smart object user's life simpler and + * will use less memory, as descriptions and arrays will be + * shared among all instances. * - * @note while instance callbacks descriptions are possible, they are - * not recommended. Use class callbacks descriptions instead as they - * make user's life simpler and will use less memory as descriptions - * and arrays will be shared among all instances. + * @ingroup Evas_Smart_Object_Group */ EAPI Eina_Bool evas_object_smart_callbacks_descriptions_set(Evas_Object *obj, const Evas_Smart_Cb_Description *descriptions) EINA_ARG_NONNULL(1); /** - * Get the callbacks descriptions known by this smart object. - * - * This call retrieves processed callbacks descriptions for both - * instance and class. These arrays are sorted by description's name - * and are @c NULL terminated, so both @a class_count and - * @a instance_count can be ignored, the terminator @c NULL is not - * counted in these values. + * Retrieve an smart object's know smart callback descriptions (both + * instance and class ones). * - * @param obj the smart object. - * @param class_descriptions where to store class callbacks + * @param obj The smart object to get callback descriptions from. + * @param class_descriptions Where to store class callbacks * descriptions array, if any is known. If no descriptions are - * known, @c NULL is returned. This parameter may be @c NULL if - * it is not of interest. - * @param class_count returns how many class callbacks descriptions + * known, @c NULL is returned + * @param class_count Returns how many class callbacks descriptions * are known. - * @param instance_descriptions where to store instance callbacks + * @param instance_descriptions Where to store instance callbacks * descriptions array, if any is known. If no descriptions are - * known, @c NULL is returned. This parameter may be @c NULL if - * it is not of interest. - * @param instance_count returns how many instance callbacks + * known, @c NULL is returned. + * @param instance_count Returns how many instance callbacks * descriptions are known. * - * @note if just class descriptions are of interest, try + * This call searchs for registered callback descriptions for both + * instance and class of the given smart object. These arrays will be + * sorted by Evas_Smart_Cb_Description::name and also @c NULL + * terminated, so both @a class_count and @a instance_count can be + * ignored, if the caller wishes so. The terminator @c NULL is not + * counted in these values. + * + * @note If just class descriptions are of interest, try * evas_smart_callbacks_descriptions_get() instead. * + * @note Use @c NULL pointers on the descriptions/counters you're not + * interested in: they'll be ignored by the function. + * * @see evas_smart_callbacks_descriptions_get() + * * @ingroup Evas_Smart_Object_Group */ EAPI 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) EINA_ARG_NONNULL(1);