forked from enlightenment/efl
[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 SVN revision: 61158
This commit is contained in:
parent
ea1123d387
commit
ebe741dbba
|
@ -545,7 +545,7 @@
|
|||
* 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
|
||||
|
@ -621,22 +621,51 @@
|
|||
* "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);
|
||||
|
|
|
@ -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
|
||||
|
@ -84,13 +85,11 @@ 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 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);
|
||||
|
|
|
@ -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.
|
||||
*
|
||||
* This is likely different from Evas_Smart_Class::callbacks as it
|
||||
* will contain the callbacks of all class hierarchy sorted, while the
|
||||
* @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_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 <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.
|
||||
*
|
||||
|
@ -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 <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
|
||||
* @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 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.
|
||||
* 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
|
||||
*/
|
||||
|
@ -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.
|
||||
* 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.
|
||||
*
|
||||
* @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
|
||||
*
|
||||
* @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.
|
||||
*/
|
||||
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.
|
||||
* Retrieve an smart object's know smart callback descriptions (both
|
||||
* instance and class ones).
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* @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);
|
||||
|
|
Loading…
Reference in New Issue