* handy <b>helper macro</b>:
* @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
* "static clippers" -- clipped smart objects have their global
* clippers flagged static.
*
+ * Other important things we also exemplify here are <b>smart
+ * callbacks</b> 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 <b>smart class</b>'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);
"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"
{
Ecore_Evas *ee;
Evas *evas;
- Evas_Object *smt, *bg, *clipper;
+ Evas_Object *smt, *bg, *clipper, *rects[2];
};
struct color_tuple
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}
};
{
Evas_Object_Smart_Clipped_Data base;
Evas_Object *children[2], *border;
+ int child_count;
};
#define EVAS_SMART_EXAMPLE_DATA_GET(o, ptr) \
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__)
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,
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;
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;
}
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;
}
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 */
{
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",
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",
}
}
+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));
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);
/**
* @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;
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 */
/**
* @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:
*
* @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;
};
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
/**
- * 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;
* selected. As a smart object, the normal Evas object API could be
* used on the icon object.
*
+ * Besides that, generally smart objects implement a <b>specific
+ * API</b>, so that users interect with its own custom features. The
+ * API takes form of explicit exported functions one may call and
+ * <b>smart callbacks</b>.
+ *
+ * @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 <b>event string</b>, 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 <b>at run time</b>.
+ *
* See some @ref Example_Evas_Smart_Objects "examples" of this group
* of functions.
*
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 <b>the first</b> 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 <b>at run time</b>.
*
* @ingroup Evas_Smart_Object_Group
*/
/**
- * 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);
projects / framework / uifw / evas.git / commitdiff