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>:
|
* handy <b>helper macro</b>:
|
||||||
* @dontinclude evas-smart-object.c
|
* @dontinclude evas-smart-object.c
|
||||||
* @skip EVAS_SMART_SUBCLASS_NEW
|
* @skip EVAS_SMART_SUBCLASS_NEW
|
||||||
* @until _signals
|
* @until _smart_callbacks
|
||||||
* What it does is to @b subclass a given existing smart class, thus
|
* 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
|
* specializing it. This is very common and useful in Evas. There is a
|
||||||
* built-in smart object, the "clipped smart object", whose behavior is
|
* built-in smart object, the "clipped smart object", whose behavior is
|
||||||
|
@ -621,22 +621,51 @@
|
||||||
* "static clippers" -- clipped smart objects have their global
|
* "static clippers" -- clipped smart objects have their global
|
||||||
* clippers flagged static.
|
* 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
|
* 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:
|
* line interface, whose help string can be asked for with the 'h' key:
|
||||||
*
|
|
||||||
* @dontinclude evas-smart-object.c
|
* @dontinclude evas-smart-object.c
|
||||||
* @skip static const char *commands =
|
* @skip static const char *commands =
|
||||||
* @until ;
|
* @until ;
|
||||||
* Use 'l' and 'r' keys, to create new rectangles and place them on the
|
* Use 'l' and 'r' keys, to create new rectangles and place them on
|
||||||
* left (@c evas_smart_example_set_left()) or right
|
* the left (@c evas_smart_example_set_left()) or right (@c
|
||||||
* (@c evas_smart_example_set_right()) spots of our smart object,
|
* evas_smart_example_set_right()) spots of our smart object,
|
||||||
* respectively. The keyboard arrows will move the smart object along
|
* respectively. The 'w' command will remove all member objects from
|
||||||
* the canvas. See how it takes any child objects with it during its
|
* the smart object and delete them. The keyboard arrows will move the
|
||||||
* movement. The 'd' and 'i' keys will increase or decrease the smart
|
* smart object along the canvas. See how it takes any child objects
|
||||||
* object's size -- see how it affects the children's sizes,
|
* with it during its movement. The 'd' and 'i' keys will increase or
|
||||||
* too. Finally, 'c' will change the color of the smart object's
|
* decrease the smart object's size -- see how it affects the
|
||||||
* clipper (which is the exact internal clipper coming from a clipped
|
* children's sizes, too. Finally, 'c' will change the color of the
|
||||||
* smart object):
|
* smart object's clipper (which is the exact internal clipper coming
|
||||||
|
* from a clipped smart object):
|
||||||
* @dontinclude evas-smart-object.c
|
* @dontinclude evas-smart-object.c
|
||||||
* @skip d.clipper =
|
* @skip d.clipper =
|
||||||
* @until .a);
|
* @until .a);
|
||||||
|
|
|
@ -31,6 +31,7 @@ static const char *commands = \
|
||||||
"commands are:\n"
|
"commands are:\n"
|
||||||
"\tl - insert child rectangle on the left\n"
|
"\tl - insert child rectangle on the left\n"
|
||||||
"\tr - insert child rectangle on the right\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"
|
"\tright arrow - move smart object to the right\n"
|
||||||
"\tleft arrow - move smart object to the left\n"
|
"\tleft arrow - move smart object to the left\n"
|
||||||
"\tup arrow - move smart object up\n"
|
"\tup arrow - move smart object up\n"
|
||||||
|
@ -49,7 +50,7 @@ struct test_data
|
||||||
{
|
{
|
||||||
Ecore_Evas *ee;
|
Ecore_Evas *ee;
|
||||||
Evas *evas;
|
Evas *evas;
|
||||||
Evas_Object *smt, *bg, *clipper;
|
Evas_Object *smt, *bg, *clipper, *rects[2];
|
||||||
};
|
};
|
||||||
|
|
||||||
struct color_tuple
|
struct color_tuple
|
||||||
|
@ -83,14 +84,12 @@ _index_to_color(int i)
|
||||||
static struct test_data d = {0};
|
static struct test_data d = {0};
|
||||||
static const char *border_img_path = PACKAGE_EXAMPLES_DIR "/red.png";
|
static const char *border_img_path = PACKAGE_EXAMPLES_DIR "/red.png";
|
||||||
|
|
||||||
#define _evas_smart_example_type "Evas_Smart_Example"
|
#define _evas_smart_example_type "Evas_Smart_Example"
|
||||||
#define SIG_CHILD_ADDED "child,added"
|
#define EVT_CHILDREN_NUMBER_CHANGED "children,changed"
|
||||||
#define SIG_CHILD_REMOVED "child,removed"
|
|
||||||
|
|
||||||
static const Evas_Smart_Cb_Description _signals[] =
|
static const Evas_Smart_Cb_Description _smart_callbacks[] =
|
||||||
{
|
{
|
||||||
{SIG_CHILD_ADDED, ""},
|
{EVT_CHILDREN_NUMBER_CHANGED, "i"},
|
||||||
{SIG_CHILD_REMOVED, ""},
|
|
||||||
{NULL, NULL}
|
{NULL, NULL}
|
||||||
};
|
};
|
||||||
|
|
||||||
|
@ -104,6 +103,7 @@ struct _Evas_Smart_Example_Data
|
||||||
{
|
{
|
||||||
Evas_Object_Smart_Clipped_Data base;
|
Evas_Object_Smart_Clipped_Data base;
|
||||||
Evas_Object *children[2], *border;
|
Evas_Object *children[2], *border;
|
||||||
|
int child_count;
|
||||||
};
|
};
|
||||||
|
|
||||||
#define EVAS_SMART_EXAMPLE_DATA_GET(o, ptr) \
|
#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_SUBCLASS_NEW(_evas_smart_example_type, _evas_smart_example,
|
||||||
Evas_Smart_Class, Evas_Smart_Class,
|
Evas_Smart_Class, Evas_Smart_Class,
|
||||||
evas_object_smart_clipped_class_get, _signals);
|
evas_object_smart_clipped_class_get, _smart_callbacks);
|
||||||
|
|
||||||
static void
|
static void
|
||||||
_on_destroy(Ecore_Evas *ee __UNUSED__)
|
_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());
|
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) */
|
/* remove a child element, return its pointer (or NULL on errors) */
|
||||||
Evas_Object *
|
Evas_Object *
|
||||||
evas_smart_example_remove(Evas_Object *o,
|
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 = (int)evas_object_data_get(child, "index");
|
||||||
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_object_smart_callback_call(
|
||||||
_evas_smart_example_child_callbacks_unregister(child);
|
o, EVT_CHILDREN_NUMBER_CHANGED, (void *)priv->child_count);
|
||||||
evas_object_smart_member_del(child);
|
|
||||||
evas_object_smart_changed(o);
|
evas_object_smart_changed(o);
|
||||||
|
|
||||||
return child;
|
return child;
|
||||||
|
@ -362,17 +372,25 @@ evas_smart_example_set_left(Evas_Object *o,
|
||||||
if (priv->children[0])
|
if (priv->children[0])
|
||||||
{
|
{
|
||||||
if (priv->children[0] != child)
|
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;
|
else return child;
|
||||||
}
|
}
|
||||||
|
|
||||||
priv->children[0] = 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_smart_example_child_callbacks_register(o, child, 0);
|
||||||
evas_object_smart_member_add(child, o);
|
evas_object_smart_member_add(child, o);
|
||||||
evas_object_smart_changed(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 ret;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -398,17 +416,25 @@ evas_smart_example_set_right(Evas_Object *o,
|
||||||
if (priv->children[1])
|
if (priv->children[1])
|
||||||
{
|
{
|
||||||
if (priv->children[1] != child)
|
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;
|
else return child;
|
||||||
}
|
}
|
||||||
|
|
||||||
priv->children[1] = 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_smart_example_child_callbacks_register(o, child, 1);
|
||||||
evas_object_smart_member_add(child, o);
|
evas_object_smart_member_add(child, o);
|
||||||
evas_object_smart_changed(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 ret;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -428,6 +454,26 @@ _on_keydown(void *data __UNUSED__,
|
||||||
return;
|
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
|
if (strcmp(ev->keyname, "l") == 0) /* insert random colored
|
||||||
* rectangle on the left */
|
* rectangle on the left */
|
||||||
{
|
{
|
||||||
|
@ -437,6 +483,8 @@ _on_keydown(void *data __UNUSED__,
|
||||||
evas_object_show(rect);
|
evas_object_show(rect);
|
||||||
|
|
||||||
prev = evas_smart_example_set_left(d.smt, 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"
|
fprintf(stdout, "Setting smart object's left spot with a new"
|
||||||
" rectangle.\n");
|
" rectangle.\n");
|
||||||
fprintf(stdout, "Checking its new smart object parent: %s\n",
|
fprintf(stdout, "Checking its new smart object parent: %s\n",
|
||||||
|
@ -464,6 +512,8 @@ _on_keydown(void *data __UNUSED__,
|
||||||
evas_object_show(rect);
|
evas_object_show(rect);
|
||||||
|
|
||||||
prev = evas_smart_example_set_right(d.smt, 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"
|
fprintf(stdout, "Setting smart object's right spot with a new"
|
||||||
" rectangle.\n");
|
" rectangle.\n");
|
||||||
fprintf(stdout, "Checking its new smart object parent: %s\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
|
int
|
||||||
main(void)
|
main(void)
|
||||||
{
|
{
|
||||||
|
const Evas_Smart_Cb_Description **descriptions;
|
||||||
|
unsigned int count;
|
||||||
Eina_Bool ret;
|
Eina_Bool ret;
|
||||||
|
|
||||||
srand(time(NULL));
|
srand(time(NULL));
|
||||||
|
@ -600,13 +661,34 @@ main(void)
|
||||||
|
|
||||||
d.clipper = evas_object_smart_clipped_clipper_get(d.smt);
|
d.clipper = evas_object_smart_clipped_clipper_get(d.smt);
|
||||||
fprintf(stdout, "Checking if clipped smart object's clipper is a "
|
fprintf(stdout, "Checking if clipped smart object's clipper is a "
|
||||||
"\"static\" one: %s\n", evas_object_static_clip_get(d.clipper) ?
|
"\"static\" one: %s\n", evas_object_static_clip_get(
|
||||||
"yes" : "no");
|
d.clipper) ? "yes" : "no");
|
||||||
|
|
||||||
evas_object_color_set(
|
evas_object_color_set(
|
||||||
d.clipper, clipper_colors[cur_color].r, clipper_colors[cur_color].g,
|
d.clipper, clipper_colors[cur_color].r, clipper_colors[cur_color].g,
|
||||||
clipper_colors[cur_color].b, clipper_colors[cur_color].a);
|
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_focus_set(d.bg, EINA_TRUE);
|
||||||
evas_object_event_callback_add(
|
evas_object_event_callback_add(
|
||||||
d.bg, EVAS_CALLBACK_KEY_DOWN, _on_keydown, NULL);
|
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
|
* @typedef Evas_Smart_Cb_Description
|
||||||
|
*
|
||||||
* A smart object callback description, used to provide introspection
|
* A smart object callback description, used to provide introspection
|
||||||
|
*
|
||||||
* @ingroup Evas_Smart_Group
|
* @ingroup Evas_Smart_Group
|
||||||
*/
|
*/
|
||||||
typedef struct _Evas_Smart_Cb_Description Evas_Smart_Cb_Description;
|
typedef struct _Evas_Smart_Cb_Description Evas_Smart_Cb_Description;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @typedef Evas_Map
|
* @typedef Evas_Map
|
||||||
|
*
|
||||||
* An opaque handle to map points
|
* An opaque handle to map points
|
||||||
|
*
|
||||||
* @see evas_map_new()
|
* @see evas_map_new()
|
||||||
* @see evas_map_free()
|
* @see evas_map_free()
|
||||||
* @see evas_map_dup()
|
* @see evas_map_dup()
|
||||||
|
*
|
||||||
* @ingroup Evas_Object_Group_Map
|
* @ingroup Evas_Object_Group_Map
|
||||||
*/
|
*/
|
||||||
typedef struct _Evas_Map Evas_Map;
|
typedef struct _Evas_Map Evas_Map;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @typedef Evas
|
* @typedef Evas
|
||||||
|
*
|
||||||
* An opaque handle to an Evas canvas.
|
* An opaque handle to an Evas canvas.
|
||||||
|
*
|
||||||
* @see evas_new()
|
* @see evas_new()
|
||||||
* @see evas_free()
|
* @see evas_free()
|
||||||
|
*
|
||||||
* @ingroup Evas_Canvas
|
* @ingroup Evas_Canvas
|
||||||
*/
|
*/
|
||||||
typedef struct _Evas Evas;
|
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_NOGRAB /**< pointer always bound to the object right below it */
|
||||||
} Evas_Object_Pointer_Mode; /**< How the mouse pointer should be handled by Evas. */
|
} 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 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 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 */
|
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
|
* @struct _Evas_Smart_Cb_Description
|
||||||
*
|
*
|
||||||
* Describes a callback used by a smart class
|
* Describes a callback issued by a smart object
|
||||||
* evas_object_smart_callback_call(), particularly useful to explain
|
* (evas_object_smart_callback_call()), as defined in its smart object
|
||||||
* to user and its code (ie: introspection) what the parameter @c
|
* class. This is particularly useful to explain to end users and
|
||||||
* event_info will contain.
|
* their code (i.e., introspection) what the parameter @c event_info
|
||||||
|
* will point to.
|
||||||
*
|
*
|
||||||
* @ingroup Evas_Smart_Group
|
* @ingroup Evas_Smart_Group
|
||||||
*/
|
*/
|
||||||
struct _Evas_Smart_Cb_Description
|
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
|
* 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
|
* but extended to optionally include variable names within
|
||||||
* brackets preceding types. Example:
|
* brackets preceding types. Example:
|
||||||
*
|
*
|
||||||
|
@ -8047,9 +8055,9 @@ struct _Evas_Smart_Cb_Description
|
||||||
* @c "[x]a(ii)"
|
* @c "[x]a(ii)"
|
||||||
*
|
*
|
||||||
* @note This type string is used as a hint and is @b not validated
|
* @note This type string is used as a hint and is @b not validated
|
||||||
* or enforced anyhow. Implementors should make the best use
|
* or enforced in any way. Implementors should make the best
|
||||||
* of it to help bindings, documentation and other users of
|
* use of it to help bindings, documentation and other users
|
||||||
* introspection features.
|
* of introspection features.
|
||||||
*/
|
*/
|
||||||
const char *type;
|
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;
|
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
|
* @param s A valid #Evas_Smart handle.
|
||||||
* will contain the callbacks of all class hierarchy sorted, while the
|
* @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
|
* direct smart class member refers only to that specific class and
|
||||||
* should not include parent's.
|
* should not include parent's.
|
||||||
*
|
*
|
||||||
* If no callbacks are known, this function returns @c NULL.
|
* If no callbacks are known, this function returns @c NULL.
|
||||||
*
|
*
|
||||||
* The array elements and thus their contents will be reference to
|
* The array elements and thus their contents will be @b references to
|
||||||
* original values given to evas_smart_new() as
|
* original values given to evas_smart_class_new() as
|
||||||
* Evas_Smart_Class::callbacks.
|
* Evas_Smart_Class::callbacks.
|
||||||
*
|
*
|
||||||
* The array is sorted by name. The last array element is the @c NULL
|
* The array is sorted by Evas_Smart_Cb_Description::name. The last
|
||||||
* pointer and is not counted in @a count. Loop iterations can check
|
* array element is a @c NULL pointer and is not accounted for in @a
|
||||||
* any of these cases.
|
* count. Loop iterations can check any of these size indicators.
|
||||||
*
|
|
||||||
* @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().
|
|
||||||
*
|
*
|
||||||
* @note objects may provide per-instance callbacks, use
|
* @note objects may provide per-instance callbacks, use
|
||||||
* evas_object_smart_callbacks_descriptions_get() to get those
|
* 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 s The #Evas_Smart where to search for class registered smart
|
||||||
* @param name name of desired callback, must @b not be @c NULL. The
|
* event callbacks.
|
||||||
* search have a special case for @a name being the same
|
* @param name Name of the desired callback, which must @b not be @c
|
||||||
* pointer as registered with Evas_Smart_Cb_Description, one
|
* NULL. The search has a special case for @a name being the
|
||||||
* can use it to avoid excessive use of strcmp().
|
* same pointer as registered with #Evas_Smart_Cb_Description.
|
||||||
* @return reference to description if found, @c NULL if not found.
|
* 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;
|
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
|
* selected. As a smart object, the normal Evas object API could be
|
||||||
* used on the icon object.
|
* 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
|
* See some @ref Example_Evas_Smart_Objects "examples" of this group
|
||||||
* of functions.
|
* 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);
|
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 obj a smart object
|
||||||
* @param event the event name
|
* @param event the event's name string
|
||||||
* @param func the callback function
|
* @param func the callback function
|
||||||
* @param data user data to be passed to 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
|
* @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);
|
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
|
* Delete (unregister) a callback function from the smart event
|
||||||
*
|
* specified by @p event on the smart object @p obj.
|
||||||
* Removes a callback that was added by evas_object_smart_callback_add()
|
|
||||||
*
|
*
|
||||||
* @param obj a smart object
|
* @param obj a smart object
|
||||||
* @param event the event name
|
* @param event the event's name string
|
||||||
* @param func the callback function
|
* @param func the callback function
|
||||||
* @return the data pointer
|
* @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
|
* @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);
|
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 obj the smart object
|
||||||
* @param event the event name
|
* @param event the event's name string
|
||||||
* @param event_info an event specific struct of info to pass to the callback
|
* @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
|
* This should be called @b internally, from the smart object's own
|
||||||
* event has occurred. The documentation for the smart object should include
|
* code, when some specific event has occurred and the implementor
|
||||||
* a list of possible events and what type of @p event_info to expect.
|
* 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
|
* @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
|
* These descriptions are hints to be used by introspection and are
|
||||||
* not enforced in any way.
|
* not enforced in any way.
|
||||||
*
|
*
|
||||||
* It will not be checked if instance callbacks descriptions have the
|
* It will not be checked if instance callbacks descriptions have the
|
||||||
* same name as another in class. Both are kept in different arrays
|
* same name as respective possibly registered in the smart object
|
||||||
* and users of evas_object_smart_callbacks_descriptions_get() should
|
* @b class. Both are kept in different arrays and users of
|
||||||
* handle this case as they wish.
|
* 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
|
* @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);
|
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
|
* @param obj The smart object to get callback descriptions from.
|
||||||
* instance and class. These arrays are sorted by description's name
|
* @param class_descriptions Where to store class callbacks
|
||||||
* 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
|
|
||||||
* descriptions array, if any is known. If no descriptions are
|
* descriptions array, if any is known. If no descriptions are
|
||||||
* known, @c NULL is returned. This parameter may be @c NULL if
|
* known, @c NULL is returned
|
||||||
* it is not of interest.
|
* @param class_count Returns how many class callbacks descriptions
|
||||||
* @param class_count returns how many class callbacks descriptions
|
|
||||||
* are known.
|
* 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
|
* descriptions array, if any is known. If no descriptions are
|
||||||
* known, @c NULL is returned. This parameter may be @c NULL if
|
* known, @c NULL is returned.
|
||||||
* it is not of interest.
|
* @param instance_count Returns how many instance callbacks
|
||||||
* @param instance_count returns how many instance callbacks
|
|
||||||
* descriptions are known.
|
* 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.
|
* 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()
|
* @see evas_smart_callbacks_descriptions_get()
|
||||||
|
*
|
||||||
* @ingroup Evas_Smart_Object_Group
|
* @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);
|
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